@7h3/protocol 0.1.2 → 0.4.0

package/src/gateway.ts

@@ -0,0 +1,171 @@
+import { type KeyRegistry } from './keyRegistry'
+import { type RoutePolicy, matchPolicy, isAllowedSender } from './routePolicy'
+import { SlidingWindowRateLimiter } from './rateLimiter'
+import { verifyHttpEnvelope } from './httpBinding'
+import { signResponse } from './signedResponse'
+
+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
+}
+
+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 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) {
+      return { ok: true, sender: '' }
+    }
+
+    // deny if no policy and defaultPolicy is 'deny'
+    if (!policy && (this.config.defaultPolicy ?? 'allow') === 'deny') {
+      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) {
+      return { ok: false, status: 401, reason: result.reason }
+    }
+
+    const envelope = result.envelope
+    const sender = envelope.header.sender
+    const envelopeId = envelope.header.messageId
+
+    // 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) {
+        return { ok: false, status: 401, reason: 'invalid-signature' }
+      }
+    }
+
+    // Check allowedSenders
+    if (policy && !isAllowedSender(policy, sender)) {
+      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) {
+        return { ok: false, status: 429, reason: 'rate-limited' }
+      }
+    }
+
+    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 }

package/src/grpcBinding.test.ts

@@ -0,0 +1,211 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  signGrpcCall,
+  verifyGrpcCall,
+  withGrpcVerification,
+  GRPC_METADATA_KEY,
+} from './grpcBinding'
+import { createStaticKeyRegistry, type KeyRegistry } from './keyRegistry'
+import {
+  generateEd25519KeypairBase64Url,
+  createEnvelope,
+  signEnvelopeEd25519,
+  type ProtocolEnvelope,
+} from './protocol'
+
+// Helper: build a KeyRegistry that holds HMAC shared secrets but no public keys
+function createHmacKeyRegistry(secrets: Record<string, string>): KeyRegistry {
+  return {
+    async getPublicKey() { return null },
+    async getSharedSecret(keyId) { return secrets[keyId] ?? null },
+  }
+}
+
+describe('signGrpcCall', () => {
+  it('produces metadata with the correct key', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-client-agent'
+
+    const metadata = await signGrpcCall({ privateKey, sender })
+
+    expect(metadata[GRPC_METADATA_KEY]).toBeDefined()
+    expect(typeof metadata[GRPC_METADATA_KEY]).toBe('string')
+
+    // Parse and validate structure
+    const parsed = JSON.parse(metadata[GRPC_METADATA_KEY]) as ProtocolEnvelope
+    expect(parsed.header.sender).toBe(sender)
+    expect(parsed.signature?.alg).toBe('ED25519')
+  })
+
+  it('uses a custom metadataKey when provided', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const customKey = 'x-custom-grpc-sig'
+
+    const metadata = await signGrpcCall({ privateKey, sender: 'agent-x', metadataKey: customKey })
+
+    expect(metadata[customKey]).toBeDefined()
+    expect(metadata[GRPC_METADATA_KEY]).toBeUndefined()
+  })
+})
+
+describe('verifyGrpcCall', () => {
+  it('valid signed call returns ok:true with envelope', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-server-agent'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const metadata = await signGrpcCall({ privateKey, sender })
+    const result = await verifyGrpcCall(metadata, { 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('missing metadata returns ok:false with code 16', async () => {
+    const registry = createStaticKeyRegistry({})
+    const result = await verifyGrpcCall({}, { keyRegistry: registry })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.code).toBe(16)
+      expect(result.message).toContain('missing')
+    }
+  })
+
+  it('tampered envelope returns ok:false with code 16', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-tamper-agent'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'original', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+
+    // Tamper with content after signing
+    const tampered: ProtocolEnvelope = {
+      ...signed,
+      body: { ...signed.body, content: 'tampered' },
+    }
+    const metadata = { [GRPC_METADATA_KEY]: JSON.stringify(tampered) }
+
+    const result = await verifyGrpcCall(metadata, { keyRegistry: registry })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.code).toBe(16)
+    }
+  })
+
+  it('expired envelope returns ok:false with code 4', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-expired-agent'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const pastNow = Date.now() - 120_000 // 2 minutes ago
+    const env = createEnvelope({
+      sender,
+      intent: 'TASK',
+      content: 'expired-task',
+      ttlMs: 1_000, // 1 second TTL — already expired
+      nowMs: pastNow,
+    })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const metadata = { [GRPC_METADATA_KEY]: JSON.stringify(signed) }
+
+    const result = await verifyGrpcCall(metadata, { keyRegistry: registry, strictTtl: true })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.code).toBe(4)
+    }
+  })
+
+  it('unknown sender returns ok:false with code 16', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const registry = createStaticKeyRegistry({}) // empty registry
+
+    const env = createEnvelope({ sender: 'unknown-grpc-agent', intent: 'TASK', content: 'hi', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const metadata = { [GRPC_METADATA_KEY]: JSON.stringify(signed) }
+
+    const result = await verifyGrpcCall(metadata, { keyRegistry: registry })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.code).toBe(16)
+      expect(result.message).toContain('unknown-grpc-agent')
+    }
+  })
+
+  it('accepts Buffer values in metadata', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-buffer-agent'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'buf-test', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const metadata: Record<string, Buffer> = {
+      [GRPC_METADATA_KEY]: Buffer.from(JSON.stringify(signed), 'utf8'),
+    }
+
+    const result = await verifyGrpcCall(metadata, { keyRegistry: registry })
+    expect(result.ok).toBe(true)
+  })
+
+  it('accepts string array values in metadata', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-array-agent'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'arr-test', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const metadata: Record<string, string[]> = {
+      [GRPC_METADATA_KEY]: [JSON.stringify(signed)],
+    }
+
+    const result = await verifyGrpcCall(metadata, { keyRegistry: registry })
+    expect(result.ok).toBe(true)
+  })
+})
+
+describe('withGrpcVerification', () => {
+  it('calls handler on valid call and attaches envelope to call object', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-wrap-agent'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const signedMeta = await signGrpcCall({ privateKey, sender })
+    const call = { metadata: signedMeta, someField: 'value' }
+
+    const handler = vi.fn().mockResolvedValue({ status: 'ok' })
+    const wrapped = withGrpcVerification(handler, { keyRegistry: registry })
+
+    const response = await wrapped(call)
+
+    expect(handler).toHaveBeenCalledOnce()
+    expect(handler).toHaveBeenCalledWith(call)
+    expect(response).toEqual({ status: 'ok' })
+    expect((call as any)['7h3Envelope']).toBeDefined()
+    expect((call as any)['7h3Envelope'].header.sender).toBe(sender)
+  })
+
+  it('throws on invalid call and does not invoke handler', async () => {
+    const registry = createStaticKeyRegistry({})
+    const call = { metadata: {} } // no envelope metadata
+
+    const handler = vi.fn().mockResolvedValue({ status: 'ok' })
+    const wrapped = withGrpcVerification(handler, { keyRegistry: registry })
+
+    await expect(wrapped(call)).rejects.toThrow()
+    expect(handler).not.toHaveBeenCalled()
+
+    // The thrown error should carry the gRPC status code
+    try {
+      await wrapped(call)
+    } catch (err: any) {
+      expect(err.code).toBe(16)
+    }
+  })
+})

package/src/grpcBinding.ts

@@ -0,0 +1,103 @@
+import {
+  signEnvelopeEd25519,
+  verifyEnvelopeEd25519, verifyEnvelopeHmac,
+  createEnvelope, validateEnvelope,
+  type ProtocolEnvelope,
+} from './protocol'
+import type { KeyRegistry } from './keyRegistry'
+
+export { type KeyRegistry }
+
+export const GRPC_METADATA_KEY = '7h3-envelope-bin'  // -bin suffix = binary safe in gRPC
+
+export interface GrpcSignOptions {
+  privateKey: string
+  sender: string
+  recipient?: string
+  ttlMs?: number
+  metadataKey?: string
+}
+
+export interface GrpcVerifyOptions {
+  keyRegistry: KeyRegistry
+  metadataKey?: string
+  strictTtl?: boolean
+}
+
+export type GrpcVerifyResult =
+  | { ok: true; envelope: ProtocolEnvelope }
+  | { ok: false; code: number; message: string }  // code = gRPC status code
+
+// Client side: produce metadata to attach to outbound call
+export async function signGrpcCall(
+  opts: GrpcSignOptions
+): Promise<Record<string, string>> {
+  const envelope = createEnvelope({
+    sender: opts.sender,
+    recipient: opts.recipient,
+    ttlMs: opts.ttlMs ?? 60_000,
+    intent: 'TASK',
+    content: 'grpc-call',
+  })
+  const signed = await signEnvelopeEd25519(envelope, opts.privateKey)
+  return { [opts.metadataKey ?? GRPC_METADATA_KEY]: JSON.stringify(signed) }
+}
+
+// Server side: verify metadata from incoming call
+export async function verifyGrpcCall(
+  metadata: Record<string, string | Buffer | string[]>,
+  opts: GrpcVerifyOptions
+): Promise<GrpcVerifyResult> {
+  const key = opts.metadataKey ?? GRPC_METADATA_KEY
+  const raw = metadata[key]
+  const rawStr = Array.isArray(raw) ? raw[0] : (raw instanceof Uint8Array ? new TextDecoder().decode(raw) : raw)
+  if (!rawStr) return { ok: false, code: 16, message: '7h3: missing gRPC envelope metadata' }
+
+  let envelope: ProtocolEnvelope
+  try { envelope = JSON.parse(typeof rawStr === 'string' ? rawStr : String(rawStr)) as ProtocolEnvelope }
+  catch { return { ok: false, code: 3, message: '7h3: malformed envelope metadata' } }
+
+  if (opts.strictTtl !== false) {
+    const diags = validateEnvelope(envelope)
+    if (diags.some(d => d.level === 'error')) {
+      return { ok: false, code: 4, message: '7h3: envelope expired or invalid' }
+    }
+  }
+
+  const sender = envelope.header?.sender
+  const alg = envelope.signature?.alg
+  if (!sender || !alg) return { ok: false, code: 3, message: '7h3: missing sender or alg' }
+
+  if (alg === 'ED25519') {
+    const publicKey = await opts.keyRegistry.getPublicKey(sender)
+    if (!publicKey) return { ok: false, code: 16, message: `7h3: unknown sender ${sender}` }
+    const valid = await verifyEnvelopeEd25519(envelope, publicKey)
+    if (!valid) return { ok: false, code: 16, message: '7h3: invalid signature' }
+  } else if (alg === 'HS256') {
+    const secret = await opts.keyRegistry.getSharedSecret?.(envelope.signature!.keyId)
+    if (!secret) return { ok: false, code: 16, message: '7h3: unknown key' }
+    const valid = await verifyEnvelopeHmac(envelope, secret)
+    if (!valid) return { ok: false, code: 16, message: '7h3: invalid signature' }
+  } else {
+    return { ok: false, code: 3, message: `7h3: unsupported alg ${String(alg)}` }
+  }
+
+  return { ok: true, envelope }
+}
+
+// Factory: creates a function that wraps any async gRPC handler with verify logic
+// Usage: const handler = withGrpcVerification(myHandler, verifyOpts)
+export function withGrpcVerification<TCall extends { metadata: Record<string, string | Buffer | string[]> }, TResp>(
+  handler: (call: TCall) => Promise<TResp>,
+  opts: GrpcVerifyOptions
+): (call: TCall) => Promise<TResp> {
+  return async (call: TCall) => {
+    const result = await verifyGrpcCall(call.metadata, opts)
+    if (!result.ok) {
+      const err = Object.assign(new Error(result.message), { code: result.code })
+      throw err
+    }
+    ;(call as any)['7h3Envelope'] = result.envelope
+    return handler(call)
+  }
+}