@7h3/protocol 0.4.0 → 0.5.1

package/src/frameworkAdapters.ts

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

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