@gotgenes/pi-permission-system 11.0.0 → 13.0.0

package/test/helpers/gate-fixtures.ts

@@ -26,10 +26,13 @@ import { makeCheckResult } from "#test/helpers/handler-fixtures";
  */
 export function makeResolver(defaultCheck?: PermissionCheckResult) {
   const resolve = vi.fn<ScopedPermissionResolver["resolve"]>();
+  const resolvePathPolicy =
+    vi.fn<ScopedPermissionResolver["resolvePathPolicy"]>();
   if (defaultCheck) {
     resolve.mockReturnValue(defaultCheck);
+    resolvePathPolicy.mockReturnValue(defaultCheck);
   }
-  return { resolve };
+  return { resolve, resolvePathPolicy };
 }
 
 /**
@@ -92,6 +95,7 @@ export function makeGateRunner(
   overrides: {
     resolveResult?: PermissionCheckResult;
     resolve?: ScopedPermissionResolver["resolve"];
+    resolvePathPolicy?: ScopedPermissionResolver["resolvePathPolicy"];
     recordSessionApproval?: SessionApprovalRecorder["recordSessionApproval"];
     canConfirm?: GatePrompter["canConfirm"];
     prompt?: GatePrompter["prompt"];
@@ -106,6 +110,13 @@ export function makeGateRunner(
       .mockReturnValue(
         overrides.resolveResult ?? makeCheckResult({ matchedPattern: "*" }),
       );
+  const resolvePathPolicy =
+    overrides.resolvePathPolicy ??
+    vi
+      .fn<ScopedPermissionResolver["resolvePathPolicy"]>()
+      .mockReturnValue(
+        overrides.resolveResult ?? makeCheckResult({ matchedPattern: "*" }),
+      );
   const recordSessionApproval =
     overrides.recordSessionApproval ??
     (vi.fn() as SessionApprovalRecorder["recordSessionApproval"]);
@@ -118,7 +129,7 @@ export function makeGateRunner(
       .fn<GatePrompter["prompt"]>()
       .mockResolvedValue({ approved: true, state: "approved" });
   const runner = new GateRunner(
-    { resolve },
+    { resolve, resolvePathPolicy },
     { recordSessionApproval },
     { canConfirm, prompt },
     reporter,
@@ -127,6 +138,7 @@ export function makeGateRunner(
     runner,
     deps: {
       resolve,
+      resolvePathPolicy,
       recordSessionApproval,
       canConfirm,
       prompt,
@@ -212,7 +224,15 @@ export function makePathDispatchResolver(
     }
     return defaultResult;
   });
-  return { resolve };
+  const resolvePathPolicy =
+    vi.fn<ScopedPermissionResolver["resolvePathPolicy"]>();
+  resolvePathPolicy.mockImplementation((values) => {
+    for (const value of values) {
+      if (value in byPath) return byPath[value];
+    }
+    return defaultResult;
+  });
+  return { resolve, resolvePathPolicy };
 }
 
 /**

package/test/helpers/handler-fixtures.ts

@@ -236,9 +236,21 @@ export function makeHandler(overrides?: {
 
   // Apply session override bag to the real collaborators.
   const so = overrides?.session;
-  if (so?.checkPermission) {
+  const surfaceCheck = so?.checkPermission;
+  if (surfaceCheck) {
     vi.mocked(permissionManager.checkPermission).mockImplementation(
-      so.checkPermission,
+      surfaceCheck,
+    );
+    // The bash path gate resolves through checkPathPolicy; route it through
+    // the same surface dispatcher so `path` overrides apply to bash tokens.
+    vi.mocked(permissionManager.checkPathPolicy).mockImplementation(
+      (values, agentName, sessionRules) =>
+        surfaceCheck(
+          "path",
+          { path: values[0] ?? "*" },
+          agentName,
+          sessionRules,
+        ),
     );
   }
   if (so?.getActiveSkillEntries) {

package/test/helpers/session-fixtures.ts

@@ -102,6 +102,20 @@ export function makeFakePermissionManager() {
         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"),

package/test/input-normalizer.test.ts

@@ -68,6 +68,32 @@ describe("normalizeInput — non-MCP surfaces", () => {
       const result = normalizeInput("path", {}, []);
       expect(result.values).toEqual(["*"]);
     });
+
+    it("adds cwd-normalized and relative aliases when cwd is provided", () => {
+      const result = normalizeInput(
+        "path",
+        { path: "src/App.jsx" },
+        [],
+        "/workspace/project",
+      );
+      expect(result.values).toEqual([
+        "/workspace/project/src/App.jsx",
+        "src/App.jsx",
+      ]);
+    });
+
+    it("ignores a user-supplied string pathPolicyValues field", () => {
+      const result = normalizeInput(
+        "path",
+        { path: "src/App.jsx", pathPolicyValues: ["/etc/shadow"] },
+        [],
+        "/workspace/project",
+      );
+      expect(result.values).toEqual([
+        "/workspace/project/src/App.jsx",
+        "src/App.jsx",
+      ]);
+    });
   });
 
   describe("special / external_directory", () => {
@@ -119,6 +145,19 @@ describe("normalizeInput — non-MCP surfaces", () => {
       );
       expect(result.values).toEqual([join("/mock/home", "dev/project")]);
     });
+
+    it("adds cwd-normalized and relative aliases when cwd is provided", () => {
+      const result = normalizeInput(
+        "external_directory",
+        { path: "src/App.jsx" },
+        [],
+        "/workspace/project",
+      );
+      expect(result.values).toEqual([
+        "/workspace/project/src/App.jsx",
+        "src/App.jsx",
+      ]);
+    });
   });
 
   describe("skill", () => {
@@ -206,6 +245,19 @@ describe("normalizeInput — non-MCP surfaces", () => {
       const result = normalizeInput("write", { path: "$HOME/.ssh/config" }, []);
       expect(result.values).toEqual([join("/mock/home", ".ssh/config")]);
     });
+
+    it("adds cwd-normalized and relative aliases when cwd is provided", () => {
+      const result = normalizeInput(
+        "read",
+        { path: "src/App.jsx" },
+        [],
+        "/workspace/project",
+      );
+      expect(result.values).toEqual([
+        "/workspace/project/src/App.jsx",
+        "src/App.jsx",
+      ]);
+    });
   });
 
   describe("extension tools (non-path-bearing)", () => {

package/test/path-utils.test.ts

@@ -23,15 +23,19 @@ 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,
 } from "#src/path-utils";
+import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
 
 describe("normalizePathForComparison", () => {
   const cwd = "/projects/my-app";
@@ -244,6 +248,67 @@ describe("getPathBearingToolPath", () => {
   });
 });
 
+describe("getToolInputPath", () => {
+  function lookupOf(
+    toolName: string,
+    extractor: (input: Record<string, unknown>) => string | undefined,
+  ): ToolAccessExtractorLookup {
+    return {
+      get: (name) => (name === toolName ? extractor : undefined),
+    };
+  }
+
+  test("returns input.path for a built-in path-bearing tool", () => {
+    expect(getToolInputPath("read", { path: "/src/foo.ts" })).toBe(
+      "/src/foo.ts",
+    );
+    expect(getToolInputPath("write", { path: "/src/bar.ts" })).toBe(
+      "/src/bar.ts",
+    );
+  });
+
+  test("returns null for bash", () => {
+    expect(getToolInputPath("bash", { path: "/src/foo.ts" })).toBeNull();
+  });
+
+  test("returns the MCP arguments.path for an mcp call", () => {
+    expect(getToolInputPath("mcp", { arguments: { path: "/etc/hosts" } })).toBe(
+      "/etc/hosts",
+    );
+  });
+
+  test("returns null for an mcp call without an arguments.path", () => {
+    expect(getToolInputPath("mcp", { arguments: { query: "x" } })).toBeNull();
+    expect(getToolInputPath("mcp", {})).toBeNull();
+  });
+
+  test("defaults to input.path for an unregistered extension tool", () => {
+    expect(getToolInputPath("my-ext", { path: "/work/file.txt" })).toBe(
+      "/work/file.txt",
+    );
+  });
+
+  test("returns null for an extension tool without a path", () => {
+    expect(getToolInputPath("my-ext", { other: true })).toBeNull();
+    expect(getToolInputPath("my-ext", { path: "" })).toBeNull();
+    expect(getToolInputPath("my-ext", null)).toBeNull();
+  });
+
+  test("uses a registered extractor's path over the default convention", () => {
+    const extractors = lookupOf("ffgrep", (input) =>
+      typeof input.target === "string" ? input.target : undefined,
+    );
+    expect(
+      getToolInputPath("ffgrep", { target: "/etc/passwd" }, extractors),
+    ).toBe("/etc/passwd");
+  });
+
+  test("returns null when a registered extractor declines", () => {
+    const extractors = lookupOf("ffgrep", () => undefined);
+    expect(getToolInputPath("ffgrep", { target: "x" }, extractors)).toBeNull();
+  });
+});
+
 describe("isPathOutsideWorkingDirectory", () => {
   const cwd = "/projects/my-app";
 
@@ -479,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

@@ -3081,3 +3081,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/permissions-service.test.ts

@@ -3,6 +3,7 @@ import type { ScopedPermissionManager } from "#src/permission-manager";
 import { LocalPermissionsService } from "#src/permissions-service";
 import type { Ruleset } from "#src/rule";
 import type { SessionRules } from "#src/session-rules";
+import type { ToolAccessExtractorRegistrar } from "#src/tool-access-extractor-registry";
 import type {
   ToolInputFormatter,
   ToolInputFormatterRegistrar,
@@ -39,22 +40,40 @@ function makeFormatterRegistry(): ToolInputFormatterRegistrar {
   };
 }
 
+function makeAccessExtractorRegistry(): ToolAccessExtractorRegistrar {
+  return {
+    register: vi
+      .fn<ToolAccessExtractorRegistrar["register"]>()
+      .mockReturnValue(vi.fn()),
+  };
+}
+
 function makeService(overrides?: {
   permissionManager?: ScopedPermissionManager;
   sessionRules?: Pick<SessionRules, "getRuleset">;
   formatterRegistry?: ToolInputFormatterRegistrar;
+  accessExtractorRegistry?: ToolAccessExtractorRegistrar;
 }) {
   const permissionManager =
     overrides?.permissionManager ?? makeFakePermissionManager();
   const sessionRules = overrides?.sessionRules ?? makeSessionRules();
   const formatterRegistry =
     overrides?.formatterRegistry ?? makeFormatterRegistry();
+  const accessExtractorRegistry =
+    overrides?.accessExtractorRegistry ?? makeAccessExtractorRegistry();
   const service = new LocalPermissionsService(
     permissionManager,
     sessionRules,
     formatterRegistry,
+    accessExtractorRegistry,
   );
-  return { service, permissionManager, sessionRules, formatterRegistry };
+  return {
+    service,
+    permissionManager,
+    sessionRules,
+    formatterRegistry,
+    accessExtractorRegistry,
+  };
 }
 
 // ── tests ──────────────────────────────────────────────────────────────────
@@ -141,3 +160,18 @@ describe("registerToolInputFormatter", () => {
     expect(result).toBe(unsub);
   });
 });
+
+describe("registerToolAccessExtractor", () => {
+  it("delegates to accessExtractorRegistry.register and returns the unsubscribe function", () => {
+    const unsub = vi.fn();
+    const { service, accessExtractorRegistry } = makeService();
+    vi.mocked(accessExtractorRegistry.register).mockReturnValue(unsub);
+    const extractor = vi.fn();
+    const result = service.registerToolAccessExtractor("ffgrep", extractor);
+    expect(accessExtractorRegistry.register).toHaveBeenCalledWith(
+      "ffgrep",
+      extractor,
+    );
+    expect(result).toBe(unsub);
+  });
+});