@7h3/protocol 0.5.0 → 0.5.1

package/src/httpBinding.ts

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

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

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