@specific.dev/spectest 0.88.3 → 0.89.0

package/src/components/electron-chrome.ts

@@ -1,7 +1,55 @@
+// Trust for the environment CA, applied per session. Chromium on Linux
+// reads its own root store (NSS), never the container's mounted bundle, so
+// the renderer rejects every certificate the environment mints while Node
+// in the main process accepts them through NODE_EXTRA_CA_CERTS. This verify
+// procedure accepts exactly the chains that CA issued for the requested
+// host, and defers to Chromium's own verdict for everything else. An app
+// that installs its own procedure later replaces it, as in production.
+// Kept free of Electron so the unit test can run it under Bun.
+export const ELECTRON_CA_TRUST = String.raw`
+const { X509Certificate } = require('node:crypto');
+function loadEnvironmentCa(path) {
+  try { return path ? new X509Certificate(require('node:fs').readFileSync(path)) : null; }
+  catch { return null; }
+}
+// request: { hostname, errorCode, certificate: { data, issuerCert? } }.
+// Returns true only for a chain that ends at the CA and names the host.
+function issuedByEnvironmentCa(ca, request) {
+  try {
+    const leaf = new X509Certificate(request.certificate.data);
+    const host = request.hostname;
+    const named = leaf.checkHost(host) !== undefined || leaf.checkIP(host) !== undefined;
+    if (!named) return false;
+    const chain = [leaf];
+    for (let c = request.certificate; c.issuerCert && c.issuerCert !== c && chain.length < 8; c = c.issuerCert) {
+      chain.push(new X509Certificate(c.issuerCert.data));
+    }
+    for (let i = 0; i < chain.length; i++) {
+      const cert = chain[i];
+      if (cert.fingerprint256 === ca.fingerprint256) return i > 0;
+      const issuer = chain[i + 1] ?? ca;
+      if (!cert.checkIssued(issuer) || !cert.verify(issuer.publicKey)) return false;
+    }
+    return true;
+  } catch { return false; }
+}
+`;
+
 // Runs before the application's main entry, like Playwright's Electron loader.
 // Observe constructor options; do not replace the app entry, preload, IPC, or OS.
 export const ELECTRON_CHROME_HOOK = String.raw`
 const electron = require('electron');
+${ELECTRON_CA_TRUST}
+const environmentCa = loadEnvironmentCa(process.env.NODE_EXTRA_CA_CERTS);
+if (environmentCa) {
+  // Every session, including the default one and app-created partitions.
+  electron.app.on('session-created', session => {
+    session.setCertificateVerifyProc((request, callback) => {
+      if (request.errorCode === 0) return callback(0);
+      callback(issuedByEnvironmentCa(environmentCa, request) ? 0 : -3);
+    });
+  });
+}
 const NativeBrowserWindow = electron.BrowserWindow;
 const WrappedBrowserWindow = new Proxy(NativeBrowserWindow, {
   construct(Target, args, NewTarget) {

package/src/components/electron.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { electron } from './electron.js';
@@ -36,3 +36,86 @@ describe('Electron component contract', () => {
     expect(isDesktopApp(null)).toBe(false);
   });
 });
+
+describe('Electron component in a monorepo', () => {
+  function monorepo(run: (root: string) => void) {
+    const root = mkdtempSync(join(tmpdir(), 'spectest-electron-mono-'));
+    try {
+      mkdirSync(join(root, 'apps', 'desktop'), { recursive: true });
+      writeFileSync(join(root, 'package.json'), JSON.stringify({ workspaces: ['apps/*'], devDependencies: { electron: '44.0.0' } }));
+      writeFileSync(join(root, 'package-lock.json'), '{}');
+      writeFileSync(join(root, 'apps', 'desktop', 'package.json'), JSON.stringify({ name: '@acme/desktop' }));
+      run(root);
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  }
+  test('builds from the context root and runs the app from its workspace', () => monorepo(root => {
+    const service = electron({ appDir: join(root, 'apps/desktop'), context: root });
+    expect(service.image).toMatchObject({ context: root });
+    const content = (service.image as { content: string }).content;
+    expect(content).toContain('COPY . .\nRUN npm ci\n');
+    expect(content).toContain("RUN cd apps/desktop && node \"$(node -p \"require.resolve('electron/install.js')\")\"\n");
+    expect(content).toContain('RUN cd apps/desktop && npm run build\n');
+    expect(service.env?.SPECTEST_ELECTRON_APP_DIR).toBe('/app/apps/desktop');
+  }));
+  test('accepts electron declared at the context root only', () => monorepo(root => {
+    expect(() => electron({ appDir: join(root, 'apps/desktop'), context: root })).not.toThrow();
+    writeFileSync(join(root, 'package.json'), JSON.stringify({ workspaces: ['apps/*'] }));
+    expect(() => electron({ appDir: join(root, 'apps/desktop'), context: root })).toThrow('declare electron');
+  }));
+  test('rejects an app directory outside the context', () => monorepo(root => {
+    expect(() => electron({ appDir: root, context: join(root, 'apps/desktop') })).toThrow('must be inside context');
+  }));
+  test('the default context keeps the single-app image shape', () => fixture(appDir => {
+    const content = (electron({ appDir }).image as { content: string }).content;
+    expect(content).toContain('RUN node "$(node -p "require.resolve(\'electron/install.js\')")"\nRUN npm run build\n');
+    expect(electron({ appDir }).env?.SPECTEST_ELECTRON_APP_DIR).toBe('/app');
+  }));
+});
+
+describe('Electron environment-CA trust', () => {
+  const { ELECTRON_CA_TRUST } = require('./electron-chrome.js');
+  const { execFileSync } = require('node:child_process');
+  const { readFileSync: read } = require('node:fs');
+  function pki(run: (dir: string) => void) {
+    const dir = mkdtempSync(join(tmpdir(), 'spectest-electron-ca-'));
+    const sh = (cmd: string) => execFileSync('sh', ['-c', cmd], { cwd: dir, stdio: 'pipe' });
+    try {
+      sh('openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.pem -days 2 -subj /CN=env-ca 2>/dev/null');
+      sh('openssl req -x509 -newkey rsa:2048 -nodes -keyout other.key -out other.pem -days 2 -subj /CN=other-ca 2>/dev/null');
+      sh('printf "subjectAltName=DNS:api.example.test\\nbasicConstraints=CA:FALSE\\n" > ext.cnf');
+      sh('openssl req -newkey rsa:2048 -nodes -keyout leaf.key -out leaf.csr -subj /CN=api.example.test 2>/dev/null');
+      sh('openssl x509 -req -in leaf.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out leaf.pem -days 2 -extfile ext.cnf 2>/dev/null');
+      sh('openssl x509 -req -in leaf.csr -CA other.pem -CAkey other.key -CAcreateserial -out stranger.pem -days 2 -extfile ext.cnf 2>/dev/null');
+      sh('printf "basicConstraints=CA:TRUE\\nkeyUsage=keyCertSign\\n" > ica.cnf');
+      sh('openssl req -newkey rsa:2048 -nodes -keyout ica.key -out ica.csr -subj /CN=env-intermediate 2>/dev/null');
+      sh('openssl x509 -req -in ica.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out ica.pem -days 2 -extfile ica.cnf 2>/dev/null');
+      sh('openssl x509 -req -in leaf.csr -CA ica.pem -CAkey ica.key -CAcreateserial -out leaf2.pem -days 2 -extfile ext.cnf 2>/dev/null');
+      run(dir);
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  }
+  // The hook's source, evaluated the way Electron evaluates it: plain CommonJS.
+  const trust = new Function('require', `${ELECTRON_CA_TRUST}; return { loadEnvironmentCa, issuedByEnvironmentCa };`)(require);
+  const request = (leafPath: string, hostname: string, issuers: string[] = []) => {
+    let cert: any = undefined;
+    for (const p of [...issuers].reverse()) cert = { data: read(p, 'utf8'), issuerCert: cert };
+    return { hostname, errorCode: -202, certificate: { data: read(leafPath, 'utf8'), issuerCert: cert } };
+  };
+  test('accepts a leaf the environment CA issued for the requested host', () => pki(dir => {
+    const ca = trust.loadEnvironmentCa(join(dir, 'ca.pem'));
+    expect(ca).not.toBeNull();
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf.pem'), 'api.example.test'))).toBe(true);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf2.pem'), 'api.example.test', [join(dir, 'ica.pem')]))).toBe(true);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf2.pem'), 'api.example.test', [join(dir, 'ica.pem'), join(dir, 'ca.pem')]))).toBe(true);
+  }));
+  test('rejects other issuers, other hosts, a bare intermediate, and the CA itself', () => pki(dir => {
+    const ca = trust.loadEnvironmentCa(join(dir, 'ca.pem'));
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'stranger.pem'), 'api.example.test'))).toBe(false);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf.pem'), 'evil.example.test'))).toBe(false);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf2.pem'), 'api.example.test'))).toBe(false);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'ca.pem'), 'api.example.test'))).toBe(false);
+  }));
+  test('no CA file means no trust hook', () => {
+    expect(trust.loadEnvironmentCa(undefined)).toBeNull();
+    expect(trust.loadEnvironmentCa('/nonexistent/ca.pem')).toBeNull();
+  });
+});

package/src/components/electron.ts

@@ -1,12 +1,22 @@
 import { existsSync, readFileSync } from "node:fs";
+import { posix } from "node:path";
 import type { ServiceDefinition } from "../index.js";
 import { resolveProjectPath } from "../project-files.js";
 import { desktopApp, type DesktopApp } from "../desktop.js";
 import { ELECTRON_CHROME_HOOK } from "./electron-chrome.js";
 
 export interface ElectronOptions {
-  /** Project-relative app directory; must contain package.json and Electron. */
+  /** Project-relative app directory; must contain package.json. Electron must
+   * be declared here or in the context's package.json. */
   appDir?: string;
+  /**
+   * Image build context, relative to the project root. Default `appDir`.
+   * Set it to the repository root when the app is one workspace of a
+   * monorepo and resolves packages from above its own directory. The
+   * context is copied to `/app`; `installCommand` runs at the context root,
+   * `buildCommand` and Electron run in the app directory below it.
+   */
+  context?: string;
   /** Debian Node image tag, default 24-bookworm-slim. */
   nodeVersion?: string;
   /** Build the main/preload/renderer output; default npm run build. */
@@ -26,13 +36,14 @@ export const ELECTRON_LAUNCHER = String.raw`
 import http from 'node:http';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-const require = createRequire('/app/package.json');
+const appDir = process.env.SPECTEST_ELECTRON_APP_DIR || '/app';
+const require = createRequire(appDir + '/package.json');
 const child = spawn(require('electron'), [
   ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []),
   '--disable-dev-shm-usage', '--remote-debugging-port=9222',
   '-r', '/spectest-electron-chrome.cjs',
   process.env.SPECTEST_ELECTRON_ENTRY || '.',
-], { cwd: '/app', stdio: 'inherit', env: process.env });
+], { cwd: appDir, stdio: 'inherit', env: process.env });
 const upstream = req => ({
   host: '127.0.0.1', port: 9222, path: req.url, method: req.method,
   headers: { ...req.headers, host: '127.0.0.1:9222' },
@@ -68,18 +79,42 @@ child.on('exit', code => process.exit(code ?? 1));
 for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => child.kill(signal));
 `;
 
+/** Read a package.json and tell whether it declares electron. */
+function declaresElectron(manifest: string): boolean {
+  if (!existsSync(manifest)) return false;
+  const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+  return Boolean(pkg.dependencies?.electron || pkg.devDependencies?.electron);
+}
+
+/** The app directory as a path inside the build context: "." or "a/b". */
+function appPathInContext(appDir: string, context: string): string {
+  const rel = posix.relative(posix.normalize(context), posix.normalize(appDir));
+  if (rel === "") return ".";
+  if (rel.startsWith("..") || posix.isAbsolute(rel)) {
+    throw new Error(`electron(): appDir ${JSON.stringify(appDir)} must be inside context ${JSON.stringify(context)}`);
+  }
+  return rel;
+}
+
 /** Real Linux Electron under Xvfb, with a generated image and graphical replay.
  * Like expo(), returns an app handle for the matching context method.
  * Requires Linux-compatible application dependencies and binaries. */
 export function electron(options: ElectronOptions = {}) {
   const appDir = options.appDir ?? ".";
+  const context = options.context ?? appDir;
+  const appPath = appPathInContext(appDir, context);
   const manifest = resolveProjectPath(`${appDir}/package.json`);
   if (!existsSync(manifest)) throw new Error(`electron(): no package.json in ${appDir}`);
-  const pkg = JSON.parse(readFileSync(manifest, "utf8"));
-  if (!pkg.dependencies?.electron && !pkg.devDependencies?.electron) {
-    throw new Error("electron(): declare electron in the app's dependencies or devDependencies");
+  // A monorepo declares electron in the workspace or at the root; both work
+  // because the app resolves `electron` upward from its own directory.
+  if (!declaresElectron(manifest) && !declaresElectron(resolveProjectPath(`${context}/package.json`))) {
+    throw new Error(
+      "electron(): declare electron in the app's dependencies or devDependencies" +
+        (context === appDir ? "" : ` (in ${appDir} or in the context ${context})`),
+    );
   }
-  const locked = existsSync(resolveProjectPath(`${appDir}/package-lock.json`));
+  // The install runs at the context root, so that is where the lockfile counts.
+  const locked = existsSync(resolveProjectPath(`${context}/package-lock.json`));
   const node = options.nodeVersion ?? "24-bookworm-slim";
   if (!/^[\w.-]+$/.test(node)) throw new Error("electron(): invalid Node image tag");
   const install = options.installCommand ?? (locked ? "npm ci" : "npm install");
@@ -87,18 +122,22 @@ export function electron(options: ElectronOptions = {}) {
   if ([install, build].some(command => /[\r\n]/.test(command))) {
     throw new Error("electron(): build/install commands must be single-line shell commands");
   }
+  // Electron can be hoisted to the context root, so find its install script
+  // through Node's resolution from the app directory instead of a fixed path.
+  const inApp = appPath === "." ? "" : `cd ${appPath} && `;
+  const fetchElectron = `${inApp}node "$(node -p "require.resolve('electron/install.js')")"`;
   return {
     image: {
       type: "dockerfile",
-      context: appDir,
+      context,
       exclude: ["node_modules", "**/node_modules", "out", "test-results", ".data"],
       content: `FROM node:${node}
 RUN apt-get update && apt-get install -y --no-install-recommends xvfb xauth libgtk-3-0 libnss3 libgbm1 libasound2 fonts-liberation ca-certificates && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY . .
 RUN ${install}
-RUN node node_modules/electron/install.js
-RUN ${build}
+RUN ${fetchElectron}
+RUN ${inApp}${build}
 `,
     },
     files: [
@@ -106,7 +145,11 @@ RUN ${build}
       { path: "/spectest-electron-chrome.cjs", content: ELECTRON_CHROME_HOOK },
     ],
     command: "xvfb-run -a node /spectest-electron.mjs",
-    env: { ...options.env, SPECTEST_ELECTRON_ENTRY: options.entry ?? "." },
+    env: {
+      ...options.env,
+      SPECTEST_ELECTRON_ENTRY: options.entry ?? ".",
+      SPECTEST_ELECTRON_APP_DIR: appPath === "." ? "/app" : `/app/${appPath}`,
+    },
     dependsOn: options.dependsOn,
     ports: [9223],
     readyCheck: { type: "http", port: 9223, path: "/json/version", timeoutSecs: 60 },

package/src/harness/fetch.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { expect as assertValue } from "../index.js";
-import { type WrappedResponse } from "../inspect.js";
-import { recordFake, startRecording, stopRecording } from "../recorder.js";
+import { readRaw, readTag, type SpectestFetch, type WrappedResponse } from "../inspect.js";
+import { recordFake, startRecording, stopRecording, type HttpEvent } from "../recorder.js";
 import { installFetchWrapper, isTransportError } from "./fetch.js";
 import {
   bindInstrumentationScope,
@@ -65,6 +65,72 @@ describe("fetch execution scopes", () => {
     expect(stopRecording()).toEqual([]);
   });
 
+  test("header assertions retain HTTP provenance, including missing headers and cookies", async () => {
+    handler = () => new Response("ok", { headers: [
+      ["content-type", "text/plain"],
+      ["set-cookie", "a=1; Path=/"],
+      ["set-cookie", "b=2; Path=/"],
+    ] });
+    await runInstrumented(scope, async () => {
+      const res = await fetch(url("/headers")) as unknown as WrappedResponse;
+      assertValue(res.headers.get("Content-Type")).toBe("text/plain");
+      assertValue(res.headers.get("x-missing")).toBe(null);
+      assertValue(res.headers.has("CONTENT-TYPE")).toBe(true);
+      assertValue(res.headers.has("x-missing")).toBe(false);
+      assertValue(res.headers.getSetCookie()).toEqual(["a=1; Path=/", "b=2; Path=/"]);
+      assertValue(res.headers.getSetCookie()[1]).toBe("b=2; Path=/");
+    });
+    const events = stopRecording();
+    expect(events.map((e) => e.kind)).toEqual(["http", ...Array(6).fill("assertion")]);
+    expect(events.slice(1)).toMatchObject([
+      { sourceSeq: events[0]!.seq, path: ["headers", "content-type"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "x-missing"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "content-type", "<has>"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "x-missing", "<has>"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "set-cookie"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "set-cookie", "1"] },
+    ]);
+  });
+
+  test("wrapped headers keep native iteration and expose raw headers for ordinary APIs", async () => {
+    await runInstrumented(scope, async () => {
+      const res = await fetch(url("/headers")) as unknown as WrappedResponse;
+      const headers = res.headers;
+      const raw = res.unwrap().headers;
+      expect(res.headers).toBe(headers);
+      expect(headers.unwrap()).toBe(raw);
+      expect<unknown>(readRaw(headers)).toBe(raw);
+      expect(headers.get("content-type")?.unwrap() ?? null).toBe(raw.get("content-type"));
+      expect(headers.get("missing")).toBe(null);
+      expect(headers.has("missing").unwrap()).toBe(false);
+      expect([...headers]).toEqual([...raw]);
+      expect([...headers.entries()]).toEqual([...raw.entries()]);
+      expect([...headers.keys()]).toEqual([...raw.keys()]);
+      expect([...headers.values()]).toEqual([...raw.values()]);
+      const entries: [string, string][] = [];
+      headers.forEach((value, key) => entries.push([key, value]));
+      expect(entries).toEqual([...raw]);
+      assertValue(headers.transform("entries", (h) => Object.fromEntries(h))["content-type"])
+        .toBe(raw.get("content-type"));
+    });
+  });
+
+  test("cloned responses keep header provenance and independent bodies", async () => {
+    await runInstrumented(scope, async () => {
+      const res = await fetch(url("/clone")) as unknown as WrappedResponse;
+      const clone = res.clone();
+      assertValue(clone.headers.get("content-type")).toBe("application/json;charset=utf-8");
+      expect(clone.unwrap()).not.toBe(res.unwrap());
+      expect((await clone.text()).unwrap()).toBe('{"value":42}');
+      expect((await res.json<{ value: number }>()).value.unwrap()).toBe(42);
+    });
+    const events = stopRecording();
+    expect(events).toMatchObject([
+      { kind: "http" },
+      { kind: "assertion", sourceSeq: events[0]!.seq, path: ["headers", "content-type"] },
+    ]);
+  });
+
   test("an HTTP fake records only the test's outer request", async () => {
     handler = (req) => {
       if (new URL(req.url).pathname === "/fake") {
@@ -142,6 +208,42 @@ describe("fetch execution scopes", () => {
     expect(stopRecording()).toEqual([]);
   }, 2_000);
 
+  test.each([
+    { contentType: "text/event-stream; charset=utf-8", captureBody: undefined },
+    { contentType: "text/plain", captureBody: false },
+  ])("instrumented streams return before closing: %j", async ({ contentType, captureBody }) => {
+    let controller!: ReadableStreamDefaultController<Uint8Array>;
+    handler = () => new Response(new ReadableStream<Uint8Array>({
+      start(c) {
+        controller = c;
+        c.enqueue(new TextEncoder().encode("first chunk"));
+      },
+    }), { headers: { "content-type": contentType } });
+    try {
+      await runInstrumented(scope, async () => {
+        const res = await (fetch as unknown as SpectestFetch)(url("/stream"), {
+          captureBody, signal: AbortSignal.timeout(1_000),
+        });
+        assertValue(res.bodyUsed).toBe(false);
+        const reader = res.body!.getReader();
+        try {
+          const chunk = await reader.read();
+          expect(chunk.done).toBe(false);
+          assertValue(chunk.value!.transform("text", (bytes) => new TextDecoder().decode(bytes)))
+            .toBe("first chunk");
+        } finally { reader.releaseLock(); }
+      });
+    } finally { controller?.close(); }
+    const events = stopRecording();
+    expect(events).toMatchObject([
+      { kind: "http", status: 200 },
+      { kind: "assertion", sourceSeq: events[0]!.seq, path: ["bodyUsed"] },
+      { kind: "assertion", sourceSeq: events[0]!.seq, path: ["body", "<read>", "0", "<text>"] },
+    ]);
+    if (events[0]?.kind !== "http") throw new Error("Missing HTTP event");
+    expect((events[0] as HttpEvent).responseBody).toBeUndefined();
+  }, 2_000);
+
   test("test-authored ingress callbacks retain their scope but their fake upstream does not", async () => {
     const callback = runInstrumented(scope, () => bindInstrumentationScope(async () => {
       const res = await fetch(url("/interceptor")) as unknown as WrappedResponse;
@@ -241,6 +343,10 @@ describe("fetch execution scopes", () => {
       await runInstrumented(setup, async () => {
         const res = await fetch(url("/setup")) as unknown as WrappedResponse;
         expect(res.status.unwrap()).toBe(200);
+        expect(res.headers.get("content-type")?.unwrap()).toBe("application/json;charset=utf-8");
+        expect(readTag(res.headers.get("content-type"))).toEqual({
+          sourceSeq: undefined, path: ["headers", "content-type"],
+        });
         await runUninstrumented(async () => {
           expect((await fetch(url("/setup-fake"))).status).toBe(200);
         });

package/src/harness/fetch.ts

@@ -1,4 +1,4 @@
-import { wrapResponse, type WrappedResponse } from "../inspect.js";
+import { wrapResponse, type SpectestRequestInit, type WrappedResponse } from "../inspect.js";
 import { recordHttp, reserveEvent, truncateUtf8, type OmittedBody } from "../recorder.js";
 import { isTextualContentType, looksBinary, omittedBody, parseContentLength } from "./http-body.js";
 import { currentInstrumentationScope } from "./instrumentation-scope.js";
@@ -72,12 +72,11 @@ export function isTransportError(err: unknown): boolean {
 export function installFetchWrapper(): () => void {
   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.
+  // wrapper: its response properties and body readers return wrapped values.
   setRawFetch(original);
   const wrappedFn = async (
     input: Parameters<typeof fetch>[0],
-    init?: Parameters<typeof fetch>[1],
+    init?: SpectestRequestInit,
   ): Promise<Response | WrappedResponse> => {
     const scope = currentInstrumentationScope();
     if (!scope?.active) return original(input, init);
@@ -97,7 +96,11 @@ export function installFetchWrapper(): () => void {
       const contentType = res.headers.get("content-type");
       const contentLength = () => parseContentLength(res.headers.get("content-length"));
       const textual = isTextualContentType(contentType);
-      if (textual === false) {
+      const streaming = contentType?.split(";")[0]?.trim().toLowerCase() === "text/event-stream";
+      if (init?.captureBody === false || streaming) {
+        // Return on headers: an open-ended stream must not be drained (or
+        // cloned into an unbounded background buffer) by the recorder.
+      } else if (textual === false) {
         responseBody = omittedBody("binary", contentType, contentLength());
       } else {
         try {

package/src/index.ts

@@ -17,9 +17,21 @@ export type {
   Wrapped,
   WrappedObject,
   WrappedArray,
+  WrappedHeaders,
+  WrappedBuffer,
+  WrappedBinaryView,
+  WrappedBytes,
+  WrappedBlob,
+  WrappedFile,
+  WrappedFormData,
+  WrappedStream,
+  WrappedReader,
+  WrappedBYOBReader,
+  WrappedReadResult,
   WrappedResponse,
   Provenanced,
   SpectestFetch,
+  SpectestRequestInit,
   Unwrap,
 } from "./inspect.js";
 import type { OpTag, Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
@@ -475,11 +487,15 @@ export interface SpectestContext<
   /**
    * Instrumented `fetch`. In a test each call is recorded on the timeline
    * and resolves to a {@link WrappedResponse}: reads carry provenance so
-   * `expect(res.status)` / `expect(await res.json())` nest under the HTTP
+   * `expect(res.status)`, `expect(res.headers.get("content-type"))`, and
+   * `expect(await res.json())` nest under the HTTP
    * call. Because the status-line accessors are {@link Carrier}s, a raw
    * `res.status === 200` is a *type error* — use `res.status.unwrap()` /
    * `res.unwrap().status`, or assert via `expect`. Outside a test the
    * result is wrapped the same way, just with no timeline to link to.
+   * Body readers (`bytes`, `arrayBuffer`, `blob`, `formData`, `json`, `text`)
+   * and stream reader values also retain provenance. Use `captureBody: false`
+   * for open-ended streams; SSE responses skip recorder body capture automatically.
    *
    * (The plain global `fetch` is wrapped the same way at runtime but keeps
    * the standard `Response` type, so prefer `ctx.fetch` for honestly-typed