@7h3/protocol 0.4.0 → 0.5.1

package/src/keyInfra.test.ts

@@ -1,278 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest'
-import {
-  parseWellKnownKeys,
-  serveWellKnownKeys,
-  KeyRotationManager,
-  RevocationRegistry,
-} from './keyInfra'
-import type { WellKnownKeysDocument, RevocationList } from './keyInfra'
-import { createStaticKeyRegistry } from './keyRegistry'
-
-// ── 1. parseWellKnownKeys: valid document parses correctly ───────────────────
-
-describe('parseWellKnownKeys', () => {
-  it('parses a valid document correctly', () => {
-    const doc: WellKnownKeysDocument = {
-      version: '7h3/0.1',
-      updated: 1_700_000_000_000,
-      keys: [
-        {
-          id: 'agent@example.com',
-          algorithm: 'Ed25519',
-          publicKey: 'MCowBQYDK2VwAyEA',
-          created: 1_699_000_000_000,
-        },
-      ],
-    }
-    const json = JSON.stringify(doc)
-    const parsed = parseWellKnownKeys(json)
-    expect(parsed.version).toBe('7h3/0.1')
-    expect(parsed.updated).toBe(1_700_000_000_000)
-    expect(parsed.keys).toHaveLength(1)
-    expect(parsed.keys[0].id).toBe('agent@example.com')
-    expect(parsed.keys[0].algorithm).toBe('Ed25519')
-    expect(parsed.keys[0].publicKey).toBe('MCowBQYDK2VwAyEA')
-    expect(parsed.keys[0].created).toBe(1_699_000_000_000)
-  })
-
-  // ── 2. parseWellKnownKeys: wrong version throws ────────────────────────────
-
-  it('throws on unsupported version', () => {
-    const doc = {
-      version: '7h3/0.2',
-      updated: Date.now(),
-      keys: [],
-    }
-    expect(() => parseWellKnownKeys(JSON.stringify(doc))).toThrow('unsupported version: 7h3/0.2')
-  })
-})
-
-// ── 3. serveWellKnownKeys: produces valid JSON ───────────────────────────────
-
-describe('serveWellKnownKeys', () => {
-  it('produces valid JSON that round-trips through parseWellKnownKeys', () => {
-    const doc: WellKnownKeysDocument = {
-      version: '7h3/0.1',
-      updated: 1_700_000_000_000,
-      keys: [],
-    }
-    const json = serveWellKnownKeys(doc)
-    expect(() => JSON.parse(json)).not.toThrow()
-    const parsed = parseWellKnownKeys(json)
-    expect(parsed.version).toBe('7h3/0.1')
-    expect(parsed.updated).toBe(doc.updated)
-    expect(parsed.keys).toEqual([])
-  })
-})
-
-// ── KeyRotationManager tests ─────────────────────────────────────────────────
-
-describe('KeyRotationManager', () => {
-  // ── 4. addKey + getCurrentKey returns newest ─────────────────────────────
-
-  it('addKey + getCurrentKey returns the newest key', () => {
-    const mgr = new KeyRotationManager({ maxAgeMs: 60_000 })
-    const now = Date.now()
-
-    const older = {
-      id: 'key-old',
-      publicKey: 'pub-old',
-      privateKey: 'priv-old',
-      createdAt: now - 10_000,
-    }
-    const newer = {
-      id: 'key-new',
-      publicKey: 'pub-new',
-      privateKey: 'priv-new',
-      createdAt: now - 1_000,
-    }
-
-    mgr.addKey(older)
-    mgr.addKey(newer)
-
-    const current = mgr.getCurrentKey()
-    expect(current).not.toBeNull()
-    expect(current!.id).toBe('key-new')
-  })
-
-  // ── 5. rotateIfNeeded generates new key when current is too old ──────────
-
-  it('rotateIfNeeded generates a new key when current key is too old', async () => {
-    const mgr = new KeyRotationManager({ maxAgeMs: 1_000, overlapMs: 100 })
-    const now = Date.now()
-
-    // Add a key that is older than maxAgeMs - overlapMs = 900ms
-    const oldKey = {
-      id: 'key-stale',
-      publicKey: 'pub-stale',
-      privateKey: 'priv-stale',
-      createdAt: now - 1_000,  // exactly at maxAgeMs, past the rotate threshold
-    }
-    mgr.addKey(oldKey)
-
-    const rotated = await mgr.rotateIfNeeded()
-    expect(rotated).not.toBeNull()
-    expect(rotated!.publicKey).toBeTruthy()
-    expect(rotated!.privateKey).toBeTruthy()
-    expect(rotated!.id).toMatch(/^key-/)
-    expect(rotated!.createdAt).toBeGreaterThanOrEqual(now)
-  })
-
-  // ── 6. rotateIfNeeded returns null when key is still fresh ───────────────
-
-  it('rotateIfNeeded returns null when the current key is still fresh', async () => {
-    const mgr = new KeyRotationManager({ maxAgeMs: 60_000, overlapMs: 6_000 })
-    const now = Date.now()
-
-    // Key created just now — well within the maxAgeMs - overlapMs window
-    const freshKey = {
-      id: 'key-fresh',
-      publicKey: 'pub-fresh',
-      privateKey: 'priv-fresh',
-      createdAt: now,
-    }
-    mgr.addKey(freshKey)
-
-    const result = await mgr.rotateIfNeeded()
-    expect(result).toBeNull()
-  })
-
-  // ── 7. getWellKnownDocument structure ───────────────────────────────────
-
-  it('getWellKnownDocument returns correct structure', () => {
-    const mgr = new KeyRotationManager({ maxAgeMs: 60_000 })
-    const now = Date.now()
-
-    mgr.addKey({
-      id: 'key-abc',
-      publicKey: 'pub-abc',
-      privateKey: 'priv-abc',
-      createdAt: now - 5_000,
-    })
-
-    const doc = mgr.getWellKnownDocument()
-
-    expect(doc.version).toBe('7h3/0.1')
-    expect(typeof doc.updated).toBe('number')
-    expect(doc.keys).toHaveLength(1)
-    expect(doc.keys[0].id).toBe('key-abc')
-    expect(doc.keys[0].algorithm).toBe('Ed25519')
-    expect(doc.keys[0].publicKey).toBe('pub-abc')
-    expect(doc.keys[0].created).toBe(now - 5_000)
-  })
-
-  it('getWellKnownDocument marks expired keys as revoked', () => {
-    const mgr = new KeyRotationManager({ maxAgeMs: 60_000 })
-    const pastTime = Date.now() - 10_000
-
-    mgr.addKey({
-      id: 'key-expired',
-      publicKey: 'pub-exp',
-      privateKey: 'priv-exp',
-      createdAt: Date.now() - 30_000,
-      expiresAt: pastTime,  // already expired
-    })
-
-    const doc = mgr.getWellKnownDocument()
-    expect(doc.keys[0].revoked).toBe(true)
-    expect(doc.keys[0].revokedAt).toBe(pastTime)
-  })
-})
-
-// ── RevocationRegistry tests ─────────────────────────────────────────────────
-
-describe('RevocationRegistry', () => {
-  let registry: RevocationRegistry
-
-  beforeEach(() => {
-    registry = new RevocationRegistry()
-  })
-
-  // ── 8. revoke + isRevoked ────────────────────────────────────────────────
-
-  it('revoke + isRevoked: marks key as revoked', () => {
-    expect(registry.isRevoked('key-001')).toBe(false)
-    registry.revoke('key-001', 'compromised')
-    expect(registry.isRevoked('key-001')).toBe(true)
-  })
-
-  it('isRevoked returns false for unknown key', () => {
-    expect(registry.isRevoked('key-unknown')).toBe(false)
-  })
-
-  // ── 9. getList structure ─────────────────────────────────────────────────
-
-  it('getList returns correct structure', () => {
-    registry.revoke('key-alpha', 'expired')
-    registry.revoke('key-beta')
-
-    const list = registry.getList()
-
-    expect(list.version).toBe('7h3/0.1')
-    expect(typeof list.updated).toBe('number')
-    expect(list.revokedKeys).toHaveLength(2)
-
-    const alpha = list.revokedKeys.find(e => e.id === 'key-alpha')
-    expect(alpha).toBeDefined()
-    expect(alpha!.reason).toBe('expired')
-    expect(typeof alpha!.revokedAt).toBe('number')
-
-    const beta = list.revokedKeys.find(e => e.id === 'key-beta')
-    expect(beta).toBeDefined()
-    expect(beta!.reason).toBeUndefined()
-  })
-
-  // ── 10. importList merges without overwrite ──────────────────────────────
-
-  it('importList merges entries without overwriting existing ones', () => {
-    // Pre-revoke key-a locally with a specific timestamp
-    const originalTime = Date.now() - 5_000
-    registry['revoked'].set('key-a', { id: 'key-a', revokedAt: originalTime, reason: 'local-reason' })
-
-    const incomingList: RevocationList = {
-      version: '7h3/0.1',
-      updated: Date.now(),
-      revokedKeys: [
-        { id: 'key-a', revokedAt: Date.now(), reason: 'remote-reason' },  // should NOT overwrite
-        { id: 'key-b', revokedAt: Date.now(), reason: 'new-key' },         // should be added
-      ],
-    }
-
-    registry.importList(incomingList)
-
-    // key-a should keep original local entry (no overwrite)
-    const entryA = registry['revoked'].get('key-a')
-    expect(entryA!.revokedAt).toBe(originalTime)
-    expect(entryA!.reason).toBe('local-reason')
-
-    // key-b should have been added
-    expect(registry.isRevoked('key-b')).toBe(true)
-    const entryB = registry['revoked'].get('key-b')
-    expect(entryB!.reason).toBe('new-key')
-  })
-
-  // ── 11. wrapRegistry returns null for revoked sender ────────────────────
-
-  it('wrapRegistry returns null for a revoked sender', async () => {
-    const inner = createStaticKeyRegistry({
-      'agent@example.com': 'pub-key-abc',
-    })
-
-    registry.revoke('agent@example.com')
-    const wrapped = registry.wrapRegistry(inner)
-
-    const result = await wrapped.getPublicKey('agent@example.com')
-    expect(result).toBeNull()
-  })
-
-  it('wrapRegistry returns the public key for a non-revoked sender', async () => {
-    const inner = createStaticKeyRegistry({
-      'agent@example.com': 'pub-key-abc',
-    })
-
-    const wrapped = registry.wrapRegistry(inner)
-
-    const result = await wrapped.getPublicKey('agent@example.com')
-    expect(result).toBe('pub-key-abc')
-  })
-})

package/src/keyInfra.ts

@@ -1,228 +0,0 @@
-import { generateEd25519KeypairBase64Url } from './protocol'
-import type { KeyRegistry } from './keyRegistry'
-
-// ── Well-Known Document ──────────────────────────────────────────────────────
-
-export interface KeyEntry {
-  id: string
-  algorithm: 'Ed25519'
-  publicKey: string   // SPKI base64url
-  created: number     // Unix ms
-  expires?: number
-  revoked?: boolean
-  revokedAt?: number
-}
-
-export interface WellKnownKeysDocument {
-  version: '7h3/0.1'
-  updated: number
-  keys: KeyEntry[]
-}
-
-export function serveWellKnownKeys(doc: WellKnownKeysDocument): string {
-  return JSON.stringify(doc)
-}
-
-export function parseWellKnownKeys(json: string): WellKnownKeysDocument {
-  const d = JSON.parse(json) as WellKnownKeysDocument
-  if (d.version !== '7h3/0.1') throw new Error(`unsupported version: ${d.version}`)
-  return d
-}
-
-// Fetch .well-known/7h3-keys from a base URL (uses global fetch)
-export async function fetchWellKnownKeys(
-  baseUrl: string,
-  opts?: { timeout?: number }
-): Promise<WellKnownKeysDocument> {
-  const url = baseUrl.replace(/\/$/, '') + '/.well-known/7h3-keys'
-  const controller = new AbortController()
-  const timer = opts?.timeout
-    ? setTimeout(() => controller.abort(), opts.timeout)
-    : undefined
-  try {
-    const resp = await fetch(url, { signal: controller.signal })
-    if (!resp.ok) throw new Error(`HTTP ${resp.status} from ${url}`)
-    return parseWellKnownKeys(await resp.text())
-  } finally {
-    if (timer !== undefined) clearTimeout(timer)
-  }
-}
-
-// ── HTTP-backed KeyRegistry (auto-discovers from .well-known) ────────────────
-
-export function createHttpKeyRegistry(opts?: {
-  timeout?: number
-  cacheMs?: number
-}): KeyRegistry {
-  const cache = new Map<string, { doc: WellKnownKeysDocument; expiresAt: number }>()
-  const cacheMs = opts?.cacheMs ?? 60_000
-  const timeout = opts?.timeout ?? 5_000
-
-  async function getDoc(baseUrl: string): Promise<WellKnownKeysDocument> {
-    const now = Date.now()
-    const hit = cache.get(baseUrl)
-    if (hit && hit.expiresAt > now) return hit.doc
-    const doc = await fetchWellKnownKeys(baseUrl, { timeout })
-    cache.set(baseUrl, { doc, expiresAt: now + cacheMs })
-    return doc
-  }
-
-  return {
-    async getPublicKey(senderId: string): Promise<string | null> {
-      // senderId format: "service@example.com" or "agent.example.com"
-      // extract domain for well-known lookup
-      const domain = senderId.includes('@')
-        ? senderId.split('@')[1]
-        : senderId.split('.').slice(-2).join('.')
-      if (!domain) return null
-      try {
-        const doc = await getDoc(`https://${domain}`)
-        const now = Date.now()
-        const entry = doc.keys.find(
-          k =>
-            (k.id === senderId || k.id === senderId.split('@')[0]) &&
-            !k.revoked &&
-            (!k.expires || k.expires > now)
-        )
-        return entry?.publicKey ?? null
-      } catch {
-        return null
-      }
-    },
-  }
-}
-
-// ── Key Rotation Manager ─────────────────────────────────────────────────────
-
-export interface ManagedKeyPair {
-  id: string
-  publicKey: string
-  privateKey: string
-  createdAt: number
-  expiresAt?: number
-}
-
-export interface KeyRotationOptions {
-  maxAgeMs: number
-  overlapMs?: number
-}
-
-export class KeyRotationManager {
-  private readonly maxAgeMs: number
-  private readonly overlapMs: number
-  private keys: ManagedKeyPair[] = []
-
-  constructor(opts: KeyRotationOptions) {
-    this.maxAgeMs = opts.maxAgeMs
-    this.overlapMs = opts.overlapMs ?? Math.floor(opts.maxAgeMs * 0.1)
-  }
-
-  addKey(pair: ManagedKeyPair): void {
-    this.keys.push(pair)
-  }
-
-  getCurrentKey(): ManagedKeyPair | null {
-    const now = Date.now()
-    const active = this.keys.filter(k => !k.expiresAt || k.expiresAt > now)
-    if (active.length === 0) return null
-    return active.reduce((a, b) => (a.createdAt > b.createdAt ? a : b))
-  }
-
-  async rotateIfNeeded(): Promise<ManagedKeyPair | null> {
-    const now = Date.now()
-    const current = this.getCurrentKey()
-    if (current && now - current.createdAt < this.maxAgeMs - this.overlapMs) return null
-    // Expire the current key after overlap period
-    if (current && !current.expiresAt) {
-      current.expiresAt = now + this.overlapMs
-    }
-    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
-    const newKey: ManagedKeyPair = {
-      id: `key-${now}-${Math.random().toString(36).slice(2, 8)}`,
-      publicKey,
-      privateKey,
-      createdAt: now,
-    }
-    this.keys.push(newKey)
-    return newKey
-  }
-
-  getWellKnownDocument(): WellKnownKeysDocument {
-    const now = Date.now()
-    return {
-      version: '7h3/0.1',
-      updated: now,
-      keys: this.keys.map(k => ({
-        id: k.id,
-        algorithm: 'Ed25519' as const,
-        publicKey: k.publicKey,
-        created: k.createdAt,
-        ...(k.expiresAt ? { expires: k.expiresAt } : {}),
-        ...(k.expiresAt && k.expiresAt < now ? { revoked: true, revokedAt: k.expiresAt } : {}),
-      })),
-    }
-  }
-
-  toKeyRegistry(): KeyRegistry {
-    return {
-      getPublicKey: async (senderId: string): Promise<string | null> => {
-        const now = Date.now()
-        // Find by ID or return the current active key's public key
-        const byId = this.keys.find(k => k.id === senderId && (!k.expiresAt || k.expiresAt > now))
-        return byId?.publicKey ?? this.getCurrentKey()?.publicKey ?? null
-      },
-    }
-  }
-}
-
-// ── Revocation Registry ──────────────────────────────────────────────────────
-
-export interface RevocationEntry {
-  id: string
-  revokedAt: number
-  reason?: string
-}
-
-export interface RevocationList {
-  version: '7h3/0.1'
-  updated: number
-  revokedKeys: RevocationEntry[]
-}
-
-export class RevocationRegistry {
-  private revoked = new Map<string, RevocationEntry>()
-
-  revoke(keyId: string, reason?: string): void {
-    this.revoked.set(keyId, { id: keyId, revokedAt: Date.now(), reason })
-  }
-
-  isRevoked(keyId: string): boolean {
-    return this.revoked.has(keyId)
-  }
-
-  getList(): RevocationList {
-    return {
-      version: '7h3/0.1',
-      updated: Date.now(),
-      revokedKeys: [...this.revoked.values()],
-    }
-  }
-
-  importList(list: RevocationList): void {
-    for (const entry of list.revokedKeys) {
-      if (!this.revoked.has(entry.id)) this.revoked.set(entry.id, entry)
-    }
-  }
-
-  // Returns a KeyRegistry wrapper that rejects revoked keys
-  wrapRegistry(inner: KeyRegistry): KeyRegistry {
-    const self = this
-    return {
-      async getPublicKey(senderId: string) {
-        if (self.isRevoked(senderId)) return null
-        return inner.getPublicKey(senderId)
-      },
-      getSharedSecret: inner.getSharedSecret?.bind(inner),
-    }
-  }
-}

package/src/keyRegistry.ts

@@ -1,59 +0,0 @@
-// Core interface all bindings use to look up keys
-export interface KeyRegistry {
-  getPublicKey(senderId: string): Promise<string | null>  // Ed25519 SPKI base64url
-  getSharedSecret?(keyId: string): Promise<string | null>  // HMAC secret (optional)
-}
-
-// Simple in-memory registry from a static map
-export function createStaticKeyRegistry(keys: Record<string, string>): KeyRegistry {
-  return {
-    async getPublicKey(senderId) { return keys[senderId] ?? null },
-  }
-}
-
-// Multi-registry: tries registries in order, returns first non-null
-export function createCompositeKeyRegistry(...registries: KeyRegistry[]): KeyRegistry {
-  return {
-    async getPublicKey(senderId) {
-      for (const r of registries) {
-        const key = await r.getPublicKey(senderId)
-        if (key !== null) return key
-      }
-      return null
-    },
-    async getSharedSecret(keyId) {
-      for (const r of registries) {
-        if (!r.getSharedSecret) continue
-        const secret = await r.getSharedSecret(keyId)
-        if (secret !== null) return secret
-      }
-      return null
-    },
-  }
-}
-
-// Caching wrapper around any KeyRegistry (avoids repeated network calls)
-export function createCachingKeyRegistry(
-  inner: KeyRegistry,
-  opts?: { ttlMs?: number }
-): KeyRegistry {
-  const ttl = opts?.ttlMs ?? 60_000
-  const cache = new Map<string, { value: string | null; expiresAt: number }>()
-  async function get(key: string, fetch: () => Promise<string | null>): Promise<string | null> {
-    const now = Date.now()
-    const cached = cache.get(key)
-    if (cached && cached.expiresAt > now) return cached.value
-    const value = await fetch()
-    cache.set(key, { value, expiresAt: now + ttl })
-    return value
-  }
-  return {
-    async getPublicKey(senderId) {
-      return get(`pk:${senderId}`, () => inner.getPublicKey(senderId))
-    },
-    async getSharedSecret(keyId) {
-      if (!inner.getSharedSecret) return null
-      return get(`ss:${keyId}`, () => inner.getSharedSecret!(keyId))
-    },
-  }
-}

package/src/keyRotation.test.ts

@@ -1,78 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { createEnvelope, signEnvelopeHmac } from './protocol'
-import { RollingKeyring, createKeyringSignatureResolver } from './keyRotation'
-import { InMemoryReplayCache } from './protocolReplay'
-import { receiveEnvelope } from './protocolTransport'
-
-describe('rolling keyring', () => {
-  it('selects newest active signing key and enforces revocation', () => {
-    const ring = new RollingKeyring([
-      {
-        sender: 'agent.alpha',
-        keyId: 'k-old',
-        alg: 'HS256',
-        status: 'verify-only',
-        notBeforeMs: 1000,
-        notAfterMs: 5000,
-        material: { alg: 'HS256', secret: 'old-secret' },
-      },
-      {
-        sender: 'agent.alpha',
-        keyId: 'k-new',
-        alg: 'HS256',
-        status: 'active',
-        notBeforeMs: 4000,
-        notAfterMs: 9000,
-        material: { alg: 'HS256', secret: 'new-secret' },
-      },
-    ])
-
-    expect(ring.selectSigningKey('agent.alpha', 'HS256', 4500)?.keyId).toBe('k-new')
-    expect(ring.revoke('agent.alpha', 'k-new', 4600)).toBe(true)
-    expect(ring.selectSigningKey('agent.alpha', 'HS256', 4700)).toBeNull()
-  })
-
-  it('resolves verification material and integrates with transport signatureResolver', async () => {
-    const ring = new RollingKeyring([
-      {
-        sender: 'agent.alpha',
-        keyId: 'k1',
-        alg: 'HS256',
-        status: 'active',
-        notBeforeMs: 1000,
-        notAfterMs: 9000,
-        material: { alg: 'HS256', secret: 'shared-secret' },
-      },
-    ])
-
-    const envelope = await signEnvelopeHmac(
-      createEnvelope({
-        sender: 'agent.alpha',
-        intent: 'PING',
-        content: 'hello',
-        messageId: 'kr-1',
-        nonce: 'kr-n1',
-        nowMs: 2000,
-        ttlMs: 60_000,
-      }),
-      'shared-secret',
-      'k1',
-    )
-
-    const ok = await receiveEnvelope(envelope, {
-      nowMs: 3000,
-      replayCache: new InMemoryReplayCache(),
-      signatureResolver: createKeyringSignatureResolver(ring, () => 3000),
-    })
-    expect(ok.ok).toBe(true)
-
-    ring.revoke('agent.alpha', 'k1', 3100)
-    const blocked = await receiveEnvelope(envelope, {
-      nowMs: 3200,
-      replayCache: new InMemoryReplayCache(),
-      signatureResolver: createKeyringSignatureResolver(ring, () => 3200),
-    })
-    expect(blocked.ok).toBe(false)
-    expect(blocked.diagnostics.some((d) => d.message.includes('No signature verification material'))).toBe(true)
-  })
-})