From 3503b6ae55c9af510eff3fccce9241485fcc00d2 Mon Sep 17 00:00:00 2001 From: arkon Date: Tue, 9 Jun 2026 00:52:27 +0200 Subject: [PATCH] docs(security): add trust model, CSP detail, and source-file map Expand docs/security-architecture.md: - Add a table-of-contents and an explicit "Trust model" section framing the security boundary as network-bind + auth (not a sandbox around --dangerously-skip-permissions), with an actor/granted matrix and out-of-scope notes. - Clarify the file-serving hardening: the octet-stream + attachment + nosniff combination (not the CSP, which allows 'unsafe-inline') is what blocks SVG/HTML execution. - Detail the actual transport security headers: enumerated CSP widenings (cdn.jsdelivr.net, deepgram wss, data:/blob: img-src, gesture wasm opt-in), HSTS, X-Frame-Options, localhost-only CORS. - Add a "Key source files" table and a dated maintenance note. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/security-architecture.md | 97 +++++++++++++++++++++++++++++++---- 1 file changed, 86 insertions(+), 11 deletions(-) diff --git a/docs/security-architecture.md b/docs/security-architecture.md index 6a19f33d..79637314 100644 --- a/docs/security-architecture.md +++ b/docs/security-architecture.md @@ -19,6 +19,43 @@ an explicit, guided opt‑in. --- +## Contents + +1. [Network binding model](#1-network-binding-model) +2. [Authentication](#2-authentication) +3. [Request‑origin trust & the tunnel caveat](#3-requestorigin-trust--the-tunnel-caveat) +4. [Recommended remote‑access setups](#4-recommended-remoteaccess-setups) +5. [File‑serving hardening](#5-fileserving-hardening) +6. [tmux launch hardening](#6-tmux-launch-hardening-cod31) +7. [Supply‑chain & build‑asset hardening](#7-supplychain--buildasset-hardening-cod28) +8. [Multi‑instance isolation](#8-multiinstance-isolation) +9. [Transport security headers](#9-transport-security-headers) +10. [Quick reference](#10-quick-reference) + +--- + +## Trust model + +**The security boundary is the network bind plus authentication — not the code Codeman +runs.** Because sessions launch with `--dangerously-skip-permissions`, the web UI is by +design a remote‑code‑execution surface for whoever is allowed to reach it. Everything +below exists to control *who* that is. + +| Actor | Reaches the UI when… | Is granted | +|-------|----------------------|------------| +| Same‑machine user | Always (default loopback bind) | Full session control — the intended local‑use case. | +| Authenticated remote client | Tunnel/LAN reachability **and** a valid password or session cookie | Full session control. | +| Unauthenticated remote client | Only if you bind a non‑loopback host with no password | Full session control — the exact case every default and warning works to prevent. | +| Clients behind a loopback‑connecting tunnel | A reverse tunnel terminates on `127.0.0.1` | Inherit `req.ip = 127.0.0.1`, so they hit the localhost‑only exemptions (§3) unless a password is set. | + +**Explicitly out of scope.** Codeman is access control for the operator console, not a +sandbox for the code that console runs. It does **not** defend against: a compromised +local user account (loopback is trusted), malicious contents in a workspace you +deliberately open, or the breadth of filesystem a session's `workingDir` is pointed at +(§5). + +--- + ## 1. Network binding model | Setting | Default | Source | @@ -210,10 +247,13 @@ TOCTOU window. A workspace `.svg` served inline as `image/svg+xml` is a stored‑XSS vector (SVG can carry `