@7h3/protocol 0.1.2 → 0.4.0

package/src/keyRotation.ts

@@ -0,0 +1,72 @@
+import type { ProtocolEnvelope, SignatureVerificationMaterial } from './protocol'
+
+export type KeyStatus = 'active' | 'verify-only' | 'revoked'
+
+export interface KeyRecord {
+  sender: string
+  keyId: string
+  alg: SignatureVerificationMaterial['alg']
+  status: KeyStatus
+  notBeforeMs: number
+  notAfterMs: number
+  material: SignatureVerificationMaterial
+}
+
+export class RollingKeyring {
+  private readonly records: KeyRecord[]
+
+  constructor(records: KeyRecord[] = []) {
+    this.records = [...records]
+  }
+
+  add(record: KeyRecord): void {
+    this.records.push(record)
+  }
+
+  revoke(sender: string, keyId: string, revokedAtMs = Date.now()): boolean {
+    const record = this.records.find((entry) => entry.sender === sender && entry.keyId === keyId)
+    if (!record) return false
+    record.status = 'revoked'
+    record.notAfterMs = Math.min(record.notAfterMs, revokedAtMs)
+    return true
+  }
+
+  selectSigningKey(sender: string, alg: SignatureVerificationMaterial['alg'], nowMs = Date.now()): KeyRecord | null {
+    const candidates = this.records
+      .filter(
+        (entry) =>
+          entry.sender === sender &&
+          entry.alg === alg &&
+          entry.status === 'active' &&
+          entry.notBeforeMs <= nowMs &&
+          nowMs < entry.notAfterMs,
+      )
+      .sort((a, b) => b.notBeforeMs - a.notBeforeMs)
+    return candidates[0] ?? null
+  }
+
+  resolveVerificationMaterial(
+    signature: NonNullable<ProtocolEnvelope['signature']>,
+    sender: string,
+    nowMs = Date.now(),
+  ): SignatureVerificationMaterial | undefined {
+    const candidates = this.records
+      .filter(
+        (entry) =>
+          entry.sender === sender &&
+          entry.keyId === signature.keyId &&
+          entry.alg === signature.alg &&
+          entry.status !== 'revoked' &&
+          entry.notBeforeMs <= nowMs &&
+          nowMs < entry.notAfterMs,
+      )
+      .sort((a, b) => b.notBeforeMs - a.notBeforeMs)
+
+    return candidates[0]?.material
+  }
+}
+
+export function createKeyringSignatureResolver(keyring: RollingKeyring, nowMsProvider: () => number = () => Date.now()) {
+  return async (signature: NonNullable<ProtocolEnvelope['signature']>, sender: string): Promise<SignatureVerificationMaterial | undefined> =>
+    keyring.resolveVerificationMaterial(signature, sender, nowMsProvider())
+}

package/src/mcpGateway.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'vitest'
+import { createAipMcpGatewayRuntime } from './mcpGateway'
+
+describe('AIP MCP gateway runtime', () => {
+  it('returns JSON-RPC result for allowed method', async () => {
+    const runtime = createAipMcpGatewayRuntime({ sharedSecret: 'gateway-test-secret' })
+
+    const line = JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'tools/call',
+      params: { name: 'planner' },
+    })
+
+    const responseLine = await runtime.handleLine(line)
+    expect(responseLine).not.toBeNull()
+    const response = JSON.parse(responseLine ?? '{}') as {
+      jsonrpc: string
+      id: number
+      result?: { ok: boolean; capability: string }
+      error?: { code: number; message: string }
+    }
+
+    expect(response.jsonrpc).toBe('2.0')
+    expect(response.id).toBe(1)
+    expect(response.error).toBeUndefined()
+    expect(response.result?.ok).toBe(true)
+    expect(response.result?.capability).toBe('mcp.tools/call')
+  })
+
+  it('returns invalid request for malformed JSON-RPC line', async () => {
+    const runtime = createAipMcpGatewayRuntime({ sharedSecret: 'gateway-test-secret' })
+    const responseLine = await runtime.handleLine('{"bad": true}')
+    const response = JSON.parse(responseLine ?? '{}') as { error?: { code: number; message: string } }
+
+    expect(response.error?.code).toBe(-32600)
+    expect(response.error?.message).toBe('Invalid Request')
+  })
+
+  it('returns method not found for disallowed method', async () => {
+    const runtime = createAipMcpGatewayRuntime({
+      sharedSecret: 'gateway-test-secret',
+      allowedMethods: ['tools/call'],
+    })
+
+    const line = JSON.stringify({
+      jsonrpc: '2.0',
+      id: 'x',
+      method: 'resources/read',
+      params: {},
+    })
+
+    const responseLine = await runtime.handleLine(line)
+    const response = JSON.parse(responseLine ?? '{}') as { error?: { code: number; message: string } }
+
+    expect(response.error?.code).toBe(-32601)
+    expect(response.error?.message).toContain("is not allowed")
+  })
+
+  it('returns authorization error when policy hook blocks request', async () => {
+    const runtime = createAipMcpGatewayRuntime({
+      sharedSecret: 'gateway-test-secret',
+      authorizeMethod: async () => false,
+    })
+
+    const line = JSON.stringify({
+      jsonrpc: '2.0',
+      id: 'auth-2',
+      method: 'tools/call',
+      params: {},
+    })
+
+    const responseLine = await runtime.handleLine(line)
+    const response = JSON.parse(responseLine ?? '{}') as { error?: { code: number; message: string } }
+
+    expect(response.error?.code).toBe(-32001)
+    expect(response.error?.message).toContain('not authorized')
+  })
+
+  it('returns rate-limit error when limiter blocks request', async () => {
+    const runtime = createAipMcpGatewayRuntime({
+      sharedSecret: 'gateway-test-secret',
+      rateLimiter: {
+        consume: async () => false,
+      },
+    })
+
+    const line = JSON.stringify({
+      jsonrpc: '2.0',
+      id: 'rl-3',
+      method: 'tools/call',
+      params: {},
+    })
+
+    const responseLine = await runtime.handleLine(line)
+    const response = JSON.parse(responseLine ?? '{}') as { error?: { code: number; message: string } }
+
+    expect(response.error?.code).toBe(-32002)
+    expect(response.error?.message).toContain('rate-limited')
+  })
+
+  it('ignores empty lines', async () => {
+    const runtime = createAipMcpGatewayRuntime({ sharedSecret: 'gateway-test-secret' })
+    await expect(runtime.handleLine('   ')).resolves.toBeNull()
+  })
+
+  it('emits audit events for policy and request phases', async () => {
+    const phases: string[] = []
+    const runtime = createAipMcpGatewayRuntime({
+      sharedSecret: 'gateway-test-secret',
+      onAuditEvent: async (event) => {
+        phases.push(event.phase)
+      },
+    })
+
+    const line = JSON.stringify({
+      jsonrpc: '2.0',
+      id: 'audit-1',
+      method: 'tools/call',
+      params: { name: 'planner' },
+    })
+
+    const responseLine = await runtime.handleLine(line)
+    expect(responseLine).not.toBeNull()
+    expect(phases).toContain('request_received')
+    expect(phases).toContain('policy')
+    expect(phases).toContain('request_success')
+  })
+})

package/src/mcpGateway.ts

@@ -0,0 +1,250 @@
+import { createAipAgentAdapter } from './agentAdapter'
+import { bootstrapRuntimePolicyEnforcer, type BootstrapRuntimePolicyEnforcerOptions } from './policyEnforcer'
+import {
+  createRawTaskFromJsonRpc,
+  type JsonRpcPolicyEvent,
+  toJsonRpcResponse,
+  type JsonRpcBridgeOptions,
+  type JsonRpcRequestLike,
+} from './frameworkAdapters'
+import { type WireEnvelope } from './protocolTransport'
+
+export interface AipMcpGatewayOptions {
+  sharedSecret: string
+  gatewayAgentId?: string
+  workerAgentId?: string
+  allowedMethods?: readonly string[]
+  workerCapabilityPrefix?: string
+  methodToCapability?: JsonRpcBridgeOptions['methodToCapability']
+  authorizeMethod?: JsonRpcBridgeOptions['authorizeMethod']
+  rateLimitKey?: JsonRpcBridgeOptions['rateLimitKey']
+  rateLimiter?: JsonRpcBridgeOptions['rateLimiter']
+  onAuditEvent?: (event: AipMcpGatewayAuditEvent) => void | Promise<void>
+  gatewayWireFormat?: 'json' | 'compact' | 'binary'
+  workerWireFormat?: 'json' | 'compact' | 'binary'
+  runtimePolicy?: {
+    enabled?: boolean
+    options?: BootstrapRuntimePolicyEnforcerOptions
+    concurrencyHint?: number
+    latencySensitive?: boolean
+    compatibilityFirst?: boolean
+  }
+}
+
+export interface AipMcpGatewayRuntime {
+  handleLine: (line: string) => Promise<string | null>
+}
+
+export interface AipMcpGatewayAuditEvent {
+  phase: 'request_received' | 'policy' | 'verification_failed' | 'request_success' | 'request_error'
+  id?: string | number | null
+  method?: string
+  code?: number
+  message?: string
+  policy?: JsonRpcPolicyEvent
+  timestampMs: number
+}
+
+const DEFAULT_ALLOWED_METHODS = ['tools/call', 'resources/read', 'prompts/get']
+
+function jsonString(value: unknown): string {
+  return JSON.stringify(value)
+}
+
+function createErrorResponse(id: string | number | null, code: number, message: string): string {
+  return jsonString({
+    jsonrpc: '2.0',
+    id,
+    error: { code, message },
+  })
+}
+
+function parseRequest(raw: string): JsonRpcRequestLike | null {
+  const parsed = JSON.parse(raw) as Partial<JsonRpcRequestLike>
+  if (parsed.jsonrpc !== '2.0') return null
+  if (typeof parsed.method !== 'string' || parsed.method.length === 0) return null
+  if (typeof parsed.id !== 'string' && typeof parsed.id !== 'number') return null
+
+  return {
+    jsonrpc: '2.0',
+    id: parsed.id,
+    method: parsed.method,
+    params: parsed.params,
+  }
+}
+
+function mapBridgeErrorCode(message: string): number {
+  if (message.includes('not allowed')) return -32601
+  if (message.includes('not authorized')) return -32001
+  if (message.includes('rate-limited')) return -32002
+  return -32603
+}
+
+export function createAipMcpGatewayRuntime(options: AipMcpGatewayOptions): AipMcpGatewayRuntime {
+  const gatewayAgentId = options.gatewayAgentId ?? 'agent.gateway'
+  const workerAgentId = options.workerAgentId ?? 'agent.worker'
+  const allowedMethods = options.allowedMethods ?? DEFAULT_ALLOWED_METHODS
+  const workerCapabilityPrefix = options.workerCapabilityPrefix ?? 'mcp.'
+  const gatewayWireFormat = options.gatewayWireFormat ?? 'compact'
+  const workerWireFormat = options.workerWireFormat ?? 'compact'
+
+  async function emitAuditEvent(event: Omit<AipMcpGatewayAuditEvent, 'timestampMs'>): Promise<void> {
+    if (options.onAuditEvent) {
+      await options.onAuditEvent({
+        ...event,
+        timestampMs: Date.now(),
+      })
+    }
+  }
+
+  const gateway = createAipAgentAdapter({
+    agentId: gatewayAgentId,
+    outboundSecret: options.sharedSecret,
+    sharedSecrets: { [workerAgentId]: options.sharedSecret },
+    wireFormat: gatewayWireFormat,
+  })
+
+  const worker = createAipAgentAdapter({
+    agentId: workerAgentId,
+    outboundSecret: options.sharedSecret,
+    sharedSecrets: { [gatewayAgentId]: options.sharedSecret },
+    wireFormat: workerWireFormat,
+    onTask: async (envelope) => ({
+      intent: 'RESULT',
+      content: jsonString({
+        ok: true,
+        capability: envelope.body.capability,
+        content: envelope.body.content,
+      }),
+      capability: envelope.body.capability?.startsWith(workerCapabilityPrefix)
+        ? envelope.body.capability
+        : `${workerCapabilityPrefix}${envelope.body.capability ?? 'unknown'}`,
+    }),
+  })
+
+  return {
+    async handleLine(line: string): Promise<string | null> {
+      const raw = line.trim()
+      if (!raw) return null
+
+      let id: string | number | null = null
+      try {
+        const request = parseRequest(raw)
+        if (!request) {
+          await emitAuditEvent({
+            phase: 'request_error',
+            code: -32600,
+            message: 'Invalid Request',
+          })
+          return createErrorResponse(null, -32600, 'Invalid Request')
+        }
+        id = request.id
+        await emitAuditEvent({
+          phase: 'request_received',
+          id: request.id,
+          method: request.method,
+        })
+
+        const bridgeOptions: JsonRpcBridgeOptions = {
+          recipient: workerAgentId,
+          allowedMethods,
+          methodToCapability: options.methodToCapability,
+          authorizeMethod: options.authorizeMethod,
+          rateLimitKey: options.rateLimitKey,
+          rateLimiter: options.rateLimiter,
+          onPolicyEvent: async (event) => {
+            await emitAuditEvent({
+              phase: 'policy',
+              id: request.id,
+              method: request.method,
+              policy: event,
+            })
+          },
+        }
+
+        const outbound = await createRawTaskFromJsonRpc(gateway, request, bridgeOptions)
+        let rawResponse: WireEnvelope | null = null
+        await worker.handleRaw(outbound, async (responseRaw) => {
+          rawResponse = responseRaw
+        })
+        if (!rawResponse) {
+          await emitAuditEvent({
+            phase: 'verification_failed',
+            id: request.id,
+            method: request.method,
+            code: -32603,
+            message: 'AIP worker did not produce a response',
+          })
+          return createErrorResponse(id, -32603, 'AIP worker did not produce a response')
+        }
+
+        const verified = await gateway.receiveRaw(rawResponse)
+        if (!verified.ok || !verified.received) {
+          await emitAuditEvent({
+            phase: 'verification_failed',
+            id: request.id,
+            method: request.method,
+            code: -32603,
+            message: 'AIP verification failed',
+          })
+          return createErrorResponse(id, -32603, 'AIP verification failed')
+        }
+
+        await emitAuditEvent({
+          phase: 'request_success',
+          id: request.id,
+          method: request.method,
+        })
+
+        return jsonString(toJsonRpcResponse(verified.received, request.id))
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : 'Internal error'
+        const code = mapBridgeErrorCode(message)
+        await emitAuditEvent({
+          phase: 'request_error',
+          id,
+          code,
+          message,
+        })
+        return createErrorResponse(id, code, message)
+      }
+    },
+  }
+}
+
+export async function createAipMcpGatewayRuntimeWithPolicy(options: AipMcpGatewayOptions): Promise<AipMcpGatewayRuntime> {
+  if (!options.runtimePolicy?.enabled) {
+    return createAipMcpGatewayRuntime(options)
+  }
+
+  const { enforcer } = await bootstrapRuntimePolicyEnforcer(options.runtimePolicy.options)
+  enforcer.assertInvariant({
+    signatureVerification: true,
+    canonicalization: true,
+    replayDefense: true,
+    ttlClockSkewEnforcement: true,
+  })
+
+  const mode = enforcer.selectMode({
+    concurrency: options.runtimePolicy.concurrencyHint ?? 1,
+    latencySensitive: options.runtimePolicy.latencySensitive,
+    compatibilityFirst: options.runtimePolicy.compatibilityFirst,
+  })
+
+  const wireFormat = mode.includes('binary') ? 'binary' : 'compact'
+  return createAipMcpGatewayRuntime({
+    ...options,
+    gatewayWireFormat: wireFormat,
+    workerWireFormat: wireFormat,
+    gatewayAgentId: options.gatewayAgentId,
+    workerAgentId: options.workerAgentId,
+    onAuditEvent: async (event) => {
+      if (options.onAuditEvent) {
+        await options.onAuditEvent({
+          ...event,
+          message: event.message ?? `policy-mode=${mode};wire-format=${wireFormat}`,
+        })
+      }
+    },
+  })
+}

package/src/mcpTransports.test.ts

@@ -0,0 +1,92 @@
+import http from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { PassThrough } from 'node:stream'
+import { afterEach, describe, expect, it } from 'vitest'
+import { signEnvelopeHmac } from './protocol'
+import {
+  createMcpClientCodec,
+  wrapMcpClient,
+  wrapMcpServer,
+  type JsonRpcRequest,
+  type McpSecurityOptions,
+} from './mcpWrapper'
+import { createHttpMcpClient, createHttpMcpHandler, createStdioMcpClient, serveMcpOverStdio } from './mcpTransports'
+
+const SECRET = 'mcp-shared-secret'
+
+const serverOptions: McpSecurityOptions = {
+  selfAgentId: 'agent.server',
+  sign: (envelope) => signEnvelopeHmac(envelope, SECRET, 'server-k1'),
+  receive: { secretResolver: async () => SECRET },
+  wireFormat: 'json',
+}
+
+const clientOptions: McpSecurityOptions = {
+  selfAgentId: 'agent.client',
+  peerAgentId: 'agent.server',
+  sign: (envelope) => signEnvelopeHmac(envelope, SECRET, 'client-k1'),
+  receive: { secretResolver: async () => SECRET },
+  wireFormat: 'json',
+}
+
+const echo = async (req: JsonRpcRequest) => ({ jsonrpc: '2.0' as const, id: req.id, result: { echo: req.params } })
+
+describe('stdio transport adapter', () => {
+  const cleanups: Array<() => void> = []
+  afterEach(() => {
+    for (const c of cleanups.splice(0)) c()
+  })
+
+  it('round-trips signed MCP messages over newline-delimited streams', async () => {
+    const clientToServer = new PassThrough()
+    const serverToClient = new PassThrough()
+
+    const server = serveMcpOverStdio(wrapMcpServer(echo, serverOptions), { input: clientToServer, output: serverToClient })
+    const client = createStdioMcpClient({ input: serverToClient, output: clientToServer })
+    cleanups.push(() => server.close(), () => client.close())
+
+    const call = wrapMcpClient(client.send, clientOptions)
+
+    const first = await call({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'planner' } })
+    const second = await call({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'deploy' } })
+
+    expect(first).toEqual({ jsonrpc: '2.0', id: 1, result: { echo: { name: 'planner' } } })
+    expect(second).toEqual({ jsonrpc: '2.0', id: 2, result: { echo: { name: 'deploy' } } })
+  })
+})
+
+describe('http transport adapter', () => {
+  let server: http.Server | undefined
+  afterEach(async () => {
+    if (server) await new Promise<void>((resolve) => server!.close(() => resolve()))
+    server = undefined
+  })
+
+  it('round-trips signed MCP messages over a real HTTP server', async () => {
+    server = http.createServer(createHttpMcpHandler(wrapMcpServer(echo, serverOptions)))
+    await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
+    const { port } = server.address() as AddressInfo
+
+    const client = createHttpMcpClient({ url: `http://127.0.0.1:${port}` })
+    const call = wrapMcpClient(client.send, clientOptions)
+
+    const response = await call({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'planner' } })
+
+    expect(response).toEqual({ jsonrpc: '2.0', id: 1, result: { echo: { name: 'planner' } } })
+  })
+
+  it('rejects an unsigned/invalid request over HTTP and returns a signed JSON-RPC error', async () => {
+    server = http.createServer(createHttpMcpHandler(wrapMcpServer(echo, serverOptions)))
+    await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
+    const { port } = server.address() as AddressInfo
+
+    const client = createHttpMcpClient({ url: `http://127.0.0.1:${port}` })
+    const codec = createMcpClientCodec(clientOptions)
+
+    // a body that is not a valid signed envelope
+    const responseRaw = await client.send('{"not":"an envelope"}')
+    const response = await codec.decodeResponse(responseRaw)
+
+    expect(response.error).toBeDefined()
+  })
+})