@12-apps/mcp 3.11.0 → 3.13.0

package/dist/oauth/index.js

@@ -1,6 +1,9 @@
 import {
-  providerForHostId
-} from "../chunk-FBUSSQSK.js";
+  createPrismaMcpStores,
+  disconnectAiHost,
+  listAiConnections
+} from "../chunk-VDD4YRNP.js";
+import "../chunk-FBUSSQSK.js";
 import {
   ACCESS_TOKEN_TTL_SECONDS,
   AUTHORIZATION_CODE_AUDIENCE,
@@ -44,193 +47,7 @@ import {
   verifyCode
 } from "../chunk-UIILEGAC.js";
 import "../chunk-WJJNKKNS.js";
-import {
-  __name
-} from "../chunk-7QVYU63E.js";
-
-// src/oauth/prisma-stores.ts
-function clientStore(getPrisma) {
-  return {
-    async create(client) {
-      const prisma = await getPrisma();
-      return prisma.oAuthClient.create({ data: client });
-    },
-    async findByClientId(clientId) {
-      const prisma = await getPrisma();
-      return prisma.oAuthClient.findUnique({ where: { clientId } });
-    }
-  };
-}
-__name(clientStore, "clientStore");
-function refreshTokenStore(getPrisma) {
-  return {
-    async create(token) {
-      const prisma = await getPrisma();
-      await prisma.oAuthRefreshToken.create({ data: token });
-    },
-    async findByHash(tokenHash) {
-      const prisma = await getPrisma();
-      return prisma.oAuthRefreshToken.findUnique({ where: { tokenHash } });
-    },
-    async hasSuccessor(tokenHash) {
-      const prisma = await getPrisma();
-      const successor = await prisma.oAuthRefreshToken.findFirst({
-        where: { rotatedFrom: tokenHash }
-      });
-      return successor !== null;
-    },
-    async listFamily(userEmail, clientId) {
-      const prisma = await getPrisma();
-      return prisma.oAuthRefreshToken.findMany({ where: { userEmail, clientId } });
-    },
-    async revokeHashes(tokenHashes, at) {
-      if (tokenHashes.length === 0) return;
-      const prisma = await getPrisma();
-      await prisma.oAuthRefreshToken.updateMany({
-        where: { tokenHash: { in: [...tokenHashes] } },
-        data: { revokedAt: at }
-      });
-    },
-    async rotate(successor, parentHash, at) {
-      const prisma = await getPrisma();
-      return prisma.$transaction(async (tx) => {
-        const { count } = await tx.oAuthRefreshToken.updateMany({
-          where: { tokenHash: parentHash, revokedAt: null },
-          data: { revokedAt: at }
-        });
-        if (count !== 1) return false;
-        await tx.oAuthRefreshToken.create({ data: successor });
-        return true;
-      });
-    },
-    async revokeLiveForClient(userEmail, clientId) {
-      const prisma = await getPrisma();
-      const { count } = await prisma.oAuthRefreshToken.updateMany({
-        where: { userEmail, clientId, revokedAt: null },
-        data: { revokedAt: /* @__PURE__ */ new Date() }
-      });
-      return count;
-    }
-  };
-}
-__name(refreshTokenStore, "refreshTokenStore");
-var CONNECTION_SELECT = {
-  oauthClientId: true,
-  clientName: true,
-  host: true,
-  connectedAt: true,
-  lastActiveAt: true
-};
-function connectionStore(getPrisma) {
-  return {
-    async lastActiveAt(userId, oauthClientId) {
-      const prisma = await getPrisma();
-      const row = await prisma.mcpConnection.findUnique({
-        where: { userId_oauthClientId: { userId, oauthClientId } },
-        select: { lastActiveAt: true }
-      });
-      return row?.lastActiveAt ?? null;
-    },
-    async recordActivity({ userId, oauthClientId, clientName, host, at }) {
-      const prisma = await getPrisma();
-      await prisma.mcpConnection.upsert({
-        where: { userId_oauthClientId: { userId, oauthClientId } },
-        create: { userId, oauthClientId, clientName, host, connectedAt: at, lastActiveAt: at },
-        // Never blank a known host on refresh — keep the existing attribution
-        // when this grant cannot derive one.
-        update: {
-          clientName,
-          lastActiveAt: at,
-          revokedAt: null,
-          ...host ? { host } : {}
-        }
-      });
-    },
-    async listActive(userId) {
-      const prisma = await getPrisma();
-      const rows = await prisma.mcpConnection.findMany({
-        where: { userId, revokedAt: null },
-        orderBy: { lastActiveAt: "desc" },
-        select: { ...CONNECTION_SELECT }
-      });
-      return rows;
-    },
-    revokeByHost: /* @__PURE__ */ __name((userId, host) => revokeByHost(getPrisma, userId, host), "revokeByHost"),
-    announce: /* @__PURE__ */ __name((userId, host) => announce(getPrisma, userId, host), "announce")
-  };
-}
-__name(connectionStore, "connectionStore");
-async function revokeByHost(getPrisma, userId, host) {
-  const prisma = await getPrisma();
-  const attributed = await prisma.mcpConnection.findMany({
-    where: { userId, revokedAt: null, host },
-    select: { id: true, oauthClientId: true }
-  });
-  const targets = attributed.length > 0 ? attributed : await prisma.mcpConnection.findMany({
-    where: { userId, revokedAt: null, host: null },
-    select: { id: true, oauthClientId: true }
-  });
-  if (targets.length === 0) return [];
-  await prisma.mcpConnection.updateMany({
-    where: { id: { in: targets.map((row) => String(row.id)) } },
-    data: { revokedAt: /* @__PURE__ */ new Date() }
-  });
-  return targets.map((row) => String(row.oauthClientId));
-}
-__name(revokeByHost, "revokeByHost");
-async function announce(getPrisma, userId, host) {
-  const prisma = await getPrisma();
-  const now = /* @__PURE__ */ new Date();
-  const refreshed = await prisma.mcpConnection.updateMany({
-    where: { userId, revokedAt: null, host },
-    data: { lastActiveAt: now, revokedAt: null }
-  });
-  if (refreshed.count > 0) return refreshed.count;
-  const candidate = await prisma.mcpConnection.findFirst({
-    where: { userId, revokedAt: null, host: null },
-    orderBy: { lastActiveAt: "desc" },
-    select: { id: true }
-  });
-  if (!candidate) return 0;
-  await prisma.mcpConnection.update({
-    where: { id: candidate.id },
-    data: { host, lastActiveAt: now, revokedAt: null }
-  });
-  return 1;
-}
-__name(announce, "announce");
-function createPrismaMcpStores(getPrisma) {
-  return {
-    clients: clientStore(getPrisma),
-    refreshTokens: refreshTokenStore(getPrisma),
-    connections: connectionStore(getPrisma)
-  };
-}
-__name(createPrismaMcpStores, "createPrismaMcpStores");
-
-// src/oauth/connections.ts
-function asProvider(host) {
-  return host === null ? null : providerForHostId(host);
-}
-__name(asProvider, "asProvider");
-async function listAiConnections(connections, userId) {
-  const rows = await connections.listActive(userId);
-  return rows.map((row) => ({ ...row, host: asProvider(row.host) }));
-}
-__name(listAiConnections, "listAiConnections");
-async function disconnectAiHost(stores, caller, host) {
-  const disconnectedClientIds = await stores.connections.revokeByHost(caller.userId, host);
-  const revoked = await Promise.all(
-    disconnectedClientIds.map(
-      (clientId) => stores.refreshTokens.revokeLiveForClient(caller.email, clientId)
-    )
-  );
-  return {
-    disconnectedClientIds,
-    revokedRefreshTokens: revoked.reduce((total, count) => total + count, 0)
-  };
-}
-__name(disconnectAiHost, "disconnectAiHost");
+import "../chunk-7QVYU63E.js";
 export {
   ACCESS_TOKEN_TTL_SECONDS,
   AUTHORIZATION_CODE_AUDIENCE,

package/dist/oauth/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/oauth/prisma-stores.ts","../../src/oauth/connections.ts"],"sourcesContent":["import type {\n  McpConnectionStore,\n  McpOauthStores,\n  NewOAuthClient,\n  NewRefreshToken,\n  OAuthClientStore,\n  RefreshTokenStore,\n  StoredMcpConnection,\n  StoredOAuthClient,\n  StoredRefreshToken,\n} from \"./stores\";\n\n/**\n * The ports of `./stores.ts`, filled by Prisma (12-23).\n *\n * The package owns the three models (`prisma/mcp.prisma`), so their delegate\n * shapes are known and this adapter can be exact. A host with Prisma therefore\n * writes ONE line —\n *\n *   stores: createPrismaMcpStores(async () => getPrismaClient() as unknown as McpOauthPrisma)\n *\n * — and no host code at all beyond it. The client is duck-typed (only the\n * delegates used, only the arguments used) so this file never imports a project's\n * generated client, and a non-Prisma host fills the ports directly instead.\n */\n\n/** A `where` on the composite unique of `mcp_connections`. */\ninterface ConnectionKey {\n  userId_oauthClientId: { userId: string; oauthClientId: string };\n}\n\n/** The minimal Prisma surface the AS needs. Every field is one the surface writes. */\nexport interface McpOauthPrisma {\n  oAuthClient: {\n    create(args: { data: NewOAuthClient }): Promise<StoredOAuthClient>;\n    findUnique(args: { where: { clientId: string } }): Promise<StoredOAuthClient | null>;\n  };\n  oAuthRefreshToken: {\n    create(args: { data: NewRefreshToken }): Promise<unknown>;\n    findUnique(args: { where: { tokenHash: string } }): Promise<StoredRefreshToken | null>;\n    findFirst(args: { where: { rotatedFrom: string } }): Promise<{ tokenHash: string } | null>;\n    findMany(args: {\n      where: { userEmail: string; clientId: string };\n    }): Promise<StoredRefreshToken[]>;\n    // No single-row `update`: the rotation used to revoke its parent with one and\n    // that was the bug (unconditional, so two concurrent rotations both won). Every\n    // revoke here is now an `updateMany` with a predicate that says WHICH rows may\n    // move, which is also why this delegate list stays honest about what is written.\n    updateMany(args: {\n      where:\n        | { tokenHash: { in: string[] } }\n        | { userEmail: string; clientId: string; revokedAt: null };\n      data: { revokedAt: Date };\n    }): Promise<{ count: number }>;\n  };\n  mcpConnection: {\n    findUnique(args: {\n      where: ConnectionKey;\n      select: { lastActiveAt: true };\n    }): Promise<{ lastActiveAt: Date } | null>;\n    findFirst(args: {\n      where: { userId: string; revokedAt: null; host: null };\n      orderBy: { lastActiveAt: \"desc\" };\n      select: { id: true };\n    }): Promise<{ id: string } | null>;\n    findMany(args: {\n      where: { userId: string; revokedAt: null; host?: string | null };\n      orderBy?: { lastActiveAt: \"desc\" };\n      select: Record<string, true>;\n    }): Promise<Record<string, unknown>[]>;\n    upsert(args: {\n      where: ConnectionKey;\n      create: Record<string, unknown>;\n      update: Record<string, unknown>;\n    }): Promise<unknown>;\n    update(args: { where: { id: string }; data: Record<string, unknown> }): Promise<unknown>;\n    updateMany(args: {\n      where: { id: { in: string[] } } | { userId: string; revokedAt: null; host: string };\n      data: Record<string, unknown>;\n    }): Promise<{ count: number }>;\n  };\n  /**\n   * Prisma's INTERACTIVE transaction, used for the rotation's claim + write. The\n   * callback form (not the array form) is required: the successor may only be\n   * created once the conditional revoke has reported that it, and not a concurrent\n   * sibling, claimed the parent — see `RefreshTokenStore.rotate`.\n   */\n  $transaction<T>(fn: (tx: McpOauthTx) => Promise<T>): Promise<T>;\n}\n\n/**\n * The delegate subset used INSIDE the rotation transaction. Not exported: it is\n * reachable structurally through `McpOauthPrisma.$transaction`, so no host ever\n * needs to name it, and exporting a type nobody imports is what knip flags.\n */\ninterface McpOauthTx {\n  oAuthRefreshToken: {\n    create(args: { data: NewRefreshToken }): Promise<unknown>;\n    updateMany(args: {\n      where: { tokenHash: string; revokedAt: null };\n      data: { revokedAt: Date };\n    }): Promise<{ count: number }>;\n  };\n}\n\n/** A lazily-resolved client, so a host's singleton is awaited per call. */\nexport type McpOauthPrismaProvider = () => Promise<McpOauthPrisma>;\n\nfunction clientStore(getPrisma: McpOauthPrismaProvider): OAuthClientStore {\n  return {\n    async create(client: NewOAuthClient) {\n      const prisma = await getPrisma();\n      return prisma.oAuthClient.create({ data: client });\n    },\n    async findByClientId(clientId: string) {\n      const prisma = await getPrisma();\n      return prisma.oAuthClient.findUnique({ where: { clientId } });\n    },\n  };\n}\n\nfunction refreshTokenStore(getPrisma: McpOauthPrismaProvider): RefreshTokenStore {\n  return {\n    async create(token) {\n      const prisma = await getPrisma();\n      await prisma.oAuthRefreshToken.create({ data: token });\n    },\n    async findByHash(tokenHash) {\n      const prisma = await getPrisma();\n      return prisma.oAuthRefreshToken.findUnique({ where: { tokenHash } });\n    },\n    async hasSuccessor(tokenHash) {\n      const prisma = await getPrisma();\n      const successor = await prisma.oAuthRefreshToken.findFirst({\n        where: { rotatedFrom: tokenHash },\n      });\n      return successor !== null;\n    },\n    async listFamily(userEmail, clientId) {\n      const prisma = await getPrisma();\n      return prisma.oAuthRefreshToken.findMany({ where: { userEmail, clientId } });\n    },\n    async revokeHashes(tokenHashes, at) {\n      if (tokenHashes.length === 0) return;\n      const prisma = await getPrisma();\n      await prisma.oAuthRefreshToken.updateMany({\n        where: { tokenHash: { in: [...tokenHashes] } },\n        data: { revokedAt: at },\n      });\n    },\n    async rotate(successor, parentHash, at) {\n      const prisma = await getPrisma();\n      return prisma.$transaction(async (tx) => {\n        // CLAIM-ONCE. The `revokedAt: null` predicate is what makes this safe under\n        // concurrency, and it is load-bearing rather than defensive: on Postgres's\n        // default READ COMMITTED, a second transaction's `updateMany` blocks on the\n        // row lock, then re-evaluates this WHERE against the COMMITTED row — which\n        // now has a `revokedAt` — and reports 0 rows. So exactly one caller can ever\n        // see count 1, and it is the only one that goes on to create a successor.\n        // An unconditional `update` would let both through: two live successors of\n        // one parent, and replay detection silently defeated (it waits for a third\n        // use of the parent that now never comes).\n        const { count } = await tx.oAuthRefreshToken.updateMany({\n          where: { tokenHash: parentHash, revokedAt: null },\n          data: { revokedAt: at },\n        });\n        // Lost the claim: write NOTHING. The zero-row update commits as the no-op\n        // it is, so there is nothing to roll back.\n        if (count !== 1) return false;\n        // Same transaction as the claim, so a crash cannot leave a live parent AND\n        // a live child either.\n        await tx.oAuthRefreshToken.create({ data: successor });\n        return true;\n      });\n    },\n    async revokeLiveForClient(userEmail, clientId) {\n      const prisma = await getPrisma();\n      const { count } = await prisma.oAuthRefreshToken.updateMany({\n        where: { userEmail, clientId, revokedAt: null },\n        data: { revokedAt: new Date() },\n      });\n      return count;\n    },\n  };\n}\n\n/** The connection columns the account surface reads. */\nconst CONNECTION_SELECT = {\n  oauthClientId: true,\n  clientName: true,\n  host: true,\n  connectedAt: true,\n  lastActiveAt: true,\n} as const;\n\nfunction connectionStore(getPrisma: McpOauthPrismaProvider): McpConnectionStore {\n  return {\n    async lastActiveAt(userId, oauthClientId) {\n      const prisma = await getPrisma();\n      const row = await prisma.mcpConnection.findUnique({\n        where: { userId_oauthClientId: { userId, oauthClientId } },\n        select: { lastActiveAt: true },\n      });\n      return row?.lastActiveAt ?? null;\n    },\n    async recordActivity({ userId, oauthClientId, clientName, host, at }) {\n      const prisma = await getPrisma();\n      await prisma.mcpConnection.upsert({\n        where: { userId_oauthClientId: { userId, oauthClientId } },\n        create: { userId, oauthClientId, clientName, host, connectedAt: at, lastActiveAt: at },\n        // Never blank a known host on refresh — keep the existing attribution\n        // when this grant cannot derive one.\n        update: {\n          clientName,\n          lastActiveAt: at,\n          revokedAt: null,\n          ...(host ? { host } : {}),\n        },\n      });\n    },\n    async listActive(userId) {\n      const prisma = await getPrisma();\n      const rows = await prisma.mcpConnection.findMany({\n        where: { userId, revokedAt: null },\n        orderBy: { lastActiveAt: \"desc\" },\n        select: { ...CONNECTION_SELECT },\n      });\n      return rows as unknown as StoredMcpConnection[];\n    },\n    revokeByHost: (userId, host) => revokeByHost(getPrisma, userId, host),\n    announce: (userId, host) => announce(getPrisma, userId, host),\n  };\n}\n\n/**\n * Disconnect one provider's connections — and ONLY that provider's.\n *\n * Every read and write is scoped by `userId`: a connection is per-user (an MCP\n * bearer is not tenant-scoped), so the user id IS the isolation here, and the\n * `id` list passed to the update comes from a query that already applied it.\n */\nasync function revokeByHost(\n  getPrisma: McpOauthPrismaProvider,\n  userId: string,\n  host: string,\n): Promise<string[]> {\n  const prisma = await getPrisma();\n  const attributed = await prisma.mcpConnection.findMany({\n    where: { userId, revokedAt: null, host },\n    select: { id: true, oauthClientId: true },\n  });\n  // A legacy `host = null` row is claimed only when the provider has no row of\n  // its own: pre-attribution connections must stay disconnectable, but a provider\n  // that DID attribute can never revoke another assistant's row.\n  const targets =\n    attributed.length > 0\n      ? attributed\n      : await prisma.mcpConnection.findMany({\n          where: { userId, revokedAt: null, host: null },\n          select: { id: true, oauthClientId: true },\n        });\n  if (targets.length === 0) return [];\n  await prisma.mcpConnection.updateMany({\n    where: { id: { in: targets.map((row) => String(row.id)) } },\n    data: { revokedAt: new Date() },\n  });\n  return targets.map((row) => String(row.oauthClientId));\n}\n\n/** A provider's self-report: refresh its own row, or claim the unattributed one. */\nasync function announce(\n  getPrisma: McpOauthPrismaProvider,\n  userId: string,\n  host: string,\n): Promise<number> {\n  const prisma = await getPrisma();\n  const now = new Date();\n  const refreshed = await prisma.mcpConnection.updateMany({\n    where: { userId, revokedAt: null, host },\n    data: { lastActiveAt: now, revokedAt: null },\n  });\n  if (refreshed.count > 0) return refreshed.count;\n\n  // No row for this provider yet — attribute the just-connected one. Scoped by\n  // user, so a self-report can never reach another account's connection.\n  const candidate = await prisma.mcpConnection.findFirst({\n    where: { userId, revokedAt: null, host: null },\n    orderBy: { lastActiveAt: \"desc\" },\n    select: { id: true },\n  });\n  if (!candidate) return 0;\n  await prisma.mcpConnection.update({\n    where: { id: candidate.id },\n    data: { host, lastActiveAt: now, revokedAt: null },\n  });\n  return 1;\n}\n\n/** Every port, over one lazily-resolved Prisma client. */\nexport function createPrismaMcpStores(getPrisma: McpOauthPrismaProvider): McpOauthStores {\n  return {\n    clients: clientStore(getPrisma),\n    refreshTokens: refreshTokenStore(getPrisma),\n    connections: connectionStore(getPrisma),\n  };\n}\n","import { providerForHostId, type AiProvider } from \"../guide\";\nimport type {\n  McpConnectionStore,\n  RefreshTokenStore,\n  StoredMcpConnection,\n} from \"./stores\";\n\n/**\n * The account surface's connection OPERATIONS (12-48) — the half of the\n * `GET/DELETE /api/account/mcp-connections` endpoints that is contract rather\n * than host vocabulary.\n *\n * The ROUTE stays in the host on purpose: it mixes the host's session\n * resolution, its response envelope, its published plugin URLs and its logger,\n * and injecting all four here would make the config surface bigger than the\n * handler it replaces. What must NOT stay in each host is the disconnect's\n * both-halves rule, because getting it half right LOOKS right:\n *\n * `connections.revokeByHost` ends the connection rows and returns the OAuth\n * client ids behind them — and a host that stops there has revoked nothing that\n * matters. The assistant still holds a live refresh token for each of those\n * clients, rotates it on schedule, and the very next grant records fresh\n * activity: the card the user just disconnected lights green again on its own.\n * So the rule is one function: revoke the rows AND end every live refresh token\n * of each returned client, in the same call, with no way to import one half\n * without the other.\n *\n * Deliberately NOT invalidated here: the assistant's current ACCESS token.\n * Those are self-contained JWTs the server does not track; a just-disconnected\n * host keeps working for at most their TTL (15 minutes by default) and can then\n * obtain nothing further.\n */\n\n/** An active AI connection, narrowed for display. */\nexport interface AiConnectionSnapshot {\n  oauthClientId: string;\n  clientName: string | null;\n  /** The provider this connection is attributed to (`null` = pre-attribution). */\n  host: AiProvider | null;\n  connectedAt: Date;\n  lastActiveAt: Date;\n}\n\n/** The caller the operations act for — always the session's own user. */\nexport interface AiConnectionCaller {\n  /** The host's user id — what `mcp_connections` rows are keyed by. */\n  userId: string;\n  /** The identity refresh tokens are bound to (the AS binds by email). */\n  email: string;\n}\n\n/** What one disconnect actually ended, for the host's log and response. */\nexport interface AiDisconnectResult {\n  /** OAuth client ids whose connection rows were revoked. */\n  disconnectedClientIds: string[];\n  /** Live refresh tokens ended across those clients — the half that cuts access. */\n  revokedRefreshTokens: number;\n}\n\n/** Narrow a stored `host` string to a known provider, or `null`. */\nfunction asProvider(host: string | null): AiProvider | null {\n  return host === null ? null : providerForHostId(host);\n}\n\n/**\n * A user's active connections, most-recently-active first, with the stored open\n * `host` string narrowed to the package's closed {@link AiProvider} union — the\n * store cannot know which assistants have screens, but the union is this\n * package's own vocabulary (`guide.ts`), so the narrowing lives beside it\n * rather than being re-derived in every host.\n */\nexport async function listAiConnections(\n  connections: McpConnectionStore,\n  userId: string,\n): Promise<AiConnectionSnapshot[]> {\n  const rows: StoredMcpConnection[] = await connections.listActive(userId);\n  return rows.map((row) => ({ ...row, host: asProvider(row.host) }));\n}\n\n/**\n * Disconnect one provider for this user — BOTH halves, atomically from the\n * caller's point of view (see the module doc for why one half alone is a\n * disconnect that undoes itself).\n *\n * Idempotent: disconnecting a provider that was never connected returns zero\n * counts rather than failing, so a double-click is harmless. Repeat calls also\n * report zero — `revokeLiveForClient` skips already-revoked tokens by contract.\n */\nexport async function disconnectAiHost(\n  stores: { connections: McpConnectionStore; refreshTokens: RefreshTokenStore },\n  caller: AiConnectionCaller,\n  host: AiProvider,\n): Promise<AiDisconnectResult> {\n  const disconnectedClientIds = await stores.connections.revokeByHost(caller.userId, host);\n  const revoked = await Promise.all(\n    disconnectedClientIds.map((clientId) =>\n      stores.refreshTokens.revokeLiveForClient(caller.email, clientId),\n    ),\n  );\n  return {\n    disconnectedClientIds,\n    revokedRefreshTokens: revoked.reduce((total, count) => total + count, 0),\n  };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/mcp",
-  "version": "3.11.0",
+  "version": "3.13.0",
   "type": "module",
   "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": {
@@ -28,6 +28,14 @@
       "types": "./dist/generate/index.d.ts",
       "default": "./dist/generate/index.js"
     },
+    "./manifest": {
+      "types": "./dist/manifest/index.d.ts",
+      "default": "./dist/manifest/index.js"
+    },
+    "./manifest/server": {
+      "types": "./dist/manifest/server.d.ts",
+      "default": "./dist/manifest/server.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -42,22 +50,35 @@
     "prisma:sync:check": "node scripts/sync-mcp-schema.mjs --check"
   },
   "dependencies": {
-    "@12-apps/onboarding": "^2.4.0",
-    "@12-apps/rbac": "^4.7.0",
+    "@12-apps/onboarding": "^2.6.0",
+    "@12-apps/rbac": "^4.9.0",
     "@12-apps/ui": "^6.9.0",
     "@mui/icons-material": "^6.5.0",
     "jose": "^6.1.3",
     "react": "^19.2.0"
   },
   "peerDependencies": {
-    "react": ">=19.0.0",
+    "@12-apps/wiring": ">=1.9.0",
     "hono": ">=4.0.0",
+    "react": ">=19.0.0",
     "zod": ">=4.0.0"
   },
+  "peerDependenciesMeta": {
+    "@12-apps/wiring": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@12-apps/eslint-config": "^1.21.1",
-    "@12-apps/i18n": "^1.0.0",
+    "@12-apps/i18n": "^1.1.0",
     "@12-apps/typescript-config": "^1.20.1",
+    "@12-apps/wiring": "^1.13.0",
     "@mui/material": "^6.5.0",
     "@testing-library/react": "^16.1.0",
     "@types/node": "^22.15.3",
@@ -72,6 +93,12 @@
     "vitest": "^3.2.4",
     "zod": "^4.3.5"
   },
+  "wiring": {
+    "db": {
+      "partial": "prisma/mcp.prisma",
+      "migrations": "prisma/migrations"
+    }
+  },
   "engines": {
     "node": ">=22.0.0"
   },
@@ -102,13 +129,5 @@
     "!**/*.stories.*",
     "!**/*.test-story.*",
     "!**/test-helpers.*"
-  ],
-  "peerDependenciesMeta": {
-    "hono": {
-      "optional": true
-    },
-    "zod": {
-      "optional": true
-    }
-  }
+  ]
 }

package/src/index.ts

@@ -29,7 +29,16 @@ export { inlineSchemaRefs, UnsupportedSchemaError } from "./openapi/refs";
 // here so that packages which own a domain can ship that domain's endpoints and
 // a host can concatenate them — which requires all of them to mean the same
 // thing by "an endpoint". See `openapi/endpoint.ts`.
-export type { McpEndpoint, HttpMethod } from "./openapi/endpoint";
+export type { McpEndpoint, HttpMethod, McpAnnotationDefaults } from "./openapi/endpoint";
+/**
+ * Composing a tool's classification from a package's declared defaults and the
+ * host's own table — the host still wins every field it states, and a field
+ * neither side supplies is a refusal. See `./openapi/annotations`.
+ */
+export {
+  resolveToolAnnotations,
+  type ToolAnnotationOverrides,
+} from "./openapi/annotations";
 export type {
   OpenApiDocument,
   OpenApiOperation,

package/src/manifest/index.ts

@@ -0,0 +1,89 @@
+/**
+ * `@12-apps/mcp/manifest` — the SHARED wiring manifest.
+ *
+ * Identity, the Prisma contribution (the three tables behind the
+ * authorization server) and the runtime inventory: `http` on the server.
+ *
+ * ON THE `db` DECLARATION — the reason this manifest exists at all.
+ *
+ * This package ships `prisma/mcp.prisma` and a migration beside it, and until
+ * now nothing said so in a form a host assembler could read. The origin
+ * host's assembler discovers partials in two steps: a package that carries
+ * `"wiring": { "db": ... }` in its package.json is taken at its word, and a
+ * package that carries nothing falls back to a STRUCTURAL scan — every
+ * `prisma/*.prisma` under the package root is treated as a partial. So three
+ * tables reach somebody's database because a `readdir` found them, not
+ * because this package said they should. `@12-apps/notifications`' manifest
+ * closed exactly this gap for its four models and the anti-pattern audit
+ * names it directly; declaring changes no assembler behaviour (the
+ * declaration is read where the scan used to run) and closes the one case
+ * where composition was happening by accident.
+ *
+ * The mirror is what makes the declaration reachable: host assemblers are
+ * plain Node reading `node_modules` and cannot execute this TypeScript, so
+ * the contribution is repeated under `package.json` `"wiring": { "db": … }`
+ * and `assertDbMirror` pins the two together in this package's own test run.
+ *
+ * `composed`, not `isolated`, and the choice is forced. An isolated stack
+ * needs models carrying no relation into host tables — true of the three
+ * here as SHIPPED (`user_id` and `user_email` are deliberately by-value
+ * scalars, see the partial's header) — but the host is invited to add the FK
+ * in its own migration, and the origin host's is `ON DELETE CASCADE`. A
+ * package cannot declare isolation for models whose adopters relate them
+ * into their own account tables.
+ *
+ * ## THE NARROWINGS, each deliberate
+ *
+ * - **No `mcp` capability.** This package IS the MCP runtime — the
+ *   OpenAPI→tools generator, the registry, the JSON-RPC transport, the
+ *   coverage gate. It advertises no tools of its own, and a manifest that
+ *   declared any would be the runtime describing itself to itself.
+ * - **No `permissions`.** Authorization here is the OAuth scope set
+ *   (`MCP_SUPPORTED_SCOPES`) plus whatever the host's own RBAC says about
+ *   the proxied endpoint — the point of bearer passthrough is that an agent
+ *   inherits the caller's permissions rather than holding its own. There is
+ *   no id for this package to contribute.
+ * - **No `web` inventory**, though `./react` ships the whole AI-connect
+ *   onboarding flow. A `surface` contribution is a `createWeb*` FACTORY —
+ *   one config object in, an object of component types out, memoised once by
+ *   the binder. `./react` has no such factory: it exports components a host
+ *   mounts with its own props (`AiIntegrationOnboarding` takes the store,
+ *   the endpoint URL and the live connection at the call site). Inventing a
+ *   factory here to have something to declare would freeze a props table
+ *   three hosts pass differently, which is the opposite of what a surface
+ *   contribution is for. When the flow grows a real bound surface, the
+ *   inventory grows with it.
+ * - **No `env`.** The signing-key variables (`DEFAULT_SIGNING_KEY_ENV`,
+ *   `DEFAULT_SIGNING_KEY_ID_ENV`) and `trustedOriginsFromEnv` are NAMES this
+ *   package exports for a host to read `process.env` with; the package reads
+ *   nothing itself, and the names are overridable per call. Declaring them
+ *   would oblige a host to answer for variables it may legitimately have
+ *   spelled differently.
+ * - **No `e2e`.** This package packages no journeys.
+ * - **No `jobs`.** Nothing here sweeps: authorization codes are stateless
+ *   signed blobs (the partial's header says so — there is no `oauth_codes`
+ *   table and nothing to expire), and refresh-token revocation happens on
+ *   the rotation path rather than on a clock.
+ *
+ * `@12-apps/wiring` is a TYPE-ONLY devDependency (the report-builder move):
+ * the manifest is a plain `satisfies`-checked value, and the producer
+ * factories' runtime assertions run in this package's own test suite.
+ */
+
+import type { PackageManifest } from "@12-apps/wiring";
+
+export const mcpManifest = {
+  name: "@12-apps/mcp",
+  contract: 1,
+  db: { partial: "prisma/mcp.prisma", migrations: "prisma/migrations" },
+  /**
+   * A refused token grant, an unresolvable signing key or a rejected
+   * redirect URI files under `mcp` rather than under whichever host mounted
+   * the authorization server. Mandatory for runtime manifests since wiring
+   * 1.3.0, and this is the surface that most needs it: every failure here is
+   * a caller who cannot connect, reported to them as an opaque OAuth error
+   * code by specification.
+   */
+  observability: { namespace: "mcp" },
+  server: ["http"],
+} as const satisfies PackageManifest;

package/src/manifest/server.ts

@@ -0,0 +1,94 @@
+/**
+ * `@12-apps/mcp/manifest/server` — the server capabilities.
+ *
+ * `http.create` wraps `createApiMcpOauth` in a WIRE VIEW, and the reason is
+ * the shape of an OAuth answer. `McpOauthRoute.handle` takes a Fetch
+ * `Request` and returns a Fetch `Response` — not a `{ status, body }` pair —
+ * because every endpoint here answers something the JSON pair cannot say: a
+ * 302 whose `Location` IS the payload, a form-encoded exchange answering
+ * RFC 6749 §5.1/§5.2 with its own cache headers, a JWKS with a
+ * `public, max-age=300`, an RFC 8414/9728 document. `create-api-mcp-oauth`'s
+ * own docstring says a wrapper would only break those. So the view answers
+ * the contract's RAW half (`{ response }`, wiring 1.9.0), which exists for
+ * exactly this, and the descriptors stay untouched.
+ *
+ * ## THE RAW REQUEST IS REQUIRED, and the view says so out loud
+ *
+ * The contract obliges an adapter to fill `params`/`query`/`body` and lets it
+ * fill `request`. Every handler here needs the whole request — the exact URL
+ * (redirect_uri echo, PKCE parameters, the `Host` an issuer is derived
+ * from), the form body byte-for-byte, the cookie header the session is read
+ * off. So a missing `request` is refused loudly at the first call rather
+ * than silently producing an authorization server that mints codes for the
+ * wrong origin. `@12-apps/storage`'s view takes the same posture for the
+ * same reason.
+ *
+ * ## THE MOUNT IS THE ORIGIN ROOT
+ *
+ * `McpOauthRoute.path` is absolute from the origin root — `.well-known/*`
+ * cannot live under a prefix (RFC 8615), and a connector reads those
+ * documents before it has ever spoken to us. The consumer joins
+ * `mountPath + path`, so the ONLY correct binding is `mountPath: "/"`; the
+ * paths themselves stay configurable per host through `config.paths`, which
+ * is where a host that serves `authorize` somewhere else says so. Binding
+ * this surface under a prefix would move the discovery documents off the
+ * two URLs the specification reserves, and the symptom is a connector that
+ * cannot find the authorization server at all.
+ *
+ * ## EVERY ROUTE IS `public`, and that is a decision
+ *
+ * Not "unguarded": these six ARE the authentication, so a host RBAC gate in
+ * front of them would demand a token from the endpoint that issues tokens.
+ * `authorize` reads the host's cookie session itself (`config.resolveSession`)
+ * and sends an anonymous caller through the host's sign-in flow; `token` and
+ * `register` authenticate the CLIENT per RFC; the three documents are public
+ * by specification. `public` is also the contract's only kind that forbids a
+ * `permission` while allowing the routes to be reached anonymously — which
+ * is precisely the property that has to hold here.
+ *
+ * `@12-apps/wiring` is a TYPE-ONLY devDependency — see `./index`.
+ */
+
+import type { AnyServerManifest, WireRequest, WireRouteAnswer } from "@12-apps/wiring";
+
+import {
+  createApiMcpOauth,
+  type ApiMcpOauth,
+  type McpOauthConfig,
+  type McpOauthRoute,
+} from "../oauth";
+
+/** One `McpOauthRoute` as the wiring contract reads it. */
+function asWireRoute(route: McpOauthRoute): {
+  method: McpOauthRoute["method"];
+  path: string;
+  kind: "public";
+  handle(request: WireRequest): Promise<WireRouteAnswer>;
+} {
+  return {
+    method: route.method,
+    path: route.path,
+    kind: "public",
+    handle: async (request) => {
+      if (!request.request) {
+        throw new Error(
+          "@12-apps/mcp/oauth needs the raw request — bind an adapter that forwards it.",
+        );
+      }
+      return { response: await route.handle(request.request) };
+    },
+  };
+}
+
+/** `createApiMcpOauth`, its routes re-shaped for the aggregate. */
+export function createWireApiMcpOauth(
+  config: McpOauthConfig,
+): Omit<ApiMcpOauth, "routes"> & { routes: ReturnType<typeof asWireRoute>[] } {
+  const api = createApiMcpOauth(config);
+  return { ...api, routes: api.routes.map(asWireRoute) };
+}
+
+export const mcpServerManifest = {
+  name: "@12-apps/mcp",
+  http: { create: createWireApiMcpOauth },
+} as const satisfies AnyServerManifest;

package/src/openapi/annotations.ts

@@ -0,0 +1,106 @@
+/**
+ * Composing a tool's behavior classification out of two sources.
+ *
+ * The rule the host's gate enforces is unchanged: every served tool ends with
+ * a COMPLETE `ToolAnnotations` — a title and all three hints — and a tool that
+ * ends unclassified fails `mcp:lint`. ChatGPT App review treats a missing hint
+ * as a blocker, and the Anthropic connector directory derives auto-permissions
+ * from `readOnlyHint`/`destructiveHint`, so there is no defensible default for
+ * "we did not say".
+ *
+ * What this adds is where the answer may COME FROM. A package that declares
+ * `getSupplierVersions` knows it reads and does not destroy; the host cannot
+ * know that without reading the package's source, so it restated the
+ * classification by hand — one line per tool, per collection, wrong the moment
+ * the package changed a verb. Now the package can assert what it knows and the
+ * host's table becomes what it should always have been: OVERRIDES, plus the
+ * tools the host itself owns.
+ *
+ * ## Precedence, and why it runs this way
+ *
+ * The HOST wins every field it states. A package's claim is a default, not a
+ * fact about the host's deployment: the same endpoint can be read-only in one
+ * app and reach an external service in another (a host that proxies its
+ * catalog reads through a vendor), and the host is the only party that knows.
+ * Inverting this would make a package version bump silently re-classify a tool
+ * an operator had already audited — the exact thing an audited classification
+ * exists to prevent.
+ *
+ * ## What it refuses
+ *
+ * A field neither side supplies. `resolveToolAnnotations` throws naming the
+ * tool and the missing fields, which keeps the completeness property a
+ * REFUSAL rather than a lint pass over a table that quietly grew a gap. The
+ * host's own gate can keep its message; this one fires first and says the same
+ * thing in the same terms.
+ */
+
+import type { ToolAnnotations } from "../types";
+import type { McpAnnotationDefaults } from "./endpoint";
+
+/** The host's half — whatever it chose to state, per tool. */
+export type ToolAnnotationOverrides = Partial<ToolAnnotations>;
+
+/**
+ * Merge a package's declared defaults under a host's overrides.
+ *
+ * @param name the tool id, for the refusal message
+ * @param defaults what the package asserted (`McpEndpoint.annotations`)
+ * @param overrides what the host's own table says; wins every field it states
+ */
+/** A title only counts when it has something in it. */
+function titleOf(candidate: string | undefined): string | undefined {
+  return typeof candidate === "string" && candidate.trim() !== "" ? candidate : undefined;
+}
+
+/**
+ * Merge a package's declared defaults under a host's overrides.
+ *
+ * The four fields are resolved into one record and checked generically rather
+ * than branch by branch — which keeps the "host wins, and `false` is an
+ * answer" rule stated exactly once per field instead of once per field per
+ * check.
+ *
+ * `??` and not `||` throughout, and that is the trap the whole merge turns on:
+ * `false` is a real classification — "this tool does not destroy" — and must
+ * not fall through to the package's answer.
+ *
+ * @param name the tool id, for the refusal message
+ * @param defaults what the package asserted (`McpEndpoint.annotations`)
+ * @param overrides what the host's own table says; wins every field it states
+ */
+export function resolveToolAnnotations(
+  name: string,
+  defaults: McpAnnotationDefaults | undefined,
+  overrides: ToolAnnotationOverrides | undefined,
+): ToolAnnotations {
+  const host = overrides ?? {};
+  const declared = defaults ?? {};
+  const resolved: Partial<ToolAnnotations> = {
+    title: titleOf(host.title ?? declared.title),
+    readOnlyHint: host.readOnlyHint ?? declared.readOnly,
+    openWorldHint: host.openWorldHint ?? declared.openWorld,
+    destructiveHint: host.destructiveHint ?? declared.destructive,
+  };
+
+  const missing = REQUIRED_FIELDS.filter((field) => resolved[field] === undefined);
+  if (missing.length > 0) refuse(name, missing);
+  return resolved as ToolAnnotations;
+}
+
+/** Every field a served tool must end with — the completeness property itself. */
+const REQUIRED_FIELDS = [
+  "title",
+  "readOnlyHint",
+  "openWorldHint",
+  "destructiveHint",
+] as const satisfies readonly (keyof ToolAnnotations)[];
+
+function refuse(name: string, missing: readonly string[]): never {
+  throw new Error(
+    `MCP tool "${name}" ends unclassified: neither the package nor the host supplied ` +
+      `${missing.join(", ")}. Every served tool needs a complete classification — a missing ` +
+      `hint blocks ChatGPT App review, and the connector directory derives auto-permissions ` +
+      `from readOnlyHint/destructiveHint.`,
+  );
+}