@parcha/agentrun-kernel 0.0.0-bootstrap.0 → 0.1.0-beta.29

package/dist/host/egress-proxy.js

@@ -0,0 +1,416 @@
+// A box's egress proxy, written for AgentRun: the one way out of a box whose network namespace has only its own loopback.
+// It listens on a Unix socket (0600) in the session's local runtime directory, bound into the box, and speaks HTTP CONNECT, plain HTTP
+// forwarding and SOCKS5 CONNECT (told apart by the first byte), each to the public internet only (egress-table.ts):
+//  - a host is resolved once, every address in the answer is checked, and the connection goes to exactly the address
+//    that was checked, so a name cannot point elsewhere between the check and the dial; an IP literal is checked the
+//    same way, by its bytes, whatever form the client wrote it in;
+//  - a refusal is an answer, sent before any socket opens: 403 (or SOCKS reply 2) with the class in its reason;
+//  - plain HTTP goes to the request URI's host, and a Host header that names another host is refused (400);
+//  - a redirect is never followed here: it reaches the client as the origin sent it, and the client's next request is
+//    one more request through this proxy, checked the same way;
+//  - SOCKS5 BIND and UDP ASSOCIATE are refused by name, and so is an HTTP upgrade;
+//  - a run has a cap on connections open at once and a budget of connections in all, each refused by name;
+//  - a log line holds the host, the port, the address and the class, never a path, a query, a header or a body;
+//  - with a host list (`allow`), a host off it, an IP literal and any port but 80 and 443 are refused before any lookup,
+//    so a name off the list never leaves the host (no DNS channel out); a listed name then meets the address rule as
+//    any other does.
+// It holds no key. `close()` ends every connection and removes the socket.
+import { randomBytes } from "node:crypto";
+import { lookup as dnsLookup } from "node:dns";
+import { chmod, link, lstat, unlink } from "node:fs/promises";
+import { createServer as createHttpServer, request as httpRequest } from "node:http";
+import { connect as netConnect, createServer } from "node:net";
+import { networkInterfaces } from "node:os";
+import { dirname, join } from "node:path";
+import { addressBytes, checkAddress } from "./egress-table.js";
+/** A host list's entry: a name of two labels or more, or `*.` and such a name. */
+const ENTRY = /^(\*\.)?([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/;
+/** A host list from its entries, or a comma list of them: each lowercased, its trailing dot dropped, the repeats gone.
+ *  Throws for an entry that is not a name of two labels or more, or `*.` and one (an address, a port, a URL, a bare `*`). */
+export function parseAllow(entries) {
+    const list = (typeof entries === "string" ? entries.split(/[\s,]+/) : entries).map((entry) => entry.trim()).filter((entry) => entry !== "");
+    const out = [];
+    for (const entry of list) {
+        const name = entry.toLowerCase().replace(/\.$/, "");
+        if (!ENTRY.test(name) || addressBytes(name.replace(/^\*\./, "")) !== undefined) {
+            throw new Error(`the network list's entry ${JSON.stringify(entry)} is not a name with at least two labels, or *. and one`);
+        }
+        if (!out.includes(name))
+            out.push(name);
+    }
+    return out;
+}
+/** Whether `host` is on `list`: an exact name, or below a `*.suffix`; in any case, and without a trailing dot. */
+const listedHost = (list, host) => {
+    const name = host.toLowerCase().replace(/\.$/, "");
+    return list.some((entry) => (entry.startsWith("*.") ? name.endsWith(entry.slice(1)) && name.length > entry.length - 1 : name === entry));
+};
+/** The ports a host list opens: plain HTTP and HTTPS. */
+const LISTED_PORTS = [80, 443];
+const HOP = new Set(["connection", "proxy-connection", "keep-alive", "proxy-authorization", "proxy-authenticate", "te", "trailer", "upgrade", "transfer-encoding"]);
+/** The headers that stay on this hop: the fixed hop-by-hop names, and every name a Connection header lists. */
+function hopHeaders(headers) {
+    const listed = [headers.connection ?? []].flat().flatMap((value) => String(value).split(",")).map((name) => name.trim().toLowerCase()).filter(Boolean);
+    return new Set([...HOP, ...listed]);
+}
+/** The canonical text of an address's bytes: what is dialled. */
+function addressText(bytes) {
+    if (bytes.length === 4)
+        return [...bytes].join(".");
+    const groups = [];
+    for (let i = 0; i < 16; i += 2)
+        groups.push(((bytes[i] << 8) | bytes[i + 1]).toString(16));
+    return groups.join(":");
+}
+const hostOf = (text) => JSON.stringify(text.slice(0, 255));
+export async function startEgressProxy(options) {
+    const { socketPath, maxTunnels, maxConnections, log } = options;
+    const allow = options.allow === undefined ? undefined : parseAllow(options.allow);
+    // The hint goes into a status line, which carries printable ASCII only: Node refuses anything else there (an em dash
+    // included), and a control character would end the line.
+    if (options.allowHint !== undefined && !/^[\x20-\x7e]*$/.test(options.allowHint))
+        throw new Error("the egress proxy's allowHint holds a character a status line cannot carry: printable ASCII only");
+    const hinted = (words) => (options.allowHint ? `${words}: ${options.allowHint}` : words);
+    /** The refusal of a target off the host list, or undefined: checked before any lookup. */
+    const offList = (host, port) => {
+        if (allow === undefined)
+            return undefined;
+        // A phrase holds only a plain host: anything else is named as such.
+        const shown = /^[A-Za-z0-9._:-]+$/.test(host) ? host : "the host";
+        const words = addressBytes(host) !== undefined
+            ? hinted(`${shown} is an address, not a name on this box's network list`)
+            : !listedHost(allow, host)
+                ? hinted(`${shown} is not on this box's network list`)
+                : !LISTED_PORTS.includes(port)
+                    ? `${shown}:${port} is not open on this box's network list, which takes ports 80 and 443 only`
+                    : undefined;
+        return words === undefined ? undefined : { status: 403, reason: "not-listed", socks: 2, words };
+    };
+    const lookup = options.lookup ?? ((hostname, opts, callback) => dnsLookup(hostname, opts, callback));
+    const dial = options.dial ?? ((address, port) => netConnect({ host: address, port }));
+    const sockets = new Set();
+    let open = 0;
+    let used = 0;
+    let closed = false;
+    const track = (socket) => {
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+        if (closed)
+            socket.destroy();
+    };
+    /** The host's addresses at this moment: every interface's, and the seam's. */
+    const local = () => [
+        ...Object.values(networkInterfaces()).flatMap((list) => (list ?? []).map((entry) => entry.address)),
+        ...(options.alsoLocal?.() ?? []),
+    ];
+    /** Resolves `host` once and checks every answer: the address to dial, or the refusal. */
+    const resolve = async (host) => {
+        const literal = addressBytes(host);
+        let answers;
+        if (literal)
+            answers = [literal];
+        else {
+            if (!/^[A-Za-z0-9._-]+$/.test(host) || host.length > 253)
+                return { refused: { status: 400, reason: "invalid host", socks: 4 } };
+            try {
+                const found = await new Promise((ok, fail) => lookup(host, { all: true, verbatim: true }, (error, list) => (error ? fail(error) : ok(list))));
+                answers = found.map((entry) => addressBytes(entry.address)).filter((bytes) => bytes !== undefined);
+            }
+            catch {
+                return { refused: { status: 502, reason: "name not resolved", socks: 4 } };
+            }
+            if (answers.length === 0)
+                return { refused: { status: 502, reason: "name not resolved", socks: 4 } };
+        }
+        const here = local();
+        for (const bytes of answers) {
+            const verdict = checkAddress(bytes, here);
+            if (!verdict.ok)
+                return { refused: { status: 403, reason: verdict.class, socks: 2 }, address: addressText(bytes) };
+        }
+        return { address: addressText(answers[0]) };
+    };
+    /** A connection may open now: the cap and the budget. Takes a slot; `release` gives it back. */
+    const admit = () => {
+        if (open >= maxTunnels)
+            return { status: 429, reason: "tunnel cap", socks: 2 };
+        if (used >= maxConnections)
+            return { status: 429, reason: "connection budget", socks: 2 };
+        open++;
+        used++;
+        return undefined;
+    };
+    /** Resolve, check, admit and dial: the upstream socket once it connects, or the refusal. */
+    const reach = async (kind, host, port) => {
+        const unlisted = offList(host, port);
+        if (unlisted) {
+            log(`egress ${kind} host=${hostOf(host)} port=${port} ip=- class=${unlisted.reason}`);
+            return { refused: unlisted };
+        }
+        const target = await resolve(host);
+        if ("refused" in target) {
+            log(`egress ${kind} host=${hostOf(host)} port=${port} ip=${target.address ?? "-"} class=${target.refused.reason}`);
+            return target;
+        }
+        const full = admit();
+        if (full) {
+            log(`egress ${kind} host=${hostOf(host)} port=${port} ip=${target.address} class=${full.reason}`);
+            return { refused: full };
+        }
+        log(`egress ${kind} host=${hostOf(host)} port=${port} ip=${target.address} class=ok`);
+        const upstream = dial(target.address, port);
+        track(upstream);
+        upstream.once("close", () => open--);
+        return await new Promise((ok) => {
+            upstream.once("connect", () => ok({ socket: upstream, address: target.address }));
+            upstream.once("error", () => ok({ refused: { status: 502, reason: "dial failed", socks: 5 } }));
+        });
+    };
+    // HTTP: CONNECT, and plain requests in absolute form.
+    const http = createHttpServer();
+    const refuseRaw = (socket, refusal) => {
+        const body = `${refusal.words ?? `egress refused: ${refusal.reason}`}\n`;
+        socket.end(`HTTP/1.1 ${refusal.status} ${refusal.words ?? `Egress refused: ${refusal.reason}`}\r\nx-egress-refused: ${refusal.reason}\r\ncontent-type: text/plain\r\ncontent-length: ${Buffer.byteLength(body)}\r\nconnection: close\r\n\r\n${body}`);
+    };
+    const refuse = (res, refusal) => {
+        const body = `${refusal.words ?? `egress refused: ${refusal.reason}`}\n`;
+        res.writeHead(refusal.status, refusal.words ?? `Egress refused: ${refusal.reason}`, { "x-egress-refused": refusal.reason, "content-type": "text/plain", "content-length": Buffer.byteLength(body), connection: "close" });
+        res.end(body);
+    };
+    http.on("connect", (req, client, head) => {
+        void (async () => {
+            const target = /^\[([0-9A-Fa-f:.%a-zA-Z]+)\]:(\d{1,5})$/.exec(req.url ?? "") ?? /^([^:[\]/@\s]+):(\d{1,5})$/.exec(req.url ?? "");
+            const port = Number(target?.[2]);
+            if (!target || !(port >= 1 && port <= 65535))
+                return refuseRaw(client, { status: 400, reason: "invalid target", socks: 1 });
+            const reached = await reach("connect", target[1], port);
+            if ("refused" in reached)
+                return refuseRaw(client, reached.refused);
+            // A client that left during the lookup or the dial gets no tunnel: its socket goes, and so does its slot.
+            if (client.destroyed)
+                return void reached.socket.destroy();
+            client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+            if (head.length)
+                reached.socket.write(head);
+            reached.socket.pipe(client).pipe(reached.socket);
+            reached.socket.on("error", () => client.destroy());
+            client.on("error", () => reached.socket.destroy());
+            reached.socket.on("close", () => client.destroy());
+            client.on("close", () => reached.socket.destroy());
+        })();
+    });
+    http.on("upgrade", (_req, client) => refuseRaw(client, { status: 400, reason: "upgrade not supported", socks: 7 }));
+    http.on("request", (req, res) => {
+        // Watched from the start: a client that leaves during the lookup or the dial is gone before any listener below exists.
+        let gone = false;
+        res.once("close", () => (gone = true));
+        void (async () => {
+            let url;
+            try {
+                url = new URL(req.url ?? "");
+            }
+            catch {
+                return refuse(res, { status: 400, reason: "not an absolute URI", socks: 1 });
+            }
+            if (url.protocol !== "http:")
+                return refuse(res, { status: 400, reason: "not an http URI", socks: 1 });
+            const host = url.hostname.replace(/^\[|\]$/g, "");
+            const port = url.port === "" ? 80 : Number(url.port);
+            if (req.headers.host !== undefined) {
+                let named;
+                try {
+                    named = new URL(`http://${req.headers.host}`);
+                }
+                catch { }
+                if (!named || named.hostname !== url.hostname || (named.port === "" ? 80 : Number(named.port)) !== port) {
+                    log(`egress http host=${hostOf(host)} port=${port} ip=- class=host mismatch`);
+                    return refuse(res, { status: 400, reason: "host mismatch", socks: 1 });
+                }
+            }
+            const reached = await reach("http", host, port);
+            if ("refused" in reached)
+                return refuse(res, reached.refused);
+            if (gone)
+                return void reached.socket.destroy();
+            const headers = {};
+            const hop = hopHeaders(req.headers);
+            for (const [name, value] of Object.entries(req.headers))
+                if (!hop.has(name))
+                    headers[name] = value;
+            headers.host = url.host;
+            headers.connection = "close";
+            // The request goes over the socket already dialled to the checked address. Its host and port name that address too,
+            // so nothing else is reached even if the socket were not used (with `agent: false`, Node ignores createConnection
+            // and dials host and port itself).
+            const upstream = httpRequest({ host: reached.address, port, method: req.method, path: `${url.pathname}${url.search}`, headers, createConnection: () => reached.socket });
+            upstream.on("response", (answer) => {
+                const out = {};
+                const back = hopHeaders(answer.headers);
+                for (const [name, value] of Object.entries(answer.headers))
+                    if (!back.has(name) && value !== undefined)
+                        out[name] = value;
+                res.writeHead(answer.statusCode ?? 502, answer.statusMessage, out);
+                answer.pipe(res);
+            });
+            upstream.on("error", () => (res.headersSent ? res.destroy() : refuse(res, { status: 502, reason: "upstream failed", socks: 1 })));
+            req.pipe(upstream);
+            res.on("close", () => reached.socket.destroy());
+        })();
+    });
+    // SOCKS5: a greeting offering "no authentication", then one CONNECT.
+    const socks = (client) => {
+        let buffer = Buffer.alloc(0);
+        let stage = "greet";
+        const reply = (code) => Buffer.from([5, code, 0, 1, 0, 0, 0, 0, 0, 0]);
+        const onData = (chunk) => {
+            buffer = Buffer.concat([buffer, chunk]);
+            if (buffer.length > 1024)
+                return client.destroy();
+            if (stage === "greet") {
+                if (buffer.length < 2 || buffer.length < 2 + buffer[1])
+                    return;
+                const methods = buffer.subarray(2, 2 + buffer[1]);
+                buffer = buffer.subarray(2 + buffer[1]);
+                if (!methods.includes(0))
+                    return client.end(Buffer.from([5, 0xff]));
+                client.write(Buffer.from([5, 0]));
+                stage = "request";
+            }
+            if (stage !== "request" || buffer.length < 5)
+                return;
+            const [version, command, , type] = buffer;
+            if (version !== 5)
+                return client.destroy();
+            const length = type === 1 ? 4 : type === 4 ? 16 : type === 3 ? 1 + buffer[4] : -1;
+            if (length < 0)
+                return client.end(reply(8));
+            if (buffer.length < 4 + length + 2)
+                return;
+            stage = "done";
+            client.off("data", onData);
+            client.setTimeout(0);
+            const raw = buffer.subarray(4, 4 + length);
+            const host = type === 3 ? raw.subarray(1).toString("latin1") : addressText(raw);
+            const port = buffer.readUInt16BE(4 + length);
+            const rest = buffer.subarray(4 + length + 2);
+            if (command !== 1) {
+                const name = command === 2 ? "socks bind" : command === 3 ? "socks udp associate" : "socks command";
+                log(`egress socks host=${hostOf(host)} port=${port} ip=- class=${name}`);
+                return client.end(reply(7));
+            }
+            void (async () => {
+                const reached = await reach("socks", host, port);
+                if ("refused" in reached)
+                    return client.end(reply(reached.refused.socks));
+                if (client.destroyed)
+                    return void reached.socket.destroy();
+                client.write(reply(0));
+                if (rest.length)
+                    reached.socket.write(rest);
+                reached.socket.pipe(client).pipe(reached.socket);
+                reached.socket.on("error", () => client.destroy());
+                client.on("error", () => reached.socket.destroy());
+                reached.socket.on("close", () => client.destroy());
+                client.on("close", () => reached.socket.destroy());
+            })();
+        };
+        client.on("data", onData);
+    };
+    const server = createServer((client) => {
+        track(client);
+        client.on("error", () => client.destroy());
+        client.setTimeout(30_000, () => client.destroy());
+        client.once("data", (first) => {
+            client.pause();
+            client.unshift(first);
+            if (first[0] === 5) {
+                socks(client);
+                client.resume();
+            }
+            else {
+                client.setTimeout(0);
+                http.emit("connection", client);
+                client.resume();
+            }
+        });
+    });
+    // A socket already at the path belongs to another proxy while it answers, and is never taken from it. The socket's
+    // directory is local; a connect refused there means nothing listens. So only a socket that refuses a connection is
+    // removed; any other failure of the probe (EACCES, say) is thrown and the socket left, and anything that is not a socket
+    // is left where it is. (On a disk shared between hosts, a live proxy's socket on another host would refuse this host's
+    // connection: that is why the directory must be local.) Two starts that both find the same dead socket could each
+    // remove it in turn, the second after the first has linked its live socket there; that needs two starters in one
+    // session's runtime directory, which its single claim holder rules out, so nothing here guards it (moving the socket
+    // aside to check it would leave a live one briefly missing from its path instead).
+    const taken = (code, what) => Object.assign(new Error(`egress proxy: ${socketPath} ${what}`), { code });
+    let found;
+    try {
+        found = await lstat(socketPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (found) {
+        if (!found.isSocket())
+            throw taken("egress_socket_path_taken", "exists and is not a socket");
+        const answer = await new Promise((ok) => {
+            const probe = netConnect(socketPath);
+            probe.once("connect", () => {
+                probe.destroy();
+                ok(true);
+            });
+            probe.once("error", (error) => ok(error));
+        });
+        if (answer === true)
+            throw taken("egress_socket_in_use", "is a live egress proxy's socket");
+        if (answer.code !== "ECONNREFUSED")
+            throw answer;
+        await unlink(socketPath);
+    }
+    // Made under a name of its own and made 0600 before it gets its path, so it is never reachable there with a wider
+    // mode. The path is a hard link, never a rename. Between the check above and this link, another start can put a socket
+    // at the path: a link then fails (EEXIST, refused as egress_socket_in_use), where a rename would replace that socket
+    // silently. No test can hold that window open, so this comment is its record. The temporary name is removed once linked.
+    const making = join(dirname(socketPath), `.egress-${randomBytes(6).toString("hex")}.sock`);
+    await new Promise((ok, fail) => {
+        server.once("error", fail);
+        server.listen(making, () => {
+            server.off("error", fail);
+            ok();
+        });
+    });
+    try {
+        await chmod(making, 0o600);
+        await link(making, socketPath);
+    }
+    catch (error) {
+        server.close();
+        await unlink(making).catch(() => { });
+        if (error.code === "EEXIST")
+            throw taken("egress_socket_in_use", "was taken while this proxy started");
+        throw error;
+    }
+    // This socket's inode: close removes the path only while it still holds it, never a socket another start put there.
+    const mine = await lstat(making);
+    await unlink(making).catch(() => { });
+    return {
+        socketPath,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            const done = new Promise((ok) => server.close(() => ok()));
+            for (const socket of sockets)
+                socket.destroy();
+            http.close();
+            await done;
+            const now = await lstat(socketPath).catch((error) => {
+                if (error.code !== "ENOENT")
+                    throw error;
+            });
+            if (now && now.dev === mine.dev && now.ino === mine.ino)
+                await unlink(socketPath);
+        },
+    };
+}

package/dist/host/egress-table.d.ts

@@ -0,0 +1,24 @@
+/** Why an address is refused. */
+export type EgressClass = "loopback" | "unspecified" | "private" | "cgnat" | "link-local" | "metadata" | "multicast" | "broadcast" | "reserved" | "benchmarking" | "this-host" | "invalid";
+export type EgressVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    class: EgressClass;
+};
+/** The table's ranges as written, in order: what the no-drift test pins. */
+export declare const EGRESS_RANGES: readonly string[];
+/**
+ * An IP address's bytes (4 or 16), or undefined when `text` is not one. Takes what a socket or a URL could carry for a
+ * host: a dotted IPv4 address, or the forms the classic resolver reads as one (a single number, 0x hex and 0 octal
+ * parts, fewer than four parts with the last filling the rest), and an IPv6 address, bracketed or not, with or without a
+ * zone. Never a name.
+ */
+export declare function addressBytes(text: string): Uint8Array | undefined;
+/**
+ * Whether a box may reach `address` (its bytes, or an address's text: never a name). `local` is the host's own interface
+ * addresses, read by the caller at the dial: an address equal to one of them is refused as "this-host". An IPv6 address
+ * that carries an IPv4 one is judged by the IPv4 inside, and is then still the host's own if the host holds that IPv6
+ * address itself (the dial goes to the IPv6 address, not to the IPv4 inside it).
+ */
+export declare function checkAddress(address: Uint8Array | string, local: readonly string[]): EgressVerdict;

package/dist/host/egress-table.js

@@ -0,0 +1,165 @@
+// The address rule of a box's egress, written for AgentRun: which addresses a box may reach through its egress proxy.
+// Everything public; nothing private or local. It judges the binary address a socket would connect to, never the text a
+// client wrote, so a single decimal number, octal or hex parts, or a bracketed IPv6 address is the address it parses to. An IPv6 address that carries
+// an IPv4 one (mapped, NAT64, 6to4) is judged by the IPv4 inside. The host's own interface addresses are refused too: the
+// caller reads them at each dial and passes them in, so the table itself stays pure. This is the one place the rule
+// lives; the key gate's denylist marker accepts exactly these literals, and a test pins the list against drift.
+import { isIP } from "node:net";
+/** The refused ranges, specific ones first (the first match decides): a single metadata address before the range it sits
+ *  in, the broadcast address before the reserved block. Past the table, an IPv6 address outside global unicast
+ *  (2000::/3) is refused as reserved, in code: the IPv4-compatible form (::a.b.c.d) and every unassigned block among
+ *  them. The mapped and NAT64 forms sit outside 2000::/3 too, and are judged by their IPv4 before that rule. */
+const TABLE = [
+    { cidr: "0.0.0.0/8", class: "unspecified" }, // key-gate: denylist unspecified, refused by the egress proxy
+    { cidr: "127.0.0.0/8", class: "loopback" }, // key-gate: loopback-rule loopback, refused by the egress proxy
+    { cidr: "10.0.0.0/8", class: "private" }, // key-gate: denylist RFC 1918, refused by the egress proxy
+    { cidr: "172.16.0.0/12", class: "private" }, // key-gate: denylist RFC 1918, refused by the egress proxy
+    { cidr: "192.168.0.0/16", class: "private" }, // key-gate: denylist RFC 1918, refused by the egress proxy
+    { cidr: "192.0.0.0/24", class: "private" }, // key-gate: denylist IETF protocol assignments, refused by the egress proxy
+    { cidr: "100.100.100.200/32", class: "metadata" }, // key-gate: denylist a cloud metadata address, refused by the egress proxy
+    { cidr: "100.64.0.0/10", class: "cgnat" }, // key-gate: denylist shared address space, refused by the egress proxy
+    { cidr: "168.63.129.16/32", class: "metadata" }, // key-gate: denylist a cloud metadata address, refused by the egress proxy
+    { cidr: "169.254.0.0/16", class: "link-local" }, // key-gate: denylist link-local, refused by the egress proxy
+    { cidr: "198.18.0.0/15", class: "benchmarking" }, // key-gate: denylist benchmarking, refused by the egress proxy
+    { cidr: "192.0.2.0/24", class: "reserved" }, // key-gate: denylist documentation, refused by the egress proxy
+    { cidr: "198.51.100.0/24", class: "reserved" }, // key-gate: denylist documentation, refused by the egress proxy
+    { cidr: "203.0.113.0/24", class: "reserved" }, // key-gate: denylist documentation, refused by the egress proxy
+    { cidr: "192.88.99.0/24", class: "reserved" }, // key-gate: denylist the 6to4 relay anycast, refused by the egress proxy
+    { cidr: "224.0.0.0/4", class: "multicast" }, // key-gate: denylist multicast, refused by the egress proxy
+    { cidr: "255.255.255.255/32", class: "broadcast" }, // key-gate: denylist broadcast, refused by the egress proxy
+    { cidr: "240.0.0.0/4", class: "reserved" }, // key-gate: denylist reserved, refused by the egress proxy
+    { cidr: "::1/128", class: "loopback" }, // key-gate: loopback-rule loopback, refused by the egress proxy
+    { cidr: "::/128", class: "unspecified" }, // key-gate: denylist unspecified, refused by the egress proxy
+    { cidr: "::ffff:0:0/96", class: "last32" }, // key-gate: denylist IPv4-mapped, judged by the IPv4 inside
+    { cidr: "64:ff9b::/96", class: "last32" }, // key-gate: denylist NAT64, judged by the IPv4 inside
+    // Local-use NAT64 (RFC 8215): its operator picks a prefix of /48 to /96 inside it, so where an IPv4 sits cannot be read
+    // from the address alone. The whole block is refused.
+    { cidr: "64:ff9b:1::/48", class: "private" }, // key-gate: denylist local-use NAT64, refused by the egress proxy
+    { cidr: "2002::/16", class: "6to4" }, // key-gate: denylist 6to4, judged by the IPv4 inside
+    { cidr: "2001::/32", class: "reserved" }, // key-gate: denylist Teredo, refused by the egress proxy
+    { cidr: "2001:db8::/32", class: "reserved" }, // key-gate: denylist documentation, refused by the egress proxy
+    { cidr: "fd00:ec2::/32", class: "metadata" }, // key-gate: denylist a cloud metadata range, refused by the egress proxy
+    { cidr: "fc00::/7", class: "private" }, // key-gate: denylist unique local, refused by the egress proxy
+    { cidr: "fe80::/10", class: "link-local" }, // key-gate: denylist link-local, refused by the egress proxy
+    { cidr: "ff00::/8", class: "multicast" }, // key-gate: denylist multicast, refused by the egress proxy
+];
+/** The table's ranges as written, in order: what the no-drift test pins. */
+export const EGRESS_RANGES = TABLE.map((entry) => entry.cidr);
+/**
+ * An IP address's bytes (4 or 16), or undefined when `text` is not one. Takes what a socket or a URL could carry for a
+ * host: a dotted IPv4 address, or the forms the classic resolver reads as one (a single number, 0x hex and 0 octal
+ * parts, fewer than four parts with the last filling the rest), and an IPv6 address, bracketed or not, with or without a
+ * zone. Never a name.
+ */
+export function addressBytes(text) {
+    let host = text.trim();
+    if (host.startsWith("[") && host.endsWith("]"))
+        host = host.slice(1, -1);
+    const zone = host.indexOf("%");
+    if (zone >= 0 && host.includes(":"))
+        host = host.slice(0, zone);
+    if (isIP(host) === 6)
+        return v6Bytes(host);
+    return v4Bytes(host);
+}
+/** The classic resolver's reading of an IPv4 address (inet_aton): 1 to 4 parts, each decimal, 0x hex or 0 octal. */
+function v4Bytes(text) {
+    const parts = text.split(".");
+    if (parts.length < 1 || parts.length > 4)
+        return undefined;
+    const values = [];
+    for (const part of parts) {
+        let value;
+        if (/^0[xX][0-9a-fA-F]*$/.test(part))
+            value = part.length === 2 ? 0 : parseInt(part.slice(2), 16);
+        else if (/^0[0-7]*$/.test(part))
+            value = parseInt(part, 8);
+        else if (/^[1-9][0-9]*$/.test(part))
+            value = parseInt(part, 10);
+        else
+            return undefined;
+        if (!Number.isSafeInteger(value))
+            return undefined;
+        values.push(value);
+    }
+    const last = values.pop();
+    if (values.some((v) => v > 255) || last >= 2 ** (8 * (4 - values.length)))
+        return undefined;
+    const out = new Uint8Array(4);
+    values.forEach((v, i) => (out[i] = v));
+    for (let i = 3, rest = last; i >= values.length; i--, rest = Math.floor(rest / 256))
+        out[i] = rest % 256;
+    return out;
+}
+/** An IPv6 address's 16 bytes; `text` is one `isIP` accepts. */
+function v6Bytes(text) {
+    let head = text;
+    const dotted = /^(.*:)(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+    if (dotted) {
+        const v4 = v4Bytes(dotted[2]);
+        if (!v4 || dotted[2].split(".").length !== 4)
+            return undefined;
+        head = `${dotted[1]}${((v4[0] << 8) | v4[1]).toString(16)}:${((v4[2] << 8) | v4[3]).toString(16)}`;
+    }
+    const [left, right] = head.split("::");
+    const groups = (s) => (s === "" ? [] : s.split(":").map((g) => parseInt(g, 16)));
+    const l = groups(left);
+    const r = right === undefined ? [] : groups(right);
+    const fill = right === undefined ? 0 : 8 - l.length - r.length;
+    const all = [...l, ...Array(Math.max(fill, 0)).fill(0), ...r];
+    if (all.length !== 8 || all.some((g) => !(g >= 0 && g <= 0xffff)))
+        return undefined;
+    const out = new Uint8Array(16);
+    all.forEach((g, i) => {
+        out[2 * i] = g >> 8;
+        out[2 * i + 1] = g & 0xff;
+    });
+    return out;
+}
+const RANGES = TABLE.map((entry) => {
+    const [base, bits] = entry.cidr.split("/");
+    return { bytes: addressBytes(base), bits: Number(bits), class: entry.class };
+});
+const within = (address, range) => {
+    if (address.length !== range.bytes.length)
+        return false;
+    for (let bit = 0; bit < range.bits; bit += 8) {
+        const mask = range.bits - bit >= 8 ? 0xff : (0xff << (8 - (range.bits - bit))) & 0xff;
+        if ((address[bit / 8] & mask) !== (range.bytes[bit / 8] & mask))
+            return false;
+    }
+    return true;
+};
+const same = (a, b) => a.length === b.length && a.every((byte, i) => byte === b[i]);
+/**
+ * Whether a box may reach `address` (its bytes, or an address's text: never a name). `local` is the host's own interface
+ * addresses, read by the caller at the dial: an address equal to one of them is refused as "this-host". An IPv6 address
+ * that carries an IPv4 one is judged by the IPv4 inside, and is then still the host's own if the host holds that IPv6
+ * address itself (the dial goes to the IPv6 address, not to the IPv4 inside it).
+ */
+export function checkAddress(address, local) {
+    const bytes = typeof address === "string" ? addressBytes(address) : address;
+    if (!bytes || (bytes.length !== 4 && bytes.length !== 16))
+        return { ok: false, class: "invalid" };
+    for (const range of RANGES) {
+        if (!within(bytes, range))
+            continue;
+        if (range.class === "last32" || range.class === "6to4") {
+            const inner = checkAddress(range.class === "last32" ? bytes.slice(12, 16) : bytes.slice(2, 6), local);
+            return inner.ok ? ownAddress(bytes, local) : inner;
+        }
+        return { ok: false, class: range.class };
+    }
+    if (bytes.length === 16 && (bytes[0] & 0xe0) !== 0x20)
+        return { ok: false, class: "reserved" };
+    return ownAddress(bytes, local);
+}
+/** Refused as "this-host" when `bytes` is one of the host's own addresses, as it is written there. */
+function ownAddress(bytes, local) {
+    for (const text of local) {
+        const own = addressBytes(text);
+        if (own && same(own, bytes))
+            return { ok: false, class: "this-host" };
+    }
+    return { ok: true };
+}

package/dist/host/index.d.ts

@@ -0,0 +1,16 @@
+export { ANTHROPIC_IMAGE_TOKENS_MAX, ANTHROPIC_TOOL_USE_SYSTEM_PROMPT_TOKENS, ASSUMED_TOOL_PROMPT_TOKENS, INPUT_OVERHEAD_APIS, OPENAI_IMAGE_TOKENS_MAX, providerInputOverhead, type InputShape } from "./overhead.js";
+export { hostHeaderProblems, inputTokensMaxOf, matchRoute, parseStrict, providerIdsOf, ProxyRefusal, reportedCostOf, sameKey, startModelProxy } from "./proxy.js";
+export type { ModelProxy, ModelProxyHooks, ModelProxyOptions, ModelUsageReport, ProviderPolicy, ProxyRequest, ProxyRoute, ProxyUsage } from "./proxy.js";
+export { processAlive } from "./alive.js";
+export { serialWriter } from "./serial.js";
+export { addressBytes, checkAddress, EGRESS_RANGES } from "./egress-table.js";
+export type { EgressClass, EgressVerdict } from "./egress-table.js";
+export { parseAllow, startEgressProxy } from "./egress-proxy.js";
+export type { EgressLookup, EgressProxy, EgressProxyOptions } from "./egress-proxy.js";
+export { PARENT_WATCH_SHIM, parentWatched, parentWatchHere, SETPRIV } from "./parent-death.js";
+export type { LaunchCommand, ParentWatch } from "./parent-death.js";
+export { BoxError } from "./box.js";
+export type { Box, BoxedChild, BoxErrorCode, BoxRecord, BoxRecorder, BoxSpec, Isolation, Reaped } from "./box.js";
+export { boxSlot } from "./box-slot.js";
+export type { BoxSlot, BoxSlotState, BoxStart, SlotChild } from "./box-slot.js";
+export { checkedOnce, sha256OfFile } from "./pinned-binary.js";

package/dist/host/index.js

@@ -0,0 +1,12 @@
+// What a harness adapter runs beside its harness on the host: the session's model proxy, provider-neutral, with each
+// provider's rules in a `ProviderPolicy`. Written for AgentRun.
+export { ANTHROPIC_IMAGE_TOKENS_MAX, ANTHROPIC_TOOL_USE_SYSTEM_PROMPT_TOKENS, ASSUMED_TOOL_PROMPT_TOKENS, INPUT_OVERHEAD_APIS, OPENAI_IMAGE_TOKENS_MAX, providerInputOverhead } from "./overhead.js";
+export { hostHeaderProblems, inputTokensMaxOf, matchRoute, parseStrict, providerIdsOf, ProxyRefusal, reportedCostOf, sameKey, startModelProxy } from "./proxy.js";
+export { processAlive } from "./alive.js";
+export { serialWriter } from "./serial.js";
+export { addressBytes, checkAddress, EGRESS_RANGES } from "./egress-table.js";
+export { parseAllow, startEgressProxy } from "./egress-proxy.js";
+export { PARENT_WATCH_SHIM, parentWatched, parentWatchHere, SETPRIV } from "./parent-death.js";
+export { BoxError } from "./box.js";
+export { boxSlot } from "./box-slot.js";
+export { checkedOnce, sha256OfFile } from "./pinned-binary.js";