Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs(relay-pop): scope the two PoP invariants the push-webhook merge made false
review8567f2737929
diff --git a/CLAUDE.md b/CLAUDE.mdindex 0df02cdaf..89291cd13 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -7839,12 +7839,22 @@ The invariants, each with its reason:asked for, so a code holder could spend the host's hourly mints. Now the host-token mint (desktopphone relay and Server Edition hosted mint) and the desktop's host-mode push first take achallenge from `/v1/relay/challenge` and send a proof. Rules a refactor must not undo:- - **`src/core/relay/relay-pop.ts` is the ONLY proof computation**, and it refuses an all-zero- shared secret (a low-order server key gives every caller the same secret). Its bytes are pinned- by `relay-pop-vector.json`, mirrored byte for byte in nodeterm-server: a protocol change changes- both.+ - **`src/core/relay/relay-pop.ts` is the ONLY computation of the relay PoP proof** (the+ host-token mint and push host-auth), and it refuses an all-zero shared secret (a low-order+ server key gives every caller the same secret). Its bytes are pinned by `relay-pop-vector.json`,+ mirrored byte for byte in nodeterm-server: a protocol change changes both. The push webhook's+ management proof (`core/push-webhook.ts` `webhookProof`, § Push webhook) is a SEPARATE,+ independent proof of the same host key, with its own challenge route+ (`/v1/push/webhook/challenge`), its own context string and its own wire contract (nodeterm-server+ `src/lib/host-proof.ts`). Do not fold either one into the other; the all-zero refusal here does+ not cover it.- **A request goes out unproven ONLY when the challenge answered 404/405** (a backend that- predates the proof). Never after a transient failure (5xx, 429, network, an unusable challenge):+ predates the proof). **One exception, push only:** a challenge answered 200 followed by+ `/v1/push/host-auth` answering 404 also posts unproven, and that verdict is cached 10 minutes like+ a 404/405 one (`push-notify.ts` `establish`). One backend registers both routes or neither, so+ this happens only in a redeploy window; push stops nothing, and the backend gates the unproven+ post regardless (a latched host's is refused, which forgets the verdict, and the host proves+ again). Never after a transient failure (5xx, 429, network, an unusable challenge):the backend LATCHES a host at its first valid proof and refuses an unproven request from it(`403 pop_required`; every host after `POP_REQUIRED_AFTER`, default 2027-01-01), so anunproven mint there would stop hosting. Conversely, a `pop_required` answer to a mint sentdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 32d559d13..938704288 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -505,8 +505,10 @@ anything else. Board-level fields survive every transform — `pullLinks` is one- **A request that trusts a relay host key (host-token mint, host-mode push) proves possessionthrough `src/core/relay/relay-pop.ts`, and falls back to an unproven request ONLY on a 404/405- challenge.** Change the protocol and `relay-pop-vector.json` must change in both repos. Deep- version: CLAUDE.md § Hosted team relay.+ challenge.** One exception, push only: a 200 challenge followed by a 404 from `/v1/push/host-auth`+ (possible only in a backend redeploy window) also posts unproven, and caches that verdict for 10+ minutes; push stops nothing, and the backend gates the post regardless. Change the protocol and+ `relay-pop-vector.json` must change in both repos. Deep version: CLAUDE.md § Hosted team relay.- **Normalize BOTH sides of a path comparison, through one function.** A marker normalized whereit is built and matched raw where it is used is a no-op on the machine you wrote it on and adiff --git a/docs/hosted-team-relay.md b/docs/hosted-team-relay.mdindex 661cdc4df..4199691a2 100644--- a/docs/hosted-team-relay.md+++ b/docs/hosted-team-relay.md@@ -26,7 +26,7 @@ every message**. The desktop's UI only mirrors it.| Hosted service | `src/core/relay/hosted-service.ts` | Composes the host key, team store, scheduler and access policy; holds pending join requests; answers the `relay:hosted:*` verbs. || Standing listener | `hosted-scheduler.ts` + `host-token.ts` | A pure scheduler over injected mint / open / timers. || Host identity | `host-key.ts` | `<dataDir>/relay/host-key.json`, 0600, plaintext secret (headless Linux has no keyring). |-| Host key proof | `relay-pop.ts` + `relay-pop-vector.json` | The only place a proof of the host key is computed. See [Host key proof of possession](#host-key-proof-of-possession). |+| Host key proof | `relay-pop.ts` + `relay-pop-vector.json` | The only place the relay PoP proof (host-token mint, push host-auth) is computed. See [Host key proof of possession](#host-key-proof-of-possession). The push webhook's management proof is a separate protocol (`src/core/push-webhook.ts`). || Membership | `team-store.ts` | `<dataDir>/relay/team.json`, 0600, single writer. || Role policy | `access-policy.ts` | `VIEW`, `COMMENT`, `EDITOR_ONLY`, `VIEW_EVENTS`; the guard test is `access-policy.guard.test.ts`. || Admin channel | `team-admin.ts` (socket) + `src/server/team-cli.ts` (CLI) | `<dataDir>/relay/admin.sock`, 0600 in a 0700 directory. |@@ -644,9 +644,10 @@ The human `team status` reads `state`, `idle` and `lastError` together:## Host key proof of possession-The fix for R44 (see [Threat notes](#threat-notes)). It covers every request that trusts a relay-host key: the Server Edition's hosted mint, the desktop phone relay's mint, and the desktop's-host-mode push. It is enforced by nodeterm-server; this repository holds the client half.+The fix for R44 (see [Threat notes](#threat-notes)). It covers the Server Edition's hosted mint, the+desktop phone relay's mint, and the desktop's host-mode push. (The push webhook's management routes+prove the same key through a protocol of their own; see below.) It is enforced by nodeterm-server;+this repository holds the client half.**The exchange.**@@ -662,10 +663,18 @@ host-mode push. It is enforced by nodeterm-server; this repository holds the clialready accepted, and an all-zero shared secret, and answers any proof that does not verify with`403 {"error":"pop_invalid"}`.-`src/core/relay/relay-pop.ts` is the only place the client computes a proof, and it also refuses an-all-zero shared secret (a low-order server key gives every caller the same secret). The bytes are-pinned by `src/core/relay/relay-pop-vector.json`, which nodeterm-server carries byte for byte as-`test/fixtures/relay-pop-vector.json`. A protocol change changes both.+`src/core/relay/relay-pop.ts` is the only place the client computes this proof (for the host-token+mint and push host-auth), and it also refuses an all-zero shared secret (a low-order server key gives+every caller the same secret). The bytes are pinned by `src/core/relay/relay-pop-vector.json`, which+nodeterm-server carries byte for byte as `test/fixtures/relay-pop-vector.json`. A protocol change+changes both.++The push webhook's management routes (minting, reading and revoking a webhook token) also prove+possession of the host key, through a separate and independent protocol: `webhookProof` in+`src/core/push-webhook.ts`, with its own challenge route (`/v1/push/webhook/challenge`), its own+context string and its own wire contract (nodeterm-server's `src/lib/host-proof.ts`). It shares+nothing with this proof but the key. Do not route it through `relay-pop.ts`, and do not assume the+all-zero refusal above covers it.**The latch and the cutoff.** The first valid proof for a host **latches** it (the backend recordsits host id). From then on, a request for that host without a proof is refused@@ -704,6 +713,13 @@ means "this backend predates the proof", and only then does a request go out unpchallenge failure is transient: the request is not sent, and the caller backs off. An unprovenrequest from a latched host is refused, and for a mint that refusal would stop hosting.+There is one exception, and only push has it: a challenge answered 200 followed by+`/v1/push/host-auth` answering 404 is also read as a backend without the proof, so the post goes out+unproven and that verdict is cached for 10 minutes. One backend registers both routes or neither, so+this answer comes only from a redeploy window. Push stops nothing, and the backend gates the+unproven post regardless: a latched host's post is refused, which forgets the verdict, and the host+proves again.+- **Server Edition hosted mint** (`host-token.ts`, `hosted-scheduler.ts`). The challenge, the mintand the mint's body read share one 8 s timer. A challenge answered 429 waits at least 60 s(`rate-limited (429)`); a 2xx that is not a usable challenge, or a server key the proof cannotdiff --git a/src/core/push-notify.ts b/src/core/push-notify.tsindex b50a9d6dd..60595eda1 100644--- a/src/core/push-notify.ts+++ b/src/core/push-notify.ts@@ -220,7 +220,11 @@ async function postJson(// gets (`hostAuth`) to every host-mode post until it re-proves. Push never stops anything, so nothing// here is terminal: a batch that cannot be proven is DROPPED, exactly like a network error, because an// unproven send from a latched host is refused anyway. Only a challenge answered 404/405 means "this-// backend predates the proof" (relay-pop.ts), and only then does the post go out legacy.+// backend predates the proof" (relay-pop.ts), and only then does the post go out legacy — with ONE+// exception, push's own: a 200 challenge whose host-auth post answers 404 (see `establish`), cached for+// 10 minutes like the 404/405 verdict. One backend registers both routes or neither, so that answer+// comes only from a redeploy window; push stops nothing, and the backend gates the unproven post+// regardless (a latched host's is refused, which forgets the verdict — see postHostMode).// The server's session TTL is 15 min; re-prove on OUR clock, well inside it, so a skewed clock or a// long batch window never presents an expired session.diff --git a/src/core/relay/relay-pop.ts b/src/core/relay/relay-pop.tsindex 33858be8e..87d0a6139 100644--- a/src/core/relay/relay-pop.ts+++ b/src/core/relay/relay-pop.ts@@ -1,7 +1,10 @@// Proof that this process holds a relay host's X25519 secret key (hosted relay, R44 — see// docs/hosted-team-relay.md). The backend issues a challenge plus a one-off X25519 key; the proof is-// an HMAC keyed by the shared secret. The ONLY place a proof is computed. Its bytes are pinned by-// relay-pop-vector.json, which nodeterm-server carries too (test/fixtures/relay-pop-vector.json).+// an HMAC keyed by the shared secret. The ONLY place this proof (host-token mint, push host-auth) is+// computed. Its bytes are pinned by relay-pop-vector.json, which nodeterm-server carries too+// (test/fixtures/relay-pop-vector.json). The push webhook's management proof (core/push-webhook.ts+// `webhookProof`) is a separate protocol with its own challenge route and wire contract: never fold+// it into this one.import { createHmac } from 'node:crypto'import nacl from 'tweetnacl'@@ -52,8 +55,9 @@ export type ChallengeResult =| { ok: false; unsupported: false; status?: number }/** Only 404/405 means "this backend predates PoP" — the one case a caller may send an unproven- * request. Every other failure is transient and must go to the caller's backoff: an unproven- * request from a LATCHED host is refused (403) and would stop hosting. */+ * request (push adds one more: a host-auth 404 after a 200 challenge, see push-notify.ts). Every+ * other failure is transient and must go to the caller's backoff: an unproven request from a+ * LATCHED host is refused (403) and would stop hosting. */export async function fetchPopChallenge(d: {apiBase: stringhostPublicKeyB64: string