docs: move sandbox threat model to docs/security.md, add code reference

docs/security.md

@@ -0,0 +1,33 @@
+# 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**:
+
+- `/root/.claude/` — mode `0700`, owned by root. nixbld users cannot read it.
+- `/state/forge-token` — written at mode `0600` by `hive-c0re/src/forge.rs`.
+  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.