@sproutboat/wire 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @sproutboat/wire
 
+## 0.12.0
+
+### Minor Changes
+
+- 9e9638d: An egress service for `fetch()` (baronunread/sproutboat#252). `@sproutboat/wire/egress` runs as its own process (`SB_EGRESS_TOKEN=... bun egress.ts --port 8070`), listens on loopback, requires a token on every call, and performs the vetted fetch itself. A broker given `SB_EGRESS_URL` and `SB_EGRESS_TOKEN` sends `fetch()` through it instead of connecting directly, so on a host where the broker's own unit has no network, sprouts can still reach the internet. The address checks and `SB_EGRESS_ALLOW` behave the same in both modes; refusals read the same; compressed bodies and redirects come back as a direct fetch would see them.
+  
+  `fetch()` also moves on to the next resolved address when one can't be connected to, such as an IPv6 answer on a host with no IPv6 route. It only does so on failures where nothing was sent.
+
+## 0.11.0
+
+### Minor Changes
+
+- 4dd16b7: `fetch()` reaches any public address and never a private or reserved one (baronunread/sproutboat#174). The `outbound` allowlist is gone.
+  
+  - Both backends, the broker and the standalone client, check the address they resolved, not the hostname, so DNS rebinding can't get past the check. The broker connects to the vetted address and verifies TLS against the name.
+  - Blocked: loopback, RFC 1918, link-local and cloud metadata, CGNAT, benchmarking, documentation, multicast and reserved ranges, IPv6 ULA and link-local, and the IPv4 address inside IPv4-mapped, NAT64 and 6to4 addresses.
+  - An operator can let addresses through with `SB_EGRESS_ALLOW` (`*` or exact addresses) in the broker's or the binary's environment. Handler code can't.
+  - `@sproutboat/runtime`: `URL.hostname` and `URL.port` handle IPv6 literals (`[::1]:9` used to give hostname `[`). Every sprout gets `fetch()`, with no binding needed. `validateHttpSyncSource` no longer takes an `outboundAllowed` argument, and `Bindings` loses `outbound`.
+  - `@sproutboat/wire`: `Bindings` loses `outbound`.
+  - `@sproutboat/config`: `outbound` is accepted but ignored, with a warning in the new `warnings` field of a successful parse (`OUTBOUND_IGNORED`). It will be refused in a later minor release.
+
+### Patch Changes
+
+- Updated dependencies [4dd16b7]
+  - @sproutboat/runtime@0.14.0
+
 ## 0.10.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/wire",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -11,12 +11,14 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "dependencies": {
-    "@sproutboat/assets": "^0.3.0"
+    "@sproutboat/assets": "^0.3.0",
+    "@sproutboat/runtime": "^0.14.0"
   },
   "exports": {
     ".": "./src/index.ts",
     "./broker": "./src/broker.ts",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./egress": "./src/egress.ts"
   },
   "scripts": {
     "test": "bun test ./"

package/src/broker.test.ts

@@ -29,7 +29,8 @@ afterEach(() => {
 });
 
 function make(opts: Parameters<typeof createBroker>[0] = {}): Broker {
-  const b = createBroker(opts);
+  // A public address, so fetch tests are about fetch and not about DNS (#174).
+  const b = createBroker({ resolveImpl: async () => [{ address: "93.184.216.34" }], ...opts });
   brokers.push(b);
   return b;
 }
@@ -151,20 +152,70 @@ test("secrets resolve only when both bound and present", async () => {
   await expect(b.dispatch({ op: "secret.get", name: "UNBOUND" })).rejects.toThrow("not bound");
 });
 
-test("fetch is gated by the exact-host allowlist", async () => {
+test("fetch reaches any public host, with no allowlist (#174)", async () => {
   const calls: string[] = [];
   const fetchImpl: FetchLike = async (url) => {
     calls.push(String(url));
     return new Response("body", { status: 200, headers: { "x-mark": "1" } });
   };
-  const b = make({ bindings: { outbound: ["api.example.com"] }, fetchImpl });
-
-  await expect(b.dispatch({ op: "fetch", url: "https://evil.example.com/x" })).rejects.toThrow("allowlist");
-  expect(calls).toEqual([]);
+  const b = make({ fetchImpl });
 
+  await expect(b.dispatch({ op: "fetch", url: "ftp://api.example.com/x" })).rejects.toThrow("unsupported protocol");
   const res = await b.dispatch({ op: "fetch", url: "https://api.example.com/x" });
   expect(res).toMatchObject({ ok: true, status: 200, body: "body" });
-  expect(calls).toEqual(["https://api.example.com/x"]);
+  expect(calls).toEqual(["https://93.184.216.34/x"]);
+});
+
+test("#174: fetch never connects to a private address, whatever the name says", async () => {
+  const calls: string[] = [];
+  const fetchImpl: FetchLike = async (url) => {
+    calls.push(String(url));
+    return new Response("ok");
+  };
+  const resolving = (addresses: string[]) => async () => addresses.map((address) => ({ address }));
+
+  // A public-looking name that resolves somewhere private is refused before connect.
+  for (const address of ["127.0.0.1", "169.254.169.254", "10.0.0.7", "::1", "64:ff9b::7f00:1"]) {
+    const b = make({ fetchImpl, resolveImpl: resolving([address]), egressAllow: [] });
+    await expect(b.dispatch({ op: "fetch", url: "https://api.example.com/x" })).rejects.toThrow(
+      `api.example.com resolves to ${address}, a private or reserved address`,
+    );
+  }
+  expect(calls).toEqual([]);
+
+  // A mixed answer connects to the public address, not the first one.
+  const mixed = make({ fetchImpl, resolveImpl: resolving(["10.0.0.7", "2606:4700::1111"]), egressAllow: [] });
+  await mixed.dispatch({ op: "fetch", url: "https://api.example.com/x" });
+  expect(calls).toEqual(["https://[2606:4700::1111]/x"]);
+
+  // The operator, not the handler, can let one address through.
+  const allowed = make({ fetchImpl, resolveImpl: resolving(["10.0.0.7"]), egressAllow: ["10.0.0.7"] });
+  expect(await allowed.dispatch({ op: "fetch", url: "https://api.example.com/x" })).toMatchObject({ status: 200 });
+});
+
+test("#174: the pinned connection still sends the name as Host and verifies TLS against it", async () => {
+  const inits: RequestInit[] = [];
+  const fetchImpl: FetchLike = async (_url, init) => {
+    inits.push(init ?? {});
+    return new Response("ok");
+  };
+  const b = make({ fetchImpl });
+  await b.dispatch({ op: "fetch", url: "https://api.example.com/x" });
+  expect(new Headers(inits[0].headers).get("host")).toBe("api.example.com");
+  expect(inits[0]).toMatchObject({ tls: { serverName: "api.example.com" } });
+});
+
+test("#174: a real request reaches an allowed local upstream through the pinned address", async () => {
+  const upstream = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: (req) => new Response(req.headers.get("host")) });
+  try {
+    const host = `localhost:${upstream.port}`;
+    const b = make({ resolveImpl: undefined, egressAllow: ["127.0.0.1"] });
+    expect(await b.dispatch({ op: "fetch", url: `http://${host}/` })).toMatchObject({ status: 200, body: host });
+    const blocked = make({ resolveImpl: undefined, egressAllow: [] });
+    await expect(blocked.dispatch({ op: "fetch", url: `http://${host}/` })).rejects.toThrow("SB_EGRESS_ALLOW=");
+  } finally {
+    upstream.stop(true);
+  }
 });
 
 test("#232: a binary fetch request body is sent as its bytes, a text body as UTF-8", async () => {
@@ -173,7 +224,7 @@ test("#232: a binary fetch request body is sent as its bytes, a text body as UTF
     seen.push(new Uint8Array(await new Response(init?.body).arrayBuffer()));
     return new Response("ok");
   };
-  const b = make({ bindings: { outbound: ["api.example.com"] }, fetchImpl });
+  const b = make({ fetchImpl });
   // The runtime sends a binary body one char per byte, flagged bodyBinary.
   const raw = Array.from({ length: 256 }, (_, i) => String.fromCharCode(i)).join("");
   await b.dispatch({ op: "fetch", url: "https://api.example.com/up", method: "POST", body: raw, bodyBinary: true });
@@ -186,7 +237,7 @@ test("#232: a v1 fetch returns the upstream body as raw bytes; v0 keeps decoded
   const binary = Uint8Array.from({ length: 256 }, (_, i) => i);
   const fetchImpl: FetchLike = async (url) =>
     new Response(String(url).endsWith("/bin") ? binary : "café", { status: 200 });
-  const b = make({ bindings: { outbound: ["api.example.com"] }, fetchImpl });
+  const b = make({ fetchImpl });
 
   const raw = decodeV1Frame(
     await b.handleFrame(encodeV1({ v: 1, token: "tok", op: "fetch", url: "https://api.example.com/bin" })),
@@ -1111,21 +1162,21 @@ test("service: declared but not deployed says so, instead of a bare 502", async
   );
 });
 
-test("service: a call is not subject to the outbound allowlist", async () => {
-  // The target is reached internally through the edge, so a project with no
-  // `outbound` hosts can still call a service binding.
+test("service: a call reaches the edge on loopback, which plain fetch() may not", async () => {
+  // The target is reached internally through the edge, so the private-address
+  // block (#174) does not apply to it.
   const fetchImpl: FetchLike = async () => new Response("ok", { status: 200 });
   const b = make({
-    bindings: { ...svcBindings, outbound: [] },
+    bindings: svcBindings,
     services: { AUTH: "auth-api.andrea.example.com" },
     edgeUrl: "http://127.0.0.1:8080/",
     fetchImpl,
+    resolveImpl: async () => [{ address: "127.0.0.1" }],
+    egressAllow: [],
   });
   expect((await b.dispatch({ op: "service.fetch", binding: "AUTH", url: "https://service/" })).status).toBe(200);
-  // ...while real egress to the same host is still refused.
-  await expect(b.dispatch({ op: "fetch", url: "https://auth-api.andrea.example.com/" })).rejects.toThrow(
-    /outbound allowlist/,
-  );
+  // ...while real egress to the same place is refused.
+  await expect(b.dispatch({ op: "fetch", url: "http://127.0.0.1:8080/" })).rejects.toThrow("private or reserved");
 });
 
 // --- v1 frames (#63) --------------------------------------------------------

package/src/broker.ts

@@ -13,9 +13,9 @@
  *   reply payload   : "<json>"
  *
  * ponytail: one SQLite file for KV, secrets from a plain JSON file, fetch
- * allowlisted by exact host. Encryption at rest, per-key TTLs, redirect
- * re-validation and private-IP blocking are v2 — the exact-host allowlist is
- * the only SSRF control today.
+ * to any public address, never a private one (#174).
+ * Encryption at rest and per-key TTLs are v2; redirects are never followed,
+ * so there is nothing to re-validate.
  */
 import { Database, type Statement } from "bun:sqlite";
 import { createHash, randomBytes } from "node:crypto";
@@ -24,13 +24,14 @@ import { open } from "node:fs/promises";
 import { dirname, join, normalize, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { resolveAssetKey, type AssetManifest } from "@sproutboat/assets";
+import { egressAllowList } from "@sproutboat/runtime";
+import { EGRESS_ERROR_HEADER, EGRESS_TOKEN_HEADER, EGRESS_URL_HEADER, resolveAll, vettedFetch } from "./egress";
 import { isSafeInteger } from "./json";
 import { isBoolean, isString, jsonObject, parseJsonValue, type JsonObject, type JsonValue } from "./json";
 
 export type Bindings = {
   kv: string[];
   secrets: string[];
-  outbound: string[];
   d1: string[];
   r2: string[];
   queues: string[];
@@ -117,6 +118,15 @@ export type BrokerOptions = {
   assetsDir?: string;
   /** Injected in tests; defaults to the global `fetch`. */
   fetchImpl?: FetchLike;
+  /** Injected in tests; defaults to `dns.lookup` with every address. */
+  resolveImpl?: (hostname: string) => Promise<Array<{ address: string }>>;
+  /** #174 — private addresses `fetch()` may reach anyway. Defaults to
+   *  `SB_EGRESS_ALLOW` (`*` or comma-separated exact addresses). */
+  egressAllow?: string[];
+  /** #252 — send `fetch()` through the egress service (egress.ts) instead of
+   *  connecting directly. Defaults to `SB_EGRESS_URL` / `SB_EGRESS_TOKEN`. */
+  egressUrl?: string;
+  egressToken?: string;
 };
 
 type SqlParam = string | number | null;
@@ -214,7 +224,6 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   const bindings: Bindings = {
     kv: [],
     secrets: [],
-    outbound: [],
     d1: [],
     r2: [],
     queues: [],
@@ -255,6 +264,10 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   const replayed = new Map<string, Frame>();
   const serviceHosts = opts.services ?? {};
   const doFetch = opts.fetchImpl ?? fetch;
+  const resolveHost = opts.resolveImpl ?? resolveAll;
+  const egressAllow = opts.egressAllow ?? egressAllowList(process.env.SB_EGRESS_ALLOW);
+  const egressUrl = opts.egressUrl ?? process.env.SB_EGRESS_URL ?? "";
+  const egressToken = opts.egressToken ?? process.env.SB_EGRESS_TOKEN ?? "";
 
   const dbPath = opts.db ?? ":memory:";
   const inMemory = dbPath === ":memory:" || dbPath === "";
@@ -1129,7 +1142,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
    *
    * The size is the remote host's choice, and the body is held whole: measured
    * on a standalone binary, a 100 MB response took resident memory from 43 MB
-   * to 321 MB. One allowlisted upstream having a bad day should not be able to
+   * to 321 MB. One upstream having a bad day should not be able to
    * end the process. 32 MiB by default, and the same variable the embedded
    * transport reads so both backends agree.
    */
@@ -1171,6 +1184,21 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         ? new Uint8Array(Buffer.from(str(msg.body), "latin1"))
         : str(msg.body);
 
+  /** #252 — the egress service vets and fetches; its refusal reads as ours. */
+  async function viaEgressService(url: URL, init: RequestInit): Promise<Response> {
+    const headers = new Headers(init.headers);
+    headers.set(EGRESS_URL_HEADER, url.href);
+    headers.set(EGRESS_TOKEN_HEADER, egressToken);
+    const res = await doFetch(egressUrl, { ...init, headers });
+    if (res.headers.get(EGRESS_ERROR_HEADER)) {
+      // SAFETY: the egress service answers a refusal with { error: string }.
+      const { error } = (await res.json()) as { error: string };
+      throw new Error(error);
+    }
+    if (res.status === 401) throw new Error("the egress service rejected this broker's token");
+    return res;
+  }
+
   async function proxyFetch(msg: Frame): Promise<Upstream> {
     let url: URL;
     try {
@@ -1179,7 +1207,6 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       throw new Error(`invalid url: ${str(msg.url)}`);
     }
     if (url.protocol !== "https:" && url.protocol !== "http:") throw new Error(`unsupported protocol: ${url.protocol}`);
-    if (!bindings.outbound.includes(url.host)) throw new Error(`host not in outbound allowlist: ${url.host}`);
 
     const headers = new Headers();
     if (Array.isArray(msg.headers)) {
@@ -1188,12 +1215,15 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       }
     }
     const method = str(msg.method || "GET").toUpperCase();
-    const res = await doFetch(url, {
+    const init: RequestInit = {
       method,
       headers,
       body: method === "GET" || method === "HEAD" ? undefined : upstreamBody(msg),
       redirect: "manual",
-    });
+    };
+    const res = egressUrl
+      ? await viaEgressService(url, init)
+      : await vettedFetch(url, init, { resolve: resolveHost, allow: egressAllow, fetchImpl: doFetch });
     const outHeaders: Array<[string, string]> = [];
     res.headers.forEach((v, k) => outHeaders.push([k, v]));
     return { reply: { ok: true, status: res.status, headers: outHeaders }, bytes: await readCapped(res, url.host) };

package/src/egress.test.ts

@@ -0,0 +1,131 @@
+import { afterEach, expect, test } from "bun:test";
+import { gzipSync } from "node:zlib";
+import { createBroker } from "./broker";
+import { createEgressHandler, EGRESS_ERROR_HEADER, EGRESS_TOKEN_HEADER, EGRESS_URL_HEADER, vettedFetch } from "./egress";
+
+const TOKEN = "egress-test-token";
+const stops: Array<() => void> = [];
+afterEach(() => {
+  for (const stop of stops.splice(0)) stop();
+});
+
+/** A real upstream on loopback: echoes method, body and Host, or answers gzip / a redirect. */
+function upstream() {
+  const server = Bun.serve({
+    port: 0,
+    hostname: "127.0.0.1",
+    fetch: async (request) => {
+      const path = new URL(request.url).pathname;
+      if (path === "/gzip")
+        return new Response(gzipSync("compressed hello"), { headers: { "content-encoding": "gzip" } });
+      if (path === "/redirect") return new Response(null, { status: 302, headers: { location: "http://127.0.0.2/" } });
+      return Response.json(
+        { method: request.method, body: await request.text(), host: request.headers.get("host") },
+        { status: 201, headers: { "x-upstream": "1" } },
+      );
+    },
+  });
+  stops.push(() => server.stop(true));
+  return server;
+}
+
+/** The egress service on loopback, allowed to reach 127.0.0.1 only (for the upstream). */
+function egress() {
+  const server = Bun.serve({
+    port: 0,
+    hostname: "127.0.0.1",
+    fetch: createEgressHandler({ token: TOKEN, allow: ["127.0.0.1"] }),
+  });
+  stops.push(() => server.stop(true));
+  return server;
+}
+
+const call = (service: { url: URL }, target: string, init: RequestInit = {}, token = TOKEN) =>
+  fetch(service.url, {
+    ...init,
+    // SAFETY: every caller here passes headers as a plain record, or none.
+    headers: { ...(init.headers as Record<string, string>), [EGRESS_URL_HEADER]: target, [EGRESS_TOKEN_HEADER]: token },
+  });
+
+test("#252: the service relays a request and its response, Host set to the target's name", async () => {
+  const up = upstream();
+  const res = await call(egress(), `http://localhost:${up.port}/x`, { method: "POST", body: "payload" });
+  expect(res.status).toBe(201);
+  expect(res.headers.get("x-upstream")).toBe("1");
+  expect(await res.json()).toEqual({ method: "POST", body: "payload", host: `localhost:${up.port}` });
+});
+
+test("#252: compressed bodies and redirects pass through as a direct fetch would see them", async () => {
+  const up = upstream();
+  const service = egress();
+  const gz = await call(service, `http://127.0.0.1:${up.port}/gzip`);
+  expect([gz.headers.get("content-encoding"), await gz.text()]).toEqual(["gzip", "compressed hello"]);
+  const hop = await call(service, `http://127.0.0.1:${up.port}/redirect`, { redirect: "manual" });
+  expect([hop.status, hop.headers.get("location")]).toEqual([302, "http://127.0.0.2/"]);
+});
+
+test("#252: without the token the service does nothing", async () => {
+  const up = upstream();
+  const res = await call(egress(), `http://127.0.0.1:${up.port}/`, {}, "wrong-token-of-same-size");
+  expect(res.status).toBe(401);
+  expect(createEgressHandler.bind(null, { token: "" })).toThrow("needs a token");
+});
+
+test("#252: the service refuses private addresses with the #174 message", async () => {
+  const res = await call(egress(), "http://169.254.169.254/latest/meta-data/");
+  expect(res.headers.get(EGRESS_ERROR_HEADER)).toBe("1");
+  // SAFETY: a refusal (EGRESS_ERROR_HEADER, checked above) is { error: string }.
+  expect(((await res.json()) as { error: string }).error).toBe(
+    "fetch() refused: 169.254.169.254 resolves to 169.254.169.254, a private or reserved address (169.254.0.0/16). An operator can allow it with SB_EGRESS_ALLOW=169.254.169.254",
+  );
+});
+
+test("#252: a broker given SB_EGRESS_URL fetches through the service, refusals included", async () => {
+  const up = upstream();
+  const service = egress();
+  // The broker itself may not connect anywhere: egressAllow [] and a resolver
+  // that would only ever answer loopback. Success can only come via the service.
+  const broker = createBroker({
+    egressUrl: service.url.href,
+    egressToken: TOKEN,
+    egressAllow: [],
+    resolveImpl: async () => [{ address: "127.0.0.1" }],
+  });
+  stops.push(() => broker.close());
+
+  const ok = await broker.dispatch({ op: "fetch", url: `http://127.0.0.1:${up.port}/gzip` });
+  expect(ok).toMatchObject({ ok: true, status: 200, body: "compressed hello" });
+
+  await expect(broker.dispatch({ op: "fetch", url: "http://10.0.0.1/" })).rejects.toThrow(
+    "fetch() refused: 10.0.0.1 resolves to 10.0.0.1",
+  );
+
+  const stranger = createBroker({ egressUrl: service.url.href, egressToken: "not-the-token" });
+  stops.push(() => stranger.close());
+  await expect(stranger.dispatch({ op: "fetch", url: `http://127.0.0.1:${up.port}/` })).rejects.toThrow(
+    "rejected this broker's token",
+  );
+});
+
+test("an address that cannot be connected to falls through to the next, and only then", async () => {
+  const tried: string[] = [];
+  const unreachable = Object.assign(new TypeError("no route"), { code: "FailedToOpenSocket" });
+  const fetchImpl = async (url: URL | string) => {
+    tried.push(new URL(url).hostname);
+    if (tried.length === 1) throw unreachable;
+    return new Response("ok");
+  };
+  const resolve = async () => [{ address: "2606:4700::1111" }, { address: "1.1.1.1" }];
+  const res = await vettedFetch(new URL("https://one.example/"), {}, { resolve, allow: [], fetchImpl });
+  expect([tried, await res.text()]).toEqual([["[2606:4700::1111]", "1.1.1.1"], "ok"]);
+
+  // Any other failure may have sent the request already: no second attempt.
+  tried.length = 0;
+  const reset = Object.assign(new TypeError("reset"), { code: "ConnectionClosed" });
+  const failing = async (url: URL | string) => {
+    tried.push(new URL(url).hostname);
+    throw reset;
+  };
+  await expect(vettedFetch(new URL("https://one.example/"), {}, { resolve, allow: [], fetchImpl: failing })).rejects.toBe(reset);
+  expect(tried).toEqual(["[2606:4700::1111]"]);
+});

package/src/egress.ts

@@ -0,0 +1,150 @@
+/**
+ * Outbound `fetch()` for sprouts: the private-address block (#174) and the
+ * egress service (baronunread/sproutboat#252).
+ *
+ * The broker normally fetches itself. On the systemd install it runs inside the
+ * edge unit, whose `IPAddressDeny=any` keeps sprouts off the network and the
+ * broker with them, so it hands each request to this service instead: a
+ * separate unit outside that cgroup, listening on loopback. Sprouts share
+ * loopback, so every call carries a token that only brokers are given (the
+ * sprout sandbox clears its environment).
+ *
+ *   SB_EGRESS_TOKEN=... bun egress.ts --port 8070
+ *
+ * Either way the request goes through `vettedFetch`, so the address checks and
+ * `SB_EGRESS_ALLOW` behave identically.
+ */
+import { timingSafeEqual } from "node:crypto";
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { parseArgs } from "node:util";
+import { egressAllowList, egressRefusal } from "@sproutboat/runtime";
+
+type FetchLike = (input: URL | string, init?: RequestInit) => Promise<Response>;
+export type Resolve = (hostname: string) => Promise<Array<{ address: string }>>;
+export const resolveAll: Resolve = (hostname) => lookup(hostname, { all: true });
+
+/** The target URL, the caller's token, and the marker on a refusal reply. */
+export const EGRESS_URL_HEADER = "x-sb-egress-url";
+export const EGRESS_TOKEN_HEADER = "x-sb-egress-token";
+export const EGRESS_ERROR_HEADER = "x-sb-egress-error";
+
+/**
+ * #174 — resolve, vet every address, then connect to the vetted one, never the
+ * name: handing the name to fetch() would resolve it again, and DNS rebinding
+ * lives in that gap. TLS still verifies against the name. Throws the refusal.
+ */
+export async function vettedFetch(
+  url: URL,
+  init: RequestInit,
+  opts: { resolve: Resolve; allow: readonly string[]; fetchImpl: FetchLike },
+): Promise<Response> {
+  const hostname = url.hostname.replace(/^\[|\]$/g, "");
+  let addresses: Array<{ address: string }>;
+  try {
+    addresses = await opts.resolve(hostname);
+  } catch {
+    throw new Error(`could not resolve ${url.hostname}`);
+  }
+  let refusal: string | null = null;
+  const vetted = addresses.filter(({ address }) => {
+    const why = egressRefusal(url.hostname, address, opts.allow);
+    refusal ??= why;
+    return why === null;
+  });
+  if (vetted.length === 0) throw new Error(refusal ?? `could not resolve ${url.hostname}`);
+  const headers = new Headers(init.headers);
+  headers.set("host", url.host);
+  const pinnedInit: RequestInit & { tls?: { serverName: string } } = { ...init, headers, redirect: "manual" };
+  // Bun's TLS option: SNI and certificate checks against the name, not the address.
+  if (url.protocol === "https:" && !isIP(hostname)) pinnedInit.tls = { serverName: hostname };
+  // Like the standalone client, move on to the next address when one cannot be
+  // connected to (an IPv6 answer on a host with no IPv6 route). Only on those
+  // codes: nothing has been sent yet, so a retry cannot repeat a request.
+  let lastError: unknown;
+  for (const { address } of vetted) {
+    const pinned = new URL(url);
+    pinned.hostname = isIP(address) === 6 ? `[${address}]` : address;
+    try {
+      return await opts.fetchImpl(pinned, pinnedInit);
+    } catch (error) {
+      lastError = error;
+      // SAFETY: only reads an optional `code`; anything without one is rethrown.
+      const code = (error as { code?: unknown } | null)?.code;
+      if (!CONNECT_FAILURES.has(String(code))) throw error;
+    }
+  }
+  throw lastError;
+}
+
+/** Bun's fetch codes for a connection that never opened. */
+const CONNECT_FAILURES = new Set(["FailedToOpenSocket", "ConnectionRefused", "ECONNREFUSED", "ENETUNREACH", "EHOSTUNREACH"]);
+
+const refuse = (status: number, error: string) =>
+  Response.json({ error }, { status, headers: { [EGRESS_ERROR_HEADER]: "1" } });
+
+export type EgressOptions = {
+  /** Required: brokers send it, sprouts never see it. */
+  token: string;
+  /** `SB_EGRESS_ALLOW`, split. */
+  allow?: string[];
+  /** Injected in tests. */
+  resolve?: Resolve;
+  fetchImpl?: FetchLike;
+};
+
+/** The service's request handler: one upstream request per call. */
+export function createEgressHandler(opts: EgressOptions): (request: Request) => Promise<Response> {
+  if (!opts.token) throw new Error("the egress service needs a token");
+  const expected = Buffer.from(opts.token);
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const resolve = opts.resolve ?? resolveAll;
+  const allow = opts.allow ?? [];
+  return async (request) => {
+    const given = Buffer.from(request.headers.get(EGRESS_TOKEN_HEADER) ?? "");
+    if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
+      return new Response("unauthorized", { status: 401 });
+    }
+    let url: URL;
+    try {
+      url = new URL(request.headers.get(EGRESS_URL_HEADER) ?? "");
+    } catch {
+      return refuse(400, `invalid url: ${request.headers.get(EGRESS_URL_HEADER) ?? ""}`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") return refuse(400, `unsupported protocol: ${url.protocol}`);
+    const headers = new Headers(request.headers);
+    for (const name of [EGRESS_URL_HEADER, EGRESS_TOKEN_HEADER, "host", "content-length"]) headers.delete(name);
+    const method = request.method;
+    // `decompress: false` relays the upstream's bytes and Content-Encoding as
+    // they came, so the broker decodes them exactly as a direct fetch would.
+    const init: RequestInit & { decompress?: boolean } = {
+      method,
+      headers,
+      body: method === "GET" || method === "HEAD" ? undefined : await request.arrayBuffer(),
+      decompress: false,
+    };
+    try {
+      const upstream = await vettedFetch(url, init, { resolve, allow, fetchImpl });
+      return new Response(upstream.body, { status: upstream.status, headers: upstream.headers });
+    } catch (error) {
+      return refuse(502, error instanceof Error ? error.message : String(error));
+    }
+  };
+}
+
+if (import.meta.main) {
+  const { values } = parseArgs({ options: { port: { type: "string" }, host: { type: "string" } } });
+  const token = process.env.SB_EGRESS_TOKEN ?? "";
+  if (!token) {
+    console.error("sproutboat egress: SB_EGRESS_TOKEN is required");
+    process.exit(1);
+  }
+  const server = Bun.serve({
+    hostname: values.host ?? "127.0.0.1",
+    port: Number(values.port ?? process.env.PORT ?? 8070),
+    // A direct fetch has no idle cutoff either; the broker owns the deadline.
+    idleTimeout: 0,
+    fetch: createEgressHandler({ token, allow: egressAllowList(process.env.SB_EGRESS_ALLOW) }),
+  });
+  console.log(`sproutboat egress listening on ${server.url}`);
+}