@7h3/protocol 0.4.0 → 0.5.1

package/src/protocolTransport.ts

@@ -1,483 +0,0 @@
-import {
-  createEnvelope,
-  signEnvelopeHmac,
-  validateEnvelope,
-  canonicalizeEnvelope,
-  verifyCanonicalPayloadSignature,
-  type SignatureVerificationMaterial,
-  type IntentKind,
-  type ProtocolDiagnostic,
-  type ProtocolEnvelope,
-} from './protocol'
-import { decodeEnvelopeBinary, encodeEnvelopeBinary } from './protocolBinary'
-import { InMemoryReplayCache, type ReplayCache } from './protocolReplay'
-
-export type WireFormat = 'json' | 'compact' | 'binary'
-export type BatchWireFormat = Exclude<WireFormat, 'binary'>
-
-interface CompactSignature {
-  a?: 'HS256' | 'ED25519'
-  k: string
-  v: string
-}
-
-interface CompactEnvelope {
-  v: '7h3/0.1'
-  mid: string
-  ts: number
-  ttl: number
-  s: string
-  n: string
-  i: IntentKind
-  c: string
-  r?: string
-  cap?: string
-  cid?: string
-  sig?: CompactSignature
-}
-
-export interface ReceiveEnvelopeOptions {
-  nowMs?: number
-  requireSignature?: boolean
-  maxClockSkewMs?: number
-  replayCache?: ReplayCache
-  verificationMaterialCache?: VerificationMaterialCache
-  secretResolver?: (keyId: string, sender: string) => string | undefined | Promise<string | undefined>
-  signatureResolver?: (
-    signature: NonNullable<ProtocolEnvelope['signature']>,
-    sender: string,
-  ) => SignatureVerificationMaterial | undefined | Promise<SignatureVerificationMaterial | undefined>
-  telemetry?: (event: TransportTelemetryEvent) => void | Promise<void>
-}
-
-export interface ReceiveEnvelopeBatchOptions extends ReceiveEnvelopeOptions {
-  batchConcurrency?: number
-}
-
-export interface TransportTelemetryEvent {
-  phase:
-    | 'decoded'
-    | 'rejected_clock_skew'
-    | 'rejected_validation'
-    | 'rejected_replay'
-    | 'rejected_missing_signature'
-    | 'rejected_missing_material'
-    | 'rejected_bad_signature'
-    | 'batch_summary'
-    | 'accepted'
-  nowMs: number
-  sender?: string
-  messageId?: string
-  reason?: string
-}
-
-export interface ReceiveEnvelopeResult {
-  ok: boolean
-  diagnostics: ProtocolDiagnostic[]
-  envelope: ProtocolEnvelope | null
-}
-
-export interface VerificationMaterialCache {
-  get(key: string, nowMs?: number): SignatureVerificationMaterial | undefined
-  set(key: string, material: SignatureVerificationMaterial, expiresAtMs: number): void
-  delete?(key: string): void
-}
-
-export class InMemoryVerificationMaterialCache implements VerificationMaterialCache {
-  private readonly entries = new Map<string, { expiresAtMs: number; material: SignatureVerificationMaterial }>()
-
-  private readonly maxEntries: number
-
-  constructor(maxEntries = 512) {
-    this.maxEntries = maxEntries
-  }
-
-  get(key: string, nowMs = Date.now()): SignatureVerificationMaterial | undefined {
-    const entry = this.entries.get(key)
-    if (!entry) return undefined
-    if (entry.expiresAtMs <= nowMs) {
-      this.entries.delete(key)
-      return undefined
-    }
-    return entry.material
-  }
-
-  set(key: string, material: SignatureVerificationMaterial, expiresAtMs: number): void {
-    if (this.entries.size >= this.maxEntries) {
-      const oldest = this.entries.keys().next().value as string | undefined
-      if (oldest) this.entries.delete(oldest)
-    }
-    this.entries.set(key, { expiresAtMs, material })
-  }
-
-  delete(key: string): void {
-    this.entries.delete(key)
-  }
-}
-
-function verificationMaterialCacheKey(signature: NonNullable<ProtocolEnvelope['signature']>, sender: string): string {
-  return `${sender}|${signature.alg}|${signature.keyId}`
-}
-
-function isProtocolEnvelope(value: unknown): value is ProtocolEnvelope {
-  if (!value || typeof value !== 'object') return false
-  const candidate = value as Partial<ProtocolEnvelope>
-  return Boolean(candidate.header && candidate.body)
-}
-
-function isCompactEnvelope(value: unknown): value is CompactEnvelope {
-  if (!value || typeof value !== 'object') return false
-  const candidate = value as Partial<CompactEnvelope>
-  return candidate.v === '7h3/0.1' && typeof candidate.mid === 'string' && typeof candidate.i === 'string'
-}
-
-function compactToEnvelope(compact: CompactEnvelope): ProtocolEnvelope {
-  return {
-    header: {
-      version: compact.v,
-      messageId: compact.mid,
-      timestampMs: compact.ts,
-      ttlMs: compact.ttl,
-      sender: compact.s,
-      recipient: compact.r,
-      nonce: compact.n,
-    },
-    body: {
-      intent: compact.i,
-      content: compact.c,
-      capability: compact.cap,
-      correlationId: compact.cid,
-    },
-    signature: compact.sig
-      ? {
-          alg: compact.sig.a ?? 'HS256',
-          keyId: compact.sig.k,
-          value: compact.sig.v,
-        }
-      : undefined,
-  }
-}
-
-function envelopeToCompact(envelope: ProtocolEnvelope): CompactEnvelope {
-  return {
-    v: envelope.header.version,
-    mid: envelope.header.messageId,
-    ts: envelope.header.timestampMs,
-    ttl: envelope.header.ttlMs,
-    s: envelope.header.sender,
-    r: envelope.header.recipient,
-    n: envelope.header.nonce,
-    i: envelope.body.intent,
-    c: envelope.body.content,
-    cap: envelope.body.capability,
-    cid: envelope.body.correlationId,
-    sig: envelope.signature
-      ? {
-          a: envelope.signature.alg,
-          k: envelope.signature.keyId,
-          v: envelope.signature.value,
-        }
-      : undefined,
-  }
-}
-
-export type WireEnvelope = string | Uint8Array
-
-export function decodeEnvelope(raw: WireEnvelope): ReceiveEnvelopeResult {
-  if (raw instanceof Uint8Array) {
-    return decodeEnvelopeBinary(raw)
-  }
-
-  try {
-    const parsed = JSON.parse(raw) as unknown
-    if (isCompactEnvelope(parsed)) {
-      return { ok: true, diagnostics: [], envelope: compactToEnvelope(parsed) }
-    }
-    if (isProtocolEnvelope(parsed)) {
-      return { ok: true, diagnostics: [], envelope: parsed }
-    }
-    return {
-      ok: false,
-      diagnostics: [{ level: 'error', message: 'Envelope JSON shape is not recognized' }],
-      envelope: null,
-    }
-  } catch {
-    return {
-      ok: false,
-      diagnostics: [{ level: 'error', message: 'Invalid JSON envelope' }],
-      envelope: null,
-    }
-  }
-}
-
-export function encodeEnvelope(envelope: ProtocolEnvelope, format: 'binary'): Uint8Array
-export function encodeEnvelope(envelope: ProtocolEnvelope, format?: 'json' | 'compact'): string
-export function encodeEnvelope(envelope: ProtocolEnvelope, format: WireFormat): WireEnvelope
-export function encodeEnvelope(envelope: ProtocolEnvelope, format: WireFormat = 'json'): WireEnvelope {
-  if (format === 'binary') {
-    return encodeEnvelopeBinary(envelope)
-  }
-  if (format === 'compact') {
-    return JSON.stringify(envelopeToCompact(envelope))
-  }
-  return JSON.stringify(envelope)
-}
-
-export function encodeEnvelopeBatch(envelopes: ProtocolEnvelope[], format: BatchWireFormat = 'compact'): string {
-  if (format === 'compact') {
-    return JSON.stringify(envelopes.map(envelopeToCompact))
-  }
-  return JSON.stringify(envelopes)
-}
-
-export function decodeEnvelopeBatch(raw: string): ReceiveEnvelopeResult[] {
-  try {
-    const parsed = JSON.parse(raw) as unknown
-    if (!Array.isArray(parsed)) {
-      return [
-        {
-          ok: false,
-          diagnostics: [{ level: 'error', message: 'Batch payload must be a JSON array' }],
-          envelope: null,
-        },
-      ]
-    }
-
-    return parsed.map((entry): ReceiveEnvelopeResult => {
-      if (isCompactEnvelope(entry)) {
-        return { ok: true, diagnostics: [], envelope: compactToEnvelope(entry) }
-      }
-      if (isProtocolEnvelope(entry)) {
-        return { ok: true, diagnostics: [], envelope: entry }
-      }
-      return {
-        ok: false,
-        diagnostics: [{ level: 'error', message: 'Batch item has unrecognized envelope shape' }],
-        envelope: null,
-      }
-    })
-  } catch {
-    return [
-      {
-        ok: false,
-        diagnostics: [{ level: 'error', message: 'Invalid JSON batch payload' }],
-        envelope: null,
-      },
-    ]
-  }
-}
-
-export async function receiveEnvelope(
-  input: WireEnvelope | ProtocolEnvelope,
-  options: ReceiveEnvelopeOptions = {},
-): Promise<ReceiveEnvelopeResult> {
-  const nowMs = options.nowMs ?? Date.now()
-  const requireSignature = options.requireSignature ?? true
-  const maxClockSkewMs = options.maxClockSkewMs ?? 30_000
-
-  async function emitTelemetry(event: Omit<TransportTelemetryEvent, 'nowMs'>): Promise<void> {
-    if (!options.telemetry) return
-    await options.telemetry({
-      nowMs,
-      ...event,
-    })
-  }
-
-  const decoded = typeof input === 'string' || input instanceof Uint8Array ? decodeEnvelope(input) : { ok: true, diagnostics: [], envelope: input }
-  if (!decoded.ok || !decoded.envelope) return decoded
-
-  await emitTelemetry({
-    phase: 'decoded',
-    sender: decoded.envelope.header.sender,
-    messageId: decoded.envelope.header.messageId,
-  })
-
-  if (decoded.envelope.header.timestampMs > nowMs + maxClockSkewMs) {
-    const message = 'Message timestamp exceeds allowed clock skew'
-    const diagnostics: ProtocolDiagnostic[] = [{ level: 'error', message }]
-    await emitTelemetry({
-      phase: 'rejected_clock_skew',
-      sender: decoded.envelope.header.sender,
-      messageId: decoded.envelope.header.messageId,
-      reason: message,
-    })
-    return { ok: false, diagnostics, envelope: decoded.envelope }
-  }
-
-  const diagnostics: ProtocolDiagnostic[] = [...validateEnvelope(decoded.envelope, nowMs)]
-  if (diagnostics.some((d) => d.level === 'error')) {
-    await emitTelemetry({
-      phase: 'rejected_validation',
-      sender: decoded.envelope.header.sender,
-      messageId: decoded.envelope.header.messageId,
-      reason: diagnostics.find((d) => d.level === 'error')?.message,
-    })
-    return { ok: false, diagnostics, envelope: decoded.envelope }
-  }
-
-  if (!decoded.envelope.signature) {
-    if (requireSignature) {
-      diagnostics.push({ level: 'error', message: 'Missing signature' })
-      await emitTelemetry({
-        phase: 'rejected_missing_signature',
-        sender: decoded.envelope.header.sender,
-        messageId: decoded.envelope.header.messageId,
-        reason: 'Missing signature',
-      })
-      return { ok: false, diagnostics, envelope: decoded.envelope }
-    }
-    await emitTelemetry({
-      phase: 'accepted',
-      sender: decoded.envelope.header.sender,
-      messageId: decoded.envelope.header.messageId,
-    })
-    return { ok: true, diagnostics, envelope: decoded.envelope }
-  }
-
-  let verificationMaterial: SignatureVerificationMaterial | undefined
-  const signature = decoded.envelope.signature
-  const cacheKey = verificationMaterialCacheKey(signature, decoded.envelope.header.sender)
-  if (options.verificationMaterialCache) {
-    verificationMaterial = options.verificationMaterialCache.get(cacheKey, nowMs)
-  }
-
-  if (options.signatureResolver) {
-    verificationMaterial =
-      verificationMaterial ?? (await options.signatureResolver(signature, decoded.envelope.header.sender))
-  }
-
-  if (!verificationMaterial && signature.alg === 'HS256' && options.secretResolver) {
-    const secret = await options.secretResolver(signature.keyId, decoded.envelope.header.sender)
-    if (secret) {
-      verificationMaterial = { alg: 'HS256', secret }
-    }
-  }
-
-  if (verificationMaterial && options.verificationMaterialCache) {
-    const expiresAtMs = Math.max(nowMs + 1, decoded.envelope.header.timestampMs + decoded.envelope.header.ttlMs)
-    options.verificationMaterialCache.set(cacheKey, verificationMaterial, expiresAtMs)
-  }
-
-  if (!verificationMaterial) {
-    diagnostics.push({ level: 'error', message: 'No signature verification material found for keyId/sender' })
-    await emitTelemetry({
-      phase: 'rejected_missing_material',
-      sender: decoded.envelope.header.sender,
-      messageId: decoded.envelope.header.messageId,
-      reason: 'No signature verification material found for keyId/sender',
-    })
-    return { ok: false, diagnostics, envelope: decoded.envelope }
-  }
-
-  const canonicalPayload = canonicalizeEnvelope({ header: decoded.envelope.header, body: decoded.envelope.body })
-  const isValid = await verifyCanonicalPayloadSignature(canonicalPayload, decoded.envelope.signature, verificationMaterial)
-  if (!isValid) {
-    diagnostics.push({ level: 'error', message: 'Signature verification failed' })
-    await emitTelemetry({
-      phase: 'rejected_bad_signature',
-      sender: decoded.envelope.header.sender,
-      messageId: decoded.envelope.header.messageId,
-      reason: 'Signature verification failed',
-    })
-    return { ok: false, diagnostics, envelope: decoded.envelope }
-  }
-
-  if (options.replayCache) {
-    const replay = await options.replayCache.consume(decoded.envelope, nowMs)
-    if (!replay.ok) {
-      diagnostics.push({ level: 'error', message: replay.reason ?? 'Replay detected' })
-      await emitTelemetry({
-        phase: 'rejected_replay',
-        sender: decoded.envelope.header.sender,
-        messageId: decoded.envelope.header.messageId,
-        reason: replay.reason,
-      })
-      return { ok: false, diagnostics, envelope: decoded.envelope }
-    }
-  }
-
-  await emitTelemetry({
-    phase: 'accepted',
-    sender: decoded.envelope.header.sender,
-    messageId: decoded.envelope.header.messageId,
-  })
-
-  return { ok: true, diagnostics, envelope: decoded.envelope }
-}
-
-export async function receiveEnvelopeBatch(
-  input: string | Array<WireEnvelope | ProtocolEnvelope>,
-  options: ReceiveEnvelopeBatchOptions = {},
-): Promise<ReceiveEnvelopeResult[]> {
-  const concurrency = Math.max(1, Math.floor(options.batchConcurrency ?? Number.POSITIVE_INFINITY))
-  const receiveItems = async (items: Array<WireEnvelope | ProtocolEnvelope | ReceiveEnvelopeResult>): Promise<ReceiveEnvelopeResult[]> => {
-    const results: ReceiveEnvelopeResult[] = new Array(items.length)
-    let nextIndex = 0
-    const workerCount = Number.isFinite(concurrency) ? Math.min(concurrency, items.length) : items.length
-    await Promise.all(
-      Array.from({ length: workerCount }, async () => {
-        while (nextIndex < items.length) {
-          const index = nextIndex
-          nextIndex += 1
-          const item = items[index]
-          if (item && typeof item === 'object' && 'ok' in item && 'diagnostics' in item && 'envelope' in item) {
-            results[index] = item
-          } else {
-            results[index] = await receiveEnvelope(item as WireEnvelope | ProtocolEnvelope, options)
-          }
-        }
-      }),
-    )
-    await options.telemetry?.({
-      phase: 'batch_summary',
-      nowMs: options.nowMs ?? Date.now(),
-      reason: `items=${items.length};accepted=${results.filter((result) => result?.ok).length}`,
-    })
-    return results
-  }
-
-  if (typeof input === 'string') {
-    const decoded = decodeEnvelopeBatch(input)
-    return receiveItems(decoded.map((item) => (item.ok && item.envelope ? item.envelope : item)))
-  }
-
-  return receiveItems(input)
-}
-
-export class SessionTransport {
-  private readonly options: ReceiveEnvelopeOptions
-
-  constructor(options: Omit<ReceiveEnvelopeOptions, 'replayCache'> & { replayCache?: ReplayCache } = {}) {
-    this.options = {
-      ...options,
-      replayCache: options.replayCache ?? new InMemoryReplayCache(),
-      verificationMaterialCache: options.verificationMaterialCache ?? new InMemoryVerificationMaterialCache(),
-    }
-  }
-
-  receive(input: WireEnvelope | ProtocolEnvelope, nowMs = Date.now()): Promise<ReceiveEnvelopeResult> {
-    return receiveEnvelope(input, { ...this.options, nowMs })
-  }
-
-  receiveBatch(input: string | Array<WireEnvelope | ProtocolEnvelope>, nowMs = Date.now()): Promise<ReceiveEnvelopeResult[]> {
-    return receiveEnvelopeBatch(input, { ...this.options, nowMs })
-  }
-}
-
-export async function createSignedMessage(input: {
-  sender: string
-  recipient?: string
-  intent: IntentKind
-  content: string
-  capability?: string
-  correlationId?: string
-  ttlMs?: number
-  messageId?: string
-  nonce?: string
-  nowMs?: number
-  secret: string
-  keyId?: string
-}): Promise<ProtocolEnvelope> {
-  const unsigned = createEnvelope(input)
-  return signEnvelopeHmac(unsigned, input.secret, input.keyId)
-}

package/src/queueBinding.test.ts

@@ -1,130 +0,0 @@
-import { describe, it, expect, beforeAll } from 'vitest'
-import { generateEd25519KeypairBase64Url } from './protocol'
-import { signQueueMessage, verifyQueueMessage, verifyQueueBatch } from './queueBinding'
-
-let publicKey: string
-let privateKey: string
-let altPublicKey: string
-let altPrivateKey: string
-
-beforeAll(async () => {
-  const kp = await generateEd25519KeypairBase64Url()
-  publicKey = kp.publicKey
-  privateKey = kp.privateKey
-
-  const alt = await generateEd25519KeypairBase64Url()
-  altPublicKey = alt.publicKey
-  altPrivateKey = alt.privateKey
-})
-
-describe('signQueueMessage + verifyQueueMessage', () => {
-  it('round trip with string payload', async () => {
-    const payload = 'hello queue'
-    const msg = await signQueueMessage(payload, { privateKey, sender: 'agent-a' })
-    const result = await verifyQueueMessage<string>(msg, { publicKey })
-    expect(result.payload).toBe(payload)
-    expect(result.envelope.header.sender).toBe('agent-a')
-    expect(result.envelope.body.intent).toBe('TASK')
-  })
-
-  it('round trip with object payload', async () => {
-    const payload = { task: 'do-something', priority: 5 }
-    const msg = await signQueueMessage(payload, { privateKey, sender: 'agent-b', recipient: 'agent-c' })
-    const result = await verifyQueueMessage<typeof payload>(msg, { publicKey })
-    expect(result.payload).toEqual(payload)
-    expect(result.envelope.header.recipient).toBe('agent-c')
-  })
-
-  it('uses default 1 hour TTL', async () => {
-    const msg = await signQueueMessage('ttl-test', { privateKey, sender: 'agent-a' })
-    const parsed = JSON.parse(msg)
-    expect(parsed.envelope.header.ttlMs).toBe(3_600_000)
-  })
-
-  it('respects custom ttlMs', async () => {
-    const msg = await signQueueMessage('ttl-custom', { privateKey, sender: 'agent-a', ttlMs: 7200000 })
-    const parsed = JSON.parse(msg)
-    expect(parsed.envelope.header.ttlMs).toBe(7200000)
-  })
-
-  it('throws on tampered message (modified payload)', async () => {
-    const msg = await signQueueMessage({ x: 1 }, { privateKey, sender: 'agent-a' })
-    const parsed = JSON.parse(msg)
-    // tamper with the envelope content
-    parsed.envelope.body.content = '{"x":999}'
-    const tampered = JSON.stringify(parsed)
-    await expect(verifyQueueMessage(tampered, { publicKey })).rejects.toThrow('signature verification failed')
-  })
-
-  it('throws on wrong public key', async () => {
-    const msg = await signQueueMessage('secure', { privateKey, sender: 'agent-a' })
-    await expect(verifyQueueMessage(msg, { publicKey: altPublicKey })).rejects.toThrow('signature verification failed')
-  })
-
-  it('throws on invalid JSON', async () => {
-    await expect(verifyQueueMessage('not-json', { publicKey })).rejects.toThrow('not valid JSON')
-  })
-
-  it('throws on missing envelope', async () => {
-    await expect(verifyQueueMessage(JSON.stringify({ payload: 'x' }), { publicKey })).rejects.toThrow(
-      'missing envelope',
-    )
-  })
-})
-
-describe('verifyQueueBatch', () => {
-  it('mixed valid/invalid returns correct ok/false results', async () => {
-    const valid1 = await signQueueMessage('msg1', { privateKey, sender: 'a' })
-    const valid2 = await signQueueMessage({ n: 2 }, { privateKey, sender: 'b' })
-    const invalid = 'garbage-json'
-
-    const results = await verifyQueueBatch<unknown>([valid1, invalid, valid2], { publicKey })
-    expect(results).toHaveLength(3)
-    expect(results[0].ok).toBe(true)
-    expect(results[1].ok).toBe(false)
-    expect(results[2].ok).toBe(true)
-
-    const failed = results[1]
-    if (!failed.ok) {
-      expect(failed.raw).toBe(invalid)
-      expect(failed.error).toBeTruthy()
-    }
-  })
-
-  it('all valid batch', async () => {
-    const messages = await Promise.all([
-      signQueueMessage('a', { privateKey, sender: 'x' }),
-      signQueueMessage('b', { privateKey, sender: 'y' }),
-      signQueueMessage('c', { privateKey, sender: 'z' }),
-    ])
-    const results = await verifyQueueBatch<string>(messages, { publicKey })
-    expect(results.every((r) => r.ok)).toBe(true)
-    const payloads = results.filter((r) => r.ok).map((r) => (r.ok ? r.payload : null))
-    expect(payloads).toEqual(['a', 'b', 'c'])
-  })
-
-  it('all invalid batch', async () => {
-    const messages = ['bad1', 'bad2', JSON.stringify({ payload: 'no-envelope' })]
-    const results = await verifyQueueBatch<string>(messages, { publicKey })
-    expect(results.every((r) => !r.ok)).toBe(true)
-    results.forEach((r, i) => {
-      if (!r.ok) {
-        expect(r.raw).toBe(messages[i])
-        expect(typeof r.error).toBe('string')
-      }
-    })
-  })
-
-  it('wrong key causes all-invalid for valid messages', async () => {
-    const messages = await Promise.all([
-      signQueueMessage('p', { privateKey, sender: 'a' }),
-      signQueueMessage('q', { privateKey, sender: 'b' }),
-    ])
-    const results = await verifyQueueBatch<string>(messages, { publicKey: altPublicKey })
-    expect(results.every((r) => !r.ok)).toBe(true)
-  })
-
-  it('never throws even if all messages are invalid', async () => {
-    await expect(verifyQueueBatch(['{}', 'nope', '{"envelope":null,"payload":1}'], { publicKey })).resolves.toBeDefined()
-  })
-})