@7h3/protocol 0.5.0 → 0.5.2

package/src/gateway.test.ts

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

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