@12-apps/mcp 1.19.0 → 1.20.0

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;
+    },
+  };
+}

package/src/oauth/config.ts

@@ -0,0 +1,142 @@
+/**
+ * The OAuth 2.1 authorization-server foundation: the shared scope source, the
+ * issuer/audience derivation, and the trusted-origin resolver every URL in the
+ * surface is built from (12-23, ported from future-pay's
+ * `lib/mcp/oauth/config.ts`).
+ *
+ * Keeping the scopes and the origin resolution in ONE place is what stops the
+ * two discovery documents — RFC 8414 `/.well-known/oauth-authorization-server`
+ * and RFC 9728 `/.well-known/oauth-protected-resource` — from drifting apart,
+ * and what makes a token minted for an origin verify against that same origin.
+ *
+ * What was env-reading in the host is CONFIG here (the package must not learn a
+ * host's variable names); `trustedOriginsFromEnv` is the one-line helper that
+ * keeps future-pay's wiring identical.
+ */
+
+/** Scopes advertised by both discovery documents. `mcp:write` gates mutating tools. */
+export const MCP_SUPPORTED_SCOPES = ["mcp:read", "mcp:write"] as const;
+
+export type McpScope = (typeof MCP_SUPPORTED_SCOPES)[number];
+
+/** Path the MCP JSON-RPC endpoint is mounted at — the access token's audience. */
+export const DEFAULT_MCP_RESOURCE_PATH = "/api/mcp";
+
+/** The OAuth `iss` — the deployment origin, used verbatim. */
+export function issuer(origin: string): string {
+  return origin;
+}
+
+/** The access-token `aud` — the MCP resource URL (`${origin}${resourcePath}`). */
+export function resourceAudience(
+  origin: string,
+  resourcePath: string = DEFAULT_MCP_RESOURCE_PATH,
+): string {
+  return `${origin}${resourcePath}`;
+}
+
+/**
+ * A single bare `host` or `host:port` — no scheme, path, userinfo (`@`), or
+ * whitespace. A syntactic guard so a forwarded host cannot smuggle anything but
+ * a hostname; it does NOT by itself decide trust (the allowlist does).
+ */
+const HOST_ONLY =
+  /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?::\d{1,5})?$/i;
+
+/** ASCII `/`. */
+const SLASH = 0x2f;
+
+/**
+ * Strip trailing slashes by index, not by regex.
+ *
+ * `replace(/\/+$/, "")` is quadratic on a string of many slashes — the classic
+ * anchored-quantifier backtrack — and this function is reached from an operator's
+ * env var AND (through `resolveTrustedOrigin`) from values that arrive with a
+ * request. A backwards walk is linear and needs no reasoning about the engine.
+ */
+function stripTrailingSlashes(value: string): string {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === SLASH) end -= 1;
+  return value.slice(0, end);
+}
+
+/** Normalize an allowlist entry (trailing `/` stripped, blanks dropped). */
+function normalizeOrigins(origins: readonly string[]): string[] {
+  return origins.map((origin) => stripTrailingSlashes(origin.trim())).filter(Boolean);
+}
+
+/**
+ * Read a comma-separated allowlist out of an environment variable — future-pay
+ * passes `trustedOriginsFromEnv('MCP_OAUTH_TRUSTED_ORIGINS')`, so the behaviour
+ * is identical while the variable's NAME stays the host's.
+ */
+export function trustedOriginsFromEnv(name: string): string[] {
+  const raw = typeof process === "undefined" ? undefined : process.env?.[name];
+  return raw ? normalizeOrigins(raw.split(",")) : [];
+}
+
+/**
+ * The origin a request's forwarded headers CLAIM, or `null` when
+ * absent/malformed. Only the first hop of a comma-separated list is taken, the
+ * host must be a bare host[:port], and the proto is restricted to http/https.
+ * This is a claim to be checked against the allowlist — never trusted alone.
+ */
+function claimedForwardedOrigin(getHeader: (name: string) => string | null): string | null {
+  const host = getHeader("x-forwarded-host")?.split(",")[0]?.trim();
+  if (!host || !HOST_ONLY.test(host)) return null;
+  const proto = getHeader("x-forwarded-proto")?.split(",")[0]?.trim();
+  return `${proto === "http" ? "http" : "https"}://${host}`;
+}
+
+/**
+ * THE single trusted-origin resolver, shared by token ISSUANCE (the `iss`/`aud` a
+ * token is minted with) and bearer VERIFICATION (the expected `aud` a protected
+ * route checks). Because both sides pass the SAME request's headers, a token
+ * minted for the allowlisted origin verifies against that same origin — they
+ * cannot drift (e.g. mint `https://app.example.com` but verify
+ * `http://0.0.0.0:3000` and reject a valid token).
+ *
+ * The origin must NEVER be attacker-controllable. Behind a reverse proxy the
+ * server sees only its internal bind on `request.url`, so the public origin comes
+ * from the proxy's `X-Forwarded-Host` — but a forwarded host is honored ONLY when
+ * it is on the operator-configured allowlist; ANY other value (a spoofed/foreign
+ * host, or an absent header) resolves to the canonical (FIRST) allowlisted origin.
+ * So even if the edge forwards `X-Forwarded-Host: evil.example.com`, the origin
+ * stays the trusted one.
+ *
+ * With NO allowlist configured a forwarded host is NEVER trusted — a spoofed
+ * header must not be able to choose the issuer — so `fallbackOrigin` (the
+ * request's OWN origin) is used instead. A proxied deployment therefore REQUIRES
+ * the allowlist; until it is set the surface fails closed to the internal origin
+ * rather than a foreign one.
+ */
+export function resolveTrustedOrigin(
+  getHeader: (name: string) => string | null,
+  fallbackOrigin: string | undefined,
+  trustedOrigins: readonly string[] = [],
+): string | undefined {
+  const [canonical, ...rest] = normalizeOrigins(trustedOrigins);
+  // No allowlist → the forwarded host is untrusted; fall back to the request's
+  // own origin so a spoofed X-Forwarded-Host can never become the issuer.
+  if (!canonical) return fallbackOrigin;
+
+  const allowed = [canonical, ...rest];
+  const claimed = claimedForwardedOrigin(getHeader);
+  return claimed && allowed.includes(claimed) ? claimed : canonical;
+}
+
+/**
+ * The PUBLIC origin every URL in the surface derives from (issuer, endpoint URLs,
+ * access-token `iss`/`aud`). A thin wrapper over {@link resolveTrustedOrigin}
+ * bound to a `Request`, falling back to the request URL's origin when no
+ * allowlist is configured.
+ */
+export function originFromRequest(
+  request: Request,
+  trustedOrigins: readonly string[] = [],
+): string {
+  const fallback = new URL(request.url).origin;
+  return (
+    resolveTrustedOrigin((name) => request.headers.get(name), fallback, trustedOrigins) ?? fallback
+  );
+}

package/src/oauth/context.ts

@@ -0,0 +1,253 @@
+import {
+  DEFAULT_MCP_RESOURCE_PATH,
+  MCP_SUPPORTED_SCOPES,
+  originFromRequest,
+} from "./config";
+import {
+  inProcessCodeReplayStore,
+  type CodeReplayStore,
+} from "./code-replay";
+import { ACCESS_TOKEN_TTL_SECONDS } from "./access-token";
+import { REFRESH_TOKEN_TTL_MS } from "./refresh";
+import { loadSigningKeyFromEnv, type McpSigningKeyProvider } from "./keys";
+import type { ProviderAttributionRule } from "./clients";
+import type { McpOauthStores, StoredOAuthClient } from "./stores";
+
+/**
+ * The config seam of the authorization server, and its resolved form (12-23).
+ *
+ * Everything a HOST knows and the package cannot: who the signed-in caller is,
+ * where the data lives, which origins are trusted, whether the surface is turned
+ * on at all, and where its endpoints are mounted. Everything else — the RFC wire,
+ * PKCE, rotation, replay, the discovery documents — is the package's.
+ */
+
+/** The identity an authorize request binds a code to. From the SESSION only. */
+export interface McpOauthSession {
+  /**
+   * The OAuth subject (future-pay passes the Google `sub`, falling back to the
+   * email). Carried through every rotation so a refreshed token keeps the same
+   * stable `sub`.
+   */
+  subject: string;
+  /** The signed-in user's email — the identity the AS binds to. */
+  email: string;
+}
+
+/** Where each endpoint of the surface lives, from the origin root. */
+export interface McpOauthPaths {
+  authorize: string;
+  token: string;
+  register: string;
+  jwks: string;
+  authorizationServerMetadata: string;
+  protectedResourceMetadata: string;
+}
+
+export const DEFAULT_OAUTH_PATHS: McpOauthPaths = {
+  // future-pay's paths, and the ones the RFC 8414 document has always advertised.
+  authorize: "/api/oauth/authorize",
+  token: "/api/oauth/token",
+  register: "/api/oauth/register",
+  jwks: "/.well-known/jwks.json",
+  authorizationServerMetadata: "/.well-known/oauth-authorization-server",
+  protectedResourceMetadata: "/.well-known/oauth-protected-resource",
+};
+
+/** How a connection's liveness is recorded on a successful grant. */
+export interface McpConnectionRecording {
+  /**
+   * The host's DB user id for a token's email, or `null` when there is no user row
+   * yet (recording is then skipped — email is the identity, not the id).
+   */
+  resolveUserId: (email: string) => Promise<string | null> | string | null;
+  /** Provider attribution rules; defaults to claude/chatgpt roots. */
+  providerRules?: readonly ProviderAttributionRule[];
+  /** Don't rewrite on every grant — refresh liveness at most this often. */
+  activityThrottleMs?: number;
+}
+
+export interface McpOauthConfig {
+  /** Where the three owned tables live (see `./stores.ts`). */
+  stores: McpOauthStores;
+  /**
+   * Resolve the caller's COOKIE SESSION for the authorize endpoint. `null` sends
+   * the caller through the host's sign-in flow; no code is ever minted for an
+   * unauthenticated request, and a client can never supply the identity itself.
+   */
+  resolveSession: (request: Request) => Promise<McpOauthSession | null> | McpOauthSession | null;
+  /**
+   * The operator gate. `false` makes the whole surface inert — authorize/token/jwks
+   * answer 404 and registration answers 403 — which is how future-pay ships it OFF
+   * by default (`MCP_BEARER_ENABLED`). Default: enabled (mounting is the opt-in).
+   */
+  enabled?: boolean | (() => boolean);
+  /**
+   * Signing material. Default: the env-backed provider with future-pay's variable
+   * names. `null` from the provider means "not provisioned": nothing is minted and
+   * the JWKS answers 503 rather than falling back to a weaker mode.
+   */
+  signingKey?: McpSigningKeyProvider;
+  /**
+   * The trusted PUBLIC origin allowlist — REQUIRED behind a reverse proxy, where
+   * the server sees only its internal bind. The FIRST entry is canonical. With
+   * none configured a forwarded host is never trusted (see `resolveTrustedOrigin`).
+   */
+  trustedOrigins?: readonly string[];
+  /** Scopes the AS advertises and validates against. Default `mcp:read mcp:write`. */
+  scopes?: readonly string[];
+  /** Where the MCP resource is mounted — the token audience. Default `/api/mcp`. */
+  resourcePath?: string;
+  /** Endpoint paths, if the host mounts them somewhere else. */
+  paths?: Partial<McpOauthPaths>;
+  /** Where an unauthenticated authorize request is sent. Default `/login`. */
+  loginPath?: string;
+  /**
+   * The query parameter carrying the post-login return path. Default
+   * `callbackUrl` (Auth.js's name).
+   */
+  loginCallbackParam?: string;
+  accessTokenTtlSeconds?: number;
+  refreshTokenTtlMs?: number;
+  /**
+   * The single-use guard for authorization codes — REQUIRED, and required on
+   * purpose. Pass a shared atomic store, or the literal `'in-process'` to accept
+   * the single-instance limitation explicitly.
+   *
+   * There is deliberately NO default, because a default here would be the only one
+   * in this config that fails OPEN. Every other one fails closed: no signing key
+   * mints nothing and answers JWKS 503; `enabled: false` is 404 everywhere; an
+   * empty `trustedOrigins` never trusts a forwarded host. An in-process default
+   * instead silently permits cross-instance code replay — against an OAuth 2.1
+   * MUST, on the very deployment shape a reusable package exists for (two pods
+   * behind one load balancer), with nothing in the types to notice. Scaling out
+   * must not be able to weaken the guard without somebody having typed something.
+   */
+  codeReplay: CodeReplayStore | "in-process";
+  /**
+   * Approve an authorize request before a code is minted — the CONSENT step.
+   *
+   * Registration is open whenever `enabled` is true (RFC 7591), so without an
+   * approval step anyone may register a client carrying their OWN redirect URI and
+   * their OWN scope ceiling, send a signed-in admin one link, and have the endpoint
+   * mint them a code with no interaction: the redirect URI is exact-matched against
+   * the attacker's own registration and the scope ceiling is the attacker's too, so
+   * every other guard here holds and none of them helps.
+   *
+   * Until a host supplies this, `authorize` REFUSES any client it cannot see the
+   * operator behind — i.e. any client not named in {@link preApprovedClientIds}.
+   * Return `false` to deny (the caller gets an `access_denied` redirect, exactly as
+   * a human refusal would).
+   */
+  resolveApproval?: (
+    request: Request,
+    client: StoredOAuthClient,
+    scopes: readonly string[],
+  ) => Promise<boolean> | boolean;
+  /**
+   * Client ids the OPERATOR registered, exempt from the approval gate above — the
+   * escape hatch for a host that ships its own first-party clients and has no
+   * consent screen to offer. Anything NOT listed here is treated as dynamically
+   * registered, i.e. as attacker-controllable.
+   */
+  preApprovedClientIds?: readonly string[];
+  /** Liveness recording on a grant; omit to record nothing. */
+  connections?: McpConnectionRecording;
+}
+
+/** The config with every default applied — what the handlers actually read. */
+export interface McpOauthContext {
+  stores: McpOauthStores;
+  resolveSession: McpOauthConfig["resolveSession"];
+  enabled: () => boolean;
+  signingKey: McpSigningKeyProvider;
+  trustedOrigins: readonly string[];
+  scopes: readonly string[];
+  resourcePath: string;
+  paths: McpOauthPaths;
+  loginPath: string;
+  loginCallbackParam: string;
+  accessTokenTtlSeconds: number;
+  refreshTokenTtlMs: number;
+  codeReplay: CodeReplayStore;
+  /**
+   * The resolved consent decision for one authorize request. Always present: with
+   * no host seam it refuses every client the operator did not pre-approve, so the
+   * handler has no "unset" case to forget.
+   */
+  approve: (
+    request: Request,
+    client: StoredOAuthClient,
+    scopes: readonly string[],
+  ) => Promise<boolean>;
+  connections?: McpConnectionRecording;
+  /** The trusted public origin for THIS request (issuance and verification agree). */
+  originOf: (request: Request) => string;
+}
+
+/** The surface's own shape: what it advertises, where it lives, how long it lasts. */
+function resolveSurface(
+  config: McpOauthConfig,
+): Pick<
+  McpOauthContext,
+  | "scopes"
+  | "resourcePath"
+  | "paths"
+  | "loginPath"
+  | "loginCallbackParam"
+  | "accessTokenTtlSeconds"
+  | "refreshTokenTtlMs"
+> {
+  return {
+    scopes: config.scopes ?? [...MCP_SUPPORTED_SCOPES],
+    resourcePath: config.resourcePath ?? DEFAULT_MCP_RESOURCE_PATH,
+    paths: { ...DEFAULT_OAUTH_PATHS, ...config.paths },
+    loginPath: config.loginPath ?? "/login",
+    loginCallbackParam: config.loginCallbackParam ?? "callbackUrl",
+    accessTokenTtlSeconds: config.accessTokenTtlSeconds ?? ACCESS_TOKEN_TTL_SECONDS,
+    refreshTokenTtlMs: config.refreshTokenTtlMs ?? REFRESH_TOKEN_TTL_MS,
+  };
+}
+
+export function resolveMcpOauthConfig(config: McpOauthConfig): McpOauthContext {
+  const enabled = config.enabled ?? true;
+  const trustedOrigins = config.trustedOrigins ?? [];
+  return {
+    stores: config.stores,
+    resolveSession: config.resolveSession,
+    // Mounting is the opt-in, so the gate defaults to ON; a host that ships the
+    // surface dark passes its own flag (future-pay: `MCP_BEARER_ENABLED`).
+    enabled: typeof enabled === "function" ? enabled : () => enabled,
+    // `null` from the provider means "not provisioned": nothing is minted and the
+    // JWKS answers 503 rather than falling back to a weaker mode.
+    signingKey: config.signingKey ?? loadSigningKeyFromEnv(),
+    trustedOrigins,
+    ...resolveSurface(config),
+    // `'in-process'` is an ACKNOWLEDGEMENT, not a default — see the field's docs.
+    codeReplay:
+      config.codeReplay === "in-process" ? inProcessCodeReplayStore() : config.codeReplay,
+    approve: resolveApprover(config),
+    ...(config.connections ? { connections: config.connections } : {}),
+    originOf: (request) => originFromRequest(request, trustedOrigins),
+  };
+}
+
+/**
+ * The consent decision, resolved once. A host seam wins; otherwise only a client
+ * the OPERATOR named may proceed, so an open registration endpoint cannot mint a
+ * code for a client nobody approved.
+ */
+function resolveApprover(config: McpOauthConfig): McpOauthContext["approve"] {
+  const preApproved = new Set(config.preApprovedClientIds ?? []);
+  const { resolveApproval } = config;
+  return async (request, client, scopes) => {
+    if (preApproved.has(client.clientId)) return true;
+    if (!resolveApproval) return false;
+    return resolveApproval(request, client, scopes);
+  };
+}
+
+/** The gate's own answer: 404, so a disabled surface looks like no surface. */
+export function notFound(): Response {
+  return new Response("Not Found", { status: 404 });
+}