@aliou/pi-guardrails 0.11.2 → 0.12.0

package/extensions/path-access/index.ts

@@ -0,0 +1,143 @@
+import { dirname } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { checkAction } from "../../src/core";
+import {
+  normalizeForDisplay,
+  type PathAccessState,
+} from "../../src/core/paths";
+import { configLoader } from "../../src/shared/config";
+import {
+  createFeatureRegisterPayload,
+  emitActionBlocked,
+  GUARDRAILS_FEATURE_REGISTER_EVENT,
+  GUARDRAILS_FEATURE_REQUEST_EVENT,
+} from "../../src/shared/events";
+import {
+  createPendingGrant,
+  isGrantTooBroad,
+  type PendingPathGrant,
+  pendingAllowedPaths,
+  persistGrant,
+  resolveAllowedPaths,
+} from "./grants";
+import { createPathAccessPromptComponent, type PromptResult } from "./prompt";
+import { createPathAccessRule } from "./rules";
+import { targetsForTool } from "./targets";
+
+export default async function pathAccess(pi: ExtensionAPI) {
+  await configLoader.load();
+
+  pi.events.on(GUARDRAILS_FEATURE_REQUEST_EVENT, () => {
+    pi.events.emit(
+      GUARDRAILS_FEATURE_REGISTER_EVENT,
+      createFeatureRegisterPayload("pathAccess"),
+    );
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    const config = configLoader.getConfig();
+    if (
+      !config.enabled ||
+      !config.features.pathAccess ||
+      config.pathAccess.mode === "allow"
+    ) {
+      return;
+    }
+
+    const input = event.input as Record<string, unknown>;
+    const targets = [
+      ...new Set(await targetsForTool(event.toolName, input, ctx.cwd)),
+    ];
+    const acceptedGrants: PendingPathGrant[] = [];
+
+    for (const absolutePath of targets) {
+      const action = {
+        kind: "file" as const,
+        path: absolutePath,
+        origin: event.toolName,
+      };
+      const state: PathAccessState = {
+        cwd: ctx.cwd,
+        mode: config.pathAccess.mode,
+        allowedPaths: [
+          ...resolveAllowedPaths(config.pathAccess.allowedPaths, ctx.cwd),
+          ...pendingAllowedPaths(acceptedGrants),
+        ],
+        hasUI: ctx.hasUI,
+      };
+      const safety = await checkAction(action, [createPathAccessRule(state)]);
+      if (safety.kind === "safe") continue;
+
+      if (config.pathAccess.mode === "block" || !ctx.hasUI) {
+        emitActionBlocked(pi, {
+          feature: "pathAccess",
+          action: safety.action,
+          reason: safety.reason,
+          block: {
+            source: ctx.hasUI ? "policy" : "nonInteractive",
+            metadata: safety.metadata,
+          },
+          context: { toolName: event.toolName, input },
+        });
+        return { block: true, reason: safety.reason };
+      }
+
+      const parentDir = dirname(absolutePath);
+      const showFileOptions =
+        event.toolName !== "ls" && event.toolName !== "find";
+      const result = await ctx.ui.custom<PromptResult>(
+        createPathAccessPromptComponent(
+          event.toolName,
+          safety.metadata.displayPath,
+          normalizeForDisplay(parentDir, ctx.cwd),
+          ctx.cwd,
+          showFileOptions,
+        ),
+      );
+
+      if (result === "allow-file-once" || result === "allow-dir-once") {
+        continue;
+      }
+
+      if (result === "allow-file-session" || result === "allow-file-always") {
+        const grant = createPendingGrant(
+          absolutePath,
+          false,
+          result === "allow-file-session" ? "memory" : "local",
+        );
+        acceptedGrants.push(grant);
+        await persistGrant(grant);
+        continue;
+      }
+
+      if (result === "allow-dir-session" || result === "allow-dir-always") {
+        const dirPath = showFileOptions ? parentDir : absolutePath;
+        if (isGrantTooBroad(dirPath)) {
+          ctx.ui.notify(
+            `Cannot grant access to ${normalizeForDisplay(dirPath, ctx.cwd)}/ — too broad. Treating as allow once.`,
+            "warning",
+          );
+          continue;
+        }
+        const grant = createPendingGrant(
+          dirPath,
+          true,
+          result === "allow-dir-session" ? "memory" : "local",
+        );
+        acceptedGrants.push(grant);
+        await persistGrant(grant);
+        continue;
+      }
+
+      const reason = "User denied access outside working directory";
+      emitActionBlocked(pi, {
+        feature: "pathAccess",
+        action: safety.action,
+        reason,
+        block: { source: "user", metadata: safety.metadata },
+        context: { toolName: event.toolName, input },
+      });
+      return { block: true, reason };
+    }
+  });
+}

package/extensions/path-access/prompt.ts

@@ -0,0 +1,196 @@
+import { homedir } from "node:os";
+import {
+  Container,
+  Key,
+  matchesKey,
+  Spacer,
+  Text,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+
+// Grant result type from the UI prompt
+export type PromptResult =
+  | "allow-file-once"
+  | "allow-dir-once"
+  | "allow-file-session"
+  | "allow-dir-session"
+  | "allow-file-always"
+  | "allow-dir-always"
+  | "deny";
+
+/**
+ * Collapse home directory to ~ for display.
+ */
+function displayCwd(cwd: string): string {
+  const home = homedir();
+  if (cwd === home) return "~";
+  if (cwd.startsWith(`${home}/`) || cwd.startsWith(`${home}\\`)) {
+    return `~${cwd.slice(home.length)}`;
+  }
+  return cwd;
+}
+
+interface PromptOption {
+  label: string;
+  result: PromptResult;
+}
+
+const FILE_OPTIONS: PromptOption[] = [
+  { label: "Allow once", result: "allow-file-once" },
+  { label: "Allow file this session", result: "allow-file-session" },
+  { label: "Allow file always", result: "allow-file-always" },
+  { label: "Allow directory this session", result: "allow-dir-session" },
+  { label: "Allow directory always", result: "allow-dir-always" },
+  { label: "Deny", result: "deny" },
+];
+
+const DIR_OPTIONS: PromptOption[] = [
+  { label: "Allow once", result: "allow-dir-once" },
+  { label: "Allow directory this session", result: "allow-dir-session" },
+  { label: "Allow directory always", result: "allow-dir-always" },
+  { label: "Deny", result: "deny" },
+];
+
+/**
+ * Build the confirmation UI component.
+ * For directory-oriented tools (ls, find): only directory grant options.
+ * For file tools and bash: both file and directory options.
+ * Options rendered as highlighted tabs (selected = accent bg, unselected = dim),
+ * navigable with ←/→/Tab/Shift+Tab.
+ */
+export function createPathAccessPromptComponent(
+  toolName: string,
+  displayPath: string,
+  displayDir: string,
+  cwd: string,
+  showFileOptions: boolean,
+) {
+  return (
+    tui: { terminal: { columns: number }; requestRender(): void },
+    theme: {
+      fg(color: string, text: string): string;
+      bg(color: string, text: string): string;
+      bold(text: string): string;
+    },
+    _kb: unknown,
+    done: (result: PromptResult) => void,
+  ) => {
+    const options = showFileOptions ? FILE_OPTIONS : DIR_OPTIONS;
+    let selectedIndex = 0;
+
+    const container = new Container();
+    const border = (s: string) => theme.fg("warning", s);
+    const cwdDisplay = displayCwd(cwd);
+
+    container.addChild(
+      new Text(
+        theme.fg("warning", theme.bold("Outside Workspace Access")),
+        1,
+        0,
+      ),
+    );
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(
+        theme.fg(
+          "text",
+          `\`${toolName}\` targets a path outside the working directory.`,
+        ),
+        1,
+        0,
+      ),
+    );
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(theme.fg("dim", `  Cwd:  ${cwdDisplay}`), 1, 0),
+    );
+    container.addChild(
+      new Text(theme.fg("dim", `  Path: ${displayPath}`), 1, 0),
+    );
+    container.addChild(
+      new Text(theme.fg("dim", `  Dir:  ${displayDir}`), 1, 0),
+    );
+    container.addChild(new Spacer(1));
+
+    // Dynamically rendered option lines
+    const optionLines: Text[] = options.map(() => new Text("", 1, 0));
+    for (const line of optionLines) {
+      container.addChild(line);
+    }
+
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(
+        theme.fg("dim", "↑/↓/Tab select · Enter select · Esc deny"),
+        1,
+        0,
+      ),
+    );
+
+    const renderOptions = () => {
+      for (let i = 0; i < options.length; i++) {
+        const label = options[i].label;
+        if (i === selectedIndex) {
+          optionLines[i].setText(
+            theme.bg("selectedBg", theme.fg("accent", ` ${label} `)),
+          );
+        } else {
+          optionLines[i].setText(theme.fg("dim", ` ${label} `));
+        }
+      }
+    };
+
+    renderOptions();
+
+    const moveSelection = (direction: number) => {
+      selectedIndex =
+        (selectedIndex + direction + options.length) % options.length;
+      renderOptions();
+      tui.requestRender();
+    };
+
+    return {
+      render: (width: number) => {
+        const innerWidth = Math.max(1, width - 2);
+        const contentWidth = Math.max(1, width - 4);
+        const raw = container.render(contentWidth);
+        const top = border(`╭${"─".repeat(innerWidth)}╮`);
+        const bottom = border(`╰${"─".repeat(innerWidth)}╯`);
+        const left = border("│");
+        const right = border("│");
+        const lines = raw.map((line) => {
+          const visible = visibleWidth(line);
+          const pad = Math.max(0, contentWidth - visible);
+          return `${left} ${line}${" ".repeat(pad)} ${right}`;
+        });
+        return [top, ...lines, bottom];
+      },
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        if (
+          matchesKey(data, Key.up) ||
+          data === "k" ||
+          matchesKey(data, Key.shift("tab"))
+        ) {
+          moveSelection(-1);
+          return;
+        }
+        if (
+          matchesKey(data, Key.down) ||
+          data === "j" ||
+          matchesKey(data, Key.tab)
+        ) {
+          moveSelection(1);
+          return;
+        }
+        if (matchesKey(data, Key.enter)) {
+          done(options[selectedIndex].result);
+          return;
+        }
+        if (matchesKey(data, Key.escape)) {
+          done("deny");
+        }
+      },
+    };
+  };
+}

package/extensions/path-access/rules.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { createPathAccessRule } from "./rules";
+
+const cwd = "/repo";
+const state = (allowedPaths: string[] = []) => ({
+  cwd,
+  mode: "block" as const,
+  allowedPaths,
+  hasUI: true,
+});
+
+describe("createPathAccessRule", () => {
+  it("passes command actions", () => {
+    const rule = createPathAccessRule(state());
+    expect(rule.check({ kind: "command", command: "cat /tmp/a" })).toEqual({
+      kind: "pass",
+    });
+  });
+
+  it("passes files inside cwd", () => {
+    const rule = createPathAccessRule(state());
+    expect(rule.check({ kind: "file", path: "/repo/src/index.ts" })).toEqual({
+      kind: "pass",
+    });
+  });
+
+  it("matches outside files in block mode", () => {
+    const rule = createPathAccessRule(state());
+    expect(rule.check({ kind: "file", path: "/tmp/secret.txt" })).toMatchObject(
+      {
+        kind: "match",
+        metadata: {
+          absolutePath: "/tmp/secret.txt",
+          displayPath: "/tmp/secret.txt",
+        },
+      },
+    );
+  });
+
+  it("passes explicitly allowed outside paths", () => {
+    const rule = createPathAccessRule(state(["/tmp/"]));
+    expect(rule.check({ kind: "file", path: "/tmp/secret.txt" })).toEqual({
+      kind: "pass",
+    });
+  });
+});

package/extensions/path-access/rules.ts

@@ -0,0 +1,37 @@
+import type { Action, Rule } from "../../src/core";
+import {
+  checkPathAccess,
+  normalizeForDisplay,
+  type PathAccessState,
+} from "../../src/core/paths";
+
+export type PathAccessMeta = {
+  absolutePath: string;
+  displayPath: string;
+};
+
+export function createPathAccessRule(
+  state: PathAccessState,
+): Rule<PathAccessMeta> {
+  return {
+    key: "path-access.outside-workspace",
+    check(action: Action) {
+      if (action.kind !== "file") return { kind: "pass" };
+      const displayPath = normalizeForDisplay(action.path, state.cwd);
+      const decision = checkPathAccess(action.path, displayPath, state);
+      if (decision.kind === "allow") return { kind: "pass" };
+
+      return {
+        kind: "match",
+        reason:
+          decision.kind === "deny"
+            ? decision.reason
+            : `Access to ${displayPath} requires confirmation.`,
+        metadata: {
+          absolutePath: action.path,
+          displayPath,
+        },
+      };
+    },
+  };
+}

package/extensions/path-access/targets.test.ts

@@ -0,0 +1,40 @@
+import { join } from "node:path";
+import { vol } from "memfs";
+import { describe, expect, it } from "vitest";
+import { targetsForTool } from "./targets";
+
+describe("targetsForTool", () => {
+  it("resolves direct file tool targets from cwd", async () => {
+    await expect(
+      targetsForTool("read", { path: "README.md" }, "/repo"),
+    ).resolves.toEqual(["/repo/README.md"]);
+  });
+
+  it("extracts bash path candidates", async () => {
+    const cwd = "/repo";
+    vol.fromJSON({ "/repo/README.md": "hello" });
+
+    await expect(
+      targetsForTool("bash", { command: "cat ./README.md" }, cwd),
+    ).resolves.toEqual([join(cwd, "README.md")]);
+  });
+
+  it("does not treat awk regexes as paths", async () => {
+    const cwd = "/repo";
+    vol.fromJSON({ "/repo/test.txt": "aaa" });
+
+    await expect(
+      targetsForTool(
+        "bash",
+        { command: "awk '/aaa/{flag=1} flag{print}' ./test.txt" },
+        cwd,
+      ),
+    ).resolves.toEqual([join(cwd, "test.txt")]);
+  });
+
+  it("ignores unrelated tools", async () => {
+    await expect(
+      targetsForTool("custom", { path: "README.md" }, "/repo"),
+    ).resolves.toEqual([]);
+  });
+});

package/extensions/path-access/targets.ts

@@ -0,0 +1,19 @@
+import { resolveFromCwd } from "../../src/core/paths";
+import { extractBashPathCandidates } from "../../src/shared/paths";
+
+export async function targetsForTool(
+  toolName: string,
+  input: Record<string, unknown>,
+  cwd: string,
+): Promise<string[]> {
+  if (["read", "write", "edit", "grep", "find", "ls"].includes(toolName)) {
+    const raw = String(input.file_path ?? input.path ?? "").trim();
+    return raw ? [resolveFromCwd(raw, cwd)] : [];
+  }
+
+  if (toolName === "bash") {
+    return extractBashPathCandidates(String(input.command ?? ""), cwd);
+  }
+
+  return [];
+}

package/extensions/permission-gate/grants.ts

@@ -0,0 +1,21 @@
+import { configLoader } from "../../src/shared/config";
+import { compileCommandPatterns } from "../../src/shared/matching";
+
+export function isCommandAllowed(command: string): boolean {
+  const config = configLoader.getConfig();
+  return compileCommandPatterns(config.permissionGate.allowedPatterns).some(
+    (pattern) => pattern.test(command),
+  );
+}
+
+export async function saveCommandSessionGrant(command: string): Promise<void> {
+  const resolved = configLoader.getConfig();
+  await configLoader.save("memory", {
+    permissionGate: {
+      allowedPatterns: [
+        ...resolved.permissionGate.allowedPatterns,
+        { pattern: command },
+      ],
+    },
+  });
+}

package/extensions/permission-gate/index.ts

@@ -0,0 +1,122 @@
+import {
+  type ExtensionAPI,
+  isToolCallEventType,
+} from "@earendil-works/pi-coding-agent";
+import { checkAction } from "../../src/core";
+import { configLoader } from "../../src/shared/config";
+import {
+  createFeatureRegisterPayload,
+  emitActionBlocked,
+  emitRiskDetected,
+  GUARDRAILS_FEATURE_REGISTER_EVENT,
+  GUARDRAILS_FEATURE_REQUEST_EVENT,
+} from "../../src/shared/events";
+import { isCommandAllowed, saveCommandSessionGrant } from "./grants";
+import { createPermissionGateConfirmComponent } from "./prompt";
+import {
+  createPermissionGateRule,
+  formatAutoDenyReason,
+  matchCommandPattern,
+} from "./rules";
+
+export default async function permissionGate(pi: ExtensionAPI) {
+  await configLoader.load();
+
+  pi.events.on(GUARDRAILS_FEATURE_REQUEST_EVENT, () => {
+    pi.events.emit(
+      GUARDRAILS_FEATURE_REGISTER_EVENT,
+      createFeatureRegisterPayload("permissionGate"),
+    );
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    const config = configLoader.getConfig();
+    if (!config.enabled || !config.features.permissionGate) return;
+    if (!isToolCallEventType("bash", event)) return;
+
+    const command = event.input.command;
+    const action = { kind: "command" as const, command, origin: "bash" };
+    if (isCommandAllowed(command)) return;
+
+    const autoDenyMatch = matchCommandPattern(
+      command,
+      config.permissionGate.autoDenyPatterns,
+    );
+
+    if (autoDenyMatch) {
+      const reason = formatAutoDenyReason(autoDenyMatch);
+
+      emitActionBlocked(pi, {
+        feature: "permissionGate",
+        action,
+        reason,
+        block: { source: "permission", metadata: autoDenyMatch },
+        context: { toolName: "bash", input: event.input },
+      });
+
+      return { block: true, reason };
+    }
+
+    const safety = await checkAction(action, [
+      createPermissionGateRule({
+        patterns: config.permissionGate.patterns,
+        useBuiltinMatchers: config.permissionGate.useBuiltinMatchers,
+      }),
+    ]);
+    if (safety.kind === "safe") return;
+
+    emitRiskDetected(pi, {
+      feature: "permissionGate",
+      risk: safety,
+      context: { toolName: "bash", input: event.input },
+    });
+
+    if (!config.permissionGate.requireConfirmation) {
+      ctx.ui.notify(`Dangerous command detected: ${safety.reason}`, "warning");
+      return;
+    }
+
+    if (!ctx.hasUI) {
+      const reason = `Dangerous command blocked (no UI to confirm): ${safety.reason}`;
+      emitActionBlocked(pi, {
+        feature: "permissionGate",
+        action: safety.action,
+        reason,
+        block: { source: "nonInteractive", metadata: safety.metadata },
+        context: { toolName: "bash", input: event.input },
+      });
+      return { block: true, reason };
+    }
+
+    type ConfirmResult = "allow" | "allow-session" | "deny";
+    let result = await ctx.ui.custom<ConfirmResult>(
+      createPermissionGateConfirmComponent(command, safety.reason),
+    );
+
+    if (result === undefined) {
+      const selection = await ctx.ui.select(
+        `Dangerous command: ${safety.reason}`,
+        ["Allow once", "Allow for session", "Deny"],
+      );
+      if (selection === "Allow once") result = "allow";
+      else if (selection === "Allow for session") result = "allow-session";
+      else result = "deny";
+    }
+
+    if (result === "allow") return;
+    if (result === "allow-session") {
+      await saveCommandSessionGrant(command);
+      return;
+    }
+
+    const reason = "User denied dangerous command";
+    emitActionBlocked(pi, {
+      feature: "permissionGate",
+      action: safety.action,
+      reason,
+      block: { source: "user", metadata: safety.metadata },
+      context: { toolName: "bash", input: event.input },
+    });
+    return { block: true, reason };
+  });
+}