XERK-268: make an agent's host proved by its credential, not typed

[xerhab]

Closes XERK-268.

The defect, and how it turned out to be bigger than the ticket

<host> in /api/agents/<host>/… is a value the caller types. With one fleet-shared TURMA_AGENT_TOKEN, nothing backed it — so scoping a relay to m.srcHost / m.targetHost / u.host refused a caller naming itself and passed one naming the victim.

Verifying that, I found the ticket's severity rationale understated. device on /api/heartbeat is self-asserted the same way, and the reply hands back that host's queued commands — so the shared token alone was enough, with no leaked id:

1. Attacker POSTs {"device":"hsA"} → gets back {"type":"exportSession","migrationId":"…"}.
2. Beats again as hsA asserting worktreePath:"…/PWNED", then POSTs forged bytes to /api/agents/hsA/migrations/<id>/blob → {"ok":true}.
3. The real target is told importSession … cwd:"…/PWNED" — attacker-chosen bytes and cwd.

That also rules out the per-relay one-time secret the ticket weighed as the other option: it would ride on exactly the commands an impersonated heartbeat hands out. Only binding the credential to a host closes it. Chosen with the ticket's author.

The fix

Each agent runs on its own token, <base64url(device)>.<HMAC-SHA256(master, device)>. The hub keeps only the master and re-derives it for whatever host a request names, so there is no host list and no restart to add one.

The token names its host on purpose. An HMAC can't be inverted, so a bare digest could only be checked once the host was known — and /api/heartbeat, whose host is buried in a 32 MiB body, would have had to admit any bearer before reading it. tokenHost() reads the name half and re-derives, comparing the whole token, so editing the name breaks the HMAC.

agentBearerKind(req, host) → proved / operator / legacy / null is the one resolver. Bound at: the three blob relays, archive ingest, the updating signal, the heartbeat's device, /agent/control's ?name=, and /agent/data (which now carries the host its channel was opened for). This fixes every agent-authed route at once, including ones added later — and the two XERK-266 guards land here too, since that branch is unmerged; with the binding they finally mean what they claim.

Compatibility — nothing breaks on merge

The master still authenticates as legacy, so upgrading the hub alone changes nothing and every agent keeps working. TURMA_AGENT_STRICT=1 retires it; the hub warns at boot until it is set. ttydAuth(host) sends whichever token that host actually authenticated with, so a half-rolled fleet keeps its terminals. No agent-side behavior change — only the value of TURMA_TOKEN.

node turma/server.js --agent-token <device> prints a host's token.

The DockerOps rollover is XERK-275, deliberately not here: an agent presenting a derived token to a pre-XERK-268 hub gets a flat 401, so the hub must ship first.

Verification

Adversarial QA (~/.claude/agents/qa.md) ran three passes; the first two were FAIL and PARTIAL and both were right.

FAIL — an unauthenticated remote DoS I introduced. Binding the heartbeat forced its gate to a weaker check that accepted any Bearer <anything>, so an anonymous caller reached a 32 MiB readBody + JSON.parse. 8 concurrent 31 MiB posts killed a 256 MiB container 3/3 with a V8 heap OOM — the control plane for the whole fleet. Fixed at the root by the self-identifying token above. Re-measured: 401 in 3 ms, RSS +256 KiB vs +143 MiB, container survives 8 and 24 concurrent. Two riders died with it (a JSON.parse internals leak, and an attacker-chosen device reaching the log pre-binding).

PARTIAL — TURMA_AGENT_STRICT did not bite at that gate. A master-holder still reached the read before the 403, so a leaked master still OOM'd a fleet whose whole point was that the master had been retired. Not a regression (origin/main dies to the same attack) but it was this change's own claim. Now refused at the gate, with the rollover message rather than a bare 401. QA re-verified by memory, not status code: refused master +3 MiB RSS vs +137 MiB for an accepted beat — a 45× gap proving the body is unread.

PASS. All six claims confirmed with running evidence; 23/24 mutants caught, the survivor empirically proven equivalent. What QA could not break: 20 forged-token shapes and 40 non-canonical encodings all rejected; no timing oracle (spread 1.70×, non-monotonic, full match fastest); no host-enumeration oracle — a nonexistent host name gives an identical refusal; gate and handlers cannot disagree on the decoded segment. Full cross-host matrix over 6 surfaces × 2 rigs, 26-case WebSocket matrix, migration/attachment/archive/terminal E2E, and the real hub-agent.py driven both ways.

Also fixed from QA: the /agent/data?ch=__proto__ hub kill (pre-existing, on a line this diff rewrote — both tunnel maps are null-prototype now); the agent discarding the hub's refusal body, so a bad rollover no longer reads as a bare HTTP Error 403; a wrong-host token answering 403 naming both hosts, since its likeliest cause is a rename (the name is inside the token); hostAgentToken refusing non-string and non-round-tripping names, which String() would have coerced into a real credential; and tests for the three mutants that escaped — including the migration GET's targetHost scope, which unguarded hands any host another's raw transcript.

I disputed one finding with evidence and QA retracted it: the tokenBound-ordering mutant is caught (their mutant left the original assignment in place, making it a no-op).

Suites: node 1099/1099, python 1288 OK.

Known limitation, not introduced here

An authenticated agent can still OOM the hub with 8 × 31 MiB beats. Inherent to the design — the host is in the body, so the body must be read to bind it — and present on origin/main via its equivalent credential. Filed as XERK-288 rather than scope-crept into this PR; the fix is a decision about what rides the heartbeat.

Not verified

Android / glasses / veiller were not booted: no wire change (tokenBound is stripped from /api/agents and SSE, no field added or retyped), so no PARITY.md entry is owed. Also unexercised: a real two-agent migration with live tmux/claude (the auth-relevant half is covered), the Sessions Move UI, the agent-host image, and a DockerOps rehearsal.

Merge with main, and one thing carried that isn't mine

XERK-266 and XERK-263 landed while this was in QA, and both had grown the same two migration blob routes. The route bodies are main's entirely — its uniform-404 refusals and disk spooling are ahead of what this branch carried, and this branch's contribution there was only the srcHost/targetHost scope main already has. What is kept is the binding at the gate, which is orthogonal.

The comments are rewritten rather than taken from either side, because this change alters what main's now say: where main documents the scoping as "defense in depth, NOT an identity check" and names the two oracles its uniform 404s could not close — the reply timing and the 413 — both needed an unverified caller, and there no longer is one. The uniform 404s stay: they are what still holds if a future route reaches that code with a weaker credential.

Test suites were additive on both sides, so both are kept; this branch's duplicate title was renamed. One real behavioral conflict, fixed rather than papered over: XERK-263's MIGRATE_INFLIGHT_MAX (4) counts in-flight moves fleet-wide, and this branch's tests left three of them, so main's later tests got a 503 and failed somewhere unrelated to what they test. Added settleMigration() to the three tests that start a move.

.trivyignore carries one entry that has nothing to do with this change. CVE-2026-46600 (golang.org/x/net in the bundled terraform) was published today and fails the agent-image scan on every open PR — XERK-265 is red on it too. terraform 1.15.8 is still the newest stable (1.16.0 is at rc1), so TERRAFORM_VERSION has nothing to bump to short of shipping a pre-release into a production image. Triaged in the same shape and with the same reasoning as the three terraform entries already in that file, with an expiry to force the revisit. Called out here because it is unrelated to the rest of the diff — revert that commit alone if you would rather handle it separately.