@namzu/sandbox 16.0.0 → 17.0.0

package/src/backends/http-worker-client.ts

@@ -21,6 +21,68 @@ type WorkerEvent =
 	  }
 	| { readonly type: 'error'; readonly error: string }
 
+/**
+ * What every call to a worker's control API carries, if the worker has a
+ * credential at all.
+ *
+ * The worker (`packages/sandbox/worker/server.js`) requires
+ * `Authorization: Bearer <token>` on every route but `/healthz`, where the
+ * token is the per-instance `NAMZU_SANDBOX_TOKEN` it was started with. An
+ * absent token here sends no header, which is exactly right for a worker
+ * that has none: a loopback-bound dev worker, or a warm-pool worker whose
+ * profile authenticates nothing.
+ *
+ * A worker the host did NOT create is the case this cannot solve by
+ * itself. The token is minted by whoever starts the container and travels
+ * in its environment, so a warm pool has to be provisioned with the same
+ * token before a host can claim it — there is no channel back. Constructing
+ * this client with no token against such a worker fails at the first call
+ * with a `401`, not silently.
+ */
+export function workerAuthorization(token: string | undefined): Record<string, string> {
+	return token ? { authorization: `Bearer ${token}` } : {}
+}
+
+/**
+ * The `401` a worker answers with, and what to do about it.
+ *
+ * Hung on every path that can be a caller's FIRST request to a worker —
+ * `reserve`, `execute`, and the container backend's direct `read-file` /
+ * `write-file` — because the bare status is the one failure whose cause is
+ * never visible from the sandbox the caller thinks it is talking to: the
+ * container is up, the port is open, and every command fails.
+ */
+export const WORKER_UNAUTHORIZED_HINT =
+	'The worker requires the per-instance token it was started with, as `Authorization: Bearer <token>`. If this host created the worker, the token it minted and the token the client sends have diverged. If it did not — a warm pool, a shared profile, a container someone else started — that worker must be provisioned with the token by whoever builds it: the worker has no channel back to hand one over.'
+
+/**
+ * The same failure, for the one backend that can never fix it.
+ *
+ * The standby pool has no way to present a token. The claim API admits
+ * exactly one property override, and it is not `env`: it is a config map,
+ * and a config map reaches the container as a FILE MOUNT under
+ * `/mnt/configmap/<containername>/<key>`, not as an environment variable.
+ * This worker reads its credential from `process.env` once at startup, so
+ * a value delivered that way is not read at all — and Microsoft's own
+ * guidance is that config map values are not validated by the runtime and
+ * that a value affecting application security belongs in an environment
+ * variable instead. The channel exists; this credential is declined for
+ * it, at both ends. See `docs/sdk/container-sandbox-worker.md` for the
+ * answer, the reason, and the change that would close the gap.
+ *
+ * A token on the shared profile would make the worker boot and then refuse
+ * every call the backend makes — an unrecoverable loop that looks like a
+ * broken worker. So what works there is the address first and the
+ * worker-side escape second, and the hint says which of the two situations
+ * the caller is in.
+ *
+ * `HttpWorkerClient` uses {@link WORKER_UNAUTHORIZED_HINT} rather than this
+ * one: the client is shared by two backends, and a 401 it sees could be
+ * either situation.
+ */
+export const STANDBY_POOL_UNAUTHORIZED_HINT =
+	'The worker requires a per-instance token, and this backend cannot present one: the claim API admits a config map and nothing else, and a config map arrives as a file mount under /mnt/configmap, not as an environment variable this worker reads. Putting a token on the shared container group profile does NOT fix this — the worker boots, the backend sends no header, and every call 401s. What works today is the address and then the worker-side escape: claim the group with `subnetId` so it sits on a private network, and set `NAMZU_SANDBOX_ALLOW_UNAUTHENTICATED=1` on that group profile, which is the only configuration in which a pooled worker starts and this backend can talk to it. Any other workload should run on a backend that can carry a credential. See `docs/sdk/container-sandbox-worker.md`.'
+
 function parseWorkerEvent(line: string): WorkerEvent {
 	let parsed: unknown
 	try {
@@ -57,6 +119,7 @@ function parseWorkerEvent(line: string): WorkerEvent {
 
 async function readExecution(
 	baseUrl: string,
+	token: string | undefined,
 	executionId: string | undefined,
 	command: string,
 	argv: string[] | undefined,
@@ -67,7 +130,7 @@ async function readExecution(
 	try {
 		response = await fetch(`${baseUrl}/execute`, {
 			method: 'POST',
-			headers: { 'content-type': 'application/json' },
+			headers: { 'content-type': 'application/json', ...workerAuthorization(token) },
 			signal: transportSignal,
 			body: JSON.stringify({
 				...(executionId ? { executionId } : {}),
@@ -94,6 +157,12 @@ async function readExecution(
 			'The worker was reachable when the sandbox started, so it has most likely exited, been killed, or become unreachable since. Check the container logs and runtime exit state.',
 		)
 	}
+	if (response.status === 401) {
+		throw withHint(
+			new Error(`execute failed: HTTP 401 ${await response.text()}`),
+			WORKER_UNAUTHORIZED_HINT,
+		)
+	}
 	if (!response.ok || !response.body) {
 		throw new Error(`execute failed: HTTP ${response.status} ${await response.text()}`)
 	}
@@ -163,16 +232,24 @@ async function readExecution(
 /**
  * A per-sandbox HTTP worker client. Every command must reserve an identity
  * through the exact worker protocol before it can be admitted.
+ *
+ * `token` is the per-instance credential the worker was started with, and
+ * it rides on every request this client makes. It is optional because a
+ * worker that was never given one — a loopback dev worker — requires none;
+ * say what happens when it is missing from the wrong side rather than
+ * sending nothing quietly: the worker answers `401` and the failure names
+ * the reason.
  */
 export class HttpWorkerClient {
 	private readonly controller: RemoteExecutionController
 
-	constructor(baseUrl: string) {
+	constructor(baseUrl: string, token?: string) {
 		const adapter: RemoteExecutionAdapter = {
 			label: 'HTTP worker',
 			reserve: async (signal) => {
 				const response = await fetch(`${baseUrl}/executions/reserve`, {
 					method: 'POST',
+					headers: workerAuthorization(token),
 					signal,
 				})
 				if (response.status === 404) {
@@ -180,6 +257,12 @@ export class HttpWorkerClient {
 						'The sandbox worker does not implement the required execution protocol. Rebuild the worker image or standby-pool profile from the same Namzu release before admitting commands.',
 					)
 				}
+				if (response.status === 401) {
+					throw withHint(
+						new Error(`execution reservation failed: HTTP 401 ${await response.text()}`),
+						WORKER_UNAUTHORIZED_HINT,
+					)
+				}
 				if (!response.ok) {
 					throw new Error(
 						`execution reservation failed: HTTP ${response.status} ${await response.text()}`,
@@ -190,7 +273,7 @@ export class HttpWorkerClient {
 			cancel: async (executionId, signal) => {
 				const response = await fetch(`${baseUrl}/cancel`, {
 					method: 'POST',
-					headers: { 'content-type': 'application/json' },
+					headers: { 'content-type': 'application/json', ...workerAuthorization(token) },
 					body: JSON.stringify({ executionId }),
 					signal,
 				})
@@ -200,7 +283,7 @@ export class HttpWorkerClient {
 				return await response.json()
 			},
 			execute: async (executionId, command, argv, opts, signal) =>
-				await readExecution(baseUrl, executionId, command, argv, opts, signal),
+				await readExecution(baseUrl, token, executionId, command, argv, opts, signal),
 		}
 		this.controller = new RemoteExecutionController(adapter)
 	}
@@ -220,6 +303,7 @@ export async function execViaHttpWorker(
 	command: string,
 	argv: string[] | undefined,
 	opts: SandboxExecOptions | undefined,
+	token?: string,
 ): Promise<SandboxExecResult> {
-	return await new HttpWorkerClient(baseUrl).exec(command, argv, opts)
+	return await new HttpWorkerClient(baseUrl, token).exec(command, argv, opts)
 }

package/src/backends/kubernetes/transport.ts

@@ -530,6 +530,13 @@ export interface KubernetesTransportOptions
 	 * Fires once per completed `exec()` call (success or failure) with
 	 * the four phase durations above. The payload is exactly those four
 	 * numbers — never the token, never a command, argv, or output.
+	 *
+	 * THIS is the timing hook for this tier. The base options also carry
+	 * `VsockTransportOptions.onExecTiming`, which is inherited here and is
+	 * INERT: it belongs to the firecracker tier, whose `exec()` reports into
+	 * it, while this transport drives the shared wire through
+	 * `executeStreamed` and never calls that `exec()`. Setting it on a
+	 * Kubernetes transport starts nothing.
 	 */
 	readonly onTiming?: (timing: KubernetesTransportTiming) => void
 	/**

package/src/egress/proxy.ts

@@ -71,13 +71,46 @@ export interface EgressProxyOptions {
 	 * reach — which is the hole this screen exists to close.
 	 */
 	readonly allowInwardFor?: readonly string[]
+	/**
+	 * Address this proxy listens on. Default `127.0.0.1`.
+	 *
+	 * The default is loopback because a proxy holding real credentials and
+	 * bound to every interface is reachable by anything on the network, which
+	 * is the opposite of what it exists for. There is exactly one deployment
+	 * where that reasoning flips, and it is the whole reason this is
+	 * configurable: the docker tier runs the proxy as a container of its own
+	 * (`egress-proxy/server.mjs`), the sandbox is attached to an `--internal`
+	 * network with no route out, and this container is the only way its traffic
+	 * reaches the internet. There, `0.0.0.0` inside the proxy container is not
+	 * "every interface on the host" — the container IS the boundary — and what
+	 * else the sandbox can reach on that network is whatever other containers a
+	 * host attached to it, which `docs/sdk/sandbox-egress.md` states.
+	 */
+	readonly bindHost?: string
+	/**
+	 * Names that denote THIS proxy, for the loop guard in `listen`.
+	 *
+	 * `isSelf` refuses a request whose target is the proxy itself, because
+	 * forwarding it makes the proxy call itself until the process runs out of
+	 * sockets — a failure that arrives as a hang rather than as an error. On
+	 * loopback the target is one of `127.0.0.1`, `localhost`, `::1` and the
+	 * check is closed by construction. Bound to another address it is not:
+	 * anything that names this proxy by a name it answers to — its container
+	 * name or network alias, say — would walk straight into that loop. So
+	 * every such name is listed here by whoever knows it.
+	 */
+	readonly selfNames?: readonly string[]
 	/** Injected in tests. Defaults to the platform resolver. */
 	readonly resolveAddresses?: ScreeningLookupOptions['resolve']
 }
 
 export interface RunningEgressProxy {
 	readonly port: number
-	/** `http://127.0.0.1:<port>` — what a sandbox sets `HTTP_PROXY` to. */
+	/**
+	 * `http://<the address this proxy bound>:<port>` — what a sandbox sets
+	 * `HTTP_PROXY` to. Loopback by default; the address is whatever
+	 * {@link EgressProxyOptions.bindHost} said.
+	 */
 	readonly url: string
 	/** Swap the allowlist on a live proxy. See `setNetworkPolicy`. */
 	setAllowedHosts(resolve: () => Promise<readonly string[]>): void
@@ -86,6 +119,12 @@ export interface RunningEgressProxy {
 
 const DENIED_STATUS = 403
 
+/** The default bind address. See {@link EgressProxyOptions.bindHost}. */
+const LOOPBACK_BIND_HOST = '127.0.0.1'
+
+/** Names that mean "this proxy" on loopback, whatever it bound to. */
+const LOOPBACK_SELF_NAMES: readonly string[] = ['127.0.0.1', 'localhost', '::1']
+
 export class EgressProxy {
 	private resolveAllowed: () => Promise<readonly string[]>
 	private readonly credentials: readonly BrokeredCredential[]
@@ -101,6 +140,8 @@ export class EgressProxy {
 	 */
 	private readonly lookup: ReturnType<typeof createScreeningLookup>
 	private readonly inwardAllowed: readonly string[]
+	private readonly bindHost: string
+	private readonly selfNames: readonly string[]
 
 	constructor(options: EgressProxyOptions) {
 		this.resolveAllowed = options.allowedHosts
@@ -108,6 +149,8 @@ export class EgressProxy {
 		this.upgradeToHttps = options.upgradeToHttps ?? true
 		this.onDenied = options.onDenied
 		this.inwardAllowed = options.allowInwardFor ?? []
+		this.bindHost = options.bindHost ?? LOOPBACK_BIND_HOST
+		this.selfNames = options.selfNames ?? []
 		this.lookup = createScreeningLookup(
 			{
 				...(options.allowInwardFor ? { allowInwardFor: options.allowInwardFor } : {}),
@@ -131,10 +174,12 @@ export class EgressProxy {
 		})
 		await new Promise<void>((resolve, reject) => {
 			server.once('error', reject)
-			// Loopback only. A proxy that holds real credentials and binds
-			// every interface is reachable by anything on the network, which
-			// is the opposite of what it exists for.
-			server.listen(port, '127.0.0.1', () => {
+			// Loopback by default. A proxy that holds real credentials and binds
+			// every interface is reachable by anything on the network, which is
+			// the opposite of what it exists for — see
+			// {@link EgressProxyOptions.bindHost} for the one deployment where
+			// the container itself is the boundary and this is not that.
+			server.listen(port, this.bindHost, () => {
 				server.off('error', reject)
 				resolve()
 			})
@@ -153,7 +198,7 @@ export class EgressProxy {
 
 		return {
 			port: boundPort,
-			url: `http://127.0.0.1:${boundPort}`,
+			url: `http://${this.bindHost}:${boundPort}`,
 			setAllowedHosts: (resolve) => {
 				this.resolveAllowed = resolve
 			},
@@ -363,10 +408,22 @@ export class EgressProxy {
 		})
 	}
 
-	/** Whether a target names this proxy. See the loop guard in `listen`. */
+	/**
+	 * Whether a target names this proxy. See the loop guard in `listen`.
+	 *
+	 * The loopback spellings are always this proxy — a client inside the same
+	 * network namespace reaches it at one of them whatever it bound to, and
+	 * the bound address when that address is a literal is one more. Anything
+	 * else has to be named by the caller, through
+	 * {@link EgressProxyOptions.selfNames}: this process cannot know which
+	 * names resolve to it on the network it is attached to, and a guard that
+	 * guessed would either miss the loop or refuse a legitimate target.
+	 */
 	private isSelf(host: string, port?: number): boolean {
 		if (port === undefined || port !== this.selfPort) return false
-		return host === '127.0.0.1' || host === 'localhost' || host === '::1'
+		if (host === this.bindHost) return true
+		if (LOOPBACK_SELF_NAMES.includes(host)) return true
+		return this.selfNames.includes(host)
 	}
 
 	private credentialFor(host: string): BrokeredCredential | undefined {

package/src/index.ts

@@ -62,6 +62,7 @@ import type {
 import { buildAciStandbyPoolBackend } from './backends/aci-standby-pool/index.js'
 import { buildDockerBackend, resolveLayout } from './backends/docker/index.js'
 import { buildFirecrackerBackend } from './backends/firecracker/index.js'
+import type { FirecrackerTransportTiming } from './backends/firecracker/transport.js'
 import type { KubernetesEgressConfig } from './backends/kubernetes/egress-policy.js'
 import {
 	type KubernetesAgentAddressMode,
@@ -126,6 +127,7 @@ export {
 	AgentWriteFileTooLargeError,
 	DEFAULT_MAX_WRITE_FILE_BYTES,
 	FIRECRACKER_AGENT_PROTOCOL_VERSION,
+	type FirecrackerTransportTiming,
 	GUEST_FRAME_LIMIT_BYTES,
 	type SandboxAgentHandle,
 	TCP_PREAUTH_FRAME_LIMIT_BYTES,
@@ -659,8 +661,51 @@ export interface ContainerBackendConfig {
 	 *
 	 * Egress from the sandbox is governed separately by `EgressPolicy`,
 	 * which is checked against this network rather than trusted.
+	 *
+	 * An egress policy of `static` or `resolver` — a host allowlist —
+	 * additionally REQUIRES this network to be `--internal`, and requires
+	 * `hostReachability: 'container-network'`. The allowlist is enforced by
+	 * the egress proxy running as a sibling container on this network: the
+	 * sandbox is attached to this network alone, and an internal network has
+	 * no route off it, so the only way the sandbox's traffic reaches the
+	 * internet is through that container. It is a container on a subnet like
+	 * any other there, so what else a host attaches to this network — a second
+	 * sandbox, and that sandbox's proxy — is reachable from this one too; on a
+	 * network with a route out the allowlist is a proxy environment variable a
+	 * workload may decline to read, and `create()` refuses rather than
+	 * reporting a boundary that is not there.
 	 */
 	readonly network?: 'none' | 'bridge' | string
+	/**
+	 * Image the egress proxy runs as, when the policy needs one.
+	 *
+	 * Required for a `static` or `resolver` policy, refused without it. The
+	 * image is `packages/sandbox/egress-proxy/Dockerfile`:
+	 *
+	 *   pnpm --filter @namzu/sandbox build
+	 *   docker build -f packages/sandbox/egress-proxy/Dockerfile \
+	 *     -t <tag> packages/sandbox
+	 *
+	 * It is a second image rather than the sandbox's own because the
+	 * sandbox image is a string this backend cannot read: there is no way to
+	 * know whether it contains the proxy module, and the bind-mount
+	 * alternative fails on exactly the remote-daemon deployment
+	 * `hostReachability: 'container-network'` exists for. `deny-all` and
+	 * `allow-all` need no image.
+	 */
+	readonly egressProxyImage?: string
+	/**
+	 * Network the egress proxy joins for its route to the internet. Default
+	 * `'bridge'`, docker's own default bridge.
+	 *
+	 * The proxy is dual-homed: it sits on the internal network the sandbox
+	 * is on, and on this one, which is how it reaches the world. Name a
+	 * dedicated network when the daemon is shared, because anything else
+	 * attached to this one can reach the proxy — and this proxy enforces its
+	 * allowlist for whoever asks and stamps brokered credentials on what it
+	 * forwards.
+	 */
+	readonly egressProxyUpstreamNetwork?: string
 	/**
 	 * Maximum time spent waiting for the container worker's `/healthz`
 	 * readiness probe. Must be a positive integer within Node's timer range.
@@ -796,6 +841,28 @@ export type MicroVMBackendConfig = {
 	readonly readyTimeoutMs?: number
 	/** Delay between guest-agent health probes. Default 250ms. */
 	readonly readyPollIntervalMs?: number
+	/**
+	 * Fires once per completed `exec()` on this provider's sandboxes with
+	 * that call's wall-time breakdown — the reserve round trip, the execute
+	 * round trip, the dials inside them, the first reply frame, the
+	 * terminator frame and the peer's own close. See
+	 * {@link FirecrackerTransportTiming} for what each number is and is not,
+	 * and {@link VsockTransportOptions.onExecTiming} for why the field is
+	 * named this rather than the kubernetes tier's `onTiming`.
+	 *
+	 * Opt-in and additive, with no default: a host that sets nothing sends,
+	 * receives and waits for exactly what it did before. The intended use is
+	 * attribution — a relay or a guest that adds a fixed cost to every call
+	 * moves a named phase, and one that adds none leaves the numbers at the
+	 * cost of a command's own runtime.
+	 *
+	 * It is an OBSERVER, not a control: it cannot change a command's result,
+	 * it is called after the call has settled, and a listener that throws is
+	 * that listener's problem. The payload is durations only — never the
+	 * agent token, a command, its arguments, or any output — so a host may
+	 * log it without leaking what the sandbox ran.
+	 */
+	readonly onExecTiming?: (timing: FirecrackerTransportTiming) => void
 	/**
 	 * NETWORK-mode mTLS client material (ses_051 P4 client-proxy
 	 * bridge). When present, the orchestrator returns an `mtls` agent
@@ -1317,6 +1384,12 @@ function pickBackend(config: SandboxProviderConfig): SandboxBackend {
 				: {}),
 			...(backend.network !== undefined ? { network: backend.network } : {}),
 			...(backend.allowInwardFor !== undefined ? { allowInwardFor: backend.allowInwardFor } : {}),
+			...(backend.egressProxyImage !== undefined
+				? { egressProxyImage: backend.egressProxyImage }
+				: {}),
+			...(backend.egressProxyUpstreamNetwork !== undefined
+				? { egressProxyUpstreamNetwork: backend.egressProxyUpstreamNetwork }
+				: {}),
 			...(backend.labels !== undefined ? { labels: backend.labels } : {}),
 			...(backend.cpuLimit !== undefined ? { cpuLimit: backend.cpuLimit } : {}),
 			...(backend.readOnlyRootfs !== undefined ? { readOnlyRootfs: backend.readOnlyRootfs } : {}),
@@ -1342,6 +1415,12 @@ function pickBackend(config: SandboxProviderConfig): SandboxBackend {
 				: {}),
 			...(backend.network !== undefined ? { network: backend.network } : {}),
 			...(backend.allowInwardFor !== undefined ? { allowInwardFor: backend.allowInwardFor } : {}),
+			...(backend.egressProxyImage !== undefined
+				? { egressProxyImage: backend.egressProxyImage }
+				: {}),
+			...(backend.egressProxyUpstreamNetwork !== undefined
+				? { egressProxyUpstreamNetwork: backend.egressProxyUpstreamNetwork }
+				: {}),
 			...(backend.labels !== undefined ? { labels: backend.labels } : {}),
 			...(backend.cpuLimit !== undefined ? { cpuLimit: backend.cpuLimit } : {}),
 			...(backend.readOnlyRootfs !== undefined ? { readOnlyRootfs: backend.readOnlyRootfs } : {}),
@@ -1372,6 +1451,16 @@ function pickBackend(config: SandboxProviderConfig): SandboxBackend {
 			...(backend.readyPollIntervalMs !== undefined
 				? { readyPollIntervalMs: backend.readyPollIntervalMs }
 				: {}),
+			// Forwarded into the transport's own options rather than onto the
+			// backend's config: the backend reads nothing here, and the phase
+			// numbers are the transport's to report — see
+			// `VsockTransportOptions.onExecTiming`, which is where a host that
+			// builds a `VsockAgentTransport` directly sets it too. Absent ⇒
+			// this spread adds no key at all and the transport is built with
+			// the options it was always built with.
+			...(backend.onExecTiming !== undefined
+				? { transport: { onExecTiming: backend.onExecTiming } }
+				: {}),
 			...(backend.mtls !== undefined ? { mtls: backend.mtls } : {}),
 			...(backend.controlPlaneMtls !== undefined
 				? { controlPlaneMtls: backend.controlPlaneMtls }