sovr-mcp-proxy 6.0.1 → 7.1.0

package/dist/teamPolicyManager.mjs

@@ -0,0 +1,502 @@
+// src/teamPolicyManager.ts
+var ROLE_HIERARCHY = {
+  admin: 100,
+  lead: 75,
+  developer: 50,
+  viewer: 25,
+  custom: 0
+};
+var DEFAULT_ROLE_RULES = {
+  admin: [
+    {
+      id: "admin-full-access",
+      name: "Admin full access",
+      action: "allow",
+      tools: ["*"],
+      priority: 1e3,
+      enabled: true,
+      description: "Admins have full access to all tools"
+    }
+  ],
+  lead: [
+    {
+      id: "lead-read-write",
+      name: "Lead read/write access",
+      action: "allow",
+      tools: ["*"],
+      conditions: [{ field: "risk_score", operator: "lt", value: 70 }],
+      priority: 900,
+      enabled: true,
+      description: "Leads can use tools with risk < 70"
+    },
+    {
+      id: "lead-high-risk-approval",
+      name: "Lead high-risk requires approval",
+      action: "require-approval",
+      tools: ["*"],
+      conditions: [{ field: "risk_score", operator: "gte", value: 70 }],
+      priority: 901,
+      enabled: true,
+      description: "High-risk actions require approval for leads"
+    }
+  ],
+  developer: [
+    {
+      id: "dev-safe-access",
+      name: "Developer safe access",
+      action: "allow",
+      tools: ["*"],
+      conditions: [{ field: "risk_score", operator: "lt", value: 40 }],
+      priority: 800,
+      enabled: true,
+      description: "Developers can use safe tools freely"
+    },
+    {
+      id: "dev-moderate-approval",
+      name: "Developer moderate risk requires approval",
+      action: "require-approval",
+      tools: ["*"],
+      conditions: [{ field: "risk_score", operator: "gte", value: 40 }],
+      priority: 801,
+      enabled: true,
+      description: "Moderate+ risk requires approval for developers"
+    }
+  ],
+  viewer: [
+    {
+      id: "viewer-readonly",
+      name: "Viewer read-only",
+      action: "allow",
+      tools: ["read_*", "get_*", "list_*", "search_*", "view_*"],
+      priority: 700,
+      enabled: true,
+      description: "Viewers can only use read-only tools"
+    },
+    {
+      id: "viewer-block-write",
+      name: "Viewer block writes",
+      action: "block",
+      tools: ["*"],
+      priority: 699,
+      enabled: true,
+      description: "Block all non-read tools for viewers"
+    }
+  ],
+  custom: []
+};
+var TeamPolicyManager = class {
+  policySet;
+  constructor(name, settings) {
+    this.policySet = {
+      name,
+      activeVersion: 0,
+      versions: [],
+      members: [],
+      settings: {
+        defaultAction: settings?.defaultAction ?? "require-approval",
+        conflictResolution: settings?.conflictResolution ?? "most-restrictive",
+        enableCanary: settings?.enableCanary ?? false,
+        canaryPercentage: settings?.canaryPercentage ?? 10,
+        requireApprovalForChanges: settings?.requireApprovalForChanges ?? true,
+        notificationWebhook: settings?.notificationWebhook
+      }
+    };
+    this.createVersion("system", "Initial default policy", this.flattenDefaultRules());
+  }
+  // ─── Member Management ─────────────────────────────────────────────────
+  /** Add a team member */
+  addMember(member) {
+    if (this.policySet.members.find((m) => m.id === member.id)) {
+      throw new Error(`Member ${member.id} already exists`);
+    }
+    this.policySet.members.push({ ...member, active: true });
+  }
+  /** Update a team member */
+  updateMember(id, updates) {
+    const member = this.policySet.members.find((m) => m.id === id);
+    if (!member) throw new Error(`Member ${id} not found`);
+    Object.assign(member, updates);
+  }
+  /** Remove a team member (soft delete) */
+  deactivateMember(id) {
+    const member = this.policySet.members.find((m) => m.id === id);
+    if (!member) throw new Error(`Member ${id} not found`);
+    member.active = false;
+  }
+  /** Get all active members */
+  getMembers() {
+    return this.policySet.members.filter((m) => m.active);
+  }
+  /** Get member by ID */
+  getMember(id) {
+    return this.policySet.members.find((m) => m.id === id && m.active);
+  }
+  // ─── Policy Version Management ─────────────────────────────────────────
+  /** Create a new policy version */
+  createVersion(createdBy, description, rules, roleRules) {
+    const version = this.policySet.versions.length + 1;
+    const effectiveRoleRules = roleRules ?? this.generateRoleRules(rules);
+    const policyVersion = {
+      version,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      createdBy,
+      description,
+      rules,
+      roleRules: effectiveRoleRules,
+      active: true,
+      hash: this.computeHash(rules)
+    };
+    for (const v of this.policySet.versions) {
+      v.active = false;
+    }
+    this.policySet.versions.push(policyVersion);
+    this.policySet.activeVersion = version;
+    return policyVersion;
+  }
+  /** Rollback to a previous version */
+  rollback(targetVersion) {
+    const version = this.policySet.versions.find((v) => v.version === targetVersion);
+    if (!version) throw new Error(`Version ${targetVersion} not found`);
+    for (const v of this.policySet.versions) {
+      v.active = false;
+    }
+    version.active = true;
+    this.policySet.activeVersion = targetVersion;
+    return version;
+  }
+  /** Get all versions */
+  getVersions() {
+    return [...this.policySet.versions];
+  }
+  /** Get active version */
+  getActiveVersion() {
+    return this.policySet.versions.find((v) => v.active);
+  }
+  /** Compare two versions */
+  diffVersions(v1, v2) {
+    const ver1 = this.policySet.versions.find((v) => v.version === v1);
+    const ver2 = this.policySet.versions.find((v) => v.version === v2);
+    if (!ver1 || !ver2) throw new Error("Version not found");
+    const rules1Map = new Map(ver1.rules.map((r) => [r.id, r]));
+    const rules2Map = new Map(ver2.rules.map((r) => [r.id, r]));
+    const added = ver2.rules.filter((r) => !rules1Map.has(r.id));
+    const removed = ver1.rules.filter((r) => !rules2Map.has(r.id));
+    const modified = [];
+    for (const [id, rule1] of rules1Map) {
+      const rule2 = rules2Map.get(id);
+      if (rule2) {
+        const changes = [];
+        if (rule1.action !== rule2.action) changes.push(`action: ${rule1.action} \u2192 ${rule2.action}`);
+        if (rule1.priority !== rule2.priority) changes.push(`priority: ${rule1.priority} \u2192 ${rule2.priority}`);
+        if (rule1.enabled !== rule2.enabled) changes.push(`enabled: ${rule1.enabled} \u2192 ${rule2.enabled}`);
+        if (JSON.stringify(rule1.tools) !== JSON.stringify(rule2.tools)) changes.push("tools changed");
+        if (JSON.stringify(rule1.conditions) !== JSON.stringify(rule2.conditions)) changes.push("conditions changed");
+        if (changes.length > 0) modified.push({ ruleId: id, changes });
+      }
+    }
+    return { added, removed, modified };
+  }
+  // ─── Policy Evaluation ─────────────────────────────────────────────────
+  /** Evaluate a tool call against the policy for a specific member */
+  evaluate(memberId, toolName, context) {
+    const startTime = Date.now();
+    const member = this.getMember(memberId);
+    const activeVersion = this.getActiveVersion();
+    if (!activeVersion) {
+      return {
+        decision: this.policySet.settings.defaultAction,
+        matchedRules: [],
+        appliedOverrides: [],
+        effectiveRole: member?.role ?? "viewer",
+        policyVersion: 0,
+        durationMs: Date.now() - startTime
+      };
+    }
+    const effectiveRole = member?.role ?? "viewer";
+    const applicableRuleIds = this.getInheritedRuleIds(effectiveRole, activeVersion.roleRules);
+    const applicableRules = activeVersion.rules.filter((r) => applicableRuleIds.includes(r.id) && r.enabled).sort((a, b) => b.priority - a.priority);
+    const matchedRules = [];
+    const decisions = [];
+    for (const rule of applicableRules) {
+      if (this.matchesTool(toolName, rule.tools) && this.matchesConditions(rule.conditions, context)) {
+        matchedRules.push({ ruleId: rule.id, ruleName: rule.name, action: rule.action });
+        decisions.push({ action: rule.action, priority: rule.priority });
+      }
+    }
+    const appliedOverrides = [];
+    if (member?.overrides) {
+      for (const override of member.overrides) {
+        if (override.expiresAt && new Date(override.expiresAt) < /* @__PURE__ */ new Date()) continue;
+        const matchedRule = matchedRules.find((r) => r.ruleId === override.ruleId);
+        if (matchedRule) {
+          matchedRule.action = override.action;
+          appliedOverrides.push(override);
+          const decisionIdx = decisions.findIndex((d) => d.priority === applicableRules.find((r) => r.id === override.ruleId)?.priority);
+          if (decisionIdx >= 0) {
+            decisions[decisionIdx].action = override.action;
+          }
+        }
+      }
+    }
+    let finalDecision;
+    if (decisions.length === 0) {
+      finalDecision = this.policySet.settings.defaultAction;
+    } else {
+      finalDecision = this.resolveConflict(decisions);
+    }
+    return {
+      decision: finalDecision,
+      matchedRules,
+      appliedOverrides,
+      effectiveRole,
+      policyVersion: activeVersion.version,
+      durationMs: Date.now() - startTime
+    };
+  }
+  // ─── Canary Deployment ─────────────────────────────────────────────────
+  /** Check if a member should use the canary policy */
+  isInCanaryGroup(memberId) {
+    if (!this.policySet.settings.enableCanary) return false;
+    const member = this.getMember(memberId);
+    return member?.canaryGroup === "canary";
+  }
+  /** Assign members to canary group */
+  assignCanaryGroup(memberIds) {
+    for (const id of memberIds) {
+      const member = this.policySet.members.find((m) => m.id === id);
+      if (member) member.canaryGroup = "canary";
+    }
+  }
+  /** Promote canary to stable (all members get the canary policy) */
+  promoteCanary() {
+    for (const member of this.policySet.members) {
+      member.canaryGroup = void 0;
+    }
+    this.policySet.settings.enableCanary = false;
+  }
+  // ─── Import/Export ─────────────────────────────────────────────────────
+  /** Export policy as YAML-compatible object */
+  exportPolicy() {
+    const active = this.getActiveVersion();
+    return {
+      name: this.policySet.name,
+      version: active?.version ?? 0,
+      settings: this.policySet.settings,
+      rules: active?.rules.map((r) => ({
+        id: r.id,
+        name: r.name,
+        action: r.action,
+        tools: r.tools,
+        conditions: r.conditions,
+        priority: r.priority,
+        enabled: r.enabled,
+        description: r.description
+      })) ?? [],
+      roles: active?.roleRules ?? {},
+      members: this.policySet.members.map((m) => ({
+        id: m.id,
+        name: m.name,
+        role: m.role,
+        active: m.active,
+        tags: m.tags
+      }))
+    };
+  }
+  /** Import policy from object */
+  importPolicy(data, importedBy) {
+    if (data.settings) {
+      Object.assign(this.policySet.settings, data.settings);
+    }
+    if (data.members) {
+      for (const member of data.members) {
+        if (!this.policySet.members.find((m) => m.id === member.id)) {
+          this.addMember(member);
+        }
+      }
+    }
+    return this.createVersion(
+      importedBy,
+      "Imported policy",
+      data.rules,
+      data.roles
+    );
+  }
+  /** Export as JSON string */
+  toJSON() {
+    return JSON.stringify(this.exportPolicy(), null, 2);
+  }
+  // ─── Getters ───────────────────────────────────────────────────────────
+  get name() {
+    return this.policySet.name;
+  }
+  get settings() {
+    return { ...this.policySet.settings };
+  }
+  get memberCount() {
+    return this.policySet.members.filter((m) => m.active).length;
+  }
+  get versionCount() {
+    return this.policySet.versions.length;
+  }
+  // ─── Private ─────────────────────────────────────────────────────────────
+  flattenDefaultRules() {
+    const allRules = [];
+    for (const [, rules] of Object.entries(DEFAULT_ROLE_RULES)) {
+      for (const rule of rules) {
+        if (!allRules.find((r) => r.id === rule.id)) {
+          allRules.push(rule);
+        }
+      }
+    }
+    return allRules;
+  }
+  generateRoleRules(rules) {
+    const result = {
+      admin: [],
+      lead: [],
+      developer: [],
+      viewer: [],
+      custom: []
+    };
+    result.admin = rules.map((r) => r.id);
+    for (const role of ["lead", "developer", "viewer"]) {
+      const defaultIds = DEFAULT_ROLE_RULES[role].map((r) => r.id);
+      const customIds = rules.filter((r) => !Object.values(DEFAULT_ROLE_RULES).flat().find((dr) => dr.id === r.id)).map((r) => r.id);
+      result[role] = [...defaultIds, ...customIds];
+    }
+    return result;
+  }
+  getInheritedRuleIds(role, roleRules) {
+    const ruleIds = /* @__PURE__ */ new Set();
+    const ownRules = roleRules[role] ?? [];
+    for (const id of ownRules) ruleIds.add(id);
+    const roleLevel = ROLE_HIERARCHY[role];
+    for (const [r, level] of Object.entries(ROLE_HIERARCHY)) {
+      if (level < roleLevel) {
+        const lowerRules = roleRules[r] ?? [];
+        for (const id of lowerRules) ruleIds.add(id);
+      }
+    }
+    return [...ruleIds];
+  }
+  matchesTool(toolName, patterns) {
+    for (const pattern of patterns) {
+      if (pattern === "*") return true;
+      if (pattern.endsWith("*")) {
+        if (toolName.startsWith(pattern.slice(0, -1))) return true;
+      } else if (pattern.startsWith("*")) {
+        if (toolName.endsWith(pattern.slice(1))) return true;
+      } else if (pattern === toolName) {
+        return true;
+      }
+    }
+    return false;
+  }
+  matchesConditions(conditions, context) {
+    if (!conditions || conditions.length === 0) return true;
+    for (const condition of conditions) {
+      let fieldValue;
+      switch (condition.field) {
+        case "risk_score":
+          fieldValue = context.riskScore;
+          break;
+        case "time_of_day":
+          fieldValue = (/* @__PURE__ */ new Date()).getHours();
+          break;
+        case "day_of_week":
+          fieldValue = (/* @__PURE__ */ new Date()).getDay();
+          break;
+        default:
+          fieldValue = void 0;
+      }
+      if (fieldValue === void 0) continue;
+      if (!this.evaluateCondition(fieldValue, condition.operator, condition.value)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  evaluateCondition(fieldValue, operator, conditionValue) {
+    switch (operator) {
+      case "eq":
+        return fieldValue === conditionValue;
+      case "neq":
+        return fieldValue !== conditionValue;
+      case "gt":
+        return fieldValue > conditionValue;
+      case "lt":
+        return fieldValue < conditionValue;
+      case "gte":
+        return fieldValue >= conditionValue;
+      case "lte":
+        return fieldValue <= conditionValue;
+      case "contains":
+        return String(fieldValue).includes(String(conditionValue));
+      case "matches":
+        return new RegExp(String(conditionValue)).test(String(fieldValue));
+      case "in":
+        return Array.isArray(conditionValue) && conditionValue.includes(String(fieldValue));
+      default:
+        return false;
+    }
+  }
+  resolveConflict(decisions) {
+    if (decisions.length === 0) return this.policySet.settings.defaultAction;
+    switch (this.policySet.settings.conflictResolution) {
+      case "most-restrictive": {
+        const restrictiveness = {
+          "block": 100,
+          "require-approval": 75,
+          "transform": 50,
+          "log-only": 25,
+          "allow": 0
+        };
+        return decisions.reduce(
+          (most, d) => (restrictiveness[d.action] ?? 0) > (restrictiveness[most.action] ?? 0) ? d : most
+        ).action;
+      }
+      case "least-restrictive": {
+        const permissiveness = {
+          "allow": 100,
+          "log-only": 75,
+          "transform": 50,
+          "require-approval": 25,
+          "block": 0
+        };
+        return decisions.reduce(
+          (least, d) => (permissiveness[d.action] ?? 0) > (permissiveness[least.action] ?? 0) ? d : least
+        ).action;
+      }
+      case "priority-based":
+      default:
+        return decisions.sort((a, b) => b.priority - a.priority)[0].action;
+    }
+  }
+  computeHash(rules) {
+    const str = JSON.stringify(rules);
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash |= 0;
+    }
+    return `v${Math.abs(hash).toString(16).padStart(8, "0")}`;
+  }
+};
+function createTeamPolicyManager(name, settings) {
+  return new TeamPolicyManager(name, settings);
+}
+function createEnterprisePolicyManager(name) {
+  return new TeamPolicyManager(name, {
+    defaultAction: "block",
+    conflictResolution: "most-restrictive",
+    requireApprovalForChanges: true,
+    enableCanary: true,
+    canaryPercentage: 10
+  });
+}
+export {
+  TeamPolicyManager,
+  createEnterprisePolicyManager,
+  createTeamPolicyManager
+};

package/dist/toolReplacement.d.mts

@@ -0,0 +1,108 @@
+/**
+ * @sovr/proxy-mcp — Tool Replacement Mode (--mode=exclusive)
+ *
+ * Solves the FATAL bypass problem identified in Reddit feedback:
+ *   "The LLM isn't forced to route commands through your MCP server."
+ *
+ * Solution: Instead of adding SOVR as an *additional* MCP tool alongside
+ * the native Bash tool, SOVR *replaces* the native Bash tool entirely.
+ * The LLM has no choice — every command goes through SOVR.
+ *
+ * How it works:
+ *   1. SOVR proxy intercepts the MCP `tools/list` response from upstream
+ *   2. In exclusive mode, it REMOVES dangerous native tools (Bash, shell, etc.)
+ *   3. It INJECTS SOVR-wrapped equivalents that enforce policy checks
+ *   4. When the LLM calls the SOVR tool, the proxy evaluates the command,
+ *      then either forwards to the real tool or blocks it
+ *
+ * Supported modes:
+ *   - "monitor"   (default) — Log all tool calls, allow everything
+ *   - "advisory"  — Log + warn on risky calls, but allow
+ *   - "enforce"   — Block risky calls, allow safe ones
+ *   - "exclusive" — Replace native tools entirely, ALL calls go through SOVR
+ *
+ * @example
+ * ```
+ * # Start proxy in exclusive mode (recommended for production)
+ * npx sovr-mcp-proxy --upstream "..." --mode=exclusive
+ *
+ * # Start proxy in enforce mode (less intrusive)
+ * npx sovr-mcp-proxy --upstream "..." --mode=enforce
+ * ```
+ */
+type ProxyMode = 'monitor' | 'advisory' | 'enforce' | 'exclusive';
+/** Tools that are considered dangerous and should be replaced in exclusive mode */
+interface ToolReplacementConfig {
+    /** Proxy enforcement mode */
+    mode: ProxyMode;
+    /** Tool names to intercept/replace (glob patterns supported) */
+    targetTools: string[];
+    /** Custom tool descriptions for replaced tools */
+    toolDescriptions?: Record<string, string>;
+    /** Whether to add a SOVR status tool */
+    addStatusTool: boolean;
+    /** Whether to add a SOVR audit tool */
+    addAuditTool: boolean;
+}
+/** MCP Tool definition (from MCP spec) */
+interface McpToolDef {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: 'object';
+        properties?: Record<string, unknown>;
+        required?: string[];
+        [key: string]: unknown;
+    };
+}
+/** Result of tool list transformation */
+interface ToolListTransformResult {
+    /** The transformed tool list */
+    tools: McpToolDef[];
+    /** Tools that were removed */
+    removedTools: string[];
+    /** Tools that were added by SOVR */
+    addedTools: string[];
+    /** Tools that were wrapped (kept but intercepted) */
+    wrappedTools: string[];
+}
+/**
+ * Default dangerous tool patterns that should be replaced in exclusive mode.
+ * These are the native tools that AI coding agents typically have access to.
+ */
+declare const DEFAULT_TARGET_TOOLS: string[];
+declare const DEFAULT_TOOL_REPLACEMENT_CONFIG: ToolReplacementConfig;
+/**
+ * Transform the upstream MCP server's tool list based on the proxy mode.
+ *
+ * In exclusive mode:
+ *   - Removes ALL native execution tools (Bash, shell, etc.)
+ *   - Injects SOVR-wrapped equivalents
+ *   - The LLM literally cannot bypass SOVR because the native tools don't exist
+ *
+ * In enforce mode:
+ *   - Keeps native tools but wraps them with SOVR interception
+ *   - Adds SOVR tools alongside native ones
+ *
+ * In advisory/monitor mode:
+ *   - Keeps all native tools unchanged
+ *   - Adds SOVR tools for optional use
+ */
+declare function transformToolList(upstreamTools: McpToolDef[], config: ToolReplacementConfig): ToolListTransformResult;
+/**
+ * Determine if a tool call should be intercepted based on the proxy mode.
+ */
+declare function shouldIntercept(toolName: string, config: ToolReplacementConfig): {
+    intercept: boolean;
+    reason: string;
+};
+/**
+ * Generate a human-readable summary of the tool replacement configuration.
+ */
+declare function describeMode(config: ToolReplacementConfig): string;
+/**
+ * Parse mode from CLI argument string.
+ */
+declare function parseMode(input: string): ProxyMode;
+
+export { DEFAULT_TARGET_TOOLS, DEFAULT_TOOL_REPLACEMENT_CONFIG, type McpToolDef, type ProxyMode, type ToolListTransformResult, type ToolReplacementConfig, describeMode, parseMode, shouldIntercept, transformToolList };