@12-apps/mcp 3.0.0 → 3.1.0

package/ADOPTING.md

@@ -109,11 +109,14 @@ library updates, every host updates with **no app changes**. Same contract
     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
+11. **Disconnecting means BOTH halves — call `disconnectAiHost`, not the stores.**
+    `connections.revokeByHost(...)` ends the rows and returns the OAuth client ids
+    behind them, and every live refresh token of those clients must be ended in the
+    same act — a host holding a live refresh token simply rotates its way back in
+    and the card lights green on the next grant. Since 12-48 the rule IS a
+    function: `disconnectAiHost(stores, { userId, email }, host)` does both and
+    reports what it ended, so a host cannot import one half without the other.
+    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
@@ -234,10 +237,18 @@ Deliberate deltas to reconcile:
 
 ## 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 account/connection SCREENS' route files** (`GET/DELETE
+  /api/account/mcp-connections`) — they answer in the HOST's app-wide response
+  envelope and mix its session resolution, published plugin URLs and logger, so
+  the handler stays host code (unlike the OAuth endpoints, whose shapes are
+  fixed by RFC — rule 12 — these are ordinary host API routes). What DID move
+  (12-48) is the operations under them: `listAiConnections` (the stored open
+  `host` string narrowed to the package's own `AiProvider` union) and
+  `disconnectAiHost`, which owns the disconnect's both-halves rule — revoke the
+  connection rows AND end every live refresh token of each returned client id in
+  one call. A host that imports the disconnect cannot get only half of it; half
+  is the failure mode where the assistant rotates its live token and the card
+  the user just disconnected lights green again on the next grant (rule 11).
 - **The MCP registry itself** — which endpoints become tools, their annotations
   and redactions, is the host's catalogue. The package generates, dispatches and
   gates it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/mcp",
-  "version": "3.0.0",
+  "version": "3.1.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": {
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@12-apps/onboarding": "^2.0.0",
-    "@12-apps/rbac": "^4.0.0",
+    "@12-apps/rbac": "^4.0.1",
     "@12-apps/ui": "^5.0.0",
     "@mui/icons-material": "^6.5.0",
     "jose": "^6.1.3",

package/src/oauth/connections.ts

@@ -0,0 +1,104 @@
+import { providerForHostId, type AiProvider } from "../guide";
+import type {
+  McpConnectionStore,
+  RefreshTokenStore,
+  StoredMcpConnection,
+} from "./stores";
+
+/**
+ * The account surface's connection OPERATIONS (12-48) — the half of the
+ * `GET/DELETE /api/account/mcp-connections` endpoints that is contract rather
+ * than host vocabulary.
+ *
+ * The ROUTE stays in the host on purpose: it mixes the host's session
+ * resolution, its response envelope, its published plugin URLs and its logger,
+ * and injecting all four here would make the config surface bigger than the
+ * handler it replaces. What must NOT stay in each host is the disconnect's
+ * both-halves rule, because getting it half right LOOKS right:
+ *
+ * `connections.revokeByHost` ends the connection rows and returns the OAuth
+ * client ids behind them — and a host that stops there has revoked nothing that
+ * matters. The assistant still holds a live refresh token for each of those
+ * clients, rotates it on schedule, and the very next grant records fresh
+ * activity: the card the user just disconnected lights green again on its own.
+ * So the rule is one function: revoke the rows AND end every live refresh token
+ * of each returned client, in the same call, with no way to import one half
+ * without the other.
+ *
+ * Deliberately NOT invalidated here: the assistant's current ACCESS token.
+ * Those are self-contained JWTs the server does not track; a just-disconnected
+ * host keeps working for at most their TTL (15 minutes by default) and can then
+ * obtain nothing further.
+ */
+
+/** An active AI connection, narrowed for display. */
+export interface AiConnectionSnapshot {
+  oauthClientId: string;
+  clientName: string | null;
+  /** The provider this connection is attributed to (`null` = pre-attribution). */
+  host: AiProvider | null;
+  connectedAt: Date;
+  lastActiveAt: Date;
+}
+
+/** The caller the operations act for — always the session's own user. */
+export interface AiConnectionCaller {
+  /** The host's user id — what `mcp_connections` rows are keyed by. */
+  userId: string;
+  /** The identity refresh tokens are bound to (the AS binds by email). */
+  email: string;
+}
+
+/** What one disconnect actually ended, for the host's log and response. */
+export interface AiDisconnectResult {
+  /** OAuth client ids whose connection rows were revoked. */
+  disconnectedClientIds: string[];
+  /** Live refresh tokens ended across those clients — the half that cuts access. */
+  revokedRefreshTokens: number;
+}
+
+/** Narrow a stored `host` string to a known provider, or `null`. */
+function asProvider(host: string | null): AiProvider | null {
+  return host === null ? null : providerForHostId(host);
+}
+
+/**
+ * A user's active connections, most-recently-active first, with the stored open
+ * `host` string narrowed to the package's closed {@link AiProvider} union — the
+ * store cannot know which assistants have screens, but the union is this
+ * package's own vocabulary (`guide.ts`), so the narrowing lives beside it
+ * rather than being re-derived in every host.
+ */
+export async function listAiConnections(
+  connections: McpConnectionStore,
+  userId: string,
+): Promise<AiConnectionSnapshot[]> {
+  const rows: StoredMcpConnection[] = await connections.listActive(userId);
+  return rows.map((row) => ({ ...row, host: asProvider(row.host) }));
+}
+
+/**
+ * Disconnect one provider for this user — BOTH halves, atomically from the
+ * caller's point of view (see the module doc for why one half alone is a
+ * disconnect that undoes itself).
+ *
+ * Idempotent: disconnecting a provider that was never connected returns zero
+ * counts rather than failing, so a double-click is harmless. Repeat calls also
+ * report zero — `revokeLiveForClient` skips already-revoked tokens by contract.
+ */
+export async function disconnectAiHost(
+  stores: { connections: McpConnectionStore; refreshTokens: RefreshTokenStore },
+  caller: AiConnectionCaller,
+  host: AiProvider,
+): Promise<AiDisconnectResult> {
+  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),
+  };
+}

package/src/oauth/index.ts

@@ -115,3 +115,10 @@ export type {
   StoredRefreshToken,
   TokenEndpointAuthMethod,
 } from "./stores";
+export {
+  disconnectAiHost,
+  listAiConnections,
+  type AiConnectionCaller,
+  type AiConnectionSnapshot,
+  type AiDisconnectResult,
+} from "./connections";