@aliou/pi-guardrails 0.0.1 → 0.1.0

package/README.md

@@ -1,2 +1,72 @@
-# @aliou/pi-guardrails
-Placeholder for initial npm publish.
+# Guardrails
+
+Security hooks to prevent potentially dangerous operations.
+
+## Installation
+
+Install via the pi-extensions package:
+
+```bash
+pi install git:github.com/aliou/pi-extensions
+```
+
+Or selectively in your `settings.json`:
+
+```json
+{
+  "packages": [
+    {
+      "source": "git:github.com/aliou/pi-extensions",
+      "extensions": ["extensions/guardrails"]
+    }
+  ]
+}
+```
+
+Or from npm:
+
+```bash
+pi install npm:@aliou/pi-guardrails
+```
+
+## Features
+
+- **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
+
+## Hooks
+
+### prevent-brew
+
+Blocks bash commands that attempt to install packages using Homebrew. Notifies the user that the project uses Nix for package management.
+
+Blocked patterns:
+- `brew install`
+- `brew cask install`
+- `brew bundle`
+- `brew upgrade`
+- `brew reinstall`
+
+### protect-env-files
+
+Prevents accessing `.env` files that might contain secrets. Only allows access to safe variants:
+- `.env.example`
+- `.env.sample`
+- `.env.test`
+- `*.example.env`
+- `*.sample.env`
+- `*.test.env`
+
+Covers tools: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`
+
+### permission-gate
+
+Prompts user confirmation before executing dangerous commands:
+- `rm -rf` (recursive force delete)
+- `sudo` (superuser command)
+- `: | sh` (piped shell execution)
+- `dd if=` (disk write operation)
+- `mkfs.` (filesystem format)
+- `chmod -R 777` (insecure recursive permissions)
+- `chown -R` (recursive ownership change)

package/hooks/index.ts

@@ -0,0 +1,10 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { setupPermissionGateHook } from "./permission-gate";
+import { setupPreventBrewHook } from "./prevent-brew";
+import { setupProtectEnvFilesHook } from "./protect-env-files";
+
+export function setupGuardrailsHooks(pi: ExtensionAPI) {
+  setupPreventBrewHook(pi);
+  setupProtectEnvFilesHook(pi);
+  setupPermissionGateHook(pi);
+}

package/hooks/permission-gate.ts

@@ -0,0 +1,152 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { DynamicBorder } from "@mariozechner/pi-coding-agent";
+import {
+  Container,
+  Key,
+  matchesKey,
+  Spacer,
+  Text,
+  wrapTextWithAnsi,
+} from "@mariozechner/pi-tui";
+
+/**
+ * Permission gate that prompts user confirmation for dangerous commands.
+ * Blocks patterns like rm -rf, sudo, and piped shell execution.
+ */
+
+// Notification event channel (duplicated for decoupling)
+const NOTIFICATION_EVENT = "ad:notification";
+const ATTENTION_SOUND = "/System/Library/Sounds/Ping.aiff";
+
+interface NotificationEvent {
+  message: string;
+  sound?: string;
+}
+
+function emitNotification(pi: ExtensionAPI, message: string, sound?: string) {
+  const event: NotificationEvent = { message, sound };
+  pi.events.emit(NOTIFICATION_EVENT, event);
+}
+
+const DANGEROUS_PATTERNS = [
+  { pattern: /rm\s+-rf/, description: "recursive force delete" },
+  { pattern: /\bsudo\b/, description: "superuser command" },
+  { pattern: /:\s*\|\s*sh/, description: "piped shell execution" },
+  { pattern: /\bdd\s+if=/, description: "disk write operation" },
+  { pattern: /mkfs\./, description: "filesystem format" },
+  {
+    pattern: /\bchmod\s+-R\s+777/,
+    description: "insecure recursive permissions",
+  },
+  { pattern: /\bchown\s+-R/, description: "recursive ownership change" },
+];
+
+export function setupPermissionGateHook(pi: ExtensionAPI) {
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName !== "bash") return;
+
+    const command = String(event.input.command ?? "");
+
+    for (const { pattern, description } of DANGEROUS_PATTERNS) {
+      if (pattern.test(command)) {
+        // Emit notification before showing confirm dialog
+        emitNotification(
+          pi,
+          `Dangerous command: ${description}`,
+          ATTENTION_SOUND,
+        );
+
+        const proceed = await ctx.ui.custom<boolean>(
+          (_tui, theme, _kb, done) => {
+            const container = new Container();
+
+            // Red border styling
+            const redBorder = (s: string) => theme.fg("error", s);
+
+            // Top border
+            container.addChild(new DynamicBorder(redBorder));
+
+            // Title
+            container.addChild(
+              new Text(
+                theme.fg("error", theme.bold("Dangerous Command Detected")),
+                1,
+                0,
+              ),
+            );
+            container.addChild(new Spacer(1));
+
+            // Description
+            container.addChild(
+              new Text(
+                theme.fg("warning", `This command contains ${description}:`),
+                1,
+                0,
+              ),
+            );
+            container.addChild(new Spacer(1));
+
+            // Full command with border
+            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));
+
+            // Prompt
+            container.addChild(
+              new Text(theme.fg("text", "Allow execution?"), 1, 0),
+            );
+            container.addChild(new Spacer(1));
+
+            // Help text
+            container.addChild(
+              new Text(theme.fg("dim", "y/enter: allow • n/esc: deny"), 1, 0),
+            );
+
+            // Bottom border
+            container.addChild(new DynamicBorder(redBorder));
+
+            return {
+              render: (width: number) => {
+                // Update command text with proper wrapping for current width
+                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) {
+          return { block: true, reason: "User denied dangerous command" };
+        }
+        break;
+      }
+    }
+    return;
+  });
+}

package/hooks/prevent-brew.ts

@@ -0,0 +1,37 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Prevents bash tool calls that attempt to install packages using Homebrew.
+ * Reminds the user that this project uses Nix for package management.
+ */
+
+const BREW_INSTALL_PATTERNS = [
+  /\bbrew\s+install\b/,
+  /\bbrew\s+cask\s+install\b/,
+  /\bbrew\s+bundle\b/,
+  /\bbrew\s+upgrade\b/,
+  /\bbrew\s+reinstall\b/,
+];
+
+export function setupPreventBrewHook(pi: ExtensionAPI) {
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName !== "bash") return;
+
+    const command = String(event.input.command ?? "");
+
+    for (const pattern of BREW_INSTALL_PATTERNS) {
+      if (pattern.test(command)) {
+        ctx.ui.notify(
+          "Blocked brew command. This project uses Nix for package management.",
+          "warning",
+        );
+        return {
+          block: true,
+          reason:
+            "Homebrew is not used in this project. Please use Nix for package management instead. Run packages via nix-shell or add them to the project's Nix configuration.",
+        };
+      }
+    }
+    return;
+  });
+}

package/hooks/protect-env-files.ts

@@ -0,0 +1,128 @@
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Prevents accessing .env files unless they are suffixed with example, sample, or test.
+ * This protects sensitive environment files from being accessed accidentally.
+ *
+ * Covers native tools: read, write, edit, bash, grep, find, ls
+ */
+
+const ENV_FILE_PATTERN = /\.env$/i;
+const ALLOWED_SUFFIXES =
+  /\.(example|sample|test)\.env$|\.env\.(example|sample|test)$/i;
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await stat(resolve(filePath));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isProtectedEnvFile(filePath: string): Promise<boolean> {
+  if (!ENV_FILE_PATTERN.test(filePath)) {
+    return false;
+  }
+
+  if (ALLOWED_SUFFIXES.test(filePath)) {
+    return false;
+  }
+
+  // Only block if file actually exists on disk
+  return fileExists(filePath);
+}
+
+// -------------------------------------------------------------------
+// Tool protection rule interface
+// -------------------------------------------------------------------
+
+interface ToolProtectionRule {
+  /** Tool names this rule applies to */
+  tools: string[];
+  /** Extract paths/targets from tool input that need checking */
+  extractTargets: (input: Record<string, unknown>) => string[];
+  /** Check if a target should be blocked */
+  shouldBlock: (target: string) => Promise<boolean>;
+  /** Generate block message for a target */
+  blockMessage: (target: string) => string;
+}
+
+// -------------------------------------------------------------------
+// Protection rules
+// -------------------------------------------------------------------
+
+const protectionRules: ToolProtectionRule[] = [
+  {
+    // Tools that use path/file_path input parameter
+    tools: ["read", "write", "edit", "grep", "find", "ls"],
+    extractTargets: (input) => {
+      const path = String(input.file_path ?? input.path ?? "");
+      return path ? [path] : [];
+    },
+    shouldBlock: isProtectedEnvFile,
+    blockMessage: (target) =>
+      `Accessing ${target} is not allowed. Environment files containing secrets are protected. Explain to the user why you want to access this .env file, and if changes are needed ask the user to make them. Only .env.example, .env.sample, or .env.test files can be accessed.`,
+  },
+  {
+    // Bash needs to parse command string for .env references
+    tools: ["bash"],
+    extractTargets: (input) => {
+      const command = String(input.command ?? "");
+      const files: string[] = [];
+
+      // Match .env file references in bash commands
+      const envFileRegex =
+        /(?:^|\s|[<>|;&"'`])([^\s<>|;&"'`]*\.env)(?:\s|$|[<>|;&"'`])/gi;
+
+      for (const match of command.matchAll(envFileRegex)) {
+        const file = match[1];
+        if (file) {
+          files.push(file);
+        }
+      }
+
+      return files;
+    },
+    shouldBlock: isProtectedEnvFile,
+    blockMessage: (target) =>
+      `Command references protected file ${target}. Environment files containing secrets are protected. Explain to the user why you want to access this .env file, and if changes are needed ask the user to make them. Only .env.example, .env.sample, or .env.test files can be accessed.`,
+  },
+];
+
+// Build lookup: tool name -> rule
+const rulesByTool = new Map<string, ToolProtectionRule>();
+for (const rule of protectionRules) {
+  for (const tool of rule.tools) {
+    rulesByTool.set(tool, rule);
+  }
+}
+
+// -------------------------------------------------------------------
+// Hook
+// -------------------------------------------------------------------
+
+export function setupProtectEnvFilesHook(pi: ExtensionAPI) {
+  pi.on("tool_call", async (event, ctx) => {
+    const rule = rulesByTool.get(event.toolName);
+    if (!rule) return;
+
+    const targets = rule.extractTargets(event.input);
+
+    for (const target of targets) {
+      if (await rule.shouldBlock(target)) {
+        ctx.ui.notify(
+          `Blocked access to protected .env file: ${target}`,
+          "warning",
+        );
+        return {
+          block: true,
+          reason: rule.blockMessage(target),
+        };
+      }
+    }
+    return;
+  });
+}

package/index.ts

@@ -0,0 +1,14 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { setupGuardrailsHooks } from "./hooks";
+
+/**
+ * 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
+ */
+export default function (pi: ExtensionAPI) {
+  setupGuardrailsHooks(pi);
+}

package/package.json

@@ -1,14 +1,34 @@
 {
   "name": "@aliou/pi-guardrails",
-  "version": "0.0.1",
-  "description": "Security hooks for Pi coding agent",
+  "version": "0.1.0",
   "type": "module",
-  "keywords": ["pi-package", "pi-extension", "pi", "guardrails", "security"],
-  "publishConfig": {
-    "access": "public"
-  },
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "guardrails",
+    "security"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/aliou/pi-extensions"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "*.ts",
+    "hooks",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": ">=0.49.0",
+    "@mariozechner/pi-tui": ">=0.49.0"
   }
 }