sovr-mcp-proxy 6.0.1 → 7.0.0

package/dist/toolReplacement.mjs

@@ -0,0 +1,204 @@
+// src/toolReplacement.ts
+var DEFAULT_TARGET_TOOLS = [
+  // Claude Code native tools
+  "Bash",
+  "bash",
+  "shell",
+  "execute_command",
+  "run_command",
+  "terminal",
+  // Cursor / Windsurf / Continue
+  "run_terminal_command",
+  "execute_shell",
+  "shell_exec",
+  // Generic patterns
+  "exec",
+  "system",
+  "subprocess"
+];
+var SOVR_EXEC_TOOL = {
+  name: "sovr_exec",
+  description: "Execute a shell command through the SOVR Responsibility Layer. All commands are evaluated against security policies before execution. Dangerous commands (rm -rf, DROP TABLE, etc.) will be blocked. This is the ONLY way to execute commands \u2014 use this for ALL shell operations.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      command: {
+        type: "string",
+        description: "The shell command to execute. Will be policy-checked before running."
+      },
+      workdir: {
+        type: "string",
+        description: "Working directory for the command (optional)."
+      },
+      timeout: {
+        type: "number",
+        description: "Timeout in milliseconds (default: 300000 = 5 min)."
+      }
+    },
+    required: ["command"]
+  }
+};
+var SOVR_STATUS_TOOL = {
+  name: "sovr_status",
+  description: "Check the current SOVR security status, including active policies, recent decisions, and system health. Use this to understand what commands are allowed or blocked.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      verbose: {
+        type: "boolean",
+        description: "Include detailed policy information (default: false)."
+      }
+    }
+  }
+};
+var SOVR_AUDIT_TOOL = {
+  name: "sovr_audit",
+  description: "View the SOVR audit log of recent command evaluations. Shows what was allowed, blocked, or escalated.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      limit: {
+        type: "number",
+        description: "Number of recent entries to show (default: 10)."
+      },
+      filter: {
+        type: "string",
+        enum: ["all", "allowed", "blocked", "escalated"],
+        description: "Filter by decision type (default: all)."
+      }
+    }
+  }
+};
+var DEFAULT_TOOL_REPLACEMENT_CONFIG = {
+  mode: "enforce",
+  targetTools: DEFAULT_TARGET_TOOLS,
+  addStatusTool: true,
+  addAuditTool: true
+};
+function transformToolList(upstreamTools, config) {
+  const removedTools = [];
+  const addedTools = [];
+  const wrappedTools = [];
+  let resultTools = [];
+  switch (config.mode) {
+    case "exclusive": {
+      for (const tool of upstreamTools) {
+        if (isTargetTool(tool.name, config.targetTools)) {
+          removedTools.push(tool.name);
+        } else {
+          resultTools.push(tool);
+        }
+      }
+      resultTools.push(SOVR_EXEC_TOOL);
+      addedTools.push(SOVR_EXEC_TOOL.name);
+      break;
+    }
+    case "enforce": {
+      for (const tool of upstreamTools) {
+        if (isTargetTool(tool.name, config.targetTools)) {
+          resultTools.push({
+            ...tool,
+            description: `[SOVR-ENFORCED] ${tool.description || ""} \u2014 All calls are policy-checked by SOVR before execution.`
+          });
+          wrappedTools.push(tool.name);
+        } else {
+          resultTools.push(tool);
+        }
+      }
+      resultTools.push(SOVR_EXEC_TOOL);
+      addedTools.push(SOVR_EXEC_TOOL.name);
+      break;
+    }
+    case "advisory": {
+      resultTools = [...upstreamTools];
+      resultTools.push(SOVR_EXEC_TOOL);
+      addedTools.push(SOVR_EXEC_TOOL.name);
+      break;
+    }
+    case "monitor":
+    default: {
+      resultTools = [...upstreamTools];
+      break;
+    }
+  }
+  if (config.addStatusTool) {
+    resultTools.push(SOVR_STATUS_TOOL);
+    addedTools.push(SOVR_STATUS_TOOL.name);
+  }
+  if (config.addAuditTool) {
+    resultTools.push(SOVR_AUDIT_TOOL);
+    addedTools.push(SOVR_AUDIT_TOOL.name);
+  }
+  return { tools: resultTools, removedTools, addedTools, wrappedTools };
+}
+function isTargetTool(toolName, targets) {
+  const lowerName = toolName.toLowerCase();
+  return targets.some((target) => {
+    const lowerTarget = target.toLowerCase();
+    if (lowerName === lowerTarget) return true;
+    if (lowerTarget.includes("*")) {
+      const regex = new RegExp(
+        "^" + lowerTarget.replace(/\*/g, ".*").replace(/\?/g, ".") + "$"
+      );
+      return regex.test(lowerName);
+    }
+    return false;
+  });
+}
+function shouldIntercept(toolName, config) {
+  switch (config.mode) {
+    case "exclusive":
+      if (toolName === "sovr_exec") {
+        return { intercept: true, reason: "exclusive-mode: all exec calls routed through SOVR" };
+      }
+      if (isTargetTool(toolName, config.targetTools)) {
+        return { intercept: true, reason: "exclusive-mode: native tool blocked, use sovr_exec" };
+      }
+      return { intercept: false, reason: "non-exec tool, passthrough" };
+    case "enforce":
+      if (toolName === "sovr_exec" || isTargetTool(toolName, config.targetTools)) {
+        return { intercept: true, reason: "enforce-mode: policy check required" };
+      }
+      return { intercept: false, reason: "non-exec tool, passthrough" };
+    case "advisory":
+      if (toolName === "sovr_exec") {
+        return { intercept: true, reason: "advisory-mode: SOVR exec call" };
+      }
+      if (isTargetTool(toolName, config.targetTools)) {
+        return { intercept: false, reason: "advisory-mode: native tool allowed with warning" };
+      }
+      return { intercept: false, reason: "non-exec tool, passthrough" };
+    case "monitor":
+    default:
+      return { intercept: false, reason: "monitor-mode: all tools passthrough" };
+  }
+}
+function describeMode(config) {
+  switch (config.mode) {
+    case "exclusive":
+      return `EXCLUSIVE MODE: Native execution tools (${config.targetTools.join(", ")}) are REMOVED. The LLM can ONLY execute commands through sovr_exec. Bypass is impossible.`;
+    case "enforce":
+      return `ENFORCE MODE: Native execution tools are wrapped with SOVR policy checks. All command executions are evaluated before running. Dangerous commands are blocked.`;
+    case "advisory":
+      return `ADVISORY MODE: Native tools remain available. SOVR tools are added alongside. Warnings are logged for risky commands but execution is not blocked.`;
+    case "monitor":
+      return `MONITOR MODE: All tools pass through unchanged. SOVR only logs activity. No enforcement or blocking.`;
+  }
+}
+function parseMode(input) {
+  const normalized = input.toLowerCase().trim();
+  if (["exclusive", "enforce", "advisory", "monitor"].includes(normalized)) {
+    return normalized;
+  }
+  throw new Error(
+    `Invalid mode: "${input}". Valid modes: exclusive, enforce, advisory, monitor`
+  );
+}
+export {
+  DEFAULT_TARGET_TOOLS,
+  DEFAULT_TOOL_REPLACEMENT_CONFIG,
+  describeMode,
+  parseMode,
+  shouldIntercept,
+  transformToolList
+};

package/dist/whitelistEngine.d.mts

@@ -0,0 +1,167 @@
+/**
+ * @sovr/proxy-mcp — Whitelist Policy Engine
+ *
+ * Solves the critical Reddit feedback:
+ *   "A whitelist is much safer than a blacklist" — rvistro (9↑)
+ *   "If you ban that, I can just spin up a shell with -c" — coloradical5280 (2↑)
+ *
+ * Philosophy: DEFAULT DENY.
+ * Instead of trying to enumerate every dangerous command (impossible),
+ * we enumerate the SAFE commands and block everything else.
+ *
+ * The whitelist is project-scoped: each project declares what commands
+ * its AI agent needs, and SOVR enforces that boundary.
+ *
+ * Three policy modes:
+ *   - "whitelist"  — Only explicitly allowed commands can execute (recommended)
+ *   - "blacklist"  — Legacy mode, block known-dangerous patterns
+ *   - "hybrid"     — Whitelist + blacklist (whitelist takes priority)
+ *
+ * @example
+ * ```yaml
+ * # .sovr/policy.yaml
+ * version: "1.0"
+ * mode: whitelist
+ * rules:
+ *   - pattern: "ls *"
+ *     allow: true
+ *     description: "List directory contents"
+ *   - pattern: "cat *"
+ *     allow: true
+ *     description: "Read file contents"
+ *   - pattern: "npm run *"
+ *     allow: true
+ *     description: "Run npm scripts"
+ *   - pattern: "git status"
+ *     allow: true
+ *   - pattern: "git add *"
+ *     allow: true
+ *   - pattern: "git commit *"
+ *     allow: true
+ *   - pattern: "git push *"
+ *     allow: true
+ *     require_approval: true  # Human must approve pushes
+ * ```
+ */
+type PolicyMode = 'whitelist' | 'blacklist' | 'hybrid';
+/** A single whitelist/blacklist rule */
+interface WhitelistRule {
+    /** Glob-style pattern for the command (e.g., "ls *", "npm run *") */
+    pattern: string;
+    /** Whether this pattern is allowed (true) or blocked (false) */
+    allow: boolean;
+    /** Human-readable description */
+    description?: string;
+    /** Whether this command requires human approval even if allowed */
+    require_approval?: boolean;
+    /** Maximum arguments allowed (prevents injection via long args) */
+    max_args?: number;
+    /** Allowed working directories (glob patterns) */
+    allowed_dirs?: string[];
+    /** Priority (higher = evaluated first, default: 0) */
+    priority?: number;
+    /** Whether this rule is enabled */
+    enabled?: boolean;
+}
+/** Complete policy configuration */
+interface WhitelistPolicy {
+    /** Policy version */
+    version: string;
+    /** Policy mode */
+    mode: PolicyMode;
+    /** Policy rules */
+    rules: WhitelistRule[];
+    /** Default action when no rule matches (only for hybrid mode) */
+    default_action?: 'allow' | 'deny' | 'escalate';
+    /** Global settings */
+    settings?: {
+        /** Maximum command length in characters */
+        max_command_length?: number;
+        /** Whether to allow environment variable expansion */
+        allow_env_expansion?: boolean;
+        /** Whether to allow subshell execution ($(cmd) or `cmd`) */
+        allow_subshell?: boolean;
+        /** Whether to allow pipe chains */
+        allow_pipes?: boolean;
+        /** Whether to allow command chaining (&&, ||, ;) */
+        allow_chains?: boolean;
+        /** Whether to allow output redirection (>, >>) */
+        allow_redirects?: boolean;
+    };
+}
+/** Result of whitelist evaluation */
+interface WhitelistEvalResult {
+    /** Whether the command is allowed */
+    allowed: boolean;
+    /** Whether human approval is required */
+    require_approval: boolean;
+    /** The matching rule (if any) */
+    matched_rule?: WhitelistRule;
+    /** Reason for the decision */
+    reason: string;
+    /** Risk level */
+    risk: 'none' | 'low' | 'medium' | 'high' | 'critical';
+    /** Structural violations detected */
+    violations: string[];
+}
+/**
+ * Minimal whitelist for read-only operations.
+ * Suitable for AI agents that should only read, not write.
+ */
+declare const PRESET_READONLY: WhitelistPolicy;
+/**
+ * Developer whitelist for coding agents.
+ * Allows common dev operations but blocks destructive ones.
+ */
+declare const PRESET_DEVELOPER: WhitelistPolicy;
+/**
+ * Strict whitelist for production environments.
+ * Only allows pre-defined deployment commands.
+ */
+declare const PRESET_PRODUCTION: WhitelistPolicy;
+/** Map of preset names to policies */
+declare const PRESETS: Record<string, WhitelistPolicy>;
+declare class WhitelistEngine {
+    private policy;
+    constructor(policy: WhitelistPolicy);
+    /**
+     * Evaluate a command against the whitelist policy.
+     */
+    evaluate(command: string): WhitelistEvalResult;
+    /**
+     * Check structural constraints (pipes, chains, subshells, etc.)
+     */
+    private checkStructural;
+    /**
+     * Get the current policy.
+     */
+    getPolicy(): WhitelistPolicy;
+    /**
+     * Add a rule dynamically.
+     */
+    addRule(rule: WhitelistRule): void;
+    /**
+     * Remove a rule by pattern.
+     */
+    removeRule(pattern: string): boolean;
+    /**
+     * List all rules.
+     */
+    listRules(): WhitelistRule[];
+}
+/**
+ * Load a whitelist policy from a YAML-like file.
+ * Supports simplified YAML format (JSON subset).
+ */
+declare function loadPolicy(filePath: string): WhitelistPolicy;
+/**
+ * Auto-detect and load policy from project directory.
+ * Looks for .sovr/policy.json or .sovr/policy.yaml
+ */
+declare function autoLoadPolicy(projectDir: string): WhitelistPolicy | null;
+/**
+ * Generate a sample policy file for a given preset.
+ */
+declare function generatePolicyFile(preset: string, format?: 'json' | 'yaml'): string;
+
+export { PRESETS, PRESET_DEVELOPER, PRESET_PRODUCTION, PRESET_READONLY, type PolicyMode, WhitelistEngine, type WhitelistEvalResult, type WhitelistPolicy, type WhitelistRule, autoLoadPolicy, generatePolicyFile, loadPolicy };

package/dist/whitelistEngine.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @sovr/proxy-mcp — Whitelist Policy Engine
+ *
+ * Solves the critical Reddit feedback:
+ *   "A whitelist is much safer than a blacklist" — rvistro (9↑)
+ *   "If you ban that, I can just spin up a shell with -c" — coloradical5280 (2↑)
+ *
+ * Philosophy: DEFAULT DENY.
+ * Instead of trying to enumerate every dangerous command (impossible),
+ * we enumerate the SAFE commands and block everything else.
+ *
+ * The whitelist is project-scoped: each project declares what commands
+ * its AI agent needs, and SOVR enforces that boundary.
+ *
+ * Three policy modes:
+ *   - "whitelist"  — Only explicitly allowed commands can execute (recommended)
+ *   - "blacklist"  — Legacy mode, block known-dangerous patterns
+ *   - "hybrid"     — Whitelist + blacklist (whitelist takes priority)
+ *
+ * @example
+ * ```yaml
+ * # .sovr/policy.yaml
+ * version: "1.0"
+ * mode: whitelist
+ * rules:
+ *   - pattern: "ls *"
+ *     allow: true
+ *     description: "List directory contents"
+ *   - pattern: "cat *"
+ *     allow: true
+ *     description: "Read file contents"
+ *   - pattern: "npm run *"
+ *     allow: true
+ *     description: "Run npm scripts"
+ *   - pattern: "git status"
+ *     allow: true
+ *   - pattern: "git add *"
+ *     allow: true
+ *   - pattern: "git commit *"
+ *     allow: true
+ *   - pattern: "git push *"
+ *     allow: true
+ *     require_approval: true  # Human must approve pushes
+ * ```
+ */
+type PolicyMode = 'whitelist' | 'blacklist' | 'hybrid';
+/** A single whitelist/blacklist rule */
+interface WhitelistRule {
+    /** Glob-style pattern for the command (e.g., "ls *", "npm run *") */
+    pattern: string;
+    /** Whether this pattern is allowed (true) or blocked (false) */
+    allow: boolean;
+    /** Human-readable description */
+    description?: string;
+    /** Whether this command requires human approval even if allowed */
+    require_approval?: boolean;
+    /** Maximum arguments allowed (prevents injection via long args) */
+    max_args?: number;
+    /** Allowed working directories (glob patterns) */
+    allowed_dirs?: string[];
+    /** Priority (higher = evaluated first, default: 0) */
+    priority?: number;
+    /** Whether this rule is enabled */
+    enabled?: boolean;
+}
+/** Complete policy configuration */
+interface WhitelistPolicy {
+    /** Policy version */
+    version: string;
+    /** Policy mode */
+    mode: PolicyMode;
+    /** Policy rules */
+    rules: WhitelistRule[];
+    /** Default action when no rule matches (only for hybrid mode) */
+    default_action?: 'allow' | 'deny' | 'escalate';
+    /** Global settings */
+    settings?: {
+        /** Maximum command length in characters */
+        max_command_length?: number;
+        /** Whether to allow environment variable expansion */
+        allow_env_expansion?: boolean;
+        /** Whether to allow subshell execution ($(cmd) or `cmd`) */
+        allow_subshell?: boolean;
+        /** Whether to allow pipe chains */
+        allow_pipes?: boolean;
+        /** Whether to allow command chaining (&&, ||, ;) */
+        allow_chains?: boolean;
+        /** Whether to allow output redirection (>, >>) */
+        allow_redirects?: boolean;
+    };
+}
+/** Result of whitelist evaluation */
+interface WhitelistEvalResult {
+    /** Whether the command is allowed */
+    allowed: boolean;
+    /** Whether human approval is required */
+    require_approval: boolean;
+    /** The matching rule (if any) */
+    matched_rule?: WhitelistRule;
+    /** Reason for the decision */
+    reason: string;
+    /** Risk level */
+    risk: 'none' | 'low' | 'medium' | 'high' | 'critical';
+    /** Structural violations detected */
+    violations: string[];
+}
+/**
+ * Minimal whitelist for read-only operations.
+ * Suitable for AI agents that should only read, not write.
+ */
+declare const PRESET_READONLY: WhitelistPolicy;
+/**
+ * Developer whitelist for coding agents.
+ * Allows common dev operations but blocks destructive ones.
+ */
+declare const PRESET_DEVELOPER: WhitelistPolicy;
+/**
+ * Strict whitelist for production environments.
+ * Only allows pre-defined deployment commands.
+ */
+declare const PRESET_PRODUCTION: WhitelistPolicy;
+/** Map of preset names to policies */
+declare const PRESETS: Record<string, WhitelistPolicy>;
+declare class WhitelistEngine {
+    private policy;
+    constructor(policy: WhitelistPolicy);
+    /**
+     * Evaluate a command against the whitelist policy.
+     */
+    evaluate(command: string): WhitelistEvalResult;
+    /**
+     * Check structural constraints (pipes, chains, subshells, etc.)
+     */
+    private checkStructural;
+    /**
+     * Get the current policy.
+     */
+    getPolicy(): WhitelistPolicy;
+    /**
+     * Add a rule dynamically.
+     */
+    addRule(rule: WhitelistRule): void;
+    /**
+     * Remove a rule by pattern.
+     */
+    removeRule(pattern: string): boolean;
+    /**
+     * List all rules.
+     */
+    listRules(): WhitelistRule[];
+}
+/**
+ * Load a whitelist policy from a YAML-like file.
+ * Supports simplified YAML format (JSON subset).
+ */
+declare function loadPolicy(filePath: string): WhitelistPolicy;
+/**
+ * Auto-detect and load policy from project directory.
+ * Looks for .sovr/policy.json or .sovr/policy.yaml
+ */
+declare function autoLoadPolicy(projectDir: string): WhitelistPolicy | null;
+/**
+ * Generate a sample policy file for a given preset.
+ */
+declare function generatePolicyFile(preset: string, format?: 'json' | 'yaml'): string;
+
+export { PRESETS, PRESET_DEVELOPER, PRESET_PRODUCTION, PRESET_READONLY, type PolicyMode, WhitelistEngine, type WhitelistEvalResult, type WhitelistPolicy, type WhitelistRule, autoLoadPolicy, generatePolicyFile, loadPolicy };