@intutic/mcp-governance-proxy 1.0.3

package/src/__tests__/unit/telemetryBatcher.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import * as http from 'node:http'
+import * as net from 'node:net'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import * as fs from 'node:fs/promises'
+
+describe('telemetryBatcher Unit Tests', () => {
+  let mockServer: http.Server
+  let port: number
+  let receivedPayloads: any[] = []
+
+  let enqueueEvent: any
+  let startBatcher: any
+  let stopBatcher: any
+
+  beforeAll(async () => {
+    // Clear stale disk buffer file to ensure hermetic tests
+    const bufPath = path.join(os.homedir(), '.intutic', 'telemetry-buffer.ndjson')
+    await fs.rm(bufPath, { force: true })
+
+    mockServer = http.createServer((req, res) => {
+      let body = ''
+      req.on('data', (c) => {
+        body += c.toString()
+      })
+      req.on('end', () => {
+        try {
+          receivedPayloads.push(JSON.parse(body))
+        } catch {}
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ ok: true }))
+      })
+    })
+
+    await new Promise<void>((resolve) => {
+      mockServer.listen(0, '127.0.0.1', () => {
+        const addr = mockServer.address() as net.AddressInfo | null
+        port = addr?.port ?? 3001
+        process.env['CONTROL_PLANE_URL'] = `http://127.0.0.1:${port}`
+        process.env['MCP_DAEMON_TELEMETRY_FLUSH_MS'] = '100' // Flush fast for test
+        resolve()
+      })
+    })
+
+    // Import after process.env is set to ensure it uses the mock URL
+    const mod = await import('../../daemon/telemetryBatcher.js')
+    enqueueEvent = mod.enqueueEvent
+    startBatcher = mod.startBatcher
+    stopBatcher = mod.stopBatcher
+  })
+
+  afterAll(async () => {
+    await stopBatcher()
+    await new Promise<void>((resolve) => mockServer.close(() => resolve()))
+  })
+
+  it('batches and uploads enqueued telemetry events', async () => {
+    startBatcher()
+
+    const event = {
+      event: 'tool_blocked',
+      toolName: 'Bash',
+      workspaceId: 'ws_test_telemetry',
+      harnessType: 'mcp-governance-proxy',
+      timestamp: new Date().toISOString(),
+    }
+
+    enqueueEvent(event)
+
+    // Wait for the 100ms flush timer to trigger
+    await new Promise((resolve) => setTimeout(resolve, 250))
+
+    expect(receivedPayloads).toHaveLength(1)
+    expect(receivedPayloads[0].events).toHaveLength(1)
+    expect(receivedPayloads[0].events[0].toolName).toBe('Bash')
+  })
+})

package/src/config.ts

@@ -0,0 +1,145 @@
+/**
+ * config.ts — MCP Governance Proxy configuration.
+ *
+ * Reads from ~/.intutic/env/runtime.env (written by sync-daemon runtimeEnv.ts)
+ * and from CLI arguments passed after `--`.
+ *
+ * @module
+ */
+
+import * as node_fs from 'node:fs/promises'
+import * as node_os from 'node:os'
+import * as node_path from 'node:path'
+
+export interface ProxyConfig {
+  /** Workspace ID for policy lookups and event attribution */
+  workspaceId: string
+  /** Control plane base URL (e.g. http://localhost:3001) */
+  controlPlaneUrl: string
+  /** API key for control plane requests */
+  apiKey: string
+  /** Real MCP server command + args (everything after --). Empty = standalone mode. */
+  realServerCommand: string[]
+  /** Path to write hook-events JSONL (Path B) */
+  eventsFilePath: string
+  /** Policy cache TTL in milliseconds (default: 60_000) */
+  policyTtlMs: number
+  /** Whether to fail-open when control plane is unreachable (default: true) */
+  failOpen: boolean
+  /**
+   * MCP proxy deployment model ('per-session' | 'daemon').
+   * WS-5 Q2 — stored and propagated but 'daemon' is not yet active in Phase 4.
+   */
+  mcpProxyMode: string
+  /**
+   * Standalone mode — when true, the proxy acts as the Intutic MCP server
+   * directly (no downstream server to proxy). Used for the `intutic` harness
+   * entry that exposes Intutic governance tools to the harness.
+   */
+  standalone: boolean
+}
+
+const DEFAULT_EVENTS_PATH = node_path.join(node_os.homedir(), '.intutic', 'events', 'hook-events.jsonl')
+const RUNTIME_ENV_PATH = node_path.join(node_os.homedir(), '.intutic', 'env', 'runtime.env')
+
+/**
+ * Parse a .env-format file into a key→value record.
+ * Lines starting with # are comments; blank lines are skipped.
+ */
+async function parseEnvFile(filePath: string): Promise<Record<string, string>> {
+  const result: Record<string, string> = {}
+  try {
+    const content = await node_fs.readFile(filePath, 'utf-8')
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim()
+      if (!trimmed || trimmed.startsWith('#')) continue
+      const eq = trimmed.indexOf('=')
+      if (eq === -1) continue
+      const key = trimmed.slice(0, eq).trim()
+      // Strip surrounding quotes from value
+      let value = trimmed.slice(eq + 1).trim()
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1)
+      }
+      result[key] = value
+    }
+  } catch {
+    // File may not exist — return empty record
+  }
+  return result
+}
+
+/**
+ * Parse CLI arguments for --workspace-id and the real server command (after --).
+ */
+function parseCliArgs(argv: string[]): { workspaceId?: string; realServerCommand: string[] } {
+  let workspaceId: string | undefined
+  let separatorIndex = -1
+
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--workspace-id' && i + 1 < argv.length) {
+      workspaceId = argv[i + 1]
+      i++ // skip value
+    } else if (argv[i] === '--') {
+      separatorIndex = i
+      break
+    }
+  }
+
+  const realServerCommand = separatorIndex !== -1 ? argv.slice(separatorIndex + 1) : []
+  return { workspaceId, realServerCommand }
+}
+
+/**
+ * Load the proxy configuration from runtime.env + CLI args + environment.
+ */
+export async function loadConfig(argv: string[] = process.argv.slice(2)): Promise<ProxyConfig> {
+  const runtimeEnv = await parseEnvFile(RUNTIME_ENV_PATH)
+  const cli = parseCliArgs(argv)
+
+  const controlPlaneUrl =
+    process.env['INTUTIC_CONTROL_PLANE_URL'] ??
+    runtimeEnv['INTUTIC_CONTROL_PLANE_URL'] ??
+    'http://localhost:3001'
+
+  const apiKey =
+    process.env['INTUTIC_API_KEY'] ??
+    runtimeEnv['INTUTIC_API_KEY'] ??
+    ''
+
+  const workspaceId =
+    cli.workspaceId ??
+    process.env['INTUTIC_WORKSPACE_ID'] ??
+    runtimeEnv['INTUTIC_WORKSPACE_ID'] ??
+    'unknown'
+
+  const eventsFilePath =
+    process.env['INTUTIC_EVENTS_FILE'] ??
+    runtimeEnv['INTUTIC_EVENTS_FILE'] ??
+    DEFAULT_EVENTS_PATH
+
+  const failOpen =
+    (runtimeEnv['INTUTIC_MCP_FAIL_OPEN'] ?? 'true').toLowerCase() !== 'false'
+
+  const mcpProxyMode = runtimeEnv['INTUTIC_MCP_PROXY_MODE'] ?? 'per-session'
+  if (mcpProxyMode === 'daemon') {
+    console.warn(
+      '[mcp-proxy] INTUTIC_MCP_PROXY_MODE=daemon is stored but not yet active — '
+      + 'running in per-session mode (Phase 4). Will be activated in Phase 5.'
+    )
+  }
+
+  const standalone = cli.realServerCommand.length === 0
+
+  return {
+    workspaceId,
+    controlPlaneUrl,
+    apiKey,
+    realServerCommand: cli.realServerCommand,
+    eventsFilePath,
+    policyTtlMs: 60_000,
+    failOpen,
+    mcpProxyMode,
+    standalone,
+  }
+}

package/src/daemon/healthMonitor.ts

@@ -0,0 +1,210 @@
+/**
+ * MCP Server Health Monitor
+ *
+ * Probes MCP servers every 30s and records health snapshots.
+ * Emits mcp_daemon.mcp_server_down when a server becomes unreachable.
+ *
+ * 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 { execSync } from 'node:child_process'
+import { createLogger } from '@intutic/logger'
+
+const logger = createLogger('mcp-proxy.healthMonitor')
+
+const HEARTBEAT_MS = 30_000
+const PROBE_TIMEOUT = 5_000
+
+const CP_URL          = process.env['CONTROL_PLANE_URL'] ?? 'http://localhost:3001'
+const DAEMON_API_KEY  = process.env['INTUTIC_API_KEY']   ?? ''
+const WORKSPACE_ID    = process.env['INTUTIC_WORKSPACE_ID'] ?? ''
+
+export interface McpServerConfig {
+  name:     string
+  url:      string
+  credentialExpiryAt?: Date
+}
+
+export interface McpServerHealth {
+  serverName:          string
+  status:              'healthy' | 'degraded' | 'unreachable'
+  p95LatencyMs?:       number
+  errorRatePct?:       number
+  credentialExpiryAt?: string
+  checkedAt:           string
+}
+
+const servers: McpServerConfig[] = []
+const latestHealth = new Map<string, McpServerHealth>()
+let timer: ReturnType<typeof setInterval> | null = null
+
+function discoverServers(): McpServerConfig[] {
+  const discovered: McpServerConfig[] = []
+  const homedir = os.homedir()
+
+  const configPaths = [
+    path.join(homedir, '.claude', 'mcp.json'),
+    process.platform === 'darwin'
+      ? path.join(homedir, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+      : process.platform === 'win32'
+      ? path.join(process.env['APPDATA'] ?? '', 'Claude', 'claude_desktop_config.json')
+      : path.join(homedir, '.config', 'Claude', 'claude_desktop_config.json'),
+    process.platform === 'darwin'
+      ? path.join(homedir, 'Library', 'Application Support', 'Cursor', 'User', 'globalSettings.json')
+      : process.platform === 'win32'
+      ? path.join(process.env['APPDATA'] ?? '', 'Cursor', 'User', 'globalSettings.json')
+      : path.join(homedir, '.config', 'Cursor', 'User', 'globalSettings.json'),
+  ]
+
+  for (const configPath of configPaths) {
+    try {
+      if (!fs.existsSync(configPath)) continue
+      const raw = fs.readFileSync(configPath, 'utf8')
+      const parsed = JSON.parse(raw)
+      const mcpServers = parsed.mcpServers ?? parsed.mcp ?? {}
+      for (const [name, entry] of Object.entries(mcpServers)) {
+        if (name === 'intutic') continue // Skip self
+        const serverEntry = entry as any
+        
+        let url = ''
+        if (serverEntry.url) {
+          url = serverEntry.url
+        } else if (serverEntry.command) {
+          url = `stdio://${serverEntry.command}`
+        }
+
+        if (url && !discovered.some(s => s.name === name)) {
+          discovered.push({
+            name,
+            url,
+            credentialExpiryAt: undefined
+          })
+        }
+      }
+    } catch {}
+  }
+
+  return discovered
+}
+
+async function probeServer(server: McpServerConfig): Promise<McpServerHealth> {
+  const start = Date.now()
+  if (server.url.startsWith('stdio://')) {
+    const cmd = server.url.replace('stdio://', '')
+    let status: 'healthy' | 'unreachable' = 'healthy'
+    try {
+      const whichCmd = process.platform === 'win32' ? `where ${cmd}` : `which ${cmd}`
+      execSync(whichCmd, { stdio: 'ignore' })
+    } catch {
+      status = 'unreachable'
+    }
+    return {
+      serverName: server.name,
+      status,
+      p95LatencyMs: Date.now() - start,
+      credentialExpiryAt: server.credentialExpiryAt?.toISOString(),
+      checkedAt: new Date().toISOString()
+    }
+  }
+
+  return new Promise((resolve) => {
+    try {
+      const url   = new URL(server.url)
+      const isHttps = url.protocol === 'https:'
+      const lib   = isHttps ? https : http
+      const req   = lib.request(
+        { hostname: url.hostname, port: url.port, path: url.pathname + url.search, method: 'GET' },
+        (res) => {
+          res.resume()
+          const latency = Date.now() - start
+          const status  = res.statusCode && res.statusCode < 500 ? 'healthy' : 'degraded'
+          resolve({ serverName: server.name, status, p95LatencyMs: latency,
+            credentialExpiryAt: server.credentialExpiryAt?.toISOString(),
+            checkedAt: new Date().toISOString() })
+        }
+      )
+      req.on('error', () => resolve({ serverName: server.name, status: 'unreachable',
+        checkedAt: new Date().toISOString() }))
+      req.setTimeout(PROBE_TIMEOUT, () => { req.destroy(); resolve({
+        serverName: server.name, status: 'unreachable', checkedAt: new Date().toISOString() }) })
+      req.end()
+    } catch {
+      resolve({ serverName: server.name, status: 'unreachable', checkedAt: new Date().toISOString() })
+    }
+  })
+}
+
+async function uploadSnapshots(snapshots: McpServerHealth[]): Promise<void> {
+  if (snapshots.length === 0 || !WORKSPACE_ID) return
+  const body = JSON.stringify({ mcpServers: snapshots })
+  const url = new URL('/api/v1/mcp-daemon/health-snapshot', CP_URL)
+  const isHttps = url.protocol === 'https:'
+  const lib = isHttps ? https : http
+
+  return new Promise((resolve) => {
+    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}`,
+          'x-workspace-id': WORKSPACE_ID
+        }
+      },
+      (res: any) => {
+        res.resume()
+        resolve()
+      }
+    )
+    req.on('error', () => resolve())
+    req.setTimeout(5000, () => { req.destroy(); resolve() })
+    req.write(body)
+    req.end()
+  })
+}
+
+export function registerServer(server: McpServerConfig): void {
+  servers.push(server)
+}
+
+export function startHealthMonitor(): void {
+  // Run config discovery
+  const discovered = discoverServers()
+  for (const s of discovered) {
+    registerServer(s)
+  }
+
+  timer = setInterval(async () => {
+    const snapshots: McpServerHealth[] = []
+    for (const server of servers) {
+      const health = await probeServer(server)
+      const prev   = latestHealth.get(server.name)
+      latestHealth.set(server.name, health)
+      snapshots.push(health)
+      if (health.status === 'unreachable' && prev?.status !== 'unreachable') {
+        logger.warn({ serverName: server.name }, 'mcp_daemon.mcp_server_down')
+      }
+    }
+    if (snapshots.length > 0) {
+      await uploadSnapshots(snapshots)
+    }
+  }, HEARTBEAT_MS)
+  timer.unref()
+}
+
+export function stopHealthMonitor(): void {
+  if (timer) { clearInterval(timer); timer = null }
+}
+
+export function getHealthSnapshot(): McpServerHealth[] {
+  return Array.from(latestHealth.values())
+}

package/src/daemon/index.ts

@@ -0,0 +1,76 @@
+/**
+ * intutic-mcp-daemon entry point
+ *
+ * Long-lived process listening on ~/.intutic/mcp-proxy.sock.
+ * Manages policy cache, telemetry batching, and MCP server health monitoring.
+ *
+ * LLD #28: MCP Daemon Mode, WS-5MCP
+ *
+ * Usage:
+ *   node dist/daemon/index.js
+ *   (managed by LaunchAgent / systemd via `intutic daemon mcp start`)
+ *
+ * @module
+ */
+import fs   from 'node:fs'
+import path from 'node:path'
+import os   from 'node:os'
+import { createLogger } from '@intutic/logger'
+import { startBatcher, stopBatcher } from './telemetryBatcher.js'
+import { startHealthMonitor, stopHealthMonitor } from './healthMonitor.js'
+import { createSocketServer, getSocketPath } from './socketServer.js'
+
+const logger = createLogger('intutic-mcp-daemon')
+const PID_FILE = path.join(os.homedir(), '.intutic', 'mcp-daemon.pid')
+
+function ensureDir(dir: string): void {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+}
+
+async function main(): Promise<void> {
+  const socketPath = getSocketPath()
+  logger.info({ pid: process.pid, socketPath }, 'mcp_daemon.starting')
+
+  // Ensure ~/.intutic directory exists with correct permissions
+  ensureDir(path.dirname(socketPath))
+
+  // Remove stale socket file
+  try { fs.unlinkSync(socketPath) } catch {}
+
+  // Write PID file
+  fs.writeFileSync(PID_FILE, String(process.pid), { mode: 0o600 })
+
+  // Start subsystems
+  startBatcher()
+  startHealthMonitor()
+
+  const server = createSocketServer()
+  server.listen(socketPath, () => {
+    // Restrict socket to owner only
+    try { fs.chmodSync(socketPath, 0o600) } catch {}
+    logger.info({ socketPath, pid: process.pid }, 'mcp_daemon.running')
+    process.stdout.write(JSON.stringify({ event: 'mcp_daemon.started', pid: process.pid }) + '\n')
+  })
+
+  server.on('error', (err) => {
+    logger.error({ err }, 'mcp_daemon.socket_error')
+    process.exit(1)
+  })
+
+  // Graceful shutdown
+  const shutdown = async (signal: string): Promise<void> => {
+    logger.info({ signal }, 'mcp_daemon.stopping')
+    server.close()
+    stopHealthMonitor()
+    await stopBatcher()
+    try { fs.unlinkSync(socketPath) } catch {}
+    try { fs.unlinkSync(PID_FILE) }    catch {}
+    logger.info('mcp_daemon.stopped')
+    process.exit(0)
+  }
+
+  process.on('SIGTERM', () => { void shutdown('SIGTERM') })
+  process.on('SIGINT',  () => { void shutdown('SIGINT')  })
+}
+
+void main()

package/src/daemon/policyCache.ts

@@ -0,0 +1,143 @@
+/**
+ * Policy Cache — LRU in-memory + Valkey write-through
+ *
+ * Resolves PCAS permissions + active SOP rules for MCP daemon.
+ * Cache hit: < 0.1ms (LRU). Valkey hit: < 2ms. Miss: HTTP to control-plane.
+ *
+ * LLD #28: MCP Daemon Mode, WS-5MCP
+ * @module
+ */
+import https from 'node:https'
+import http from 'node:http'
+import { Redis } from 'ioredis'
+import { createLogger } from '@intutic/logger'
+
+const logger = createLogger('mcp-proxy.policyCache')
+
+const getPolicyTtlMs = () => parseInt(process.env['MCP_DAEMON_POLICY_TTL_MS'] ?? '300000', 10)
+const getMaxEntries = () => parseInt(process.env['MCP_DAEMON_MAX_CACHE_ENTRIES'] ?? '500',    10)
+const getCpUrl = () => process.env['CONTROL_PLANE_URL'] ?? 'http://localhost:3001'
+const getDaemonApiKey = () => process.env['INTUTIC_API_KEY']   ?? ''
+
+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 }, 'policyCache Valkey connection error')
+})
+
+export interface ResolvedPolicy {
+  workspaceId:   string
+  sopRules:      Record<string, unknown>[]
+  dlpPatterns:   string[]
+  interventionMode: string
+  cachedAt:      number
+}
+
+// Simple LRU map (insertion-order eviction)
+const lru = new Map<string, ResolvedPolicy>()
+
+function evictIfFull(): void {
+  if (lru.size >= getMaxEntries()) {
+    const firstKey = lru.keys().next().value as string
+    lru.delete(firstKey)
+  }
+}
+
+function isStale(entry: ResolvedPolicy): boolean {
+  return Date.now() - entry.cachedAt > getPolicyTtlMs()
+}
+
+async function fetchFromControlPlane(workspaceId: string): Promise<ResolvedPolicy | null> {
+  return new Promise((resolve) => {
+    const path = `/api/v1/policy/resolve?workspaceId=${encodeURIComponent(workspaceId)}`
+    const url  = new URL(path, getCpUrl())
+    const lib  = url.protocol === 'https:' ? https : http
+    const req  = lib.request(
+      { hostname: url.hostname, port: url.port, path: url.pathname + url.search, method: 'GET',
+        headers: { 'Authorization': `Bearer ${getDaemonApiKey()}`, 'Accept': 'application/json' } },
+      (res: any) => {
+        let data = ''
+        res.on('data', (c: string) => { data += c })
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(data) as Partial<ResolvedPolicy>
+            resolve({ workspaceId, sopRules: parsed.sopRules ?? [], dlpPatterns: parsed.dlpPatterns ?? [],
+              interventionMode: parsed.interventionMode ?? 'BYPASS', cachedAt: Date.now() })
+          } catch { resolve(null) }
+        })
+      }
+    )
+    req.on('error', () => resolve(null))
+    req.setTimeout(5000, () => { req.destroy(); resolve(null) })
+    req.end()
+  })
+}
+
+/**
+ * Resolves policy for a workspace.
+ * Order: LRU (fresh) → LRU (stale, triggers async refresh) → Valkey → HTTP fetch
+ */
+export async function resolvePolicy(workspaceId: string): Promise<ResolvedPolicy | null> {
+  const cached = lru.get(workspaceId)
+
+  if (cached && !isStale(cached)) {
+    // Touch for LRU recency
+    lru.delete(workspaceId)
+    lru.set(workspaceId, cached)
+    return cached
+  }
+
+  if (cached && isStale(cached)) {
+    // Return stale, trigger async refresh
+    void fetchFromControlPlane(workspaceId).then(async (fresh) => {
+      if (fresh) {
+        lru.delete(workspaceId)
+        evictIfFull()
+        lru.set(workspaceId, fresh)
+        try {
+          await valkey.set(`mcp_daemon:policy:${workspaceId}`, JSON.stringify(fresh), 'PX', getPolicyTtlMs())
+        } catch {}
+      }
+    })
+    return cached
+  }
+
+  // Cache miss in LRU — check Valkey
+  try {
+    const valkeyCached = await valkey.get(`mcp_daemon:policy:${workspaceId}`)
+    if (valkeyCached) {
+      const parsed = JSON.parse(valkeyCached) as ResolvedPolicy
+      evictIfFull()
+      lru.set(workspaceId, parsed)
+      return parsed
+    }
+  } catch {}
+
+  // Cache miss in Valkey too — fetch synchronously
+  logger.debug({ workspaceId }, 'policy_cache.miss')
+  const fresh = await fetchFromControlPlane(workspaceId)
+  if (fresh) {
+    evictIfFull()
+    lru.set(workspaceId, fresh)
+    try {
+      await valkey.set(`mcp_daemon:policy:${workspaceId}`, JSON.stringify(fresh), 'PX', getPolicyTtlMs())
+    } catch {}
+  }
+  return fresh
+}
+
+/** Invalidates policy cache for a workspace (called on SOP update). */
+export function invalidatePolicy(workspaceId: string): void {
+  lru.delete(workspaceId)
+  valkey.del(`mcp_daemon:policy:${workspaceId}`, `mcp_daemon:sop_rules:${workspaceId}`).catch(() => {})
+  logger.info({ workspaceId }, 'policy_cache.invalidated')
+}
+
+/** Returns cache statistics. */
+export function getCacheStats(): { entries: number; hitRate: number } {
+  return { entries: lru.size, hitRate: 0 } // hit rate tracked by metrics in production
+}