@12-apps/mcp 1.19.0 → 2.0.0

package/src/oauth/authorization-code.ts

@@ -0,0 +1,215 @@
+import { SignJWT, jwtVerify, importJWK, type JWTPayload } from "jose";
+
+import { issuer } from "./config";
+import { SIGNING_ALG, type McpSigningKeyProvider } from "./keys";
+
+/**
+ * Stateless authorization-code mint/verify (12-23, ported from future-pay's
+ * `lib/mcp/oauth/authorization-code.ts` — behaviour unchanged; the signing key
+ * arrives through a provider instead of an env read).
+ *
+ * The authorization code is a short-lived (<=60s) ES256-signed JWT — no DB table,
+ * no cleanup job. It binds the signed-in user (`sub`/`email`), the `client_id`,
+ * the `redirect_uri`, the PKCE `code_challenge`, and the requested `scope`, plus a
+ * unique `jti` the token endpoint records once to enforce single-use (replay)
+ * semantics on top of the short expiry.
+ *
+ * The code carries a DISTINCT audience (`oauth:code`) from the access token
+ * (`${origin}/api/mcp`), so a code can never be presented to the resource server
+ * as a bearer access token (and vice versa): {@link verifyCode} pins
+ * `audience: "oauth:code"`, and the access-token verifier pins the resource
+ * audience — each rejects the other's blobs.
+ */
+
+/**
+ * Audience pinning the code to the OAuth code-exchange step only. Distinct from
+ * the access-token audience so a code cannot be replayed as an access token.
+ */
+export const AUTHORIZATION_CODE_AUDIENCE = "oauth:code";
+
+/** Authorization-code lifetime — single-use and short-lived (<=60s per spec). */
+export const AUTHORIZATION_CODE_TTL_SECONDS = 60;
+
+/** Clock skew tolerated on `exp`/`iat` validation, in seconds. */
+const CLOCK_TOLERANCE_SECONDS = 5;
+
+/** Fields bound into a minted authorization code. */
+export interface MintCodeInput {
+  /** The OAuth subject bound to the code (identity from the cookie session). */
+  sub: string;
+  /** The signed-in user's email (the identity all downstream tokens bind to). */
+  email: string;
+  /** The OAuth client the code is issued to. */
+  clientId: string;
+  /** The exact registered redirect URI the flow started with. */
+  redirectUri: string;
+  /** The PKCE S256 `code_challenge` the token endpoint verifies against. */
+  codeChallenge: string;
+  /** The requested scope (space-delimited), carried through to the token. */
+  scope: string;
+  /** The deployment origin — derives the code's `iss`. */
+  origin: string;
+}
+
+/** The bound fields a verified authorization code resolves to. */
+export interface VerifiedAuthorizationCode {
+  sub: string;
+  email: string;
+  clientId: string;
+  redirectUri: string;
+  codeChallenge: string;
+  scope: string;
+  /** The one-time identifier the token endpoint records to enforce single-use. */
+  jti: string;
+}
+
+/** The single failure discriminator for the OAuth token endpoint. */
+export type AuthorizationCodeErrorCode = "invalid_grant";
+
+/**
+ * A typed authorization-code failure. Every rejection (expired, wrong-audience,
+ * wrong-issuer, tampered, bad-signature, unconfigured key) surfaces as
+ * `invalid_grant` per RFC 6749 §5.2 for the token endpoint.
+ */
+export class AuthorizationCodeError extends Error {
+  readonly code: AuthorizationCodeErrorCode;
+
+  constructor(message?: string) {
+    super(message ?? "invalid_grant");
+    this.name = "AuthorizationCodeError";
+    this.code = "invalid_grant";
+  }
+}
+
+/** Deterministic-clock option shared by mint + verify. */
+interface ClockOption {
+  /** Epoch milliseconds; defaults to `Date.now()`. Injected for deterministic tests. */
+  now?: number;
+}
+
+/** The JWT claim shape of an authorization code. */
+interface AuthorizationCodeClaims extends JWTPayload {
+  email: string;
+  client_id: string;
+  redirect_uri: string;
+  code_challenge: string;
+  scope: string;
+}
+
+function nowSeconds(now?: number): number {
+  return Math.floor((now ?? Date.now()) / 1000);
+}
+
+/** Read a required string claim, or `null` when absent/wrong-typed. */
+function stringClaim(payload: JWTPayload, key: string): string | null {
+  const value = payload[key];
+  return typeof value === "string" ? value : null;
+}
+
+/**
+ * Extract the bound fields from an already-signature/iss/aud/exp-validated code
+ * payload, enforcing that every required claim is a present string (`scope` may be
+ * the empty string but must be present). Throws {@link AuthorizationCodeError}
+ * when any required bound field is missing or wrong-typed.
+ */
+function extractBoundFields(payload: JWTPayload): VerifiedAuthorizationCode {
+  const sub = stringClaim(payload, "sub");
+  const email = stringClaim(payload, "email");
+  const clientId = stringClaim(payload, "client_id");
+  const redirectUri = stringClaim(payload, "redirect_uri");
+  const codeChallenge = stringClaim(payload, "code_challenge");
+  const scope = stringClaim(payload, "scope");
+  const jti = stringClaim(payload, "jti");
+
+  if (!sub || !email || !clientId || !redirectUri || !codeChallenge || scope === null || !jti) {
+    throw new AuthorizationCodeError("code is missing required bound fields");
+  }
+
+  return { sub, email, clientId, redirectUri, codeChallenge, scope, jti };
+}
+
+/**
+ * Mint a single-use, stateless authorization code bound to the flow inputs.
+ *
+ * Returns `null` when no signing key is configured (safe-by-default: the AS
+ * refuses to issue rather than falling back to a weaker mode). Sets the `kid`
+ * header so the same key resolves the code at verify time.
+ */
+export async function mintCode(
+  loadSigningKey: McpSigningKeyProvider,
+  input: MintCodeInput,
+  options?: ClockOption,
+): Promise<string | null> {
+  const key = await loadSigningKey();
+  if (!key) return null;
+
+  const iat = nowSeconds(options?.now);
+  const exp = iat + AUTHORIZATION_CODE_TTL_SECONDS;
+
+  const claims: AuthorizationCodeClaims = {
+    email: input.email,
+    client_id: input.clientId,
+    redirect_uri: input.redirectUri,
+    code_challenge: input.codeChallenge,
+    scope: input.scope,
+  };
+
+  return new SignJWT(claims)
+    .setProtectedHeader({ alg: SIGNING_ALG, kid: key.kid })
+    .setIssuer(issuer(input.origin))
+    .setAudience(AUTHORIZATION_CODE_AUDIENCE)
+    .setSubject(input.sub)
+    .setIssuedAt(iat)
+    .setExpirationTime(exp)
+    .setJti(crypto.randomUUID())
+    .sign(key.privateKey);
+}
+
+/** Options for {@link verifyCode}. */
+export interface VerifyCodeOptions extends ClockOption {
+  /** The deployment origin — derives the expected `iss`. */
+  origin: string;
+}
+
+/**
+ * Verify a stateless authorization code and return its bound fields.
+ *
+ * Validates signature (via the public JWK selected by `kid`), `iss`, the
+ * `oauth:code` audience, and `exp`. Every failure — expired, wrong-audience (e.g.
+ * an access token), wrong-issuer, tampered, bad-signature, or no configured key —
+ * throws an {@link AuthorizationCodeError} (`invalid_grant`).
+ *
+ * The returned `jti` is the one-time identifier the token endpoint records to
+ * enforce single-use on top of the short expiry (replay guard).
+ */
+export async function verifyCode(
+  loadSigningKey: McpSigningKeyProvider,
+  code: string,
+  options: VerifyCodeOptions,
+): Promise<VerifiedAuthorizationCode> {
+  const key = await loadSigningKey();
+  if (!key) {
+    // No signing key configured → nothing can verify (safe-by-default).
+    throw new AuthorizationCodeError("no signing key configured");
+  }
+
+  const publicKey = await importJWK(key.publicJwk, SIGNING_ALG);
+
+  let payload: JWTPayload;
+  try {
+    const result = await jwtVerify(code, publicKey, {
+      algorithms: [SIGNING_ALG],
+      issuer: issuer(options.origin),
+      audience: AUTHORIZATION_CODE_AUDIENCE,
+      clockTolerance: CLOCK_TOLERANCE_SECONDS,
+      currentDate: options.now === undefined ? undefined : new Date(options.now),
+    });
+    payload = result.payload;
+  } catch {
+    // jose throws on bad signature, wrong iss/aud, expiry, malformed token,
+    // unknown key — all map to a single opaque `invalid_grant`.
+    throw new AuthorizationCodeError("code verification failed");
+  }
+
+  return extractBoundFields(payload);
+}

package/src/oauth/authorize.ts

@@ -0,0 +1,260 @@
+import { mintCode } from "./authorization-code";
+import { matchesRedirectUri } from "./clients";
+import type { McpOauthContext } from "./context";
+import { SUPPORTED_CHALLENGE_METHOD } from "./pkce";
+import type { StoredOAuthClient } from "./stores";
+
+/**
+ * The OAuth 2.1 Authorization Code + PKCE authorization endpoint (12-23, ported
+ * from future-pay's `app/api/oauth/authorize/route.ts`).
+ *
+ * It renders no UI: it authenticates the caller against the host's cookie session
+ * (through `resolveSession`), validates the request, and either 302-redirects an
+ * unauthenticated caller into the host's sign-in flow (so the flow resumes
+ * post-login) or, for a signed-in caller with a valid request, mints a stateless
+ * authorization code bound to the SESSION identity and 302-redirects back to the
+ * client's registered `redirect_uri` with the code and echoed `state`.
+ *
+ * Security invariants, unchanged:
+ *   - **Open-redirect prevention:** `client_id` + `redirect_uri` are validated
+ *     against the registered client BEFORE anything else; an unknown client or a
+ *     `redirect_uri` that is not an EXACT registered match yields a 400 plain-text
+ *     response — the endpoint NEVER redirects an error to an unvalidated URI. Only
+ *     once the URI is validated do other failures redirect back to it.
+ *   - **Mandatory PKCE S256:** a missing `code_challenge`, or a method other than
+ *     `S256` (incl. `plain`), is rejected.
+ *   - **Identity from the session only:** `sub`/`email` come solely from the
+ *     verified session; a client can never supply the identity via a query param.
+ *   - **No key, no code:** an unprovisioned signing key is a `server_error`
+ *     redirect, never a weaker mode.
+ */
+
+/** OAuth 2.1 error codes this endpoint can emit on a validated redirect_uri. */
+type AuthorizeErrorCode =
+  | "invalid_request"
+  | "unsupported_response_type"
+  | "invalid_scope"
+  /** The resource owner said no — or nobody was asked and nobody approved. */
+  | "access_denied"
+  | "server_error";
+
+/** The parsed, still-untrusted query parameters of an authorize request. */
+interface AuthorizeParams {
+  responseType: string | null;
+  clientId: string | null;
+  redirectUri: string | null;
+  codeChallenge: string | null;
+  codeChallengeMethod: string | null;
+  scope: string | null;
+  state: string | null;
+}
+
+function parseParams(url: URL): AuthorizeParams {
+  const q = url.searchParams;
+  return {
+    responseType: q.get("response_type"),
+    clientId: q.get("client_id"),
+    redirectUri: q.get("redirect_uri"),
+    codeChallenge: q.get("code_challenge"),
+    codeChallengeMethod: q.get("code_challenge_method"),
+    scope: q.get("scope"),
+    state: q.get("state"),
+  };
+}
+
+/** A 302 response to `location` with no body. */
+function redirectTo(location: string): Response {
+  return new Response(null, { status: 302, headers: { location } });
+}
+
+/**
+ * A 400 plain-text refusal used ONLY when the `redirect_uri`/`client_id` are
+ * themselves invalid — i.e. there is no validated URI to safely redirect an error
+ * to (the open-redirect guard).
+ */
+function badRequest(message: string): Response {
+  return new Response(message, {
+    status: 400,
+    headers: { "content-type": "text/plain; charset=utf-8" },
+  });
+}
+
+/**
+ * Build an error redirect back to the (already-validated) `redirect_uri`, carrying
+ * the OAuth `error` and the echoed `state` per OAuth 2.1 §4.1.2.1.
+ */
+function errorRedirect(
+  redirectUri: string,
+  error: AuthorizeErrorCode,
+  state: string | null,
+): Response {
+  const target = new URL(redirectUri);
+  target.searchParams.set("error", error);
+  if (state !== null) target.searchParams.set("state", state);
+  return redirectTo(target.toString());
+}
+
+/**
+ * Whether every space-delimited requested scope is within `allowed`. An
+ * empty/absent scope is permitted (the server applies its default), but any present
+ * scope must be in `allowed` — and `allowed` is the SPECIFIC CLIENT's registered
+ * scopes, so a client that registered for only `mcp:read` cannot request
+ * `mcp:write` and be issued a code for it ("no privilege escalation via metadata",
+ * enforced at authorize rather than trusted at registration).
+ */
+function scopeIsSupported(scope: string | null, allowed: readonly string[]): boolean {
+  if (!scope) return true;
+  const requested = scope.split(/\s+/).filter(Boolean);
+  const allowedSet = new Set<string>(allowed);
+  return requested.every((candidate) => allowedSet.has(candidate));
+}
+
+/**
+ * Resolve + validate the client and its `redirect_uri` FIRST (the open-redirect
+ * guard). Returns the validated URI AND the client's registered scopes, or a plain
+ * 400 — NEVER a redirect — when the client or URI is unknown/unregistered, so an
+ * error is never steered to an unvalidated URI.
+ */
+async function validateClientAndRedirect(
+  context: McpOauthContext,
+  params: AuthorizeParams,
+): Promise<{ client: StoredOAuthClient; redirectUri: string } | Response> {
+  if (!params.clientId) return badRequest("invalid_request: missing client_id");
+  if (!params.redirectUri) return badRequest("invalid_request: missing redirect_uri");
+
+  const client = await context.stores.clients.findByClientId(params.clientId);
+  if (!client) return badRequest("invalid_client: unknown client_id");
+  if (!matchesRedirectUri(client, params.redirectUri)) {
+    return badRequest("invalid_request: redirect_uri is not registered");
+  }
+
+  return { client, redirectUri: params.redirectUri };
+}
+
+/**
+ * Validate the response_type, mandatory PKCE S256, and the requested scope against
+ * the already-validated `redirectUri`. Returns `null` when the request passes, or an
+ * error redirect back to the validated URI on the first failure.
+ */
+function validateAuthorizeRequest(
+  params: AuthorizeParams,
+  redirectUri: string,
+  clientScopes: readonly string[],
+): Response | null {
+  const { state } = params;
+
+  if (params.responseType !== "code") {
+    return errorRedirect(redirectUri, "unsupported_response_type", state);
+  }
+  // Mandatory PKCE S256: reject a missing challenge or any non-S256 method.
+  if (!params.codeChallenge || params.codeChallengeMethod !== SUPPORTED_CHALLENGE_METHOD) {
+    return errorRedirect(redirectUri, "invalid_request", state);
+  }
+  if (!scopeIsSupported(params.scope, clientScopes)) {
+    return errorRedirect(redirectUri, "invalid_scope", state);
+  }
+  return null;
+}
+
+/** The already-validated inputs an authorize request resolves to before minting. */
+interface ValidatedAuthorize {
+  /** The registered client — needed by the approval seam, not just its id. */
+  client: StoredOAuthClient;
+  clientId: string;
+  redirectUri: string;
+  codeChallenge: string;
+  scope: string;
+  state: string | null;
+}
+
+/**
+ * With a validated request, resolve the authenticated session (identity from the
+ * session ONLY) and either send the caller through sign-in, mint the code, or
+ * `server_error` when no signing key is configured.
+ */
+async function authenticateAndMint(
+  context: McpOauthContext,
+  request: Request,
+  url: URL,
+  origin: string,
+  validated: ValidatedAuthorize,
+): Promise<Response> {
+  const { redirectUri, state } = validated;
+
+  const session = await context.resolveSession(request);
+  if (!session?.email) {
+    // No session: send the caller through the host's sign-in flow with a callback
+    // back to THIS authorize URL so the flow resumes post-login. No code is minted
+    // for an unauthenticated request.
+    const loginUrl = new URL(context.loginPath, origin);
+    loginUrl.searchParams.set(context.loginCallbackParam, url.pathname + url.search);
+    return redirectTo(loginUrl.toString());
+  }
+
+  // CONSENT. A session proves WHO is asking; it never proves they agreed to THIS
+  // client holding THESE scopes. Registration is open (RFC 7591), so without this
+  // step anyone may register a client carrying their own redirect URI and their own
+  // scope ceiling, send a signed-in admin a single link, and have that admin's
+  // browser mint them a code — and the two guards that look like they would stop it,
+  // exact redirect-URI matching and the per-client scope ceiling, are both checked
+  // against the ATTACKER'S OWN registration. Refuses by default; see
+  // `resolveApproval` / `preApprovedClientIds`.
+  const scopes = validated.scope.split(/\s+/).filter(Boolean);
+  if (!(await context.approve(request, validated.client, scopes))) {
+    // The answer a human refusal gives, at the URI validated further up.
+    return errorRedirect(redirectUri, "access_denied", state);
+  }
+
+  const code = await mintCode(context.signingKey, {
+    // The subject is the OAuth `sub` the host resolved, NOT a DB id: downstream
+    // guards resolve the user by EMAIL, and the code carries only what the session
+    // verified.
+    sub: session.subject || session.email,
+    email: session.email,
+    clientId: validated.clientId,
+    redirectUri,
+    codeChallenge: validated.codeChallenge,
+    scope: validated.scope,
+    origin,
+  });
+
+  if (!code) {
+    // No signing key configured while the surface is on — refuse to issue rather
+    // than fall back to a weaker mode (safe-by-default).
+    return errorRedirect(redirectUri, "server_error", state);
+  }
+
+  const success = new URL(redirectUri);
+  success.searchParams.set("code", code);
+  if (state !== null) success.searchParams.set("state", state);
+  return redirectTo(success.toString());
+}
+
+/** `GET <authorize>` — the whole endpoint. */
+export async function authorizeEndpoint(
+  context: McpOauthContext,
+  request: Request,
+): Promise<Response> {
+  const url = new URL(request.url);
+  const origin = context.originOf(request);
+  const params = parseParams(url);
+
+  // --- Validate client + redirect_uri FIRST (the open-redirect guard) --------
+  const clientResult = await validateClientAndRedirect(context, params);
+  if (clientResult instanceof Response) return clientResult;
+  const { client, redirectUri } = clientResult;
+
+  // --- Validate the rest (scope checked against the CLIENT's own registration)
+  const requestError = validateAuthorizeRequest(params, redirectUri, client.scopes);
+  if (requestError) return requestError;
+
+  // The guards above guarantee a present client_id + PKCE challenge; narrow them.
+  return authenticateAndMint(context, request, url, origin, {
+    client,
+    clientId: params.clientId as string,
+    redirectUri,
+    codeChallenge: params.codeChallenge as string,
+    scope: params.scope ?? "",
+    state: params.state,
+  });
+}

package/src/oauth/clients.ts

@@ -0,0 +1,158 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+
+import type {
+  OAuthClientStore,
+  StoredOAuthClient,
+  TokenEndpointAuthMethod,
+} from "./stores";
+
+/**
+ * Client registration and the open-redirect guard (12-23, ported from
+ * future-pay's `lib/mcp/oauth/clients.ts`).
+ *
+ * A registered client is an external host (a Claude.ai / ChatGPT connector) from
+ * RFC 7591 dynamic client registration, or a static registration an operator
+ * created out of band. A confidential client's secret is generated HERE, returned
+ * exactly once, and stored only as a SHA-256 hash — it is never persisted in
+ * plaintext, never logged, and never re-derivable.
+ */
+
+/** Default grant types for a registered client (OAuth 2.1 code + refresh). */
+const DEFAULT_GRANT_TYPES = ["authorization_code", "refresh_token"] as const;
+
+/** Bytes of entropy for a generated confidential-client secret (→ 64 hex). */
+const CLIENT_SECRET_BYTES = 32;
+
+/** RFC 7591 registration input (the durable subset the store persists). */
+export interface RegisterClientInput {
+  /** The exact-match redirect-uri allowlist (open-redirect guard). */
+  redirectUris: string[];
+  clientName?: string | null;
+  /**
+   * `none` (public PKCE client, the default) or `client_secret_basic`
+   * (confidential — a secret is generated and its hash stored).
+   */
+  tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
+  /** Grant types; defaults to authorization_code + refresh_token. */
+  grantTypes?: string[];
+  scopes: string[];
+}
+
+/**
+ * The registration RESULT. `clientSecret` is present (plaintext, ONCE) only for a
+ * confidential client — it is never stored and never returned again.
+ */
+export interface RegisteredClient {
+  clientId: string;
+  clientSecret?: string;
+  redirectUris: string[];
+  clientName: string | null;
+  tokenEndpointAuthMethod: TokenEndpointAuthMethod;
+  grantTypes: string[];
+  scopes: string[];
+}
+
+/** SHA-256 hex digest — the at-rest form of the client secret. */
+export function hashSecret(secret: string): string {
+  return createHash("sha256").update(secret).digest("hex");
+}
+
+/**
+ * Register an OAuth client under a generated `clientId`. For a confidential
+ * client a random secret is generated and its hash stored; the plaintext is
+ * returned once.
+ */
+export async function registerClient(
+  store: OAuthClientStore,
+  input: RegisterClientInput,
+): Promise<RegisteredClient> {
+  const clientId = randomUUID();
+  const authMethod: TokenEndpointAuthMethod = input.tokenEndpointAuthMethod ?? "none";
+  const grantTypes = input.grantTypes ?? [...DEFAULT_GRANT_TYPES];
+
+  // Only a confidential client gets a secret; a public PKCE client has none.
+  const clientSecret =
+    authMethod === "client_secret_basic"
+      ? randomBytes(CLIENT_SECRET_BYTES).toString("hex")
+      : undefined;
+
+  const row = await store.create({
+    clientId,
+    clientSecretHash: clientSecret ? hashSecret(clientSecret) : null,
+    redirectUris: input.redirectUris,
+    clientName: input.clientName ?? null,
+    tokenEndpointAuthMethod: authMethod,
+    grantTypes,
+    scopes: input.scopes,
+  });
+
+  return {
+    clientId: row.clientId,
+    ...(clientSecret ? { clientSecret } : {}),
+    redirectUris: row.redirectUris,
+    clientName: row.clientName,
+    tokenEndpointAuthMethod: row.tokenEndpointAuthMethod as TokenEndpointAuthMethod,
+    grantTypes: row.grantTypes,
+    scopes: row.scopes,
+  };
+}
+
+/**
+ * Open-redirect guard: a redirect target is accepted ONLY when it EXACTLY equals a
+ * registered `redirect_uri`. No normalization, no prefix, no trailing-slash
+ * leniency — an intercepted authorization request must not be steerable to any URI
+ * the client did not register.
+ */
+export function matchesRedirectUri(
+  client: Pick<StoredOAuthClient, "redirectUris">,
+  redirectUri: string,
+): boolean {
+  if (!redirectUri) return false;
+  return client.redirectUris.includes(redirectUri);
+}
+
+/**
+ * Provider attribution rules: the canonical root domains that own each host's
+ * OAuth callback. A redirect host matches a root only as the exact domain or a
+ * real (dot-guarded) subdomain — never a suffix, so `evilchatgpt.com` never
+ * matches `chatgpt.com`.
+ */
+export interface ProviderAttributionRule {
+  roots: readonly string[];
+  provider: string;
+}
+
+/** future-pay's rules, and a sane default for any host talking to the same two. */
+export const DEFAULT_PROVIDER_ROOTS: readonly ProviderAttributionRule[] = [
+  { roots: ["claude.ai", "anthropic.com"], provider: "claude" },
+  { roots: ["chatgpt.com", "openai.com"], provider: "chatgpt" },
+];
+
+/** Whether `host` is exactly `root` or a real subdomain of it (dot-guarded). */
+function hostMatchesRoot(host: string, root: string): boolean {
+  return host === root || host.endsWith(`.${root}`);
+}
+
+/**
+ * Best-effort provider attribution from a client's redirect URIs: the host that
+ * owns the callback (`claude.ai` → claude, `chatgpt.com` → chatgpt). Returns
+ * `null` when nothing matches — the UI then falls back to what the owner
+ * completed the flow with, and a self-report (the `announce` path) can attribute
+ * it later.
+ */
+export function providerFromRedirectUris(
+  redirectUris: readonly string[],
+  rules: readonly ProviderAttributionRule[] = DEFAULT_PROVIDER_ROOTS,
+): string | null {
+  for (const uri of redirectUris) {
+    let host: string;
+    try {
+      host = new URL(uri).host.toLowerCase();
+    } catch {
+      continue;
+    }
+    const match = rules.find((rule) => rule.roots.some((root) => hostMatchesRoot(host, root)));
+    if (match) return match.provider;
+  }
+  return null;
+}

package/src/oauth/code-replay.ts

@@ -0,0 +1,51 @@
+/**
+ * Single-use guard for the stateless authorization codes (12-23, ported from
+ * future-pay's `lib/mcp/oauth/token-replay.ts`).
+ *
+ * A code is a signed blob with a `jti`, so "already redeemed" has to be remembered
+ * somewhere. The in-process option remembers it IN THIS PROCESS: a small map of
+ * `jti → expiry`, self-pruning once the code that carried it would have expired
+ * anyway, so the set never grows without bound.
+ *
+ * ⚠️ MULTI-INSTANCE LIMITATION (best-effort single-use): that map lives in ONE
+ * process. On a horizontally-scaled deployment a code could be replayed against a
+ * second instance that has not yet seen the `jti`, within the ≤60s code lifetime.
+ * Single-use is therefore strictly guaranteed only on a SINGLE instance — which is
+ * why choosing it is explicit and cannot happen by omission: `codeReplay` has no
+ * default, so a host either names a shared store or types `'in-process'`. BEFORE
+ * running this surface on more than one instance, pass a `codeReplay` store backed
+ * by something shared and atomic — a short-TTL row with a unique constraint, or a
+ * distributed cache with an atomic set-if-absent. The port exists precisely so
+ * that is a config change rather than a patch to the grant handler.
+ */
+
+export interface CodeReplayStore {
+  /**
+   * Record a code's `jti` as consumed. `false` means it was ALREADY recorded (a
+   * replay); `true` is the first redemption. Must be atomic to be a real guard.
+   */
+  consume(jti: string, nowMs: number): Promise<boolean> | boolean;
+}
+
+/** Retain slightly beyond the 60s code TTL to cover the verify clock tolerance. */
+const RETENTION_MS = 90_000;
+
+/**
+ * The in-process store — correct on ONE instance, see the caveat above. Reached by
+ * passing `codeReplay: 'in-process'`, which is a required acknowledgement rather
+ * than a default: the config has no default for this field precisely because the
+ * only possible one would fail open on a multi-pod deployment.
+ */
+export function inProcessCodeReplayStore(): CodeReplayStore {
+  const usedJtis = new Map<string, number>();
+  return {
+    consume(jti: string, nowMs: number): boolean {
+      for (const [seen, expiresAt] of usedJtis) {
+        if (expiresAt <= nowMs) usedJtis.delete(seen);
+      }
+      if (usedJtis.has(jti)) return false;
+      usedJtis.set(jti, nowMs + RETENTION_MS);
+      return true;
+    },
+  };
+}