@synap-core/cli 1.12.2 → 1.13.1-next.20261102.246dc73

package/dist/lib/box/egress.js

@@ -0,0 +1,264 @@
+/**
+ * The run box's ONE way out: an HTTP(S) proxy on the provisioner, bound to the
+ * box bridge. A box has no gateway and no resolver; everything it fetches goes
+ * through here, and here decides (runbox design C4 "Egress"):
+ *
+ *   setup phase → the package registries only (PyPI, npm)
+ *   run phase   → the hosts the script declared, nothing else
+ *
+ * A name that passes is resolved HERE, every address it resolves to is checked
+ * against internal ranges (RFC1918, loopback, link-local and cloud metadata,
+ * CGNAT = the tailnet), and the connection goes to the address that was
+ * checked, never to a second lookup — so a declared host that resolves to the
+ * pod (DNS rebinding) is refused. Every refusal is recorded for the evidence
+ * bundle. The bridge firewall is the wall; this is the policy.
+ */
+import dns from "node:dns/promises";
+import http from "node:http";
+import net from "node:net";
+/** Hosts a box may reach while it installs declared packages. */
+export const REGISTRY_HOSTS = [
+    "pypi.org",
+    "files.pythonhosted.org",
+    "registry.npmjs.org",
+];
+/** Ports a bare allow entry opens: the web only. */
+export const ALLOWED_PORTS = [80, 443];
+// ─── addresses ───────────────────────────────────────────────────────────────
+function v4ToInt(ip) {
+    return ip.split(".").reduce((acc, o) => (acc << 8) + Number(o), 0) >>> 0;
+}
+function inV4(ip, cidr) {
+    const [base, bits] = cidr.split("/");
+    const mask = Number(bits) === 0 ? 0 : (~0 << (32 - Number(bits))) >>> 0;
+    return (ip & mask) === (v4ToInt(base) & mask);
+}
+/** IPv4 ranges a box must never reach, whatever name led there. */
+const FORBIDDEN_V4 = [
+    "0.0.0.0/8", // "this network"
+    "10.0.0.0/8", // RFC1918: vmbr1 (the pod at 10.10.0.10) and the box bridge
+    "100.64.0.0/10", // CGNAT: the tailnet
+    "127.0.0.0/8", // loopback
+    "169.254.0.0/16", // link-local, incl. cloud metadata 169.254.169.254
+    "172.16.0.0/12", // RFC1918
+    "192.0.0.0/24", // IETF protocol assignments
+    "192.168.0.0/16", // RFC1918: the LAN, the Proxmox host
+    "198.18.0.0/15", // benchmarking
+    "224.0.0.0/4", // multicast
+    "240.0.0.0/4", // reserved, incl. broadcast
+];
+/** Expands a valid IPv6 literal to 8 hextets (zone id dropped, embedded v4 folded). */
+function v6Hextets(ip) {
+    let addr = ip.split("%")[0].toLowerCase();
+    const embedded = /^(.*:)(\d+\.\d+\.\d+\.\d+)$/.exec(addr);
+    if (embedded) {
+        if (!net.isIPv4(embedded[2]))
+            return null;
+        const n = v4ToInt(embedded[2]);
+        addr = `${embedded[1]}${(n >>> 16).toString(16)}:${(n & 0xffff).toString(16)}`;
+    }
+    const parts = addr.split("::");
+    if (parts.length > 2)
+        return null;
+    const left = parts[0] ? parts[0].split(":") : [];
+    const right = parts.length === 2 && parts[1] ? parts[1].split(":") : [];
+    const missing = 8 - left.length - right.length;
+    if (parts.length === 1 ? missing !== 0 : missing < 0)
+        return null;
+    const out = [...left, ...Array(missing).fill("0"), ...right].map((h) => parseInt(h, 16));
+    return out.every((h) => Number.isInteger(h) && h >= 0 && h <= 0xffff) ? out : null;
+}
+/**
+ * True when a box must not connect to this address. An unparsable address is
+ * forbidden: the check fails closed.
+ */
+export function isForbiddenAddress(ip) {
+    if (net.isIPv4(ip)) {
+        const n = v4ToInt(ip);
+        return FORBIDDEN_V4.some((c) => inV4(n, c));
+    }
+    if (!net.isIPv6(ip))
+        return true;
+    const h = v6Hextets(ip);
+    if (!h)
+        return true;
+    // IPv4-mapped (::ffff:a.b.c.d) and NAT64 (64:ff9b::a.b.c.d) carry a v4 address.
+    const isMapped = h.slice(0, 5).every((x) => x === 0) && h[5] === 0xffff;
+    const isNat64 = h[0] === 0x64 && h[1] === 0xff9b && h.slice(2, 6).every((x) => x === 0);
+    if (isMapped || isNat64) {
+        const v4 = `${h[6] >>> 8}.${h[6] & 0xff}.${h[7] >>> 8}.${h[7] & 0xff}`;
+        return isForbiddenAddress(v4);
+    }
+    // ::/96 holds ::, ::1 and the deprecated IPv4-compatible ::a.b.c.d: none is a public peer.
+    if (h.slice(0, 6).every((x) => x === 0))
+        return true;
+    // 6to4 (2002::/16) carries a v4 address in hextets 1-2.
+    if (h[0] === 0x2002)
+        return isForbiddenAddress(`${h[1] >>> 8}.${h[1] & 0xff}.${h[2] >>> 8}.${h[2] & 0xff}`);
+    if (h[0] === 0x2001 && h[1] === 0)
+        return true; // Teredo 2001::/32 (an obfuscated v4 inside)
+    if (h[0] === 0x2001 && h[1] === 0x0db8)
+        return true; // documentation 2001:db8::/32
+    if ((h[0] & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 unique local
+    if ((h[0] & 0xffc0) === 0xfe80)
+        return true; // fe80::/10 link-local
+    if ((h[0] & 0xff00) === 0xff00)
+        return true; // multicast
+    return false;
+}
+// ─── names ───────────────────────────────────────────────────────────────────
+/** Lower-cased, trailing dot dropped, brackets of an IPv6 literal removed. */
+export function normalizeHost(host) {
+    return host.trim().toLowerCase().replace(/^\[(.*)\]$/, "$1").replace(/\.$/, "");
+}
+/**
+ * `host` matches an allow entry exactly, or a `*.example.com` entry as a
+ * strict subdomain (never the apex, never a suffix like `evilexample.com`).
+ */
+export function hostMatches(host, allow) {
+    const h = normalizeHost(host);
+    return allow.some((raw) => {
+        const a = normalizeHost(raw);
+        if (a.startsWith("*."))
+            return h.endsWith(a.slice(1)) && h.length > a.length - 1;
+        return h === a;
+    });
+}
+/** An allow entry split into its host and, when it names one, its port. */
+function splitEntry(entry) {
+    const m = /^(.*):(\d{1,5})$/.exec(entry.trim());
+    return m && !m[1].includes(":") ? { host: m[1], port: Number(m[2]) } : { host: entry, port: null };
+}
+/**
+ * The name-level decision, before any lookup. A bare entry opens the web
+ * ports (80, 443); a `host:port` entry opens that port on that host only.
+ */
+export function decideByName(host, port, policy) {
+    const h = normalizeHost(host);
+    if (net.isIP(h))
+        return { allow: false, reason: "an address literal is never allowed; declare a host name" };
+    const entries = (policy.phase === "setup" ? REGISTRY_HOSTS : policy.runHosts).map(splitEntry);
+    const named = entries.filter((e) => hostMatches(h, [e.host]));
+    if (named.length === 0) {
+        return {
+            allow: false,
+            reason: policy.phase === "setup"
+                ? "only the package registries are reachable while packages install"
+                : "not a host this script declared",
+        };
+    }
+    const portOk = named.some((e) => (e.port === null ? ALLOWED_PORTS.includes(port) : e.port === port));
+    if (!portOk)
+        return { allow: false, reason: `port ${port} is not declared for this host` };
+    return { allow: true };
+}
+const systemResolver = async (host) => (await dns.lookup(host, { all: true, verbatim: true })).map((a) => a.address);
+/**
+ * The full decision: by name, then by every resolved address. Returns the ONE
+ * address to connect to, so the connection never re-resolves.
+ */
+export async function decideEgress(host, port, policy, resolve = systemResolver) {
+    const byName = decideByName(host, port, policy);
+    if (!byName.allow)
+        return byName;
+    let addresses;
+    try {
+        addresses = await resolve(normalizeHost(host));
+    }
+    catch (err) {
+        return { allow: false, reason: `could not resolve: ${err.message}` };
+    }
+    if (addresses.length === 0)
+        return { allow: false, reason: "resolved to no address" };
+    const bad = addresses.find(isForbiddenAddress);
+    if (bad)
+        return { allow: false, reason: `resolves to an internal address (${bad})` };
+    return { allow: true, address: addresses[0] };
+}
+function sourceIpOf(sock) {
+    return (sock.remoteAddress ?? "").replace(/^::ffff:/, "");
+}
+function splitHostPort(authority, defaultPort) {
+    const m = /^(\[[^\]]+\]|[^:]+)(?::(\d+))?$/.exec(authority);
+    if (!m)
+        return null;
+    return { host: m[1], port: m[2] ? Number(m[2]) : defaultPort };
+}
+/**
+ * An HTTP proxy: CONNECT for HTTPS (a tunnel to the checked address), and
+ * absolute-form requests for plain HTTP. Anything else is refused.
+ */
+export function createEgressProxy(opts) {
+    const resolve = opts.resolve ?? systemResolver;
+    const connect = opts.connect ?? ((address, port) => net.connect({ host: address, port }));
+    async function gate(sock, host, port) {
+        const src = sourceIpOf(sock);
+        const policy = opts.policyFor(src);
+        if (!policy)
+            return { status: 403, reason: "not a running box" };
+        const d = await decideEgress(host, port, policy, resolve);
+        if (!d.allow) {
+            opts.onBlock(src, { host: normalizeHost(host), port, phase: policy.phase, reason: d.reason, at: new Date().toISOString() });
+            return { status: 403, reason: d.reason };
+        }
+        return { address: d.address };
+    }
+    const server = http.createServer(async (req, res) => {
+        let target;
+        try {
+            target = new URL(req.url ?? "");
+        }
+        catch {
+            res.writeHead(400).end("absolute-form request required\n");
+            return;
+        }
+        if (target.protocol !== "http:") {
+            res.writeHead(400).end("only http:// is proxied in absolute form; use CONNECT for https\n");
+            return;
+        }
+        const port = target.port ? Number(target.port) : 80;
+        const g = await gate(req.socket, target.hostname, port);
+        if (!("address" in g)) {
+            res.writeHead(g.status, { "content-type": "text/plain" }).end(`synap box egress refused: ${g.reason}\n`);
+            return;
+        }
+        const upstream = http.request({
+            host: g.address,
+            port,
+            method: req.method,
+            path: target.pathname + target.search,
+            headers: { ...req.headers, host: target.host },
+            createConnection: () => connect(g.address, port),
+        }, (up) => {
+            res.writeHead(up.statusCode ?? 502, up.headers);
+            up.pipe(res);
+        });
+        upstream.on("error", () => res.headersSent ? res.destroy() : res.writeHead(502).end());
+        req.pipe(upstream);
+    });
+    server.on("connect", async (req, client, head) => {
+        const hp = splitHostPort(req.url ?? "", 443);
+        if (!hp) {
+            client.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+            return;
+        }
+        const g = await gate(client, hp.host, hp.port);
+        if (!("address" in g)) {
+            client.end(`HTTP/1.1 ${g.status} Forbidden\r\ncontent-type: text/plain\r\n\r\nsynap box egress refused: ${g.reason}\n`);
+            return;
+        }
+        const upstream = connect(g.address, hp.port);
+        upstream.once("connect", () => {
+            client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+            if (head.length)
+                upstream.write(head);
+            upstream.pipe(client);
+            client.pipe(upstream);
+        });
+        upstream.on("error", () => client.destroy());
+        client.on("error", () => upstream.destroy());
+    });
+    return server;
+}
+//# sourceMappingURL=egress.js.map

package/dist/lib/box/egress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress.js","sourceRoot":"","sources":["../../../src/lib/box/egress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,GAAG,MAAM,mBAAmB,CAAC;AACpC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,GAAG,MAAM,UAAU,CAAC;AAI3B,iEAAiE;AACjE,MAAM,CAAC,MAAM,cAAc,GAAsB;IAC/C,UAAU;IACV,wBAAwB;IACxB,oBAAoB;CACrB,CAAC;AAEF,oDAAoD;AACpD,MAAM,CAAC,MAAM,aAAa,GAAsB,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;AAU1D,gFAAgF;AAEhF,SAAS,OAAO,CAAC,EAAU;IACzB,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC;AAED,SAAS,IAAI,CAAC,EAAU,EAAE,IAAY;IACpC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACxE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;AAChD,CAAC;AAED,mEAAmE;AACnE,MAAM,YAAY,GAAG;IACnB,WAAW,EAAE,iBAAiB;IAC9B,YAAY,EAAE,4DAA4D;IAC1E,eAAe,EAAE,qBAAqB;IACtC,aAAa,EAAE,WAAW;IAC1B,gBAAgB,EAAE,mDAAmD;IACrE,eAAe,EAAE,UAAU;IAC3B,cAAc,EAAE,4BAA4B;IAC5C,gBAAgB,EAAE,qCAAqC;IACvD,eAAe,EAAE,eAAe;IAChC,aAAa,EAAE,YAAY;IAC3B,aAAa,EAAE,4BAA4B;CAC5C,CAAC;AAEF,uFAAuF;AACvF,SAAS,SAAS,CAAC,EAAU;IAC3B,IAAI,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1C,MAAM,QAAQ,GAAG,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;IACjF,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjD,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACxE,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC/C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClE,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,CAAS,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACjG,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACrF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAC3C,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;QACnB,MAAM,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC;QACtB,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACjC,MAAM,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;IACxB,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,gFAAgF;IAChF,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;IACxE,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACxF,IAAI,QAAQ,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC;QACvE,OAAO,kBAAkB,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC;IACD,2FAA2F;IAC3F,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,wDAAwD;IACxD,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM;QAAE,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;IAC5G,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,6CAA6C;IAC7F,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC,CAAC,8BAA8B;IACnF,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC,CAAC,wBAAwB;IACrE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC,CAAC,uBAAuB;IACpE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC,CAAC,YAAY;IACzD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gFAAgF;AAEhF,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAClF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,KAAwB;IAChE,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;QACxB,MAAM,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QACjF,OAAO,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;AACL,CAAC;AAUD,2EAA2E;AAC3E,SAAS,UAAU,CAAC,KAAa;IAC/B,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACrG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,IAAY,EAAE,MAAoB;IAC3E,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,0DAA0D,EAAE,CAAC;IAC7G,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC9F,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EACJ,MAAM,CAAC,KAAK,KAAK,OAAO;gBACtB,CAAC,CAAC,kEAAkE;gBACpE,CAAC,CAAC,iCAAiC;SACxC,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC;IACrG,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,IAAI,gCAAgC,EAAE,CAAC;IAC3F,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC;AAID,MAAM,cAAc,GAAa,KAAK,EAAE,IAAI,EAAE,EAAE,CAC9C,CAAC,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AAEhF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,IAAY,EACZ,MAAoB,EACpB,UAAoB,cAAc;IAElC,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IACjC,IAAI,SAAmB,CAAC;IACxB,IAAI,CAAC;QACH,SAAS,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAuB,GAAa,CAAC,OAAO,EAAE,EAAE,CAAC;IAClF,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACtF,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IAC/C,IAAI,GAAG;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,GAAG,GAAG,EAAE,CAAC;IACrF,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;AAChD,CAAC;AAaD,SAAS,UAAU,CAAC,IAAgB;IAClC,OAAO,CAAC,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,aAAa,CAAC,SAAiB,EAAE,WAAmB;IAC3D,MAAM,CAAC,GAAG,iCAAiC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC5D,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AACjE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAwB;IACxD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,cAAc,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAE1F,KAAK,UAAU,IAAI,CACjB,IAAgB,EAChB,IAAY,EACZ,IAAY;QAEZ,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;QACjE,MAAM,CAAC,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAC1D,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;YAC5H,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;QAC3C,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IAChC,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAClD,IAAI,MAAW,CAAC;QAChB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;YAC3D,OAAO;QACT,CAAC;QACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YAChC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,mEAAmE,CAAC,CAAC;YAC5F,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACxD,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,EAAE,CAAC;YACtB,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;YACzG,OAAO;QACT,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAC3B;YACE,IAAI,EAAE,CAAC,CAAC,OAAO;YACf,IAAI;YACJ,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,IAAI,EAAE,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM;YACrC,OAAO,EAAE,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE;YAC9C,gBAAgB,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC;SACjD,EACD,CAAC,EAAE,EAAE,EAAE;YACL,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,UAAU,IAAI,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;YAChD,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACf,CAAC,CACF,CAAC;QACF,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QACvF,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,GAAyB,EAAE,MAAkB,EAAE,IAAY,EAAE,EAAE;QACzF,MAAM,EAAE,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;QAC7C,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,MAAM,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;YAC/C,OAAO;QACT,CAAC;QACD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,EAAE,CAAC;YACtB,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,MAAM,2EAA2E,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;YACxH,OAAO;QACT,CAAC;QACD,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QAC7C,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;YAC5B,MAAM,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;YAC5D,IAAI,IAAI,CAAC,MAAM;gBAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACtC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACtB,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxB,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7C,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/lib/box/evidence.d.ts

@@ -0,0 +1,86 @@
+/**
+ * What a box run hands back: the evidence bundle (runbox design C4 "Outputs";
+ * BOX-CONTRACT v2 finish). Exit code, duration, the log kept as head + tail
+ * under a cap, the /out files (with their upload tokens), the blocked-egress
+ * list and the packages actually installed.
+ *
+ * A run that did not answer (the clone failed, the box never reported) carries
+ * status `infra`: INFRA is never the script's verdict. A wall-clock kill is
+ * `timeout`, the script's doing, not INFRA.
+ */
+import type { BlockedEgress } from "./egress.js";
+import type { FinishBody, FinishedFile, FinishStatus } from "./wire.js";
+/** BOX-CONTRACT: head 64 KiB + tail 64 KiB. */
+export declare const LOG_HEAD_BYTES: number;
+export declare const LOG_TAIL_BYTES: number;
+/** Keeps the first HEAD bytes and the last TAIL bytes of a stream, counts all. */
+export declare class LogCapture {
+    private readonly headCap;
+    private readonly tailCap;
+    private head;
+    private headLen;
+    private tail;
+    private tailLen;
+    totalBytes: number;
+    constructor(headCap?: number, tailCap?: number);
+    append(chunk: Buffer | string): void;
+    snapshot(): RunLog;
+}
+export interface RunLog {
+    head: string;
+    /** Everything after the head when nothing was dropped; otherwise the last bytes. */
+    tail: string;
+    totalBytes: number;
+    /** Bytes were dropped between head and tail. */
+    truncated: boolean;
+}
+export interface InstalledPackage {
+    name: string;
+    version: string;
+    manager: "pip" | "npm";
+}
+export interface RunOutcome {
+    /** The exit code the box runner reported, or null when it reported none. */
+    exitCode: number | null;
+    timedOut: boolean;
+    /** A person pressed Stop. */
+    stopped: boolean;
+    /** Set when the run did not answer for an infrastructure reason. */
+    infraReason?: string;
+}
+/**
+ * One status from what happened. Order matters: a person's Stop beats the
+ * wall clock, the wall clock beats an exit code that came too late, and INFRA
+ * is reported only when the script gave no verdict.
+ */
+export declare function deriveStatus(o: RunOutcome): {
+    status: FinishStatus;
+    infraReason?: string;
+};
+/**
+ * The pod's finish schema (synap-backend `routers/hub-protocol/rest/box-runs.ts`
+ * FinishBody). A body over any of these is refused whole (400), and the run's
+ * evidence is lost with it, so the bundle is cut to fit HERE, and every cut is
+ * said in the log the person reads.
+ */
+export declare const WIRE: {
+    readonly maxBlocked: 500;
+    readonly maxPackages: 500;
+    readonly hostChars: 300;
+    readonly reasonChars: 500;
+    readonly infraReasonChars: 1000;
+    readonly pathChars: 500;
+    readonly titleChars: 255;
+    readonly packageNameChars: 214;
+    readonly packageVersionChars: 64;
+};
+export declare function assembleFinish(input: {
+    leaseId: string;
+    outcome: RunOutcome;
+    startedAt: number;
+    finishedAt: number;
+    log: LogCapture;
+    blockedEgress: BlockedEgress[];
+    installedPackages: InstalledPackage[];
+    files: FinishedFile[];
+}): FinishBody;

package/dist/lib/box/evidence.js

@@ -0,0 +1,121 @@
+/**
+ * What a box run hands back: the evidence bundle (runbox design C4 "Outputs";
+ * BOX-CONTRACT v2 finish). Exit code, duration, the log kept as head + tail
+ * under a cap, the /out files (with their upload tokens), the blocked-egress
+ * list and the packages actually installed.
+ *
+ * A run that did not answer (the clone failed, the box never reported) carries
+ * status `infra`: INFRA is never the script's verdict. A wall-clock kill is
+ * `timeout`, the script's doing, not INFRA.
+ */
+/** BOX-CONTRACT: head 64 KiB + tail 64 KiB. */
+export const LOG_HEAD_BYTES = 64 * 1024;
+export const LOG_TAIL_BYTES = 64 * 1024;
+/** Keeps the first HEAD bytes and the last TAIL bytes of a stream, counts all. */
+export class LogCapture {
+    headCap;
+    tailCap;
+    head = [];
+    headLen = 0;
+    tail = [];
+    tailLen = 0;
+    totalBytes = 0;
+    constructor(headCap = LOG_HEAD_BYTES, tailCap = LOG_TAIL_BYTES) {
+        this.headCap = headCap;
+        this.tailCap = tailCap;
+    }
+    append(chunk) {
+        let buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        this.totalBytes += buf.length;
+        if (this.headLen < this.headCap) {
+            const take = buf.subarray(0, this.headCap - this.headLen);
+            this.head.push(take);
+            this.headLen += take.length;
+            buf = buf.subarray(take.length);
+        }
+        if (buf.length === 0)
+            return;
+        this.tail.push(buf);
+        this.tailLen += buf.length;
+        while (this.tail.length > 1 && this.tailLen - this.tail[0].length >= this.tailCap) {
+            this.tailLen -= this.tail.shift().length;
+        }
+    }
+    snapshot() {
+        const head = Buffer.concat(this.head).toString("utf8");
+        let tailBuf = Buffer.concat(this.tail);
+        if (tailBuf.length > this.tailCap)
+            tailBuf = tailBuf.subarray(tailBuf.length - this.tailCap);
+        const truncated = this.totalBytes > this.headLen + tailBuf.length;
+        return { head, tail: tailBuf.toString("utf8"), totalBytes: this.totalBytes, truncated };
+    }
+}
+/**
+ * One status from what happened. Order matters: a person's Stop beats the
+ * wall clock, the wall clock beats an exit code that came too late, and INFRA
+ * is reported only when the script gave no verdict.
+ */
+export function deriveStatus(o) {
+    if (o.stopped)
+        return { status: "stopped" };
+    if (o.timedOut)
+        return { status: "timeout" };
+    if (o.infraReason)
+        return { status: "infra", infraReason: o.infraReason };
+    if (o.exitCode === null)
+        return { status: "infra", infraReason: "the box ended without reporting an exit code" };
+    return { status: o.exitCode === 0 ? "done" : "failed" };
+}
+/**
+ * The pod's finish schema (synap-backend `routers/hub-protocol/rest/box-runs.ts`
+ * FinishBody). A body over any of these is refused whole (400), and the run's
+ * evidence is lost with it, so the bundle is cut to fit HERE, and every cut is
+ * said in the log the person reads.
+ */
+export const WIRE = {
+    maxBlocked: 500,
+    maxPackages: 500,
+    hostChars: 300,
+    reasonChars: 500,
+    infraReasonChars: 1000,
+    pathChars: 500,
+    titleChars: 255,
+    packageNameChars: 214,
+    packageVersionChars: 64,
+};
+const cut = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+export function assembleFinish(input) {
+    const d = deriveStatus(input.outcome);
+    const blocked = input.blockedEgress;
+    if (blocked.length > WIRE.maxBlocked) {
+        input.log.append(`\n[synap box] ${blocked.length - WIRE.maxBlocked} more blocked connections not listed (first ${WIRE.maxBlocked} kept)\n`);
+    }
+    const packages = input.installedPackages.filter((p) => p.name && p.version);
+    if (packages.length > WIRE.maxPackages) {
+        input.log.append(`\n[synap box] ${packages.length - WIRE.maxPackages} more installed packages not listed\n`);
+    }
+    return {
+        leaseId: input.leaseId,
+        status: d.status,
+        exitCode: input.outcome.exitCode,
+        durationMs: Math.max(0, Math.round(input.finishedAt - input.startedAt)),
+        ...(d.infraReason ? { infraReason: cut(d.infraReason, WIRE.infraReasonChars) } : {}),
+        log: input.log.snapshot(),
+        files: input.files.map((f) => ({
+            ...f,
+            path: cut(f.path, WIRE.pathChars),
+            ...(f.title !== undefined ? { title: cut(f.title, WIRE.titleChars) } : {}),
+        })),
+        blockedEgress: blocked.slice(0, WIRE.maxBlocked).map((b) => ({
+            ...b,
+            host: cut(b.host, WIRE.hostChars),
+            reason: cut(b.reason, WIRE.reasonChars),
+        })),
+        installedPackages: packages.slice(0, WIRE.maxPackages).map((p) => ({
+            ...p,
+            name: cut(p.name, WIRE.packageNameChars),
+            version: cut(p.version, WIRE.packageVersionChars),
+        })),
+    };
+}
+//# sourceMappingURL=evidence.js.map

package/dist/lib/box/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../../src/lib/box/evidence.ts"],"names":[],"mappings":"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"}

package/dist/lib/box/job-server.d.ts

@@ -0,0 +1,72 @@
+/**
+ * What the box talks to: a small HTTP server on the provisioner's bridge
+ * address. The box holds no token: its identity IS its address on the isolated
+ * bridge (the provisioner assigned it), so a request is answered only for the
+ * run that address was given to.
+ *
+ *   GET  /job          the script, its packages, parameters and wall clock
+ *   POST /phase        {"phase":"run"}: packages are in, egress narrows to the
+ *                      declared hosts (one way: never back to setup)
+ *   POST /log          a chunk of the run's stdout+stderr
+ *   PUT  /out/<path>   one /out file, streamed to staging under the caps
+ *   POST /done         {"exitCode", "installedPackages"}
+ */
+import http from "node:http";
+import type { BlockedEgress, BoxPhase, EgressPolicy } from "./egress.js";
+import { LogCapture, type InstalledPackage } from "./evidence.js";
+import type { LeasedRun } from "./wire.js";
+/** BOX-CONTRACT v1: at most 20 files per run. */
+export declare const MAX_OUT_FILES = 20;
+export interface StagedFile {
+    path: string;
+    size: number;
+    sha256: string;
+}
+export interface BoxReport {
+    /** null when the runner sent no integer exit code (the runner's fault, read as INFRA). */
+    exitCode: number | null;
+    installedPackages: InstalledPackage[];
+}
+export interface ActiveBox {
+    run: LeasedRun;
+    phase: BoxPhase;
+    log: LogCapture;
+    blocked: BlockedEgress[];
+    outDir: string;
+    outBytes: number;
+    outFiles: StagedFile[];
+    /** The runner asked for its job (the box booted and reached the provisioner). */
+    jobFetched: boolean;
+    /** Resolves when the runner reports done. */
+    done: Promise<BoxReport>;
+}
+/**
+ * A safe relative path for an /out file, or null. Each segment is decoded
+ * once; no empty, `.`, `..`, NUL or separator inside a segment.
+ */
+export declare function safeOutPath(urlPath: string): string | null;
+/** The job document the box runner reads. */
+export declare function jobFor(run: LeasedRun): Record<string, unknown>;
+type Entry = ActiveBox & {
+    finish: (r: BoxReport) => void;
+};
+/** `job`: the box booted and asked for its job; `run`: its packages are in, the script starts. */
+export type BoxEvent = "job" | "run";
+export declare class BoxRegistry {
+    private readonly stagingRoot;
+    private boxes;
+    /** Called once per box and event (the provisioner sets it per run: its clocks hang on it). */
+    onEvent: (run: LeasedRun, event: BoxEvent) => void;
+    constructor(stagingRoot: string);
+    register(ip: string, run: LeasedRun): ActiveBox;
+    /** Forget the box and drop its staged files. */
+    unregister(ip: string): void;
+    get(ip: string): Entry | undefined;
+    policyFor(ip: string): EgressPolicy | null;
+    recordBlock(ip: string, block: BlockedEgress): void;
+    markJobFetched(ip: string): void;
+    enterRunPhase(ip: string): void;
+}
+export declare function parseReport(raw: unknown): BoxReport;
+export declare function createJobServer(registry: BoxRegistry): http.Server;
+export {};