@specific.dev/spectest 0.54.1 → 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,7 +33,12 @@ 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";
 // Low-level ingress primitives + the framework lowering that the friendly
 // `tls` / `hostnames` fields and `defineFake(...)` are built on. See
@@ -549,7 +554,8 @@ function buildLocatorMatchers(loc, negated, message) {
     // value for the timeline.
     const run = async (matcher, timeout, check, describe, expected) => {
         const started = Date.now();
-        const deadline = started + (timeout ?? DEFAULT_ACTION_TIMEOUT_MS);
+        const budget = timeout ?? DEFAULT_ACTION_TIMEOUT_MS;
+        const deadline = started + budget;
         let actual;
         // Whether this matcher's subject is meant to be on screen, i.e. whether
         // the step should carry a reveal target for the replay (see
@@ -560,20 +566,59 @@ function buildLocatorMatchers(loc, negated, message) {
         const expectsGone = (visibility && (matcher === "toBeHidden") !== negated) ||
             (matcher === "toHaveCount" && expected === 0);
         const settleOpts = { reveal: !expectsGone };
+        // "That element is not there" said plainly, or `undefined` when the
+        // element IS there and the matcher's own description is the better
+        // sentence.
+        //
+        // Two ways to learn it. A matcher whose probe waits (textContent,
+        // inputValue, isEnabled …) has already been told, by the playwright
+        // timeout it caught. One whose probe answers instantly (isVisible) has
+        // not — `toBeVisible()` on a selector that matches nothing and one that
+        // matches a hidden element fail identically — so the count is read once,
+        // at failure time only. `toHaveCount` is left alone: "expected count 2,
+        // got 0" already says it, and better.
+        const elementFailure = async (err) => {
+            if (err !== undefined)
+                return locatorFailureMessage(probe.label, err);
+            if (expectsGone || matcher === "toHaveCount")
+                return undefined;
+            try {
+                if ((await probe.count()) === 0) {
+                    return `No element matches ${probe.label} (waited ${formatWaited(budget)})`;
+                }
+            }
+            catch {
+                /* The page is gone or the chain is invalid — the matcher's own
+                   description still says what was expected. */
+            }
+            return undefined;
+        };
+        // The last error a probe threw, kept for the failure message: a matcher
+        // whose read waits for the element (textContent, inputValue, isEnabled …)
+        // reports a missing element as a playwright timeout, and that — not
+        // "got <error: Timeout 5000ms exceeded …>" — is the sentence to fail with.
+        let probeError;
         for (;;) {
             let satisfied;
             try {
                 const r = await check();
                 satisfied = r.satisfied;
                 actual = r.actual;
+                probeError = undefined;
             }
             catch (err) {
+                probeError = err;
                 if (Date.now() < deadline) {
                     await new Promise((r) => setTimeout(r, LOCATOR_POLL_MS));
                     continue;
                 }
                 satisfied = false;
-                actual = `<error: ${err?.message ?? String(err)}>`;
+                // The recorded "actual" is what the timeline shows next to the
+                // matcher, so it gets the readable summary too — never the call-log
+                // wall a playwright timeout carries.
+                actual =
+                    locatorFailureMessage(probe.label, err) ??
+                        `<error: ${err?.message ?? String(err)}>`;
             }
             const passed = satisfied !== negated;
             if (passed) {
@@ -590,7 +635,11 @@ function buildLocatorMatchers(loc, negated, message) {
                 return;
             }
             if (Date.now() >= deadline) {
-                const msg = describe(actual);
+                // The deadline, not the stopwatch: every one of these polled until it
+                // ran out, and "(waited 5s)" is both what the author set and the same
+                // number twice in a row — a measured 4_987ms is neither.
+                const msg = (await elementFailure(probeError)) ??
+                    `${describe(actual)} (waited ${formatWaited(budget)})`;
                 const sourceSeq = await probe.settle(matcher, Date.now() - started, msg, settleOpts);
                 recordAssertion({
                     matcher,

package/dist/locator-errors.d.ts

@@ -0,0 +1,21 @@
+/** A wait's duration, in the units a reader thinks in: "800ms", "5s", "1.5s". */
+export declare function formatWaited(ms: number): string;
+/**
+ * The sentence to fail with, or `undefined` when `err` is not a locator
+ * timeout we understand (in which case the caller must leave it alone).
+ *
+ * `label` is the locator's human chain label, the same string the timeline
+ * step shows.
+ */
+export declare function locatorFailureMessage(label: string, err: unknown): string | undefined;
+/**
+ * Replace a locator timeout's message in place and hand the error back, so the
+ * caller can `throw` it unchanged in every other respect.
+ *
+ * The error is mutated rather than wrapped: its stack holds the frames of the
+ * author's own call, which a fresh Error would lose. The stack string embeds
+ * the old message (it is built at construction), so that copy is rewritten
+ * too — otherwise the CLI's failure block would print the friendly message and
+ * then the timeout wall right under it.
+ */
+export declare function rewriteLocatorError(err: unknown, label: string): unknown;

package/dist/locator-errors.js

@@ -0,0 +1,142 @@
+// Readable failures for locator steps.
+//
+// Playwright reports every unmet actionability wait the same way: a
+// `TimeoutError` whose message is "Timeout 5000ms exceeded." with the real
+// story — did the element exist at all? was it disabled? did something cover
+// it? — buried in a call log below it. A test that clicks a button that is not
+// on the page therefore fails with a sentence about OUR deadline, which reads
+// as an infrastructure problem and says nothing about the page.
+//
+// This module turns those into one sentence that names the element and what
+// was wrong with it. Anything it does not recognise (a strict-mode violation,
+// a closed page, an assertion of ours) is passed through untouched — the rule
+// is that a message is only ever replaced when we have something better to
+// say.
+//
+// The call log is read from the error's own `log` array (playwright attaches
+// it) and falls back to parsing the message, since only the message survives
+// a serialize/deserialize round trip.
+/** A wait's duration, in the units a reader thinks in: "800ms", "5s", "1.5s". */
+export function formatWaited(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return "0ms";
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    // Rounded off the millisecond count, not through toFixed — 1450ms is
+    // "1.5s", and binary floating point renders 1.45 as 1.4.
+    return `${Math.round(ms / 100) / 10}s`;
+}
+/** Recognise playwright's actionability timeout and pull it apart. Returns
+ *  `undefined` for every other error. */
+function parseTimeout(err) {
+    const e = err;
+    if (!e || e.name !== "TimeoutError" || typeof e.message !== "string")
+        return undefined;
+    const m = /Timeout (\d+)ms exceeded/.exec(e.message);
+    if (!m)
+        return undefined;
+    const raw = Array.isArray(e.log)
+        ? e.log.filter((l) => typeof l === "string")
+        : logFromMessage(e.message);
+    return { timeoutMs: Number(m[1]), log: raw.map(cleanLogLine).filter(Boolean) };
+}
+function logFromMessage(message) {
+    const at = message.indexOf("Call log:");
+    if (at === -1)
+        return [];
+    return message.slice(at + "Call log:".length).split("\n");
+}
+/** Strip a line's leading bullet and repeat count ("2 × waiting for …"). */
+function cleanLogLine(line) {
+    return line.trim().replace(/^-\s*/, "").replace(/^\d+\s*×\s*/, "");
+}
+/** Did the locator ever match anything? Playwright logs "locator resolved to
+ *  <html>" the moment it does, and nothing of the sort when it never did. */
+function resolved(log) {
+    return log.some((l) => l.startsWith("locator resolved to"));
+}
+/** The state a `waitFor`-style wait was after, from its opening log line. */
+function waitedForState(log) {
+    for (const line of log) {
+        const m = /^waiting for .* to be (attached|detached|visible|hidden)$/.exec(line);
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
+/** Why an element that DID match still could not be acted on. Read from the
+ *  last attempt, since that is the state the deadline caught it in. */
+function actionabilityReason(log) {
+    for (let i = log.length - 1; i >= 0; i--) {
+        const line = log[i];
+        // "element is not visible" / "not enabled" / "not stable" / "not editable"
+        const missing = /^element is not (.+)$/.exec(line);
+        if (missing)
+            return `is not ${missing[1]}`;
+        // "<div id="overlay"></div> intercepts pointer events"
+        const covered = /^(<.+>) intercepts pointer events$/.exec(line);
+        if (covered)
+            return `is covered by ${covered[1]}`;
+    }
+    return undefined;
+}
+/**
+ * The sentence to fail with, or `undefined` when `err` is not a locator
+ * timeout we understand (in which case the caller must leave it alone).
+ *
+ * `label` is the locator's human chain label, the same string the timeline
+ * step shows.
+ */
+export function locatorFailureMessage(label, err) {
+    const detail = parseTimeout(err);
+    if (!detail)
+        return undefined;
+    const waited = `(waited ${formatWaited(detail.timeoutMs)})`;
+    if (!resolved(detail.log))
+        return `No element matches ${label} ${waited}`;
+    // It matched, so the failure is about the element's state.
+    switch (waitedForState(detail.log)) {
+        case "hidden":
+            return `Element ${label} is still visible ${waited}`;
+        case "detached":
+            return `Element ${label} is still attached to the page ${waited}`;
+        case "visible":
+            return `Element ${label} is not visible ${waited}`;
+        default:
+            break;
+    }
+    const reason = actionabilityReason(detail.log);
+    return reason
+        ? `Element ${label} ${reason} ${waited}`
+        : `Element ${label} never became ready for this action ${waited}`;
+}
+/**
+ * Replace a locator timeout's message in place and hand the error back, so the
+ * caller can `throw` it unchanged in every other respect.
+ *
+ * The error is mutated rather than wrapped: its stack holds the frames of the
+ * author's own call, which a fresh Error would lose. The stack string embeds
+ * the old message (it is built at construction), so that copy is rewritten
+ * too — otherwise the CLI's failure block would print the friendly message and
+ * then the timeout wall right under it.
+ */
+export function rewriteLocatorError(err, label) {
+    const message = locatorFailureMessage(label, err);
+    if (message === undefined)
+        return err;
+    const e = err;
+    const old = e.message;
+    if (typeof e.stack === "string") {
+        for (const [header, replacement] of [
+            [`${e.name}: ${old}`, `${e.name}: ${message}`],
+            [old, message],
+        ]) {
+            if (e.stack.startsWith(header)) {
+                e.stack = replacement + e.stack.slice(header.length);
+                break;
+            }
+        }
+    }
+    e.message = message;
+    return e;
+}

package/dist/locator.js

@@ -22,6 +22,7 @@
 // author-facing call is exactly one recorded browser event (with its rrweb
 // drain), whatever playwright work it composes underneath.
 import { Buffer } from "node:buffer";
+import { rewriteLocatorError } from "./locator-errors.js";
 import { resolveExistingProjectPath } from "./project-files.js";
 import { truncateUtf8 } from "./recorder.js";
 /** Default deadline for a locator action/read's target to become actionable.
@@ -350,20 +351,31 @@ function lowerInputFiles(files) {
 export function makeLocator(backend, strategy, chain) {
     const label = chainLabel(chain);
     const extend = (step) => makeLocator(backend, strategy, { steps: [...chain.steps, step] });
+    // Every terminal op runs through this: playwright's actionability timeouts
+    // say "Timeout 5000ms exceeded" and hide what actually went wrong in a call
+    // log, so they are rewritten into a sentence naming the element and its
+    // state (see locator-errors.ts). Applied INSIDE `pageOp`, so the recorded
+    // step carries the readable message too — not just the thrown error.
+    const readable = async (fn) => {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            throw rewriteLocatorError(err, label);
+        }
+    };
     // One recorded event, result NOT wrapped (void/action).
-    const act = (action, fields, fn) => backend.pageOp(action, { selector: label, ...fields }, (page) => fn(lower(page, chain), page));
+    const act = (action, fields, fn) => backend.pageOp(action, { selector: label, ...fields }, (page) => readable(() => fn(lower(page, chain), page)));
     // One recorded event whose fields the action itself finishes filling in:
     // `rec` is the very object the recorder spreads once `fn` resolves (the
     // same mutate-in-flight seam `screenshot`'s artifact id rides), so the
     // click family can stamp the point it acted on. See stampActionPoint.
     const actAt = (action, fn) => {
         const rec = { selector: label };
-        return backend.pageOp(action, rec, (page) => fn(lower(page, chain), rec));
+        return backend.pageOp(action, rec, (page) => readable(() => fn(lower(page, chain), rec)));
     };
     // One recorded event, result provenance-wrapped for expect().
-    const read = (action, fn, fields = {}) => backend.pageOp(action, { selector: label, ...fields }, (page) => fn(lower(page, chain)), {
-        wrap: true,
-    });
+    const read = (action, fn, fields = {}) => backend.pageOp(action, { selector: label, ...fields }, (page) => readable(() => fn(lower(page, chain))), { wrap: true });
     // Silent, non-recorded reads for expect(locator) matchers to poll.
     const probe = {
         label,
@@ -459,7 +471,7 @@ export function makeLocator(backend, strategy, chain) {
                 out.push(extend({ m: "nth", args: [i] }));
             return out;
         },
-        evaluate: (description, fn, arg) => backend.pageOp("evaluate", { selector: label, description }, (page) => lower(page, chain).evaluate(fn, arg), { wrap: true }),
+        evaluate: (description, fn, arg) => backend.pageOp("evaluate", { selector: label, description }, (page) => readable(() => lower(page, chain).evaluate(fn, arg)), { wrap: true }),
         waitFor: (opts) => act("waitFor", {}, (l) => l.waitFor({ state: opts?.state, timeout: opts?.timeout })),
     };
     // Attach the silent-read probe under its symbol (kept off the typed literal

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 {};