@7h3/protocol 0.5.0 → 0.5.2

package/src/encryption.test.ts

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

package/src/encryption.ts

@@ -1,245 +0,0 @@
-/**
- * E2E Encryption for 7h3 Protocol
- *
- * Uses X25519 Diffie-Hellman key exchange + ChaCha20-Poly1305 AEAD.
- * All operations via Node.js built-in `node:crypto` — zero new dependencies.
- *
- * Architecture:
- *   EncryptedEnvelope = SignedEnvelope where body.content is a base64url-encoded
- *   EncryptedPayload, body.intent = 'ENCRYPTED', body.capability = 'x25519-chacha20poly1305'
- */
-
-import { createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes } from 'node:crypto'
-import type { KeyObject } from 'node:crypto'
-import {
-  signEnvelopeEd25519,
-  verifyEnvelopeEd25519,
-  type ProtocolBody,
-  type ProtocolEnvelope,
-} from './protocol.js'
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface X25519KeyPair {
-  /** Raw 32-byte X25519 public key, base64url-encoded (no padding) */
-  publicKey: string
-  /** Raw 32-byte X25519 private key, base64url-encoded (no padding) */
-  privateKey: string
-}
-
-export interface EncryptedPayload {
-  /** Ephemeral X25519 public key (base64url, raw 32 bytes) */
-  ephemeralPublic: string
-  /** ChaCha20 nonce / HKDF salt (base64url, 12 bytes) */
-  nonce: string
-  /** Ciphertext without auth tag (base64url) */
-  ciphertext: string
-  /** 16-byte Poly1305 auth tag (base64url) */
-  tag: string
-}
-
-// ---------------------------------------------------------------------------
-// Key helpers
-// ---------------------------------------------------------------------------
-
-function toBase64Url(buf: Buffer | Uint8Array): string {
-  return Buffer.from(buf).toString('base64url')
-}
-
-function fromBase64Url(s: string): Buffer {
-  return Buffer.from(s, 'base64url')
-}
-
-/**
- * X25519 PKCS8 DER header: 30 2e 02 01 00 30 05 06 03 2b 65 6e 04 22 04 20
- * (RFC 5958 / RFC 8410 encoding for X25519, OID 1.3.101.110 = 2b 65 6e)
- */
-const X25519_PKCS8_HEADER = Buffer.from('302e020100300506032b656e04220420', 'hex')
-
-/**
- * X25519 SPKI DER header: 30 2a 30 05 06 03 2b 65 6e 03 21 00
- * (RFC 5480 SubjectPublicKeyInfo for X25519)
- */
-const X25519_SPKI_HEADER = Buffer.from('302a300506032b656e032100', 'hex')
-
-function importX25519Private(privRaw32Base64Url: string): KeyObject {
-  const rawBytes = fromBase64Url(privRaw32Base64Url)
-  // Build PKCS8 DER: fixed 16-byte header + 32-byte raw private key
-  const der = Buffer.concat([X25519_PKCS8_HEADER, rawBytes])
-  return createPrivateKey({ key: der, format: 'der', type: 'pkcs8' })
-}
-
-function importX25519Public(pubRaw32Base64Url: string): KeyObject {
-  const rawBytes = fromBase64Url(pubRaw32Base64Url)
-  // Build SPKI DER: fixed 12-byte header + 32-byte raw public key
-  const der = Buffer.concat([X25519_SPKI_HEADER, rawBytes])
-  return createPublicKey({ key: der, format: 'der', type: 'spki' })
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Generate a fresh X25519 keypair.
- * Both keys are raw 32-byte values encoded as base64url (no padding).
- */
-export function generateX25519KeyPair(): X25519KeyPair {
-  const { privateKey, publicKey } = generateKeyPairSync('x25519')
-  const privJwk = privateKey.export({ format: 'jwk' }) as { d: string }
-  const pubJwk = publicKey.export({ format: 'jwk' }) as { x: string }
-  return {
-    publicKey: pubJwk.x,
-    privateKey: privJwk.d,
-  }
-}
-
-/**
- * Perform X25519 DH + HKDF-SHA256 to derive a 32-byte ChaCha20-Poly1305 key.
- *
- * @param privateKeyBase64Url  - raw 32-byte X25519 private key (base64url)
- * @param peerPublicKeyBase64Url - raw 32-byte X25519 public key (base64url)
- * @param nonce - raw 12-byte nonce (base64url); used as HKDF salt
- * @returns 32-byte Buffer ready for use with createCipheriv/createDecipheriv
- */
-export function deriveEncryptionKey(
-  privateKeyBase64Url: string,
-  peerPublicKeyBase64Url: string,
-  nonce: string,
-): Buffer {
-  const privKey = importX25519Private(privateKeyBase64Url)
-  const pubKey = importX25519Public(peerPublicKeyBase64Url)
-
-  const sharedSecret = diffieHellman({ privateKey: privKey, publicKey: pubKey })
-  const salt = fromBase64Url(nonce)
-  const info = Buffer.from('7h3-enc/1', 'utf8')
-
-  const derived = hkdfSync('sha256', sharedSecret, salt, info, 32)
-  return Buffer.from(derived)
-}
-
-/**
- * Encrypt a ProtocolBody with the recipient's X25519 public key.
- *
- * @returns encryptedContent (base64url-encoded EncryptedPayload JSON) and ephemeralPublic
- */
-export function encryptBody(
-  body: ProtocolBody,
-  recipientX25519PublicKey: string,
-): { encryptedContent: string; ephemeralPublic: string } {
-  // 1. Generate ephemeral X25519 keypair for forward secrecy
-  const ephemeral = generateX25519KeyPair()
-
-  // 2. Generate 12-byte ChaCha nonce (also used as HKDF salt)
-  const nonce12 = randomBytes(12)
-  const nonceBase64Url = toBase64Url(nonce12)
-
-  // 3. Derive encryption key
-  const key = deriveEncryptionKey(ephemeral.privateKey, recipientX25519PublicKey, nonceBase64Url)
-
-  // 4. Encrypt body as JSON
-  const plaintext = Buffer.from(JSON.stringify(body), 'utf8')
-  const cipher = createCipheriv('chacha20-poly1305', key, nonce12, { authTagLength: 16 })
-  const ciphertextBuf = Buffer.concat([cipher.update(plaintext), cipher.final()])
-  const tag = cipher.getAuthTag()
-
-  // 5. Build EncryptedPayload
-  const payload: EncryptedPayload = {
-    ephemeralPublic: ephemeral.publicKey,
-    nonce: nonceBase64Url,
-    ciphertext: toBase64Url(ciphertextBuf),
-    tag: toBase64Url(tag),
-  }
-
-  return {
-    encryptedContent: toBase64Url(Buffer.from(JSON.stringify(payload), 'utf8')),
-    ephemeralPublic: ephemeral.publicKey,
-  }
-}
-
-/**
- * Decrypt an encrypted ProtocolBody.
- *
- * @param encryptedContent - base64url-encoded EncryptedPayload
- * @param recipientX25519PrivateKey - raw 32-byte X25519 private key (base64url)
- * @returns decrypted ProtocolBody
- * @throws if AEAD tag verification fails
- */
-export function decryptBody(encryptedContent: string, recipientX25519PrivateKey: string): ProtocolBody {
-  const payloadJson = fromBase64Url(encryptedContent).toString('utf8')
-  const payload = JSON.parse(payloadJson) as EncryptedPayload
-
-  const { ephemeralPublic, nonce, ciphertext, tag } = payload
-
-  // Derive the same key using recipient's private key + ephemeral public key
-  const key = deriveEncryptionKey(recipientX25519PrivateKey, ephemeralPublic, nonce)
-
-  const nonce12 = fromBase64Url(nonce)
-  const ciphertextBuf = fromBase64Url(ciphertext)
-  const tagBuf = fromBase64Url(tag)
-
-  const decipher = createDecipheriv('chacha20-poly1305', key, nonce12, { authTagLength: 16 })
-  decipher.setAuthTag(tagBuf)
-
-  const plaintext = Buffer.concat([decipher.update(ciphertextBuf), decipher.final()])
-  return JSON.parse(plaintext.toString('utf8')) as ProtocolBody
-}
-
-/**
- * Encrypt and sign an envelope (full pipeline).
- *
- * The original body is encrypted; the envelope body is replaced with:
- *   { intent: 'ENCRYPTED', content: <encrypted-payload>, capability: 'x25519-chacha20poly1305' }
- * The modified envelope is then signed with Ed25519.
- */
-export async function sealEnvelope(
-  envelope: Omit<ProtocolEnvelope, 'signature'>,
-  opts: {
-    recipientX25519PublicKey: string
-    senderEd25519PrivateKey: string
-  },
-): Promise<ProtocolEnvelope> {
-  const { encryptedContent } = encryptBody(envelope.body, opts.recipientX25519PublicKey)
-
-  const encryptedEnvelope: Omit<ProtocolEnvelope, 'signature'> = {
-    header: envelope.header,
-    body: {
-      intent: 'ENCRYPTED' as const,
-      content: encryptedContent,
-      capability: 'x25519-chacha20poly1305',
-      correlationId: envelope.body.correlationId,
-    },
-  }
-
-  // Sign the envelope containing the encrypted body
-  return signEnvelopeEd25519(encryptedEnvelope, opts.senderEd25519PrivateKey)
-}
-
-/**
- * Verify signature and decrypt an envelope (full pipeline).
- *
- * Signature is verified FIRST; decryption only proceeds if valid.
- *
- * @returns The signed envelope (with encrypted body) and the decrypted original body
- * @throws if Ed25519 signature invalid or AEAD tag fails
- */
-export async function openEnvelope(
-  envelope: ProtocolEnvelope,
-  opts: {
-    recipientX25519PrivateKey: string
-    senderEd25519PublicKey: string
-  },
-): Promise<{ envelope: ProtocolEnvelope; body: ProtocolBody }> {
-  // 1. Verify Ed25519 signature FIRST — reject before decrypting
-  const valid = await verifyEnvelopeEd25519(envelope, opts.senderEd25519PublicKey)
-  if (!valid) {
-    throw new Error('7h3/encryption: Ed25519 signature verification failed')
-  }
-
-  // 2. Decrypt body
-  const body = decryptBody(envelope.body.content, opts.recipientX25519PrivateKey)
-
-  return { envelope, body }
-}

package/src/envelopeCbor.ts

@@ -1,140 +0,0 @@
-/**
- * Higher-level CBOR codec for ProtocolEnvelope.
- * Uses numeric field keys for maximum compactness.
- *
- * Envelope map structure:
- *   1 → header map
- *   2 → body map
- *   3 → signature map (omitted if no signature)
- *
- * Header map:
- *   1 → version (string)
- *   2 → messageId (string)
- *   3 → timestampMs (int)
- *   4 → ttlMs (int)
- *   5 → sender (string)
- *   6 → recipient (string, omit if absent)
- *   7 → nonce (string)
- *
- * Body map:
- *   1 → intent (string)
- *   2 → content (string)
- *   3 → capability (string, omit if absent)
- *   4 → correlationId (string, omit if absent)
- *
- * Signature map:
- *   1 → alg (string)
- *   2 → keyId (string)
- *   3 → value (string — base64url signature)
- */
-
-import type { ProtocolEnvelope, ProtocolSignature } from './protocol'
-import { encodeCbor, decodeCbor } from './cborCodec'
-
-export const CBOR_CONTENT_TYPE = 'application/7h3-cbor'
-
-export function encodeEnvelopeCbor(env: ProtocolEnvelope): Uint8Array {
-  // Build header map
-  const headerMap = new Map<number, unknown>()
-  headerMap.set(1, env.header.version)
-  headerMap.set(2, env.header.messageId)
-  headerMap.set(3, env.header.timestampMs)
-  headerMap.set(4, env.header.ttlMs)
-  headerMap.set(5, env.header.sender)
-  if (env.header.recipient !== undefined) {
-    headerMap.set(6, env.header.recipient)
-  }
-  headerMap.set(7, env.header.nonce)
-
-  // Build body map
-  const bodyMap = new Map<number, unknown>()
-  bodyMap.set(1, env.body.intent)
-  bodyMap.set(2, env.body.content)
-  if (env.body.capability !== undefined) {
-    bodyMap.set(3, env.body.capability)
-  }
-  if (env.body.correlationId !== undefined) {
-    bodyMap.set(4, env.body.correlationId)
-  }
-
-  // Build top-level map
-  const topMap = new Map<number, unknown>()
-  topMap.set(1, headerMap)
-  topMap.set(2, bodyMap)
-
-  const sig = env.signature
-  if (sig) {
-    const sigMap = new Map<number, unknown>()
-    sigMap.set(1, sig.alg)
-    sigMap.set(2, sig.keyId)
-    sigMap.set(3, sig.value)
-    topMap.set(3, sigMap)
-  }
-
-  return encodeCbor(topMap)
-}
-
-export function decodeEnvelopeCbor(data: Uint8Array): ProtocolEnvelope {
-  const top = decodeCbor(data)
-
-  if (!top || typeof top !== 'object' || Array.isArray(top)) {
-    throw new Error('decodeEnvelopeCbor: expected a map at top level')
-  }
-
-  const topRecord = top as Record<string, unknown>
-
-  // Header
-  const headerRaw = topRecord['1']
-  if (!headerRaw || typeof headerRaw !== 'object' || Array.isArray(headerRaw)) {
-    throw new Error('decodeEnvelopeCbor: missing header map (key 1)')
-  }
-  const hr = headerRaw as Record<string, unknown>
-
-  // Body
-  const bodyRaw = topRecord['2']
-  if (!bodyRaw || typeof bodyRaw !== 'object' || Array.isArray(bodyRaw)) {
-    throw new Error('decodeEnvelopeCbor: missing body map (key 2)')
-  }
-  const br = bodyRaw as Record<string, unknown>
-
-  const env: ProtocolEnvelope = {
-    header: {
-      version: hr['1'] as ProtocolEnvelope['header']['version'],
-      messageId: hr['2'] as string,
-      timestampMs: hr['3'] as number,
-      ttlMs: hr['4'] as number,
-      sender: hr['5'] as string,
-      nonce: hr['7'] as string,
-    },
-    body: {
-      intent: br['1'] as ProtocolEnvelope['body']['intent'],
-      content: br['2'] as string,
-    },
-  }
-
-  if (hr['6'] !== undefined) {
-    env.header.recipient = hr['6'] as string
-  }
-  if (br['3'] !== undefined) {
-    env.body.capability = br['3'] as string
-  }
-  if (br['4'] !== undefined) {
-    env.body.correlationId = br['4'] as string
-  }
-
-  // Signature
-  const sigRaw = topRecord['3']
-  if (sigRaw !== undefined && sigRaw !== null) {
-    if (typeof sigRaw !== 'object' || Array.isArray(sigRaw)) {
-      throw new Error('decodeEnvelopeCbor: expected signature map at key 3')
-    }
-    const sr = sigRaw as Record<string, unknown>
-    env.signature = {
-      alg: sr['1'] as ProtocolSignature['alg'],
-      keyId: sr['2'] as string,
-      value: sr['3'] as string,
-    }
-  }
-
-  return env
-}