@specific.dev/spectest 0.55.0 → 0.56.0

package/dist/mcp-auth.js

@@ -0,0 +1,455 @@
+// 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 user (or the authorization server) refused the grant. */
+export class McpAuthDeniedError extends Error {
+    code;
+    description;
+    constructor(code, description) {
+        super(`authorization denied: ${code}${description ? ` — ${description}` : ""}`);
+        this.name = "McpAuthDeniedError";
+        this.code = code;
+        this.description = description;
+    }
+}
+const DEFAULT_COMPLETE_TIMEOUT_MS = 120_000;
+/**
+ * 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. */
+    url;
+    redirectUri;
+    state;
+    clientId;
+    server;
+    /** Scopes requested, which may be empty — see {@link AuthorizeOptions.scopes}. */
+    scopes;
+    resource;
+    verifier;
+    clientSecret;
+    timeoutMs;
+    listener;
+    settled = false;
+    constructor(init) {
+        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) {
+        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() {
+        if (this.settled)
+            return;
+        this.settled = true;
+        this.listener?.stop();
+    }
+    async waitForRedirect(timeoutMs) {
+        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);
+    }
+    async exchange(code) {
+        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, resourceMetadataUrl, opts = {}) {
+    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;
+    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, clientSecret) {
+    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,
+    };
+}
+async function postToken(endpoint, body) {
+    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 = text.slice(0, 300);
+        try {
+            const parsed = JSON.parse(text);
+            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);
+    if (!token.access_token)
+        throw new Error(`token endpoint returned no access_token: ${text}`);
+    return token;
+}
+async function registerClient(endpoint, init) {
+    const body = {
+        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);
+    if (!parsed.client_id)
+        throw new Error(`registration returned no client_id: ${text}`);
+    return parsed;
+}
+async function fetchProtectedResourceMetadata(serverUrl, resourceMetadataUrl) {
+    const candidates = resourceMetadataUrl
+        ? [resourceMetadataUrl]
+        : wellKnownUrls(serverUrl, "oauth-protected-resource");
+    for (const url of candidates) {
+        const found = await fetchJson(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) {
+    for (const url of [
+        ...wellKnownUrls(issuer, "oauth-authorization-server"),
+        ...wellKnownUrls(issuer, "openid-configuration"),
+    ]) {
+        const found = await fetchJson(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, suffix) {
+    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) {
+    const url = new URL(serverUrl);
+    url.hash = "";
+    url.host = url.host.toLowerCase();
+    return url.toString();
+}
+async function fetchJson(url) {
+    try {
+        const res = await rawFetch(url, { headers: { accept: "application/json" } });
+        if (!res.ok)
+            return undefined;
+        return (await res.json());
+    }
+    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) {
+    if (!scope)
+        return undefined;
+    const parts = scope.split(/\s+/).filter((s) => s !== "");
+    return parts.length > 0 ? parts : undefined;
+}
+export function base64url(bytes) {
+    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(/=+$/, "");
+}
+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) {
+    let resolve;
+    const received = new Promise((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.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) {
+            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) {
+            let timer;
+            const expired = new Promise((_, 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() {
+            server.stop(true);
+        },
+    };
+}

package/dist/mcp-transport.d.ts

@@ -0,0 +1,130 @@
+/** A JSON-RPC id. The client only ever mints numbers. */
+export type JsonRpcId = number | string;
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    result?: unknown;
+    error?: JsonRpcError;
+}
+/**
+ * The `WWW-Authenticate` challenge an MCP server sends with a `401`.
+ *
+ * `resourceMetadataUrl` is the entry point of the whole OAuth flow
+ * (RFC 9728). A server that omits it forces the client to guess the
+ * metadata location from its own URL, which `mcp-auth.ts` does.
+ */
+export interface McpChallenge {
+    /** The HTTP status that carried the challenge. */
+    status: number;
+    /** Almost always `Bearer`. */
+    scheme: string;
+    /** `resource_metadata` parameter — where the protected-resource
+     *  metadata lives. */
+    resourceMetadataUrl?: string;
+    /** `scope` parameter, when the server names what it wants. */
+    scope?: string;
+    /** `error` parameter, e.g. `invalid_token` for an expired token. */
+    error?: string;
+    /** The header, verbatim. Recorded so a test can assert on it. */
+    raw: string;
+}
+/** An HTTP-level failure from the MCP endpoint. A `401` carries the
+ *  parsed {@link McpChallenge}, which is what makes "the server rejected
+ *  this call" assertable in a test. */
+export declare class McpHttpError extends Error {
+    readonly status: number;
+    readonly challenge?: McpChallenge;
+    readonly body?: string;
+    constructor(status: number, message: string, challenge?: McpChallenge, body?: string);
+}
+/** A JSON-RPC error result. The request reached the server and the server
+ *  answered with an error object. */
+export declare class McpRpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(error: JsonRpcError);
+}
+/** Parse a `WWW-Authenticate` header. Returns `undefined` when there is
+ *  no header, so a bare `401` still reports a status with no challenge. */
+export declare function parseChallenge(header: string | null, status: number): McpChallenge | undefined;
+/** One HTTP exchange, for the step detail panel. Bodies are the parsed
+ *  JSON-RPC messages, not raw text. */
+export interface HttpExchange {
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    sessionId?: string;
+    /** Set when the reply was an SSE stream rather than a JSON body. */
+    streamed?: boolean;
+}
+export interface McpTransportOptions {
+    url: string;
+    /** Extra headers on every request (a static API key, a tenant id). */
+    headers?: Record<string, string>;
+    /** Read at call time, so a token minted mid-session applies at once. */
+    token?: () => string | undefined;
+    /** Default per-request budget. */
+    timeoutMs?: number;
+    /** Called for every server notification. */
+    onNotification?: (n: JsonRpcNotification) => void;
+    /** Called for every server-to-client request. Resolve with the result,
+     *  or throw to answer with a JSON-RPC error. */
+    onRequest?: (r: JsonRpcRequest) => Promise<unknown>;
+    /** Called after every HTTP exchange, for the recorder. */
+    onExchange?: (x: HttpExchange) => void;
+}
+/** The revision we speak. A server that wants an older one negotiates it
+ *  in the `initialize` result and we echo whatever it chose. */
+export declare const PROTOCOL_VERSION = "2025-06-18";
+export declare class McpTransport {
+    readonly url: string;
+    /** Issued by the server on `initialize`, echoed on every later request.
+     *  Absent for a stateless server, which is legal. */
+    sessionId?: string;
+    /** Negotiated on `initialize`. Sent on every request after that. */
+    protocolVersion?: string;
+    private nextId;
+    private readonly opts;
+    constructor(opts: McpTransportOptions);
+    /** Send a request and resolve with its result. Throws
+     *  {@link McpHttpError} for a transport failure and {@link McpRpcError}
+     *  for a JSON-RPC error result. */
+    request<T = unknown>(method: string, params?: unknown, opts?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    /** Send a notification. Nothing comes back. */
+    notify(method: string, params?: unknown, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /** End the session. Best-effort: a server that does not support
+     *  `DELETE` answers 405, which is not an error for us. */
+    close(): Promise<void>;
+    private headers;
+    private post;
+    /** Read the reply to request `id`. The body is either one JSON-RPC
+     *  response, or an SSE stream that carries it — possibly after
+     *  server-to-client traffic that belongs to the same request. */
+    private readResponse;
+    /** Handle one server-to-client request and post the answer back. */
+    private answer;
+}
+/** The `data` of one SSE frame, or `undefined` when it carries none.
+ *  Exported for tests. */
+export declare function sseData(frame: string): string | undefined;