@7h3/protocol 0.4.0 → 0.5.1

package/src/gateway.ts

@@ -1,171 +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'
-
-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

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

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