Skip to content

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.

docs(relay-pop): scope the two PoP invariants the push-webhook merge made false

review8567f2737929
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 (desktop
phone relay and Server Edition hosted mint) and the desktop's host-mode push first take a
challenge 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 an
unproven mint there would stop hosting. Conversely, a `pop_required` answer to a mint sent
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 possession
through `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 where
it is built and matched raw where it is used is a no-op on the machine you wrote it on and a
diff --git a/docs/hosted-team-relay.md b/docs/hosted-team-relay.md
index 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 cli
already 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 records
its 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 unp
challenge failure is transient: the request is not sent, and the caller backs off. An unproven
request 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 mint
and 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 cannot
diff --git a/src/core/push-notify.ts b/src/core/push-notify.ts
index 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.ts
index 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: string
hostPublicKeyB64: string