@12-apps/mcp 1.19.0 → 2.0.0

package/src/oauth/stores.ts

@@ -0,0 +1,157 @@
+/**
+ * The persistence PORTS of the authorization server (12-23).
+ *
+ * Three tables back the AS, and the package owns all three (see
+ * `prisma/mcp.prisma`): registered clients, rotating refresh tokens, and the
+ * per-user record of which AI host is live. What the package does NOT own is the
+ * client library used to reach them — so every read and write in the surface goes
+ * through these narrow ports, and `createPrismaMcpStores` (in
+ * `./prisma-stores.ts`) fills them for the common case in one line.
+ *
+ * The shapes are deliberately CLOSED and small: a host on something other than
+ * Prisma has a finite surface to fill, and the harness fills exactly this with
+ * hand-written SQL over a real Postgres.
+ */
+
+/** The two token-endpoint auth methods the AS accepts (matches the DB CHECK). */
+export type TokenEndpointAuthMethod = "none" | "client_secret_basic";
+
+/** A registered OAuth client (an external host app — Claude.ai, ChatGPT…). */
+export interface StoredOAuthClient {
+  clientId: string;
+  /** SHA-256 hex of the secret; `null` for a public PKCE client. */
+  clientSecretHash: string | null;
+  /** The EXACT-MATCH allowlist the authorize endpoint validates against. */
+  redirectUris: string[];
+  clientName: string | null;
+  tokenEndpointAuthMethod: string;
+  grantTypes: string[];
+  scopes: string[];
+}
+
+/** What `register` persists (the durable subset of RFC 7591 metadata). */
+export interface NewOAuthClient {
+  clientId: string;
+  clientSecretHash: string | null;
+  redirectUris: string[];
+  clientName: string | null;
+  tokenEndpointAuthMethod: TokenEndpointAuthMethod;
+  grantTypes: string[];
+  scopes: string[];
+}
+
+export interface OAuthClientStore {
+  create(client: NewOAuthClient): Promise<StoredOAuthClient>;
+  /** By the PUBLIC `client_id`, or `null` when unknown. */
+  findByClientId(clientId: string): Promise<StoredOAuthClient | null>;
+}
+
+/** A rotating refresh token, stored HASHED — never plaintext. */
+export interface StoredRefreshToken {
+  tokenHash: string;
+  userEmail: string;
+  /** The original OAuth subject, kept stable across every rotation. */
+  userSub: string;
+  clientId: string;
+  scopes: string[];
+  expiresAt: Date;
+  /** The prior token's hash — the rotation lineage. `null` for a root token. */
+  rotatedFrom: string | null;
+  revokedAt: Date | null;
+}
+
+/** A token about to be stored (the plaintext never is). */
+export type NewRefreshToken = Omit<StoredRefreshToken, "revokedAt">;
+
+export interface RefreshTokenStore {
+  create(token: NewRefreshToken): Promise<void>;
+  findByHash(tokenHash: string): Promise<StoredRefreshToken | null>;
+  /** Whether some token was already rotated FROM this hash (replay detection). */
+  hasSuccessor(tokenHash: string): Promise<boolean>;
+  /** Every token of one `(userEmail, clientId)` family — the lineage walk's input. */
+  listFamily(userEmail: string, clientId: string): Promise<StoredRefreshToken[]>;
+  /** Revoke exactly these hashes (idempotent). */
+  revokeHashes(tokenHashes: readonly string[], at: Date): Promise<void>;
+  /**
+   * CLAIM the parent and store the successor, atomically. The whole of OAuth 2.1
+   * §4.3.1 replay protection rests on this one method, so read the contract before
+   * implementing it.
+   *
+   * Returns `true` when THIS call is the one that consumed `parentHash`, `false`
+   * when another call already had. `false` MUST mean nothing was written: no
+   * successor row, no second revocation.
+   *
+   * An implementation MUST revoke the parent CONDITIONALLY on it still being
+   * unrevoked — `updateMany({ where: { tokenHash: parentHash, revokedAt: null } })`,
+   * requiring a count of exactly 1 — and create the successor in the SAME
+   * transaction. An unconditional `update` is NOT enough: two concurrent rotations
+   * of one parent would both succeed, leaving two live successors of one token with
+   * no replay ever detected, because the replay rule fires on a THIRD use of the
+   * parent that then never comes. That is replay protection defeated by WINNING a
+   * race rather than by arriving second — precisely the attack rotation exists to
+   * stop, since an attacker holding a stolen refresh token need only fire it
+   * alongside the legitimate client to walk away with a live, independently
+   * rotating family.
+   *
+   * Atomicity against a CRASH is necessary too (a half-applied rotation leaves a
+   * live parent AND a live child) but it is not sufficient, and it is the easier
+   * half to satisfy by accident.
+   */
+  rotate(successor: NewRefreshToken, parentHash: string, at: Date): Promise<boolean>;
+  /**
+   * Revoke every LIVE token a user holds for one client; returns how many were
+   * actually ended (already-revoked rows are skipped, so a repeat reports 0).
+   */
+  revokeLiveForClient(userEmail: string, clientId: string): Promise<number>;
+}
+
+/** The AI provider a connection is attributed to. */
+export type McpConnectionHost = string;
+
+/** A live connection, as the account surface shows it. */
+export interface StoredMcpConnection {
+  oauthClientId: string;
+  clientName: string | null;
+  /** `null` for a pre-attribution connection. */
+  host: string | null;
+  connectedAt: Date;
+  lastActiveAt: Date;
+}
+
+export interface McpConnectionStore {
+  /** Liveness of one `(user, client)` pair, for the activity throttle. */
+  lastActiveAt(userId: string, oauthClientId: string): Promise<Date | null>;
+  /**
+   * Record (or refresh) liveness. Any activity CLEARS a prior `revokedAt` — the
+   * host is talking to us again — and must never blank a known `host` when this
+   * grant cannot derive one.
+   */
+  recordActivity(input: {
+    userId: string;
+    oauthClientId: string;
+    clientName: string | null;
+    host: string | null;
+    at: Date;
+  }): Promise<void>;
+  /** A user's active (non-revoked) connections, most-recently-active first. */
+  listActive(userId: string): Promise<StoredMcpConnection[]>;
+  /**
+   * Revoke every live connection of one provider for this user and return the
+   * OAuth client ids that were revoked — the caller ends their refresh tokens,
+   * which is what actually cuts access.
+   */
+  revokeByHost(userId: string, host: McpConnectionHost): Promise<string[]>;
+  /**
+   * The self-report path: attribute this user's just-connected, still-unattributed
+   * connection to `host`, or refresh the one already attributed to it. Returns
+   * rows touched.
+   */
+  announce(userId: string, host: McpConnectionHost): Promise<number>;
+}
+
+/** The stores the AS needs. `connections` is optional — see the config docs. */
+export interface McpOauthStores {
+  clients: OAuthClientStore;
+  refreshTokens: RefreshTokenStore;
+  connections?: McpConnectionStore;
+}

package/src/oauth/token-grants.ts

@@ -0,0 +1,326 @@
+import { ACCESS_TOKEN_TTL_SECONDS, signAccessToken } from "./access-token";
+import { AuthorizationCodeError, verifyCode } from "./authorization-code";
+import { providerFromRedirectUris } from "./clients";
+import type { McpConnectionRecording, McpOauthContext } from "./context";
+import { verifyChallenge } from "./pkce";
+import {
+  RefreshTokenError,
+  getRefreshTokenIdentity,
+  issueRefreshToken,
+  rotateRefreshToken,
+} from "./refresh";
+import type { McpConnectionStore } from "./stores";
+import {
+  authenticateClient,
+  readClientCredentials,
+  tokenError,
+  tokenSuccess,
+  type ClientCredentials,
+} from "./token-response";
+
+/**
+ * The two grant handlers of the token endpoint (12-23, ported from future-pay's
+ * `lib/mcp/oauth/token-grants.ts`).
+ *
+ * Security invariants enforced here, unchanged:
+ *   - **Single-use codes:** the code's `jti` is consumed the moment it is
+ *     redeemed; a replay of the same code is `invalid_grant`.
+ *   - **PKCE:** a `code_verifier` that does not S256-match the code's
+ *     `code_challenge` is `invalid_grant`.
+ *   - **Client auth:** a public client's `client_id` must equal the code's bound
+ *     client; a confidential client must present a secret whose SHA-256 matches
+ *     the stored hash, else `invalid_client` (401).
+ *   - **Bound `redirect_uri`:** it must equal the one the code was minted with
+ *     (RFC 6749 §4.1.3).
+ *   - **Refresh rotation:** client-bound, replay-revoking, narrow-only scope.
+ */
+
+/** Throttle default: don't rewrite liveness on every grant. */
+const DEFAULT_ACTIVITY_THROTTLE_MS = 60_000;
+
+/**
+ * Best-effort: record that this user's AI host (OAuth client) is live, so an
+ * account page can show "connected via Claude · active 2 min ago". Runs on the
+ * token grant, not the per-request hot path; hosts refresh every ~15 min so
+ * liveness stays fresh.
+ *
+ * NEVER lets a failure break token issuance — a recording error is swallowed, and
+ * nothing about it is logged, because the only interesting values here are an
+ * email and a client id. Skipped when the host resolves no user row (email is the
+ * identity) or when no connection recording is configured at all.
+ */
+async function recordHostConnection(
+  context: McpOauthContext,
+  email: string,
+  clientId: string,
+): Promise<void> {
+  const recording = context.connections;
+  const store = context.stores.connections;
+  if (!recording || !store) return;
+  try {
+    await writeConnectionActivity(context, { recording, store }, email, clientId);
+  } catch {
+    // Liveness is non-critical — never fail the grant on it. Nothing is logged
+    // either: the only values here are an email and a client id.
+  }
+}
+
+/** The write itself, once the recording ports are known to exist. */
+async function writeConnectionActivity(
+  context: McpOauthContext,
+  ports: { recording: McpConnectionRecording; store: McpConnectionStore },
+  email: string,
+  clientId: string,
+): Promise<void> {
+  const { recording, store } = ports;
+  const [userId, client] = await Promise.all([
+    recording.resolveUserId(email),
+    context.stores.clients.findByClientId(clientId),
+  ]);
+  // No user row yet: email is the identity the AS binds to, so the grant stands
+  // and there is simply nothing to attribute it to.
+  if (!userId) return;
+
+  const throttleMs = recording.activityThrottleMs ?? DEFAULT_ACTIVITY_THROTTLE_MS;
+  const lastActiveAt = await store.lastActiveAt(userId, clientId);
+  const now = new Date();
+  if (lastActiveAt && now.getTime() - lastActiveAt.getTime() < throttleMs) return;
+
+  await store.recordActivity({
+    userId,
+    oauthClientId: clientId,
+    clientName: client?.clientName ?? null,
+    // Attribute to a provider from the client's redirect URIs (claude.ai →
+    // claude, chatgpt.com → chatgpt) so an account page lights the right card.
+    host: client ? providerFromRedirectUris(client.redirectUris, recording.providerRules) : null,
+    at: now,
+  });
+}
+
+/** The presented `authorization_code` grant parameters, once validated present. */
+interface AuthorizationCodeParams {
+  code: string;
+  redirectUri: string;
+  codeVerifier: string;
+}
+
+/**
+ * Read + presence-check the `authorization_code` form parameters. Returns the three
+ * required values, or an `invalid_request` (400) naming the first missing field.
+ */
+function readAuthorizationCodeParams(form: URLSearchParams): AuthorizationCodeParams | Response {
+  const code = form.get("code");
+  const redirectUri = form.get("redirect_uri");
+  const codeVerifier = form.get("code_verifier");
+
+  if (!code) return tokenError("invalid_request", 400, "missing code");
+  if (!redirectUri) return tokenError("invalid_request", 400, "missing redirect_uri");
+  if (!codeVerifier) return tokenError("invalid_request", 400, "missing code_verifier");
+
+  return { code, redirectUri, codeVerifier };
+}
+
+/**
+ * Redeem a presented code, or refuse.
+ *
+ * The ORDER is the security contract, and it is the order future-pay established:
+ * verify the code's signature, authenticate the presenting client against the
+ * client the code was bound to, check the bound `redirect_uri`, check PKCE — and
+ * only THEN consume the single-use `jti`. Consuming earlier would let a failed
+ * attempt (a wrong secret, a mismatched verifier) burn a legitimate code.
+ */
+async function redeemCode(
+  context: McpOauthContext,
+  params: AuthorizationCodeParams,
+  credentials: ClientCredentials,
+  origin: string,
+): Promise<Awaited<ReturnType<typeof verifyCode>> | Response> {
+  const { code, redirectUri, codeVerifier } = params;
+
+  // Every code-level failure (expired, tampered, wrong-audience) is invalid_grant.
+  let verified;
+  try {
+    verified = await verifyCode(context.signingKey, code, { origin });
+  } catch (error) {
+    if (error instanceof AuthorizationCodeError) {
+      return tokenError("invalid_grant", 400, "invalid or expired authorization code");
+    }
+    throw error;
+  }
+
+  const authError = await authenticateClient(
+    context.stores.clients,
+    credentials,
+    verified.clientId,
+  );
+  if (authError) return authError;
+
+  // The redirect_uri MUST match the one the code was bound to (RFC 6749 §4.1.3).
+  if (redirectUri !== verified.redirectUri) {
+    return tokenError("invalid_grant", 400, "redirect_uri mismatch");
+  }
+
+  // PKCE: the presented verifier must S256-match the bound challenge.
+  if (!(await verifyChallenge(codeVerifier, verified.codeChallenge))) {
+    return tokenError("invalid_grant", 400, "PKCE verification failed");
+  }
+
+  // Single-use: consume the code's jti; a replay of the same code fails.
+  if (!(await context.codeReplay.consume(verified.jti, Date.now()))) {
+    return tokenError("invalid_grant", 400, "authorization code already used");
+  }
+
+  return verified;
+}
+
+/** Handle the `authorization_code` grant. */
+async function handleAuthorizationCode(
+  context: McpOauthContext,
+  form: URLSearchParams,
+  credentials: ClientCredentials,
+  origin: string,
+): Promise<Response> {
+  const params = readAuthorizationCodeParams(form);
+  if (params instanceof Response) return params;
+
+  const verified = await redeemCode(context, params, credentials, origin);
+  if (verified instanceof Response) return verified;
+
+  const scopes = verified.scope.split(/\s+/).filter(Boolean);
+
+  const accessToken = await signAccessToken(context.signingKey, {
+    email: verified.email,
+    subject: verified.sub,
+    scopes,
+    origin,
+    resourcePath: context.resourcePath,
+    ttlSeconds: context.accessTokenTtlSeconds,
+  });
+  if (!accessToken) {
+    // No signing key configured while the surface is on — refuse rather than fall
+    // back to a weaker mode (safe-by-default).
+    return tokenError("invalid_request", 400, "token issuance unavailable");
+  }
+
+  const refresh = await issueRefreshToken(
+    { store: context.stores.refreshTokens, ttlMs: context.refreshTokenTtlMs },
+    {
+      userEmail: verified.email,
+      userSub: verified.sub,
+      clientId: verified.clientId,
+      scopes,
+    },
+  );
+
+  await recordHostConnection(context, verified.email, verified.clientId);
+
+  return tokenSuccess({
+    access_token: accessToken,
+    token_type: "Bearer",
+    expires_in: context.accessTokenTtlSeconds ?? ACCESS_TOKEN_TTL_SECONDS,
+    refresh_token: refresh.refreshToken,
+    scope: refresh.scopes.join(" "),
+  });
+}
+
+/** Handle the `refresh_token` grant. */
+async function handleRefreshToken(
+  context: McpOauthContext,
+  form: URLSearchParams,
+  credentials: ClientCredentials,
+  origin: string,
+): Promise<Response> {
+  const refreshToken = form.get("refresh_token");
+  const requestedScope = form.get("scope");
+
+  if (!refreshToken) return tokenError("invalid_request", 400, "missing refresh_token");
+
+  // Authenticate the presenting client (public: client_id present; confidential:
+  // secret checked). `authenticateClient` rejects a missing client_id, so on
+  // success `credentials.clientId` is non-null and is the identity the rotation is
+  // bound to below.
+  const authError = await authenticateClient(context.stores.clients, credentials);
+  if (authError) return authError;
+  const clientId = credentials.clientId as string;
+
+  const newScopes = requestedScope ? requestedScope.split(/\s+/).filter(Boolean) : undefined;
+  const refreshContext = {
+    store: context.stores.refreshTokens,
+    ttlMs: context.refreshTokenTtlMs,
+  };
+
+  // Rotation enforces client binding (the token's stored clientId must equal the
+  // authenticated one, else invalid_grant — OAuth 2.1 §4.3), plus
+  // replay-revocation and scope-narrowing.
+  let rotated;
+  try {
+    rotated = await rotateRefreshToken(refreshContext, refreshToken, clientId, newScopes);
+  } catch (error) {
+    if (error instanceof RefreshTokenError) {
+      return tokenError(error.code, 400, error.message);
+    }
+    throw error;
+  }
+
+  // The refresh token binds the user's email AND original OAuth `sub`; recover both
+  // so the successor access token carries the SAME stable `sub` as the initial
+  // token (RFC 6749 §5.1 / OIDC §2), not the email.
+  const identity = await getRefreshTokenIdentity(refreshContext, rotated.refreshToken);
+  if (!identity) return tokenError("invalid_grant", 400, "refresh token binding not found");
+
+  const accessToken = await signAccessToken(context.signingKey, {
+    email: identity.userEmail,
+    subject: identity.userSub,
+    scopes: rotated.scopes,
+    origin,
+    resourcePath: context.resourcePath,
+    ttlSeconds: context.accessTokenTtlSeconds,
+  });
+  if (!accessToken) return tokenError("invalid_request", 400, "token issuance unavailable");
+
+  await recordHostConnection(context, identity.userEmail, clientId);
+
+  return tokenSuccess({
+    access_token: accessToken,
+    token_type: "Bearer",
+    expires_in: context.accessTokenTtlSeconds ?? ACCESS_TOKEN_TTL_SECONDS,
+    refresh_token: rotated.refreshToken,
+    scope: rotated.scopes.join(" "),
+  });
+}
+
+/**
+ * `POST <token>` — the endpoint itself: gate → parse form → dispatch by
+ * `grant_type`. Thin on purpose; the flows above are where the invariants live.
+ */
+export async function tokenEndpoint(
+  context: McpOauthContext,
+  request: Request,
+): Promise<Response> {
+  const origin = context.originOf(request);
+
+  let form: URLSearchParams;
+  try {
+    form = new URLSearchParams(await request.text());
+  } catch {
+    return tokenError("invalid_request", 400, "malformed request body");
+  }
+
+  const grantType = form.get("grant_type");
+  if (!grantType) return tokenError("invalid_request", 400, "missing grant_type");
+
+  const credentials = readClientCredentials(request, form);
+
+  switch (grantType) {
+    case "authorization_code":
+      return handleAuthorizationCode(context, form, credentials, origin);
+    case "refresh_token":
+      return handleRefreshToken(context, form, credentials, origin);
+    default:
+      return tokenError(
+        "unsupported_grant_type",
+        400,
+        `grant_type '${grantType}' is not supported`,
+      );
+  }
+}

package/src/oauth/token-response.ts

@@ -0,0 +1,154 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+
+import type { OAuthClientStore } from "./stores";
+
+/**
+ * The token endpoint's wire helpers: the RFC 6749 §5.1/§5.2 bodies and client
+ * authentication (12-23, split out of the grant handlers so each file stays under
+ * the size gate — the same split future-pay made).
+ *
+ * These bodies are NOT the house `{ data }` envelope, deliberately: they are read
+ * by OAuth clients that expect the RFC shapes at the top level, and `Cache-Control:
+ * no-store` is required on every one of them because they carry credentials.
+ */
+
+/** OAuth 2.1 / RFC 6749 §5.2 error codes the token endpoint can emit. */
+type TokenErrorCode =
+  | "invalid_request"
+  | "invalid_client"
+  | "invalid_grant"
+  | "invalid_scope"
+  | "unsupported_grant_type";
+
+/** The RFC 6749 §5.1 successful token response. */
+interface TokenSuccessResponse {
+  access_token: string;
+  token_type: "Bearer";
+  expires_in: number;
+  refresh_token: string;
+  scope: string;
+}
+
+const JSON_HEADERS = {
+  "content-type": "application/json; charset=utf-8",
+  "cache-control": "no-store",
+} as const;
+
+/** A JSON error response in the RFC 6749 §5.2 shape. */
+export function tokenError(
+  error: TokenErrorCode,
+  status: number,
+  description?: string,
+  headers: Record<string, string> = {},
+): Response {
+  const body: { error: TokenErrorCode; error_description?: string } = { error };
+  if (description) body.error_description = description;
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { ...JSON_HEADERS, ...headers },
+  });
+}
+
+/** A JSON success response with `Cache-Control: no-store` (RFC 6749 §5.1). */
+export function tokenSuccess(payload: TokenSuccessResponse): Response {
+  return new Response(JSON.stringify(payload), { status: 200, headers: { ...JSON_HEADERS } });
+}
+
+/** Constant-time equality of two SHA-256 hex digests. */
+function hashesEqual(a: string, b: string): boolean {
+  const bufA = Buffer.from(a, "hex");
+  const bufB = Buffer.from(b, "hex");
+  if (bufA.length !== bufB.length || bufA.length === 0) return false;
+  return timingSafeEqual(bufA, bufB);
+}
+
+/** SHA-256 hex digest — matches the at-rest client-secret hashing convention. */
+function sha256Hex(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+/** Client credentials extracted from HTTP Basic auth or the form body. */
+export interface ClientCredentials {
+  clientId: string | null;
+  clientSecret: string | null;
+}
+
+/**
+ * Resolve the presented client credentials. HTTP Basic (`client_secret_basic`)
+ * takes precedence over the form-body `client_id` per RFC 6749 §2.3.1; a malformed
+ * Basic header is treated as absent (the form body still applies).
+ */
+export function readClientCredentials(
+  request: Request,
+  form: URLSearchParams,
+): ClientCredentials {
+  const authorization = request.headers.get("authorization");
+  if (authorization && authorization.startsWith("Basic ")) {
+    const decoded = Buffer.from(authorization.slice(6), "base64").toString("utf8");
+    const separator = decoded.indexOf(":");
+    if (separator !== -1) {
+      return {
+        clientId: decoded.slice(0, separator),
+        clientSecret: decoded.slice(separator + 1),
+      };
+    }
+  }
+  return { clientId: form.get("client_id"), clientSecret: form.get("client_secret") };
+}
+
+/** The 401 challenge issued on a client-authentication failure. */
+const CLIENT_AUTH_CHALLENGE = { "www-authenticate": 'Basic realm="oauth-token"' };
+
+/**
+ * Authenticate the client that presents the request. A public client is identified
+ * by `client_id` alone (which must equal `expectedClientId` when provided). A
+ * confidential client (`client_secret_basic`) MUST present a secret whose SHA-256
+ * matches the stored hash. Returns `null` on success, or a 401 `invalid_client`
+ * response on failure — never a body that says which half was wrong.
+ */
+export async function authenticateClient(
+  clients: OAuthClientStore,
+  credentials: ClientCredentials,
+  expectedClientId?: string,
+): Promise<Response | null> {
+  const clientId = credentials.clientId;
+  if (!clientId) {
+    return tokenError("invalid_client", 401, "missing client_id", CLIENT_AUTH_CHALLENGE);
+  }
+  if (expectedClientId && clientId !== expectedClientId) {
+    // The presenting client does not match the client the code was issued to.
+    return tokenError(
+      "invalid_client",
+      401,
+      "client_id does not match the grant",
+      CLIENT_AUTH_CHALLENGE,
+    );
+  }
+
+  const client = await clients.findByClientId(clientId);
+  if (!client) {
+    return tokenError("invalid_client", 401, "unknown client", CLIENT_AUTH_CHALLENGE);
+  }
+
+  if (client.tokenEndpointAuthMethod === "client_secret_basic") {
+    const secret = credentials.clientSecret;
+    if (!secret || !client.clientSecretHash) {
+      return tokenError(
+        "invalid_client",
+        401,
+        "client authentication required",
+        CLIENT_AUTH_CHALLENGE,
+      );
+    }
+    if (!hashesEqual(sha256Hex(secret), client.clientSecretHash)) {
+      return tokenError(
+        "invalid_client",
+        401,
+        "invalid client credentials",
+        CLIENT_AUTH_CHALLENGE,
+      );
+    }
+  }
+
+  return null;
+}