@7h3/protocol 0.4.0 → 0.5.0

package/src/otel.ts

@@ -0,0 +1,136 @@
+/**
+ * otel.ts — Optional OpenTelemetry integration for 7h3 Protocol
+ *
+ * Pass your @opentelemetry/api Tracer provider via setOtelProvider.
+ * No hard dependency — works with any OTel-compatible SDK or without any OTel at all.
+ *
+ * Duck-typed interfaces: any object matching the shape will work, including
+ * the real @opentelemetry/api TracerProvider.
+ *
+ * Usage:
+ *   import { setOtelProvider } from '@7h3/protocol/otel'
+ *   import { trace } from '@opentelemetry/api'
+ *
+ *   setOtelProvider(trace.getTracerProvider())
+ *
+ * Without OTel configured, withVerificationSpan and withAuditSpan call fn(null)
+ * with zero overhead.
+ */
+
+// ─── Duck-typed OTel interfaces ───────────────────────────────────────────────
+
+/**
+ * A minimal OTel-compatible span interface.
+ * Compatible with @opentelemetry/api Span.
+ */
+export interface OtelSpan {
+  setAttribute(key: string, value: string | number | boolean): void
+  end(): void
+  recordException(error: Error): void
+}
+
+/**
+ * A minimal OTel-compatible tracer interface.
+ * Compatible with @opentelemetry/api Tracer.
+ */
+export interface OtelTracer {
+  startSpan(name: string, attrs?: Record<string, string | number>): OtelSpan
+}
+
+/**
+ * A minimal OTel-compatible provider interface.
+ * Compatible with @opentelemetry/api TracerProvider.
+ */
+export interface OtelProvider {
+  getTracer(name: string): OtelTracer
+}
+
+// ─── State ────────────────────────────────────────────────────────────────────
+
+let _provider: OtelProvider | null = null
+
+// ─── Provider management ──────────────────────────────────────────────────────
+
+/**
+ * Register an OTel provider. Call once at application startup.
+ * Subsequent calls replace the previous provider.
+ */
+export function setOtelProvider(provider: OtelProvider): void {
+  _provider = provider
+}
+
+/**
+ * Returns the active OTel tracer for '7h3/protocol', or null if no provider
+ * has been registered.
+ */
+export function getOtelTracer(): OtelTracer | null {
+  if (_provider === null) return null
+  try {
+    return _provider.getTracer('7h3/protocol')
+  } catch {
+    return null
+  }
+}
+
+// ─── Span helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Creates a span named '7h3.verify' if OTel is configured, calls fn(span),
+ * records any exception, and ends the span on completion.
+ *
+ * If no OTel provider is registered, calls fn(null) directly with zero overhead.
+ */
+export async function withVerificationSpan<T>(
+  fn: (span: OtelSpan | null) => Promise<T>,
+  attrs?: Record<string, string | number>,
+): Promise<T> {
+  const tracer = getOtelTracer()
+  if (tracer === null) {
+    return fn(null)
+  }
+
+  const span = tracer.startSpan('7h3.verify', attrs)
+  try {
+    const result = await fn(span)
+    return result
+  } catch (err) {
+    if (err instanceof Error) {
+      span.recordException(err)
+    } else {
+      span.recordException(new Error(String(err)))
+    }
+    throw err
+  } finally {
+    span.end()
+  }
+}
+
+/**
+ * Creates a span named '7h3.audit.write' if OTel is configured, calls fn(span),
+ * records any exception, and ends the span on completion.
+ *
+ * If no OTel provider is registered, calls fn(null) directly with zero overhead.
+ */
+export async function withAuditSpan<T>(
+  fn: (span: OtelSpan | null) => Promise<T>,
+): Promise<T> {
+  const tracer = getOtelTracer()
+  if (tracer === null) {
+    return fn(null)
+  }
+
+  const span = tracer.startSpan('7h3.audit.write')
+  try {
+    const result = await fn(span)
+    return result
+  } catch (err) {
+    if (err instanceof Error) {
+      span.recordException(err)
+    } else {
+      span.recordException(new Error(String(err)))
+    }
+    throw err
+  } finally {
+    span.end()
+  }
+}

package/src/protocol.d.ts

@@ -0,0 +1,67 @@
+export type ProtocolVersion = '7h3/0.1';
+export type IntentKind = 'PING' | 'PONG' | 'CAPS' | 'TASK' | 'RESULT' | 'ERROR';
+export interface ProtocolHeader {
+    version: ProtocolVersion;
+    messageId: string;
+    timestampMs: number;
+    ttlMs: number;
+    sender: string;
+    recipient?: string;
+    nonce: string;
+}
+export interface ProtocolBody {
+    intent: IntentKind;
+    content: string;
+    capability?: string;
+    correlationId?: string;
+}
+export interface ProtocolSignature {
+    alg: 'HS256' | 'ED25519';
+    keyId: string;
+    value: string;
+}
+export interface ProtocolEnvelope {
+    header: ProtocolHeader;
+    body: ProtocolBody;
+    signature?: ProtocolSignature;
+}
+export interface ProtocolDiagnostic {
+    level: 'error' | 'warning';
+    message: string;
+}
+export type SignatureVerificationMaterial = {
+    alg: 'HS256';
+    secret: string;
+} | {
+    alg: 'ED25519';
+    publicKey: string;
+};
+export declare function canonicalizeEnvelope(envelope: Omit<ProtocolEnvelope, 'signature'>): string;
+export declare function signCanonicalPayloadHmac(payload: string, secret: string): Promise<string>;
+export declare function verifyCanonicalPayloadHmac(payload: string, signature: string, secret: string): Promise<boolean>;
+export declare function generateEd25519KeypairBase64Url(): Promise<{
+    publicKey: string;
+    privateKey: string;
+}>;
+export declare function signCanonicalPayloadEd25519(payload: string, privateKeyPkcs8Base64Url: string): Promise<string>;
+export declare function verifyCanonicalPayloadEd25519(payload: string, signature: string, publicKeySpkiBase64Url: string): Promise<boolean>;
+export declare function signEnvelopeHmac(envelope: Omit<ProtocolEnvelope, 'signature'>, secret: string, keyId?: string): Promise<ProtocolEnvelope>;
+export declare function verifyEnvelopeHmac(envelope: ProtocolEnvelope, secret: string): Promise<boolean>;
+export declare function signEnvelopeEd25519(envelope: Omit<ProtocolEnvelope, 'signature'>, privateKeyPkcs8Base64Url: string, keyId?: string): Promise<ProtocolEnvelope>;
+export declare function verifyEnvelopeEd25519(envelope: ProtocolEnvelope, publicKeySpkiBase64Url: string): Promise<boolean>;
+export declare function verifyEnvelopeSignature(envelope: ProtocolEnvelope, material: SignatureVerificationMaterial): Promise<boolean>;
+export declare function verifyCanonicalPayloadSignature(payload: string, signature: ProtocolSignature | undefined, material: SignatureVerificationMaterial): Promise<boolean>;
+export declare function validateEnvelope(envelope: ProtocolEnvelope, nowMs?: number): ProtocolDiagnostic[];
+export declare function createEnvelope(input: {
+    sender: string;
+    recipient?: string;
+    intent: IntentKind;
+    content: string;
+    capability?: string;
+    correlationId?: string;
+    ttlMs?: number;
+    messageId?: string;
+    nonce?: string;
+    nowMs?: number;
+}): Omit<ProtocolEnvelope, 'signature'>;
+//# sourceMappingURL=protocol.d.ts.map

package/src/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["protocol.ts"],"names":[],"mappings":"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"}

package/src/protocol.js

@@ -0,0 +1,294 @@
+const textEncoder = new TextEncoder();
+const HMAC_KEY_CACHE_LIMIT = 256;
+const hmacKeyCache = new Map();
+const ED25519_KEY_CACHE_LIMIT = 256;
+const ed25519PrivateKeyCache = new Map();
+const ed25519PublicKeyCache = new Map();
+function getBufferLike() {
+    const candidate = globalThis;
+    return candidate.Buffer ?? null;
+}
+function serializeHeaderCanonical(header) {
+    const parts = [
+        `"messageId":${JSON.stringify(header.messageId)}`,
+        `"nonce":${JSON.stringify(header.nonce)}`,
+    ];
+    if (header.recipient !== undefined) {
+        parts.push(`"recipient":${JSON.stringify(header.recipient)}`);
+    }
+    parts.push(`"sender":${JSON.stringify(header.sender)}`);
+    parts.push(`"timestampMs":${header.timestampMs}`);
+    parts.push(`"ttlMs":${header.ttlMs}`);
+    parts.push(`"version":${JSON.stringify(header.version)}`);
+    return `{${parts.join(',')}}`;
+}
+function serializeBodyCanonical(body) {
+    const parts = [];
+    if (body.capability !== undefined) {
+        parts.push(`"capability":${JSON.stringify(body.capability)}`);
+    }
+    parts.push(`"content":${JSON.stringify(body.content)}`);
+    if (body.correlationId !== undefined) {
+        parts.push(`"correlationId":${JSON.stringify(body.correlationId)}`);
+    }
+    parts.push(`"intent":${JSON.stringify(body.intent)}`);
+    return `{${parts.join(',')}}`;
+}
+function getCachedHmacKey(secret) {
+    const cacheKey = `hs256:${secret}`;
+    const cached = hmacKeyCache.get(cacheKey);
+    if (cached)
+        return cached;
+    if (hmacKeyCache.size >= HMAC_KEY_CACHE_LIMIT) {
+        hmacKeyCache.clear();
+    }
+    const subtle = requireCryptoSubtle();
+    const imported = subtle
+        .importKey('raw', textEncoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify'])
+        .catch((error) => {
+        hmacKeyCache.delete(cacheKey);
+        throw error;
+    });
+    hmacKeyCache.set(cacheKey, imported);
+    return imported;
+}
+function getCachedEd25519PrivateKey(privateKeyPkcs8Base64Url) {
+    const cacheKey = `ed25519:pkcs8:${privateKeyPkcs8Base64Url}`;
+    const cached = ed25519PrivateKeyCache.get(cacheKey);
+    if (cached)
+        return cached;
+    if (ed25519PrivateKeyCache.size >= ED25519_KEY_CACHE_LIMIT) {
+        ed25519PrivateKeyCache.clear();
+    }
+    const subtle = requireCryptoSubtle();
+    const imported = subtle
+        .importKey('pkcs8', toArrayBuffer(fromBase64Url(privateKeyPkcs8Base64Url)), { name: 'Ed25519' }, false, ['sign'])
+        .catch((error) => {
+        ed25519PrivateKeyCache.delete(cacheKey);
+        throw error;
+    });
+    ed25519PrivateKeyCache.set(cacheKey, imported);
+    return imported;
+}
+function getCachedEd25519PublicKey(publicKeySpkiBase64Url) {
+    const cacheKey = `ed25519:spki:${publicKeySpkiBase64Url}`;
+    const cached = ed25519PublicKeyCache.get(cacheKey);
+    if (cached)
+        return cached;
+    if (ed25519PublicKeyCache.size >= ED25519_KEY_CACHE_LIMIT) {
+        ed25519PublicKeyCache.clear();
+    }
+    const subtle = requireCryptoSubtle();
+    const imported = subtle
+        .importKey('spki', toArrayBuffer(fromBase64Url(publicKeySpkiBase64Url)), { name: 'Ed25519' }, false, ['verify'])
+        .catch((error) => {
+        ed25519PublicKeyCache.delete(cacheKey);
+        throw error;
+    });
+    ed25519PublicKeyCache.set(cacheKey, imported);
+    return imported;
+}
+function toBase64Url(bytes) {
+    const bufferLike = getBufferLike();
+    const base64 = bufferLike ? bufferLike.from(bytes).toString('base64') : btoa(String.fromCharCode(...bytes));
+    return base64
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/g, '');
+}
+function fromBase64Url(value) {
+    const padded = value
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(Math.ceil(value.length / 4) * 4, '=');
+    const bufferLike = getBufferLike();
+    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 += 1) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function toArrayBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+export function canonicalizeEnvelope(envelope) {
+    return `{"body":${serializeBodyCanonical(envelope.body)},"header":${serializeHeaderCanonical(envelope.header)}}`;
+}
+function requireCryptoSubtle() {
+    if (typeof crypto === 'undefined' || !crypto.subtle) {
+        throw new Error('Web Crypto API is not available in this runtime');
+    }
+    return crypto.subtle;
+}
+async function hmacSign(payload, secret) {
+    const subtle = requireCryptoSubtle();
+    const key = await getCachedHmacKey(secret);
+    const signature = await subtle.sign('HMAC', key, textEncoder.encode(payload));
+    return toBase64Url(new Uint8Array(signature));
+}
+async function hmacVerify(payload, signature, secret) {
+    const subtle = requireCryptoSubtle();
+    const key = await getCachedHmacKey(secret);
+    const signatureBytes = fromBase64Url(signature);
+    return subtle.verify('HMAC', key, signatureBytes.buffer, textEncoder.encode(payload));
+}
+async function ed25519Sign(payload, privateKeyPkcs8Base64Url) {
+    const subtle = requireCryptoSubtle();
+    const key = await getCachedEd25519PrivateKey(privateKeyPkcs8Base64Url);
+    const signature = await subtle.sign('Ed25519', key, textEncoder.encode(payload));
+    return toBase64Url(new Uint8Array(signature));
+}
+async function ed25519Verify(payload, signature, publicKeySpkiBase64Url) {
+    const subtle = requireCryptoSubtle();
+    const key = await getCachedEd25519PublicKey(publicKeySpkiBase64Url);
+    const signatureBytes = fromBase64Url(signature);
+    return subtle.verify('Ed25519', key, signatureBytes.buffer, textEncoder.encode(payload));
+}
+export async function signCanonicalPayloadHmac(payload, secret) {
+    return hmacSign(payload, secret);
+}
+export async function verifyCanonicalPayloadHmac(payload, signature, secret) {
+    return hmacVerify(payload, signature, secret);
+}
+export async function generateEd25519KeypairBase64Url() {
+    const subtle = requireCryptoSubtle();
+    const pair = await subtle.generateKey({ name: 'Ed25519' }, true, ['sign', 'verify']);
+    const privateKeyRaw = await subtle.exportKey('pkcs8', pair.privateKey);
+    const publicKeyRaw = await subtle.exportKey('spki', pair.publicKey);
+    return {
+        privateKey: toBase64Url(new Uint8Array(privateKeyRaw)),
+        publicKey: toBase64Url(new Uint8Array(publicKeyRaw)),
+    };
+}
+export async function signCanonicalPayloadEd25519(payload, privateKeyPkcs8Base64Url) {
+    return ed25519Sign(payload, privateKeyPkcs8Base64Url);
+}
+export async function verifyCanonicalPayloadEd25519(payload, signature, publicKeySpkiBase64Url) {
+    return ed25519Verify(payload, signature, publicKeySpkiBase64Url);
+}
+export async function signEnvelopeHmac(envelope, secret, keyId = 'local-dev-key') {
+    const payload = canonicalizeEnvelope(envelope);
+    const signature = await hmacSign(payload, secret);
+    return {
+        ...envelope,
+        signature: {
+            alg: 'HS256',
+            keyId,
+            value: signature,
+        },
+    };
+}
+export async function verifyEnvelopeHmac(envelope, secret) {
+    if (!envelope.signature)
+        return false;
+    if (envelope.signature.alg !== 'HS256')
+        return false;
+    const unsigned = {
+        header: envelope.header,
+        body: envelope.body,
+    };
+    const payload = canonicalizeEnvelope(unsigned);
+    return hmacVerify(payload, envelope.signature.value, secret);
+}
+export async function signEnvelopeEd25519(envelope, privateKeyPkcs8Base64Url, keyId = 'local-ed25519-key') {
+    const payload = canonicalizeEnvelope(envelope);
+    const signature = await ed25519Sign(payload, privateKeyPkcs8Base64Url);
+    return {
+        ...envelope,
+        signature: {
+            alg: 'ED25519',
+            keyId,
+            value: signature,
+        },
+    };
+}
+export async function verifyEnvelopeEd25519(envelope, publicKeySpkiBase64Url) {
+    if (!envelope.signature)
+        return false;
+    if (envelope.signature.alg !== 'ED25519')
+        return false;
+    const unsigned = {
+        header: envelope.header,
+        body: envelope.body,
+    };
+    const payload = canonicalizeEnvelope(unsigned);
+    return ed25519Verify(payload, envelope.signature.value, publicKeySpkiBase64Url);
+}
+export async function verifyEnvelopeSignature(envelope, material) {
+    if (!envelope.signature)
+        return false;
+    if (envelope.signature.alg !== material.alg)
+        return false;
+    if (material.alg === 'HS256') {
+        return verifyEnvelopeHmac(envelope, material.secret);
+    }
+    return verifyEnvelopeEd25519(envelope, material.publicKey);
+}
+export async function verifyCanonicalPayloadSignature(payload, signature, material) {
+    if (!signature)
+        return false;
+    if (signature.alg !== material.alg)
+        return false;
+    if (material.alg === 'HS256') {
+        return verifyCanonicalPayloadHmac(payload, signature.value, material.secret);
+    }
+    return verifyCanonicalPayloadEd25519(payload, signature.value, material.publicKey);
+}
+export function validateEnvelope(envelope, nowMs = Date.now()) {
+    const diagnostics = [];
+    const header = envelope.header ?? {};
+    const body = envelope.body ?? {};
+    const version = typeof header.version === 'string' ? header.version : '';
+    const messageId = typeof header.messageId === 'string' ? header.messageId : '';
+    const sender = typeof header.sender === 'string' ? header.sender : '';
+    const nonce = typeof header.nonce === 'string' ? header.nonce : '';
+    const timestampMs = typeof header.timestampMs === 'number' ? header.timestampMs : 0;
+    const ttlMs = typeof header.ttlMs === 'number' ? header.ttlMs : 0;
+    const content = typeof body.content === 'string' ? body.content : '';
+    if (version !== '7h3/0.1') {
+        diagnostics.push({ level: 'error', message: `Unsupported protocol version '${version}'` });
+    }
+    if (!messageId.trim()) {
+        diagnostics.push({ level: 'error', message: 'Missing messageId' });
+    }
+    if (!sender.trim()) {
+        diagnostics.push({ level: 'error', message: 'Missing sender identity' });
+    }
+    if (!nonce.trim()) {
+        diagnostics.push({ level: 'error', message: 'Missing nonce — replay protection requires a unique nonce per message' });
+    }
+    if (ttlMs <= 0) {
+        diagnostics.push({ level: 'error', message: 'ttlMs must be greater than zero' });
+    }
+    if (timestampMs + ttlMs < nowMs) {
+        diagnostics.push({ level: 'error', message: 'Message TTL expired' });
+    }
+    if (!content.trim()) {
+        diagnostics.push({ level: 'warning', message: 'Empty content payload' });
+    }
+    return diagnostics;
+}
+export function createEnvelope(input) {
+    const nowMs = input.nowMs ?? Date.now();
+    return {
+        header: {
+            version: '7h3/0.1',
+            messageId: input.messageId ?? `msg-${nowMs}-${Math.random().toString(36).slice(2, 10)}`,
+            timestampMs: nowMs,
+            ttlMs: input.ttlMs ?? 60_000,
+            sender: input.sender,
+            recipient: input.recipient,
+            nonce: input.nonce ?? Math.random().toString(36).slice(2, 12),
+        },
+        body: {
+            intent: input.intent,
+            content: input.content,
+            capability: input.capability,
+            correlationId: input.correlationId,
+        },
+    };
+}

package/src/protocol.ts

@@ -7,6 +7,7 @@ export type IntentKind =
   | 'TASK'
   | 'RESULT'
   | 'ERROR'
+  | 'ENCRYPTED'
 
 export interface ProtocolHeader {
   version: ProtocolVersion

package/src/replayStores.test.ts

@@ -1,6 +1,13 @@
 import { describe, expect, it, vi } from 'vitest'
 import { InMemoryRedisLikeClient } from './redisClient'
-import { createRedisReplayStore } from './replayStores'
+import {
+  createRedisReplayStore,
+  RedisReplayStore,
+  ClusterRedisReplayStore,
+  createClusterReplayStore,
+  type ReplayStore,
+  type RedisClientLike,
+} from './replayStores'
 import { DistributedReplayCache } from './protocolReplay'
 import { createEnvelope } from './protocol'
 
@@ -139,3 +146,128 @@ describe('DistributedReplayCache batch delegation', () => {
     expect(results.map((r) => r.ok)).toEqual([true, true])
   })
 })
+
+// ---------------------------------------------------------------------------
+// New ReplayStore interface and class tests (check()-based API)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a mock RedisClientLike whose SET NX behaviour can be scripted:
+ * first call returns 'OK' (fresh), subsequent calls return null (replay).
+ */
+function mockRedisClient(): RedisClientLike {
+  let callCount = 0
+  return {
+    set: vi.fn(async (_key: string, _value: string, _opts?: { nx?: boolean; px?: number }) => {
+      callCount++
+      return callCount === 1 ? 'OK' : null
+    }),
+    get: vi.fn(async (_key: string) => null),
+    del: vi.fn(async (_key: string) => 0),
+    quit: vi.fn(async () => undefined),
+  }
+}
+
+describe('RedisReplayStore (check() interface)', () => {
+  it('first call returns false (fresh) and second call returns true (replay)', async () => {
+    const client = mockRedisClient()
+    const store = new RedisReplayStore({ client })
+    const fresh = await store.check('nonce-abc', 30_000)
+    const replay = await store.check('nonce-abc', 30_000)
+    expect(fresh).toBe(false)
+    expect(replay).toBe(true)
+  })
+
+  it('satisfies the ReplayStore interface', () => {
+    const store: ReplayStore = new RedisReplayStore({ client: mockRedisClient() })
+    expect(typeof store.check).toBe('function')
+  })
+
+  it('uses default keyPrefix "7h3:nonce:"', async () => {
+    const client = mockRedisClient()
+    const store = new RedisReplayStore({ client })
+    await store.check('my-nonce', 5000)
+    expect(client.set).toHaveBeenCalledWith('7h3:nonce:my-nonce', '1', { nx: true, px: 5000 })
+  })
+
+  it('respects a custom keyPrefix', async () => {
+    const client = mockRedisClient()
+    const store = new RedisReplayStore({ client, keyPrefix: 'custom:' })
+    await store.check('n1', 1000)
+    expect(client.set).toHaveBeenCalledWith('custom:n1', '1', { nx: true, px: 1000 })
+  })
+
+  it('clamps TTL to at least 1ms', async () => {
+    const client = mockRedisClient()
+    const store = new RedisReplayStore({ client })
+    await store.check('n1', 0)
+    expect(client.set).toHaveBeenCalledWith('7h3:nonce:n1', '1', { nx: true, px: 1 })
+  })
+})
+
+describe('createRedisReplayStore opts-object overload', () => {
+  it('returns a RedisReplayStore with the correct keyPrefix', () => {
+    const store = createRedisReplayStore({ keyPrefix: '7h3:nonce:' })
+    expect(store).toBeInstanceOf(RedisReplayStore)
+  })
+
+  it('returns a RedisReplayStore with default keyPrefix when none specified', () => {
+    const store = createRedisReplayStore({ client: mockRedisClient() })
+    expect(store).toBeInstanceOf(RedisReplayStore)
+  })
+})
+
+describe('ClusterRedisReplayStore', () => {
+  it('check() returns false (fresh) when ALL nodes say fresh', async () => {
+    // Build two nodes each with a fresh client
+    const makeClient = () => {
+      const c = mockRedisClient()
+      return c
+    }
+    const node1 = new RedisReplayStore({ client: makeClient() })
+    const node2 = new RedisReplayStore({ client: makeClient() })
+    const cluster = new ClusterRedisReplayStore([node1, node2])
+    // First call: both nodes return OK → fresh
+    const result = await cluster.check('nonce-xyz', 10_000)
+    expect(result).toBe(false)
+  })
+
+  it('check() returns true (replay) when ANY node reports replay', async () => {
+    // node1: already seen (returns null immediately)
+    const replayClient: RedisClientLike = {
+      set: vi.fn(async () => null), // always null = always replay
+      get: vi.fn(async () => null),
+      del: vi.fn(async () => 0),
+      quit: vi.fn(async () => undefined),
+    }
+    // node2: fresh (returns OK)
+    const freshClient: RedisClientLike = {
+      set: vi.fn(async () => 'OK'),
+      get: vi.fn(async () => null),
+      del: vi.fn(async () => 0),
+      quit: vi.fn(async () => undefined),
+    }
+    const node1 = new RedisReplayStore({ client: replayClient })
+    const node2 = new RedisReplayStore({ client: freshClient })
+    const cluster = new ClusterRedisReplayStore([node1, node2])
+    const result = await cluster.check('nonce-xyz', 10_000)
+    expect(result).toBe(true)
+  })
+
+  it('queries all nodes in parallel via Promise.all', async () => {
+    const clients = [mockRedisClient(), mockRedisClient(), mockRedisClient()]
+    const nodes = clients.map((c) => new RedisReplayStore({ client: c }))
+    const cluster = new ClusterRedisReplayStore(nodes)
+    await cluster.check('nonce-parallel', 5000)
+    for (const c of clients) {
+      expect(c.set).toHaveBeenCalledOnce()
+    }
+  })
+})
+
+describe('createClusterReplayStore', () => {
+  it('returns a ClusterRedisReplayStore from an array of URLs', () => {
+    const cluster = createClusterReplayStore(['redis://node1:6379', 'redis://node2:6379'])
+    expect(cluster).toBeInstanceOf(ClusterRedisReplayStore)
+  })
+})