@7h3/protocol 0.5.0 → 0.5.1

package/src/wsBinding.test.ts

@@ -1,221 +0,0 @@
-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')
-  })
-})

package/src/wsBinding.ts

@@ -1,200 +0,0 @@
-import {
-  signEnvelopeEd25519, verifyEnvelopeEd25519,
-  createEnvelope, validateEnvelope,
-  generateEd25519KeypairBase64Url, type ProtocolEnvelope
-} from './protocol'
-import type { KeyRegistry } from './keyRegistry'
-import {
-  SignedStreamWriter,
-  verifyStream,
-  decodeStreamChunk,
-  encodeStreamChunk,
-  type StreamSignerOpts,
-  type StreamVerifierOpts,
-  type StreamVerifyResult,
-  type StreamChunk,
-} from './stream'
-
-export { type KeyRegistry, generateEd25519KeypairBase64Url }
-export type { StreamSignerOpts, StreamVerifierOpts, StreamVerifyResult, StreamChunk }
-
-// Minimal WebSocket interface (works with browser WebSocket, ws library, etc.)
-export interface WebSocketLike {
-  send(data: string): void
-  addEventListener(event: 'message', handler: (e: { data: string | Buffer }) => void): void
-  addEventListener(event: 'close', handler: () => void): void
-  removeEventListener(event: string, handler: (...args: unknown[]) => void): void
-  readyState?: number
-}
-
-export interface WsBindingOptions {
-  privateKey: string
-  sender: string
-  recipient?: string
-  keyRegistry: KeyRegistry   // to look up peer public keys by sender ID
-  ttlMs?: number             // per-frame TTL, default 30_000
-  onVerifyFail?: (err: Error, rawData: string) => void
-}
-
-export interface ProtectedWebSocket {
-  // Send a payload — automatically signs it
-  send(payload: unknown): Promise<void>
-  // Register handler for verified incoming messages
-  onMessage(handler: (payload: unknown, envelope: ProtocolEnvelope) => void): void
-  // Register handler for verify failures (optional)
-  onVerifyFail(handler: (err: Error, rawData: string) => void): void
-  // Sequence number of last sent message
-  readonly seq: number
-}
-
-export function wrapWebSocket(ws: WebSocketLike, opts: WsBindingOptions): ProtectedWebSocket {
-  let seq = 0
-  const messageHandlers: Array<(payload: unknown, envelope: ProtocolEnvelope) => void> = []
-  const failHandlers: Array<(err: Error, rawData: string) => void> = []
-
-  function fireVerifyFail(err: Error, raw: string) {
-    opts.onVerifyFail?.(err, raw)
-    for (const h of failHandlers) h(err, raw)
-  }
-
-  // Listen for incoming frames
-  const messageListener = async (e: { data: string | Buffer }) => {
-    const raw = typeof e.data === 'string' ? e.data : e.data.toString('utf8')
-    let envelope: ProtocolEnvelope
-    try { envelope = JSON.parse(raw) as ProtocolEnvelope }
-    catch (err) { fireVerifyFail(new Error('malformed frame'), raw); return }
-
-    const sender = envelope?.header?.sender
-    if (!sender) { fireVerifyFail(new Error('missing sender'), raw); return }
-
-    const publicKey = await opts.keyRegistry.getPublicKey(sender)
-    if (!publicKey) { fireVerifyFail(new Error(`unknown sender: ${sender}`), raw); return }
-
-    const valid = await verifyEnvelopeEd25519(envelope, publicKey).catch(() => false)
-    if (!valid) { fireVerifyFail(new Error('invalid signature'), raw); return }
-
-    const diags = validateEnvelope(envelope)
-    if (diags.some(d => d.level === 'error')) {
-      fireVerifyFail(new Error(`envelope invalid: ${diags.map(d => d.message).join('; ')}`), raw)
-      return
-    }
-
-    let payload: unknown = envelope.body.content
-    try { payload = JSON.parse(envelope.body.content) } catch { /* keep as string */ }
-    for (const h of messageHandlers) h(payload, envelope)
-  }
-
-  ws.addEventListener('message', messageListener as any)
-  ws.addEventListener('close', () => {
-    ws.removeEventListener('message', messageListener as any)
-  })
-
-  return {
-    get seq() { return seq },
-    async send(payload: unknown): Promise<void> {
-      const content = typeof payload === 'string' ? payload : JSON.stringify(payload)
-      const envelope = createEnvelope({
-        sender: opts.sender,
-        recipient: opts.recipient,
-        ttlMs: opts.ttlMs ?? 30_000,
-        intent: 'TASK',
-        content,
-      })
-      // embed sequence number in correlationId to help downstream ordering
-      ;(envelope.body as any).correlationId = String(++seq)
-      const signed = await signEnvelopeEd25519(envelope, opts.privateKey)
-      ws.send(JSON.stringify(signed))
-    },
-    onMessage(handler) { messageHandlers.push(handler) },
-    onVerifyFail(handler) { failHandlers.push(handler) },
-  }
-}
-
-// ─────────────────── Stream signing over WebSocket ────────────────────────────
-
-/**
- * createSignedWebSocketStream
- *
- * Attaches a SignedStreamWriter to a WebSocket:
- *   - Each incoming WebSocket message is signed as a stream chunk and sent back.
- *   - On connection close, the final signed frame is sent.
- *
- * Returns the underlying SignedStreamWriter so callers can also call writeChunk
- * directly (e.g. when driving the stream from application code rather than
- * forwarding received messages).
- */
-export function createSignedWebSocketStream(
-  ws: WebSocketLike,
-  opts: StreamSignerOpts,
-): SignedStreamWriter {
-  const writer = new SignedStreamWriter(opts)
-
-  const messageListener = async (e: { data: string | Buffer }) => {
-    const data = typeof e.data === 'string' ? e.data : e.data.toString('utf8')
-    const chunk = await writer.writeChunk(data)
-    ws.send(encodeStreamChunk(chunk))
-  }
-
-  const closeListener = async () => {
-    ws.removeEventListener('message', messageListener as any)
-    ws.removeEventListener('close', closeListener as any)
-    const finalChunk = await writer.finalize()
-    ws.send(encodeStreamChunk(finalChunk))
-  }
-
-  ws.addEventListener('message', messageListener as any)
-  ws.addEventListener('close', closeListener as any)
-
-  return writer
-}
-
-/**
- * receiveSignedWebSocketStream
- *
- * Listens for StreamChunk JSON frames on a WebSocket, accumulates them, and
- * when the final frame (f=true) arrives calls verifyStream over the complete
- * set of collected chunks.
- *
- * Resolves with StreamVerifyResult when the final frame is received.
- * Rejects if a frame cannot be decoded.
- */
-export function receiveSignedWebSocketStream(
-  ws: WebSocketLike,
-  opts: StreamVerifierOpts,
-): Promise<StreamVerifyResult> {
-  return new Promise<StreamVerifyResult>((resolve, reject) => {
-    const collected: StreamChunk[] = []
-
-    const messageListener = async (e: { data: string | Buffer }) => {
-      const raw = typeof e.data === 'string' ? e.data : e.data.toString('utf8')
-      let chunk: StreamChunk
-      try {
-        chunk = decodeStreamChunk(raw)
-      } catch (err) {
-        cleanup()
-        reject(err)
-        return
-      }
-      collected.push(chunk)
-      if (chunk.f) {
-        cleanup()
-        const result = await verifyStream(collected, opts)
-        resolve(result)
-      }
-    }
-
-    const closeListener = () => {
-      // Connection closed before receiving final frame
-      cleanup()
-      resolve({ ok: false, reason: 'connection closed before final frame' })
-    }
-
-    function cleanup() {
-      ws.removeEventListener('message', messageListener as any)
-      ws.removeEventListener('close', closeListener as any)
-    }
-
-    ws.addEventListener('message', messageListener as any)
-    ws.addEventListener('close', closeListener as any)
-  })
-}

package/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "lib": ["ES2023", "DOM"],
-    "types": ["node"],
-    "strict": true,
-    "skipLibCheck": true,
-    "noEmit": true,
-    "esModuleInterop": true,
-    "verbatimModuleSyntax": false
-  },
-  "include": ["src/**/*.ts", "scripts/**/*.ts"]
-}

package/tsconfig.lib.json

@@ -1,23 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "declaration": true,
-    "emitDeclarationOnly": true,
-    "declarationMap": false,
-    "sourceMap": false,
-    "outDir": "./dist/protocol",
-    "rootDir": "./src",
-    "stripInternal": true,
-    "strict": true,
-    "types": ["node"],
-    "skipLibCheck": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedSideEffectImports": true
-  },
-  "include": ["src/**/*.ts"],
-  "exclude": ["src/**/*.test.ts", "src/**/*.bench.ts"]
-}

package/vite.lib.config.ts

@@ -1,16 +0,0 @@
-import { defineConfig } from 'vite'
-
-export default defineConfig({
-  build: {
-    lib: {
-      entry: 'src/index.ts',
-      formats: ['es'],
-      fileName: () => 'index.js',
-    },
-    outDir: 'dist/protocol',
-    emptyOutDir: false,
-    rollupOptions: {
-      external: [],
-    },
-  },
-})

package/vitest.config.ts

@@ -1,11 +0,0 @@
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    exclude: [
-      'sdk/pq/dist/**',
-      'sdk/threshold/dist/**',
-      '**/node_modules/**',
-    ],
-  },
-})