sovr-mcp-proxy 6.0.1 → 7.0.0

package/dist/cli.mjs

@@ -9,6 +9,10 @@ async function main(args) {
       await initCli(args.slice(1));
       return;
     }
+    case "hooks": {
+      await hooksCli(args.slice(1));
+      return;
+    }
     case "keys": {
       const { keysCli } = await import("./apiKeyManager.mjs");
       await keysCli(args.slice(1));
@@ -52,15 +56,151 @@ async function main(args) {
     }
   }
 }
+async function hooksCli(args) {
+  const { installHooks, uninstallHooks, detectClaudeCode, generateHooksConfig } = await import("./hooksAdapter.mjs");
+  const subcommand = args[0] || "install";
+  let failMode = "open";
+  let sovrEndpoint = "http://localhost:3271";
+  let projectDir = process.cwd();
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === "--fail-closed") failMode = "closed";
+    if (args[i] === "--fail-open") failMode = "open";
+    if (args[i] === "--endpoint" && args[i + 1]) sovrEndpoint = args[++i];
+    if (args[i] === "--dir" && args[i + 1]) projectDir = args[++i];
+  }
+  const config = {
+    endpoint: sovrEndpoint,
+    failMode,
+    toolPatterns: ["Bash", "Write", "Edit", "MultiEdit", "NotebookEdit"],
+    addAuditHook: true
+  };
+  switch (subcommand) {
+    case "install": {
+      const hooksConfig = generateHooksConfig(config);
+      const { generateHookScript, generateAuditHookScript } = await import("./hooksAdapter.mjs");
+      const preToolScript = generateHookScript(config);
+      const postToolScript = config.addAuditHook ? generateAuditHookScript(config) : null;
+      const fs = await import("fs");
+      const path = await import("path");
+      const settingsDir = path.join(projectDir, ".claude");
+      const settingsFile = path.join(settingsDir, "settings.json");
+      if (!fs.existsSync(settingsDir)) {
+        fs.mkdirSync(settingsDir, { recursive: true });
+      }
+      let existingSettings = {};
+      if (fs.existsSync(settingsFile)) {
+        try {
+          existingSettings = JSON.parse(fs.readFileSync(settingsFile, "utf-8"));
+        } catch {
+        }
+      }
+      const newSettings = {
+        ...existingSettings,
+        hooks: hooksConfig
+      };
+      fs.writeFileSync(settingsFile, JSON.stringify(newSettings, null, 2));
+      const scriptsDir = path.join(settingsDir, "hooks");
+      if (!fs.existsSync(scriptsDir)) {
+        fs.mkdirSync(scriptsDir, { recursive: true });
+      }
+      fs.writeFileSync(
+        path.join(scriptsDir, "sovr-pre-tool.sh"),
+        preToolScript,
+        { mode: 493 }
+      );
+      if (postToolScript) {
+        fs.writeFileSync(
+          path.join(scriptsDir, "sovr-post-tool.sh"),
+          postToolScript,
+          { mode: 493 }
+        );
+      }
+      process.stderr.write(`
+\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+\u2551          SOVR Claude Code Hooks Installed                    \u2551
+\u2560\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2563
+\u2551                                                              \u2551
+\u2551  Settings:  ${settingsFile.padEnd(47)}\u2551
+\u2551  Scripts:   ${scriptsDir.padEnd(47)}\u2551
+\u2551  Fail mode: ${failMode.padEnd(47)}\u2551
+\u2551  Endpoint:  ${sovrEndpoint.padEnd(47)}\u2551
+\u2551                                                              \u2551
+\u2551  Every Bash/Write/Edit call will now pass through SOVR.      \u2551
+\u2551  Use 'sovr-mcp-proxy hooks status' to verify.                \u2551
+\u2551                                                              \u2551
+\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
+`);
+      break;
+    }
+    case "uninstall": {
+      const fs = await import("fs");
+      const path = await import("path");
+      const settingsFile = path.join(projectDir, ".claude", "settings.json");
+      if (fs.existsSync(settingsFile)) {
+        try {
+          const settings = JSON.parse(fs.readFileSync(settingsFile, "utf-8"));
+          delete settings.hooks;
+          fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2));
+          process.stderr.write("[SOVR] Hooks removed from .claude/settings.json\n");
+        } catch (err) {
+          process.stderr.write(`[SOVR] Error removing hooks: ${err.message}
+`);
+        }
+      }
+      const scriptsDir = path.join(projectDir, ".claude", "hooks");
+      for (const f of ["sovr-pre-tool.sh", "sovr-post-tool.sh"]) {
+        const fp = path.join(scriptsDir, f);
+        if (fs.existsSync(fp)) fs.unlinkSync(fp);
+      }
+      process.stderr.write("[SOVR] Hooks uninstalled successfully.\n");
+      break;
+    }
+    case "status": {
+      const fs = await import("fs");
+      const path = await import("path");
+      const settingsFile = path.join(projectDir, ".claude", "settings.json");
+      if (!fs.existsSync(settingsFile)) {
+        process.stderr.write("[SOVR] No .claude/settings.json found. Hooks not installed.\n");
+        return;
+      }
+      try {
+        const settings = JSON.parse(fs.readFileSync(settingsFile, "utf-8"));
+        if (settings.hooks) {
+          const preHooks = settings.hooks.PreToolUse || [];
+          const postHooks = settings.hooks.PostToolUse || [];
+          process.stderr.write(`[SOVR] Hooks Status:
+`);
+          process.stderr.write(`  PreToolUse hooks:  ${preHooks.length}
+`);
+          process.stderr.write(`  PostToolUse hooks: ${postHooks.length}
+`);
+          process.stderr.write(`  Settings file:     ${settingsFile}
+`);
+        } else {
+          process.stderr.write("[SOVR] No hooks configured in settings.json\n");
+        }
+      } catch (err) {
+        process.stderr.write(`[SOVR] Error reading settings: ${err.message}
+`);
+      }
+      break;
+    }
+    default:
+      process.stderr.write(`Unknown hooks subcommand: ${subcommand}
+Usage: sovr-mcp-proxy hooks [install|uninstall|status]
+`);
+  }
+}
 function printHelp() {
   process.stderr.write(`
-sovr-mcp-proxy \u2014 The Responsibility Layer for AI Agents
+sovr-mcp-proxy v7.0.0 \u2014 The Responsibility Layer for AI Agents
 
 USAGE:
   sovr-mcp-proxy [COMMAND] [OPTIONS]
 
 COMMANDS:
   init              One-command setup for AI coding platforms
+  hooks             Install/manage Claude Code Hooks (PreToolUse)
   keys              Manage SOVR API keys
   usage             View usage statistics
   daemon            Manage persistent background daemon
@@ -68,10 +208,25 @@ COMMANDS:
 
 PROXY OPTIONS (default mode):
   --upstream, -u    Downstream MCP server command to wrap
+  --mode, -m        Security mode: exclusive|enforce|advisory|monitor
+                      exclusive  \u2014 Replace all native tools (strongest)
+                      enforce    \u2014 Intercept + block violations (default)
+                      advisory   \u2014 Warn but don't block
+                      monitor    \u2014 Silent audit only
+  --whitelist, -w   Whitelist preset or path: readonly|developer|production|<file>
   --rules, -r       Path to custom policy rules file
   --timeout, -t     Startup timeout in ms (default: 30000)
   --verbose, -v     Verbose output
 
+HOOKS OPTIONS:
+  install           Install Claude Code PreToolUse hooks (default)
+  uninstall         Remove SOVR hooks from .claude/settings.json
+  status            Show current hooks configuration
+  --fail-closed     Block on SOVR unreachable (default: fail-open)
+  --fail-open       Allow on SOVR unreachable
+  --endpoint URL    SOVR daemon endpoint (default: http://localhost:3271)
+  --dir PATH        Project directory (default: cwd)
+
 INIT OPTIONS:
   --claude-code     Configure Claude Code
   --claude-desktop  Configure Claude Desktop
@@ -100,31 +255,43 @@ DAEMON OPTIONS:
   --foreground      Run in foreground (for debugging)
   --verbose         Verbose logging
 
-EXAMPLES:
-  # One-command setup (auto-detect platforms)
-  npx sovr-mcp-proxy init
+SECURITY MODES:
+  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+  \u2502 exclusive   \u2502 SOVR replaces native Bash/Shell tools.           \u2502
+  \u2502             \u2502 LLM can ONLY execute through sovr_exec.          \u2502
+  \u2502             \u2502 Bypass is architecturally impossible.             \u2502
+  \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+  \u2502 enforce     \u2502 Native tools preserved but all calls intercepted.\u2502
+  \u2502             \u2502 Violations are blocked with error response.       \u2502
+  \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+  \u2502 advisory    \u2502 Violations trigger warnings in stderr.            \u2502
+  \u2502             \u2502 Calls are still forwarded to upstream.            \u2502
+  \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+  \u2502 monitor     \u2502 Silent audit logging only.                        \u2502
+  \u2502             \u2502 No warnings, no blocking.                         \u2502
+  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
 
-  # Setup for Cursor with API key
-  npx sovr-mcp-proxy init --cursor --api-key sovr_sk_abc123
+WHITELIST PRESETS:
+  readonly    \u2014 git status/log/diff, ls, cat, find, grep (read-only ops)
+  developer   \u2014 readonly + git add/commit/push, npm/pnpm, tsc, eslint
+  production  \u2014 developer + docker, kubectl, terraform (with restrictions)
 
-  # Start proxy wrapping another MCP server
-  npx sovr-mcp-proxy --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp"
+EXAMPLES:
+  # Maximum security: exclusive mode + readonly whitelist
+  npx sovr-mcp-proxy --upstream "npx @mcp/server-fs /tmp" --mode=exclusive --whitelist=readonly
 
-  # Check usage
-  npx sovr-mcp-proxy usage
+  # Developer workflow: enforce mode + developer whitelist
+  npx sovr-mcp-proxy --upstream "npx @mcp/server-fs ." --mode=enforce --whitelist=developer
 
-  # Manage keys
-  npx sovr-mcp-proxy keys add sovr_sk_abc123
+  # Install Claude Code hooks (no upstream needed)
+  npx sovr-mcp-proxy hooks install --fail-closed
 
-  # Start daemon (eliminates cold-start overhead)
-  npx sovr-mcp-proxy daemon start
+  # One-command setup (auto-detect platforms)
+  npx sovr-mcp-proxy init
 
-  # Start daemon with fail-closed mode
+  # Start daemon with fail-closed
   npx sovr-mcp-proxy daemon start --fail-closed
 
-  # Check daemon status
-  npx sovr-mcp-proxy daemon status
-
 ENVIRONMENT:
   SOVR_API_KEY      API key for authentication
   SOVR_ENDPOINT     Custom SOVR endpoint URL

package/dist/commandNormalizer.d.mts

@@ -0,0 +1,95 @@
+/**
+ * @sovr/proxy-mcp — Command Normalizer
+ *
+ * Solves the Reddit feedback:
+ *   "If you ban `rm`, I can just `bash -c 'rm -rf /'`" — coloradical5280
+ *   "find / -delete, TRUNCATE TABLE, etc." — multiple users
+ *
+ * The normalizer decomposes complex commands into atomic operations
+ * that can each be individually evaluated against the whitelist.
+ *
+ * Key capabilities:
+ *   1. Unwrap shell wrappers: bash -c, sh -c, env, xargs, etc.
+ *   2. Split pipe chains: cmd1 | cmd2 | cmd3 → [cmd1, cmd2, cmd3]
+ *   3. Split command chains: cmd1 && cmd2; cmd3 → [cmd1, cmd2, cmd3]
+ *   4. Detect encoding tricks: base64 -d, hex encoding, etc.
+ *   5. Detect alias/function tricks: alias rm='rm -rf'
+ *   6. Extract the "effective command" from each segment
+ *
+ * Every segment must pass the whitelist independently.
+ * If ANY segment fails, the entire command is blocked.
+ *
+ * @example
+ * ```
+ * normalize('bash -c "rm -rf /tmp && echo done"')
+ * → [
+ *     { raw: 'bash -c "rm -rf /tmp && echo done"', effective: 'rm -rf /tmp', type: 'unwrapped' },
+ *     { raw: 'bash -c "rm -rf /tmp && echo done"', effective: 'echo done', type: 'chain-segment' },
+ *   ]
+ * ```
+ */
+/** A normalized command segment */
+interface NormalizedSegment {
+    /** The original raw command (or the segment of it) */
+    raw: string;
+    /** The effective command after normalization */
+    effective: string;
+    /** How this segment was derived */
+    type: 'direct' | 'unwrapped' | 'pipe-segment' | 'chain-segment' | 'subshell' | 'heredoc' | 'encoded';
+    /** Warning flags */
+    warnings: string[];
+}
+/** Result of normalization */
+interface NormalizationResult {
+    /** All command segments that need individual evaluation */
+    segments: NormalizedSegment[];
+    /** Whether the command structure itself is suspicious */
+    suspicious: boolean;
+    /** Reasons for suspicion */
+    suspicion_reasons: string[];
+    /** The original command */
+    original: string;
+}
+/**
+ * Normalize a command into atomic segments for individual evaluation.
+ *
+ * This is the main entry point. It:
+ * 1. Splits command chains (&&, ||, ;)
+ * 2. Splits pipe chains (|)
+ * 3. Unwraps shell wrappers (bash -c, sudo, env, etc.)
+ * 4. Detects encoding tricks
+ * 5. Detects destructive equivalents
+ *
+ * Returns all segments that need to be individually evaluated.
+ */
+declare function normalize(command: string): NormalizationResult;
+/**
+ * Get the base command name (first word) from a command string.
+ */
+declare function getBaseCommand(command: string): string;
+/**
+ * Check if a command contains any destructive equivalent patterns.
+ */
+declare function hasDestructiveEquivalent(command: string): {
+    found: boolean;
+    matches: Array<{
+        equivalent: string;
+        description: string;
+    }>;
+};
+/**
+ * Check if a command uses any encoding/obfuscation tricks.
+ */
+declare function hasEncodingTricks(command: string): {
+    found: boolean;
+    tricks: Array<{
+        name: string;
+        risk: string;
+    }>;
+};
+/**
+ * Summarize normalization result in a human-readable format.
+ */
+declare function summarize(result: NormalizationResult): string;
+
+export { type NormalizationResult, type NormalizedSegment, getBaseCommand, hasDestructiveEquivalent, hasEncodingTricks, normalize, summarize };

package/dist/commandNormalizer.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @sovr/proxy-mcp — Command Normalizer
+ *
+ * Solves the Reddit feedback:
+ *   "If you ban `rm`, I can just `bash -c 'rm -rf /'`" — coloradical5280
+ *   "find / -delete, TRUNCATE TABLE, etc." — multiple users
+ *
+ * The normalizer decomposes complex commands into atomic operations
+ * that can each be individually evaluated against the whitelist.
+ *
+ * Key capabilities:
+ *   1. Unwrap shell wrappers: bash -c, sh -c, env, xargs, etc.
+ *   2. Split pipe chains: cmd1 | cmd2 | cmd3 → [cmd1, cmd2, cmd3]
+ *   3. Split command chains: cmd1 && cmd2; cmd3 → [cmd1, cmd2, cmd3]
+ *   4. Detect encoding tricks: base64 -d, hex encoding, etc.
+ *   5. Detect alias/function tricks: alias rm='rm -rf'
+ *   6. Extract the "effective command" from each segment
+ *
+ * Every segment must pass the whitelist independently.
+ * If ANY segment fails, the entire command is blocked.
+ *
+ * @example
+ * ```
+ * normalize('bash -c "rm -rf /tmp && echo done"')
+ * → [
+ *     { raw: 'bash -c "rm -rf /tmp && echo done"', effective: 'rm -rf /tmp', type: 'unwrapped' },
+ *     { raw: 'bash -c "rm -rf /tmp && echo done"', effective: 'echo done', type: 'chain-segment' },
+ *   ]
+ * ```
+ */
+/** A normalized command segment */
+interface NormalizedSegment {
+    /** The original raw command (or the segment of it) */
+    raw: string;
+    /** The effective command after normalization */
+    effective: string;
+    /** How this segment was derived */
+    type: 'direct' | 'unwrapped' | 'pipe-segment' | 'chain-segment' | 'subshell' | 'heredoc' | 'encoded';
+    /** Warning flags */
+    warnings: string[];
+}
+/** Result of normalization */
+interface NormalizationResult {
+    /** All command segments that need individual evaluation */
+    segments: NormalizedSegment[];
+    /** Whether the command structure itself is suspicious */
+    suspicious: boolean;
+    /** Reasons for suspicion */
+    suspicion_reasons: string[];
+    /** The original command */
+    original: string;
+}
+/**
+ * Normalize a command into atomic segments for individual evaluation.
+ *
+ * This is the main entry point. It:
+ * 1. Splits command chains (&&, ||, ;)
+ * 2. Splits pipe chains (|)
+ * 3. Unwraps shell wrappers (bash -c, sudo, env, etc.)
+ * 4. Detects encoding tricks
+ * 5. Detects destructive equivalents
+ *
+ * Returns all segments that need to be individually evaluated.
+ */
+declare function normalize(command: string): NormalizationResult;
+/**
+ * Get the base command name (first word) from a command string.
+ */
+declare function getBaseCommand(command: string): string;
+/**
+ * Check if a command contains any destructive equivalent patterns.
+ */
+declare function hasDestructiveEquivalent(command: string): {
+    found: boolean;
+    matches: Array<{
+        equivalent: string;
+        description: string;
+    }>;
+};
+/**
+ * Check if a command uses any encoding/obfuscation tricks.
+ */
+declare function hasEncodingTricks(command: string): {
+    found: boolean;
+    tricks: Array<{
+        name: string;
+        risk: string;
+    }>;
+};
+/**
+ * Summarize normalization result in a human-readable format.
+ */
+declare function summarize(result: NormalizationResult): string;
+
+export { type NormalizationResult, type NormalizedSegment, getBaseCommand, hasDestructiveEquivalent, hasEncodingTricks, normalize, summarize };