@7h3/protocol 0.1.2 → 0.4.0

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

package/src/mcpWrapper.ts

@@ -0,0 +1,206 @@
+import { createEnvelope, type ProtocolEnvelope } from './protocol'
+import { InMemoryReplayCache } from './protocolReplay'
+import {
+  encodeEnvelope,
+  receiveEnvelope,
+  type ReceiveEnvelopeOptions,
+  type WireEnvelope,
+  type WireFormat,
+} from './protocolTransport'
+
+/**
+ * MCP hardening middleware.
+ *
+ * MCP messages are plain JSON-RPC 2.0 and, as shipped, carry no signature or
+ * replay protection. These wrappers put an AIP envelope around each message on
+ * the wire — signing, TTL-bounding, and replay-checking every request and
+ * response — while the underlying MCP handler still receives plain JSON-RPC.
+ * "Zero app changes": your handler signature does not change.
+ *
+ * The wrappers enforce four bindings beyond signature verification:
+ *   - recipient binding: the server only runs the handler when the envelope is
+ *     addressed to it (`recipient === selfAgentId`) — defeats cross-server relay.
+ *   - sender binding: the client only accepts responses from its expected peer
+ *     (`sender === peerAgentId`) — defeats response spoofing.
+ *   - correlation binding: the client only accepts a response whose
+ *     `correlationId` matches the request it sent — defeats response substitution.
+ *   - replay protection on by default (an `InMemoryReplayCache` if none supplied).
+ *
+ * Verification reuses the transport pipeline (`receiveEnvelope`), so it composes
+ * directly with a Redis-backed replay cache (`createRedisReplayStore`) and
+ * fleet-wide revocation (`withRevocationCheck`) via the `receive` options.
+ */
+
+export type JsonRpcId = string | number | null
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0'
+  id: JsonRpcId
+  method: string
+  params?: unknown
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0'
+  id: JsonRpcId
+  result?: unknown
+  error?: { code: number; message: string; data?: unknown }
+}
+
+export type McpJsonRpcHandler = (request: JsonRpcRequest) => JsonRpcResponse | Promise<JsonRpcResponse>
+
+export interface McpSecurityOptions {
+  /** This peer's agent id, used as the envelope `sender` and enforced as the inbound `recipient`. */
+  selfAgentId: string
+  /** The peer's agent id: set as the envelope `recipient` (client) and enforced as the response `sender`. */
+  peerAgentId?: string
+  /** Signs an unsigned envelope, e.g. `(e) => signEnvelopeHmac(e, secret, keyId)`. */
+  sign: (envelope: Omit<ProtocolEnvelope, 'signature'>) => Promise<ProtocolEnvelope>
+  /** Inbound verification options: signature material resolver, replay cache, clock skew, etc. */
+  receive?: ReceiveEnvelopeOptions
+  /** Wire format for the envelope on the wire. Default `compact`. */
+  wireFormat?: WireFormat
+  /** Envelope TTL in ms. Default 60_000. */
+  ttlMs?: number
+}
+
+export interface EncodedRequest {
+  raw: WireEnvelope
+  /** The envelope `messageId` generated for this request; bind the response's `correlationId` to it. */
+  messageId: string
+}
+
+export interface DecodeResponseOptions {
+  /** When set, require the response `correlationId` to equal this value (the request's messageId). */
+  expectCorrelationId?: string
+}
+
+function jsonRpcError(id: JsonRpcId, code: number, message: string): JsonRpcResponse {
+  return { jsonrpc: '2.0', id, error: { code, message } }
+}
+
+/** Verification options with signature required and a replay cache guaranteed (secure defaults). */
+function hardenedReceive(options: McpSecurityOptions, replayCache: ReceiveEnvelopeOptions['replayCache']): ReceiveEnvelopeOptions {
+  return { requireSignature: true, ...options.receive, replayCache }
+}
+
+/**
+ * Wraps an existing MCP JSON-RPC handler so every inbound message is verified
+ * (signature + replay + TTL + recipient binding) before the handler runs, and
+ * every response is signed. Returns a function over the AIP wire envelope.
+ */
+export function wrapMcpServer(handler: McpJsonRpcHandler, options: McpSecurityOptions): (raw: WireEnvelope) => Promise<WireEnvelope> {
+  const wireFormat = options.wireFormat ?? 'compact'
+  const ttlMs = options.ttlMs ?? 60_000
+  // Replay protection is on by default; supply a Redis-backed cache via options.receive for scale.
+  const replayCache = options.receive?.replayCache ?? new InMemoryReplayCache()
+  const receiveOptions = hardenedReceive(options, replayCache)
+
+  async function signAndEncode(envelope: Omit<ProtocolEnvelope, 'signature'>): Promise<WireEnvelope> {
+    return encodeEnvelope(await options.sign(envelope), wireFormat)
+  }
+
+  function reply(recipient: string | undefined, intent: 'RESULT' | 'ERROR', response: JsonRpcResponse, correlationId?: string) {
+    return signAndEncode(
+      createEnvelope({ sender: options.selfAgentId, recipient, intent, content: JSON.stringify(response), correlationId, ttlMs }),
+    )
+  }
+
+  return async (raw: WireEnvelope): Promise<WireEnvelope> => {
+    const received = await receiveEnvelope(raw, receiveOptions)
+    const senderHint = received.envelope?.header.sender
+    const correlationId = received.envelope?.header.messageId
+
+    if (!received.ok || !received.envelope) {
+      const reason = received.diagnostics.find((d) => d.level === 'error')?.message ?? 'AIP verification failed'
+      return reply(senderHint, 'ERROR', jsonRpcError(null, -32600, reason), correlationId)
+    }
+
+    // Recipient binding: refuse to act on an envelope not addressed to this agent.
+    if (received.envelope.header.recipient !== options.selfAgentId) {
+      return reply(senderHint, 'ERROR', jsonRpcError(null, -32600, 'Recipient mismatch: envelope not addressed to this agent'), correlationId)
+    }
+
+    let request: JsonRpcRequest
+    try {
+      request = JSON.parse(received.envelope.body.content) as JsonRpcRequest
+    } catch {
+      return reply(senderHint, 'ERROR', jsonRpcError(null, -32700, 'Parse error: envelope body is not JSON-RPC'), correlationId)
+    }
+
+    let response: JsonRpcResponse
+    try {
+      response = await handler(request)
+    } catch (error) {
+      response = jsonRpcError(request.id ?? null, -32603, error instanceof Error ? error.message : 'Internal error')
+    }
+    return reply(received.envelope.header.sender, 'RESULT', response, correlationId)
+  }
+}
+
+export interface McpClientCodec {
+  encodeRequest(request: JsonRpcRequest): Promise<EncodedRequest>
+  decodeResponse(raw: WireEnvelope, options?: DecodeResponseOptions): Promise<JsonRpcResponse>
+}
+
+/** Signs outbound requests and verifies inbound responses (with sender + correlation binding). */
+export function createMcpClientCodec(options: McpSecurityOptions): McpClientCodec {
+  const wireFormat = options.wireFormat ?? 'compact'
+  const ttlMs = options.ttlMs ?? 60_000
+  const replayCache = options.receive?.replayCache ?? new InMemoryReplayCache()
+  const receiveOptions = hardenedReceive(options, replayCache)
+
+  return {
+    async encodeRequest(request: JsonRpcRequest): Promise<EncodedRequest> {
+      const envelope = createEnvelope({
+        sender: options.selfAgentId,
+        recipient: options.peerAgentId,
+        intent: 'TASK',
+        content: JSON.stringify(request),
+        ttlMs,
+      })
+      return { raw: encodeEnvelope(await options.sign(envelope), wireFormat), messageId: envelope.header.messageId }
+    },
+
+    async decodeResponse(raw: WireEnvelope, decodeOptions: DecodeResponseOptions = {}): Promise<JsonRpcResponse> {
+      const received = await receiveEnvelope(raw, receiveOptions)
+      if (!received.ok || !received.envelope) {
+        const reason = received.diagnostics.find((d) => d.level === 'error')?.message ?? 'unknown'
+        throw new Error(`AIP response verification failed: ${reason}`)
+      }
+
+      // Sender binding: the response must come from the expected peer.
+      if (!options.peerAgentId) {
+        throw new Error('createMcpClientCodec requires peerAgentId to bind the response sender')
+      }
+      if (received.envelope.header.sender !== options.peerAgentId) {
+        throw new Error(`AIP response sender '${received.envelope.header.sender}' is not the expected peer '${options.peerAgentId}'`)
+      }
+
+      // Correlation binding: the response must answer the request we sent.
+      if (decodeOptions.expectCorrelationId !== undefined && received.envelope.body.correlationId !== decodeOptions.expectCorrelationId) {
+        throw new Error(
+          `AIP response correlationId '${received.envelope.body.correlationId ?? ''}' does not match request '${decodeOptions.expectCorrelationId}'`,
+        )
+      }
+
+      return JSON.parse(received.envelope.body.content) as JsonRpcResponse
+    },
+  }
+}
+
+/**
+ * Wraps a transport send function (`stdio`, HTTP, ...) so callers issue and
+ * receive plain JSON-RPC while AIP signing, verification, and request/response
+ * correlation happen on the wire.
+ */
+export function wrapMcpClient(
+  send: (raw: WireEnvelope) => Promise<WireEnvelope>,
+  options: McpSecurityOptions,
+): (request: JsonRpcRequest) => Promise<JsonRpcResponse> {
+  const codec = createMcpClientCodec(options)
+  return async (request: JsonRpcRequest): Promise<JsonRpcResponse> => {
+    const { raw, messageId } = await codec.encodeRequest(request)
+    return codec.decodeResponse(await send(raw), { expectCorrelationId: messageId })
+  }
+}

package/src/policyEnforcer.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest'
+import { bootstrapRuntimePolicyEnforcer, createPolicyEnforcer, isRuntimeMode } from './policyEnforcer'
+import type { RuntimePolicy } from './runtimePolicy'
+
+const policy: RuntimePolicy = {
+  version: '1.0',
+  name: 'gluv-runtime-policy',
+  status: 'active',
+  slo_defaults: {
+    drop_pct_max: 0.1,
+    p99_ms_max: 20,
+  },
+  tuning: {
+    batch_size: {
+      low_traffic: [4, 8],
+      medium_traffic: [8, 32],
+      high_traffic: [32, 64],
+    },
+    inflight_cap: {
+      low_traffic: [16, 64],
+      medium_traffic: [64, 256],
+      high_traffic: [256, 1024],
+    },
+    retry_backoff_ms: {
+      low_traffic: [1, 2],
+      medium_traffic: [2, 8],
+      high_traffic: [4, 16],
+    },
+    max_retry_attempts: 3,
+    retriable_status_codes: [503],
+  },
+}
+
+describe('policy enforcer', () => {
+  it('selects binary batch for high concurrency', () => {
+    const enforcer = createPolicyEnforcer(policy)
+    expect(enforcer.selectMode({ concurrency: 100 })).toBe('http-binary-batch')
+  })
+
+  it('selects ws-batch for latency-sensitive low concurrency', () => {
+    const enforcer = createPolicyEnforcer(policy)
+    expect(enforcer.selectMode({ concurrency: 10, latencySensitive: true })).toBe('ws-batch')
+  })
+
+  it('returns tuning ranges and remediation actions', () => {
+    const enforcer = createPolicyEnforcer(policy)
+    const decision = enforcer.tune({
+      trafficClass: 'high',
+      dropPct: 1,
+      p99Ms: 30,
+    })
+    expect(decision.batchSizeRange).toEqual([32, 64])
+    expect(decision.inflightCapRange).toEqual([256, 1024])
+    expect(decision.retryBackoffMsRange).toEqual([4, 16])
+    expect(decision.actions.length).toBeGreaterThan(0)
+  })
+
+  it('retries only retriable status and under attempt cap', () => {
+    const enforcer = createPolicyEnforcer(policy)
+    expect(enforcer.shouldRetry({ error: new Error('http status 503: overloaded'), attempt: 1 })).toBe(true)
+    expect(enforcer.shouldRetry({ error: new Error('http status 400: bad request'), attempt: 1 })).toBe(false)
+    expect(enforcer.shouldRetry({ error: new Error('http status 503: overloaded'), attempt: 3 })).toBe(false)
+  })
+
+  it('asserts invariants', () => {
+    const enforcer = createPolicyEnforcer(policy)
+    expect(() =>
+      enforcer.assertInvariant({
+        signatureVerification: true,
+        canonicalization: true,
+        replayDefense: true,
+        ttlClockSkewEnforcement: true,
+      }),
+    ).not.toThrow()
+    expect(() =>
+      enforcer.assertInvariant({
+        signatureVerification: false,
+        canonicalization: true,
+        replayDefense: true,
+        ttlClockSkewEnforcement: true,
+      }),
+    ).toThrow(/Invariant violation/i)
+  })
+
+  it('checks runtime mode literals', () => {
+    expect(isRuntimeMode('http-binary-batch')).toBe(true)
+    expect(isRuntimeMode('invalid-mode')).toBe(false)
+  })
+
+  it('bootstraps policy + enforcer in one call', async () => {
+    const bootstrapped = await bootstrapRuntimePolicyEnforcer({
+      path: '/virtual/AI_RUNTIME_POLICY.json',
+      readTextFile: async () => JSON.stringify(policy),
+    })
+
+    expect(bootstrapped.policy.name).toBe('gluv-runtime-policy')
+    expect(bootstrapped.enforcer.selectMode({ concurrency: 100 })).toBe('http-binary-batch')
+  })
+})