@12-apps/mcp 1.18.0 → 1.20.0

package/src/index.ts

@@ -73,4 +73,5 @@ export {
   buildAuthorizationServerMetadata,
   type AuthorizationServerMetadata,
   type AuthorizationServerMetadataInput,
+  type AuthorizationServerPaths,
 } from "./auth/authorization-server-metadata";

package/src/oauth/access-token.ts

@@ -0,0 +1,186 @@
+import { SignJWT, jwtVerify, importJWK, type JWTPayload } from "jose";
+
+import { issuer, resourceAudience, DEFAULT_MCP_RESOURCE_PATH, type McpScope } from "./config";
+import { SIGNING_ALG, type McpSigningKeyProvider } from "./keys";
+
+/**
+ * JWT access-token issuer + verifier (12-23, ported from future-pay's
+ * `lib/mcp/oauth/jwt.ts` — behaviour unchanged; the signing key arrives through a
+ * provider and the resource path is config).
+ *
+ * The access token is a short-lived, ES256-signed JWT bound to the signed-in
+ * user. It carries the claims the resource server checks LOCALLY against the
+ * published JWKS (no introspection round-trip): `iss` (the issuer origin), `aud`
+ * (`${origin}${resourcePath}`), `sub`, `email`, `scope` (space-delimited), `iat`,
+ * `exp` (short TTL), and `jti`; the JWT header carries `kid` so the verifier can
+ * select the public key during rotation.
+ *
+ * Failures are typed so the caller maps them to the right OAuth challenge
+ * (`invalid_token` vs `insufficient_scope`).
+ */
+
+/** Access-token lifetime — short-lived (15 min) per the spec. */
+export const ACCESS_TOKEN_TTL_SECONDS = 15 * 60;
+
+/** Clock skew tolerated on `exp`/`iat` validation, in seconds. */
+const CLOCK_TOLERANCE_SECONDS = 5;
+
+/** The identity a verified access token resolves to. */
+export interface VerifiedAccessToken {
+  email: string;
+  subject: string;
+  scopes: string[];
+}
+
+/** Distinct verification failure reasons the caller maps to OAuth challenges. */
+export type AccessTokenErrorCode = "invalid_token" | "insufficient_scope";
+
+/** A typed verification failure — `code` drives the `WWW-Authenticate` challenge. */
+export class AccessTokenError extends Error {
+  readonly code: AccessTokenErrorCode;
+
+  constructor(code: AccessTokenErrorCode, message?: string) {
+    super(message ?? code);
+    this.name = "AccessTokenError";
+    this.code = code;
+  }
+}
+
+/** Inputs bound into a minted access token. */
+export interface SignAccessTokenInput {
+  email: string;
+  subject: string;
+  scopes: readonly McpScope[] | readonly string[];
+  origin: string;
+  /** Where the MCP resource is mounted. Default `/api/mcp`. */
+  resourcePath?: string;
+  /** Token lifetime in seconds. Default 15 minutes. */
+  ttlSeconds?: number;
+}
+
+/** Deterministic-clock option shared by mint + verify. */
+interface ClockOption {
+  /** Epoch milliseconds; defaults to `Date.now()`. Injected for deterministic tests. */
+  now?: number;
+}
+
+/** The full access-token claim set (beyond the registered JWT claims). */
+interface AccessTokenClaims extends JWTPayload {
+  email: string;
+  scope: string;
+}
+
+function nowSeconds(now?: number): number {
+  return Math.floor((now ?? Date.now()) / 1000);
+}
+
+/**
+ * Mint an ES256-signed access token bound to the user.
+ *
+ * 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 from the loaded key so the verifier can resolve the public JWK during
+ * rotation.
+ */
+export async function signAccessToken(
+  loadSigningKey: McpSigningKeyProvider,
+  input: SignAccessTokenInput,
+  options?: ClockOption,
+): Promise<string | null> {
+  const key = await loadSigningKey();
+  if (!key) return null;
+
+  const iat = nowSeconds(options?.now);
+  const exp = iat + (input.ttlSeconds ?? ACCESS_TOKEN_TTL_SECONDS);
+  const scope = input.scopes.join(" ");
+
+  return new SignJWT({ email: input.email, scope } satisfies AccessTokenClaims)
+    .setProtectedHeader({ alg: SIGNING_ALG, kid: key.kid })
+    .setIssuer(issuer(input.origin))
+    .setAudience(resourceAudience(input.origin, input.resourcePath ?? DEFAULT_MCP_RESOURCE_PATH))
+    .setSubject(input.subject)
+    .setIssuedAt(iat)
+    .setExpirationTime(exp)
+    .setJti(crypto.randomUUID())
+    .sign(key.privateKey);
+}
+
+/** Options for {@link verifyAccessToken}. */
+export interface VerifyAccessTokenOptions extends ClockOption {
+  /** The deployment origin — derives the expected `iss` and `aud`. */
+  origin: string;
+  /** Where the MCP resource is mounted. Default `/api/mcp`. */
+  resourcePath?: string;
+  /** When set, the token must carry this scope or verification fails `insufficient_scope`. */
+  requiredScope?: McpScope | string;
+}
+
+/** Parse the space-delimited `scope` claim into a de-duplicated string array. */
+function parseScopes(scope: unknown): string[] {
+  if (typeof scope !== "string" || scope.trim() === "") return [];
+  return [...new Set(scope.trim().split(/\s+/))];
+}
+
+/**
+ * Verify a bearer access token locally against the published JWKS public key.
+ *
+ * Checks signature (via the public JWK selected by the token's `kid`), `iss`,
+ * `aud`, and `exp`. When `requiredScope` is supplied, also enforces scope. On
+ * success returns `{ email, subject, scopes }`; on failure throws an
+ * {@link AccessTokenError} whose `code` distinguishes `invalid_token` (bad
+ * signature / wrong issuer / wrong audience / expired / malformed / unconfigured
+ * key) from `insufficient_scope` (a valid token lacking the required scope).
+ */
+/**
+ * The cryptographic half: signature, `iss`, `aud`, `exp`.
+ *
+ * Every jose failure — bad signature, wrong issuer, wrong audience, expiry,
+ * malformed token, unknown key — collapses into ONE opaque `invalid_token`. A
+ * message naming the failed claim would be an oracle for the next attempt.
+ */
+async function verifiedPayload(
+  loadSigningKey: McpSigningKeyProvider,
+  token: string,
+  options: VerifyAccessTokenOptions,
+): Promise<JWTPayload> {
+  const key = await loadSigningKey();
+  // No signing key configured → nothing can verify (safe-by-default).
+  if (!key) throw new AccessTokenError("invalid_token", "no signing key configured");
+
+  try {
+    const { payload } = await jwtVerify(token, await importJWK(key.publicJwk, SIGNING_ALG), {
+      algorithms: [SIGNING_ALG],
+      issuer: issuer(options.origin),
+      audience: resourceAudience(options.origin, options.resourcePath ?? DEFAULT_MCP_RESOURCE_PATH),
+      clockTolerance: CLOCK_TOLERANCE_SECONDS,
+      currentDate: options.now === undefined ? undefined : new Date(options.now),
+    });
+    return payload;
+  } catch {
+    throw new AccessTokenError("invalid_token", "token verification failed");
+  }
+}
+
+export async function verifyAccessToken(
+  loadSigningKey: McpSigningKeyProvider,
+  token: string,
+  options: VerifyAccessTokenOptions,
+): Promise<VerifiedAccessToken> {
+  const payload = await verifiedPayload(loadSigningKey, token, options);
+
+  const email = typeof payload.email === "string" ? payload.email : null;
+  const subject = typeof payload.sub === "string" ? payload.sub : null;
+  if (!email || !subject) {
+    throw new AccessTokenError("invalid_token", "missing subject or email claim");
+  }
+
+  const scopes = parseScopes(payload.scope);
+  if (options.requiredScope && !scopes.includes(options.requiredScope)) {
+    throw new AccessTokenError(
+      "insufficient_scope",
+      `token lacks required scope '${options.requiredScope}'`,
+    );
+  }
+
+  return { email, subject, scopes };
+}

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