Update to InsForge

{
  "description": "Use when wiring an external auth provider (Clerk, Auth0, WorkOS, Kinde, Stytch, Better Auth) into InsForge for JWT-based RLS, or when adding the OKX x402 payment facilitator for onchain pay-per-use billing.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 235
    },
    {
      "relative_path": "references/auth0.md",
      "size_in_bytes": 6590
    },
    {
      "relative_path": "references/better-auth.md",
      "size_in_bytes": 34456
    },
    {
      "relative_path": "references/clerk.md",
      "size_in_bytes": 8974
    },
    {
      "relative_path": "references/kinde.md",
      "size_in_bytes": 4799
    },
    {
      "relative_path": "references/okx-x402.md",
      "size_in_bytes": 39127
    },
    {
      "relative_path": "references/stytch.md",
      "size_in_bytes": 7709
    },
    {
      "relative_path": "references/workos.md",
      "size_in_bytes": 5591
    }
  ],
  "name": "insforge-integrations",
  "skill_md_contents": "---\nname: insforge-integrations\ndescription: >-\n  Use when wiring an external auth provider (Clerk, Auth0, WorkOS, Kinde,\n  Stytch, Better Auth) into InsForge for JWT-based RLS, or when adding the\n  OKX x402 payment facilitator for onchain pay-per-use billing.\nlicense: Apache-2.0\n---\n\n# InsForge Integrations\n\nThis skill covers integrating **third-party providers** with InsForge. Currently two categories are supported: **auth providers** (RLS via JWT claims) and **payment facilitators** (x402 HTTP payment protocol). Each provider has its own guide under this directory.\n\n## Auth Providers\n\n| Provider | Guide | When to use |\n|----------|-------|-------------|\n| [Clerk](references/clerk.md) | Clerk JWT Templates + InsForge RLS | Clerk signs tokens directly via JWT Template — no server-side signing needed |\n| [Auth0](references/auth0.md) | Auth0 Actions + InsForge RLS | Auth0 uses a post-login Action to embed claims into the access token |\n| [WorkOS](references/workos.md) | WorkOS AuthKit + InsForge RLS | WorkOS AuthKit middleware + server-side JWT signing with `jsonwebtoken` |\n| [Kinde](references/kinde.md) | Kinde + InsForge RLS | Kinde token customization for InsForge integration |\n| [Stytch](references/stytch.md) | Stytch + InsForge RLS | Stytch session tokens for InsForge integration |\n| [Better Auth](references/better-auth.md) | Better Auth + InsForge RLS | Self-hosted auth running in your InsForge Postgres — no third-party SaaS, no per-MAU cost |\n\n## Payment Facilitators\n\n| Provider | Guide | When to use |\n|----------|-------|-------------|\n| [OKX x402](references/okx-x402.md) | OKX as x402 facilitator (USDG on X Layer) | Pay-per-use HTTP endpoints settled onchain with zero gas for the payer |\n\n## Common Patterns\n\n### Auth providers\n1. **Provider signs or issues a JWT** containing the user's ID\n2. **JWT is passed to InsForge** via `accessToken` in `createClient()` (deprecated alias: `edgeFunctionToken`)\n3. **InsForge exposes claims** through `auth.jwt()` in SQL\n4. **RLS policies** use a `requesting_user_id()` function to enforce row-level security\n\n### Payment facilitators (x402)\n1. **Server returns `402 Payment Required`** with a JSON challenge base64-encoded in `PAYMENT-REQUIRED` header\n2. **Client signs an EIP-3009 authorization** using the stablecoin's EIP-712 domain\n3. **Server forwards the signed payload** to the facilitator's `/verify` + `/settle` endpoints\n4. **Server records the settled payment** in an InsForge table with a realtime trigger for live dashboards\n\n## Choosing a Provider\n\n**Auth**\n- **Clerk** — Simplest setup; JWT Template handles signing, no server code needed\n- **Auth0** — Flexible; uses post-login Actions for claim injection\n- **WorkOS** — Enterprise-focused; AuthKit middleware + server-side JWT signing\n- **Kinde** — Developer-friendly; built-in token customization\n- **Stytch** — API-first; session-based token flow\n- **Better Auth** — Self-hosted in your Postgres; no SaaS vendor; you own the user table. Pairs cleanly with InsForge's Postgres via a connection string + a small bridge route. Requires a one-time `REVOKE` after migrate to seal PostgREST exposure.\n\n**Payment facilitators**\n- **OKX x402** — Onchain pay-per-use via USDG on X Layer; zero gas for the payer\n\n## Setup\n\n1. Identify which provider the project uses\n2. Read the corresponding reference guide from the tables above\n3. Follow the provider-specific setup steps\n\n## Usage Examples\n\nEach provider guide includes full code examples for:\n- Provider dashboard configuration (API keys, application settings, etc.)\n- Server and client code (JWT utilities for auth; facilitator client + signing utilities for payments)\n- Database setup (RLS for auth; payment table + realtime trigger for payments)\n- Environment variable setup\n\nRefer to the specific `references/<provider>.md` file for complete examples.\n\n## Best Practices\n\n**Auth**\n- All auth provider user IDs are strings (not UUIDs) — always use `TEXT` columns for `user_id`\n- Use `requesting_user_id()` instead of `auth.uid()` for RLS policies\n- Pass the JWT via `accessToken` — a static string, not a function; for short-lived tokens (Clerk) sync refreshes with `client.setAccessToken(token, AuthChangeEvent.TOKEN_REFRESHED)` after the initial same-user sign-in\n- Always get the JWT secret via `npx @insforge/cli secrets get JWT_SECRET`\n\n**Payment facilitators (x402)**\n- Always check the result of the database `insert(...)` after settlement — settlement takes money onchain before the insert runs; a silent DB failure loses the record\n- Add `UNIQUE` to the `tx_hash` column to prevent duplicate records from retries\n- Verify EIP-712 domain (`name`, `version`) against the token contract's on-chain `DOMAIN_SEPARATOR` — wrong values produce `Invalid Authority` errors\n- Use a `MOCK_OKX_FACILITATOR` env flag for local dev so the full flow can be exercised without real funds\n\n## Common Mistakes\n\n**Auth**\n\n| Mistake | Solution |\n|---------|----------|\n| Using `auth.uid()` for RLS | Use `requesting_user_id()` — third-party IDs are strings, not UUIDs |\n| Using UUID columns for `user_id` | Use `TEXT` — all supported providers use string-format IDs |\n| Hardcoding the JWT secret | Always retrieve via `npx @insforge/cli secrets get JWT_SECRET` |\n| Missing `requesting_user_id()` function | Must be created before RLS policies will work |\n\n**Payments (x402)**\n\n| Mistake | Solution |\n|---------|----------|\n| Using an OKX exchange trading API key | Create a separate Web3 API key at `web3.okx.com/onchainos/dev-portal` |\n| Wrong EIP-712 domain values | Read the token contract's `DOMAIN_SEPARATOR` — for USDG on X Layer use `name: \"Global Dollar\"`, `version: \"1\"` |\n| Ignoring DB insert error after settlement | Always destructure `{ error }` and log/handle it — money has already moved |\n| `MOCK_OKX_FACILITATOR=true` in production | Mock mode is demo-only; it returns fake tx hashes and bypasses verification |\n"
}