insforge-integrations

InsForge 集成

本技能涵盖将第三方提供商与 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 — 灵活；使用登录后 Action 注入声明
• 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 环境标志，以便在不使用真实资金的情况下演练完整流程

常见错误

认证

错误	解决方案
使用 auth.uid() 用于 RLS	使用 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	模拟模式仅用于演示；它返回虚假的交易哈希并绕过验证