@stigmer/outbound 3.18.1-dev.20260919070736

package/src/__tests__/metadata.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Pins the login-server walk: the RFC 9728 documents tried most specific
+ * first, the RFC 8414 well-known segment inserted BEFORE an issuer's path,
+ * OpenID's document as the fallback, the challenge's pointer preferred, and
+ * every attempt recorded so a caller can name the document it failed on.
+ */
+import { describe, expect, it } from "vitest";
+
+import type { OutboundFetch } from "../egress/fetch.js";
+import {
+  authorizationServerMetadataUrls,
+  protectedResourceMetadataUrls,
+  readAuthorizationServerMetadata,
+  resolveAuthorizationServers,
+} from "../mcp-oauth/metadata.js";
+
+const deps = { timeoutMs: 1_000 };
+
+function serving(documents: Record<string, unknown | { status: number; body?: unknown }>): { fetchImpl: OutboundFetch; requested: string[] } {
+  const requested: string[] = [];
+  const fetchImpl: OutboundFetch = async (url) => {
+    const key = String(url);
+    requested.push(key);
+    const entry = documents[key];
+    if (entry === undefined) return new Response(JSON.stringify({ error: "not found" }), { status: 404 });
+    if (typeof entry === "object" && entry !== null && "status" in entry && typeof (entry as { status: unknown }).status === "number") {
+      const { status, body } = entry as { status: number; body?: unknown };
+      return new Response(body === undefined ? null : JSON.stringify(body), { status });
+    }
+    return new Response(JSON.stringify(entry), { status: 200, headers: { "content-type": "application/json" } });
+  };
+  return { fetchImpl, requested };
+}
+
+const ISSUER_DOCUMENT = {
+  issuer: "https://login.vendor.test",
+  authorization_endpoint: "https://login.vendor.test/authorize",
+  token_endpoint: "https://login.vendor.test/token",
+  registration_endpoint: "https://login.vendor.test/register",
+  scopes_supported: ["read"],
+  code_challenge_methods_supported: ["S256"],
+};
+
+describe("protectedResourceMetadataUrls", () => {
+  it("tries the path-suffixed document first, then the bare one", () => {
+    expect(protectedResourceMetadataUrls(new URL("https://mcp.vendor.test/mcp/"))).toEqual([
+      "https://mcp.vendor.test/.well-known/oauth-protected-resource/mcp",
+      "https://mcp.vendor.test/.well-known/oauth-protected-resource",
+    ]);
+  });
+
+  it("tries only the bare document for a root resource", () => {
+    expect(protectedResourceMetadataUrls(new URL("https://mcp.vendor.test/"))).toEqual(["https://mcp.vendor.test/.well-known/oauth-protected-resource"]);
+  });
+});
+
+describe("authorizationServerMetadataUrls", () => {
+  it("inserts the well-known segment before an issuer's path (RFC 8414 section 3), then falls back", () => {
+    expect(authorizationServerMetadataUrls(new URL("https://login.vendor.test/tenant"))).toEqual([
+      "https://login.vendor.test/.well-known/oauth-authorization-server/tenant",
+      "https://login.vendor.test/.well-known/oauth-authorization-server",
+      "https://login.vendor.test/tenant/.well-known/openid-configuration",
+      "https://login.vendor.test/.well-known/openid-configuration",
+    ]);
+  });
+
+  it("for a bare issuer tries RFC 8414 at the origin first, the document the reader before this one read", () => {
+    expect(authorizationServerMetadataUrls(new URL("https://mcp.vendor.test"))).toEqual([
+      "https://mcp.vendor.test/.well-known/oauth-authorization-server",
+      "https://mcp.vendor.test/.well-known/openid-configuration",
+    ]);
+  });
+});
+
+describe("resolveAuthorizationServers", () => {
+  it("prefers the challenge's pointer and reads authorization_servers from it", async () => {
+    const { fetchImpl, requested } = serving({
+      "https://mcp.vendor.test/.well-known/oauth-protected-resource/mcp": { resource: "https://mcp.vendor.test/mcp", authorization_servers: ["https://login.vendor.test"] },
+    });
+    const result = await resolveAuthorizationServers("https://mcp.vendor.test/mcp", "https://mcp.vendor.test/.well-known/oauth-protected-resource/mcp", { ...deps, fetchImpl });
+    expect(result.issuers).toEqual(["https://login.vendor.test"]);
+    expect(requested).toEqual(["https://mcp.vendor.test/.well-known/oauth-protected-resource/mcp"]);
+  });
+
+  it("without a pointer walks the well-known documents most specific first", async () => {
+    const { fetchImpl, requested } = serving({
+      "https://mcp.vendor.test/.well-known/oauth-protected-resource": { authorization_servers: ["https://login.vendor.test/tenant"] },
+    });
+    const result = await resolveAuthorizationServers("https://mcp.vendor.test/mcp", undefined, { ...deps, fetchImpl });
+    expect(result.issuers).toEqual(["https://login.vendor.test/tenant"]);
+    expect(requested).toEqual(["https://mcp.vendor.test/.well-known/oauth-protected-resource/mcp", "https://mcp.vendor.test/.well-known/oauth-protected-resource"]);
+    expect(result.attempts).toEqual([
+      { url: "https://mcp.vendor.test/.well-known/oauth-protected-resource/mcp", status: 404 },
+      { url: "https://mcp.vendor.test/.well-known/oauth-protected-resource", status: 200 },
+    ]);
+  });
+
+  it("answers no issuers when no document names any, recording every attempt", async () => {
+    const { fetchImpl } = serving({});
+    const result = await resolveAuthorizationServers("https://mcp.vendor.test/mcp", undefined, { ...deps, fetchImpl });
+    expect(result.issuers).toEqual([]);
+    expect(result.attempts).toHaveLength(2);
+  });
+
+  it("records a network failure as an attempt and moves on", async () => {
+    const fetchImpl: OutboundFetch = async () => {
+      throw new Error("connect ECONNREFUSED");
+    };
+    const result = await resolveAuthorizationServers("https://mcp.vendor.test/", undefined, { ...deps, fetchImpl });
+    expect(result.issuers).toEqual([]);
+    expect(result.attempts).toEqual([{ url: "https://mcp.vendor.test/.well-known/oauth-protected-resource", error: "connect ECONNREFUSED" }]);
+  });
+});
+
+describe("readAuthorizationServerMetadata", () => {
+  it("reads a path-bearing issuer through the inserted well-known segment", async () => {
+    const { fetchImpl, requested } = serving({
+      "https://login.vendor.test/.well-known/oauth-authorization-server/tenant": ISSUER_DOCUMENT,
+    });
+    const read = await readAuthorizationServerMetadata("https://login.vendor.test/tenant", { ...deps, fetchImpl });
+    expect(read.kind).toBe("found");
+    if (read.kind === "found") {
+      expect(read.metadata).toEqual({
+        metadataUrl: "https://login.vendor.test/.well-known/oauth-authorization-server/tenant",
+        issuer: "https://login.vendor.test",
+        authorizationEndpoint: "https://login.vendor.test/authorize",
+        tokenEndpoint: "https://login.vendor.test/token",
+        registrationEndpoint: "https://login.vendor.test/register",
+        scopesSupported: ["read"],
+        codeChallengeMethodsSupported: ["S256"],
+      });
+    }
+    expect(requested).toEqual(["https://login.vendor.test/.well-known/oauth-authorization-server/tenant"]);
+  });
+
+  it("falls back to OpenID's document and reads an absent registration_endpoint as empty", async () => {
+    const { fetchImpl, requested } = serving({
+      "https://login.vendor.test/.well-known/openid-configuration": { ...ISSUER_DOCUMENT, registration_endpoint: undefined, scopes_supported: undefined },
+    });
+    const read = await readAuthorizationServerMetadata("https://login.vendor.test", { ...deps, fetchImpl });
+    expect(read.kind).toBe("found");
+    if (read.kind === "found") {
+      expect(read.metadata.registrationEndpoint).toBe("");
+      expect(read.metadata.scopesSupported).toEqual([]);
+      expect(read.metadata.metadataUrl).toBe("https://login.vendor.test/.well-known/openid-configuration");
+    }
+    expect(requested).toEqual(["https://login.vendor.test/.well-known/oauth-authorization-server", "https://login.vendor.test/.well-known/openid-configuration"]);
+  });
+
+  it("skips a document that lacks either endpoint and reports not-found with every attempt", async () => {
+    const { fetchImpl } = serving({
+      "https://login.vendor.test/.well-known/oauth-authorization-server": { issuer: "x", authorization_endpoint: "https://login.vendor.test/authorize" },
+      "https://login.vendor.test/.well-known/openid-configuration": { status: 503 },
+    });
+    const read = await readAuthorizationServerMetadata("https://login.vendor.test", { ...deps, fetchImpl });
+    expect(read).toEqual({
+      kind: "not-found",
+      attempts: [
+        { url: "https://login.vendor.test/.well-known/oauth-authorization-server", status: 200, missing: "token_endpoint" },
+        { url: "https://login.vendor.test/.well-known/openid-configuration", status: 503 },
+      ],
+    });
+  });
+
+  it("reports not-found for an unparseable issuer without dialling", async () => {
+    const { fetchImpl, requested } = serving({});
+    const read = await readAuthorizationServerMetadata("::::", { ...deps, fetchImpl });
+    expect(read).toEqual({ kind: "not-found", attempts: [] });
+    expect(requested).toEqual([]);
+  });
+});

package/src/__tests__/probe.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Pins the one-request probe: the complete `initialize` body (the shape
+ * several hosted servers demand before they authenticate), the caller's
+ * headers and name carried, the closed outcome vocabulary, the body
+ * released unread, and a failing fetch answered as `unreachable`.
+ */
+import { describe, expect, it } from "vitest";
+
+import type { OutboundFetch } from "../egress/fetch.js";
+import { probeEndpointAuth } from "../mcp-oauth/probe.js";
+import { MCP_PROTOCOL_VERSION } from "../mcp-oauth/request.js";
+
+const deps = { timeoutMs: 3_000, clientName: "stigmer-test" };
+
+function answering(status: number, headers: Record<string, string> = {}, body: string | null = null): { fetchImpl: OutboundFetch; calls: { url: string; init: RequestInit | undefined }[] } {
+  const calls: { url: string; init: RequestInit | undefined }[] = [];
+  const fetchImpl: OutboundFetch = async (url, init) => {
+    calls.push({ url: String(url), init });
+    return new Response(body, { status, headers });
+  };
+  return { fetchImpl, calls };
+}
+
+describe("probeEndpointAuth", () => {
+  it("sends one complete initialize, naming the caller, with the endpoint's headers layered on", async () => {
+    const { fetchImpl, calls } = answering(200, {}, "{}");
+    await probeEndpointAuth("https://mcp.vendor.test/mcp", { "X-Vendor": "v" }, { ...deps, fetchImpl });
+    expect(calls).toHaveLength(1);
+    const init = calls[0]?.init;
+    expect(init?.method).toBe("POST");
+    const headers = init?.headers as Record<string, string>;
+    expect(headers["Accept"]).toBe("application/json, text/event-stream");
+    expect(headers["Content-Type"]).toBe("application/json");
+    expect(headers["MCP-Protocol-Version"]).toBe(MCP_PROTOCOL_VERSION);
+    expect(headers["X-Vendor"]).toBe("v");
+    const body = JSON.parse(String(init?.body)) as { method: string; params: { protocolVersion: string; capabilities: object; clientInfo: { name: string } } };
+    expect(body.method).toBe("initialize");
+    expect(body.params.protocolVersion).toBe(MCP_PROTOCOL_VERSION);
+    expect(body.params.capabilities).toEqual({});
+    expect(body.params.clientInfo.name).toBe("stigmer-test");
+    expect(init?.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it("reads a 401 OAuth challenge as oauth with its resource_metadata pointer", async () => {
+    const { fetchImpl } = answering(401, { "www-authenticate": 'Bearer realm="OAuth", resource_metadata="https://mcp.vendor.test/.well-known/oauth-protected-resource"' });
+    await expect(probeEndpointAuth("https://mcp.vendor.test/mcp", undefined, { ...deps, fetchImpl })).resolves.toEqual({
+      kind: "oauth",
+      challenge: 'Bearer realm="OAuth", resource_metadata="https://mcp.vendor.test/.well-known/oauth-protected-resource"',
+      resourceMetadataUrl: "https://mcp.vendor.test/.well-known/oauth-protected-resource",
+    });
+  });
+
+  it("reads a 401 without a pointer as oauth when the realm says OAuth", async () => {
+    const { fetchImpl } = answering(401, { "www-authenticate": 'Bearer realm="OAuth"' });
+    await expect(probeEndpointAuth("https://mcp.vendor.test/mcp", undefined, { ...deps, fetchImpl })).resolves.toEqual({
+      kind: "oauth",
+      challenge: 'Bearer realm="OAuth"',
+      resourceMetadataUrl: undefined,
+    });
+  });
+
+  it("reads a plain Bearer 401 as challenge-not-oauth", async () => {
+    const { fetchImpl } = answering(401, { "www-authenticate": 'Bearer error="invalid_token"' });
+    await expect(probeEndpointAuth("https://api.vendor.test/mcp", undefined, { ...deps, fetchImpl })).resolves.toEqual({
+      kind: "challenge-not-oauth",
+      challenge: 'Bearer error="invalid_token"',
+    });
+  });
+
+  it("reads a 401 without a WWW-Authenticate header as challenge-not-oauth with an empty challenge", async () => {
+    const { fetchImpl } = answering(401);
+    await expect(probeEndpointAuth("https://api.vendor.test/mcp", undefined, { ...deps, fetchImpl })).resolves.toEqual({ kind: "challenge-not-oauth", challenge: "" });
+  });
+
+  it("reads a 2xx as accepted whatever the body says, and releases the body", async () => {
+    let cancelled = false;
+    const stream = new ReadableStream<Uint8Array>({
+      cancel() {
+        cancelled = true;
+      },
+    });
+    const fetchImpl: OutboundFetch = async () => new Response(stream, { status: 200, headers: { "content-type": "text/event-stream" } });
+    await expect(probeEndpointAuth("https://open.vendor.test/mcp", undefined, { ...deps, fetchImpl })).resolves.toEqual({ kind: "accepted", status: 200 });
+    expect(cancelled).toBe(true);
+  });
+
+  it("reads any other status as http-other", async () => {
+    const { fetchImpl } = answering(405);
+    await expect(probeEndpointAuth("https://api.vendor.test/mcp", undefined, { ...deps, fetchImpl })).resolves.toEqual({ kind: "http-other", status: 405 });
+  });
+
+  it("never throws: a failing fetch is unreachable, naming the error", async () => {
+    const fetchImpl: OutboundFetch = async () => {
+      throw new Error("connect ECONNREFUSED");
+    };
+    await expect(probeEndpointAuth("http://127.0.0.1:9/mcp", undefined, { ...deps, fetchImpl })).resolves.toEqual({ kind: "unreachable", error: "Error: connect ECONNREFUSED" });
+  });
+});

package/src/egress/address.ts

@@ -0,0 +1,168 @@
+/**
+ * Address classification for outbound egress: which IP addresses a Stigmer
+ * process refuses to dial, under which posture, and why.
+ *
+ * This is the one home of the rule. It began as the runner's `web_fetch`
+ * SSRF boundary (backend/services/runner/src/tools/url-guard.ts, which now
+ * delegates here) and is shared because the control plane dials
+ * user-supplied URLs too: an MCP endpoint at save time and its login server
+ * on Sign in. A rule with two copies drifts; a copy that drifted on the
+ * control plane would be the copy guarding the wider network.
+ *
+ * Two postures, because locality differs, not trust:
+ *
+ * - "strict" (managed cloud processes): loopback, RFC 1918 private,
+ *   link-local, unspecified, and their IPv6 equivalents are all refused.
+ * - "relaxed" (self-hosted and local processes): the machine belongs to
+ *   the user, and a server beside the process (http://localhost:3000/mcp,
+ *   the proto's own example) is the normal case. Only the link-local range,
+ *   which carries the cloud metadata endpoint 169.254.169.254, stays
+ *   refused, as costless defence in depth.
+ *
+ * Who chooses the posture is the caller's business: the runner keys it on
+ * its mode with an operator override; the control plane takes it from an
+ * edition driver point. This module knows addresses and nothing else.
+ *
+ * IPv4-mapped IPv6 (::ffff:a.b.c.d in dotted or hex form) is classified by
+ * the embedded IPv4, so the mapping cannot smuggle a refused address past
+ * the check. Anything that is not a well-formed address fails closed.
+ *
+ * Proven by __tests__/address.test.ts, the runner's classification cases
+ * moved here byte for byte.
+ */
+import { isIP } from "node:net";
+
+/** The two egress postures; the caller derives one from where it runs. */
+export type EgressPosture = "strict" | "relaxed";
+
+/**
+ * An egress policy: the synchronous address judgement a process dials
+ * under. `blockedReason` answers for every string (an unparseable one is
+ * refused as "unrecognized"), never throws, and does no I/O. A policy that
+ * would need a network or a hostname to answer is a different seam.
+ */
+export interface EgressPolicy {
+  /** The posture's name, for logs and error copy. */
+  readonly name: string;
+  /** A human-readable range name when the address is refused, null when allowed. */
+  blockedReason(address: string): string | null;
+}
+
+/** The policy for a posture: the two shapes every consumer composes. */
+export function egressPolicyForPosture(posture: EgressPosture): EgressPolicy {
+  return {
+    name: posture,
+    blockedReason: (address) => blockedReason(address, posture),
+  };
+}
+
+/**
+ * Classify an IP address against the posture's refused ranges.
+ *
+ * @returns a human-readable range name when refused, or null when allowed.
+ */
+export function blockedReason(address: string, posture: EgressPosture): string | null {
+  const family = isIP(address);
+
+  if (family === 4) {
+    return blockedReasonV4(address, posture);
+  }
+
+  if (family === 6) {
+    const groups = expandV6(address);
+    if (!groups) return "unrecognized";
+
+    const embedded = extractMappedV4(groups);
+    if (embedded) {
+      return blockedReasonV4(embedded, posture);
+    }
+    return blockedReasonV6(groups, posture);
+  }
+
+  // Unparseable: fail closed; only real addresses get sockets.
+  return "unrecognized";
+}
+
+function blockedReasonV4(address: string, posture: EgressPosture): string | null {
+  const octets = address.split(".").map(Number);
+  if (octets.length !== 4 || octets.some((o) => Number.isNaN(o) || o < 0 || o > 255)) {
+    return "unrecognized";
+  }
+  const a = octets[0];
+  const b = octets[1];
+
+  // Link-local (169.254.0.0/16) hosts the cloud metadata service at
+  // 169.254.169.254: refused under BOTH postures.
+  if (a === 169 && b === 254) return "link-local (cloud metadata)";
+
+  if (posture === "relaxed") return null;
+
+  if (a === 127) return "loopback";
+  if (a === 0) return "unspecified";
+  if (a === 10) return "private (RFC 1918)";
+  if (a === 172 && b !== undefined && b >= 16 && b <= 31) return "private (RFC 1918)";
+  if (a === 192 && b === 168) return "private (RFC 1918)";
+
+  return null;
+}
+
+function blockedReasonV6(groups: readonly number[], posture: EgressPosture): string | null {
+  const first = groups[0] ?? 0;
+  // fe80::/10, the IPv6 link-local range, the v6 sibling of the metadata
+  // range: refused under BOTH postures for symmetry with v4.
+  if ((first & 0xffc0) === 0xfe80) return "link-local (cloud metadata)";
+
+  if (posture === "relaxed") return null;
+
+  const allZero = groups.every((g) => g === 0);
+  if (allZero) return "unspecified";
+  if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1) return "loopback";
+  // fc00::/7: unique local (private) addresses.
+  if ((first & 0xfe00) === 0xfc00) return "private (unique local)";
+
+  return null;
+}
+
+/**
+ * Expand an IPv6 address (already validated by isIP) into its 8 groups.
+ * Handles `::` compression, a trailing dotted-IPv4 tail, and zone suffixes.
+ */
+function expandV6(address: string): number[] | null {
+  let text = address.toLowerCase().split("%")[0] ?? "";
+
+  // Convert a dotted-IPv4 tail (for example ::ffff:127.0.0.1) into two hex groups.
+  const v4Tail = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+  const tail4 = v4Tail?.[1];
+  if (tail4 !== undefined) {
+    const octets = tail4.split(".").map(Number);
+    if (octets.length !== 4 || octets.some((o) => o > 255)) return null;
+    const [o0 = 0, o1 = 0, o2 = 0, o3 = 0] = octets;
+    const hex = `${((o0 << 8) | o1).toString(16)}:${((o2 << 8) | o3).toString(16)}`;
+    text = text.slice(0, -tail4.length) + hex;
+  }
+
+  const halves = text.split("::");
+  if (halves.length > 2) return null;
+
+  const parseHalf = (half: string): number[] => (half === "" ? [] : half.split(":").map((g) => parseInt(g, 16)));
+
+  const head = parseHalf(halves[0] ?? "");
+  const tail = halves.length === 2 ? parseHalf(halves[1] ?? "") : [];
+  const fill = 8 - head.length - tail.length;
+  if (halves.length === 2 ? fill < 0 : head.length !== 8) return null;
+
+  const groups = [...head, ...(halves.length === 2 ? Array<number>(fill).fill(0) : []), ...tail];
+  if (groups.length !== 8 || groups.some((g) => Number.isNaN(g) || g < 0 || g > 0xffff)) {
+    return null;
+  }
+  return groups;
+}
+
+/** Extract the IPv4 payload from IPv4-mapped groups (::ffff:0:0/96), if any. */
+function extractMappedV4(groups: readonly number[]): string | null {
+  const isMapped = groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff;
+  if (!isMapped) return null;
+  const hi = groups[6] ?? 0;
+  const lo = groups[7] ?? 0;
+  return `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+}

package/src/egress/check.ts

@@ -0,0 +1,163 @@
+/**
+ * The egress check: may this process dial this URL under this policy?
+ *
+ * The answer is a value, not a throw, so a caller can render its own
+ * sentence (the runner tells a model "this runner does not fetch from", the
+ * control plane tells a user what the endpoint resolved to) while the
+ * judgement itself has one home. `EgressError` wraps a refusal for the
+ * callers that want a throw (the guarded fetch).
+ *
+ * The check resolves the hostname and judges EVERY address it resolves to:
+ * a name with one public and one private record must be refused, or the
+ * private record becomes the bypass. Literal IP hosts are judged as they
+ * are, without a lookup. Resolution is injected (`LookupFn`) so tests never
+ * touch DNS, and it races the caller's `signal`: `dns.lookup` has no
+ * timeout of its own, and a save that waits on a hanging resolver would be
+ * a save that hangs (the control plane's probe runs under one deadline
+ * that covers resolution, for exactly this reason). An aborted signal
+ * propagates as the signal's reason, the way `fetch` itself behaves.
+ *
+ * Accepted limitation, inherited from the runner's guard: a DNS-rebinding
+ * window remains between our lookup and the socket connect. Node's fetch
+ * (undici) offers no lookup pinning without replacing the dispatcher, and
+ * the strict posture's range refusals make the rebinding payoff (an
+ * internal address) unreachable anyway.
+ *
+ * Proven by __tests__/check.test.ts.
+ */
+import { isIP } from "node:net";
+
+import type { EgressPolicy } from "./address.js";
+
+/** Resolve a hostname to every address it has; rejects when it has none. */
+export type LookupFn = (hostname: string) => Promise<readonly string[]>;
+
+/** Why a URL was refused; one shape per cause, each carrying what a sentence needs. */
+export type EgressRefusal =
+  | { readonly kind: "invalid-url"; readonly url: string }
+  | { readonly kind: "unsupported-scheme"; readonly url: URL; readonly scheme: string }
+  | { readonly kind: "unresolvable"; readonly url: URL; readonly hostname: string }
+  | {
+      readonly kind: "blocked";
+      readonly url: URL;
+      readonly hostname: string;
+      readonly address: string;
+      readonly reason: string;
+      readonly policy: string;
+    }
+  | { readonly kind: "too-many-redirects"; readonly url: URL; readonly hops: number };
+
+export type EgressCheck =
+  | { readonly ok: true; readonly url: URL; readonly addresses: readonly string[] }
+  | { readonly ok: false; readonly refusal: EgressRefusal };
+
+export interface EgressCheckOptions {
+  readonly lookup: LookupFn;
+  /** Bounds the resolution; an abort propagates as the signal's reason. */
+  readonly signal?: AbortSignal | null | undefined;
+}
+
+/** One sentence per refusal, safe to show a user or a model. */
+export function describeRefusal(refusal: EgressRefusal): string {
+  switch (refusal.kind) {
+    case "invalid-url":
+      return `Invalid URL: ${refusal.url}`;
+    case "unsupported-scheme":
+      return `Unsupported URL scheme "${refusal.scheme}": only http and https are allowed.`;
+    case "unresolvable":
+      return `Could not resolve hostname: ${refusal.hostname}`;
+    case "blocked":
+      return `Refusing to reach ${refusal.hostname}: it resolves to ${refusal.address}, a ${refusal.reason} address the ${refusal.policy} egress policy does not dial.`;
+    case "too-many-redirects":
+      return `Refusing to follow more than ${refusal.hops} redirects from ${refusal.url.href}.`;
+    default: {
+      const exhaustive: never = refusal;
+      return exhaustive;
+    }
+  }
+}
+
+/** A refusal as a throwable, for callers that want one. */
+export class EgressError extends Error {
+  constructor(readonly refusal: EgressRefusal) {
+    super(describeRefusal(refusal));
+    this.name = "EgressError";
+  }
+}
+
+/** Judge a URL under a policy: scheme, then every resolved address. */
+export async function checkEgress(rawUrl: string | URL, policy: EgressPolicy, options: EgressCheckOptions): Promise<EgressCheck> {
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    return { ok: false, refusal: { kind: "invalid-url", url: String(rawUrl) } };
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return { ok: false, refusal: { kind: "unsupported-scheme", url, scheme: url.protocol.replace(/:$/, "") } };
+  }
+
+  const addresses = await resolveAddresses(url.hostname, options);
+  if (addresses === undefined) {
+    return { ok: false, refusal: { kind: "unresolvable", url, hostname: url.hostname } };
+  }
+
+  for (const address of addresses) {
+    const reason = policy.blockedReason(address);
+    if (reason !== null) {
+      return { ok: false, refusal: { kind: "blocked", url, hostname: url.hostname, address, reason, policy: policy.name } };
+    }
+  }
+
+  return { ok: true, url, addresses };
+}
+
+/**
+ * Every address a hostname has. Literal IPs pass through (a bracketed IPv6
+ * host arrives from URL.hostname still bracketed). `undefined` when the name
+ * does not resolve; an aborted signal throws its reason.
+ */
+async function resolveAddresses(hostname: string, options: EgressCheckOptions): Promise<readonly string[] | undefined> {
+  const literal = hostname.replace(/^\[|\]$/g, "");
+  if (isIP(literal) !== 0) {
+    return [literal];
+  }
+  try {
+    const records = await raceSignal(options.lookup(hostname), options.signal);
+    return records.length === 0 ? undefined : records;
+  } catch (error) {
+    if (options.signal?.aborted === true) throw error;
+    return undefined;
+  }
+}
+
+function raceSignal<T>(promise: Promise<T>, signal: AbortSignal | null | undefined): Promise<T> {
+  if (signal === null || signal === undefined) return promise;
+  if (signal.aborted) {
+    // The resolver was already asked; its eventual answer is nobody's now.
+    promise.catch(() => undefined);
+    return Promise.reject(abortReason(signal));
+  }
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => {
+      promise.catch(() => undefined);
+      reject(abortReason(signal));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}