@specific.dev/spectest 0.55.0 → 0.56.1

package/src/mcp-auth.ts

@@ -0,0 +1,626 @@
+// OAuth 2.1 for the MCP client (`mcp.ts`).
+//
+// An MCP server is an OAuth *resource server*. It rejects an unauthorized
+// request with `401` and a `WWW-Authenticate` header, and that header is
+// the entry point of this file. From there the flow is:
+//
+//   1. Read the protected-resource metadata (RFC 9728). It names the
+//      authorization server and the canonical `resource` identifier.
+//   2. Read the authorization-server metadata (RFC 8414). Note the
+//      path-insertion rule: an issuer with a path is discovered at
+//      `https://host/.well-known/oauth-authorization-server/<path>`, not
+//      at `<issuer>/.well-known/...`.
+//   3. Register the client dynamically (RFC 7591) when the server offers
+//      it. This is also what lets us declare a redirect URI on a port we
+//      only chose a moment ago.
+//   4. Authorization code with PKCE (S256, mandatory) and the `resource`
+//      parameter (RFC 8707, required by MCP — it binds the token to this
+//      one server).
+//   5. Exchange the code, then refresh the token when it expires.
+//
+// The SDK owns all of that. It does NOT own the browser. A test drives the
+// login and the consent screen itself, because that screen belongs to the
+// application under test and a framework that clicks it by guesswork turns
+// a broken consent page into a passing test. See `mcp.ts` for the seam.
+//
+// WHY LOOPBACK. The default redirect URI is `http://127.0.0.1:<port>/callback`
+// on an ephemeral port. That is what a desktop MCP client does — it is
+// OAuth 2.0 for Native Apps (RFC 8252 §7.3), and §8.3 prefers the IP
+// literal over the name `localhost`. It works here because Chromium is the
+// guest's own browser, in the same VM and the same network namespace as
+// this daemon, so the browser's loopback IS our loopback. The
+// authorization server never touches the address: a redirect is a browser
+// navigation, not a server-to-server call.
+//
+// LANDMINE — GoTrue (Supabase Auth) refuses a plain-http redirect URI
+// unless it is localhost, and it recognises the NAME. So a Supabase-backed
+// project must use `localhost`, not `127.0.0.1`. `loopbackHost()` below
+// keeps the RFC's preference as the default and the name as the documented
+// override; do not "correct" one into the other without testing both.
+
+import { secureRandomBytes } from "./ids.js";
+import { rawFetch } from "./harness/raw-fetch.js";
+import { createHash } from "node:crypto";
+
+/** The redirect host. RFC 8252 §8.3 prefers the IP literal. Some
+ *  authorization servers only special-case the name — see the landmine at
+ *  the top of this file. */
+export type LoopbackHost = "127.0.0.1" | "localhost";
+
+/** Protected-resource metadata (RFC 9728), the subset MCP uses. */
+export interface ProtectedResourceMetadata {
+  resource?: string;
+  authorization_servers?: string[];
+  scopes_supported?: string[];
+  bearer_methods_supported?: string[];
+}
+
+/** Authorization-server metadata (RFC 8414), the subset we need. */
+export interface AuthServerMetadata {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  registration_endpoint?: string;
+  scopes_supported?: string[];
+  code_challenge_methods_supported?: string[];
+  grant_types_supported?: string[];
+}
+
+/** What the client ended up with. Handed to the test, so it can assert on
+ *  the grant and reuse the token elsewhere. */
+export interface McpIdentity {
+  /** The bearer token. Redacted in every recorded event, never in this
+   *  value — a test may need it to call the same API directly. */
+  accessToken: string;
+  refreshToken?: string;
+  tokenType: string;
+  /** What the server GRANTED, which is not always what was asked for. */
+  scopes: string[];
+  /** The RFC 8707 resource the token is bound to. */
+  resource?: string;
+  clientId: string;
+  issuer: string;
+  /** The redirect URI this grant was issued for. Kept so a test can prove
+   *  which kind of client it just was — a loopback one, by default. */
+  redirectUri: string;
+  /** Where to spend the refresh token. Carried on the identity because a
+   *  refresh usually happens in a forked test that never ran discovery,
+   *  and an issuer's token endpoint is not derivable from its URL. */
+  tokenEndpoint: string;
+  /** Epoch milliseconds, when the server reported `expires_in`. */
+  expiresAt?: number;
+}
+
+/** The user (or the authorization server) refused the grant. */
+export class McpAuthDeniedError extends Error {
+  readonly code: string;
+  readonly description?: string;
+
+  constructor(code: string, description?: string) {
+    super(`authorization denied: ${code}${description ? ` — ${description}` : ""}`);
+    this.name = "McpAuthDeniedError";
+    this.code = code;
+    this.description = description;
+  }
+}
+
+export interface AuthorizeOptions {
+  /** Skip dynamic registration and use a pre-registered client. */
+  clientId?: string;
+  /** For a confidential client. Sent with the token request. */
+  clientSecret?: string;
+  /**
+   * Use this redirect URI instead of a loopback listener. Nothing is
+   * served for it — the browser lands somewhere this daemon does not own,
+   * so the test must hand the landed URL back:
+   * `await auth.complete({ url: page.url() })`.
+   */
+  redirectUri?: string;
+  /**
+   * Escape hatch. Scopes normally come from the protected-resource
+   * metadata, because that is what a real MCP client does — it does not
+   * ask its user which scopes to request. Set this only for a server that
+   * advertises none and still demands one.
+   */
+  scopes?: string[];
+  /** Client name presented at dynamic registration and, usually, on the
+   *  consent screen. */
+  clientName?: string;
+  /** Override the RFC 8707 resource. Defaults to the metadata's
+   *  `resource`, else the MCP server URL. */
+  resource?: string;
+  /** Which loopback host to register. Defaults to `127.0.0.1`. */
+  loopbackHost?: LoopbackHost;
+  /** Budget for {@link Authorization.complete}. Default 120 s — a human
+   *  flow driven by browser steps is slower than an HTTP call. */
+  timeoutMs?: number;
+}
+
+/** Everything discovery found, so a test can assert on it. */
+export interface AuthorizationServerInfo {
+  issuer: string;
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  registrationEndpoint?: string;
+  /** True when this client registered itself for this flow. */
+  dynamicallyRegistered: boolean;
+}
+
+const DEFAULT_COMPLETE_TIMEOUT_MS = 120_000;
+
+/** A minimal loopback HTTP server. Declared structurally so this file does
+ *  not need Bun's types at the call site. */
+interface LoopbackServer {
+  port: number;
+  stop(closeActiveConnections?: boolean): void;
+}
+
+/**
+ * One authorization attempt, in progress.
+ *
+ * `authorize()` has already done discovery, registration and PKCE, and has
+ * bound the loopback listener. All that is left is the part with a human
+ * in it: the test navigates a browser to {@link url}, and then calls
+ * {@link complete}.
+ */
+export class Authorization {
+  /** Send the browser here. */
+  readonly url: string;
+  readonly redirectUri: string;
+  readonly state: string;
+  readonly clientId: string;
+  readonly server: AuthorizationServerInfo;
+  /** Scopes requested, which may be empty — see {@link AuthorizeOptions.scopes}. */
+  readonly scopes: string[];
+  readonly resource?: string;
+
+  private readonly verifier: string;
+  private readonly clientSecret?: string;
+  private readonly timeoutMs: number;
+  private readonly listener?: LoopbackListener;
+  private settled = false;
+
+  constructor(init: {
+    url: string;
+    redirectUri: string;
+    state: string;
+    clientId: string;
+    clientSecret?: string;
+    server: AuthorizationServerInfo;
+    scopes: string[];
+    resource?: string;
+    verifier: string;
+    timeoutMs: number;
+    listener?: LoopbackListener;
+  }) {
+    this.url = init.url;
+    this.redirectUri = init.redirectUri;
+    this.state = init.state;
+    this.clientId = init.clientId;
+    this.clientSecret = init.clientSecret;
+    this.server = init.server;
+    this.scopes = init.scopes;
+    this.resource = init.resource;
+    this.verifier = init.verifier;
+    this.timeoutMs = init.timeoutMs;
+    this.listener = init.listener;
+  }
+
+  /**
+   * Wait for the redirect, then exchange the code for a token.
+   *
+   * With the default loopback redirect there is nothing to pass: the
+   * listener already holds the code, and this returns at once when the
+   * browser has landed. Pass `url` when the flow used a redirect URI this
+   * daemon does not serve — hand back where the browser ended up
+   * (`page.url()`).
+   */
+  async complete(opts?: { url?: string; timeoutMs?: number }): Promise<McpIdentity> {
+    try {
+      const params = opts?.url
+        ? new URL(opts.url).searchParams
+        : await this.waitForRedirect(opts?.timeoutMs ?? this.timeoutMs);
+
+      const error = params.get("error");
+      if (error) {
+        throw new McpAuthDeniedError(error, params.get("error_description") ?? undefined);
+      }
+      const returnedState = params.get("state");
+      if (returnedState !== this.state) {
+        throw new Error(
+          `authorization state mismatch: expected ${this.state}, got ${returnedState ?? "none"}`,
+        );
+      }
+      const code = params.get("code");
+      if (!code) throw new Error("the redirect carried no authorization code");
+
+      return await this.exchange(code);
+    } finally {
+      this.settled = true;
+      this.listener?.stop();
+    }
+  }
+
+  /** Release the loopback port without finishing the flow. */
+  cancel(): void {
+    if (this.settled) return;
+    this.settled = true;
+    this.listener?.stop();
+  }
+
+  private async waitForRedirect(timeoutMs: number): Promise<URLSearchParams> {
+    if (!this.listener) {
+      throw new Error(
+        "this authorization used a custom redirectUri, which spectest does not serve. " +
+          "Pass where the browser landed: await auth.complete({ url: page.url() })",
+      );
+    }
+    return this.listener.wait(timeoutMs);
+  }
+
+  private async exchange(code: string): Promise<McpIdentity> {
+    const body = new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: this.redirectUri,
+      client_id: this.clientId,
+      code_verifier: this.verifier,
+    });
+    // RFC 8707. MCP requires it on the token request too, not only on the
+    // authorize request — it is what binds the token to this one server.
+    if (this.resource) body.set("resource", this.resource);
+    if (this.clientSecret) body.set("client_secret", this.clientSecret);
+
+    const token = await postToken(this.server.tokenEndpoint, body);
+    return {
+      accessToken: token.access_token,
+      refreshToken: token.refresh_token,
+      tokenType: token.token_type ?? "Bearer",
+      scopes: splitScope(token.scope) ?? this.scopes,
+      resource: this.resource,
+      clientId: this.clientId,
+      issuer: this.server.issuer,
+      redirectUri: this.redirectUri,
+      tokenEndpoint: this.server.tokenEndpoint,
+      expiresAt: token.expires_in ? Date.now() + token.expires_in * 1000 : undefined,
+    };
+  }
+}
+
+/**
+ * Do everything up to the browser: discovery, registration, PKCE, and the
+ * loopback listener. Returns the URL to send the user to.
+ */
+export async function authorize(
+  serverUrl: string,
+  resourceMetadataUrl: string | undefined,
+  opts: AuthorizeOptions = {},
+): Promise<Authorization> {
+  const prm = await fetchProtectedResourceMetadata(serverUrl, resourceMetadataUrl);
+  const issuer = prm?.authorization_servers?.[0] ?? new URL(serverUrl).origin;
+  const metadata = await fetchAuthServerMetadata(issuer);
+
+  const resource = opts.resource ?? prm?.resource ?? canonicalResource(serverUrl);
+  // A real MCP client does not ask its user for scopes: it uses what the
+  // resource advertises, and otherwise sends none and lets the server
+  // decide.
+  const scopes = opts.scopes ?? prm?.scopes_supported ?? [];
+
+  let listener: LoopbackListener | undefined;
+  let redirectUri = opts.redirectUri;
+  if (!redirectUri) {
+    listener = await startLoopbackListener(opts.loopbackHost ?? "127.0.0.1");
+    redirectUri = listener.redirectUri;
+  }
+
+  let clientId = opts.clientId;
+  let clientSecret = opts.clientSecret;
+  let dynamicallyRegistered = false;
+  if (!clientId) {
+    if (!metadata.registration_endpoint) {
+      listener?.stop();
+      throw new Error(
+        `${issuer} does not offer dynamic client registration. ` +
+          "Pass an existing client: mcp.authorize({ clientId, redirectUri }).",
+      );
+    }
+    const registered = await registerClient(metadata.registration_endpoint, {
+      redirectUri,
+      clientName: opts.clientName ?? "spectest",
+      scopes,
+    });
+    clientId = registered.client_id;
+    clientSecret = registered.client_secret;
+    dynamicallyRegistered = true;
+  }
+
+  const verifier = base64url(secureRandomBytes(32));
+  const challenge = base64url(createHash("sha256").update(verifier).digest());
+  const state = base64url(secureRandomBytes(16));
+
+  const url = new URL(metadata.authorization_endpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", clientId);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  if (resource) url.searchParams.set("resource", resource);
+  if (scopes.length > 0) url.searchParams.set("scope", scopes.join(" "));
+
+  return new Authorization({
+    url: url.toString(),
+    redirectUri,
+    state,
+    clientId,
+    clientSecret,
+    server: {
+      issuer: metadata.issuer,
+      authorizationEndpoint: metadata.authorization_endpoint,
+      tokenEndpoint: metadata.token_endpoint,
+      registrationEndpoint: metadata.registration_endpoint,
+      dynamicallyRegistered,
+    },
+    scopes,
+    resource,
+    verifier,
+    timeoutMs: opts.timeoutMs ?? DEFAULT_COMPLETE_TIMEOUT_MS,
+    listener,
+  });
+}
+
+/** Exchange a refresh token for a new access token. Returns `undefined`
+ *  when the identity has no refresh token to spend. */
+export async function refreshIdentity(
+  identity: McpIdentity,
+  clientSecret?: string,
+): Promise<McpIdentity | undefined> {
+  if (!identity.refreshToken) return undefined;
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: identity.refreshToken,
+    client_id: identity.clientId,
+  });
+  if (identity.resource) body.set("resource", identity.resource);
+  if (clientSecret) body.set("client_secret", clientSecret);
+
+  const token = await postToken(identity.tokenEndpoint, body);
+  return {
+    ...identity,
+    accessToken: token.access_token,
+    // A server that rotates refresh tokens returns a new one; one that
+    // does not expects the old one to be reused.
+    refreshToken: token.refresh_token ?? identity.refreshToken,
+    scopes: splitScope(token.scope) ?? identity.scopes,
+    expiresAt: token.expires_in ? Date.now() + token.expires_in * 1000 : undefined,
+  };
+}
+
+interface TokenResponse {
+  access_token: string;
+  token_type?: string;
+  expires_in?: number;
+  refresh_token?: string;
+  scope?: string;
+}
+
+async function postToken(endpoint: string, body: URLSearchParams): Promise<TokenResponse> {
+  const res = await rawFetch(endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+    body: body.toString(),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    // The error body is a JSON object with `error` / `error_description`
+    // (RFC 6749 §5.2). Surface both; the code is what a test asserts on.
+    let code = `HTTP ${res.status}`;
+    let description: string | undefined = text.slice(0, 300);
+    try {
+      const parsed = JSON.parse(text) as { error?: string; error_description?: string };
+      if (parsed.error) code = parsed.error;
+      description = parsed.error_description ?? description;
+    } catch {
+      // Not JSON. The raw body is the best description available.
+    }
+    throw new McpAuthDeniedError(code, description);
+  }
+  const token = JSON.parse(text) as TokenResponse;
+  if (!token.access_token) throw new Error(`token endpoint returned no access_token: ${text}`);
+  return token;
+}
+
+interface RegistrationResponse {
+  client_id: string;
+  client_secret?: string;
+}
+
+async function registerClient(
+  endpoint: string,
+  init: { redirectUri: string; clientName: string; scopes: string[] },
+): Promise<RegistrationResponse> {
+  const body: Record<string, unknown> = {
+    client_name: init.clientName,
+    redirect_uris: [init.redirectUri],
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    // A loopback client cannot keep a secret (RFC 8252 §8.4).
+    token_endpoint_auth_method: "none",
+  };
+  if (init.scopes.length > 0) body["scope"] = init.scopes.join(" ");
+
+  const res = await rawFetch(endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`dynamic client registration failed: HTTP ${res.status} — ${text.slice(0, 300)}`);
+  }
+  const parsed = JSON.parse(text) as RegistrationResponse;
+  if (!parsed.client_id) throw new Error(`registration returned no client_id: ${text}`);
+  return parsed;
+}
+
+async function fetchProtectedResourceMetadata(
+  serverUrl: string,
+  resourceMetadataUrl?: string,
+): Promise<ProtectedResourceMetadata | undefined> {
+  const candidates = resourceMetadataUrl
+    ? [resourceMetadataUrl]
+    : wellKnownUrls(serverUrl, "oauth-protected-resource");
+  for (const url of candidates) {
+    const found = await fetchJson<ProtectedResourceMetadata>(url);
+    if (found) return found;
+  }
+  // Legal: a server may protect itself without publishing metadata. The
+  // caller then falls back to the server's own origin as the issuer.
+  return undefined;
+}
+
+async function fetchAuthServerMetadata(issuer: string): Promise<AuthServerMetadata> {
+  for (const url of [
+    ...wellKnownUrls(issuer, "oauth-authorization-server"),
+    ...wellKnownUrls(issuer, "openid-configuration"),
+  ]) {
+    const found = await fetchJson<AuthServerMetadata>(url);
+    if (found?.authorization_endpoint && found?.token_endpoint) {
+      return { ...found, issuer: found.issuer ?? issuer };
+    }
+  }
+  // MCP's fallback for a server that publishes nothing.
+  const base = issuer.replace(/\/$/, "");
+  return {
+    issuer,
+    authorization_endpoint: `${base}/authorize`,
+    token_endpoint: `${base}/token`,
+    registration_endpoint: `${base}/register`,
+  };
+}
+
+/**
+ * Candidate well-known URLs for an issuer, in the order to try them.
+ *
+ * RFC 8414 inserts the well-known segment BEFORE the issuer's path:
+ * `https://host/tenant` is discovered at
+ * `https://host/.well-known/oauth-authorization-server/tenant`. OpenID
+ * Connect appends instead. A path-carrying issuer therefore has two valid
+ * spellings and servers differ on which they serve, so we try the RFC 8414
+ * order first and fall back.
+ */
+export function wellKnownUrls(issuer: string, suffix: string): string[] {
+  const url = new URL(issuer);
+  const path = url.pathname.replace(/\/$/, "");
+  const root = `${url.origin}/.well-known/${suffix}`;
+  if (path === "" || path === "/") return [root];
+  return [`${url.origin}/.well-known/${suffix}${path}`, `${url.origin}${path}/.well-known/${suffix}`, root];
+}
+
+/** The canonical resource identifier (RFC 8707): the server URL with no
+ *  fragment, and a lowercase host. */
+export function canonicalResource(serverUrl: string): string {
+  const url = new URL(serverUrl);
+  url.hash = "";
+  url.host = url.host.toLowerCase();
+  return url.toString();
+}
+
+async function fetchJson<T>(url: string): Promise<T | undefined> {
+  try {
+    const res = await rawFetch(url, { headers: { accept: "application/json" } });
+    if (!res.ok) return undefined;
+    return (await res.json()) as T;
+  } catch {
+    // An unreachable or non-JSON endpoint is a miss, not a failure: the
+    // caller has other candidates and a documented fallback.
+    return undefined;
+  }
+}
+
+function splitScope(scope?: string): string[] | undefined {
+  if (!scope) return undefined;
+  const parts = scope.split(/\s+/).filter((s) => s !== "");
+  return parts.length > 0 ? parts : undefined;
+}
+
+export function base64url(bytes: Uint8Array | string): string {
+  const buf = typeof bytes === "string" ? new TextEncoder().encode(bytes) : bytes;
+  let binary = "";
+  for (const b of buf) binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** The loopback callback server. One per flow, stopped when the flow
+ *  settles. */
+interface LoopbackListener {
+  redirectUri: string;
+  wait(timeoutMs: number): Promise<URLSearchParams>;
+  stop(): void;
+}
+
+const CALLBACK_PATH = "/callback";
+
+/** Landing page. The browser is a real browser driven by a test, so this
+ *  is what a screenshot of the last step will show. */
+const CALLBACK_HTML = `<!doctype html>
+<meta charset="utf-8">
+<title>Authorized</title>
+<body style="font: 16px system-ui; padding: 3rem; color: #222">
+<h1 style="font-size: 1.25rem">Authorized</h1>
+<p>You can close this window.</p>
+`;
+
+async function startLoopbackListener(host: LoopbackHost): Promise<LoopbackListener> {
+  let resolve: ((params: URLSearchParams) => void) | undefined;
+  const received = new Promise<URLSearchParams>((r) => {
+    resolve = r;
+  });
+
+  // Port 0 asks the kernel for a free port. It is registered with the
+  // authorization server a moment later, which is exactly why dynamic
+  // client registration exists (RFC 8252 §7.3 also forbids a server from
+  // pinning the port of a loopback redirect).
+  const bun = (globalThis as { Bun?: { serve(opts: unknown): LoopbackServer } }).Bun;
+  if (!bun) throw new Error("the OAuth loopback listener needs Bun's HTTP server");
+  const server = bun.serve({
+    hostname: host,
+    port: 0,
+    fetch(req: Request) {
+      const url = new URL(req.url);
+      if (url.pathname !== CALLBACK_PATH) return new Response("not found", { status: 404 });
+      resolve?.(url.searchParams);
+      return new Response(CALLBACK_HTML, {
+        status: 200,
+        headers: { "content-type": "text/html; charset=utf-8" },
+      });
+    },
+  });
+
+  return {
+    redirectUri: `http://${host}:${server.port}${CALLBACK_PATH}`,
+    async wait(timeoutMs: number): Promise<URLSearchParams> {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const expired = new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () =>
+            reject(
+              new Error(
+                `no authorization redirect arrived within ${timeoutMs} ms. ` +
+                  "Did the test navigate a browser to auth.url and complete the sign-in?",
+              ),
+            ),
+          timeoutMs,
+        );
+      });
+      try {
+        return await Promise.race([received, expired]);
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    },
+    stop(): void {
+      server.stop(true);
+    },
+  };
+}