@gotgenes/pi-permission-system 18.0.0 → 18.0.2

package/src/pi-infrastructure-read.ts

@@ -0,0 +1,65 @@
+import { join } from "node:path";
+
+import { expandHomePath } from "./expand-home";
+import { isPathWithinDirectory } from "./path-containment";
+import { READ_ONLY_PATH_BEARING_TOOLS } from "./path-surfaces";
+import { wildcardMatch } from "./wildcard-matcher";
+
+function containsGlobChars(value: string): boolean {
+  return value.includes("*") || value.includes("?");
+}
+
+/**
+ * Returns true if the given tool + normalized path combination qualifies for
+ * automatic allow as a Pi infrastructure read.
+ *
+ * A path qualifies when:
+ * 1. The tool is read-only (in READ_ONLY_PATH_BEARING_TOOLS).
+ * 2. The normalized path is within one of the provided `infrastructureDirs`
+ *    OR within the project-local Pi package directories
+ *    (`<cwd>/.pi/npm/` or `<cwd>/.pi/git/`).
+ *
+ * `infrastructureDirs` entries may be absolute paths or patterns containing
+ * `~`/`$HOME` (expanded at call time) or glob characters (`*`, `?`).
+ * Project-local paths are computed fresh from `cwd` on each call so they
+ * follow working-directory changes without a runtime rebuild.
+ */
+export function isPiInfrastructureRead(
+  toolName: string,
+  normalizedPath: string,
+  infrastructureDirs: readonly string[],
+  cwd: string,
+  platform: NodeJS.Platform,
+): boolean {
+  if (!READ_ONLY_PATH_BEARING_TOOLS.has(toolName)) {
+    return false;
+  }
+
+  // On Windows the path value is canonicalized + lowercased; fold case (and
+  // separators) so mixed-case infra dirs and glob patterns still match.
+  const matchOptions =
+    platform === "win32"
+      ? { caseInsensitive: true, windowsSeparators: true }
+      : undefined;
+
+  for (const dir of infrastructureDirs) {
+    if (containsGlobChars(dir)) {
+      if (wildcardMatch(dir, normalizedPath, matchOptions)) return true;
+    } else {
+      if (isPathWithinDirectory(normalizedPath, expandHomePath(dir), platform))
+        return true;
+    }
+  }
+
+  // Project-local Pi packages — checked fresh every call so CWD changes work.
+  const projectNpmDir = join(cwd, ".pi", "npm");
+  const projectGitDir = join(cwd, ".pi", "git");
+  if (isPathWithinDirectory(normalizedPath, projectNpmDir, platform)) {
+    return true;
+  }
+  if (isPathWithinDirectory(normalizedPath, projectGitDir, platform)) {
+    return true;
+  }
+
+  return false;
+}

package/src/rule.ts

@@ -1,4 +1,4 @@
-import { PATH_SURFACES } from "./path-utils";
+import { PATH_SURFACES } from "./path-surfaces";
 import type { PermissionState } from "./types";
 import { wildcardMatch } from "./wildcard-matcher";
 

package/src/safe-system-paths.ts

@@ -0,0 +1,18 @@
+/**
+ * Paths that are universally safe and should never trigger external-directory checks.
+ * These are OS device files: read returns EOF or process streams, write discards or goes to process streams.
+ */
+export const SAFE_SYSTEM_PATHS: ReadonlySet<string> = new Set([
+  "/dev/null",
+  "/dev/stdin",
+  "/dev/stdout",
+  "/dev/stderr",
+]);
+
+/**
+ * Returns true if the given normalized path is a safe OS device file
+ * that should never trigger external-directory checks.
+ */
+export function isSafeSystemPath(normalizedPath: string): boolean {
+  return SAFE_SYSTEM_PATHS.has(normalizedPath);
+}

package/src/tool-input-path.ts

@@ -0,0 +1,54 @@
+import { PATH_BEARING_TOOLS } from "./path-surfaces";
+import type { ToolAccessExtractorLookup } from "./tool-access-extractor-registry";
+import { getNonEmptyString, toRecord } from "./value-guards";
+
+export function getPathBearingToolPath(
+  toolName: string,
+  input: unknown,
+): string | null {
+  if (!PATH_BEARING_TOOLS.has(toolName)) {
+    return null;
+  }
+
+  return getNonEmptyString(toRecord(input).path);
+}
+
+/**
+ * Extract the filesystem path a tool will access, for the cross-cutting `path`
+ * and `external_directory` gates.
+ *
+ * Unlike {@link getPathBearingToolPath} (built-in tools only), this recognizes
+ * extension and MCP tools so they are no longer exempt from path gating:
+ *
+ * - `bash` → `null` (bash has its own token-based path gates).
+ * - Built-in path-bearing tools → `input.path`.
+ * - `mcp` → `input.arguments.path`.
+ * - Any other tool → a registered {@link ToolAccessExtractor}'s path, else the
+ *   default `input.path` convention.
+ */
+export function getToolInputPath(
+  toolName: string,
+  input: unknown,
+  extractors?: ToolAccessExtractorLookup,
+): string | null {
+  if (toolName === "bash") {
+    return null;
+  }
+
+  const record = toRecord(input);
+
+  if (PATH_BEARING_TOOLS.has(toolName)) {
+    return getNonEmptyString(record.path);
+  }
+
+  if (toolName === "mcp") {
+    return getNonEmptyString(toRecord(record.arguments).path);
+  }
+
+  const custom = extractors?.get(toolName);
+  if (custom) {
+    return getNonEmptyString(custom(record));
+  }
+
+  return getNonEmptyString(record.path);
+}

package/test/access-intent/access-path.test.ts

@@ -191,6 +191,67 @@ describe("AccessPath.forPath", () => {
   });
 });
 
+describe("resolvedAlias()", () => {
+  const cwd = "/projects/my-app";
+
+  beforeEach(() => {
+    realpathSync.mockReset();
+    realpathSync.mockImplementation((p: string) => p);
+  });
+
+  test("returns the canonical form when a symlink resolves elsewhere", () => {
+    realpathSync.mockImplementation((p: string) =>
+      p === "/projects/my-app/demo-symlink-passwd" ? "/etc/passwd" : p,
+    );
+    expect(
+      AccessPath.forPath("demo-symlink-passwd", {
+        cwd,
+        platform: "linux",
+      }).resolvedAlias(),
+    ).toBe("/etc/passwd");
+  });
+
+  test("returns undefined when the path has no symlinks (canonical equals lexical)", () => {
+    expect(
+      AccessPath.forPath("/etc/hosts", {
+        cwd,
+        platform: "linux",
+      }).resolvedAlias(),
+    ).toBeUndefined();
+  });
+
+  test("returns undefined for a literal-only path (no canonical)", () => {
+    expect(AccessPath.forLiteral("foo.ts").resolvedAlias()).toBeUndefined();
+  });
+
+  test("returns undefined for empty input", () => {
+    expect(
+      AccessPath.forPath("", { cwd, platform: "linux" }).resolvedAlias(),
+    ).toBeUndefined();
+  });
+
+  test("win32: returns the lowercased canonical form for a real symlink target", () => {
+    realpathSync.mockImplementation((p: string) =>
+      p === "c:\\projects\\app\\link" ? "C:\\Real\\App" : p,
+    );
+    expect(
+      AccessPath.forPath("link", {
+        cwd: "C:\\Projects\\App",
+        platform: "win32",
+      }).resolvedAlias(),
+    ).toBe("c:\\real\\app");
+  });
+
+  test("win32: returns undefined for a case-only difference (both forms lowercased)", () => {
+    expect(
+      AccessPath.forPath("src\\foo.ts", {
+        cwd: "C:\\Projects\\App",
+        platform: "win32",
+      }).resolvedAlias(),
+    ).toBeUndefined();
+  });
+});
+
 describe("AccessPath.forLiteral", () => {
   beforeEach(() => {
     realpathSync.mockReset();

package/test/bash-external-directory.test.ts

@@ -924,7 +924,7 @@ describe("formatBashExternalDirectoryAskPrompt", () => {
   test("includes command, external paths, and CWD", () => {
     const result = formatBashExternalDirectoryAskPrompt(
       "cat /etc/hosts",
-      ["/etc/hosts"],
+      [{ path: "/etc/hosts" }],
       "/projects/my-app",
     );
     expect(result).toContain("cat /etc/hosts");
@@ -935,7 +935,7 @@ describe("formatBashExternalDirectoryAskPrompt", () => {
   test("includes agent name when provided", () => {
     const result = formatBashExternalDirectoryAskPrompt(
       "cat /etc/hosts",
-      ["/etc/hosts"],
+      [{ path: "/etc/hosts" }],
       "/projects/my-app",
       "my-agent",
     );
@@ -945,12 +945,26 @@ describe("formatBashExternalDirectoryAskPrompt", () => {
   test("shows multiple external paths", () => {
     const result = formatBashExternalDirectoryAskPrompt(
       "diff /etc/hosts /var/log/syslog",
-      ["/etc/hosts", "/var/log/syslog"],
+      [{ path: "/etc/hosts" }, { path: "/var/log/syslog" }],
       "/projects/my-app",
     );
     expect(result).toContain("/etc/hosts");
     expect(result).toContain("/var/log/syslog");
   });
+
+  test("discloses the resolved target per path when it differs", () => {
+    const result = formatBashExternalDirectoryAskPrompt(
+      "cat demo-symlink-passwd /etc/hosts",
+      [
+        { path: "demo-symlink-passwd", resolvedPath: "/etc/passwd" },
+        { path: "/etc/hosts" },
+      ],
+      "/projects/my-app",
+    );
+    expect(result).toBe(
+      "Current agent requested bash command 'cat demo-symlink-passwd /etc/hosts' which references path(s) outside working directory '/projects/my-app': demo-symlink-passwd (resolves to '/etc/passwd'), /etc/hosts. Allow this external directory access?",
+    );
+  });
 });
 
 describe("Windows drive-letter paths (win32 semantics)", () => {
@@ -996,7 +1010,7 @@ describe("bash external-directory denial messages (centralized)", () => {
     const result = formatDenyReason({
       kind: "bash_external_directory",
       command: "cat /etc/hosts",
-      externalPaths: ["/etc/hosts"],
+      externalPaths: [{ path: "/etc/hosts" }],
       cwd: "/projects/my-app",
     });
     expect(result).toContain("cat /etc/hosts");

package/test/denial-messages.test.ts

@@ -242,6 +242,20 @@ describe("formatDenyReason", () => {
         "[pi-permission-system] Agent 'sec-agent' is not permitted to run tool 'read' for path '/etc/passwd' outside working directory '/project'.",
       );
     });
+
+    test("discloses the resolved path when it differs from the typed path", () => {
+      expect(
+        formatDenyReason({
+          kind: "external_directory",
+          toolName: "read",
+          pathValue: "demo-symlink-passwd",
+          resolvedPath: "/etc/passwd",
+          cwd: "/project",
+        }),
+      ).toBe(
+        "[pi-permission-system] Current agent is not permitted to run tool 'read' for path 'demo-symlink-passwd' (resolves to '/etc/passwd') outside working directory '/project'.",
+      );
+    });
   });
 
   describe("bash_external_directory context", () => {
@@ -250,7 +264,7 @@ describe("formatDenyReason", () => {
         formatDenyReason({
           kind: "bash_external_directory",
           command: "cat /etc/hosts",
-          externalPaths: ["/etc/hosts"],
+          externalPaths: [{ path: "/etc/hosts" }],
           cwd: "/project",
         }),
       ).toBe(
@@ -263,7 +277,7 @@ describe("formatDenyReason", () => {
         formatDenyReason({
           kind: "bash_external_directory",
           command: "cp /etc/hosts /tmp/out",
-          externalPaths: ["/etc/hosts", "/tmp/out"],
+          externalPaths: [{ path: "/etc/hosts" }, { path: "/tmp/out" }],
           cwd: "/project",
           agentName: "my-agent",
         }),
@@ -271,6 +285,22 @@ describe("formatDenyReason", () => {
         "[pi-permission-system] Agent 'my-agent' is not permitted to run bash command 'cp /etc/hosts /tmp/out' which references path(s) outside working directory '/project': /etc/hosts, /tmp/out.",
       );
     });
+
+    test("discloses resolved targets per path when they differ", () => {
+      expect(
+        formatDenyReason({
+          kind: "bash_external_directory",
+          command: "cat demo-symlink-passwd /etc/hosts",
+          externalPaths: [
+            { path: "demo-symlink-passwd", resolvedPath: "/etc/passwd" },
+            { path: "/etc/hosts" },
+          ],
+          cwd: "/project",
+        }),
+      ).toBe(
+        "[pi-permission-system] Current agent is not permitted to run bash command 'cat demo-symlink-passwd /etc/hosts' which references path(s) outside working directory '/project': demo-symlink-passwd (resolves to '/etc/passwd'), /etc/hosts.",
+      );
+    });
   });
 
   describe("bash_path context", () => {
@@ -403,12 +433,26 @@ describe("formatUnavailableReason", () => {
     );
   });
 
+  test("external_directory discloses the resolved path when it differs from the typed path", () => {
+    expect(
+      formatUnavailableReason({
+        kind: "external_directory",
+        toolName: "read",
+        pathValue: "demo-symlink-passwd",
+        resolvedPath: "/etc/passwd",
+        cwd: "/project",
+      }),
+    ).toBe(
+      "[pi-permission-system] Accessing 'demo-symlink-passwd' (resolves to '/etc/passwd') outside the working directory requires approval, but no interactive UI is available.",
+    );
+  });
+
   test("bash_external_directory", () => {
     expect(
       formatUnavailableReason({
         kind: "bash_external_directory",
         command: "cat /etc/hosts",
-        externalPaths: ["/etc/hosts"],
+        externalPaths: [{ path: "/etc/hosts" }],
         cwd: "/project",
       }),
     ).toBe(
@@ -539,6 +583,20 @@ describe("formatUserDeniedReason", () => {
         "[pi-permission-system] User denied external directory access for tool 'edit' path '/etc/hosts'. Reason: too risky.",
       );
     });
+
+    test("discloses the resolved path when it differs from the typed path", () => {
+      expect(
+        formatUserDeniedReason({
+          kind: "external_directory",
+          toolName: "edit",
+          pathValue: "demo-symlink-hosts",
+          resolvedPath: "/etc/hosts",
+          cwd: "/project",
+        }),
+      ).toBe(
+        "[pi-permission-system] User denied external directory access for tool 'edit' path 'demo-symlink-hosts' (resolves to '/etc/hosts').",
+      );
+    });
   });
 
   describe("bash_external_directory context", () => {
@@ -547,7 +605,7 @@ describe("formatUserDeniedReason", () => {
         formatUserDeniedReason({
           kind: "bash_external_directory",
           command: "rm /etc/hosts",
-          externalPaths: ["/etc/hosts"],
+          externalPaths: [{ path: "/etc/hosts" }],
           cwd: "/project",
         }),
       ).toBe(
@@ -561,7 +619,7 @@ describe("formatUserDeniedReason", () => {
           {
             kind: "bash_external_directory",
             command: "rm /etc/hosts",
-            externalPaths: ["/etc/hosts"],
+            externalPaths: [{ path: "/etc/hosts" }],
             cwd: "/project",
           },
           "dangerous",

package/test/handlers/external-directory-integration.test.ts

@@ -47,7 +47,12 @@ describe("external_directory helper regression guard", () => {
   it("formatExternalDirectoryAskPrompt is a callable function", () => {
     expect(typeof formatExternalDirectoryAskPrompt).toBe("function");
     expect(
-      formatExternalDirectoryAskPrompt("read", "/outside/file", "/project"),
+      formatExternalDirectoryAskPrompt(
+        "read",
+        "/outside/file",
+        undefined,
+        "/project",
+      ),
     ).toContain("/outside/file");
   });
 

package/test/handlers/gates/external-directory-messages.test.ts

@@ -15,6 +15,7 @@ describe("formatExternalDirectoryAskPrompt", () => {
     const result = formatExternalDirectoryAskPrompt(
       "read",
       "/etc/passwd",
+      undefined,
       "/projects/my-app",
     );
     expect(result).toContain("Current agent");
@@ -27,6 +28,7 @@ describe("formatExternalDirectoryAskPrompt", () => {
     const result = formatExternalDirectoryAskPrompt(
       "write",
       "/tmp/out.txt",
+      undefined,
       "/projects/my-app",
       "my-agent",
     );
@@ -34,13 +36,35 @@ describe("formatExternalDirectoryAskPrompt", () => {
     expect(result).toContain("write");
     expect(result).toContain("/tmp/out.txt");
   });
+
+  test("discloses the resolved path when it differs from the typed path", () => {
+    const result = formatExternalDirectoryAskPrompt(
+      "read",
+      "demo-symlink-passwd",
+      "/etc/passwd",
+      "/projects/my-app",
+    );
+    expect(result).toBe(
+      "Current agent requested tool 'read' for path 'demo-symlink-passwd' (resolves to '/etc/passwd') outside working directory '/projects/my-app'. Allow this external directory access?",
+    );
+  });
+
+  test("omits the disclosure when resolvedPath is undefined", () => {
+    const result = formatExternalDirectoryAskPrompt(
+      "read",
+      "/etc/passwd",
+      undefined,
+      "/projects/my-app",
+    );
+    expect(result).not.toContain("resolves to");
+  });
 });
 
 describe("formatBashExternalDirectoryAskPrompt", () => {
   test("includes command, paths, cwd, and agent name", () => {
     const result = formatBashExternalDirectoryAskPrompt(
       "cat /etc/passwd",
-      ["/etc/passwd"],
+      [{ path: "/etc/passwd" }],
       "/projects/my-app",
       "my-agent",
     );
@@ -53,7 +77,7 @@ describe("formatBashExternalDirectoryAskPrompt", () => {
   test("uses 'Current agent' when no agent name provided", () => {
     const result = formatBashExternalDirectoryAskPrompt(
       "ls /tmp",
-      ["/tmp"],
+      [{ path: "/tmp" }],
       "/projects/my-app",
     );
     expect(result).toContain("Current agent");

package/test/path-containment.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, test, vi } from "vitest";
+
+// Mock node:fs so the discriminator test can assert realpathSync is untouched.
+const realpathSync = vi.hoisted(() =>
+  vi.fn<(path: string) => string>((p) => p),
+);
+vi.mock("node:fs", () => ({
+  realpathSync,
+  default: { realpathSync },
+}));
+
+import {
+  isPathOutsideWorkingDirectory,
+  isPathWithinDirectory,
+} from "#src/path-containment";
+
+describe("isPathWithinDirectory", () => {
+  test("returns true when path equals directory", () => {
+    expect(isPathWithinDirectory("/a/b", "/a/b", "linux")).toBe(true);
+  });
+
+  test("returns true when path is a direct child", () => {
+    expect(isPathWithinDirectory("/a/b/c", "/a/b", "linux")).toBe(true);
+  });
+
+  test("returns true when path is a deep descendant", () => {
+    expect(isPathWithinDirectory("/a/b/c/d/e", "/a/b", "linux")).toBe(true);
+  });
+
+  test("returns false when path is a sibling directory", () => {
+    expect(isPathWithinDirectory("/a/bc", "/a/b", "linux")).toBe(false);
+  });
+
+  test("returns false when path is outside the directory", () => {
+    expect(isPathWithinDirectory("/other/path", "/a/b", "linux")).toBe(false);
+  });
+
+  test("returns false for empty path", () => {
+    expect(isPathWithinDirectory("", "/a/b", "linux")).toBe(false);
+  });
+
+  test("returns false for empty directory", () => {
+    expect(isPathWithinDirectory("/a/b", "", "linux")).toBe(false);
+  });
+
+  // ── platform-aware containment (Windows is case-insensitive) ────────────
+
+  test("win32: folds case for a case-different descendant", () => {
+    expect(
+      isPathWithinDirectory(
+        "c:\\users\\foo\\dir\\sub\\x.md",
+        "C:\\Users\\Foo\\dir",
+        "win32",
+      ),
+    ).toBe(true);
+  });
+
+  test("win32: folds case when path equals directory in different case", () => {
+    expect(
+      isPathWithinDirectory(
+        "c:\\users\\foo\\dir\\sub",
+        "C:\\USERS\\foo\\DIR",
+        "win32",
+      ),
+    ).toBe(true);
+  });
+
+  test("win32: rejects a sibling directory", () => {
+    expect(
+      isPathWithinDirectory(
+        "C:\\Users\\Foo\\other",
+        "C:\\Users\\Foo\\dir",
+        "win32",
+      ),
+    ).toBe(false);
+  });
+
+  test("posix platform stays case-sensitive", () => {
+    expect(isPathWithinDirectory("/a/B/c", "/a/b", "linux")).toBe(false);
+  });
+});
+
+describe("isPathOutsideWorkingDirectory", () => {
+  // Pure geometry over already-canonical operands: the caller (PathNormalizer)
+  // prepares the canonical path and cwd; this predicate never canonicalizes.
+  const canonicalCwd = "/projects/my-app";
+
+  test("does not canonicalize its operands (no filesystem access)", () => {
+    realpathSync.mockClear();
+    isPathOutsideWorkingDirectory(
+      "/projects/my-app/src",
+      canonicalCwd,
+      "linux",
+    );
+    expect(realpathSync).not.toHaveBeenCalled();
+  });
+
+  test("returns false when path is inside cwd", () => {
+    expect(
+      isPathOutsideWorkingDirectory(
+        "/projects/my-app/src",
+        canonicalCwd,
+        "linux",
+      ),
+    ).toBe(false);
+  });
+
+  test("returns false when path equals cwd", () => {
+    expect(
+      isPathOutsideWorkingDirectory("/projects/my-app", canonicalCwd, "linux"),
+    ).toBe(false);
+  });
+
+  test("returns true when path is outside cwd", () => {
+    expect(
+      isPathOutsideWorkingDirectory("/etc/passwd", canonicalCwd, "linux"),
+    ).toBe(true);
+  });
+
+  test("returns false for an empty canonical path", () => {
+    expect(isPathOutsideWorkingDirectory("", canonicalCwd, "linux")).toBe(
+      false,
+    );
+  });
+
+  test("returns false for an empty canonical cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/etc/passwd", "", "linux")).toBe(
+      false,
+    );
+  });
+
+  test("returns false for /dev/null (safe system path)", () => {
+    expect(
+      isPathOutsideWorkingDirectory("/dev/null", canonicalCwd, "linux"),
+    ).toBe(false);
+  });
+
+  test("returns false for /dev/stdin (safe system path)", () => {
+    expect(
+      isPathOutsideWorkingDirectory("/dev/stdin", canonicalCwd, "linux"),
+    ).toBe(false);
+  });
+
+  test("returns false for /dev/stdout (safe system path)", () => {
+    expect(
+      isPathOutsideWorkingDirectory("/dev/stdout", canonicalCwd, "linux"),
+    ).toBe(false);
+  });
+
+  test("returns false for /dev/stderr (safe system path)", () => {
+    expect(
+      isPathOutsideWorkingDirectory("/dev/stderr", canonicalCwd, "linux"),
+    ).toBe(false);
+  });
+
+  test("returns true for /dev/null/subdir (not a safe path)", () => {
+    expect(
+      isPathOutsideWorkingDirectory("/dev/null/subdir", canonicalCwd, "linux"),
+    ).toBe(true);
+  });
+});