@7h3/protocol 0.1.2 → 0.5.0

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)
+  })
+})
+

package/src/stream.ts

@@ -0,0 +1,417 @@
+// 7h3 Protocol — Streaming message signing (Feature 4)
+//
+// Wire format per chunk:
+//   { i, d, h, f }                    — non-final frame
+//   { i, d, h, f:true, sig, kid }     — final frame
+//
+// Security model:
+//   Writer derives an HMAC-SHA256 key via HKDF(privateKeyBytes, salt=nonce, info='7h3-stream/1')
+//   and produces per-chunk HMACs.  Only the writer can verify these (private key material).
+//
+//   Reader verification is anchored on the Ed25519 final signature which covers
+//   SHA-256( ordered concat of "i:d" per chunk ) — so any mid-stream tamper, reorder,
+//   or cross-stream splice is caught at finalize time.
+
+// ────────────────────────────────── types ─────────────────────────────────────
+
+export interface StreamChunk {
+  i: number       // sequence index (0-based)
+  d: string       // data (string)
+  h: string       // per-chunk HMAC-SHA256 (base64url) — writer-side only
+  f: boolean      // true = final frame
+  sig?: string    // Ed25519 sig over content hash (only on final frame)
+  kid?: string    // keyId (only on final frame)
+}
+
+export interface StreamSignerOpts {
+  privateKey: string    // Ed25519 PKCS8 base64url
+  sender: string
+  nonce?: string        // auto-generated when omitted
+  keyId?: string
+}
+
+export interface StreamVerifierOpts {
+  publicKey: string     // Ed25519 SPKI base64url
+  maxChunks?: number    // default 10000
+}
+
+export type StreamVerifyResult =
+  | { ok: true; totalBytes: number; chunkCount: number }
+  | { ok: false; reason: string; chunkIndex?: number }
+
+// ─────────────────────────── constants ────────────────────────────────────────
+
+export const STREAM_HEADER = 'x-7h3-stream'
+
+// ─────────────────────────── internal helpers ─────────────────────────────────
+
+const textEncoder = new TextEncoder()
+
+function requireCryptoSubtle(): SubtleCrypto {
+  if (typeof crypto === 'undefined' || !crypto.subtle) {
+    throw new Error('Web Crypto API is not available in this runtime')
+  }
+  return crypto.subtle
+}
+
+function toBase64Url(bytes: Uint8Array): string {
+  const bufferLike = (globalThis as any).Buffer
+  const base64 = bufferLike
+    ? bufferLike.from(bytes).toString('base64')
+    : btoa(String.fromCharCode(...bytes))
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '')
+}
+
+function fromBase64Url(value: string): Uint8Array {
+  const padded = value
+    .replace(/-/g, '+')
+    .replace(/_/g, '/')
+    .padEnd(Math.ceil(value.length / 4) * 4, '=')
+  const bufferLike = (globalThis as any).Buffer
+  if (bufferLike) return new Uint8Array(bufferLike.from(padded, 'base64'))
+  const binary = atob(padded)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+  return bytes
+}
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer
+}
+
+function generateNonce(): string {
+  const arr = new Uint8Array(16)
+  crypto.getRandomValues(arr)
+  return toBase64Url(arr)
+}
+
+// ─────────────────── HMAC key derivation (HKDF from private key) ──────────────
+//
+// IKM = raw PKCS8 DER bytes of the Ed25519 private key
+// salt = nonce (UTF-8)
+// info = '7h3-stream/1' (UTF-8)
+// output = 32-byte HMAC-SHA256 key
+//
+// The derived key is cached per (privateKey, nonce) pair so 1000 chunks only
+// pay one HKDF derivation.
+
+const derivedHmacKeyCache = new Map<string, Promise<CryptoKey>>()
+const HMAC_KEY_CACHE_LIMIT = 128
+
+function getDerivedHmacKey(privateKeyBase64Url: string, nonce: string): Promise<CryptoKey> {
+  const cacheKey = `${privateKeyBase64Url}:${nonce}`
+  const cached = derivedHmacKeyCache.get(cacheKey)
+  if (cached) return cached
+
+  if (derivedHmacKeyCache.size >= HMAC_KEY_CACHE_LIMIT) derivedHmacKeyCache.clear()
+
+  const subtle = requireCryptoSubtle()
+  const pkcs8Bytes = fromBase64Url(privateKeyBase64Url)
+
+  const promise = (async () => {
+    // Import the raw PKCS8 bytes as HKDF input keying material
+    const hkdfKey = await subtle.importKey(
+      'raw',
+      toArrayBuffer(pkcs8Bytes),
+      'HKDF',
+      false,
+      ['deriveBits'],
+    )
+    // Derive 256 bits
+    const bits = await subtle.deriveBits(
+      {
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt: textEncoder.encode(nonce),
+        info: textEncoder.encode('7h3-stream/1'),
+      },
+      hkdfKey,
+      256,
+    )
+    // Wrap as HMAC-SHA256 signing key
+    return subtle.importKey(
+      'raw',
+      bits,
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign'],
+    )
+  })()
+
+  promise.catch(() => derivedHmacKeyCache.delete(cacheKey))
+  derivedHmacKeyCache.set(cacheKey, promise)
+  return promise
+}
+
+// ─────────────────── Ed25519 private key cache ────────────────────────────────
+
+const ed25519PrivCache = new Map<string, Promise<CryptoKey>>()
+const ED25519_PRIV_CACHE_LIMIT = 64
+
+function getCachedEd25519PrivateKey(privateKeyBase64Url: string): Promise<CryptoKey> {
+  const cached = ed25519PrivCache.get(privateKeyBase64Url)
+  if (cached) return cached
+  if (ed25519PrivCache.size >= ED25519_PRIV_CACHE_LIMIT) ed25519PrivCache.clear()
+  const subtle = requireCryptoSubtle()
+  const promise = subtle
+    .importKey('pkcs8', toArrayBuffer(fromBase64Url(privateKeyBase64Url)), { name: 'Ed25519' }, false, ['sign'])
+    .catch((err: unknown) => { ed25519PrivCache.delete(privateKeyBase64Url); throw err })
+  ed25519PrivCache.set(privateKeyBase64Url, promise)
+  return promise
+}
+
+const ed25519PubCache = new Map<string, Promise<CryptoKey>>()
+const ED25519_PUB_CACHE_LIMIT = 64
+
+function getCachedEd25519PublicKey(publicKeyBase64Url: string): Promise<CryptoKey> {
+  const cached = ed25519PubCache.get(publicKeyBase64Url)
+  if (cached) return cached
+  if (ed25519PubCache.size >= ED25519_PUB_CACHE_LIMIT) ed25519PubCache.clear()
+  const subtle = requireCryptoSubtle()
+  const promise = subtle
+    .importKey('spki', toArrayBuffer(fromBase64Url(publicKeyBase64Url)), { name: 'Ed25519' }, false, ['verify'])
+    .catch((err: unknown) => { ed25519PubCache.delete(publicKeyBase64Url); throw err })
+  ed25519PubCache.set(publicKeyBase64Url, promise)
+  return promise
+}
+
+// ─────────────────── content-hash helpers ─────────────────────────────────────
+//
+// Content hash = SHA-256 over UTF-8 join of "i:d" per chunk, in order.
+// For the empty stream the message is the empty string "".
+// The join separator is "\n" to keep chunks from blending across boundaries.
+
+function buildContentMessage(chunks: Array<{ i: number; d: string }>): Uint8Array {
+  const parts = chunks.map(c => `${c.i}:${c.d}`)
+  return textEncoder.encode(parts.join('\n'))
+}
+
+async function sha256(data: Uint8Array): Promise<Uint8Array> {
+  const subtle = requireCryptoSubtle()
+  const digest = await subtle.digest('SHA-256', toArrayBuffer(data))
+  return new Uint8Array(digest)
+}
+
+// ─────────────────── SignedStreamWriter ───────────────────────────────────────
+
+export class SignedStreamWriter {
+  private readonly opts: Required<StreamSignerOpts>
+  private seq = 0
+  private readonly accum: Array<{ i: number; d: string }> = []
+  // Lazily-derived HMAC key (cached after first use)
+  private hmacKeyPromise: Promise<CryptoKey> | null = null
+
+  constructor(opts: StreamSignerOpts) {
+    this.opts = {
+      nonce: opts.nonce ?? generateNonce(),
+      keyId: opts.keyId ?? 'stream-key',
+      ...opts,
+    }
+  }
+
+  get nonce(): string { return this.opts.nonce }
+
+  private getHmacKey(): Promise<CryptoKey> {
+    if (!this.hmacKeyPromise) {
+      this.hmacKeyPromise = getDerivedHmacKey(this.opts.privateKey, this.opts.nonce)
+    }
+    return this.hmacKeyPromise
+  }
+
+  private async computeChunkHmac(index: number, data: string): Promise<string> {
+    const subtle = requireCryptoSubtle()
+    const key = await this.getHmacKey()
+    // payload = nonce ":" index ":" data
+    const payload = `${this.opts.nonce}:${index}:${data}`
+    const sig = await subtle.sign('HMAC', key, textEncoder.encode(payload))
+    return toBase64Url(new Uint8Array(sig))
+  }
+
+  async writeChunk(data: string): Promise<StreamChunk> {
+    const index = this.seq++
+    const h = await this.computeChunkHmac(index, data)
+    this.accum.push({ i: index, d: data })
+    return { i: index, d: data, h, f: false }
+  }
+
+  async finalize(): Promise<StreamChunk> {
+    const subtle = requireCryptoSubtle()
+    const privKey = await getCachedEd25519PrivateKey(this.opts.privateKey)
+
+    // Sign over SHA-256 of ordered chunk content
+    const contentMsg = buildContentMessage(this.accum)
+    const digest = await sha256(contentMsg)
+    // Ed25519 signs the digest bytes directly (WebCrypto Ed25519 takes raw message)
+    const sigBytes = await subtle.sign('Ed25519', privKey, toArrayBuffer(digest))
+    const sig = toBase64Url(new Uint8Array(sigBytes))
+
+    // Final frame HMAC is over the content hash (hex) so it binds the full stream
+    const index = this.seq
+    const finalData = ''
+    const h = await this.computeChunkHmac(index, toBase64Url(digest))
+
+    return { i: index, d: finalData, h, f: true, sig, kid: this.opts.keyId }
+  }
+}
+
+// ─────────────────── SignedStreamReader ───────────────────────────────────────
+
+export class SignedStreamReader {
+  private readonly opts: StreamVerifierOpts
+  private expectedSeq = 0
+  private readonly accum: Array<{ i: number; d: string }> = []
+  private totalBytes = 0
+  private done = false
+
+  constructor(opts: StreamVerifierOpts) {
+    this.opts = opts
+  }
+
+  async receiveChunk(chunk: StreamChunk): Promise<{ ok: boolean; reason?: string }> {
+    if (this.done) return { ok: false, reason: 'stream already finalized' }
+
+    const maxChunks = this.opts.maxChunks ?? 10_000
+    if (this.accum.length >= maxChunks) {
+      return { ok: false, reason: `exceeded maxChunks (${maxChunks})` }
+    }
+
+    // Sequence check — no gaps, no reorder
+    if (chunk.i !== this.expectedSeq) {
+      return { ok: false, reason: `sequence error: expected ${this.expectedSeq}, got ${chunk.i}` }
+    }
+    this.expectedSeq++
+
+    // Accumulate data
+    this.accum.push({ i: chunk.i, d: chunk.d })
+    this.totalBytes += textEncoder.encode(chunk.d).length
+
+    // Per-chunk HMAC is writer-side only (requires private key); we skip it here.
+    // The Ed25519 final signature covers all chunks and is the reader's guarantee.
+
+    return { ok: true }
+  }
+
+  async finalize(finalChunk: StreamChunk): Promise<StreamVerifyResult> {
+    if (this.done) return { ok: false, reason: 'stream already finalized' }
+    this.done = true
+
+    if (!finalChunk.sig) {
+      return { ok: false, reason: 'missing signature on final chunk' }
+    }
+
+    const subtle = requireCryptoSubtle()
+    let pubKey: CryptoKey
+    try {
+      pubKey = await getCachedEd25519PublicKey(this.opts.publicKey)
+    } catch {
+      return { ok: false, reason: 'invalid public key' }
+    }
+
+    // Recompute the content hash (same as writer)
+    const contentMsg = buildContentMessage(this.accum)
+    const digest = await sha256(contentMsg)
+
+    const sigBytes = fromBase64Url(finalChunk.sig)
+    const valid = await subtle.verify('Ed25519', pubKey, toArrayBuffer(sigBytes), toArrayBuffer(digest))
+
+    if (!valid) {
+      return { ok: false, reason: 'signature verification failed' }
+    }
+
+    return { ok: true, totalBytes: this.totalBytes, chunkCount: this.accum.length }
+  }
+}
+
+// ─────────────────── factory helpers ──────────────────────────────────────────
+
+export function createSignedStream(opts: StreamSignerOpts): SignedStreamWriter {
+  return new SignedStreamWriter(opts)
+}
+
+export function createStreamVerifier(opts: StreamVerifierOpts): SignedStreamReader {
+  return new SignedStreamReader(opts)
+}
+
+// ─────────────────── convenience functions ────────────────────────────────────
+
+export async function signStream(
+  chunks: AsyncIterable<string> | string[],
+  opts: StreamSignerOpts,
+): Promise<StreamChunk[]> {
+  const writer = new SignedStreamWriter(opts)
+  const result: StreamChunk[] = []
+  if (Array.isArray(chunks)) {
+    for (const data of chunks) {
+      result.push(await writer.writeChunk(data))
+    }
+  } else {
+    for await (const data of chunks) {
+      result.push(await writer.writeChunk(data))
+    }
+  }
+  result.push(await writer.finalize())
+  return result
+}
+
+export async function verifyStream(
+  chunks: StreamChunk[],
+  opts: StreamVerifierOpts,
+): Promise<StreamVerifyResult> {
+  const reader = new SignedStreamReader(opts)
+  // All frames except the last
+  const nonFinal = chunks.slice(0, -1)
+  const finalFrame = chunks[chunks.length - 1]
+
+  if (chunks.length === 0) {
+    return { ok: false, reason: 'empty chunk array — missing final frame' }
+  }
+
+  for (const chunk of nonFinal) {
+    const res = await reader.receiveChunk(chunk)
+    if (!res.ok) return { ok: false, reason: res.reason!, chunkIndex: chunk.i }
+  }
+
+  if (!finalFrame.f) {
+    // The last chunk in the array is not marked final — still try to read it as non-final
+    // so sequence errors are reported, but finalize will fail due to missing sig
+    const res = await reader.receiveChunk(finalFrame)
+    if (!res.ok) return { ok: false, reason: res.reason!, chunkIndex: finalFrame.i }
+    return { ok: false, reason: 'missing final frame' }
+  }
+
+  return reader.finalize(finalFrame)
+}
+
+// ─────────────────── encode / decode helpers ──────────────────────────────────
+
+export function encodeStreamChunk(chunk: StreamChunk): string {
+  return JSON.stringify(chunk)
+}
+
+export function decodeStreamChunk(raw: string): StreamChunk {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error('decodeStreamChunk: invalid JSON')
+  }
+  const obj = parsed as Record<string, unknown>
+  if (
+    typeof obj.i !== 'number' ||
+    typeof obj.d !== 'string' ||
+    typeof obj.h !== 'string' ||
+    typeof obj.f !== 'boolean'
+  ) {
+    throw new Error('decodeStreamChunk: missing required fields (i, d, h, f)')
+  }
+  const chunk: StreamChunk = { i: obj.i, d: obj.d, h: obj.h, f: obj.f }
+  if (obj.sig !== undefined) {
+    if (typeof obj.sig !== 'string') throw new Error('decodeStreamChunk: sig must be string')
+    chunk.sig = obj.sig
+  }
+  if (obj.kid !== undefined) {
+    if (typeof obj.kid !== 'string') throw new Error('decodeStreamChunk: kid must be string')
+    chunk.kid = obj.kid
+  }
+  return chunk
+}