insforge-integrations

InsForge のインテグレーション

このスキルでは、InsForge とサードパーティプロバイダーのインテグレーションについて説明します。現在、認証プロバイダー（JWT クレームによる RLS）と決済ファシリテーター（x402 HTTP 決済プロトコル）の 2 つのカテゴリに対応しています。各プロバイダーのガイドは、このディレクトリ内にあります。

認証プロバイダー

プロバイダー	ガイド	使用する場面
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	InsForge とのインテグレーションのための Kinde トークンのカスタマイズ
Stytch	Stytch + InsForge RLS	InsForge とのインテグレーションのための Stytch セッショントークン
Better Auth	Better Auth + InsForge RLS	InsForge の Postgres 上で動作するセルフホスト可能な認証。サードパーティの SaaS も、MAU ごとの料金も不要です

決済ファシリテーター

プロバイダー	ガイド	使用する場面
OKX x402	x402 ファシリテーターとしての OKX（X Layer 上の USDG）	支払者のガス代負担なしで、オンチェーン決済される従量課金制 HTTP エンドポイント

共通パターン

認証プロバイダー

1. プロバイダーがユーザー ID を含む JWT に署名するか、発行します
2. JWT は createClient() の accessToken を介して InsForge に渡されます（非推奨のエイリアス：edgeFunctionToken）
3. InsForge は SQL の auth.jwt() を通じてクレームを公開します
4. RLS ポリシーは requesting_user_id() 関数を使い、行レベルのセキュリティを適用します

決済ファシリテーター（x402）

1. サーバーは 402 Payment Required を返します。JSON チャレンジは Base64 エンコードされ、PAYMENT-REQUIRED ヘッダーに含まれます
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 とスムーズに連携します。PostgREST の公開範囲を封じるには、マイグレーション後に一度だけ REVOKE を実行する必要があります。

決済ファシリテーター

• OKX x402 — X Layer 上の USDG によるオンチェーン従量課金。支払者のガス代負担はありません

セットアップ

1. プロジェクトで使用するプロバイダーを特定します
2. 上の表から対応するリファレンスガイドを読みます
3. プロバイダー固有のセットアップ手順に従います

使用例

各プロバイダーのガイドには、次の完全なコード例が含まれています。

• プロバイダーのダッシュボード設定（API キー、アプリケーション設定など）
• サーバーおよびクライアントのコード（認証用の JWT ユーティリティ、決済用のファシリテータークライアントと署名ユーティリティ）
• データベースのセットアップ（認証用の RLS、決済用の決済テーブルとリアルタイムトリガー）
• 環境変数の設定

完全な例については、該当する references/<provider>.md ファイルを参照してください。

ベストプラクティス

認証

• すべての認証プロバイダーのユーザー ID は文字列です（UUID ではありません）。user_id には常に TEXT 列を使用してください。
• RLS ポリシーには auth.uid() ではなく requesting_user_id() を使用してください。
• JWT は accessToken 経由で渡してください。関数ではなく、静的な文字列を指定します。短期間で期限切れになるトークン（Clerk）の場合は、同じユーザーで最初にサインインした後、client.setAccessToken(token, AuthChangeEvent.TOKEN_REFRESHED) で更新を同期してください。
• JWT シークレットは必ず npx -y @insforge/cli secrets get JWT_SECRET で取得してください。

決済代行業者（x402）

• 決済確定後、データベースの insert(...) の結果を必ず確認してください。決済確定では insert の実行前にオンチェーンで資金が移動するため、DB のエラーを見逃すと記録が失われます。
• 再試行による重複レコードを防ぐため、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 -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" を使用します。
決済確定後の DB 挿入エラーを無視する	常に { error } を分割代入し、ログに記録するか処理してください。資金はすでに移動しています。
本番環境で MOCK_OKX_FACILITATOR=true を設定する	モックモードはデモ専用です。偽のトランザクションハッシュを返し、検証をバイパスします。