@7h3/protocol 0.5.0 → 0.5.1

package/src/auditLog.ts

@@ -1,147 +0,0 @@
-import {
-  signCanonicalPayloadEd25519,
-  verifyCanonicalPayloadEd25519,
-} from './protocol'
-
-export type AuditEventType =
-  | 'verify-ok'
-  | 'verify-fail'
-  | 'rate-limited'
-  | 'sender-denied'
-  | 'response-signed'
-
-export interface AuditEntry {
-  id: string
-  timestampMs: number
-  type: AuditEventType
-  sender?: string
-  path?: string
-  method?: string
-  envelopeId?: string
-  failReason?: string
-  upstream?: string
-  responseStatus?: number
-  entrySignature: string // Ed25519 sig over the entry (minus entrySignature itself)
-}
-
-/**
- * Produce a canonical payload string from an AuditEntry, excluding entrySignature.
- * Uses explicit key order and omits undefined fields for determinism.
- */
-function canonicalAuditPayload(entry: Omit<AuditEntry, 'entrySignature'> & { entrySignature?: string }): string {
-  const parts: string[] = [
-    `"id":${JSON.stringify(entry.id)}`,
-    `"timestampMs":${entry.timestampMs}`,
-    `"type":${JSON.stringify(entry.type)}`,
-  ]
-  if (entry.sender !== undefined) parts.push(`"sender":${JSON.stringify(entry.sender)}`)
-  if (entry.path !== undefined) parts.push(`"path":${JSON.stringify(entry.path)}`)
-  if (entry.method !== undefined) parts.push(`"method":${JSON.stringify(entry.method)}`)
-  if (entry.envelopeId !== undefined) parts.push(`"envelopeId":${JSON.stringify(entry.envelopeId)}`)
-  if (entry.failReason !== undefined) parts.push(`"failReason":${JSON.stringify(entry.failReason)}`)
-  if (entry.upstream !== undefined) parts.push(`"upstream":${JSON.stringify(entry.upstream)}`)
-  if (entry.responseStatus !== undefined) parts.push(`"responseStatus":${entry.responseStatus}`)
-  return `{${parts.join(',')}}`
-}
-
-export interface AuditLogger {
-  log(event: Omit<AuditEntry, 'id' | 'timestampMs' | 'entrySignature'>): Promise<void>
-  query(opts?: { type?: AuditEventType; sender?: string; since?: number; limit?: number }): Promise<AuditEntry[]>
-  verify(entry: AuditEntry, publicKey: string): Promise<boolean>
-}
-
-class InMemoryAuditLog implements AuditLogger {
-  private entries: AuditEntry[] = []
-  private privateKey: string
-  private maxEntries: number
-
-  constructor(privateKey: string, maxEntries = 10_000) {
-    this.privateKey = privateKey
-    this.maxEntries = maxEntries
-  }
-
-  async log(event: Omit<AuditEntry, 'id' | 'timestampMs' | 'entrySignature'>): Promise<void> {
-    const id = `audit-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
-    const timestampMs = Date.now()
-
-    const partial: Omit<AuditEntry, 'entrySignature'> = { id, timestampMs, ...event }
-    const payload = canonicalAuditPayload(partial)
-    const entrySignature = await signCanonicalPayloadEd25519(payload, this.privateKey)
-
-    const entry: AuditEntry = { ...partial, entrySignature }
-
-    if (this.entries.length >= this.maxEntries) {
-      this.entries.shift()
-    }
-    this.entries.push(entry)
-  }
-
-  async query(opts?: {
-    type?: AuditEventType
-    sender?: string
-    since?: number
-    limit?: number
-  }): Promise<AuditEntry[]> {
-    let results = [...this.entries]
-
-    if (opts?.type !== undefined) {
-      results = results.filter(e => e.type === opts.type)
-    }
-    if (opts?.sender !== undefined) {
-      results = results.filter(e => e.sender === opts.sender)
-    }
-    if (opts?.since !== undefined) {
-      results = results.filter(e => e.timestampMs >= opts.since!)
-    }
-    if (opts?.limit !== undefined) {
-      results = results.slice(-opts.limit)
-    }
-
-    return results
-  }
-
-  async verify(entry: AuditEntry, publicKey: string): Promise<boolean> {
-    const partial: Omit<AuditEntry, 'entrySignature'> = {
-      id: entry.id,
-      timestampMs: entry.timestampMs,
-      type: entry.type,
-      sender: entry.sender,
-      path: entry.path,
-      method: entry.method,
-      envelopeId: entry.envelopeId,
-      failReason: entry.failReason,
-      upstream: entry.upstream,
-      responseStatus: entry.responseStatus,
-    }
-    const payload = canonicalAuditPayload(partial)
-    return verifyCanonicalPayloadEd25519(payload, entry.entrySignature, publicKey)
-  }
-
-  size(): number {
-    return this.entries.length
-  }
-}
-
-class NoopAuditLog implements AuditLogger {
-  async log(_event: Omit<AuditEntry, 'id' | 'timestampMs' | 'entrySignature'>): Promise<void> {}
-  async query(_opts?: {
-    type?: AuditEventType
-    sender?: string
-    since?: number
-    limit?: number
-  }): Promise<AuditEntry[]> {
-    return []
-  }
-  async verify(_entry: AuditEntry, _publicKey: string): Promise<boolean> {
-    return false
-  }
-  size(): number {
-    return 0
-  }
-}
-
-export function createAuditLog(privateKey: string, opts?: { maxEntries?: number }): InMemoryAuditLog {
-  return new InMemoryAuditLog(privateKey, opts?.maxEntries)
-}
-
-export { InMemoryAuditLog, NoopAuditLog }

package/src/capability.test.ts

@@ -1,504 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import {
-  generateEd25519KeypairBase64Url,
-  issueCapabilityToken,
-  verifyCapabilityToken,
-  delegateCapabilityToken,
-  verifyCapabilityChain,
-  tokenMatchesScope,
-  serializeCapabilityChain,
-  parseCapabilityChain,
-  canonicalizeCapabilityToken,
-  type CapabilityToken,
-  type CapabilityScope,
-} from './capability'
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-async function makeKeypair() {
-  return generateEd25519KeypairBase64Url()
-}
-
-function makeKeyRegistry(map: Record<string, string>): { getPublicKey(id: string): Promise<string | null> } {
-  return {
-    async getPublicKey(id: string) {
-      return map[id] ?? null
-    },
-  }
-}
-
-const paymentScopes: CapabilityScope[] = [
-  { pathGlob: '/api/payments/**', methods: ['POST', 'PUT'] },
-]
-
-const readonlyPaymentScopes: CapabilityScope[] = [
-  { pathGlob: '/api/payments/**', methods: ['POST'] },
-]
-
-// ---------------------------------------------------------------------------
-// Test 1: issueCapabilityToken creates token with correct fields
-// ---------------------------------------------------------------------------
-describe('issueCapabilityToken', () => {
-  it('creates token with correct fields', async () => {
-    const root = await makeKeypair()
-    const now = Date.now()
-
-    const token = await issueCapabilityToken({
-      issuerPrivateKey: root.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-      maxDelegations: 2,
-    })
-
-    expect(token.version).toBe('7h3-cap/1')
-    expect(token.issuer).toBe('agent-root')
-    expect(token.subject).toBe('agent-b')
-    expect(token.scopes).toEqual(paymentScopes)
-    expect(token.delegationDepth).toBe(0)
-    expect(token.maxDelegations).toBe(2)
-    expect(token.parentTokenId).toBeUndefined()
-    expect(token.issuedAt).toBeGreaterThanOrEqual(now)
-    expect(token.expiresAt).toBeGreaterThan(token.issuedAt)
-    expect(typeof token.id).toBe('string')
-    expect(typeof token.signature).toBe('string')
-    expect(typeof token.keyId).toBe('string')
-  })
-
-  it('defaults maxDelegations to 0 when not specified', async () => {
-    const root = await makeKeypair()
-    const token = await issueCapabilityToken({
-      issuerPrivateKey: root.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-    })
-    expect(token.maxDelegations).toBe(0)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Test 2: verifyCapabilityToken succeeds with correct key
-// ---------------------------------------------------------------------------
-describe('verifyCapabilityToken', () => {
-  it('succeeds with correct key', async () => {
-    const root = await makeKeypair()
-    const token = await issueCapabilityToken({
-      issuerPrivateKey: root.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-    })
-
-    const valid = await verifyCapabilityToken(token, root.publicKey)
-    expect(valid).toBe(true)
-  })
-
-  // Test 3: verifyCapabilityToken fails with wrong key
-  it('fails with wrong key', async () => {
-    const root = await makeKeypair()
-    const other = await makeKeypair()
-    const token = await issueCapabilityToken({
-      issuerPrivateKey: root.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-    })
-
-    const valid = await verifyCapabilityToken(token, other.publicKey)
-    expect(valid).toBe(false)
-  })
-
-  // Test 4: verifyCapabilityToken fails on expired token
-  it('fails on expired token', async () => {
-    const root = await makeKeypair()
-    const token = await issueCapabilityToken({
-      issuerPrivateKey: root.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 1, // 1ms — will be expired by the time we check
-    })
-
-    // Use a future "now" to simulate expiry
-    const futureNow = token.expiresAt + 1
-    const valid = await verifyCapabilityToken(token, root.publicKey, { now: futureNow })
-    expect(valid).toBe(false)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Test 5: delegateCapabilityToken creates valid delegation
-// ---------------------------------------------------------------------------
-describe('delegateCapabilityToken', () => {
-  it('creates valid delegation', async () => {
-    const rootKeys = await makeKeypair()
-    const agentBKeys = await makeKeypair()
-
-    const rootToken = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-      maxDelegations: 2,
-    })
-
-    const delegated = await delegateCapabilityToken({
-      parentToken: rootToken,
-      delegatorPrivateKey: agentBKeys.privateKey,
-      delegatorId: 'agent-b',
-      newSubject: 'agent-c',
-      scopes: readonlyPaymentScopes,
-      ttlMs: 30_000,
-    })
-
-    expect(delegated.issuer).toBe('agent-b')
-    expect(delegated.subject).toBe('agent-c')
-    expect(delegated.delegationDepth).toBe(1)
-    expect(delegated.parentTokenId).toBe(rootToken.id)
-    expect(delegated.scopes).toEqual(readonlyPaymentScopes)
-    // maxDelegations should be decremented
-    expect(delegated.maxDelegations).toBe(1)
-
-    const valid = await verifyCapabilityToken(delegated, agentBKeys.publicKey)
-    expect(valid).toBe(true)
-  })
-
-  // Test 6: delegateCapabilityToken fails when maxDelegations=0
-  it('fails when maxDelegations=0', async () => {
-    const rootKeys = await makeKeypair()
-    const agentBKeys = await makeKeypair()
-
-    const rootToken = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-      maxDelegations: 0, // no further delegation
-    })
-
-    await expect(
-      delegateCapabilityToken({
-        parentToken: rootToken,
-        delegatorPrivateKey: agentBKeys.privateKey,
-        delegatorId: 'agent-b',
-        newSubject: 'agent-c',
-        scopes: readonlyPaymentScopes,
-        ttlMs: 30_000,
-      }),
-    ).rejects.toThrow(/maxDelegations/)
-  })
-
-  // Test 7: delegateCapabilityToken fails when new scopes exceed parent scopes
-  it('fails when new scopes exceed parent scopes', async () => {
-    const rootKeys = await makeKeypair()
-    const agentBKeys = await makeKeypair()
-
-    const rootToken = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: [{ pathGlob: '/api/payments/**', methods: ['POST'] }],
-      ttlMs: 60_000,
-      maxDelegations: 2,
-    })
-
-    // Try to delegate with a method (DELETE) not in parent
-    await expect(
-      delegateCapabilityToken({
-        parentToken: rootToken,
-        delegatorPrivateKey: agentBKeys.privateKey,
-        delegatorId: 'agent-b',
-        newSubject: 'agent-c',
-        scopes: [{ pathGlob: '/api/payments/**', methods: ['POST', 'DELETE'] }],
-        ttlMs: 30_000,
-      }),
-    ).rejects.toThrow(/exceed|subset/i)
-  })
-
-  it('fails when delegatorId does not match parentToken.subject', async () => {
-    const rootKeys = await makeKeypair()
-    const wrongKeys = await makeKeypair()
-
-    const rootToken = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-      maxDelegations: 2,
-    })
-
-    await expect(
-      delegateCapabilityToken({
-        parentToken: rootToken,
-        delegatorPrivateKey: wrongKeys.privateKey,
-        delegatorId: 'agent-wrong', // not agent-b
-        newSubject: 'agent-c',
-        ttlMs: 30_000,
-      }),
-    ).rejects.toThrow(/does not match/)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Test 8: verifyCapabilityChain: 2-link chain (root→delegate) verifies
-// ---------------------------------------------------------------------------
-describe('verifyCapabilityChain', () => {
-  it('2-link chain (root→delegate) verifies', async () => {
-    const rootKeys = await makeKeypair()
-    const agentBKeys = await makeKeypair()
-
-    const rootToken = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-      maxDelegations: 2,
-    })
-
-    const delegated = await delegateCapabilityToken({
-      parentToken: rootToken,
-      delegatorPrivateKey: agentBKeys.privateKey,
-      delegatorId: 'agent-b',
-      newSubject: 'agent-c',
-      scopes: readonlyPaymentScopes,
-      ttlMs: 30_000,
-    })
-
-    const registry = makeKeyRegistry({
-      'agent-root': rootKeys.publicKey,
-      'agent-b': agentBKeys.publicKey,
-    })
-
-    const result = await verifyCapabilityChain([rootToken, delegated], registry)
-    expect(result.ok).toBe(true)
-    if (result.ok) {
-      expect(result.token.subject).toBe('agent-c')
-      expect(result.chain).toHaveLength(2)
-    }
-  })
-
-  // Test 9: verifyCapabilityChain: tampered chain fails
-  it('tampered chain fails', async () => {
-    const rootKeys = await makeKeypair()
-    const agentBKeys = await makeKeypair()
-
-    const rootToken = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-      maxDelegations: 2,
-    })
-
-    const delegated = await delegateCapabilityToken({
-      parentToken: rootToken,
-      delegatorPrivateKey: agentBKeys.privateKey,
-      delegatorId: 'agent-b',
-      newSubject: 'agent-c',
-      scopes: readonlyPaymentScopes,
-      ttlMs: 30_000,
-    })
-
-    // Tamper with the delegated token's subject
-    const tampered: CapabilityToken = { ...delegated, subject: 'agent-evil' }
-
-    const registry = makeKeyRegistry({
-      'agent-root': rootKeys.publicKey,
-      'agent-b': agentBKeys.publicKey,
-    })
-
-    const result = await verifyCapabilityChain([rootToken, tampered], registry)
-    expect(result.ok).toBe(false)
-  })
-
-  it('rejects when issuer key not in registry', async () => {
-    const rootKeys = await makeKeypair()
-
-    const rootToken = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-    })
-
-    // Empty registry — no key for agent-root
-    const registry = makeKeyRegistry({})
-    const result = await verifyCapabilityChain([rootToken], registry)
-    expect(result.ok).toBe(false)
-    if (!result.ok) {
-      expect(result.reason).toMatch(/no-public-key/)
-    }
-  })
-
-  it('rejects when required scope not covered', async () => {
-    const rootKeys = await makeKeypair()
-
-    const rootToken = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: [{ pathGlob: '/api/payments/**' }],
-      ttlMs: 60_000,
-    })
-
-    const registry = makeKeyRegistry({ 'agent-root': rootKeys.publicKey })
-    const result = await verifyCapabilityChain([rootToken], registry, {
-      requiredPathGlob: '/api/admin/delete',
-    })
-    expect(result.ok).toBe(false)
-  })
-
-  it('rejects expired token in chain', async () => {
-    const rootKeys = await makeKeypair()
-
-    const rootToken = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-    })
-
-    const registry = makeKeyRegistry({ 'agent-root': rootKeys.publicKey })
-
-    // Check with a future now that makes the token expired
-    const result = await verifyCapabilityChain([rootToken], registry, {
-      now: rootToken.expiresAt + 1,
-    })
-    expect(result.ok).toBe(false)
-    if (!result.ok) {
-      expect(result.reason).toMatch(/expired/)
-    }
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Test 10: tokenMatchesScope: glob matching works
-// ---------------------------------------------------------------------------
-describe('tokenMatchesScope', () => {
-  it('matches exact glob pattern', async () => {
-    const rootKeys = await makeKeypair()
-    const token = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: [{ pathGlob: '/api/payments/**', methods: ['POST', 'PUT'] }],
-      ttlMs: 60_000,
-    })
-
-    expect(tokenMatchesScope(token, '/api/payments/create', 'POST')).toBe(true)
-    expect(tokenMatchesScope(token, '/api/payments/update/123', 'PUT')).toBe(true)
-  })
-
-  it('rejects method not in scope', async () => {
-    const rootKeys = await makeKeypair()
-    const token = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: [{ pathGlob: '/api/payments/**', methods: ['POST'] }],
-      ttlMs: 60_000,
-    })
-
-    expect(tokenMatchesScope(token, '/api/payments/create', 'DELETE')).toBe(false)
-  })
-
-  it('matches any method when methods is undefined', async () => {
-    const rootKeys = await makeKeypair()
-    const token = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: [{ pathGlob: '/api/**' }], // no methods restriction
-      ttlMs: 60_000,
-    })
-
-    expect(tokenMatchesScope(token, '/api/anything', 'DELETE')).toBe(true)
-    expect(tokenMatchesScope(token, '/api/payments/create', 'GET')).toBe(true)
-  })
-
-  it('rejects path not matching glob', async () => {
-    const rootKeys = await makeKeypair()
-    const token = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: [{ pathGlob: '/api/payments/**' }],
-      ttlMs: 60_000,
-    })
-
-    expect(tokenMatchesScope(token, '/api/admin/delete', 'POST')).toBe(false)
-  })
-
-  it('handles single-segment wildcard', async () => {
-    const rootKeys = await makeKeypair()
-    const token = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: [{ pathGlob: '/api/*/status' }],
-      ttlMs: 60_000,
-    })
-
-    expect(tokenMatchesScope(token, '/api/payments/status', 'GET')).toBe(true)
-    // Multi-segment should NOT match single *
-    expect(tokenMatchesScope(token, '/api/a/b/status', 'GET')).toBe(false)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Serialization round-trip
-// ---------------------------------------------------------------------------
-describe('serializeCapabilityChain / parseCapabilityChain', () => {
-  it('round-trips a chain', async () => {
-    const rootKeys = await makeKeypair()
-    const token = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-    })
-
-    const serialized = serializeCapabilityChain([token])
-    const parsed = parseCapabilityChain(serialized)
-
-    expect(parsed).toHaveLength(1)
-    expect(parsed[0].id).toBe(token.id)
-    expect(parsed[0].signature).toBe(token.signature)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Canonicalization determinism
-// ---------------------------------------------------------------------------
-describe('canonicalizeCapabilityToken', () => {
-  it('produces the same string for equivalent tokens', async () => {
-    const rootKeys = await makeKeypair()
-    const token = await issueCapabilityToken({
-      issuerPrivateKey: rootKeys.privateKey,
-      issuerId: 'agent-root',
-      subject: 'agent-b',
-      scopes: paymentScopes,
-      ttlMs: 60_000,
-    })
-
-    const { signature, ...unsigned } = token
-    const c1 = canonicalizeCapabilityToken(unsigned)
-    const c2 = canonicalizeCapabilityToken(unsigned)
-    expect(c1).toBe(c2)
-  })
-})