@aliou/pi-guardrails 0.11.2 → 0.12.1

package/src/{hooks/permission-gate/dangerous-commands.ts → core/commands/dangerous.ts}

@@ -1,3 +1,6 @@
+import { parse } from "@aliou/sh";
+import { walkCommands, wordToString } from "../shell/ast";
+
 /**
  * Dangerous command matchers for the permission gate.
  *
@@ -8,6 +11,29 @@
 
 export type StructuralMatcher = (words: string[]) => string | undefined;
 
+export interface CommandPattern {
+  pattern: string;
+  description?: string;
+  regex?: boolean;
+}
+
+export interface CompiledCommandPattern {
+  test: (input: string) => boolean;
+  source: CommandPattern;
+}
+
+export interface DangerousCommandMatch {
+  description: string;
+  pattern: string;
+}
+
+export interface DangerousCommandCheckOptions {
+  command: string;
+  patterns: readonly CompiledCommandPattern[];
+  useBuiltinMatchers: boolean;
+  fallbackPatterns: readonly CommandPattern[];
+}
+
 /**
  * Helper to check if any word starts with a given prefix.
  */
@@ -332,7 +358,7 @@ export const BUILTIN_KEYWORD_PATTERNS = new Set([
  */
 export function matchDangerousCommand(
   words: string[],
-): { description: string; pattern: string } | undefined {
+): DangerousCommandMatch | undefined {
   for (const matcher of BUILTIN_MATCHERS) {
     const description = matcher(words);
     if (description) {
@@ -343,3 +369,95 @@ export function matchDangerousCommand(
   }
   return undefined;
 }
+
+export function compileCommandPattern(
+  config: CommandPattern,
+): CompiledCommandPattern {
+  if (config.regex) {
+    try {
+      const re = new RegExp(config.pattern);
+      return { test: (input) => re.test(input), source: config };
+    } catch {
+      return { test: () => false, source: config };
+    }
+  }
+
+  return {
+    test: (input) => input.includes(config.pattern),
+    source: config,
+  };
+}
+
+export function compileCommandPatterns(
+  configs: readonly CommandPattern[],
+): CompiledCommandPattern[] {
+  return configs.map(compileCommandPattern);
+}
+
+function matchBuiltinDangerous(
+  words: string[],
+): DangerousCommandMatch | undefined {
+  if (words.length === 0) return undefined;
+  for (const matcher of BUILTIN_MATCHERS) {
+    const description = matcher(words);
+    if (description) return { description, pattern: "(structural)" };
+  }
+  return undefined;
+}
+
+export function checkDangerousCommand({
+  command,
+  patterns,
+  useBuiltinMatchers,
+  fallbackPatterns,
+}: DangerousCommandCheckOptions): DangerousCommandMatch | undefined {
+  let parsedSuccessfully = false;
+
+  if (useBuiltinMatchers) {
+    try {
+      const { ast } = parse(command);
+      parsedSuccessfully = true;
+      let match: DangerousCommandMatch | undefined;
+      walkCommands(ast, (cmd) => {
+        const words = (cmd.words ?? []).map(wordToString);
+        const result = matchBuiltinDangerous(words);
+        if (result) {
+          match = result;
+          return true;
+        }
+        return false;
+      });
+      if (match) return match;
+    } catch {
+      for (const pattern of fallbackPatterns) {
+        if (command.includes(pattern.pattern)) {
+          return {
+            description: pattern.description ?? pattern.pattern,
+            pattern: pattern.pattern,
+          };
+        }
+      }
+    }
+  }
+
+  for (const compiled of patterns) {
+    const source = compiled.source;
+    if (
+      useBuiltinMatchers &&
+      parsedSuccessfully &&
+      !source.regex &&
+      BUILTIN_KEYWORD_PATTERNS.has(source.pattern)
+    ) {
+      continue;
+    }
+
+    if (compiled.test(command)) {
+      return {
+        description: source.description ?? source.pattern,
+        pattern: source.pattern,
+      };
+    }
+  }
+
+  return undefined;
+}

package/src/core/commands/index.ts

@@ -0,0 +1,15 @@
+export type {
+  CommandPattern,
+  CompiledCommandPattern,
+  DangerousCommandCheckOptions,
+  DangerousCommandMatch,
+  StructuralMatcher,
+} from "./dangerous";
+export {
+  BUILTIN_KEYWORD_PATTERNS,
+  BUILTIN_MATCHERS,
+  checkDangerousCommand,
+  compileCommandPattern,
+  compileCommandPatterns,
+  matchDangerousCommand,
+} from "./dangerous";

package/src/core/index.ts

@@ -0,0 +1,13 @@
+export { checkAction, resolveDecision } from "./check";
+export * from "./commands";
+export * from "./paths";
+export * from "./shell";
+export type {
+  Action,
+  Decision,
+  Grant,
+  PermissionState,
+  Rule,
+  RuleResult,
+  Safety,
+} from "./types";

package/src/{utils/path-access.test.ts → core/paths/access.test.ts}

@@ -1,9 +1,5 @@
 import { assert, describe, expect, it } from "vitest";
-import {
-  checkPathAccess,
-  isPathAllowed,
-  type PathAccessState,
-} from "./path-access";
+import { checkPathAccess, isPathAllowed, type PathAccessState } from "./access";
 
 describe("isPathAllowed", () => {
   describe("when allowedPaths is empty", () => {

package/src/core/paths/index.ts

@@ -0,0 +1,14 @@
+export {
+  checkPathAccess,
+  isPathAllowed,
+  type PathAccessState,
+  type PathDecision,
+} from "./access";
+export {
+  expandHomePath,
+  isWithinBoundary,
+  maybePathLike,
+  normalizeForDisplay,
+  resolveFromCwd,
+  toStorageForm,
+} from "./path";

package/src/core/shell/command-args.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "vitest";
+import { classifyCommandArgs } from "./command-args";
+
+const tokens = (command: string, args: string[]) =>
+  classifyCommandArgs(command, args).map((arg) => arg.token);
+
+describe("classifyCommandArgs", () => {
+  it("keeps unknown command arguments unchanged", () => {
+    expect(tokens("cat", ["/etc/hosts", "./file"])).toEqual([
+      "/etc/hosts",
+      "./file",
+    ]);
+  });
+
+  it("normalizes command basenames", () => {
+    expect(tokens("/usr/bin/awk", ["/aaa/{print}", "./input"])).toEqual([
+      "./input",
+    ]);
+  });
+
+  it("ignores awk inline program and keeps file operands", () => {
+    expect(tokens("awk", ["/aaa/{print}", "./input"])).toEqual(["./input"]);
+  });
+
+  it.each([
+    ["-f as separate option", ["-f", "./prog.awk", "./input"]],
+    ["-f as joined option", ["-f./prog.awk", "./input"]],
+  ])("keeps awk program files with %s", (_label, args) => {
+    expect(tokens("awk", args)).toEqual(["./prog.awk", "./input"]);
+  });
+
+  it("ignores sed inline scripts and keeps file operands", () => {
+    expect(tokens("sed", ["s#/old#/new#g", "./file"])).toEqual(["./file"]);
+  });
+
+  it.each([
+    ["-f as separate option", ["-f", "./script.sed", "./file"]],
+    ["--file as long option", ["--file", "./script.sed", "./file"]],
+    ["-f as joined option", ["-f./script.sed", "./file"]],
+  ])("keeps sed script files with %s", (_label, args) => {
+    expect(tokens("sed", args)).toEqual(["./script.sed", "./file"]);
+  });
+
+  it("ignores grep patterns and keeps file operands", () => {
+    expect(tokens("grep", ["/api/v1", "./src"])).toEqual(["./src"]);
+  });
+
+  it.each([
+    ["-f as separate option", ["-f", "./patterns", "./src"]],
+    ["--file as long option", ["--file", "./patterns", "./src"]],
+    ["-f as joined option", ["-f./patterns", "./src"]],
+  ])("keeps grep pattern files with %s", (_label, args) => {
+    expect(tokens("grep", args)).toEqual(["./patterns", "./src"]);
+  });
+
+  it("keeps find roots and ignores expression patterns", () => {
+    expect(tokens("find", ["./src", "-regex", ".*/test/.*"])).toEqual([
+      "./src",
+    ]);
+  });
+
+  it("ignores jq filters and keeps file operands", () => {
+    expect(tokens("jq", ['.path | test("^/tmp/")', "./data.json"])).toEqual([
+      "./data.json",
+    ]);
+  });
+
+  it.each([
+    ["-f as separate option", ["-f", "./filter.jq", "./data.json"]],
+    [
+      "--from-file as long option",
+      ["--from-file", "./filter.jq", "./data.json"],
+    ],
+  ])("keeps jq filter files with %s", (_label, args) => {
+    expect(tokens("jq", args)).toEqual(["./filter.jq", "./data.json"]);
+  });
+
+  it("ignores interpreter inline code", () => {
+    expect(tokens("python3", ["-c", 'open("/etc/passwd")'])).toEqual([]);
+  });
+
+  it("keeps interpreter script operands", () => {
+    expect(tokens("python3", ["./script.py", "./data.json"])).toEqual([
+      "./script.py",
+      "./data.json",
+    ]);
+  });
+
+  it("ignores delimiter args", () => {
+    expect(tokens("cut", ["-d", "/", "./file"])).toEqual(["./file"]);
+    expect(tokens("sort", ["-t", "/", "./file"])).toEqual(["./file"]);
+    expect(tokens("tr", ["/", ":"])).toEqual([]);
+  });
+
+  describe("go subcommand", () => {
+    it("skips Go package wildcard patterns", () => {
+      expect(tokens("go", ["test", "./..."])).toEqual([]);
+    });
+
+    it("keeps go run .go file operands", () => {
+      expect(tokens("go", ["run", "main.go"])).toEqual(["main.go"]);
+    });
+
+    it("skips non-.go positionals for go run", () => {
+      expect(tokens("go", ["run", "-exec", "/bin/env", "main.go"])).toEqual([
+        "main.go",
+      ]);
+    });
+
+    it("skips package patterns for build/vet/list", () => {
+      expect(tokens("go", ["build", "./..."])).toEqual([]);
+      expect(tokens("go", ["vet", "./pkg/..."])).toEqual([]);
+      expect(tokens("go", ["list", "./..."])).toEqual([]);
+    });
+
+    it("keeps file-valued flags", () => {
+      expect(tokens("go", ["build", "-modfile", "./go.mod", "./..."])).toEqual([
+        "./go.mod",
+      ]);
+    });
+
+    it("keeps -o flag value for go build", () => {
+      expect(tokens("go", ["build", "-o", "./bin/app", "./..."])).toEqual([
+        "./bin/app",
+      ]);
+    });
+
+    it("handles -C global flag before subcommand", () => {
+      expect(tokens("go", ["-C", "/tmp", "test", "./..."])).toEqual([]);
+    });
+
+    it("handles -C joined form before subcommand", () => {
+      expect(tokens("go", ["-C=/tmp", "test", "./..."])).toEqual([]);
+    });
+
+    it("keeps go run .go file operands with -C", () => {
+      expect(tokens("go", ["-C", "/tmp", "run", "main.go"])).toEqual([
+        "main.go",
+      ]);
+    });
+  });
+});

package/src/{utils → core/shell}/command-args.ts

@@ -32,6 +32,7 @@ export function classifyCommandArgs(
   ) {
     return classifyInterpreterArgs(cmd, args);
   }
+  if (cmd === "go") return classifyGoArgs(args);
   if (cmd === "cut")
     return skipOptionValues(args, new Set(["-d", "--delimiter"]));
   if (cmd === "sort")
@@ -224,3 +225,73 @@ function skipOptionValues(
   }
   return out;
 }
+
+/**
+ * Classify `go` subcommand arguments.
+ *
+ * Go commands take package patterns, not file paths, as positional args
+ * for most subcommands. Package patterns like `./...`, `pkg/...`,
+ * or `github.com/user/repo/...` use Go's `...` wildcard and are not
+ * filesystem paths.
+ *
+ * `go run` is an exception: it takes .go file operands, emitted with
+ * `forcePath` since bare filenames like `main.go` don't pass
+ * `maybePathLike`.
+ *
+ * File-valued flags (e.g. `-o`, `-modfile`, `-overlay`) are kept
+ * so that policy checks can still gate them.
+ *
+ * Global flags like `-C dir` are handled before subcommand detection
+ * so their values aren't mistaken for the subcommand.
+ */
+function classifyGoArgs(args: string[]): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  const fileFlags = new Set(["-o", "-modfile", "-overlay"]);
+
+  // Global flags that consume a value and must be skipped before
+  // subcommand detection. E.g. `go -C /tmp test ./...`
+  const globalFlagsWithValues = new Set(["-C"]);
+
+  let subcommand: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+
+    // Handle file-valued flags
+    if (fileFlags.has(arg)) {
+      if (args[i + 1]) out.push({ token: args[++i] as string });
+      continue;
+    }
+
+    // Handle joined file flags like -o=./bin/app
+    if (arg.startsWith("-o=")) {
+      out.push({ token: arg.slice(3) });
+      continue;
+    }
+
+    // Skip global flags with values before subcommand detection
+    if (!subcommand && globalFlagsWithValues.has(arg)) {
+      i++; // skip value
+      continue;
+    }
+    if (!subcommand && arg.startsWith("-C=")) {
+      // joined form -C=/tmp
+      continue;
+    }
+
+    if (isOption(arg)) continue;
+
+    // First non-flag positional is the subcommand
+    if (!subcommand) {
+      subcommand = arg;
+      continue;
+    }
+
+    // `go run` takes .go file operands; emit with forcePath since
+    // bare filenames like main.go don't pass maybePathLike.
+    // All other subcommands take package patterns; skip them.
+    if (subcommand === "run" && arg.endsWith(".go")) {
+      out.push({ token: arg, forcePath: true });
+    }
+  }
+  return out;
+}

package/src/core/shell/index.ts

@@ -0,0 +1,2 @@
+export { walkCommands, wordToString } from "./ast";
+export { type ClassifiedArg, classifyCommandArgs } from "./command-args";

package/src/core/types.ts

@@ -0,0 +1,55 @@
+export type Action =
+  | {
+      kind: "file";
+      path: string;
+      origin?: string;
+    }
+  | {
+      kind: "command";
+      command: string;
+      origin?: string;
+    };
+
+export type RuleResult<TMeta = null> =
+  | {
+      kind: "pass";
+    }
+  | {
+      kind: "match";
+      reason: string;
+      metadata: TMeta;
+    };
+
+export type Safety<TMeta = null> =
+  | {
+      kind: "safe";
+    }
+  | {
+      kind: "dangerous";
+      action: Action;
+      key: string;
+      reason: string;
+      metadata: TMeta;
+    };
+
+export type Rule<TMeta = null> = {
+  key: string;
+  check: (action: Action) => RuleResult<TMeta> | Promise<RuleResult<TMeta>>;
+};
+
+export type PermissionState = "granted" | "prompt" | "denied";
+
+export type Grant = "once" | "always" | "never";
+
+export type Decision<TMeta = null> =
+  | {
+      kind: "allow";
+    }
+  | {
+      kind: "deny";
+      reason: string;
+    }
+  | {
+      kind: "prompt";
+      risk: Safety<TMeta> & { kind: "dangerous" };
+    };

package/src/shared/config/defaults.ts

@@ -0,0 +1,118 @@
+import { CURRENT_VERSION } from "./migration";
+import type { ResolvedConfig } from "./types";
+
+export const DEFAULT_CONFIG: ResolvedConfig = {
+  version: CURRENT_VERSION,
+  enabled: true,
+  applyBuiltinDefaults: true,
+  features: {
+    policies: true,
+    permissionGate: true,
+    pathAccess: false,
+  },
+  pathAccess: {
+    mode: "ask",
+    allowedPaths: [],
+  },
+  policies: {
+    rules: [
+      {
+        id: "secret-files",
+        description: "Files containing secrets",
+        patterns: [
+          { pattern: ".env" },
+          { pattern: ".env.local" },
+          { pattern: ".env.production" },
+          { pattern: ".env.prod" },
+          { pattern: ".dev.vars" },
+        ],
+        allowedPatterns: [
+          { pattern: "*.example.env" },
+          { pattern: "*.sample.env" },
+          { pattern: "*.test.env" },
+          { pattern: ".env.example" },
+          { pattern: ".env.sample" },
+          { pattern: ".env.test" },
+        ],
+        protection: "noAccess",
+        onlyIfExists: true,
+        blockMessage:
+          "Accessing {file} is not allowed. This file contains secrets. " +
+          "Explain to the user why you want to access this file, and if changes are needed ask the user to make them.",
+      },
+      {
+        id: "home-ssh",
+        description: "SSH directory and keys",
+        enabled: false,
+        patterns: [
+          { pattern: "~/.ssh/**" },
+          { pattern: "~/.ssh/*_rsa" },
+          { pattern: "~/.ssh/*_ed25519" },
+          { pattern: "~/.ssh/*.pem" },
+        ],
+        allowedPatterns: [{ pattern: "~/.ssh/*.pub" }],
+        protection: "noAccess",
+        onlyIfExists: true,
+        blockMessage:
+          "Accessing {file} is not allowed. This file is part of your SSH configuration and may contain private keys or sensitive host information.",
+      },
+      {
+        id: "home-config",
+        description: "Sensitive user configuration directories",
+        enabled: false,
+        patterns: [
+          { pattern: "~/.config/gh/**" },
+          { pattern: "~/.config/gcloud/**" },
+          { pattern: "~/.config/op/**" },
+          { pattern: "~/.config/sops/**" },
+        ],
+        protection: "noAccess",
+        onlyIfExists: true,
+        blockMessage:
+          "Accessing {file} is not allowed. This file is in a sensitive user configuration directory and may contain credentials or tokens.",
+      },
+      {
+        id: "home-gpg",
+        description: "GPG keys and configuration",
+        enabled: false,
+        patterns: [
+          { pattern: "~/.gnupg/**" },
+          { pattern: "~/*.gpg" },
+          { pattern: "~/.gpg-agent.conf" },
+        ],
+        protection: "noAccess",
+        onlyIfExists: true,
+        blockMessage:
+          "Accessing {file} is not allowed. This file is part of your GPG configuration and may contain private keys or trust settings.",
+      },
+    ],
+  },
+  permissionGate: {
+    patterns: [
+      { pattern: "rm -rf", description: "recursive force delete" },
+      { pattern: "sudo", description: "superuser command" },
+      { pattern: "dd of=", description: "disk write operation" },
+      { pattern: "mkfs.", description: "filesystem format" },
+      {
+        pattern: "chmod -R 777",
+        description: "insecure recursive permissions",
+      },
+      { pattern: "chown -R", description: "recursive ownership change" },
+      { pattern: "doas", description: "privileged command execution" },
+      { pattern: "pkexec", description: "privileged command execution" },
+      { pattern: "shred", description: "secure file overwrite" },
+      { pattern: "wipefs", description: "filesystem signature wipe" },
+      { pattern: "blkdiscard", description: "block device discard" },
+      { pattern: "fdisk", description: "disk partitioning" },
+      { pattern: "parted", description: "disk partitioning" },
+      {
+        pattern: "docker run --privileged",
+        description: "container with privileged mode",
+      },
+    ],
+    useBuiltinMatchers: true,
+    requireConfirmation: true,
+    allowedPatterns: [],
+    autoDenyPatterns: [],
+  },
+};

package/src/shared/config/index.ts

@@ -0,0 +1,17 @@
+export { DEFAULT_CONFIG } from "./defaults";
+export { configLoader } from "./loader";
+export {
+  CURRENT_VERSION,
+  globalConfigMigrations,
+  migrations,
+} from "./migration";
+export type {
+  DangerousPattern,
+  GuardrailsConfig,
+  PathAccessConfig,
+  PathAccessMode,
+  PatternConfig,
+  PolicyRule,
+  Protection,
+  ResolvedConfig,
+} from "./types";

package/src/shared/config/loader.ts

@@ -0,0 +1,64 @@
+import { buildSchemaUrl, ConfigLoader } from "@aliou/pi-utils-settings";
+import pkg from "../../../package.json" with { type: "json" };
+import { DEFAULT_CONFIG } from "./defaults";
+import { migrations } from "./migration";
+import type { GuardrailsConfig, PolicyRule, ResolvedConfig } from "./types";
+
+export const configLoader = new ConfigLoader<GuardrailsConfig, ResolvedConfig>(
+  "guardrails",
+  DEFAULT_CONFIG,
+  {
+    scopes: ["global", "local", "memory"],
+    migrations,
+    schemaUrl: buildSchemaUrl(pkg.name, pkg.version),
+    afterMerge: (resolved, global, local, memory) => {
+      const ruleMap = new Map<string, PolicyRule>();
+
+      if (resolved.applyBuiltinDefaults) {
+        for (const rule of DEFAULT_CONFIG.policies.rules) {
+          ruleMap.set(rule.id, rule);
+        }
+      }
+      if (global?.policies?.rules) {
+        for (const rule of global.policies.rules) {
+          ruleMap.set(rule.id, rule);
+        }
+      }
+      if (local?.policies?.rules) {
+        for (const rule of local.policies.rules) {
+          ruleMap.set(rule.id, rule);
+        }
+      }
+      if (memory?.policies?.rules) {
+        for (const rule of memory.policies.rules) {
+          ruleMap.set(rule.id, rule);
+        }
+      }
+      resolved.policies.rules = [...ruleMap.values()];
+
+      const customPatterns =
+        memory?.permissionGate?.customPatterns ??
+        local?.permissionGate?.customPatterns ??
+        global?.permissionGate?.customPatterns;
+      if (customPatterns) {
+        resolved.permissionGate.patterns = customPatterns;
+        resolved.permissionGate.useBuiltinMatchers = false;
+      }
+
+      const mergedPaths = new Set<string>();
+      for (const paths of [
+        global?.pathAccess?.allowedPaths,
+        local?.pathAccess?.allowedPaths,
+        memory?.pathAccess?.allowedPaths,
+      ]) {
+        for (const path of paths ?? []) {
+          const trimmed = path.trim();
+          if (trimmed) mergedPaths.add(trimmed);
+        }
+      }
+      resolved.pathAccess.allowedPaths = [...mergedPaths];
+
+      return resolved;
+    },
+  },
+);