@7h3/protocol 0.5.0 → 0.5.2

package/src/cborCodec.ts

@@ -1,339 +0,0 @@
-/**
- * Minimal deterministic CBOR encoder/decoder — zero external dependencies.
- * Follows RFC 8949 §4.2 deterministic encoding:
- *   - Shortest-length integers
- *   - Map keys sorted by lexicographic byte order of encoded key
- */
-
-const textEncoder = new TextEncoder()
-const textDecoder = new TextDecoder()
-
-// CBOR major types
-const MT_UINT    = 0 // major type 0: unsigned int
-const MT_NINT    = 1 // major type 1: negative int
-const MT_BSTR    = 2 // major type 2: byte string
-const MT_TSTR    = 3 // major type 3: text string
-const MT_ARRAY   = 4 // major type 4: array
-const MT_MAP     = 5 // major type 5: map
-const MT_SIMPLE  = 7 // major type 7: simple/float
-
-const SIMPLE_FALSE  = 0xf4
-const SIMPLE_TRUE   = 0xf5
-const SIMPLE_NULL   = 0xf6
-
-// Additional info thresholds
-const AI_1BYTE  = 24
-const AI_2BYTE  = 25
-const AI_4BYTE  = 26
-const AI_8BYTE  = 27
-
-// float64 additional info
-const AI_FLOAT64 = 27
-
-export class CborEncoder {
-  private chunks: Uint8Array[] = []
-
-  encode(value: unknown): Uint8Array {
-    this.chunks = []
-    this._encode(value)
-    return this._concat()
-  }
-
-  private _encode(value: unknown): void {
-    if (value === null || value === undefined) {
-      this.chunks.push(new Uint8Array([SIMPLE_NULL]))
-      return
-    }
-    if (typeof value === 'boolean') {
-      this.chunks.push(new Uint8Array([value ? SIMPLE_TRUE : SIMPLE_FALSE]))
-      return
-    }
-    if (typeof value === 'number') {
-      this._encodeNumber(value)
-      return
-    }
-    if (typeof value === 'string') {
-      this._encodeString(value)
-      return
-    }
-    if (value instanceof Uint8Array) {
-      this._encodeByteString(value)
-      return
-    }
-    if (Array.isArray(value)) {
-      this._encodeArray(value)
-      return
-    }
-    if (value instanceof Map) {
-      // Keys can be numbers or strings
-      const entries = [...value.entries()] as Array<[unknown, unknown]>
-      this._encodeMapFromAnyEntries(entries)
-      return
-    }
-    if (typeof value === 'object') {
-      // Plain object: treat keys as strings
-      const entries = Object.entries(value as Record<string, unknown>)
-      this._encodeMapFromEntries(entries)
-      return
-    }
-    throw new Error(`CborEncoder: unsupported type: ${typeof value}`)
-  }
-
-  private _encodeNumber(value: number): void {
-    if (!Number.isFinite(value) || !Number.isInteger(value)) {
-      // float64
-      this.chunks.push(this._float64Header())
-      const buf = new ArrayBuffer(8)
-      new DataView(buf).setFloat64(0, value, false)
-      this.chunks.push(new Uint8Array(buf))
-      return
-    }
-    if (value >= 0) {
-      this._encodeHead(MT_UINT, value)
-    } else {
-      // negative: -1 - n encoded as n
-      this._encodeHead(MT_NINT, -1 - value)
-    }
-  }
-
-  private _float64Header(): Uint8Array {
-    return new Uint8Array([(MT_SIMPLE << 5) | AI_FLOAT64])
-  }
-
-  private _encodeString(value: string): void {
-    const bytes = textEncoder.encode(value)
-    this._encodeHead(MT_TSTR, bytes.length)
-    this.chunks.push(bytes)
-  }
-
-  private _encodeByteString(value: Uint8Array): void {
-    this._encodeHead(MT_BSTR, value.length)
-    this.chunks.push(value)
-  }
-
-  private _encodeArray(value: unknown[]): void {
-    this._encodeHead(MT_ARRAY, value.length)
-    for (const item of value) {
-      this._encode(item)
-    }
-  }
-
-  private _encodeMapFromAnyEntries(entries: Array<[unknown, unknown]>): void {
-    // Encode each key to bytes, then sort by lexicographic byte order of encoded key
-    const encoded: Array<{ keyEncoded: Uint8Array; key: unknown; value: unknown }> = entries.map(([k, v]) => {
-      let keyEncoded: Uint8Array
-      if (typeof k === 'number' && Number.isInteger(k)) {
-        keyEncoded = this._encodeHeadBytes(MT_UINT, k)
-      } else {
-        const keyBytes = textEncoder.encode(String(k))
-        const keyLenEncoded = this._encodeHeadBytes(MT_TSTR, keyBytes.length)
-        keyEncoded = this._concatPair(keyLenEncoded, keyBytes)
-      }
-      return { keyEncoded, key: k, value: v }
-    })
-
-    encoded.sort((a, b) => this._compareBytes(a.keyEncoded, b.keyEncoded))
-
-    this._encodeHead(MT_MAP, encoded.length)
-    for (const { key, value } of encoded) {
-      // Write key
-      if (typeof key === 'number' && Number.isInteger(key)) {
-        this._encodeHead(MT_UINT, key as number)
-      } else {
-        const keyBytes = textEncoder.encode(String(key))
-        this._encodeHead(MT_TSTR, keyBytes.length)
-        this.chunks.push(keyBytes)
-      }
-      // Write value
-      this._encode(value)
-    }
-  }
-
-  private _encodeMapFromEntries(entries: Array<[string, unknown]>): void {
-    // Deterministic: sort keys by UTF-8 byte order of encoded key
-    const encoded: Array<{ keyBytes: Uint8Array; keyEncoded: Uint8Array; value: unknown }> = entries.map(([k, v]) => {
-      const keyBytes = textEncoder.encode(k)
-      const keyLenEncoded = this._encodeHeadBytes(MT_TSTR, keyBytes.length)
-      const keyEncoded = this._concatPair(keyLenEncoded, keyBytes)
-      return { keyBytes, keyEncoded, value: v }
-    })
-
-    encoded.sort((a, b) => this._compareBytes(a.keyEncoded, b.keyEncoded))
-
-    this._encodeHead(MT_MAP, encoded.length)
-    for (const { keyBytes, value } of encoded) {
-      // Write key
-      this._encodeHead(MT_TSTR, keyBytes.length)
-      this.chunks.push(keyBytes)
-      // Write value
-      this._encode(value)
-    }
-  }
-
-  private _compareBytes(a: Uint8Array, b: Uint8Array): number {
-    const len = Math.min(a.length, b.length)
-    for (let i = 0; i < len; i++) {
-      const diff = (a[i] ?? 0) - (b[i] ?? 0)
-      if (diff !== 0) return diff
-    }
-    return a.length - b.length
-  }
-
-  private _concatPair(a: Uint8Array, b: Uint8Array): Uint8Array {
-    const result = new Uint8Array(a.length + b.length)
-    result.set(a, 0)
-    result.set(b, a.length)
-    return result
-  }
-
-  private _encodeHead(majorType: number, value: number): void {
-    this.chunks.push(this._encodeHeadBytes(majorType, value))
-  }
-
-  private _encodeHeadBytes(majorType: number, value: number): Uint8Array {
-    const mt = majorType << 5
-    if (value <= 23) {
-      return new Uint8Array([mt | value])
-    }
-    if (value <= 0xff) {
-      return new Uint8Array([mt | AI_1BYTE, value])
-    }
-    if (value <= 0xffff) {
-      const buf = new ArrayBuffer(3)
-      const dv = new DataView(buf)
-      dv.setUint8(0, mt | AI_2BYTE)
-      dv.setUint16(1, value, false)
-      return new Uint8Array(buf)
-    }
-    if (value <= 0xffffffff) {
-      const buf = new ArrayBuffer(5)
-      const dv = new DataView(buf)
-      dv.setUint8(0, mt | AI_4BYTE)
-      dv.setUint32(1, value, false)
-      return new Uint8Array(buf)
-    }
-    // 8-byte (for large numbers)
-    const buf = new ArrayBuffer(9)
-    const dv = new DataView(buf)
-    dv.setUint8(0, mt | AI_8BYTE)
-    dv.setBigUint64(1, BigInt(value), false)
-    return new Uint8Array(buf)
-  }
-
-  private _concat(): Uint8Array {
-    const total = this.chunks.reduce((sum, c) => sum + c.length, 0)
-    const result = new Uint8Array(total)
-    let offset = 0
-    for (const chunk of this.chunks) {
-      result.set(chunk, offset)
-      offset += chunk.length
-    }
-    return result
-  }
-}
-
-export class CborDecoder {
-  private data!: Uint8Array
-  private offset = 0
-
-  decode(data: Uint8Array): unknown {
-    this.data = data
-    this.offset = 0
-    const result = this._decode()
-    return result
-  }
-
-  private _decode(): unknown {
-    const initialByte = this._readByte()
-    const majorType = (initialByte >> 5) & 0x7
-    const additionalInfo = initialByte & 0x1f
-
-    switch (majorType) {
-      case MT_UINT:
-        return this._decodeUint(additionalInfo)
-      case MT_NINT:
-        return -1 - this._decodeUint(additionalInfo)
-      case MT_BSTR: {
-        const len = this._decodeUint(additionalInfo)
-        return this._readBytes(len)
-      }
-      case MT_TSTR: {
-        const len = this._decodeUint(additionalInfo)
-        const bytes = this._readBytes(len)
-        return textDecoder.decode(bytes)
-      }
-      case MT_ARRAY: {
-        const count = this._decodeUint(additionalInfo)
-        const result: unknown[] = []
-        for (let i = 0; i < count; i++) {
-          result.push(this._decode())
-        }
-        return result
-      }
-      case MT_MAP: {
-        const count = this._decodeUint(additionalInfo)
-        const result: Record<string, unknown> = {}
-        for (let i = 0; i < count; i++) {
-          const key = this._decode()
-          const value = this._decode()
-          result[String(key)] = value
-        }
-        return result
-      }
-      case MT_SIMPLE: {
-        if (additionalInfo === 20) return false  // 0xf4
-        if (additionalInfo === 21) return true   // 0xf5
-        if (additionalInfo === 22) return null   // 0xf6
-        if (additionalInfo === AI_FLOAT64) {
-          const bytes = this._readBytes(8)
-          return new DataView(bytes.buffer, bytes.byteOffset, 8).getFloat64(0, false)
-        }
-        throw new Error(`CborDecoder: unsupported simple value ${additionalInfo}`)
-      }
-      default:
-        throw new Error(`CborDecoder: unsupported major type ${majorType}`)
-    }
-  }
-
-  private _decodeUint(additionalInfo: number): number {
-    if (additionalInfo <= 23) return additionalInfo
-    if (additionalInfo === AI_1BYTE) return this._readByte()
-    if (additionalInfo === AI_2BYTE) {
-      const bytes = this._readBytes(2)
-      return new DataView(bytes.buffer, bytes.byteOffset, 2).getUint16(0, false)
-    }
-    if (additionalInfo === AI_4BYTE) {
-      const bytes = this._readBytes(4)
-      return new DataView(bytes.buffer, bytes.byteOffset, 4).getUint32(0, false)
-    }
-    if (additionalInfo === AI_8BYTE) {
-      const bytes = this._readBytes(8)
-      return Number(new DataView(bytes.buffer, bytes.byteOffset, 8).getBigUint64(0, false))
-    }
-    throw new Error(`CborDecoder: unsupported additional info ${additionalInfo}`)
-  }
-
-  private _readByte(): number {
-    if (this.offset >= this.data.length) {
-      throw new Error('CborDecoder: unexpected end of data')
-    }
-    return this.data[this.offset++] ?? 0
-  }
-
-  private _readBytes(count: number): Uint8Array {
-    if (this.offset + count > this.data.length) {
-      throw new Error('CborDecoder: unexpected end of data')
-    }
-    const result = this.data.slice(this.offset, this.offset + count)
-    this.offset += count
-    return result
-  }
-}
-
-export function encodeCbor(value: unknown): Uint8Array {
-  return new CborEncoder().encode(value)
-}
-
-export function decodeCbor(data: Uint8Array): unknown {
-  return new CborDecoder().decode(data)
-}

package/src/conformance.test.ts

@@ -1,136 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import {
-  canonicalizeEnvelope,
-  signCanonicalPayloadEd25519,
-  signCanonicalPayloadHmac,
-  signEnvelopeEd25519,
-  signEnvelopeHmac,
-  verifyCanonicalPayloadEd25519,
-  verifyCanonicalPayloadHmac,
-  verifyEnvelopeEd25519,
-  verifyEnvelopeHmac,
-} from './protocol'
-import { InMemoryReplayCache } from './protocolReplay'
-import { decodeEnvelope, encodeEnvelope, receiveEnvelope } from './protocolTransport'
-import { decodeEnvelopeBinary, encodeEnvelopeBinary } from './protocolBinary'
-import { AIP_V01_CONFORMANCE_VECTORS, AIP_V01_ED25519_CONFORMANCE_VECTORS } from './conformanceVectors'
-
-describe('AIP v0.1 conformance vectors', () => {
-  for (const vector of AIP_V01_CONFORMANCE_VECTORS) {
-    it(`${vector.id}: canonicalization and signatures match fixture`, async () => {
-      const canonical = canonicalizeEnvelope(vector.envelope)
-      expect(canonical).toBe(vector.canonical)
-
-      const signature = await signCanonicalPayloadHmac(canonical, vector.secret)
-      expect(signature).toBe(vector.signature)
-
-      const signed = await signEnvelopeHmac(vector.envelope, vector.secret, vector.keyId)
-      expect(signed.signature).toEqual({
-        alg: 'HS256',
-        keyId: vector.keyId,
-        value: vector.signature,
-      })
-
-      expect(await verifyCanonicalPayloadHmac(canonical, vector.signature, vector.secret)).toBe(true)
-      expect(await verifyEnvelopeHmac(signed, vector.secret)).toBe(true)
-      expect(await verifyEnvelopeHmac(signed, `${vector.secret}-wrong`)).toBe(false)
-    })
-
-    it(`${vector.id}: transport roundtrip and replay/ttl checks`, async () => {
-      const signed = await signEnvelopeHmac(vector.envelope, vector.secret, vector.keyId)
-      const encodedCompact = encodeEnvelope(signed, 'compact')
-      const decoded = decodeEnvelope(encodedCompact)
-      expect(decoded.ok).toBe(true)
-      expect(decoded.envelope).toEqual(signed)
-
-      const binary = encodeEnvelopeBinary(signed)
-      const decodedBinary = decodeEnvelopeBinary(binary)
-      expect(decodedBinary.ok).toBe(true)
-      expect(decodedBinary.envelope).toEqual(signed)
-
-      const replayCache = new InMemoryReplayCache()
-      const first = await receiveEnvelope(encodedCompact, {
-        nowMs: vector.envelope.header.timestampMs + 1,
-        replayCache,
-        secretResolver: async () => vector.secret,
-      })
-      expect(first.ok).toBe(true)
-
-      const replay = await receiveEnvelope(encodedCompact, {
-        nowMs: vector.envelope.header.timestampMs + 2,
-        replayCache,
-        secretResolver: async () => vector.secret,
-      })
-      expect(replay.ok).toBe(false)
-      expect(replay.diagnostics.some((d) => d.message.includes('Replay detected'))).toBe(true)
-
-      const expired = await receiveEnvelope(encodedCompact, {
-        nowMs: vector.envelope.header.timestampMs + vector.envelope.header.ttlMs + 1,
-        replayCache: new InMemoryReplayCache(),
-        secretResolver: async () => vector.secret,
-      })
-      expect(expired.ok).toBe(false)
-      expect(expired.diagnostics.some((d) => d.message === 'Message TTL expired')).toBe(true)
-    })
-  }
-
-  for (const vector of AIP_V01_ED25519_CONFORMANCE_VECTORS) {
-    it(`${vector.id}: canonicalization and Ed25519 signatures match fixture`, async () => {
-      const canonical = canonicalizeEnvelope(vector.envelope)
-      expect(canonical).toBe(vector.canonical)
-
-      const signature = await signCanonicalPayloadEd25519(canonical, vector.privateKey)
-      expect(signature).toBe(vector.signature)
-
-      const signed = await signEnvelopeEd25519(vector.envelope, vector.privateKey, vector.keyId)
-      expect(signed.signature).toEqual({
-        alg: 'ED25519',
-        keyId: vector.keyId,
-        value: vector.signature,
-      })
-
-      expect(await verifyCanonicalPayloadEd25519(canonical, vector.signature, vector.publicKey)).toBe(true)
-      expect(await verifyEnvelopeEd25519(signed, vector.publicKey)).toBe(true)
-
-      const tampered = {
-        ...signed,
-        body: {
-          ...signed.body,
-          content: `${signed.body.content}:tampered`,
-        },
-      }
-      expect(await verifyEnvelopeEd25519(tampered, vector.publicKey)).toBe(false)
-    })
-
-    it(`${vector.id}: transport verify via signatureResolver`, async () => {
-      const signed = await signEnvelopeEd25519(vector.envelope, vector.privateKey, vector.keyId)
-      const encodedCompact = encodeEnvelope(signed, 'compact')
-      const decoded = decodeEnvelope(encodedCompact)
-      expect(decoded.ok).toBe(true)
-      expect(decoded.envelope).toEqual(signed)
-
-      const binary = encodeEnvelopeBinary(signed)
-      const decodedBinary = decodeEnvelopeBinary(binary)
-      expect(decodedBinary.ok).toBe(true)
-      expect(decodedBinary.envelope).toEqual(signed)
-
-      const first = await receiveEnvelope(encodedCompact, {
-        nowMs: vector.envelope.header.timestampMs + 1,
-        replayCache: new InMemoryReplayCache(),
-        signatureResolver: async (signature, sender) =>
-          signature.alg === 'ED25519' && signature.keyId === vector.keyId && sender === vector.envelope.header.sender
-            ? { alg: 'ED25519', publicKey: vector.publicKey }
-            : undefined,
-      })
-      expect(first.ok).toBe(true)
-
-      const expired = await receiveEnvelope(encodedCompact, {
-        nowMs: vector.envelope.header.timestampMs + vector.envelope.header.ttlMs + 1,
-        replayCache: new InMemoryReplayCache(),
-        signatureResolver: async () => ({ alg: 'ED25519', publicKey: vector.publicKey }),
-      })
-      expect(expired.ok).toBe(false)
-      expect(expired.diagnostics.some((d) => d.message === 'Message TTL expired')).toBe(true)
-    })
-  }
-})

package/src/conformanceVectors.ts

@@ -1,99 +0,0 @@
-import type { ProtocolEnvelope } from './protocol'
-
-export interface ConformanceVector {
-  id: string
-  secret: string
-  keyId: string
-  envelope: Omit<ProtocolEnvelope, 'signature'>
-  canonical: string
-  signature: string
-}
-
-export interface Ed25519ConformanceVector {
-  id: string
-  keyId: string
-  publicKey: string
-  privateKey: string
-  envelope: Omit<ProtocolEnvelope, 'signature'>
-  canonical: string
-  signature: string
-}
-
-export const AIP_V01_CONFORMANCE_VECTORS: ConformanceVector[] = [
-  {
-    id: 'task-with-capability-and-recipient',
-    secret: 'vector-secret-1',
-    keyId: 'vector-key-1',
-    envelope: {
-      header: {
-        version: '7h3/0.1',
-        messageId: 'vec-1',
-        timestampMs: 1712500000000,
-        ttlMs: 60000,
-        sender: 'agent.alpha',
-        recipient: 'agent.beta',
-        nonce: 'nonce-vec-1',
-      },
-      body: {
-        intent: 'TASK',
-        content: 'route:alpha->beta',
-        capability: 'task.plan',
-        correlationId: 'corr-1',
-      },
-    },
-    canonical:
-      '{"body":{"capability":"task.plan","content":"route:alpha->beta","correlationId":"corr-1","intent":"TASK"},"header":{"messageId":"vec-1","nonce":"nonce-vec-1","recipient":"agent.beta","sender":"agent.alpha","timestampMs":1712500000000,"ttlMs":60000,"version":"7h3/0.1"}}',
-    signature: 'bZP1N1f4w4RGSKw6pfdcA6dQjvpv9nIHAQCttjNCZyI',
-  },
-  {
-    id: 'result-with-minimal-fields',
-    secret: 'vector-secret-2',
-    keyId: 'vector-key-2',
-    envelope: {
-      header: {
-        version: '7h3/0.1',
-        messageId: 'vec-2',
-        timestampMs: 1712500005000,
-        ttlMs: 30000,
-        sender: 'memory.agent',
-        nonce: 'nonce-vec-2',
-      },
-      body: {
-        intent: 'RESULT',
-        content: 'memory:ok',
-      },
-    },
-    canonical:
-      '{"body":{"content":"memory:ok","intent":"RESULT"},"header":{"messageId":"vec-2","nonce":"nonce-vec-2","sender":"memory.agent","timestampMs":1712500005000,"ttlMs":30000,"version":"7h3/0.1"}}',
-    signature: '_soWM4GZS8qWZDWyXEeXPaQp7Diyp2SQua9mKy2q0BQ',
-  },
-]
-
-export const AIP_V01_ED25519_CONFORMANCE_VECTORS: Ed25519ConformanceVector[] = [
-  {
-    id: 'task-ed25519-with-recipient',
-    keyId: 'ed-vector-key-1',
-    publicKey: 'MCowBQYDK2VwAyEA-mUFiTQtcKN4nnD19V_-Wyy4q19OivnAutRUPhOcC78',
-    privateKey: 'MC4CAQAwBQYDK2VwBCIEICheZbQGuDVb6hezIlcs0QnCHGxz6IhiLkC9M0qr8OOZ',
-    envelope: {
-      header: {
-        version: '7h3/0.1',
-        messageId: 'vec-ed-1',
-        timestampMs: 1712500010000,
-        ttlMs: 45000,
-        sender: 'agent.ed',
-        recipient: 'agent.verify',
-        nonce: 'nonce-ed-1',
-      },
-      body: {
-        intent: 'TASK',
-        content: 'route:ed25519',
-        capability: 'task.sign',
-        correlationId: 'corr-ed-1',
-      },
-    },
-    canonical:
-      '{"body":{"capability":"task.sign","content":"route:ed25519","correlationId":"corr-ed-1","intent":"TASK"},"header":{"messageId":"vec-ed-1","nonce":"nonce-ed-1","recipient":"agent.verify","sender":"agent.ed","timestampMs":1712500010000,"ttlMs":45000,"version":"7h3/0.1"}}',
-    signature: 'AAWu-6pp7NQZ-NtWKrgREWlMBx-kMZZzZ5dIiBqOdT-zdr-u4HtS6upE79yX7UUNPYUfyKs7lfssi0EeOvIxAA',
-  },
-]