@namzu/sandbox 16.0.0 → 17.0.1

package/CHANGELOG.md

@@ -1,5 +1,336 @@
 # @namzu/sandbox
 
+## 17.0.1
+
+### Patch Changes
+
+- 27a1665: A kubernetes deployment with `egress.policy: { kind: 'no-network' }` can create
+  sandboxes again. It could not before: every `create()` was refused with
+  `KubernetesEgressPolicyMismatchError` — a host that maps that to a reason such
+  as `sandbox-egress-policy-unverified` fails the run closed — and no policy an
+  operator could apply would have cleared it.
+
+  The named-object check compared `spec.egress` to the translation with a
+  deep-equal, and a core `NetworkPolicy` never stores an empty rule list:
+  `egress` is `omitempty` on the wire struct, so an object applied with
+  `egress: []` reads back with no `egress` key at all, and a merge patch cannot
+  put one back.
+  `no-network`'s whole translation IS that empty list, so `undefined !== []` made
+  the check unsatisfiable by any object a cluster can store. `verifyEgressPolicyApplied`
+  now reads an absent `egress` as the empty list it is, in that one comparison.
+  They are one policy and not merely one shape, because the check has already
+  required `policyTypes` to include `'Egress'` on a core policy, and that alone
+  denies all egress.
+
+  Nothing else is loosened. A live object whose rule array is non-empty still
+  fails a translation that intended none, and a live object with no `egress` at
+  all still fails a translation that intended rules — an absent list means
+  deny-all, which is not what config asked for. The comparison still exists to
+  refuse an object enforcing anything other than what was intended.
+
+  `patch`, and the reason it is not a `major`: this is not a change to the public
+  surface. No export, field, option or default moved, and the accepted set grows
+  by exactly the object the API server stores for the intent the deployment had
+  already declared. The refusal that disappears is one no consumer could have
+  been relying on — `no-network` is configured in order to create sandboxes, and
+  the only thing the refusal ever did was prevent that — so no upgrade action is
+  required and no deployment that passes today starts failing.
+
+  There was also no setting that avoided the refusal, so nothing to unset:
+  `egress.verify: 'named-object-only'` opts out of the UNION check and nothing
+  else — `egressUnionVerificationEnabled` gates `verifyUnion`, while the
+  named-object check runs on every create path regardless — so a `no-network`
+  host was refused under either setting. The ways out were to configure no
+  `egress` at all, or to fall back to `deny-all`, which allows the cluster
+  resolver on port 53 and is therefore not the same boundary.
+
+  Verified against a live `kind` cluster (v1.37), not only against a fake API
+  server: the `no-network` manifest applied, the object read back with this
+  backend's own client (a core `NetworkPolicy` stored with no `egress` key, and
+  `kubectl patch --type=merge -p '{"spec":{"egress":[]}}'` does not restore one),
+  and the real `verifyEgressPolicyApplied` run on what came off the cluster —
+  refused before this change, verified after, with a live object carrying a rule
+  and a live object carrying none both still refused.
+
+- 9092a37: Nothing a consumer installs changes. The one edited file is
+  `k8s/__tests__/entrypoint.test.ts`, which `package.json#files` excludes from the
+  tarball; the harness only, and `entrypoint.sh` itself is deliberately untouched —
+  runtime behaviour, exports, types and defaults are the same.
+
+  `entrypoint.test.ts` has been intermittently red on `main`, twice in a release
+  run:
+
+  ```
+  FAIL entrypoint.test.ts > entrypoint.sh prestop: the flush a stopping pod gets
+     > returns rather than hanging when the init does not go
+  AssertionError: expected 6 to be greater than or equal to 900
+  ```
+
+  The mechanism is a race in the harness, not in the image. `entrypoint.sh` reads
+  `/proc/<pid>/comm` before it signals anything and exits 0 immediately when the
+  name is not the init it expects — a fail-closed refusal the image must keep, and
+  the reason `entrypoint.sh` is not what changed here. `spawnStandIn` echoed `$!`
+  for a child that had not `exec`'d yet, so inside that window the hook read `sh`
+  where the symlinked `tini` was intended, refused, and skipped its whole wait. The
+  case then measured the refusal — a few milliseconds of elapsed time and a handful
+  of ticks — instead of the flush it is about, and failed against a constant that
+  looks nothing like the number it got.
+
+  The fix is a bounded, loud-failing readiness poll, `awaitStandInExec`, routed
+  through `spawnStandIn` so every stand-in call site gets it: cases now wait for
+  the process to become the binary it was started as before they hand its pid to
+  the hook. It waits for the SPECIFIC name rather than for `sh` to disappear,
+  because the name is what the hook turns on and one call site deliberately wants a
+  plain `sleep` to stay a `sleep`. A stand-in that died during the wait says so
+  instead of waiting its bound out.
+
+  It also refuses up front an expected name longer than the kernel can report: the
+  kernel keeps at most 15 characters in `/proc/<pid>/comm`, so a longer name could
+  never match and the wait would fail on its deadline rather than on the truth.
+  Latent today — every stand-in this suite starts is named well inside the limit —
+  and the guard exists so a future one is a one-line failure that names the limit.
+
+  Verified: the race reproduced deterministically before the fix, 20/20 runs green
+  under load after it, and removing the wait restores the failure byte-identically.
+
+## 17.0.0
+
+### Major Changes
+
+- 1722448: **A `container:docker` sandbox with an egress allowlist now needs an internal
+  network, a proxy image, and `container-network` reachability. Take this version
+  if you use one; otherwise nothing you install changes shape.**
+
+  The allowlist tier used to be enforced by `HTTP_PROXY` and nothing else. The
+  proxy ran in the process that created the sandbox, on the host's loopback, and
+  the sandbox kept ordinary bridge networking with full outbound reachability —
+  `--add-host namzu-egress:host-gateway` was the only thing pointing traffic at
+  it. Anything inside the container that opened a socket directly reached the
+  network with the allowlist unconsulted. It is now a sibling container on an
+  `--internal` network the sandbox is also on, which has no route off it: the
+  sandbox's traffic reaches the internet only through that container, and
+  everything else a host attaches to that network is a container on the sandbox's
+  own subnet.
+
+  **What a host using `EgressPolicy` of `static` or `resolver` must now do**, all
+  three refused at `create()` rather than downgraded:
+
+  1. `network` must be an `--internal` network: `docker network create
+--internal <name>`. The network's `Internal` flag is read back from the
+     daemon; the name is never trusted.
+  2. `hostReachability` must be `'container-network'`. A published host port
+     needs a route out and an internal network has none — the refusal names the
+     mode to move to. **A host-side consumer (the CLI, direct dev) that reached
+     the worker on `127.0.0.1:<port>` under an allowlist policy must move to a
+     consumer on the internal network.**
+  3. `egressProxyImage` must name the proxy image:
+
+     ```bash
+     pnpm --filter @namzu/sandbox build
+     docker build -f packages/sandbox/egress-proxy/Dockerfile -t <tag> packages/sandbox
+     ```
+
+     It is a second image because the sandbox image is a string this backend
+     cannot read, and the bind-mount alternative breaks on the remote-daemon
+     deployment `container-network` exists for.
+
+  `HTTP_PROXY` and friends are still set and now direct traffic rather than
+  permit it: a tool that honours them goes through the boundary, one that ignores
+  them fails `Network unreachable` instead of bypassing the policy.
+
+  **Four behaviour changes to know about, all of them consequences of the
+  boundary existing:**
+
+  - A `resolver` policy is resolved at `create()` and at each
+    `setNetworkPolicy()`, not per request. A resolver that rotates between those
+    moments is not picked up until the next one.
+  - `setNetworkPolicy()` replaces the proxy container rather than swapping the
+    allowlist in place. The window between the two has no proxy in it and fails
+    **closed** — no request is permitted that the new policy would refuse.
+  - `brokeredCredentials` are passed to the proxy container's environment. They
+    still never enter the sandbox; they are now readable by anything with access
+    to the docker daemon, which should be treated as credential access. (On the
+    way there the value goes through the `docker` CLI child's ENVIRONMENT, not its
+    argv — an argv is world-readable in `/proc/<pid>/cmdline` on Linux.) Note also
+    that `createSandboxProvider` has never forwarded `brokeredCredentials` at all;
+    that pre-existing gap is unchanged.
+  - `egressProxyUpstreamNetwork` (default `bridge`) is where the proxy reaches
+    the internet. Anything else attached to that network can reach the proxy and
+    use it, so name a dedicated one on a shared daemon. `'none'`, and the internal
+    network itself, are refused: either leaves the proxy with no route out.
+  - Everything else on the SANDBOX's internal network is reachable from the
+    sandbox — a second sandbox, a second sandbox's proxy. That is a property of
+    the network rather than of this tier; give each sandbox its own internal
+    network when they should not see one another.
+
+  `deny-all` and `allow-all` are unaffected beyond the internal network
+  `deny-all` already required. `EgressProxy` gains two optional options
+  (`bindHost`, `selfNames`) and the container entrypoint sets them; the class is
+  otherwise unchanged.
+
+- f1fd331: The container backend's worker now authenticates its caller, and a worker that
+  cannot refuses to start on a routable bind. This is a `major` because the wire
+  shape of a public surface changed: every route but `GET /healthz` now requires
+  `Authorization: Bearer <NAMZU_SANDBOX_TOKEN>`, a missing or wrong token is
+  `401 {"error":"unauthorized"}`, and a worker with no token will not listen on
+  anything but loopback. A token that is set but cannot be answered — empty,
+  padded, or carrying a character an HTTP header cannot hold — now refuses to
+  start rather than leaving a worker that looks authenticated and refuses its own
+  host.
+
+  Nothing in the package's TypeScript API changed — no export was removed,
+  renamed or narrowed, and `HttpWorkerClient` and `execViaHttpWorker` only gained
+  an optional token parameter. What changed is the contract between this backend
+  and the worker process it runs, and that contract is deployed separately: the
+  worker lives in `packages/sandbox/worker/server.js`, which the tarball does not
+  ship, so the image is built from whatever checkout the operator has.
+
+  **What breaks, and for whom.**
+
+  - **A worker image rebuilt from this release, paired with a host that predates
+    it.** The old host injects no token, so the new worker refuses to start on
+    the default `0.0.0.0` bind and every `create()` fails at readiness with the
+    container already exited. The refusal names the variable. Bring the host up
+    in the same step, or set the escape below.
+  - **Anything that talks to the worker without going through this backend.** The
+    route contract is now authenticated; a probe, a health-check script that
+    calls `/execute`, or a hand-rolled client must present the token.
+  - **The standby-pool backend.** A pooled worker built from this release will
+    refuse to boot on its routable default bind, because this backend has no way
+    to hand it a credential. The claim API admits exactly one property override,
+    and it is not `env` — it is a config map, which on Linux reaches the container
+    as a file mount under `/mnt/configmap/<containername>/<key>`, not as an
+    environment variable, while the worker reads its token from `process.env` at
+    startup. The platform does not validate config-map values either, and its own
+    guidance is that a value affecting application security belongs in an
+    environment variable. So the per-instance credential for this backend is NOT
+    implemented here, and the change that would close the gap — a per-claim value
+    in the config map, read by the worker — is written down in
+    `docs/sdk/container-sandbox-worker.md` rather than half-built. A token on the
+    shared profile does not fix it either: the worker would boot and then `401`
+    every call the backend makes, because this backend's client is constructed
+    without a token and it has no field to carry one.
+
+  **A host and a worker from the same release need no configuration.** The
+  container backend mints 32 random bytes per `create()`, hands the value to the
+  docker CLI in its own environment (resolved by a valueless
+  `--env NAMZU_SANDBOX_TOKEN`, so it is in no argv), and sends it as a bearer
+  header on every call it makes. Upgrading both together is the whole migration.
+  The token is per instance, never written to disk, and dies with the container.
+  It is readable where a peer in the same container or a caller who can already
+  talk to the docker daemon could read it — `docker inspect` shows it on the
+  container config for the container's life — which is why it is per-instance
+  rather than shared, and why it is a defence in depth behind network placement
+  rather than a replacement for it.
+
+  **The standby pool: place it first, decide about the credential second.** If you
+  run that backend, the control that actually carries the exposure is the network,
+  and it is the one to get right before anything else — `aci-standby-pool` already
+  refuses to claim a container group without `subnetId` (unless you set
+  `allowPublicAddress: true` and mean it), so the group sits on a private address
+  and that network is what stands in front of the worker. The refusal is unchanged
+  by this release; what has changed is that it is now the first half of the answer
+  rather than the whole of it. The second half is the escape below, which is what
+  makes a pooled worker start at all today: put
+  `NAMZU_SANDBOX_ALLOW_UNAUTHENTICATED=1` on the container group profile, with the
+  group on a private address. It is needed there only because this backend cannot
+  present a credential, and it turns a worker that cannot boot into one that
+  serves inside that address. Read the standby-pool bullet under "What breaks"
+  before taking that step, and note that a token on the shared profile is not an
+  alternative to it.
+
+  **For a deployment the container backend creates**, the escape is a migration
+  tool rather than a destination: it is what keeps you running while the host and
+  the worker image are brought up in the same step.
+
+  **To keep the old behaviour on purpose**, set
+  `NAMZU_SANDBOX_ALLOW_UNAUTHENTICATED=1` in the worker's environment — the
+  container backend's `options.env` for a sandbox it creates, or the standby
+  pool's container group profile for a pooled one. That gives the credential up
+  rather than deferring it: with it set and no token, every route but `/healthz`
+  is open to whoever can route to the container, which is exactly what the
+  default used to be. On the pool, the address comes first and this second; on
+  every other backend, both the host and the image should be upgraded in one step
+  instead. Only `1`, `true`, `yes` and `on` count, in any case and with no
+  surrounding whitespace; everything else — `= 0`, `= false`, `= " yes "` — means
+  off, so the flag cannot turn itself on.
+
+  Also unchanged, and worth repeating from the README: the transport is plain
+  HTTP, so this is a bearer token over the wire and it is defence in depth behind
+  network placement, not a replacement for it. See
+  `docs/sdk/container-sandbox-worker.md`.
+
+### Minor Changes
+
+- 01fbc9b: Three additive declarations, no default changed and nothing removed:
+
+  - `MicroVMBackendConfig.onExecTiming` — the owned Firecracker tier's provider
+    config gains an optional per-exec timing hook.
+  - `FirecrackerTransportTiming` — exported from the package entry point, the
+    shape that hook is called with.
+  - `VsockTransportOptions.onExecTiming` — the same hook at the transport level,
+    for a host that builds a `VsockAgentTransport` itself.
+
+  A host that sets none of them sends, receives and waits for exactly what it did
+  before: the timing accumulator is created only when the hook is set, and the
+  `undefined` checks that skip creating it skip every clock read that would have
+  filled it.
+
+  The hook reports one `exec()`'s wall clock as named phases — `dialMs`,
+  `reserveMs`, `executeMs` and `drainMs`, the four the Kubernetes tier's
+  `onTiming` already reports, plus `firstFrameMs`, `terminatorMs` and
+  `peerCloseMs` for the intervals inside the execute round trip. The three
+  sub-phases are absent, rather than zero, when their phase was never reached; the
+  four base phases are always present and use `0` for "this never happened" (a
+  call that failed at the dial reports `executeMs: 0`). The payload is durations
+  only: never the agent token, a command, its arguments, or any output.
+
+  One behaviour change worth naming, because it is the reason the hook is useful:
+  the transport's execution adapter and its `RemoteExecutionController` are now
+  built per call instead of once per transport. That controller holds no per-call
+  state, so nothing observable changes — but an adapter built once had nowhere
+  per-call to accumulate into, and a single accumulator on the transport would
+  have two concurrent `exec()` calls writing each other's phases. The Kubernetes
+  tier's own transport has been arranged this way since it was written.
+
+  `POST_RESPONSE_CLOSE_TIMEOUT_MS` (1 s) is unchanged and its behaviour is
+  unchanged; it is now documented as what it always was — a reject-only guard
+  that fails a socket whose peer never closes, never a wait a successful call
+  pays. If your host puts a relay between this process and the guest, `peerCloseMs`
+  is the number that tells you whether that relay holds the FIN: a hold **under**
+  a second is reported there on a call that resolved, and a hold **at or past**
+  a second fails the call with `vsock transport: exec peer did not close after
+terminator`, reporting no `peerCloseMs` at all — the close in that case is the
+  one this transport causes itself when the guard fires, and its own constant is
+  not published as an elapsed time. So a resolved exec's fixed cost cannot be
+  hiding in that window: whichever way the window goes, it is either reported or
+  it is a rejection, and never a silent second.
+
+### Patch Changes
+
+- 656598a: Nothing a consumer installs changes. The one edited file is
+  `src/backends/docker/__tests__/leaf-permissions.smoke.test.ts`, which
+  `package.json#files` excludes from the tarball; runtime behaviour, exports, types
+  and defaults are untouched.
+
+  The `Sandbox smoke` workflow has been red on `main` since the docker hardening
+  landed (`481fb8ff`, `--read-only` on by default). That case asserts that uid 1001
+  cannot `mkdir` into the unbound `/mnt/user-data`, and it pinned the refusal to
+  one spelling — `permission denied`. With a read-only rootfs the kernel answers
+  `read-only file system` instead, because EROFS is consulted before the DAC check
+  that would have produced EACCES. The property the case exists for never changed
+  (a bound writable leaf would let the `mkdir` succeed, and the `--rc` assertion
+  still catches that); only the kernel's wording did.
+
+  The assertion now accepts either refusal and says why both are legitimate, so the
+  next change to which check fires first is a one-line read rather than a day of
+  red. `dash` and Docker are both absent from the machine this was written on, so
+  the fix is verified by the workflow that runs this file, not locally.
+
+- Updated dependencies [4e8cf5c]
+- Updated dependencies [19abb2c]
+  - @namzu/sdk@42.0.0
+
 ## 16.0.0
 
 ### Major Changes

package/README.md

@@ -122,6 +122,59 @@ tier gets uid 0 mapped to an unprivileged uid outside.
 overrides the image's own choice and the reference image already ends with
 `USER namzu`.
 
+## Container egress boundary
+
+An egress policy of `static` or `resolver` — a host allowlist — is enforced by
+the egress proxy running as a **sibling container**, not by the process that
+created the sandbox. The proxy is dual-homed: `docker run` puts it on an
+ordinary network so it has a route to the internet, and `docker network
+connect --alias namzu-egress` adds the `--internal` network the sandbox is on.
+The sandbox joins that internal network alone and has no route off it — a route
+it cannot put back, because `--cap-drop=ALL` removed `NET_ADMIN`.
+`--add-host namzu-egress:host-gateway` and the loopback proxy that needed it are
+gone.
+
+"No route off it" is the accurate half of that, and it is worth being exact
+about the other: the internal network is a subnet, so the sandbox can also
+reach whatever else a host attaches there — a second sandbox, a second
+sandbox's proxy. Give each sandbox its own internal network when they should
+not see one another; see
+[docs/sdk/sandbox-egress.md](../../docs/sdk/sandbox-egress.md).
+
+`HTTP_PROXY`, `http_proxy`, `HTTPS_PROXY`, `https_proxy` and `NO_PROXY` are
+still set on the sandbox, and what they are has changed. They no longer permit
+traffic, they direct it: a tool that honours them sends its request through the
+boundary, and a tool that ignores them — a binary that does not read proxy
+environment, `curl --noproxy '*'`, a raw socket — has nowhere to send anything
+and fails with `Network unreachable`. Before this, that second tool reached the
+network with the allowlist unconsulted.
+
+Three things a host must supply, each refused at `create()` rather than
+downgraded: an `--internal` network in `network` (`docker network create
+--internal <name>`), `hostReachability: 'container-network'` (a published host
+port needs a route out that this network does not have), and
+`egressProxyImage` — the proxy image, built from
+`packages/sandbox/egress-proxy/Dockerfile` exactly as the sandbox image is
+built from `packages/sandbox/worker/Dockerfile`. Nothing in this repository
+pushes an image; both are built by hand and named by tag in the config.
+
+The proxy container carries the same baseline the sandbox does
+(`--cap-drop=ALL`, `--security-opt=no-new-privileges`, `--ipc private`,
+`--read-only`), because it is the process standing between untrusted code and
+the internet. `deny-all` and `allow-all` need none of this beyond the internal
+network `deny-all` already required.
+
+What the boundary does not cover — domain fronting inside a `CONNECT` tunnel, a
+`resolver` policy resolved at `create()` and `setNetworkPolicy()` rather than
+per request, `setNetworkPolicy()` replacing the proxy container rather than
+swapping a list in place, brokered credentials now readable by anything with
+daemon access, the proxy's listener being reachable by whatever else shares its
+upstream network, and everything else the sandbox shares its own internal
+network with — is stated in
+[docs/sdk/sandbox-egress.md](../../docs/sdk/sandbox-egress.md), along with the
+argv-level evidence this change is verified by and the fact that no test here
+starts a container.
+
 ## Protocol readiness and cancellation
 
 Pass `SandboxExecOptions.signal` to stop a command on any shipped backend. A
@@ -581,6 +634,117 @@ sees the agent's own settings — `NAMZU_SANDBOX_WORKSPACE` among them. A
 workload that needs a value in its terminal passes it in `env` on the
 `openTerminal` call, which still wins over everything else, `TERM` included.
 
+## The container worker's control API, and its token
+
+The container backend runs `worker/server.js` — a different process from the
+guest agent above, with a different wire: plain HTTP on a port Docker forwards,
+not a framed stream over a socket. It serves `GET /healthz`,
+`POST /execute`, `POST /executions/reserve`, `POST /cancel`, `POST /read-file`
+and `POST /write-file`, and until recently it authenticated nothing: any peer
+that could route to the container could run a command or read and write a file
+inside it. What made that defensible was the network the container is attached
+to, which is a property of a deployment rather than of the worker, and is
+absent wherever a control plane can put the container on a public address.
+
+Every route but `GET /healthz` now requires
+`Authorization: Bearer <NAMZU_SANDBOX_TOKEN>`. A missing, empty or different
+token is answered `401` with `{"error":"unauthorized"}` and nothing else — no
+expected/got, no length, no hint about which routes exist — and the request
+never reaches a handler, so a refused `/write-file` writes nothing. The
+comparison is a fixed-width SHA-256 digest compare, so neither the value nor
+its length is learnable by probing, and the gate runs before every dispatch,
+including the 404, so an unauthenticated caller cannot tell a real route from a
+missing one, or a wrong token from a missing one. `/healthz` requires no token
+and never echoes one, because it is what the host polls before it has any other
+business with the worker, and it answers with liveness and the protocol version
+only. That exemption is an exact match on the whole URL, so `POST /healthz`,
+`GET /healthz?x=1` and `GET /healthz/` are gated like anything else. It also
+leaves exactly one bit readable without a credential, deliberately: the
+retiring-worker check answers before the `/healthz` dispatch, so a worker that
+has poisoned itself answers `503 {"error":"worker_retiring"}` where a healthy
+one answers `200`. That is the drain signal, and the readiness probe — which
+has no credential to present — is who reads it; on every route that does
+anything, a caller without the token gets the same `401` from a retiring worker
+and a serving one.
+
+**The token is minted per instance, by whoever starts the container.** The
+container backend generates 32 random bytes at `create()` time and hands the
+value to the docker CLI in ITS environment, resolved by the valueless
+`--env NAMZU_SANDBOX_TOKEN`. It shares a destination with three variables that
+already exist — the workspace path and the read/write roots land in the
+container's environment through the same `--env` mechanism — and nothing else:
+those three are rendered in the argv as `--env K=V`, values and all, while this
+one is valueless, which is docker's form for "take the value from the CLI's own
+environment". So it is in no argv, `ps` on the host does not show it, and a
+failed `docker run` renders its argv with every `--env` value redacted, in all
+four spellings of the flag, so the error a host logs does not carry it either.
+What it IS visible in, said plainly: the container's own config, so
+`docker inspect <name>` shows it for the container's life to anyone who can
+already talk to the daemon, and the worker's `/proc` inside the container to a
+workload sharing its uid. That is why it is per-instance and why it dies with
+the container — an image-level secret would be shared by every container ever
+built from it and readable by anything that can pull it, and a profile-level one
+would be shared by every instance claimed from a pool. The variable carries the
+`NAMZU_SANDBOX_` prefix, which is what keeps it out of every command the sandbox
+runs: the worker strips that prefix from the environment it hands to a spawned
+command, so a sandboxed task cannot read the credential out of its own
+environment.
+
+**A worker with no token refuses to start on a routable address.** The bind
+default is `0.0.0.0` and stays that way: a published container port forwards to
+the container's interface address rather than to its loopback, so narrowing the
+default disables the container backend instead of hardening it. The credential
+is what makes that default defensible, so its absence fails closed:
+
+| What the worker was given | What it does |
+|---|---|
+| `NAMZU_SANDBOX_TOKEN` set | Requires it on every route but `/healthz`, whatever the bind address |
+| No token, bound to loopback (`127.0.0.1`, `::1`, `localhost`) | Starts, unauthenticated. Nothing outside the container's own network namespace can open that socket, and refusing here would break the host-beside-docker dev case while closing nothing |
+| No token, bound anywhere else — including the `0.0.0.0` default | Refuses to start, exit 1, naming the variable and every way out |
+| `NAMZU_SANDBOX_TOKEN` set but **empty**, or with leading/trailing whitespace | Refuses to start in every mode. An empty value is the shape an injected secret takes when the injection resolved to nothing; a padded one is read from a trimmed header and so can never be presented, leaving a worker that looks authenticated and refuses its own host for the container's life |
+| `NAMZU_SANDBOX_TOKEN` set to something **no HTTP header can carry** — a code point above U+00FF, or a C0 control other than HTAB | Refuses to start in every mode. A header value is one byte per character, so the client's own `fetch` throws before the request leaves the host for the first, and the HTTP parser on this side drops the connection for the second. Same "boots authenticated, refuses its host" state, caught at boot instead of at the first call |
+| No token, routable, and `NAMZU_SANDBOX_ALLOW_UNAUTHENTICATED=1` | Starts, unauthenticated, on purpose |
+
+**The escape, and what it gives up.**
+`NAMZU_SANDBOX_ALLOW_UNAUTHENTICATED=1` is the explicit, named way to keep an
+existing deployment running unauthenticated. It gives up the credential
+entirely rather than deferring it: every route but `/healthz` is then open to
+whoever can route to the container, which is exactly the pre-token behaviour
+and exactly what the credential was added to remove. Only `1`, `true`, `yes` and
+`on`, in any case and with no surrounding whitespace, turn it on: `= 0` and
+`= false` mean off, and so does everything else, because a flag whose
+off-spelling turns it on is a trap — and so is a security escape that accepts
+the shape a value takes when an editor adds a space to it. A configured token
+always wins over the escape, since the escape can only mean "serve without a
+credential", never "ignore the one I was given".
+
+**A worker this host did not create must be provisioned with the token by
+whoever does.** There is no channel back: the worker is handed its credential
+at startup and never publishes it, so a warm pool, a shared container-group
+profile or a container someone else started cannot be authenticated against by
+a host that has no way to learn what it holds. The standby-pool backend cannot
+send a per-instance token: the one property override its claim API admits is a
+config map, and a config map arrives as a file mount under `/mnt/configmap`,
+not as an environment variable — while this worker reads its token from
+`process.env` at startup and never looks at the filesystem for one. That is a
+channel that exists and a credential that still does not go in it, for two
+reasons rather than none: the worker would not read it, and Microsoft's own
+guidance is that config map values are not validated by the runtime and are not
+where a value affecting application security belongs. A token on the shared
+profile would be one credential for every instance claimed from the pool, and
+this backend has no field to present one anyway — so what runs there today is a
+private address (`subnetId`) plus the worker-side escape. The full answer, and
+the change that would close the gap, are in
+`docs/sdk/container-sandbox-worker.md`.
+
+**The transport is not confidential.** `Authorization: Bearer` over plain HTTP
+is replayable by anything on the path, so this is defence in depth behind
+network placement, not a replacement for it. On the container backend the
+worker is reached over Docker's port-forward on host loopback, or by DNS name
+on a private bridge; it does not make a public-address deployment safe, which is
+why the standby-pool backend still refuses to claim one without `subnetId`. The
+egress proxy is unrelated to any of this and checks nothing inbound.
+
 ## Firecracker workspace channels
 
 The Firecracker backend exposes two optional same-sandbox channels. Call

package/dist/backends/aci-standby-pool/index.d.ts

@@ -132,10 +132,28 @@ export declare function assertEnforceable(options: SandboxBackendOptions): void;
  * so nothing looks wrong. A caller who never heard of `subnetId` gets a
  * working sandbox on the internet and no signal at all.
  *
- * What is on that address matters: `worker/server.js` states "Authn: none"
- * in its own docblock and binds every interface. Inside a private network
- * that is the boundary doing the work. With a public address there is no
- * boundary left, and the worker's `/execute` is reachable by anyone.
+ * What is on that address matters: `worker/server.js` binds every interface
+ * and, inside a private network, that was the boundary doing the work — the
+ * worker authenticated nobody. With a public address there is no boundary
+ * left, and the worker's `/execute` is reachable by anyone.
+ *
+ * The worker now requires a per-instance `Authorization: Bearer` token on
+ * every route but `/healthz`, and REFUSES TO START on a routable bind when
+ * it has none. This backend cannot supply one, and the reason this comment
+ * used to give for that was wrong: it said the claim API's single admitted
+ * override — a config map — is no channel into the container group. It is
+ * one, on Linux a file mount under `/mnt/configmap/<containername>/<key>`
+ * carrying caller-supplied per-claim values. The credential is declined
+ * anyway, for two reasons that survive their source: the worker reads its
+ * token from `process.env` at startup and never looks for a file, so a
+ * mounted value is not read; and Microsoft's own guidance is that config
+ * map values are not validated by the runtime and that values affecting
+ * application security "should be made available to the container using
+ * environment variables". The full answer, and the change that would close
+ * the gap, is in `docs/sdk/container-sandbox-worker.md`. What that means
+ * for an operator is written down there too, rather than left to be
+ * discovered at startup; this refusal is unchanged, and now stands in
+ * front of a worker that would refuse the routable case itself.
  *
  * Defaulting to refusal rather than to a warning, because a warning on a
  * path that otherwise succeeds is read once and never again.

package/dist/backends/aci-standby-pool/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/backends/aci-standby-pool/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAEX,8BAA8B,EAU9B,MAAM,YAAY,CAAA;AAGnB,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAc3E;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;AAEpD,MAAM,WAAW,mCAAmC;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;IACtC;;;OAGG;IACH,QAAQ,CAAC,+BAA+B,EAAE,MAAM,CAAA;IAChD;;;OAGG;IACH,QAAQ,CAAC,6BAA6B,CAAC,EAAE,MAAM,CAAA;IAC/C;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAA;IAC/C;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAA;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;IACrC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACrC;AASD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,mCAAmC,GACzC,cAAc,CAiBhB;AAoMD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CActE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC5B,GAAG,IAAI,CAOP"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/backends/aci-standby-pool/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAEX,8BAA8B,EAU9B,MAAM,YAAY,CAAA;AAGnB,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAc3E;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;AAEpD,MAAM,WAAW,mCAAmC;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;IACtC;;;OAGG;IACH,QAAQ,CAAC,+BAA+B,EAAE,MAAM,CAAA;IAChD;;;OAGG;IACH,QAAQ,CAAC,6BAA6B,CAAC,EAAE,MAAM,CAAA;IAC/C;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAA;IAC/C;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAA;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;IACrC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACrC;AASD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,mCAAmC,GACzC,cAAc,CAiBhB;AAoMD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CActE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC5B,GAAG,IAAI,CAOP"}

package/dist/backends/aci-standby-pool/index.js

@@ -39,8 +39,8 @@
  *    a pool-side knob, not a backend knob — the backend never
  *    chooses; it just PUTs against whichever pool the caller named.
  */
-import { generateSandboxId, walkFilesViaExec } from '@namzu/sdk';
-import { HttpWorkerClient } from '../http-worker-client.js';
+import { generateSandboxId, walkFilesViaExec, withHint } from '@namzu/sdk';
+import { HttpWorkerClient, STANDBY_POOL_UNAUTHORIZED_HINT } from '../http-worker-client.js';
 import { OperationDeadline, OperationDeadlineExpired, probeHttpHealth, resolveReadinessOptions, runFailureCleanup, } from '../readiness.js';
 import { RemoteCancellationUnknownError, RemoteProtocolError, } from '../remote-execution-controller.js';
 const DEFAULT_READY_POLL_MS = 500;
@@ -226,10 +226,28 @@ export function assertEnforceable(options) {
  * so nothing looks wrong. A caller who never heard of `subnetId` gets a
  * working sandbox on the internet and no signal at all.
  *
- * What is on that address matters: `worker/server.js` states "Authn: none"
- * in its own docblock and binds every interface. Inside a private network
- * that is the boundary doing the work. With a public address there is no
- * boundary left, and the worker's `/execute` is reachable by anyone.
+ * What is on that address matters: `worker/server.js` binds every interface
+ * and, inside a private network, that was the boundary doing the work — the
+ * worker authenticated nobody. With a public address there is no boundary
+ * left, and the worker's `/execute` is reachable by anyone.
+ *
+ * The worker now requires a per-instance `Authorization: Bearer` token on
+ * every route but `/healthz`, and REFUSES TO START on a routable bind when
+ * it has none. This backend cannot supply one, and the reason this comment
+ * used to give for that was wrong: it said the claim API's single admitted
+ * override — a config map — is no channel into the container group. It is
+ * one, on Linux a file mount under `/mnt/configmap/<containername>/<key>`
+ * carrying caller-supplied per-claim values. The credential is declined
+ * anyway, for two reasons that survive their source: the worker reads its
+ * token from `process.env` at startup and never looks for a file, so a
+ * mounted value is not read; and Microsoft's own guidance is that config
+ * map values are not validated by the runtime and that values affecting
+ * application security "should be made available to the container using
+ * environment variables". The full answer, and the change that would close
+ * the gap, is in `docs/sdk/container-sandbox-worker.md`. What that means
+ * for an operator is written down there too, rather than left to be
+ * discovered at startup; this refusal is unchanged, and now stands in
+ * front of a worker that would refuse the routable case itself.
  *
  * Defaulting to refusal rather than to a warning, because a warning on a
  * path that otherwise succeeds is read once and never again.
@@ -239,7 +257,7 @@ export function assertNotPubliclyAddressed(config) {
         return;
     if (config.allowPublicAddress)
         return;
-    throw new Error('The standby-pool sandbox backend will not claim a container group without `subnetId`: with no subnet the platform assigns a public address, and the worker on it has no authentication of any kind, so its execute endpoint would be reachable from the internet. Supply `subnetId` to inject the group into a private network, or set `allowPublicAddress: true` if this is a benchmark and you mean it.');
+    throw new Error('The standby-pool sandbox backend will not claim a container group without `subnetId`: with no subnet the platform assigns a public address, so the group is reachable by anything that can route to it, and this backend has no credential to put in front of that. A worker with no token refuses to start on a routable bind at all, and a worker that has one is only as strong as its transport — plain HTTP, where a bearer token is replayable by anything on the path. Supply `subnetId` to inject the group into a private network, or set `allowPublicAddress: true` if this is a benchmark and you mean it.');
 }
 async function spawnAciSandbox(config, options, readiness) {
     options.signal?.throwIfAborted();
@@ -407,6 +425,9 @@ async function spawnAciSandbox(config, options, readiness) {
                         encoding: 'base64',
                     }),
                 });
+                if (res.status === 401) {
+                    throw withHint(new Error(`write-file failed: HTTP 401 ${await res.text()}`), STANDBY_POOL_UNAUTHORIZED_HINT);
+                }
                 if (!res.ok) {
                     throw new Error(`write-file failed: HTTP ${res.status} ${await res.text()}`);
                 }
@@ -430,6 +451,9 @@ async function spawnAciSandbox(config, options, readiness) {
                     body: JSON.stringify({ path, encoding: 'base64' }),
                     signal: options?.signal,
                 });
+                if (res.status === 401) {
+                    throw withHint(new Error(`read-file failed: HTTP 401 ${await res.text()}`), STANDBY_POOL_UNAUTHORIZED_HINT);
+                }
                 if (!res.ok) {
                     throw new Error(`read-file failed: HTTP ${res.status} ${await res.text()}`);
                 }