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.

agent/src/e2e/replaySeal.ts

@@ -13,7 +13,19 @@
  * the frozen relay-contracts signatures — production wiring passes the relay-e2e impls verbatim.
  * `hostContentSecret` comes from Keystore.loadContentSecret() (T3); NEVER the ephemeral key,
  * NEVER logged, NEVER sent to the relay (INV2/INV9).
+ *
+ * PER-GENERATION EPOCH (F6 fix): K_content = HKDF(hostContentSecret, salt=sessionId, info=const) is
+ * byte-identical for a given (host, sessionId) and RECOVERABLE by design — but the deterministic seal
+ * nonce is seq, which resets to 0 on every sealer reconstruction (restart / re-attach). Two sealer
+ * GENERATIONS would therefore seal DISTINCT plaintext under the SAME (key, nonce) → catastrophic AEAD
+ * reuse. Each `createReplaySealer` call mints a FRESH, NON-SECRET `epoch` (randomUUID) that is folded
+ * into K_content derivation, so a restart / new generation yields a FRESH key even for the same
+ * (hostContentSecret, sessionId); seq=0 can never collide across generations. The epoch is exposed on
+ * the sealer so the wiring can persist it with the ring buffer / replay stream and serve it to the
+ * browser, which re-derives the matching key. Recoverability WITHIN one generation (same epoch ⇒ same
+ * key) is preserved.
  */
+import { randomUUID } from 'node:crypto'
 import type { AeadAlg, AeadKey, E2EEnvelope, ReplayKeyParams } from 'relay-contracts'
 
 /** The two §4.4 replay primitives, typed to the frozen relay-contracts signatures (P4 impls). */
@@ -23,13 +35,20 @@ export interface ReplayCrypto {
 }
 
 export interface ReplaySealer {
+  /**
+   * The fresh, NON-SECRET per-generation epoch folded into K_content (F6). The wiring persists it
+   * with the ring buffer / replay stream so the browser re-derives the matching key.
+   */
+  readonly epoch: string
   /** K_content seal with monotonic seq per session (INV13); NOT the live h2c frame. */
   seal(plaintext: Uint8Array): E2EEnvelope
 }
 
 /**
- * Build a per-(host, session) replay sealer. K_content is derived ONCE from
- * { hostContentSecret, sessionId, alg }; seq is strictly monotonic from 0 (INV13).
+ * Build a per-(host, session) replay sealer for ONE generation. A FRESH `epoch` is minted per call
+ * and folded into K_content, which is derived ONCE from { hostContentSecret, sessionId, alg, epoch };
+ * seq is strictly monotonic from 0 (INV13). A restart / re-attach constructs a NEW generation with a
+ * NEW epoch ⇒ a FRESH key, so seq=0 never collides across generations (F6).
  */
 export function createReplaySealer(
   hostContentSecret: Uint8Array,
@@ -37,9 +56,11 @@ export function createReplaySealer(
   alg: AeadAlg,
   crypto: ReplayCrypto,
 ): ReplaySealer {
-  const key = crypto.deriveContentKey({ hostContentSecret, sessionId, alg })
+  const epoch = randomUUID()
+  const key = crypto.deriveContentKey({ hostContentSecret, sessionId, alg, epoch })
   let seq = 0n
   return {
+    epoch,
     seal(plaintext: Uint8Array): E2EEnvelope {
       const env = crypto.sealReplayFrame(key, seq, plaintext)
       seq += 1n

agent/test/hostEndpoint.test.ts

@@ -107,6 +107,7 @@ describe('createE2ETransform (T15)', () => {
   function fakeReplay(): ReplaySealer & { calls: number } {
     const r = {
       calls: 0,
+      epoch: 'test-epoch',
       seal(_pt: Uint8Array) {
         r.calls += 1
         return { seq: 0n, nonce: new Uint8Array(), ciphertext: new Uint8Array([0xde]), tag: new Uint8Array() }

agent/test/replaySeal.test.ts

@@ -2,14 +2,24 @@ import { describe, expect, it, vi } from 'vitest'
 import type { AeadKey, E2EEnvelope, ReplayKeyParams } from 'relay-contracts'
 import { createReplaySealer, type ReplayCrypto } from '../src/e2e/replaySeal.js'
 
-/** Fake AEAD: key = tagged secret‖sessionId; ciphertext = plaintext XOR keyByte (marker hidden). */
-function fakeCrypto(): ReplayCrypto & { derivations: ReplayKeyParams[] } {
+/**
+ * Fake AEAD. The derived key is a tag that DEPENDS on every ReplayKeyParams field — crucially on
+ * `epoch` (F6), so two sealer generations for the same (secret, sessionId, alg) yield DIFFERENT keys.
+ * The tag leads with `epoch` so key[0] also varies per generation; ciphertext = plaintext XOR key[0]
+ * (a UUID's first char is a hex digit 0x30–0x66 → always nonzero, so the marker is always hidden).
+ */
+function fakeCrypto(): ReplayCrypto & { derivations: ReplayKeyParams[]; keys: Uint8Array[] } {
   const derivations: ReplayKeyParams[] = []
+  const keys: Uint8Array[] = []
   return {
     derivations,
+    keys,
     deriveContentKey(params: ReplayKeyParams): AeadKey {
       derivations.push(params)
-      const tag = new TextEncoder().encode(`${Buffer.from(params.hostContentSecret).toString('hex')}:${params.sessionId}`)
+      const tag = new TextEncoder().encode(
+        `${params.epoch}:${Buffer.from(params.hostContentSecret).toString('hex')}:${params.sessionId}:${params.alg}`,
+      )
+      keys.push(tag)
       return tag as unknown as AeadKey
     },
     sealReplayFrame(key: AeadKey, seq: bigint, plaintext: Uint8Array): E2EEnvelope {
@@ -23,12 +33,26 @@ function fakeCrypto(): ReplayCrypto & { derivations: ReplayKeyParams[] } {
 const SECRET = new Uint8Array([1, 2, 3, 4])
 
 describe('createReplaySealer (T19, FIX 3)', () => {
-  it('derives K_content deterministically from (secret, sessionId, alg)', () => {
-    const c1 = fakeCrypto()
-    createReplaySealer(SECRET, 'sess-1', 'aes-256-gcm', c1)
-    const c2 = fakeCrypto()
-    createReplaySealer(SECRET, 'sess-1', 'aes-256-gcm', c2)
-    expect(c1.derivations[0]).toEqual(c2.derivations[0])
+  it('folds the exposed per-generation epoch into K_content, deriving it exactly once', () => {
+    const c = fakeCrypto()
+    const sealer = createReplaySealer(SECRET, 'sess-1', 'aes-256-gcm', c)
+    expect(c.derivations).toHaveLength(1)
+    expect(c.derivations[0]!.epoch).toBe(sealer.epoch)
+    expect(sealer.epoch).toMatch(/^[0-9a-f-]{36}$/) // randomUUID shape
+  })
+
+  it('recoverable WITHIN one generation: re-deriving with the exposed epoch yields the same key', () => {
+    const c = fakeCrypto()
+    const sealer = createReplaySealer(SECRET, 'sess-1', 'aes-256-gcm', c)
+    // The browser re-derives from the SAME (secret, sessionId, alg, epoch) carried with the ring buffer.
+    const browser = fakeCrypto()
+    const browserKey = browser.deriveContentKey({
+      hostContentSecret: SECRET,
+      sessionId: 'sess-1',
+      alg: 'aes-256-gcm',
+      epoch: sealer.epoch,
+    }) as unknown as Uint8Array
+    expect(Buffer.from(browserKey).equals(Buffer.from(c.keys[0]!))).toBe(true)
   })
 
   it('a different sessionId → a different key (per-session separation)', () => {
@@ -38,6 +62,23 @@ describe('createReplaySealer (T19, FIX 3)', () => {
     expect(c.derivations[0]!.sessionId).not.toBe(c.derivations[1]!.sessionId)
   })
 
+  it('F6 regression: two generations for the SAME (secret, sessionId, alg) get DIFFERENT epochs → DIFFERENT keys, so seq=0 never collides', () => {
+    const c = fakeCrypto()
+    const gen1 = createReplaySealer(SECRET, 'sess-1', 'aes-256-gcm', c)
+    const gen2 = createReplaySealer(SECRET, 'sess-1', 'aes-256-gcm', c)
+    // Fresh epoch per generation…
+    expect(gen2.epoch).not.toBe(gen1.epoch)
+    // …therefore distinct K_content even though (secret, sessionId, alg) are identical…
+    expect(Buffer.from(c.keys[1]!).equals(Buffer.from(c.keys[0]!))).toBe(false)
+    // …so the seq=0 seal of generation 2 uses a DIFFERENT key than the seq=0 seal of generation 1
+    // (this is exactly the (key, nonce) reuse F6 prevents — same nonce, but a fresh key).
+    const s1 = gen1.seal(new Uint8Array([0x41, 0x42, 0x43]))
+    const s2 = gen2.seal(new Uint8Array([0x41, 0x42, 0x43]))
+    expect(s1.seq).toBe(0n)
+    expect(s2.seq).toBe(0n)
+    expect(s1.nonce).toEqual(s2.nonce) // same deterministic nonce (seq=0)…
+  })
+
   it('emits a monotonic seq (INV13) and never leaks the plaintext marker (INV2)', () => {
     const sealer = createReplaySealer(SECRET, 'sess-1', 'aes-256-gcm', fakeCrypto())
     const marker = new TextEncoder().encode('SECRET-MARKER')
@@ -50,7 +91,7 @@ describe('createReplaySealer (T19, FIX 3)', () => {
 
   it('replay seal is DISTINCT from a live h2c seal for the same plaintext (FIX 3)', () => {
     const replay = createReplaySealer(SECRET, 'sess-1', 'aes-256-gcm', fakeCrypto())
-    // model a live seal with a different key byte
+    // model a live seal with a different key byte (0x11 is below the 0x30–0x66 hex-digit epoch prefix)
     const liveKey = new Uint8Array([0x11]) as unknown as AeadKey
     const live = fakeCrypto().sealReplayFrame(liveKey, 0n, new Uint8Array([0x41, 0x42]))
     const rep = replay.seal(new Uint8Array([0x41, 0x42]))