@sproutboat/wire 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/wire",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -17,7 +17,8 @@
   "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.ts

@@ -24,9 +24,8 @@ 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, egressRefusal } from "@sproutboat/runtime";
-import { lookup } from "node:dns/promises";
-import { isIP } from "node:net";
+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";
 
@@ -124,6 +123,10 @@ export type BrokerOptions = {
   /** #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;
@@ -261,8 +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 ?? ((hostname: string) => lookup(hostname, { all: true }));
+  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 === "";
@@ -1179,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 {
@@ -1194,37 +1214,16 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         if (Array.isArray(pair) && pair.length === 2) headers.set(str(pair[0]), str(pair[1]));
       }
     }
-    // #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.
-    const hostname = url.hostname.replace(/^\[|\]$/g, "");
-    let addresses: Array<{ address: string }>;
-    try {
-      addresses = await resolveHost(hostname);
-    } catch {
-      throw new Error(`could not resolve ${url.hostname}`);
-    }
-    let refusal: string | null = null;
-    const vetted = addresses.find(({ address }) => {
-      const why = egressRefusal(url.hostname, address, egressAllow);
-      refusal ??= why;
-      return why === null;
-    });
-    if (!vetted) throw new Error(refusal ?? `could not resolve ${url.hostname}`);
-    const pinned = new URL(url);
-    pinned.hostname = isIP(vetted.address) === 6 ? `[${vetted.address}]` : vetted.address;
-    headers.set("host", url.host);
-
     const method = str(msg.method || "GET").toUpperCase();
-    const init: RequestInit & { tls?: { serverName: string } } = {
+    const init: RequestInit = {
       method,
       headers,
       body: method === "GET" || method === "HEAD" ? undefined : upstreamBody(msg),
       redirect: "manual",
     };
-    // Bun's TLS option: SNI and certificate checks against the name, not the address.
-    if (url.protocol === "https:" && !isIP(hostname)) init.tls = { serverName: hostname };
-    const res = await doFetch(pinned, init);
+    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}`);
+}