@7h3/protocol 0.4.0 → 0.5.0

package/src/capability.ts

@@ -0,0 +1,380 @@
+import {
+  generateEd25519KeypairBase64Url,
+  signCanonicalPayloadEd25519,
+  verifyCanonicalPayloadEd25519,
+} from './protocol'
+import { matchGlob } from './routePolicy'
+
+// Re-export for test convenience
+export { generateEd25519KeypairBase64Url }
+
+export interface CapabilityScope {
+  pathGlob: string
+  methods?: string[]
+  maxDelegations?: number
+}
+
+export interface CapabilityToken {
+  id: string
+  version: '7h3-cap/1'
+  issuer: string
+  subject: string
+  scopes: CapabilityScope[]
+  issuedAt: number
+  expiresAt: number
+  delegationDepth: number
+  parentTokenId?: string
+  /** How many more times this token can be re-delegated. undefined = unlimited, 0 = no further delegation. */
+  maxDelegations: number | undefined
+  signature: string
+  keyId: string
+}
+
+export type CapabilityVerifyResult =
+  | { ok: true; token: CapabilityToken; chain: CapabilityToken[] }
+  | { ok: false; reason: string }
+
+export const CAP_HEADER = 'x-7h3-capability'
+
+// ---------------------------------------------------------------------------
+// Canonicalization
+// ---------------------------------------------------------------------------
+
+function canonicalizeScope(scope: CapabilityScope): string {
+  const parts: string[] = []
+  if (scope.maxDelegations !== undefined) {
+    parts.push(`"maxDelegations":${scope.maxDelegations}`)
+  }
+  if (scope.methods !== undefined) {
+    parts.push(`"methods":${JSON.stringify(scope.methods)}`)
+  }
+  parts.push(`"pathGlob":${JSON.stringify(scope.pathGlob)}`)
+  return `{${parts.join(',')}}`
+}
+
+/**
+ * Deterministic canonical form for signing: alphabetically sorted top-level fields,
+ * each scope also sorted. The `signature` field is excluded.
+ */
+export function canonicalizeCapabilityToken(token: Omit<CapabilityToken, 'signature'>): string {
+  const parts: string[] = []
+
+  parts.push(`"delegationDepth":${token.delegationDepth}`)
+  parts.push(`"expiresAt":${token.expiresAt}`)
+  parts.push(`"id":${JSON.stringify(token.id)}`)
+  parts.push(`"issuedAt":${token.issuedAt}`)
+  parts.push(`"issuer":${JSON.stringify(token.issuer)}`)
+  parts.push(`"keyId":${JSON.stringify(token.keyId)}`)
+
+  if (token.maxDelegations !== undefined) {
+    parts.push(`"maxDelegations":${token.maxDelegations}`)
+  }
+
+  if (token.parentTokenId !== undefined) {
+    parts.push(`"parentTokenId":${JSON.stringify(token.parentTokenId)}`)
+  }
+
+  const scopesStr = `[${token.scopes.map(canonicalizeScope).join(',')}]`
+  parts.push(`"scopes":${scopesStr}`)
+
+  parts.push(`"subject":${JSON.stringify(token.subject)}`)
+  parts.push(`"version":${JSON.stringify(token.version)}`)
+
+  return `{${parts.join(',')}}`
+}
+
+// ---------------------------------------------------------------------------
+// Issue
+// ---------------------------------------------------------------------------
+
+export async function issueCapabilityToken(opts: {
+  issuerPrivateKey: string
+  issuerId: string
+  subject: string
+  scopes: CapabilityScope[]
+  ttlMs: number
+  maxDelegations?: number
+  keyId?: string
+}): Promise<CapabilityToken> {
+  const now = Date.now()
+  const id = `cap-${now}-${Math.random().toString(36).slice(2, 12)}`
+  const keyId = opts.keyId ?? `${opts.issuerId}-key`
+  const maxDelegations = opts.maxDelegations ?? 0
+
+  const unsigned: Omit<CapabilityToken, 'signature'> = {
+    id,
+    version: '7h3-cap/1',
+    issuer: opts.issuerId,
+    subject: opts.subject,
+    scopes: opts.scopes,
+    issuedAt: now,
+    expiresAt: now + opts.ttlMs,
+    delegationDepth: 0,
+    maxDelegations,
+    keyId,
+  }
+
+  const payload = canonicalizeCapabilityToken(unsigned)
+  const signature = await signCanonicalPayloadEd25519(payload, opts.issuerPrivateKey)
+
+  return { ...unsigned, signature }
+}
+
+// ---------------------------------------------------------------------------
+// Delegate
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether childScope is a subset of parentScope.
+ * - pathGlob: the parent must matchGlob the child's pathGlob literal (or the child's glob must be
+ *   at least as restrictive). We check that every path that matches child also matches parent by
+ *   testing the child pathGlob against the parent pathGlob pattern.
+ * - methods: parent undefined = any (child is allowed anything); child undefined = any =
+ *   broader than a defined parent → reject.
+ */
+function scopeIsSubset(child: CapabilityScope, parent: CapabilityScope): boolean {
+  // Path: child path must be covered by parent path pattern
+  if (!matchGlob(parent.pathGlob, child.pathGlob)) {
+    // Also try: child glob should be at most as broad as parent
+    // For glob subset we check that child's pathGlob matches under the parent glob pattern
+    // This covers the common case of /api/payments/** under /api/**
+    // We fall back: if parent.pathGlob doesn't match child.pathGlob directly,
+    // test by checking child is a "narrower" glob — just use matchGlob both ways
+    return false
+  }
+
+  // Methods: parent undefined = allows all; child must not exceed parent
+  if (parent.methods !== undefined) {
+    if (child.methods === undefined) {
+      // child wants all methods, parent is restricted — not a subset
+      return false
+    }
+    // Every child method must be in parent methods
+    for (const m of child.methods) {
+      if (!parent.methods.includes(m)) {
+        return false
+      }
+    }
+  }
+  // parent.methods === undefined → parent allows all; child can be anything
+
+  return true
+}
+
+function scopesAreSubset(childScopes: CapabilityScope[], parentScopes: CapabilityScope[]): boolean {
+  // Every child scope must be covered by at least one parent scope
+  for (const child of childScopes) {
+    const covered = parentScopes.some((parent) => scopeIsSubset(child, parent))
+    if (!covered) return false
+  }
+  return true
+}
+
+export async function delegateCapabilityToken(opts: {
+  parentToken: CapabilityToken
+  delegatorPrivateKey: string
+  delegatorId: string
+  newSubject: string
+  scopes?: CapabilityScope[]
+  ttlMs: number
+  keyId?: string
+}): Promise<CapabilityToken> {
+  const { parentToken, delegatorId, newSubject } = opts
+
+  // Validate delegator is parent token's subject
+  if (delegatorId !== parentToken.subject) {
+    throw new Error(`delegatorId '${delegatorId}' does not match parentToken.subject '${parentToken.subject}'`)
+  }
+
+  // Validate parent not expired
+  const now = Date.now()
+  if (now >= parentToken.expiresAt) {
+    throw new Error('Parent token is expired')
+  }
+
+  // Validate delegation is still allowed
+  if (parentToken.maxDelegations !== undefined && parentToken.maxDelegations <= 0) {
+    throw new Error('Parent token does not allow further delegation (maxDelegations=0)')
+  }
+
+  // Determine new scopes
+  const newScopes = opts.scopes ?? parentToken.scopes
+
+  // Validate new scopes are a subset of parent scopes
+  if (!scopesAreSubset(newScopes, parentToken.scopes)) {
+    throw new Error('Delegated scopes exceed parent token scopes')
+  }
+
+  // Validate TTL does not exceed parent remaining TTL
+  const parentRemainingMs = parentToken.expiresAt - now
+  if (opts.ttlMs > parentRemainingMs) {
+    throw new Error(
+      `Delegated ttlMs (${opts.ttlMs}) exceeds parent token remaining TTL (${parentRemainingMs})`,
+    )
+  }
+
+  const id = `cap-${now}-${Math.random().toString(36).slice(2, 12)}`
+  const keyId = opts.keyId ?? `${delegatorId}-key`
+
+  // Compute new maxDelegations: decrement from parent (undefined = unlimited stays unlimited)
+  const newMaxDelegations =
+    parentToken.maxDelegations === undefined ? undefined : parentToken.maxDelegations - 1
+
+  const unsigned: Omit<CapabilityToken, 'signature'> = {
+    id,
+    version: '7h3-cap/1',
+    issuer: delegatorId,
+    subject: newSubject,
+    scopes: newScopes,
+    issuedAt: now,
+    expiresAt: now + opts.ttlMs,
+    delegationDepth: parentToken.delegationDepth + 1,
+    parentTokenId: parentToken.id,
+    maxDelegations: newMaxDelegations,
+    keyId,
+  }
+
+  const payload = canonicalizeCapabilityToken(unsigned)
+  const signature = await signCanonicalPayloadEd25519(payload, opts.delegatorPrivateKey)
+
+  return { ...unsigned, signature }
+}
+
+// ---------------------------------------------------------------------------
+// Verify single token
+// ---------------------------------------------------------------------------
+
+export async function verifyCapabilityToken(
+  token: CapabilityToken,
+  publicKey: string,
+  opts?: { now?: number },
+): Promise<boolean> {
+  const now = opts?.now ?? Date.now()
+
+  // Check expiry
+  if (now >= token.expiresAt) {
+    return false
+  }
+
+  // Reconstruct unsigned form
+  const { signature, ...unsigned } = token
+
+  const payload = canonicalizeCapabilityToken(unsigned)
+  return verifyCanonicalPayloadEd25519(payload, signature, publicKey)
+}
+
+// ---------------------------------------------------------------------------
+// Verify chain
+// ---------------------------------------------------------------------------
+
+export async function verifyCapabilityChain(
+  chain: CapabilityToken[],
+  keyRegistry: { getPublicKey(id: string): Promise<string | null> },
+  opts?: { requiredPathGlob?: string; requiredMethod?: string; now?: number },
+): Promise<CapabilityVerifyResult> {
+  if (chain.length === 0) {
+    return { ok: false, reason: 'empty-chain' }
+  }
+
+  const now = opts?.now ?? Date.now()
+
+  // Verify each token in the chain
+  for (let i = 0; i < chain.length; i++) {
+    const token = chain[i]
+
+    // Structural check: root must have depth 0
+    if (i === 0 && token.delegationDepth !== 0) {
+      return { ok: false, reason: 'root-token-delegation-depth-must-be-zero' }
+    }
+
+    // Chain linkage: issuer of token[i] must be subject of token[i-1]
+    if (i > 0) {
+      const prev = chain[i - 1]
+      if (token.issuer !== prev.subject) {
+        return {
+          ok: false,
+          reason: `chain-broken: token[${i}].issuer '${token.issuer}' !== token[${i - 1}].subject '${prev.subject}'`,
+        }
+      }
+      if (token.parentTokenId !== prev.id) {
+        return {
+          ok: false,
+          reason: `chain-broken: token[${i}].parentTokenId '${token.parentTokenId}' !== token[${i - 1}].id '${prev.id}'`,
+        }
+      }
+      if (token.delegationDepth !== prev.delegationDepth + 1) {
+        return {
+          ok: false,
+          reason: `chain-broken: token[${i}].delegationDepth ${token.delegationDepth} !== ${prev.delegationDepth + 1}`,
+        }
+      }
+    }
+
+    // Expiry check
+    if (now >= token.expiresAt) {
+      return { ok: false, reason: `token[${i}]-expired` }
+    }
+
+    // Get public key for issuer
+    const issuerPub = await keyRegistry.getPublicKey(token.issuer)
+    if (!issuerPub) {
+      return { ok: false, reason: `no-public-key-for-issuer:${token.issuer}` }
+    }
+
+    // Verify signature
+    const { signature, ...unsigned } = token
+    const payload = canonicalizeCapabilityToken(unsigned)
+    const valid = await verifyCanonicalPayloadEd25519(payload, signature, issuerPub)
+    if (!valid) {
+      return { ok: false, reason: `invalid-signature-at-index:${i}` }
+    }
+  }
+
+  const leaf = chain[chain.length - 1]
+
+  // Check required scope
+  if (opts?.requiredPathGlob !== undefined) {
+    if (!tokenMatchesScope(leaf, opts.requiredPathGlob, opts.requiredMethod)) {
+      return { ok: false, reason: 'leaf-token-does-not-cover-required-scope' }
+    }
+  }
+
+  return { ok: true, token: leaf, chain }
+}
+
+// ---------------------------------------------------------------------------
+// Scope matching
+// ---------------------------------------------------------------------------
+
+export function tokenMatchesScope(token: CapabilityToken, pathGlob: string, method?: string): boolean {
+  for (const scope of token.scopes) {
+    // Check path: the scope's pathGlob must match the requested path
+    if (!matchGlob(scope.pathGlob, pathGlob)) {
+      continue
+    }
+
+    // Check method: if scope has no methods restriction, any method is allowed
+    if (scope.methods === undefined) {
+      return true
+    }
+    if (method === undefined) {
+      return true
+    }
+    if (scope.methods.includes(method.toUpperCase())) {
+      return true
+    }
+  }
+  return false
+}
+
+// ---------------------------------------------------------------------------
+// Serialization
+// ---------------------------------------------------------------------------
+
+export function serializeCapabilityChain(chain: CapabilityToken[]): string {
+  return JSON.stringify(chain)
+}
+
+export function parseCapabilityChain(serialized: string): CapabilityToken[] {
+  return JSON.parse(serialized) as CapabilityToken[]
+}

package/src/cborCodec.test.ts

@@ -0,0 +1,263 @@
+import { describe, it, expect } from 'vitest'
+import { encodeCbor, decodeCbor, CborEncoder, CborDecoder } from './cborCodec'
+import { encodeEnvelopeCbor, decodeEnvelopeCbor } from './envelopeCbor'
+import type { ProtocolEnvelope } from './protocol'
+
+// Helper: compare Uint8Arrays
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}
+
+describe('CborCodec - round-trip', () => {
+  it('null round-trips', () => {
+    const encoded = encodeCbor(null)
+    expect(decodeCbor(encoded)).toBe(null)
+  })
+
+  it('boolean false round-trips', () => {
+    const encoded = encodeCbor(false)
+    expect(decodeCbor(encoded)).toBe(false)
+  })
+
+  it('boolean true round-trips', () => {
+    const encoded = encodeCbor(true)
+    expect(decodeCbor(encoded)).toBe(true)
+  })
+
+  it('integer 0 round-trips', () => {
+    const encoded = encodeCbor(0)
+    expect(decodeCbor(encoded)).toBe(0)
+  })
+
+  it('integer 42 round-trips', () => {
+    const encoded = encodeCbor(42)
+    expect(decodeCbor(encoded)).toBe(42)
+  })
+
+  it('negative integer round-trips', () => {
+    const encoded = encodeCbor(-100)
+    expect(decodeCbor(encoded)).toBe(-100)
+  })
+
+  it('float round-trips', () => {
+    const encoded = encodeCbor(3.14)
+    const decoded = decodeCbor(encoded)
+    expect(typeof decoded).toBe('number')
+    expect(decoded as number).toBeCloseTo(3.14, 10)
+  })
+
+  it('string round-trips', () => {
+    const encoded = encodeCbor('hello world')
+    expect(decodeCbor(encoded)).toBe('hello world')
+  })
+
+  it('empty string round-trips', () => {
+    const encoded = encodeCbor('')
+    expect(decodeCbor(encoded)).toBe('')
+  })
+
+  it('array round-trips', () => {
+    const arr = [1, 'two', true, null, 3.14]
+    const encoded = encodeCbor(arr)
+    const decoded = decodeCbor(encoded)
+    expect(decoded).toEqual(arr)
+  })
+
+  it('nested object round-trips', () => {
+    const obj = { a: 1, b: 'hello', c: [1, 2, 3], d: { e: true } }
+    const encoded = encodeCbor(obj)
+    const decoded = decodeCbor(encoded)
+    expect(decoded).toEqual(obj)
+  })
+
+  it('Uint8Array round-trips', () => {
+    const bytes = new Uint8Array([0x01, 0x02, 0x03, 0xff])
+    const encoded = encodeCbor(bytes)
+    const decoded = decodeCbor(encoded)
+    expect(decoded).toBeInstanceOf(Uint8Array)
+    expect(bytesEqual(decoded as Uint8Array, bytes)).toBe(true)
+  })
+})
+
+describe('CborCodec - deterministic encoding', () => {
+  it('encoding same object twice gives identical bytes', () => {
+    const obj = { z: 3, a: 1, m: 2, nested: { x: 'hello' } }
+    const enc1 = encodeCbor(obj)
+    const enc2 = encodeCbor(obj)
+    expect(bytesEqual(enc1, enc2)).toBe(true)
+  })
+
+  it('encoding independently with two encoder instances gives identical bytes', () => {
+    const obj = { foo: 'bar', baz: 42 }
+    const enc1 = new CborEncoder().encode(obj)
+    const enc2 = new CborEncoder().encode(obj)
+    expect(bytesEqual(enc1, enc2)).toBe(true)
+  })
+})
+
+describe('CborCodec - key ordering', () => {
+  it('map keys {z, a, m} are encoded in a < m < z byte order', () => {
+    const obj = { z: 3, a: 1, m: 2 }
+    const encoded = encodeCbor(obj)
+    const decoded = decodeCbor(encoded) as Record<string, unknown>
+    // Verify all keys present and correct values
+    expect(decoded['a']).toBe(1)
+    expect(decoded['m']).toBe(2)
+    expect(decoded['z']).toBe(3)
+
+    // Verify byte order: find the offset of each key char in encoded bytes
+    // Key 'a' (0x61) must appear before 'm' (0x6d) which must appear before 'z' (0x7a)
+    const textA = 0x61 // 'a'
+    const textM = 0x6d // 'm'
+    const textZ = 0x7a // 'z'
+
+    let posA = -1, posM = -1, posZ = -1
+    for (let i = 0; i < encoded.length; i++) {
+      if (encoded[i] === textA && posA === -1) posA = i
+      if (encoded[i] === textM && posM === -1) posM = i
+      if (encoded[i] === textZ && posZ === -1) posZ = i
+    }
+    expect(posA).toBeGreaterThanOrEqual(0)
+    expect(posM).toBeGreaterThan(posA)
+    expect(posZ).toBeGreaterThan(posM)
+  })
+})
+
+describe('CborCodec - integer encoding sizes', () => {
+  it('0 encodes to 1 byte', () => {
+    const encoded = encodeCbor(0)
+    expect(encoded.length).toBe(1)
+    expect(encoded[0]).toBe(0x00)
+  })
+
+  it('23 encodes to 1 byte', () => {
+    const encoded = encodeCbor(23)
+    expect(encoded.length).toBe(1)
+    expect(encoded[0]).toBe(0x17) // 0<<5 | 23
+  })
+
+  it('24 encodes to 2 bytes', () => {
+    const encoded = encodeCbor(24)
+    expect(encoded.length).toBe(2)
+    expect(encoded[0]).toBe(0x18) // 0<<5 | 24 (1-byte additional)
+    expect(encoded[1]).toBe(24)
+  })
+
+  it('255 encodes to 2 bytes', () => {
+    const encoded = encodeCbor(255)
+    expect(encoded.length).toBe(2)
+    expect(encoded[0]).toBe(0x18)
+    expect(encoded[1]).toBe(255)
+  })
+
+  it('256 encodes to 3 bytes', () => {
+    const encoded = encodeCbor(256)
+    expect(encoded.length).toBe(3)
+    expect(encoded[0]).toBe(0x19) // 0<<5 | 25 (2-byte additional)
+    expect(encoded[1]).toBe(0x01)
+    expect(encoded[2]).toBe(0x00)
+  })
+})
+
+describe('envelopeCbor - round-trip', () => {
+  const baseEnvelope: ProtocolEnvelope = {
+    header: {
+      version: '7h3/0.1',
+      messageId: 'msg-1234567890-abc12345',
+      timestampMs: 1700000000000,
+      ttlMs: 60000,
+      sender: 'agent:alice@example.com',
+      nonce: 'abcdefghij',
+    },
+    body: {
+      intent: 'TASK',
+      content: 'Hello, agent!',
+    },
+  }
+
+  it('round-trip preserves all required fields', () => {
+    const encoded = encodeEnvelopeCbor(baseEnvelope)
+    const decoded = decodeEnvelopeCbor(encoded)
+
+    expect(decoded.header.version).toBe(baseEnvelope.header.version)
+    expect(decoded.header.messageId).toBe(baseEnvelope.header.messageId)
+    expect(decoded.header.timestampMs).toBe(baseEnvelope.header.timestampMs)
+    expect(decoded.header.ttlMs).toBe(baseEnvelope.header.ttlMs)
+    expect(decoded.header.sender).toBe(baseEnvelope.header.sender)
+    expect(decoded.header.nonce).toBe(baseEnvelope.header.nonce)
+    expect(decoded.body.intent).toBe(baseEnvelope.body.intent)
+    expect(decoded.body.content).toBe(baseEnvelope.body.content)
+  })
+
+  it('round-trip preserves optional fields: recipient, capability, correlationId', () => {
+    const full: ProtocolEnvelope = {
+      ...baseEnvelope,
+      header: { ...baseEnvelope.header, recipient: 'agent:bob@example.com' },
+      body: { ...baseEnvelope.body, capability: 'file.read', correlationId: 'corr-xyz' },
+      signature: {
+        alg: 'HS256',
+        keyId: 'my-key-id',
+        value: 'base64urlencodedvalue',
+      },
+    }
+
+    const encoded = encodeEnvelopeCbor(full)
+    const decoded = decodeEnvelopeCbor(encoded)
+
+    expect(decoded.header.recipient).toBe('agent:bob@example.com')
+    expect(decoded.body.capability).toBe('file.read')
+    expect(decoded.body.correlationId).toBe('corr-xyz')
+    expect(decoded.signature?.alg).toBe('HS256')
+    expect(decoded.signature?.keyId).toBe('my-key-id')
+    expect(decoded.signature?.value).toBe('base64urlencodedvalue')
+  })
+
+  it('CBOR envelope is smaller than JSON equivalent (size comparison)', () => {
+    const full: ProtocolEnvelope = {
+      ...baseEnvelope,
+      header: { ...baseEnvelope.header, recipient: 'agent:bob@example.com' },
+      body: { ...baseEnvelope.body, capability: 'file.read', correlationId: 'corr-xyz' },
+      signature: {
+        alg: 'HS256',
+        keyId: 'my-key-id',
+        value: 'base64urlencodedvalue',
+      },
+    }
+
+    const cborBytes = encodeEnvelopeCbor(full)
+    const jsonBytes = new TextEncoder().encode(JSON.stringify(full))
+
+    console.log(`CBOR size: ${cborBytes.length} bytes, JSON size: ${jsonBytes.length} bytes, ratio: ${(cborBytes.length / jsonBytes.length).toFixed(2)}`)
+    expect(cborBytes.length).toBeLessThan(jsonBytes.length)
+  })
+
+  it('optional fields absent in input are absent in output', () => {
+    // No recipient, capability, correlationId, signature
+    const minimal: ProtocolEnvelope = {
+      header: {
+        version: '7h3/0.1',
+        messageId: 'msg-min',
+        timestampMs: 1700000000000,
+        ttlMs: 30000,
+        sender: 'agent:sender',
+        nonce: 'nonce123',
+      },
+      body: {
+        intent: 'PING',
+        content: 'ping',
+      },
+    }
+
+    const encoded = encodeEnvelopeCbor(minimal)
+    const decoded = decodeEnvelopeCbor(encoded)
+
+    expect(decoded.header.recipient).toBeUndefined()
+    expect(decoded.body.capability).toBeUndefined()
+    expect(decoded.body.correlationId).toBeUndefined()
+    expect(decoded.signature).toBeUndefined()
+  })
+})