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

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

View File

@@ -16,11 +16,23 @@ import { createApiClient } from '../api-client'
import { mountPreviewGrid } from '../preview-grid'
import type { ReplaySource } from '../preview-client'
/**
* FIX 3b / F6 placeholder epoch. The real per-generation `epoch` MUST be served by P1/P2 alongside
* the ciphertext ring buffer (the agent stamps a fresh epoch each time it reconstructs the sealer and
* resets seq to 0). This constant only keeps the `ReplaySource` shape explicit until those endpoints
* land; the stub still throws, so no frame is ever decrypted under it.
*/
const PLACEHOLDER_EPOCH = 'PENDING_P1_P2_EPOCH'
async function loadReplay(
_hostId: string,
): Promise<{ replay: ReplaySource; hostContentSecret: Uint8Array }> {
// TODO(P5/P1): fetch ciphertext replay + hostContentSecret (post auth/step-up). Not yet available.
throw new Error('replay source not yet wired (pending P5/P1 endpoints)')
// TODO(P5/P1/P2): fetch ciphertext replay + hostContentSecret (post auth/step-up) AND the real
// per-generation `epoch` (FIX 3b / F6) that the frames were sealed under. Until then the shape is:
// { replay: { sessionId, alg, epoch: PLACEHOLDER_EPOCH, frames }, hostContentSecret }
// Not yet available → throw so a card shows "unavailable" rather than a fabricated screen.
void PLACEHOLDER_EPOCH
throw new Error('replay source not yet wired (pending P5/P1/P2 endpoints)')
}
function boot(): void {

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()