docs: move dashboard.rs security + bind rationale to docs (#715)

docs/security.md

@@ -1,5 +1,42 @@
 # Security model
 
+## State-file endpoint security model
+
+`GET /api/state-file?path=<p>` serves files from agent state dirs and
+the shared space to authenticated dashboard users (browser, operator).
+Two allow-listed root prefixes are accepted; all other paths are rejected
+before touching the filesystem:
+
+- `/var/lib/hyperhive/agents/<n>/state/` — per-agent durable notes
+  (canonical host form or the in-container view `/agents/<n>/state/`)
+- `/var/lib/hyperhive/shared/` — shared docs (`/shared/` in-container)
+
+`/state/...` without an agent prefix is explicitly *not* accepted — it is
+ambiguous from the host's perspective.
+
+Defense-in-depth layers (in order):
+
+1. **Allow-list prefix check** — rejects without touching the filesystem
+   if the path doesn't match either root.
+2. **No symlinks below the matched root** — each path component is
+   checked with `symlink_metadata` before canonicalize. A sub-agent
+   that plants `ln -s /other/secret /agents/me/state/peek` can't proxy
+   another agent's file through this endpoint (canonicalize would
+   happily resolve the symlink to a still-within-allow-list path).
+3. **Canonicalize as belt-and-braces** — resolves `..`/`.` traversal
+   and rejects if the result escapes the roots.
+4. **`state/` subdir constraint** — under `AGENTS_ROOT`, the second
+   path component must be `state/`. Applied, proposed git repos and
+   config dirs are off-limits.
+5. **World-readable check** — file must have `mode & 0o004` set.
+   A `0600` file inside `state/` would otherwise be accessible to any
+   operator with dashboard access.
+
+`scan_validated_paths` (broker-message ingest, linkifier) uses the same
+`resolve_state_path` helper so security rules stay in sync — the
+dashboard renders anchors only for tokens that passed the same checks the
+read endpoint enforces.
+
 ## Nix builds and credential isolation
 
 ### Background