kai/web-terminal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(relay): close F6 replay K_content nonce reuse via per-generation epoch-in-key

Browse Source 
The recoverable replay key was stable per (hostContentSecret, sessionId) while the
agent-side sealer resets its deterministic-nonce seq to 0 on every restart/re-attach
→ two sealer generations sealed distinct plaintext under the SAME (key, nonce).

Add a required 'epoch' to ReplayKeyParams, fold it into the K_content HKDF salt
(sessionId U+001F epoch), mint a fresh epoch per createReplaySealer generation and
expose it, and thread it through ReplaySource so the browser re-derives the matching
key. Fresh epoch per generation ⇒ fresh key ⇒ seq=0 can never collide; recoverability
within a generation is preserved.

Touches relay-contracts/relay-e2e/agent/relay-web. Green: contracts 81, e2e 78,
agent 133, web 99; tsc clean. Regression proves same seq-0 nonce, different key.
This commit is contained in:
Yaojia Wang
2026-07-02 16:41:19 +02:00
parent a09c131539
commit 3020184054
13 changed files with 243 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
relay-web/src/preview-client.ts
View File

@@ -6,10 +6,11 @@
* Ring-buffer replay survives a reload because the agent (P2) sealed each stored frame with
* `sealReplayFrame` under the RECOVERABLE content key `K_content` — NOT the ephemeral live
* `DirectionalKeys` (which are re-derived per handshake and lost on reload). The browser re-derives
* the SAME `K_content` via `deriveContentKey({ hostContentSecret, sessionId, alg })` (§4.4 FIX 3;
* the SAME `K_content` via `deriveContentKey({ hostContentSecret, sessionId, alg, epoch })` (§4.4 FIX 3;
* `hostContentSecret` obtained via P5 after auth/step-up) and decrypts each payload with
* `openReplayCiphertext`. A wrong/ephemeral key throws (AEAD tag) → the card shows "unavailable",
* never a torn/garbled screen (cross-host/session isolation, INV1).
* `openReplayCiphertext`. A wrong/ephemeral key — or a `ReplaySource.epoch` that doesn't match the
* generation the frames were sealed under (FIX 3b / F6) — throws (AEAD tag) → the card shows
* "unavailable", never a torn/garbled screen (cross-host/session isolation, INV1).
*
* The §4.4 crypto (`deriveContentKey`/`openReplayCiphertext`) is imported from `relay-e2e` and
* injected — cited verbatim, never re-implemented. `hostContentSecret`/`K_content` are transient in
@@ -17,10 +18,17 @@
*/
import type { AeadAlg, AeadKey, ReplayKeyParams } from 'relay-contracts'
/** Ciphertext ring-buffer replay for one host/session. */
/** Ciphertext ring-buffer replay for one host/session (one sealer generation). */
export interface ReplaySource {
readonly sessionId: string
readonly alg: AeadAlg // negotiated aead (matches how P2 sealed the replay)
// FIX 3b / F6: the per-generation `epoch` under which THESE frames were sealed. The agent resets
// its deterministic-nonce seq to 0 on every reconstruction (restart/re-attach); folding a fresh
// epoch into K_content gives each generation a fresh key, so a seq=0 reset can never collide with
// a prior generation's (key, nonce). NON-SECRET — carried with the ring buffer so the browser
// re-derives the matching key. Frames from a DIFFERENT epoch derive a different key → AEAD tag
// fails → "unavailable" (never a torn screen).
readonly epoch: string
readonly frames: readonly Uint8Array[] // stored DATA payloads, each a sealReplayFrame envelope
}
@@ -85,6 +93,7 @@ export function mountPreviewClient(
hostContentSecret,
sessionId: replay.sessionId,
alg: replay.alg,
epoch: replay.epoch, // F6: bind the key to THIS generation; a mismatched epoch → wrong key.
})
} catch {
showUnavailable()