sovr-mcp-proxy 6.0.1 → 7.0.0

package/dist/hooksAdapter.d.mts

@@ -0,0 +1,122 @@
+/**
+ * @sovr/proxy-mcp — Claude Code Hooks Adapter
+ *
+ * Solves the bypass problem for Claude Code users specifically.
+ * Claude Code supports "Hooks" — scripts that run before/after tool use.
+ * PreToolUse hooks can BLOCK tool calls before they execute.
+ *
+ * This adapter generates the correct hooks configuration for Claude Code
+ * that routes ALL tool calls through SOVR for policy evaluation.
+ *
+ * Unlike the MCP proxy approach, hooks are ENFORCED by Claude Code itself —
+ * the LLM cannot bypass them because they run at the platform level.
+ *
+ * Integration:
+ *   npx sovr-mcp-proxy init --claude-code
+ *   → Writes hooks config to ~/.claude/settings.json
+ *   → Installs sovr-hook.sh as the PreToolUse handler
+ *
+ * Hook flow:
+ *   1. LLM decides to call a tool (e.g., Bash with "rm -rf /")
+ *   2. Claude Code triggers PreToolUse hook BEFORE execution
+ *   3. sovr-hook.sh calls SOVR daemon/API for policy evaluation
+ *   4. Hook exits 0 (allow) or 2 (block) based on SOVR decision
+ *   5. Claude Code either proceeds or blocks the tool call
+ *
+ * Exit codes (Claude Code hook spec):
+ *   0 = Allow (proceed with tool call)
+ *   2 = Block (reject tool call, show reason to user)
+ *   Other = Error (Claude Code decides based on its own policy)
+ *
+ * @see https://docs.anthropic.com/en/docs/claude-code/hooks
+ */
+/** Claude Code hook event types */
+type HookEvent = 'PreToolUse' | 'PostToolUse' | 'Notification' | 'Stop' | 'SubagentStop';
+/** A single hook matcher */
+interface HookMatcher {
+    /** Tool name pattern (regex supported) */
+    tool_name?: string;
+    /** Notification type pattern */
+    type?: string;
+}
+/** A single hook definition */
+interface HookDef {
+    /** Matchers that determine when this hook fires */
+    matcher: HookMatcher;
+    /** Array of hook commands to execute */
+    hooks: Array<{
+        /** The command to run */
+        command: string;
+        /** Timeout in seconds */
+        timeout?: number;
+    }>;
+}
+/** Claude Code settings.json structure (partial) */
+interface ClaudeCodeSettings {
+    hooks?: Record<HookEvent, HookDef[]>;
+    [key: string]: unknown;
+}
+/** Configuration for the hooks adapter */
+interface HooksAdapterConfig {
+    /** SOVR API key */
+    apiKey?: string;
+    /** SOVR endpoint (default: daemon socket) */
+    endpoint?: string;
+    /** Fail mode: 'open' allows on error, 'closed' blocks on error */
+    failMode?: 'open' | 'closed';
+    /** Tools to intercept (regex patterns) */
+    toolPatterns?: string[];
+    /** Timeout for hook execution in seconds */
+    hookTimeout?: number;
+    /** Path to Claude Code settings (auto-detected if not provided) */
+    settingsPath?: string;
+    /** Whether to also add PostToolUse audit hook */
+    addAuditHook?: boolean;
+}
+/**
+ * Generate the sovr-hook.sh script content.
+ * This script is called by Claude Code for every PreToolUse event.
+ *
+ * It reads the hook input from stdin (JSON with tool_name, tool_input),
+ * calls SOVR for evaluation, and exits with the appropriate code.
+ */
+declare function generateHookScript(config: HooksAdapterConfig): string;
+/**
+ * Generate the PostToolUse audit hook script.
+ * This records what happened after a tool call completes.
+ */
+declare function generateAuditHookScript(config: HooksAdapterConfig): string;
+/**
+ * Generate the Claude Code hooks configuration object.
+ */
+declare function generateHooksConfig(config: HooksAdapterConfig): Record<HookEvent, HookDef[]>;
+/**
+ * Install SOVR hooks into Claude Code settings.
+ * Merges with existing settings, preserving non-SOVR hooks.
+ */
+declare function installHooks(config: HooksAdapterConfig): {
+    settingsPath: string;
+    hookScriptPath: string;
+    auditScriptPath?: string;
+    installed: boolean;
+    backup?: string;
+};
+/**
+ * Remove SOVR hooks from Claude Code settings.
+ */
+declare function uninstallHooks(config?: {
+    settingsPath?: string;
+}): {
+    removed: boolean;
+    settingsPath: string;
+};
+/**
+ * Detect installed Claude Code and return its settings path.
+ */
+declare function detectClaudeCode(): {
+    found: boolean;
+    settingsPath?: string;
+    version?: string;
+};
+
+export { type ClaudeCodeSettings, type HookDef, type HookEvent, type HookMatcher, type HooksAdapterConfig, detectClaudeCode, generateAuditHookScript, generateHookScript, generateHooksConfig, installHooks, uninstallHooks };

package/dist/hooksAdapter.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @sovr/proxy-mcp — Claude Code Hooks Adapter
+ *
+ * Solves the bypass problem for Claude Code users specifically.
+ * Claude Code supports "Hooks" — scripts that run before/after tool use.
+ * PreToolUse hooks can BLOCK tool calls before they execute.
+ *
+ * This adapter generates the correct hooks configuration for Claude Code
+ * that routes ALL tool calls through SOVR for policy evaluation.
+ *
+ * Unlike the MCP proxy approach, hooks are ENFORCED by Claude Code itself —
+ * the LLM cannot bypass them because they run at the platform level.
+ *
+ * Integration:
+ *   npx sovr-mcp-proxy init --claude-code
+ *   → Writes hooks config to ~/.claude/settings.json
+ *   → Installs sovr-hook.sh as the PreToolUse handler
+ *
+ * Hook flow:
+ *   1. LLM decides to call a tool (e.g., Bash with "rm -rf /")
+ *   2. Claude Code triggers PreToolUse hook BEFORE execution
+ *   3. sovr-hook.sh calls SOVR daemon/API for policy evaluation
+ *   4. Hook exits 0 (allow) or 2 (block) based on SOVR decision
+ *   5. Claude Code either proceeds or blocks the tool call
+ *
+ * Exit codes (Claude Code hook spec):
+ *   0 = Allow (proceed with tool call)
+ *   2 = Block (reject tool call, show reason to user)
+ *   Other = Error (Claude Code decides based on its own policy)
+ *
+ * @see https://docs.anthropic.com/en/docs/claude-code/hooks
+ */
+/** Claude Code hook event types */
+type HookEvent = 'PreToolUse' | 'PostToolUse' | 'Notification' | 'Stop' | 'SubagentStop';
+/** A single hook matcher */
+interface HookMatcher {
+    /** Tool name pattern (regex supported) */
+    tool_name?: string;
+    /** Notification type pattern */
+    type?: string;
+}
+/** A single hook definition */
+interface HookDef {
+    /** Matchers that determine when this hook fires */
+    matcher: HookMatcher;
+    /** Array of hook commands to execute */
+    hooks: Array<{
+        /** The command to run */
+        command: string;
+        /** Timeout in seconds */
+        timeout?: number;
+    }>;
+}
+/** Claude Code settings.json structure (partial) */
+interface ClaudeCodeSettings {
+    hooks?: Record<HookEvent, HookDef[]>;
+    [key: string]: unknown;
+}
+/** Configuration for the hooks adapter */
+interface HooksAdapterConfig {
+    /** SOVR API key */
+    apiKey?: string;
+    /** SOVR endpoint (default: daemon socket) */
+    endpoint?: string;
+    /** Fail mode: 'open' allows on error, 'closed' blocks on error */
+    failMode?: 'open' | 'closed';
+    /** Tools to intercept (regex patterns) */
+    toolPatterns?: string[];
+    /** Timeout for hook execution in seconds */
+    hookTimeout?: number;
+    /** Path to Claude Code settings (auto-detected if not provided) */
+    settingsPath?: string;
+    /** Whether to also add PostToolUse audit hook */
+    addAuditHook?: boolean;
+}
+/**
+ * Generate the sovr-hook.sh script content.
+ * This script is called by Claude Code for every PreToolUse event.
+ *
+ * It reads the hook input from stdin (JSON with tool_name, tool_input),
+ * calls SOVR for evaluation, and exits with the appropriate code.
+ */
+declare function generateHookScript(config: HooksAdapterConfig): string;
+/**
+ * Generate the PostToolUse audit hook script.
+ * This records what happened after a tool call completes.
+ */
+declare function generateAuditHookScript(config: HooksAdapterConfig): string;
+/**
+ * Generate the Claude Code hooks configuration object.
+ */
+declare function generateHooksConfig(config: HooksAdapterConfig): Record<HookEvent, HookDef[]>;
+/**
+ * Install SOVR hooks into Claude Code settings.
+ * Merges with existing settings, preserving non-SOVR hooks.
+ */
+declare function installHooks(config: HooksAdapterConfig): {
+    settingsPath: string;
+    hookScriptPath: string;
+    auditScriptPath?: string;
+    installed: boolean;
+    backup?: string;
+};
+/**
+ * Remove SOVR hooks from Claude Code settings.
+ */
+declare function uninstallHooks(config?: {
+    settingsPath?: string;
+}): {
+    removed: boolean;
+    settingsPath: string;
+};
+/**
+ * Detect installed Claude Code and return its settings path.
+ */
+declare function detectClaudeCode(): {
+    found: boolean;
+    settingsPath?: string;
+    version?: string;
+};
+
+export { type ClaudeCodeSettings, type HookDef, type HookEvent, type HookMatcher, type HooksAdapterConfig, detectClaudeCode, generateAuditHookScript, generateHookScript, generateHooksConfig, installHooks, uninstallHooks };

package/dist/hooksAdapter.js

@@ -0,0 +1,321 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/hooksAdapter.ts
+var hooksAdapter_exports = {};
+__export(hooksAdapter_exports, {
+  detectClaudeCode: () => detectClaudeCode,
+  generateAuditHookScript: () => generateAuditHookScript,
+  generateHookScript: () => generateHookScript,
+  generateHooksConfig: () => generateHooksConfig,
+  installHooks: () => installHooks,
+  uninstallHooks: () => uninstallHooks
+});
+module.exports = __toCommonJS(hooksAdapter_exports);
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_os = require("os");
+var DEFAULT_TOOL_PATTERNS = [
+  "Bash",
+  "bash",
+  "shell",
+  "execute_command",
+  "Write",
+  // File write operations
+  "Edit",
+  // File edit operations
+  "MultiEdit"
+  // Multi-file edit operations
+];
+var DEFAULT_HOOK_TIMEOUT = 10;
+function generateHookScript(config) {
+  const failExit = config.failMode === "closed" ? 2 : 0;
+  const endpoint = config.endpoint || "http://localhost:45557";
+  const apiKeyRef = config.apiKey ? `"${config.apiKey}"` : '"${SOVR_API_KEY:-}"';
+  return `#!/bin/bash
+# SOVR PreToolUse Hook for Claude Code
+# Generated by: npx sovr-mcp-proxy init --claude-code
+# 
+# This hook intercepts ALL tool calls and evaluates them against
+# SOVR security policies BEFORE Claude Code executes them.
+#
+# Exit codes:
+#   0 = ALLOW (proceed with tool call)
+#   2 = BLOCK (reject tool call)
+#
+# Environment:
+#   SOVR_API_KEY     \u2014 API key for SOVR authentication
+#   SOVR_ENDPOINT    \u2014 SOVR daemon endpoint (default: ${endpoint})
+#   SOVR_FAIL_MODE   \u2014 'open' (default) or 'closed'
+#   SOVR_HOOK_DEBUG  \u2014 Set to '1' for debug logging
+
+set -euo pipefail
+
+# Configuration
+SOVR_ENDPOINT="\${SOVR_ENDPOINT:-${endpoint}}"
+SOVR_API_KEY=${apiKeyRef}
+SOVR_FAIL_MODE="\${SOVR_FAIL_MODE:-${config.failMode || "open"}}"
+SOVR_HOOK_DEBUG="\${SOVR_HOOK_DEBUG:-0}"
+FAIL_EXIT=${failExit}
+
+# Debug logging
+debug() {
+  if [ "$SOVR_HOOK_DEBUG" = "1" ]; then
+    echo "[SOVR-HOOK $(date -u +%H:%M:%S)] $*" >&2
+  fi
+}
+
+# Read hook input from stdin
+INPUT=$(cat)
+debug "Input: $INPUT"
+
+# Extract tool name and input from JSON
+TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4 2>/dev/null || echo "unknown")
+TOOL_INPUT=$(echo "$INPUT" | grep -o '"tool_input":{[^}]*}' | head -1 2>/dev/null || echo "{}")
+
+debug "Tool: $TOOL_NAME"
+
+# Skip non-dangerous tools (read-only operations)
+case "$TOOL_NAME" in
+  Read|View|LS|Glob|Grep|TodoRead|WebFetch|WebSearch)
+    debug "SKIP: Read-only tool $TOOL_NAME"
+    exit 0
+    ;;
+esac
+
+# Extract command for Bash tools
+COMMAND=""
+case "$TOOL_NAME" in
+  Bash|bash|shell|execute_command)
+    COMMAND=$(echo "$TOOL_INPUT" | grep -o '"command":"[^"]*"' | head -1 | cut -d'"' -f4 2>/dev/null || echo "")
+    ;;
+  Write|Edit|MultiEdit)
+    COMMAND=$(echo "$TOOL_INPUT" | grep -o '"file_path":"[^"]*"' | head -1 | cut -d'"' -f4 2>/dev/null || echo "")
+    ;;
+esac
+
+debug "Command: $COMMAND"
+
+# Call SOVR daemon for evaluation
+RESPONSE=$(curl -s -X POST "$SOVR_ENDPOINT/api/hook/evaluate" \\
+  -H "Content-Type: application/json" \\
+  -H "X-SOVR-API-Key: $SOVR_API_KEY" \\
+  -d "{
+    \\"tool_name\\": \\"$TOOL_NAME\\",
+    \\"command\\": $(echo "$COMMAND" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))' 2>/dev/null || echo '""'),
+    \\"channel\\": \\"hooks\\",
+    \\"context\\": {
+      \\"platform\\": \\"claude-code\\",
+      \\"hook_event\\": \\"PreToolUse\\"
+    }
+  }" \\
+  --connect-timeout 3 --max-time 5 2>/dev/null) || {
+  debug "SOVR daemon unreachable, fail-$SOVR_FAIL_MODE"
+  exit $FAIL_EXIT
+}
+
+debug "Response: $RESPONSE"
+
+# Parse verdict
+VERDICT=$(echo "$RESPONSE" | grep -o '"verdict":"[^"]*"' | head -1 | cut -d'"' -f4 2>/dev/null || echo "")
+REASON=$(echo "$RESPONSE" | grep -o '"reason":"[^"]*"' | head -1 | cut -d'"' -f4 2>/dev/null || echo "Policy evaluation failed")
+
+case "$VERDICT" in
+  allow)
+    debug "ALLOWED: $TOOL_NAME"
+    exit 0
+    ;;
+  deny)
+    debug "BLOCKED: $TOOL_NAME \u2014 $REASON"
+    # Output block reason as JSON for Claude Code to display
+    echo "{\\"error\\": \\"SOVR Policy Violation: $REASON\\"}"
+    exit 2
+    ;;
+  escalate)
+    debug "ESCALATED: $TOOL_NAME \u2014 requires approval"
+    echo "{\\"error\\": \\"SOVR: This action requires human approval. Reason: $REASON\\"}"
+    exit 2
+    ;;
+  *)
+    debug "UNKNOWN verdict: $VERDICT, fail-$SOVR_FAIL_MODE"
+    exit $FAIL_EXIT
+    ;;
+esac
+`;
+}
+function generateAuditHookScript(config) {
+  const endpoint = config.endpoint || "http://localhost:45557";
+  const apiKeyRef = config.apiKey ? `"${config.apiKey}"` : '"${SOVR_API_KEY:-}"';
+  return `#!/bin/bash
+# SOVR PostToolUse Audit Hook for Claude Code
+# Records tool execution results for audit trail
+set -euo pipefail
+
+SOVR_ENDPOINT="\${SOVR_ENDPOINT:-${endpoint}}"
+SOVR_API_KEY=${apiKeyRef}
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4 2>/dev/null || echo "unknown")
+
+# Fire-and-forget audit log
+curl -s -X POST "$SOVR_ENDPOINT/api/hook/audit" \\
+  -H "Content-Type: application/json" \\
+  -H "X-SOVR-API-Key: $SOVR_API_KEY" \\
+  -d "{
+    \\"tool_name\\": \\"$TOOL_NAME\\",
+    \\"event\\": \\"PostToolUse\\",
+    \\"timestamp\\": $(date +%s)000
+  }" \\
+  --connect-timeout 2 --max-time 3 2>/dev/null &
+
+# Always allow (audit is non-blocking)
+exit 0
+`;
+}
+function generateHooksConfig(config) {
+  const hookScriptPath = getHookScriptPath();
+  const timeout = config.hookTimeout || DEFAULT_HOOK_TIMEOUT;
+  const hooks = {
+    PreToolUse: []
+  };
+  const patterns = config.toolPatterns || DEFAULT_TOOL_PATTERNS;
+  for (const pattern of patterns) {
+    hooks.PreToolUse.push({
+      matcher: { tool_name: pattern },
+      hooks: [{ command: hookScriptPath, timeout }]
+    });
+  }
+  if (config.addAuditHook) {
+    const auditScriptPath = getAuditHookScriptPath();
+    hooks.PostToolUse = patterns.map((pattern) => ({
+      matcher: { tool_name: pattern },
+      hooks: [{ command: auditScriptPath, timeout: 5 }]
+    }));
+  }
+  return hooks;
+}
+function installHooks(config) {
+  const settingsPath = config.settingsPath || getDefaultSettingsPath();
+  const hookScriptPath = getHookScriptPath();
+  const auditScriptPath = config.addAuditHook ? getAuditHookScriptPath() : void 0;
+  const settingsDir = (0, import_node_path.dirname)(settingsPath);
+  const hooksDir = (0, import_node_path.dirname)(hookScriptPath);
+  (0, import_node_fs.mkdirSync)(settingsDir, { recursive: true });
+  (0, import_node_fs.mkdirSync)(hooksDir, { recursive: true });
+  (0, import_node_fs.writeFileSync)(hookScriptPath, generateHookScript(config), "utf-8");
+  (0, import_node_fs.chmodSync)(hookScriptPath, 493);
+  if (auditScriptPath) {
+    (0, import_node_fs.writeFileSync)(auditScriptPath, generateAuditHookScript(config), "utf-8");
+    (0, import_node_fs.chmodSync)(auditScriptPath, 493);
+  }
+  let existingSettings = {};
+  let backup;
+  if ((0, import_node_fs.existsSync)(settingsPath)) {
+    try {
+      const raw = (0, import_node_fs.readFileSync)(settingsPath, "utf-8");
+      existingSettings = JSON.parse(raw);
+      backup = `${settingsPath}.sovr-backup.${Date.now()}`;
+      (0, import_node_fs.writeFileSync)(backup, raw, "utf-8");
+    } catch {
+    }
+  }
+  const sovrHooks = generateHooksConfig(config);
+  const mergedHooks = {};
+  if (existingSettings.hooks) {
+    for (const [event, defs] of Object.entries(existingSettings.hooks)) {
+      mergedHooks[event] = defs.filter(
+        (d) => !d.hooks.some((h) => h.command.includes("sovr"))
+      );
+    }
+  }
+  for (const [event, defs] of Object.entries(sovrHooks)) {
+    if (!mergedHooks[event]) mergedHooks[event] = [];
+    mergedHooks[event].push(...defs);
+  }
+  const updatedSettings = {
+    ...existingSettings,
+    hooks: mergedHooks
+  };
+  (0, import_node_fs.writeFileSync)(settingsPath, JSON.stringify(updatedSettings, null, 2), "utf-8");
+  return {
+    settingsPath,
+    hookScriptPath,
+    auditScriptPath,
+    installed: true,
+    backup
+  };
+}
+function uninstallHooks(config) {
+  const settingsPath = config?.settingsPath || getDefaultSettingsPath();
+  if (!(0, import_node_fs.existsSync)(settingsPath)) {
+    return { removed: false, settingsPath };
+  }
+  try {
+    const raw = (0, import_node_fs.readFileSync)(settingsPath, "utf-8");
+    const settings = JSON.parse(raw);
+    if (settings.hooks) {
+      for (const [event, defs] of Object.entries(settings.hooks)) {
+        settings.hooks[event] = defs.filter(
+          (d) => !d.hooks.some((h) => h.command.includes("sovr"))
+        );
+      }
+    }
+    (0, import_node_fs.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2), "utf-8");
+    return { removed: true, settingsPath };
+  } catch {
+    return { removed: false, settingsPath };
+  }
+}
+function getDefaultSettingsPath() {
+  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".claude", "settings.json");
+}
+function getHookScriptPath() {
+  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".sovr", "hooks", "sovr-pretool-hook.sh");
+}
+function getAuditHookScriptPath() {
+  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".sovr", "hooks", "sovr-posttool-audit.sh");
+}
+function detectClaudeCode() {
+  const defaultPath = getDefaultSettingsPath();
+  if ((0, import_node_fs.existsSync)((0, import_node_path.dirname)(defaultPath))) {
+    return {
+      found: true,
+      settingsPath: defaultPath
+    };
+  }
+  const altPaths = [
+    (0, import_node_path.join)((0, import_node_os.homedir)(), ".config", "claude", "settings.json"),
+    (0, import_node_path.join)((0, import_node_os.homedir)(), "Library", "Application Support", "Claude", "settings.json")
+  ];
+  for (const p of altPaths) {
+    if ((0, import_node_fs.existsSync)((0, import_node_path.dirname)(p))) {
+      return { found: true, settingsPath: p };
+    }
+  }
+  return { found: false };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  detectClaudeCode,
+  generateAuditHookScript,
+  generateHookScript,
+  generateHooksConfig,
+  installHooks,
+  uninstallHooks
+});