insforge-integrations

InsForge Integrations

此技能涵蓋將第三方提供者與 InsForge 整合。目前支援兩類：驗證提供者（透過 JWT 聲明實現 RLS）和付款促進器（x402 HTTP 付款協定）。每個提供者在此目錄下都有各自的指南。

驗證提供者

提供者	指南	使用時機
Clerk	Clerk JWT 模板 + InsForge RLS	Clerk 直接透過 JWT 模板簽署令牌 — 無需伺服器端簽署
Auth0	Auth0 Actions + InsForge RLS	Auth0 使用登入後 Action 將聲明嵌入存取令牌
WorkOS	WorkOS AuthKit + InsForge RLS	WorkOS AuthKit 中介軟體 + 使用 jsonwebtoken 進行伺服器端 JWT 簽署
Kinde	Kinde + InsForge RLS	Kinde 令牌自訂以整合 InsForge
Stytch	Stytch + InsForge RLS	Stytch 工作階段令牌用於 InsForge 整合
Better Auth	Better Auth + InsForge RLS	自託管驗證，運行在您的 InsForge Postgres 中 — 無第三方 SaaS，無每 MAU 成本

付款促進器

提供者	指南	使用時機
OKX x402	OKX 作為 x402 促進器（X Layer 上的 USDG）	按用量計費的 HTTP 端點，在鏈上結算，付款人無需 Gas 費用

常見模式

驗證提供者

1. 提供者簽署或發行 JWT，包含使用者 ID
2. JWT 傳遞給 InsForge，透過 createClient() 中的 accessToken（已棄用別名：edgeFunctionToken）
3. InsForge 透過 SQL 中的 auth.jwt() 暴露聲明
4. RLS 政策使用 requesting_user_id() 函數來強制執行資料列層級安全性

付款促進器 (x402)

1. 伺服器回傳 402 Payment Required，並在 PAYMENT-REQUIRED 標頭中附帶 base64 編碼的 JSON 挑戰
2. 用戶端使用穩定幣的 EIP-712 域簽署 EIP-3009 授權
3. 伺服器將已簽署的負載轉發給促進器的 /verify 和 /settle 端點
4. 伺服器將已結算的付款記錄在 InsForge 表格中，並附帶即時觸發器以支援即時儀表板

選擇提供者

驗證

• Clerk — 設定最簡單；JWT 模板處理簽署，無需伺服器程式碼
• Auth0 — 靈活；使用登入後 Actions 注入聲明
• WorkOS — 企業導向；AuthKit 中介軟體 + 伺服器端 JWT 簽署
• Kinde — 開發者友善；內建令牌自訂
• Stytch — API 優先；基於工作階段的令牌流程
• Better Auth — 在您的 Postgres 中自託管；無 SaaS 供應商；您擁有使用者表格。透過連線字串加上小型橋接路由，與 InsForge 的 Postgres 乾淨搭配。遷移後需一次性執行 REVOKE 以封閉 PostgREST 暴露。

付款促進器

• OKX x402 — 透過 X Layer 上的 USDG 實現鏈上按用量計費；付款人無需 Gas 費用

設定

1. 確認專案使用的提供者
2. 閱讀上方表格中對應的參考指南
3. 依照提供者特定的設定步驟操作

使用範例

每個提供者指南都包含完整的程式碼範例，涵蓋：

• 提供者儀表板設定（API 金鑰、應用程式設定等）
• 伺服器和用戶端程式碼（驗證用的 JWT 工具；付款用的促進器用戶端 + 簽署工具）
• 資料庫設定（驗證用的 RLS；付款用的付款表格 + 即時觸發器）
• 環境變數設定

請參閱特定的 references/<provider>.md 檔案以取得完整範例。

最佳實務

驗證

• 所有驗證提供者的使用者 ID 都是字串（非 UUID）— 始終對 user_id 使用 TEXT 欄位
• 使用 requesting_user_id() 而非 auth.uid() 來撰寫 RLS 政策
• 透過 accessToken 傳遞 JWT — 一個靜態字串，而非函數；對於短期令牌（Clerk），使用 client.setAccessToken() 同步重新整理
• 始終透過 npx @insforge/cli secrets get JWT_SECRET 取得 JWT 密鑰

付款促進器 (x402)

• 結算後務必檢查資料庫 insert(...) 的結果 — 結算在插入執行前已從鏈上扣款；無聲的資料庫失敗會遺失記錄
• 在 tx_hash 欄位加上 UNIQUE 限制，以防止重試造成重複記錄
• 驗證 EIP-712 域（name、version）是否與代幣合約的鏈上 DOMAIN_SEPARATOR 一致 — 錯誤的值會產生 Invalid Authority 錯誤
• 在本地開發時使用 MOCK_OKX_FACILITATOR 環境變數標記，以便在無需真實資金的情況下測試完整流程

常見錯誤

驗證

錯誤	解決方案
對 RLS 使用 auth.uid()	使用 requesting_user_id() — 第三方 ID 是字串，非 UUID
對 user_id 使用 UUID 欄位	使用 TEXT — 所有支援的提供者都使用字串格式 ID
硬編碼 JWT 密鑰	始終透過 npx @insforge/cli secrets get JWT_SECRET 取得
缺少 requesting_user_id() 函數	必須先建立，RLS 政策才能生效

付款 (x402)

錯誤	解決方案
使用 OKX 交易所交易 API 金鑰	在 web3.okx.com/onchainos/dev-portal 建立獨立的 Web3 API 金鑰
錯誤的 EIP-712 域值	讀取代幣合約的 DOMAIN_SEPARATOR — 對於 X Layer 上的 USDG，使用 name: "Global Dollar"、version: "1"
結算後忽略資料庫插入錯誤	務必解構 { error } 並記錄/處理 — 資金已經轉移
在正式環境中使用 MOCK_OKX_FACILITATOR=true	模擬模式僅供展示；它回傳假的交易雜湊並繞過驗證