@gotgenes/pi-permission-system 11.0.0 → 13.0.0

package/src/path-utils.ts

@@ -2,6 +2,7 @@ import {
   join,
   normalize,
   posix as posixPath,
+  relative,
   resolve,
   win32 as winPath,
 } from "node:path";
@@ -9,6 +10,7 @@ import {
 import { canonicalizePath } from "./canonicalize-path";
 import { getNonEmptyString, toRecord } from "./common";
 import { expandHomePath } from "./expand-home";
+import type { ToolAccessExtractorLookup } from "./tool-access-extractor-registry";
 import { wildcardMatch } from "./wildcard-matcher";
 
 export function normalizePathForComparison(
@@ -62,6 +64,86 @@ export function isPathWithinDirectory(
   );
 }
 
+export interface PathPolicyValueOptions {
+  /**
+   * Current Pi working directory. When provided, returned values include a
+   * project-relative alias for paths that resolve inside this directory.
+   */
+  cwd?: string;
+  /**
+   * Directory used to resolve `pathValue` into an absolute policy value.
+   * Defaults to `cwd`. Bash uses this for tokens seen after a literal `cd`.
+   */
+  resolveBase?: string;
+}
+
+/**
+ * Normalize a single path-like lookup value without resolving it against CWD.
+ *
+ * Preserves compatibility with existing relative path rules (`src/*`, `*.env`)
+ * while applying the same lexical cleanup as
+ * {@link normalizePathForComparison}: trim, strip simple wrapping quotes,
+ * strip the OpenCode-style leading `@`, and expand `~` / `$HOME`.
+ */
+export function normalizePathPolicyLiteral(pathValue: string): string {
+  const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
+  if (!trimmed) return "";
+  const unprefixed = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+  return expandHomePath(unprefixed);
+}
+
+/**
+ * Return equivalent lookup values for path-policy matching.
+ *
+ * The first value is the cwd/effective-base normalized absolute path when a
+ * base is available. The later values preserve project-relative and raw
+ * relative forms so existing rules like `src/*` and `*.env` continue to match.
+ */
+export function getPathPolicyValues(
+  pathValue: string,
+  options: PathPolicyValueOptions = {},
+): string[] {
+  const literal = normalizePathPolicyLiteral(pathValue);
+  if (!literal) return [];
+  if (literal === "*") return ["*"];
+
+  return [
+    ...new Set([...getAbsolutePathPolicyValues(pathValue, options), literal]),
+  ];
+}
+
+function getAbsolutePathPolicyValues(
+  pathValue: string,
+  options: PathPolicyValueOptions,
+): string[] {
+  const resolveBase = options.resolveBase ?? options.cwd;
+  if (!resolveBase) return [];
+
+  const absolute = normalizePathForComparison(pathValue, resolveBase);
+  if (!absolute) return [];
+
+  return [absolute, ...getCwdRelativePathPolicyValues(absolute, options.cwd)];
+}
+
+function getCwdRelativePathPolicyValues(
+  absolute: string,
+  cwd: string | undefined,
+): string[] {
+  if (!cwd) return [];
+
+  const normalizedCwd = normalizePathForComparison(cwd, cwd);
+  if (!normalizedCwd) return [];
+  if (
+    absolute !== normalizedCwd &&
+    !isPathWithinDirectory(absolute, normalizedCwd)
+  ) {
+    return [];
+  }
+
+  const relativeValue = relative(normalizedCwd, absolute);
+  return relativeValue ? [relativeValue] : [];
+}
+
 /**
  * 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.
@@ -123,6 +205,46 @@ export function getPathBearingToolPath(
   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);
+}
+
 /**
  * Like {@link normalizePathForComparison} but also resolves symlinks via
  * `realpathSync` (best-effort). Use this for containment decisions where the

package/src/permission-manager.ts

@@ -3,6 +3,7 @@ import { isPermissionState } from "./common";
 import { getGlobalConfigPath, getProjectConfigPath } from "./config-paths";
 import { normalizeInput } from "./input-normalizer";
 import { normalizeFlatConfig } from "./normalize";
+import { PATH_SURFACES } from "./path-utils";
 import {
   FilePolicyLoader,
   type PolicyLoader,
@@ -10,7 +11,7 @@ import {
   type ResolvedPolicyPaths,
 } from "./policy-loader";
 import type { Rule, RuleOrigin, Ruleset } from "./rule";
-import { evaluate, evaluateFirst } from "./rule";
+import { evaluate, evaluateAnyValue, evaluateFirst } from "./rule";
 import { mergeScopesWithOrigins } from "./scope-merge";
 import {
   composeRuleset,
@@ -63,6 +64,17 @@ export interface ScopedPermissionManager {
     agentName?: string,
     sessionRules?: Ruleset,
   ): PermissionCheckResult;
+  /**
+   * Evaluate the cross-cutting `path` surface against a caller-supplied set of
+   * equivalent policy values (e.g. bash tokens already resolved against a
+   * preceding literal `cd`). The values are trusted because they are computed
+   * internally, never read from a field on raw tool input.
+   */
+  checkPathPolicy(
+    values: readonly string[],
+    agentName?: string,
+    sessionRules?: Ruleset,
+  ): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
   getConfigIssues(agentName?: string): string[];
   getPolicyCacheStamp(agentName?: string): string;
@@ -79,6 +91,7 @@ export interface PermissionManagerOptions extends PolicyLoaderOptions {
 
 export class PermissionManager implements ScopedPermissionManager {
   private readonly agentDir: string | undefined;
+  private currentCwd: string | undefined;
   private loader: PolicyLoader;
   private readonly resolvedPermissionsCache = new Map<
     string,
@@ -104,6 +117,8 @@ export class PermissionManager implements ScopedPermissionManager {
    * built with explicit paths), only the cache is cleared.
    */
   configureForCwd(cwd: string | undefined | null): void {
+    this.currentCwd =
+      typeof cwd === "string" && cwd.trim().length > 0 ? cwd : undefined;
     if (this.agentDir !== undefined) {
       this.loader = new FilePolicyLoader(
         derivePolicyLoaderOptions(this.agentDir, cwd),
@@ -245,29 +260,78 @@ export class PermissionManager implements ScopedPermissionManager {
       normalizedToolName,
       input,
       this.loader.getConfiguredMcpServerNames(),
+      this.currentCwd,
     );
 
-    const { rule, value } = evaluateFirst(surface, values, fullRules);
+    return buildCheckResult(
+      surface,
+      values,
+      resultExtras,
+      normalizedToolName,
+      toolName,
+      fullRules,
+    );
+  }
 
-    // For MCP, replace the normalizer's fallback target with the actual
-    // matched candidate value so PermissionCheckResult.target is accurate.
-    const extras =
-      surface === "mcp" ? { ...resultExtras, target: value } : resultExtras;
+  checkPathPolicy(
+    values: readonly string[],
+    agentName?: string,
+    sessionRules?: Ruleset,
+  ): PermissionCheckResult {
+    const { composedRules } = this.resolvePermissions(agentName);
+    const fullRules: Ruleset = sessionRules?.length
+      ? [...composedRules, ...sessionRules]
+      : composedRules;
 
-    return {
-      toolName,
-      state: rule.action,
-      matchedPattern:
-        rule.layer === "config" || rule.layer === "session"
-          ? rule.pattern
-          : undefined,
-      source: deriveSource(rule, normalizedToolName),
-      origin: rule.origin,
-      ...extras,
-    };
+    const lookupValues = values.length > 0 ? [...values] : ["*"];
+    return buildCheckResult(
+      "path",
+      lookupValues,
+      {},
+      "path",
+      "path",
+      fullRules,
+    );
   }
 }
 
+/**
+ * Evaluate a normalized surface/values triple and shape the result.
+ *
+ * Path surfaces use {@link evaluateAnyValue} (last-match-wins across equivalent
+ * aliases); every other surface keeps {@link evaluateFirst}. Shared by
+ * `checkPermission` and `checkPathPolicy`.
+ */
+function buildCheckResult(
+  surface: string,
+  values: string[],
+  resultExtras: Record<string, unknown>,
+  normalizedToolName: string,
+  toolName: string,
+  fullRules: Ruleset,
+): PermissionCheckResult {
+  const { rule, value } = PATH_SURFACES.has(surface)
+    ? evaluateAnyValue(surface, values, fullRules)
+    : evaluateFirst(surface, values, fullRules);
+
+  // For MCP, replace the normalizer's fallback target with the actual
+  // matched candidate value so PermissionCheckResult.target is accurate.
+  const extras =
+    surface === "mcp" ? { ...resultExtras, target: value } : resultExtras;
+
+  return {
+    toolName,
+    state: rule.action,
+    matchedPattern:
+      rule.layer === "config" || rule.layer === "session"
+        ? rule.pattern
+        : undefined,
+    source: deriveSource(rule, normalizedToolName),
+    origin: rule.origin,
+    ...extras,
+  };
+}
+
 /**
  * Derive `PolicyLoaderOptions` from an agentDir + an optional cwd.
  * Setting agentsDir explicitly from agentDir removes the hidden

package/src/permission-resolver.ts

@@ -17,6 +17,15 @@ export interface ScopedPermissionResolver {
     input: unknown,
     agentName?: string,
   ): PermissionCheckResult;
+  /**
+   * Resolve the cross-cutting `path` surface against a caller-supplied set of
+   * equivalent policy values, applying the current session rules. Used by the
+   * bash path gate, which computes cd-aware policy values per token.
+   */
+  resolvePathPolicy(
+    values: readonly string[],
+    agentName?: string,
+  ): PermissionCheckResult;
 }
 
 /**
@@ -53,6 +62,21 @@ export class PermissionResolver implements ScopedPermissionResolver {
     );
   }
 
+  /**
+   * Resolve the `path` surface for precomputed policy values, composing the
+   * current session ruleset so callers never thread it by hand.
+   */
+  resolvePathPolicy(
+    values: readonly string[],
+    agentName?: string,
+  ): PermissionCheckResult {
+    return this.permissionManager.checkPathPolicy(
+      values,
+      agentName,
+      this.sessionRules.getRuleset(),
+    );
+  }
+
   checkPermission(
     surface: string,
     input: unknown,

package/src/permission-session.ts

@@ -150,10 +150,8 @@ export class PermissionSession implements ToolCallGateInputs {
     return this.knownAgentName;
   }
 
-  // Read by config-modal (`controller.session.lastKnownActiveAgentName`).
-  // fallow cannot trace the getter through the command's object-literal
-  // wiring, so it reports a false positive here.
-  // fallow-ignore-next-line unused-class-member
+  // Read by the `index.ts` config-modal adapter closure:
+  // `permissionManager.getComposedConfigRules(session.lastKnownActiveAgentName ?? undefined)`.
   get lastKnownActiveAgentName(): string | null {
     return this.knownAgentName;
   }

package/src/permissions-service.ts

@@ -2,6 +2,10 @@ import { buildInputForSurface } from "./input-normalizer";
 import type { ScopedPermissionManager } from "./permission-manager";
 import type { PermissionsService } from "./service";
 import type { SessionRules } from "./session-rules";
+import type {
+  ToolAccessExtractor,
+  ToolAccessExtractorRegistrar,
+} from "./tool-access-extractor-registry";
 import type {
   ToolInputFormatter,
   ToolInputFormatterRegistrar,
@@ -19,6 +23,7 @@ export class LocalPermissionsService implements PermissionsService {
     private readonly permissionManager: ScopedPermissionManager,
     private readonly sessionRules: Pick<SessionRules, "getRuleset">,
     private readonly formatterRegistry: ToolInputFormatterRegistrar,
+    private readonly accessExtractorRegistry: ToolAccessExtractorRegistrar,
   ) {}
 
   checkPermission(
@@ -48,4 +53,11 @@ export class LocalPermissionsService implements PermissionsService {
   ): ReturnType<PermissionsService["registerToolInputFormatter"]> {
     return this.formatterRegistry.register(toolName, formatter);
   }
+
+  registerToolAccessExtractor(
+    toolName: string,
+    extractor: ToolAccessExtractor,
+  ): ReturnType<PermissionsService["registerToolAccessExtractor"]> {
+    return this.accessExtractorRegistry.register(toolName, extractor);
+  }
 }

package/src/rule.ts

@@ -55,17 +55,8 @@ export function evaluate(
   defaultAction?: PermissionState,
   platform: NodeJS.Platform = process.platform,
 ): Rule {
-  // On Windows, path-surface values are canonicalized + lowercased; fold the
-  // pattern→value match (case and separators) so mixed-case / forward-slash
-  // overrides still match. The surface→surface match stays exact.
-  const matchOptions =
-    platform === "win32" && PATH_SURFACES.has(surface)
-      ? { caseInsensitive: true, windowsSeparators: true }
-      : undefined;
-  const rule = rules.findLast(
-    (r) =>
-      wildcardMatch(r.surface, surface) &&
-      wildcardMatch(r.pattern, pattern, matchOptions),
+  const rule = rules.findLast((r) =>
+    ruleMatches(r, surface, pattern, platform),
   );
   if (rule !== undefined) return rule;
   return {
@@ -76,6 +67,33 @@ export function evaluate(
   };
 }
 
+/**
+ * On Windows, path-surface values are canonicalized + lowercased; fold the
+ * pattern→value match (case and separators) so mixed-case / forward-slash
+ * overrides still match. The surface→surface match stays exact.
+ */
+function pathMatchOptions(
+  surface: string,
+  platform: NodeJS.Platform,
+): { caseInsensitive: true; windowsSeparators: true } | undefined {
+  return platform === "win32" && PATH_SURFACES.has(surface)
+    ? { caseInsensitive: true, windowsSeparators: true }
+    : undefined;
+}
+
+function ruleMatches(
+  rule: Rule,
+  surface: string,
+  value: string,
+  platform: NodeJS.Platform,
+): boolean {
+  const matchOptions = pathMatchOptions(surface, platform);
+  return (
+    wildcardMatch(rule.surface, surface) &&
+    wildcardMatch(rule.pattern, value, matchOptions)
+  );
+}
+
 /**
  * Evaluate a surface against an ordered list of candidate values, stopping at
  * the first candidate that matches a non-default rule (last-match-wins within
@@ -134,3 +152,35 @@ export function evaluateFirst(
     value: fallbackValue,
   };
 }
+
+/**
+ * Evaluate equivalent lookup values as aliases of the same path.
+ *
+ * Unlike `evaluateFirst()`, this preserves rule ordering across aliases: the
+ * last rule that matches any alias wins. This lets absolute allowlists and
+ * legacy relative rules coexist without a catch-all match on the first alias
+ * masking a later, more specific rule on another alias.
+ */
+export function evaluateAnyValue(
+  surface: string,
+  values: string[],
+  rules: Ruleset,
+  platform: NodeJS.Platform = process.platform,
+): { rule: Rule; value: string } {
+  const fallbackValue = values[0] ?? "*";
+  const rule = rules.findLast((r) =>
+    values.some((value) => ruleMatches(r, surface, value, platform)),
+  );
+  if (rule !== undefined) {
+    return {
+      rule,
+      value:
+        values.find((value) => ruleMatches(rule, surface, value, platform)) ??
+        fallbackValue,
+    };
+  }
+  return {
+    rule: evaluate(surface, fallbackValue, rules),
+    value: fallbackValue,
+  };
+}

package/src/service.ts

@@ -11,6 +11,7 @@
  * reference — this ensures resilience across `/reload` and load-order edge cases.
  */
 
+import type { ToolAccessExtractor } from "./tool-access-extractor-registry";
 import type { ToolInputFormatter } from "./tool-input-formatter-registry";
 import type { PermissionCheckResult, PermissionState } from "./types";
 
@@ -80,6 +81,29 @@ export interface PermissionsService {
     formatter: ToolInputFormatter,
   ): () => void;
 
+  /**
+   * Register a custom access-intent extractor for a specific tool name.
+   *
+   * The extractor declares the filesystem path a tool will access so the
+   * cross-cutting `path` and `external_directory` gates can see it. Use it for
+   * tools whose path lives under a non-standard key — built-in file tools and
+   * any tool exposing `input.path` (plus MCP via `input.arguments.path`) are
+   * already covered by convention without registration.
+   *
+   * The extractor receives the raw `input` record and returns the path string,
+   * or `undefined` to decline. Only one extractor may be registered per tool
+   * name — a second call for the same name throws. The returned disposer
+   * unregisters the extractor.
+   *
+   * @param toolName  - Exact tool name to register for (e.g. `"ffgrep"`).
+   * @param extractor - Receives the raw `input` record; return the path string,
+   *                    or `undefined` to decline.
+   */
+  registerToolAccessExtractor(
+    toolName: string,
+    extractor: ToolAccessExtractor,
+  ): () => void;
+
   /**
    * Query the tool-level permission state for pre-filtering tools before
    * creating a child session.

package/src/tool-access-extractor-registry.ts

@@ -0,0 +1,68 @@
+/**
+ * Registry for custom tool access-intent extractors.
+ *
+ * Lets sibling extensions declare the filesystem path a tool will access when
+ * the tool's input shape is not the default `input.path` convention, so the
+ * cross-cutting `path` and `external_directory` gates can see it.
+ * One extractor per tool name; duplicate registration throws.
+ */
+
+/** Returns the filesystem path this tool will access, or `undefined` to decline. */
+export type ToolAccessExtractor = (
+  input: Record<string, unknown>,
+) => string | undefined;
+
+/**
+ * Read-only lookup used by the gate pipeline (ISP — exposes only the read
+ * side, not the registration surface).
+ */
+export interface ToolAccessExtractorLookup {
+  get(toolName: string): ToolAccessExtractor | undefined;
+}
+
+/**
+ * Registration side of the extractor registry (ISP — exposes only the write
+ * surface, mirroring the read-only {@link ToolAccessExtractorLookup}).
+ */
+export interface ToolAccessExtractorRegistrar {
+  register(toolName: string, extractor: ToolAccessExtractor): () => void;
+}
+
+/**
+ * Persistent registry mapping tool names to custom access-intent extractors.
+ *
+ * Owned by the extension factory (`index.ts`) so it survives across the
+ * per-tool-call gate evaluation cycle.
+ * Exposed to sibling extensions via `PermissionsService.registerToolAccessExtractor`.
+ */
+export class ToolAccessExtractorRegistry
+  implements ToolAccessExtractorLookup, ToolAccessExtractorRegistrar
+{
+  private readonly extractors = new Map<string, ToolAccessExtractor>();
+
+  /**
+   * Register an extractor for `toolName`.
+   *
+   * Throws if an extractor is already registered for that name — keeps
+   * resolution deterministic (a pi-permission-system package priority).
+   * Returns a disposer that removes the extractor; the disposer is
+   * identity-guarded so a stale call cannot evict a later registration.
+   */
+  register(toolName: string, extractor: ToolAccessExtractor): () => void {
+    if (this.extractors.has(toolName)) {
+      throw new Error(
+        `A tool access extractor is already registered for '${toolName}'.`,
+      );
+    }
+    this.extractors.set(toolName, extractor);
+    return () => {
+      if (this.extractors.get(toolName) === extractor) {
+        this.extractors.delete(toolName);
+      }
+    };
+  }
+
+  get(toolName: string): ToolAccessExtractor | undefined {
+    return this.extractors.get(toolName);
+  }
+}

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

@@ -18,10 +18,7 @@ vi.mock("node:fs", () => ({
 }));
 
 import { formatDenyReason } from "#src/denial-messages";
-import {
-  extractExternalPathsFromBashCommand,
-  extractTokensForPathRules,
-} from "#src/handlers/gates/bash-path-extractor";
+import { extractExternalPathsFromBashCommand } from "#src/handlers/gates/bash-path-extractor";
 import { formatBashExternalDirectoryAskPrompt } from "#src/handlers/gates/external-directory-messages";
 
 afterEach(() => {
@@ -957,80 +954,3 @@ describe("bash external-directory denial messages (centralized)", () => {
     expect(result).not.toContain("Hard stop");
   });
 });
-
-describe("extractTokensForPathRules", () => {
-  test("extracts dot-files: cat .env", async () => {
-    const tokens = await extractTokensForPathRules("cat .env");
-    expect(tokens).toContain(".env");
-  });
-
-  test("extracts relative dot-paths: git add src/.env", async () => {
-    const tokens = await extractTokensForPathRules("git add src/.env");
-    expect(tokens).toContain("src/.env");
-  });
-
-  test("extracts nothing from plain words: echo hello", async () => {
-    const tokens = await extractTokensForPathRules("echo hello");
-    expect(tokens).toHaveLength(0);
-  });
-
-  test("extracts ./src and skips flags: rm -rf ./src", async () => {
-    const tokens = await extractTokensForPathRules("rm -rf ./src");
-    expect(tokens).toContain("./src");
-    expect(tokens).not.toContain("-rf");
-  });
-
-  test("extracts absolute paths: cat /etc/hosts", async () => {
-    const tokens = await extractTokensForPathRules("cat /etc/hosts");
-    expect(tokens).toContain("/etc/hosts");
-  });
-
-  test("skips URLs: curl https://example.com", async () => {
-    const tokens = await extractTokensForPathRules("curl https://example.com");
-    expect(tokens).not.toContain("https://example.com");
-  });
-
-  test("extracts slash-containing tokens: cat src/foo.ts", async () => {
-    const tokens = await extractTokensForPathRules("cat src/foo.ts");
-    expect(tokens).toContain("src/foo.ts");
-  });
-
-  test("skips heredoc content", async () => {
-    const tokens = await extractTokensForPathRules("cat <<EOF\n.env\nEOF");
-    expect(tokens).not.toContain(".env");
-  });
-
-  test("skips @scope/package patterns", async () => {
-    const tokens = await extractTokensForPathRules(
-      "npm install @scope/package",
-    );
-    expect(tokens).not.toContain("@scope/package");
-  });
-
-  test("skips env assignments", async () => {
-    const tokens = await extractTokensForPathRules("FOO=/bar command");
-    expect(tokens).not.toContain("FOO=/bar");
-  });
-
-  test("skips bare-slash tokens", async () => {
-    const tokens = await extractTokensForPathRules("ls /");
-    expect(tokens).not.toContain("/");
-  });
-
-  test("extracts redirect targets: echo test > .env", async () => {
-    const tokens = await extractTokensForPathRules("echo test > .env");
-    expect(tokens).toContain(".env");
-  });
-
-  test("extracts multiple path tokens: cp .env .env.backup", async () => {
-    const tokens = await extractTokensForPathRules("cp .env .env.backup");
-    expect(tokens).toContain(".env");
-    expect(tokens).toContain(".env.backup");
-  });
-
-  test("deduplicates repeated tokens", async () => {
-    const tokens = await extractTokensForPathRules("cat .env && rm .env");
-    const envCount = tokens.filter((t) => t === ".env").length;
-    expect(envCount).toBe(1);
-  });
-});