@7h3/protocol 0.1.2 → 0.5.0

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

package/src/mcpTransports.ts

@@ -0,0 +1,169 @@
+import readline from 'node:readline'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Readable, Writable } from 'node:stream'
+import type { WireEnvelope } from './protocolTransport'
+
+/**
+ * Transport adapters for the MCP hardening wrapper.
+ *
+ * The wrapper (`wrapMcpServer` / `wrapMcpClient`) is transport-agnostic: it
+ * operates on `WireEnvelope`s. These adapters connect it to real transports —
+ * newline-delimited stdio and HTTP — so a secured server is deployable as-is.
+ *
+ * Note: the stdio adapter frames one envelope per line and therefore supports
+ * the string wire formats (`json`, `compact`). For `binary`, use HTTP.
+ */
+
+type WireHandler = (raw: WireEnvelope) => Promise<WireEnvelope>
+
+function assertStringWire(raw: WireEnvelope): string {
+  if (typeof raw !== 'string') {
+    throw new Error('stdio adapter supports json/compact (string) wire formats; use the HTTP adapter for binary')
+  }
+  return raw
+}
+
+export interface StdioServerHandle {
+  close(): void
+}
+
+/**
+ * Serves a wrapped MCP handler over newline-delimited streams (default
+ * `process.stdin` / `process.stdout`). Lines are processed sequentially so
+ * responses are emitted in request order.
+ */
+export function serveMcpOverStdio(
+  handle: WireHandler,
+  options: { input?: Readable; output?: Writable; onError?: (error: unknown) => void } = {},
+): StdioServerHandle {
+  const input = options.input ?? process.stdin
+  const output = options.output ?? process.stdout
+  const rl = readline.createInterface({ input, crlfDelay: Number.POSITIVE_INFINITY })
+
+  let chain: Promise<void> = Promise.resolve()
+  const onLine = (line: string): void => {
+    const raw = line.trim()
+    if (!raw) return
+    chain = chain.then(async () => {
+      try {
+        const response = await handle(raw)
+        output.write(`${assertStringWire(response)}\n`)
+      } catch (error) {
+        options.onError?.(error)
+      }
+    })
+  }
+
+  rl.on('line', onLine)
+  return {
+    close(): void {
+      rl.off('line', onLine)
+      rl.close()
+    },
+  }
+}
+
+export interface StdioClientHandle {
+  send: WireHandler
+  close(): void
+}
+
+/**
+ * Creates a stdio client `send` function for `wrapMcpClient`. Requests and
+ * responses are correlated by order over the single pipe (one envelope per line).
+ */
+export function createStdioMcpClient(options: { input: Readable; output: Writable }): StdioClientHandle {
+  const rl = readline.createInterface({ input: options.input, crlfDelay: Number.POSITIVE_INFINITY })
+  const pending: Array<(line: string) => void> = []
+
+  const onLine = (line: string): void => {
+    const raw = line.trim()
+    if (!raw) return
+    const resolve = pending.shift()
+    if (resolve) resolve(raw)
+  }
+  rl.on('line', onLine)
+
+  return {
+    send(raw: WireEnvelope): Promise<WireEnvelope> {
+      const line = assertStringWire(raw)
+      return new Promise<WireEnvelope>((resolve) => {
+        pending.push(resolve)
+        options.output.write(`${line}\n`)
+      })
+    },
+    close(): void {
+      rl.off('line', onLine)
+      rl.close()
+    },
+  }
+}
+
+/**
+ * Creates a `node:http`-compatible request handler that runs the wrapped MCP
+ * handler. The request body is the wire envelope; the response body is the
+ * signed reply envelope.
+ */
+export function createHttpMcpHandler(
+  handle: WireHandler,
+  options: { binary?: boolean } = {},
+): (req: IncomingMessage, res: ServerResponse) => void {
+  return (req, res) => {
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => chunks.push(chunk))
+    req.on('error', () => {
+      res.writeHead(400)
+      res.end()
+    })
+    req.on('end', () => {
+      void (async () => {
+        try {
+          const buffer = Buffer.concat(chunks)
+          const raw: WireEnvelope = options.binary ? new Uint8Array(buffer) : buffer.toString('utf8')
+          const response = await handle(raw)
+          if (typeof response === 'string') {
+            res.writeHead(200, { 'content-type': 'application/json' })
+            res.end(response)
+          } else {
+            res.writeHead(200, { 'content-type': 'application/octet-stream' })
+            res.end(Buffer.from(response))
+          }
+        } catch (error) {
+          res.writeHead(500, { 'content-type': 'application/json' })
+          res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32603, message: error instanceof Error ? error.message : 'internal error' } }))
+        }
+      })()
+    })
+  }
+}
+
+export interface HttpClientHandle {
+  send: WireHandler
+}
+
+/**
+ * Creates an HTTP client `send` function for `wrapMcpClient`. POSTs the request
+ * envelope to `url` and returns the response envelope. Uses the global `fetch`
+ * by default; inject `fetchImpl` for tests or custom agents.
+ */
+export function createHttpMcpClient(options: {
+  url: string
+  fetchImpl?: typeof fetch
+  binary?: boolean
+  headers?: Record<string, string>
+}): HttpClientHandle {
+  const doFetch = options.fetchImpl ?? fetch
+  const contentType = options.binary ? 'application/octet-stream' : 'application/json'
+
+  return {
+    async send(raw: WireEnvelope): Promise<WireEnvelope> {
+      const response = await doFetch(options.url, {
+        method: 'POST',
+        headers: { 'content-type': contentType, ...options.headers },
+        body: typeof raw === 'string' ? raw : Buffer.from(raw),
+      })
+      if (options.binary) return new Uint8Array(await response.arrayBuffer())
+      return response.text()
+    },
+  }
+}

package/src/mcpWrapper.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createEnvelope, signEnvelopeHmac } from './protocol'
+import { InMemoryReplayCache } from './protocolReplay'
+import { encodeEnvelope, type WireEnvelope } from './protocolTransport'
+import {
+  createMcpClientCodec,
+  wrapMcpClient,
+  wrapMcpServer,
+  type JsonRpcRequest,
+  type McpSecurityOptions,
+} from './mcpWrapper'
+
+const SECRET = 'mcp-shared-secret'
+
+function serverOptions(extra: Partial<McpSecurityOptions> = {}): McpSecurityOptions {
+  return {
+    selfAgentId: 'agent.server',
+    sign: (envelope) => signEnvelopeHmac(envelope, SECRET, 'server-k1'),
+    receive: { secretResolver: async () => SECRET },
+    wireFormat: 'json',
+    ...extra,
+  }
+}
+
+function clientOptions(extra: Partial<McpSecurityOptions> = {}): McpSecurityOptions {
+  return {
+    selfAgentId: 'agent.client',
+    peerAgentId: 'agent.server',
+    sign: (envelope) => signEnvelopeHmac(envelope, SECRET, 'client-k1'),
+    receive: { secretResolver: async () => SECRET },
+    wireFormat: 'json',
+    ...extra,
+  }
+}
+
+const echo: (req: JsonRpcRequest) => Promise<{ jsonrpc: '2.0'; id: JsonRpcRequest['id']; result: unknown }> = async (req) => ({
+  jsonrpc: '2.0',
+  id: req.id,
+  result: { echo: req.params },
+})
+
+describe('wrapMcpServer + wrapMcpClient round-trip', () => {
+  it('delivers a signed request, runs the handler, and returns a verified result', async () => {
+    const server = wrapMcpServer(echo, serverOptions())
+    const call = wrapMcpClient((raw) => server(raw), clientOptions())
+
+    const response = await call({ jsonrpc: '2.0', id: 7, method: 'tools/call', params: { name: 'planner' } })
+
+    expect(response).toEqual({ jsonrpc: '2.0', id: 7, result: { echo: { name: 'planner' } } })
+  })
+
+  it('hands the underlying handler PLAIN json-rpc (no envelope, no signature)', async () => {
+    const handler = vi.fn(echo)
+    const server = wrapMcpServer(handler, serverOptions())
+    const call = wrapMcpClient((raw) => server(raw), clientOptions())
+
+    await call({ jsonrpc: '2.0', id: 1, method: 'resources/read', params: { uri: 'file://x' } })
+
+    expect(handler).toHaveBeenCalledOnce()
+    expect(handler).toHaveBeenCalledWith({ jsonrpc: '2.0', id: 1, method: 'resources/read', params: { uri: 'file://x' } })
+  })
+})
+
+describe('tamper detection', () => {
+  function tamperContent(raw: WireEnvelope): WireEnvelope {
+    const env = JSON.parse(raw as string)
+    env.body.content = `${env.body.content} TAMPERED`
+    return JSON.stringify(env)
+  }
+
+  it('a request tampered after signing is rejected by the server (handler never runs)', async () => {
+    const handler = vi.fn(echo)
+    const server = wrapMcpServer(handler, serverOptions())
+    const codec = createMcpClientCodec(clientOptions())
+
+    const { raw } = await codec.encodeRequest({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'x' } })
+    const response = await codec.decodeResponse(await server(tamperContent(raw)))
+
+    expect(handler).not.toHaveBeenCalled()
+    expect(response.error).toBeDefined()
+    expect(response.result).toBeUndefined()
+  })
+})
+
+describe('replay detection', () => {
+  it('rejects the second delivery of an identical signed request', async () => {
+    const replayCache = new InMemoryReplayCache()
+    const handler = vi.fn(echo)
+    const server = wrapMcpServer(handler, serverOptions({ receive: { secretResolver: async () => SECRET, replayCache } }))
+    const codec = createMcpClientCodec(clientOptions())
+
+    const { raw } = await codec.encodeRequest({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: {} })
+    const first = await codec.decodeResponse(await server(raw))
+    const second = await codec.decodeResponse(await server(raw))
+
+    expect(first.result).toBeDefined()
+    expect(second.error).toBeDefined()
+    expect(handler).toHaveBeenCalledOnce()
+  })
+
+  it('defaults to replay protection even when no cache is configured', async () => {
+    const handler = vi.fn(echo)
+    const server = wrapMcpServer(handler, serverOptions()) // no replayCache provided
+    const codec = createMcpClientCodec(clientOptions())
+
+    const { raw } = await codec.encodeRequest({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: {} })
+    await codec.decodeResponse(await server(raw))
+    const replayed = await codec.decodeResponse(await server(raw))
+
+    expect(replayed.error).toBeDefined()
+    expect(handler).toHaveBeenCalledOnce()
+  })
+})
+
+describe('response authenticity', () => {
+  it('client rejects a response whose signature does not verify', async () => {
+    const server = wrapMcpServer(echo, serverOptions())
+    const codec = createMcpClientCodec(clientOptions({ receive: { secretResolver: async () => 'WRONG-SECRET' } }))
+
+    const { raw } = await codec.encodeRequest({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: {} })
+    const responseRaw = await server(raw)
+
+    await expect(codec.decodeResponse(responseRaw)).rejects.toThrow(/verif/i)
+  })
+})
+
+describe('recipient binding (cross-server relay defense)', () => {
+  it('server rejects an envelope addressed to a different recipient', async () => {
+    const handler = vi.fn(echo)
+    const server = wrapMcpServer(handler, serverOptions({ selfAgentId: 'agent.server' }))
+    // a validly-signed request addressed to 'agent.other', relayed to this server
+    const misaddressed = await signEnvelopeHmac(
+      createEnvelope({
+        sender: 'agent.client',
+        recipient: 'agent.other',
+        intent: 'TASK',
+        content: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: {} }),
+      }),
+      SECRET,
+      'client-k1',
+    )
+    const responseRaw = await server(encodeEnvelope(misaddressed, 'json'))
+
+    // decode the error with a codec that matches the real server identity
+    const codec = createMcpClientCodec(clientOptions({ peerAgentId: 'agent.server' }))
+    const response = await codec.decodeResponse(responseRaw)
+
+    expect(handler).not.toHaveBeenCalled()
+    expect(response.error).toBeDefined()
+  })
+})
+
+describe('sender binding (response spoofing defense)', () => {
+  it('client rejects a validly-signed response whose sender is not the expected peer', async () => {
+    const codec = createMcpClientCodec(clientOptions({ peerAgentId: 'agent.server' }))
+    // a response signed with the shared secret but by a DIFFERENT agent id
+    const spoofed = await signEnvelopeHmac(
+      createEnvelope({ sender: 'agent.evil', recipient: 'agent.client', intent: 'RESULT', content: JSON.stringify({ jsonrpc: '2.0', id: 1, result: 'pwned' }) }),
+      SECRET,
+      'evil-k1',
+    )
+    const spoofedRaw = encodeEnvelope(spoofed, 'json')
+
+    await expect(codec.decodeResponse(spoofedRaw)).rejects.toThrow(/sender|peer/i)
+  })
+})
+
+describe('correlation binding (response substitution defense)', () => {
+  it('client rejects a response whose correlationId does not match the request', async () => {
+    const server = wrapMcpServer(echo, serverOptions())
+    const codec = createMcpClientCodec(clientOptions())
+
+    const { raw } = await codec.encodeRequest({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: {} })
+    const responseRaw = await server(raw)
+
+    // decode while asserting it answers a DIFFERENT request id
+    await expect(codec.decodeResponse(responseRaw, { expectCorrelationId: 'some-other-message-id' })).rejects.toThrow(/correlation/i)
+  })
+})