@7h3/protocol 0.1.2 → 0.4.0

package/src/signedResponse.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { signResponse, verifyResponse, RESPONSE_HEADER } from './signedResponse'
+import { generateEd25519KeypairBase64Url } from './protocol'
+
+let keys: { publicKey: string; privateKey: string }
+let wrongKeys: { publicKey: string; privateKey: string }
+
+beforeAll(async () => {
+  keys = await generateEd25519KeypairBase64Url()
+  wrongKeys = await generateEd25519KeypairBase64Url()
+})
+
+describe('signedResponse', () => {
+  it('round-trip: signs and verifies correctly', async () => {
+    const body = 'hello world'
+    const { headers } = await signResponse(body, {
+      privateKey: keys.privateKey,
+      sender: 'gateway-agent',
+    })
+
+    const result = await verifyResponse(body, headers, { publicKey: keys.publicKey })
+    expect(result.ok).toBe(true)
+    expect(result.envelope?.body.intent).toBe('RESULT')
+    expect(result.envelope?.body.content).toBe(body)
+  })
+
+  it('fails when body does not match envelope content', async () => {
+    const body = 'original body'
+    const { headers } = await signResponse(body, {
+      privateKey: keys.privateKey,
+      sender: 'gateway-agent',
+    })
+
+    const result = await verifyResponse('tampered body', headers, { publicKey: keys.publicKey })
+    expect(result.ok).toBe(false)
+    expect(result.reason).toBe('content-mismatch')
+  })
+
+  it('fails with wrong public key', async () => {
+    const body = 'some content'
+    const { headers } = await signResponse(body, {
+      privateKey: keys.privateKey,
+      sender: 'gateway-agent',
+    })
+
+    const result = await verifyResponse(body, headers, { publicKey: wrongKeys.publicKey })
+    expect(result.ok).toBe(false)
+    expect(result.reason).toBe('invalid-signature')
+  })
+
+  it('fails when header is missing', async () => {
+    const result = await verifyResponse('body', {}, { publicKey: keys.publicKey })
+    expect(result.ok).toBe(false)
+    expect(result.reason).toBe('missing-header')
+  })
+
+  it('fails when envelope TTL is expired', async () => {
+    // Sign with 1ms ttl — immediately expired
+    const body = 'ttl-test'
+    const { headers } = await signResponse(body, {
+      privateKey: keys.privateKey,
+      sender: 'gateway-agent',
+      ttlMs: 1,
+    })
+
+    // Wait a tick to ensure expiry
+    await new Promise(r => setTimeout(r, 10))
+
+    const result = await verifyResponse(body, headers, { publicKey: keys.publicKey })
+    expect(result.ok).toBe(false)
+    expect(result.reason).toBe('ttl-expired')
+  })
+
+  it('fails when maxAgeMs exceeded', async () => {
+    const body = 'max-age-test'
+    const { headers } = await signResponse(body, {
+      privateKey: keys.privateKey,
+      sender: 'gateway-agent',
+      ttlMs: 60_000, // long ttl
+    })
+
+    // Wait to ensure age exceeds maxAgeMs
+    await new Promise(r => setTimeout(r, 10))
+
+    const result = await verifyResponse(body, headers, {
+      publicKey: keys.publicKey,
+      maxAgeMs: 1, // tiny window
+    })
+    expect(result.ok).toBe(false)
+    expect(result.reason).toBe('ttl-expired')
+  })
+
+  it('passes correlationId and recipient through envelope', async () => {
+    const body = 'corr-test'
+    const { headers } = await signResponse(body, {
+      privateKey: keys.privateKey,
+      sender: 'gateway-agent',
+      recipient: 'client-agent',
+      correlationId: 'req-123',
+    })
+
+    const result = await verifyResponse(body, headers, { publicKey: keys.publicKey })
+    expect(result.ok).toBe(true)
+    expect(result.envelope?.body.correlationId).toBe('req-123')
+    expect(result.envelope?.header.recipient).toBe('client-agent')
+  })
+
+  it('RESPONSE_HEADER constant is x-7h3-response', () => {
+    expect(RESPONSE_HEADER).toBe('x-7h3-response')
+  })
+})

package/src/signedResponse.ts

@@ -0,0 +1,83 @@
+import {
+  createEnvelope,
+  signEnvelopeEd25519,
+  verifyEnvelopeEd25519,
+  type ProtocolEnvelope,
+} from './protocol'
+
+export const RESPONSE_HEADER = 'x-7h3-response'
+
+export async function signResponse(
+  body: string,
+  opts: {
+    privateKey: string
+    sender: string
+    recipient?: string
+    correlationId?: string
+    ttlMs?: number
+  },
+): Promise<{ headers: { 'x-7h3-response': string } }> {
+  const envelope = createEnvelope({
+    sender: opts.sender,
+    recipient: opts.recipient,
+    intent: 'RESULT',
+    content: body,
+    correlationId: opts.correlationId,
+    ttlMs: opts.ttlMs ?? 60_000,
+  })
+
+  const signed = await signEnvelopeEd25519(envelope, opts.privateKey)
+
+  return {
+    headers: {
+      [RESPONSE_HEADER]: JSON.stringify(signed),
+    },
+  }
+}
+
+export async function verifyResponse(
+  body: string,
+  headers: Record<string, string | string[] | undefined>,
+  opts: {
+    publicKey: string
+    maxAgeMs?: number
+  },
+): Promise<{ ok: boolean; envelope?: ProtocolEnvelope; reason?: string }> {
+  const raw = headers[RESPONSE_HEADER]
+  const rawStr = Array.isArray(raw) ? raw[0] : raw
+  if (!rawStr) {
+    return { ok: false, reason: 'missing-header' }
+  }
+
+  let envelope: ProtocolEnvelope
+  try {
+    envelope = JSON.parse(rawStr) as ProtocolEnvelope
+  } catch {
+    return { ok: false, reason: 'malformed-envelope' }
+  }
+
+  // Check TTL from envelope
+  const nowMs = Date.now()
+  const { timestampMs, ttlMs } = envelope.header
+  if (timestampMs + ttlMs < nowMs) {
+    return { ok: false, reason: 'ttl-expired', envelope }
+  }
+
+  // Check maxAgeMs if provided
+  if (opts.maxAgeMs !== undefined && nowMs - timestampMs > opts.maxAgeMs) {
+    return { ok: false, reason: 'ttl-expired', envelope }
+  }
+
+  // Verify signature
+  const valid = await verifyEnvelopeEd25519(envelope, opts.publicKey)
+  if (!valid) {
+    return { ok: false, reason: 'invalid-signature', envelope }
+  }
+
+  // Verify body matches envelope content
+  if (envelope.body.content !== body) {
+    return { ok: false, reason: 'content-mismatch', envelope }
+  }
+
+  return { ok: true, envelope }
+}

package/src/webhookBinding.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect } from 'vitest'
+import {
+  signWebhook,
+  verifyWebhook,
+  signWebhookHmac,
+  verifyWebhookHmac,
+  consumeWebhook,
+  generateEd25519KeypairBase64Url,
+  WEBHOOK_SIG_HEADER,
+  WEBHOOK_TS_HEADER,
+} from './webhookBinding'
+
+describe('webhookBinding', () => {
+  // 1. Ed25519 sign + verify round trip
+  it('signWebhook + verifyWebhook round trip (Ed25519)', async () => {
+    const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
+    const payload = JSON.stringify({ event: 'user.created', userId: '123' })
+    const headers = await signWebhook(payload, { privateKey })
+    const valid = await verifyWebhook(payload, headers, { publicKey })
+    expect(valid).toBe(true)
+  })
+
+  // 2. HMAC sign + verify round trip
+  it('signWebhookHmac + verifyWebhookHmac round trip', async () => {
+    const secret = 'super-secret-webhook-key'
+    const payload = JSON.stringify({ event: 'order.paid', orderId: 'abc' })
+    const headers = await signWebhookHmac(payload, { secret })
+    const valid = await verifyWebhookHmac(payload, headers, { secret })
+    expect(valid).toBe(true)
+  })
+
+  // 3. Tampered payload returns false (Ed25519)
+  it('tampered payload returns false (Ed25519)', async () => {
+    const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
+    const payload = JSON.stringify({ event: 'user.created', userId: '123' })
+    const headers = await signWebhook(payload, { privateKey })
+    const tamperedPayload = JSON.stringify({ event: 'user.created', userId: '999' })
+    const valid = await verifyWebhook(tamperedPayload, headers, { publicKey })
+    expect(valid).toBe(false)
+  })
+
+  // 3b. Tampered payload returns false (HMAC)
+  it('tampered payload returns false (HMAC)', async () => {
+    const secret = 'super-secret-webhook-key'
+    const payload = JSON.stringify({ event: 'order.paid', orderId: 'abc' })
+    const headers = await signWebhookHmac(payload, { secret })
+    const tamperedPayload = JSON.stringify({ event: 'order.paid', orderId: 'TAMPERED' })
+    const valid = await verifyWebhookHmac(tamperedPayload, headers, { secret })
+    expect(valid).toBe(false)
+  })
+
+  // 4. Expired timestamp returns false
+  it('expired timestamp returns false', async () => {
+    const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
+    const payload = JSON.stringify({ event: 'ping' })
+    const headers = await signWebhook(payload, { privateKey })
+    // Backdate the timestamp to be 10 minutes ago
+    const expiredHeaders = {
+      ...headers,
+      [WEBHOOK_TS_HEADER]: String(Date.now() - 10 * 60 * 1000),
+    }
+    const valid = await verifyWebhook(payload, expiredHeaders, { publicKey, maxAgeMs: 300_000 })
+    expect(valid).toBe(false)
+  })
+
+  // 5. Wrong key returns false
+  it('wrong public key returns false', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const { publicKey: wrongPublicKey } = await generateEd25519KeypairBase64Url()
+    const payload = JSON.stringify({ event: 'test' })
+    const headers = await signWebhook(payload, { privateKey })
+    const valid = await verifyWebhook(payload, headers, { publicKey: wrongPublicKey })
+    expect(valid).toBe(false)
+  })
+
+  // 5b. Wrong HMAC secret returns false
+  it('wrong HMAC secret returns false', async () => {
+    const secret = 'correct-secret'
+    const payload = JSON.stringify({ event: 'test' })
+    const headers = await signWebhookHmac(payload, { secret })
+    const valid = await verifyWebhookHmac(payload, headers, { secret: 'wrong-secret' })
+    expect(valid).toBe(false)
+  })
+
+  // 6. consumeWebhook parses valid payload
+  it('consumeWebhook parses valid payload and returns parsed object', async () => {
+    const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
+    const data = { event: 'invoice.paid', amount: 9900, currency: 'usd' }
+    const payload = JSON.stringify(data)
+    const headers = await signWebhook(payload, { privateKey })
+    const result = await consumeWebhook<typeof data>(payload, headers as Record<string, string>, { publicKey })
+    expect(result).toEqual(data)
+  })
+
+  // 7. consumeWebhook throws on invalid signature
+  it('consumeWebhook throws on invalid signature', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const { publicKey: wrongPublicKey } = await generateEd25519KeypairBase64Url()
+    const payload = JSON.stringify({ event: 'invoice.paid' })
+    const headers = await signWebhook(payload, { privateKey })
+    await expect(
+      consumeWebhook(payload, headers as Record<string, string>, { publicKey: wrongPublicKey })
+    ).rejects.toThrow('7h3: webhook signature verification failed')
+  })
+
+  // 7b. consumeWebhook throws on expired timestamp
+  it('consumeWebhook throws on expired timestamp', async () => {
+    const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
+    const payload = JSON.stringify({ event: 'test' })
+    const headers = await signWebhook(payload, { privateKey })
+    const expiredHeaders = {
+      ...headers,
+      [WEBHOOK_TS_HEADER]: String(Date.now() - 10 * 60 * 1000),
+    }
+    await expect(
+      consumeWebhook(payload, expiredHeaders as Record<string, string>, { publicKey, maxAgeMs: 300_000 })
+    ).rejects.toThrow('7h3: webhook signature verification failed')
+  })
+
+  // Edge: missing headers return false
+  it('missing sig header returns false', async () => {
+    const { publicKey } = await generateEd25519KeypairBase64Url()
+    const payload = 'hello'
+    const valid = await verifyWebhook(payload, { [WEBHOOK_TS_HEADER]: String(Date.now()) } as Record<string, string>, { publicKey })
+    expect(valid).toBe(false)
+  })
+
+  it('missing ts header returns false', async () => {
+    const { publicKey } = await generateEd25519KeypairBase64Url()
+    const payload = 'hello'
+    const valid = await verifyWebhook(payload, { [WEBHOOK_SIG_HEADER]: 'fakesig' } as Record<string, string>, { publicKey })
+    expect(valid).toBe(false)
+  })
+
+  // Uint8Array payload works (Ed25519)
+  it('Uint8Array payload signs and verifies (Ed25519)', async () => {
+    const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
+    const payloadStr = JSON.stringify({ binary: true })
+    const payloadBytes = new TextEncoder().encode(payloadStr)
+    const headers = await signWebhook(payloadBytes, { privateKey })
+    const valid = await verifyWebhook(payloadBytes, headers, { publicKey })
+    expect(valid).toBe(true)
+  })
+})

package/src/webhookBinding.ts

@@ -0,0 +1,115 @@
+import {
+  signCanonicalPayloadEd25519,
+  verifyCanonicalPayloadEd25519,
+  signCanonicalPayloadHmac,
+  verifyCanonicalPayloadHmac,
+  generateEd25519KeypairBase64Url,
+} from './protocol'
+
+export const WEBHOOK_SIG_HEADER = 'x-7h3-sig'
+export const WEBHOOK_TS_HEADER = 'x-7h3-ts'
+export const WEBHOOK_DEFAULT_TTL_MS = 300_000  // 5 minutes
+
+// What gets signed: "${timestampMs}.${rawBody}" — binds time AND content
+function webhookSigningPayload(timestampMs: number, body: string): string {
+  return `${timestampMs}.${body}`
+}
+
+export interface WebhookSignOptions {
+  privateKey: string  // Ed25519 PKCS8 base64url
+  ttlMs?: number      // default 5 min
+}
+
+export interface WebhookSignHmacOptions {
+  secret: string
+  ttlMs?: number
+}
+
+export interface WebhookVerifyOptions {
+  publicKey: string   // Ed25519 SPKI base64url
+  maxAgeMs?: number   // default 5 min
+}
+
+export interface WebhookVerifyHmacOptions {
+  secret: string
+  maxAgeMs?: number
+}
+
+export interface WebhookHeaders {
+  [WEBHOOK_SIG_HEADER]: string
+  [WEBHOOK_TS_HEADER]: string
+}
+
+// Sign a webhook payload with Ed25519
+export async function signWebhook(
+  payload: string | Uint8Array,
+  opts: WebhookSignOptions
+): Promise<WebhookHeaders> {
+  const body = typeof payload === 'string' ? payload : new TextDecoder().decode(payload)
+  const timestampMs = Date.now()
+  const signingPayload = webhookSigningPayload(timestampMs, body)
+  const sig = await signCanonicalPayloadEd25519(signingPayload, opts.privateKey)
+  return { [WEBHOOK_SIG_HEADER]: sig, [WEBHOOK_TS_HEADER]: String(timestampMs) }
+}
+
+// Sign with HMAC shared secret
+export async function signWebhookHmac(
+  payload: string | Uint8Array,
+  opts: WebhookSignHmacOptions
+): Promise<WebhookHeaders> {
+  const body = typeof payload === 'string' ? payload : new TextDecoder().decode(payload)
+  const timestampMs = Date.now()
+  const signingPayload = webhookSigningPayload(timestampMs, body)
+  const sig = await signCanonicalPayloadHmac(signingPayload, opts.secret)
+  return { [WEBHOOK_SIG_HEADER]: sig, [WEBHOOK_TS_HEADER]: String(timestampMs) }
+}
+
+// Verify Ed25519 webhook signature
+export async function verifyWebhook(
+  payload: string | Uint8Array,
+  headers: WebhookHeaders | Record<string, string>,
+  opts: WebhookVerifyOptions
+): Promise<boolean> {
+  const body = typeof payload === 'string' ? payload : new TextDecoder().decode(payload)
+  const sig = headers[WEBHOOK_SIG_HEADER]
+  const tsStr = headers[WEBHOOK_TS_HEADER]
+  if (!sig || !tsStr) return false
+  const ts = Number(tsStr)
+  if (!Number.isFinite(ts)) return false
+  const maxAge = opts.maxAgeMs ?? WEBHOOK_DEFAULT_TTL_MS
+  if (Date.now() - ts > maxAge) return false
+  const signingPayload = webhookSigningPayload(ts, body)
+  return verifyCanonicalPayloadEd25519(signingPayload, sig, opts.publicKey)
+}
+
+// Verify HMAC webhook signature
+export async function verifyWebhookHmac(
+  payload: string | Uint8Array,
+  headers: WebhookHeaders | Record<string, string>,
+  opts: WebhookVerifyHmacOptions
+): Promise<boolean> {
+  const body = typeof payload === 'string' ? payload : new TextDecoder().decode(payload)
+  const sig = headers[WEBHOOK_SIG_HEADER]
+  const tsStr = headers[WEBHOOK_TS_HEADER]
+  if (!sig || !tsStr) return false
+  const ts = Number(tsStr)
+  if (!Number.isFinite(ts)) return false
+  const maxAge = opts.maxAgeMs ?? WEBHOOK_DEFAULT_TTL_MS
+  if (Date.now() - ts > maxAge) return false
+  const signingPayload = webhookSigningPayload(ts, body)
+  return verifyCanonicalPayloadHmac(signingPayload, sig, opts.secret)
+}
+
+// Parse and verify in one call, throws on failure
+export async function consumeWebhook<T = unknown>(
+  payload: string,
+  headers: Record<string, string>,
+  opts: WebhookVerifyOptions
+): Promise<T> {
+  const valid = await verifyWebhook(payload, headers, opts)
+  if (!valid) throw new Error('7h3: webhook signature verification failed')
+  return JSON.parse(payload) as T
+}
+
+// Re-export key generation for convenience
+export { generateEd25519KeypairBase64Url }

package/src/wsBinding.test.ts

@@ -0,0 +1,221 @@
+import { describe, it, expect, vi } from 'vitest'
+import { wrapWebSocket, generateEd25519KeypairBase64Url, type WebSocketLike } from './wsBinding'
+import { signEnvelopeEd25519, createEnvelope, type ProtocolEnvelope } from './protocol'
+import { createStaticKeyRegistry } from './keyRegistry'
+
+// Mock WebSocket class that buffers sent messages and lets you inject received messages
+class MockWebSocket implements WebSocketLike {
+  public sent: string[] = []
+  private messageHandlers: Array<(e: { data: string }) => void> = []
+  private closeHandlers: Array<() => void> = []
+  readyState = 1
+
+  send(data: string): void {
+    this.sent.push(data)
+  }
+
+  addEventListener(event: string, handler: (...args: any[]) => void): void {
+    if (event === 'message') {
+      this.messageHandlers.push(handler as (e: { data: string }) => void)
+    } else if (event === 'close') {
+      this.closeHandlers.push(handler as () => void)
+    }
+  }
+
+  removeEventListener(event: string, handler: (...args: unknown[]) => void): void {
+    if (event === 'message') {
+      const idx = this.messageHandlers.indexOf(handler as any)
+      if (idx !== -1) this.messageHandlers.splice(idx, 1)
+    } else if (event === 'close') {
+      const idx = this.closeHandlers.indexOf(handler as any)
+      if (idx !== -1) this.closeHandlers.splice(idx, 1)
+    }
+  }
+
+  // Inject a received message
+  receive(data: string): void {
+    for (const h of this.messageHandlers) h({ data })
+  }
+
+  close(): void {
+    for (const h of this.closeHandlers) h()
+  }
+}
+
+describe('wrapWebSocket', () => {
+  it('send() produces a signed JSON frame', async () => {
+    const keypair = await generateEd25519KeypairBase64Url()
+    const ws = new MockWebSocket()
+    const registry = createStaticKeyRegistry({ 'agent-A': keypair.publicKey })
+
+    const pws = wrapWebSocket(ws, {
+      privateKey: keypair.privateKey,
+      sender: 'agent-A',
+      keyRegistry: registry,
+    })
+
+    await pws.send({ hello: 'world' })
+
+    expect(ws.sent).toHaveLength(1)
+    const frame = JSON.parse(ws.sent[0]) as ProtocolEnvelope
+    expect(frame.header.sender).toBe('agent-A')
+    expect(frame.signature).toBeDefined()
+    expect(frame.signature?.alg).toBe('ED25519')
+    expect(frame.body.intent).toBe('TASK')
+    expect(frame.body.content).toBe(JSON.stringify({ hello: 'world' }))
+  })
+
+  it('incoming signed frame calls onMessage handler', async () => {
+    const keypair = await generateEd25519KeypairBase64Url()
+    const ws = new MockWebSocket()
+    const registry = createStaticKeyRegistry({ 'agent-B': keypair.publicKey })
+
+    const pws = wrapWebSocket(ws, {
+      privateKey: keypair.privateKey,
+      sender: 'agent-A',
+      keyRegistry: registry,
+    })
+
+    const received: Array<{ payload: unknown; envelope: ProtocolEnvelope }> = []
+    pws.onMessage((payload, envelope) => received.push({ payload, envelope }))
+
+    // Create a valid signed frame from agent-B
+    const envelope = createEnvelope({
+      sender: 'agent-B',
+      intent: 'TASK',
+      content: JSON.stringify({ ping: true }),
+      ttlMs: 30_000,
+    })
+    const signed = await signEnvelopeEd25519(envelope, keypair.privateKey)
+
+    // Wait for async message processing
+    await new Promise<void>(resolve => {
+      pws.onMessage(() => resolve())
+      ws.receive(JSON.stringify(signed))
+    })
+
+    expect(received).toHaveLength(1)
+    expect(received[0].payload).toEqual({ ping: true })
+    expect(received[0].envelope.header.sender).toBe('agent-B')
+  })
+
+  it('tampered frame calls onVerifyFail', async () => {
+    const keypair = await generateEd25519KeypairBase64Url()
+    const ws = new MockWebSocket()
+    const registry = createStaticKeyRegistry({ 'agent-B': keypair.publicKey })
+
+    const pws = wrapWebSocket(ws, {
+      privateKey: keypair.privateKey,
+      sender: 'agent-A',
+      keyRegistry: registry,
+    })
+
+    const errors: Error[] = []
+    pws.onVerifyFail((err) => errors.push(err))
+
+    // Create a valid signed frame, then tamper with body content
+    const envelope = createEnvelope({
+      sender: 'agent-B',
+      intent: 'TASK',
+      content: 'original content',
+      ttlMs: 30_000,
+    })
+    const signed = await signEnvelopeEd25519(envelope, keypair.privateKey)
+    // Tamper with content after signing
+    const tampered = { ...signed, body: { ...signed.body, content: 'tampered content' } }
+
+    await new Promise<void>(resolve => {
+      pws.onVerifyFail(() => resolve())
+      ws.receive(JSON.stringify(tampered))
+    })
+
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain('invalid signature')
+  })
+
+  it('unknown sender calls onVerifyFail', async () => {
+    const keypair = await generateEd25519KeypairBase64Url()
+    const ws = new MockWebSocket()
+    // Registry has no entry for 'unknown-agent'
+    const registry = createStaticKeyRegistry({})
+
+    const pws = wrapWebSocket(ws, {
+      privateKey: keypair.privateKey,
+      sender: 'agent-A',
+      keyRegistry: registry,
+    })
+
+    const errors: Error[] = []
+    pws.onVerifyFail((err) => errors.push(err))
+
+    const envelope = createEnvelope({
+      sender: 'unknown-agent',
+      intent: 'TASK',
+      content: 'hello',
+      ttlMs: 30_000,
+    })
+    const signed = await signEnvelopeEd25519(envelope, keypair.privateKey)
+
+    await new Promise<void>(resolve => {
+      pws.onVerifyFail(() => resolve())
+      ws.receive(JSON.stringify(signed))
+    })
+
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain('unknown sender')
+  })
+
+  it('malformed JSON calls onVerifyFail', async () => {
+    const keypair = await generateEd25519KeypairBase64Url()
+    const ws = new MockWebSocket()
+    const registry = createStaticKeyRegistry({})
+
+    const pws = wrapWebSocket(ws, {
+      privateKey: keypair.privateKey,
+      sender: 'agent-A',
+      keyRegistry: registry,
+    })
+
+    const errors: Error[] = []
+    pws.onVerifyFail((err) => errors.push(err))
+
+    await new Promise<void>(resolve => {
+      pws.onVerifyFail(() => resolve())
+      ws.receive('this is not valid JSON {{{')
+    })
+
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain('malformed frame')
+  })
+
+  it('seq increments on each send', async () => {
+    const keypair = await generateEd25519KeypairBase64Url()
+    const ws = new MockWebSocket()
+    const registry = createStaticKeyRegistry({ 'agent-A': keypair.publicKey })
+
+    const pws = wrapWebSocket(ws, {
+      privateKey: keypair.privateKey,
+      sender: 'agent-A',
+      keyRegistry: registry,
+    })
+
+    expect(pws.seq).toBe(0)
+
+    await pws.send('first')
+    expect(pws.seq).toBe(1)
+
+    await pws.send('second')
+    expect(pws.seq).toBe(2)
+
+    await pws.send('third')
+    expect(pws.seq).toBe(3)
+
+    // Verify correlationId carries the seq number
+    const frame1 = JSON.parse(ws.sent[0]) as ProtocolEnvelope
+    const frame2 = JSON.parse(ws.sent[1]) as ProtocolEnvelope
+    const frame3 = JSON.parse(ws.sent[2]) as ProtocolEnvelope
+    expect(frame1.body.correlationId).toBe('1')
+    expect(frame2.body.correlationId).toBe('2')
+    expect(frame3.body.correlationId).toBe('3')
+  })
+})