@7h3/protocol 0.1.2 → 0.5.0

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

package/src/keyRotation.ts

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

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