pi-guard 1.0.0

package/src/index.ts

@@ -0,0 +1,426 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { parse as parseBash } from "unbash";
+import { extractAllCommandsFromAST } from "./extract.ts";
+import { getCommandName, getCommandArgs } from "./resolve.ts";
+import { formatCommand } from "./format.ts";
+import { buildApprovalPrompt, buildFileApprovalPrompt, buildCustomApprovalPrompt } from "./prompt.ts";
+import {
+  loadConfig,
+  saveConfig,
+  loadProjectConfig,
+  buildEffectiveRules,
+} from "./config.ts";
+import { resolveBashAction, resolveGlobAction, resolveExactAction } from "./matching.ts";
+import type { Action, ToolRules, CommandRef, ToolCallInput } from "./types.ts";
+
+export function parseGuardArgs(args: string): { action: string; target: string } {
+  const trimmed = args.trim();
+  if (!trimmed) return { action: "", target: "" };
+
+  const [action = "", ...targetParts] = trimmed.split(/\s+/);
+  const target = targetParts.join(" ").trim();
+
+  return { action, target };
+}
+
+export default function (pi: ExtensionAPI) {
+  const loaded = loadConfig();
+  let config = loaded.config;
+  let configWarning = loaded.warning;
+  // Session rules are stored per-tool
+  const sessionRules: Record<string, Record<string, Action>> = {};
+
+  if (configWarning) {
+    console.warn(`[pi-guard] ${configWarning}`);
+  }
+
+  // Settings Management Command
+  pi.registerCommand("guard", {
+    description: "Manage pi-guard security settings",
+    handler: async (args, ctx) => {
+      if (configWarning && ctx.hasUI) {
+        ctx.ui.notify(`[pi-guard] ${configWarning}`, "warning");
+        configWarning = undefined;
+      }
+
+      const { action, target } = parseGuardArgs(args);
+
+      if (action === "toggle") {
+        config.enabled = !config.enabled;
+        saveConfig(config);
+        ctx.ui.notify(`pi-guard is now ${config.enabled ? "ENABLED" : "DISABLED"}`, "info");
+      } else if (action === "list") {
+        const enabled = config.enabled ? "ENABLED" : "DISABLED";
+
+        let output = `pi-guard: ${enabled}\n\n`;
+
+        if (typeof config.rules === "string") {
+          output += `Global rule: ${config.rules}\n`;
+        } else {
+          for (const [tool, rules] of Object.entries(config.rules)) {
+            output += `${tool}:\n`;
+            if (typeof rules === "string") {
+              output += `  ${rules}\n`;
+            } else {
+              for (const [pattern, action] of Object.entries(rules)) {
+                output += `  ${pattern}: ${action}\n`;
+              }
+            }
+            output += "\n";
+          }
+        }
+
+        if (Object.keys(sessionRules).length > 0) {
+          output += "Session rules:\n";
+          for (const [tool, rules] of Object.entries(sessionRules)) {
+            output += `  ${tool}:\n`;
+            for (const [pattern, action] of Object.entries(rules)) {
+              output += `    ${pattern}: ${action}\n`;
+            }
+          }
+        }
+
+        ctx.ui.notify(output, "info");
+      } else {
+        ctx.ui.notify("Usage: /guard <toggle|list>", "warning");
+      }
+    },
+  });
+
+  // The core interception hook
+  pi.on("tool_call", async (event, ctx) => {
+    if (configWarning && ctx.hasUI) {
+      ctx.ui.notify(`[pi-guard] ${configWarning}`, "warning");
+      configWarning = undefined;
+    }
+
+    if (!config.enabled) return;
+
+    const tool = event.toolName;
+    const input = event.input as ToolCallInput;
+
+    // Get the effective rules (user + project + session + env)
+    const projectResult = loadProjectConfig(ctx.cwd);
+    const projectRules = projectResult?.config.rules ?? {};
+    if (projectResult?.warning && ctx.hasUI) {
+      ctx.ui.notify(`[pi-guard] ${projectResult.warning}`, "warning");
+    }
+
+    const envRules = process.env.PI_GUARD ? JSON.parse(process.env.PI_GUARD) : undefined;
+    const effectiveRules = buildEffectiveRules(
+      config.rules,
+      projectRules,
+      sessionRules,
+      envRules,
+    );
+
+    // Check for global rule (single action for all tools)
+    if (typeof effectiveRules === "string") {
+      const action = effectiveRules;
+      if (action === "allow") return;
+      if (action === "deny") {
+        return {
+          block: true,
+          reason: `[Blocked by pi-guard: Security policy]`,
+        };
+      }
+      // "ask" - fall through to interactive handling
+    }
+
+    // Get tool-specific rules
+    const toolRules = typeof effectiveRules === "object" ? effectiveRules[tool] : undefined;
+
+    if (!toolRules) {
+      // No rules for this tool - use default action ("ask")
+      if (!ctx.hasUI) {
+        return {
+          block: true,
+          reason: `[Blocked by pi-guard: No interactive session available]`,
+        };
+      }
+      // Interactive mode - prompt for approval
+      return handleInteractiveApproval(pi, tool, input, ctx, sessionRules);
+    }
+
+    // Handle whole-tool action (no pattern matching needed)
+    if (typeof toolRules === "string") {
+      const action = toolRules;
+      if (action === "allow") return;
+      if (action === "deny") {
+        return {
+          block: true,
+          reason: `[Blocked by pi-guard: Security policy]`,
+        };
+      }
+      // "ask" - prompt for approval
+      if (!ctx.hasUI) {
+        return {
+          block: true,
+          reason: `[Blocked by pi-guard: No interactive session available]`,
+        };
+      }
+      return handleInteractiveApproval(pi, tool, input, ctx, sessionRules);
+    }
+
+    // Get matcher for this tool
+    const matchers = config.matchers ?? {};
+    const matcher = matchers[tool];
+
+    // If no matcher, use whole-tool logic (already handled above if action is allow/deny)
+    if (!matcher) {
+      // For tools without matchers, check for catch-all "*"
+      const defaultAction = toolRules["*"];
+      if (defaultAction === "allow") return;
+      if (defaultAction === "deny") {
+        return {
+          block: true,
+          reason: `[Blocked by pi-guard: Security policy]`,
+        };
+      }
+      if (!ctx.hasUI) {
+        return {
+          block: true,
+          reason: `[Blocked by pi-guard: No interactive session available]`,
+        };
+      }
+      return handleInteractiveApproval(pi, tool, input, ctx, sessionRules);
+    }
+
+    // Extract input based on matcher param
+    const value = input[matcher.param];
+    if (typeof value !== "string" || value.trim() === "") return;
+
+    // Handle bash tool specially (needs AST parsing)
+    if (matcher.type === "bash") {
+      return handleBashTool(pi, tool, value, toolRules, ctx, sessionRules);
+    }
+
+    // Handle glob-based tools (read, edit, write)
+    if (matcher.type === "glob") {
+      return handleGlobTool(pi, tool, value, toolRules, ctx, sessionRules);
+    }
+
+    // Handle exact-match tools
+    if (matcher.type === "exact") {
+      return handleExactTool(pi, tool, value, toolRules, ctx, sessionRules);
+    }
+  });
+}
+
+async function handleInteractiveApproval(
+  pi: ExtensionAPI,
+  tool: string,
+  input: ToolCallInput,
+  ctx: ExtensionContext,
+  sessionRules: Record<string, Record<string, Action>>,
+): Promise<{ block: true; reason: string } | void> {
+  // Build appropriate prompt based on tool
+  const value = String(input[tool === "bash" ? "command" : tool === "read" || tool === "edit" || tool === "write" ? "path" : Object.keys(input)[0] ?? "input"]);
+  const prompt = buildCustomApprovalPrompt(tool, value);
+
+  pi.events.emit("nudge", { body: `${tool} needs approval` });
+
+  const alwaysLabel = `Always allow ${tool} (this session)`;
+  const choice = await ctx.ui.select(prompt, ["Allow", alwaysLabel, "Reject"]);
+
+  if (choice === alwaysLabel) {
+    sessionRules[tool] = { ...sessionRules[tool], "*": "allow" };
+    return;
+  }
+
+  if (choice !== "Allow") {
+    return { block: true, reason: `[Blocked by pi-guard: User rejected this invocation]` };
+  }
+}
+
+async function handleBashTool(
+  pi: ExtensionAPI,
+  tool: string,
+  rawCmd: string,
+  toolRules: Record<string, Action>,
+  ctx: ExtensionContext,
+  sessionRules: Record<string, Record<string, Action>>,
+): Promise<{ block: true; reason: string } | void> {
+  let ast;
+  try {
+    ast = parseBash(rawCmd);
+  } catch {
+    if (!ctx.hasUI) {
+      return { block: true, reason: `[Blocked by pi-guard: Failed to parse command safely]` };
+    }
+
+    pi.events.emit("nudge", { body: "Command needs approval" });
+    const confirmed = await ctx.ui.confirm(
+      "⚠️ Could Not Parse Command Safely",
+      "\nAllow anyway?",
+    );
+
+    if (!confirmed) {
+      return { block: true, reason: `[Blocked by pi-guard: User rejected this invocation]` };
+    }
+
+    return;
+  }
+
+  const allCommands = extractAllCommandsFromAST(ast, rawCmd);
+  if (allCommands.length === 0) return;
+
+  // Merge session rules with config rules
+  const mergedRules: Record<string, Action> = { ...toolRules };
+  if (sessionRules[tool]) {
+    Object.assign(mergedRules, sessionRules[tool]);
+  }
+
+  const unauthorizedCommands: CommandRef[] = [];
+
+  for (const cmd of allCommands) {
+    const name = getCommandName(cmd);
+    const args = getCommandArgs(cmd);
+    const action = resolveBashAction(name, args, mergedRules);
+    if (action !== "allow") {
+      unauthorizedCommands.push(cmd);
+    }
+  }
+
+  if (unauthorizedCommands.length === 0) return;
+
+  if (!ctx.hasUI) {
+    // Non-interactive: check first unauthorized command's action
+    const firstCmd = unauthorizedCommands[0]!;
+    const name = getCommandName(firstCmd);
+    const args = getCommandArgs(firstCmd);
+    const action = resolveBashAction(name, args, mergedRules);
+
+    if (action === "deny") {
+      return {
+        block: true,
+        reason: `[Blocked by pi-guard: Security policy]`,
+      };
+    }
+
+    return {
+      block: true,
+      reason: `[Blocked by pi-guard: No interactive session available]`,
+    };
+  }
+
+  // Interactive: prompt user
+  const uniqueBaseNames = Array.from(new Set(unauthorizedCommands.map(getCommandName)));
+  const alwaysLabel = `Always allow ${uniqueBaseNames.join(", ")} (this session)`;
+
+  pi.events.emit("nudge", { body: "Command needs approval" });
+  const choice = await ctx.ui.select(
+    buildApprovalPrompt(allCommands, unauthorizedCommands),
+    ["Allow", alwaysLabel, "Reject"],
+  );
+
+  if (choice === alwaysLabel) {
+    sessionRules[tool] = sessionRules[tool] ?? {};
+    for (const name of uniqueBaseNames) {
+      sessionRules[tool]![name] = "allow";
+    }
+    return;
+  }
+
+  if (choice !== "Allow") {
+    return { block: true, reason: `[Blocked by pi-guard: User rejected this invocation]` };
+  }
+}
+
+async function handleGlobTool(
+  pi: ExtensionAPI,
+  tool: string,
+  path: string,
+  toolRules: Record<string, Action>,
+  ctx: ExtensionContext,
+  sessionRules: Record<string, Record<string, Action>>,
+): Promise<{ block: true; reason: string } | void> {
+  // Merge session rules with config rules
+  const mergedRules: Record<string, Action> = { ...toolRules };
+  if (sessionRules[tool]) {
+    Object.assign(mergedRules, sessionRules[tool]);
+  }
+
+  const action = resolveGlobAction(path, mergedRules);
+
+  if (action === "allow") return;
+
+  if (action === "deny") {
+    return {
+      block: true,
+      reason: `[Blocked by pi-guard: Security policy]`,
+    };
+  }
+
+  if (!ctx.hasUI) {
+    return {
+      block: true,
+      reason: `[Blocked by pi-guard: No interactive session available]`,
+    };
+  }
+
+  // Interactive: prompt user
+  const prompt = buildFileApprovalPrompt(tool, path);
+  const alwaysLabel = `Always allow ${tool} (this session)`;
+
+  pi.events.emit("nudge", { body: `${tool} needs approval` });
+  const choice = await ctx.ui.select(prompt, ["Allow", alwaysLabel, "Reject"]);
+
+  if (choice === alwaysLabel) {
+    sessionRules[tool] = { ...sessionRules[tool], "*": "allow" };
+    return;
+  }
+
+  if (choice !== "Allow") {
+    return { block: true, reason: `[Blocked by pi-guard: User rejected this invocation]` };
+  }
+}
+
+async function handleExactTool(
+  pi: ExtensionAPI,
+  tool: string,
+  value: string,
+  toolRules: Record<string, Action>,
+  ctx: ExtensionContext,
+  sessionRules: Record<string, Record<string, Action>>,
+): Promise<{ block: true; reason: string } | void> {
+  // Merge session rules with config rules
+  const mergedRules: Record<string, Action> = { ...toolRules };
+  if (sessionRules[tool]) {
+    Object.assign(mergedRules, sessionRules[tool]);
+  }
+
+  const action = resolveExactAction(value, mergedRules);
+
+  if (action === "allow") return;
+
+  if (action === "deny") {
+    return {
+      block: true,
+      reason: `[Blocked by pi-guard: Security policy]`,
+    };
+  }
+
+  if (!ctx.hasUI) {
+    return {
+      block: true,
+      reason: `[Blocked by pi-guard: No interactive session available]`,
+    };
+  }
+
+  // Interactive: prompt user
+  const prompt = buildCustomApprovalPrompt(tool, value);
+  const alwaysLabel = `Always allow ${tool} (this session)`;
+
+  pi.events.emit("nudge", { body: `${tool} needs approval` });
+  const choice = await ctx.ui.select(prompt, ["Allow", alwaysLabel, "Reject"]);
+
+  if (choice === alwaysLabel) {
+    sessionRules[tool] = { ...sessionRules[tool], "*": "allow" };
+    return;
+  }
+
+  if (choice !== "Allow") {
+    return { block: true, reason: `[Blocked by pi-guard: User rejected this invocation]` };
+  }
+}

package/src/matchers.ts

@@ -0,0 +1,72 @@
+import { parse as parseBash } from "unbash";
+import type { Script } from "unbash";
+import type { Matcher, MatcherType, Action, ToolCallInput } from "./types.ts";
+import { resolveBashAction, resolveGlobAction, resolveExactAction } from "./matching.ts";
+import { extractAllCommandsFromAST } from "./extract.ts";
+import { getCommandName, getCommandArgs } from "./resolve.ts";
+
+/** Extract the value to match from a tool call based on the matcher's param. */
+export function extractInput(toolCall: ToolCallInput, matcher: Matcher): string | undefined {
+  const value = toolCall[matcher.param];
+  if (typeof value === "string") return value;
+  return undefined;
+}
+
+/** Match a tool call against rules using the specified matcher type. */
+export function matchWithMatcher(
+  input: string,
+  matcherType: MatcherType,
+  rules: Record<string, Action>,
+): Action | undefined {
+  switch (matcherType) {
+    case "bash":
+      // For bash matching, we need to parse the command first
+      // This is handled separately in the main hook due to complexity
+      throw new Error("Bash matching requires parsed commands - use matchBashCall instead");
+    case "glob":
+      return resolveGlobAction(input, rules);
+    case "exact":
+      return resolveExactAction(input, rules);
+  }
+}
+
+/** Bash-specific matching that parses the command and checks all extracted commands. */
+export function matchBashCall(
+  rawCmd: string,
+  rules: Record<string, Action>,
+): { action: Action | undefined; unauthorizedCommands: CommandInfo[] } {
+  let ast: Script;
+  try {
+    ast = parseBash(rawCmd);
+  } catch {
+    return { action: undefined, unauthorizedCommands: [{ raw: rawCmd, name: "", args: [] }] };
+  }
+
+  const allCommands = extractAllCommandsFromAST(ast, rawCmd);
+  if (allCommands.length === 0) {
+    return { action: "allow", unauthorizedCommands: [] };
+  }
+
+  const unauthorizedCommands: CommandInfo[] = [];
+
+  for (const cmd of allCommands) {
+    const name = getCommandName(cmd);
+    const args = getCommandArgs(cmd);
+    const action = resolveBashAction(name, args, rules);
+    if (action !== "allow") {
+      unauthorizedCommands.push({ raw: cmd.source.slice(cmd.node.pos, cmd.node.end), name, args });
+    }
+  }
+
+  if (unauthorizedCommands.length === 0) {
+    return { action: "allow", unauthorizedCommands: [] };
+  }
+
+  return { action: undefined, unauthorizedCommands };
+}
+
+export interface CommandInfo {
+  raw: string;
+  name: string;
+  args: string[];
+}

package/src/matching.ts

@@ -0,0 +1,133 @@
+import { minimatch } from "minimatch";
+import type { Action } from "./types.ts";
+
+/**
+ * Check if `needle` tokens appear in order within `haystack`.
+ * Used for bash command matching where rule tokens must appear in order,
+ * but extra flags or positional args anywhere in the sequence are permitted.
+ */
+export function isSubsequence(needle: string[], haystack: string[]): boolean {
+  let ni = 0;
+  for (let hi = 0; hi < haystack.length && ni < needle.length; hi++) {
+    if (haystack[hi] === needle[ni]) ni++;
+  }
+  return ni === needle.length;
+}
+
+/**
+ * Match a glob pattern against a string using minimatch.
+ * - `*` matches anything except `/`
+ * - `**` matches anything including `/`
+ * - `?` matches single character
+ * - `~` at start expands to home directory
+ */
+export function globMatch(pattern: string, input: string): boolean {
+  // Expand ~ at the start
+  if (pattern.startsWith("~")) {
+    const home = process.env.HOME ?? "";
+    pattern = home + pattern.slice(1);
+  }
+  if (input.startsWith("~")) {
+    const home = process.env.HOME ?? "";
+    input = home + input.slice(1);
+  }
+
+  return minimatch(input, pattern);
+}
+
+/**
+ * Resolve the action for a bash command against a rules map.
+ *
+ * Rules are evaluated in insertion order; last match wins.
+ * The special pattern "*" matches any command.
+ *
+ * Matching uses subsequence logic:
+ * - "git" → matches all git commands (base command match)
+ * - "git status" → matches `git status`, `git status --short`, etc.
+ * - "git branch --show-current" → matches `git branch --show-current`,
+ *   `git branch -v --show-current`, etc.
+ *
+ * Returns undefined if no rule matches.
+ */
+export function resolveBashAction(
+  commandName: string,
+  commandArgs: string[],
+  rules: Record<string, Action>,
+): Action | undefined {
+  let result: Action | undefined;
+
+  for (const [pattern, action] of Object.entries(rules)) {
+    if (pattern === "*") {
+      result = action;
+      continue;
+    }
+
+    const tokens = pattern.split(" ");
+    const patternName = tokens[0]!;
+    const patternArgs = tokens.slice(1);
+
+    if (patternName !== commandName) continue;
+
+    if (patternArgs.length === 0 || isSubsequence(patternArgs, commandArgs)) {
+      result = action;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Resolve the action for a glob-based tool (read, edit, write) against a rules map.
+ *
+ * Rules are evaluated in insertion order; last match wins.
+ * The special pattern "*" matches any path.
+ *
+ * Returns undefined if no rule matches.
+ */
+export function resolveGlobAction(
+  input: string,
+  rules: Record<string, Action>,
+): Action | undefined {
+  let result: Action | undefined;
+
+  for (const [pattern, action] of Object.entries(rules)) {
+    if (pattern === "*") {
+      result = action;
+      continue;
+    }
+
+    if (globMatch(pattern, input)) {
+      result = action;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Resolve the action for an exact-match tool against a rules map.
+ *
+ * Rules are evaluated in insertion order; last match wins.
+ * The special pattern "*" matches any value.
+ *
+ * Returns undefined if no rule matches.
+ */
+export function resolveExactAction(
+  input: string,
+  rules: Record<string, Action>,
+): Action | undefined {
+  let result: Action | undefined;
+
+  for (const [pattern, action] of Object.entries(rules)) {
+    if (pattern === "*") {
+      result = action;
+      continue;
+    }
+
+    if (pattern === input) {
+      result = action;
+    }
+  }
+
+  return result;
+}

package/src/prompt.ts

@@ -0,0 +1,47 @@
+import type { CommandRef } from "./types.ts";
+import { formatCommand } from "./format.ts";
+
+export interface ApprovalPromptOptions {
+  maxLength?: number;
+  argMaxLength?: number;
+}
+
+export function buildApprovalPrompt(
+  allCommands: CommandRef[],
+  unauthorizedCommands: CommandRef[],
+  options?: ApprovalPromptOptions,
+): string {
+  const unauthorizedSet = new Set(unauthorizedCommands);
+  const lines = allCommands.map(command => {
+    const marker = unauthorizedSet.has(command) ? "✖" : "✔";
+    return `${marker} ${formatCommand(command, options)}`;
+  });
+
+  return [
+    "⚠️ Unapproved Commands",
+    "",
+    ...lines,
+  ].join("\n");
+}
+
+/** Build prompt for file operations (read/edit/write). */
+export function buildFileApprovalPrompt(
+  tool: string,
+  path: string,
+  options?: { maxLength?: number },
+): string {
+  const maxLength = options?.maxLength ?? 120;
+  const displayPath = path.length > maxLength ? path.slice(0, maxLength - 1) + "…" : path;
+  return `⚠️ ${tool.charAt(0).toUpperCase() + tool.slice(1)} Permission Required\n\n${displayPath}`;
+}
+
+/** Build prompt for custom tools with exact matchers. */
+export function buildCustomApprovalPrompt(
+  tool: string,
+  input: string,
+  options?: { maxLength?: number },
+): string {
+  const maxLength = options?.maxLength ?? 120;
+  const display = input.length > maxLength ? input.slice(0, maxLength - 1) + "…" : input;
+  return `⚠️ ${tool} Permission Required\n\n${display}`;
+}

package/src/resolve.ts

@@ -0,0 +1,9 @@
+import type { CommandRef } from "./types.ts";
+
+export function getCommandName(cmd: CommandRef): string {
+  return cmd.node.name?.value ?? cmd.node.name?.text ?? "";
+}
+
+export function getCommandArgs(cmd: CommandRef): string[] {
+  return cmd.node.suffix.map(word => word.value ?? word.text);
+}