@komarspn/pi-permission-system 16.0.2

package/src/input-normalizer.ts

@@ -0,0 +1,157 @@
+import { stripBashCommentLines } from "./bash-arity";
+import { getNonEmptyString, toRecord } from "./common";
+import { createMcpPermissionTargets } from "./mcp-targets";
+import { getPathPolicyValues, PATH_BEARING_TOOLS } from "./path-utils";
+
+/**
+ * Construct a surface-appropriate input object from a raw value string.
+ *
+ * This is the inverse of `normalizeInput()` — it builds the minimal input
+ * object that `PermissionManager.checkPermission()` expects for a given
+ * surface, from a single string value.
+ *
+ * Used by the event-bus RPC handler and the `Symbol.for()` service accessor
+ * so external callers can query policy with `(surface, value)` instead of
+ * constructing a full tool-call input payload.
+ *
+ * Note: MCP inputs are complex (server name + tool name derivation). Callers
+ * providing an MCP surface receive a best-effort policy evaluation using the
+ * value as a pre-qualified target string. Pass the fully-qualified target
+ * (e.g. "exa:search" or "exa") directly.
+ */
+export function buildInputForSurface(
+  surface: string,
+  value: string | undefined,
+): unknown {
+  const v = value ?? "";
+  if (surface === "bash") return { command: v };
+  if (surface === "skill") return { name: v };
+  if (surface === "external_directory") return { path: v };
+  // MCP and tool surfaces: normalizeInput handles them from the surface alone.
+  return {};
+}
+
+/**
+ * Surface-normalized representation of a tool invocation used by
+ * `checkPermission()` to feed a single `evaluateFirst()` call.
+ */
+export interface NormalizedInput {
+  /** The permission surface for `evaluate()` (e.g. "bash", "mcp", "skill"). */
+  surface: string;
+  /**
+   * Candidate lookup values in priority order (most-specific first).
+   * Most surfaces produce a single-element array; MCP produces a
+   * multi-candidate list derived from the invocation input.
+   */
+  values: string[];
+  /**
+   * Surface-specific fields forwarded verbatim into `PermissionCheckResult`
+   * (e.g. `{ command }` for bash, `{ target }` for mcp).
+   */
+  resultExtras: Record<string, unknown>;
+}
+
+const SPECIAL_PERMISSION_KEYS = new Set(["external_directory", "path"]);
+
+/**
+ * Map a raw tool invocation to the surface/values/extras triple needed by
+ * `checkPermission()`.
+ *
+ * @param toolName - Normalized (trimmed) tool name from the tool-call event.
+ * @param input    - Raw input payload from the tool-call event.
+ * @param configuredMcpServerNames - Ordered list of MCP server names from the
+ *   global MCP config, used to derive server-qualified MCP targets.
+ */
+export function normalizeInput(
+  toolName: string,
+  input: unknown,
+  configuredMcpServerNames: readonly string[],
+  cwd?: string,
+): NormalizedInput {
+  // --- Special surfaces (path, external_directory) ---
+  if (SPECIAL_PERMISSION_KEYS.has(toolName)) {
+    return {
+      surface: toolName,
+      values: normalizePathSurfaceValues(input, cwd),
+      resultExtras: {},
+    };
+  }
+
+  // --- Skill ---
+  if (toolName === "skill") {
+    const record = toRecord(input);
+    const skillName = record.name;
+    const lookupValue = typeof skillName === "string" ? skillName : "*";
+    return {
+      surface: "skill",
+      values: [lookupValue],
+      resultExtras: {},
+    };
+  }
+
+  // --- Bash ---
+  if (toolName === "bash") {
+    const record = toRecord(input);
+    const command = typeof record.command === "string" ? record.command : "";
+    // Strip leading shell comment lines so pattern matching operates on the
+    // actual command, not a `# description` prefix agents often prepend.
+    // Fall back to the raw command when stripping leaves nothing, so an
+    // all-comment command still evaluates against its literal text.
+    const matchValue = stripBashCommentLines(command) || command;
+    return {
+      surface: "bash",
+      values: [matchValue],
+      resultExtras: { command },
+    };
+  }
+
+  // --- MCP ---
+  if (toolName === "mcp") {
+    const mcpTargets = [
+      ...createMcpPermissionTargets(input, configuredMcpServerNames),
+      "mcp",
+    ];
+    const fallbackTarget = mcpTargets[0] ?? "mcp";
+    return {
+      surface: "mcp",
+      values: mcpTargets,
+      resultExtras: { target: fallbackTarget },
+    };
+  }
+
+  // --- Path-bearing tools (read, write, edit, grep, find, ls) ---
+  if (PATH_BEARING_TOOLS.has(toolName)) {
+    return {
+      surface: toolName,
+      values: normalizePathSurfaceValues(input, cwd),
+      resultExtras: {},
+    };
+  }
+
+  // --- Extension tools (non-path-bearing) ---
+  return {
+    surface: toolName,
+    values: ["*"],
+    resultExtras: {},
+  };
+}
+
+/**
+ * Extract and normalize the path lookup values shared by every path surface
+ * (`path`, `external_directory`, and the path-bearing tools).
+ *
+ * Missing, empty, or whitespace-only paths collapse to the surface catch-all
+ * `"*"`. When CWD is known, a relative path also produces a normalized
+ * absolute policy value and a project-relative alias while keeping its legacy
+ * relative value, so values match home- and cwd-anchored patterns
+ * symmetrically with how the patterns themselves are expanded (#350).
+ *
+ * Only `input.path` is read — policy values are never sourced from any other
+ * (potentially attacker-controlled) field on the raw tool input.
+ */
+function normalizePathSurfaceValues(input: unknown, cwd?: string): string[] {
+  const path = getNonEmptyString(toRecord(input).path);
+  if (path === null) return ["*"];
+  const values = getPathPolicyValues(path, cwd ? { cwd } : {});
+  return values.length > 0 ? values : ["*"];
+}

package/src/logging.ts

@@ -0,0 +1,113 @@
+import { appendFileSync } from "node:fs";
+
+import {
+  EXTENSION_ID,
+  type PermissionSystemExtensionConfig,
+} from "./extension-config";
+
+export function safeJsonStringify(value: unknown): string | undefined {
+  const seen = new WeakSet<object>();
+  return JSON.stringify(value, (_key, currentValue) => {
+    if (currentValue instanceof Error) {
+      return {
+        name: currentValue.name,
+        message: currentValue.message,
+        stack: currentValue.stack,
+      };
+    }
+
+    if (typeof currentValue === "bigint") {
+      return currentValue.toString();
+    }
+
+    if (typeof currentValue === "object" && currentValue !== null) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument -- JSON.stringify replacer receives any; currentValue is narrowed to object here
+      if (seen.has(currentValue)) {
+        return "[Circular]";
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument -- same as above
+      seen.add(currentValue);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- JSON.stringify replacer must return any
+    return currentValue;
+  });
+}
+
+export interface PermissionSystemLogger {
+  debug: (
+    event: string,
+    details?: Record<string, unknown>,
+  ) => string | undefined;
+  review: (
+    event: string,
+    details?: Record<string, unknown>,
+  ) => string | undefined;
+}
+
+interface PermissionSystemLoggerOptions {
+  getConfig: () => PermissionSystemExtensionConfig;
+  debugLogPath: string;
+  reviewLogPath: string;
+  ensureLogsDirectory: () => string | undefined;
+}
+
+export function createPermissionSystemLogger(
+  options: PermissionSystemLoggerOptions,
+): PermissionSystemLogger {
+  const { debugLogPath, reviewLogPath, ensureLogsDirectory } = options;
+
+  const writeLine = (
+    stream: "debug" | "review",
+    path: string,
+    event: string,
+    details: Record<string, unknown>,
+  ): string | undefined => {
+    const directoryError = ensureLogsDirectory();
+    if (directoryError) {
+      return directoryError;
+    }
+
+    try {
+      const line = safeJsonStringify({
+        timestamp: new Date().toISOString(),
+        extension: EXTENSION_ID,
+        stream,
+        event,
+        ...details,
+      });
+      if (!line) {
+        return `Failed to write permission-system ${stream} log '${path}': event could not be serialized.`;
+      }
+      appendFileSync(path, `${line}\n`, "utf-8");
+      return undefined;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return `Failed to write permission-system ${stream} log '${path}': ${message}`;
+    }
+  };
+
+  const debug = (
+    event: string,
+    details: Record<string, unknown> = {},
+  ): string | undefined => {
+    if (!options.getConfig().debugLog) {
+      return undefined;
+    }
+
+    return writeLine("debug", debugLogPath, event, details);
+  };
+
+  const review = (
+    event: string,
+    details: Record<string, unknown> = {},
+  ): string | undefined => {
+    if (!options.getConfig().permissionReviewLog) {
+      return undefined;
+    }
+
+    return writeLine("review", reviewLogPath, event, details);
+  };
+
+  return { debug, review };
+}

package/src/mcp-targets.ts

@@ -0,0 +1,170 @@
+import { getNonEmptyString, toRecord } from "./common";
+
+/**
+ * An ordered accumulator that owns the uniqueness invariant.
+ *
+ * `add` ignores null/empty values and silently skips duplicates (first-insertion
+ * wins). `toArray` returns the ordered result as an independent copy.
+ */
+export class McpTargetList {
+  private readonly targets: string[] = [];
+
+  add(value: string | null): void {
+    if (!value) {
+      return;
+    }
+    if (!this.targets.includes(value)) {
+      this.targets.push(value);
+    }
+  }
+
+  toArray(): string[] {
+    return [...this.targets];
+  }
+}
+
+/**
+ * Parse a qualified MCP tool name of the form `server:tool`.
+ *
+ * Returns `{ server, tool }` when the string contains exactly one colon with
+ * non-empty text on both sides; otherwise returns `null`.
+ */
+export function parseQualifiedMcpToolName(
+  value: string,
+): { server: string; tool: string } | null {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  const colonIndex = trimmed.indexOf(":");
+  if (colonIndex <= 0 || colonIndex >= trimmed.length - 1) {
+    return null;
+  }
+
+  const server = trimmed.slice(0, colonIndex).trim();
+  const tool = trimmed.slice(colonIndex + 1).trim();
+  if (!server || !tool) {
+    return null;
+  }
+
+  return { server, tool };
+}
+
+function addDerivedMcpServerTargets(
+  toolName: string,
+  configuredServerNames: readonly string[],
+  targets: McpTargetList,
+): void {
+  const trimmedToolName = toolName.trim();
+  if (!trimmedToolName) {
+    return;
+  }
+
+  for (const serverName of configuredServerNames) {
+    const trimmedServerName = serverName.trim();
+    if (!trimmedServerName) {
+      continue;
+    }
+
+    if (!trimmedToolName.endsWith(`_${trimmedServerName}`)) {
+      continue;
+    }
+
+    if (trimmedToolName.startsWith(`${trimmedServerName}_`)) {
+      continue;
+    }
+
+    targets.add(`${trimmedServerName}_${trimmedToolName}`);
+    targets.add(`${trimmedServerName}:${trimmedToolName}`);
+    targets.add(trimmedServerName);
+  }
+}
+
+function pushMcpToolPermissionTargets(
+  rawReference: string,
+  serverHint: string | null,
+  configuredServerNames: readonly string[],
+  targets: McpTargetList,
+): void {
+  const qualified = parseQualifiedMcpToolName(rawReference);
+  const resolvedServer = serverHint ?? qualified?.server ?? null;
+  const resolvedTool = qualified?.tool ?? rawReference;
+
+  if (resolvedServer) {
+    targets.add(`${resolvedServer}_${resolvedTool}`);
+    targets.add(`${resolvedServer}:${resolvedTool}`);
+    targets.add(resolvedServer);
+  } else {
+    addDerivedMcpServerTargets(resolvedTool, configuredServerNames, targets);
+  }
+
+  targets.add(resolvedTool);
+  targets.add(rawReference);
+}
+
+/**
+ * Derive the ordered list of MCP permission-lookup candidates from a raw MCP
+ * tool invocation input.
+ *
+ * Candidates are ordered from most-specific to least-specific so that
+ * `evaluateFirst()` stops at the first non-default match.
+ */
+export function createMcpPermissionTargets(
+  input: unknown,
+  configuredServerNames: readonly string[] = [],
+): string[] {
+  const record = toRecord(input);
+  const tool = getNonEmptyString(record.tool);
+  const server = getNonEmptyString(record.server);
+  const connect = getNonEmptyString(record.connect);
+  const describe = getNonEmptyString(record.describe);
+  const search = getNonEmptyString(record.search);
+
+  const targets = new McpTargetList();
+
+  if (tool) {
+    pushMcpToolPermissionTargets(tool, server, configuredServerNames, targets);
+    targets.add("mcp_call");
+    return targets.toArray();
+  }
+
+  if (connect) {
+    targets.add(`mcp_connect_${connect}`);
+    targets.add(connect);
+    targets.add("mcp_connect");
+    return targets.toArray();
+  }
+
+  if (describe) {
+    pushMcpToolPermissionTargets(
+      describe,
+      server,
+      configuredServerNames,
+      targets,
+    );
+    targets.add("mcp_describe");
+    return targets.toArray();
+  }
+
+  if (search) {
+    if (server) {
+      targets.add(`mcp_server_${server}`);
+      targets.add(server);
+    }
+
+    targets.add(search);
+    targets.add("mcp_search");
+    return targets.toArray();
+  }
+
+  if (server) {
+    targets.add(`mcp_server_${server}`);
+    targets.add(server);
+    targets.add("mcp_list");
+    return targets.toArray();
+  }
+
+  targets.add("mcp_status");
+  return targets.toArray();
+}

package/src/node-modules-discovery.ts

@@ -0,0 +1,76 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Walk up the directory tree from the given file URL until a directory
+ * literally named `node_modules` is found.
+ *
+ * Returns the `node_modules` path, or `null` if the URL cannot be parsed or
+ * no `node_modules` ancestor exists.
+ */
+function walkUpToNodeModules(fromUrl: string): string | null {
+  try {
+    const thisFile = fileURLToPath(fromUrl);
+    let dir = dirname(thisFile);
+    while (dir !== dirname(dir)) {
+      if (basename(dir) === "node_modules") {
+        return dir;
+      }
+      dir = dirname(dir);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run `npm root -g` synchronously and return the trimmed output, or `null` on
+ * any failure (non-zero exit, ENOENT, timeout, non-existent path).
+ *
+ * Only called when the walk-up-from-self strategy fails (i.e. the extension is
+ * running from a local development checkout, not a global install).
+ */
+function discoverGlobalNodeModulesViaSubprocess(): string | null {
+  try {
+    const result = spawnSync("npm", ["root", "-g"], {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const root = result.stdout.trim();
+    if (result.status === 0 && root && existsSync(root)) {
+      return root;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Discover the global node_modules root.
+ *
+ * Strategy 1 (zero-cost, covers all global installs): walk up from
+ * `fromUrl` (defaults to this module's own `import.meta.url`) looking for a
+ * directory named `node_modules`. This works whenever the extension is
+ * installed inside a `node_modules` tree.
+ *
+ * Strategy 2 (subprocess fallback, dev checkout only): when Strategy 1 fails
+ * because the extension is running from a local development checkout with no
+ * `node_modules` ancestor, run `npm root -g` to discover the global root.
+ * Pi installs skills and extensions via `npm` by default, so `npm root -g`
+ * returns the correct root regardless of the user's own project package
+ * manager.
+ *
+ * Returns `null` when both strategies fail — callers must degrade gracefully.
+ */
+export function discoverGlobalNodeModulesRoot(
+  fromUrl = import.meta.url,
+): string | null {
+  const fromSelf = walkUpToNodeModules(fromUrl);
+  if (fromSelf) return fromSelf;
+  return discoverGlobalNodeModulesViaSubprocess();
+}

package/src/normalize.ts

@@ -0,0 +1,43 @@
+import { isDenyWithReason, isPermissionState } from "./common";
+import type { Rule, Ruleset } from "./rule";
+import type { FlatPermissionConfig } from "./types";
+
+/**
+ * Convert a flat permission config into a Ruleset.
+ *
+ * Each key is a surface name. A string value is shorthand for
+ * `{ "*": action }`. An object value maps patterns to actions.
+ * A pattern value may be a PermissionState string or a `DenyWithReason`
+ * object (`{ action: "deny", reason?: string }`).
+ * Invalid action values are silently skipped.
+ *
+ * The universal fallback key `"*"` is included if present — callers
+ * that use `"*"` only for `synthesizeDefaults()` should strip it before
+ * calling this function.
+ */
+export function normalizeFlatConfig(permission: FlatPermissionConfig): Ruleset {
+  const rules: Rule[] = [];
+  for (const [surface, value] of Object.entries(permission)) {
+    if (typeof value === "string") {
+      if (isPermissionState(value)) {
+        rules.push({ surface, pattern: "*", action: value, origin: "builtin" });
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive null check; value type does not include null but runtime JSON may
+    } else if (typeof value === "object" && value !== null) {
+      for (const [pattern, action] of Object.entries(value)) {
+        if (isDenyWithReason(action)) {
+          rules.push({
+            surface,
+            pattern,
+            action: "deny",
+            reason: action.reason,
+            origin: "builtin",
+          });
+        } else if (isPermissionState(action)) {
+          rules.push({ surface, pattern, action, origin: "builtin" });
+        }
+      }
+    }
+  }
+  return rules;
+}