@aliou/pi-guardrails 0.11.2 → 0.12.0

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/{utils → core/shell}/command-args.test.ts

@@ -12,37 +12,45 @@ describe("classifyCommandArgs", () => {
     ]);
   });
 
+  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("keeps awk -f program files", () => {
-    expect(tokens("awk", ["-f", "./prog.awk", "./input"])).toEqual([
-      "./prog.awk",
-      "./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("keeps sed -f script files", () => {
-    expect(tokens("sed", ["-f", "./script.sed", "./file"])).toEqual([
-      "./script.sed",
-      "./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("keeps grep pattern files", () => {
-    expect(tokens("grep", ["-f", "./patterns", "./src"])).toEqual([
-      "./patterns",
-      "./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", () => {
@@ -57,11 +65,14 @@ describe("classifyCommandArgs", () => {
     ]);
   });
 
-  it("keeps jq -f filter files", () => {
-    expect(tokens("jq", ["-f", "./filter.jq", "./data.json"])).toEqual([
-      "./filter.jq",
-      "./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", () => {

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;
+    },
+  },
+);

package/src/shared/config/migration/001-v0-format-upgrade.ts

@@ -0,0 +1,107 @@
+import { copyFile, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { addPendingWarning } from "../../warnings";
+import type {
+  DangerousPattern,
+  GuardrailsConfig,
+  PatternConfig,
+} from "../types";
+import { CURRENT_VERSION } from "./version";
+
+export function shouldRun(config: GuardrailsConfig): boolean {
+  return config.version === undefined;
+}
+
+export async function run(
+  config: GuardrailsConfig,
+  filePath: string,
+): Promise<GuardrailsConfig> {
+  await backupConfig(filePath);
+  return migrateV0(config);
+}
+
+function migrateV0(config: GuardrailsConfig): GuardrailsConfig {
+  const migrated = structuredClone(config);
+
+  if (migrated.envFiles) {
+    if (migrated.envFiles.protectedPatterns) {
+      migrated.envFiles.protectedPatterns = migrateStringArray(
+        migrated.envFiles.protectedPatterns,
+      );
+    }
+    if (migrated.envFiles.allowedPatterns) {
+      migrated.envFiles.allowedPatterns = migrateStringArray(
+        migrated.envFiles.allowedPatterns,
+      );
+    }
+    if (migrated.envFiles.protectedDirectories) {
+      migrated.envFiles.protectedDirectories = migrateStringArray(
+        migrated.envFiles.protectedDirectories,
+      );
+    }
+  }
+
+  if (migrated.permissionGate) {
+    if (migrated.permissionGate.patterns) {
+      migrated.permissionGate.patterns = migrateDangerousPatterns(
+        migrated.permissionGate.patterns,
+      );
+    }
+    if (migrated.permissionGate.customPatterns) {
+      migrated.permissionGate.customPatterns = migrateDangerousPatterns(
+        migrated.permissionGate.customPatterns,
+      );
+    }
+    if (migrated.permissionGate.allowedPatterns) {
+      migrated.permissionGate.allowedPatterns = migrateStringArray(
+        migrated.permissionGate.allowedPatterns,
+      );
+    }
+    if (migrated.permissionGate.autoDenyPatterns) {
+      migrated.permissionGate.autoDenyPatterns = migrateStringArray(
+        migrated.permissionGate.autoDenyPatterns,
+      );
+    }
+  }
+
+  migrated.version = CURRENT_VERSION;
+  return migrated;
+}
+
+function migrateStringArray(
+  items: (string | PatternConfig)[],
+): PatternConfig[] {
+  return items.map((item) => {
+    if (typeof item === "string") return { pattern: item, regex: true };
+    if (item.regex === undefined) return { ...item, regex: true };
+    return item;
+  });
+}
+
+function migrateDangerousPatterns(
+  items: (DangerousPattern | { pattern: string; description: string })[],
+): DangerousPattern[] {
+  return items.map((item) => {
+    if ("regex" in item && item.regex !== undefined) {
+      return item as DangerousPattern;
+    }
+    return { ...item, regex: true };
+  });
+}
+
+async function backupConfig(configPath: string): Promise<void> {
+  const dir = dirname(configPath);
+  const basename = configPath.split("/").pop() ?? "guardrails.json";
+  const backupName = basename.replace(".json", ".v0.json");
+  const backupPath = resolve(dir, backupName);
+
+  try {
+    await stat(backupPath);
+  } catch {
+    try {
+      await copyFile(configPath, backupPath);
+    } catch (err) {
+      addPendingWarning(`guardrails: could not back up config: ${err}`);
+    }
+  }
+}

package/src/shared/config/migration/002-strip-toolchain-fields.ts

@@ -0,0 +1,39 @@
+import { addPendingWarning } from "../../warnings";
+import type { GuardrailsConfig } from "../types";
+import { CURRENT_VERSION } from "./version";
+
+const REMOVED_FEATURE_KEYS = [
+  "preventBrew",
+  "preventPython",
+  "enforcePackageManager",
+] as const;
+
+export function shouldRun(config: GuardrailsConfig): boolean {
+  const raw = config as Record<string, unknown>;
+  const features = raw.features as Record<string, unknown> | undefined;
+  if (features) {
+    for (const key of REMOVED_FEATURE_KEYS) {
+      if (key in features) return true;
+    }
+  }
+  return "packageManager" in raw;
+}
+
+export function run(config: GuardrailsConfig): GuardrailsConfig {
+  addPendingWarning(
+    "[guardrails] preventBrew, preventPython, enforcePackageManager, and packageManager " +
+      "have been removed from guardrails and moved to @aliou/pi-toolchain. " +
+      "These fields will be stripped from your config.",
+  );
+
+  const cleaned = structuredClone(config) as Record<string, unknown>;
+  const features = cleaned.features as Record<string, unknown> | undefined;
+  if (features) {
+    for (const key of REMOVED_FEATURE_KEYS) {
+      delete features[key];
+    }
+  }
+  delete cleaned.packageManager;
+  cleaned.version = CURRENT_VERSION;
+  return cleaned as GuardrailsConfig;
+}