sovr-mcp-proxy 6.0.1 → 7.1.0

package/dist/index.mjs

@@ -5,7 +5,7 @@ import {
 // src/index.ts
 import { spawn } from "child_process";
 import { EventEmitter } from "events";
-var PROXY_VERSION = "5.2.0";
+var PROXY_VERSION = "7.0.0";
 var SOVR_MIN_VERSION_URL = "https://api.sovr.inc/api/sovr/v1/version/check";
 var SOVR_DASHBOARD_URL = "https://sovr.inc/dashboard/api-keys";
 function validateApiKey(key) {
@@ -823,11 +823,15 @@ var McpProxy = class extends EventEmitter {
 };
 async function cli(args) {
   const { PolicyEngine, DEFAULT_RULES } = await import("./engine-DWKHAJGE.mjs");
+  const { transformToolList, shouldIntercept, parseMode } = await import("./toolReplacement.mjs");
+  const { normalize: normalizeCommand, summarize: summarizeNormalization } = await import("./commandNormalizer.mjs");
   let upstreamCmd = "";
   let upstreamArgs = [];
   let rulesFile = null;
   let verbose = false;
   let startupTimeoutMs = 3e4;
+  let mode = "enforce";
+  let whitelistPreset = null;
   for (let i = 0; i < args.length; i++) {
     switch (args[i]) {
       case "--upstream":
@@ -849,14 +853,39 @@ async function cli(args) {
       case "-t":
         startupTimeoutMs = parseInt(args[++i] ?? "30000", 10);
         break;
+      case "--mode":
+      case "-m":
+        mode = args[++i] ?? "enforce";
+        break;
+      case "--whitelist":
+      case "-w":
+        whitelistPreset = args[++i] ?? null;
+        break;
+      default: {
+        const modeMatch = args[i]?.match(/^--mode=(.+)$/);
+        if (modeMatch) {
+          mode = modeMatch[1];
+          break;
+        }
+        const wlMatch = args[i]?.match(/^--whitelist=(.+)$/);
+        if (wlMatch) {
+          whitelistPreset = wlMatch[1];
+          break;
+        }
+      }
     }
   }
   if (!upstreamCmd) {
     process.stderr.write(
-      'Usage: sovr-mcp-proxy --upstream "command args..." [--rules policy.json] [--timeout 30000] [--verbose]\n'
+      'Usage: sovr-mcp-proxy --upstream "command args..." [--mode=exclusive|enforce|advisory|monitor] [--whitelist=preset|path] [--verbose]\n'
     );
     process.exit(1);
   }
+  if (!["exclusive", "enforce", "advisory", "monitor"].includes(mode)) {
+    process.stderr.write(`[SOVR] Invalid mode: ${mode}. Must be: exclusive|enforce|advisory|monitor
+`);
+    process.exit(1);
+  }
   let rules = DEFAULT_RULES;
   if (rulesFile) {
     const fs = await import("fs");
@@ -864,6 +893,26 @@ async function cli(args) {
     const parsed = JSON.parse(content);
     rules = parsed.rules ?? parsed;
   }
+  const { WhitelistEngine, PRESETS: WL_PRESETS } = await import("./whitelistEngine.mjs");
+  let whitelist = null;
+  if (whitelistPreset) {
+    const presetNames = Object.keys(WL_PRESETS);
+    if (presetNames.includes(whitelistPreset)) {
+      whitelist = new WhitelistEngine(WL_PRESETS[whitelistPreset]);
+    } else {
+      try {
+        const fs = await import("fs");
+        const content = fs.readFileSync(whitelistPreset, "utf-8");
+        const parsed = JSON.parse(content);
+        whitelist = new WhitelistEngine(parsed);
+      } catch (err) {
+        process.stderr.write(`[SOVR] Failed to load whitelist from ${whitelistPreset}: ${err.message}
+`);
+        process.exit(1);
+      }
+    }
+  }
+  const validatedMode = parseMode(mode);
   const engine = new PolicyEngine({
     rules,
     audit_log: true,
@@ -876,6 +925,24 @@ async function cli(args) {
       }
     }
   });
+  process.stderr.write(`
+`);
+  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\u2557
+`);
+  process.stderr.write(`  \u2551  SOVR MCP Proxy v${PROXY_VERSION}                      \u2551
+`);
+  process.stderr.write(`  \u2551  Mode: ${mode.toUpperCase().padEnd(40)}\u2551
+`);
+  if (whitelist) {
+    process.stderr.write(`  \u2551  Whitelist: ${(whitelistPreset ?? "custom").padEnd(35)}\u2551
+`);
+  }
+  process.stderr.write(`  \u2551  Upstream: ${upstreamCmd.substring(0, 36).padEnd(36)}\u2551
+`);
+  process.stderr.write(`  \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\u255D
+`);
+  process.stderr.write(`
+`);
   const proxy = new McpProxy({
     engine,
     upstream: { command: upstreamCmd, args: upstreamArgs },
@@ -892,8 +959,37 @@ async function cli(args) {
         `[ESCALATED] ${info.toolName}: ${info.decision.reason}
 `
       );
+    },
+    onIntercept: (info) => {
+      if (info.arguments?.command && typeof info.arguments.command === "string") {
+        const normalized = normalizeCommand(info.arguments.command);
+        if (verbose) {
+          process.stderr.write(`[SOVR] Normalized: ${summarizeNormalization(normalized)}
+`);
+          if (normalized.suspicious) {
+            process.stderr.write(`[SOVR] \u26A0 Suspicious: ${normalized.suspicion_reasons.join(", ")}
+`);
+          }
+        }
+      }
+      if (whitelist && info.arguments?.command && typeof info.arguments.command === "string") {
+        const wlResult = whitelist.evaluate(info.arguments.command);
+        if (!wlResult.allowed && (validatedMode === "enforce" || validatedMode === "exclusive")) {
+          if (verbose) {
+            process.stderr.write(`[SOVR] Whitelist DENIED: ${wlResult.reason}
+`);
+          }
+        }
+      }
     }
   });
+  if (validatedMode === "exclusive") {
+    proxy.on("intercept", () => {
+      if (verbose) {
+        process.stderr.write("[SOVR] Exclusive mode: all tool calls routed through SOVR\n");
+      }
+    });
+  }
   await proxy.start();
 }
 var index_default = McpProxy;

package/dist/mcpProxyInterceptor.d.mts

@@ -0,0 +1,256 @@
+/**
+ * SOVR MCP Proxy Interceptor — Universal Tool Call Interception
+ *
+ * P1-1: SOVR sits between the MCP client (LLM) and the MCP server (tools),
+ * intercepting ALL tool calls regardless of transport (stdio/SSE/HTTP).
+ *
+ * Architecture:
+ *   [LLM Client] → [SOVR Proxy] → [Upstream MCP Server]
+ *                      ↓
+ *              [Policy Engine]
+ *              [Audit Trail]
+ *              [Rate Limiter]
+ *              [Semantic Analyzer]
+ *
+ * Unlike Tool Replacement (which replaces tools), this module transparently
+ * proxies ALL tools and applies policies at the protocol level.
+ */
+interface InterceptorConfig {
+    /** Policy mode: block | warn | audit-only */
+    mode: 'block' | 'warn' | 'audit';
+    /** Maximum concurrent tool calls */
+    maxConcurrent: number;
+    /** Per-tool rate limits (calls per minute) */
+    rateLimits: Record<string, number>;
+    /** Global rate limit (calls per minute) */
+    globalRateLimit: number;
+    /** Tool-specific policies */
+    toolPolicies: ToolPolicy[];
+    /** Enable semantic analysis for tool arguments */
+    enableSemanticAnalysis: boolean;
+    /** Callback for human approval */
+    onApprovalRequired?: (request: InterceptedCall) => Promise<ApprovalResult>;
+    /** Callback for audit events */
+    onAuditEvent?: (event: AuditEvent) => void;
+    /** Timeout for upstream tool calls (ms) */
+    upstreamTimeout: number;
+    /** Max retries for transient failures */
+    maxRetries: number;
+}
+interface ToolPolicy {
+    /** Tool name pattern (glob) */
+    toolPattern: string;
+    /** Action to take */
+    action: 'allow' | 'block' | 'require-approval' | 'rate-limit' | 'transform';
+    /** Conditions for this policy */
+    conditions?: PolicyCondition[];
+    /** Argument transformations (for 'transform' action) */
+    transforms?: ArgumentTransform[];
+    /** Priority (higher = evaluated first) */
+    priority: number;
+    /** Human-readable description */
+    description: string;
+}
+interface PolicyCondition {
+    /** Field path in tool arguments (dot notation) */
+    field: string;
+    /** Operator */
+    operator: 'contains' | 'matches' | 'equals' | 'gt' | 'lt' | 'exists' | 'not-exists';
+    /** Value to compare against */
+    value: string | number | boolean;
+}
+interface ArgumentTransform {
+    /** Field path to transform */
+    field: string;
+    /** Transform type */
+    type: 'redact' | 'mask' | 'replace' | 'remove';
+    /** Replacement value (for 'replace') */
+    replacement?: string;
+}
+interface InterceptedCall {
+    /** Unique call ID */
+    id: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Tool name */
+    toolName: string;
+    /** Original arguments */
+    arguments: Record<string, unknown>;
+    /** Matched policies */
+    matchedPolicies: ToolPolicy[];
+    /** Decision */
+    decision: InterceptDecision;
+    /** Semantic analysis result (if enabled) */
+    semanticResult?: SemanticAnalysisResult;
+}
+interface InterceptDecision {
+    /** Final action */
+    action: 'allow' | 'block' | 'require-approval' | 'transform';
+    /** Reason for decision */
+    reason: string;
+    /** Policy that triggered this decision */
+    triggeringPolicy?: ToolPolicy;
+    /** Risk score (0-100) */
+    riskScore: number;
+    /** Transformed arguments (if action is 'transform') */
+    transformedArguments?: Record<string, unknown>;
+}
+interface SemanticAnalysisResult {
+    /** Detected intent */
+    intent: string;
+    /** Risk category */
+    riskCategory: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    /** Confidence (0-1) */
+    confidence: number;
+    /** Explanation */
+    explanation: string;
+}
+interface ApprovalResult {
+    approved: boolean;
+    approver?: string;
+    reason?: string;
+    timestamp: number;
+}
+interface AuditEvent {
+    id: string;
+    timestamp: number;
+    type: 'intercept' | 'allow' | 'block' | 'approval-requested' | 'approval-granted' | 'approval-denied' | 'error' | 'rate-limited';
+    toolName: string;
+    arguments: Record<string, unknown>;
+    decision: InterceptDecision;
+    duration?: number;
+    error?: string;
+    upstreamResult?: unknown;
+}
+interface InterceptorStats {
+    totalCalls: number;
+    allowed: number;
+    blocked: number;
+    approvalRequested: number;
+    rateLimited: number;
+    errors: number;
+    avgLatencyMs: number;
+    callsByTool: Record<string, number>;
+    blocksByPolicy: Record<string, number>;
+    riskDistribution: {
+        safe: number;
+        suspicious: number;
+        dangerous: number;
+        critical: number;
+    };
+}
+declare class McpProxyInterceptor {
+    private config;
+    private rateLimiter;
+    private stats;
+    private auditLog;
+    private maxAuditLogSize;
+    private activeCalls;
+    private cleanupInterval;
+    constructor(config?: Partial<InterceptorConfig>);
+    /**
+     * Intercept a tool call — the core entry point.
+     * Returns the decision and optionally transformed arguments.
+     */
+    intercept(toolName: string, args: Record<string, unknown>): Promise<InterceptedCall>;
+    /**
+     * Wrap an upstream tool call with interception.
+     * If allowed, executes the upstream function; if blocked, returns error.
+     */
+    wrapToolCall<T>(toolName: string, args: Record<string, unknown>, upstream: (args: Record<string, unknown>) => Promise<T>): Promise<{
+        result?: T;
+        intercepted: InterceptedCall;
+        error?: string;
+    }>;
+    /** Get current statistics */
+    getStats(): InterceptorStats;
+    /** Get recent audit log */
+    getAuditLog(limit?: number): AuditEvent[];
+    /** Export audit log as CSV */
+    exportAuditCSV(): string;
+    /** Add a policy at runtime */
+    addPolicy(policy: ToolPolicy): void;
+    /** Remove policies matching a pattern */
+    removePolicies(toolPattern: string): number;
+    /** Reset statistics */
+    resetStats(): void;
+    /** Cleanup resources */
+    destroy(): void;
+    private emitAudit;
+    private trimAuditLog;
+}
+declare const PRESET_POLICIES: {
+    /** Block all destructive file operations */
+    noDestructiveFiles: {
+        toolPattern: string;
+        action: "block";
+        conditions: {
+            field: string;
+            operator: "matches";
+            value: string;
+        }[];
+        priority: number;
+        description: string;
+    };
+    /** Block all database write operations */
+    readOnlyDatabase: {
+        toolPattern: string;
+        action: "block";
+        conditions: {
+            field: string;
+            operator: "matches";
+            value: string;
+        }[];
+        priority: number;
+        description: string;
+    };
+    /** Require approval for payment operations */
+    approvePayments: {
+        toolPattern: string;
+        action: "require-approval";
+        priority: number;
+        description: string;
+    };
+    /** Redact secrets in tool arguments */
+    redactSecrets: {
+        toolPattern: string;
+        action: "transform";
+        conditions: {
+            field: string;
+            operator: "matches";
+            value: string;
+        }[];
+        transforms: ({
+            field: string;
+            type: "redact";
+        } | {
+            field: string;
+            type: "mask";
+        })[];
+        priority: number;
+        description: string;
+    };
+    /** Rate limit shell commands */
+    rateLimitShell: {
+        toolPattern: string;
+        action: "rate-limit";
+        priority: number;
+        description: string;
+    };
+    /** Allow read-only operations */
+    allowReadOnly: {
+        toolPattern: string;
+        action: "allow";
+        conditions: {
+            field: string;
+            operator: "matches";
+            value: string;
+        }[];
+        priority: number;
+        description: string;
+    };
+};
+/** Create a pre-configured interceptor with common security policies */
+declare function createSecureInterceptor(overrides?: Partial<InterceptorConfig>): McpProxyInterceptor;
+
+export { type ApprovalResult, type ArgumentTransform, type AuditEvent, type InterceptDecision, type InterceptedCall, type InterceptorConfig, type InterceptorStats, McpProxyInterceptor, PRESET_POLICIES, type PolicyCondition, type SemanticAnalysisResult, type ToolPolicy, createSecureInterceptor };

package/dist/mcpProxyInterceptor.d.ts

@@ -0,0 +1,256 @@
+/**
+ * SOVR MCP Proxy Interceptor — Universal Tool Call Interception
+ *
+ * P1-1: SOVR sits between the MCP client (LLM) and the MCP server (tools),
+ * intercepting ALL tool calls regardless of transport (stdio/SSE/HTTP).
+ *
+ * Architecture:
+ *   [LLM Client] → [SOVR Proxy] → [Upstream MCP Server]
+ *                      ↓
+ *              [Policy Engine]
+ *              [Audit Trail]
+ *              [Rate Limiter]
+ *              [Semantic Analyzer]
+ *
+ * Unlike Tool Replacement (which replaces tools), this module transparently
+ * proxies ALL tools and applies policies at the protocol level.
+ */
+interface InterceptorConfig {
+    /** Policy mode: block | warn | audit-only */
+    mode: 'block' | 'warn' | 'audit';
+    /** Maximum concurrent tool calls */
+    maxConcurrent: number;
+    /** Per-tool rate limits (calls per minute) */
+    rateLimits: Record<string, number>;
+    /** Global rate limit (calls per minute) */
+    globalRateLimit: number;
+    /** Tool-specific policies */
+    toolPolicies: ToolPolicy[];
+    /** Enable semantic analysis for tool arguments */
+    enableSemanticAnalysis: boolean;
+    /** Callback for human approval */
+    onApprovalRequired?: (request: InterceptedCall) => Promise<ApprovalResult>;
+    /** Callback for audit events */
+    onAuditEvent?: (event: AuditEvent) => void;
+    /** Timeout for upstream tool calls (ms) */
+    upstreamTimeout: number;
+    /** Max retries for transient failures */
+    maxRetries: number;
+}
+interface ToolPolicy {
+    /** Tool name pattern (glob) */
+    toolPattern: string;
+    /** Action to take */
+    action: 'allow' | 'block' | 'require-approval' | 'rate-limit' | 'transform';
+    /** Conditions for this policy */
+    conditions?: PolicyCondition[];
+    /** Argument transformations (for 'transform' action) */
+    transforms?: ArgumentTransform[];
+    /** Priority (higher = evaluated first) */
+    priority: number;
+    /** Human-readable description */
+    description: string;
+}
+interface PolicyCondition {
+    /** Field path in tool arguments (dot notation) */
+    field: string;
+    /** Operator */
+    operator: 'contains' | 'matches' | 'equals' | 'gt' | 'lt' | 'exists' | 'not-exists';
+    /** Value to compare against */
+    value: string | number | boolean;
+}
+interface ArgumentTransform {
+    /** Field path to transform */
+    field: string;
+    /** Transform type */
+    type: 'redact' | 'mask' | 'replace' | 'remove';
+    /** Replacement value (for 'replace') */
+    replacement?: string;
+}
+interface InterceptedCall {
+    /** Unique call ID */
+    id: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Tool name */
+    toolName: string;
+    /** Original arguments */
+    arguments: Record<string, unknown>;
+    /** Matched policies */
+    matchedPolicies: ToolPolicy[];
+    /** Decision */
+    decision: InterceptDecision;
+    /** Semantic analysis result (if enabled) */
+    semanticResult?: SemanticAnalysisResult;
+}
+interface InterceptDecision {
+    /** Final action */
+    action: 'allow' | 'block' | 'require-approval' | 'transform';
+    /** Reason for decision */
+    reason: string;
+    /** Policy that triggered this decision */
+    triggeringPolicy?: ToolPolicy;
+    /** Risk score (0-100) */
+    riskScore: number;
+    /** Transformed arguments (if action is 'transform') */
+    transformedArguments?: Record<string, unknown>;
+}
+interface SemanticAnalysisResult {
+    /** Detected intent */
+    intent: string;
+    /** Risk category */
+    riskCategory: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    /** Confidence (0-1) */
+    confidence: number;
+    /** Explanation */
+    explanation: string;
+}
+interface ApprovalResult {
+    approved: boolean;
+    approver?: string;
+    reason?: string;
+    timestamp: number;
+}
+interface AuditEvent {
+    id: string;
+    timestamp: number;
+    type: 'intercept' | 'allow' | 'block' | 'approval-requested' | 'approval-granted' | 'approval-denied' | 'error' | 'rate-limited';
+    toolName: string;
+    arguments: Record<string, unknown>;
+    decision: InterceptDecision;
+    duration?: number;
+    error?: string;
+    upstreamResult?: unknown;
+}
+interface InterceptorStats {
+    totalCalls: number;
+    allowed: number;
+    blocked: number;
+    approvalRequested: number;
+    rateLimited: number;
+    errors: number;
+    avgLatencyMs: number;
+    callsByTool: Record<string, number>;
+    blocksByPolicy: Record<string, number>;
+    riskDistribution: {
+        safe: number;
+        suspicious: number;
+        dangerous: number;
+        critical: number;
+    };
+}
+declare class McpProxyInterceptor {
+    private config;
+    private rateLimiter;
+    private stats;
+    private auditLog;
+    private maxAuditLogSize;
+    private activeCalls;
+    private cleanupInterval;
+    constructor(config?: Partial<InterceptorConfig>);
+    /**
+     * Intercept a tool call — the core entry point.
+     * Returns the decision and optionally transformed arguments.
+     */
+    intercept(toolName: string, args: Record<string, unknown>): Promise<InterceptedCall>;
+    /**
+     * Wrap an upstream tool call with interception.
+     * If allowed, executes the upstream function; if blocked, returns error.
+     */
+    wrapToolCall<T>(toolName: string, args: Record<string, unknown>, upstream: (args: Record<string, unknown>) => Promise<T>): Promise<{
+        result?: T;
+        intercepted: InterceptedCall;
+        error?: string;
+    }>;
+    /** Get current statistics */
+    getStats(): InterceptorStats;
+    /** Get recent audit log */
+    getAuditLog(limit?: number): AuditEvent[];
+    /** Export audit log as CSV */
+    exportAuditCSV(): string;
+    /** Add a policy at runtime */
+    addPolicy(policy: ToolPolicy): void;
+    /** Remove policies matching a pattern */
+    removePolicies(toolPattern: string): number;
+    /** Reset statistics */
+    resetStats(): void;
+    /** Cleanup resources */
+    destroy(): void;
+    private emitAudit;
+    private trimAuditLog;
+}
+declare const PRESET_POLICIES: {
+    /** Block all destructive file operations */
+    noDestructiveFiles: {
+        toolPattern: string;
+        action: "block";
+        conditions: {
+            field: string;
+            operator: "matches";
+            value: string;
+        }[];
+        priority: number;
+        description: string;
+    };
+    /** Block all database write operations */
+    readOnlyDatabase: {
+        toolPattern: string;
+        action: "block";
+        conditions: {
+            field: string;
+            operator: "matches";
+            value: string;
+        }[];
+        priority: number;
+        description: string;
+    };
+    /** Require approval for payment operations */
+    approvePayments: {
+        toolPattern: string;
+        action: "require-approval";
+        priority: number;
+        description: string;
+    };
+    /** Redact secrets in tool arguments */
+    redactSecrets: {
+        toolPattern: string;
+        action: "transform";
+        conditions: {
+            field: string;
+            operator: "matches";
+            value: string;
+        }[];
+        transforms: ({
+            field: string;
+            type: "redact";
+        } | {
+            field: string;
+            type: "mask";
+        })[];
+        priority: number;
+        description: string;
+    };
+    /** Rate limit shell commands */
+    rateLimitShell: {
+        toolPattern: string;
+        action: "rate-limit";
+        priority: number;
+        description: string;
+    };
+    /** Allow read-only operations */
+    allowReadOnly: {
+        toolPattern: string;
+        action: "allow";
+        conditions: {
+            field: string;
+            operator: "matches";
+            value: string;
+        }[];
+        priority: number;
+        description: string;
+    };
+};
+/** Create a pre-configured interceptor with common security policies */
+declare function createSecureInterceptor(overrides?: Partial<InterceptorConfig>): McpProxyInterceptor;
+
+export { type ApprovalResult, type ArgumentTransform, type AuditEvent, type InterceptDecision, type InterceptedCall, type InterceptorConfig, type InterceptorStats, McpProxyInterceptor, PRESET_POLICIES, type PolicyCondition, type SemanticAnalysisResult, type ToolPolicy, createSecureInterceptor };