@gotgenes/pi-permission-system 12.0.0 → 13.1.0

package/test/path-utils.test.ts

@@ -23,12 +23,14 @@ vi.mock("node:fs", () => ({
 import {
   canonicalNormalizePathForComparison,
   getPathBearingToolPath,
+  getPathPolicyValues,
   getToolInputPath,
   isPathOutsideWorkingDirectory,
   isPathWithinDirectory,
   isPiInfrastructureRead,
   isSafeSystemPath,
   normalizePathForComparison,
+  normalizePathPolicyLiteral,
   PATH_BEARING_TOOLS,
   READ_ONLY_PATH_BEARING_TOOLS,
   SAFE_SYSTEM_PATHS,
@@ -542,3 +544,73 @@ describe("isPiInfrastructureRead", () => {
     ).toBe(false);
   });
 });
+
+describe("normalizePathPolicyLiteral", () => {
+  test("returns a relative token unchanged", () => {
+    expect(normalizePathPolicyLiteral("src/foo.ts")).toBe("src/foo.ts");
+  });
+
+  test("trims and strips simple wrapping quotes", () => {
+    expect(normalizePathPolicyLiteral("  'src/foo.ts'  ")).toBe("src/foo.ts");
+    expect(normalizePathPolicyLiteral('"a/b"')).toBe("a/b");
+  });
+
+  test("strips a leading @ prefix", () => {
+    expect(normalizePathPolicyLiteral("@src/foo.ts")).toBe("src/foo.ts");
+  });
+
+  test("expands ~ to the home directory", () => {
+    expect(normalizePathPolicyLiteral("~/docs/readme.md")).toBe(
+      join("/mock/home", "docs/readme.md"),
+    );
+  });
+
+  test("does not resolve a relative value against any cwd", () => {
+    expect(normalizePathPolicyLiteral("foo.ts")).toBe("foo.ts");
+  });
+
+  test("returns empty string for blank input", () => {
+    expect(normalizePathPolicyLiteral("   ")).toBe("");
+  });
+
+  test("preserves the surface catch-all", () => {
+    expect(normalizePathPolicyLiteral("*")).toBe("*");
+  });
+});
+
+describe("getPathPolicyValues", () => {
+  const cwd = "/projects/my-app";
+
+  test("returns only the literal when no base is available", () => {
+    expect(getPathPolicyValues("src/foo.ts")).toEqual(["src/foo.ts"]);
+    expect(getPathPolicyValues("src/foo.ts", {})).toEqual(["src/foo.ts"]);
+  });
+
+  test("adds absolute and project-relative aliases for a relative token", () => {
+    expect(getPathPolicyValues("src/foo.ts", { cwd })).toEqual([
+      "/projects/my-app/src/foo.ts",
+      "src/foo.ts",
+    ]);
+  });
+
+  test("omits the relative alias for a token outside cwd", () => {
+    expect(getPathPolicyValues("/etc/hosts", { cwd })).toEqual(["/etc/hosts"]);
+  });
+
+  test("resolves against resolveBase while aliasing relative to cwd", () => {
+    expect(
+      getPathPolicyValues("foo.txt", {
+        cwd,
+        resolveBase: "/projects/my-app/nested",
+      }),
+    ).toEqual(["/projects/my-app/nested/foo.txt", "nested/foo.txt", "foo.txt"]);
+  });
+
+  test("preserves the surface catch-all", () => {
+    expect(getPathPolicyValues("*", { cwd })).toEqual(["*"]);
+  });
+
+  test("returns empty for blank input", () => {
+    expect(getPathPolicyValues("   ", { cwd })).toEqual([]);
+  });
+});

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

@@ -1245,6 +1245,71 @@ describe("cross-cutting path surface", () => {
     }
   });
 
+  // ── Deny-with-reason ────────────────────────────────────────────────────
+
+  it("deny-with-reason: reason threads through to PermissionCheckResult", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      bash: { "npm *": { action: "deny", reason: "Use pnpm instead" } },
+    });
+    try {
+      const result = manager.checkPermission("bash", {
+        command: "npm install",
+      });
+      expect(result.state).toBe("deny");
+      expect(result.reason).toBe("Use pnpm instead");
+      expect(result.matchedPattern).toBe("npm *");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("deny-without-reason: reason is undefined in PermissionCheckResult", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      bash: { "rm -rf *": "deny" },
+    });
+    try {
+      const result = manager.checkPermission("bash", { command: "rm -rf /" });
+      expect(result.state).toBe("deny");
+      expect(result.reason).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("deny-with-reason on a non-bash surface", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: {
+        "*.env": {
+          action: "deny",
+          reason: "Environment files contain secrets",
+        },
+      },
+    });
+    try {
+      const result = manager.checkPermission("read", { path: ".env" });
+      expect(result.state).toBe("deny");
+      expect(result.reason).toBe("Environment files contain secrets");
+      expect(result.matchedPattern).toBe("*.env");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("non-string reason falls through to the default (malformed config)", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      bash: { "npm *": { action: "deny", reason: 42 } },
+    });
+    try {
+      const result = manager.checkPermission("bash", {
+        command: "npm install",
+      });
+      expect(result.state).toBe("ask");
+      expect(result.reason).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
   // ── Last-match-wins ordering ────────────────────────────────────────────
 
   it("last-match-wins: catch-all after deny overrides the deny", () => {
@@ -3081,3 +3146,137 @@ test("getResolvedPolicyPaths returns false for missing files and null for absent
     rmSync(tempDir, { recursive: true, force: true });
   }
 });
+
+describe("checkPermission — cwd-aware path policy values", () => {
+  const cwd = "/workspace/project";
+
+  it("matches a relative read input against an absolute allowlist", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: { "*": "ask", [`${cwd}/*`]: "allow" },
+    });
+    try {
+      manager.configureForCwd(cwd);
+      const result = manager.checkPermission("read", { path: "src/App.jsx" });
+      expect(result.state).toBe("allow");
+      expect(result.matchedPattern).toBe(`${cwd}/*`);
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("keeps legacy relative path rules working after configureForCwd", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: { "*": "allow", "src/*": "deny" },
+    });
+    try {
+      manager.configureForCwd(cwd);
+      const result = manager.checkPermission("read", { path: "src/App.jsx" });
+      expect(result.state).toBe("deny");
+      expect(result.matchedPattern).toBe("src/*");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("preserves last-match-wins across absolute and relative aliases", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: {
+        "*": "ask",
+        [`${cwd}/*`]: "allow",
+        "src/*": "deny",
+      },
+    });
+    try {
+      manager.configureForCwd(cwd);
+      const result = manager.checkPermission("read", { path: "src/App.jsx" });
+      // The later "src/*" deny wins over the earlier absolute allow.
+      expect(result.state).toBe("deny");
+      expect(result.matchedPattern).toBe("src/*");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("matches the cross-cutting path surface against absolute allowlists", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*": "ask", [`${cwd}/*`]: "allow" },
+    });
+    try {
+      manager.configureForCwd(cwd);
+      const result = manager.checkPermission("path", { path: "src/App.jsx" });
+      expect(result.state).toBe("allow");
+      expect(result.matchedPattern).toBe(`${cwd}/*`);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("checkPathPolicy", () => {
+  const cwd = "/workspace/project";
+
+  it("evaluates precomputed policy values against the path surface", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*": "ask", [`${cwd}/*`]: "allow" },
+    });
+    try {
+      const result = manager.checkPathPolicy([
+        `${cwd}/src/App.jsx`,
+        "src/App.jsx",
+      ]);
+      expect(result.state).toBe("allow");
+      expect(result.matchedPattern).toBe(`${cwd}/*`);
+      expect(result.source).toBe("special");
+      expect(result.toolName).toBe("path");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("preserves last-match-wins across the provided aliases", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*": "ask", [`${cwd}/*`]: "allow", "src/*": "deny" },
+    });
+    try {
+      const result = manager.checkPathPolicy([
+        `${cwd}/src/App.jsx`,
+        "src/App.jsx",
+      ]);
+      expect(result.state).toBe("deny");
+      expect(result.matchedPattern).toBe("src/*");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("applies session rules over config", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*": "ask", "src/*": "deny" },
+    });
+    try {
+      const sessionRules: Ruleset = [sessionAllow("path", "src/*")];
+      const result = manager.checkPathPolicy(
+        ["src/App.jsx"],
+        undefined,
+        sessionRules,
+      );
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("session");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("falls back to the catch-all for an empty value list", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      path: { "*": "deny" },
+    });
+    try {
+      const result = manager.checkPathPolicy([]);
+      expect(result.state).toBe("deny");
+      expect(result.matchedPattern).toBe("*");
+    } finally {
+      cleanup();
+    }
+  });
+});

package/test/permission-resolver.test.ts

@@ -24,6 +24,20 @@ function makePermissionManager() {
         source: "tool",
         origin: "builtin",
       }),
+    checkPathPolicy: vi
+      .fn<
+        (
+          values: readonly string[],
+          agentName?: string,
+          sessionRules?: Ruleset,
+        ) => PermissionCheckResult
+      >()
+      .mockReturnValue({
+        state: "allow",
+        toolName: "path",
+        source: "special",
+        origin: "builtin",
+      }),
     getToolPermission: vi
       .fn<(toolName: string, agentName?: string) => PermissionState>()
       .mockReturnValue("allow"),
@@ -119,6 +133,61 @@ describe("PermissionResolver", () => {
     });
   });
 
+  describe("resolvePathPolicy", () => {
+    it("forwards values and agentName with the current session ruleset", () => {
+      const { resolver, permissionManager } = makeResolver();
+
+      resolver.resolvePathPolicy(["/proj/src/a.ts", "src/a.ts"], "agent-x");
+
+      expect(permissionManager.checkPathPolicy).toHaveBeenCalledWith(
+        ["/proj/src/a.ts", "src/a.ts"],
+        "agent-x",
+        [],
+      );
+    });
+
+    it("applies a recorded session approval on the next call", () => {
+      const pm = makePermissionManager();
+      const sessionRules = new SessionRules();
+      const { resolver } = makeResolver(pm, sessionRules);
+
+      sessionRules.recordSessionApproval(
+        SessionApproval.single("path", "src/*"),
+      );
+      resolver.resolvePathPolicy(["src/a.ts"]);
+
+      const passedRules = vi.mocked(pm.checkPathPolicy).mock.calls[0][2];
+      expect(passedRules).toHaveLength(1);
+      expect(passedRules?.[0]).toMatchObject({
+        surface: "path",
+        pattern: "src/*",
+        action: "allow",
+      });
+    });
+
+    it("returns the PermissionManager's check result", () => {
+      const pm = makePermissionManager();
+      vi.mocked(pm.checkPathPolicy).mockReturnValue({
+        state: "deny",
+        toolName: "path",
+        source: "special",
+        origin: "global",
+        matchedPattern: "src/*",
+      });
+      const { resolver } = makeResolver(pm);
+
+      const result = resolver.resolvePathPolicy(["src/a.ts"]);
+
+      expect(result).toEqual({
+        state: "deny",
+        toolName: "path",
+        source: "special",
+        origin: "global",
+        matchedPattern: "src/*",
+      });
+    });
+  });
+
   describe("checkPermission", () => {
     it("delegates to permissionManager.checkPermission with the given args", () => {
       const { resolver, permissionManager } = makeResolver();

package/test/rule.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, test } from "vitest";
 import type { Rule, RuleOrigin, Ruleset } from "#src/rule";
-import { evaluate, evaluateFirst, evaluateMostRestrictive } from "#src/rule";
+import {
+  evaluate,
+  evaluateAnyValue,
+  evaluateFirst,
+  evaluateMostRestrictive,
+} from "#src/rule";
 
 describe("evaluate", () => {
   const allowBashGit: Rule = {
@@ -211,6 +216,67 @@ describe("evaluate", () => {
     expect(result.origin).toBe("builtin");
   });
 
+  test("evaluate() propagates reason from the matched deny rule", () => {
+    const rule: Rule = {
+      surface: "bash",
+      pattern: "npm *",
+      action: "deny",
+      reason: "Use pnpm instead",
+      layer: "config",
+      origin: "global",
+    };
+    const result = evaluate("bash", "npm install", [rule]);
+    expect(result.action).toBe("deny");
+    expect(result.reason).toBe("Use pnpm instead");
+  });
+
+  test("evaluate() carries reason through last-match-wins when deny wins", () => {
+    const allowAll: Rule = {
+      surface: "bash",
+      pattern: "*",
+      action: "allow",
+      layer: "config",
+      origin: "global",
+    };
+    const denyNpm: Rule = {
+      surface: "bash",
+      pattern: "npm *",
+      action: "deny",
+      reason: "Use pnpm",
+      layer: "config",
+      origin: "global",
+    };
+    const result = evaluate("bash", "npm install", [allowAll, denyNpm]);
+    expect(result.action).toBe("deny");
+    expect(result.reason).toBe("Use pnpm");
+  });
+
+  test("evaluate() drops reason when a later allow overrides the deny", () => {
+    const denyNpm: Rule = {
+      surface: "bash",
+      pattern: "npm *",
+      action: "deny",
+      reason: "Use pnpm",
+      layer: "config",
+      origin: "global",
+    };
+    const allowInstall: Rule = {
+      surface: "bash",
+      pattern: "npm install",
+      action: "allow",
+      layer: "config",
+      origin: "global",
+    };
+    const result = evaluate("bash", "npm install", [denyNpm, allowInstall]);
+    expect(result.action).toBe("allow");
+    expect(result.reason).toBeUndefined();
+  });
+
+  test("evaluate() synthetic fallback rule has no reason", () => {
+    const result = evaluate("bash", "npm install", []);
+    expect(result.reason).toBeUndefined();
+  });
+
   test("RuleOrigin covers all seven provenance values", () => {
     const origins: RuleOrigin[] = [
       "global",
@@ -393,6 +459,74 @@ describe("evaluateFirst", () => {
   });
 });
 
+describe("evaluateAnyValue", () => {
+  const catchAllAllow: Rule = {
+    surface: "path",
+    pattern: "*",
+    action: "allow",
+    layer: "config",
+    origin: "global",
+  };
+  const catchAllAsk: Rule = {
+    surface: "path",
+    pattern: "*",
+    action: "ask",
+    layer: "config",
+    origin: "global",
+  };
+  const relativeDeny: Rule = {
+    surface: "path",
+    pattern: "src/*",
+    action: "deny",
+    layer: "config",
+    origin: "global",
+  };
+  const absoluteAllow: Rule = {
+    surface: "path",
+    pattern: "/proj/*",
+    action: "allow",
+    layer: "config",
+    origin: "global",
+  };
+
+  test("a later relative rule wins over a catch-all matched by another alias", () => {
+    const rules: Ruleset = [catchAllAllow, relativeDeny];
+    const result = evaluateAnyValue(
+      "path",
+      ["/proj/src/foo.ts", "src/foo.ts"],
+      rules,
+    );
+    expect(result.rule).toEqual(relativeDeny);
+    expect(result.value).toBe("src/foo.ts");
+  });
+
+  test("uses an absolute alias when no later relative rule matches", () => {
+    const rules: Ruleset = [catchAllAsk, absoluteAllow];
+    const result = evaluateAnyValue(
+      "path",
+      ["/proj/src/foo.ts", "src/foo.ts"],
+      rules,
+    );
+    expect(result.rule).toEqual(absoluteAllow);
+    expect(result.value).toBe("/proj/src/foo.ts");
+  });
+
+  test("falls back to the first value's default when no rule matches", () => {
+    const result = evaluateAnyValue(
+      "path",
+      ["/proj/src/foo.ts", "src/foo.ts"],
+      [],
+    );
+    expect(result.rule.action).toBe("ask");
+    expect(result.value).toBe("/proj/src/foo.ts");
+  });
+
+  test("uses '*' as fallback value when values array is empty", () => {
+    const result = evaluateAnyValue("path", [], []);
+    expect(result.value).toBe("*");
+  });
+});
+
 describe("evaluateMostRestrictive", () => {
   const denyEnv: Rule = {
     surface: "path",