@intutic/mcp-governance-proxy 1.0.3

package/src/daemon/socketServer.ts

@@ -0,0 +1,111 @@
+/**
+ * JSON-RPC over Unix Domain Socket server
+ *
+ * Accepts newline-delimited JSON requests from MCP shims.
+ * Methods: proxy.tool_call, proxy.health_check, policy.get, telemetry.flush
+ *
+ * LLD #28: MCP Daemon Mode, WS-5MCP
+ * @module
+ */
+import net  from 'node:net'
+import path from 'node:path'
+import os   from 'node:os'
+import { createLogger } from '@intutic/logger'
+import { resolvePolicy, getCacheStats, invalidatePolicy } from './policyCache.js'
+import { enqueueEvent } from './telemetryBatcher.js'
+import { getHealthSnapshot } from './healthMonitor.js'
+import type { HookEvent } from './telemetryBatcher.js'
+
+const logger = createLogger('mcp-proxy.socketServer')
+
+export function getSocketPath(): string {
+  return process.env['MCP_DAEMON_SOCKET'] ??
+    path.join(os.homedir(), '.intutic', 'mcp-proxy.sock')
+}
+
+interface JsonRpcRequest {
+  jsonrpc: '2.0'
+  id:      string | number
+  method:  string
+  params:  Record<string, unknown>
+}
+
+function respond(socket: net.Socket, id: string | number, result: unknown): void {
+  socket.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n')
+}
+
+function respondError(socket: net.Socket, id: string | number, code: number, message: string): void {
+  socket.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n')
+}
+
+async function handleRequest(socket: net.Socket, req: JsonRpcRequest): Promise<void> {
+  const { id, method, params } = req
+
+  switch (method) {
+    case 'proxy.health_check':
+      respond(socket, id, { status: 'ok', version: process.env['npm_package_version'] ?? '0.0.0',
+        cacheStats: getCacheStats(), mcpServers: getHealthSnapshot() })
+      break
+
+    case 'proxy.tool_call': {
+      const workspaceId = params['workspaceId'] as string
+      const policy = await resolvePolicy(workspaceId)
+      // Simplified enforcement: if policy loaded, apply it
+      const allowed = policy !== null
+      respond(socket, id, { allowed, policy: policy ?? null })
+      break
+    }
+
+    case 'policy.get': {
+      const workspaceId = params['workspaceId'] as string
+      const policy = await resolvePolicy(workspaceId)
+      respond(socket, id, policy)
+      break
+    }
+
+    case 'policy.invalidate': {
+      const workspaceId = params['workspaceId'] as string
+      invalidatePolicy(workspaceId)
+      respond(socket, id, { invalidated: true })
+      break
+    }
+
+    case 'telemetry.enqueue': {
+      enqueueEvent(params as unknown as HookEvent)
+      respond(socket, id, { queued: true })
+      break
+    }
+
+    default:
+      respondError(socket, id, -32601, `Method not found: ${method}`)
+  }
+}
+
+export function createSocketServer(): net.Server {
+  const server = net.createServer((socket) => {
+    socket.setEncoding('utf8')
+    let buffer = ''
+
+    socket.on('data', (chunk: string) => {
+      buffer += chunk
+      const lines = buffer.split('\n')
+      buffer = lines.pop() ?? ''
+      for (const line of lines) {
+        const trimmed = line.trim()
+        if (!trimmed) continue
+        try {
+          const req = JSON.parse(trimmed) as JsonRpcRequest
+          void handleRequest(socket, req).catch(err =>
+            respondError(socket, req.id, -32603, String(err)))
+        } catch {
+          socket.write(JSON.stringify({ jsonrpc: '2.0', id: null,
+            error: { code: -32700, message: 'Parse error' } }) + '\n')
+        }
+      }
+    })
+
+    socket.on('error', (err) => logger.warn({ err }, 'socket.client_error'))
+  })
+
+  return server
+}

package/src/daemon/telemetryBatcher.ts

@@ -0,0 +1,147 @@
+/**
+ * Telemetry Batcher — ring buffer + 1s flush to control-plane
+ *
+ * Accumulates hook events and batches them for upload.
+ * Fallback: Valkey event buffer, followed by disk buffer at ~/.intutic/telemetry-buffer.ndjson on flush failure.
+ *
+ * LLD #28: MCP Daemon Mode, WS-5MCP
+ * @module
+ */
+import https from 'node:https'
+import http  from 'node:http'
+import fs    from 'node:fs'
+import path  from 'node:path'
+import os    from 'node:os'
+import { Redis } from 'ioredis'
+import { createLogger } from '@intutic/logger'
+
+const logger = createLogger('mcp-proxy.telemetryBatcher')
+
+const CP_URL          = process.env['CONTROL_PLANE_URL']              ?? 'http://localhost:3001'
+const DAEMON_API_KEY  = process.env['INTUTIC_API_KEY']                ?? ''
+const FLUSH_MS        = parseInt(process.env['MCP_DAEMON_TELEMETRY_FLUSH_MS'] ?? '1000', 10)
+const RING_CAPACITY   = 200
+const DISK_BUFFER     = path.join(os.homedir(), '.intutic', 'telemetry-buffer.ndjson')
+
+const VALKEY_URL = process.env['VALKEY_URL'] ?? process.env['REDIS_URL'] ?? 'redis://localhost:6379'
+const valkey = new Redis(VALKEY_URL, {
+  lazyConnect: true,
+  maxRetriesPerRequest: 3,
+})
+
+valkey.on('error', (err: any) => {
+  logger.warn({ err: err.message }, 'telemetryBatcher Valkey connection error')
+})
+
+const daemonId = process.pid.toString()
+
+export interface HookEvent {
+  event:       string
+  toolName:    string
+  workspaceId: string
+  harnessType: string
+  timestamp:   string
+  [key: string]: unknown
+}
+
+const ring: HookEvent[] = []
+let flushTimer: ReturnType<typeof setInterval> | null = null
+let isFlushing = false
+
+/** Enqueues a hook event. Evicts oldest on overflow. */
+export function enqueueEvent(event: HookEvent): void {
+  if (ring.length >= RING_CAPACITY) ring.shift()
+  ring.push(event)
+}
+
+async function flush(): Promise<void> {
+  if (isFlushing || ring.length === 0) return
+  isFlushing = true
+  const batch = ring.splice(0, ring.length)
+
+  const body   = JSON.stringify({ events: batch })
+  const url    = new URL('/api/v1/hook-events', CP_URL)
+  const isHttps = url.protocol === 'https:'
+  const lib    = isHttps ? https : http
+
+  const tryUpload = (attempt: number): Promise<void> => new Promise((resolve, reject) => {
+    const req = lib.request(
+      { hostname: url.hostname, port: url.port, path: url.pathname, method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body),
+                   'Authorization': `Bearer ${DAEMON_API_KEY}` } },
+      (res) => {
+        res.resume()
+        if (res.statusCode && res.statusCode < 400) resolve()
+        else reject(new Error(`HTTP ${res.statusCode}`))
+      }
+    )
+    req.on('error', reject)
+    req.setTimeout(5000, () => { req.destroy(); reject(new Error('timeout')) })
+    req.write(body)
+    req.end()
+  })
+
+  let success = false
+  for (let i = 0; i < 3; i++) {
+    try { await tryUpload(i); success = true; break }
+    catch { await new Promise(r => setTimeout(r, 500 * (i + 1))) }
+  }
+
+  if (!success) {
+    // Persist to Valkey first
+    try {
+      const key = `mcp_daemon:event_buffer:${daemonId}`
+      await valkey.rpush(key, ...batch.map(e => JSON.stringify(e)))
+      await valkey.expire(key, 600) // 10 min TTL
+      logger.warn({ count: batch.length }, 'telemetry.flush_failed_buffered_to_valkey')
+    } catch (valkeyErr: any) {
+      // Fallback: local disk buffer
+      try {
+        fs.mkdirSync(path.dirname(DISK_BUFFER), { recursive: true, mode: 0o700 })
+        fs.appendFileSync(DISK_BUFFER, batch.map(e => JSON.stringify(e)).join('\n') + '\n', { mode: 0o600 })
+        logger.warn({ count: batch.length }, 'telemetry.flush_failed_buffered_to_disk')
+      } catch (diskErr) {
+        logger.error({ diskErr, count: batch.length }, 'telemetry.disk_buffer_failed')
+      }
+    }
+  } else {
+    logger.debug({ count: batch.length }, 'telemetry.flushed')
+  }
+  isFlushing = false
+}
+
+/** Drains any Valkey or disk buffer from a previous crash, then starts the flush timer. */
+export function startBatcher(): void {
+  // Drain Valkey buffer
+  const key = `mcp_daemon:event_buffer:${daemonId}`
+  valkey.lrange(key, 0, -1).then(async (lines: string[]) => {
+    if (lines && lines.length > 0) {
+      for (const line of lines) {
+        try { enqueueEvent(JSON.parse(line) as HookEvent) } catch {}
+      }
+      await valkey.del(key)
+      logger.info({ count: lines.length }, 'telemetry.valkey_buffer_drained')
+    }
+  }).catch(() => {})
+
+  // Drain disk buffer
+  try {
+    if (fs.existsSync(DISK_BUFFER)) {
+      const lines = fs.readFileSync(DISK_BUFFER, 'utf8').trim().split('\n').filter(Boolean)
+      for (const line of lines) {
+        try { enqueueEvent(JSON.parse(line) as HookEvent) } catch {}
+      }
+      fs.unlinkSync(DISK_BUFFER)
+      logger.info({ count: lines.length }, 'telemetry.disk_buffer_drained')
+    }
+  } catch {}
+
+  flushTimer = setInterval(() => { void flush() }, FLUSH_MS)
+  flushTimer.unref()
+}
+
+/** Flushes remaining events and stops the timer. */
+export async function stopBatcher(): Promise<void> {
+  if (flushTimer) { clearInterval(flushTimer); flushTimer = null }
+  await flush()
+}

package/src/daemonClient.ts

@@ -0,0 +1,71 @@
+/**
+ * daemonClient.ts — IPC socket client helper for communicating with mcp-daemon.
+ * LLD #28: MCP Daemon Mode, WS-5MCP
+ *
+ * @module
+ */
+import * as net from 'node:net'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import { createStderrLogger as createLogger } from './stderrLog.js'
+
+const log = createLogger('mcp-proxy-daemon-client')
+
+function getSocketPath(): string {
+  return process.env['MCP_DAEMON_SOCKET'] ??
+    path.join(os.homedir(), '.intutic', 'mcp-proxy.sock')
+}
+
+/**
+ * Sends a JSON-RPC request to the mcp-daemon Unix domain socket.
+ */
+export function callDaemonSocket(method: string, params: Record<string, unknown>): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(getSocketPath())
+    socket.setEncoding('utf8')
+
+    let buffer = ''
+    const req = {
+      jsonrpc: '2.0',
+      id: Date.now().toString() + Math.random().toString(36).substring(2, 7),
+      method,
+      params,
+    }
+
+    socket.on('connect', () => {
+      socket.write(JSON.stringify(req) + '\n')
+    })
+
+    socket.on('data', (chunk: string) => {
+      buffer += chunk
+      const lines = buffer.split('\n')
+      if (lines.length > 1) {
+        const line = lines[0]!.trim()
+        if (line) {
+          try {
+            const res = JSON.parse(line)
+            if (res.error) {
+              reject(new Error(res.error.message))
+            } else {
+              resolve(res.result)
+            }
+          } catch (err) {
+            reject(err)
+          } finally {
+            socket.end()
+          }
+        }
+      }
+    })
+
+    socket.on('error', (err) => {
+      reject(err)
+    })
+
+    // 2s timeout
+    socket.setTimeout(2000, () => {
+      socket.destroy()
+      reject(new Error('Daemon socket timeout'))
+    })
+  })
+}

package/src/dlp.ts

@@ -0,0 +1,72 @@
+/**
+ * dlp.ts — DLP (Data Loss Prevention) argument scanner.
+ *
+ * Scans tool arguments (as a JSON string) for patterns that indicate
+ * credentials, secrets, PII, or other sensitive data before allowing
+ * the tool call to proceed.
+ *
+ * @module
+ */
+
+export interface DlpFinding {
+  pattern: string
+  description: string
+}
+
+export interface DlpScanResult {
+  hasFinding: boolean
+  findings: DlpFinding[]
+}
+
+/**
+ * Compiled DLP patterns. Each entry has a regex and a human-readable description.
+ */
+const DLP_PATTERNS: Array<{ regex: RegExp; description: string }> = [
+  // API keys / tokens
+  { regex: /sk-[A-Za-z0-9]{20,}/, description: 'OpenAI API key pattern' },
+  { regex: /sk-ant-[A-Za-z0-9\-_]{20,}/, description: 'Anthropic API key pattern' },
+  { regex: /AIza[A-Za-z0-9\-_]{35}/, description: 'Google API key pattern' },
+  { regex: /ghp_[A-Za-z0-9]{36}/, description: 'GitHub personal access token' },
+  { regex: /ghs_[A-Za-z0-9]{36}/, description: 'GitHub server token' },
+  { regex: /xoxb-[A-Za-z0-9\-]{50,}/, description: 'Slack bot token' },
+  { regex: /xoxp-[A-Za-z0-9\-]{50,}/, description: 'Slack user token' },
+  { regex: /AKIA[A-Z0-9]{16}/, description: 'AWS Access Key ID' },
+  // High-entropy strings that look like secrets (≥40 chars of hex or base64)
+  { regex: /[0-9a-f]{40,}/, description: 'High-entropy hex string (possible secret)' },
+  // Destructive shell patterns in Bash/command arguments
+  { regex: /rm\s+-rf?\s+\//, description: 'Destructive rm -rf / command' },
+  { regex: /DROP\s+TABLE/i, description: 'SQL DROP TABLE statement' },
+  { regex: /DROP\s+DATABASE/i, description: 'SQL DROP DATABASE statement' },
+  { regex: /TRUNCATE\s+TABLE/i, description: 'SQL TRUNCATE TABLE statement' },
+  // Private key material
+  { regex: /-----BEGIN\s+(RSA\s+)?PRIVATE KEY-----/, description: 'PEM private key material' },
+  { regex: /-----BEGIN\s+EC\s+PRIVATE KEY-----/, description: 'EC private key material' },
+]
+
+/**
+ * Scan tool arguments for DLP findings.
+ *
+ * @param toolInput - The tool_input object from the MCP tools/call request
+ * @returns DLP scan result with any findings
+ */
+export function scanToolInput(toolInput: unknown): DlpScanResult {
+  // Serialize to string for pattern matching
+  const serialized = JSON.stringify(toolInput ?? {})
+  const findings: DlpFinding[] = []
+
+  for (const { regex, description } of DLP_PATTERNS) {
+    if (regex.test(serialized)) {
+      findings.push({ pattern: regex.source, description })
+    }
+  }
+
+  return { hasFinding: findings.length > 0, findings }
+}
+
+/**
+ * Format DLP findings into a human-readable block reason.
+ */
+export function formatDlpBlockReason(findings: DlpFinding[]): string {
+  const list = findings.map((f) => `• ${f.description}`).join('\n')
+  return `Tool call blocked by Intutic DLP scanner. Sensitive data detected:\n${list}`
+}

package/src/emitter.ts

@@ -0,0 +1,144 @@
+/**
+ * emitter.ts — Dual-path governance event emitter.
+ *
+ * Path A: HTTP POST to /api/v1/hook-events (same endpoint as claudeCodeHooks.ts)
+ * Path B: Append JSONL line to ~/.intutic/events/hook-events.jsonl
+ *
+ * Mirrors the dual-path pattern from claudeCodeHooks.ts / syncLoop.ts.
+ *
+ * @module
+ */
+
+import * as node_fs from 'node:fs/promises'
+import * as node_https from 'node:https'
+import * as node_http from 'node:http'
+import * as node_path from 'node:path'
+import * as node_crypto from 'node:crypto'
+import { createStderrLogger as createLogger } from './stderrLog.js'
+import { callDaemonSocket } from './daemonClient.js'
+
+const log = createLogger('mcp-proxy-emitter')
+
+export type EventKind = 'tool_allowed' | 'tool_blocked' | 'tool_redacted'
+
+export interface GovernanceEvent {
+  incidentId: string
+  kind: EventKind
+  toolName: string
+  toolInput: unknown
+  workspaceId: string
+  harnessType: string
+  reason?: string
+  timestamp: string
+}
+
+export class GovernanceEmitter {
+  constructor(
+    private readonly controlPlaneUrl: string,
+    private readonly apiKey: string,
+    private readonly eventsFilePath: string,
+    private readonly workspaceId: string,
+    private readonly mcpProxyMode: string = 'per-session'
+  ) {}
+
+  emit(kind: EventKind, toolName: string, toolInput: unknown, reason?: string): void {
+    const event: GovernanceEvent = {
+      incidentId: node_crypto.randomUUID(),
+      kind,
+      toolName,
+      toolInput,
+      workspaceId: this.workspaceId,
+      harnessType: 'mcp-governance-proxy',
+      reason,
+      timestamp: new Date().toISOString(),
+    }
+
+    if (this.mcpProxyMode === 'daemon') {
+      const eventPayload = {
+        event: kind === 'tool_blocked' ? 'tool_blocked' : 'tool_allowed',
+        toolName,
+        workspaceId: this.workspaceId,
+        harnessType: 'mcp-governance-proxy',
+        timestamp: event.timestamp,
+        reason,
+        toolInput,
+      }
+      callDaemonSocket('telemetry.enqueue', eventPayload).then(() => {
+        log.debug({ action: 'telemetry_enqueued' }, 'Telemetry successfully enqueued to daemon')
+      }).catch((err) => {
+        log.warn({ action: 'telemetry_daemon_failed', err: err.message }, 'Failed to enqueue telemetry to daemon socket — falling back to dual-path')
+        this.runDualPath(event)
+      })
+      return
+    }
+
+    this.runDualPath(event)
+  }
+
+  private runDualPath(event: GovernanceEvent): void {
+    // Path A: HTTP POST (best effort)
+    this.postToControlPlane(event).catch((err) => {
+      log.warn({ action: 'emit_path_a_failed', err: (err as Error).message }, 'Path A emission failed')
+    })
+
+    // Path B: JSONL file append (best effort)
+    this.appendToFile(event).catch((err) => {
+      log.warn({ action: 'emit_path_b_failed', err: (err as Error).message }, 'Path B emission failed')
+    })
+  }
+
+  private async postToControlPlane(event: GovernanceEvent): Promise<void> {
+    const payload = JSON.stringify({
+      events: [
+        {
+          event: event.kind === 'tool_blocked' ? 'tool_blocked' : 'tool_allowed',
+          toolName: event.toolName,
+          toolInput: event.toolInput,
+          workspaceId: event.workspaceId,
+          harnessType: event.harnessType,
+          incidentId: event.incidentId,
+          reason: event.reason,
+          timestamp: event.timestamp,
+        },
+      ],
+    })
+
+    const url = `${this.controlPlaneUrl}/api/v1/telemetry/enqueue`
+    await httpPost(url, this.apiKey, payload)
+  }
+
+  private async appendToFile(event: GovernanceEvent): Promise<void> {
+    const dir = node_path.dirname(this.eventsFilePath)
+    await node_fs.mkdir(dir, { recursive: true })
+    const line = JSON.stringify(event) + '\n'
+    await node_fs.appendFile(this.eventsFilePath, line, 'utf-8')
+  }
+}
+
+function httpPost(url: string, apiKey: string, body: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url)
+    const lib = parsed.protocol === 'https:' ? node_https : node_http
+    const req = lib.request(
+      url,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(body),
+          Authorization: `Bearer ${apiKey}`,
+        },
+        timeout: 4000,
+      },
+      (res) => {
+        // Drain response body to free socket
+        res.resume()
+        res.on('end', resolve)
+      }
+    )
+    req.on('error', reject)
+    req.on('timeout', () => { req.destroy(); reject(new Error('HTTP POST timed out')) })
+    req.write(body)
+    req.end()
+  })
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * index.ts — CLI entry point for @intutic/mcp-governance-proxy.
+ *
+ * CRITICAL: In the MCP proxy, stdout is exclusively reserved for JSON-RPC frames.
+ * All logging MUST go to stderr. We redirect pino's output to fd 2 (stderr)
+ * by overriding the destination before any logger is instantiated.
+ *
+ * Usage:
+ *   intutic-mcp-proxy [--workspace-id <id>] -- <real-mcp-server> [args...]
+ *
+ * Example (harness config):
+ *   {
+ *     "command": "node",
+ *     "args": ["/path/to/@intutic/mcp-governance-proxy/dist/index.js",
+ *              "--workspace-id", "ws_xxx",
+ *              "--",
+ *              "npx", "-y", "@modelcontextprotocol/server-filesystem", "/projects"]
+ *   }
+ *
+ * @module
+ */
+
+import { loadConfig } from './config.js'
+import { McpGovernanceProxy } from './proxy.js'
+import { createStderrLogger as createLogger } from './stderrLog.js'
+
+const log = createLogger('mcp-proxy-main')
+
+async function main(): Promise<void> {
+  let config
+  try {
+    config = await loadConfig()
+  } catch (err) {
+    // Write to stderr — never stdout
+    process.stderr.write(`[intutic-mcp-proxy] Configuration error: ${(err as Error).message}\n`)
+    process.exit(1)
+  }
+
+  const proxy = new McpGovernanceProxy(config)
+
+  try {
+    await proxy.run()
+  } catch (err) {
+    log.error({ action: 'proxy_fatal', err: (err as Error).message }, 'Proxy exited with error')
+    process.exit(1)
+  }
+}
+
+main().catch((err: unknown) => {
+  process.stderr.write(`[intutic-mcp-proxy] Fatal error: ${String(err)}\n`)
+  process.exit(1)
+})