@7h3/protocol 0.4.0 → 0.5.1

package/src/keyRotation.ts

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

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

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

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