@7h3/protocol 0.1.2 → 0.4.0

package/src/frameworkAdapters.ts

@@ -0,0 +1,261 @@
+import { type AipAgentAdapter } from './agentAdapter'
+import { type ProtocolEnvelope } from './protocol'
+import { type WireEnvelope } from './protocolTransport'
+
+export interface LangChainMessageLike {
+  content: string
+  name?: string
+  additionalKwargs?: Record<string, unknown>
+}
+
+export interface LlamaIndexMessageLike {
+  role: 'user' | 'assistant' | 'system'
+  content: string
+  additionalKwargs?: Record<string, unknown>
+}
+
+export interface JsonRpcError {
+  code: number
+  message: string
+  data?: unknown
+}
+
+export interface JsonRpcRequestLike {
+  jsonrpc: '2.0'
+  id: string | number
+  method: string
+  params?: unknown
+}
+
+export interface JsonRpcResponseLike {
+  jsonrpc: '2.0'
+  id: string | number
+  result?: unknown
+  error?: JsonRpcError
+}
+
+export interface JsonRpcBridgeOptions {
+  recipient?: string
+  allowedMethods?: readonly string[]
+  methodToCapability?: (method: string) => string
+  authorizeMethod?: (request: JsonRpcRequestLike, context: JsonRpcPolicyContext) => boolean | Promise<boolean>
+  rateLimitKey?: (request: JsonRpcRequestLike, context: JsonRpcPolicyContext) => string
+  rateLimiter?: {
+    consume: (key: string, request: JsonRpcRequestLike, context: JsonRpcPolicyContext) => boolean | Promise<boolean>
+  }
+  onPolicyEvent?: (event: JsonRpcPolicyEvent) => void | Promise<void>
+}
+
+export interface JsonRpcPolicyContext {
+  intent: 'TASK'
+  recipient?: string
+  capability: string
+  correlationId: string
+  createdAtMs: number
+}
+
+export interface JsonRpcPolicyEvent {
+  stage: 'allowlist' | 'authorize' | 'rateLimit'
+  decision: 'allow' | 'deny'
+  method: string
+  context: JsonRpcPolicyContext
+  reason?: string
+}
+
+export interface JsonRpcResponseOptions {
+  defaultErrorCode?: number
+}
+
+export async function createRawTaskFromLangChain(
+  adapter: AipAgentAdapter,
+  message: LangChainMessageLike,
+  options: { recipient?: string; capability?: string; correlationId?: string } = {},
+): Promise<WireEnvelope> {
+  return adapter.createRawIntent({
+    recipient: options.recipient,
+    intent: 'TASK',
+    content: message.content,
+    capability: options.capability,
+    correlationId: options.correlationId,
+  })
+}
+
+export function toLangChainMessage(envelope: ProtocolEnvelope): LangChainMessageLike {
+  return {
+    content: envelope.body.content,
+    name: envelope.body.intent,
+    additionalKwargs: {
+      capability: envelope.body.capability,
+      correlationId: envelope.body.correlationId,
+      sender: envelope.header.sender,
+      recipient: envelope.header.recipient,
+      messageId: envelope.header.messageId,
+      timestampMs: envelope.header.timestampMs,
+    },
+  }
+}
+
+export async function createRawTaskFromLlamaIndex(
+  adapter: AipAgentAdapter,
+  message: LlamaIndexMessageLike,
+  options: { recipient?: string; capability?: string; correlationId?: string } = {},
+): Promise<WireEnvelope> {
+  return adapter.createRawIntent({
+    recipient: options.recipient,
+    intent: 'TASK',
+    content: message.content,
+    capability: options.capability,
+    correlationId: options.correlationId,
+  })
+}
+
+export function toLlamaIndexMessage(envelope: ProtocolEnvelope): LlamaIndexMessageLike {
+  const role: LlamaIndexMessageLike['role'] = envelope.body.intent === 'TASK' ? 'user' : 'assistant'
+  return {
+    role,
+    content: envelope.body.content,
+    additionalKwargs: {
+      intent: envelope.body.intent,
+      capability: envelope.body.capability,
+      correlationId: envelope.body.correlationId,
+      sender: envelope.header.sender,
+      recipient: envelope.header.recipient,
+    },
+  }
+}
+
+function createMcpCapability(method: string): string {
+  return `mcp.${method}`
+}
+
+export async function createRawTaskFromJsonRpc(
+  adapter: AipAgentAdapter,
+  request: JsonRpcRequestLike,
+  options: JsonRpcBridgeOptions = {},
+): Promise<WireEnvelope> {
+  async function emitPolicyEvent(event: JsonRpcPolicyEvent): Promise<void> {
+    if (options.onPolicyEvent) await options.onPolicyEvent(event)
+  }
+
+  if (options.allowedMethods && !options.allowedMethods.includes(request.method)) {
+    const capability = options.methodToCapability
+      ? options.methodToCapability(request.method)
+      : createMcpCapability(request.method)
+    const blockedContext: JsonRpcPolicyContext = {
+      intent: 'TASK',
+      recipient: options.recipient,
+      capability,
+      correlationId: String(request.id),
+      createdAtMs: Date.now(),
+    }
+    await emitPolicyEvent({
+      stage: 'allowlist',
+      decision: 'deny',
+      method: request.method,
+      context: blockedContext,
+      reason: 'method_not_allowed',
+    })
+    throw new Error(`JSON-RPC method '${request.method}' is not allowed`)
+  }
+
+  const capability = options.methodToCapability
+    ? options.methodToCapability(request.method)
+    : createMcpCapability(request.method)
+  const context: JsonRpcPolicyContext = {
+    intent: 'TASK',
+    recipient: options.recipient,
+    capability,
+    correlationId: String(request.id),
+    createdAtMs: Date.now(),
+  }
+
+  await emitPolicyEvent({
+    stage: 'allowlist',
+    decision: 'allow',
+    method: request.method,
+    context,
+  })
+
+  if (options.authorizeMethod) {
+    const authorized = await options.authorizeMethod(request, context)
+    if (!authorized) {
+      await emitPolicyEvent({
+        stage: 'authorize',
+        decision: 'deny',
+        method: request.method,
+        context,
+        reason: 'not_authorized',
+      })
+      throw new Error(`JSON-RPC method '${request.method}' is not authorized`)
+    }
+    await emitPolicyEvent({
+      stage: 'authorize',
+      decision: 'allow',
+      method: request.method,
+      context,
+    })
+  }
+
+  if (options.rateLimiter) {
+    const key = options.rateLimitKey ? options.rateLimitKey(request, context) : request.method
+    const allowed = await options.rateLimiter.consume(key, request, context)
+    if (!allowed) {
+      await emitPolicyEvent({
+        stage: 'rateLimit',
+        decision: 'deny',
+        method: request.method,
+        context,
+        reason: 'rate_limited',
+      })
+      throw new Error(`JSON-RPC method '${request.method}' is rate-limited`)
+    }
+    await emitPolicyEvent({
+      stage: 'rateLimit',
+      decision: 'allow',
+      method: request.method,
+      context,
+    })
+  }
+
+  return adapter.createRawIntent({
+    recipient: options.recipient,
+    intent: 'TASK',
+    capability,
+    correlationId: String(request.id),
+    content: JSON.stringify({ method: request.method, params: request.params ?? null }),
+  })
+}
+
+export function toJsonRpcResponse(
+  envelope: ProtocolEnvelope,
+  id: string | number,
+  options: JsonRpcResponseOptions = {},
+): JsonRpcResponseLike {
+  if (envelope.body.intent === 'ERROR') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      error: {
+        code: options.defaultErrorCode ?? -32000,
+        message: envelope.body.content,
+        data: {
+          capability: envelope.body.capability,
+          correlationId: envelope.body.correlationId,
+        },
+      },
+    }
+  }
+
+  let result: unknown = envelope.body.content
+  try {
+    result = JSON.parse(envelope.body.content)
+  } catch {
+    result = envelope.body.content
+  }
+
+  return {
+    jsonrpc: '2.0',
+    id,
+    result,
+  }
+}

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)
+  })
+})