@specific.dev/spectest 0.55.0 → 0.56.0

package/dist/daemon.js

@@ -45,6 +45,10 @@ import { runContainerArgs } from "./harness/container-run.js";
 import { assertAbsolute, certificateHostnames, defaultKeyMode, expandServiceToken, isNoopChown, mountFlag, needsIdTables, numericId, resolveChownIds, } from "./harness/file-mounts.js";
 import { conflict, notFound, requireString, } from "./harness/methods.js";
 import { openTerminal } from "./terminal.js";
+// `ctx.mcp(url)`. One client per call, no registry: an authenticated
+// client is passed to descendants as a test's return value.
+import { openMcp } from "./mcp.js";
+import { setRawFetch } from "./harness/raw-fetch.js";
 import { readAnnotation } from "./annotate.js";
 import { pauseRecording, recordEmail, recordEnv, recordExec, recordFake, recordHttp, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, resumeRecording, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
 import { deepUnwrap, readRaw, wrap, wrapResponse } from "./inspect.js";
@@ -3392,6 +3396,10 @@ function isTransportError(err) {
  */
 function installFetchWrapper() {
     const original = globalThis.fetch;
+    // SDK internals (the MCP client, its OAuth flow) must not see the
+    // wrapper: a wrapped `res.ok` is an object, and the wrapper reads every
+    // body to the end, which never finishes for an SSE stream.
+    setRawFetch(original);
     const wrappedFn = async (input, init) => {
         const start = Date.now();
         const resv = reserveEvent();
@@ -4042,6 +4050,7 @@ async function runOne(testCase) {
         openTerminal: recordedOpenTerminal,
         browser: trackedOpenBrowser,
         mobile: trackedOpenMobile,
+        mcp: openMcp,
         testName: testCase.name,
         parent,
     };
@@ -4491,6 +4500,7 @@ async function evalCode(code, secrets) {
         openTerminal: evalOpenTerminal,
         browser: trackedOpenBrowser,
         mobile: trackedOpenMobile,
+        mcp: openMcp,
         testName: "eval",
         parent: undefined,
     };

package/dist/harness/raw-fetch.d.ts

@@ -0,0 +1,7 @@
+/** Called by the daemon with the real `fetch`, before it installs its
+ *  instrumented one. */
+export declare function setRawFetch(fn: typeof fetch): void;
+/** `fetch`, never the instrumented wrapper. Falls back to the global for
+ *  a context where nothing was ever installed (unit tests, a plain
+ *  script). */
+export declare function rawFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;

package/dist/harness/raw-fetch.js

@@ -0,0 +1,33 @@
+// The real `fetch`, for SDK internals that must not go through the test
+// recorder's wrapper.
+//
+// While a test (or an eval) runs, the daemon replaces `globalThis.fetch`
+// with an instrumented one: it records an `http` event, and it hands back
+// a WRAPPED response whose `ok` / `status` are provenance handles rather
+// than a boolean and a number. That is exactly right for a test's own
+// calls, and exactly wrong inside the SDK, in two ways:
+//
+//   1. `if (!res.ok)` is always false against a handle, because a handle
+//      is an object. An SDK client that checks it would read a `401` as a
+//      success. (`pauseRecording()` does not help: it stops the event, not
+//      the wrapper.)
+//   2. The wrapper clones the response and reads the clone to the end so
+//      it can record the body. For a streaming reply — Server-Sent Events
+//      — that does not finish until the stream closes, so the caller is
+//      handed its response only after the stream it was waiting to read
+//      has already ended. A long-lived stream deadlocks.
+//
+// So SDK-internal HTTP goes through `rawFetch`. The daemon publishes the
+// original here when it installs its wrapper.
+let original;
+/** Called by the daemon with the real `fetch`, before it installs its
+ *  instrumented one. */
+export function setRawFetch(fn) {
+    original = fn;
+}
+/** `fetch`, never the instrumented wrapper. Falls back to the global for
+ *  a context where nothing was ever installed (unit tests, a plain
+ *  script). */
+export function rawFetch(input, init) {
+    return (original ?? globalThis.fetch)(input, init);
+}

package/dist/ids.d.ts

@@ -1,2 +1,11 @@
 /** Mint a fresh id, e.g. `generateId("art")` → `art_0c3k9mpq…`. */
 export declare function generateId(prefix: string): string;
+/**
+ * Read `n` bytes directly from /dev/urandom (NOT Bun's cached pool).
+ *
+ * Exported because every in-VM secret with a uniqueness requirement has
+ * the same problem as an id: Bun's pool is frozen into the snapshot, so
+ * sibling forks draw identical bytes. An OAuth PKCE verifier and `state`
+ * (`mcp-auth.ts`) must come from here, not from `crypto.getRandomValues`.
+ */
+export declare function secureRandomBytes(n: number): Uint8Array;

package/dist/ids.js

@@ -38,7 +38,17 @@ export function generateId(prefix) {
         .digest();
     return `${prefix}_0${base32Crockford(digest.subarray(0, 16)).slice(0, RANDOM_LEN)}`;
 }
-/** Read `n` bytes directly from /dev/urandom (NOT Bun's cached pool). */
+/**
+ * Read `n` bytes directly from /dev/urandom (NOT Bun's cached pool).
+ *
+ * Exported because every in-VM secret with a uniqueness requirement has
+ * the same problem as an id: Bun's pool is frozen into the snapshot, so
+ * sibling forks draw identical bytes. An OAuth PKCE verifier and `state`
+ * (`mcp-auth.ts`) must come from here, not from `crypto.getRandomValues`.
+ */
+export function secureRandomBytes(n) {
+    return urandom(n);
+}
 function urandom(n) {
     const buf = new Uint8Array(n);
     try {

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export { RedisClient, type RedisClientLike, type RedisOptions } from "./redis.js
 export { S3Client, type S3ClientLike, type S3File, type S3ClientOptions } from "./s3.js";
 export type { Browser, BrowserOptions, Keyboard, Mouse, Touchscreen } from "./browser.js";
 import type { Browser, BrowserOptions } from "./browser.js";
+export { McpHttpError, McpRpcError, McpAuthDeniedError, type Mcp, type McpOptions, type McpAuthorization, type McpChallenge, type McpIdentity, type McpToolResult, type McpToolInfo, type McpResourceInfo, type McpResourceContents, type McpPromptInfo, type McpPromptResult, type McpContent, type McpNotification, type McpSamplingRequest, type McpSamplingResult, type AuthorizeOptions, type AuthorizationServerInfo, } from "./mcp.js";
+import type { Mcp, McpOptions } from "./mcp.js";
 export type { Locator, GetByRoleOptions, GetByTextOptions, FilterOptions, ClickOptions, BoundingBox, FilePayload, InputFiles, } from "./locator.js";
 import type { Locator } from "./locator.js";
 export type { UrlPattern } from "./url-match.js";
@@ -996,6 +998,47 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
      * natural way to assert on the exit code.
      */
     openTerminal(service: string, opts?: TerminalOpts): Promise<Terminal>;
+    /**
+     * Connect to a Model Context Protocol server over HTTP, as an AI client
+     * would. Every tool call, resource read and prompt renders as its own
+     * step in the timeline, with the arguments and the result.
+     *
+     * ```ts
+     * const mcp = await ctx.mcp("https://api.test/mcp");
+     * const res = await mcp.call("create_invoice", { customer: "Acme" });
+     * expect(res.json<{ id: string }>().id).toMatch(/^inv_/);
+     * ```
+     *
+     * **Each call returns a NEW client.** There is no per-name registry like
+     * `ctx.browser("alice")` has, and no default session. A client that has
+     * authenticated is handed to the tests that need it, as this test's
+     * return value — `ctx.parent` crosses the fork in daemon memory, live
+     * connections included:
+     *
+     * ```ts
+     * export const signedIn = env.test("sign in", async (ctx) => {
+     *   const mcp = await ctx.mcp(URL);
+     *   const auth = await mcp.authorize();
+     *   const page = await ctx.browser();
+     *   await page.goto(auth.url);
+     *   await page.getByRole("button", { name: "Allow" }).click();
+     *   await auth.complete();
+     *   return mcp;
+     * });
+     *
+     * env.test("call a tool", { dependsOn: signedIn }, async (ctx) => {
+     *   await ctx.parent.call("create_invoice", { amount: 250 });
+     * });
+     * ```
+     *
+     * Two identities are two calls to `ctx.mcp` — nothing to name.
+     *
+     * A server that needs authorization answers `401`, which is reported and
+     * not hidden: `ctx.mcp(url)` returns an unauthenticated client carrying
+     * the challenge, and a call on it fails with the server's own rejection.
+     * That is what makes "this tool is protected" a test.
+     */
+    mcp(url: string, opts?: McpOptions): Promise<Mcp>;
     /**
      * Open the headless browser. Backed by Chromium-over-CDP inside the VM.
      *

package/dist/index.js

@@ -33,6 +33,10 @@ export { annotate } from "./annotate.js";
 export { SQL } from "./sql.js";
 export { RedisClient } from "./redis.js";
 export { S3Client } from "./s3.js";
+// The MCP client (`ctx.mcp`). Drives a Model Context Protocol server the
+// way a real AI client would, with the OAuth flow a test runs through its
+// own browser. See `mcp.ts`.
+export { McpHttpError, McpRpcError, McpAuthDeniedError, } from "./mcp.js";
 import { isLocator, getLocatorProbe, isBrowserSession, getBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, } from "./locator.js";
 import { formatWaited, locatorFailureMessage } from "./locator-errors.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";

package/dist/mcp-auth.d.ts

@@ -0,0 +1,176 @@
+/** 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 declare class McpAuthDeniedError extends Error {
+    readonly code: string;
+    readonly description?: string;
+    constructor(code: string, description?: string);
+}
+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;
+}
+/**
+ * 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 declare 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;
+    private readonly clientSecret?;
+    private readonly timeoutMs;
+    private readonly listener?;
+    private settled;
+    constructor(init: {
+        url: string;
+        redirectUri: string;
+        state: string;
+        clientId: string;
+        clientSecret?: string;
+        server: AuthorizationServerInfo;
+        scopes: string[];
+        resource?: string;
+        verifier: string;
+        timeoutMs: number;
+        listener?: LoopbackListener;
+    });
+    /**
+     * 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()`).
+     */
+    complete(opts?: {
+        url?: string;
+        timeoutMs?: number;
+    }): Promise<McpIdentity>;
+    /** Release the loopback port without finishing the flow. */
+    cancel(): void;
+    private waitForRedirect;
+    private exchange;
+}
+/**
+ * Do everything up to the browser: discovery, registration, PKCE, and the
+ * loopback listener. Returns the URL to send the user to.
+ */
+export declare function authorize(serverUrl: string, resourceMetadataUrl: string | undefined, opts?: AuthorizeOptions): Promise<Authorization>;
+/** Exchange a refresh token for a new access token. Returns `undefined`
+ *  when the identity has no refresh token to spend. */
+export declare function refreshIdentity(identity: McpIdentity, clientSecret?: string): Promise<McpIdentity | undefined>;
+/**
+ * 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 declare function wellKnownUrls(issuer: string, suffix: string): string[];
+/** The canonical resource identifier (RFC 8707): the server URL with no
+ *  fragment, and a lowercase host. */
+export declare function canonicalResource(serverUrl: string): string;
+export declare function base64url(bytes: Uint8Array | string): string;
+/** The loopback callback server. One per flow, stopped when the flow
+ *  settles. */
+interface LoopbackListener {
+    redirectUri: string;
+    wait(timeoutMs: number): Promise<URLSearchParams>;
+    stop(): void;
+}
+export {};