@mmerterden/multi-agent-pipeline 20.29.0 → 20.30.0

package/pipeline/multi-agent-refs/features/office-threat-model.md

@@ -0,0 +1,91 @@
+# Office routes: threat model
+
+The office routes of `scripts/contract-server.mjs` let a client watch the
+agents on this machine, read what they said, answer and steer runs, and change
+what runs here (autopilot, stacks, routines). A browser panel may be served at
+`GET /office`. This file names what is protected, from whom, by which control,
+and which test performs the attack.
+
+Scope: the local server only. A remote carrier (a private network or a relay to
+a phone) is a later stage; its additional threats are listed at the end and are
+not mitigated here.
+
+## Assets
+
+| Asset | Where it lives | Why it matters |
+|---|---|---|
+| Bearer token | the server's memory and a 0600 file under `~/.claude/logs/multi-agent/contract-server/` | holds every desktop route |
+| Transcripts | `~/.claude/projects/**.jsonl` | everything a session read, including file contents and command output |
+| Credentials | the credential store (keychain), read only by the pipeline's own scripts | a leak is an account takeover |
+| Run state | `agent-state.json`, `tracker-state.json` | an answer or steer written here changes what a run does |
+| Machine configuration | autopilot `config.json` and launchd jobs, a repo's `.claude/settings.json`, routine commands | widening any of them changes what runs unattended |
+| PR verdicts | posted to GitHub or Bitbucket with the user's own credential | an approval in the user's name |
+
+## Attackers
+
+1. **A malicious web page** in the user's browser, while the server runs.
+2. **Another local user or process** that can reach 127.0.0.1.
+3. **Hostile transcript content**: text an agent read (a web page, an issue, a
+   file) written to make the panel run script or leak data.
+4. **Later, with a remote carrier**: a compromised relay or site, a stolen
+   phone.
+
+## Threats and controls
+
+| # | Threat | Control | Proof |
+|---|---|---|---|
+| T1 | DNS rebinding: a page on an attacker host resolves to 127.0.0.1 and calls the API under its own name | Every request, `/office` and the event stream included, must carry `Host: 127.0.0.1:<port>` or `localhost:<port>`; anything else is 403 before routing | `smoke-office-security.sh` T1, `test/office-routes.test.mjs` "403 under a rebound Host" |
+| T2 | CSRF: a page posts to a write route | Writes (POST, DELETE) accept no `Origin` but the server's own, even an origin allowed with `--allow-origin`; a foreign preflight is 403 and no CORS header is ever sent to a foreign page; writes that widen what runs here take a second request with a single-use, route-bound confirm token | `smoke-office-security.sh` T2, `office-routes.test.mjs` "a write from a foreign page is refused" |
+| T3 | Token theft or replay | The token is read from the `Authorization` header only (never a cookie or a query parameter), compared in constant time over digests, never written into a response, an error or a log line. It never appears in a URL: `office-on` opens the page with a one-time code in the fragment (10 seconds, one use, minted by the bearer holder at `POST /office/code` with no Origin), and the page trades it at `POST /office/exchange`, which accepts only the server's own Origin; a second use, an expired or an unknown code is 401. The code never reaches a command line, which every local user can read (`ps`): the browser is opened on a 0600 launcher page in the 0700 state directory that carries the code and forwards with `location.replace`, under a CSP that allows only its own script by hash; the launcher is removed after 15 seconds. An Origin header can be forged by a non-browser client, so the code's secrecy and its 10 second, single-use life are what protect the exchange. The page keeps the token in memory and strips the fragment. The server exits after 8 hours however busy it is, so a token cannot outlive a working day | `office-control.test.mjs` "the opener's argv carries no code", "the launcher page has a strict CSP", "the launcher is deleted"; `office-routes.test.mjs` "a panel code trades for the token once", "a code is refused from a foreign page", "an expired code is 401", "exits at its absolute lifetime"; `smoke-office-page.sh` "the code trades once" |
+| T4 | Secret exposure through a response | Transcripts are read through `_transcript-tail.mjs`, which never parses api-request records and drops thinking blocks; every string passes the credential redactor and the scrubber; the finished office and chat documents are checked by the outbound gate; seat labels come from allow-listed fields (tool name, file basename, sidecar description), never a command line; credentials are read only by the service scripts and never returned | `smoke-office-privacy.sh`, `smoke-office-security.sh` T4, `test/office-activity.test.mjs` "carries no credential" |
+| T5 | Path traversal into arbitrary files | Session, agent, run, routine, tool and evidence ids are matched against safe character sets after decoding; transcripts are looked up by name under the projects root only; a screenshot must resolve (real path) inside the run's evidence directory; an analysis document named in run state is read only when its real path is inside the run's log directory, its artifacts or a worktree git lists under the state's projectRoot, and only when it is Markdown or HTML | `smoke-office-security.sh` T5, `test/office-work.test.mjs` "nothing outside its directory", "analysis documents are read only inside the run's roots", "a worktreePath counts only when git lists it" |
+| T6 | Oversized or malformed input | Bodies are capped at 64 KiB and validated against the route's schema; tool arguments are checked against the tool's inputSchema; launch input goes through `launch-request.mjs` validation only; chat paging is capped at 500 | `smoke-office-security.sh` T6, `office-work.test.mjs` "refuses an unknown tool, invalid arguments and an oversized body" |
+| T7 | Resource exhaustion | At most four event streams and 64 connections; a phone request has five seconds to send its body before any signature work; at most 256 confirm tokens, the oldest dropped first; service clients, the work list and autopilot control run as child processes, never blocking the event loop, one at a time per service (429 `busy` for a second one); one snapshot is computed per poll from bounded tail reads; the session list is cached for ten seconds; the server exits after its idle time, after 8 hours in any case, and on SIGTERM | `smoke-office-security.sh` T7; `office-routes.test.mjs` "connections past the cap are dropped", "never sends its body", "confirm tokens are capped"; `office-work.test.mjs` "a slow service read neither blocks other routes nor runs twice at once" |
+| T8 | XSS from hostile transcript or issue text | The panel renders every server string with `textContent` or canvas text; markdown is shown as plain text; server images only as `data:` URLs of image types; the office sprites are same-origin PNGs from `/office/assets/`, which answers only a plain file name (no separator or escape) whose real path is a PNG directly in the installed assets directory, and 404 otherwise; the page language the server stamps comes from a two-value set (`en`, `tr`), whatever the preferences file holds; the page's CSP allows only its per-response nonce for script and style, `connect-src 'self'`, no framing, no base URI, no form action | `smoke-office-page.sh`, `office-routes.test.mjs` "stamps the page language from outputLanguage", "serves a sprite and nothing else under /office/assets/", `office-build.test.mjs`, `smoke-office-runtime.sh` |
+| T9 | Clickjacking | `frame-ancestors 'none'` on the page and on every API response | `office-routes.test.mjs` "serves the page without a token, with a nonce CSP" |
+| T10 | An action nobody can account for | Every write leaves one line (who, route, step, status; never a body or token) in `office-actions.jsonl` | `office-routes.test.mjs` "every write leaves a line" |
+| T11 | The panel widening the machine silently | Autopilot on, stack changes and routine removal are tagged `local-only` and `high`, take two requests, and run the same scripts as the terminal commands | `smoke-office-routes.sh`, `smoke-office-single-source.sh` |
+| T12 | A toolkit tool used as a reader of local files or services (a path, a `file://` or loopback URL, a shared browser page, an index of files) | Tool calls are denied by default: only a tool that declares readOnlyHint, is not destructive, is not in the `web` or `context` family and whose inputSchema takes no location (a property named for a path, URL, file, directory, output, project, root and similar, or a uri format, at any depth) is callable; everything else is 403 `tool-not-allowed` and never reaches the server. A `confirm` argument is refused, so a tool's own preview is never skipped. The toolkit child always runs with `MULTI_AGENT_UNATTENDED=1` and `MCP_TOOLKIT_URL_POLICY=strict`, applied after the registration's own environment. An `@latest` registration is pinned to a configured version or refused. The route is `local-only`, and its audit line names the tool and carries a SHA-256 of the arguments, never the arguments | `office-work.test.mjs` "refuses every tool outside the allowlist with 403 and never runs it", "refuses a confirm argument", "runs unattended with the strict URL policy", "pinned to a known version or refused", "the audit line names the tool and hashes the arguments" |
+| T13 | A steer instruction injected into an unattended run | Steering is tagged `launch` and `high` and takes two requests: the first shows the text, the run's phase and the unread instruction it replaces, and returns a token bound to that run and exactly that text; the second carries only the token. A finished run cannot be steered | `office-routes.test.mjs` "previews first, then queues on confirm", "a steer token is single use, bound to its run and cannot carry new text" |
+| T14 | A review verdict posted from a stale or unfinished review | A verdict is previewed only for a finished review whose every finding is accepted, rejected or deferred (409 `review-incomplete` otherwise); the confirm token is bound to the decision and a digest of the findings, and a confirmation after either changed is 409 `confirm-mismatch` | `office-work.test.mjs` "a running review or one with an untriaged finding cannot be previewed", "refused when the findings changed after the preview" |
+| T15 | A service read pointed at another host | A Confluence URL is accepted only on the configured Confluence host, and with no host configured only a page id is accepted (409 `host-not-allowed`), before the client script runs; Crashlytics takes only a Firebase console URL | `office-work.test.mjs` "a Confluence URL on another host is refused before the client runs", "only a page id is accepted" |
+| T16 | Machine paths leaking through errors, or `office-off` signalling a reused pid | Error bodies name no absolute path (the launchd refusal and the unreadable settings message say what failed, not where); `office-off` sends SIGTERM only when the recorded pid's token file still names it, its command is `contract-server.mjs` and its start time matches the token file's | `office-routes.test.mjs` "refused without naming its path", "reported without the plist path"; `smoke-office-control.sh` "off never signals a pid that is not its server" |
+
+## Residual risks
+
+- **Figma REST from the panel**: `GET /v1/services/figma` renders a frame
+  with the user's Figma token through `figma-screenshot.sh`. It runs only for
+  a panel request, in the server's own process, never inside a pipeline run's
+  context; the pipeline's own rule that Figma is fetched only in the analysis
+  phase is about runs and is unaffected. The Figma MCP is never called here.
+
+- **Another process of the same user** can read the token file and call the
+  API. The server does not defend against code already running as the user;
+  nothing local does.
+- **A page on the server's own origin** is trusted. Only the page this server
+  serves can be there, and its CSP keeps other code out.
+- **Starting a session**: the server returns the launch plan and never starts
+  a host process, so a panel without a local process to run the plan cannot
+  start work by itself. That is a deliberate boundary of the contract.
+- **Host permission prompts** are not forwarded: the host records none where
+  another process can read them (`GET /v1/permissions` says `available:
+  false`).
+
+## Later, with a remote carrier
+
+Not mitigated by this server alone; the carrier must add them before any route
+leaves the machine:
+
+- a compromised relay or site: end-to-end encryption with keys only on the
+  phone and the machine, a separate locked origin with a strict CSP;
+- a stolen phone: device keys bound to a passkey, revocation
+  (`phone-devices.mjs revoke`), and per-operation passkey signatures for every
+  `high` route;
+- the `remote` and `risk` tags on every route are the input for that
+  enforcement; `local-only` routes are never offered remotely;
+- steering from a phone takes a closed set of canned templates (for example
+  "stop after the current phase", "keep the change minimal", "skip the UI
+  test"), chosen by id and expanded on the machine, never free text typed on
+  the phone; free-text steer stays a desktop route;
+- toolkit tool calls stay `local-only`; a phone gets their results only
+  through a run.

package/pipeline/multi-agent-refs/help/en.md

@@ -86,6 +86,9 @@ Status & Resume:
   /multi-agent:autopilot-status  Running, queued, awaiting an answer, today's PRs
   /multi-agent:autopilot-off  Stop picking work up (running work finishes; --now stops it)
   /multi-agent:serve          Contract server for a client: 127.0.0.1, token, stops when idle
+  /multi-agent:office-on      Open the office panel in your browser: agents at work, chats, ledger, runs
+  /multi-agent:office-status  Is the panel running, its URL (never the token), its last actions
+  /multi-agent:office-off     Close the panel now (it also stops by itself when idle)
 
 Post-Hoc & Side-Channel:
 

package/pipeline/multi-agent-refs/help/tr.md

@@ -85,6 +85,9 @@ Status & Resume:
   /multi-agent:autopilot-status  Koşan, sıradaki, cevap bekleyen, bugünkü PR'lar
   /multi-agent:autopilot-off  Yeni madde alma (koşan iş biter; --now onu da durdurur)
   /multi-agent:serve          İstemci için sözleşme sunucusu: 127.0.0.1, token, boşta durur
+  /multi-agent:office-on      Ofis panelini tarayıcıda aç: çalışan ajanlar, sohbetler, defter, koşular
+  /multi-agent:office-status  Panel çalışıyor mu, adresi (token asla), son işlemleri
+  /multi-agent:office-off     Paneli hemen kapat (boşta kalınca kendisi de kapanır)
 
 Post-Hoc & Side-Channel:
 

package/pipeline/office/NOTICE.md

@@ -0,0 +1,42 @@
+# Notice
+
+The office page (`index.html`, built from `pipeline/office-src` by
+`pipeline/scripts/office-build.mjs`) draws sprites from pixel-agents
+(https://github.com/pixel-agents-hq/pixel-agents, commit b1bafd0): the six
+character sheets, the floor and wall tiles and the furniture, kept unchanged
+in `assets/`. pixel-agents'
+characters are based on JIK-A-4's MetroCity free top-down character pack
+(https://jik-a-4.itch.io/metrocity-free-topdown-character-pack), released
+under CC0 1.0.
+
+The page also follows pixel-agents' rendering approach: bitmask wall tiles,
+colorized grayscale floors, bottom-anchored furniture sorted by depth, and
+16x32 characters with walk, type and read frames. The transcript reading in
+`pipeline/scripts/activity-snapshot.mjs` and `_transcript-tail.mjs` follows
+its half-line buffer and its subagent classification by `.meta.json`
+sidecar. The code, the map layout, the stations, the runtime and the server
+are written for this pipeline; no pixel-agents code is copied.
+
+pixel-agents is distributed under this license:
+
+MIT License
+
+Copyright (c) 2026 Pablo De Lucca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.