@7h3/protocol 0.4.0 → 0.5.0

package/src/replayStores.ts

@@ -1,6 +1,137 @@
 import type { DistributedReplayStore } from './protocolReplay'
 import { InMemoryRedisLikeClient, type RedisLikeClient } from './redisClient'
 
+// ---------------------------------------------------------------------------
+// ReplayStore — high-level check() interface (returns true = REPLAY)
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal Redis client surface required by RedisReplayStore.
+ *
+ * Distinct from the internal RedisLikeClient: this interface uses a `quit()`
+ * lifecycle method and does not require pipeline support, making it easy to
+ * adapt any Redis client (ioredis, node-redis, Upstash, etc.) without coupling
+ * to the internal pipeline abstraction.
+ */
+export interface RedisClientLike {
+  set(key: string, value: string, opts?: { nx?: boolean; px?: number }): Promise<string | null>
+  get(key: string): Promise<string | null>
+  del(key: string): Promise<number | any>
+  quit(): Promise<any>
+}
+
+/**
+ * Gateway-facing replay store interface.
+ *
+ * `check()` atomically marks a key as seen and returns whether it was already
+ * present: `false` = fresh (first time seen), `true` = replay (already seen).
+ */
+export interface ReplayStore {
+  check(key: string, ttlMs: number): Promise<boolean>
+}
+
+/**
+ * Redis-backed implementation of {@link ReplayStore}.
+ *
+ * Uses SET … NX PX for an atomic "set if not exists with TTL" operation.
+ * The operation is single-round-trip and safe under concurrent access from
+ * multiple gateway instances.
+ */
+export class RedisReplayStore implements ReplayStore {
+  private readonly keyPrefix: string
+  private readonly client: RedisClientLike
+
+  constructor(opts: { redisUrl?: string; keyPrefix?: string; client?: RedisClientLike } = {}) {
+    this.keyPrefix = opts.keyPrefix ?? '7h3:nonce:'
+    if (opts.client) {
+      this.client = opts.client
+    } else {
+      // Lazily adapt InMemoryRedisLikeClient to RedisClientLike for zero-dep default
+      const inner = new InMemoryRedisLikeClient()
+      this.client = {
+        set: (key, value, setOpts) =>
+          inner.set(key, value, { nx: setOpts?.nx, pxMs: setOpts?.px }),
+        get: (key) => inner.get ? inner.get(key) : Promise.resolve(null),
+        del: (key) => inner.del ? inner.del(key) : Promise.resolve(0),
+        quit: () => Promise.resolve(),
+      }
+    }
+  }
+
+  /**
+   * Returns `false` if the key is fresh (first time seen — key was set in Redis),
+   * or `true` if the key is a replay (key already existed — SET NX returned null).
+   */
+  async check(key: string, ttlMs: number): Promise<boolean> {
+    const redisKey = `${this.keyPrefix}${key}`
+    const result = await this.client.set(redisKey, '1', { nx: true, px: Math.max(1, ttlMs) })
+    // SET NX returns 'OK' when the key was newly set (fresh), null when already present (replay)
+    return result === null
+  }
+}
+
+/**
+ * Cluster-aware replay store that wraps multiple {@link RedisReplayStore}
+ * instances — one per Redis shard / node.
+ *
+ * A message is treated as a replay if ANY node has already seen the nonce.
+ * All nodes are checked in parallel via Promise.all.
+ */
+export class ClusterRedisReplayStore implements ReplayStore {
+  private readonly nodes: RedisReplayStore[]
+
+  constructor(nodes: RedisReplayStore[]) {
+    this.nodes = nodes
+  }
+
+  async check(key: string, ttlMs: number): Promise<boolean> {
+    const results = await Promise.all(this.nodes.map((node) => node.check(key, ttlMs)))
+    // If any node reports replay (true), the request is a replay
+    return results.some((seen) => seen)
+  }
+}
+
+/**
+ * Convenience factory that creates a {@link RedisReplayStore} from a URL
+ * or options object.
+ */
+export function createRedisReplayStore(
+  clientOrOpts: RedisLikeClient | { redisUrl?: string; keyPrefix?: string; client?: RedisClientLike },
+  options?: RedisReplayStoreOptions,
+): DistributedReplayStore
+
+export function createRedisReplayStore(
+  clientOrOpts: RedisLikeClient | { redisUrl?: string; keyPrefix?: string; client?: RedisClientLike },
+  options: RedisReplayStoreOptions = {},
+): DistributedReplayStore | RedisReplayStore {
+  // Detect old (client-first) vs new (opts-object) call style
+  if (isRedisLikeClient(clientOrOpts)) {
+    return _createDistributedReplayStore(clientOrOpts, options)
+  }
+  // New style: return a RedisReplayStore instance
+  return new RedisReplayStore(clientOrOpts as { redisUrl?: string; keyPrefix?: string; client?: RedisClientLike })
+}
+
+function isRedisLikeClient(val: unknown): val is RedisLikeClient {
+  return (
+    val !== null &&
+    typeof val === 'object' &&
+    typeof (val as any).set === 'function' &&
+    // RedisLikeClient does NOT have a `quit` method — RedisClientLike does
+    // Pipeline presence distinguishes internal RedisLikeClient
+    (typeof (val as any).pipeline === 'function' || !('quit' in val))
+  )
+}
+
+/**
+ * Creates a {@link ClusterRedisReplayStore} from an array of Redis URLs.
+ * Each URL is used to create an independent {@link RedisReplayStore} node.
+ */
+export function createClusterReplayStore(redisUrls: string[]): ClusterRedisReplayStore {
+  const nodes = redisUrls.map((url) => new RedisReplayStore({ redisUrl: url }))
+  return new ClusterRedisReplayStore(nodes)
+}
+
 /**
  * What to do when the Redis client throws (network blip, server down).
  *
@@ -24,12 +155,14 @@ export interface RedisReplayStoreOptions {
 }
 
 /**
- * Creates a {@link DistributedReplayStore} backed by Redis-style `SET NX PX`.
+ * Internal factory — creates a {@link DistributedReplayStore} backed by
+ * Redis-style `SET NX PX`. Used by the overloaded `createRedisReplayStore`
+ * when a `RedisLikeClient` is passed as the first argument.
  *
  * Drop the returned store into `new DistributedReplayCache(store)` (or pass a
  * `DistributedReplayCache` as the transport `replayCache`).
  */
-export function createRedisReplayStore(
+function _createDistributedReplayStore(
   client: RedisLikeClient,
   options: RedisReplayStoreOptions = {},
 ): DistributedReplayStore {
@@ -41,7 +174,7 @@ export function createRedisReplayStore(
     (errorBehavior === 'fallback'
       ? // The local fallback runs over a non-throwing in-memory client, so it
         // needs no fallback of its own — `reject` terminates the chain.
-        createRedisReplayStore(new InMemoryRedisLikeClient(), { keyPrefix, errorBehavior: 'reject' })
+        _createDistributedReplayStore(new InMemoryRedisLikeClient(), { keyPrefix, errorBehavior: 'reject' })
       : undefined)
 
   function degrade(error: unknown, key: string, expiresAtMs: number, nowMs: number): Promise<boolean> | boolean {

package/src/stream.test.ts

@@ -0,0 +1,254 @@
+import { describe, it, expect } from 'vitest'
+import {
+  SignedStreamWriter,
+  SignedStreamReader,
+  createSignedStream,
+  createStreamVerifier,
+  signStream,
+  verifyStream,
+  encodeStreamChunk,
+  decodeStreamChunk,
+  type StreamChunk,
+  type StreamSignerOpts,
+  type StreamVerifierOpts,
+} from './stream'
+import { generateEd25519KeypairBase64Url } from './protocol'
+
+// ─────────────────── helpers ───────────────────────────────────────────────────
+
+async function makeKeyPair() {
+  return generateEd25519KeypairBase64Url()
+}
+
+function signerOpts(privateKey: string, nonce?: string): StreamSignerOpts {
+  return { privateKey, sender: 'test-agent', nonce: nonce ?? 'fixed-nonce-for-tests', keyId: 'test-key' }
+}
+
+function verifierOpts(publicKey: string): StreamVerifierOpts {
+  return { publicKey }
+}
+
+// ─────────────────── tests ────────────────────────────────────────────────────
+
+describe('SignedStreamWriter + SignedStreamReader', () => {
+  it('test 1: 5-chunk round trip verifies', async () => {
+    const kp = await makeKeyPair()
+    const writer = new SignedStreamWriter(signerOpts(kp.privateKey))
+    const reader = new SignedStreamReader(verifierOpts(kp.publicKey))
+
+    const dataChunks = ['Hello ', 'World', ' from', ' 7h3', ' Protocol']
+    const frames: StreamChunk[] = []
+
+    for (const d of dataChunks) {
+      const frame = await writer.writeChunk(d)
+      expect(frame.f).toBe(false)
+      expect(frame.i).toBe(frames.length)
+      expect(typeof frame.h).toBe('string')
+      frames.push(frame)
+    }
+
+    // Feed non-final chunks to reader
+    for (const frame of frames) {
+      const res = await reader.receiveChunk(frame)
+      expect(res.ok).toBe(true)
+    }
+
+    const finalFrame = await writer.finalize()
+    expect(finalFrame.f).toBe(true)
+    expect(typeof finalFrame.sig).toBe('string')
+    expect(finalFrame.kid).toBe('test-key')
+
+    const result = await reader.finalize(finalFrame)
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.chunkCount).toBe(5)
+      // totalBytes = sum of UTF-8 bytes of each data chunk
+      const expected = dataChunks.reduce((s, d) => s + new TextEncoder().encode(d).length, 0)
+      expect(result.totalBytes).toBe(expected)
+    }
+  })
+
+  it('test 2: single chunk round trip', async () => {
+    const kp = await makeKeyPair()
+    const writer = new SignedStreamWriter(signerOpts(kp.privateKey))
+    const reader = new SignedStreamReader(verifierOpts(kp.publicKey))
+
+    const frame = await writer.writeChunk('only one chunk')
+    const res = await reader.receiveChunk(frame)
+    expect(res.ok).toBe(true)
+
+    const finalFrame = await writer.finalize()
+    const result = await reader.finalize(finalFrame)
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.chunkCount).toBe(1)
+    }
+  })
+
+  it('test 3: empty stream (just finalize) verifies', async () => {
+    const kp = await makeKeyPair()
+    const writer = new SignedStreamWriter(signerOpts(kp.privateKey))
+    const reader = new SignedStreamReader(verifierOpts(kp.publicKey))
+
+    const finalFrame = await writer.finalize()
+    expect(finalFrame.f).toBe(true)
+    expect(typeof finalFrame.sig).toBe('string')
+
+    const result = await reader.finalize(finalFrame)
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.chunkCount).toBe(0)
+      expect(result.totalBytes).toBe(0)
+    }
+  })
+
+  it('test 4: tampered chunk data detected (HMAC fails on that chunk, Ed25519 fails at finalize)', async () => {
+    const kp = await makeKeyPair()
+    const writer = new SignedStreamWriter(signerOpts(kp.privateKey))
+    const reader = new SignedStreamReader(verifierOpts(kp.publicKey))
+
+    const frame0 = await writer.writeChunk('legit data')
+    const frame1 = await writer.writeChunk('also legit')
+    const finalFrame = await writer.finalize()
+
+    // Tamper with frame0's data
+    const tampered: StreamChunk = { ...frame0, d: 'TAMPERED' }
+
+    // Reader accepts the chunk (sequence is fine; reader can't verify HMAC without private key)
+    await reader.receiveChunk(tampered)
+    await reader.receiveChunk(frame1)
+
+    // But the final Ed25519 signature will fail because the content hash is different
+    const result = await reader.finalize(finalFrame)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toMatch(/signature verification failed/i)
+    }
+  })
+
+  it('test 5: wrong public key: final Ed25519 fails', async () => {
+    const kp = await makeKeyPair()
+    const wrongKp = await makeKeyPair()
+
+    const writer = new SignedStreamWriter(signerOpts(kp.privateKey))
+    // Reader uses a DIFFERENT public key
+    const reader = new SignedStreamReader(verifierOpts(wrongKp.publicKey))
+
+    const frame = await writer.writeChunk('data')
+    await reader.receiveChunk(frame)
+
+    const finalFrame = await writer.finalize()
+    const result = await reader.finalize(finalFrame)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toMatch(/signature verification failed/i)
+    }
+  })
+
+  it('test 6: out-of-order chunk: sequence error', async () => {
+    const kp = await makeKeyPair()
+    const writer = new SignedStreamWriter(signerOpts(kp.privateKey))
+    const reader = new SignedStreamReader(verifierOpts(kp.publicKey))
+
+    const frame0 = await writer.writeChunk('first')
+    const frame1 = await writer.writeChunk('second')
+
+    // Feed frame1 before frame0 (out of order — frame1 has i=1, reader expects i=0)
+    const resOoo = await reader.receiveChunk(frame1)
+    expect(resOoo.ok).toBe(false)
+    if (!resOoo.ok) {
+      expect(resOoo.reason).toMatch(/sequence error/i)
+    }
+
+    // Feed in yet another out-of-order delivery: feed frame0, then frame1 again — frame1 will be seen
+    // as seq=1 but reader has only accepted 0 so far (via the successful frame0), so now inject a
+    // duplicate of frame1 which would be at seq=1 yet again — that should be fine.
+    // More importantly: verify that the FIRST out-of-order was caught.
+    // The reader did NOT increment on failure, so frame0 (i=0) is now OK.
+    const resAfter = await reader.receiveChunk(frame0)
+    expect(resAfter.ok).toBe(true)  // seq=0 is correct now (reader expected 0 after ooo failure)
+  })
+
+  it('test 7: signStream(array) + verifyStream round trip', async () => {
+    const kp = await makeKeyPair()
+    const data = ['chunk A', 'chunk B', 'chunk C']
+    const chunks = await signStream(data, signerOpts(kp.privateKey))
+
+    // signStream returns n+1 frames (n data + 1 final)
+    expect(chunks).toHaveLength(data.length + 1)
+    expect(chunks[chunks.length - 1].f).toBe(true)
+
+    const result = await verifyStream(chunks, verifierOpts(kp.publicKey))
+    expect(result.ok).toBe(true)
+  })
+
+  it('test 8: replay — same StreamChunk in a different stream fails (nonce in HMAC)', async () => {
+    const kp = await makeKeyPair()
+
+    // Stream A
+    const writerA = new SignedStreamWriter({ ...signerOpts(kp.privateKey), nonce: 'nonce-A' })
+    const chunkA0 = await writerA.writeChunk('data A')
+    const finalA = await writerA.finalize()
+
+    // Stream B — different nonce
+    const writerB = new SignedStreamWriter({ ...signerOpts(kp.privateKey), nonce: 'nonce-B' })
+    // Don't write any chunk to B, then produce its final frame
+    const finalB = await writerB.finalize()
+
+    // Reader for stream B expects B's content — inject A's chunk into B's reader
+    const readerB = new SignedStreamReader(verifierOpts(kp.publicKey))
+    // Feed chunk from stream A (which has content 'data A') and use B's finalFrame
+    await readerB.receiveChunk(chunkA0)
+    // finalB was computed over empty content — now we have chunkA0's data accumulated
+    const result = await readerB.finalize(finalB)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toMatch(/signature verification failed/i)
+    }
+
+    // Stream A itself verifies fine
+    const readerA = new SignedStreamReader(verifierOpts(kp.publicKey))
+    await readerA.receiveChunk(chunkA0)
+    const resultA = await readerA.finalize(finalA)
+    expect(resultA.ok).toBe(true)
+  })
+
+  it('test 9: large stream — 1000 chunks verify in <500ms', async () => {
+    const kp = await makeKeyPair()
+    const chunks: string[] = Array.from({ length: 1000 }, (_, i) => `token-${i}`)
+
+    const start = Date.now()
+    const frames = await signStream(chunks, signerOpts(kp.privateKey))
+    const result = await verifyStream(frames, verifierOpts(kp.publicKey))
+    const elapsed = Date.now() - start
+
+    expect(result.ok).toBe(true)
+    expect(elapsed).toBeLessThan(500)
+    if (result.ok) {
+      expect(result.chunkCount).toBe(1000)
+    }
+  })
+})
+
+describe('encodeStreamChunk / decodeStreamChunk', () => {
+  it('round-trips a non-final chunk', () => {
+    const chunk: StreamChunk = { i: 3, d: 'hello', h: 'abc-def', f: false }
+    const encoded = encodeStreamChunk(chunk)
+    const decoded = decodeStreamChunk(encoded)
+    expect(decoded).toEqual(chunk)
+  })
+
+  it('round-trips a final chunk', () => {
+    const chunk: StreamChunk = { i: 10, d: '', h: 'xxx', f: true, sig: 'yyy', kid: 'mykey' }
+    expect(decodeStreamChunk(encodeStreamChunk(chunk))).toEqual(chunk)
+  })
+
+  it('throws on invalid JSON', () => {
+    expect(() => decodeStreamChunk('not json')).toThrow(/invalid JSON/i)
+  })
+
+  it('throws on missing required fields', () => {
+    expect(() => decodeStreamChunk('{"i":0,"d":"x"}')).toThrow(/missing required fields/i)
+  })
+})
+