sovr-mcp-proxy 7.0.0 → 7.2.0

package/dist/auditDashboard.mjs

@@ -0,0 +1,370 @@
+// src/auditDashboard.ts
+var AuditDashboard = class {
+  entries = [];
+  config;
+  saveTimer = null;
+  quotaCounter = 0;
+  quotaPeriodStart = Date.now();
+  constructor(config = {}) {
+    this.config = {
+      maxEntries: config.maxEntries ?? 5e4,
+      persistPath: config.persistPath,
+      autoSaveInterval: config.autoSaveInterval ?? 6e4,
+      quotaLimit: config.quotaLimit ?? 1e4,
+      quotaPeriod: config.quotaPeriod ?? 30 * 24 * 60 * 60 * 1e3,
+      // 30 days
+      redactPatterns: config.redactPatterns ?? [
+        /password/i,
+        /secret/i,
+        /token/i,
+        /api.?key/i,
+        /credential/i,
+        /authorization/i,
+        /cookie/i,
+        /session/i
+      ]
+    };
+    if (this.config.persistPath && this.config.autoSaveInterval > 0) {
+      this.saveTimer = setInterval(() => this.persist(), this.config.autoSaveInterval);
+    }
+  }
+  // ─── Core Operations ───────────────────────────────────────────────────
+  /** Record a new audit entry */
+  record(entry) {
+    const now = Date.now();
+    const fullEntry = {
+      ...entry,
+      id: `ae_${now}_${Math.random().toString(36).slice(2, 8)}`,
+      timestamp: new Date(now).toISOString(),
+      epochMs: now,
+      arguments: this.redactSensitive(entry.arguments)
+    };
+    this.entries.push(fullEntry);
+    this.quotaCounter++;
+    if (this.entries.length > this.config.maxEntries) {
+      this.entries = this.entries.slice(-this.config.maxEntries);
+    }
+    return fullEntry;
+  }
+  /** Get entries with optional filters */
+  query(filters = {}) {
+    let filtered = this.entries;
+    if (filters.from) filtered = filtered.filter((e) => e.epochMs >= filters.from);
+    if (filters.to) filtered = filtered.filter((e) => e.epochMs <= filters.to);
+    if (filters.toolName) filtered = filtered.filter((e) => e.toolName === filters.toolName);
+    if (filters.decision) filtered = filtered.filter((e) => e.decision === filters.decision);
+    if (filters.riskLevel) filtered = filtered.filter((e) => e.riskLevel === filters.riskLevel);
+    if (filters.sessionId) filtered = filtered.filter((e) => e.sessionId === filters.sessionId);
+    if (filters.agentId) filtered = filtered.filter((e) => e.agentId === filters.agentId);
+    const total = filtered.length;
+    const offset = filters.offset ?? 0;
+    const limit = filters.limit ?? 100;
+    const paged = filtered.slice(offset, offset + limit);
+    return { entries: paged, total };
+  }
+  /** Get a single entry by ID */
+  getById(id) {
+    return this.entries.find((e) => e.id === id);
+  }
+  // ─── Statistics ────────────────────────────────────────────────────────
+  /** Get dashboard statistics for a time range */
+  getStats(from, to) {
+    const now = Date.now();
+    const rangeFrom = from ?? now - 24 * 60 * 60 * 1e3;
+    const rangeTo = to ?? now;
+    const filtered = this.entries.filter((e) => e.epochMs >= rangeFrom && e.epochMs <= rangeTo);
+    const byDecision = {};
+    const byRiskLevel = {};
+    const byTool = {};
+    const byType = {};
+    const policyCount = {};
+    const blockedTools = {};
+    const latencies = [];
+    for (const entry of filtered) {
+      byDecision[entry.decision] = (byDecision[entry.decision] || 0) + 1;
+      byRiskLevel[entry.riskLevel] = (byRiskLevel[entry.riskLevel] || 0) + 1;
+      byTool[entry.toolName] = (byTool[entry.toolName] || 0) + 1;
+      byType[entry.type] = (byType[entry.type] || 0) + 1;
+      latencies.push(entry.durationMs);
+      if (entry.policyId) {
+        policyCount[entry.policyId] = (policyCount[entry.policyId] || 0) + 1;
+      }
+      if (entry.decision === "block") {
+        blockedTools[entry.toolName] = (blockedTools[entry.toolName] || 0) + 1;
+      }
+    }
+    const sortedLatencies = latencies.sort((a, b) => a - b);
+    const p95Index = Math.floor(sortedLatencies.length * 0.95);
+    const p99Index = Math.floor(sortedLatencies.length * 0.99);
+    const topBlocked = Object.entries(blockedTools).sort(([, a], [, b]) => b - a).slice(0, 10).map(([tool, count]) => ({ tool, count }));
+    const topPolicies = Object.entries(policyCount).sort(([, a], [, b]) => b - a).slice(0, 10).map(([policyId, count]) => ({ policyId, count }));
+    const riskHistogram = [
+      { range: "0-20", count: filtered.filter((e) => e.riskScore < 20).length },
+      { range: "20-40", count: filtered.filter((e) => e.riskScore >= 20 && e.riskScore < 40).length },
+      { range: "40-60", count: filtered.filter((e) => e.riskScore >= 40 && e.riskScore < 60).length },
+      { range: "60-80", count: filtered.filter((e) => e.riskScore >= 60 && e.riskScore < 80).length },
+      { range: "80-100", count: filtered.filter((e) => e.riskScore >= 80).length }
+    ];
+    const durationMinutes = Math.max(1, (rangeTo - rangeFrom) / 6e4);
+    const allowed = byDecision["allow"] || 0;
+    return {
+      timeRange: { from: new Date(rangeFrom).toISOString(), to: new Date(rangeTo).toISOString() },
+      totalEvents: filtered.length,
+      byDecision,
+      byRiskLevel,
+      byTool,
+      byType,
+      successRate: filtered.length > 0 ? Math.round(allowed / filtered.length * 1e4) / 100 : 100,
+      avgLatencyMs: latencies.length > 0 ? Math.round(latencies.reduce((a, b) => a + b, 0) / latencies.length) : 0,
+      p95LatencyMs: sortedLatencies[p95Index] ?? 0,
+      p99LatencyMs: sortedLatencies[p99Index] ?? 0,
+      eventsPerMinute: Math.round(filtered.length / durationMinutes * 100) / 100,
+      topBlocked,
+      topPolicies,
+      riskHistogram
+    };
+  }
+  // ─── Trends ────────────────────────────────────────────────────────────
+  /** Get time-series trend data */
+  getTrends(granularity = "hourly", from, to) {
+    const now = Date.now();
+    const rangeFrom = from ?? now - 7 * 24 * 60 * 60 * 1e3;
+    const rangeTo = to ?? now;
+    const bucketSize = granularity === "hourly" ? 36e5 : granularity === "daily" ? 864e5 : 6048e5;
+    const filtered = this.entries.filter((e) => e.epochMs >= rangeFrom && e.epochMs <= rangeTo);
+    const buckets = /* @__PURE__ */ new Map();
+    for (const entry of filtered) {
+      const bucketStart = Math.floor(entry.epochMs / bucketSize) * bucketSize;
+      if (!buckets.has(bucketStart)) buckets.set(bucketStart, []);
+      buckets.get(bucketStart).push(entry);
+    }
+    const points = [];
+    let current = Math.floor(rangeFrom / bucketSize) * bucketSize;
+    while (current <= rangeTo) {
+      const entries = buckets.get(current) || [];
+      const allowed = entries.filter((e) => e.decision === "allow" || e.decision === "transform").length;
+      const blocked = entries.filter((e) => e.decision === "block" || e.decision === "rate-limited").length;
+      points.push({
+        label: this.formatBucketLabel(current, granularity),
+        epochMs: current,
+        total: entries.length,
+        allowed,
+        blocked,
+        avgRisk: entries.length > 0 ? Math.round(entries.reduce((sum, e) => sum + e.riskScore, 0) / entries.length) : 0,
+        avgLatency: entries.length > 0 ? Math.round(entries.reduce((sum, e) => sum + e.durationMs, 0) / entries.length) : 0
+      });
+      current += bucketSize;
+    }
+    return points;
+  }
+  // ─── Quota ─────────────────────────────────────────────────────────────
+  /** Get current quota status with prediction */
+  getQuotaStatus() {
+    const now = Date.now();
+    if (now - this.quotaPeriodStart > this.config.quotaPeriod) {
+      this.quotaCounter = 0;
+      this.quotaPeriodStart = now;
+    }
+    const elapsed = now - this.quotaPeriodStart;
+    const elapsedDays = Math.max(1, elapsed / (24 * 60 * 60 * 1e3));
+    const dailyAverage = Math.round(this.quotaCounter / elapsedDays);
+    const remaining = this.config.quotaLimit - this.quotaCounter;
+    const daysRemaining = dailyAverage > 0 ? Math.round(remaining / dailyAverage) : void 0;
+    let predictedExhaustion;
+    if (daysRemaining !== void 0 && daysRemaining > 0) {
+      predictedExhaustion = new Date(now + daysRemaining * 24 * 60 * 60 * 1e3).toISOString();
+    }
+    return {
+      used: this.quotaCounter,
+      limit: this.config.quotaLimit,
+      percentage: Math.round(this.quotaCounter / this.config.quotaLimit * 1e4) / 100,
+      predictedExhaustion,
+      dailyAverage,
+      daysRemaining
+    };
+  }
+  // ─── Export ────────────────────────────────────────────────────────────
+  /** Export audit log as CSV */
+  exportCSV(filters) {
+    const { entries } = this.query({ from: filters?.from, to: filters?.to, limit: this.config.maxEntries });
+    const headers = [
+      "id",
+      "timestamp",
+      "type",
+      "toolName",
+      "decision",
+      "riskScore",
+      "riskLevel",
+      "policyId",
+      "reason",
+      "durationMs",
+      "sessionId",
+      "agentId",
+      "error"
+    ];
+    const rows = entries.map((e) => [
+      e.id,
+      e.timestamp,
+      e.type,
+      e.toolName,
+      e.decision,
+      e.riskScore,
+      e.riskLevel,
+      e.policyId || "",
+      `"${(e.reason || "").replace(/"/g, '""')}"`,
+      e.durationMs,
+      e.sessionId || "",
+      e.agentId || "",
+      e.error ? `"${e.error.replace(/"/g, '""')}"` : ""
+    ].join(","));
+    return [headers.join(","), ...rows].join("\n");
+  }
+  /** Export audit log as JSON */
+  exportJSON(filters) {
+    const { entries } = this.query({ from: filters?.from, to: filters?.to, limit: this.config.maxEntries });
+    return JSON.stringify({
+      exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      totalEntries: entries.length,
+      entries
+    }, null, 2);
+  }
+  /** Export Trust Bundle (evidence package) */
+  exportTrustBundle(sessionId) {
+    const { entries } = sessionId ? this.query({ sessionId, limit: this.config.maxEntries }) : this.query({ limit: 1e3 });
+    const stats = this.getStats();
+    const dataStr = JSON.stringify(entries);
+    let hash = 0;
+    for (let i = 0; i < dataStr.length; i++) {
+      const char = dataStr.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash |= 0;
+    }
+    return {
+      bundleId: `tb_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      entries,
+      stats,
+      integrity: `sha256:${Math.abs(hash).toString(16).padStart(16, "0")}`
+    };
+  }
+  // ─── Session Management ────────────────────────────────────────────────
+  /** Start a new audit session */
+  startSession(agentId) {
+    const sessionId = `ses_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    this.record({
+      type: "session_start",
+      toolName: "__session__",
+      arguments: {},
+      decision: "allow",
+      riskScore: 0,
+      riskLevel: "safe",
+      reason: "Session started",
+      durationMs: 0,
+      sessionId,
+      agentId
+    });
+    return sessionId;
+  }
+  /** End an audit session */
+  endSession(sessionId) {
+    this.record({
+      type: "session_end",
+      toolName: "__session__",
+      arguments: {},
+      decision: "allow",
+      riskScore: 0,
+      riskLevel: "safe",
+      reason: "Session ended",
+      durationMs: 0,
+      sessionId
+    });
+  }
+  // ─── Lifecycle ─────────────────────────────────────────────────────────
+  /** Get total entry count */
+  get size() {
+    return this.entries.length;
+  }
+  /** Clear all entries */
+  clear() {
+    this.entries = [];
+  }
+  /** Destroy and cleanup */
+  destroy() {
+    if (this.saveTimer) {
+      clearInterval(this.saveTimer);
+      this.saveTimer = null;
+    }
+    this.persist();
+  }
+  // ─── Private ─────────────────────────────────────────────────────────────
+  redactSensitive(args) {
+    const result = JSON.parse(JSON.stringify(args));
+    const redact = (obj) => {
+      for (const key of Object.keys(obj)) {
+        if (this.config.redactPatterns.some((p) => p.test(key))) {
+          obj[key] = "[REDACTED]";
+        } else if (typeof obj[key] === "object" && obj[key] !== null) {
+          redact(obj[key]);
+        } else if (typeof obj[key] === "string") {
+          let val = obj[key];
+          for (const pattern of this.config.redactPatterns) {
+            if (pattern.test(val)) {
+              obj[key] = "[REDACTED]";
+              break;
+            }
+          }
+        }
+      }
+    };
+    redact(result);
+    return result;
+  }
+  formatBucketLabel(epochMs, granularity) {
+    const d = new Date(epochMs);
+    switch (granularity) {
+      case "hourly":
+        return `${d.getUTCMonth() + 1}/${d.getUTCDate()} ${d.getUTCHours().toString().padStart(2, "0")}:00`;
+      case "daily":
+        return `${d.getUTCFullYear()}-${(d.getUTCMonth() + 1).toString().padStart(2, "0")}-${d.getUTCDate().toString().padStart(2, "0")}`;
+      case "weekly":
+        return `Week of ${d.getUTCMonth() + 1}/${d.getUTCDate()}`;
+      default:
+        return d.toISOString();
+    }
+  }
+  persist() {
+    if (!this.config.persistPath) return;
+    try {
+      const data = JSON.stringify({
+        entries: this.entries.slice(-this.config.maxEntries),
+        quotaCounter: this.quotaCounter,
+        quotaPeriodStart: this.quotaPeriodStart
+      });
+      void data;
+    } catch {
+    }
+  }
+};
+function createAuditDashboard(overrides = {}) {
+  return new AuditDashboard(overrides);
+}
+function createFreeTierDashboard() {
+  return new AuditDashboard({
+    maxEntries: 1e3,
+    quotaLimit: 500,
+    quotaPeriod: 30 * 24 * 60 * 60 * 1e3
+  });
+}
+function createProDashboard() {
+  return new AuditDashboard({
+    maxEntries: 5e4,
+    quotaLimit: 5e4,
+    quotaPeriod: 30 * 24 * 60 * 60 * 1e3
+  });
+}
+export {
+  AuditDashboard,
+  createAuditDashboard,
+  createFreeTierDashboard,
+  createProDashboard
+};

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