# Security model

## Nix builds and credential isolation (issue #240)

### Background

Agent containers bind-mount the host's `nix-daemon` socket. The host daemon may
have `sandbox-fallback = false` (strict NixOS defaults), which causes `nix build`
inside nspawn containers to fail — containers lack kernel user namespaces, so nix
cannot set up its build sandbox. `harness-base.nix` sets `sandbox-fallback = true`
so that builds fall back to unsandboxed execution rather than failing outright.

### Threat model

Unsandboxed nix builds run as `nixbld` users (non-root, typically UIDs 30001-30010).
Without sandbox isolation, a build derivation's builder script has read access to
any file in the container that the nixbld user can read.

**What is NOT exposed**:

- `/home/<name>/.claude/` — mode `0700`, owned by the per-agent
  user `<name>` (post-#658 — was `/root/.claude` owned by root
  pre-#658). nixbld users cannot read it.
- `$HYPERHIVE_STATE_DIR/forge-token` (= `/agents/<name>/state/forge-token`)
  — written at mode `0600` by `hive-c0re/src/forge.rs` and chowned to the
  per-agent uid:gid by `lifecycle::chown_to_agent` (post-#673/#678).
  nixbld users cannot read it.

**Policy**: all credential files written to agent state directories MUST be mode
`0600` or stricter. Do not create world-readable secret files in agent state dirs.

### Long-term fix

The proper fix is to enable user namespaces inside nspawn containers
(`--private-users=inherit` in `EXTRA_NSPAWN_FLAGS`) so nix can set up its real
sandbox and `sandbox-fallback` becomes a true last resort. This requires verifying
bind-mount compatibility with user namespace UID mapping and is tracked as a TODO.