@schemavaults/sandbox-management-sdk 0.0.0-stage → 0.1.0

package/dist/docker/egress-proxy/config.d.ts

@@ -0,0 +1,20 @@
+import type { SandboxNetworkAllowlist } from "../../types.js";
+/** Environment variable the proxy image reads its `EgressProxyConfig` from, as JSON. */
+export declare const EGRESS_PROXY_CONFIG_ENV = "SANDBOX_EGRESS_PROXY_CONFIG";
+/** A TCP port the proxy forwards to the sandbox, so it can be published on the host. */
+export interface EgressProxyForward {
+    port: number;
+    host: string;
+    targetPort: number;
+}
+export interface EgressProxyConfig {
+    /** Port of the HTTP proxy (plain requests and `CONNECT`). */
+    port: number;
+    policy: SandboxNetworkAllowlist;
+    /** CIDRs of the clients that may use the HTTP proxy. Loopback always may. */
+    clients: string[];
+    forwards: EgressProxyForward[];
+}
+/** Parses and checks `SANDBOX_EGRESS_PROXY_CONFIG`. Throws a descriptive `Error`. */
+export declare function parseEgressProxyConfig(raw: string | undefined): EgressProxyConfig;
+export declare function isPort(value: unknown): value is number;

package/dist/docker/egress-proxy/config.js

@@ -0,0 +1,29 @@
+import { validateNetworkPolicy } from "../../network.js";
+import { ranges } from "./policy.js";
+/** Environment variable the proxy image reads its `EgressProxyConfig` from, as JSON. */
+export const EGRESS_PROXY_CONFIG_ENV = "SANDBOX_EGRESS_PROXY_CONFIG";
+/** Parses and checks `SANDBOX_EGRESS_PROXY_CONFIG`. Throws a descriptive `Error`. */
+export function parseEgressProxyConfig(raw) {
+    if (!raw)
+        throw new Error(`${EGRESS_PROXY_CONFIG_ENV} is not set`);
+    const config = JSON.parse(raw);
+    if (!isPort(config.port))
+        throw new Error("config.port must be a port number");
+    if (typeof config.policy !== "object" || config.policy === null)
+        throw new Error("config.policy must be an allowlist");
+    validateNetworkPolicy(config.policy);
+    if (!Array.isArray(config.clients))
+        throw new Error("config.clients must be an array of CIDRs");
+    ranges(config.clients);
+    if (!Array.isArray(config.forwards))
+        throw new Error("config.forwards must be an array");
+    for (const forward of config.forwards) {
+        if (!isPort(forward?.port) || !isPort(forward.targetPort) || typeof forward.host !== "string") {
+            throw new Error("config.forwards entries must be { port, host, targetPort }");
+        }
+    }
+    return config;
+}
+export function isPort(value) {
+    return Number.isInteger(value) && value >= 1 && value <= 65535;
+}

package/dist/docker/egress-proxy/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/docker/egress-proxy/main.js

@@ -0,0 +1,19 @@
+/**
+ * Entry point of the egress proxy image (`images/egress-proxy`). Reads its
+ * config from `SANDBOX_EGRESS_PROXY_CONFIG`. `--health` checks a running
+ * proxy instead, for the image's HEALTHCHECK.
+ */
+import { EGRESS_PROXY_CONFIG_ENV, parseEgressProxyConfig } from "./config.js";
+import { startEgressProxy } from "./server.js";
+const config = parseEgressProxyConfig(process.env[EGRESS_PROXY_CONFIG_ENV]);
+if (process.argv.includes("--health")) {
+    const response = await fetch(`http://127.0.0.1:${config.port}/healthz`, { signal: AbortSignal.timeout(2000) }).catch(() => null);
+    process.exit(response?.ok ? 0 : 1);
+}
+const proxy = await startEgressProxy(config, {
+    log: (line) => console.log(`${new Date().toISOString()} ${line}`),
+});
+console.log(`egress proxy listening on :${proxy.port}` +
+    config.forwards.map((forward) => `, forwarding :${forward.port} to ${forward.host}:${forward.targetPort}`).join(""));
+for (const signal of ["SIGTERM", "SIGINT"])
+    process.once(signal, () => process.exit(0));

package/dist/docker/egress-proxy/policy.d.ts

@@ -0,0 +1,49 @@
+import type { CidrRange } from "../../network.js";
+import type { SandboxNetworkAllowlist } from "../../types.js";
+/** Destinations the proxy never connects to: its own loopback and the unspecified address. */
+export declare const PROXY_LOCAL_CIDRS: string[];
+export type EgressDecision = {
+    allowed: true;
+    address: string;
+} | {
+    allowed: false;
+    reason: string;
+};
+/**
+ * `spec.network` allowlist semantics, shared with Vercel:
+ *
+ * - A host name is allowed if it is on `allowDomains`, or if it resolves to an
+ *   address in `allowCidrs`. A leading `*.` matches any subdomain (not the
+ *   domain itself), and `"*"` matches every name.
+ * - An IP address is allowed if it is in `allowCidrs`.
+ * - Addresses in `denyCidrs` are never connected to, whatever allowed them.
+ */
+export declare class EgressPolicy {
+    private readonly anyDomain;
+    private readonly domains;
+    private readonly suffixes;
+    private readonly allowRanges;
+    private readonly denyRanges;
+    constructor(allowlist: SandboxNetworkAllowlist, { alwaysDeny }?: {
+        alwaysDeny?: string[];
+    });
+    /** Whether `name` (a normalized host name, not an IP address) is on the domain allowlist. */
+    allowsName(name: string): boolean;
+    /**
+     * Whether `name` must be resolved to decide on it. Names that are neither
+     * allowlisted nor could match `allowCidrs` are refused without a DNS query,
+     * so a sandbox cannot use the proxy to leak data through DNS lookups.
+     */
+    needsResolution(name: string): boolean;
+    /**
+     * Picks the address to connect to for `host` (normalized with
+     * `normalizeHost`), given what it resolved to. An IP address host resolves
+     * to itself.
+     */
+    decide(host: string, addresses: string[]): EgressDecision;
+}
+/** Lowercases a host, and strips IPv6 brackets and a trailing dot. */
+export declare function normalizeHost(host: string): string;
+/** Whether `address` (as a socket reports it) is in one of `ranges`. */
+export declare function addressInRanges(address: string | undefined, cidrs: readonly CidrRange[]): boolean;
+export declare function ranges(cidrs: readonly string[]): CidrRange[];

package/dist/docker/egress-proxy/policy.js

@@ -0,0 +1,89 @@
+import { cidrContains, parseCidr, parseIp } from "../../network.js";
+/** Destinations the proxy never connects to: its own loopback and the unspecified address. */
+export const PROXY_LOCAL_CIDRS = ["127.0.0.0/8", "0.0.0.0/8", "::1/128", "::/128"];
+/**
+ * `spec.network` allowlist semantics, shared with Vercel:
+ *
+ * - A host name is allowed if it is on `allowDomains`, or if it resolves to an
+ *   address in `allowCidrs`. A leading `*.` matches any subdomain (not the
+ *   domain itself), and `"*"` matches every name.
+ * - An IP address is allowed if it is in `allowCidrs`.
+ * - Addresses in `denyCidrs` are never connected to, whatever allowed them.
+ */
+export class EgressPolicy {
+    anyDomain;
+    domains;
+    suffixes;
+    allowRanges;
+    denyRanges;
+    constructor(allowlist, { alwaysDeny = PROXY_LOCAL_CIDRS } = {}) {
+        const domains = (allowlist.allowDomains ?? []).map((domain) => domain.toLowerCase());
+        this.anyDomain = domains.includes("*");
+        this.domains = new Set(domains.filter((domain) => !domain.startsWith("*")));
+        this.suffixes = domains.filter((domain) => domain.startsWith("*.")).map((domain) => domain.slice(1));
+        this.allowRanges = ranges(allowlist.allowCidrs ?? []);
+        this.denyRanges = ranges([...(allowlist.denyCidrs ?? []), ...alwaysDeny]);
+    }
+    /** Whether `name` (a normalized host name, not an IP address) is on the domain allowlist. */
+    allowsName(name) {
+        return this.anyDomain || this.domains.has(name) || this.suffixes.some((suffix) => name.endsWith(suffix));
+    }
+    /**
+     * Whether `name` must be resolved to decide on it. Names that are neither
+     * allowlisted nor could match `allowCidrs` are refused without a DNS query,
+     * so a sandbox cannot use the proxy to leak data through DNS lookups.
+     */
+    needsResolution(name) {
+        return this.allowsName(name) || this.allowRanges.length > 0;
+    }
+    /**
+     * Picks the address to connect to for `host` (normalized with
+     * `normalizeHost`), given what it resolved to. An IP address host resolves
+     * to itself.
+     */
+    decide(host, addresses) {
+        const nameAllowed = parseIp(host) === null && this.allowsName(host);
+        let blocked = false;
+        for (const address of addresses) {
+            const ip = parseIp(address);
+            if (ip === null)
+                continue;
+            const allowed = nameAllowed || this.allowRanges.some((range) => cidrContains(range, comparable(ip)));
+            if (!allowed)
+                continue;
+            if (this.denyRanges.some((range) => cidrContains(range, comparable(ip)))) {
+                blocked = true;
+                continue;
+            }
+            return { allowed: true, address };
+        }
+        return {
+            allowed: false,
+            reason: blocked
+                ? `${host} only resolves to blocked addresses`
+                : `${host} is not on this sandbox's network allowlist`,
+        };
+    }
+}
+/** Lowercases a host, and strips IPv6 brackets and a trailing dot. */
+export function normalizeHost(host) {
+    const unbracketed = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+    return unbracketed.toLowerCase().replace(/\.$/, "");
+}
+/** Whether `address` (as a socket reports it) is in one of `ranges`. */
+export function addressInRanges(address, cidrs) {
+    const ip = address === undefined ? null : parseIp(address);
+    return ip !== null && cidrs.some((range) => cidrContains(range, comparable(ip)));
+}
+export function ranges(cidrs) {
+    return cidrs.map((cidr) => {
+        const range = parseCidr(cidr);
+        if (range === null)
+            throw new Error(`Invalid CIDR "${cidr}"`);
+        return range;
+    });
+}
+/** IPv4-mapped IPv6 addresses (`::ffff:a.b.c.d`) compare as the IPv4 address they carry. */
+function comparable(ip) {
+    return ip.version === 6 && ip.value >> 32n === 0xffffn ? { version: 4, value: ip.value & 0xffffffffn } : ip;
+}

package/dist/docker/egress-proxy/server.d.ts

@@ -0,0 +1,25 @@
+import type { EgressProxyConfig } from "./config.js";
+export interface EgressProxyOptions {
+    /** Listen address. Default `"0.0.0.0"`. */
+    host?: string;
+    /** Resolves a host name to addresses. Default: the system resolver. */
+    resolve?: (name: string) => Promise<string[]>;
+    /** Destinations always refused. Default `PROXY_LOCAL_CIDRS` (the proxy's own loopback). */
+    alwaysDeny?: string[];
+    log?: (line: string) => void;
+}
+export interface RunningEgressProxy {
+    /** Port the HTTP proxy listens on (differs from the config when it asked for port 0). */
+    port: number;
+    /** Listening port of each forward, in config order. */
+    forwardPorts: number[];
+    close(): Promise<void>;
+}
+/**
+ * Starts the egress proxy that enforces a sandbox's network allowlist. The
+ * sandbox reaches the internet only through it, as an HTTP proxy
+ * (`HTTP_PROXY` / `HTTPS_PROXY`): plain `http://` requests are forwarded and
+ * everything else is tunneled with `CONNECT`, so TLS stays end to end. It
+ * also forwards the sandbox's published ports.
+ */
+export declare function startEgressProxy(config: EgressProxyConfig, options?: EgressProxyOptions): Promise<RunningEgressProxy>;

package/dist/docker/egress-proxy/server.js

@@ -0,0 +1,225 @@
+import { lookup } from "node:dns/promises";
+import { STATUS_CODES, createServer as createHttpServer, request as httpRequest } from "node:http";
+import { connect, createServer as createTcpServer } from "node:net";
+import { parseIp } from "../../network.js";
+import { isPort } from "./config.js";
+import { EgressPolicy, PROXY_LOCAL_CIDRS, addressInRanges, normalizeHost, ranges } from "./policy.js";
+const LOOPBACK_CLIENTS = ["127.0.0.0/8", "::1/128"];
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+/**
+ * Starts the egress proxy that enforces a sandbox's network allowlist. The
+ * sandbox reaches the internet only through it, as an HTTP proxy
+ * (`HTTP_PROXY` / `HTTPS_PROXY`): plain `http://` requests are forwarded and
+ * everything else is tunneled with `CONNECT`, so TLS stays end to end. It
+ * also forwards the sandbox's published ports.
+ */
+export async function startEgressProxy(config, options = {}) {
+    const host = options.host ?? "0.0.0.0";
+    const log = options.log ?? (() => undefined);
+    const resolve = options.resolve ?? (async (name) => (await lookup(name, { all: true })).map((entry) => entry.address));
+    const policy = new EgressPolicy(config.policy, { alwaysDeny: options.alwaysDeny ?? PROXY_LOCAL_CIDRS });
+    const clients = ranges([...config.clients, ...LOOPBACK_CLIENTS]);
+    const sockets = new Set();
+    const track = (socket) => {
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+    };
+    /** Decides on a connection to `target:port`; `method` is for the log (`CONNECT`, `GET`, ...). */
+    async function route(method, target, port) {
+        const name = normalizeHost(target);
+        let addresses = [name];
+        if (parseIp(name) === null && policy.needsResolution(name)) {
+            try {
+                addresses = await resolve(name);
+            }
+            catch {
+                return { allowed: false, status: 502, reason: `could not resolve ${name}` };
+            }
+        }
+        const decision = policy.decide(name, addresses);
+        log(decision.allowed
+            ? `allow ${method} ${name}:${port} -> ${decision.address}`
+            : `deny ${method} ${name}:${port}: ${decision.reason}`);
+        return decision.allowed ? decision : { allowed: false, status: 403, reason: decision.reason };
+    }
+    const proxy = createHttpServer();
+    proxy.on("connection", (socket) => {
+        if (!addressInRanges(socket.remoteAddress, clients)) {
+            log(`refuse client ${socket.remoteAddress}`);
+            socket.destroy();
+            return;
+        }
+        track(socket);
+    });
+    proxy.on("request", (req, res) => {
+        void forwardRequest(req, res).catch((error) => {
+            if (!res.headersSent)
+                reply(res, 502, `Proxy error: ${message(error)}`);
+            else
+                res.destroy();
+        });
+    });
+    proxy.on("connect", (req, socket, head) => {
+        void tunnel(req, socket, head).catch(() => socket.destroy());
+    });
+    proxy.on("upgrade", (_req, socket) => {
+        refuse(socket, 501, "Upgrades over plain HTTP are not supported; use CONNECT");
+    });
+    proxy.on("clientError", (_error, socket) => {
+        if (socket.writable)
+            socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n");
+        else
+            socket.destroy();
+    });
+    async function forwardRequest(req, res) {
+        const target = req.url ?? "";
+        if (target.startsWith("/")) {
+            if (target === "/healthz")
+                return reply(res, 200, "ok");
+            return reply(res, 400, "This is the sandbox egress proxy: send proxy requests (absolute URLs or CONNECT)");
+        }
+        let url;
+        try {
+            url = new URL(target);
+        }
+        catch {
+            return reply(res, 400, `Invalid request target ${target}`);
+        }
+        if (url.protocol !== "http:") {
+            return reply(res, 400, `Only http:// URLs can be forwarded; tunnel ${url.protocol} with CONNECT`);
+        }
+        const port = url.port ? Number(url.port) : 80;
+        const decision = await route(req.method ?? "GET", url.hostname, port);
+        if (!decision.allowed)
+            return reply(res, decision.status, `Blocked by the sandbox egress proxy: ${decision.reason}`);
+        const upstream = httpRequest({
+            host: decision.address,
+            port,
+            method: req.method,
+            path: `${url.pathname}${url.search}`,
+            headers: { ...withoutHopByHop(req.headers), host: url.host },
+            agent: false,
+            setHost: false,
+        });
+        upstream.on("response", (response) => {
+            const status = response.statusCode ?? 502;
+            res.writeHead(status, response.statusMessage || STATUS_CODES[status] || "", withoutHopByHop(response.headers));
+            response.pipe(res);
+        });
+        upstream.on("error", (error) => {
+            if (!res.headersSent)
+                reply(res, 502, `Could not reach ${url.host}: ${message(error)}`);
+            else
+                res.destroy();
+        });
+        res.on("close", () => upstream.destroy());
+        req.pipe(upstream);
+    }
+    async function tunnel(req, client, head) {
+        const target = parseAuthority(req.url ?? "");
+        if (target === null)
+            return refuse(client, 400, `Invalid CONNECT target ${req.url}`);
+        const decision = await route("CONNECT", target.host, target.port);
+        if (!decision.allowed)
+            return refuse(client, decision.status, `Blocked by the sandbox egress proxy: ${decision.reason}`);
+        const upstream = connect({ host: decision.address, port: target.port, allowHalfOpen: true });
+        track(upstream);
+        const onConnectError = (error) => refuse(client, 502, `Could not reach ${req.url}: ${error.message}`);
+        upstream.once("error", onConnectError);
+        upstream.once("connect", () => {
+            upstream.off("error", onConnectError);
+            client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+            if (head.length > 0)
+                upstream.write(head);
+            splice(client, upstream);
+        });
+        client.once("close", () => upstream.destroy());
+    }
+    const forwardServers = config.forwards.map((forward) => createTcpServer({ allowHalfOpen: true }, (client) => {
+        track(client);
+        const upstream = connect({ host: forward.host, port: forward.targetPort, allowHalfOpen: true });
+        track(upstream);
+        splice(client, upstream);
+    }));
+    const port = await listen(proxy, config.port, host);
+    const forwardPorts = [];
+    for (const [index, server] of forwardServers.entries()) {
+        forwardPorts.push(await listen(server, config.forwards[index].port, host));
+    }
+    return {
+        port,
+        forwardPorts,
+        async close() {
+            for (const socket of sockets)
+                socket.destroy();
+            await Promise.all([proxy, ...forwardServers].map((server) => new Promise((done) => server.close(done))));
+        },
+    };
+}
+/** Pipes two sockets into each other, passing half-closes through, until both sides are done. */
+function splice(a, b) {
+    a.pipe(b);
+    b.pipe(a);
+    const destroy = () => {
+        a.destroy();
+        b.destroy();
+    };
+    a.once("error", destroy);
+    b.once("error", destroy);
+    a.once("close", () => b.destroy());
+    b.once("close", () => a.destroy());
+}
+function parseAuthority(authority) {
+    const match = /^(\[[^\]]+\]|[^:[\]]+):(\d{1,5})$/.exec(authority);
+    if (!match)
+        return null;
+    const port = Number(match[2]);
+    return isPort(port) ? { host: match[1], port } : null;
+}
+function withoutHopByHop(headers) {
+    const listed = String(headers.connection ?? "")
+        .split(",")
+        .map((name) => name.trim().toLowerCase());
+    const result = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value !== undefined && !HOP_BY_HOP.has(name) && !listed.includes(name))
+            result[name] = value;
+    }
+    return result;
+}
+function reply(res, status, body) {
+    const text = `${body}\n`;
+    res.writeHead(status, {
+        "content-type": "text/plain; charset=utf-8",
+        "content-length": Buffer.byteLength(text),
+        connection: "close",
+    });
+    res.end(text);
+}
+function refuse(socket, status, body) {
+    const reason = { 400: "Bad Request", 403: "Forbidden", 501: "Not Implemented", 502: "Bad Gateway" }[status] ?? "Error";
+    const text = `${body}\n`;
+    socket.end(`HTTP/1.1 ${status} ${reason}\r\nContent-Type: text/plain; charset=utf-8\r\nContent-Length: ${Buffer.byteLength(text)}\r\nConnection: close\r\n\r\n${text}`);
+}
+function listen(server, port, host) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.off("error", reject);
+            resolve(server.address().port);
+        });
+    });
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/docker/egress.d.ts

@@ -0,0 +1,41 @@
+import type { SandboxProvider } from "../provider.js";
+import type { SandboxNetworkAllowlist, SandboxSpec } from "../types.js";
+import type { EgressProxyConfig } from "./egress-proxy/config.js";
+/**
+ * The egress proxy image published with this SDK version (built from
+ * `images/egress-proxy`). Keep the tag in step with `package.json`.
+ */
+export declare const DOCKER_EGRESS_PROXY_IMAGE = "ghcr.io/schemavaults/sandbox-egress-proxy:0.1.0";
+/** Label on a sandbox's egress proxy container and internal network; the value is the sandbox ID. */
+export declare const DOCKER_EGRESS_PROXY_LABEL = "dev.schemavaults.sandbox.egress-proxy";
+/** Host names of the proxy and the sandbox on the sandbox's internal network. */
+export declare const EGRESS_PROXY_ALIAS = "egress-proxy";
+export declare const SANDBOX_ALIAS = "sandbox";
+/**
+ * How a sandbox container is networked:
+ *
+ * - `direct`: attached to `networkMode` (`undefined` is Docker's default bridge,
+ *   `"none"` is no network at all).
+ * - `proxy`: attached only to an internal network of its own, with no route
+ *   out. Its egress proxy shares that network and `outsideNetwork`; it
+ *   enforces `policy` and forwards the sandbox's ports.
+ */
+export type DockerNetworkPlan = {
+    mode: "direct";
+    networkMode: string | undefined;
+} | {
+    mode: "proxy";
+    policy: SandboxNetworkAllowlist;
+    outsideNetwork: string;
+    proxyPort: number;
+};
+/** Whether the sandbox runs behind an egress proxy: an allowlist, or `"deny-all"` with published ports. */
+export declare function usesEgressProxy(spec: SandboxSpec): boolean;
+/** Works out the networking for `spec`, or throws a `SandboxError` if Docker cannot honor it. */
+export declare function dockerNetworkPlan(provider: Pick<SandboxProvider, "name" | "networkPolicies">, spec: SandboxSpec, network: string | undefined): DockerNetworkPlan;
+/** The proxy's config: the policy, who may use it (the internal network), and the ports to forward. */
+export declare function egressProxyConfig(plan: DockerNetworkPlan & {
+    mode: "proxy";
+}, spec: SandboxSpec, clients: string[]): EgressProxyConfig;
+/** Points HTTP clients in the sandbox at its egress proxy. `spec.env` can override any of these. */
+export declare function egressProxyEnv(proxyPort: number): Record<string, string>;

package/dist/docker/egress.js

@@ -0,0 +1,67 @@
+import { SandboxError } from "../errors.js";
+import { assertNetworkPolicySupported, networkPolicyKind } from "../network.js";
+/**
+ * The egress proxy image published with this SDK version (built from
+ * `images/egress-proxy`). Keep the tag in step with `package.json`.
+ */
+export const DOCKER_EGRESS_PROXY_IMAGE = "ghcr.io/schemavaults/sandbox-egress-proxy:0.1.0";
+/** Label on a sandbox's egress proxy container and internal network; the value is the sandbox ID. */
+export const DOCKER_EGRESS_PROXY_LABEL = "dev.schemavaults.sandbox.egress-proxy";
+/** Host names of the proxy and the sandbox on the sandbox's internal network. */
+export const EGRESS_PROXY_ALIAS = "egress-proxy";
+export const SANDBOX_ALIAS = "sandbox";
+const DEFAULT_PROXY_PORT = 3128;
+const UNUSABLE_OUTSIDE_NETWORKS = new Set(["none", "host"]);
+/** Whether the sandbox runs behind an egress proxy: an allowlist, or `"deny-all"` with published ports. */
+export function usesEgressProxy(spec) {
+    const kind = networkPolicyKind(spec.network);
+    return kind === "allowlist" || (kind === "deny-all" && (spec.ports?.length ?? 0) > 0);
+}
+/** Works out the networking for `spec`, or throws a `SandboxError` if Docker cannot honor it. */
+export function dockerNetworkPlan(provider, spec, network) {
+    // Also checked by the manager; repeated for callers that use the provider directly.
+    assertNetworkPolicySupported(provider, spec.network);
+    const kind = networkPolicyKind(spec.network);
+    if (kind === "allow-all")
+        return { mode: "direct", networkMode: network };
+    if (!usesEgressProxy(spec)) {
+        if (network !== undefined && network !== "none") {
+            throw new SandboxError(`spec.network "deny-all" conflicts with spec.providerOptions.docker.network "${network}"`);
+        }
+        return { mode: "direct", networkMode: "none" };
+    }
+    const outsideNetwork = network ?? "bridge";
+    if (UNUSABLE_OUTSIDE_NETWORKS.has(outsideNetwork) || outsideNetwork.startsWith("container:")) {
+        throw new SandboxError(`spec.providerOptions.docker.network "${outsideNetwork}" cannot carry the egress proxy's traffic; use a bridge network or leave it unset`);
+    }
+    const policy = kind === "allowlist" ? spec.network : {};
+    const ports = new Set(spec.ports ?? []);
+    let proxyPort = DEFAULT_PROXY_PORT;
+    while (ports.has(proxyPort))
+        proxyPort++;
+    return { mode: "proxy", policy, outsideNetwork, proxyPort };
+}
+/** The proxy's config: the policy, who may use it (the internal network), and the ports to forward. */
+export function egressProxyConfig(plan, spec, clients) {
+    return {
+        port: plan.proxyPort,
+        policy: plan.policy,
+        clients,
+        forwards: (spec.ports ?? []).map((port) => ({ port, host: SANDBOX_ALIAS, targetPort: port })),
+    };
+}
+/** Points HTTP clients in the sandbox at its egress proxy. `spec.env` can override any of these. */
+export function egressProxyEnv(proxyPort) {
+    const url = `http://${EGRESS_PROXY_ALIAS}:${proxyPort}`;
+    const local = "localhost,127.0.0.1,::1";
+    return {
+        HTTP_PROXY: url,
+        HTTPS_PROXY: url,
+        http_proxy: url,
+        https_proxy: url,
+        NO_PROXY: local,
+        no_proxy: local,
+        // Node.js (24+) only honors the variables above with this set.
+        NODE_USE_ENV_PROXY: "1",
+    };
+}

package/dist/docker/index.d.ts

@@ -0,0 +1,3 @@
+export { DOCKER_SANDBOX_ID_LABEL, DockerSandboxProvider } from "./provider.js";
+export type { DockerPullPolicy, DockerSandboxOptions, DockerSandboxProviderOptions } from "./provider.js";
+export { DOCKER_EGRESS_PROXY_IMAGE, DOCKER_EGRESS_PROXY_LABEL } from "./egress.js";

package/dist/docker/index.js

@@ -0,0 +1,2 @@
+export { DOCKER_SANDBOX_ID_LABEL, DockerSandboxProvider } from "./provider.js";
+export { DOCKER_EGRESS_PROXY_IMAGE, DOCKER_EGRESS_PROXY_LABEL } from "./egress.js";