@12-apps/mcp 1.19.0 → 1.20.0

package/ADOPTING.md

@@ -0,0 +1,248 @@
+# Adopting @12-apps/mcp
+
+A **plug-and-play MCP plugin** (12-23): the tool surface, the authorization server
+that protects it, the models both need, and the two CI gates that keep the
+advertised surface honest. A host repo only *points* at these surfaces; when the
+library updates, every host updates with **no app changes**. Same contract
+`@12-apps/report-builder` and `@12-apps/rbac` established.
+
+## The standardized plugin surfaces
+
+| Surface | Export | What the host does |
+|---|---|---|
+| **Core** | `@12-apps/mcp` | `generateTools(openapi)`, `createToolRegistry`, `dispatchTool` (bearer passthrough), `buildManifest`, the surface lock, and both discovery-document builders. |
+| **OAuth AS** | `@12-apps/mcp/oauth` | `createApiMcpOauth({ stores, resolveSession })` → `routes` + named `handlers` + `verifyBearer`. register / authorize / token, the JWKS, and both `.well-known` documents, with PKCE, stateless codes, hashed rotating refresh tokens and replay revocation inside. |
+| **Hono** | `@12-apps/mcp/hono` | `const oauth = mcpOauthRouter({ … }); app.route('/', oauth.router)` — at the ORIGIN ROOT (see rule 2). `hono` is an OPTIONAL peer. |
+| **React** | `@12-apps/mcp/react` | The AI-connect onboarding UI and status board (pt-BR, overridable). |
+| **`mcp:generate` / `mcp:check`** | `@12-apps/mcp/generate` | Your script becomes `mcpGenerateCli({ document, version, source, versionLocation, outputs, check })`. `12-apps/ci`'s `mcp-contract.yml` shells out to your `mcp:check` package script and keeps working unchanged. |
+| **`mcp:coverage`** | `@12-apps/mcp/coverage` | `mcpCoverageCli({ appDir, endpoints, exclusionsPath, actionMapPath })` — the route/action completeness gate. |
+| **Prisma** | `prisma/mcp.prisma` + `prisma/migrations/*` | `pnpm --filter @12-apps/mcp prisma:sync -- <host schema dir>`: the partial is **COPIED** into the host's multi-file schema folder — never symlinked (a symlinked migration is silently skipped by Prisma; a symlinked partial dangles under `turbo prune`). |
+
+## Host wiring rules (the ones that bite)
+
+1. **The host answers WHO; the package answers WHAT THEY MAY HAVE.**
+   `resolveSession` reads the host's cookie session and returns
+   `{ subject, email }` — or `null`, which redirects the caller into the host's
+   sign-in flow with a callback back to the authorize URL. **Identity never comes
+   from a query parameter**, so a client cannot name the user it wants a token for.
+2. **Mount at the origin root.** Two of the six paths are `.well-known` documents
+   and a connector reads them from the origin, not from a prefix — the descriptors
+   therefore carry absolute paths. `paths` moves any of them, and the RFC 8414
+   document is built from the RESOLVED paths, so a document that lies about a path
+   (a flow that fails at the first hop) is not expressible.
+3. **The gate is an operator decision, and 404 is the disabled answer.** With
+   `enabled: false` authorize/token/jwks/discovery answer **404** — a probe cannot
+   tell a disabled AS from an app that has none — while registration answers
+   **403 `access_denied`**, because RFC 7591 has a code for "the endpoint is here,
+   registration is closed". future-pay passes
+   `enabled: () => process.env.MCP_BEARER_ENABLED === 'true'`, so the surface stays
+   OFF until an operator opts in.
+4. **No signing key, no tokens.** `signingKey` defaults to the env-backed provider
+   (`MCP_OAUTH_SIGNING_KEY` + `MCP_OAUTH_SIGNING_KEY_ID`, PKCS#8 PEM, ES256).
+   Returning `null` is a *safe-by-default* state, not an error: authorize
+   `server_error`s, token issuance refuses, and the JWKS answers **503** rather
+   than an empty key set a client would mistake for a usable one. Rotation is by
+   `kid` — publish old + new during the overlap window.
+5. **`trustedOrigins` is REQUIRED behind a reverse proxy.** The server sees only
+   its internal bind on `request.url`, so the public origin comes from
+   `X-Forwarded-Host` — honoured **only** when it is on this allowlist; anything
+   else (spoofed, foreign, absent) resolves to the FIRST entry. With no allowlist a
+   forwarded host is never trusted at all, so a proxied deployment fails closed to
+   the internal origin rather than to an attacker's. Issuance and verification read
+   the same resolver from the same request, which is what stops "minted for A,
+   verified against B" from rejecting valid tokens.
+   `trustedOriginsFromEnv('MCP_OAUTH_TRUSTED_ORIGINS')` keeps future-pay's wiring.
+6. **The stores are narrow ports; Prisma fills them in one line.**
+   `createPrismaMcpStores(async () => prisma as unknown as McpOauthPrisma)`. A
+   non-Prisma host implements `OAuthClientStore` / `RefreshTokenStore` /
+   `McpConnectionStore` directly — the shapes are CLOSED and documented in
+   `src/oauth/stores.ts`, and the harness fills exactly them with SQL.
+7. **`rotate` must CLAIM the parent, not just revoke it.** The port's contract is
+   "revoke the parent CONDITIONALLY on it still being live, require a count of
+   exactly 1, and create the successor in the same transaction — otherwise write
+   nothing and return `false`". Atomicity alone (both writes or neither) covers a
+   crash and NOT a race: with an unconditional `update`, two concurrent rotations of
+   one token both succeed, leaving two live successors and replay detection silently
+   defeated, because the replay rule waits for a third use of the parent that now
+   never comes. That is OAuth 2.1 §4.3.1 bypassed by WINNING a race instead of
+   arriving second, which is the whole attack rotation exists to stop. The Prisma
+   adapter does it with `updateMany({ where: { tokenHash, revokedAt: null } })`
+   inside an interactive `$transaction`; the harness does the same in raw SQL, on
+   purpose, as the worked example of a non-Prisma host meeting the contract.
+8. **`codeReplay` is REQUIRED, and that is the point.** Single-use codes are only as
+   strong as the replay store, and the in-process one remembers redeemed `jti`s IN
+   THIS PROCESS: exact on one instance, and on several a code can be replayed
+   against a pod that has not seen the `jti`, inside the ≤60s code lifetime. So
+   there is no default. Pass a shared atomic store (a short-TTL row with a unique
+   constraint, or a distributed cache), or pass the literal `'in-process'` to
+   acknowledge the single-instance limit out loud:
+
+   ```ts
+   codeReplay: 'in-process',              // one pod, and you have said so
+   codeReplay: myRedisSetIfAbsentStore,   // more than one pod
+   ```
+
+   Every other default in this config fails CLOSED — no signing key mints nothing
+   and answers JWKS 503, `enabled: false` is 404 everywhere, an empty
+   `trustedOrigins` never trusts a forwarded host. An in-process default would be
+   the only one that fails OPEN, on the very topology a reusable package exists for.
+   Scaling out must not be able to weaken the guard by silence.
+9. **`authorize` has NO consent screen, so it refuses clients nobody approved.**
+   Registration is open whenever `enabled` is true (RFC 7591), and a cookie session
+   proves who is asking, never that they AGREED. Without a gate the chain is one
+   click: an attacker registers a client carrying their own `redirect_uris` and
+   their own `scope`, sends a signed-in admin a link to `authorize`, and the
+   endpoint mints them a code — and the two guards that look like they would stop
+   it, exact redirect-URI matching and the per-client scope ceiling, are both
+   checked against the ATTACKER'S OWN registration. So:
+
+   - pass **`resolveApproval(request, client, scopes)`** — your approval screen or
+     policy; returning `false` gives the caller `access_denied`;
+   - or list first-party client ids in **`preApprovedClientIds`** if you register
+     your own clients and have no screen to show;
+   - with neither, every dynamically registered client is refused. That is the
+     default, and it is deliberately the inconvenient one.
+10. **Connections are per USER, not per tenant** — an MCP bearer is
+    auth-passthrough. `connections.resolveUserId(email)` maps the token's email to
+    the host's user id (future-pay resolves it by email because `session.user.id` is
+    the OAuth `sub`); returning `null` records nothing. Recording is best-effort and
+    FENCED: a failing directory can never turn a valid grant into a 500, and nothing
+    about the attempt is logged, because the only values in hand are an email and a
+    client id.
+11. **Disconnecting means BOTH halves.** `connections.revokeByHost(...)` returns the
+    OAuth client ids it revoked, and the caller must then
+    `refreshTokens.revokeLiveForClient(email, clientId)` for each — a host holding a
+    live refresh token simply rotates its way back in and the card lights green on
+    the next grant. Neither half invalidates an outstanding ACCESS token: those are
+    self-contained JWTs, so a disconnected host keeps working for at most their
+    15-minute TTL and can then obtain nothing further.
+12. **These bodies are NOT the `{ data }` envelope.** A 302 with a `Location`, RFC
+    6749 §5.1/§5.2 JSON, an RFC 8414/9728 document — every shape here is fixed by
+    specification, and `Cache-Control: no-store` is on every credential-bearing
+    response. Wrapping any of it would break every client. That is why the adapters
+    are one line and hand the `Response` straight back.
+
+## The config, field by field
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `stores` | yes | — | `clients` + `refreshTokens` (+ optional `connections`) |
+| `resolveSession` | yes | — | `{ subject, email }` or `null` → sign-in redirect |
+| `enabled` | no | `true` | `false` ⇒ 404 everywhere, 403 on register |
+| `signingKey` | no | env provider | `null` ⇒ mints nothing, JWKS 503 |
+| `trustedOrigins` | no | `[]` (never trust a forwarded host) | REQUIRED behind a proxy |
+| `scopes` | no | `mcp:read mcp:write` | advertised AND validated against |
+| `resourcePath` | no | `/api/mcp` | the access token's `aud` |
+| `paths` | no | `/api/oauth/*` + `/.well-known/*` | also rewrites the discovery document |
+| `loginPath` / `loginCallbackParam` | no | `/login` / `callbackUrl` | Auth.js's names |
+| `accessTokenTtlSeconds` | no | 900 | 15 minutes |
+| `refreshTokenTtlMs` | no | 30 days | |
+| `codeReplay` | **yes** | — (no default, on purpose) | a shared atomic store, or `'in-process'` to acknowledge one pod — rule 8 |
+| `resolveApproval` | no | refuse unapproved clients | the consent seam — rule 9 |
+| `preApprovedClientIds` | no | `[]` | first-party client ids exempt from the approval gate — rule 9 |
+| `connections` | no | — | `resolveUserId`, `providerRules`, `activityThrottleMs` |
+
+## The endpoints
+
+| Method | Path (default) | Answers |
+|---|---|---|
+| GET | `/.well-known/oauth-authorization-server` | RFC 8414 metadata, built from the resolved paths |
+| GET | `/.well-known/oauth-protected-resource` | RFC 9728 metadata (same origin + scope source) |
+| GET | `/.well-known/jwks.json` | the public JWK (503 while unprovisioned), `max-age=300` |
+| GET | `/api/oauth/authorize` | 302 with `code` + `state`; a plain 400 when the client/`redirect_uri` is unregistered — **never** an error redirect to an unvalidated URI |
+| POST | `/api/oauth/token` | `authorization_code` (single-use, PKCE-verified, bound `redirect_uri`) and `refresh_token` (rotated, client-bound, narrow-only scope) |
+| POST | `/api/oauth/register` | 201 RFC 7591 client information; the secret exactly once, hashed at rest |
+
+## Minimal host (Hono)
+
+```ts
+import { mcpOauthRouter } from '@12-apps/mcp/hono';
+import { createPrismaMcpStores, trustedOriginsFromEnv, type McpOauthPrisma } from '@12-apps/mcp/oauth';
+
+const oauth = mcpOauthRouter({
+  stores: createPrismaMcpStores(async () => (await getPrismaClient()) as unknown as McpOauthPrisma),
+  enabled: () => process.env.MCP_BEARER_ENABLED === 'true',
+  trustedOrigins: trustedOriginsFromEnv('MCP_OAUTH_TRUSTED_ORIGINS'),
+  resolveSession: async (request) => {
+    const session = await getRequestSession(request);
+    const email = session?.user?.email;
+    return email ? { subject: session.user.id || email, email } : null;
+  },
+  connections: { resolveUserId: async (email) => (await getUserByEmail(email))?.id ?? null },
+});
+
+app.route('/', oauth.router);
+// The resource server's half, on the same key and origin resolution:
+const identity = await oauth.verifyBearer(token, request, { requiredScope: 'mcp:write' });
+```
+
+## Minimal host (the two gates)
+
+```ts
+// scripts/mcp/generate.ts  (mcp:generate / mcp:check)
+import { mcpGenerateCli } from '@12-apps/mcp/generate';
+mcpGenerateCli({
+  document: () => buildOpenApiDocument(),
+  version: MCP_SURFACE_VERSION,
+  source: 'my app',
+  versionLocation: 'lib/mcp/surface-version.ts',
+  outputs: { openapi: …, manifest: …, surfaceLock: … },
+  extraArtifacts: [{ path: submissionPath, render: renderSubmission }],
+  check: process.argv.includes('--check'),
+});
+
+// scripts/mcp/coverage.ts  (mcp:coverage)
+import { mcpCoverageCli } from '@12-apps/mcp/coverage';
+mcpCoverageCli({ appDir, webRoot, endpoints, exclusionsPath, actionMapPath });
+```
+
+Two things about the gates worth knowing before you adopt them:
+
+- **The scan root is the whole `app` folder, never `app/api`.** A completeness gate
+  rooted below the surface it claims to cover does not fail when it misses
+  something — it simply never looks, and three OAuth/JWKS discovery routes shipped
+  unregistered for exactly as long as that was true.
+- **The filesystem walk is imported from `@12-apps/rbac/coverage`**, not copied.
+  Both gates assert completeness over the same two surfaces, and they must not be
+  able to disagree about what the surface IS; two copies agree on the day they are
+  written and drift silently afterwards, in the direction of not looking.
+- `mcp:coverage` reports staleness for ACTION exclusions only, exactly as the host
+  gate did. Route-prefix staleness is a follow-up (it would go red on a host's
+  committed exclusions file the moment it adopted the package, so it needs its own
+  burn-down).
+
+## Phase B — adopting into a host that ALREADY has these tables (future-pay)
+
+**Nothing to baseline.** Every statement in the package migration is guarded
+(`CREATE TABLE IF NOT EXISTS`, `CREATE [UNIQUE] INDEX IF NOT EXISTS`, `ADD COLUMN
+IF NOT EXISTS`, and a conrelid-scoped `DO` block for the CHECK), so applying it to
+a host that already has `oauth_clients` / `oauth_refresh_tokens` /
+`mcp_connections` changes nothing and exits 0 — no `prisma migrate resolve
+--applied` step, and no risk of a green deploy that skipped a schema change.
+
+Deliberate deltas to reconcile:
+
+- **The FK from `mcp_connections.user_id` to `users` is not in the package
+  migration** — host vocabulary. future-pay keeps its `ON DELETE CASCADE`.
+- **`onboarding_states` is not here.** future-pay's migration created it beside
+  `mcp_connections`; it belongs to `@12-apps/onboarding` (12-23).
+- The host's `lib/mcp/oauth/**` (~1.5k LOC) and its four route files are replaced
+  by the mount plus, where a coverage gate forces the file to exist, a one-line
+  `export const GET = mcpOauth.handlers.authorize`.
+- `scripts/mcp/generate.ts`, `scripts/mcp/coverage.ts` and
+  `scripts/mcp/surface-lock.ts` collapse into the two CLI calls above.
+
+## What deliberately did NOT move into the package
+
+- **The account/connection SCREENS' endpoints** (`GET/DELETE
+  /api/account/mcp-connections`) — they mix session resolution, published plugin
+  URLs and a logger. The stores they need (`listActive`, `revokeByHost`,
+  `revokeLiveForClient`) are all here; the route is a follow-up.
+- **The MCP registry itself** — which endpoints become tools, their annotations
+  and redactions, is the host's catalogue. The package generates, dispatches and
+  gates it.
+- **`mcp:lint`, `mcp:parity`, `mcp:smoke`, `mcp:test-coverage`** — the remaining
+  future-pay MCP scripts. Only the two the reusable CI workflows shell out to moved
+  (12-23's scope).
+- **Authorization codes as rows.** They are stateless signed blobs, so there is no
+  table and nothing to sweep — only the replay store (rule 8).

package/README.md

@@ -35,19 +35,46 @@ across apps.
 | `buildManifest` / `serializeManifest` | The committed drift artifact `mcp:check` regenerates + diffs (see `12-apps/ci` `mcp-contract.yml`). |
 | `buildProtectedResourceMetadata` / `bearerChallenge` | OAuth 2.0 Protected Resource Metadata (RFC 9728) + `WWW-Authenticate` for the resource-server mode. |
 
+## The authorization server (12-23)
+
+The passthrough above needs somebody to MINT the bearer it forwards, and until
+12-23 every app wrote that itself — ~1.5k LOC of authorize/token/register plus the
+code, PKCE, rotation and replay machinery under it. All of that is the surface's
+contract, so it lives here now:
+
+| Entry | Export | Role |
+|---|---|---|
+| `./oauth` | `createApiMcpOauth({ stores, resolveSession })` | OAuth 2.1 authorization server: `register` (RFC 7591) / `authorize` (code + mandatory PKCE S256) / `token` (code + refresh), the JWKS, and BOTH `.well-known` documents. Also the primitives — stateless signed codes, ES256 access tokens, hashed rotating refresh tokens with lineage revocation, the `verifyBearer` resource-server half. |
+| `./hono` | `mcpOauthRouter(config)` | The same surface as a router, mounted at the **origin root** (a connector reads `.well-known` from the origin, never from a prefix). `hono` is an OPTIONAL peer. |
+| `./generate` | `mcpGenerateCli(options)` | `mcp:generate` / `mcp:check` — the committed manifest and its drift gate. |
+| `./coverage` | `mcpCoverageCli(options)` | `mcp:coverage` — every route method and server action either exposed as a tool or excluded with a reason. |
+| `prisma/` | `mcp.prisma` + a migration | `OAuthClient`, `OAuthRefreshToken`, `McpConnection`. Authorization codes are deliberately NOT a table: they are stateless signed blobs. |
+
+The gates are library + CLI FACE, so a host's `scripts/mcp/{generate,coverage}.ts`
+becomes an import and one call, and the reusable CI workflows
+(`12-apps/ci`'s `mcp-contract.yml`) keep shelling out to the same package scripts.
+
+**[ADOPTING.md](./ADOPTING.md) is the adoption contract** — the config table, the
+ten wiring rules (the operator gate, the trusted-origin allowlist, the
+multi-instance caveat on the replay store) and the Phase B notes.
+
+```ts
+const mcpOauth = mcpOauthRouter({
+  stores: createPrismaMcpStores(async () => (await getPrismaClient()) as unknown as McpOauthPrisma),
+  resolveSession: async (request) => sessionOf(request),   // cookie session ONLY
+  enabled: () => process.env.MCP_BEARER_ENABLED === '1',
+  trustedOrigins: trustedOriginsFromEnv('MCP_OAUTH_TRUSTED_ORIGINS'),
+});
+app.route('/', mcpOauth.router);
+```
+
 ## What the app provides (not here)
 
-- The **OpenAPI document** (from its Zod-schema'd routes).
-- The **`AuthResolver`** — validates the incoming access token (OAuth
-  resource-server: signature / audience / scope) and returns the bearer to
-  forward. In future-pay this is the `getRequestSession()` shim over NextAuth
-  `auth()`.
+- The **OpenAPI document** (from its Zod-schema'd routes) and the registry that
+  decides which endpoints become tools.
+- **Who is signed in** — the cookie session `authorize` binds a code to, and the
+  `AuthResolver` for the resource-server side.
+- **Where the data lives** — the three stores (one line with
+  `createPrismaMcpStores`), and the signing material.
 - Binding `ToolRegistry` to the **MCP transport** (the `@modelcontextprotocol/sdk`
   HTTP server at `/api/mcp`).
-
-## Status
-
-Scaffold: the generator, dispatcher, registry, manifest, and OAuth
-resource-metadata helpers are implemented and dependency-light (no MCP SDK). The
-SDK/HTTP transport binding and the app-side `AuthResolver` land in the pilot's
-next phase (`apps/web`). See the pilot design notes under `docs/`.

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "@12-apps/mcp",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "type": "module",
-  "description": "App-agnostic MCP server core: generate one MCP tool per OpenAPI operation and proxy each call to the endpoint carrying the caller's bearer token (permission passthrough). Also ships the reusable AI-connect onboarding UI at @12-apps/mcp/react.",
+  "description": "App-agnostic MCP server core: generate one MCP tool per OpenAPI operation and proxy each call carrying the caller's bearer token (permission passthrough). Also ships the OAuth 2.1 authorization server (./oauth, ./hono: register/authorize/token, JWKS and both .well-known documents), the package-owned Prisma partial + migration for its three tables, the mcp:generate/mcp:check (./generate) and mcp:coverage (./coverage) gates, and the reusable AI-connect onboarding UI (./react).",
   "exports": {
     ".": "./src/index.ts",
-    "./react": "./src/react/index.ts"
+    "./react": "./src/react/index.ts",
+    "./oauth": "./src/oauth/index.ts",
+    "./hono": "./src/hono/index.ts",
+    "./coverage": "./src/coverage-gate/index.ts",
+    "./generate": "./src/generate/index.ts",
+    "./package.json": "./package.json"
   },
   "scripts": {
     "clean": "rm -rf node_modules coverage",
@@ -13,24 +18,32 @@
     "test:watch": "vitest watch",
     "lint": "eslint src --max-warnings 0",
     "check-types": "tsc --noEmit",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prisma:sync": "node scripts/sync-mcp-schema.mjs",
+    "prisma:sync:check": "node scripts/sync-mcp-schema.mjs --check"
   },
   "dependencies": {
+    "@12-apps/onboarding": "^1.20.0",
+    "@12-apps/rbac": "^1.20.0",
+    "@12-apps/ui": "^4.0.0",
     "@mui/icons-material": "^6.5.0",
-    "@12-apps/onboarding": "^1.19.0",
-    "@12-apps/ui": "^1.19.0",
+    "jose": "^6.1.3",
     "react": "^19.2.0"
   },
   "peerDependencies": {
-    "react": ">=19.0.0"
+    "react": ">=19.0.0",
+    "hono": ">=4.0.0"
   },
   "devDependencies": {
+    "@12-apps/eslint-config": "^1.20.0",
+    "@12-apps/typescript-config": "^1.20.0",
     "@mui/material": "^6.5.0",
     "@testing-library/react": "^16.1.0",
-    "@12-apps/typescript-config": "^1.20.0",
     "@types/node": "^22.15.3",
     "@types/react": "19.2.2",
     "eslint": "^9.39.1",
+    "eslint-plugin-test-flakiness": "^1.4.0",
+    "hono": "^4.6.0",
     "jsdom": "^25.0.1",
     "react-dom": "^19.2.0",
     "typescript": "^5.8.2",
@@ -53,6 +66,7 @@
     "src",
     "dist",
     "prisma",
+    "scripts",
     "*.js",
     "*.mjs",
     "*.md",
@@ -64,5 +78,10 @@
     "!**/*.stories.*",
     "!**/*.test-story.*",
     "!**/test-helpers.*"
-  ]
+  ],
+  "peerDependenciesMeta": {
+    "hono": {
+      "optional": true
+    }
+  }
 }

package/prisma/mcp.prisma

@@ -0,0 +1,108 @@
+// ---------------------------------------------------------------------------
+// @12-apps/mcp — CANONICAL Prisma model partial (plug-and-play).
+//
+// The three tables behind an MCP surface's authorization server. A host project
+// does NOT copy these models into its main schema by hand: it uses Prisma's
+// multi-file schema folder and SYNCS this file into it with this package's
+// `prisma:sync` script (a byte-for-byte COPY — never a symlink; see
+// scripts/sync-mcp-schema.mjs for why). The migration ships alongside, in
+// prisma/migrations/, and is copied into the host's migrations folder by the
+// host's plugin-migration sync.
+//
+// Host-agnostic by design (the entity-lifecycle / rbac doctrine): `user_id` is a
+// by-value scalar with NO relation, because this package cannot know the name of
+// the host's user model. The host's own migration may add the FK (future-pay's
+// is ON DELETE CASCADE). Note there is deliberately no `oauth_codes` table:
+// authorization codes are STATELESS signed blobs, so there is nothing to store
+// and nothing to sweep.
+// ---------------------------------------------------------------------------
+
+// A registered external OAuth host — a Claude.ai / ChatGPT connector produced by
+// RFC 7591 dynamic client registration, or a static registration an operator
+// created out of band. This is the OAuth *client application*, NOT a
+// multi-tenant customer: namespaced `OAuth*` to avoid that collision, and with
+// no relation to any user (clients are apps, not people).
+//
+// `clientId` is the public, unique identifier; `clientSecretHash` is null for
+// public PKCE clients (which authenticate via `token_endpoint_auth_method =
+// "none"`) and holds a SHA-256 hash for confidential ones — the plaintext secret
+// is returned exactly once at registration and never persisted. `redirectUris`
+// is the EXACT-MATCH allowlist the authorization endpoint validates against for
+// open-redirect prevention. Array columns are Postgres `TEXT[]`.
+model OAuthClient {
+  id                      String   @id @default(uuid())
+  clientId                String   @unique @map("client_id")
+  clientSecretHash        String?  @map("client_secret_hash")
+  redirectUris            String[] @map("redirect_uris")
+  clientName              String?  @map("client_name")
+  // "none" (public PKCE) | "client_secret_basic" (confidential). String + CHECK
+  // (the house convention), not a Prisma enum; validated at the register route.
+  tokenEndpointAuthMethod String   @default("none") @map("token_endpoint_auth_method")
+  grantTypes              String[] @map("grant_types")
+  scopes                  String[]
+  createdAt               DateTime @default(now()) @map("created_at")
+  updatedAt               DateTime @updatedAt @map("updated_at")
+
+  @@map("oauth_clients")
+}
+
+// A rotating OAuth refresh token bound to a signed-in user + a registered
+// client. Stored HASHED (`tokenHash` = SHA-256 of the opaque token, never
+// plaintext) and rotated on every use. Identity is the user's EMAIL: the AS binds
+// to email and a host's guards resolve their user row by it, so this is a scalar
+// rather than a FK and the token store stays decoupled from the user table.
+// `userSub` is the original OAuth subject, carried so a rotated successor mints
+// an access token with the SAME stable `sub` as the initial one (RFC 6749 §5.1 /
+// OIDC §2) — without it a refreshed token's `sub` would fall back to the email
+// and diverge, breaking identity correlation after the first refresh.
+// `clientId` is a by-value link to `OAuthClient.clientId`. Rotation lineage:
+// `rotatedFrom` holds the prior token's hash so reuse of a rotated token is
+// detectable and revokes the whole lineage; `revokedAt` is the explicit revoke
+// path.
+model OAuthRefreshToken {
+  id          String    @id @default(uuid())
+  tokenHash   String    @unique @map("token_hash")
+  userEmail   String    @map("user_email")
+  userSub     String    @map("user_sub")
+  clientId    String    @map("client_id")
+  scopes      String[]
+  expiresAt   DateTime  @map("expires_at")
+  rotatedFrom String?   @map("rotated_from")
+  revokedAt   DateTime? @map("revoked_at")
+  createdAt   DateTime  @default(now()) @map("created_at")
+
+  // `tokenHash` is already indexed by its `@unique` constraint — the
+  // lookup-on-presentation path — so no separate `@@index([tokenHash])` is added
+  // (it would be redundant). The composite index serves per-user/per-client
+  // enumeration and bulk revoke.
+  @@index([userEmail, clientId])
+  @@map("oauth_refresh_tokens")
+}
+
+// A live AI-assistant (MCP) connection a user has authorized. MCP auth is
+// auth-passthrough / per-user (a token is not tenant-scoped), so this is keyed by
+// the host's user id + the registered OAuth client — NOT by tenant. `clientName`
+// snapshots the client's display name for the UI (a registration can change it).
+// `lastActiveAt` is bumped (throttled, best-effort) on each token grant so a
+// config page can show "connected via Claude · active 2 min ago" and an operator
+// panel can tell an active connection from a stalled one. `host` is the AI
+// provider the connection is attributed to (claude / chatgpt / codex), derived
+// from the client's redirect URIs at grant time and confirmable by a self-report
+// tool; null for a pre-attribution connection. `revokedAt` is the explicit
+// disconnect path — and ending the connection is only half of a disconnect, since
+// a host holding a live refresh token would simply rotate its way back in.
+model McpConnection {
+  id            String    @id @default(uuid())
+  userId        String    @map("user_id")
+  oauthClientId String    @map("oauth_client_id")
+  clientName    String?   @map("client_name")
+  host          String?   @map("host")
+  connectedAt   DateTime  @default(now()) @map("connected_at")
+  lastActiveAt  DateTime  @default(now()) @map("last_active_at")
+  revokedAt     DateTime? @map("revoked_at")
+
+  @@unique([userId, oauthClientId])
+  @@index([userId])
+  @@index([lastActiveAt])
+  @@map("mcp_connections")
+}

package/prisma/migrations/20260812150000_add_mcp_oauth_tables/migration.sql

@@ -0,0 +1,152 @@
+-- @12-apps/mcp (12-23): the three tables behind an MCP surface's OAuth 2.1
+-- authorization server, owned by the package and copied into a host's migrations
+-- folder by its plugin-migration sync.
+--
+--   * oauth_clients        — a registered external host (a Claude.ai / ChatGPT
+--                            connector) from RFC 7591 dynamic client
+--                            registration or a static registration. NOT a
+--                            multi-tenant customer table — namespaced to avoid
+--                            that collision; no FK to users (clients are apps).
+--   * oauth_refresh_tokens — a rotating refresh token bound to a user email +
+--                            client, stored HASHED (SHA-256), rotated on use
+--                            with `rotated_from` lineage and a `revoked_at`
+--                            revoke path.
+--   * mcp_connections      — which AI host a user has connected, and how
+--                            recently it was active. Per-USER, because an MCP
+--                            bearer is auth-passthrough and not tenant-scoped.
+--
+-- Authorization codes are deliberately absent: they are STATELESS signed blobs,
+-- so there is no table to create and nothing to sweep.
+--
+-- The columns, defaults, indexes and CHECK are future-pay's
+-- `20260713120000_add_oauth_client_refresh`,
+-- `20260715180000_add_onboarding_state_mcp_connection` (the mcp_connections half
+-- — the onboarding half belongs to @12-apps/onboarding) and
+-- `20260720120000_add_mcp_connection_host` verbatim, minus the FK to `users`:
+-- this package cannot know the name of a host's user table, and a host that has
+-- one keeps its own constraint (future-pay's is ON DELETE CASCADE).
+--
+-- EVERY statement is guarded (`IF NOT EXISTS`, and a conrelid-scoped DO block for
+-- the CHECK, which has no IF NOT EXISTS form). That is what makes adoption by a
+-- host that ALREADY has these tables a no-op instead of a failed deploy — and
+-- what lets the PGlite provisioner replay it into an existing schema.
+--
+-- Guarding every STATEMENT is not the same as guarding every COLUMN, though, and
+-- the difference bites exactly the host this file is written for: `CREATE TABLE IF
+-- NOT EXISTS` skips the whole table, columns included, so a host holding an OLDER
+-- shape of one of these tables silently keeps it. Each table below is therefore
+-- followed by a guarded `ADD COLUMN` for every column that reached future-pay in a
+-- LATER migration than its own CREATE. The full audit: `oauth_refresh_tokens
+-- .user_sub` (`20260713150000_add_oauth_refresh_user_sub`) and `mcp_connections
+-- .host` (`20260720120000_add_mcp_connection_host`). `oauth_clients` needs none —
+-- it arrived complete, CHECK and all, and was never altered afterwards. A column
+-- added to this file later needs the same treatment.
+
+-- Registered OAuth client (host app). Array columns are Postgres TEXT[]:
+-- redirect_uris is the exact-match allowlist for open-redirect prevention;
+-- grant_types / scopes are the DCR metadata.
+CREATE TABLE IF NOT EXISTS "oauth_clients" (
+    "id" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+    "client_secret_hash" TEXT,
+    "redirect_uris" TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+    "client_name" TEXT,
+    "token_endpoint_auth_method" TEXT NOT NULL DEFAULT 'none',
+    "grant_types" TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+    "scopes" TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "oauth_clients_pkey" PRIMARY KEY ("id")
+);
+
+-- Public identifier a token/authorize request presents; unique across clients.
+CREATE UNIQUE INDEX IF NOT EXISTS "oauth_clients_client_id_key"
+  ON "oauth_clients"("client_id");
+
+-- token_endpoint_auth_method domain guard (String+CHECK house style). Scoped to
+-- conrelid because constraint names are unique only per table.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+    WHERE conname = 'oauth_clients_token_endpoint_auth_method_valid'
+      AND conrelid = 'oauth_clients'::regclass
+  ) THEN
+    ALTER TABLE "oauth_clients"
+      ADD CONSTRAINT "oauth_clients_token_endpoint_auth_method_valid"
+      CHECK ("token_endpoint_auth_method" IN ('none', 'client_secret_basic'));
+  END IF;
+END $$;
+
+-- Rotating refresh token. token_hash is the SHA-256 of the opaque token (never
+-- plaintext); user_email is the bound identity; user_sub is the original OAuth
+-- subject, kept stable across every rotation; client_id is a by-value link to
+-- oauth_clients.client_id; rotated_from carries the prior token's hash for
+-- rotation lineage / replay detection; revoked_at is the explicit revoke path.
+CREATE TABLE IF NOT EXISTS "oauth_refresh_tokens" (
+    "id" TEXT NOT NULL,
+    "token_hash" TEXT NOT NULL,
+    "user_email" TEXT NOT NULL,
+    "user_sub" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+    "scopes" TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+    "expires_at" TIMESTAMP(3) NOT NULL,
+    "rotated_from" TEXT,
+    "revoked_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "oauth_refresh_tokens_pkey" PRIMARY KEY ("id")
+);
+
+-- Lookup-on-presentation: hash the incoming token, find its row. Unique so a
+-- duplicate insert is a DB-level error rather than a silent second live token.
+CREATE UNIQUE INDEX IF NOT EXISTS "oauth_refresh_tokens_token_hash_key"
+  ON "oauth_refresh_tokens"("token_hash");
+
+-- Per-user/per-client enumeration + bulk revoke (the lineage walk's input, and
+-- the disconnect path).
+CREATE INDEX IF NOT EXISTS "oauth_refresh_tokens_user_email_client_id_idx"
+  ON "oauth_refresh_tokens"("user_email", "client_id");
+
+-- `CREATE TABLE IF NOT EXISTS` skips the WHOLE table, so a host that already holds
+-- `oauth_refresh_tokens` in an OLDER SHAPE gets none of the columns declared above
+-- — statement-level guarding is not the same as column-level guarding. That is
+-- precisely how future-pay's own history ran: `user_sub` arrived in a SECOND
+-- migration (FUT-105, `20260713150000_add_oauth_refresh_user_sub`), so a host
+-- frozen before it would adopt this file, skip the CREATE, never get the column,
+-- and then fail on every refresh the package serves. Mirror future-pay's pair
+-- verbatim — guarded add with a backfill default to satisfy NOT NULL, then drop
+-- the default so the column matches the Prisma schema (`String`, no default).
+-- Both statements are no-ops on a fresh host and on a replay.
+ALTER TABLE "oauth_refresh_tokens"
+  ADD COLUMN IF NOT EXISTS "user_sub" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "oauth_refresh_tokens"
+  ALTER COLUMN "user_sub" DROP DEFAULT;
+
+-- A user's live AI connections. `host` is nullable: a connection can exist before
+-- any provider attribution is derivable (a CLI callback with no public domain).
+CREATE TABLE IF NOT EXISTS "mcp_connections" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "oauth_client_id" TEXT NOT NULL,
+    "client_name" TEXT,
+    "host" TEXT,
+    "connected_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "last_active_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "revoked_at" TIMESTAMP(3),
+
+    CONSTRAINT "mcp_connections_pkey" PRIMARY KEY ("id")
+);
+
+-- One connection row per (user, OAuth client) — the upsert key for liveness.
+CREATE UNIQUE INDEX IF NOT EXISTS "mcp_connections_user_id_oauth_client_id_key"
+  ON "mcp_connections"("user_id", "oauth_client_id");
+CREATE INDEX IF NOT EXISTS "mcp_connections_user_id_idx" ON "mcp_connections"("user_id");
+CREATE INDEX IF NOT EXISTS "mcp_connections_last_active_at_idx"
+  ON "mcp_connections"("last_active_at");
+
+-- A host adopting this migration where `mcp_connections` predates the `host`
+-- column (future-pay added it in a later migration) gets it here; a fresh host
+-- already has it from the CREATE above, so the guard makes both cases a no-op.
+ALTER TABLE "mcp_connections" ADD COLUMN IF NOT EXISTS "host" TEXT;