sovr-mcp-proxy 7.0.0 → 7.2.0

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 };