insforge-integrations

InsForge 集成

本技能介绍如何将第三方提供商与 InsForge 集成。目前支持两类：身份验证提供商（通过 JWT 声明实现 RLS）和支付促成方（x402 HTTP 支付协议）。本目录下为每个提供商提供了单独的指南。

身份验证提供商

提供商	指南	适用场景
Clerk	Clerk JWT Templates + InsForge RLS	Clerk 通过 JWT Template 直接签发令牌 — 无需在服务端签名
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. 提供商签名或签发包含用户 ID 的 JWT
2. 通过 createClient() 中的 accessToken 将 JWT 传递给 InsForge（已弃用的别名：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 Template 负责签名，无需服务端代码
• 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 列
• RLS 策略使用 requesting_user_id()，而不是 auth.uid()
• 通过 accessToken 传递 JWT——它是静态字符串，不是函数；对于短期令牌（Clerk），在同一用户首次登录后，使用 client.setAccessToken(token, AuthChangeEvent.TOKEN_REFRESHED) 同步刷新
• 始终通过 npx -y @insforge/cli secrets get JWT_SECRET 获取 JWT 密钥

支付服务商（x402）

• 结算后始终检查数据库 insert(...) 的结果——结算会在执行插入前先在链上转移资金；数据库静默失败会导致记录丢失
• 为 tx_hash 列添加 UNIQUE，以防重试时产生重复记录
• 根据代币合约链上的 DOMAIN_SEPARATOR 验证 EIP-712 域（name、version）——值错误会导致 Invalid Authority 错误
• 在本地开发时使用 MOCK_OKX_FACILITATOR 环境变量，以便在无需真实资金的情况下运行完整流程

常见错误

身份验证

错误	解决方案
在 RLS 中使用 auth.uid()	使用 requesting_user_id()——第三方 ID 是字符串，不是 UUID
将 user_id 列设为 UUID 类型	使用 TEXT——所有受支持的提供方都使用字符串格式的 ID
将 JWT 密钥硬编码	始终通过 npx -y @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	Mock 模式仅供演示；它会返回伪造的交易哈希并绕过验证