From 28df69286d7f1ae8a0e38336fb2be7ea4724572f Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Fri, 5 Jun 2026 16:28:55 +0200
Subject: [PATCH] docs(security): document hive-priv privilege separation model

---
 docs/boundary.md |  7 +++++--
 docs/security.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/docs/boundary.md b/docs/boundary.md
index 95a07ebc..ba3f7b2b 100644
--- a/docs/boundary.md
+++ b/docs/boundary.md
@@ -51,9 +51,12 @@ Suggested sequencing of the `area:ops` issues:
 
 1. **Gateway** first — pure ergonomics win, unblocks same-origin
    (lets the cross-origin CORS shim on `/answer-question/{id}` go
-   away), no behavioural risk.
+   away), no behavioural risk. ✅ **Done** — nginx gateway in front of
+   all surfaces; per-agent UIs proxied under `/agent/<name>/`.
 2. **Network isolation** next — the step that makes the boundary
    real. Everything before it is honour-system.
 3. **Privsep** last — defence in depth on the core process
    itself; valuable independent of the other two, but the
-   biggest refactor.
+   biggest refactor. ✅ **Done** — `hive-c0re` dropped from root to
+   `hive-core` user; `hive-priv` is the narrow root helper.
+   See [`docs/security.md`](security.md) for the privilege boundary table.
diff --git a/docs/security.md b/docs/security.md
index d740f066..4c9ead78 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -71,3 +71,53 @@ 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.
+
+## hive-c0re privilege separation
+
+### Background
+
+`hive-c0re` runs as the unprivileged system user `hive-core`
+(`/var/lib/hyperhive` owned by `hive-core:hive-core`). It cannot
+directly invoke `nixos-container`, `journalctl -M`, or `systemctl
+-M hive-gateway` — those require root. `hive-priv` fills this gap.
+
+### hive-priv
+
+`hive-priv` is a minimal privileged helper that runs as root, socket-activated
+at `/run/hive/priv.sock` (mode `0660`, group `hive-core` — only the
+`hive-core` user can connect). `hive-c0re` calls it via `priv_client`
+for every operation that genuinely requires root.
+
+**Narrow interface** — `PrivRequest` variants map 1:1 to specific
+known operations; there is no arbitrary command pass-through:
+
+| Operation | What it runs |
+|-----------|-------------|
+| `StartContainer` / `StopContainer` / `KillContainer` | `nixos-container start/stop/kill <name>` |
+| `CreateContainer` / `UpdateContainer` | `nixos-container create/update <name> --flake <ref>` |
+| `DestroyContainer` | `nixos-container destroy <name>` |
+| `ListContainers` | `nixos-container list` |
+| `ReadContainerJournal` | `journalctl -M <container> -n <n> [filters...]` |
+| `ReloadGateway` | `systemctl -M hive-gateway reload/start/reset-failed nginx` |
+| `AddBindMount` / `RemoveBindMount` | `systemctl set-property` or `machinectl bind` |
+| `WriteAgentForgeToken` / `WriteAgentMatrixToken` | write `0600` credential file into agent state |
+| `SetNetworkIsolation` | manage per-container network isolation flags |
+
+**Container allowlist** — every request is validated against an
+allowlist before any operation: only names matching `h-<agent>` (the
+standard agent prefix), the manager container, or the known sibling
+service containers (`hive-gateway`, `hive-forge`, `hive-matrix`,
+`hive-ci`) are accepted. Arbitrary container names are rejected.
+
+**Socket-activated** — systemd starts `hive-priv` on the first
+incoming connection (`LISTEN_FDS=1`); it is not running between calls.
+The `ProtectSystem=strict` + `ReadWritePaths` sandbox limits filesystem
+writes to only the paths `hive-priv` legitimately needs.
+
+### Privilege boundary summary
+
+| Component | Runs as | Privilege needed for |
+|-----------|---------|----------------------|
+| `hive-c0re` | `hive-core` | broker, HTTP dashboard, scheduling, approvals |
+| `hive-priv` | `root` | container lifecycle, journal reads, bind mounts, cred writes |
+| `hive-ag3nt` (per-container) | per-agent user | turn execution, MCP serving |