@cosmicdrift/kumiko-framework 0.282.0 → 0.284.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.282.0",
+  "version": "0.284.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.282.0",
+    "@cosmicdrift/kumiko-http": "0.284.0",
+    "@cosmicdrift/kumiko-types": "0.284.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.282.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.284.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.283.0",
+    "type": "improvement",
+    "title": "loadAggregate and ctx.fetchForWriting gain an optional aggregateType filter, plus handle.hasEvent(...)",
+    "detail": "`loadAggregate(db, aggregateId, tenantId, options)` accepts an optional `options.aggregateType`. Without it, behavior is unchanged — every event on the aggregateId's stream is returned, same as today. With it, only events matching that `aggregateType` are returned, so two features that happen to share an `aggregateId` (e.g. reusing an upstream id as the key for a second, unrelated aggregate type) no longer leak each other's events into a business-rule check that only expected its own type.\n`ctx.fetchForWriting({ aggregateId, aggregateType, ... })` now passes `aggregateType` through to `loadAggregate`, so `handle.events` is scoped the same way. The returned `AggregateStreamHandle` also gains `hasEvent(type: string): boolean`, an idempotency check against the fetch-time `events` snapshot — cheaper and safer than an `appendIfAbsent`-style helper, which risks masking a genuine optimistic-concurrency conflict as an already-applied write.",
+    "migration": "No action required — purely additive. Every existing loadAggregate/fetchForWriting\ncall keeps its current behavior; opt into the aggregateType filter only where an\naggregateId is shared across more than one aggregate type."
+  },
   {
     "version": "0.281.0",
     "type": "breaking",

package/src/event-store/__tests__/event-store.integration.test.ts

@@ -361,6 +361,97 @@ describe("event-store: tenant isolation", () => {
   });
 });
 
+describe("event-store: loadAggregate aggregateType filter (#2979)", () => {
+  test("without aggregateType, both types on one aggregateId are returned (no breaking change)", async () => {
+    const aggregateId = uuid();
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "cart",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "cart.created",
+      payload: {},
+      metadata: { userId: userA },
+    });
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "reservation",
+      tenantId: tenantA,
+      expectedVersion: 1,
+      type: "reservation.created",
+      payload: {},
+      metadata: { userId: userA },
+    });
+
+    const events = await loadAggregate(testDb.db, aggregateId, tenantA);
+    expect(events.map((e) => e.type)).toEqual(["cart.created", "reservation.created"]);
+  });
+
+  test("with aggregateType, a foreign-type event on the same aggregateId is excluded (solon-style id collision)", async () => {
+    const aggregateId = uuid();
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "cart",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "cart.created",
+      payload: {},
+      metadata: { userId: userA },
+    });
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "reservation",
+      tenantId: tenantA,
+      expectedVersion: 1,
+      type: "reservation.created",
+      payload: {},
+      metadata: { userId: userA },
+    });
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "cart",
+      tenantId: tenantA,
+      expectedVersion: 2,
+      type: "cart.itemAdded",
+      payload: {},
+      metadata: { userId: userA },
+    });
+
+    const cartEvents = await loadAggregate(testDb.db, aggregateId, tenantA, {
+      aggregateType: "cart",
+    });
+    expect(cartEvents.map((e) => e.type)).toEqual(["cart.created", "cart.itemAdded"]);
+
+    const reservationEvents = await loadAggregate(testDb.db, aggregateId, tenantA, {
+      aggregateType: "reservation",
+    });
+    expect(reservationEvents.map((e) => e.type)).toEqual(["reservation.created"]);
+  });
+
+  test("aggregateType filter does not weaken tenant isolation", async () => {
+    const aggregateId = uuid();
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "cart",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "cart.created",
+      payload: {},
+      metadata: { userId: userA },
+    });
+
+    const crossTenant = await loadAggregate(testDb.db, aggregateId, tenantB, {
+      aggregateType: "cart",
+    });
+    expect(crossTenant).toHaveLength(0);
+
+    const sameTenant = await loadAggregate(testDb.db, aggregateId, tenantA, {
+      aggregateType: "cart",
+    });
+    expect(sameTenant).toHaveLength(1);
+  });
+});
+
 describe("event-store: requestId is a trace marker (no DB-level uniqueness)", () => {
   test("same (tenant, requestId) twice → both events persist, no collision", async () => {
     // Idempotency is an HTTP-level concern, handled via Redis in

package/src/event-store/event-store.ts

@@ -208,11 +208,17 @@ function buildStoredEvent(
 // { includeArchived: true } for ops tools / audit that must see the tail
 // of an archived aggregate. The archive check is a single indexed lookup —
 // negligible on the hot path.
+//
+// { aggregateType } is opt-in: without it, a stream is loaded by
+// aggregateId alone, matching prior behavior. Callers that share id
+// generation across multiple aggregate types on the same id (e.g. a solon-
+// style collision) must pass it to avoid folding a foreign type's events
+// into the loaded stream.
 export async function loadAggregate(
   db: DbRunner,
   aggregateId: string,
   tenantId: TenantId,
-  options?: { readonly includeArchived?: boolean },
+  options?: { readonly includeArchived?: boolean; readonly aggregateType?: string },
 ): Promise<readonly StoredEvent[]> {
   if (!options?.includeArchived) {
     const archived = await isStreamArchived(db, tenantId, aggregateId);
@@ -221,7 +227,9 @@ export async function loadAggregate(
   const rows = await selectMany<SelectedEvent>(
     db,
     eventsTable,
-    { aggregateId, tenantId },
+    options?.aggregateType
+      ? { aggregateId, tenantId, aggregateType: options.aggregateType }
+      : { aggregateId, tenantId },
     { orderBy: { col: "version", direction: "asc" } },
   );
   return rows.map(toStoredEvent);

package/src/http/index.ts

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

package/src/pipeline/__tests__/fetch-for-writing.integration.test.ts

@@ -14,7 +14,7 @@ import { asRawClient } from "../../db/query-api";
 import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import { UnprocessableError, writeFailure } from "../../errors";
-import { loadAggregate } from "../../event-store";
+import { append, loadAggregate } from "../../event-store";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
 
 // --- Feature ---
@@ -109,6 +109,28 @@ const cartFeature = defineFeature("f4w", (r) => {
     { access: { roles: ["Admin"] } },
   );
 
+  // Reports the raw event types + a hasEvent probe seen through the handle —
+  // lets a test assert on both aggregateType-scoping and idempotency-checks
+  // without adding another executor.
+  r.writeHandler(
+    "cart:fetch-info",
+    z.object({ id: z.uuid(), probeType: z.string() }),
+    async (event, ctx) => {
+      const stream = await ctx.fetchForWriting({
+        aggregateId: event.payload.id,
+        aggregateType: "f4wCart",
+      });
+      return {
+        isSuccess: true as const,
+        data: {
+          types: stream.events.map((e) => e.type),
+          hasProbe: stream.hasEvent(event.payload.probeType),
+        },
+      };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
   // Fetch with expectedVersion — OCC gate for external callers.
   r.writeHandler(
     "cart:add-with-occ",
@@ -282,4 +304,61 @@ describe("Runde 3 / C.2a — ctx.fetchForWriting", () => {
     expect(types).toContain("f4w:event:checked-out");
     expect(types).not.toContain("f4w:event:item-added");
   });
+
+  test("#2979: a foreign-type event planted on the same aggregateId is excluded from the handle", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "f4w:write:cart:create",
+      { customer: "grace" },
+      admin,
+    );
+
+    // Solon-style id collision: another aggregateType lands its own event on
+    // the exact same aggregateId, outside the cart executor entirely.
+    await append(stack.db, {
+      aggregateId: created.id,
+      aggregateType: "reservation",
+      tenantId: admin.tenantId,
+      expectedVersion: 1,
+      type: "reservation:event:created",
+      payload: {},
+      metadata: { userId: String(admin.id) },
+    });
+
+    const info = await stack.http.writeOk<{ types: string[]; hasProbe: boolean }>(
+      "f4w:write:cart:fetch-info",
+      { id: created.id, probeType: "reservation:event:created" },
+      admin,
+    );
+
+    expect(info.types).toEqual(["f4wCart.created"]);
+    expect(info.hasProbe).toBe(false);
+  });
+
+  test("#2979: hasEvent reflects the fetch-time snapshot for the handle's own aggregateType", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "f4w:write:cart:create",
+      { customer: "heidi" },
+      admin,
+    );
+
+    const before = await stack.http.writeOk<{ hasProbe: boolean }>(
+      "f4w:write:cart:fetch-info",
+      { id: created.id, probeType: "f4w:event:checked-out" },
+      admin,
+    );
+    expect(before.hasProbe).toBe(false);
+
+    await stack.http.writeOk(
+      "f4w:write:cart:checkout",
+      { id: created.id, totalCents: 1500 },
+      admin,
+    );
+
+    const after = await stack.http.writeOk<{ hasProbe: boolean }>(
+      "f4w:write:cart:fetch-info",
+      { id: created.id, probeType: "f4w:event:checked-out" },
+      admin,
+    );
+    expect(after.hasProbe).toBe(true);
+  });
 });

package/src/pipeline/dispatch-shared.ts

@@ -549,7 +549,9 @@ export async function buildHandlerContext(
       // when the caller just wants to append — but most callers also want
       // the events (business-rule checks), so fetch both in parallel.
       const [storedEvents, fetchedVersion] = await Promise.all([
-        loadAggregate(dbSource, args.aggregateId, user.tenantId),
+        loadAggregate(dbSource, args.aggregateId, user.tenantId, {
+          aggregateType: args.aggregateType,
+        }),
         getStreamVersion(dbSource, args.aggregateId, user.tenantId),
       ]);
       const events = await upcastStoredEvents(storedEvents, registry.getEventUpcasters(), {
@@ -596,6 +598,7 @@ export async function buildHandlerContext(
           return handleVersion;
         },
         appendOne,
+        hasEvent: (type: string) => events.some((e) => e.type === type),
       };
     },
     loadAggregate: async (

package/src/http/__tests__/egress-real-endpoint.integration.test.ts

@@ -1,37 +0,0 @@
-import { beforeAll, describe, expect, test } from "bun:test";
-import { lookup } from "node:dns/promises";
-import { egress } from "../egress";
-
-// fw#2149 DoD requires proving TLS/SNI validation stays intact against a
-// real HTTPS endpoint, not just a mock — the self-signed-cert tests in
-// egress.test.ts pin the fetch-by-pinned-IP mechanism, this test pins it
-// against a certificate chain issued by a real, publicly trusted CA.
-// example.com is IANA-reserved and kept up for exactly this kind of use.
-const REAL_HOST = "example.com";
-
-let networkAvailable = true;
-
-beforeAll(async () => {
-  try {
-    await lookup(REAL_HOST);
-  } catch {
-    networkAvailable = false;
-  }
-});
-
-describe("egress external: real HTTPS endpoint", () => {
-  test("connects through the pinned IP and validates the real certificate chain", async () => {
-    if (!networkAvailable) {
-      console.warn(
-        `egress real-endpoint test skipped: DNS resolution for ${REAL_HOST} failed (no network in this environment)`,
-      );
-      return;
-    }
-
-    const fetchIt = egress({ kind: "external" });
-    const res = await fetchIt(`https://${REAL_HOST}/`);
-
-    expect(res.status).toBe(200);
-    expect(await res.text()).toContain("Example Domain");
-  });
-});

package/src/http/__tests__/egress.test.ts

@@ -1,440 +0,0 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { execFileSync } from "node:child_process";
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { buildPinnedRequest, egress, withManualRedirect, withOriginalUrl } from "../egress";
-
-let server: ReturnType<typeof Bun.serve>;
-let port: number;
-const requestCounts = new Map<string, number>();
-
-function countedResponse(path: string, respond: () => Response): Response {
-  requestCounts.set(path, (requestCounts.get(path) ?? 0) + 1);
-  return respond();
-}
-
-beforeAll(() => {
-  server = Bun.serve({
-    hostname: "127.0.0.1",
-    port: 0,
-    fetch(req) {
-      const url = new URL(req.url);
-      if (url.pathname === "/ok") {
-        return countedResponse("/ok", () => new Response("hello", { status: 200 }));
-      }
-      if (url.pathname === "/final") {
-        return countedResponse("/final", () => new Response("final", { status: 200 }));
-      }
-      if (url.pathname === "/allowed-redirect") {
-        return countedResponse(
-          "/allowed-redirect",
-          () =>
-            new Response(null, {
-              status: 302,
-              headers: { location: `http://127.0.0.1:${port}/final` },
-            }),
-        );
-      }
-      if (url.pathname === "/blocked-redirect") {
-        // Same physical server, different hostname string ("localhost" is
-        // not in the allowlist used below even though it resolves here too).
-        return countedResponse(
-          "/blocked-redirect",
-          () =>
-            new Response(null, {
-              status: 302,
-              headers: { location: `http://localhost:${port}/final` },
-            }),
-        );
-      }
-      if (url.pathname === "/cross-host-redirect") {
-        // Redirects to a *different* allowlisted host (not just a
-        // disallowed one) — this must still be rejected even though both
-        // hosts individually pass assertAllowedHost, because init.headers
-        // are replayed on every hop and must not leak across hosts.
-        return countedResponse(
-          "/cross-host-redirect",
-          () =>
-            new Response(null, {
-              status: 302,
-              headers: { location: `http://localhost:${port}/final` },
-            }),
-        );
-      }
-      if (url.pathname === "/redirect-loop") {
-        return countedResponse(
-          "/redirect-loop",
-          () =>
-            new Response(null, {
-              status: 302,
-              headers: { location: `http://127.0.0.1:${port}/redirect-loop` },
-            }),
-        );
-      }
-      return countedResponse(url.pathname, () => new Response("not found", { status: 404 }));
-    },
-  });
-  if (typeof server.port !== "number") {
-    throw new Error("test server did not report a bound port");
-  }
-  port = server.port;
-});
-
-afterAll(() => {
-  server.stop(true);
-});
-
-describe("egress internal", () => {
-  test("fetches an allowlisted host directly", async () => {
-    const fetchIt = egress({ kind: "internal", allowHosts: ["127.0.0.1"] });
-    const res = await fetchIt(`http://127.0.0.1:${port}/ok`);
-    expect(res.status).toBe(200);
-    expect(await res.text()).toBe("hello");
-  });
-
-  test("rejects a host not in the allowlist without making any request", async () => {
-    const before = requestCounts.get("/ok") ?? 0;
-    const fetchIt = egress({ kind: "internal", allowHosts: ["127.0.0.1"] });
-    await expect(fetchIt(`http://localhost:${port}/ok`)).rejects.toThrow();
-    expect(requestCounts.get("/ok") ?? 0).toBe(before); // never dialed
-  });
-
-  test("follows a redirect to a host that stays inside the allowlist", async () => {
-    const fetchIt = egress({ kind: "internal", allowHosts: ["127.0.0.1"] });
-    const res = await fetchIt(`http://127.0.0.1:${port}/allowed-redirect`);
-    expect(res.status).toBe(200);
-    expect(await res.text()).toBe("final");
-    expect(requestCounts.get("/allowed-redirect")).toBeGreaterThan(0);
-    expect(requestCounts.get("/final")).toBeGreaterThan(0);
-  });
-
-  test("rejects a redirect whose target host falls outside the allowlist, without following it", async () => {
-    const before = requestCounts.get("/final") ?? 0;
-    const fetchIt = egress({ kind: "internal", allowHosts: ["127.0.0.1"] });
-    await expect(fetchIt(`http://127.0.0.1:${port}/blocked-redirect`)).rejects.toThrow();
-    expect(requestCounts.get("/final") ?? 0).toBe(before); // redirect target never dialed
-  });
-
-  test("does not silently follow a disallowed redirect even if the caller passes redirect: 'follow'", async () => {
-    const fetchIt = egress({ kind: "internal", allowHosts: ["127.0.0.1"] });
-    await expect(
-      fetchIt(`http://127.0.0.1:${port}/blocked-redirect`, { redirect: "follow" }),
-    ).rejects.toThrow();
-  });
-
-  test("rejects a redirect to a different host even when both hosts are allowlisted", async () => {
-    const before = requestCounts.get("/final") ?? 0;
-    const fetchIt = egress({ kind: "internal", allowHosts: ["127.0.0.1", "localhost"] });
-    await expect(fetchIt(`http://127.0.0.1:${port}/cross-host-redirect`)).rejects.toThrow(
-      /crosses host/,
-    );
-    expect(requestCounts.get("/final") ?? 0).toBe(before); // never dialed the second host
-  });
-
-  test("throws once the redirect hop cap is exceeded", async () => {
-    const fetchIt = egress({ kind: "internal", allowHosts: ["127.0.0.1"] });
-    await expect(fetchIt(`http://127.0.0.1:${port}/redirect-loop`)).rejects.toThrow(/redirects/);
-  });
-});
-
-describe("egress external / tenant-supplied", () => {
-  test.each(["external", "tenant-supplied"] as const)(
-    "%s denies a loopback target without connecting to it",
-    async (kind) => {
-      const before = requestCounts.get("/ok") ?? 0;
-      const fetchIt = egress(
-        kind === "external" ? { kind: "external" } : { kind: "tenant-supplied" },
-      );
-      await expect(fetchIt(`http://127.0.0.1:${port}/ok`)).rejects.toThrow();
-      expect(requestCounts.get("/ok") ?? 0).toBe(before); // guard fired before any connection
-    },
-  );
-
-  test.each(["external", "tenant-supplied"] as const)(
-    "%s rejects a non-http(s) scheme",
-    async (kind) => {
-      const fetchIt = egress(
-        kind === "external" ? { kind: "external" } : { kind: "tenant-supplied" },
-      );
-      await expect(fetchIt("file:///etc/passwd")).rejects.toThrow();
-    },
-  );
-
-  // `external`/`tenant-supplied` never auto-follow a redirect (see
-  // withManualRedirect above) — the caller sees the 3xx itself and is
-  // expected to call egress() again with the Location header to follow it.
-  // That means every hop is a fresh egress() call, and this pins that the
-  // DNS-rebinding-safe host check applies to a redirect target exactly the
-  // way it applies to any other URL — not a special case that could be
-  // missed.
-  test.each(["external", "tenant-supplied"] as const)(
-    "%s: following a redirect Location by calling egress() again re-validates the new host",
-    async (kind) => {
-      const fetchIt = egress(
-        kind === "external" ? { kind: "external" } : { kind: "tenant-supplied" },
-      );
-      const redirectLocation = "http://169.254.169.254/latest/meta-data/"; // simulated hop target
-      await expect(fetchIt(redirectLocation)).rejects.toThrow();
-    },
-  );
-});
-
-describe("withOriginalUrl", () => {
-  test("overwrites Response.url to the original request URL, not the pinned IP", async () => {
-    const echoServer = Bun.serve({
-      hostname: "127.0.0.1",
-      port: 0,
-      fetch: () => new Response("ok"),
-    });
-    try {
-      const originalUrl = new URL("http://vhost.example/some/path");
-      const pinned = buildPinnedRequest(
-        originalUrl,
-        { address: "127.0.0.1", family: 4 },
-        undefined,
-      );
-      pinned.url.port = String(echoServer.port);
-
-      const res = await fetch(pinned.url, pinned.init);
-      expect(res.url).not.toBe(originalUrl.toString()); // sanity: fetch itself reports the pinned IP
-
-      expect(withOriginalUrl(res, originalUrl).url).toBe(originalUrl.toString());
-    } finally {
-      echoServer.stop(true);
-    }
-  });
-
-  // This is the exact caller pattern runEgress's own comment promises:
-  // "call egress() again with the Location header". A relative Location
-  // resolved against the pinned-IP res.url would land on the IP, and the
-  // resulting egress() call would then pin/SNI-validate against that IP
-  // instead of a real hostname — this pins that it resolves against the
-  // original host instead.
-  test("a relative redirect Location resolves against the original host, not the pinned IP", async () => {
-    const redirectServer = Bun.serve({
-      hostname: "127.0.0.1",
-      port: 0,
-      fetch: () => new Response(null, { status: 302, headers: { location: "/next" } }),
-    });
-    try {
-      const originalUrl = new URL("http://vhost.example/start");
-      const pinned = buildPinnedRequest(
-        originalUrl,
-        { address: "127.0.0.1", family: 4 },
-        undefined,
-      );
-      pinned.url.port = String(redirectServer.port);
-
-      const res = withOriginalUrl(
-        await fetch(pinned.url, withManualRedirect(pinned.init)),
-        originalUrl,
-      );
-      const location = res.headers.get("location");
-      if (!location) throw new Error("test server did not send a Location header");
-      const next = new URL(location, res.url);
-
-      expect(next.hostname).toBe("vhost.example"); // not the pinned 127.0.0.1
-      expect(next.pathname).toBe("/next");
-    } finally {
-      redirectServer.stop(true);
-    }
-  });
-});
-
-describe("buildPinnedRequest", () => {
-  test("sends fetch an IP-literal URL, never the original hostname", () => {
-    const url = new URL("https://attacker-controlled.example/path?x=1");
-    const pinned = buildPinnedRequest(url, { address: "203.0.113.5", family: 4 }, undefined);
-
-    expect(pinned.url.hostname).toBe("203.0.113.5");
-    expect(pinned.url.pathname).toBe("/path");
-    expect(pinned.url.search).toBe("?x=1");
-    // Nothing hostname-shaped survives into the request fetch() receives —
-    // there is no hostname left for fetch to resolve a second time.
-    expect(pinned.url.href).not.toContain("attacker-controlled.example");
-  });
-
-  test("preserves the original hostname in the Host header", () => {
-    const url = new URL("https://attacker-controlled.example/");
-    const pinned = buildPinnedRequest(url, { address: "203.0.113.5", family: 4 }, undefined);
-
-    expect(new Headers(pinned.init.headers).get("host")).toBe("attacker-controlled.example");
-  });
-
-  test("preserves the original hostname in tls.servername for https", () => {
-    const url = new URL("https://attacker-controlled.example/");
-    const pinned = buildPinnedRequest(url, { address: "203.0.113.5", family: 4 }, undefined);
-
-    expect(pinned.init.tls).toEqual({ servername: "attacker-controlled.example" });
-  });
-
-  test("omits tls for http (nothing to pin SNI for)", () => {
-    const url = new URL("http://attacker-controlled.example/");
-    const pinned = buildPinnedRequest(url, { address: "203.0.113.5", family: 4 }, undefined);
-
-    expect(pinned.init.tls).toBeUndefined();
-  });
-
-  test("pins an IPv6 address using bracket notation", () => {
-    const url = new URL("https://example.com/");
-    const pinned = buildPinnedRequest(
-      url,
-      { address: "2606:4700:10::6814:179a", family: 6 },
-      undefined,
-    );
-
-    expect(pinned.url.hostname).toBe("[2606:4700:10::6814:179a]");
-  });
-
-  test("overrides a caller-supplied Host header rather than merging it", () => {
-    const url = new URL("https://real-host.example/");
-    const pinned = buildPinnedRequest(
-      url,
-      { address: "203.0.113.5", family: 4 },
-      { headers: { Host: "spoofed.example" } },
-    );
-
-    expect(new Headers(pinned.init.headers).get("host")).toBe("real-host.example");
-  });
-
-  test("preserves a non-default port in both the pinned URL and the Host header", () => {
-    const url = new URL("https://attacker-controlled.example:9443/");
-    const pinned = buildPinnedRequest(url, { address: "203.0.113.5", family: 4 }, undefined);
-
-    expect(pinned.url.port).toBe("9443");
-    expect(new Headers(pinned.init.headers).get("host")).toBe("attacker-controlled.example:9443");
-  });
-});
-
-describe("egress external / tenant-supplied: connects to the pinned address for real", () => {
-  test("the Host header set by buildPinnedRequest reaches the origin unmodified", async () => {
-    const echo = Bun.serve({
-      hostname: "127.0.0.1",
-      port: 0,
-      fetch: (req) => new Response(req.headers.get("host") ?? "MISSING"),
-    });
-    try {
-      const url = new URL(`http://vhost.example/`);
-      const pinned = buildPinnedRequest(url, { address: "127.0.0.1", family: 4 }, undefined);
-      pinned.url.port = String(echo.port);
-      const res = await fetch(pinned.url, pinned.init);
-      expect(await res.text()).toBe("vhost.example");
-    } finally {
-      echo.stop(true);
-    }
-  });
-});
-
-describe("egress external / tenant-supplied: TLS/SNI stay intact when connecting by pinned IP", () => {
-  const CERT_HOSTNAME = "kumiko-egress-test.local";
-
-  let tlsServer: ReturnType<typeof Bun.serve>;
-  let cert: Buffer;
-  let certDir: string;
-
-  beforeAll(() => {
-    // Generated fresh per test run rather than checked in as a fixture —
-    // a committed .pem/.key pair (even a self-signed, test-only one) is
-    // what secret scanners and this repo's push protection are watching
-    // for, and there is no precedent for one in this repo's history.
-    certDir = mkdtempSync(join(tmpdir(), "kumiko-egress-tls-test-"));
-    const certPath = join(certDir, "cert.pem");
-    const keyPath = join(certDir, "key.pem");
-    execFileSync("openssl", [
-      "req",
-      "-x509",
-      "-newkey",
-      "rsa:2048",
-      "-nodes",
-      "-days",
-      "1",
-      "-keyout",
-      keyPath,
-      "-out",
-      certPath,
-      "-subj",
-      `/CN=${CERT_HOSTNAME}`,
-      "-addext",
-      `subjectAltName=DNS:${CERT_HOSTNAME}`,
-    ]);
-    cert = readFileSync(certPath);
-    const key = readFileSync(keyPath);
-
-    tlsServer = Bun.serve({
-      hostname: "127.0.0.1",
-      port: 0,
-      tls: { cert, key },
-      fetch: () => new Response("ok"),
-    });
-  });
-
-  afterAll(() => {
-    tlsServer.stop(true);
-    rmSync(certDir, { recursive: true, force: true });
-  });
-
-  // buildPinnedRequest always sets tls.servername itself (it must not be
-  // overridable by the caller, same as the redirect mode below) — so `ca`
-  // is added to its result afterwards, purely to make this self-signed
-  // fixture trusted for the test. Production call sites never set `ca`;
-  // they rely on the system trust store, which the real-endpoint
-  // integration test below exercises.
-  function trustFixtureCa(init: RequestInit & { tls?: { servername: string } }): RequestInit {
-    return { ...init, tls: { ...init.tls, ca: cert } } as RequestInit;
-  }
-
-  test("validates the certificate against the pinned servername and succeeds when it matches", async () => {
-    const url = new URL(`https://${CERT_HOSTNAME}/`);
-    const pinned = buildPinnedRequest(url, { address: "127.0.0.1", family: 4 }, undefined);
-    pinned.url.port = String(tlsServer.port);
-
-    const res = await fetch(pinned.url, trustFixtureCa(pinned.init));
-    expect(res.status).toBe(200);
-  });
-
-  test("fails closed when the pinned servername does not match the certificate", async () => {
-    const url = new URL("https://attacker-does-not-own-this-cert.example/");
-    const pinned = buildPinnedRequest(url, { address: "127.0.0.1", family: 4 }, undefined);
-    pinned.url.port = String(tlsServer.port);
-
-    // A bare `.rejects.toThrow()` would also pass if the server were simply
-    // unreachable, proving nothing about the SNI/cert check itself — match
-    // the actual TLS hostname-mismatch error so the test fails if the
-    // rejection reason ever silently changes to something unrelated.
-    await expect(fetch(pinned.url, trustFixtureCa(pinned.init))).rejects.toThrow(
-      /ALTNAME|certificate/i,
-    );
-  });
-});
-
-describe("withManualRedirect", () => {
-  test("always forces redirect: 'manual', even if the caller's init requests 'follow'", () => {
-    expect(withManualRedirect({ redirect: "follow", headers: { "x-test": "1" } })).toEqual({
-      redirect: "manual",
-      headers: { "x-test": "1" },
-    });
-  });
-
-  test("sets redirect: 'manual' when no init is given", () => {
-    expect(withManualRedirect(undefined)).toEqual({ redirect: "manual" });
-  });
-
-  // The actual runEgress call path is
-  // withManualRedirect(buildPinnedRequest(...).init) — withManualRedirect's
-  // own type signature is plain RequestInit, which type-erases `tls`.
-  // Pinning this hermetically (not just via the network-guarded TLS
-  // integration tests above) protects against a future refactor that
-  // builds the returned object explicitly, field by field, instead of
-  // spreading `init` — which would silently drop `tls` and disable SNI
-  // pinning without any test failing.
-  test("preserves tls.servername from buildPinnedRequest through the spread", () => {
-    const url = new URL("https://attacker-controlled.example/");
-    const pinned = buildPinnedRequest(url, { address: "203.0.113.5", family: 4 }, undefined);
-
-    expect(withManualRedirect(pinned.init)).toMatchObject({
-      redirect: "manual",
-      tls: { servername: "attacker-controlled.example" },
-    });
-  });
-});

package/src/http/__tests__/policy.test.ts

@@ -1,125 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import type { lookup } from "node:dns/promises";
-import { assertAllowedHost, assertHttpScheme, isBlockedIp, resolvePublicHost } from "../policy";
-
-describe("isBlockedIp", () => {
-  test.each([
-    ["169.254.169.254", true], // cloud metadata — the core SSRF target
-    ["10.0.0.1", true],
-    ["172.16.5.4", true],
-    ["172.31.255.255", true],
-    ["192.168.1.1", true],
-    ["127.0.0.1", true],
-    ["0.0.0.0", true],
-    ["100.64.0.1", true], // CGNAT
-    ["224.0.0.1", true], // multicast
-    ["::1", true],
-    ["fc00::1", true], // unique-local
-    ["fe80::1", true], // link-local
-    ["::ffff:10.0.0.1", true], // IPv4-mapped private (dotted form)
-    ["::ffff:a9fe:a9fe", true], // IPv4-mapped cloud metadata (hex form, as new URL() normalizes it)
-    ["0:0:0:0:0:ffff:169.254.169.254", true], // same address, uncompressed + dotted
-    ["0:0:0:0:0:ffff:a9fe:a9fe", true], // same address, uncompressed + hex
-    ["fec0::1", true], // deprecated site-local, RFC 3879
-    ["FEC0:0:0:0:0:0:0:1", true], // same range, uncompressed + uppercase
-    ["feff::1", true], // upper end of fec0::/10
-    ["64:ff9b::169.254.169.254", true], // NAT64-embedded cloud metadata (RFC 6052)
-    ["2002:a9fe:a9fe::", true], // 6to4-embedded cloud metadata (RFC 3056)
-    ["not-an-ip", true], // fail closed
-    ["8.8.8.8", false],
-    ["1.1.1.1", false],
-    ["172.15.0.1", false], // just outside 172.16/12
-    ["172.32.0.1", false],
-    ["93.184.216.34", false],
-    ["2606:2800:220:1:248:1893:25c8:1946", false],
-    ["64:ff9b::8.8.8.8", false], // NAT64-embedded public IP
-    ["2002:808:808::", false], // 6to4-embedded public IP (8.8.8.8)
-  ])("%s -> blocked=%p", (ip, blocked) => {
-    expect(isBlockedIp(ip)).toBe(blocked);
-  });
-});
-
-describe("assertHttpScheme", () => {
-  test("accepts http and https", () => {
-    expect(() => assertHttpScheme(new URL("http://example.com"))).not.toThrow();
-    expect(() => assertHttpScheme(new URL("https://example.com"))).not.toThrow();
-  });
-
-  test("rejects other schemes", () => {
-    expect(() => assertHttpScheme(new URL("file:///etc/passwd"))).toThrow();
-    expect(() => assertHttpScheme(new URL("ftp://example.com"))).toThrow();
-  });
-});
-
-describe("resolvePublicHost", () => {
-  test("rejects a literal private-IP host without any DNS lookup", async () => {
-    await expect(
-      resolvePublicHost(new URL("http://169.254.169.254/latest/meta-data/")),
-    ).rejects.toThrow();
-  });
-
-  test("rejects the hex IPv4-mapped form new URL() normalizes ::ffff:169.254.169.254 into", async () => {
-    await expect(resolvePublicHost(new URL("http://[::ffff:169.254.169.254]/"))).rejects.toThrow();
-  });
-
-  test("allows a public IP-literal host and pins that exact address", async () => {
-    await expect(resolvePublicHost(new URL("http://93.184.216.34/"))).resolves.toEqual({
-      address: "93.184.216.34",
-      family: 4,
-    });
-  });
-
-  test("rejects a URL with embedded credentials", async () => {
-    await expect(resolvePublicHost(new URL("http://user:pass@93.184.216.34/"))).rejects.toThrow(
-      /credentials/,
-    );
-  });
-
-  // DNS-rebinding simulation: a naive "resolve, check, then let fetch()
-  // resolve again to connect" implementation would call the resolver twice
-  // and could get a different (private) answer the second time. This pins
-  // the actual mechanism that closes that window: resolvePublicHost only
-  // ever resolves once and returns the single address from that resolution
-  // for the caller to connect to — there is no second call left for a
-  // rebinding DNS server to answer differently.
-  test("resolves the host exactly once and pins the address from that resolution", async () => {
-    const calls: string[] = [];
-    // Test double only needs the `(host, { all: true }) => LookupAddress[]`
-    // shape resolvePublicHost actually calls, not `lookup`'s full overload
-    // set — double-cast through `unknown` at this test-only boundary.
-    const fakeLookup = (async (hostname: string) => {
-      calls.push(hostname);
-      return [{ address: "203.0.113.5", family: 4 }];
-    }) as unknown as typeof lookup;
-
-    const resolved = await resolvePublicHost(new URL("http://rebinding.example/"), fakeLookup);
-
-    expect(resolved).toEqual({ address: "203.0.113.5", family: 4 });
-    expect(calls).toEqual(["rebinding.example"]); // exactly one resolution
-  });
-
-  test("rejects when any address in the resolution is private, even if another is public", async () => {
-    const fakeLookup = (async () => [
-      { address: "203.0.113.5", family: 4 },
-      { address: "10.0.0.1", family: 4 },
-    ]) as unknown as typeof lookup;
-
-    await expect(
-      resolvePublicHost(new URL("http://rebinding.example/"), fakeLookup),
-    ).rejects.toThrow(/non-public/);
-  });
-});
-
-describe("assertAllowedHost", () => {
-  test("allows a host present in allowHosts (case-insensitive)", () => {
-    expect(() =>
-      assertAllowedHost(new URL("http://Internal-Service.local/"), ["internal-service.local"]),
-    ).not.toThrow();
-  });
-
-  test("rejects a host absent from allowHosts", () => {
-    expect(() =>
-      assertAllowedHost(new URL("http://other.local/"), ["internal-service.local"]),
-    ).toThrow();
-  });
-});

package/src/http/egress.ts

@@ -1,158 +0,0 @@
-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/policy.ts

@@ -1,193 +0,0 @@
-// 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}`);
-  }
-}