@intutic/mcp-governance-proxy 1.4.1 → 1.6.0

package/src/daemon/telemetryBatcher.ts

@@ -1,147 +0,0 @@
-/**
- * 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

@@ -1,71 +0,0 @@
-/**
- * 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

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

@@ -1,144 +0,0 @@
-/**
- * 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

@@ -1,53 +0,0 @@
-#!/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)
-})

package/src/interceptor.ts

@@ -1,103 +0,0 @@
-/**
- * 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' }
-  }
-}