Require v2 signatures on state-changing endpoints, each proof once (#1700, piece 7)

[michielbdejong]

Piece 7 of #1700: answer 7, plus piece 6's endpoint list. State-changing endpoints now require a v2 request signature, and each signature is accepted once.

Second of three stacked PRs:

1. Refuse wasip2 class extenders at the integration proxy, and say why (#1700, piece 5) #1831: piece 5;
2. this one: stacked on Refuse wasip2 class extenders at the integration proxy, and say why (#1700, piece 5) #1831;
3. piece 8: stacked on this one.

Endpoints that now require v2

This applies to POST and DELETE on the routes below. v1 signatures, bearer tokens and session cookies get a 401 that explains why.

• /app-agent, /app-write, /plugin-view-token, /plugin-secret
• /plugin-run, /plugin-schedule, /plugin-resume, /plugin-auto-apply, /plugin-trigger
• /plugin-release, /plugin-release-package, /plugin-release-pin
• /plugin-sync-{preview,apply,schedule,status}, /plugin-connection-{state,checkpoint}, /plugin-external-{read,status,confirm,apply}
• all 13 /integration-action* routes: /integration-actions, plus -approve, -call, -cancel, -consumer-abandon, -consumers, -grant, -grants, -history, -history-compact, -proposals, -recovery-confirm, -recovery-inspect
• /bind-drive, /forget-peer, /iroh-sync
• /website-hosting/assets/{hash}, /website-hosting/deployments, /website-hosting/activate

GET on these paths still accepts v1.

I checked this list against the current tree. Not changed:

• /commit and PUT /blob, which Plugins phase 2 (atomic-plugins#54): installation identities, host-signed proxy calls, connection requests #1700 puts out of scope;
• /upload and POST on any other resource. /upload is multipart, so a browser can't hash the exact bytes it sends without building the multipart body by hand. POST on a resource is the general endpoint API, used by invites, endpoints and third-party clients, so requiring v2 there breaks things outside this repo and should be its own change. Both still refuse v2, as before.

How it works

• require_v2 middleware (server/src/require_v2.rs) is wrapped on each route above. It reads the raw body before the handler runs, checks the signature over the method, the full URL and exactly those bytes, then passes the same bytes on to the handler. So handlers keep their web::Json extractors, and the hash always matches what gets parsed. That covers Plugins phase 2 (atomic-plugins#54): installation identities, host-signed proxy calls, connection requests #1700's "read the raw body first" prerequisite in one place. A body with Content-Encoding is refused. The verified agent goes into the request extensions, and helpers::get_client_agent_of and get_client_agent_for_request return it from there. Refusals come back as responses, not errors, so CORS headers still apply.

• Replay cache design (server/src/replay_cache.rs):

  • One cache per node, in memory, in AppState.
  • Keyed on the SHA-256 of the decoded signature bytes. v2 uses strict Ed25519, so a signature can't be re-encoded into a second valid one.
  • Each entry is kept until timestamp + AUTH_MAX_AGE_MS, the last moment the proof counts as fresh. Entries are pruned in expiry order from a BTreeSet.
  • Bounded at 100,000 entries. When it's full of live entries it refuses new proofs with 429 rather than evicting one, since an evicted proof could be replayed.
  • A replayed proof gets 401 "already used".
  • A restart forgets the cache, which reopens at most one 5-minute window.
  • Ed25519 is deterministic, so two identical requests signed in the same millisecond get the same signature, and the second one is refused. The docs say to sign every request anew.

• Browser: @tomic/lib gets signedRequestInit(url, agent, { method, body, headers }). Every caller of these routes in @tomic/lib and the data browser now signs its writes with it:

  • plugin-connection, integration-actions, plugin-server, plugin-install (release package);
  • app agent, app write, view token;
  • plugin schedule, secrets, trigger, event automation;
  • website hosting and assets;
  • forget-peer and iroh-sync.

  Reads still sign with v1.

• Docs: docs/src/authentication.md lists the endpoints and explains the replay rule.

Tests

• replay_cache unit tests: a replay is refused; a proof is refused through its last fresh millisecond and forgotten after; a proof signed ahead of the server clock; a full cache refuses rather than evicting.
• app_endpoints_test::state_changing_routes_refuse_v1_and_cookies_and_accept_v2: sends every route above (including the DELETEs) a v1 signature, a cookie and a v2 signature through the real router and middleware. v1 and the cookie get 401 with the reason. v2 gets past authentication.
• a_replayed_v2_request_is_refused: a captured request is replayed byte for byte. reads_on_v2_routes_still_accept_v1: GET still works with v1.
• Tests moved to v2: existing ones in app_endpoints_test, website, and server/tests/it/iroh_pairing.rs, which runs two real servers.
• vitest: signedRequestInit (the signature verifies over exactly the body sent), plus every touched caller's test.

Commands run:

• cargo test -p atomic-server --lib (294 passing on this branch)
• clippy -D warnings, and the pre-commit workspace clippy
• cargo test -p atomic-server --test it iroh_pairing
• the full browser/lib vitest suite
• data-browser vitest for the touched files
• pnpm run lint
• typecheck for lib and data-browser

This base has no plugin-routes feature and no plugin_proxy test in it.

Not in this PR: the atomic-plugins repo, if anything there calls these routes directly (for example publishing to /plugin-release-package from a CLI). It needs the same switch to v2.

🤖 Generated with Claude Code

[michielbdejong]

Merge-risk triage (2026-09-28). This is a read-only review of this PR's own diff. The rule it applies: nothing that works today may break for existing users or clients, and new behaviour is added alongside the old. The stack is being rebased onto develop as one chain before merging, so line references are against the current stacked base.

Verdict: SAFE-WITH-FIX (in addition to the planned v1 acceptance and replay-after-authz fixes)

Requiring v2 on state-changing endpoints is fine once v1 stays accepted.

Fix before merging: (1) This PR edits existing tests (server/tests/it/iroh_pairing.rs, app_endpoints_test.rs); restore the originals so they prove v1 still passes. (2) The clients (managedServer.ts, pairing.ts, plugin-server.ts, hostingClient.ts → signedRequestInit) now always sign v2 on these endpoints. v0.40.4 has no v2 verification, so a new web app or @tomic/lib against an older server (or atomic-saas, if it verifies these routes itself, e.g. /forget-peer) gets a 401. Keep sending v1 unless the server advertises v2, or ship client and server strictly together. (3) Note: require_v2 buffers every POST body up to PAYLOAD_MAX before auth, which matters for plugin-release and website asset uploads.

🤖 Generated with Claude Code

[michielbdejong]

Hand-off: plugin stack rebase onto develop (in progress)

Goal agreed by Michiel and Joep (2026-09-28): keep building plugin features, but nothing that exists today may break. New behaviour is added alongside the old; for example v2 signatures are accepted, and v1 is not deprecated.

Where the work is: branch claude/plugin-stack-chain, built on develop 2e509a925. It is one linear chain in which every stack PR's own commits are cherry-picked in order. No PR branch has been force-pushed yet, and the old heads are still in claude/atomic-plugins-pin.

• The plan, checklist and triage findings are in planning/plugin-stack-rebase.md on that branch.
• The per-PR commit positions are in planning/plugin-stack-rebase/positions.txt.
• The last commit on the branch is only these notes. Drop it before pushing PR branches.

Done in the chain, from #1786 through #1832:

• Commits that were already in develop were dropped: 3f4add07a, d3fa5fed2, 72fde507e, 9788dbb41 and fb53a665a. Let a second publisher of the same plugin release install it (port of #1654) #1755 and Fix [i18n-404] in the Installation Release section #1786 are fully in develop, so both can be closed.
• Every PR that touches Rust passed cargo check -p atomic-server -p atomic_lib --tests.
• Require v2 signatures on state-changing endpoints, each proof once (#1700, piece 7) #1832 (this PR) is now additive on the server:
  • require_v2 only checks requests that send x-atomic-signature-version: 2. v1, bearer tokens and cookies pass through to the handlers as before.
  • When the replay cache is full it evicts the entry closest to expiry instead of answering 429. Anyone could fill it, so the old behaviour let them lock every client out.
  • Tests now assert that v1 and cookies still pass: app_endpoints_test, replay_cache and require_v2, 18 passed.
• Keep an app's removal removed in the page; quiet benign rights-walk warnings #1705 is cut down to its tests plus the rights-walk log level change. Develop's Batch: app key fail-closed, replacing Loro import, tombstone test teardown #1853/Keep what a replacing snapshot never had #1857 superseded its resource.ts fix.
• Plugin routes: typed refusal on Installation commits, requires for uncached releases #1769: HOST_FEATURE_UNAVAILABLE moves to error code 12, because develop uses 11 for CAUSALITY_CONFLICT.
• Let a drive app run and apply its own importer #1774: importFile.ts now uses the lib's acceptFor and readUpload, so base64 importers also work from app frames (Plugins: accept a file as base64 (#1727) #1730).
• Say which integration proxy carries a connection's traffic #1724's traffic notice now also appears in InstallationConnections, which resolves Installation page: connect proxy platforms, and no proxy calls without one (#1700) #1733's TODO.

Next:

1. Pick Fail closed on installation identities too; merges #1644 (#1700, piece 8) #1833, only 4df695145.
2. Add App frames: openExternal(url) and openResource(subject) #1744's 1545cab1a (openResource asks before leaving the app). It currently lives only on origin/claude/frame-open-external.
3. Apply the triage fixes listed in the planning doc, each folded into its own PR's commit. The triage is posted as a comment on each stack PR.
4. Finish Require v2 signatures on state-changing endpoints, each proof once (#1700, piece 7) #1832 on the client side: calls that may reach a node of another version keep sending v1. That covers pairing, managedServer, hosting, forget-peer, iroh-sync and bind-drive. Also restore tests/it/iroh_pairing.rs to v1.
5. Run pnpm clean-translations, lint, tsc, vitest and e2e light on the chain. The JS side has not been checked yet, and the .po merges only appended entries.
6. Handle Make fresh worktrees build with two commands #1830, Demo-session tooling for live user-testing sessions #1834, Integrations soft launch: no error without a server, a new-feature note, experimental toggle behind a facilitator unlock #1835 and Find already-fetched external classes in New Table's class picker #1842 on their own, rebased directly onto develop.
7. Force-push each PR branch to its chain position and retarget it to the previous PR's branch. TrekMeester picks them up after that.

Watch out: the disk on the old machine filled up during the Rust test link step. Build with CARGO_INCREMENTAL=0.

🤖 Generated with Claude Code

[michielbdejong]

Closing as part of the plugin-host stack cleanup (Q-101): not needed by atomic-plugins now. See the inventory at #1726 (comment). The branch is kept, and pin candidates are unaffected. Closed by Claude (VPS coordinator) on behalf of Michiel.