@7h3/protocol 0.1.2 → 0.5.0

package/src/httpBinding.ts

@@ -0,0 +1,189 @@
+import {
+  type ProtocolEnvelope,
+  type ProtocolDiagnostic,
+  verifyEnvelopeEd25519,
+  verifyEnvelopeHmac,
+  signEnvelopeEd25519,
+  signEnvelopeHmac,
+  createEnvelope,
+  validateEnvelope,
+} from './protocol'
+import type { KeyRegistry } from './keyRegistry'
+import { encodeEnvelopeCbor, decodeEnvelopeCbor, CBOR_CONTENT_TYPE as _CBOR_CONTENT_TYPE } from './envelopeCbor'
+
+export { _CBOR_CONTENT_TYPE as CBOR_CONTENT_TYPE }
+
+export { type KeyRegistry }
+
+export const DEFAULT_HEADER = 'x-7h3-envelope'
+
+export type VerifyFailReason =
+  | 'missing-header'
+  | 'malformed-envelope'
+  | 'unknown-sender'
+  | 'invalid-signature'
+  | 'ttl-expired'
+  | 'validation-error'
+
+export type VerifyHttpResult =
+  | { ok: true; envelope: ProtocolEnvelope }
+  | { ok: false; reason: VerifyFailReason; detail?: string }
+
+export interface HttpBindingOptions {
+  keyRegistry: KeyRegistry
+  headerName?: string
+  strictTtl?: boolean   // default true - reject expired TTL
+}
+
+// Verify the 7h3 envelope from an incoming HTTP request's headers or body
+// If content-type includes '7h3-cbor', decodes body as CBOR instead of JSON
+export async function verifyHttpEnvelope(
+  headers: Record<string, string | string[] | undefined>,
+  opts: HttpBindingOptions,
+  body?: Uint8Array
+): Promise<VerifyHttpResult> {
+  const headerName = opts.headerName ?? DEFAULT_HEADER
+  const contentType = (Array.isArray(headers['content-type']) ? headers['content-type'][0] : headers['content-type']) ?? ''
+
+  let envelope: ProtocolEnvelope
+
+  // CBOR mode: content-type contains '7h3-cbor' and body is provided
+  if (contentType.includes('7h3-cbor') && body instanceof Uint8Array) {
+    try {
+      envelope = decodeEnvelopeCbor(body)
+    } catch (e: unknown) {
+      return { ok: false, reason: 'malformed-envelope', detail: e instanceof Error ? e.message : 'CBOR decode failed' }
+    }
+  } else {
+    // JSON mode: read from header
+    const raw = headers[headerName]
+    const rawStr = Array.isArray(raw) ? raw[0] : raw
+    if (!rawStr) return { ok: false, reason: 'missing-header' }
+
+    try {
+      envelope = JSON.parse(rawStr) as ProtocolEnvelope
+    } catch {
+      return { ok: false, reason: 'malformed-envelope', detail: 'JSON parse failed' }
+    }
+  }
+
+  if (!envelope?.signature || !envelope?.header) {
+    return { ok: false, reason: 'malformed-envelope', detail: 'missing required fields' }
+  }
+
+  const strictTtl = opts.strictTtl ?? true
+  if (strictTtl) {
+    const diags: ProtocolDiagnostic[] = validateEnvelope(envelope)
+    const errors = diags.filter(d => d.level === 'error')
+    if (errors.length > 0) {
+      return { ok: false, reason: 'ttl-expired', detail: errors.map(e => e.message).join('; ') }
+    }
+  }
+
+  const sender = envelope.header.sender
+  const alg = envelope.signature.alg
+
+  if (alg === 'ED25519') {
+    const publicKey = await opts.keyRegistry.getPublicKey(sender)
+    if (!publicKey) return { ok: false, reason: 'unknown-sender', detail: sender }
+    const valid = await verifyEnvelopeEd25519(envelope, publicKey)
+    if (!valid) return { ok: false, reason: 'invalid-signature' }
+  } else if (alg === 'HS256') {
+    const secret = await opts.keyRegistry.getSharedSecret?.(envelope.signature.keyId)
+    if (!secret) return { ok: false, reason: 'unknown-sender', detail: envelope.signature.keyId }
+    const valid = await verifyEnvelopeHmac(envelope, secret)
+    if (!valid) return { ok: false, reason: 'invalid-signature' }
+  } else {
+    return { ok: false, reason: 'malformed-envelope', detail: `unsupported alg: ${String((envelope.signature as any).alg)}` }
+  }
+
+  return { ok: true, envelope }
+}
+
+// Sign an outgoing HTTP request — returns headers to merge in
+// When format is 'cbor', returns binary body + content-type header instead of JSON header
+export async function signHttpRequest(
+  envelope: Omit<ProtocolEnvelope, 'signature'>,
+  privateKey: string,
+  opts?: { headerName?: string; format?: 'cbor' | 'json' }
+): Promise<{ headers: Record<string, string>; body?: Uint8Array }> {
+  const signed = await signEnvelopeEd25519(envelope, privateKey)
+  if (opts?.format === 'cbor') {
+    const body = encodeEnvelopeCbor(signed)
+    return {
+      headers: { 'content-type': _CBOR_CONTENT_TYPE },
+      body,
+    }
+  }
+  return {
+    headers: { [opts?.headerName ?? DEFAULT_HEADER]: JSON.stringify(signed) },
+  }
+}
+
+// Sign with HMAC shared secret
+export async function signHttpRequestHmac(
+  envelope: Omit<ProtocolEnvelope, 'signature'>,
+  secret: string,
+  keyId: string,
+  opts?: { headerName?: string }
+): Promise<{ headers: Record<string, string> }> {
+  const signed = await signEnvelopeHmac(envelope, secret, keyId)
+  return {
+    headers: { [opts?.headerName ?? DEFAULT_HEADER]: JSON.stringify(signed) },
+  }
+}
+
+// Express/Fastify/Hono-compatible middleware factory (fail-closed)
+export function createHttpMiddleware(opts: HttpBindingOptions) {
+  return async function protocol7h3Middleware(
+    req: { headers: Record<string, string | string[] | undefined> },
+    res: { status: (n: number) => { json: (b: unknown) => void } },
+    next: (err?: unknown) => void,
+  ): Promise<void> {
+    const result = await verifyHttpEnvelope(req.headers, opts)
+    if (!result.ok) {
+      res.status(401).json({
+        error: '7h3: request verification failed',
+        reason: result.reason,
+        detail: result.detail,
+      })
+      return
+    }
+    ;(req as any)['7h3Envelope'] = result.envelope
+    next()
+  }
+}
+
+// Fetch API: sign a Request and return a new Request with the envelope header
+export async function signFetchRequest(
+  request: Request,
+  envelope: Omit<ProtocolEnvelope, 'signature'>,
+  privateKey: string,
+  opts?: { headerName?: string }
+): Promise<Request> {
+  const { headers } = await signHttpRequest(envelope, privateKey, opts)
+  const newHeaders = new Headers(request.headers)
+  for (const [k, v] of Object.entries(headers)) newHeaders.set(k, v)
+  return new Request(request, { headers: newHeaders })
+}
+
+// Convenience: build an envelope and sign a Fetch request in one call
+export async function createSignedFetchRequest(
+  request: Request,
+  opts: {
+    privateKey: string
+    sender: string
+    recipient?: string
+    ttlMs?: number
+    headerName?: string
+  }
+): Promise<Request> {
+  const envelope = createEnvelope({
+    sender: opts.sender,
+    recipient: opts.recipient,
+    ttlMs: opts.ttlMs ?? 60_000,
+    intent: 'TASK',
+    content: request.url,
+  })
+  return signFetchRequest(request, envelope, opts.privateKey, { headerName: opts.headerName })
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+export * from './protocol'
+export * from './protocolTransport'
+export * from './protocolBinary'
+export * from './protocolCapabilities'
+export * from './protocolReplay'
+export * from './keyRotation'
+export * from './protocolAgent'
+export * from './agentAdapter'
+export * from './frameworkAdapters'
+export * from './mcpGateway'
+export * from './runtimePolicy'
+export * from './policyEnforcer'
+export * from './runtimePolicyManager'
+export * from './runtimePolicyPresets'
+export * from './policyTelemetryFeedback'
+export * from './redisClient'
+export * from './replayStores'
+export * from './revocation'
+export * from './mcpWrapper'
+export * from './mcpTransports'
+export * from './keyRegistry'
+export * from './httpBinding'
+export * from './webhookBinding'
+export * from './queueBinding'
+export * from './wsBinding'
+export * from './grpcBinding'
+export * from './keyInfra'
+export * from './rateLimiter'
+export * from './routePolicy'
+export * from './gateway'
+export * from './signedResponse'
+export * from './auditLog'
+export * from './telemetry'
+export * from './otel'
+export * from './cborCodec'
+export * from './envelopeCbor'
+export * from './encryption'
+export * from './capability'
+export * from './stream'

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