@7h3/protocol 0.1.2 → 0.5.0

package/src/gateway.test.ts

@@ -0,0 +1,343 @@
+import { describe, it, expect, beforeAll, vi, beforeEach, afterEach } from 'vitest'
+import { createGateway, type GatewayRequest } from './gateway'
+import { createStaticKeyRegistry } from './keyRegistry'
+import { generateEd25519KeypairBase64Url, createEnvelope, signEnvelopeEd25519, signEnvelopeHmac } from './protocol'
+import type { RoutePolicy } from './routePolicy'
+
+let senderKeys: { publicKey: string; privateKey: string }
+let gatewayKeys: { publicKey: string; privateKey: string }
+
+beforeAll(async () => {
+  senderKeys = await generateEd25519KeypairBase64Url()
+  gatewayKeys = await generateEd25519KeypairBase64Url()
+})
+
+async function makeSignedHeader(sender: string, privateKey: string): Promise<Record<string, string>> {
+  const envelope = createEnvelope({
+    sender,
+    intent: 'TASK',
+    content: '/api/test',
+    ttlMs: 60_000,
+  })
+  const signed = await signEnvelopeEd25519(envelope, privateKey)
+  return { 'x-7h3-envelope': JSON.stringify(signed) }
+}
+
+function mockFetch(status: number, body: string, headers: Record<string, string> = {}) {
+  vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+    status,
+    text: () => Promise.resolve(body),
+    headers: new Headers({ 'content-type': 'application/json', ...headers }),
+  }))
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('createGateway', () => {
+  it('returns a gateway with getRateLimiter()', async () => {
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({}),
+    })
+    expect(typeof gw.getRateLimiter).toBe('function')
+    expect(gw.getRateLimiter()).toBeDefined()
+  })
+})
+
+describe('verify()', () => {
+  it('allows request when require=none policy matches', async () => {
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({}),
+      policies: [{ path: '/health', require: 'none' }],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/health', headers: {} }
+    const outcome = await gw.verify(req)
+    expect(outcome.ok).toBe(true)
+  })
+
+  it('allows when no policy matches and defaultPolicy=allow (default)', async () => {
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({}),
+      policies: [],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/unknown', headers: {} }
+    const outcome = await gw.verify(req)
+    expect(outcome.ok).toBe(true)
+  })
+
+  it('denies with 403 when no policy matches and defaultPolicy=deny', async () => {
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({}),
+      defaultPolicy: 'deny',
+      policies: [],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/unknown', headers: {} }
+    const outcome = await gw.verify(req)
+    expect(outcome.ok).toBe(false)
+    if (!outcome.ok) {
+      expect(outcome.status).toBe(403)
+    }
+  })
+
+  it('returns 401 when envelope header is missing', async () => {
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({ 'agent-a': senderKeys.publicKey }),
+      policies: [{ path: '/api/**', require: 'ed25519' }],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/data', headers: {} }
+    const outcome = await gw.verify(req)
+    expect(outcome.ok).toBe(false)
+    if (!outcome.ok) {
+      expect(outcome.status).toBe(401)
+      expect(outcome.reason).toBe('missing-header')
+    }
+  })
+
+  it('returns 401 when signature is invalid (wrong key)', async () => {
+    const wrongKeys = await generateEd25519KeypairBase64Url()
+    const headers = await makeSignedHeader('agent-a', wrongKeys.privateKey) // wrong private key
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({ 'agent-a': senderKeys.publicKey }), // expects different key
+      policies: [{ path: '/api/**', require: 'ed25519' }],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/data', headers }
+    const outcome = await gw.verify(req)
+    expect(outcome.ok).toBe(false)
+    if (!outcome.ok) {
+      expect(outcome.status).toBe(401)
+    }
+  })
+
+  it('returns 401 for unknown sender', async () => {
+    const headers = await makeSignedHeader('unknown-agent', senderKeys.privateKey)
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({}), // empty registry
+      policies: [{ path: '/api/**', require: 'ed25519' }],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/data', headers }
+    const outcome = await gw.verify(req)
+    expect(outcome.ok).toBe(false)
+    if (!outcome.ok) {
+      expect(outcome.status).toBe(401)
+    }
+  })
+
+  it('returns 403 when sender not in allowedSenders', async () => {
+    const headers = await makeSignedHeader('agent-a', senderKeys.privateKey)
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({ 'agent-a': senderKeys.publicKey }),
+      policies: [{ path: '/api/**', require: 'ed25519', allowedSenders: ['agent-b'] }],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/data', headers }
+    const outcome = await gw.verify(req)
+    expect(outcome.ok).toBe(false)
+    if (!outcome.ok) {
+      expect(outcome.status).toBe(403)
+      expect(outcome.reason).toBe('sender-denied')
+    }
+  })
+
+  it('returns 429 when rate limited', async () => {
+    const headers = await makeSignedHeader('agent-a', senderKeys.privateKey)
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({ 'agent-a': senderKeys.publicKey }),
+      policies: [{ path: '/api/**', require: 'ed25519', rateLimit: { requests: 1, windowMs: 10_000 } }],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/data', headers }
+
+    const first = await gw.verify(req)
+    expect(first.ok).toBe(true)
+
+    // Need fresh headers for second call (same sender, same policy)
+    const headers2 = await makeSignedHeader('agent-a', senderKeys.privateKey)
+    const req2: GatewayRequest = { method: 'GET', path: '/api/data', headers: headers2 }
+    const second = await gw.verify(req2)
+    expect(second.ok).toBe(false)
+    if (!second.ok) {
+      expect(second.status).toBe(429)
+    }
+  })
+
+  it('returns 401 when require=ed25519 but HMAC envelope provided', async () => {
+    const sharedSecret = 'my-hmac-secret'
+    const keyId = 'hmac-key-1'
+    const envelope = createEnvelope({ sender: 'agent-a', intent: 'TASK', content: '/api/test', ttlMs: 60_000 })
+    const signed = await signEnvelopeHmac(envelope, sharedSecret, keyId)
+    const headers = { 'x-7h3-envelope': JSON.stringify(signed) }
+
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: {
+        async getPublicKey() { return null },
+        async getSharedSecret() { return sharedSecret },
+      },
+      policies: [{ path: '/api/**', require: 'ed25519' }], // expects ed25519, got hmac
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/data', headers }
+    const outcome = await gw.verify(req)
+    expect(outcome.ok).toBe(false)
+    if (!outcome.ok) {
+      expect(outcome.status).toBe(401)
+    }
+  })
+
+  it('ok verify includes sender', async () => {
+    const headers = await makeSignedHeader('agent-a', senderKeys.privateKey)
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({ 'agent-a': senderKeys.publicKey }),
+      policies: [{ path: '/api/**', require: 'ed25519' }],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/data', headers }
+    const outcome = await gw.verify(req)
+    expect(outcome.ok).toBe(true)
+    if (outcome.ok) {
+      expect(outcome.sender).toBe('agent-a')
+    }
+  })
+})
+
+describe('handle()', () => {
+  it('returns 401 for failed verification', async () => {
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({ 'agent-a': senderKeys.publicKey }),
+      policies: [{ path: '/api/**', require: 'ed25519' }],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/data', headers: {} }
+    const response = await gw.handle(req)
+    expect(response.status).toBe(401)
+    expect(JSON.parse(response.body)).toMatchObject({ error: 'missing-header' })
+  })
+
+  it('returns 403 for sender-denied', async () => {
+    const headers = await makeSignedHeader('agent-a', senderKeys.privateKey)
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({ 'agent-a': senderKeys.publicKey }),
+      policies: [{ path: '/api/**', require: 'ed25519', allowedSenders: ['agent-b'] }],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/data', headers }
+    const response = await gw.handle(req)
+    expect(response.status).toBe(403)
+  })
+
+  it('forwards to upstream when verified and adds x-7h3 headers', async () => {
+    mockFetch(200, '{"ok":true}')
+
+    const headers = await makeSignedHeader('agent-a', senderKeys.privateKey)
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({ 'agent-a': senderKeys.publicKey }),
+      policies: [{ path: '/api/**', require: 'ed25519' }],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/data', headers }
+    const response = await gw.handle(req)
+
+    expect(response.status).toBe(200)
+    expect(response.body).toBe('{"ok":true}')
+
+    // Verify fetch was called with x-7h3 headers
+    const fetchMock = vi.mocked(fetch)
+    expect(fetchMock).toHaveBeenCalledOnce()
+    const [_url, fetchOpts] = fetchMock.mock.calls[0]
+    const forwardedHeaders = fetchOpts?.headers as Record<string, string>
+    expect(forwardedHeaders['x-7h3-sender']).toBe('agent-a')
+    expect(forwardedHeaders['x-7h3-verified']).toBe('true')
+  })
+
+  it('calls upstream at correct URL', async () => {
+    mockFetch(200, 'ok')
+
+    const headers = await makeSignedHeader('agent-a', senderKeys.privateKey)
+    const gw = createGateway({
+      upstream: 'http://myservice.internal',
+      keyRegistry: createStaticKeyRegistry({ 'agent-a': senderKeys.publicKey }),
+      policies: [{ path: '/api/**', require: 'ed25519' }],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/users', headers }
+    await gw.handle(req)
+
+    const fetchMock = vi.mocked(fetch)
+    expect(fetchMock.mock.calls[0][0]).toBe('http://myservice.internal/api/users')
+  })
+
+  it('signs response when privateKey and sender configured', async () => {
+    mockFetch(200, 'response-body')
+
+    const headers = await makeSignedHeader('agent-a', senderKeys.privateKey)
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({ 'agent-a': senderKeys.publicKey }),
+      policies: [{ path: '/api/**', require: 'ed25519' }],
+      privateKey: gatewayKeys.privateKey,
+      sender: 'gateway-agent',
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/data', headers }
+    const response = await gw.handle(req)
+
+    expect(response.status).toBe(200)
+    expect(response.headers['x-7h3-response']).toBeDefined()
+  })
+
+  it('does NOT sign response when signResponses=false', async () => {
+    mockFetch(200, 'response-body')
+
+    const headers = await makeSignedHeader('agent-a', senderKeys.privateKey)
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({ 'agent-a': senderKeys.publicKey }),
+      policies: [{ path: '/api/**', require: 'ed25519' }],
+      privateKey: gatewayKeys.privateKey,
+      sender: 'gateway-agent',
+      signResponses: false,
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/api/data', headers }
+    const response = await gw.handle(req)
+
+    expect(response.headers['x-7h3-response']).toBeUndefined()
+  })
+
+  it('allows unauthenticated route via require=none policy', async () => {
+    mockFetch(200, 'pong')
+
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({}),
+      policies: [{ path: '/health', require: 'none' }],
+    })
+    const req: GatewayRequest = { method: 'GET', path: '/health', headers: {} }
+    const response = await gw.handle(req)
+    expect(response.status).toBe(200)
+    expect(response.body).toBe('pong')
+  })
+
+  it('returns 429 status in response for rate limited', async () => {
+    const headers1 = await makeSignedHeader('agent-a', senderKeys.privateKey)
+    const gw = createGateway({
+      upstream: 'http://upstream',
+      keyRegistry: createStaticKeyRegistry({ 'agent-a': senderKeys.publicKey }),
+      policies: [{ path: '/api/**', require: 'ed25519', rateLimit: { requests: 1, windowMs: 10_000 } }],
+    })
+
+    // First request passes
+    mockFetch(200, 'ok')
+    const r1 = await gw.handle({ method: 'GET', path: '/api/data', headers: headers1 })
+    expect(r1.status).toBe(200)
+
+    // Second request is rate limited
+    const headers2 = await makeSignedHeader('agent-a', senderKeys.privateKey)
+    const r2 = await gw.handle({ method: 'GET', path: '/api/data', headers: headers2 })
+    expect(r2.status).toBe(429)
+  })
+})

package/src/gateway.ts

@@ -0,0 +1,246 @@
+import { type KeyRegistry } from './keyRegistry'
+import { type RoutePolicy, matchPolicy, isAllowedSender } from './routePolicy'
+import { SlidingWindowRateLimiter } from './rateLimiter'
+import { verifyHttpEnvelope } from './httpBinding'
+import { signResponse } from './signedResponse'
+import { metrics as globalMetrics } from './telemetry'
+import type { ReplayStore } from './replayStores'
+import { CAP_HEADER, parseCapabilityChain, verifyCapabilityChain, tokenMatchesScope } from './capability'
+
+export type { KeyRegistry, RoutePolicy }
+
+export interface GatewayConfig {
+  upstream: string
+  keyRegistry: KeyRegistry
+  policies?: RoutePolicy[]
+  privateKey?: string
+  sender?: string
+  signResponses?: boolean // default true when privateKey set
+  defaultPolicy?: 'allow' | 'deny' // default 'allow'
+  headerName?: string
+  metricsPath?: string
+  /** Optional distributed replay store — prevents nonce reuse across gateway instances. */
+  replayStore?: ReplayStore
+  /** Optional capability token registry for capability-based auth. */
+  capabilityRegistry?: { getPublicKey(id: string): Promise<string | null> }
+}
+
+export interface GatewayRequest {
+  method: string
+  path: string
+  headers: Record<string, string | string[]>
+  body?: string
+  url?: string
+}
+
+export interface GatewayResponse {
+  status: number
+  headers: Record<string, string>
+  body: string
+}
+
+export type GatewayVerifyOutcome =
+  | { ok: true; sender: string; envelopeId?: string }
+  | { ok: false; status: 401 | 403 | 429; reason: string }
+
+class Protocol7h3Gateway {
+  private config: GatewayConfig
+  private rateLimiter: SlidingWindowRateLimiter
+
+  constructor(config: GatewayConfig) {
+    this.config = config
+    this.rateLimiter = new SlidingWindowRateLimiter()
+  }
+
+  async verify(req: GatewayRequest): Promise<GatewayVerifyOutcome> {
+    const startMs = performance.now()
+    const policy = matchPolicy(this.config.policies ?? [], req.path)
+
+    // Determine if we skip verification
+    const skipVerify =
+      policy?.require === 'none' ||
+      (!policy && (this.config.defaultPolicy ?? 'allow') === 'allow')
+
+    if (skipVerify) {
+      const durationMs = performance.now() - startMs
+      globalMetrics.verifications_total.increment({ result: 'ok', alg: 'none', transport: 'http' })
+      globalMetrics.verification_duration_ms.observe(durationMs)
+      return { ok: true, sender: '' }
+    }
+
+    // Capability token path — alternative auth via x-7h3-capability header
+    if (this.config.capabilityRegistry) {
+      const rawCap = req.headers[CAP_HEADER]
+      const capHeader = Array.isArray(rawCap) ? rawCap[0] : rawCap
+      if (capHeader) {
+        try {
+          const chain = parseCapabilityChain(capHeader)
+          const result = await verifyCapabilityChain(chain, this.config.capabilityRegistry, {
+            requiredPathGlob: req.path,
+            requiredMethod: req.method,
+          })
+          if (result.ok && tokenMatchesScope(result.token, req.path, req.method)) {
+            const durationMs = performance.now() - startMs
+            globalMetrics.verifications_total.increment({ result: 'ok', alg: 'ED25519', transport: 'http' })
+            globalMetrics.verification_duration_ms.observe(durationMs)
+            return { ok: true, sender: result.token.subject }
+          }
+          const durationMs = performance.now() - startMs
+          globalMetrics.verifications_total.increment({ result: 'fail', alg: 'none', transport: 'http' })
+          globalMetrics.verification_duration_ms.observe(durationMs)
+          return { ok: false, status: 401, reason: result.ok ? 'capability-scope-mismatch' : (result as { ok: false; reason: string }).reason }
+        } catch (e) {
+          const durationMs = performance.now() - startMs
+          globalMetrics.verifications_total.increment({ result: 'fail', alg: 'none', transport: 'http' })
+          globalMetrics.verification_duration_ms.observe(durationMs)
+          return { ok: false, status: 401, reason: 'invalid-capability-chain' }
+        }
+      }
+    }
+
+    // deny if no policy and defaultPolicy is 'deny'
+    if (!policy && (this.config.defaultPolicy ?? 'allow') === 'deny') {
+      const durationMs = performance.now() - startMs
+      globalMetrics.verifications_total.increment({ result: 'fail', alg: 'none', transport: 'http' })
+      globalMetrics.verification_duration_ms.observe(durationMs)
+      globalMetrics.sender_denials_total.increment({ sender: '', path: req.path })
+      return { ok: false, status: 403, reason: 'no-matching-policy' }
+    }
+
+    // Verify the envelope
+    const result = await verifyHttpEnvelope(req.headers, {
+      keyRegistry: this.config.keyRegistry,
+      headerName: this.config.headerName,
+    })
+
+    if (!result.ok) {
+      const durationMs = performance.now() - startMs
+      globalMetrics.verifications_total.increment({ result: 'fail', alg: 'none', transport: 'http' })
+      globalMetrics.verification_duration_ms.observe(durationMs)
+      return { ok: false, status: 401, reason: result.reason }
+    }
+
+    const envelope = result.envelope
+    const sender = envelope.header.sender
+    const envelopeId = envelope.header.messageId
+    const alg = (envelope.signature?.alg as string | undefined) ?? 'none'
+
+    // Check replay store — prevents nonce reuse across multiple gateway instances
+    if (this.config.replayStore) {
+      const replayed = await this.config.replayStore.check(
+        envelope.header.nonce,
+        envelope.header.ttlMs,
+      )
+      if (replayed) {
+        return { ok: false, status: 401, reason: 'replay-detected' }
+      }
+    }
+
+    // Enforce algorithm requirement when policy specifies a specific alg
+    if (policy && policy.require !== 'any') {
+      const actualAlg = envelope.signature?.alg
+      const requiresEd25519 = policy.require === 'ed25519' && actualAlg !== 'ED25519'
+      const requiresHmac = policy.require === 'hmac' && actualAlg !== 'HS256'
+      if (requiresEd25519 || requiresHmac) {
+        const durationMs = performance.now() - startMs
+        globalMetrics.verifications_total.increment({ result: 'fail', alg, transport: 'http' })
+        globalMetrics.verification_duration_ms.observe(durationMs)
+        return { ok: false, status: 401, reason: 'invalid-signature' }
+      }
+    }
+
+    // Check allowedSenders
+    if (policy && !isAllowedSender(policy, sender)) {
+      const durationMs = performance.now() - startMs
+      globalMetrics.verifications_total.increment({ result: 'fail', alg, transport: 'http' })
+      globalMetrics.verification_duration_ms.observe(durationMs)
+      globalMetrics.sender_denials_total.increment({ sender, path: req.path })
+      return { ok: false, status: 403, reason: 'sender-denied' }
+    }
+
+    // Check rate limit
+    if (policy?.rateLimit) {
+      const rl = this.rateLimiter.consume(sender, policy.rateLimit)
+      if (!rl.allowed) {
+        const durationMs = performance.now() - startMs
+        globalMetrics.verifications_total.increment({ result: 'fail', alg, transport: 'http' })
+        globalMetrics.verification_duration_ms.observe(durationMs)
+        globalMetrics.rate_limit_hits_total.increment({ sender, path: req.path })
+        return { ok: false, status: 429, reason: 'rate-limited' }
+      }
+    }
+
+    const durationMs = performance.now() - startMs
+    globalMetrics.verifications_total.increment({ result: 'ok', alg, transport: 'http' })
+    globalMetrics.verification_duration_ms.observe(durationMs)
+    return { ok: true, sender, envelopeId }
+  }
+
+  async handle(req: GatewayRequest): Promise<GatewayResponse> {
+    const outcome = await this.verify(req)
+
+    if (!outcome.ok) {
+      return {
+        status: outcome.status,
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ error: outcome.reason }),
+      }
+    }
+
+    // Build upstream URL
+    const upstreamUrl = this.config.upstream.replace(/\/$/, '') + req.path
+
+    // Build forwarded headers, adding 7h3 metadata
+    const forwardHeaders: Record<string, string> = {}
+    for (const [k, v] of Object.entries(req.headers)) {
+      forwardHeaders[k] = Array.isArray(v) ? v[0] : v
+    }
+    if (outcome.sender) {
+      forwardHeaders['x-7h3-sender'] = outcome.sender
+    }
+    forwardHeaders['x-7h3-verified'] = 'true'
+
+    // Fetch upstream
+    const fetchResponse = await fetch(upstreamUrl, {
+      method: req.method,
+      headers: forwardHeaders,
+      body: req.body,
+    })
+
+    const responseBody = await fetchResponse.text()
+    const responseHeaders: Record<string, string> = {
+      'content-type': fetchResponse.headers.get('content-type') ?? 'application/json',
+    }
+
+    // Sign response if configured
+    const shouldSign =
+      this.config.privateKey !== undefined &&
+      (this.config.signResponses ?? true) &&
+      this.config.sender !== undefined
+
+    if (shouldSign) {
+      const signed = await signResponse(responseBody, {
+        privateKey: this.config.privateKey!,
+        sender: this.config.sender!,
+        recipient: outcome.sender || undefined,
+      })
+      Object.assign(responseHeaders, signed.headers)
+    }
+
+    return {
+      status: fetchResponse.status,
+      headers: responseHeaders,
+      body: responseBody,
+    }
+  }
+
+  getRateLimiter(): SlidingWindowRateLimiter {
+    return this.rateLimiter
+  }
+}
+
+export function createGateway(config: GatewayConfig): Protocol7h3Gateway {
+  return new Protocol7h3Gateway(config)
+}
+
+export { Protocol7h3Gateway }