@12-apps/mcp 3.2.0 → 3.3.0

package/dist/oauth/index.js

@@ -0,0 +1,279 @@
+import {
+  providerForHostId
+} from "../chunk-FYEVBTDU.js";
+import {
+  ACCESS_TOKEN_TTL_SECONDS,
+  AUTHORIZATION_CODE_AUDIENCE,
+  AUTHORIZATION_CODE_TTL_SECONDS,
+  AccessTokenError,
+  AuthorizationCodeError,
+  DEFAULT_MCP_RESOURCE_PATH,
+  DEFAULT_OAUTH_PATHS,
+  DEFAULT_PROVIDER_ROOTS,
+  DEFAULT_SIGNING_KEY_ENV,
+  DEFAULT_SIGNING_KEY_ID_ENV,
+  MCP_SUPPORTED_SCOPES,
+  REFRESH_TOKEN_TTL_MS,
+  RefreshTokenError,
+  SIGNING_ALG,
+  SUPPORTED_CHALLENGE_METHOD,
+  UnsupportedChallengeMethodError,
+  computeChallenge,
+  createApiMcpOauth,
+  getRefreshTokenIdentity,
+  hashSecret,
+  hashToken,
+  inProcessCodeReplayStore,
+  issueRefreshToken,
+  issuer,
+  loadSigningKeyFromEnv,
+  matchesRedirectUri,
+  mintCode,
+  originFromRequest,
+  providerFromRedirectUris,
+  registerClient,
+  resolveMcpOauthConfig,
+  resolveTrustedOrigin,
+  resourceAudience,
+  rotateRefreshToken,
+  signAccessToken,
+  signingKeyProvider,
+  trustedOriginsFromEnv,
+  verifyAccessToken,
+  verifyChallenge,
+  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");
+export {
+  ACCESS_TOKEN_TTL_SECONDS,
+  AUTHORIZATION_CODE_AUDIENCE,
+  AUTHORIZATION_CODE_TTL_SECONDS,
+  AccessTokenError,
+  AuthorizationCodeError,
+  DEFAULT_MCP_RESOURCE_PATH,
+  DEFAULT_OAUTH_PATHS,
+  DEFAULT_PROVIDER_ROOTS,
+  DEFAULT_SIGNING_KEY_ENV,
+  DEFAULT_SIGNING_KEY_ID_ENV,
+  MCP_SUPPORTED_SCOPES,
+  REFRESH_TOKEN_TTL_MS,
+  RefreshTokenError,
+  SIGNING_ALG,
+  SUPPORTED_CHALLENGE_METHOD,
+  UnsupportedChallengeMethodError,
+  computeChallenge,
+  createApiMcpOauth,
+  createPrismaMcpStores,
+  disconnectAiHost,
+  getRefreshTokenIdentity,
+  hashSecret,
+  hashToken,
+  inProcessCodeReplayStore,
+  issueRefreshToken,
+  issuer,
+  listAiConnections,
+  loadSigningKeyFromEnv,
+  matchesRedirectUri,
+  mintCode,
+  originFromRequest,
+  providerFromRedirectUris,
+  registerClient,
+  resolveMcpOauthConfig,
+  resolveTrustedOrigin,
+  resourceAudience,
+  rotateRefreshToken,
+  signAccessToken,
+  signingKeyProvider,
+  trustedOriginsFromEnv,
+  verifyAccessToken,
+  verifyChallenge,
+  verifyCode
+};
+//# sourceMappingURL=index.js.map

package/dist/oauth/index.js.map

@@ -0,0 +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":[]}

package/dist/react/index.d.ts

@@ -0,0 +1,239 @@
+import { OnboardingStore, OnboardingStateSnapshot } from '@12-apps/onboarding';
+import { f as AiHostGuide, h as AiProvider, b as AiCapability, d as AiHostBrand } from '../guide-DV5MQbCg.js';
+export { A as AI_CAPABILITIES, a as AI_PERMISSION_MODEL, c as AiConnectPromptSpec, e as AiHostConfigureStage, g as AiHostLink, i as aiConnectPrompt, j as aiHostGuides, p as providerForHostId } from '../guide-DV5MQbCg.js';
+
+/**
+ * Revoke a host's access. Returning a promise holds the confirmation popup in
+ * its pending state until the write settles, and a rejection keeps it open
+ * carrying the reason — so the owner sees the disconnect finish or fail.
+ */
+type DisconnectHandler = (hostId: string) => void | Promise<unknown>;
+/** One assistant's connection state. */
+interface HostStatus {
+    host: AiHostGuide;
+    connected: boolean;
+    /** Freeform activity line for a connected host (e.g. "ativo há 3 min"). */
+    detail?: string;
+}
+/**
+ * The completed-state status board for the AI integration: every assistant as a
+ * box — green when connected, red when still to connect (with a "Conectar"
+ * button that re-enters the guided flow for that host). Each connection is
+ * attributed to its provider (derived from the OAuth client + confirmed by
+ * `announceAiConnection`), so several assistants can show connected at once.
+ *
+ * A connected box carries two more controls, because the pill it used to show
+ * alone was a dead end in both directions: "Instruções" re-enters the host's
+ * setup steps (previously reachable only from a RED card, so an all-green board
+ * hid them entirely), and "Desconectar" — when the app passes `onDisconnect` —
+ * revokes access, which nothing in the UI could do at all.
+ */
+declare function AiStatusBoard({ statuses, onConnect, onDisconnect, }: {
+    statuses: readonly HostStatus[];
+    onConnect: (hostId: string) => void;
+    /** Revoke this host's access. Omit to render a read-only board. */
+    onDisconnect?: DisconnectHandler;
+}): React.JSX.Element;
+
+/**
+ * Pure helpers + the connection type shared by the AI-onboarding flow steps
+ * (`ai-flow-steps.tsx`) and the orchestration/status board (`ai-steps.tsx`),
+ * kept here so neither JSX module has to import the other (no import cycle).
+ */
+/** The live connection surfaced from the server (empty list when none). */
+interface AiConnection {
+    clientName: string | null;
+    /**
+     * The provider this connection is attributed to (derived server-side from the
+     * OAuth client's redirect URIs / confirmed by `announceAiConnection`). `null`
+     * for a legacy connection recorded before attribution existed — matched
+     * best-effort to whichever host the owner is connecting.
+     */
+    host: AiProvider | null;
+    lastActiveAt: Date;
+}
+
+/** Props for the reusable AI-connect onboarding flow. */
+interface AiIntegrationOnboardingProps {
+    /** Persistence seam — the app wires this to its own backend (server actions). */
+    store: OnboardingStore;
+    /** The MCP endpoint URL to paste (derived by the app from its public origin). */
+    endpointUrl: string;
+    /** The owner's saved progress (null → first run / landing). */
+    initialState: OnboardingStateSnapshot | null;
+    /** The live MCP connections (one per connected assistant; empty when none). */
+    connections: readonly AiConnection[];
+    /** Onboarding feature key (persistence namespace). @default "ai_integration" */
+    featureKey?: string;
+    /** Show the dev-only "reset onboarding" button. @default false */
+    devReset?: boolean;
+    /**
+     * The platform operating this MCP server, as its OAuth consent button names
+     * it. REQUIRED, and it is the reason `hosts` can have a default at all: one
+     * ChatGPT step tells the owner which "Sign in with …" button to click, and
+     * that button carries whoever runs the server. It used to be a hard-coded
+     * name — of a single STORE on one deployment, not even the product — so every
+     * other adopter pointed its owners at a button that does not exist.
+     */
+    platformName: string;
+    /** Assistants offered in the flow. @default aiHostGuides(platformName) */
+    hosts?: readonly AiHostGuide[];
+    /** Capability cards on the landing. @default the shared AI_CAPABILITIES */
+    capabilities?: readonly AiCapability[];
+    /** Permission reassurance copy on the landing. @default AI_PERMISSION_MODEL */
+    permissionModel?: string;
+    /**
+     * Message the owner pastes into the assistant on the Conectar step.
+     *
+     * REQUIRED, with no default, because the useful version of it names TOOLS —
+     * one to register the connection, one to read something real — and this
+     * package neither defines nor serves any. It shipped a constant naming two
+     * tools from one adopter's surface, so another host handed its owner a prompt
+     * that called two things that did not exist, and the confirm step then waited
+     * forever for a registration that could never happen. Build it with
+     * `aiConnectPrompt({ … })`.
+     */
+    connectPrompt: string;
+    /**
+     * Re-check the live connection on the verify step's "Testar conexão" button —
+     * apps pass a router refresh (e.g. Next's `router.refresh`). @default a full
+     * `window.location.reload()`.
+     */
+    onRetest?: () => void;
+    /**
+     * Revoke a connected assistant's access, from the completed status board. The
+     * host ID is the board's card, NOT the connection — `claude` and
+     * `claude-desktop` share one provider, so the app resolves which stored
+     * connection it owns (`providerForHostId`) and revokes that. Omitted → the
+     * board stays read-only, which is the pre-existing behavior.
+     */
+    onDisconnect?: DisconnectHandler;
+}
+/**
+ * URL-free, persisted onboarding for the AI/MCP integration — a five-step wizard
+ * (pick an assistant, copy the store URL, configure the connector, connect, then
+ * verify) whose position + chosen assistant are saved via `@12-apps/onboarding`, so
+ * a refresh resumes exactly where the owner left off. The live MCP connection
+ * signal drives the verify step and the completed status board.
+ *
+ * App-agnostic: the app supplies the persistence `store`, the `endpointUrl`, and
+ * the live `connections` (one per connected assistant); content (hosts,
+ * capabilities, copy) defaults to the shared guide but can be overridden per app.
+ */
+declare function AiIntegrationOnboarding({ store, endpointUrl, initialState, connections, featureKey, devReset, platformName, hosts, capabilities, permissionModel, connectPrompt, onRetest, onDisconnect, }: AiIntegrationOnboardingProps): React.JSX.Element;
+
+/**
+ * Homepage-style marketing landing for the AI integration (shown before the
+ * owner starts): a hero, the permission reassurance, a trust/feature strip, and
+ * the capability highlights. `onStart` begins the guided flow. `permissionModel`
+ * and `capabilities` default to the shared copy; apps can override.
+ */
+declare function AiLanding({ onStart, permissionModel, capabilities, }: {
+    onStart: () => void;
+    permissionModel?: string;
+    capabilities?: readonly AiCapability[];
+}): React.JSX.Element;
+
+/**
+ * Marketing block for the AI integration: a headline + a responsive grid of
+ * capability cards. Shown on the onboarding landing (before the owner starts) to
+ * sell the feature — "here's what the assistant does for you". `capabilities`
+ * defaults to the shared set; apps can pass their own.
+ */
+declare function AiCapabilities({ capabilities, }: {
+    capabilities?: readonly AiCapability[];
+}): React.JSX.Element;
+
+/**
+ * Step 1 of the guided AI connect flow: the owner picks a single assistant
+ * (Claude.ai, Claude Desktop, ChatGPT, Codex) from a card grid. Picking a card
+ * advances straight to the next step — no separate "Próximo" button. Selection
+ * is controlled (persisted by the onboarding flow) so a refresh resumes with the
+ * same assistant highlighted.
+ */
+declare function HostSelectStep({ hosts, selectedId, onSelect, }: {
+    hosts: readonly AiHostGuide[];
+    selectedId: string | null;
+    onSelect: (hostId: string) => void;
+}): React.JSX.Element;
+
+/**
+ * The store's MCP endpoint URL with a blue "Copiar" button (the display-only
+ * field defers the copy to this button). Controlled: `copied` flips the label to
+ * "Copiado" and `onCopy` fires after the clipboard write — the wizard uses it to
+ * unlock the "Próximo" button on the Copiar-URL step.
+ */
+declare function EndpointCopyBlock({ endpointUrl, copied, onCopy, }: {
+    endpointUrl: string;
+    copied: boolean;
+    onCopy: () => void;
+}): React.JSX.Element;
+/**
+ * A copyable multi-line message block (preserves line breaks). Used on the
+ * Conectar step for the prompt the owner pastes into the assistant so it
+ * identifies itself and calls a tool (which registers the connection).
+ */
+declare function PromptCopyBlock({ title, caption, message, }: {
+    title: string;
+    caption: string;
+    message: string;
+}): React.JSX.Element;
+/** The brand mark + "Conectar no <host>" header shared by the connect sub-steps. */
+declare function HostConnectHeader({ host }: {
+    host: AiHostGuide;
+}): React.JSX.Element;
+/**
+ * The primary direct-link button to a host's connector settings (nothing when it
+ * has none). `onOpen` fires after the link opens so the Configurar step can
+ * unlock its "Próximo" only once the owner has actually gone to the connectors.
+ */
+declare function HostOpenButton({ host, onOpen, }: {
+    host: AiHostGuide;
+    onOpen?: () => void;
+}): React.JSX.Element | null;
+/**
+ * A numbered slice of a host's connect steps. `start` keeps the numbering
+ * continuous when the steps are split across wizard stages (e.g. the Conectar
+ * stage continues at 4 after Configurar showed 1–3).
+ */
+declare function HostStepList({ steps, start, }: {
+    steps: readonly string[];
+    start?: number;
+}): React.JSX.Element;
+
+/**
+ * The store's MCP endpoint URL. Client component because the copy interaction
+ * needs the browser clipboard — the `@12-apps/ui` Code component provides the copy
+ * affordance (`copyable`). Pass `copyable={false}` for a display-only field when
+ * an external control owns the copy action (e.g. the connect flow's blue Copiar
+ * button, which also gates the following steps on the copy).
+ */
+declare function McpEndpointUrl({ url, copyable, }: {
+    url: string;
+    copyable?: boolean;
+}): React.JSX.Element;
+
+/** A round brand chip: the vendor accent + a simple glyph. */
+declare function HostBrandAvatar({ brand, size, }: {
+    brand: AiHostBrand;
+    size?: number;
+}): React.JSX.Element;
+/** The icon for a capability card, by capability id (falls back to a sparkle). */
+declare function CapabilityIcon({ id, fontSize, }: {
+    id: string;
+    fontSize?: number;
+}): React.JSX.Element;
+
+/** One entry of a landing's trust/feature strip. */
+interface FeatureBadgeItem {
+    icon: React.ReactNode;
+    label: string;
+    caption: string;
+}
+/**
+ * One item of an onboarding landing's trust/feature strip: a paper icon tile
+ * (primary-coloured glyph) with a two-line label + caption.
+ */
+declare function FeatureBadge({ icon, label, caption }: FeatureBadgeItem): React.JSX.Element;
+
+export { AiCapabilities, AiCapability, type AiConnection, AiHostBrand, AiHostGuide, AiIntegrationOnboarding, type AiIntegrationOnboardingProps, AiLanding, AiProvider, AiStatusBoard, CapabilityIcon, type DisconnectHandler, EndpointCopyBlock, FeatureBadge, type FeatureBadgeItem, HostBrandAvatar, HostConnectHeader, HostOpenButton, HostSelectStep, type HostStatus, HostStepList, McpEndpointUrl, PromptCopyBlock };