ADR 0276 — A download writes through its root capability

Context

A lexical containment check decides whether a filename is inside an output directory; writeFile still follows an existing symlink at that name. Checking with lstat first leaves a race before opening, and resolving a parent path again lets an actor replace an ancestor between the check and write. Reopening the output root for each media file also lets one command silently change its authority while awaiting a response.

The coding tools already need descriptor-relative filesystem access on Linux and macOS. CLI code must share that mechanism without importing the separately bounded agent runtime.

Decision

The generic contained directory, handle and writer primitives live in internal, a leaf shared by the runtime and tools. One writer sequence serves both platforms: an exclusive open, a full write, an optional descriptor chmod, and for a replacement a rename from the shared staging name. Linux reaches entries through descriptor paths; Darwin through the packaged directory-relative native operations. Exclusive creation opens the final name, so a filesystem without hard links still creates files.

The configured root is authority selected once before fetching. Initial root aliases are allowed: the caller chose that directory. Canonicalization selects an existing prefix; opening it walks each canonical component from the filesystem root with nofollow directory operations. Intermediate directories need search permission, not listing permission: Linux uses O_PATH, and Darwin uses O_SEARCH. A read capability is requested only by callers that list the selected directory. Missing components are created through pinned parents and then opened with nofollow. A symlink introduced after selection causes refusal rather than redirection. After pinning, the descriptor remains the selected root object for the entire batch, including when that object is renamed. This is an object boundary, not a guarantee that its original pathname remains attached to it.

Media names are direct children. An exclusive staged file is written fully before atomic publication. Replacing a leaf symlink, dangling link or hard link replaces that directory entry, never writes through it. A directory refuses replacement. Existing ordinary-file permission bits are retained; new downloads use 0666 & ~umask. Permissions are applied to the new file descriptor, never through the final path.

Unsupported platforms refuse filesystem downloads; there is no path-based fallback. macOS bundles package the native backend with createNativePackaging. Other CLI operation paths stay portable. Network pinning, credentials, byte caps and deadlines remain with the existing guarded transport. A download refusal never changes a successful operation into a reason to replay it: stdout keeps that result and the exit reports partial failure.

Alternatives

  • Resolve and check every path before writing: rejected because the path can change afterward.
  • Open the final file with nofollow and truncate it: rejected because hard links still share an external inode, and partial writes would damage an existing result.
  • Add a CLI-specific writer or import coding tools: rejected because one duplicates the security engine and the other crosses the agent-runtime boundary.
  • Fall back on unsupported platforms: rejected because success would claim a boundary the platform implementation has not established.

Consequences

This breaks callers of --output-dir, marked and migrated in 0.115.0. Windows and other unsupported platforms lose downloads, because any fallback there would claim a boundary it cannot hold. A macOS bundle or compiled binary needs the native backend at build time, because the boundary cannot exist without it. CLI commands without downloads are unaffected. A replacement is a new file, so it needs write permission on the directory, belongs to the process user and cannot land on a bind-mounted file.

Verification

The installed public CLI proof checks external bytes, link replacement, permission bits, root replacement during HTTP response delivery, a multi-file batch and partial refusal. Unit controls replace a canonical ancestor before root opening and prove it cannot redirect creation. The same binary writer accepts empty content and subarrays without decoding them. Existing Darwin artifact controls exercise successful and unavailable CLI download paths in packed, relocated and embedded artifacts; actual Darwin execution belongs to that host lane.

Serves I8, I12, I13 and I15.