@12-apps/mcp 1.18.0 → 1.20.0

package/src/oauth/prisma-stores.ts

@@ -0,0 +1,306 @@
+import type {
+  McpConnectionStore,
+  McpOauthStores,
+  NewOAuthClient,
+  NewRefreshToken,
+  OAuthClientStore,
+  RefreshTokenStore,
+  StoredMcpConnection,
+  StoredOAuthClient,
+  StoredRefreshToken,
+} from "./stores";
+
+/**
+ * The ports of `./stores.ts`, filled by Prisma (12-23).
+ *
+ * The package owns the three models (`prisma/mcp.prisma`), so their delegate
+ * shapes are known and this adapter can be exact. A host with Prisma therefore
+ * writes ONE line —
+ *
+ *   stores: createPrismaMcpStores(async () => getPrismaClient() as unknown as McpOauthPrisma)
+ *
+ * — and no host code at all beyond it. The client is duck-typed (only the
+ * delegates used, only the arguments used) so this file never imports a project's
+ * generated client, and a non-Prisma host fills the ports directly instead.
+ */
+
+/** A `where` on the composite unique of `mcp_connections`. */
+interface ConnectionKey {
+  userId_oauthClientId: { userId: string; oauthClientId: string };
+}
+
+/** The minimal Prisma surface the AS needs. Every field is one the surface writes. */
+export interface McpOauthPrisma {
+  oAuthClient: {
+    create(args: { data: NewOAuthClient }): Promise<StoredOAuthClient>;
+    findUnique(args: { where: { clientId: string } }): Promise<StoredOAuthClient | null>;
+  };
+  oAuthRefreshToken: {
+    create(args: { data: NewRefreshToken }): Promise<unknown>;
+    findUnique(args: { where: { tokenHash: string } }): Promise<StoredRefreshToken | null>;
+    findFirst(args: { where: { rotatedFrom: string } }): Promise<{ tokenHash: string } | null>;
+    findMany(args: {
+      where: { userEmail: string; clientId: string };
+    }): Promise<StoredRefreshToken[]>;
+    // No single-row `update`: the rotation used to revoke its parent with one and
+    // that was the bug (unconditional, so two concurrent rotations both won). Every
+    // revoke here is now an `updateMany` with a predicate that says WHICH rows may
+    // move, which is also why this delegate list stays honest about what is written.
+    updateMany(args: {
+      where:
+        | { tokenHash: { in: string[] } }
+        | { userEmail: string; clientId: string; revokedAt: null };
+      data: { revokedAt: Date };
+    }): Promise<{ count: number }>;
+  };
+  mcpConnection: {
+    findUnique(args: {
+      where: ConnectionKey;
+      select: { lastActiveAt: true };
+    }): Promise<{ lastActiveAt: Date } | null>;
+    findFirst(args: {
+      where: { userId: string; revokedAt: null; host: null };
+      orderBy: { lastActiveAt: "desc" };
+      select: { id: true };
+    }): Promise<{ id: string } | null>;
+    findMany(args: {
+      where: { userId: string; revokedAt: null; host?: string | null };
+      orderBy?: { lastActiveAt: "desc" };
+      select: Record<string, true>;
+    }): Promise<Record<string, unknown>[]>;
+    upsert(args: {
+      where: ConnectionKey;
+      create: Record<string, unknown>;
+      update: Record<string, unknown>;
+    }): Promise<unknown>;
+    update(args: { where: { id: string }; data: Record<string, unknown> }): Promise<unknown>;
+    updateMany(args: {
+      where: { id: { in: string[] } } | { userId: string; revokedAt: null; host: string };
+      data: Record<string, unknown>;
+    }): Promise<{ count: number }>;
+  };
+  /**
+   * Prisma's INTERACTIVE transaction, used for the rotation's claim + write. The
+   * callback form (not the array form) is required: the successor may only be
+   * created once the conditional revoke has reported that it, and not a concurrent
+   * sibling, claimed the parent — see `RefreshTokenStore.rotate`.
+   */
+  $transaction<T>(fn: (tx: McpOauthTx) => Promise<T>): Promise<T>;
+}
+
+/**
+ * The delegate subset used INSIDE the rotation transaction. Not exported: it is
+ * reachable structurally through `McpOauthPrisma.$transaction`, so no host ever
+ * needs to name it, and exporting a type nobody imports is what knip flags.
+ */
+interface McpOauthTx {
+  oAuthRefreshToken: {
+    create(args: { data: NewRefreshToken }): Promise<unknown>;
+    updateMany(args: {
+      where: { tokenHash: string; revokedAt: null };
+      data: { revokedAt: Date };
+    }): Promise<{ count: number }>;
+  };
+}
+
+/** A lazily-resolved client, so a host's singleton is awaited per call. */
+export type McpOauthPrismaProvider = () => Promise<McpOauthPrisma>;
+
+function clientStore(getPrisma: McpOauthPrismaProvider): OAuthClientStore {
+  return {
+    async create(client: NewOAuthClient) {
+      const prisma = await getPrisma();
+      return prisma.oAuthClient.create({ data: client });
+    },
+    async findByClientId(clientId: string) {
+      const prisma = await getPrisma();
+      return prisma.oAuthClient.findUnique({ where: { clientId } });
+    },
+  };
+}
+
+function refreshTokenStore(getPrisma: McpOauthPrismaProvider): RefreshTokenStore {
+  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) => {
+        // CLAIM-ONCE. The `revokedAt: null` predicate is what makes this safe under
+        // concurrency, and it is load-bearing rather than defensive: on Postgres's
+        // default READ COMMITTED, a second transaction's `updateMany` blocks on the
+        // row lock, then re-evaluates this WHERE against the COMMITTED row — which
+        // now has a `revokedAt` — and reports 0 rows. So exactly one caller can ever
+        // see count 1, and it is the only one that goes on to create a successor.
+        // An unconditional `update` would let both through: two live successors of
+        // one parent, and replay detection silently defeated (it waits for a third
+        // use of the parent that now never comes).
+        const { count } = await tx.oAuthRefreshToken.updateMany({
+          where: { tokenHash: parentHash, revokedAt: null },
+          data: { revokedAt: at },
+        });
+        // Lost the claim: write NOTHING. The zero-row update commits as the no-op
+        // it is, so there is nothing to roll back.
+        if (count !== 1) return false;
+        // Same transaction as the claim, so a crash cannot leave a live parent AND
+        // a live child either.
+        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: new Date() },
+      });
+      return count;
+    },
+  };
+}
+
+/** The connection columns the account surface reads. */
+const CONNECTION_SELECT = {
+  oauthClientId: true,
+  clientName: true,
+  host: true,
+  connectedAt: true,
+  lastActiveAt: true,
+} as const;
+
+function connectionStore(getPrisma: McpOauthPrismaProvider): McpConnectionStore {
+  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 as unknown as StoredMcpConnection[];
+    },
+    revokeByHost: (userId, host) => revokeByHost(getPrisma, userId, host),
+    announce: (userId, host) => announce(getPrisma, userId, host),
+  };
+}
+
+/**
+ * Disconnect one provider's connections — and ONLY that provider's.
+ *
+ * Every read and write is scoped by `userId`: a connection is per-user (an MCP
+ * bearer is not tenant-scoped), so the user id IS the isolation here, and the
+ * `id` list passed to the update comes from a query that already applied it.
+ */
+async function revokeByHost(
+  getPrisma: McpOauthPrismaProvider,
+  userId: string,
+  host: string,
+): Promise<string[]> {
+  const prisma = await getPrisma();
+  const attributed = await prisma.mcpConnection.findMany({
+    where: { userId, revokedAt: null, host },
+    select: { id: true, oauthClientId: true },
+  });
+  // A legacy `host = null` row is claimed only when the provider has no row of
+  // its own: pre-attribution connections must stay disconnectable, but a provider
+  // that DID attribute can never revoke another assistant's row.
+  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: new Date() },
+  });
+  return targets.map((row) => String(row.oauthClientId));
+}
+
+/** A provider's self-report: refresh its own row, or claim the unattributed one. */
+async function announce(
+  getPrisma: McpOauthPrismaProvider,
+  userId: string,
+  host: string,
+): Promise<number> {
+  const prisma = await getPrisma();
+  const now = 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;
+
+  // No row for this provider yet — attribute the just-connected one. Scoped by
+  // user, so a self-report can never reach another account's connection.
+  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;
+}
+
+/** Every port, over one lazily-resolved Prisma client. */
+export function createPrismaMcpStores(getPrisma: McpOauthPrismaProvider): McpOauthStores {
+  return {
+    clients: clientStore(getPrisma),
+    refreshTokens: refreshTokenStore(getPrisma),
+    connections: connectionStore(getPrisma),
+  };
+}

package/src/oauth/refresh.ts

@@ -0,0 +1,286 @@
+import { createHash, randomBytes } from "node:crypto";
+
+import type { NewRefreshToken, RefreshTokenStore, StoredRefreshToken } from "./stores";
+
+/**
+ * Refresh-token issue + rotation (12-23, ported from future-pay's
+ * `lib/mcp/oauth/refresh.ts` — behaviour unchanged; Prisma calls became the
+ * `RefreshTokenStore` port).
+ *
+ * Refresh tokens are opaque high-entropy strings; only their SHA-256 HASH is ever
+ * stored — the plaintext is returned once at issue/rotate time and never
+ * persisted, never logged.
+ *
+ * Rotation-on-use with replay protection:
+ *   - {@link issueRefreshToken} mints a root token bound to email + sub + client
+ *     + scopes;
+ *   - {@link rotateRefreshToken} consumes a token: it issues a NEW token chained
+ *     via `rotatedFrom` and revokes the parent, so a token is single-use;
+ *   - reuse of an already-rotated/revoked token is a REPLAY: rejected, AND the
+ *     whole lineage (every ancestor + descendant reachable through `rotatedFrom`)
+ *     is revoked — the OAuth 2.1 refresh-token replay rule;
+ *   - CONCURRENT reuse is the same event and gets the same answer. The store's
+ *     `rotate` is a claim-once write, so of two simultaneous rotations of one
+ *     parent exactly one is issued a successor and the other is treated as the
+ *     replay it is. Without that, replay protection would be bypassable by
+ *     WINNING a race instead of arriving second (see `RefreshTokenStore.rotate`);
+ *   - rotate may only NARROW scope (new ⊆ original); broadening is rejected and
+ *     nothing new is stored.
+ */
+
+/** Bytes of entropy per opaque refresh token (→ 64 hex chars). */
+const REFRESH_TOKEN_BYTES = 32;
+
+/** Refresh-token lifetime — long-lived relative to the 15-min access token. */
+export const REFRESH_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+/** The single failure discriminator surfaced to the token endpoint. */
+export type RefreshTokenErrorCode = "invalid_grant" | "invalid_scope";
+
+/**
+ * A typed refresh-token failure. Every rejection — unknown, expired, revoked,
+ * already-rotated (replay), wrong client, or a scope-broadening request —
+ * surfaces as a discriminated error the token endpoint maps to the RFC 6749
+ * error JSON.
+ */
+export class RefreshTokenError extends Error {
+  readonly code: RefreshTokenErrorCode;
+
+  constructor(code: RefreshTokenErrorCode, message?: string) {
+    super(message ?? code);
+    this.name = "RefreshTokenError";
+    this.code = code;
+  }
+}
+
+/** The result of issuing/rotating: the plaintext token (once) + bound scopes. */
+export interface IssuedRefreshToken {
+  /** The opaque plaintext refresh token — returned once, never persisted. */
+  refreshToken: string;
+  scopes: string[];
+}
+
+/** SHA-256 hex digest — the at-rest form of an opaque refresh token. */
+export function hashToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+/** Generate a fresh opaque refresh token (high-entropy hex). */
+function generateToken(): string {
+  return randomBytes(REFRESH_TOKEN_BYTES).toString("hex");
+}
+
+export interface RefreshTokenContext {
+  store: RefreshTokenStore;
+  /** Lifetime of a newly stored token. Default 30 days. */
+  ttlMs?: number;
+}
+
+function expiryOf(context: RefreshTokenContext): Date {
+  return new Date(Date.now() + (context.ttlMs ?? REFRESH_TOKEN_TTL_MS));
+}
+
+/**
+ * Issue a fresh (root) refresh token bound to a user (email + OAuth `sub`) +
+ * client + scopes. The plaintext is returned once; only its hash is stored.
+ */
+export async function issueRefreshToken(
+  context: RefreshTokenContext,
+  binding: { userEmail: string; userSub: string; clientId: string; scopes: string[] },
+): Promise<IssuedRefreshToken> {
+  const refreshToken = generateToken();
+  const row: NewRefreshToken = {
+    tokenHash: hashToken(refreshToken),
+    userEmail: binding.userEmail,
+    userSub: binding.userSub,
+    clientId: binding.clientId,
+    scopes: binding.scopes,
+    expiresAt: expiryOf(context),
+    rotatedFrom: null,
+  };
+  await context.store.create(row);
+  return { refreshToken, scopes: binding.scopes };
+}
+
+/**
+ * A pre-built O(1)-lookup index of one `(userEmail, clientId)` token family:
+ * `byHash` resolves a hash to its row (to walk ancestors via `rotatedFrom`), and
+ * `childrenOf` is the reverse index mapping a parent hash to its direct successor
+ * hashes (to walk descendants). Both are built in a single pass so the lineage
+ * traversal never re-scans the family (no O(n²) inner loop).
+ */
+interface LineageIndex {
+  byHash: Map<string, StoredRefreshToken>;
+  childrenOf: Map<string, string[]>;
+}
+
+function buildLineageIndex(family: StoredRefreshToken[]): LineageIndex {
+  const byHash = new Map<string, StoredRefreshToken>();
+  const childrenOf = new Map<string, string[]>();
+  for (const row of family) {
+    byHash.set(row.tokenHash, row);
+    if (!row.rotatedFrom) continue;
+    const siblings = childrenOf.get(row.rotatedFrom) ?? [];
+    siblings.push(row.tokenHash);
+    childrenOf.set(row.rotatedFrom, siblings);
+  }
+  return { byHash, childrenOf };
+}
+
+/**
+ * Collect every token hash reachable from `seedHash` — its ancestors (via
+ * `rotatedFrom`) and its descendants (via the reverse index) — by a BFS over the
+ * pre-built index. Each neighbour lookup is O(1), so the walk is linear in the
+ * family size.
+ */
+function collectLineage(index: LineageIndex, seedHash: string): Set<string> {
+  const lineage = new Set<string>();
+  const queue = [seedHash];
+  while (queue.length > 0) {
+    const hash = queue.shift();
+    if (!hash || lineage.has(hash)) continue;
+    lineage.add(hash);
+
+    const parent = index.byHash.get(hash)?.rotatedFrom ?? null;
+    if (parent && !lineage.has(parent)) queue.push(parent);
+
+    const children = (index.childrenOf.get(hash) ?? []).filter((child) => !lineage.has(child));
+    queue.push(...children);
+  }
+  return lineage;
+}
+
+/**
+ * Walk a token's rotation lineage (both directions) and revoke every token in it.
+ * Called on replay detection, so a leaked refresh token — once reused —
+ * invalidates the entire chain it belongs to.
+ */
+async function revokeLineage(
+  context: RefreshTokenContext,
+  scopedTo: Pick<StoredRefreshToken, "userEmail" | "clientId">,
+  seedHash: string,
+): Promise<void> {
+  // The lineage is confined to one (userEmail, clientId) pair, so load that set
+  // once and walk the `rotatedFrom` links in memory — a small, bounded chain.
+  const family = await context.store.listFamily(scopedTo.userEmail, scopedTo.clientId);
+  const lineage = collectLineage(buildLineageIndex(family), seedHash);
+  await context.store.revokeHashes([...lineage], new Date());
+}
+
+/** Reject any requested scope not already on the token (narrow-only). */
+function narrowedScopes(current: StoredRefreshToken, requested?: string[]): string[] {
+  const scopes = requested ?? current.scopes;
+  const original = new Set(current.scopes);
+  for (const scope of scopes) {
+    if (!original.has(scope)) {
+      throw new RefreshTokenError(
+        "invalid_scope",
+        `scope '${scope}' broadens the refresh token grant`,
+      );
+    }
+  }
+  return scopes;
+}
+
+/**
+ * Rotate a refresh token on use: validate it (must exist, be BOUND to the
+ * presenting client, be unexpired, unrevoked and un-rotated), then issue a NEW
+ * token chained via `rotatedFrom` and revoke the consumed one. Optionally NARROW
+ * scope; a broadening request is `invalid_scope`.
+ *
+ * Client binding (OAuth 2.1 §4.3 / RFC 6749 §10.4) is checked BEFORE any rotation
+ * or revocation, so client A can never redeem client B's refresh token — nor
+ * silently consume B's token by trying: the token stays live for its rightful
+ * owner.
+ */
+export async function rotateRefreshToken(
+  context: RefreshTokenContext,
+  plaintext: string,
+  expectedClientId: string,
+  newScopes?: string[],
+): Promise<IssuedRefreshToken> {
+  const tokenHash = hashToken(plaintext);
+  const current = await context.store.findByHash(tokenHash);
+
+  if (!current) {
+    throw new RefreshTokenError("invalid_grant", "unknown refresh token");
+  }
+  if (current.clientId !== expectedClientId) {
+    throw new RefreshTokenError(
+      "invalid_grant",
+      "refresh token was not issued to this client",
+    );
+  }
+  // Expired → reject (not a replay; no lineage revocation needed beyond the
+  // expiry itself).
+  if (current.expiresAt.getTime() <= Date.now()) {
+    throw new RefreshTokenError("invalid_grant", "refresh token expired");
+  }
+  // Already revoked OR already used as the parent of a rotation → REPLAY. Revoke
+  // the whole lineage and reject.
+  if (current.revokedAt || (await context.store.hasSuccessor(tokenHash))) {
+    await replay(context, current, tokenHash);
+  }
+
+  const scopes = narrowedScopes(current, newScopes);
+  const successorPlaintext = generateToken();
+  const claimed = await context.store.rotate(
+    {
+      tokenHash: hashToken(successorPlaintext),
+      userEmail: current.userEmail,
+      userSub: current.userSub,
+      clientId: current.clientId,
+      scopes,
+      expiresAt: expiryOf(context),
+      rotatedFrom: tokenHash,
+    },
+    tokenHash,
+    new Date(),
+  );
+  // The checks above are a READ, so a concurrent rotation of the same parent can
+  // pass them too; `rotate` is the serialization point and it hands the claim to
+  // exactly one caller. Losing it is the SAME event as the replay branch above —
+  // one token used twice — so it gets the same answer, deliberately: reject, and
+  // revoke the lineage including the winner's fresh successor. Rejecting without
+  // revoking would leave a race-winning attacker holding a live family, which is
+  // the whole attack; and a client that legitimately double-submits already loses
+  // its family in the sequential case, so this is consistent rather than harsher.
+  if (!claimed) await replay(context, current, tokenHash);
+
+  return { refreshToken: successorPlaintext, scopes };
+}
+
+/** Detected reuse: revoke the whole lineage and reject. Never returns. */
+async function replay(
+  context: RefreshTokenContext,
+  current: StoredRefreshToken,
+  tokenHash: string,
+): Promise<never> {
+  await revokeLineage(context, current, tokenHash);
+  throw new RefreshTokenError(
+    "invalid_grant",
+    "refresh token already used (replay) — lineage revoked",
+  );
+}
+
+/** The stable identity a refresh token is bound to. */
+export interface RefreshTokenIdentity {
+  /** The user's email — the identity the AS binds to and route guards resolve by. */
+  userEmail: string;
+  /** The original OAuth subject, kept stable across every rotation. */
+  userSub: string;
+}
+
+/**
+ * Resolve the identity (`email` + original OAuth `sub`) a refresh token is bound
+ * to. The token endpoint uses this after rotation to mint the successor access
+ * token with the correct email AND the SAME stable `sub` as the initial token (no
+ * re-consent, no `sub` drift). `null` if the row is unexpectedly absent.
+ */
+export async function getRefreshTokenIdentity(
+  context: RefreshTokenContext,
+  plaintext: string,
+): Promise<RefreshTokenIdentity | null> {
+  const row = await context.store.findByHash(hashToken(plaintext));
+  return row ? { userEmail: row.userEmail, userSub: row.userSub } : null;
+}