@12-apps/mcp 1.19.0 → 2.0.0

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

package/src/oauth/create-api-mcp-oauth.ts

@@ -0,0 +1,205 @@
+import { buildAuthorizationServerMetadata } from "../auth/authorization-server-metadata";
+import { buildProtectedResourceMetadata } from "../auth/resource-metadata";
+
+import { authorizeEndpoint } from "./authorize";
+import { issuer, resourceAudience } from "./config";
+import {
+  notFound,
+  resolveMcpOauthConfig,
+  type McpOauthConfig,
+  type McpOauthContext,
+} from "./context";
+import { registerEndpoint, registrationDisabled } from "./register";
+import { tokenEndpoint } from "./token-grants";
+import {
+  verifyAccessToken,
+  type VerifiedAccessToken,
+  type VerifyAccessTokenOptions,
+} from "./access-token";
+
+/**
+ * The OAuth 2.1 authorization server, as one mount (12-23).
+ *
+ * `@12-apps/mcp` shipped the OpenAPI→tools generator, the bearer proxy and the two
+ * discovery BUILDERS, and held zero authorization logic — which meant every new app
+ * still wrote the AS itself: ~1.5k LOC of authorize/token/register plus the code,
+ * token, PKCE, rotation and replay machinery under them. All of that is the
+ * surface's contract, not a host's, so it lives here.
+ *
+ * Routes are FRAMEWORK-NEUTRAL descriptors whose handler takes a Fetch `Request`
+ * and answers a Fetch `Response`. Unlike the report-builder-shaped surfaces there
+ * is no `{ data }` envelope to adapt: an OAuth response is a 302 with a `Location`,
+ * a form-encoded exchange answering RFC 6749 §5.1/§5.2 JSON, or an RFC 8414/9728
+ * document — shapes fixed by specification that a wrapper would only break. So the
+ * adapters are one line each, and a host with a file-per-route layout can export
+ * the named handlers directly:
+ *
+ *   export const GET = mcpOauth.handlers.authorize;      // app/api/oauth/authorize
+ *   export const POST = mcpOauth.handlers.token;         // app/api/oauth/token
+ *
+ * What stays the HOST's: the cookie session (`resolveSession`), where the data
+ * lives (`stores`), which origins are trusted, the operator gate, and its sign-in
+ * path. Everything else is the RFCs'.
+ */
+
+export interface McpOauthRoute {
+  method: "GET" | "POST";
+  /** Absolute path from the ORIGIN ROOT — `.well-known/*` cannot live under a prefix. */
+  path: string;
+  handle(request: Request): Promise<Response>;
+}
+
+export interface McpOauthHandlers {
+  /** `GET` — Authorization Code + PKCE, identity from the session only. */
+  authorize: (request: Request) => Promise<Response>;
+  /** `POST` — the two grants, form-encoded, RFC 6749 bodies. */
+  token: (request: Request) => Promise<Response>;
+  /** `POST` — RFC 7591 dynamic client registration (403 when the gate is off). */
+  register: (request: Request) => Promise<Response>;
+  /** `GET` — the public JWKS (503 while no key is provisioned). */
+  jwks: (request: Request) => Promise<Response>;
+  /** `GET` — RFC 8414 authorization-server metadata. */
+  authorizationServerMetadata: (request: Request) => Promise<Response>;
+  /** `GET` — RFC 9728 protected-resource metadata. */
+  protectedResourceMetadata: (request: Request) => Promise<Response>;
+}
+
+export interface ApiMcpOauth {
+  /** Every endpoint, in mount order. */
+  routes: McpOauthRoute[];
+  /** The same handlers by name, for a host whose router is its file tree. */
+  handlers: McpOauthHandlers;
+  /**
+   * Verify a bearer token the way THIS surface mints them — the resource server's
+   * half. Bound to the same signing key, resource path and trusted-origin
+   * resolution, which is what stops "minted for origin A, verified against origin
+   * B" from rejecting valid tokens.
+   */
+  verifyBearer: (
+    token: string,
+    request: Request,
+    options?: Omit<VerifyAccessTokenOptions, "origin" | "resourcePath">,
+  ) => Promise<VerifiedAccessToken>;
+  /** The resolved config, for a host that needs the same origin/audience answers. */
+  context: McpOauthContext;
+}
+
+/** JSON, with the status and cache policy each document wants. */
+function jsonResponse(
+  body: unknown,
+  status = 200,
+  headers: Record<string, string> = {},
+): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8", ...headers },
+  });
+}
+
+/**
+ * The public key set, or a 503.
+ *
+ * Safe-by-default: an unprovisioned AS answers 503 rather than an empty or
+ * partial key set, so a client never mistakes "no key yet" for "a usable key".
+ */
+async function jwksResponse(context: McpOauthContext): Promise<Response> {
+  const key = await context.signingKey();
+  if (!key) return jsonResponse({ error: "signing_key_unavailable" }, 503);
+  return jsonResponse({ keys: [key.publicJwk] }, 200, {
+    // Public, cacheable key set; hosts may cache it and re-fetch on a `kid` miss
+    // (rotation). A short max-age keeps the rotation overlap tight.
+    "cache-control": "public, max-age=300",
+  });
+}
+
+/** The two discovery documents, built from ONE origin and ONE scope source. */
+function discoveryHandlers(
+  context: McpOauthContext,
+): Pick<McpOauthHandlers, "authorizationServerMetadata" | "protectedResourceMetadata"> {
+  return {
+    authorizationServerMetadata: async (request) =>
+      jsonResponse(
+        buildAuthorizationServerMetadata({
+          issuer: issuer(context.originOf(request)),
+          scopesSupported: [...context.scopes],
+          // The RESOLVED paths, so what a connector reads before its first request
+          // is where the endpoints actually are.
+          paths: context.paths,
+        }),
+      ),
+    protectedResourceMetadata: async (request) => {
+      const origin = context.originOf(request);
+      return jsonResponse(
+        buildProtectedResourceMetadata({
+          resource: resourceAudience(origin, context.resourcePath),
+          authorizationServers: [issuer(origin)],
+          scopesSupported: [...context.scopes],
+        }),
+      );
+    },
+  };
+}
+
+/**
+ * Every endpoint, behind the operator gate.
+ *
+ * With the gate off the surface is INERT and answers 404, so a probe cannot tell
+ * a disabled AS from an app that has none. Registration is the one exception: it
+ * answers 403, because RFC 7591 has a code for "the endpoint is here, but
+ * registration is closed" and the documented static-client path is the answer.
+ */
+function buildHandlers(context: McpOauthContext): McpOauthHandlers {
+  const gated =
+    (handler: (request: Request) => Promise<Response>) =>
+    async (request: Request): Promise<Response> =>
+      context.enabled() ? handler(request) : notFound();
+  const discovery = discoveryHandlers(context);
+
+  return {
+    authorize: gated((request) => authorizeEndpoint(context, request)),
+    token: gated((request) => tokenEndpoint(context, request)),
+    register: async (request) =>
+      context.enabled() ? registerEndpoint(context, request) : registrationDisabled(),
+    jwks: gated(() => jwksResponse(context)),
+    authorizationServerMetadata: gated(discovery.authorizationServerMetadata),
+    protectedResourceMetadata: gated(discovery.protectedResourceMetadata),
+  };
+}
+
+/** Mount order, and the paths a host may have moved. */
+function buildRoutes(context: McpOauthContext, handlers: McpOauthHandlers): McpOauthRoute[] {
+  const { paths } = context;
+  return [
+    {
+      method: "GET",
+      path: paths.authorizationServerMetadata,
+      handle: handlers.authorizationServerMetadata,
+    },
+    {
+      method: "GET",
+      path: paths.protectedResourceMetadata,
+      handle: handlers.protectedResourceMetadata,
+    },
+    { method: "GET", path: paths.jwks, handle: handlers.jwks },
+    { method: "GET", path: paths.authorize, handle: handlers.authorize },
+    { method: "POST", path: paths.token, handle: handlers.token },
+    { method: "POST", path: paths.register, handle: handlers.register },
+  ];
+}
+
+export function createApiMcpOauth(config: McpOauthConfig): ApiMcpOauth {
+  const context = resolveMcpOauthConfig(config);
+  const handlers = buildHandlers(context);
+
+  return {
+    routes: buildRoutes(context, handlers),
+    handlers,
+    verifyBearer: (token, request, options) =>
+      verifyAccessToken(context.signingKey, token, {
+        ...options,
+        origin: context.originOf(request),
+        resourcePath: context.resourcePath,
+      }),
+    context,
+  };
+}