@12-apps/mcp 1.19.0 → 1.20.0

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

package/src/oauth/index.ts

@@ -0,0 +1,117 @@
+/**
+ * `@12-apps/mcp/oauth` — the OAuth 2.1 authorization server behind an MCP surface
+ * (12-23): register / authorize / token, the JWKS, and the two `.well-known`
+ * discovery documents, plus the primitives under them (stateless codes, ES256
+ * access tokens, PKCE, hashed rotating refresh tokens with replay revocation).
+ *
+ * Its own subpath because this half is Node-only — `jose`, `node:crypto` — and the
+ * package root is also imported by browsers through `@12-apps/mcp/react`. A barrel
+ * is evaluated whole by Node's ESM loader, so mixing the two would drag key
+ * material handling into a bundle that has no business with it.
+ */
+export {
+  createApiMcpOauth,
+  type ApiMcpOauth,
+  type McpOauthHandlers,
+  type McpOauthRoute,
+} from "./create-api-mcp-oauth";
+export {
+  DEFAULT_OAUTH_PATHS,
+  resolveMcpOauthConfig,
+  type McpConnectionRecording,
+  type McpOauthConfig,
+  type McpOauthContext,
+  type McpOauthPaths,
+  type McpOauthSession,
+} from "./context";
+export {
+  DEFAULT_MCP_RESOURCE_PATH,
+  MCP_SUPPORTED_SCOPES,
+  issuer,
+  originFromRequest,
+  resolveTrustedOrigin,
+  resourceAudience,
+  trustedOriginsFromEnv,
+  type McpScope,
+} from "./config";
+export {
+  ACCESS_TOKEN_TTL_SECONDS,
+  AccessTokenError,
+  signAccessToken,
+  verifyAccessToken,
+  type AccessTokenErrorCode,
+  type SignAccessTokenInput,
+  type VerifiedAccessToken,
+  type VerifyAccessTokenOptions,
+} from "./access-token";
+export {
+  AUTHORIZATION_CODE_AUDIENCE,
+  AUTHORIZATION_CODE_TTL_SECONDS,
+  AuthorizationCodeError,
+  mintCode,
+  verifyCode,
+  type AuthorizationCodeErrorCode,
+  type MintCodeInput,
+  type VerifiedAuthorizationCode,
+  type VerifyCodeOptions,
+} from "./authorization-code";
+export {
+  SUPPORTED_CHALLENGE_METHOD,
+  UnsupportedChallengeMethodError,
+  computeChallenge,
+  verifyChallenge,
+  type CodeChallengeMethod,
+} from "./pkce";
+export {
+  DEFAULT_SIGNING_KEY_ENV,
+  DEFAULT_SIGNING_KEY_ID_ENV,
+  SIGNING_ALG,
+  loadSigningKeyFromEnv,
+  signingKeyProvider,
+  type McpSigningKey,
+  type McpSigningKeyProvider,
+  type PublicSigningJwk,
+} from "./keys";
+export {
+  DEFAULT_PROVIDER_ROOTS,
+  hashSecret,
+  matchesRedirectUri,
+  providerFromRedirectUris,
+  registerClient,
+  type ProviderAttributionRule,
+  type RegisterClientInput,
+  type RegisteredClient,
+} from "./clients";
+export {
+  REFRESH_TOKEN_TTL_MS,
+  RefreshTokenError,
+  getRefreshTokenIdentity,
+  hashToken,
+  issueRefreshToken,
+  rotateRefreshToken,
+  type IssuedRefreshToken,
+  type RefreshTokenContext,
+  type RefreshTokenErrorCode,
+  type RefreshTokenIdentity,
+} from "./refresh";
+export {
+  inProcessCodeReplayStore,
+  type CodeReplayStore,
+} from "./code-replay";
+export {
+  createPrismaMcpStores,
+  type McpOauthPrisma,
+  type McpOauthPrismaProvider,
+} from "./prisma-stores";
+export type {
+  McpConnectionStore,
+  McpOauthStores,
+  NewOAuthClient,
+  NewRefreshToken,
+  OAuthClientStore,
+  RefreshTokenStore,
+  StoredMcpConnection,
+  StoredOAuthClient,
+  StoredRefreshToken,
+  TokenEndpointAuthMethod,
+} from "./stores";

package/src/oauth/keys.ts

@@ -0,0 +1,107 @@
+import { exportJWK, importPKCS8, type CryptoKey, type JWK } from "jose";
+
+/**
+ * Signing-key / JWK loading for the OAuth authorization server (12-23, ported
+ * from future-pay's `lib/mcp/oauth/keys.ts`).
+ *
+ * ES256 (P-256) from PEM material, the published public JWK (with `kid` for
+ * rotation), and a safe-by-default absence signal (`null`) when no key is
+ * configured — callers then refuse to issue tokens and serve the JWKS as 503
+ * rather than falling back to a weaker mode while the surface is mounted.
+ *
+ * WHERE the PEM comes from is the host's business: `loadSigningKeyFromEnv` keeps
+ * future-pay's env-var wiring, and any other provider (a secrets manager, a KMS
+ * export) satisfies the same `McpSigningKeyProvider` shape.
+ */
+
+/** JWS algorithm for the signing key pair (asymmetric, self-validated via JWKS). */
+export const SIGNING_ALG = "ES256";
+
+/** A public JWK safe to publish at the JWKS endpoint (never carries `d`). */
+export interface PublicSigningJwk extends JWK {
+  kid: string;
+  kty: "EC";
+  crv: "P-256";
+  alg: typeof SIGNING_ALG;
+  use: "sig";
+}
+
+/** The loaded signing material: the private key for signing + its public JWK. */
+export interface McpSigningKey {
+  privateKey: CryptoKey;
+  publicJwk: PublicSigningJwk;
+  kid: string;
+}
+
+/**
+ * How the surface obtains signing material. Returning `null` means "not
+ * provisioned": the AS then mints nothing and the JWKS answers 503.
+ */
+export type McpSigningKeyProvider = () => Promise<McpSigningKey | null>;
+
+async function parseSigningKey(pem: string, kid: string): Promise<McpSigningKey> {
+  // `extractable: true` is required so `exportJWK` can derive the public JWK;
+  // jose imports keys as non-extractable by default, which blocks the export.
+  const privateKey = await importPKCS8(pem, SIGNING_ALG, { extractable: true });
+  const jwk = await exportJWK(privateKey);
+  // Strip the private component; publish only the public half.
+  const { d: _private, ...publicHalf } = jwk;
+  void _private;
+
+  const publicJwk: PublicSigningJwk = {
+    ...publicHalf,
+    kty: "EC",
+    crv: "P-256",
+    alg: SIGNING_ALG,
+    use: "sig",
+    kid,
+  };
+
+  return { privateKey, publicJwk, kid };
+}
+
+/**
+ * Build a provider over a PKCS#8 PEM + `kid` pair, with a per-process cache.
+ *
+ * Parsing PKCS#8 and exporting the JWK is pure for a given (pem, kid), so the
+ * promise is cached keyed on the material itself. A rotated key (different pem or
+ * kid) produces a different cache key and re-parses — the cache never masks a
+ * rotation.
+ *
+ * Rotation is BY `kid`: each key is published in the JWKS and selected by the
+ * `kid` header on issued JWTs, so publishing old + new during an overlap window
+ * lets both verify.
+ */
+export function signingKeyProvider(
+  read: () => { pem: string | undefined; kid: string | undefined },
+): McpSigningKeyProvider {
+  let cache: { key: string; promise: Promise<McpSigningKey> } | null = null;
+  return async () => {
+    const { pem, kid } = read();
+    if (!pem || !kid) return null;
+    const cacheKey = `${kid} ${pem}`;
+    if (cache?.key === cacheKey) return cache.promise;
+    const promise = parseSigningKey(pem, kid);
+    cache = { key: cacheKey, promise };
+    return promise;
+  };
+}
+
+/** Env var carrying the ES256 private key as a PKCS#8 PEM (future-pay's name). */
+export const DEFAULT_SIGNING_KEY_ENV = "MCP_OAUTH_SIGNING_KEY";
+/** Env var carrying the key id (`kid`) used to select the key during rotation. */
+export const DEFAULT_SIGNING_KEY_ID_ENV = "MCP_OAUTH_SIGNING_KEY_ID";
+
+/**
+ * The env-backed provider — future-pay's wiring, kept identical, with the
+ * variable names as arguments so the package states no host's vocabulary.
+ */
+export function loadSigningKeyFromEnv(
+  keyEnv: string = DEFAULT_SIGNING_KEY_ENV,
+  kidEnv: string = DEFAULT_SIGNING_KEY_ID_ENV,
+): McpSigningKeyProvider {
+  return signingKeyProvider(() => ({
+    pem: typeof process === "undefined" ? undefined : process.env?.[keyEnv],
+    kid: typeof process === "undefined" ? undefined : process.env?.[kidEnv],
+  }));
+}

package/src/oauth/pkce.ts

@@ -0,0 +1,93 @@
+/**
+ * PKCE (RFC 7636) S256 challenge helpers for the OAuth authorization server
+ * (12-23, ported verbatim from future-pay's `lib/mcp/oauth/pkce.ts`).
+ *
+ * OAuth 2.1 mandates the `S256` code-challenge method and forbids `plain`, so
+ * this module computes `BASE64URL(SHA-256(code_verifier))` and compares it to
+ * the stored `code_challenge` in constant time. The authorization endpoint
+ * binds a `code_challenge` into the stateless authorization code; the token
+ * endpoint calls {@link verifyChallenge} with the presented `code_verifier` to
+ * prove the redeeming client is the one that started the flow.
+ *
+ * `plain` is refused (throws {@link UnsupportedChallengeMethodError}) rather
+ * than silently accepted: `plain` offers no protection against an intercepted
+ * authorization code, which is the exact threat PKCE exists to close.
+ */
+
+/** The only PKCE method this server accepts (OAuth 2.1 requires S256). */
+export const SUPPORTED_CHALLENGE_METHOD = "S256";
+
+/**
+ * PKCE code-challenge methods, including the rejected legacy `plain`.
+ *
+ * @public exported because it is a parameter type of the exported
+ * {@link verifyChallenge}.
+ */
+export type CodeChallengeMethod = "S256" | "plain";
+
+/** Thrown when a caller supplies a challenge method other than `S256`. */
+export class UnsupportedChallengeMethodError extends Error {
+  readonly method: string;
+
+  constructor(method: string) {
+    super(
+      `unsupported code_challenge_method '${method}' — only ${SUPPORTED_CHALLENGE_METHOD} is allowed`,
+    );
+    this.name = "UnsupportedChallengeMethodError";
+    this.method = method;
+  }
+}
+
+/** Encode raw bytes as unpadded base64url (RFC 7636 challenge encoding). */
+function base64UrlEncode(bytes: Uint8Array): string {
+  // Buffer.toString("base64url") emits the URL-safe alphabet with no padding.
+  return Buffer.from(bytes).toString("base64url");
+}
+
+/**
+ * Compute the RFC 7636 S256 challenge for a `code_verifier`:
+ * `BASE64URL(SHA-256(ASCII(verifier)))`.
+ */
+export async function computeChallenge(verifier: string): Promise<string> {
+  const data = new TextEncoder().encode(verifier);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return base64UrlEncode(new Uint8Array(digest));
+}
+
+/**
+ * Constant-time string comparison over the base64url challenge bytes.
+ *
+ * Returns `false` immediately on a length mismatch (lengths are not secret);
+ * for equal-length inputs every byte is compared so the timing does not reveal
+ * how many leading characters matched.
+ */
+function constantTimeEquals(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+
+/**
+ * Verify a presented `code_verifier` against a stored `code_challenge`.
+ *
+ * Recomputes the S256 challenge from `verifier` and constant-time-compares it
+ * to `storedChallenge`. Returns `true` on a match, `false` on a mismatch (or an
+ * empty stored challenge). Any method other than `S256` throws
+ * {@link UnsupportedChallengeMethodError} — `plain` is never accepted.
+ */
+export async function verifyChallenge(
+  verifier: string,
+  storedChallenge: string,
+  method: CodeChallengeMethod | string = SUPPORTED_CHALLENGE_METHOD,
+): Promise<boolean> {
+  if (method !== SUPPORTED_CHALLENGE_METHOD) {
+    throw new UnsupportedChallengeMethodError(method);
+  }
+  if (!storedChallenge) return false;
+
+  const computed = await computeChallenge(verifier);
+  return constantTimeEquals(computed, storedChallenge);
+}