@intutic/mcp-governance-proxy 1.0.3

package/src/interceptor.ts

@@ -0,0 +1,103 @@
+/**
+ * interceptor.ts — tools/call decision engine.
+ *
+ * Given a tool name and arguments, evaluates:
+ * 1. DLP scan (credential / destructive pattern detection)
+ * 2. SOP policy rules (fetched from control plane via PolicyClient)
+ *
+ * Returns an allow / block / redact decision.
+ *
+ * @module
+ */
+
+import { createStderrLogger as createLogger } from './stderrLog.js'
+import { scanToolInput, formatDlpBlockReason } from './dlp.js'
+import type { PolicyClient } from './policy.js'
+import type { GovernanceEmitter } from './emitter.js'
+
+const log = createLogger('mcp-proxy-interceptor')
+
+export type Decision =
+  | { action: 'allow' }
+  | { action: 'block'; reason: string }
+  | { action: 'redact'; reason: string; redactedInput: unknown }
+
+export class ToolCallInterceptor {
+  constructor(
+    private readonly policy: PolicyClient,
+    private readonly emitter: GovernanceEmitter,
+    private readonly failOpen: boolean = true
+  ) {}
+
+  /**
+   * Evaluate a tools/call request and return a governance decision.
+   *
+   * @param toolName - The MCP tool name (e.g. "mcp__filesystem__read_file" or "Bash")
+   * @param toolInput - The tool_input / arguments object
+   * @returns Decision: allow, block, or redact
+   */
+  async decide(toolName: string, toolInput: unknown): Promise<Decision> {
+    log.debug({ action: 'interceptor_decide', toolName }, 'Evaluating tool call')
+
+    // 1. DLP scan
+    try {
+      const dlp = scanToolInput(toolInput)
+      if (dlp.hasFinding) {
+        const reason = formatDlpBlockReason(dlp.findings)
+        log.warn({ action: 'dlp_block', toolName, findings: dlp.findings }, 'DLP block')
+        this.emitter.emit('tool_blocked', toolName, toolInput, reason)
+        return { action: 'block', reason }
+      }
+    } catch (err) {
+      log.error({ action: 'dlp_error', err: (err as Error).message }, 'DLP scan error — skipping')
+      if (!this.failOpen) {
+        return {
+          action: 'block',
+          reason:
+            'Governance check failed — Intutic control plane unreachable. ' +
+            'Tool call blocked by workspace policy (fail-closed mode). ' +
+            'Contact your administrator or update mcpProxyFailBehavior to open.',
+        }
+      }
+    }
+
+    // 2. SOP policy rule match
+    try {
+      const toolInputJson = JSON.stringify(toolInput ?? {})
+      const rule = this.policy.matchRule(toolName, toolInputJson)
+      if (rule) {
+        if (rule.action === 'block') {
+          log.warn({ action: 'policy_block', toolName, ruleId: rule.id, reason: rule.reason }, 'Policy block')
+          this.emitter.emit('tool_blocked', toolName, toolInput, rule.reason)
+          return { action: 'block', reason: rule.reason }
+        }
+        if (rule.action === 'warn') {
+          log.warn({ action: 'policy_warn', toolName, ruleId: rule.id, reason: rule.reason }, 'Policy warning (allowing)')
+          // Fall through to allow — warnings are logged only
+        }
+        // 'require_approval' treated as block in headless proxy (no interactive UI)
+        if (rule.action === 'require_approval') {
+          const reason = `Tool requires human approval per SOP rule ${rule.id}: ${rule.reason}`
+          log.warn({ action: 'policy_approval_required', toolName, ruleId: rule.id }, reason)
+          this.emitter.emit('tool_blocked', toolName, toolInput, reason)
+          return { action: 'block', reason }
+        }
+      }
+    } catch (err) {
+      log.error({ action: 'policy_error', err: (err as Error).message }, 'Policy evaluation error')
+      if (!this.failOpen) {
+        return {
+          action: 'block',
+          reason:
+            'Governance check failed — Intutic control plane unreachable. ' +
+            'Tool call blocked by workspace policy (fail-closed mode). ' +
+            'Contact your administrator or update mcpProxyFailBehavior to open.',
+        }
+      }
+    }
+
+    // 3. Allow — emit telemetry event
+    this.emitter.emit('tool_allowed', toolName, toolInput)
+    return { action: 'allow' }
+  }
+}

package/src/policy.ts

@@ -0,0 +1,152 @@
+/**
+ * policy.ts — PolicyClient: fetches and caches SOP governance rules from the Intutic control plane.
+ *
+ * Rules are refreshed every policyTtlMs (default: 60s). On fetch failure, the
+ * last-known-good set is retained (fail-open behaviour).
+ *
+ * @module
+ */
+
+import * as node_https from 'node:https'
+import * as node_http from 'node:http'
+import { createStderrLogger as createLogger } from './stderrLog.js'
+import { callDaemonSocket } from './daemonClient.js'
+
+const log = createLogger('mcp-proxy-policy')
+
+export interface SopRule {
+  id: string
+  /** Regex pattern matched against tool name (e.g. "mcp__github__.*" or "Bash") */
+  toolPattern: string
+  /** Optional regex matched against JSON.stringify(tool_input) */
+  argPattern?: string
+  /** Action to take when the rule matches */
+  action: 'block' | 'warn' | 'require_approval'
+  /** Human-readable reason reported back to harness */
+  reason: string
+}
+
+interface SopRulesResponse {
+  rules: SopRule[]
+}
+
+export class PolicyClient {
+  private rules: SopRule[] = []
+  private lastFetchAt = 0
+  private refreshTimer: NodeJS.Timeout | null = null
+
+  constructor(
+    private readonly controlPlaneUrl: string,
+    private readonly apiKey: string,
+    private readonly workspaceId: string,
+    private readonly ttlMs: number = 60_000,
+    private readonly mcpProxyMode: string = 'per-session'
+  ) {}
+
+  /** Start background refresh timer. */
+  start(): void {
+    this.refreshTimer = setInterval(() => {
+      void this.refresh().catch(() => {
+        // Errors already logged inside refresh()
+      })
+    }, this.ttlMs)
+    // Don't block Node.js exit on this timer
+    this.refreshTimer.unref()
+
+    // Kick off initial fetch (non-blocking — proxy starts immediately)
+    void this.refresh().catch(() => {})
+  }
+
+  /** Stop the background refresh timer. */
+  stop(): void {
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer)
+      this.refreshTimer = null
+    }
+  }
+
+  /** Return the current cached rule set. */
+  getRules(): readonly SopRule[] {
+    return this.rules
+  }
+
+  /** Find the first matching rule for a given tool name + serialized args. */
+  matchRule(toolName: string, toolInputJson: string): SopRule | null {
+    for (const rule of this.rules) {
+      try {
+        const toolRegex = new RegExp(rule.toolPattern)
+        if (!toolRegex.test(toolName)) continue
+        if (rule.argPattern) {
+          const argRegex = new RegExp(rule.argPattern)
+          if (!argRegex.test(toolInputJson)) continue
+        }
+        return rule
+      } catch {
+        // Malformed regex in rule — skip silently
+      }
+    }
+    return null
+  }
+
+  /** Fetch fresh rules from the control plane. */
+  async refresh(): Promise<void> {
+    if (this.mcpProxyMode === 'daemon') {
+      try {
+        const policy = await callDaemonSocket('policy.get', { workspaceId: this.workspaceId })
+        if (policy) {
+          this.rules = (policy.sopRules || []) as SopRule[]
+          this.lastFetchAt = Date.now()
+          log.info({ action: 'policy_refreshed_from_daemon', ruleCount: this.rules.length }, 'SOP rules refreshed from daemon')
+          return
+        }
+      } catch (err: any) {
+        log.warn({ action: 'policy_daemon_failed', err: err.message }, 'Failed to refresh policy from daemon socket — falling back to HTTP')
+      }
+    }
+
+    const url = `${this.controlPlaneUrl}/api/v1/sop/rules?workspaceId=${encodeURIComponent(this.workspaceId)}&active=true`
+    log.debug({ action: 'policy_refresh', url }, 'Fetching SOP rules from control plane')
+
+    const body = await httpGet(url, this.apiKey)
+    const parsed = JSON.parse(body) as SopRulesResponse
+    const rules = Array.isArray(parsed.rules) ? parsed.rules : []
+    this.rules = rules
+    this.lastFetchAt = Date.now()
+    log.info({ action: 'policy_refreshed', ruleCount: rules.length }, 'SOP rules refreshed')
+  }
+}
+
+/** Minimal HTTP/HTTPS GET helper (avoids fetch / node-fetch dep). */
+function httpGet(url: string, apiKey: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url)
+    const lib = parsed.protocol === 'https:' ? node_https : node_http
+    const req = lib.get(
+      url,
+      {
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          Accept: 'application/json',
+        },
+        timeout: 5000,
+      },
+      (res) => {
+        const chunks: Buffer[] = []
+        res.on('data', (c: Buffer) => chunks.push(c))
+        res.on('end', () => {
+          const body = Buffer.concat(chunks).toString('utf-8')
+          if ((res.statusCode ?? 0) >= 400) {
+            reject(new Error(`HTTP ${res.statusCode ?? 'unknown'}: ${body}`))
+          } else {
+            resolve(body)
+          }
+        })
+      }
+    )
+    req.on('error', reject)
+    req.on('timeout', () => {
+      req.destroy()
+      reject(new Error('Policy fetch timed out'))
+    })
+  })
+}

package/src/proxy.ts

@@ -0,0 +1,327 @@
+/**
+ * proxy.ts — McpGovernanceProxy: transparent stdio MCP proxy with governance interception.
+ *
+ * Architecture (proxy mode):
+ *   Harness stdin → [McpGovernanceProxy] → real MCP server stdin
+ *   Real MCP server stdout → [McpGovernanceProxy] → Harness stdout
+ *
+ * Architecture (standalone mode — the `intutic` harness entry):
+ *   Harness ↔ [McpGovernanceProxy as MCP Server] ↔ Control Plane REST API
+ *   Exposes governance tools: intutic_governance_status, intutic_list_sops, intutic_list_incidents.
+ *
+ * CRITICAL: Never write to process.stdout except for valid JSON-RPC frames.
+ *           All logging MUST go to process.stderr via @intutic/logger.
+ *
+ * JSON-RPC framing: newline-delimited JSON (one JSON object per line).
+ *
+ * @module
+ */
+
+import * as node_child from 'node:child_process'
+import * as node_readline from 'node:readline'
+import { createStderrLogger as createLogger } from './stderrLog.js'
+import type { ProxyConfig } from './config.js'
+import { PolicyClient } from './policy.js'
+import { GovernanceEmitter } from './emitter.js'
+import { ToolCallInterceptor } from './interceptor.js'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+
+const log = createLogger('mcp-governance-proxy')
+
+interface JsonRpcRequest {
+  jsonrpc: '2.0'
+  id: string | number | null
+  method: string
+  params?: unknown
+}
+
+interface JsonRpcResponse {
+  jsonrpc: '2.0'
+  id: string | number | null
+  result?: unknown
+  error?: { code: number; message: string; data?: unknown }
+}
+
+interface McpToolsCallParams {
+  name: string
+  arguments?: Record<string, unknown>
+}
+
+/**
+ * Build a JSON-RPC 2.0 error response for a blocked tool call.
+ */
+function buildBlockResponse(id: string | number | null, reason: string): JsonRpcResponse {
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code: -32603, // Internal error (closest standard code to "blocked")
+      message: `[Intutic Governance] Tool call blocked: ${reason}`,
+    },
+  }
+}
+
+/**
+ * Write a JSON-RPC frame to stdout (the ONLY valid place to write in a stdio MCP proxy).
+ */
+function writeFrame(frame: unknown): void {
+  process.stdout.write(JSON.stringify(frame) + '\n')
+}
+
+export class McpGovernanceProxy {
+  private readonly policy: PolicyClient
+  private readonly emitter: GovernanceEmitter
+  private readonly interceptor: ToolCallInterceptor
+  private realServer: node_child.ChildProcess | null = null
+
+  constructor(private readonly config: ProxyConfig) {
+    this.policy = new PolicyClient(
+      config.controlPlaneUrl,
+      config.apiKey,
+      config.workspaceId,
+      config.policyTtlMs,
+      config.mcpProxyMode
+    )
+
+    this.emitter = new GovernanceEmitter(
+      config.controlPlaneUrl,
+      config.apiKey,
+      config.eventsFilePath,
+      config.workspaceId,
+      config.mcpProxyMode
+    )
+
+    this.interceptor = new ToolCallInterceptor(this.policy, this.emitter, config.failOpen)
+  }
+
+  /**
+   * Start the proxy. Dispatches to standalone or proxy mode based on config.
+   */
+  async run(): Promise<void> {
+    if (this.config.standalone) {
+      return this.runStandalone()
+    }
+    return this.runProxy()
+  }
+
+  // ─── Standalone MCP Server Mode ──────────────────────────────────────────────
+
+  /**
+   * Run as a standalone MCP server (the `intutic` harness entry).
+   * Exposes Intutic governance tools directly to the harness.
+   * Gracefully degrades when the control plane is unreachable.
+   */
+  private async runStandalone(): Promise<void> {
+    log.info(
+      { action: 'standalone_start', workspaceId: this.config.workspaceId },
+      'Starting Intutic MCP governance server (standalone mode)'
+    )
+
+    const server = new McpServer({
+      name: 'intutic',
+      version: '0.1.0',
+    })
+
+    const cpUrl = this.config.controlPlaneUrl
+    const apiKey = this.config.apiKey
+    const workspaceId = this.config.workspaceId
+
+    /**
+     * Helper: call control plane REST API.
+     * Returns null on any error (graceful degradation — never crashes the MCP server).
+     */
+    async function callControlPlane(path: string): Promise<unknown> {
+      try {
+        const res = await fetch(`${cpUrl}${path}`, {
+          headers: {
+            'Authorization': `Bearer ${apiKey}`,
+            'x-workspace-id': workspaceId,
+          },
+          signal: AbortSignal.timeout(5000),
+        })
+        if (!res.ok) return null
+        return res.json()
+      } catch {
+        return null
+      }
+    }
+
+    // Tool: intutic_governance_status
+    server.tool(
+      'intutic_governance_status',
+      'Returns the current governance status and health of the Intutic control plane for this workspace.',
+      {},
+      async () => {
+        const health = await callControlPlane('/healthz') as Record<string, unknown> | null
+        const status = health
+          ? { connected: true, controlPlane: cpUrl, workspaceId, ...health }
+          : { connected: false, controlPlane: cpUrl, workspaceId, error: 'Control plane unreachable' }
+
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(status, null, 2) }],
+        }
+      }
+    )
+
+    // Tool: intutic_list_sops
+    server.tool(
+      'intutic_list_sops',
+      'Lists Standard Operating Procedures (SOPs) active in this workspace.',
+      { limit: z.number().int().min(1).max(50).default(10).describe('Number of SOPs to return (1–50)') },
+      async ({ limit }) => {
+        const data = await callControlPlane(
+          `/api/v1/sops?workspaceId=${workspaceId}&limit=${limit}`
+        ) as Record<string, unknown> | null
+        const text = data
+          ? JSON.stringify(data, null, 2)
+          : 'Could not reach control plane to list SOPs.'
+
+        return {
+          content: [{ type: 'text' as const, text }],
+        }
+      }
+    )
+
+    // Tool: intutic_list_incidents
+    server.tool(
+      'intutic_list_incidents',
+      'Lists recent governance incidents (policy violations, blocked tool calls) in this workspace.',
+      { limit: z.number().int().min(1).max(50).default(10).describe('Number of incidents to return (1–50)') },
+      async ({ limit }) => {
+        const data = await callControlPlane(
+          `/api/v1/incidents?workspaceId=${workspaceId}&limit=${limit}`
+        ) as Record<string, unknown> | null
+        const text = data
+          ? JSON.stringify(data, null, 2)
+          : 'Could not reach control plane to list incidents.'
+
+        return {
+          content: [{ type: 'text' as const, text }],
+        }
+      }
+    )
+
+    const transport = new StdioServerTransport()
+    await server.connect(transport)
+    log.info({ action: 'standalone_ready' }, 'Intutic MCP server ready')
+
+    // Keep alive until stdin closes (harness disconnects)
+    await new Promise<void>((resolve) => {
+      process.stdin.on('close', resolve)
+      process.on('SIGINT', resolve)
+      process.on('SIGTERM', resolve)
+    })
+
+    await server.close()
+  }
+
+  // ─── Proxy Mode ───────────────────────────────────────────────────────────────
+
+  /**
+   * Start the proxy. Spawns the real MCP server and begins proxying stdin/stdout.
+   * Returns a promise that resolves when the real server exits.
+   */
+  private async runProxy(): Promise<void> {
+    const [cmd, ...args] = this.config.realServerCommand
+
+    log.info(
+      { action: 'proxy_start', cmd, args, workspaceId: this.config.workspaceId },
+      'Starting MCP governance proxy'
+    )
+
+    // Start background policy refresh
+    this.policy.start()
+
+    // Spawn the real MCP server
+    const realServer = node_child.spawn(cmd!, args, {
+      stdio: ['pipe', 'pipe', 'inherit'], // inherit stderr so real server logs appear normally
+    })
+
+    this.realServer = realServer
+
+    // Handle graceful shutdown
+    const shutdown = (signal: string) => {
+      log.info({ action: 'proxy_shutdown', signal }, 'Shutting down MCP governance proxy')
+      this.policy.stop()
+      if (!realServer.killed) {
+        realServer.kill()
+      }
+      process.exit(0)
+    }
+    process.on('SIGINT', () => shutdown('SIGINT'))
+    process.on('SIGTERM', () => shutdown('SIGTERM'))
+
+    // Real server stdout → harness stdout (pass through)
+    realServer.stdout!.on('data', (chunk: Buffer) => {
+      process.stdout.write(chunk)
+    })
+
+    // Harness stdin → governance interceptor → real server stdin
+    const rl = node_readline.createInterface({ input: process.stdin, terminal: false })
+
+    rl.on('line', (line) => {
+      const trimmed = line.trim()
+      if (!trimmed) return
+
+      let msg: JsonRpcRequest
+      try {
+        msg = JSON.parse(trimmed) as JsonRpcRequest
+      } catch {
+        log.warn({ action: 'parse_error', line: trimmed.slice(0, 100) }, 'Failed to parse JSON-RPC line')
+        return
+      }
+
+      // Intercept tools/call
+      if (msg.method === 'tools/call') {
+        const params = msg.params as McpToolsCallParams | undefined
+        const toolName = params?.name ?? '<unknown>'
+        const toolInput = params?.arguments ?? {}
+
+        // Run governance check asynchronously
+        this.interceptor.decide(toolName, toolInput).then((decision) => {
+          if (decision.action === 'block') {
+            log.warn(
+              { action: 'tool_blocked', toolName, reason: decision.reason },
+              'Tool call blocked by governance proxy'
+            )
+            writeFrame(buildBlockResponse(msg.id, decision.reason))
+          } else {
+            // Allow: forward to real server
+            realServer.stdin!.write(line + '\n')
+          }
+        }).catch((err) => {
+          // Governance check failed — fail-open: forward to real server
+          log.error({ action: 'interceptor_error', err: (err as Error).message }, 'Interceptor error — failing open')
+          realServer.stdin!.write(line + '\n')
+        })
+      } else {
+        // Non-tools/call messages pass through immediately
+        realServer.stdin!.write(line + '\n')
+      }
+    })
+
+    rl.on('close', () => {
+      log.info({ action: 'stdin_closed' }, 'Harness stdin closed — shutting down')
+      this.policy.stop()
+      if (!realServer.killed) {
+        realServer.kill()
+      }
+    })
+
+    // Wait for the real server to exit
+    return new Promise((resolve, reject) => {
+      realServer.on('exit', (code, signal) => {
+        log.info({ action: 'real_server_exit', code, signal }, 'Real MCP server exited')
+        this.policy.stop()
+        resolve()
+      })
+      realServer.on('error', (err) => {
+        log.error({ action: 'real_server_error', err: err.message }, 'Real MCP server process error')
+        this.policy.stop()
+        reject(err)
+      })
+    })
+  }
+}

package/src/stderrLog.ts

@@ -0,0 +1,56 @@
+/**
+ * stderrLog.ts — Lightweight structured logger for the MCP governance proxy.
+ *
+ * CRITICAL: In an MCP stdio server, stdout is exclusively for JSON-RPC frames.
+ * This module bypasses pino (which defaults to stdout) and writes structured
+ * JSON logs directly to process.stderr (fd 2).
+ *
+ * Do NOT use @intutic/logger anywhere in packages/mcp-proxy — it routes to
+ * stdout unless PINO_DEST=stderr is set, which is fragile across harnesses.
+ *
+ * @module
+ */
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+interface LogBindings {
+  [key: string]: unknown
+}
+
+/**
+ * A stderr-only structured logger that matches the @intutic/logger call surface.
+ */
+export class StderrLogger {
+  private readonly name: string
+  private readonly staticBindings: LogBindings
+
+  constructor(name: string, bindings: LogBindings = {}) {
+    this.name = name
+    this.staticBindings = bindings
+  }
+
+  private write(level: LogLevel, bindings: LogBindings, msg: string): void {
+    const entry = {
+      level,
+      time: new Date().toISOString(),
+      name: this.name,
+      ...this.staticBindings,
+      ...bindings,
+      msg,
+    }
+    process.stderr.write(JSON.stringify(entry) + '\n')
+  }
+
+  debug(bindings: LogBindings, msg: string): void { this.write('debug', bindings, msg) }
+  info(bindings: LogBindings, msg: string): void  { this.write('info',  bindings, msg) }
+  warn(bindings: LogBindings, msg: string): void  { this.write('warn',  bindings, msg) }
+  error(bindings: LogBindings, msg: string): void { this.write('error', bindings, msg) }
+
+  child(bindings: LogBindings): StderrLogger {
+    return new StderrLogger(this.name, { ...this.staticBindings, ...bindings })
+  }
+}
+
+export function createStderrLogger(name: string, bindings?: LogBindings): StderrLogger {
+  return new StderrLogger(name, bindings)
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "composite": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/__tests__/**"]
+}