@gotgenes/pi-permission-system 4.4.1 → 4.6.0

package/tests/mcp-targets.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from "vitest";
+import {
+  createMcpPermissionTargets,
+  parseQualifiedMcpToolName,
+} from "../src/mcp-targets";
+
+describe("parseQualifiedMcpToolName", () => {
+  it("returns server and tool for a valid qualified name", () => {
+    expect(parseQualifiedMcpToolName("exa:search")).toEqual({
+      server: "exa",
+      tool: "search",
+    });
+  });
+
+  it("returns server and tool with surrounding whitespace trimmed", () => {
+    expect(parseQualifiedMcpToolName("  exa : search  ")).toEqual({
+      server: "exa",
+      tool: "search",
+    });
+  });
+
+  it("returns null for empty string", () => {
+    expect(parseQualifiedMcpToolName("")).toBeNull();
+  });
+
+  it("returns null for whitespace-only string", () => {
+    expect(parseQualifiedMcpToolName("   ")).toBeNull();
+  });
+
+  it("returns null when colon is the first character", () => {
+    expect(parseQualifiedMcpToolName(":search")).toBeNull();
+  });
+
+  it("returns null when colon is the last character", () => {
+    expect(parseQualifiedMcpToolName("exa:")).toBeNull();
+  });
+
+  it("returns null for a plain tool name with no colon", () => {
+    expect(parseQualifiedMcpToolName("exa_search")).toBeNull();
+  });
+
+  it("returns null when server part is empty after trimming", () => {
+    expect(parseQualifiedMcpToolName(" :search")).toBeNull();
+  });
+
+  it("returns null when tool part is empty after trimming", () => {
+    expect(parseQualifiedMcpToolName("exa: ")).toBeNull();
+  });
+});
+
+describe("createMcpPermissionTargets", () => {
+  describe("tool call (input.tool)", () => {
+    it("produces targets for a bare tool name with no configured servers", () => {
+      const targets = createMcpPermissionTargets({ tool: "exa_search" }, []);
+      expect(targets).toContain("exa_search");
+      expect(targets).toContain("mcp_call");
+    });
+
+    it("produces targets for a qualified tool name (server:tool)", () => {
+      const targets = createMcpPermissionTargets({ tool: "exa:search" }, []);
+      expect(targets).toContain("exa_search");
+      expect(targets).toContain("exa:search");
+      expect(targets).toContain("exa");
+      expect(targets).toContain("mcp_call");
+    });
+
+    it("produces targets for a tool call with explicit server field", () => {
+      const targets = createMcpPermissionTargets(
+        { tool: "search", server: "exa" },
+        [],
+      );
+      expect(targets).toContain("exa_search");
+      expect(targets).toContain("exa:search");
+      expect(targets).toContain("exa");
+      expect(targets).toContain("mcp_call");
+    });
+
+    it("derives server targets from configured server names when tool name ends with _<server>", () => {
+      const targets = createMcpPermissionTargets({ tool: "exa_search" }, [
+        "exa",
+      ]);
+      // exa_search ends with _exa? No — it ends with _search. This tool name
+      // does NOT trigger server derivation because it does not end with _exa.
+      expect(targets).toContain("exa_search");
+    });
+
+    it("does not include duplicate entries", () => {
+      const targets = createMcpPermissionTargets({ tool: "exa:search" }, [
+        "exa",
+      ]);
+      const unique = [...new Set(targets)];
+      expect(targets).toEqual(unique);
+    });
+  });
+
+  describe("connect call (input.connect)", () => {
+    it("produces targets for a connect operation", () => {
+      const targets = createMcpPermissionTargets({ connect: "exa" }, []);
+      expect(targets).toContain("mcp_connect_exa");
+      expect(targets).toContain("exa");
+      expect(targets).toContain("mcp_connect");
+    });
+
+    it("does not include mcp_call for connect operations", () => {
+      const targets = createMcpPermissionTargets({ connect: "exa" }, []);
+      expect(targets).not.toContain("mcp_call");
+    });
+  });
+
+  describe("describe operation (input.describe)", () => {
+    it("produces targets for a describe operation on a qualified tool", () => {
+      const targets = createMcpPermissionTargets(
+        { describe: "exa:search" },
+        [],
+      );
+      expect(targets).toContain("exa_search");
+      expect(targets).toContain("exa:search");
+      expect(targets).toContain("exa");
+      expect(targets).toContain("mcp_describe");
+    });
+  });
+
+  describe("search operation (input.search)", () => {
+    it("produces mcp_search and the search string as targets", () => {
+      const targets = createMcpPermissionTargets({ search: "weather" }, []);
+      expect(targets).toContain("weather");
+      expect(targets).toContain("mcp_search");
+    });
+
+    it("includes server targets when server is provided alongside search", () => {
+      const targets = createMcpPermissionTargets(
+        { search: "weather", server: "exa" },
+        [],
+      );
+      expect(targets).toContain("mcp_server_exa");
+      expect(targets).toContain("exa");
+      expect(targets).toContain("mcp_search");
+    });
+  });
+
+  describe("server listing (input.server only)", () => {
+    it("produces mcp_list and server-specific targets", () => {
+      const targets = createMcpPermissionTargets({ server: "exa" }, []);
+      expect(targets).toContain("mcp_server_exa");
+      expect(targets).toContain("exa");
+      expect(targets).toContain("mcp_list");
+    });
+  });
+
+  describe("status (no meaningful input)", () => {
+    it("produces mcp_status for empty input", () => {
+      const targets = createMcpPermissionTargets({}, []);
+      expect(targets).toContain("mcp_status");
+    });
+
+    it("produces mcp_status for null input", () => {
+      const targets = createMcpPermissionTargets(null, []);
+      expect(targets).toContain("mcp_status");
+    });
+
+    it("produces mcp_status when no server/tool/connect/describe/search present", () => {
+      const targets = createMcpPermissionTargets({ unrelated: "value" }, [
+        "exa",
+      ]);
+      expect(targets).toContain("mcp_status");
+    });
+  });
+
+  describe("priority ordering", () => {
+    it("tool targets appear before mcp_call", () => {
+      const targets = createMcpPermissionTargets({ tool: "exa:search" }, []);
+      const mcpCallIdx = targets.indexOf("mcp_call");
+      const exaSearchIdx = targets.indexOf("exa_search");
+      expect(exaSearchIdx).toBeGreaterThanOrEqual(0);
+      expect(mcpCallIdx).toBeGreaterThan(exaSearchIdx);
+    });
+  });
+});

package/tests/permission-manager-unified.test.ts

@@ -0,0 +1,375 @@
+/**
+ * Integration tests verifying the unified checkPermission() path.
+ *
+ * Step 5: session rules concatenated into the composed ruleset.
+ * Step 6: all five surfaces produce identical decisions to the old branching code.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { PermissionManager } from "../src/permission-manager";
+import type { Rule, Ruleset } from "../src/rule";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Manager backed by a missing config file — universal default is "ask". */
+function makeManager(
+  mcpServerNames: readonly string[] = [],
+): PermissionManager {
+  return new PermissionManager({
+    globalConfigPath: "/nonexistent/config.json",
+    agentsDir: "/nonexistent/agents",
+    mcpServerNames: [...mcpServerNames],
+  });
+}
+
+/**
+ * Manager backed by a real on-disk config file written to a temp directory.
+ * Returns the manager and a cleanup function.
+ */
+function makeManagerWithConfig(
+  permission: Record<string, unknown>,
+  mcpServerNames: readonly string[] = [],
+): { manager: PermissionManager; cleanup: () => void } {
+  const baseDir = mkdtempSync(join(tmpdir(), "pm-unified-test-"));
+  const agentsDir = join(baseDir, "agents");
+  mkdirSync(agentsDir, { recursive: true });
+  const globalConfigPath = join(baseDir, "config.json");
+  writeFileSync(globalConfigPath, JSON.stringify({ permission }, null, 2));
+  const manager = new PermissionManager({
+    globalConfigPath,
+    agentsDir,
+    mcpServerNames: [...mcpServerNames],
+  });
+  return {
+    manager,
+    cleanup: () => rmSync(baseDir, { recursive: true, force: true }),
+  };
+}
+
+const sessionAllow = (surface: string, pattern: string): Rule => ({
+  surface,
+  pattern,
+  action: "allow",
+  layer: "session",
+});
+
+// ---------------------------------------------------------------------------
+// Step 5: session rules concatenated — wins over config/default
+// ---------------------------------------------------------------------------
+
+describe("checkPermission — session rules", () => {
+  it("session rule wins over the universal default (external_directory)", () => {
+    const manager = makeManager();
+    const sessionRules: Ruleset = [
+      sessionAllow("external_directory", "/other/project"),
+    ];
+    const result = manager.checkPermission(
+      "external_directory",
+      { path: "/other/project" },
+      undefined,
+      sessionRules,
+    );
+    expect(result.state).toBe("allow");
+    expect(result.source).toBe("session");
+    expect(result.matchedPattern).toBe("/other/project");
+  });
+
+  it("session rule wins over the universal default (skill)", () => {
+    const manager = makeManager();
+    const sessionRules: Ruleset = [sessionAllow("skill", "librarian")];
+    const result = manager.checkPermission(
+      "skill",
+      { name: "librarian" },
+      undefined,
+      sessionRules,
+    );
+    expect(result.state).toBe("allow");
+    expect(result.source).toBe("session");
+    expect(result.matchedPattern).toBe("librarian");
+  });
+
+  it("session rule wins over the universal default (bash)", () => {
+    const manager = makeManager();
+    const sessionRules: Ruleset = [sessionAllow("bash", "git status")];
+    const result = manager.checkPermission(
+      "bash",
+      { command: "git status" },
+      undefined,
+      sessionRules,
+    );
+    expect(result.state).toBe("allow");
+    expect(result.source).toBe("session");
+    expect(result.matchedPattern).toBe("git status");
+  });
+
+  it("session rule wins over the universal default (tool — read)", () => {
+    const manager = makeManager();
+    const sessionRules: Ruleset = [sessionAllow("read", "*")];
+    const result = manager.checkPermission("read", {}, undefined, sessionRules);
+    expect(result.state).toBe("allow");
+    expect(result.source).toBe("session");
+  });
+
+  it("session rule wins over the universal default (mcp)", () => {
+    const manager = makeManager();
+    const sessionRules: Ruleset = [sessionAllow("mcp", "mcp_status")];
+    const result = manager.checkPermission("mcp", {}, undefined, sessionRules);
+    expect(result.state).toBe("allow");
+    expect(result.source).toBe("session");
+  });
+
+  it("no session rules — falls through to default (ask)", () => {
+    const manager = makeManager();
+    const result = manager.checkPermission("read", {}, undefined, []);
+    expect(result.state).toBe("ask");
+    expect(result.source).not.toBe("session");
+  });
+
+  it("session rule with narrower pattern does not block a broader command not in session", () => {
+    const manager = makeManager();
+    // Only "git status" is session-approved; "git push" should fall through to default.
+    const sessionRules: Ruleset = [sessionAllow("bash", "git status")];
+    const result = manager.checkPermission(
+      "bash",
+      { command: "git push origin main" },
+      undefined,
+      sessionRules,
+    );
+    expect(result.state).toBe("ask");
+    expect(result.source).not.toBe("session");
+  });
+
+  it("session wildcard pattern matches multiple commands", () => {
+    const manager = makeManager();
+    const sessionRules: Ruleset = [sessionAllow("bash", "git *")];
+    const push = manager.checkPermission(
+      "bash",
+      { command: "git push origin main" },
+      undefined,
+      sessionRules,
+    );
+    const status = manager.checkPermission(
+      "bash",
+      { command: "git status" },
+      undefined,
+      sessionRules,
+    );
+    expect(push.state).toBe("allow");
+    expect(push.source).toBe("session");
+    expect(status.state).toBe("allow");
+    expect(status.source).toBe("session");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Step 6: source field and matchedPattern for all five surfaces
+// ---------------------------------------------------------------------------
+
+describe("checkPermission — source derivation and matchedPattern", () => {
+  describe("external_directory (special surface)", () => {
+    it("source is 'special' for a config-matched path", () => {
+      const { manager, cleanup } = makeManagerWithConfig({
+        "*": "ask",
+        external_directory: { "/trusted/*": "allow" },
+      });
+      try {
+        const result = manager.checkPermission("external_directory", {
+          path: "/trusted/repo",
+        });
+        expect(result.state).toBe("allow");
+        expect(result.source).toBe("special");
+        expect(result.matchedPattern).toBe("/trusted/*");
+      } finally {
+        cleanup();
+      }
+    });
+
+    it("source is 'special' even for a default match (no config rule)", () => {
+      const manager = makeManager();
+      const result = manager.checkPermission("external_directory", {
+        path: "/some/path",
+      });
+      expect(result.state).toBe("ask");
+      expect(result.source).toBe("special");
+      expect(result.matchedPattern).toBeUndefined();
+    });
+
+    it("matchedPattern is undefined for a default match", () => {
+      const manager = makeManager();
+      const result = manager.checkPermission("external_directory", {
+        path: "/unknown",
+      });
+      expect(result.matchedPattern).toBeUndefined();
+    });
+  });
+
+  describe("skill surface", () => {
+    it("source is 'skill' for a config-matched skill name", () => {
+      const { manager, cleanup } = makeManagerWithConfig({
+        "*": "ask",
+        skill: { librarian: "allow" },
+      });
+      try {
+        const result = manager.checkPermission("skill", { name: "librarian" });
+        expect(result.state).toBe("allow");
+        expect(result.source).toBe("skill");
+        expect(result.matchedPattern).toBe("librarian");
+      } finally {
+        cleanup();
+      }
+    });
+
+    it("source is 'skill' even for a default match", () => {
+      const manager = makeManager();
+      const result = manager.checkPermission("skill", { name: "unknown" });
+      expect(result.state).toBe("ask");
+      expect(result.source).toBe("skill");
+    });
+  });
+
+  describe("bash surface", () => {
+    it("source is 'bash' and command is included in result", () => {
+      const { manager, cleanup } = makeManagerWithConfig({
+        "*": "ask",
+        bash: { "git *": "allow" },
+      });
+      try {
+        const result = manager.checkPermission("bash", {
+          command: "git status",
+        });
+        expect(result.state).toBe("allow");
+        expect(result.source).toBe("bash");
+        expect(result.command).toBe("git status");
+        expect(result.matchedPattern).toBe("git *");
+      } finally {
+        cleanup();
+      }
+    });
+
+    it("source is 'bash' even for a default match, command is empty string", () => {
+      const manager = makeManager();
+      const result = manager.checkPermission("bash", {});
+      expect(result.source).toBe("bash");
+      expect(result.command).toBe("");
+      expect(result.matchedPattern).toBeUndefined();
+    });
+  });
+
+  describe("mcp surface", () => {
+    it("source is 'mcp' for a config-matched target", () => {
+      const { manager, cleanup } = makeManagerWithConfig(
+        { "*": "ask", mcp: { exa_search: "allow" } },
+        ["exa"],
+      );
+      try {
+        const result = manager.checkPermission("mcp", {
+          tool: "exa:search",
+          server: "exa",
+        });
+        expect(result.state).toBe("allow");
+        expect(result.source).toBe("mcp");
+        expect(result.matchedPattern).toBe("exa_search");
+        expect(result.target).toBeDefined();
+      } finally {
+        cleanup();
+      }
+    });
+
+    it("source is 'default' when all targets match only the synthesized default", () => {
+      const manager = makeManager();
+      const result = manager.checkPermission("mcp", { tool: "exa:search" });
+      expect(result.state).toBe("ask");
+      expect(result.source).toBe("default");
+      expect(result.matchedPattern).toBeUndefined();
+    });
+
+    it("target field is set for a matched mcp call", () => {
+      const { manager, cleanup } = makeManagerWithConfig(
+        { "*": "ask", mcp: { mcp_status: "allow" } },
+        [],
+      );
+      try {
+        const result = manager.checkPermission("mcp", {});
+        expect(result.target).toBeDefined();
+        expect(result.source).toBe("mcp");
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe("tool surfaces", () => {
+    it("built-in tool: source is always 'tool' (config match)", () => {
+      const { manager, cleanup } = makeManagerWithConfig({
+        "*": "ask",
+        read: "allow",
+      });
+      try {
+        const result = manager.checkPermission("read", {});
+        expect(result.state).toBe("allow");
+        expect(result.source).toBe("tool");
+      } finally {
+        cleanup();
+      }
+    });
+
+    it("built-in tool: source is 'tool' even for a default match", () => {
+      const manager = makeManager();
+      const result = manager.checkPermission("read", {});
+      expect(result.state).toBe("ask");
+      expect(result.source).toBe("tool");
+    });
+
+    it("extension tool: source is 'default' when no config rule matches", () => {
+      const manager = makeManager();
+      const result = manager.checkPermission("my_custom_tool", {});
+      expect(result.state).toBe("ask");
+      expect(result.source).toBe("default");
+    });
+
+    it("extension tool: source is 'tool' when a config rule matches", () => {
+      const { manager, cleanup } = makeManagerWithConfig({
+        "*": "ask",
+        my_custom_tool: "allow",
+      });
+      try {
+        const result = manager.checkPermission("my_custom_tool", {});
+        expect(result.state).toBe("allow");
+        expect(result.source).toBe("tool");
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe("matchedPattern for session rules across surfaces", () => {
+    it("matchedPattern is the session rule pattern for a session match (bash)", () => {
+      const manager = makeManager();
+      const sessionRules: Ruleset = [sessionAllow("bash", "git *")];
+      const result = manager.checkPermission(
+        "bash",
+        { command: "git status" },
+        undefined,
+        sessionRules,
+      );
+      expect(result.matchedPattern).toBe("git *");
+      expect(result.source).toBe("session");
+    });
+
+    it("matchedPattern is the session rule pattern for a session match (skill)", () => {
+      const manager = makeManager();
+      const sessionRules: Ruleset = [sessionAllow("skill", "librarian")];
+      const result = manager.checkPermission(
+        "skill",
+        { name: "librarian" },
+        undefined,
+        sessionRules,
+      );
+      expect(result.matchedPattern).toBe("librarian");
+    });
+  });
+});

package/tests/rule.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "vitest";
 import type { Rule, Ruleset } from "../src/rule";
-import { evaluate } from "../src/rule";
+import { evaluate, evaluateFirst } from "../src/rule";
 
 describe("evaluate", () => {
   const allowBashGit: Rule = {
@@ -169,3 +169,83 @@ describe("evaluate", () => {
     );
   });
 });
+
+describe("evaluateFirst", () => {
+  const defaultRule: Rule = {
+    surface: "*",
+    pattern: "*",
+    action: "ask",
+    layer: "default",
+  };
+  const allowBash: Rule = {
+    surface: "bash",
+    pattern: "git *",
+    action: "allow",
+    layer: "config",
+  };
+  const denyMcp: Rule = {
+    surface: "mcp",
+    pattern: "exa_search",
+    action: "deny",
+    layer: "config",
+  };
+
+  test("returns the first candidate that matches a non-default rule", () => {
+    const rules: Ruleset = [defaultRule, allowBash];
+    const result = evaluateFirst("bash", ["git status", "*"], rules);
+    expect(result.rule).toEqual(allowBash);
+    expect(result.value).toBe("git status");
+  });
+
+  test("skips candidates that only match the default rule", () => {
+    // "npm install" matches only the default; "*" also matches only the
+    // default — falls back to first candidate.
+    const rules: Ruleset = [defaultRule];
+    const result = evaluateFirst("bash", ["npm install", "*"], rules);
+    expect(result.rule.layer).toBe("default");
+    expect(result.value).toBe("npm install");
+  });
+
+  test("falls back to first candidate when all candidates match only the default", () => {
+    const rules: Ruleset = [defaultRule];
+    const result = evaluateFirst("bash", ["a", "b", "c"], rules);
+    expect(result.value).toBe("a");
+  });
+
+  test("stops at first non-default match, does not continue to remaining candidates", () => {
+    // "exa_search" matches denyMcp (non-default). The loop stops there;
+    // "mcp" is never evaluated even though it would match a different rule.
+    const allowMcpCatchAll: Rule = {
+      surface: "mcp",
+      pattern: "mcp",
+      action: "allow",
+      layer: "config",
+    };
+    const rules: Ruleset = [defaultRule, denyMcp, allowMcpCatchAll];
+    const result = evaluateFirst("mcp", ["exa_search", "mcp"], rules);
+    expect(result.rule).toEqual(denyMcp);
+    expect(result.value).toBe("exa_search");
+  });
+
+  test("skips candidates that match only the default and continues to next", () => {
+    // "unknown_tool" matches only the universal default;
+    // "exa_search" matches denyMcp (non-default) — that is the result.
+    const rules: Ruleset = [defaultRule, denyMcp];
+    const result = evaluateFirst("mcp", ["unknown_tool", "exa_search"], rules);
+    expect(result.rule).toEqual(denyMcp);
+    expect(result.value).toBe("exa_search");
+  });
+
+  test("single-candidate array behaves like evaluate()", () => {
+    const rules: Ruleset = [defaultRule, allowBash];
+    const result = evaluateFirst("bash", ["git status"], rules);
+    expect(result.rule).toEqual(allowBash);
+    expect(result.value).toBe("git status");
+  });
+
+  test("uses '*' as fallback value when values array is empty", () => {
+    const rules: Ruleset = [defaultRule];
+    const result = evaluateFirst("bash", [], rules);
+    expect(result.value).toBe("*");
+  });
+});