@7h3/protocol 0.1.2 → 0.4.0

package/src/keyInfra.test.ts

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

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

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

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