@7h3/protocol 0.5.0 → 0.5.1

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)
-  })
-})

package/src/keyRotation.ts

@@ -1,72 +0,0 @@
-import type { ProtocolEnvelope, SignatureVerificationMaterial } from './protocol'
-
-export type KeyStatus = 'active' | 'verify-only' | 'revoked'
-
-export interface KeyRecord {
-  sender: string
-  keyId: string
-  alg: SignatureVerificationMaterial['alg']
-  status: KeyStatus
-  notBeforeMs: number
-  notAfterMs: number
-  material: SignatureVerificationMaterial
-}
-
-export class RollingKeyring {
-  private readonly records: KeyRecord[]
-
-  constructor(records: KeyRecord[] = []) {
-    this.records = [...records]
-  }
-
-  add(record: KeyRecord): void {
-    this.records.push(record)
-  }
-
-  revoke(sender: string, keyId: string, revokedAtMs = Date.now()): boolean {
-    const record = this.records.find((entry) => entry.sender === sender && entry.keyId === keyId)
-    if (!record) return false
-    record.status = 'revoked'
-    record.notAfterMs = Math.min(record.notAfterMs, revokedAtMs)
-    return true
-  }
-
-  selectSigningKey(sender: string, alg: SignatureVerificationMaterial['alg'], nowMs = Date.now()): KeyRecord | null {
-    const candidates = this.records
-      .filter(
-        (entry) =>
-          entry.sender === sender &&
-          entry.alg === alg &&
-          entry.status === 'active' &&
-          entry.notBeforeMs <= nowMs &&
-          nowMs < entry.notAfterMs,
-      )
-      .sort((a, b) => b.notBeforeMs - a.notBeforeMs)
-    return candidates[0] ?? null
-  }
-
-  resolveVerificationMaterial(
-    signature: NonNullable<ProtocolEnvelope['signature']>,
-    sender: string,
-    nowMs = Date.now(),
-  ): SignatureVerificationMaterial | undefined {
-    const candidates = this.records
-      .filter(
-        (entry) =>
-          entry.sender === sender &&
-          entry.keyId === signature.keyId &&
-          entry.alg === signature.alg &&
-          entry.status !== 'revoked' &&
-          entry.notBeforeMs <= nowMs &&
-          nowMs < entry.notAfterMs,
-      )
-      .sort((a, b) => b.notBeforeMs - a.notBeforeMs)
-
-    return candidates[0]?.material
-  }
-}
-
-export function createKeyringSignatureResolver(keyring: RollingKeyring, nowMsProvider: () => number = () => Date.now()) {
-  return async (signature: NonNullable<ProtocolEnvelope['signature']>, sender: string): Promise<SignatureVerificationMaterial | undefined> =>
-    keyring.resolveVerificationMaterial(signature, sender, nowMsProvider())
-}

package/src/mcpGateway.test.ts

@@ -1,129 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { createAipMcpGatewayRuntime } from './mcpGateway'
-
-describe('AIP MCP gateway runtime', () => {
-  it('returns JSON-RPC result for allowed method', async () => {
-    const runtime = createAipMcpGatewayRuntime({ sharedSecret: 'gateway-test-secret' })
-
-    const line = JSON.stringify({
-      jsonrpc: '2.0',
-      id: 1,
-      method: 'tools/call',
-      params: { name: 'planner' },
-    })
-
-    const responseLine = await runtime.handleLine(line)
-    expect(responseLine).not.toBeNull()
-    const response = JSON.parse(responseLine ?? '{}') as {
-      jsonrpc: string
-      id: number
-      result?: { ok: boolean; capability: string }
-      error?: { code: number; message: string }
-    }
-
-    expect(response.jsonrpc).toBe('2.0')
-    expect(response.id).toBe(1)
-    expect(response.error).toBeUndefined()
-    expect(response.result?.ok).toBe(true)
-    expect(response.result?.capability).toBe('mcp.tools/call')
-  })
-
-  it('returns invalid request for malformed JSON-RPC line', async () => {
-    const runtime = createAipMcpGatewayRuntime({ sharedSecret: 'gateway-test-secret' })
-    const responseLine = await runtime.handleLine('{"bad": true}')
-    const response = JSON.parse(responseLine ?? '{}') as { error?: { code: number; message: string } }
-
-    expect(response.error?.code).toBe(-32600)
-    expect(response.error?.message).toBe('Invalid Request')
-  })
-
-  it('returns method not found for disallowed method', async () => {
-    const runtime = createAipMcpGatewayRuntime({
-      sharedSecret: 'gateway-test-secret',
-      allowedMethods: ['tools/call'],
-    })
-
-    const line = JSON.stringify({
-      jsonrpc: '2.0',
-      id: 'x',
-      method: 'resources/read',
-      params: {},
-    })
-
-    const responseLine = await runtime.handleLine(line)
-    const response = JSON.parse(responseLine ?? '{}') as { error?: { code: number; message: string } }
-
-    expect(response.error?.code).toBe(-32601)
-    expect(response.error?.message).toContain("is not allowed")
-  })
-
-  it('returns authorization error when policy hook blocks request', async () => {
-    const runtime = createAipMcpGatewayRuntime({
-      sharedSecret: 'gateway-test-secret',
-      authorizeMethod: async () => false,
-    })
-
-    const line = JSON.stringify({
-      jsonrpc: '2.0',
-      id: 'auth-2',
-      method: 'tools/call',
-      params: {},
-    })
-
-    const responseLine = await runtime.handleLine(line)
-    const response = JSON.parse(responseLine ?? '{}') as { error?: { code: number; message: string } }
-
-    expect(response.error?.code).toBe(-32001)
-    expect(response.error?.message).toContain('not authorized')
-  })
-
-  it('returns rate-limit error when limiter blocks request', async () => {
-    const runtime = createAipMcpGatewayRuntime({
-      sharedSecret: 'gateway-test-secret',
-      rateLimiter: {
-        consume: async () => false,
-      },
-    })
-
-    const line = JSON.stringify({
-      jsonrpc: '2.0',
-      id: 'rl-3',
-      method: 'tools/call',
-      params: {},
-    })
-
-    const responseLine = await runtime.handleLine(line)
-    const response = JSON.parse(responseLine ?? '{}') as { error?: { code: number; message: string } }
-
-    expect(response.error?.code).toBe(-32002)
-    expect(response.error?.message).toContain('rate-limited')
-  })
-
-  it('ignores empty lines', async () => {
-    const runtime = createAipMcpGatewayRuntime({ sharedSecret: 'gateway-test-secret' })
-    await expect(runtime.handleLine('   ')).resolves.toBeNull()
-  })
-
-  it('emits audit events for policy and request phases', async () => {
-    const phases: string[] = []
-    const runtime = createAipMcpGatewayRuntime({
-      sharedSecret: 'gateway-test-secret',
-      onAuditEvent: async (event) => {
-        phases.push(event.phase)
-      },
-    })
-
-    const line = JSON.stringify({
-      jsonrpc: '2.0',
-      id: 'audit-1',
-      method: 'tools/call',
-      params: { name: 'planner' },
-    })
-
-    const responseLine = await runtime.handleLine(line)
-    expect(responseLine).not.toBeNull()
-    expect(phases).toContain('request_received')
-    expect(phases).toContain('policy')
-    expect(phases).toContain('request_success')
-  })
-})