@7h3/protocol 0.4.0 → 0.5.0

package/src/cborCodec.ts

@@ -0,0 +1,339 @@
+/**
+ * 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/encryption.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, it } from 'vitest'
+import { createEnvelope, generateEd25519KeypairBase64Url, type ProtocolBody } from './protocol.js'
+import {
+  decryptBody,
+  encryptBody,
+  generateX25519KeyPair,
+  openEnvelope,
+  sealEnvelope,
+} from './encryption.js'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeEnvelope(body: ProtocolBody) {
+  return createEnvelope({
+    sender: 'agent-alice',
+    recipient: 'agent-bob',
+    intent: body.intent,
+    content: body.content,
+    capability: body.capability,
+    correlationId: body.correlationId,
+    ttlMs: 60_000,
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('generateX25519KeyPair', () => {
+  it('returns 32-byte base64url keys (~43 chars, no padding)', () => {
+    const kp = generateX25519KeyPair()
+    // base64url of 32 bytes = ceil(32 * 4/3) = 43 chars (no padding)
+    expect(kp.publicKey).toMatch(/^[A-Za-z0-9_-]{43}$/)
+    expect(kp.privateKey).toMatch(/^[A-Za-z0-9_-]{43}$/)
+    // Decoded must be exactly 32 bytes
+    expect(Buffer.from(kp.publicKey, 'base64url').length).toBe(32)
+    expect(Buffer.from(kp.privateKey, 'base64url').length).toBe(32)
+  })
+})
+
+describe('sealEnvelope + openEnvelope', () => {
+  it('round-trip recovers original body exactly', async () => {
+    const recipientKp = generateX25519KeyPair()
+    const senderEd = await generateEd25519KeypairBase64Url()
+
+    const originalBody: ProtocolBody = {
+      intent: 'TASK',
+      content: 'Hello encrypted world!',
+      capability: 'some-cap',
+      correlationId: 'corr-123',
+    }
+    const envelope = makeEnvelope(originalBody)
+
+    const sealed = await sealEnvelope(envelope, {
+      recipientX25519PublicKey: recipientKp.publicKey,
+      senderEd25519PrivateKey: senderEd.privateKey,
+    })
+
+    const { body } = await openEnvelope(sealed, {
+      recipientX25519PrivateKey: recipientKp.privateKey,
+      senderEd25519PublicKey: senderEd.publicKey,
+    })
+
+    expect(body.intent).toBe(originalBody.intent)
+    expect(body.content).toBe(originalBody.content)
+    expect(body.capability).toBe(originalBody.capability)
+    expect(body.correlationId).toBe(originalBody.correlationId)
+  })
+
+  it('fails with wrong recipient private key (AEAD tag mismatch)', async () => {
+    const recipientKp = generateX25519KeyPair()
+    const wrongKp = generateX25519KeyPair()
+    const senderEd = await generateEd25519KeypairBase64Url()
+
+    // Sign with correct recipient public key but try to open with wrong private key
+    // To bypass the signature check we need to seal with wrongKp pubkey too,
+    // but the spec says "wrong recipient key" meaning sealed to correct pub key but opened with wrong priv.
+    const envelope = makeEnvelope({ intent: 'PING', content: 'secret' })
+    const sealed = await sealEnvelope(envelope, {
+      recipientX25519PublicKey: recipientKp.publicKey,
+      senderEd25519PrivateKey: senderEd.privateKey,
+    })
+
+    // We must tamper with the encrypted content to force the wrong key path,
+    // but the signature would fail. Instead, bypass openEnvelope and call decryptBody directly
+    // with the wrong key — which is what the spec tests.
+    expect(() => decryptBody(sealed.body.content, wrongKp.privateKey)).toThrow()
+  })
+
+  it('fails if envelope signature is tampered', async () => {
+    const recipientKp = generateX25519KeyPair()
+    const senderEd = await generateEd25519KeypairBase64Url()
+
+    const envelope = makeEnvelope({ intent: 'PING', content: 'secret' })
+    const sealed = await sealEnvelope(envelope, {
+      recipientX25519PublicKey: recipientKp.publicKey,
+      senderEd25519PrivateKey: senderEd.privateKey,
+    })
+
+    // Tamper with the signature value
+    const tampered = {
+      ...sealed,
+      signature: {
+        ...sealed.signature!,
+        value: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+      },
+    }
+
+    await expect(
+      openEnvelope(tampered, {
+        recipientX25519PrivateKey: recipientKp.privateKey,
+        senderEd25519PublicKey: senderEd.publicKey,
+      }),
+    ).rejects.toThrow('signature verification failed')
+  })
+
+  it('fails if ciphertext is tampered (AEAD auth tag fails)', async () => {
+    const recipientKp = generateX25519KeyPair()
+    const senderEd = await generateEd25519KeypairBase64Url()
+
+    const envelope = makeEnvelope({ intent: 'PING', content: 'secret' })
+    const sealed = await sealEnvelope(envelope, {
+      recipientX25519PublicKey: recipientKp.publicKey,
+      senderEd25519PrivateKey: senderEd.privateKey,
+    })
+
+    // Decode the encrypted payload, flip a bit in ciphertext, re-encode
+    const payloadJson = Buffer.from(sealed.body.content, 'base64url').toString('utf8')
+    const payload = JSON.parse(payloadJson) as { ephemeralPublic: string; nonce: string; ciphertext: string; tag: string }
+    const ctBuf = Buffer.from(payload.ciphertext, 'base64url')
+    ctBuf[0] ^= 0xff  // flip bits in first byte
+    const tamperedPayload = { ...payload, ciphertext: ctBuf.toString('base64url') }
+    const tamperedContent = Buffer.from(JSON.stringify(tamperedPayload), 'utf8').toString('base64url')
+
+    // We need to re-sign with the same key for the tamper to get past sig verification
+    // Instead: call decryptBody directly with tampered content
+    expect(() => decryptBody(tamperedContent, recipientKp.privateKey)).toThrow()
+  })
+
+  it('two sealEnvelope calls on same body produce different ciphertexts (ephemeral randomness)', async () => {
+    const recipientKp = generateX25519KeyPair()
+    const senderEd = await generateEd25519KeypairBase64Url()
+
+    const envelope1 = makeEnvelope({ intent: 'PING', content: 'same content' })
+    const envelope2 = makeEnvelope({ intent: 'PING', content: 'same content' })
+
+    const sealed1 = await sealEnvelope(envelope1, {
+      recipientX25519PublicKey: recipientKp.publicKey,
+      senderEd25519PrivateKey: senderEd.privateKey,
+    })
+    const sealed2 = await sealEnvelope(envelope2, {
+      recipientX25519PublicKey: recipientKp.publicKey,
+      senderEd25519PrivateKey: senderEd.privateKey,
+    })
+
+    // Different ephemeral keys + different nonces → different ciphertexts
+    expect(sealed1.body.content).not.toBe(sealed2.body.content)
+  })
+
+  it('encrypted content is opaque (does not contain original body.content as plaintext)', async () => {
+    const recipientKp = generateX25519KeyPair()
+    const senderEd = await generateEd25519KeypairBase64Url()
+
+    const originalContent = 'super-secret-data-12345'
+    const envelope = makeEnvelope({ intent: 'TASK', content: originalContent })
+
+    const sealed = await sealEnvelope(envelope, {
+      recipientX25519PublicKey: recipientKp.publicKey,
+      senderEd25519PrivateKey: senderEd.privateKey,
+    })
+
+    // The encrypted content blob should not contain the original plaintext string
+    const encryptedContentDecoded = Buffer.from(sealed.body.content, 'base64url').toString('utf8')
+    expect(encryptedContentDecoded).not.toContain(originalContent)
+    // Also raw base64url should not contain it
+    expect(sealed.body.content).not.toContain(originalContent)
+  })
+
+  it('encrypted envelope body has correct structure', async () => {
+    const recipientKp = generateX25519KeyPair()
+    const senderEd = await generateEd25519KeypairBase64Url()
+
+    const envelope = makeEnvelope({ intent: 'PING', content: 'test' })
+    const sealed = await sealEnvelope(envelope, {
+      recipientX25519PublicKey: recipientKp.publicKey,
+      senderEd25519PrivateKey: senderEd.privateKey,
+    })
+
+    expect(sealed.body.intent).toBe('ENCRYPTED')
+    expect(sealed.body.capability).toBe('x25519-chacha20poly1305')
+    expect(sealed.signature).toBeDefined()
+    expect(sealed.signature?.alg).toBe('ED25519')
+  })
+})
+
+describe('encryptBody + decryptBody', () => {
+  it('round-trips a body with all optional fields', () => {
+    const kp = generateX25519KeyPair()
+    const body: ProtocolBody = { intent: 'RESULT', content: 'data', capability: 'cap', correlationId: 'cid-42' }
+    const { encryptedContent } = encryptBody(body, kp.publicKey)
+    const decrypted = decryptBody(encryptedContent, kp.privateKey)
+    expect(decrypted).toEqual(body)
+  })
+})