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

@@ -11,16 +11,38 @@ import {
const HOST_SECRET = randomBytes(32)
const SESSION_ID = 'sess-1'
const ALG = 'aes-256-gcm' as const
const EPOCH = 'gen-1' // FIX 3b / F6: the sealer generation these fixtures seal + declare under.
/** Seal a screen (as a P2 agent stub would) under K_content with sealReplayFrame. */
function sealedReplay(lines: readonly string[], secret = HOST_SECRET): ReplaySource {
const k = deriveContentKey({ hostContentSecret: secret, sessionId: SESSION_ID, alg: ALG })
interface SealOpts {
readonly secret?: Uint8Array
/** Epoch the FRAMES are actually sealed under (the key that encrypts). */
readonly sealEpoch?: string
/** Epoch the ReplaySource DECLARES (the key the browser will re-derive). Defaults to sealEpoch. */
readonly declaredEpoch?: string
}
/**
* Seal a screen (as a P2 agent stub would) under K_content with sealReplayFrame. Recoverability
* holds because the frames are sealed with the SAME (secret, sessionId, alg, epoch) the returned
* ReplaySource declares. For the F6 regression, `sealEpoch` and `declaredEpoch` are set apart so the
* browser derives a different key than the frames were sealed under.
*/
function sealedReplay(lines: readonly string[], opts: SealOpts = {}): ReplaySource {
const secret = opts.secret ?? HOST_SECRET
const sealEpoch = opts.sealEpoch ?? EPOCH
const declaredEpoch = opts.declaredEpoch ?? sealEpoch
const k = deriveContentKey({
hostContentSecret: secret,
sessionId: SESSION_ID,
alg: ALG,
epoch: sealEpoch,
})
const frames = lines.map((line, i) =>
// sealReplayFrame → E2EEnvelope, encoded to a DATA payload the browser opens.
// openReplayCiphertext decodes+opens; we mirror the encode via the session envelope codec.
encodeReplayFrame(sealReplayFrame(k, BigInt(i), new TextEncoder().encode(line))),
)
return { sessionId: SESSION_ID, alg: ALG, frames }
return { sessionId: SESSION_ID, alg: ALG, epoch: declaredEpoch, frames }
}
// The replay codec: relay-e2e's openReplayCiphertext expects the encoded envelope bytes.
@@ -67,6 +89,35 @@ describe('mountPreviewClient (T9)', () => {
expect(term.written).toEqual([]) // never wrote a torn screen
})
it('F6: a ReplaySource epoch that does NOT match the sealed generation → "unavailable", never a torn screen', async () => {
const card = document.createElement('div')
const term = mockTerminal()
// Frames sealed under generation "gen-1", but the ReplaySource declares a DIFFERENT epoch
// ("gen-2") — as if the ring buffer were mislabeled with the wrong generation. The browser
// re-derives a different K_content → AEAD tag fails → unavailable (no garbled render).
const replay = sealedReplay(['stale-screen'], { sealEpoch: 'gen-1', declaredEpoch: 'gen-2' })
const client = mountPreviewClient(card, replay, HOST_SECRET, { cols: 80, rows: 24 }, {
...realDeps,
createTerminal: () => term,
})
await client.render()
expect(card.querySelector('.preview-unavailable')?.textContent).toBe('unavailable')
expect(term.written).toEqual([]) // never wrote a torn screen from the wrong generation
})
it('F6: a matching per-generation epoch preserves recoverability (frames render)', async () => {
const card = document.createElement('div')
const term = mockTerminal()
// sealEpoch === declaredEpoch (both "gen-7") ⇒ same key within one generation ⇒ replay recovers.
const replay = sealedReplay(['line-A', 'line-B'], { sealEpoch: 'gen-7', declaredEpoch: 'gen-7' })
const client = mountPreviewClient(card, replay, HOST_SECRET, { cols: 80, rows: 24 }, {
...realDeps,
createTerminal: () => term,
})
await client.render()
expect(term.written).toEqual(['line-A', 'line-B'])
})
it('read-only: the preview terminal exposes NO input path (no onData/send)', async () => {
const card = document.createElement('div')
const term = mockTerminal()