@namzu/sandbox 1.1.0 → 2.0.0

package/src/backends/docker/index.ts

@@ -40,10 +40,14 @@ import {
 	type SandboxFileEntry,
 	type SandboxId,
 	type SandboxStatus,
+	withHint,
 } from '@namzu/sdk'
+import { EgressProxy } from '../../egress/index.js'
+import type { BrokeredCredential, RunningEgressProxy } from '../../egress/index.js'
 
 import {
 	ContainerSandboxLayoutValidationError,
+	type EgressPolicy,
 	type SandboxBackend,
 	type SandboxBackendOptions,
 } from '../../index.js'
@@ -69,6 +73,30 @@ export interface DockerBackendInternalConfig {
 	 */
 	readonly layout: ResolvedContainerSandboxLayout
 	readonly dockerBinary?: string
+
+	/**
+	 * `--user` value for the container, e.g. `'1000:1000'` or `'nobody'`.
+	 *
+	 * Left unset by default because the correct uid depends on the image's
+	 * own filesystem ownership, and forcing one would break every image
+	 * that expects root at startup. Set it whenever the image supports a
+	 * non-root user — a container running as root is one bind-mount
+	 * misconfiguration away from writing the host.
+	 */
+	readonly runAsUser?: string
+
+	/**
+	 * Credentials the egress proxy stamps on, per host.
+	 *
+	 * The point is that the real value never enters the sandbox. Any token
+	 * the agent needs to reach an allowed host used to have to be in the
+	 * container's environment — readable by the untrusted code it is meant
+	 * to be isolated from, via `/proc/self/environ` or via a prompt
+	 * injection that exfiltrates it over the very egress the policy
+	 * permits. Here it is held host-side and applied at the boundary.
+	 */
+	readonly brokeredCredentials?: readonly BrokeredCredential[]
+
 	readonly network?: 'none' | 'bridge' | string
 	readonly readyPollIntervalMs?: number
 	readonly readyTimeoutMs?: number
@@ -77,8 +105,8 @@ export interface DockerBackendInternalConfig {
 	 * (vanilla Docker namespaces, what Docker Desktop ships). Linux
 	 * production deployments that have registered gVisor on the host
 	 * daemon can pass `runsc` to upgrade to a userspace-kernel trust
-	 * boundary — same primitive Modal Labs and OpenAI Code Interpreter
-	 * ship. Hosts can also pass a custom runtime name registered in
+	 * boundary — the usual primitive for running untrusted code at
+	 * scale. Hosts can also pass a custom runtime name registered in
 	 * `daemon.json`. macOS Docker Desktop has no `runsc` runtime, so
 	 * the default `runc` is the only option there; that's documented
 	 * as the local-dev tier in the package README.
@@ -133,6 +161,81 @@ export function buildDockerBackend(config: DockerBackendInternalConfig): Sandbox
 	}
 }
 
+/**
+ * Reconcile the configured docker network with the caller's egress policy.
+ *
+ * The policy used to be accepted and silently ignored, which is worse than
+ * not supporting it: a host that set `deny-all` believed the container had
+ * no network and it had the configured one. Docker can enforce `deny-all`
+ * natively (`--network none`); it cannot enforce a host allowlist without
+ * a proxy this backend does not have, so those policies are REFUSED rather
+ * than quietly downgraded to "allow everything".
+ */
+export function resolveNetwork(
+	configured: string,
+	egress: EgressPolicy | undefined,
+	hasProxy = false,
+): string {
+	if (!egress) return configured
+
+	switch (egress.kind) {
+		case 'deny-all':
+			return 'none'
+		case 'allow-all':
+			return configured
+		default:
+			// A host allowlist needs something to filter through. With the
+			// egress proxy the container keeps its network and every request
+			// crosses that boundary; without one there is nothing to enforce
+			// with, and accepting the policy would grant everything while
+			// reporting that it had been restricted.
+			if (hasProxy) return configured
+			throw new Error(
+				`The docker sandbox backend cannot enforce an egress policy of kind '${egress.kind}' without an egress proxy: it has nothing to filter hosts through. Construct the provider with one, or use 'deny-all' / 'allow-all'. Refusing rather than silently granting full network access.`,
+			)
+	}
+}
+
+/**
+ * Hosts an allowlist policy permits.
+ *
+ * Only the two filtering kinds reach here. `deny-all` is enforced by the
+ * container runtime itself and `allow-all` needs no boundary, so routing
+ * either through an allowlist would answer a question nobody asked — and
+ * for `allow-all` it would answer "nothing", denying everything.
+ */
+export async function resolveAllowedHosts(egress: EgressPolicy): Promise<readonly string[]> {
+	if (egress.kind === 'static') return egress.allowedHosts
+	if (egress.kind === 'resolver') return await egress.resolve()
+	throw new Error(
+		`Egress policy of kind "${egress.kind}" does not describe a host allowlist and must not be routed through the proxy.`,
+	)
+}
+
+/** Whether a policy needs a boundary before it can be enforced at all. */
+export function needsEgressProxy(egress: EgressPolicy | undefined): boolean {
+	return egress?.kind === 'static' || egress?.kind === 'resolver'
+}
+
+/**
+ * Confinement flags applied to every container.
+ *
+ * A sandbox whose containers run as root with the full default capability
+ * set is not confining much: `CAP_DAC_OVERRIDE` alone walks past the
+ * read-only bind mounts the layout sets up, and without
+ * `no-new-privileges` a setuid binary inside the image re-escalates. These
+ * are the defaults every container runtime hardening guide starts with,
+ * and none of them were present.
+ *
+ * `--cap-drop=ALL` is deliberately not softened by a re-add list: a
+ * workload that genuinely needs a capability should say so through
+ * `extraRunArgs` and be visible in review.
+ */
+const HARDENING_ARGS: readonly string[] = ['--cap-drop=ALL', '--security-opt=no-new-privileges']
+
+/** Name the container reaches the host-side egress proxy by. */
+const PROXY_HOST_ALIAS = 'namzu-egress'
+
 async function spawnDockerSandbox(
 	config: DockerBackendInternalConfig,
 	options: SandboxBackendOptions,
@@ -140,7 +243,28 @@ async function spawnDockerSandbox(
 	const resolvedLayout = config.layout
 	const id = generateSandboxId()
 	const docker = config.dockerBinary ?? DEFAULT_DOCKER_BINARY
-	const network = config.network ?? 'none'
+
+	// The boundary a host allowlist is actually enforced at. Started before
+	// the container so its address can be handed in as proxy environment,
+	// and torn down with the sandbox — a proxy holding real credentials
+	// must not outlive the thing it was filtering for.
+	let egressProxy: RunningEgressProxy | undefined
+	if (needsEgressProxy(options.egress) && options.egress) {
+		const policy = options.egress
+		egressProxy = await new EgressProxy({
+			// Re-resolved per request rather than captured once, so a
+			// `resolver` policy that rotates is honoured and
+			// `setNetworkPolicy` can swap it on a live sandbox.
+			allowedHosts: () => resolveAllowedHosts(policy),
+			credentials: config.brokeredCredentials ?? [],
+		}).listen()
+	}
+
+	const network = resolveNetwork(
+		config.network ?? 'none',
+		options.egress,
+		egressProxy !== undefined,
+	)
 	const runtime = config.runtime
 	const hostReachability = config.hostReachability ?? 'host-port'
 	const containerName = `namzu-sandbox-${id}`
@@ -157,6 +281,17 @@ async function spawnDockerSandbox(
 		if (containerStarted) {
 			await runOnceQuiet(docker, ['rm', '-f', containerName])
 		}
+		// The proxy starts BEFORE the container and its only other close is
+		// in `destroy()`, which a create that never returned can never
+		// reach. So every failure between the two — a daemon that is down, a
+		// port that could not be read, a worker that missed its readiness
+		// deadline, a label the validator rejected — left a listening server
+		// on loopback stamping real credential headers, plus a retained
+		// event-loop handle, and a retry loop left one per attempt. That is
+		// exactly the invariant this file states where the proxy is started:
+		// it must not outlive the thing it was filtering for.
+		await egressProxy?.close().catch(() => undefined)
+		egressProxy = undefined
 	}
 
 	let hostPort: number
@@ -180,6 +315,8 @@ async function spawnDockerSandbox(
 			containerName,
 			'--network',
 			network,
+			...HARDENING_ARGS,
+			...(config.runAsUser ? ['--user', config.runAsUser] : []),
 		]
 
 		// `--label key=value` flags. Validate first — an empty key or
@@ -207,6 +344,25 @@ async function spawnDockerSandbox(
 		// log line. A skill loader that needs the manifest will
 		// write it to a bind path the worker reads at startup —
 		// avoids env-size limits, keeps the wire shape minimal.
+		if (egressProxy) {
+			// `host-gateway` is docker's own portable name for the host from
+			// inside a container; hard-coding a bridge address would break on
+			// every platform whose bridge is numbered differently. The proxy
+			// itself binds loopback, so this alias is the only way in.
+			args.push('--add-host', `${PROXY_HOST_ALIAS}:host-gateway`)
+			const proxyUrl = `http://${PROXY_HOST_ALIAS}:${egressProxy.port}`
+			// Both spellings: tooling is split between them, and a workload
+			// that reads only the one that is missing bypasses the boundary
+			// entirely — which would look exactly like the policy working.
+			for (const key of ['HTTP_PROXY', 'http_proxy', 'HTTPS_PROXY', 'https_proxy']) {
+				args.push('--env', `${key}=${proxyUrl}`)
+			}
+			// Loopback must not be proxied, or the worker cannot talk to
+			// itself.
+			args.push('--env', 'NO_PROXY=localhost,127.0.0.1')
+			args.push('--env', 'no_proxy=localhost,127.0.0.1')
+		}
+
 		args.push('--env', `NAMZU_SANDBOX_WORKSPACE=${rootDir}`)
 		args.push('--env', `NAMZU_SANDBOX_READ_ROOTS=${renderLayoutReadRootsEnv(resolvedLayout)}`)
 		args.push('--env', `NAMZU_SANDBOX_WRITE_ROOTS=${renderLayoutWriteRootsEnv(resolvedLayout)}`)
@@ -287,6 +443,24 @@ async function spawnDockerSandbox(
 			}
 		},
 
+		async setNetworkPolicy(policy): Promise<void> {
+			// Enforceable only through the egress proxy. Without one the
+			// container's network was fixed at creation — `--network none`
+			// or not — and there is nothing to narrow: accepting the policy
+			// here and doing nothing would leave the caller believing the
+			// sandbox had been confined when it had not. Same rule the
+			// egress-kind refusal above follows.
+			if (!egressProxy) {
+				throw withHint(
+					new Error(
+						'This sandbox cannot change its network policy: it was created without an egress proxy, so its network was fixed at creation and there is nothing to narrow. Refusing rather than accepting a policy that would not be applied.',
+					),
+					'Construct the provider with an egress proxy to make the policy mutable, or create a second sandbox under the narrower policy.',
+				)
+			}
+			egressProxy.setAllowedHosts(async () => policy.allowedHosts)
+		},
+
 		async writeFile(path: string, content: string | Buffer): Promise<void> {
 			const buf = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8')
 			let res: Response
@@ -341,6 +515,11 @@ async function spawnDockerSandbox(
 		async destroy(): Promise<void> {
 			status = 'destroyed'
 			await runOnceQuiet(docker, ['rm', '-f', containerName])
+			// The proxy holds real credentials and a live allowlist. Leaving
+			// it listening after the sandbox it was filtering for is gone
+			// means a loopback port that still stamps a token onto anything
+			// that asks — outliving the only thing that justified it.
+			await egressProxy?.close()
 			// Backend never allocates host paths — every bind source
 			// comes from the consumer-supplied layout. Container
 			// teardown is sufficient; the consumer's own lifecycle
@@ -366,8 +545,11 @@ async function readMappedPort(docker: string, containerName: string): Promise<nu
 	])
 	const port = Number(inspectOutput.trim())
 	if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-		throw new Error(
-			`docker inspect returned no usable host port mapping for ${containerName}: '${inspectOutput}'`,
+		throw withHint(
+			new Error(
+				`docker inspect returned no usable host port mapping for ${containerName}: '${inspectOutput}'`,
+			),
+			'The container started but its worker port was never published. Usually the container exited immediately — check its logs — or the host had no free port to bind.',
 		)
 	}
 	return port
@@ -405,9 +587,12 @@ async function execViaWorker(
 				: cause
 					? String(cause)
 					: 'unknown'
-		throw new Error(
-			`namzu-sandbox /execute fetch failed (baseUrl=${baseUrl}): ${err instanceof Error ? err.message : String(err)} — cause: ${causeMsg}`,
-			{ cause: err },
+		throw withHint(
+			new Error(
+				`namzu-sandbox /execute fetch failed (baseUrl=${baseUrl}): ${err instanceof Error ? err.message : String(err)} — cause: ${causeMsg}`,
+				{ cause: err },
+			),
+			'The container was reachable when it started, so it has most likely exited or been killed since — an out-of-memory kill under `memoryLimitMb` is the common cause. Check the container logs and its exit code.',
 		)
 	}
 	if (!res.ok || !res.body) {
@@ -541,10 +726,17 @@ async function waitForWorkerReady(
 		}
 		await new Promise((resolve) => setTimeout(resolve, pollMs))
 	}
-	throw new Error(
-		`namzu-sandbox worker did not become ready within ${timeoutMs}ms: ${
-			lastError instanceof Error ? lastError.message : String(lastError)
-		}`,
+	// A hint attached at the throw site, where the cause is actually known.
+	// The container runtime's own message says a request failed; it cannot
+	// say that the image may not be built or the daemon may not be running,
+	// which is what a reader needs.
+	throw withHint(
+		new Error(
+			`namzu-sandbox worker did not become ready within ${timeoutMs}ms: ${
+				lastError instanceof Error ? lastError.message : String(lastError)
+			}`,
+		),
+		'Check that the container runtime is running and that the sandbox worker image is built and reachable. A cold image pull can also exceed this window — raise the readiness timeout before assuming the worker is broken.',
 	)
 }
 

package/src/backends/firecracker/__tests__/agent-timeout-clamp.test.ts

@@ -0,0 +1,48 @@
+/**
+ * `resolveTimeoutMs` is the guest agent's only guard against a
+ * caller-requested `timeoutMs` that has no schema ceiling upstream (it
+ * traces back to the bash tool's model-authored `timeout` argument — see
+ * `packages/sdk/src/tools/builtins/bash.ts`). A request above the cap must
+ * be refused (the sibling `worker/server.js` answers `invalid_timeout` on
+ * response), not silently shortened — a caller that asked for more and got
+ * less without being told would believe its process was protected for the
+ * duration it actually asked for.
+ *
+ * Pure-function test, no socket/process involved, so it runs on every
+ * platform (unlike `backend.test.ts` / `transport.test.ts`, which spawn
+ * `/bin/sh` and skip on Windows).
+ */
+
+import { createRequire } from 'node:module'
+
+import { describe, expect, it } from 'vitest'
+
+const require_ = createRequire(import.meta.url)
+
+interface AgentModule {
+	resolveTimeoutMs(rawTimeoutMs: unknown): number
+}
+
+const agent = require_('../../../../agent/agent.cjs') as AgentModule
+
+describe('agent.cjs resolveTimeoutMs', () => {
+	it('passes through a caller value within the cap', () => {
+		expect(agent.resolveTimeoutMs(10_000)).toBe(10_000)
+	})
+
+	it('falls back to the default for an omitted value', () => {
+		expect(agent.resolveTimeoutMs(undefined)).toBe(5 * 60 * 1000)
+	})
+
+	it('refuses a request far above the cap instead of honoring or silently shortening it', () => {
+		expect(() => agent.resolveTimeoutMs(Number.MAX_SAFE_INTEGER)).toThrow(/timeoutMs/)
+		expect(() => agent.resolveTimeoutMs(10 ** 12)).toThrow(/timeoutMs/)
+	})
+
+	it('refuses a non-finite or non-positive value', () => {
+		expect(() => agent.resolveTimeoutMs(0)).toThrow(/timeoutMs/)
+		expect(() => agent.resolveTimeoutMs(-1)).toThrow(/timeoutMs/)
+		expect(() => agent.resolveTimeoutMs(Number.NaN)).toThrow(/timeoutMs/)
+		expect(() => agent.resolveTimeoutMs(Number.POSITIVE_INFINITY)).toThrow(/timeoutMs/)
+	})
+})

package/src/backends/firecracker/__tests__/backend.test.ts

@@ -20,6 +20,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { buildFirecrackerBackend, normalizeHandle } from '../index.js'
 import type { WireSandboxAgentHandle } from '../transport.js'
+import { localIpcPath } from './fixtures/ipc-path.js'
 import {
 	CA_CRT,
 	CLIENT_CRT,
@@ -27,6 +28,13 @@ import {
 	type RelayHandle,
 	startMtlsRelay,
 } from './fixtures/mtls-pki.js'
+// The loopback agent under test is the guest-side agent for a Linux microVM:
+// it spawns `/bin/sh` to run commands, and that binary does not exist on
+// Windows. These cases assert behavior the platform cannot produce, so they
+// skip there rather than leaving the suite permanently red for Windows
+// contributors. The socket-address fixture IS platform-correct, so the
+// transport is still exercised wherever it can be.
+const IS_WINDOWS = process.platform === 'win32'
 
 const require_ = createRequire(import.meta.url)
 
@@ -44,7 +52,7 @@ let realPath: string | undefined
 
 beforeEach(() => {
 	workDir = mkdtempSync(join(tmpdir(), 'fc-backend-test-'))
-	sockPath = join(workDir, 'agent.sock')
+	sockPath = localIpcPath(workDir)
 	realPath = process.env.PATH
 	process.env.NAMZU_SANDBOX_WORKSPACE = workDir
 	delete require_.cache[require_.resolve('../../../../agent/agent.cjs')]
@@ -101,7 +109,7 @@ function stubOrchestrator(handle: WireSandboxAgentHandle): {
 	return { calls }
 }
 
-describe('buildFirecrackerBackend (loopback agent)', () => {
+describe.skipIf(IS_WINDOWS)('buildFirecrackerBackend (loopback agent)', () => {
 	it('creates a Sandbox handle and round-trips exec/write/read/listFiles/destroy', async () => {
 		server = await startAgent()
 		const { calls } = stubOrchestrator({ kind: 'unix', path: sockPath })
@@ -350,69 +358,72 @@ describe('normalizeHandle (mtls cert injection)', () => {
 	})
 })
 
-describe('buildFirecrackerBackend (network mode over a loopback mTLS relay)', () => {
-	it('injects the client cert + round-trips exec/file-IO through the relay', async () => {
-		// The agent on a unix socket; a loopback mTLS relay in front of it.
-		server = await startAgent()
-		relay = await startMtlsRelay(sockPath)
-		// The orchestrator returns a WIRE mtls handle (NO cert material) whose
-		// host:port point at the relay; the relay resolves the sandboxId.
-		const { calls } = stubOrchestrator({
-			kind: 'mtls',
-			host: '127.0.0.1',
-			port: relay.port,
-			sandboxId: 'sb-net',
+describe.skipIf(IS_WINDOWS)(
+	'buildFirecrackerBackend (network mode over a loopback mTLS relay)',
+	() => {
+		it('injects the client cert + round-trips exec/file-IO through the relay', async () => {
+			// The agent on a unix socket; a loopback mTLS relay in front of it.
+			server = await startAgent()
+			relay = await startMtlsRelay(sockPath)
+			// The orchestrator returns a WIRE mtls handle (NO cert material) whose
+			// host:port point at the relay; the relay resolves the sandboxId.
+			const { calls } = stubOrchestrator({
+				kind: 'mtls',
+				host: '127.0.0.1',
+				port: relay.port,
+				sandboxId: 'sb-net',
+			})
+
+			const backend = buildFirecrackerBackend({
+				orchestratorEndpoint: 'https://orchestrator.test/',
+				getToken: async () => 'tok',
+				readyTimeoutMs: 5_000,
+				readyPollIntervalMs: 50,
+				// The CONSUMER-injected client material — never returned by the
+				// orchestrator. Merged onto the handle's `tls` block.
+				mtls: {
+					ca: CA_CRT,
+					cert: CLIENT_CRT,
+					key: CLIENT_KEY,
+					servername: 'sandbox.fc.internal',
+				},
+			})
+
+			const sandbox = await backend.create({ workingDirectory: workDir })
+			expect(sandbox.status).toBe('ready')
+
+			// The dialer wrote the `SANDBOX <id>` routing preamble (the relay's key).
+			expect(await relay.preamble()).toBe('sb-net')
+
+			// Full exec + file-IO round-trip over the mTLS tunnel.
+			const r = await sandbox.exec('/bin/sh', ['-c', 'echo hello-mtls'])
+			expect(r.stdout).toContain('hello-mtls')
+			await sandbox.writeFile('out/r.txt', 'via-relay')
+			expect((await sandbox.readFile('out/r.txt')).toString('utf8')).toBe('via-relay')
+
+			await sandbox.destroy()
+			expect(calls.some((c) => c.method === 'DELETE')).toBe(true)
 		})
 
-		const backend = buildFirecrackerBackend({
-			orchestratorEndpoint: 'https://orchestrator.test/',
-			getToken: async () => 'tok',
-			readyTimeoutMs: 5_000,
-			readyPollIntervalMs: 50,
-			// The CONSUMER-injected client material — never returned by the
-			// orchestrator. Merged onto the handle's `tls` block.
-			mtls: {
-				ca: CA_CRT,
-				cert: CLIENT_CRT,
-				key: CLIENT_KEY,
-				servername: 'sandbox.fc.internal',
-			},
-		})
-
-		const sandbox = await backend.create({ workingDirectory: workDir })
-		expect(sandbox.status).toBe('ready')
-
-		// The dialer wrote the `SANDBOX <id>` routing preamble (the relay's key).
-		expect(await relay.preamble()).toBe('sb-net')
-
-		// Full exec + file-IO round-trip over the mTLS tunnel.
-		const r = await sandbox.exec('/bin/sh', ['-c', 'echo hello-mtls'])
-		expect(r.stdout).toContain('hello-mtls')
-		await sandbox.writeFile('out/r.txt', 'via-relay')
-		expect((await sandbox.readFile('out/r.txt')).toString('utf8')).toBe('via-relay')
-
-		await sandbox.destroy()
-		expect(calls.some((c) => c.method === 'DELETE')).toBe(true)
-	})
-
-	it('rejects a create when the orchestrator returns mtls but no cert material is injected', async () => {
-		server = await startAgent()
-		relay = await startMtlsRelay(sockPath)
-		stubOrchestrator({
-			kind: 'mtls',
-			host: '127.0.0.1',
-			port: relay.port,
-			sandboxId: 'sb-net',
-		})
-		const backend = buildFirecrackerBackend({
-			orchestratorEndpoint: 'https://orchestrator.test/',
-			getToken: async () => 'tok',
-			readyTimeoutMs: 2_000,
-			readyPollIntervalMs: 50,
-			// No `mtls` material → normalizeHandle must throw at create time.
+		it('rejects a create when the orchestrator returns mtls but no cert material is injected', async () => {
+			server = await startAgent()
+			relay = await startMtlsRelay(sockPath)
+			stubOrchestrator({
+				kind: 'mtls',
+				host: '127.0.0.1',
+				port: relay.port,
+				sandboxId: 'sb-net',
+			})
+			const backend = buildFirecrackerBackend({
+				orchestratorEndpoint: 'https://orchestrator.test/',
+				getToken: async () => 'tok',
+				readyTimeoutMs: 2_000,
+				readyPollIntervalMs: 50,
+				// No `mtls` material → normalizeHandle must throw at create time.
+			})
+			await expect(backend.create({ workingDirectory: workDir })).rejects.toThrow(
+				/no client cert material was injected/,
+			)
 		})
-		await expect(backend.create({ workingDirectory: workDir })).rejects.toThrow(
-			/no client cert material was injected/,
-		)
-	})
-})
+	},
+)

package/src/backends/firecracker/__tests__/control-plane-mtls.test.ts

@@ -30,6 +30,7 @@ import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
 import { buildFirecrackerBackend } from '../index.js'
+import { localIpcPath } from './fixtures/ipc-path.js'
 import {
 	CA_CRT,
 	CLIENT_CRT,
@@ -39,6 +40,13 @@ import {
 	SERVER_CRT,
 	SERVER_KEY,
 } from './fixtures/mtls-pki.js'
+// The loopback agent under test is the guest-side agent for a Linux microVM:
+// it spawns `/bin/sh` to run commands, and that binary does not exist on
+// Windows. These cases assert behavior the platform cannot produce, so they
+// skip there rather than leaving the suite permanently red for Windows
+// contributors. The socket-address fixture IS platform-correct, so the
+// transport is still exercised wherever it can be.
+const IS_WINDOWS = process.platform === 'win32'
 
 const require_ = createRequire(import.meta.url)
 
@@ -54,7 +62,7 @@ let agent: AgentModule
 
 beforeEach(() => {
 	workDir = mkdtempSync(join(tmpdir(), 'fc-cp-mtls-'))
-	sockPath = join(workDir, 'agent.sock')
+	sockPath = localIpcPath(workDir)
 	process.env.NAMZU_SANDBOX_WORKSPACE = workDir
 	delete require_.cache[require_.resolve('../../../../agent/agent.cjs')]
 	agent = require_('../../../../agent/agent.cjs') as AgentModule
@@ -143,7 +151,7 @@ function startMtlsOrchestrator(handlePath: string): Promise<{
 	})
 }
 
-describe('buildFirecrackerBackend (control-plane mTLS dial)', () => {
+describe.skipIf(IS_WINDOWS)('buildFirecrackerBackend (control-plane mTLS dial)', () => {
 	it('create POST succeeds over mTLS and round-trips an exec', async () => {
 		agentServer = await startAgent()
 		const orch = await startMtlsOrchestrator(sockPath)

package/src/backends/firecracker/__tests__/egress-policy.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { SandboxBackendOptions } from '../../../index.js'
+import { resolveEgressAllowlist } from '../index.js'
+
+/**
+ * Omitting the allowlist means "no allowlist to apply", which the
+ * orchestrator reads as unrestricted. That makes omission the encoding for
+ * `allow-all` and only for `allow-all`.
+ *
+ * `resolver` used to be omitted too — so two opposite intentions shared one
+ * encoding, the tenant-scoped allowlist the variant exists for was silently
+ * absent, and the callback that would have produced it was never called
+ * anywhere in the repo. Whichever way the orchestrator reads an omitted
+ * field, one of the two variants was always mis-enforced, and the one that
+ * failed OPEN was the one whose entire purpose is restriction.
+ */
+
+const opts = (egress?: SandboxBackendOptions['egress']): SandboxBackendOptions => ({
+	workingDirectory: '/w',
+	...(egress ? { egress } : {}),
+})
+
+describe('each policy gets its own encoding', () => {
+	it('allow-all omits the field', async () => {
+		expect(await resolveEgressAllowlist(opts({ kind: 'allow-all' }))).toBeUndefined()
+	})
+
+	it('deny-all sends an explicitly empty list, not an absent one', async () => {
+		expect(await resolveEgressAllowlist(opts({ kind: 'deny-all' }))).toEqual([])
+	})
+
+	it('static forwards the hosts as given', async () => {
+		expect(
+			await resolveEgressAllowlist(opts({ kind: 'static', allowedHosts: ['a.example'] })),
+		).toEqual(['a.example'])
+	})
+
+	it('resolver calls the callback and forwards what it returned', async () => {
+		const resolve = vi.fn(async () => ['tenant-a.example', 'tenant-b.example'])
+		expect(await resolveEgressAllowlist(opts({ kind: 'resolver', resolve }))).toEqual([
+			'tenant-a.example',
+			'tenant-b.example',
+		])
+		// The callback IS the feature. It was declared and never invoked.
+		expect(resolve).toHaveBeenCalledOnce()
+	})
+
+	it('never encodes resolver the same way as allow-all', async () => {
+		const restrictive = await resolveEgressAllowlist(
+			opts({ kind: 'resolver', resolve: async () => ['only-this.example'] }),
+		)
+		const unrestricted = await resolveEgressAllowlist(opts({ kind: 'allow-all' }))
+		expect(restrictive).not.toEqual(unrestricted)
+	})
+
+	it('sends an empty resolver result as a real deny-all', async () => {
+		// An empty allowlist is a decision, not an absence. Collapsing it
+		// back to omission would turn "this tenant may reach nothing" into
+		// "this tenant may reach everything".
+		expect(
+			await resolveEgressAllowlist(opts({ kind: 'resolver', resolve: async () => [] })),
+		).toEqual([])
+	})
+
+	it('omits the field when the host set no policy at all', async () => {
+		expect(await resolveEgressAllowlist(opts())).toBeUndefined()
+	})
+})
+
+describe('an unknown policy', () => {
+	it('refuses rather than defaulting to unrestricted', async () => {
+		await expect(resolveEgressAllowlist(opts({ kind: 'something-new' } as never))).rejects.toThrow(
+			/Refusing rather than defaulting to unrestricted/,
+		)
+	})
+
+	it('propagates a failing resolver instead of falling back to open', async () => {
+		// A resolver that cannot answer must not become "allow everything".
+		await expect(
+			resolveEgressAllowlist(
+				opts({
+					kind: 'resolver',
+					resolve: async () => {
+						throw new Error('directory unreachable')
+					},
+				}),
+			),
+		).rejects.toThrow('directory unreachable')
+	})
+})