@komarspn/pi-permission-system 16.0.2

package/src/path-utils.ts

@@ -0,0 +1,355 @@
+import {
+  join,
+  normalize,
+  posix as posixPath,
+  relative,
+  resolve,
+  win32 as winPath,
+} from "node:path";
+
+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(
+  pathValue: string,
+  cwd: string,
+): string {
+  const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
+  if (!trimmed) {
+    return "";
+  }
+
+  let normalizedPath = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+  normalizedPath = expandHomePath(normalizedPath);
+
+  const absolutePath = resolve(cwd, normalizedPath);
+  const normalizedAbsolutePath = normalize(absolutePath);
+  return process.platform === "win32"
+    ? normalizedAbsolutePath.toLowerCase()
+    : normalizedAbsolutePath;
+}
+
+/**
+ * Returns true when `pathValue` is `directory` itself or nested inside it.
+ *
+ * Containment is decided with Node's platform-native `path.relative` rather
+ * than a hand-rolled prefix check: on `win32` the comparison folds case (and
+ * tolerates either separator), matching the case-insensitive filesystem.
+ * `platform` defaults to `process.platform` and is injectable so Windows
+ * behavior is testable on a POSIX CI.
+ */
+export function isPathWithinDirectory(
+  pathValue: string,
+  directory: string,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (!pathValue || !directory) {
+    return false;
+  }
+
+  if (pathValue === directory) {
+    return true;
+  }
+
+  const impl = platform === "win32" ? winPath : posixPath;
+  const rel = impl.relative(directory, pathValue);
+  return (
+    rel !== "" &&
+    rel !== ".." &&
+    !rel.startsWith(`..${impl.sep}`) &&
+    !impl.isAbsolute(rel)
+  );
+}
+
+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]),
+  ];
+}
+
+/**
+ * Equivalent `external_directory` policy-match values for a path: the lexical
+ * (as-typed) alias list plus the canonical (symlink-resolved) absolute path.
+ *
+ * The outside-CWD boundary decision uses the canonical form separately; this
+ * helper exists only for pattern matching, so a user's pattern on the typed
+ * path (`/tmp/*`) and on the resolved path (`/private/tmp/*`) both match under
+ * the last-match-wins alias evaluation. On systems where the path is not a
+ * symlink the canonical form equals the lexical absolute alias and the `Set`
+ * collapses it, leaving today's behavior unchanged.
+ */
+export function getExternalDirectoryPolicyValues(
+  pathValue: string,
+  cwd: string,
+): string[] {
+  const lexical = getPathPolicyValues(pathValue, { cwd });
+  const canonical = canonicalNormalizePathForComparison(pathValue, cwd);
+  return canonical ? [...new Set([...lexical, canonical])] : lexical;
+}
+
+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.
+ */
+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);
+}
+
+/**
+ * File tools that only read — never write — the filesystem.
+ * Only these tools are eligible for the Pi infrastructure auto-allow.
+ */
+export const READ_ONLY_PATH_BEARING_TOOLS: ReadonlySet<string> = new Set([
+  "read",
+  "find",
+  "grep",
+  "ls",
+]);
+
+export const PATH_BEARING_TOOLS = new Set([
+  "read",
+  "write",
+  "edit",
+  "find",
+  "grep",
+  "ls",
+]);
+
+/**
+ * Surfaces whose patterns are matched against filesystem paths and therefore
+ * fold case (and separators) on Windows: the path-bearing tools plus the
+ * cross-cutting `path` gate and the `external_directory` boundary gate.
+ */
+export const PATH_SURFACES: ReadonlySet<string> = new Set([
+  ...PATH_BEARING_TOOLS,
+  "external_directory",
+  "path",
+]);
+
+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);
+}
+
+/**
+ * Like {@link normalizePathForComparison} but also resolves symlinks via
+ * `realpathSync` (best-effort). Use this for containment decisions where the
+ * OS-followed path matters, not for pattern matching.
+ */
+export function canonicalNormalizePathForComparison(
+  pathValue: string,
+  cwd: string,
+): string {
+  const lexical = normalizePathForComparison(pathValue, cwd);
+  if (!lexical) return "";
+  const canonical = canonicalizePath(lexical);
+  return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+
+export function isPathOutsideWorkingDirectory(
+  pathValue: string,
+  cwd: string,
+): boolean {
+  const normalizedCwd = canonicalNormalizePathForComparison(cwd, cwd);
+  const normalizedPath = canonicalNormalizePathForComparison(pathValue, cwd);
+  if (!normalizedCwd || !normalizedPath) {
+    return false;
+  }
+  if (isSafeSystemPath(normalizedPath)) {
+    return false;
+  }
+  return !isPathWithinDirectory(normalizedPath, normalizedCwd);
+}
+
+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 = process.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/pattern-suggest.ts

@@ -0,0 +1,132 @@
+import { prefix, stripBashCommentLines } from "./bash-arity";
+import { PATH_BEARING_TOOLS } from "./path-utils";
+import { deriveApprovalPattern } from "./session-rules";
+
+/** The suggestion returned for a "Yes, for this session" dialog option. */
+export interface SessionApprovalSuggestion {
+  /** The permission surface this approval applies to. */
+  surface: string;
+  /** The wildcard pattern to store as a session rule. */
+  pattern: string;
+  /** Human-readable label for the "for session" dialog option. */
+  label: string;
+}
+
+/**
+ * Suggest a bash session-approval pattern from a command string.
+ *
+ * Uses the arity table (`src/bash-arity.ts`) to identify the semantically
+ * meaningful prefix tokens for the command, then produces a wildcard pattern:
+ *
+ * - Single bare token (no args): exact command (`ls`).
+ * - Arity prefix covers all tokens: trailing wildcard (`npm run build*`).
+ * - Arity prefix shorter than token list: space + wildcard (`git checkout *`).
+ * - Unknown command: first token + space wildcard (`mytool *`).
+ */
+export function suggestBashPattern(command: string): string {
+  const trimmed = command.trim();
+  if (!trimmed) return "";
+  // Strip leading shell comment lines so the suggestion is based on the
+  // actual command, not a `# description` prefix agents often prepend.
+  const stripped = stripBashCommentLines(trimmed);
+  if (!stripped) return "";
+  const tokens = stripped.split(/\s+/);
+  if (tokens.length === 1) return stripped;
+  const meaningful = prefix(tokens);
+  if (meaningful.length >= tokens.length) {
+    return `${stripped}*`;
+  }
+  return `${meaningful.join(" ")} *`;
+}
+
+/**
+ * Suggest an MCP session-approval pattern from a resolved target string.
+ *
+ * - Qualified target (`server:tool`) → `server:*`
+ * - Munged target (`server_tool`) → `server_*`
+ * - Bare target (no separator) → `*`
+ */
+export function suggestMcpPattern(target: string): string {
+  const trimmed = target.trim();
+
+  const colonIndex = trimmed.indexOf(":");
+  if (colonIndex > 0) {
+    return `${trimmed.slice(0, colonIndex)}:*`;
+  }
+
+  const underscoreIndex = trimmed.indexOf("_");
+  if (underscoreIndex > 0) {
+    return `${trimmed.slice(0, underscoreIndex)}_*`;
+  }
+
+  return "*";
+}
+
+/** Surface-aware human-readable labels for the session-approval option. */
+function buildLabel(pattern: string, surface: string): string {
+  switch (surface) {
+    case "bash":
+      return `Yes, allow bash "${pattern}" for this session`;
+    case "mcp":
+      return `Yes, allow mcp tool "${pattern}" for this session`;
+    case "skill":
+      return `Yes, allow skill "${pattern}" for this session`;
+    case "external_directory":
+      return `Yes, allow access to external directory "${pattern}" for this session`;
+    case "path":
+      return `Yes, allow path "${pattern}" for this session`;
+    default:
+      // Path-bearing tools with a specific path pattern show the pattern.
+      if (PATH_BEARING_TOOLS.has(surface) && pattern !== "*") {
+        return `Yes, allow ${surface} "${pattern}" for this session`;
+      }
+      // Tool surfaces with catch-all or extension tools.
+      return `Yes, allow tool "${surface}" for this session`;
+  }
+}
+
+/**
+ * Suggest a session-approval pattern for the given permission surface and value.
+ *
+ * Returns a `SessionApprovalSuggestion` with the surface, the wildcard pattern
+ * to store in `SessionRules`, and a human-readable dialog label.
+ *
+ * `value` is expected to be the canonical (cwd-resolved, absolute) path for
+ * path surfaces — callers resolve it before suggesting, so the derived pattern
+ * matches the policy values a later tool call produces.
+ */
+export function suggestSessionPattern(
+  surface: string,
+  value: string,
+): SessionApprovalSuggestion {
+  let pattern: string;
+
+  switch (surface) {
+    case "bash":
+      pattern = suggestBashPattern(value);
+      break;
+    case "mcp":
+      pattern = suggestMcpPattern(value);
+      break;
+    case "skill":
+      pattern = value;
+      break;
+    case "external_directory":
+      pattern = deriveApprovalPattern(value);
+      break;
+    case "path":
+      pattern = deriveApprovalPattern(value);
+      break;
+    default:
+      // Path-bearing tools: derive a directory-scoped pattern from the path.
+      if (PATH_BEARING_TOOLS.has(surface) && value !== "*") {
+        pattern = deriveApprovalPattern(value);
+        break;
+      }
+      // Extension tools / fallback.
+      pattern = "*";
+      break;
+  }
+
+  return { surface, pattern, label: buildLabel(pattern, surface) };
+}

package/src/permission-dialog.ts

@@ -0,0 +1,138 @@
+export type PermissionDecisionState =
+  | "approved"
+  | "approved_for_session"
+  | "approved_for_project"
+  | "approved_globally"
+  | "denied"
+  | "denied_with_reason";
+
+export type PermissionPromptDecision = {
+  approved: boolean;
+  state: PermissionDecisionState;
+  denialReason?: string;
+  /**
+   * True when the decision was made automatically by yolo mode rather than
+   * by an interactive user prompt. Used by handlers to emit "auto_approved"
+   * rather than "user_approved" in the permissions:decision broadcast.
+   */
+  autoApproved?: true;
+};
+
+export interface PermissionDecisionUi {
+  select(title: string, options: string[]): Promise<string | undefined>;
+  input(title: string, placeholder?: string): Promise<string | undefined>;
+}
+
+const APPROVE_OPTION = "Yes";
+const APPROVE_FOR_SESSION_OPTION = "Yes, for this session";
+const APPROVE_FOR_PROJECT_OPTION = "Yes, always for this project";
+const APPROVE_GLOBALLY_OPTION = "Yes, always for all projects";
+const DENY_OPTION = "No";
+const DENY_WITH_REASON_OPTION = "No, provide reason";
+
+export function normalizePermissionDenialReason(
+  value: unknown,
+): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function createDeniedPermissionDecision(
+  denialReason?: string,
+): PermissionPromptDecision {
+  const normalizedReason = normalizePermissionDenialReason(denialReason);
+  return normalizedReason
+    ? {
+        approved: false,
+        state: "denied_with_reason",
+        denialReason: normalizedReason,
+      }
+    : {
+        approved: false,
+        state: "denied",
+      };
+}
+
+export function isPermissionDecisionState(
+  value: unknown,
+): value is PermissionDecisionState {
+  return (
+    value === "approved" ||
+    value === "approved_for_session" ||
+    value === "approved_for_project" ||
+    value === "approved_globally" ||
+    value === "denied" ||
+    value === "denied_with_reason"
+  );
+}
+
+export interface RequestPermissionOptions {
+  /** Override the "for this session" option label (e.g. to show the suggested pattern). */
+  sessionLabel?: string;
+}
+
+export async function requestPermissionDecisionFromUi(
+  ui: PermissionDecisionUi,
+  title: string,
+  message: string,
+  options?: RequestPermissionOptions,
+): Promise<PermissionPromptDecision> {
+  const sessionOption = options?.sessionLabel ?? APPROVE_FOR_SESSION_OPTION;
+  const decisionOptions = [
+    APPROVE_OPTION,
+    sessionOption,
+    APPROVE_FOR_PROJECT_OPTION,
+    APPROVE_GLOBALLY_OPTION,
+    DENY_OPTION,
+    DENY_WITH_REASON_OPTION,
+  ] as const;
+
+  const selected = await ui.select(`${title}\n${message}`, [
+    ...decisionOptions,
+  ]);
+
+  if (selected === APPROVE_OPTION) {
+    return {
+      approved: true,
+      state: "approved",
+    };
+  }
+
+  if (selected === sessionOption) {
+    return {
+      approved: true,
+      state: "approved_for_session",
+    };
+  }
+
+  if (selected === APPROVE_FOR_PROJECT_OPTION) {
+    return {
+      approved: true,
+      state: "approved_for_project",
+    };
+  }
+
+  if (selected === APPROVE_GLOBALLY_OPTION) {
+    return {
+      approved: true,
+      state: "approved_globally",
+    };
+  }
+
+  if (selected === DENY_WITH_REASON_OPTION) {
+    const denialReason = normalizePermissionDenialReason(
+      await ui.input(
+        `${title}\nShare why this request was denied (optional).`,
+        "Reason shown back to the agent",
+      ),
+    );
+
+    return createDeniedPermissionDecision(denialReason);
+  }
+
+  return createDeniedPermissionDecision();
+}