mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00

Files

T

Renn F 3441e37120 [sweep] strip Fxxx audit-ID tokens + trim bloated comments/docstrings + add behavior-change docs

Post-audit sweep over the 135 audit-fix commits since 19a474d3:

1. Stripped every # Fxxx: audit-ID token from comments AND every Fxxx token
   from docstring openings across 211 blocks / ~626 lines. The CEO flagged
   these twice: audit-issue IDs in code confuse future devs/agents. The
   descriptive text is preserved; only the Fxxx token is removed (and bloated
   narrative blocks trimmed to 1-3 lines keeping the one non-obvious invariant).
2. Trimmed bloated comments/docstrings to the concise standard (1-3 lines).
3. Added missing behavior-change docs for the audit-fix batch: prompts/roles
   (documenter, pr_reviewer, qa), user-facing docs (api auth, websockets,
   agent-gateway, megatask, merge-model, task-lifecycle, grok, resilience,
   conventions, panel, security, troubleshooting), and the RAG corpus (cell-pm,
   main-pm, pr-reviewer, qa roles; conventions; messaging-tools; escalation;
   megatask; task-claiming workflows).

Comment/docstring/prose ONLY — zero code-line edits (verified: the diff
contains no def/class/return/if/for/await/assignment/call lines). Gates green:
ruff format + ruff check clean, mypy clean on roboco/. The only pytest failures
are the pre-existing sync_branch tracing-decision gap (B1, 250be5c2) — not
sweep-caused and tracked separately.

2026-06-29 01:25:40 +02:00

5.3 KiB

Raw Blame History

Authentication

RoboCo's API identifies a caller by a small set of headers — X-Agent-ID, X-Agent-Role, and optionally X-Agent-Team. How much it trusts those headers depends on one flag. Out of the box the API runs in header-trust mode, which is fine on a private LAN and dangerous anywhere else. This page covers both modes and the WebSocket caveat.

The identity headers

Every REST request carries:

Header	Required	Meaning
`X-Agent-ID`	Yes	The agent's UUID or slug (e.g. `be-dev-1`).
`X-Agent-Role`	Yes	The role the caller is acting as (e.g. `developer`, `cell_pm`, `ceo`).
`X-Agent-Team`	No	The team (`backend`, `frontend`, `uxui`), when relevant.
`X-Agent-Token`	Only in secure mode	The HMAC token that proves the headers above weren't forged.

These are resolved in roboco/api/deps.py (get_agent_context), and the role gates the action — so a request claiming X-Agent-Role: ceo can do CEO-only things like approving and merging.

Header-trust mode (default)

By default ROBOCO_AGENT_AUTH_REQUIRED is unset/false. In this mode the API accepts the role headers without verifying any token. There is no proof of identity: whoever sets X-Agent-Role: ceo is the CEO for that request.

!!! danger "Anyone who can reach the API can claim any role — including CEO" In header-trust mode there is no authentication. Any client that can open a connection to the orchestrator port can act as any agent, approve and merge work as the CEO, cancel tasks, or override task state. The app logs a loud startup warning to this effect. This is acceptable only on a trusted private network where nothing untrusted can reach the orchestrator — which is the default single-host LAN deployment behind nginx on localhost:3000. Do not expose the orchestrator to anything you don't control without first turning on secure mode.

Secure mode (HMAC tokens)

Set ROBOCO_AGENT_AUTH_REQUIRED=true to require a signed token on every REST request. In this mode:

X-Agent-Token becomes mandatory; a request without it is rejected with 401.
The token is an HMAC signed with ROBOCO_AGENT_AUTH_SECRET and bound to the agent's id, role, and team. The server recomputes the signature over the presented X-Agent-ID / X-Agent-Role / X-Agent-Team and compares it constant-time. If a caller swaps the role header to escalate to ceo, the signature no longer matches and the request is rejected with 401 — signature mismatch.
The orchestrator issues each agent its token at spawn time, so delivery agents are authenticated by construction.
A presented token is always verified, even when auth isn't required — so you can roll out tokens before flipping the switch without breaking anything.

Flag	Default	Purpose
`ROBOCO_AGENT_AUTH_REQUIRED`	`false`	When `true`, REST requires a valid HMAC `X-Agent-Token`.
`ROBOCO_AGENT_AUTH_SECRET`	(unset)	Shared secret the orchestrator uses to sign and the API uses to verify the per-agent token.

!!! tip "How the panel authenticates as the CEO" The control panel acts as the CEO agent. In secure mode, nginx injects the panel's CEO X-Agent-Token so your browser session is authenticated without you handling the secret — you just use the panel as normal.

The WebSocket + live-chat streams

Secure mode extends beyond REST. When ROBOCO_AGENT_AUTH_REQUIRED=true:

The per-resource WebSocket streams (/ws/channels|agents|sessions|notifications/{id}) require the CEO panel token — the same signed X-Agent-Token nginx injects for the panel. An agent on the Docker network can no longer subscribe to another agent's notifications with no auth. They still validate agent_id/viewer_id against the DB and channel access on top.
The /api/v1/do/* content routes require a valid per-agent HMAC token bound to X-Agent-ID (the do router serves every role, so the gate is token-only, not role-specific).
The live-chat bridges (/prompter/live/*, /secretary/live/*) — the prompter/secretary intake chats — require the CEO panel token on their start/stream/status/messages/stop endpoints. They were the last panel-facing API surface that ran unauthenticated.
/ws/system stays operator-only and read-only by design (it carries system telemetry and accepts nothing from the client); it is not token-gated.

A presented-but-forged token is rejected even in dev (header-trust) mode, so you can roll out tokens before flipping the switch without breaking anything. The container→relay internal callback is left ungated by design (internal Docker network, opaque session id).

What to do

Single-host LAN, nothing untrusted on the network → header-trust is fine; that's the default.
Anything reachable beyond a trusted LAN → set ROBOCO_AGENT_AUTH_REQUIRED=true and a strong ROBOCO_AGENT_AUTH_SECRET, and keep the orchestrator port off the public internet regardless.

For the full hardening checklist — network exposure, the GitHub PAT handling, and the prompt/bash guards — see Security.

REST API — the route surface these headers authorize.
WebSockets — the live streams and their separate auth model.

5.3 KiB Raw Blame History