@komarspn/pi-permission-system 16.0.2

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

@@ -0,0 +1,105 @@
+/**
+ * Pure, synchronous token-classification helpers for bash path extraction.
+ *
+ * Exports two classifiers consumed by `bash-program.ts`:
+ *   - `classifyTokenAsPathCandidate` — strict gate for the external-directory guard.
+ *   - `classifyTokenAsRuleCandidate` — broader gate for cross-cutting `path` rules.
+ *
+ * Both classifiers share the private `rejectNonPathToken` predicate that captures
+ * the seven rejection cases common to both (the production clone this module was
+ * extracted to eliminate).
+ */
+
+// ── Public classifiers ─────────────────────────────────────────────────────
+
+/**
+ * Strict path-candidate classifier for the external-directory guard.
+ *
+ * Accepts tokens that unambiguously look like filesystem paths:
+ * - Absolute paths (starting with `/`)
+ * - Home-relative paths (starting with `~/`)
+ * - Parent-traversal paths (containing `..`)
+ *
+ * Returns the raw token string if it qualifies, or `null` to skip.
+ */
+export function classifyTokenAsPathCandidate(token: string): string | null {
+  if (rejectNonPathToken(token)) return null;
+
+  if (token.startsWith("/")) return token;
+  if (token.startsWith("~/")) return token;
+  if (token.includes("..")) return token;
+
+  return null;
+}
+
+/**
+ * Broader token classifier for cross-cutting `path` permission rules.
+ *
+ * Accepts the same shapes as `classifyTokenAsPathCandidate`, plus:
+ * - Dot-files and `./`-relative paths (starting with `.`)
+ * - Any relative path containing `/` (e.g. `src/foo.ts`)
+ *
+ * The `~/foo` case is covered by `includes("/")` — no separate `~/` branch needed.
+ *
+ * Does NOT require the strict "must start with `/` or `~/` or contain `..`"
+ * gate that the external-directory classifier uses.
+ *
+ * Returns the raw token string if it qualifies, or `null` to skip.
+ */
+export function classifyTokenAsRuleCandidate(token: string): string | null {
+  if (rejectNonPathToken(token)) return null;
+
+  if (token.startsWith(".")) return token;
+  if (token.includes("/")) return token; // covers ~/ paths and all relative paths with /
+  if (token.includes("..")) return token; // bare ".." (no slash)
+
+  return null;
+}
+
+// ── Private rejection predicate ────────────────────────────────────────────
+
+/**
+ * URL pattern to skip tokens that look like URLs rather than paths.
+ */
+const URL_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+/**
+ * Regex metacharacter sequences that are never found in real filesystem paths.
+ * If a token contains any of these, it is almost certainly a regex pattern
+ * (e.g. a grep argument) rather than a path.
+ */
+const REGEX_METACHAR_PATTERN = /\.\*|\.\+|\\\||\\\(|\\\)|\[.*?\]|\^\//;
+
+/**
+ * Shared rejection prelude: returns `true` when a token can never be a
+ * filesystem path, regardless of which classifier is asking.
+ *
+ * Rejects: empty tokens, flags (leading `-`), env assignments (`FOO=/bar`),
+ * URLs, `@scope/package` patterns, bare-slash tokens, and regex metacharacter
+ * sequences.
+ */
+function rejectNonPathToken(token: string): boolean {
+  if (!token) return true;
+  if (token.startsWith("-")) return true;
+
+  // Env assignment: = appears before any /  (FOO=/bar is an assignment,
+  // /foo=bar is not because the slash comes first).
+  const eqIndex = token.indexOf("=");
+  const slashIndex = token.indexOf("/");
+  if (eqIndex !== -1 && (slashIndex === -1 || eqIndex < slashIndex))
+    return true;
+
+  if (URL_PATTERN.test(token)) return true;
+
+  // @scope/package patterns (npm scoped packages) — but @/ is allowed through
+  // since it looks like an absolute-rooted path, not an npm scope.
+  if (token.startsWith("@") && !token.startsWith("@/")) return true;
+
+  // Bare-slash tokens (/, //, ///) resolve to filesystem root and are never
+  // meaningful path arguments in practice.
+  if (/^\/+$/.test(token)) return true;
+
+  if (REGEX_METACHAR_PATTERN.test(token)) return true;
+
+  return false;
+}

package/src/handlers/gates/candidate-check.ts

@@ -0,0 +1,32 @@
+import type { PermissionCheckResult, PermissionState } from "#src/types";
+
+/** Restrictiveness ordering: deny is the most restrictive, allow the least. */
+const RESTRICTIVENESS: Record<PermissionState, number> = {
+  allow: 0,
+  ask: 1,
+  deny: 2,
+};
+
+/**
+ * Select the most restrictive permission result from a list (deny > ask > allow).
+ *
+ * The first occurrence wins on ties, so a caller passing results in candidate
+ * order receives the earliest worst case. Returns `undefined` for an empty list.
+ *
+ * Shared by the bash gates (path, external-directory) to combine the per-candidate
+ * `checkPermission` results their tree-sitter token extraction produces.
+ */
+export function pickMostRestrictive(
+  results: readonly PermissionCheckResult[],
+): PermissionCheckResult | undefined {
+  let worst: PermissionCheckResult | undefined;
+  for (const result of results) {
+    if (
+      worst === undefined ||
+      RESTRICTIVENESS[result.state] > RESTRICTIVENESS[worst.state]
+    ) {
+      worst = result;
+    }
+  }
+  return worst;
+}

package/src/handlers/gates/descriptor.ts

@@ -0,0 +1,81 @@
+import type { DenialContext } from "#src/denial-messages";
+import type { PermissionDecisionEvent } from "#src/permission-events";
+import type { PromptPermissionDetails } from "#src/permission-prompter";
+import type { SessionApproval } from "#src/session-approval";
+import type { PermissionCheckResult, PermissionState } from "#src/types";
+
+// ── Descriptor types ───────────────────────────────────────────────────────
+
+/**
+ * Pure output of a gate function — describes what to check and how to present it.
+ *
+ * The gate runner (`runGateCheck`) uses this descriptor to execute the
+ * mechanical check→log→emit→approve cycle without the gate needing to know
+ * about logging, event emission, or session-rule recording.
+ */
+export interface GateDescriptor {
+  /** Permission surface to check (e.g. "bash", "external_directory", "skill"). */
+  surface: string;
+  /** Input passed to checkPermission. */
+  input: unknown;
+  /** Structured denial context — the runner formats messages from this. */
+  denialContext: DenialContext;
+  /**
+   * Session-approval suggestion for the "for this session" option.
+   * Wraps either a single pattern or multiple patterns behind a unified
+   * interface — the runner never needs to know which case applies.
+   */
+  sessionApproval?: SessionApproval;
+  /** Details passed to the interactive permission prompt (requestId is added by the runner). */
+  promptDetails: Omit<PromptPermissionDetails, "requestId">;
+  /** Extra context fields written to the review log alongside gate outcomes. */
+  logContext: Record<string, unknown>;
+  /** Surface and value for the decision event (may differ from the check surface). */
+  decision: {
+    surface: string;
+    value: string;
+  };
+  /**
+   * When set, the gate has already resolved the permission state
+   * (e.g. from a skill entry match). The runner uses this directly
+   * instead of calling checkPermission.
+   */
+  preResolved?: {
+    state: PermissionState;
+  };
+  /**
+   * When set, the runner uses this pre-computed check result directly
+   * instead of calling checkPermission. Used when the orchestrator has
+   * already performed the check (e.g. to build messages from the result).
+   */
+  preCheck?: PermissionCheckResult;
+}
+
+/**
+ * Early allow result — gate has determined the action without needing the runner.
+ *
+ * Used for cases like Pi infrastructure read bypass where the gate short-circuits
+ * with a deterministic allow before reaching the permission check.
+ */
+export interface GateBypass {
+  action: "allow";
+  /** Optional review log entry to emit. */
+  log?: { event: string; details: Record<string, unknown> };
+  /** Optional decision event to emit. */
+  decision?: PermissionDecisionEvent;
+}
+
+/** Union of possible gate function return values. */
+export type GateResult = GateDescriptor | GateBypass | null;
+
+// ── Type guard helpers ─────────────────────────────────────────────────────
+
+/** Check whether a GateResult is a GateBypass (early allow). */
+export function isGateBypass(result: GateResult): result is GateBypass {
+  return result !== null && "action" in result;
+}
+
+/** Check whether a GateResult is a GateDescriptor (needs runner). */
+export function isGateDescriptor(result: GateResult): result is GateDescriptor {
+  return result !== null && !("action" in result);
+}

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

@@ -0,0 +1,20 @@
+export function formatExternalDirectoryAskPrompt(
+  toolName: string,
+  pathValue: string,
+  cwd: string,
+  agentName?: string,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+  return `${subject} requested tool '${toolName}' for path '${pathValue}' outside working directory '${cwd}'. Allow this external directory access?`;
+}
+
+export function formatBashExternalDirectoryAskPrompt(
+  command: string,
+  externalPaths: string[],
+  cwd: string,
+  agentName?: string,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+  const pathList = externalPaths.join(", ");
+  return `${subject} requested bash command '${command}' which references path(s) outside working directory '${cwd}': ${pathList}. Allow this external directory access?`;
+}

package/src/handlers/gates/external-directory.ts

@@ -0,0 +1,133 @@
+import {
+  canonicalNormalizePathForComparison,
+  getExternalDirectoryPolicyValues,
+  getToolInputPath,
+  isPathOutsideWorkingDirectory,
+  isPiInfrastructureRead,
+  normalizePathForComparison,
+} from "#src/path-utils";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import { SessionApproval } from "#src/session-approval";
+import { deriveApprovalPattern } from "#src/session-rules";
+import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
+import type { GateResult } from "./descriptor";
+import { formatExternalDirectoryAskPrompt } from "./external-directory-messages";
+import type { ToolCallContext } from "./types";
+
+/**
+ * Build a pure descriptor for the external-directory permission gate.
+ *
+ * Returns `null` when the gate does not apply (no CWD, tool is not
+ * path-bearing, or path is inside the working directory).
+ * Returns a `GateBypass` for Pi infrastructure reads.
+ * Returns a `GateDescriptor` for external paths needing a permission check.
+ */
+export function describeExternalDirectoryGate(
+  tcc: ToolCallContext,
+  infraDirs: string[],
+  resolver: ScopedPermissionResolver,
+  extractors?: ToolAccessExtractorLookup,
+): GateResult {
+  if (!tcc.cwd) return null;
+
+  const externalDirectoryPath = getToolInputPath(
+    tcc.toolName,
+    tcc.input,
+    extractors,
+  );
+  if (!externalDirectoryPath) return null;
+
+  if (!isPathOutsideWorkingDirectory(externalDirectoryPath, tcc.cwd)) {
+    return null;
+  }
+
+  // The boundary decision (above) and the infrastructure-read containment
+  // check (below) use the canonical, symlink-resolved path; pattern matching
+  // uses the typed and resolved aliases (#418).
+  const canonicalExtPath = canonicalNormalizePathForComparison(
+    externalDirectoryPath,
+    tcc.cwd,
+  );
+
+  // ── Pi infrastructure read bypass ──────────────────────────────────────
+  if (
+    isPiInfrastructureRead(tcc.toolName, canonicalExtPath, infraDirs, tcc.cwd)
+  ) {
+    return {
+      action: "allow",
+      log: {
+        event: "permission_request.infrastructure_auto_allowed",
+        details: {
+          source: "tool_call",
+          toolCallId: tcc.toolCallId,
+          toolName: tcc.toolName,
+          agentName: tcc.agentName,
+          path: externalDirectoryPath,
+        },
+      },
+      decision: {
+        surface: tcc.toolName,
+        value: externalDirectoryPath,
+        result: "allow",
+        resolution: "infrastructure_auto_allowed",
+        origin: null,
+        agentName: tcc.agentName ?? null,
+        matchedPattern: null,
+      },
+    };
+  }
+
+  // ── Build descriptor for permission check ───────────────────────────────
+  const extDirMessage = formatExternalDirectoryAskPrompt(
+    tcc.toolName,
+    externalDirectoryPath,
+    tcc.cwd,
+    tcc.agentName ?? undefined,
+  );
+
+  // Match against both the typed and symlink-resolved aliases on the
+  // external_directory surface, so a config pattern on either form applies
+  // (#418). The runner consumes this preCheck and skips its own resolve.
+  const preCheck = resolver.resolvePathPolicy(
+    getExternalDirectoryPolicyValues(externalDirectoryPath, tcc.cwd),
+    tcc.agentName ?? undefined,
+    "external_directory",
+  );
+  const pattern = deriveApprovalPattern(
+    normalizePathForComparison(externalDirectoryPath, tcc.cwd),
+  );
+
+  return {
+    surface: "external_directory",
+    input: {},
+    preCheck,
+    denialContext: {
+      kind: "external_directory",
+      toolName: tcc.toolName,
+      pathValue: externalDirectoryPath,
+      cwd: tcc.cwd,
+      agentName: tcc.agentName ?? undefined,
+    },
+    sessionApproval: SessionApproval.single("external_directory", pattern),
+    promptDetails: {
+      source: "tool_call",
+      agentName: tcc.agentName,
+      message: extDirMessage,
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      path: externalDirectoryPath,
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      agentName: tcc.agentName,
+      path: externalDirectoryPath,
+      message: extDirMessage,
+    },
+    decision: {
+      surface: "external_directory",
+      value: externalDirectoryPath,
+    },
+  };
+}

package/src/handlers/gates/helpers.ts

@@ -0,0 +1,76 @@
+import type {
+  PermissionDecisionEvent,
+  PermissionDecisionResolution,
+} from "#src/permission-events";
+import type { PermissionCheckResult } from "#src/types";
+
+/**
+ * Derive the human-readable value for a decision event from a check result.
+ * Bash → extracted command; MCP → qualified target;
+ * path-bearing tools → file path; others → tool name.
+ */
+export function deriveDecisionValue(
+  toolName: string,
+  check: Pick<PermissionCheckResult, "command" | "target">,
+  path?: string,
+): string {
+  if (toolName === "bash") return check.command ?? toolName;
+  if (toolName === "mcp") return check.target ?? toolName;
+  if (path) return path;
+  return toolName;
+}
+
+/**
+ * Build a `PermissionDecisionEvent` from the gate's inputs.
+ *
+ * Centralises the `origin / agentName / matchedPattern ?? null` normalization
+ * that is otherwise duplicated across the session-hit path and the gate-result
+ * path in `runGateCheck`.
+ */
+export function buildDecisionEvent(
+  decision: { surface: string; value: string },
+  check: Pick<PermissionCheckResult, "origin" | "matchedPattern">,
+  agentName: string | null,
+  result: "allow" | "deny",
+  resolution: PermissionDecisionResolution,
+): PermissionDecisionEvent {
+  return {
+    surface: decision.surface,
+    value: decision.value,
+    result,
+    resolution,
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- ?? null normalises undefined to null for the log record
+    origin: check.origin ?? null,
+    agentName: agentName ?? null,
+    matchedPattern: check.matchedPattern ?? null,
+  };
+}
+
+/**
+ * Map the gate outcome back to a PermissionDecisionResolution.
+ *
+ * @param state     - The permission state passed to the gate.
+ * @param action    - The gate's resulting action ("allow" | "block").
+ * @param hasSession - True when the gate result carries a sessionApproval
+ *                    (indicates the user chose "for this session").
+ * @param canConfirm - Whether an interactive prompt was available.
+ */
+export function deriveResolution(
+  state: "allow" | "deny" | "ask",
+  action: "allow" | "block",
+  hasSession: boolean,
+  canConfirm: boolean,
+  autoApproved = false,
+  persistentApprovalScope?: "project" | "global",
+): PermissionDecisionResolution {
+  if (state === "allow") return "policy_allow";
+  if (state === "deny") return "policy_deny";
+  // state === "ask"
+  if (action === "allow") {
+    if (autoApproved) return "auto_approved";
+    if (persistentApprovalScope === "project") return "user_approved_for_project";
+    if (persistentApprovalScope === "global") return "user_approved_globally";
+    return hasSession ? "user_approved_for_session" : "user_approved";
+  }
+  return canConfirm ? "user_denied" : "confirmation_unavailable";
+}

package/src/handlers/gates/path.ts

@@ -0,0 +1,91 @@
+import { getToolInputPath, normalizePathForComparison } from "#src/path-utils";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import { SessionApproval } from "#src/session-approval";
+import { deriveApprovalPattern } from "#src/session-rules";
+import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
+import type { GateDescriptor, GateResult } from "./descriptor";
+import type { ToolCallContext } from "./types";
+
+/**
+ * Build a pure descriptor for the cross-cutting path permission gate (tools).
+ *
+ * Returns `null` when the gate does not apply (tool is not path-bearing,
+ * no extractable path, the `path` surface evaluates to `allow`, or no
+ * explicit `path` rule matched — i.e. only the universal default fired).
+ * Returns a `GateDescriptor` when the path matches a `deny` or `ask` rule.
+ */
+export function describePathGate(
+  tcc: ToolCallContext,
+  resolver: ScopedPermissionResolver,
+  extractors?: ToolAccessExtractorLookup,
+): GateResult {
+  const filePath = getToolInputPath(tcc.toolName, tcc.input, extractors);
+  if (!filePath) return null;
+
+  const check = resolver.resolve(
+    "path",
+    { path: filePath },
+    tcc.agentName ?? undefined,
+  );
+
+  if (check.state === "allow") return null;
+
+  // No explicit path rule matched — only the universal default fired.
+  // Skip the gate to preserve backward compatibility: configs without a
+  // "path" key should not trigger path-level prompts (#58).
+  if (check.matchedPattern === undefined) return null;
+
+  // Resolve to the canonical (cwd-anchored, absolute) path so the approval
+  // pattern matches the policy values a later call produces.
+  const approvalPath = tcc.cwd
+    ? normalizePathForComparison(filePath, tcc.cwd)
+    : filePath;
+  const pattern = deriveApprovalPattern(approvalPath);
+
+  const descriptor: GateDescriptor = {
+    surface: "path",
+    input: { path: filePath },
+    denialContext: {
+      kind: "path",
+      toolName: tcc.toolName,
+      pathValue: filePath,
+      agentName: tcc.agentName ?? undefined,
+    },
+    sessionApproval: SessionApproval.single("path", pattern),
+    promptDetails: {
+      source: "tool_call",
+      agentName: tcc.agentName,
+      message: formatPathAskPrompt(
+        tcc.toolName,
+        filePath,
+        tcc.agentName ?? undefined,
+      ),
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      path: filePath,
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      agentName: tcc.agentName,
+      path: filePath,
+    },
+    decision: {
+      surface: "path",
+      value: filePath,
+    },
+    preCheck: check,
+  };
+
+  return descriptor;
+}
+
+export function formatPathAskPrompt(
+  toolName: string,
+  pathValue: string,
+  agentName?: string,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+  return `${subject} requested tool '${toolName}' for path '${pathValue}'. Allow this path access?`;
+}