@aliou/pi-guardrails 0.5.4 → 0.6.1

package/hooks/permission-gate.ts

@@ -1,3 +1,4 @@
+import { parse } from "@aliou/sh";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { DynamicBorder } from "@mariozechner/pi-coding-agent";
 import {
@@ -8,66 +9,161 @@ import {
   Text,
   wrapTextWithAnsi,
 } from "@mariozechner/pi-tui";
-import type { ResolvedConfig } from "../config-schema";
-import { emitBlocked, emitDangerous } from "../events";
+import type { DangerousPattern, ResolvedConfig } from "../config";
+import { emitBlocked, emitDangerous } from "../utils/events";
+import {
+  type CompiledPattern,
+  compileCommandPatterns,
+} from "../utils/matching";
+import { walkCommands, wordToString } from "../utils/shell-utils";
 
 /**
  * Permission gate that prompts user confirmation for dangerous commands.
- * Patterns, confirmation behavior, allow/deny lists are all configurable.
+ *
+ * Built-in dangerous patterns are matched structurally via AST parsing.
+ * User custom patterns use substring/regex matching on the raw string.
+ * Allowed/auto-deny patterns match against the raw command string.
  */
 
+/**
+ * Structural matcher for a built-in dangerous command.
+ * Returns a description if matched, undefined otherwise.
+ */
+type StructuralMatcher = (words: string[]) => string | undefined;
+
+/**
+ * Built-in dangerous command matchers. These check the parsed command
+ * structure instead of regex against the raw string.
+ */
+const BUILTIN_MATCHERS: StructuralMatcher[] = [
+  // rm -rf
+  (words) => {
+    if (words[0] !== "rm") return undefined;
+    const hasRF = words.some(
+      (w) =>
+        w === "-rf" ||
+        w === "-fr" ||
+        (w.startsWith("-") && w.includes("r") && w.includes("f")),
+    );
+    return hasRF ? "recursive force delete" : undefined;
+  },
+  // sudo
+  (words) => (words[0] === "sudo" ? "superuser command" : undefined),
+  // dd if=
+  (words) => {
+    if (words[0] !== "dd") return undefined;
+    return words.some((w) => w.startsWith("if="))
+      ? "disk write operation"
+      : undefined;
+  },
+  // mkfs.*
+  (words) => (words[0]?.startsWith("mkfs.") ? "filesystem format" : undefined),
+  // chmod -R 777
+  (words) => {
+    if (words[0] !== "chmod") return undefined;
+    return words.includes("-R") && words.includes("777")
+      ? "insecure recursive permissions"
+      : undefined;
+  },
+  // chown -R
+  (words) => {
+    if (words[0] !== "chown") return undefined;
+    return words.includes("-R") ? "recursive ownership change" : undefined;
+  },
+];
+
+interface DangerMatch {
+  description: string;
+  pattern: string;
+}
+
+/**
+ * Check a parsed command against built-in structural matchers.
+ */
+function checkBuiltinDangerous(words: string[]): DangerMatch | undefined {
+  if (words.length === 0) return undefined;
+  for (const matcher of BUILTIN_MATCHERS) {
+    const desc = matcher(words);
+    if (desc) return { description: desc, pattern: "(structural)" };
+  }
+  return undefined;
+}
+
+/**
+ * Check a command string against dangerous patterns.
+ *
+ * When useBuiltinMatchers is true (default patterns): tries structural AST
+ * matching first, falls back to substring match on parse failure.
+ *
+ * When useBuiltinMatchers is false (customPatterns replaced defaults): skips
+ * structural matchers entirely, uses compiled patterns (substring/regex)
+ * against the raw command string.
+ */
+function findDangerousMatch(
+  command: string,
+  compiledPatterns: CompiledPattern[],
+  useBuiltinMatchers: boolean,
+  fallbackPatterns: DangerousPattern[],
+): DangerMatch | undefined {
+  if (useBuiltinMatchers) {
+    // Try structural matching first
+    try {
+      const { ast } = parse(command);
+      let match: DangerMatch | undefined;
+      walkCommands(ast, (cmd) => {
+        const words = (cmd.words ?? []).map(wordToString);
+        const result = checkBuiltinDangerous(words);
+        if (result) {
+          match = result;
+          return true;
+        }
+        return false;
+      });
+      if (match) return match;
+    } catch {
+      // Parse failed -- fall back to substring matching on raw string
+      for (const p of fallbackPatterns) {
+        if (command.includes(p.pattern)) {
+          return { description: p.description, pattern: p.pattern };
+        }
+      }
+    }
+  }
+
+  // Check compiled patterns (substring/regex on raw string).
+  // When customPatterns replaces defaults, this is the only matching path.
+  for (const cp of compiledPatterns) {
+    if (cp.test(command)) {
+      const src = cp.source as DangerousPattern;
+      return { description: src.description, pattern: src.pattern };
+    }
+  }
+
+  return undefined;
+}
+
 export function setupPermissionGateHook(
   pi: ExtensionAPI,
   config: ResolvedConfig,
 ) {
   if (!config.features.permissionGate) return;
 
-  // Compile patterns, skipping invalid regex
-  const dangerousPatterns = config.permissionGate.patterns
-    .map((p) => {
-      try {
-        return {
-          pattern: new RegExp(p.pattern),
-          description: p.description,
-          rawPattern: p.pattern,
-        };
-      } catch {
-        console.error(
-          `Invalid regex in guardrails permission-gate config: ${p.pattern}`,
-        );
-        return null;
-      }
-    })
-    .filter(
-      (p): p is { pattern: RegExp; description: string; rawPattern: string } =>
-        p !== null,
-    );
+  // Compile all configured patterns for substring/regex matching.
+  // When useBuiltinMatchers is true (defaults), these act as a supplement
+  // to the structural matchers. When false (customPatterns), these are the
+  // only matching path.
+  const compiledPatterns = compileCommandPatterns(
+    config.permissionGate.patterns,
+  );
+  const { useBuiltinMatchers } = config.permissionGate;
+  const fallbackPatterns = config.permissionGate.patterns;
 
-  const allowedPatterns = config.permissionGate.allowedPatterns
-    .map((p) => {
-      try {
-        return new RegExp(p);
-      } catch {
-        console.error(
-          `Invalid regex in guardrails allowedPatterns config: ${p}`,
-        );
-        return null;
-      }
-    })
-    .filter((r): r is RegExp => r !== null);
-
-  const autoDenyPatterns = config.permissionGate.autoDenyPatterns
-    .map((p) => {
-      try {
-        return new RegExp(p);
-      } catch {
-        console.error(
-          `Invalid regex in guardrails autoDenyPatterns config: ${p}`,
-        );
-        return null;
-      }
-    })
-    .filter((r): r is RegExp => r !== null);
+  const allowedPatterns = compileCommandPatterns(
+    config.permissionGate.allowedPatterns,
+  );
+  const autoDenyPatterns = compileCommandPatterns(
+    config.permissionGate.autoDenyPatterns,
+  );
 
   pi.on("tool_call", async (event, ctx) => {
     if (event.toolName !== "bash") return;
@@ -98,104 +194,112 @@ export function setupPermissionGateHook(
       }
     }
 
-    // Check dangerous patterns
-    for (const { pattern, description, rawPattern } of dangerousPatterns) {
-      if (pattern.test(command)) {
-        // Emit dangerous event (presenter will play sound)
-        emitDangerous(pi, { command, description, pattern: rawPattern });
-
-        if (config.permissionGate.requireConfirmation) {
-          const proceed = await ctx.ui.custom<boolean>(
-            (_tui, theme, _kb, done) => {
-              const container = new Container();
-              const redBorder = (s: string) => theme.fg("error", s);
-
-              container.addChild(new DynamicBorder(redBorder));
-              container.addChild(
-                new Text(
-                  theme.fg("error", theme.bold("Dangerous Command Detected")),
-                  1,
-                  0,
-                ),
-              );
-              container.addChild(new Spacer(1));
-              container.addChild(
-                new Text(
-                  theme.fg("warning", `This command contains ${description}:`),
-                  1,
-                  0,
-                ),
-              );
-              container.addChild(new Spacer(1));
-              container.addChild(
-                new DynamicBorder((s: string) => theme.fg("muted", s)),
-              );
-              const commandText = new Text("", 1, 0);
-              container.addChild(commandText);
-              container.addChild(
-                new DynamicBorder((s: string) => theme.fg("muted", s)),
-              );
-              container.addChild(new Spacer(1));
-              container.addChild(
-                new Text(theme.fg("text", "Allow execution?"), 1, 0),
-              );
-              container.addChild(new Spacer(1));
-              container.addChild(
-                new Text(theme.fg("dim", "y/enter: allow • n/esc: deny"), 1, 0),
-              );
-              container.addChild(new DynamicBorder(redBorder));
-
-              return {
-                render: (width: number) => {
-                  const wrappedCommand = wrapTextWithAnsi(
-                    theme.fg("text", command),
-                    width - 4,
-                  ).join("\n");
-                  commandText.setText(wrappedCommand);
-                  return container.render(width);
-                },
-                invalidate: () => container.invalidate(),
-                handleInput: (data: string) => {
-                  if (
-                    matchesKey(data, Key.enter) ||
-                    data === "y" ||
-                    data === "Y"
-                  ) {
-                    done(true);
-                  } else if (
-                    matchesKey(data, Key.escape) ||
-                    data === "n" ||
-                    data === "N"
-                  ) {
-                    done(false);
-                  }
-                },
-              };
-            },
-          );
-
-          if (!proceed) {
-            emitBlocked(pi, {
-              feature: "permissionGate",
-              toolName: "bash",
-              input: event.input,
-              reason: "User denied dangerous command",
-              userDenied: true,
-            });
-
-            return { block: true, reason: "User denied dangerous command" };
-          }
-        } else {
-          // No confirmation required - just notify and allow
-          ctx.ui.notify(
-            `Dangerous command detected: ${description}`,
-            "warning",
-          );
-        }
+    // Check dangerous patterns (structural + compiled)
+    const match = findDangerousMatch(
+      command,
+      compiledPatterns,
+      useBuiltinMatchers,
+      fallbackPatterns,
+    );
+    if (!match) return;
+
+    const { description, pattern: rawPattern } = match;
 
-        break;
+    // Emit dangerous event (presenter will play sound)
+    emitDangerous(pi, { command, description, pattern: rawPattern });
+
+    if (config.permissionGate.requireConfirmation) {
+      // In print/RPC mode, block by default (safe fallback)
+      if (!ctx.hasUI) {
+        const reason = `Dangerous command blocked (no UI to confirm): ${description}`;
+        emitBlocked(pi, {
+          feature: "permissionGate",
+          toolName: "bash",
+          input: event.input,
+          reason,
+        });
+        return { block: true, reason };
       }
+
+      const proceed = await ctx.ui.custom<boolean>((_tui, theme, _kb, done) => {
+        const container = new Container();
+        const redBorder = (s: string) => theme.fg("error", s);
+
+        container.addChild(new DynamicBorder(redBorder));
+        container.addChild(
+          new Text(
+            theme.fg("error", theme.bold("Dangerous Command Detected")),
+            1,
+            0,
+          ),
+        );
+        container.addChild(new Spacer(1));
+        container.addChild(
+          new Text(
+            theme.fg("warning", `This command contains ${description}:`),
+            1,
+            0,
+          ),
+        );
+        container.addChild(new Spacer(1));
+        container.addChild(
+          new DynamicBorder((s: string) => theme.fg("muted", s)),
+        );
+        const commandText = new Text("", 1, 0);
+        container.addChild(commandText);
+        container.addChild(
+          new DynamicBorder((s: string) => theme.fg("muted", s)),
+        );
+        container.addChild(new Spacer(1));
+        container.addChild(
+          new Text(theme.fg("text", "Allow execution?"), 1, 0),
+        );
+        container.addChild(new Spacer(1));
+        container.addChild(
+          new Text(theme.fg("dim", "y/enter: allow • n/esc: deny"), 1, 0),
+        );
+        container.addChild(new DynamicBorder(redBorder));
+
+        return {
+          render: (width: number) => {
+            const wrappedCommand = wrapTextWithAnsi(
+              theme.fg("text", command),
+              width - 4,
+            ).join("\n");
+            commandText.setText(wrappedCommand);
+            return container.render(width);
+          },
+          invalidate: () => container.invalidate(),
+          handleInput: (data: string) => {
+            if (matchesKey(data, Key.enter) || data === "y" || data === "Y") {
+              done(true);
+            } else if (
+              matchesKey(data, Key.escape) ||
+              data === "n" ||
+              data === "N"
+            ) {
+              done(false);
+            }
+          },
+        };
+      });
+
+      if (!proceed) {
+        emitBlocked(pi, {
+          feature: "permissionGate",
+          toolName: "bash",
+          input: event.input,
+          reason: "User denied dangerous command",
+          userDenied: true,
+        });
+
+        return { block: true, reason: "User denied dangerous command" };
+      }
+    } else {
+      // No confirmation required - just notify and allow
+      ctx.ui.notify(`Dangerous command detected: ${description}`, "warning");
     }
+
     return;
   });
 }

package/hooks/protect-env-files.ts

@@ -1,14 +1,19 @@
 import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
+import { parse } from "@aliou/sh";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import type { ResolvedConfig } from "../config-schema";
-import { emitBlocked } from "../events";
+import type { ResolvedConfig } from "../config";
+import { emitBlocked } from "../utils/events";
+import { expandGlob, hasGlobChars } from "../utils/glob-expander";
+import { type CompiledPattern, compileFilePatterns } from "../utils/matching";
+import { walkCommands, wordToString } from "../utils/shell-utils";
 
 /**
  * Prevents accessing .env files unless they match an allowed pattern.
  * Protects sensitive environment files from being accessed accidentally.
  *
- * Covers configurable set of tools (default: read, write, edit, bash, grep, find, ls).
+ * Uses AST-based parsing for bash commands to extract file references,
+ * with glob expansion via `fd` when args contain shell glob characters.
  */
 
 async function fileExists(filePath: string): Promise<boolean> {
@@ -20,48 +25,115 @@ async function fileExists(filePath: string): Promise<boolean> {
   }
 }
 
-function compilePatterns(patterns: string[]): RegExp[] {
-  return patterns
-    .map((p) => {
-      try {
-        return new RegExp(p, "i");
-      } catch {
-        console.error(`Invalid regex pattern in guardrails config: ${p}`);
-        return null;
-      }
-    })
-    .filter((r): r is RegExp => r !== null);
-}
-
 async function isProtectedEnvFile(
   filePath: string,
-  config: ResolvedConfig,
+  protectedPatterns: CompiledPattern[],
+  allowedPatterns: CompiledPattern[],
+  dirPatterns: CompiledPattern[],
+  onlyBlockIfExists: boolean,
 ): Promise<boolean> {
-  const protectedRegexes = compilePatterns(config.envFiles.protectedPatterns);
-  const isProtected = protectedRegexes.some((r) => r.test(filePath));
+  const isProtected = protectedPatterns.some((p) => p.test(filePath));
   if (!isProtected) return false;
 
-  const allowedRegexes = compilePatterns(config.envFiles.allowedPatterns);
-  const isAllowed = allowedRegexes.some((r) => r.test(filePath));
+  const isAllowed = allowedPatterns.some((p) => p.test(filePath));
   if (isAllowed) return false;
 
   // Check protected directories (if any configured)
-  if (config.envFiles.protectedDirectories.length > 0) {
-    const dirRegexes = compilePatterns(config.envFiles.protectedDirectories);
-    const inProtectedDir = dirRegexes.some((r) => r.test(filePath));
+  if (dirPatterns.length > 0) {
+    const inProtectedDir = dirPatterns.some((p) => p.test(filePath));
     if (inProtectedDir) {
-      return config.envFiles.onlyBlockIfExists
-        ? await fileExists(filePath)
-        : true;
+      return onlyBlockIfExists ? await fileExists(filePath) : true;
+    }
+  }
+
+  return onlyBlockIfExists ? await fileExists(filePath) : true;
+}
+
+/**
+ * Extract file references from a bash command using AST parsing.
+ * Falls back to regex extraction on parse failure.
+ */
+async function extractBashFileTargets(command: string): Promise<string[]> {
+  try {
+    const { ast } = parse(command);
+    const files: string[] = [];
+
+    walkCommands(ast, (cmd) => {
+      const words = (cmd.words ?? []).map(wordToString);
+      // Skip command name (words[0]), check args for env file references
+      for (let i = 1; i < words.length; i++) {
+        const arg = words[i] as string;
+        if (isEnvLikeReference(arg)) {
+          files.push(arg);
+        }
+      }
+
+      // Also check redirect targets
+      for (const redir of cmd.redirects ?? []) {
+        const target = wordToString(redir.target);
+        if (isEnvLikeReference(target)) {
+          files.push(target);
+        }
+      }
+      return false;
+    });
+
+    // Expand globs
+    const expanded: string[] = [];
+    for (const file of files) {
+      if (hasGlobChars(file)) {
+        const matches = await expandGlob(file);
+        if (matches.length > 0) {
+          expanded.push(...matches);
+        } else {
+          // Expansion returned nothing -- could be fd not found or no matches.
+          // Keep original as-is so pattern matching can still catch it.
+          expanded.push(file);
+        }
+      } else {
+        expanded.push(file);
+      }
     }
+
+    return expanded;
+  } catch {
+    // Fallback: regex extraction from raw string
+    return extractEnvFilesRegex(command);
+  }
+}
+
+/**
+ * Check if a string looks like an env file reference.
+ * Matches anything containing ".env" as a path component.
+ */
+function isEnvLikeReference(arg: string): boolean {
+  // Must contain ".env" somewhere
+  if (!arg.includes(".env") && !arg.includes(".dev.vars")) return false;
+  // Skip flags
+  if (arg.startsWith("-") && !arg.startsWith("-/") && !arg.startsWith("-."))
+    return false;
+  return true;
+}
+
+/**
+ * Fallback regex extraction for env file references in bash commands.
+ */
+function extractEnvFilesRegex(command: string): string[] {
+  const files: string[] = [];
+  const envFileRegex =
+    /(?:^|\s|[<>|;&"'`])([^\s<>|;&"'`]*\.env[^\s<>|;&"'`]*)(?:\s|$|[<>|;&"'`])/gi;
+
+  for (const match of command.matchAll(envFileRegex)) {
+    const file = match[1];
+    if (file) files.push(file);
   }
 
-  return config.envFiles.onlyBlockIfExists ? await fileExists(filePath) : true;
+  return files;
 }
 
 interface ToolProtectionRule {
   tools: string[];
-  extractTargets: (input: Record<string, unknown>) => string[];
+  extractTargets: (input: Record<string, unknown>) => Promise<string[]>;
   shouldBlock: (target: string) => Promise<boolean>;
   blockMessage: (target: string) => string;
 }
@@ -72,36 +144,41 @@ export function setupProtectEnvFilesHook(
 ) {
   if (!config.features.protectEnvFiles) return;
 
+  const protectedPatterns = compileFilePatterns(
+    config.envFiles.protectedPatterns,
+  );
+  const allowedPatterns = compileFilePatterns(config.envFiles.allowedPatterns);
+  const dirPatterns = compileFilePatterns(config.envFiles.protectedDirectories);
+
+  const shouldBlock = (target: string) =>
+    isProtectedEnvFile(
+      target,
+      protectedPatterns,
+      allowedPatterns,
+      dirPatterns,
+      config.envFiles.onlyBlockIfExists,
+    );
+
   const protectionRules: ToolProtectionRule[] = [
     {
       tools: config.envFiles.protectedTools.filter((t) =>
         ["read", "write", "edit", "grep", "find", "ls"].includes(t),
       ),
-      extractTargets: (input) => {
+      extractTargets: async (input) => {
         const path = String(input.file_path ?? input.path ?? "");
         return path ? [path] : [];
       },
-      shouldBlock: (target) => isProtectedEnvFile(target, config),
+      shouldBlock,
       blockMessage: (target) =>
         config.envFiles.blockMessage.replace("{file}", target),
     },
     {
       tools: config.envFiles.protectedTools.includes("bash") ? ["bash"] : [],
-      extractTargets: (input) => {
+      extractTargets: async (input) => {
         const command = String(input.command ?? "");
-        const files: string[] = [];
-
-        const envFileRegex =
-          /(?:^|\s|[<>|;&"'`])([^\s<>|;&"'`]*\.env[^\s<>|;&"'`]*)(?:\s|$|[<>|;&"'`])/gi;
-
-        for (const match of command.matchAll(envFileRegex)) {
-          const file = match[1];
-          if (file) files.push(file);
-        }
-
-        return files;
+        return extractBashFileTargets(command);
       },
-      shouldBlock: (target) => isProtectedEnvFile(target, config),
+      shouldBlock,
       blockMessage: (target) =>
         `Command references protected file ${target}. ` +
         config.envFiles.blockMessage.replace("{file}", target),
@@ -120,7 +197,7 @@ export function setupProtectEnvFilesHook(
     const rule = rulesByTool.get(event.toolName);
     if (!rule) return;
 
-    const targets = rule.extractTargets(event.input);
+    const targets = await rule.extractTargets(event.input);
 
     for (const target of targets) {
       if (await rule.shouldBlock(target)) {

package/index.ts

@@ -1,16 +1,19 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerGuardrailsSettings } from "./commands/settings-command";
 import { configLoader } from "./config";
 import { setupGuardrailsHooks } from "./hooks";
-import { registerSettingsCommand } from "./settings-command";
 
 /**
  * Guardrails Extension
  *
  * Security hooks to prevent potentially dangerous operations:
- * - prevent-brew: Blocks Homebrew commands (project uses Nix)
  * - protect-env-files: Prevents access to .env files (except .example/.sample/.test)
  * - permission-gate: Prompts for confirmation on dangerous commands
  *
+ * Toolchain features (preventBrew, preventPython, enforcePackageManager,
+ * packageManager) have been moved to @aliou/pi-toolchain. Old configs
+ * containing these fields are auto-migrated on first load.
+ *
  * Configuration:
  * - Global: ~/.pi/agent/extensions/guardrails.json
  * - Project: .pi/extensions/guardrails.json
@@ -23,5 +26,5 @@ export default async function (pi: ExtensionAPI) {
   if (!config.enabled) return;
 
   setupGuardrailsHooks(pi, config);
-  registerSettingsCommand(pi);
+  registerGuardrailsSettings(pi);
 }