@gotgenes/pi-permission-system 8.2.0 → 8.3.0

package/test/handlers/gates/bash-token-classification.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  classifyTokenAsPathCandidate,
+  classifyTokenAsRuleCandidate,
+} from "#src/handlers/gates/bash-token-classification";
+
+// ── Shared rejection behaviour ─────────────────────────────────────────────
+//
+// Both classifiers delegate to the private `rejectNonPathToken` predicate for
+// the seven shared rejection cases tested below.  Testing via both exports
+// pins that predicate through each caller.
+
+describe("classifyTokenAsPathCandidate", () => {
+  describe("shared rejection: rejectNonPathToken", () => {
+    test("empty string → null", () => {
+      expect(classifyTokenAsPathCandidate("")).toBeNull();
+    });
+
+    test("flag (leading dash) → null", () => {
+      expect(classifyTokenAsPathCandidate("-r")).toBeNull();
+      expect(classifyTokenAsPathCandidate("--recursive")).toBeNull();
+    });
+
+    test("env assignment (= before any /) → null", () => {
+      expect(classifyTokenAsPathCandidate("FOO=/bar")).toBeNull();
+      expect(classifyTokenAsPathCandidate("HOME=/home/user")).toBeNull();
+    });
+
+    test("env-like token where = comes after / is NOT rejected as assignment", () => {
+      // /foo=bar: slashIndex (0) < eqIndex (4) → not an assignment → continues
+      // Starts with /, so path candidate accepts it.
+      expect(classifyTokenAsPathCandidate("/foo=bar")).toBe("/foo=bar");
+    });
+
+    test("URL → null", () => {
+      expect(classifyTokenAsPathCandidate("https://example.com")).toBeNull();
+      expect(classifyTokenAsPathCandidate("http://localhost:3000")).toBeNull();
+      expect(classifyTokenAsPathCandidate("file:///tmp/foo")).toBeNull();
+      expect(
+        classifyTokenAsPathCandidate("git+ssh://github.com/a/b"),
+      ).toBeNull();
+    });
+
+    test("@scope/package → null", () => {
+      expect(classifyTokenAsPathCandidate("@foo/bar")).toBeNull();
+      expect(classifyTokenAsPathCandidate("@scope/pkg")).toBeNull();
+    });
+
+    test("@/ prefix is NOT rejected (it looks like an absolute-rooted scoped path)", () => {
+      // @/ passes the @ guard; then for path candidate it doesn't start with /
+      // or ~/, and doesn't contain .., so it returns null anyway from the
+      // acceptance gate — but the rejection is not due to the @ guard.
+      // This test documents that @/ is not rejected by the shared rejection.
+      // The path classifier then rejects it for not matching any acceptance shape.
+      expect(classifyTokenAsPathCandidate("@/foo/bar")).toBeNull();
+    });
+
+    test("bare-slash token → null", () => {
+      expect(classifyTokenAsPathCandidate("/")).toBeNull();
+      expect(classifyTokenAsPathCandidate("//")).toBeNull();
+      expect(classifyTokenAsPathCandidate("///")).toBeNull();
+    });
+
+    test("regex metacharacters → null", () => {
+      // REGEX_METACHAR_PATTERN: .*, .+, \|, \(, \), [...], ^/
+      expect(classifyTokenAsPathCandidate("foo.*")).toBeNull();
+      expect(classifyTokenAsPathCandidate("bar.+")).toBeNull();
+      expect(classifyTokenAsPathCandidate("a\\|b")).toBeNull();
+      expect(classifyTokenAsPathCandidate("\\(group\\)")).toBeNull();
+      expect(classifyTokenAsPathCandidate("[abc]")).toBeNull();
+      expect(classifyTokenAsPathCandidate("^/start")).toBeNull();
+    });
+  });
+
+  describe("path-candidate acceptance gate", () => {
+    test("absolute path (starts with /) → returned as-is", () => {
+      expect(classifyTokenAsPathCandidate("/etc/hosts")).toBe("/etc/hosts");
+      expect(classifyTokenAsPathCandidate("/tmp")).toBe("/tmp");
+      expect(classifyTokenAsPathCandidate("/home/user/file.txt")).toBe(
+        "/home/user/file.txt",
+      );
+    });
+
+    test("home-relative path (starts with ~/) → returned as-is", () => {
+      expect(classifyTokenAsPathCandidate("~/Documents")).toBe("~/Documents");
+      expect(classifyTokenAsPathCandidate("~/.ssh/config")).toBe(
+        "~/.ssh/config",
+      );
+    });
+
+    test("parent-traversal (contains ..) → returned as-is", () => {
+      expect(classifyTokenAsPathCandidate("../../etc/passwd")).toBe(
+        "../../etc/passwd",
+      );
+      expect(classifyTokenAsPathCandidate("../foo")).toBe("../foo");
+      expect(classifyTokenAsPathCandidate("..")).toBe("..");
+    });
+
+    test("plain word with no path shape → null", () => {
+      expect(classifyTokenAsPathCandidate("hello")).toBeNull();
+      expect(classifyTokenAsPathCandidate("myfile.txt")).toBeNull();
+    });
+
+    test("dot-file (starts with .) → null (strict path gate)", () => {
+      // Path candidate does NOT accept dot-files; rule candidate does.
+      expect(classifyTokenAsPathCandidate(".env")).toBeNull();
+      expect(classifyTokenAsPathCandidate(".gitignore")).toBeNull();
+    });
+
+    test("relative path with / but no leading / or ~/ → null (strict path gate)", () => {
+      // Path candidate does NOT accept bare relative paths; rule candidate does.
+      expect(classifyTokenAsPathCandidate("src/foo.ts")).toBeNull();
+      expect(classifyTokenAsPathCandidate("./build")).toBeNull();
+    });
+  });
+});
+
+describe("classifyTokenAsRuleCandidate", () => {
+  describe("shared rejection: rejectNonPathToken", () => {
+    test("empty string → null", () => {
+      expect(classifyTokenAsRuleCandidate("")).toBeNull();
+    });
+
+    test("flag (leading dash) → null", () => {
+      expect(classifyTokenAsRuleCandidate("-r")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("--recursive")).toBeNull();
+    });
+
+    test("env assignment (= before any /) → null", () => {
+      expect(classifyTokenAsRuleCandidate("FOO=/bar")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("HOME=/home/user")).toBeNull();
+    });
+
+    test("env-like token where = comes after / is NOT rejected as assignment", () => {
+      // /foo=bar: slashIndex (0) < eqIndex (4) → not an assignment → continues.
+      // Contains /, so rule candidate accepts it.
+      expect(classifyTokenAsRuleCandidate("/foo=bar")).toBe("/foo=bar");
+    });
+
+    test("URL → null", () => {
+      expect(classifyTokenAsRuleCandidate("https://example.com")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("http://localhost:3000")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("file:///tmp/foo")).toBeNull();
+    });
+
+    test("@scope/package → null", () => {
+      expect(classifyTokenAsRuleCandidate("@foo/bar")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("@scope/pkg")).toBeNull();
+    });
+
+    test("bare-slash token → null", () => {
+      expect(classifyTokenAsRuleCandidate("/")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("//")).toBeNull();
+    });
+
+    test("regex metacharacters → null", () => {
+      expect(classifyTokenAsRuleCandidate("foo.*")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("bar.+")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("a\\|b")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("[abc]")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("^/start")).toBeNull();
+    });
+  });
+
+  describe("rule-candidate acceptance gate (broader than path)", () => {
+    test("absolute path (starts with /) → returned as-is", () => {
+      expect(classifyTokenAsRuleCandidate("/etc/hosts")).toBe("/etc/hosts");
+    });
+
+    test("home-relative path (starts with ~/) → returned as-is", () => {
+      expect(classifyTokenAsRuleCandidate("~/Documents")).toBe("~/Documents");
+    });
+
+    test("parent-traversal (contains ..) → returned as-is", () => {
+      expect(classifyTokenAsRuleCandidate("../foo")).toBe("../foo");
+      expect(classifyTokenAsRuleCandidate("..")).toBe("..");
+    });
+
+    test("dot-file (starts with .) → returned as-is", () => {
+      // Rule candidate accepts dot-files; path candidate does not.
+      expect(classifyTokenAsRuleCandidate(".env")).toBe(".env");
+      expect(classifyTokenAsRuleCandidate(".gitignore")).toBe(".gitignore");
+    });
+
+    test("current-dir relative (starts with ./) → returned as-is", () => {
+      expect(classifyTokenAsRuleCandidate("./src")).toBe("./src");
+      expect(classifyTokenAsRuleCandidate("./build/output.js")).toBe(
+        "./build/output.js",
+      );
+    });
+
+    test("relative path containing / → returned as-is", () => {
+      // Rule candidate accepts any token with / (not already rejected).
+      expect(classifyTokenAsRuleCandidate("src/foo.ts")).toBe("src/foo.ts");
+      expect(classifyTokenAsRuleCandidate("packages/pi-foo/index.ts")).toBe(
+        "packages/pi-foo/index.ts",
+      );
+    });
+
+    test("plain word with no path shape → null", () => {
+      expect(classifyTokenAsRuleCandidate("hello")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("myfile.txt")).toBeNull();
+    });
+  });
+
+  describe("rule-vs-path divergence", () => {
+    const dotFiles = [".env", ".gitignore", ".eslintrc"];
+    const relPaths = ["src/index.ts", "lib/utils.js", "config/settings.json"];
+
+    for (const tok of dotFiles) {
+      test(`dot-file "${tok}": rule accepts, path rejects`, () => {
+        expect(classifyTokenAsRuleCandidate(tok)).toBe(tok);
+        expect(classifyTokenAsPathCandidate(tok)).toBeNull();
+      });
+    }
+
+    for (const tok of relPaths) {
+      test(`relative path "${tok}": rule accepts, path rejects`, () => {
+        expect(classifyTokenAsRuleCandidate(tok)).toBe(tok);
+        expect(classifyTokenAsPathCandidate(tok)).toBeNull();
+      });
+    }
+
+    const sharedAccepted = ["/etc/hosts", "~/docs", "../sibling"];
+    for (const tok of sharedAccepted) {
+      test(`"${tok}": both classifiers accept`, () => {
+        expect(classifyTokenAsRuleCandidate(tok)).toBe(tok);
+        expect(classifyTokenAsPathCandidate(tok)).toBe(tok);
+      });
+    }
+
+    const sharedRejected = ["hello", "--flag", "FOO=/bar", "https://x.com"];
+    for (const tok of sharedRejected) {
+      test(`"${tok}": both classifiers reject`, () => {
+        expect(classifyTokenAsRuleCandidate(tok)).toBeNull();
+        expect(classifyTokenAsPathCandidate(tok)).toBeNull();
+      });
+    }
+  });
+});

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

@@ -7,8 +7,11 @@ import type { ToolCallContext } from "#src/handlers/gates/types";
 import type { Rule } from "#src/rule";
 import type { PermissionCheckResult } from "#src/types";
 
+import { makeGateCheckResult as makeCheckResult } from "#test/helpers/gate-fixtures";
+
 // ── helpers ────────────────────────────────────────────────────────────────
 
+// path.test.ts uses read-tool defaults; the shared makeTcc uses bash defaults.
 function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
   return {
     toolName: "read",
@@ -20,18 +23,6 @@ function makeTcc(overrides: Partial<ToolCallContext> = {}): ToolCallContext {
   };
 }
 
-function makeCheckResult(
-  overrides: Partial<PermissionCheckResult> = {},
-): PermissionCheckResult {
-  return {
-    toolName: "path",
-    state: "allow",
-    source: "special",
-    origin: "global",
-    ...overrides,
-  };
-}
-
 type CheckPermissionFn = (
   surface: string,
   input: unknown,

package/test/handlers/gates/runner.test.ts

@@ -2,76 +2,11 @@ import { describe, expect, it, vi } from "vitest";
 
 import type { DenialContext } from "#src/denial-messages";
 import { EXTENSION_TAG } from "#src/denial-messages";
-import type {
-  GateDescriptor,
-  GateRunnerDeps,
-} from "#src/handlers/gates/descriptor";
+import type { GateDescriptor } from "#src/handlers/gates/descriptor";
 import { runGateCheck } from "#src/handlers/gates/runner";
 import { SessionApproval } from "#src/session-approval";
-import type { PermissionCheckResult } from "#src/types";
-
-// ── helpers ────────────────────────────────────────────────────────────────
-
-function makeDescriptor(
-  overrides: Partial<GateDescriptor> = {},
-): GateDescriptor {
-  return {
-    surface: "read",
-    input: {},
-    denialContext: {
-      kind: "tool",
-      check: makeCheckResult("deny"),
-    },
-    promptDetails: {
-      source: "tool_call",
-      agentName: null,
-      message: "Allow tool 'read'?",
-      toolCallId: "tc-1",
-      toolName: "read",
-    },
-    logContext: {
-      source: "tool_call",
-      toolCallId: "tc-1",
-      toolName: "read",
-    },
-    decision: {
-      surface: "read",
-      value: "read",
-    },
-    ...overrides,
-  };
-}
-
-function makeCheckResult(
-  state: "allow" | "deny" | "ask",
-  overrides: Partial<PermissionCheckResult> = {},
-): PermissionCheckResult {
-  return {
-    state,
-    toolName: "read",
-    source: "tool",
-    origin: "builtin",
-    matchedPattern: "*",
-    ...overrides,
-  };
-}
-
-function makeRunnerDeps(
-  overrides: Partial<GateRunnerDeps> = {},
-): GateRunnerDeps {
-  return {
-    checkPermission: vi.fn().mockReturnValue(makeCheckResult("allow")),
-    getSessionRuleset: vi.fn().mockReturnValue([]),
-    recordSessionApproval: vi.fn(),
-    writeReviewLog: vi.fn(),
-    emitDecision: vi.fn(),
-    canConfirm: vi.fn().mockReturnValue(true),
-    promptPermission: vi
-      .fn()
-      .mockResolvedValue({ approved: true, state: "approved" }),
-    ...overrides,
-  };
-}
+import { makeDescriptor, makeRunnerDeps } from "#test/helpers/gate-fixtures";
+import { makeCheckResult } from "#test/helpers/handler-fixtures";
 
 // ── tests ──────────────────────────────────────────────────────────────────
 
@@ -92,7 +27,11 @@ describe("runGateCheck", () => {
 
   it("returns block and emits policy_deny when policy is deny", async () => {
     const deps = makeRunnerDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("deny")),
+      checkPermission: vi
+        .fn()
+        .mockReturnValue(
+          makeCheckResult({ state: "deny", matchedPattern: "*" }),
+        ),
     });
     const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
     expect(result).toMatchObject({ action: "block" });
@@ -110,12 +49,11 @@ describe("runGateCheck", () => {
 
   it("returns allow and emits session_approved on session hit", async () => {
     const deps = makeRunnerDeps({
-      checkPermission: vi.fn().mockReturnValue(
-        makeCheckResult("allow", {
-          source: "session",
-          matchedPattern: "git *",
-        }),
-      ),
+      checkPermission: vi
+        .fn()
+        .mockReturnValue(
+          makeCheckResult({ source: "session", matchedPattern: "git *" }),
+        ),
     });
     const result = await runGateCheck(
       makeDescriptor({
@@ -145,7 +83,11 @@ describe("runGateCheck", () => {
 
   it("returns allow and emits user_approved when ask + user approves", async () => {
     const deps = makeRunnerDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      checkPermission: vi
+        .fn()
+        .mockReturnValue(
+          makeCheckResult({ state: "ask", matchedPattern: "*" }),
+        ),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved" }),
@@ -162,7 +104,11 @@ describe("runGateCheck", () => {
 
   it("returns allow, emits user_approved_for_session, and records session rule on approved_for_session", async () => {
     const deps = makeRunnerDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      checkPermission: vi
+        .fn()
+        .mockReturnValue(
+          makeCheckResult({ state: "ask", matchedPattern: "*" }),
+        ),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved_for_session" }),
@@ -184,7 +130,11 @@ describe("runGateCheck", () => {
 
   it("calls recordSessionApproval once with the full SessionApproval when sessionApproval has multiple patterns", async () => {
     const deps = makeRunnerDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      checkPermission: vi
+        .fn()
+        .mockReturnValue(
+          makeCheckResult({ state: "ask", matchedPattern: "*" }),
+        ),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved_for_session" }),
@@ -202,7 +152,11 @@ describe("runGateCheck", () => {
 
   it("returns block and emits user_denied when ask + user denies", async () => {
     const deps = makeRunnerDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      checkPermission: vi
+        .fn()
+        .mockReturnValue(
+          makeCheckResult({ state: "ask", matchedPattern: "*" }),
+        ),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: false, state: "denied" }),
@@ -219,7 +173,11 @@ describe("runGateCheck", () => {
 
   it("returns block and emits confirmation_unavailable when ask + no UI", async () => {
     const deps = makeRunnerDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      checkPermission: vi
+        .fn()
+        .mockReturnValue(
+          makeCheckResult({ state: "ask", matchedPattern: "*" }),
+        ),
       canConfirm: vi.fn().mockReturnValue(false),
     });
     const result = await runGateCheck(makeDescriptor(), null, "tc-1", deps);
@@ -234,7 +192,11 @@ describe("runGateCheck", () => {
 
   it("emits auto_approved resolution when decision has autoApproved flag", async () => {
     const deps = makeRunnerDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      checkPermission: vi
+        .fn()
+        .mockReturnValue(
+          makeCheckResult({ state: "ask", matchedPattern: "*" }),
+        ),
       promptPermission: vi.fn().mockResolvedValue({
         approved: true,
         state: "approved",
@@ -304,7 +266,11 @@ describe("runGateCheck", () => {
 
   it("passes requestId from toolCallId to promptPermission", async () => {
     const deps = makeRunnerDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      checkPermission: vi
+        .fn()
+        .mockReturnValue(
+          makeCheckResult({ state: "ask", matchedPattern: "*" }),
+        ),
     });
     await runGateCheck(makeDescriptor(), null, "tc-42", deps);
     expect(deps.promptPermission).toHaveBeenCalledWith(
@@ -314,7 +280,11 @@ describe("runGateCheck", () => {
 
   it("does not call recordSessionApproval when user approves once (no sessionApproval)", async () => {
     const deps = makeRunnerDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      checkPermission: vi
+        .fn()
+        .mockReturnValue(
+          makeCheckResult({ state: "ask", matchedPattern: "*" }),
+        ),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved" }),
@@ -326,7 +296,8 @@ describe("runGateCheck", () => {
   it("uses preCheck result directly instead of calling checkPermission", async () => {
     const deps = makeRunnerDeps();
     const descriptor = makeDescriptor({
-      preCheck: makeCheckResult("deny", {
+      preCheck: makeCheckResult({
+        state: "deny",
         origin: "global",
         matchedPattern: "rm *",
       }),
@@ -345,7 +316,11 @@ describe("runGateCheck", () => {
 
   it("does not call recordSessionApproval when user approves for session but no sessionApproval on descriptor", async () => {
     const deps = makeRunnerDeps({
-      checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+      checkPermission: vi
+        .fn()
+        .mockReturnValue(
+          makeCheckResult({ state: "ask", matchedPattern: "*" }),
+        ),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved_for_session" }),
@@ -386,11 +361,15 @@ describe("runGateCheck", () => {
 
     it("uses denialContext to format denyReason with extension tag", async () => {
       const deps = makeRunnerDeps({
-        checkPermission: vi.fn().mockReturnValue(makeCheckResult("deny")),
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(
+            makeCheckResult({ state: "deny", matchedPattern: "*" }),
+          ),
       });
       const ctx: DenialContext = {
         kind: "tool",
-        check: makeCheckResult("deny"),
+        check: makeCheckResult({ state: "deny", matchedPattern: "*" }),
         agentName: "test-agent",
       };
       const result = await runGateCheck(
@@ -408,12 +387,16 @@ describe("runGateCheck", () => {
 
     it("uses denialContext to format unavailableReason with extension tag", async () => {
       const deps = makeRunnerDeps({
-        checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(
+            makeCheckResult({ state: "ask", matchedPattern: "*" }),
+          ),
         canConfirm: vi.fn().mockReturnValue(false),
       });
       const ctx: DenialContext = {
         kind: "tool",
-        check: makeCheckResult("ask"),
+        check: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       };
       const result = await runGateCheck(
         makeDenialContextDescriptor(ctx),
@@ -430,7 +413,11 @@ describe("runGateCheck", () => {
 
     it("uses denialContext to format userDeniedReason with extension tag", async () => {
       const deps = makeRunnerDeps({
-        checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
+        checkPermission: vi
+          .fn()
+          .mockReturnValue(
+            makeCheckResult({ state: "ask", matchedPattern: "*" }),
+          ),
         promptPermission: vi.fn().mockResolvedValue({
           approved: false,
           state: "denied",
@@ -439,7 +426,7 @@ describe("runGateCheck", () => {
       });
       const ctx: DenialContext = {
         kind: "tool",
-        check: makeCheckResult("ask"),
+        check: makeCheckResult({ state: "ask", matchedPattern: "*" }),
       };
       const result = await runGateCheck(
         makeDenialContextDescriptor(ctx),