@gotgenes/pi-permission-system 5.16.0 → 5.18.0

package/tests/handlers/gates/path.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { GateDescriptor } from "../../../src/handlers/gates/descriptor";
+import { isGateDescriptor } from "../../../src/handlers/gates/descriptor";
+import { describePathGate } from "../../../src/handlers/gates/path";
+import type { ToolCallContext } from "../../../src/handlers/gates/types";
+import type { PermissionCheckResult } from "../../../src/types";
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
+  return {
+    toolName: "read",
+    agentName: null,
+    input: { path: ".env" },
+    toolCallId: "tc-1",
+    cwd: "/test/project",
+    ...overrides,
+  };
+}
+
+function makeCheckResult(
+  overrides: Partial<PermissionCheckResult> = {},
+): PermissionCheckResult {
+  return {
+    toolName: "path",
+    state: "allow",
+    source: "special",
+    origin: "global",
+    ...overrides,
+  };
+}
+
+type CheckPermissionFn = (
+  surface: string,
+  input: unknown,
+  agentName?: string,
+  sessionRules?: unknown[],
+) => PermissionCheckResult;
+
+// ── tests ──────────────────────────────────────────────────────────────────
+
+describe("describePathGate", () => {
+  it("returns null for non-path-bearing tools", () => {
+    const checkPermission = vi.fn<CheckPermissionFn>();
+    const result = describePathGate(
+      makeTcc({ toolName: "bash", input: { command: "ls" } }),
+      checkPermission,
+    );
+    expect(result).toBeNull();
+    expect(checkPermission).not.toHaveBeenCalled();
+  });
+
+  it("returns null when tool has no extractable path", () => {
+    const checkPermission = vi.fn<CheckPermissionFn>();
+    const result = describePathGate(
+      makeTcc({ toolName: "read", input: {} }),
+      checkPermission,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("returns null when path check result is allow", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "allow" }));
+    const result = describePathGate(makeTcc(), checkPermission);
+    expect(result).toBeNull();
+  });
+
+  it("returns GateDescriptor when path check result is deny", () => {
+    const checkPermission = vi.fn<CheckPermissionFn>().mockReturnValue(
+      makeCheckResult({
+        state: "deny",
+        matchedPattern: "*.env",
+      }),
+    );
+    const result = describePathGate(makeTcc(), checkPermission);
+    expect(result).not.toBeNull();
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    expect(desc.surface).toBe("path");
+    expect(desc.preCheck?.state).toBe("deny");
+  });
+
+  it("returns GateDescriptor when path check result is ask", () => {
+    const checkPermission = vi.fn<CheckPermissionFn>().mockReturnValue(
+      makeCheckResult({
+        state: "ask",
+        matchedPattern: "*.env",
+      }),
+    );
+    const result = describePathGate(makeTcc(), checkPermission);
+    expect(result).not.toBeNull();
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    expect(desc.surface).toBe("path");
+    expect(desc.preCheck?.state).toBe("ask");
+  });
+
+  it("descriptor has correct session approval surface and pattern", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "ask" }));
+    const result = describePathGate(
+      makeTcc({ input: { path: "/test/project/src/.env" } }),
+      checkPermission,
+    ) as GateDescriptor;
+    expect(result.sessionApproval).toBeDefined();
+    expect(result.sessionApproval).toHaveProperty("surface", "path");
+    expect(result.sessionApproval).toHaveProperty("pattern");
+  });
+
+  it("descriptor messages reference the file path", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "deny" }));
+    const result = describePathGate(
+      makeTcc(),
+      checkPermission,
+    ) as GateDescriptor;
+    expect(result.messages.denyReason).toContain(".env");
+    expect(result.messages.unavailableReason).toContain(".env");
+  });
+
+  it("descriptor decision uses surface 'path' and the file path as value", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "deny" }));
+    const result = describePathGate(
+      makeTcc(),
+      checkPermission,
+    ) as GateDescriptor;
+    expect(result.decision.surface).toBe("path");
+    expect(result.decision.value).toBe(".env");
+  });
+
+  it("passes agentName to checkPermission", () => {
+    const checkPermission = vi
+      .fn<CheckPermissionFn>()
+      .mockReturnValue(makeCheckResult({ state: "allow" }));
+    describePathGate(makeTcc({ agentName: "my-agent" }), checkPermission);
+    expect(checkPermission).toHaveBeenCalledWith(
+      "path",
+      { path: ".env" },
+      "my-agent",
+    );
+  });
+});

package/tests/handlers/tool-call.test.ts

@@ -297,3 +297,81 @@ describe("handleToolCall — bash external-directory gate", () => {
     expect(result).toMatchObject({ block: true });
   });
 });
+
+// ── path gate (tools) ─────────────────────────────────────────────────────
+
+describe("handleToolCall — path gate (tools)", () => {
+  it("blocks a read of .env when path surface denies *.env", async () => {
+    const checkPermission = vi
+      .fn()
+      .mockImplementation(
+        (surface: string, _input: unknown, _agentName?: string) => {
+          if (surface === "path") {
+            return makePermissionResult("deny");
+          }
+          return makePermissionResult("allow");
+        },
+      );
+    const { handler } = makeHandler({
+      session: { checkPermission },
+      toolRegistry: {
+        getAll: vi.fn().mockReturnValue([{ name: "read" }]),
+      },
+    });
+    const event = {
+      type: "tool_call",
+      toolCallId: "tc-path",
+      name: "read",
+      input: { path: ".env" },
+    };
+    const result = await handler.handleToolCall(event, makeCtx());
+    expect(result).toMatchObject({ block: true });
+  });
+
+  it("allows a read when path surface allows", async () => {
+    const { handler } = makeHandler({
+      toolRegistry: {
+        getAll: vi.fn().mockReturnValue([{ name: "read" }]),
+      },
+    });
+    const event = {
+      type: "tool_call",
+      toolCallId: "tc-path-ok",
+      name: "read",
+      input: { path: "src/index.ts" },
+    };
+    const result = await handler.handleToolCall(event, makeCtx());
+    expect(result).toEqual({});
+  });
+});
+
+// ── bash path gate ────────────────────────────────────────────────────────
+
+describe("handleToolCall — bash path gate", () => {
+  it("blocks a bash command accessing .env when path surface denies", async () => {
+    const checkPermission = vi
+      .fn()
+      .mockImplementation(
+        (surface: string, _input: unknown, _agentName?: string) => {
+          if (surface === "path") {
+            return makePermissionResult("deny");
+          }
+          return makePermissionResult("allow");
+        },
+      );
+    const { handler } = makeHandler({
+      session: { checkPermission },
+      toolRegistry: {
+        getAll: vi.fn().mockReturnValue([{ name: "bash" }]),
+      },
+    });
+    const event = {
+      type: "tool_call",
+      toolCallId: "tc-bash-path",
+      name: "bash",
+      input: { command: "cat .env" },
+    };
+    const result = await handler.handleToolCall(event, makeCtx());
+    expect(result).toMatchObject({ block: true });
+  });
+});

package/tests/input-normalizer.test.ts

@@ -3,6 +3,30 @@ import { normalizeInput } from "../src/input-normalizer";
 import { createMcpPermissionTargets } from "../src/mcp-targets";
 
 describe("normalizeInput — non-MCP surfaces", () => {
+  describe("special / path", () => {
+    it("uses path from input as the lookup value", () => {
+      const result = normalizeInput("path", { path: ".env" }, []);
+      expect(result.surface).toBe("path");
+      expect(result.values).toEqual([".env"]);
+      expect(result.resultExtras).toEqual({});
+    });
+
+    it("falls back to '*' when path is missing", () => {
+      const result = normalizeInput("path", {}, []);
+      expect(result.values).toEqual(["*"]);
+    });
+
+    it("falls back to '*' when path is not a string", () => {
+      const result = normalizeInput("path", { path: 42 }, []);
+      expect(result.values).toEqual(["*"]);
+    });
+
+    it("handles null input", () => {
+      const result = normalizeInput("path", null, []);
+      expect(result.values).toEqual(["*"]);
+    });
+  });
+
   describe("special / external_directory", () => {
     it("uses path from input as the lookup value", () => {
       const result = normalizeInput(

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

@@ -1111,3 +1111,213 @@ describe("checkPermission — per-tool path patterns", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Cross-cutting path surface (#148)
+// ---------------------------------------------------------------------------
+
+describe("cross-cutting path surface", () => {
+  it("denies .env via the path surface", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*": "allow", "*.env": "deny" },
+      read: "allow",
+    });
+    try {
+      const result = manager.checkPermission("path", { path: ".env" });
+      expect(result.state).toBe("deny");
+      expect(result.matchedPattern).toBe("*.env");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("allows non-matching paths via the path surface", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*": "allow", "*.env": "deny" },
+      read: "allow",
+    });
+    try {
+      const result = manager.checkPermission("path", { path: "README.md" });
+      expect(result.state).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("path surface does not interfere with per-tool rules", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*": "allow" },
+      read: { "*": "allow", "*.secret": "deny" },
+    });
+    try {
+      // path surface allows, per-tool denies
+      const readResult = manager.checkPermission("read", {
+        path: "data.secret",
+      });
+      expect(readResult.state).toBe("deny");
+      // path surface also allows
+      const pathResult = manager.checkPermission("path", {
+        path: "data.secret",
+      });
+      expect(pathResult.state).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("getToolPermission('path') returns catch-all action", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*": "allow", "*.env": "deny" },
+    });
+    try {
+      const toolState = manager.getToolPermission("path");
+      expect(toolState).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("session approval on path surface overrides config deny", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*": "allow", "*.env": "deny" },
+    });
+    try {
+      const sessionRules: Ruleset = [sessionAllow("path", "/project/.env")];
+      const result = manager.checkPermission(
+        "path",
+        { path: "/project/.env" },
+        undefined,
+        sessionRules,
+      );
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("session");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("configs without path key behave identically (no path gate fires)", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: "allow",
+    });
+    try {
+      // path surface falls through to universal default
+      const result = manager.checkPermission("path", { path: ".env" });
+      expect(result.state).toBe("ask");
+    } finally {
+      cleanup();
+    }
+  });
+
+  // ── Last-match-wins ordering ────────────────────────────────────────────
+
+  it("last-match-wins: catch-all after deny overrides the deny", () => {
+    // Classic misconfiguration: deny is before allow, so allow wins.
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*.env": "deny", "*": "allow" },
+    });
+    try {
+      const result = manager.checkPermission("path", { path: ".env" });
+      // "*" is last and matches .env → allow (the deny is shadowed)
+      expect(result.state).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("last-match-wins: deny after catch-all blocks the path", () => {
+    // Correct ordering: catch-all first, specific deny after.
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*": "allow", "*.env": "deny" },
+    });
+    try {
+      const result = manager.checkPermission("path", { path: ".env" });
+      expect(result.state).toBe("deny");
+    } finally {
+      cleanup();
+    }
+  });
+
+  // ── .env.example override recipe ────────────────────────────────────────
+
+  it(".env.example override: denies .env and .env.local, allows .env.example", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: {
+        "*": "allow",
+        "*.env": "deny",
+        "*.env.*": "deny",
+        "*.env.example": "allow",
+      },
+    });
+    try {
+      expect(manager.checkPermission("path", { path: ".env" }).state).toBe(
+        "deny",
+      );
+      expect(
+        manager.checkPermission("path", { path: ".env.local" }).state,
+      ).toBe("deny");
+      expect(
+        manager.checkPermission("path", { path: ".env.production" }).state,
+      ).toBe("deny");
+      expect(manager.checkPermission("path", { path: "src/.env" }).state).toBe(
+        "deny",
+      );
+      expect(
+        manager.checkPermission("path", { path: ".env.example" }).state,
+      ).toBe("allow");
+      expect(manager.checkPermission("path", { path: "README.md" }).state).toBe(
+        "allow",
+      );
+    } finally {
+      cleanup();
+    }
+  });
+
+  // ── Universal fallback interaction ──────────────────────────────────────
+
+  it("universal '*': 'allow' with no path key makes the path gate transparent", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      "*": "allow",
+    });
+    try {
+      const result = manager.checkPermission("path", { path: ".env" });
+      expect(result.state).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("universal '*': 'deny' with no path key denies via path surface too", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      "*": "deny",
+    });
+    try {
+      const result = manager.checkPermission("path", { path: ".env" });
+      expect(result.state).toBe("deny");
+    } finally {
+      cleanup();
+    }
+  });
+
+  // ── Composition: path allows, per-tool denies ──────────────────────────
+
+  it("per-tool deny still blocks even when path surface allows", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*": "allow" },
+      read: "deny",
+    });
+    try {
+      // path gate passes (allow), but tool gate denies
+      const pathResult = manager.checkPermission("path", {
+        path: "secret.txt",
+      });
+      expect(pathResult.state).toBe("allow");
+      const readResult = manager.checkPermission("read", {
+        path: "secret.txt",
+      });
+      expect(readResult.state).toBe("deny");
+    } finally {
+      cleanup();
+    }
+  });
+});

package/tests/rule.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "vitest";
 import type { Rule, RuleOrigin, Ruleset } from "../src/rule";
-import { evaluate, evaluateFirst } from "../src/rule";
+import { evaluate, evaluateFirst, evaluateMostRestrictive } from "../src/rule";
 
 describe("evaluate", () => {
   const allowBashGit: Rule = {
@@ -317,3 +317,79 @@ describe("evaluateFirst", () => {
     expect(result.value).toBe("*");
   });
 });
+
+describe("evaluateMostRestrictive", () => {
+  const denyEnv: Rule = {
+    surface: "path",
+    pattern: "*.env",
+    action: "deny",
+    layer: "config",
+    origin: "global",
+  };
+  const askSsh: Rule = {
+    surface: "path",
+    pattern: "/home/user/.ssh/*",
+    action: "ask",
+    layer: "config",
+    origin: "global",
+  };
+  const allowAll: Rule = {
+    surface: "path",
+    pattern: "*",
+    action: "allow",
+    layer: "config",
+    origin: "global",
+  };
+
+  test("deny short-circuits: returns immediately without evaluating remaining values", () => {
+    const rules: Ruleset = [allowAll, denyEnv];
+    const result = evaluateMostRestrictive(
+      "path",
+      [".env", "README.md"],
+      rules,
+    );
+    expect(result).not.toBeNull();
+    expect(result!.rule.action).toBe("deny");
+    expect(result!.value).toBe(".env");
+  });
+
+  test("ask accumulates: returns first ask when no deny found", () => {
+    const rules: Ruleset = [allowAll, askSsh];
+    const result = evaluateMostRestrictive(
+      "path",
+      ["/home/user/.ssh/id_rsa", "README.md"],
+      rules,
+    );
+    expect(result).not.toBeNull();
+    expect(result!.rule.action).toBe("ask");
+    expect(result!.value).toBe("/home/user/.ssh/id_rsa");
+  });
+
+  test("all allow: returns null", () => {
+    const rules: Ruleset = [allowAll];
+    const result = evaluateMostRestrictive(
+      "path",
+      ["README.md", "src/index.ts"],
+      rules,
+    );
+    expect(result).toBeNull();
+  });
+
+  test("empty values: returns null", () => {
+    const rules: Ruleset = [allowAll, denyEnv];
+    const result = evaluateMostRestrictive("path", [], rules);
+    expect(result).toBeNull();
+  });
+
+  test("deny wins over ask", () => {
+    const rules: Ruleset = [allowAll, askSsh, denyEnv];
+    const result = evaluateMostRestrictive(
+      "path",
+      ["/home/user/.ssh/id_rsa", ".env"],
+      rules,
+    );
+    expect(result).not.toBeNull();
+    expect(result!.rule.action).toBe("deny");
+    expect(result!.value).toBe(".env");
+  });
+});