@7h3/protocol 0.1.2 → 0.4.0

package/src/httpBinding.test.ts

@@ -0,0 +1,376 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  verifyHttpEnvelope,
+  signHttpRequest,
+  signHttpRequestHmac,
+  createHttpMiddleware,
+  signFetchRequest,
+  createSignedFetchRequest,
+  DEFAULT_HEADER,
+} from './httpBinding'
+import { createStaticKeyRegistry, type KeyRegistry } from './keyRegistry'
+import {
+  generateEd25519KeypairBase64Url,
+  createEnvelope,
+  signEnvelopeEd25519,
+  signEnvelopeHmac,
+  type ProtocolEnvelope,
+} from './protocol'
+
+// Helper: build a static KeyRegistry that also holds HMAC shared secrets
+function createHmacKeyRegistry(secrets: Record<string, string>): KeyRegistry {
+  return {
+    async getPublicKey() { return null },
+    async getSharedSecret(keyId) { return secrets[keyId] ?? null },
+  }
+}
+
+describe('verifyHttpEnvelope', () => {
+  it('returns missing-header when header is absent', async () => {
+    const registry = createStaticKeyRegistry({})
+    const result = await verifyHttpEnvelope({}, { keyRegistry: registry })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('missing-header')
+  })
+
+  it('returns missing-header when header value is undefined', async () => {
+    const registry = createStaticKeyRegistry({})
+    const result = await verifyHttpEnvelope(
+      { [DEFAULT_HEADER]: undefined },
+      { keyRegistry: registry },
+    )
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('missing-header')
+  })
+
+  it('returns malformed-envelope for invalid JSON', async () => {
+    const registry = createStaticKeyRegistry({})
+    const result = await verifyHttpEnvelope(
+      { [DEFAULT_HEADER]: 'not-json' },
+      { keyRegistry: registry },
+    )
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toBe('malformed-envelope')
+      expect(result.detail).toContain('JSON parse failed')
+    }
+  })
+
+  it('returns malformed-envelope when required fields are missing', async () => {
+    const registry = createStaticKeyRegistry({})
+    const result = await verifyHttpEnvelope(
+      { [DEFAULT_HEADER]: JSON.stringify({ header: {} }) },
+      { keyRegistry: registry },
+    )
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('malformed-envelope')
+  })
+
+  it('passes a valid Ed25519 signed envelope', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-alice'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hello', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(signed) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.envelope.header.sender).toBe(sender)
+  })
+
+  it('returns invalid-signature when envelope is tampered', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-bob'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hello', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+
+    // Tamper with the content after signing
+    const tampered: ProtocolEnvelope = {
+      ...signed,
+      body: { ...signed.body, content: 'tampered-content' },
+    }
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(tampered) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('invalid-signature')
+  })
+
+  it('returns unknown-sender when sender is not in registry', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const registry = createStaticKeyRegistry({}) // empty registry
+
+    const env = createEnvelope({ sender: 'unknown-agent', intent: 'PING', content: 'hi', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(signed) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toBe('unknown-sender')
+      expect(result.detail).toBe('unknown-agent')
+    }
+  })
+
+  it('returns ttl-expired for an expired envelope', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-expired'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    // Create envelope with past timestamp so it is already expired
+    const pastNow = Date.now() - 120_000 // 2 minutes ago
+    const env = createEnvelope({
+      sender,
+      intent: 'PING',
+      content: 'hello',
+      ttlMs: 1_000,      // 1 second TTL
+      nowMs: pastNow,
+    })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(signed) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry, strictTtl: true })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('ttl-expired')
+  })
+
+  it('skips TTL check when strictTtl is false', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-nostrictttl'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const pastNow = Date.now() - 120_000
+    const env = createEnvelope({
+      sender,
+      intent: 'PING',
+      content: 'hello',
+      ttlMs: 1_000,
+      nowMs: pastNow,
+    })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(signed) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry, strictTtl: false })
+    expect(result.ok).toBe(true)
+  })
+})
+
+describe('signHttpRequest + verifyHttpEnvelope round trip (Ed25519)', () => {
+  it('signs and verifies successfully', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-roundtrip'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'do something', ttlMs: 60_000 })
+    const { headers } = await signHttpRequest(env, privateKey)
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.envelope.header.sender).toBe(sender)
+      expect(result.envelope.body.intent).toBe('TASK')
+    }
+  })
+
+  it('uses custom header name when provided', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-custom-header'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+    const customHeader = 'x-custom-sig'
+
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hi', ttlMs: 60_000 })
+    const { headers } = await signHttpRequest(env, privateKey, { headerName: customHeader })
+
+    expect(headers[customHeader]).toBeDefined()
+    expect(headers[DEFAULT_HEADER]).toBeUndefined()
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry, headerName: customHeader })
+    expect(result.ok).toBe(true)
+  })
+})
+
+describe('createHttpMiddleware', () => {
+  it('calls next() when envelope is valid', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-middleware'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hi', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const req = { headers: { [DEFAULT_HEADER]: JSON.stringify(signed) } }
+
+    const res = { status: vi.fn().mockReturnThis(), json: vi.fn() }
+    const next = vi.fn()
+
+    const middleware = createHttpMiddleware({ keyRegistry: registry })
+    await middleware(req, res as any, next)
+
+    expect(next).toHaveBeenCalledOnce()
+    expect(next).toHaveBeenCalledWith()  // no error argument
+    expect(res.status).not.toHaveBeenCalled()
+    // The envelope should be attached to req
+    expect((req as any)['7h3Envelope']).toBeDefined()
+  })
+
+  it('returns 401 and does not call next() when envelope is missing', async () => {
+    const registry = createStaticKeyRegistry({})
+    const req = { headers: {} }
+    const jsonMock = vi.fn()
+    const res = { status: vi.fn().mockReturnValue({ json: jsonMock }) }
+    const next = vi.fn()
+
+    const middleware = createHttpMiddleware({ keyRegistry: registry })
+    await middleware(req, res as any, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(jsonMock).toHaveBeenCalledWith(
+      expect.objectContaining({ reason: 'missing-header' }),
+    )
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('returns 401 for invalid signature', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const { privateKey: otherPrivateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-bad-sig'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hi', ttlMs: 60_000 })
+    // Sign with wrong key
+    const signed = await signEnvelopeEd25519(env, otherPrivateKey)
+    const req = { headers: { [DEFAULT_HEADER]: JSON.stringify(signed) } }
+
+    const jsonMock = vi.fn()
+    const res = { status: vi.fn().mockReturnValue({ json: jsonMock }) }
+    const next = vi.fn()
+
+    const middleware = createHttpMiddleware({ keyRegistry: registry })
+    await middleware(req, res as any, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(next).not.toHaveBeenCalled()
+  })
+})
+
+describe('signFetchRequest', () => {
+  it('adds the envelope header to a Request', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-fetch'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'fetch-task', ttlMs: 60_000 })
+    const originalRequest = new Request('https://example.com/api')
+    const signedRequest = await signFetchRequest(originalRequest, env, privateKey)
+
+    expect(signedRequest.headers.get(DEFAULT_HEADER)).not.toBeNull()
+
+    // Parse and verify
+    const headerVal = signedRequest.headers.get(DEFAULT_HEADER)!
+    const headers = { [DEFAULT_HEADER]: headerVal }
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(true)
+  })
+
+  it('preserves existing headers on the Request', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-headers'
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hi', ttlMs: 60_000 })
+    const originalRequest = new Request('https://example.com/api', {
+      headers: { 'Authorization': 'Bearer token123', 'Content-Type': 'application/json' },
+    })
+    const signedRequest = await signFetchRequest(originalRequest, env, privateKey)
+
+    expect(signedRequest.headers.get('Authorization')).toBe('Bearer token123')
+    expect(signedRequest.headers.get('Content-Type')).toBe('application/json')
+    expect(signedRequest.headers.get(DEFAULT_HEADER)).not.toBeNull()
+  })
+})
+
+describe('HMAC round trip', () => {
+  it('signs with HMAC and verifies successfully', async () => {
+    const secret = 'super-secret-hmac-key'
+    const keyId = 'hmac-key-1'
+    const sender = 'agent-hmac'
+    const registry = createHmacKeyRegistry({ [keyId]: secret })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'hmac task', ttlMs: 60_000 })
+    const { headers } = await signHttpRequestHmac(env, secret, keyId)
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.envelope.header.sender).toBe(sender)
+      expect(result.envelope.signature?.alg).toBe('HS256')
+    }
+  })
+
+  it('returns invalid-signature when HMAC tampered', async () => {
+    const secret = 'super-secret-hmac-key'
+    const keyId = 'hmac-key-2'
+    const sender = 'agent-hmac-tamper'
+    const registry = createHmacKeyRegistry({ [keyId]: secret })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'hmac task', ttlMs: 60_000 })
+    const signed = await signEnvelopeHmac(env, secret, keyId)
+
+    const tampered: ProtocolEnvelope = {
+      ...signed,
+      body: { ...signed.body, content: 'tampered' },
+    }
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(tampered) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('invalid-signature')
+  })
+
+  it('returns unknown-sender when HMAC keyId not in registry', async () => {
+    const secret = 'super-secret-hmac-key'
+    const keyId = 'hmac-key-missing'
+    const sender = 'agent-hmac-unknown'
+    const registry = createHmacKeyRegistry({}) // empty
+
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hi', ttlMs: 60_000 })
+    const signed = await signEnvelopeHmac(env, secret, keyId)
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(signed) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toBe('unknown-sender')
+      expect(result.detail).toBe(keyId)
+    }
+  })
+})
+
+describe('createSignedFetchRequest', () => {
+  it('creates a signed fetch request with correct sender', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-create-signed'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const originalRequest = new Request('https://example.com/api/task')
+    const signedRequest = await createSignedFetchRequest(originalRequest, {
+      privateKey,
+      sender,
+      ttlMs: 60_000,
+    })
+
+    const headerVal = signedRequest.headers.get(DEFAULT_HEADER)
+    expect(headerVal).not.toBeNull()
+
+    const result = await verifyHttpEnvelope(
+      { [DEFAULT_HEADER]: headerVal! },
+      { keyRegistry: registry },
+    )
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.envelope.header.sender).toBe(sender)
+      expect(result.envelope.body.intent).toBe('TASK')
+    }
+  })
+})

package/src/httpBinding.ts

@@ -0,0 +1,163 @@
+import {
+  type ProtocolEnvelope,
+  type ProtocolDiagnostic,
+  verifyEnvelopeEd25519,
+  verifyEnvelopeHmac,
+  signEnvelopeEd25519,
+  signEnvelopeHmac,
+  createEnvelope,
+  validateEnvelope,
+} from './protocol'
+import type { KeyRegistry } from './keyRegistry'
+
+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
+export async function verifyHttpEnvelope(
+  headers: Record<string, string | string[] | undefined>,
+  opts: HttpBindingOptions
+): Promise<VerifyHttpResult> {
+  const headerName = opts.headerName ?? DEFAULT_HEADER
+  const raw = headers[headerName]
+  const rawStr = Array.isArray(raw) ? raw[0] : raw
+  if (!rawStr) return { ok: false, reason: 'missing-header' }
+
+  let envelope: ProtocolEnvelope
+  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
+export async function signHttpRequest(
+  envelope: Omit<ProtocolEnvelope, 'signature'>,
+  privateKey: string,
+  opts?: { headerName?: string }
+): Promise<{ headers: Record<string, string> }> {
+  const signed = await signEnvelopeEd25519(envelope, privateKey)
+  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,32 @@
+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'