@stigmer/outbound 3.18.1-dev.20260919070736

package/mcp-oauth/request.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The requests Stigmer sends an MCP endpoint it does not yet hold a
+ * credential for: one complete `initialize`, and the `tools/list` the
+ * catalogue audit follows an open handshake with.
+ *
+ * Complete, not minimal. A bare `initialize` with empty params never
+ * reaches several hosted servers' authentication: Google's Gmail, Calendar,
+ * Drive and BigQuery endpoints, GoDaddy's and Shopify's validate the
+ * request first and answer HTTP 200 with a JSON-RPC error ("Missing
+ * protocol version for Initialize"), so a probe that sent the bare request
+ * called seven OAuth servers open (measured 2026-09-19 against the three
+ * vendor catalogues; stigmer #1188 records the runner's copy of the
+ * mistake). The request therefore carries the protocol version, empty
+ * capabilities and a `clientInfo` that names the caller, so a vendor's
+ * logs say which Stigmer process asked.
+ *
+ * `MCP_PROTOCOL_VERSION` is the revision the runner's client speaks. It is
+ * a constant here rather than an import from the MCP SDK so this library
+ * stays dependency-free; the runner pins the agreement in its own tests.
+ */
+/** The MCP protocol revision the handshake names. */
+export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+/** A JSON-RPC POST, ready to hand to `fetch` after adding a signal. */
+export interface JsonRpcRequestInit {
+    readonly method: "POST";
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/**
+ * A complete `initialize`. `clientName` names the process asking
+ * (`stigmer-server`, `stigmer-runner`, `stigmer-catalogue-audit`); `headers`
+ * are the endpoint's declared headers with any credential the caller holds.
+ */
+export declare function initializeRequest(clientName: string, headers?: Readonly<Record<string, string>>): JsonRpcRequestInit;
+/** The header a stateful server hands back on `initialize` and expects on every later request. */
+export declare const MCP_SESSION_HEADER = "mcp-session-id";
+/**
+ * The anonymous `tools/list` that follows an open handshake, carrying the
+ * session the server issued when it issued one. Used by the audit, which
+ * measures what a user could reach without signing in; the control plane's
+ * save-time probe stops at `initialize`.
+ */
+export declare function toolsListRequest(headers?: Readonly<Record<string, string>>, sessionId?: string): JsonRpcRequestInit;
+//# sourceMappingURL=request.d.ts.map

package/mcp-oauth/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/mcp-oauth/request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAYD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,kBAAkB,CAepH;AAED,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAQnH"}

package/mcp-oauth/request.js

@@ -0,0 +1,71 @@
+/**
+ * The requests Stigmer sends an MCP endpoint it does not yet hold a
+ * credential for: one complete `initialize`, and the `tools/list` the
+ * catalogue audit follows an open handshake with.
+ *
+ * Complete, not minimal. A bare `initialize` with empty params never
+ * reaches several hosted servers' authentication: Google's Gmail, Calendar,
+ * Drive and BigQuery endpoints, GoDaddy's and Shopify's validate the
+ * request first and answer HTTP 200 with a JSON-RPC error ("Missing
+ * protocol version for Initialize"), so a probe that sent the bare request
+ * called seven OAuth servers open (measured 2026-09-19 against the three
+ * vendor catalogues; stigmer #1188 records the runner's copy of the
+ * mistake). The request therefore carries the protocol version, empty
+ * capabilities and a `clientInfo` that names the caller, so a vendor's
+ * logs say which Stigmer process asked.
+ *
+ * `MCP_PROTOCOL_VERSION` is the revision the runner's client speaks. It is
+ * a constant here rather than an import from the MCP SDK so this library
+ * stays dependency-free; the runner pins the agreement in its own tests.
+ */
+/** The MCP protocol revision the handshake names. */
+export const MCP_PROTOCOL_VERSION = "2025-06-18";
+/** The headers every request carries; the caller's headers are layered on top. */
+function baseHeaders(headers) {
+    return {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+        "MCP-Protocol-Version": MCP_PROTOCOL_VERSION,
+        ...(headers ?? {}),
+    };
+}
+/**
+ * A complete `initialize`. `clientName` names the process asking
+ * (`stigmer-server`, `stigmer-runner`, `stigmer-catalogue-audit`); `headers`
+ * are the endpoint's declared headers with any credential the caller holds.
+ */
+export function initializeRequest(clientName, headers) {
+    return {
+        method: "POST",
+        headers: baseHeaders(headers),
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: MCP_PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: { name: clientName, version: "0" },
+            },
+        }),
+    };
+}
+/** The header a stateful server hands back on `initialize` and expects on every later request. */
+export const MCP_SESSION_HEADER = "mcp-session-id";
+/**
+ * The anonymous `tools/list` that follows an open handshake, carrying the
+ * session the server issued when it issued one. Used by the audit, which
+ * measures what a user could reach without signing in; the control plane's
+ * save-time probe stops at `initialize`.
+ */
+export function toolsListRequest(headers, sessionId) {
+    const merged = baseHeaders(headers);
+    if (sessionId !== undefined)
+        merged[MCP_SESSION_HEADER] = sessionId;
+    return {
+        method: "POST",
+        headers: merged,
+        body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }),
+    };
+}
+//# sourceMappingURL=request.js.map

package/mcp-oauth/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/mcp-oauth/request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC;AASjD,kFAAkF;AAClF,SAAS,WAAW,CAAC,OAAqD;IACxE,OAAO;QACL,cAAc,EAAE,kBAAkB;QAClC,MAAM,EAAE,qCAAqC;QAC7C,sBAAsB,EAAE,oBAAoB;QAC5C,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;KACnB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAkB,EAAE,OAA0C;IAC9F,OAAO;QACL,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC;QAC7B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;YACnB,OAAO,EAAE,KAAK;YACd,EAAE,EAAE,CAAC;YACL,MAAM,EAAE,YAAY;YACpB,MAAM,EAAE;gBACN,eAAe,EAAE,oBAAoB;gBACrC,YAAY,EAAE,EAAE;gBAChB,UAAU,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE;aAC/C;SACF,CAAC;KACH,CAAC;AACJ,CAAC;AAED,kGAAkG;AAClG,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA0C,EAAE,SAAkB;IAC7F,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,SAAS,KAAK,SAAS;QAAE,MAAM,CAAC,kBAAkB,CAAC,GAAG,SAAS,CAAC;IACpE,OAAO;QACL,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;KAClF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@stigmer/outbound",
+  "version": "3.18.1-dev.20260919070736",
+  "description": "The rules Stigmer's TypeScript processes dial a user-supplied endpoint by, shared by the control plane, the runner and the catalogue audit: the egress address policy and its guarded fetch, and the way an MCP endpoint's authentication is read (the OAuth-challenge rule, the complete initialize handshake, the RFC 9728 / RFC 8414 / OpenID resolution of its login server)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stigmer/stigmer.git",
+    "directory": "backend/libs/ts/outbound"
+  },
+  "engines": {
+    "node": "^22.13.0 || >=23.4.0"
+  },
+  "keywords": [
+    "stigmer",
+    "egress",
+    "ssrf",
+    "mcp",
+    "oauth"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./egress": {
+      "types": "./egress/index.d.ts",
+      "import": "./egress/index.js",
+      "default": "./egress/index.js"
+    },
+    "./mcp-oauth": {
+      "types": "./mcp-oauth/index.d.ts",
+      "import": "./mcp-oauth/index.js",
+      "default": "./mcp-oauth/index.js"
+    }
+  }
+}

package/src/__tests__/address.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Pins the address classification under both postures: the runner's cases,
+ * moved here byte for byte when the rule became shared, plus the policy
+ * shape a consumer composes.
+ */
+import { describe, expect, it } from "vitest";
+
+import { blockedReason, egressPolicyForPosture } from "../egress/address.js";
+
+describe("blockedReason, strict posture", () => {
+  it.each([
+    ["127.0.0.1", "loopback"],
+    ["127.255.255.255", "loopback"],
+    ["0.0.0.0", "unspecified"],
+    ["10.0.0.1", "private (RFC 1918)"],
+    ["172.16.0.1", "private (RFC 1918)"],
+    ["172.31.255.255", "private (RFC 1918)"],
+    ["192.168.1.1", "private (RFC 1918)"],
+    ["169.254.169.254", "link-local (cloud metadata)"],
+    ["169.254.0.1", "link-local (cloud metadata)"],
+  ])("blocks %s as %s", (address, reason) => {
+    expect(blockedReason(address, "strict")).toBe(reason);
+  });
+
+  it.each(["8.8.8.8", "104.16.0.1", "172.15.0.1", "172.32.0.1", "192.169.0.1"])("allows public IPv4 %s", (address) => {
+    expect(blockedReason(address, "strict")).toBeNull();
+  });
+
+  it.each([
+    ["::1", "loopback"],
+    ["::", "unspecified"],
+    ["fc00::1", "private (unique local)"],
+    ["fd12:3456::1", "private (unique local)"],
+    ["fe80::1", "link-local (cloud metadata)"],
+    ["febf::1", "link-local (cloud metadata)"],
+  ])("blocks IPv6 %s as %s", (address, reason) => {
+    expect(blockedReason(address, "strict")).toBe(reason);
+  });
+
+  it("allows public IPv6", () => {
+    expect(blockedReason("2606:4700::6810:1", "strict")).toBeNull();
+  });
+
+  it("blocks IPv4-mapped IPv6 carrying a blocked v4 (dotted form)", () => {
+    expect(blockedReason("::ffff:127.0.0.1", "strict")).toBe("loopback");
+    expect(blockedReason("::ffff:10.0.0.1", "strict")).toBe("private (RFC 1918)");
+  });
+
+  it("blocks IPv4-mapped IPv6 carrying a blocked v4 (hex form)", () => {
+    expect(blockedReason("::ffff:7f00:1", "strict")).toBe("loopback");
+    expect(blockedReason("::ffff:a9fe:a9fe", "strict")).toBe("link-local (cloud metadata)");
+  });
+
+  it("allows IPv4-mapped IPv6 carrying a public v4", () => {
+    expect(blockedReason("::ffff:8.8.8.8", "strict")).toBeNull();
+  });
+
+  it("ignores a zone suffix when classifying", () => {
+    expect(blockedReason("fe80::1%eth0", "strict")).toBe("link-local (cloud metadata)");
+  });
+
+  it("fails closed on garbage", () => {
+    expect(blockedReason("not-an-ip", "strict")).toBe("unrecognized");
+  });
+});
+
+describe("blockedReason, relaxed posture", () => {
+  it.each(["127.0.0.1", "10.0.0.1", "192.168.1.1", "::1", "fd00::1"])("allows private/loopback %s (the machine belongs to the user)", (address) => {
+    expect(blockedReason(address, "relaxed")).toBeNull();
+  });
+
+  it("still blocks the cloud metadata range", () => {
+    expect(blockedReason("169.254.169.254", "relaxed")).toBe("link-local (cloud metadata)");
+    expect(blockedReason("fe80::1", "relaxed")).toBe("link-local (cloud metadata)");
+    expect(blockedReason("::ffff:169.254.169.254", "relaxed")).toBe("link-local (cloud metadata)");
+  });
+});
+
+describe("egressPolicyForPosture", () => {
+  it("names the posture and applies its classification", () => {
+    const strict = egressPolicyForPosture("strict");
+    const relaxed = egressPolicyForPosture("relaxed");
+    expect(strict.name).toBe("strict");
+    expect(relaxed.name).toBe("relaxed");
+    expect(strict.blockedReason("10.0.0.1")).toBe("private (RFC 1918)");
+    expect(relaxed.blockedReason("10.0.0.1")).toBeNull();
+  });
+});

package/src/__tests__/challenge.test.ts

@@ -0,0 +1,41 @@
+/**
+ * Pins the OAuth-challenge rule: the runner's cases, moved here when the
+ * rule became shared, and the `resource_metadata` pointer read.
+ */
+import { describe, expect, it } from "vitest";
+
+import { isOAuthChallenge, parseResourceMetadataUrl } from "../mcp-oauth/challenge.js";
+
+describe("isOAuthChallenge", () => {
+  it("matches the MCP auth spec Bearer + OAuth realm challenge", () => {
+    expect(isOAuthChallenge('Bearer realm="OAuth", resource_metadata="https://mcp.vendor.test/.well-known/oauth-protected-resource"')).toBe(true);
+  });
+
+  it("matches a Bearer challenge that only advertises resource_metadata", () => {
+    expect(isOAuthChallenge('Bearer resource_metadata="https://mcp.vendor.test/.well-known/oauth-protected-resource"')).toBe(true);
+  });
+
+  it("does not match a plain Bearer 401 (an invalid API key, not an OAuth requirement)", () => {
+    expect(isOAuthChallenge('Bearer error="invalid_token"')).toBe(false);
+  });
+
+  it("does not match a non-Bearer scheme", () => {
+    expect(isOAuthChallenge('Basic realm="OAuth"')).toBe(false);
+  });
+
+  it("is empty-safe", () => {
+    expect(isOAuthChallenge("")).toBe(false);
+  });
+});
+
+describe("parseResourceMetadataUrl", () => {
+  it("extracts the resource_metadata URL", () => {
+    expect(parseResourceMetadataUrl('Bearer realm="OAuth", resource_metadata="https://mcp.vendor.test/.well-known/oauth-protected-resource"')).toBe(
+      "https://mcp.vendor.test/.well-known/oauth-protected-resource",
+    );
+  });
+
+  it("returns undefined when absent", () => {
+    expect(parseResourceMetadataUrl('Bearer realm="OAuth"')).toBeUndefined();
+  });
+});

package/src/__tests__/check.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Pins the egress check: scheme first, then every resolved address, literal
+ * hosts without a lookup, an unresolvable name refused, and the caller's
+ * signal bounding a resolver that never answers.
+ */
+import { describe, expect, it } from "vitest";
+
+import { egressPolicyForPosture } from "../egress/address.js";
+import { checkEgress, describeRefusal, EgressError, type LookupFn } from "../egress/check.js";
+
+const strict = egressPolicyForPosture("strict");
+const relaxed = egressPolicyForPosture("relaxed");
+
+function table(entries: Record<string, readonly string[]>): LookupFn {
+  return async (hostname) => {
+    const found = entries[hostname];
+    if (found === undefined) throw new Error(`ENOTFOUND ${hostname}`);
+    return found;
+  };
+}
+
+describe("checkEgress", () => {
+  it("refuses a malformed URL before resolving anything", async () => {
+    const result = await checkEgress("not a url", strict, { lookup: table({}) });
+    expect(result).toEqual({ ok: false, refusal: { kind: "invalid-url", url: "not a url" } });
+  });
+
+  it.each(["file:///etc/passwd", "ftp://vendor.test/x", "gopher://vendor.test"])("refuses the scheme of %s", async (url) => {
+    const result = await checkEgress(url, strict, { lookup: table({}) });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.refusal.kind).toBe("unsupported-scheme");
+  });
+
+  it("judges a literal IP host without a lookup", async () => {
+    let lookups = 0;
+    const lookup: LookupFn = async () => {
+      lookups += 1;
+      return [];
+    };
+    const refused = await checkEgress("http://127.0.0.1:8080/x", strict, { lookup });
+    expect(refused.ok).toBe(false);
+    if (!refused.ok) expect(refused.refusal).toMatchObject({ kind: "blocked", address: "127.0.0.1", reason: "loopback", policy: "strict" });
+    const allowed = await checkEgress("http://127.0.0.1:3000/mcp", relaxed, { lookup });
+    expect(allowed).toMatchObject({ ok: true, addresses: ["127.0.0.1"] });
+    const bracketed = await checkEgress("http://[::1]/", strict, { lookup });
+    expect(bracketed.ok).toBe(false);
+    expect(lookups).toBe(0);
+  });
+
+  it("refuses a name when ANY of its addresses is blocked", async () => {
+    const lookup = table({ "split.vendor.test": ["104.16.0.1", "10.0.0.7"] });
+    const result = await checkEgress("https://split.vendor.test/mcp", strict, { lookup });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.refusal).toMatchObject({ kind: "blocked", hostname: "split.vendor.test", address: "10.0.0.7" });
+  });
+
+  it("allows a name whose every address the policy allows, and reports them", async () => {
+    const lookup = table({ "mcp.vendor.test": ["104.16.0.1", "2606:4700::6810:1"] });
+    const result = await checkEgress("https://mcp.vendor.test/mcp", strict, { lookup });
+    expect(result).toMatchObject({ ok: true, addresses: ["104.16.0.1", "2606:4700::6810:1"] });
+  });
+
+  it("refuses an unresolvable name", async () => {
+    const result = await checkEgress("https://nowhere.vendor.test/", strict, { lookup: table({}) });
+    expect(result).toMatchObject({ ok: false, refusal: { kind: "unresolvable", hostname: "nowhere.vendor.test" } });
+  });
+
+  it("refuses a name that resolves to nothing", async () => {
+    const result = await checkEgress("https://empty.vendor.test/", strict, { lookup: table({ "empty.vendor.test": [] }) });
+    expect(result).toMatchObject({ ok: false, refusal: { kind: "unresolvable" } });
+  });
+
+  it("gives up on a resolver that never answers when the signal aborts", async () => {
+    const hanging: LookupFn = () => new Promise(() => undefined);
+    const controller = new AbortController();
+    const pending = checkEgress("https://slow.vendor.test/", strict, { lookup: hanging, signal: controller.signal });
+    controller.abort(new Error("deadline"));
+    await expect(pending).rejects.toThrow("deadline");
+  });
+
+  it("rejects at once on an already-aborted signal", async () => {
+    const controller = new AbortController();
+    controller.abort(new Error("gone"));
+    await expect(checkEgress("https://slow.vendor.test/", strict, { lookup: table({}), signal: controller.signal })).rejects.toThrow("gone");
+  });
+});
+
+describe("describeRefusal and EgressError", () => {
+  it("renders one sentence per refusal and the error carries the refusal", () => {
+    const url = new URL("https://split.vendor.test/mcp");
+    const error = new EgressError({ kind: "blocked", url, hostname: url.hostname, address: "10.0.0.7", reason: "private (RFC 1918)", policy: "strict" });
+    expect(error.name).toBe("EgressError");
+    expect(error.message).toBe("Refusing to reach split.vendor.test: it resolves to 10.0.0.7, a private (RFC 1918) address the strict egress policy does not dial.");
+    expect(error.refusal.kind).toBe("blocked");
+    expect(describeRefusal({ kind: "unsupported-scheme", url: new URL("ftp://x.test/"), scheme: "ftp" })).toBe('Unsupported URL scheme "ftp": only http and https are allowed.');
+    expect(describeRefusal({ kind: "too-many-redirects", url, hops: 3 })).toBe("Refusing to follow more than 3 redirects from https://split.vendor.test/mcp.");
+  });
+});

package/src/__tests__/fetch.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Pins the guarded fetch: the first URL and every hop judged, a caller's
+ * `redirect: "manual"` honoured, `redirect: "error"` thrown like fetch, the
+ * hop budget, the Authorization header dropped across origins, and the
+ * method rewrite a 303 (or a 301/302 on a POST) implies.
+ */
+import { describe, expect, it } from "vitest";
+
+import { egressPolicyForPosture } from "../egress/address.js";
+import { EgressError, type LookupFn } from "../egress/check.js";
+import { asFetch, guardedFetch, type OutboundFetch } from "../egress/fetch.js";
+
+const strict = egressPolicyForPosture("strict");
+
+const lookup: LookupFn = async (hostname) => {
+  const table: Record<string, readonly string[]> = {
+    "a.vendor.test": ["104.16.0.1"],
+    "b.vendor.test": ["104.16.0.2"],
+    "internal.vendor.test": ["10.0.0.5"],
+  };
+  const found = table[hostname];
+  if (found === undefined) throw new Error(`ENOTFOUND ${hostname}`);
+  return found;
+};
+
+interface Seen {
+  readonly url: string;
+  readonly method: string;
+  readonly headers: Headers;
+  readonly body: RequestInit["body"];
+  readonly redirect: RequestInit["redirect"];
+}
+
+function scripted(answers: Record<string, () => Response>): { fetchImpl: OutboundFetch; seen: Seen[] } {
+  const seen: Seen[] = [];
+  const fetchImpl: OutboundFetch = async (url, init) => {
+    const key = String(url);
+    seen.push({ url: key, method: init?.method ?? "GET", headers: new Headers(init?.headers), body: init?.body, redirect: init?.redirect });
+    const answer = answers[key];
+    if (answer === undefined) throw new Error(`unscripted ${key}`);
+    return answer();
+  };
+  return { fetchImpl, seen };
+}
+
+const redirect = (status: number, location: string): Response => new Response(null, { status, headers: { location } });
+const ok = (): Response => new Response("ok", { status: 200 });
+
+describe("guardedFetch", () => {
+  it("judges the URL before dialling and refuses a blocked one without calling fetch", async () => {
+    const { fetchImpl, seen } = scripted({});
+    const fetchGuarded = guardedFetch(strict, { fetchImpl, lookup });
+    await expect(fetchGuarded("https://internal.vendor.test/mcp")).rejects.toBeInstanceOf(EgressError);
+    expect(seen).toHaveLength(0);
+  });
+
+  it("dials an allowed URL with the caller's init and asks the underlying fetch for manual redirects", async () => {
+    const { fetchImpl, seen } = scripted({ "https://a.vendor.test/mcp": ok });
+    const fetchGuarded = guardedFetch(strict, { fetchImpl, lookup });
+    const response = await fetchGuarded("https://a.vendor.test/mcp", { method: "POST", body: "{}", headers: { Accept: "application/json" } });
+    expect(response.status).toBe(200);
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toMatchObject({ method: "POST", body: "{}", redirect: "manual" });
+    expect(seen[0]?.headers.get("accept")).toBe("application/json");
+  });
+
+  it("follows a redirect and judges the hop, refusing one that lands on a blocked address", async () => {
+    const { fetchImpl, seen } = scripted({
+      "https://a.vendor.test/mcp": () => redirect(302, "https://internal.vendor.test/mcp"),
+    });
+    const fetchGuarded = guardedFetch(strict, { fetchImpl, lookup });
+    await expect(fetchGuarded("https://a.vendor.test/mcp")).rejects.toMatchObject({ refusal: { kind: "blocked", hostname: "internal.vendor.test" } });
+    expect(seen.map((s) => s.url)).toEqual(["https://a.vendor.test/mcp"]);
+  });
+
+  it("follows an allowed hop and resolves a relative Location against the current URL", async () => {
+    const { fetchImpl, seen } = scripted({
+      "https://a.vendor.test/mcp": () => redirect(301, "/mcp/"),
+      "https://a.vendor.test/mcp/": ok,
+    });
+    const fetchGuarded = guardedFetch(strict, { fetchImpl, lookup });
+    const response = await fetchGuarded("https://a.vendor.test/mcp");
+    expect(response.status).toBe(200);
+    expect(seen.map((s) => s.url)).toEqual(["https://a.vendor.test/mcp", "https://a.vendor.test/mcp/"]);
+  });
+
+  it("returns the 3xx untouched when the caller asked for manual redirects", async () => {
+    const { fetchImpl, seen } = scripted({ "https://a.vendor.test/authorize": () => redirect(302, "https://b.vendor.test/login") });
+    const fetchGuarded = guardedFetch(strict, { fetchImpl, lookup });
+    const response = await fetchGuarded("https://a.vendor.test/authorize", { redirect: "manual" });
+    expect(response.status).toBe(302);
+    expect(seen).toHaveLength(1);
+  });
+
+  it("throws a TypeError on a redirect when the caller asked for redirect: error", async () => {
+    const { fetchImpl } = scripted({ "https://a.vendor.test/x": () => redirect(302, "https://b.vendor.test/y") });
+    const fetchGuarded = guardedFetch(strict, { fetchImpl, lookup });
+    await expect(fetchGuarded("https://a.vendor.test/x", { redirect: "error" })).rejects.toBeInstanceOf(TypeError);
+  });
+
+  it("refuses past the hop budget", async () => {
+    const { fetchImpl, seen } = scripted({
+      "https://a.vendor.test/1": () => redirect(302, "https://a.vendor.test/2"),
+      "https://a.vendor.test/2": () => redirect(302, "https://a.vendor.test/3"),
+      "https://a.vendor.test/3": () => redirect(302, "https://a.vendor.test/4"),
+      "https://a.vendor.test/4": () => redirect(302, "https://a.vendor.test/5"),
+    });
+    const fetchGuarded = guardedFetch(strict, { fetchImpl, lookup });
+    await expect(fetchGuarded("https://a.vendor.test/1")).rejects.toMatchObject({ refusal: { kind: "too-many-redirects", hops: 3 } });
+    expect(seen).toHaveLength(4);
+  });
+
+  it("drops the Authorization header on a cross-origin hop and keeps it on a same-origin one", async () => {
+    const { fetchImpl, seen } = scripted({
+      "https://a.vendor.test/x": () => redirect(307, "https://a.vendor.test/y"),
+      "https://a.vendor.test/y": () => redirect(307, "https://b.vendor.test/z"),
+      "https://b.vendor.test/z": ok,
+    });
+    const fetchGuarded = guardedFetch(strict, { fetchImpl, lookup });
+    await fetchGuarded("https://a.vendor.test/x", { method: "POST", body: "{}", headers: { Authorization: "Bearer t" } });
+    expect(seen[0]?.headers.get("authorization")).toBe("Bearer t");
+    expect(seen[1]?.headers.get("authorization")).toBe("Bearer t");
+    expect(seen[2]?.headers.get("authorization")).toBeNull();
+    // 307 keeps the method and the body.
+    expect(seen[2]).toMatchObject({ method: "POST", body: "{}" });
+  });
+
+  it("turns a 303, or a 301/302 answering a POST, into a GET without a body", async () => {
+    const { fetchImpl, seen } = scripted({
+      "https://a.vendor.test/post": () => redirect(303, "https://a.vendor.test/result"),
+      "https://a.vendor.test/result": ok,
+      "https://a.vendor.test/post2": () => redirect(302, "https://a.vendor.test/result2"),
+      "https://a.vendor.test/result2": ok,
+    });
+    const fetchGuarded = guardedFetch(strict, { fetchImpl, lookup });
+    await fetchGuarded("https://a.vendor.test/post", { method: "POST", body: "{}", headers: { "Content-Type": "application/json" } });
+    expect(seen[1]).toMatchObject({ method: "GET", body: undefined });
+    expect(seen[1]?.headers.get("content-type")).toBeNull();
+    await fetchGuarded("https://a.vendor.test/post2", { method: "POST", body: "{}" });
+    expect(seen[3]).toMatchObject({ method: "GET", body: undefined });
+  });
+
+  it("asFetch wears the global fetch's shape and refuses a Request input rather than flattening it", async () => {
+    const { fetchImpl, seen } = scripted({ "https://a.vendor.test/mcp": ok });
+    const wrapped = asFetch(guardedFetch(strict, { fetchImpl, lookup }));
+    await expect(wrapped("https://a.vendor.test/mcp")).resolves.toHaveProperty("status", 200);
+    await expect(wrapped(new URL("https://a.vendor.test/mcp"))).resolves.toHaveProperty("status", 200);
+    await expect(wrapped(new Request("https://a.vendor.test/mcp"))).rejects.toBeInstanceOf(TypeError);
+    expect(seen).toHaveLength(2);
+  });
+
+  it("passes the caller's signal through to the check and to every hop", async () => {
+    const controller = new AbortController();
+    const { fetchImpl } = scripted({});
+    const hanging: LookupFn = () => new Promise(() => undefined);
+    const fetchGuarded = guardedFetch(strict, { fetchImpl, lookup: hanging });
+    const pending = fetchGuarded("https://a.vendor.test/mcp", { signal: controller.signal });
+    controller.abort(new Error("deadline"));
+    await expect(pending).rejects.toThrow("deadline");
+  });
+});