在 InsForge 中接入第三方认证提供商（JWT+RLS…

当需要把 Clerk/Auth0/WorkOS/Kinde/Stytch/Better Auth 等外部认证接入 InsForge 做基于 JWT 的 RLS，或接入 OKX x402 支付 facilitator 实现链上按次计费时使用。

适用场景

解决思路

1. 先确定项目使用哪个提供商，再从对应表格中读取 references/<provider>.md 参考指南并按其步骤配置。
2. 认证通用流程：由提供商签发或生成包含用户 ID 的 JWT；通过 createClient() 的 accessToken 参数（已废弃别名 edgeFunctionToken）把 JWT 传给 InsForge；在 SQL 中用 auth.jwt() 读取 claims；RLS 策略使用 requesting_user_id() 函数做行级安全。
3. x402 支付通用流程：服务端返回 402 Payment Required，并在 PAYMENT-REQUIRED 头中放入 base64 编码的 JSON challenge；客户端用稳定币的 EIP-712 domain 签署 EIP-3009 授权；服务端把签名 payload 转发到 facilitator 的 /verify 和 /settle 端点；服务端把已结算的支付记录写入 InsForge 表，并加 realtime 触发器做实时看板。
4. 按需选择认证提供商：Clerk 最简单，用 JWT Template 直接签名无需服务端代码；Auth0 用 post-login Action 注入 claims；WorkOS 面向企业，用 AuthKit 中间件加服务端 jsonwebtoken 签名；Kinde 用内置 token 定制；Stytch 用基于 session 的 token 流程；Better Auth 自托管在 InsForge Postgres 中，通过连接字符串加一个小的 bridge route 对接，migrate 后需一次性执行 REVOKE 封住 PostgREST 暴露。
5. 认证最佳实践：所有提供商的用户 ID 都是字符串而非 UUID，user_id 列一律用 TEXT；RLS 策略用 requesting_user_id() 而不是 auth.uid()；accessToken 传静态字符串而非函数，对 Clerk 这类短期 token 在首次同用户登录后用 client.setAccessToken(token, AuthChangeEvent.TOKEN_REFRESHED) 同步刷新；JWT secret 一律用 npx -y @insforge/cli secrets get JWT_SECRET 获取。
6. x402 最佳实践：结算后必须检查数据库 insert(...) 的返回值，因为链上已扣款，静默失败会丢记录；tx_hash 列加 UNIQUE 防止重试产生重复记录；对照 token 合约链上 DOMAIN_SEPARATOR 校验 EIP-712 domain（name、version），USDG on X Layer 用 name: "Global Dollar"、version: "1"；本地开发用 MOCK_OKX_FACILITATOR 环境变量跑通全流程而不动用真实资金。
7. 避免认证常见错误：不要用 auth.uid() 做 RLS（改用 requesting_user_id()）；不要用 UUID 列存 user_id（改用 TEXT）；不要硬编码 JWT secret；必须先创建 requesting_user_id() 函数再写 RLS 策略。
8. 避免支付常见错误：不要用 OKX 交易所交易 API key，需在 web3.okx.com/onchainos/dev-portal 单独创建 Web3 API key；不要用错误的 EIP-712 domain 值；不要忽略结算后的 DB insert 错误，必须解构 { error } 并记录处理；不要在生产环境设 MOCK_OKX_FACILITATOR=true（mock 模式仅用于演示，返回假 tx hash 且跳过验证）。

适用边界 · 注意事项

• 不涉及第三方认证或链上按次付费、仅使用 InsForge 内置认证时不需要本技能。
• 没有 InsForge 项目或未部署对应 Postgres/RLS 环境时无法直接套用。
• OKX x402 部分依赖 OKX Web3 开发者账号与 X Layer 上的 USDG，缺少这些条件时只能走 mock 模式。