@7h3/protocol 0.5.0 → 0.5.2

package/src/capability.ts

@@ -1,380 +0,0 @@
-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

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