@cosmicdrift/kumiko-framework 0.201.0 → 0.203.0

package/src/http/egress.ts

@@ -0,0 +1,158 @@
+import {
+  assertAllowedHost,
+  assertHttpScheme,
+  type EgressPolicy,
+  type ResolvedHost,
+  resolvePublicHost,
+} from "./policy";
+
+const MAX_INTERNAL_REDIRECTS = 5;
+
+// Bun's fetch() accepts a `tls.servername` request option that upstream
+// bun-types does not declare — see buildPinnedRequest below for why it is
+// needed (TLS SNI must stay pinned to the original hostname, not the
+// resolved IP we connect to).
+type PinnedRequestInit = RequestInit & { tls?: { servername: string } };
+
+// Single exported way to speak outward. The policy is named once, at bind
+// time, and cannot drift from the request that follows it.
+export function egress(
+  policy: EgressPolicy,
+): (raw: string, init?: RequestInit) => Promise<Response> {
+  return (raw, init) => runEgress(policy, raw, init);
+}
+
+async function runEgress(
+  policy: EgressPolicy,
+  raw: string,
+  init: RequestInit | undefined,
+): Promise<Response> {
+  const url = new URL(raw);
+  assertHttpScheme(url);
+
+  if (policy.kind === "internal") {
+    assertAllowedHost(url, policy.allowHosts);
+    return fetchWithAllowlistedRedirects(url, policy.allowHosts, init);
+  }
+
+  // external + tenant-supplied: deny private/reserved/link-local ranges,
+  // pin the connect to the exact address that passed that check (closes the
+  // DNS-rebinding TOCTOU, see buildPinnedRequest), and never follow a
+  // redirect — a 3xx could point anywhere, including back into the denied
+  // ranges above. The caller sees the 3xx response itself and, to follow it,
+  // is expected to call `egress()` again with the Location header — which
+  // re-runs this same resolve-and-pin check against the new host.
+  const resolved = await resolvePublicHost(url);
+  const pinned = buildPinnedRequest(url, resolved, init);
+  const res = await fetch(pinned.url, withManualRedirect(pinned.init));
+  return withOriginalUrl(res, url);
+}
+
+// fetch() reports `res.url` as the address it actually connected to — the
+// pinned IP literal, not the hostname the caller asked for. Left alone, a
+// caller resolving a relative Location header the normal way
+// (`new URL(location, res.url)`) would resolve it against the IP instead of
+// the original host, and the re-invoked egress() call would then pin and
+// SNI-validate against that IP, breaking virtual hosting and TLS for
+// essentially every real server. Overwriting `.url` back to the original
+// request URL keeps that caller pattern working exactly as it would without
+// IP pinning.
+export function withOriginalUrl(res: Response, originalUrl: URL): Response {
+  Object.defineProperty(res, "url", { value: originalUrl.toString(), configurable: true });
+  return res;
+}
+
+// Rewrites the request to connect directly to `resolved.address` — the
+// exact address `resolvePublicHost` just validated — instead of handing
+// `fetch()` the original hostname and letting it resolve again. That second
+// resolution is the DNS-rebinding window: fetch-by-IP removes it entirely,
+// since there is no hostname left for fetch to look up. The original
+// hostname is preserved in the Host header (virtual hosting) and in
+// `tls.servername` (TLS SNI, and certificate validation still checks the
+// real hostname — not the IP we dial).
+export function buildPinnedRequest(
+  url: URL,
+  resolved: ResolvedHost,
+  init: RequestInit | undefined,
+): { url: URL; init: PinnedRequestInit } {
+  const pinnedHost = resolved.family === 6 ? `[${resolved.address}]` : resolved.address;
+  const pinnedUrl = new URL(url.toString());
+  pinnedUrl.hostname = pinnedHost;
+  if (pinnedUrl.hostname !== pinnedHost) {
+    // The WHATWG URL hostname setter silently no-ops on invalid input
+    // instead of throwing. If that ever happened here, the request would
+    // silently fall back to the original (unpinned) hostname — reopening
+    // the rebinding window this function exists to close. Fail loudly.
+    throw new Error(`egress: failed to pin connection to resolved address ${resolved.address}`);
+  }
+
+  const headers = new Headers(init?.headers);
+  headers.set("host", url.host);
+
+  const pinnedInit: PinnedRequestInit = { ...init, headers };
+  if (url.protocol === "https:") {
+    pinnedInit.tls = { servername: url.hostname };
+  }
+  return { url: pinnedUrl, init: pinnedInit };
+}
+
+// Applied last, after spreading the caller's `init` — a caller cannot
+// override the policy's redirect handling by passing its own `redirect`
+// option. Used by both the external/tenant-supplied fetch above and the
+// internal redirect loop below, so it is not part of the package's public
+// barrel (not re-exported from index.ts) but is a plain named export for
+// that shared use and for pinning the invariant directly in
+// ./__tests__/egress.test.ts.
+export function withManualRedirect(init: RequestInit | undefined): RequestInit {
+  return { ...init, redirect: "manual" };
+}
+
+// `internal` is the only kind that permits redirects (it is the only kind
+// with a host allowlist to re-validate them against). Each hop's Location
+// header is resolved and checked against the same allowlist AND restricted
+// to the current hop's host before it is followed, capped at
+// MAX_INTERNAL_REDIRECTS to avoid an infinite loop.
+// `init` (method, body, headers) is replayed verbatim on every hop — unlike
+// a browser, this does not downgrade POST to GET on a 301/302/303. That is
+// deliberate for an allowlisted internal target: a silent method change is
+// its own class of surprise, and a streamed body would fail on the second
+// hop either way. Replaying headers verbatim is also why redirects may not
+// cross hosts (see below): a second allowlisted host must not receive the
+// first host's Authorization/Cookie headers.
+async function fetchWithAllowlistedRedirects(
+  url: URL,
+  allowHosts: readonly string[],
+  init: RequestInit | undefined,
+): Promise<Response> {
+  let current = url;
+  for (let hop = 0; hop <= MAX_INTERNAL_REDIRECTS; hop++) {
+    const res = await fetch(current, withManualRedirect(init));
+    if (res.status < 300 || res.status >= 400) return res;
+    const location = res.headers.get("location");
+    if (!location) return res; // 3xx without Location — nothing to follow
+
+    let next: URL;
+    try {
+      next = new URL(location, current);
+    } catch {
+      throw new Error(
+        `egress(internal): redirect Location header is not a resolvable URL: ${location}`,
+      );
+    }
+    assertHttpScheme(next);
+    // `init.headers` (e.g. Authorization, Cookie) is replayed verbatim on
+    // every hop above. Without this check, one allowlisted host redirecting
+    // to a second, different allowlisted host would forward the caller's
+    // credentials to it — a classic redirect-credential-leak. Restricting
+    // hops to the same host keeps the realistic internal case (path
+    // rewrite, trailing slash) working while closing that leak.
+    if (next.hostname.toLowerCase() !== current.hostname.toLowerCase()) {
+      throw new Error(
+        `egress(internal): redirect crosses host (${current.hostname} -> ${next.hostname}), not followed`,
+      );
+    }
+    assertAllowedHost(next, allowHosts);
+    current = next;
+  }
+  throw new Error(`egress(internal): exceeded ${MAX_INTERNAL_REDIRECTS} redirects`);
+}

package/src/http/index.ts

@@ -0,0 +1,2 @@
+export { egress } from "./egress";
+export type { EgressPolicy } from "./policy";

package/src/http/policy.ts

@@ -0,0 +1,193 @@
+// Egress trust boundary. `EgressPolicy` and the checks below back the single
+// exported way to speak outward, `egress()` in ./egress.ts — this module and
+// its exports stay off the package's public barrel (index.ts) on purpose:
+// call sites bind a policy once via `egress(policy)` and never see the range
+// table or the allowlist check directly.
+//
+// `external` and `tenant-supplied` resolve to the identical set of checks
+// below (deny private/reserved/link-local + no redirects). They stay
+// separate policy kinds because they carry different trust semantics — a
+// tenant-controlled URL is adversary-input in a way a hardcoded external
+// endpoint is not.
+//
+// DNS-rebinding protection: `resolvePublicHost` resolves the hostname
+// exactly once, validates every returned address, and hands back the one
+// address ./egress.ts connects to directly (fetch-by-IP, with the original
+// hostname preserved for the Host header and TLS SNI/cert validation).
+// There is no second resolution for an attacker-controlled DNS answer to
+// swap in between check and connect — see `resolvePublicHost` below for the
+// mechanism and ../__tests__/egress.test.ts / policy.test.ts for the tests
+// pinning it.
+
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+export type EgressPolicy =
+  | { readonly kind: "external" }
+  | { readonly kind: "internal"; readonly allowHosts: readonly string[] }
+  | { readonly kind: "tenant-supplied" };
+
+export function isBlockedIp(ip: string): boolean {
+  const kind = isIP(ip);
+  if (kind === 4) return isBlockedV4(ip);
+  if (kind === 6) return isBlockedV6(ip);
+  return true; // not parseable as an IP -> fail closed
+}
+
+function inRange(n: number, [min, max]: readonly [number, number]): boolean {
+  return n >= min && n <= max;
+}
+
+// Each entry: first-octet range, and an optional second-octet range for
+// ranges narrower than a full /8. Table form keeps the range list scannable
+// as data rather than as a chain of near-identical `if`s.
+const BLOCKED_V4_RANGES: readonly {
+  readonly a: readonly [number, number];
+  readonly b?: readonly [number, number];
+}[] = [
+  { a: [0, 0] }, // 0.0.0.0/8 "this host"
+  { a: [10, 10] }, // 10/8 private
+  { a: [127, 127] }, // loopback
+  { a: [169, 169], b: [254, 254] }, // link-local + cloud metadata (169.254.169.254)
+  { a: [172, 172], b: [16, 31] }, // 172.16/12 private
+  { a: [192, 192], b: [168, 168] }, // 192.168/16 private
+  { a: [100, 100], b: [64, 127] }, // 100.64/10 CGNAT
+  { a: [224, 255] }, // multicast/reserved
+];
+
+function isBlockedV4(ip: string): boolean {
+  const [a = 0, b = 0] = ip.split(".").map(Number);
+  return BLOCKED_V4_RANGES.some(
+    (range) => inRange(a, range.a) && (range.b === undefined || inRange(b, range.b)),
+  );
+}
+
+// WHATWG URL host-parsing always serializes IPv6 into the canonical
+// compressed lowercase form (RFC 5952) regardless of the input shape —
+// uncompressed groups, embedded IPv4-dotted notation, mixed case all collapse
+// to one string. isBlockedV6 below only has to handle that one shape, so any
+// caller-supplied IPv6 literal is normalized through `new URL()` first.
+function canonicalIPv6(ip: string): string {
+  try {
+    return new URL(`http://[${ip}]/`).hostname.replace(/^\[/, "").replace(/\]$/, "");
+  } catch {
+    return ip; // unparsable — falls through to the (fail-closed) checks below
+  }
+}
+
+// Two 16-bit hex groups, as WHATWG URL serializes an embedded IPv4 address
+// inside an IPv6 literal, decoded back into the v4 range rules.
+function isBlockedHexPair(hi: string | undefined, lo: string | undefined): boolean {
+  const hiNum = Number.parseInt(hi ?? "0", 16);
+  const loNum = Number.parseInt(lo ?? "0", 16);
+  return isBlockedV4(`${hiNum >>> 8}.${hiNum & 0xff}.${loNum >>> 8}.${loNum & 0xff}`);
+}
+
+const BLOCKED_V6_EXACT = new Set(["::1", "::"]); // loopback / unspecified
+
+// All three ranges expressed on the first 16-bit group ("head"), so they
+// share one table instead of three near-identical `if`s:
+//   fc00::/7   unique-local           -> head 0xfc00-0xfdff
+//   fe80::/10  link-local             -> head 0xfe80-0xfebf
+//   fec0::/10  deprecated site-local (RFC 3879, 2004) — no DNS server hands
+//              this out today, but this is an exported security boundary,
+//              so block it rather than lean on the deprecation.
+const BLOCKED_V6_HEAD_RANGES: readonly (readonly [number, number])[] = [
+  [0xfc00, 0xfdff],
+  [0xfe80, 0xfebf],
+  [0xfec0, 0xfeff],
+];
+
+function isBlockedV6(ip: string): boolean {
+  const lower = canonicalIPv6(ip.toLowerCase());
+  if (BLOCKED_V6_EXACT.has(lower)) return true;
+  const mappedDotted = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (mappedDotted) return isBlockedV4(mappedDotted[1] ?? "0.0.0.0"); // IPv4-mapped -> v4 rules
+  const mappedHex = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (mappedHex) return isBlockedHexPair(mappedHex[1], mappedHex[2]); // IPv4-mapped, hex form
+  // NAT64 well-known prefix (RFC 6052) embeds an IPv4 address in the low 32
+  // bits, same trick as the IPv4-mapped form above with a different prefix —
+  // a known SSRF-filter-bypass technique on NAT64/DNS64 networks.
+  const nat64 = lower.match(/^64:ff9b::([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (nat64) return isBlockedHexPair(nat64[1], nat64[2]);
+  // 6to4 (RFC 3056) embeds an IPv4 address directly after the 2002: prefix.
+  const sixToFour = lower.match(/^2002:([0-9a-f]{1,4}):([0-9a-f]{1,4})(?::|$)/);
+  if (sixToFour) return isBlockedHexPair(sixToFour[1], sixToFour[2]);
+  const head = Number.parseInt(lower.split(":")[0] || "0", 16);
+  return BLOCKED_V6_HEAD_RANGES.some((range) => inRange(head, range));
+}
+
+function stripBrackets(host: string): string {
+  return host.replace(/^\[/, "").replace(/\]$/, "");
+}
+
+export function assertHttpScheme(url: URL): void {
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`egress: unsupported scheme ${url.protocol}`);
+  }
+}
+
+export interface ResolvedHost {
+  readonly address: string;
+  readonly family: 4 | 6;
+}
+
+// Denies private/reserved/link-local ranges for `external` and
+// `tenant-supplied`, and pins the exact address ./egress.ts must connect to.
+// Resolves the hostname's A/AAAA records (or reads the literal IP directly),
+// rejects if ANY resolved address falls in a denied range — a host with one
+// public and one private record must not pass — and returns ONE validated
+// address from that same resolution. Reusing that address for the connect,
+// instead of letting `fetch()` resolve the hostname again, is what closes
+// the DNS-rebinding window: there is no second lookup left for an
+// attacker-controlled DNS server to answer differently.
+//
+// `lookupFn` defaults to the real resolver and exists only so tests can pin
+// deterministic, network-free answers — production call sites never pass it.
+export async function resolvePublicHost(
+  url: URL,
+  lookupFn: typeof lookup = lookup,
+): Promise<ResolvedHost> {
+  if (url.username || url.password) {
+    throw new Error("egress: URLs with embedded credentials are not supported");
+  }
+  const host = stripBrackets(url.hostname);
+  const ipVersion = isIP(host);
+  if (ipVersion !== 0) {
+    if (isBlockedIp(host)) throw new Error(`egress: host is not a public address: ${host}`);
+    return { address: host, family: ipVersion === 6 ? 6 : 4 };
+  }
+  let addresses: readonly { readonly address: string; readonly family: number }[];
+  try {
+    addresses = await lookupFn(host, { all: true });
+  } catch {
+    throw new Error(`egress: DNS resolution failed for host: ${host}`);
+  }
+  if (addresses.length === 0) {
+    throw new Error(`egress: DNS resolution returned no records for host: ${host}`);
+  }
+  const blocked = addresses.find((a) => isBlockedIp(a.address));
+  if (blocked) {
+    throw new Error(`egress: host resolves to a non-public address: ${host} -> ${blocked.address}`);
+  }
+  const [chosen] = addresses;
+  if (!chosen) {
+    throw new Error(`egress: DNS resolution returned no records for host: ${host}`);
+  }
+  return { address: chosen.address, family: chosen.family === 6 ? 6 : 4 };
+}
+
+// Explicit allowlist check for `internal` — the hostname (not the resolved
+// IP) must appear verbatim (case-insensitive) in `allowHosts`. No range
+// check: `internal` targets are deliberately private/cluster-local.
+// `allowHosts` is a host allowlist, not an origin allowlist: it is
+// deliberately port- and scheme-agnostic (`svc.internal` also admits
+// `svc.internal:9999` over http or https) — `EgressPolicy` doesn't carry a
+// port or scheme in its shape, so there is nothing more specific to check.
+export function assertAllowedHost(url: URL, allowHosts: readonly string[]): void {
+  const host = stripBrackets(url.hostname).toLowerCase();
+  const allowed = allowHosts.some((h) => h.toLowerCase() === host);
+  if (!allowed) {
+    throw new Error(`egress: host not in allowlist: ${host}`);
+  }
+}