pi-safety-guards 0.1.0

package/src/config.ts

@@ -0,0 +1,151 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_PRESETS, PRESETS } from "./presets.ts";
+import { i18n } from "./i18n.ts";
+import type { Detector, RuleAction, RuleMatch, RuleMessage, SafetyConfig, SafetyRule } from "./types.ts";
+
+const EXTENSIONS_DIR = "extensions";
+const PACKAGE_NAME = "pi-safety-guards";
+const CONFIG_FILENAME = "config.json";
+const FILE_NOT_FOUND_CODE = "ENOENT";
+const ACTIONS = new Set<unknown>(["warn", "confirm", "block"]);
+const DETECTORS = new Set<unknown>(["disk-format", "fork-bomb", "in-place-edit", "home-root", "root-search"]);
+
+/** 返回 agent 目录下的显式用户配置位置。 */
+export function configPath(): string {
+  return join(getAgentDir(), EXTENSIONS_DIR, PACKAGE_NAME, CONFIG_FILENAME);
+}
+
+export interface SafetyConfigDocument {
+  presets: string[];
+  rules: unknown[];
+}
+
+/** 读取配置文件的用户文档，保留预设选择和自定义规则原文。 */
+export function loadConfigDocument(path = configPath()): SafetyConfigDocument {
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    parseConfig(raw);
+    return {
+      presets: raw.presets === undefined ? [...DEFAULT_PRESETS] : [...(raw.presets as string[])],
+      rules: raw.rules === undefined ? [] : [...(raw.rules as unknown[])],
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === FILE_NOT_FOUND_CODE) {
+      return { presets: [...DEFAULT_PRESETS], rules: [] };
+    }
+    throw error;
+  }
+}
+
+/** 将完整的用户配置文档校验后写入文件。 */
+export function saveConfigDocument(document: SafetyConfigDocument, path = configPath()): string {
+  parseConfig(document);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(document, null, 2)}\n`, "utf8");
+  return path;
+}
+
+/** 将经过校验的安全规则配置写入配置文件。 */
+export function saveConfig(config: SafetyConfig, path = configPath()): string {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  return path;
+}
+
+/** 将配置错误转换成双语诊断，不悄悄忽略未知配置。 */
+function invalid(field: string): never {
+  throw new Error(i18n.t("configInvalidField", { field }));
+}
+
+/** 收窄普通 JSON 对象。 */
+function object(value: unknown, field: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return invalid(field);
+  return value as Record<string, unknown>;
+}
+
+/** 拒绝字段拼写错误和旧技术专属配置，避免误启用默认策略。 */
+function checkKeys(raw: Record<string, unknown>, keys: readonly string[], field: string): void {
+  for (const key of Object.keys(raw)) {
+    if (!keys.includes(key)) invalid(`${field}.${key}`);
+  }
+}
+
+/** 验证非空文本数组，目录允许空列表以表达不信任任何根。 */
+function strings(value: unknown, field: string, allowEmpty = false): string[] {
+  if (!Array.isArray(value) || (!allowEmpty && value.length === 0)) return invalid(field);
+  if (value.some((item) => typeof item !== "string" || !item.trim())) return invalid(field);
+  return value.map((item: string) => item.trim());
+}
+
+/** 匹配器只允许一种类型，不组合成规则表达式语言。 */
+function parseMatch(value: unknown, field: string): RuleMatch {
+  const raw = object(value, field);
+  if (Object.keys(raw).length !== 1) return invalid(field);
+  if (Object.hasOwn(raw, "commands")) return { commands: strings(raw.commands, field) };
+  if (Object.hasOwn(raw, "outsideRoots")) return { outsideRoots: strings(raw.outsideRoots, field, true) };
+  if (Object.hasOwn(raw, "detector") && DETECTORS.has(raw.detector)) return { detector: raw.detector as Detector };
+  if (typeof raw.module === "string" && raw.module.trim()) return { module: raw.module.trim() };
+  return invalid(field);
+}
+
+/** 用户本地文案可用单一语言，公共示例提供中英文。 */
+function parseMessage(value: unknown, field: string): RuleMessage {
+  if (typeof value === "string" && value.trim()) return value;
+  const raw = object(value, field);
+  checkKeys(raw, ["zh-CN", "en-US"], field);
+  if (typeof raw["zh-CN"] !== "string" || !raw["zh-CN"].trim() ||
+      typeof raw["en-US"] !== "string" || !raw["en-US"].trim()) return invalid(field);
+  return { "zh-CN": raw["zh-CN"], "en-US": raw["en-US"] };
+}
+
+/** 选择预设后按稳定 ID 覆盖，不继承任何维护者的技术栈策略。 */
+export function parseConfig(value: unknown): SafetyConfig {
+  const raw = object(value, "config");
+  checkKeys(raw, ["presets", "rules"], "config");
+  const presets = raw.presets === undefined ? DEFAULT_PRESETS : strings(raw.presets, "presets", true);
+  const rules = new Map<string, SafetyRule>();
+  for (const preset of presets) {
+    if (!Object.hasOwn(PRESETS, preset)) invalid(`presets.${preset}`);
+    for (const rule of PRESETS[preset]) {
+      // 不共享可变预设对象，用户模块也不会收到规则配置引用。
+      rules.set(rule.id, structuredClone(rule));
+    }
+  }
+  const overrides = raw.rules === undefined ? [] : raw.rules;
+  if (!Array.isArray(overrides)) return invalid("rules");
+  const seen = new Set<string>();
+  for (const value of overrides) {
+    const override = object(value, "rules");
+    checkKeys(override, ["id", "enabled", "action", "match", "message"], "rules");
+    if (typeof override.id !== "string" || !override.id.trim()) invalid("rules.id");
+    const id = (override.id as string).trim();
+    if (seen.has(id)) invalid(`rules.${id}`);
+    seen.add(id);
+    if (override.enabled !== undefined && typeof override.enabled !== "boolean") invalid(`${id}.enabled`);
+    const previous = rules.get(id);
+    const action = override.action ?? previous?.action;
+    if (override.action !== undefined && !ACTIONS.has(override.action)) invalid(`${id}.action`);
+    const match = override.match === undefined ? previous?.match : parseMatch(override.match, `${id}.match`);
+    const message = override.message === undefined ? previous?.message : parseMessage(override.message, `${id}.message`);
+    if (override.enabled === false) {
+      if (!previous && !match) invalid(`${id}.match`);
+      rules.delete(id);
+      continue;
+    }
+    if (!ACTIONS.has(action) || !match) invalid(id);
+    rules.set(id, { id, action: action as RuleAction, match: match!, ...(message === undefined ? {} : { message }) });
+  }
+  return { rules: [...rules.values()] };
+}
+
+/** 仅文件不存在时使用默认预设；配置损坏会阻止受保护工具执行。 */
+export function loadConfig(path = configPath()): SafetyConfig {
+  try {
+    return parseConfig(JSON.parse(readFileSync(path, "utf8")));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === FILE_NOT_FOUND_CODE) return parseConfig({});
+    throw error;
+  }
+}

package/src/engine.ts

@@ -0,0 +1,168 @@
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { analyzeShellCommand, type ShellCommandAnalysis } from "./shell-command-utils.ts";
+import { findOutOfScopeBashPaths } from "./bash-directory-scope-utils.ts";
+import { i18n } from "./i18n.ts";
+import type { Detector, RuleAction, RuleContext, RuleMatcher, RuleMatch, SafetyConfig, SafetyRule } from "./types.ts";
+
+const MODULE_TIMEOUT_MS = 5_000;
+const ACTION_ORDER: readonly RuleAction[] = ["block", "confirm", "warn"];
+const FORK_BOMB_NAME = ":";
+const FORMAT_COMMAND = "mkfs";
+const FORMAT_PREFIX = "mkfs.";
+const FUNCTION_NODE = "Function";
+const EDIT_COMMAND = "sed";
+const SEARCH_COMMAND = "find";
+const IN_PLACE_OPTION = "--in-place";
+const HOME_ROOT = "~";
+const FILESYSTEM_ROOT = "/";
+
+export interface CompiledRule {
+  readonly rule: SafetyRule;
+  readonly matcher?: RuleMatcher;
+}
+export interface PolicyDecision {
+  readonly action: RuleAction;
+  readonly matches: readonly SafetyRule[];
+}
+export type ModuleLoader = (path: string) => Promise<unknown>;
+
+/** 只加载配置指定的本地模块；mtime 使 reload 可以读取规则文件的新版本。 */
+async function loadModule(path: string): Promise<unknown> {
+  const url = pathToFileURL(path);
+  url.searchParams.set("mtime", String(statSync(path).mtimeMs));
+  return import(url.href);
+}
+
+/** 在注册任何工具 hook 之前加载启用的规则，避免部分注册后才发现配置错误。 */
+export async function compileRules(
+  config: SafetyConfig,
+  configDirectory: string,
+  loader: ModuleLoader = loadModule,
+): Promise<CompiledRule[]> {
+  const compiled: CompiledRule[] = [];
+  for (const rule of config.rules) {
+    if (!("module" in rule.match)) {
+      compiled.push({ rule });
+      continue;
+    }
+    try {
+      const modulePath = resolve(configDirectory, rule.match.module);
+      const module = await withDeadline(() => loader(modulePath));
+      const matcher = module && typeof module === "object" ? (module as { default?: unknown }).default : undefined;
+      if (typeof matcher !== "function") throw new Error(i18n.t("moduleMustExportMatcher"));
+      compiled.push({ rule, matcher: matcher as RuleMatcher });
+    } catch (error) {
+      throw ruleFailure(rule.id, error);
+    }
+  }
+  return compiled;
+}
+
+/** 检测器只返回匹配事实，动作和建议不属于检测器。 */
+function detect(detector: Detector, analysis: ShellCommandAnalysis, command: string): boolean {
+  switch (detector) {
+    case "disk-format":
+      return analysis.commands.some(({ name }) => name === FORMAT_COMMAND || name.startsWith(FORMAT_PREFIX));
+    case "fork-bomb":
+      return /:\(\)\s*\{/.test(command) && analysis.nodes.some(isForkBombFunction);
+    case "in-place-edit":
+      return analysis.commands.some(({ name, args }) => name === EDIT_COMMAND && args.some(({ value }) => isInPlaceOption(value)));
+    case "home-root":
+      return analysis.commands.some(({ args }) => args.some(({ text }) => text === HOME_ROOT));
+    case "root-search":
+      return analysis.commands.some(({ name, args }) => name === SEARCH_COMMAND && args.some(({ value }) => value === FILESYSTEM_ROOT));
+  }
+}
+
+/** 匹配已有 fork bomb 检测范围中的冒号函数节点。 */
+function isForkBombFunction(node: Record<string, unknown>): boolean {
+  if (node.type !== FUNCTION_NODE || !node.name || typeof node.name !== "object") return false;
+  return (node.name as { value?: unknown }).value === FORK_BOMB_NAME;
+}
+
+/** 识别 sed 组合短选项和带备份后缀的原地编辑选项。 */
+function isInPlaceOption(value: string): boolean {
+  if (value === IN_PLACE_OPTION || value.startsWith(`${IN_PLACE_OPTION}=`)) return true;
+  return /^-[^-]*i/.test(value);
+}
+
+/** 用户模块只拿到深度冻结的命令摘要，不能改写后续内置规则的分析结果。 */
+function moduleContext(command: string, cwd: string, analysis: ShellCommandAnalysis): RuleContext {
+  return Object.freeze({
+    command,
+    cwd,
+    commands: Object.freeze(analysis.commands.map(({ name, args }) => Object.freeze({
+      name,
+      args: Object.freeze(args.map(({ value }) => value)),
+    }))),
+  });
+}
+
+/** 有界等待异步规则；同进程同步死循环不能被抢占，模块必须可信。 */
+function withDeadline<T>(operation: () => Promise<T> | T): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(i18n.t("moduleTimeout"))), MODULE_TIMEOUT_MS);
+    Promise.resolve().then(operation).then(
+      (value) => { clearTimeout(timer); resolve(value); },
+      (error) => { clearTimeout(timer); reject(error); },
+    );
+  });
+}
+
+/** 命令名只建立一次索引；内置检测保持明确的分支。 */
+function matchesBuiltin(
+  match: RuleMatch,
+  context: RuleContext,
+  analysis: ShellCommandAnalysis,
+  commandNames: ReadonlySet<string>,
+  additionalRoots: readonly string[],
+): boolean {
+  if ("commands" in match) return match.commands.some((name) => commandNames.has(name));
+  if ("detector" in match) return detect(match.detector, analysis, context.command);
+  if ("outsideRoots" in match) {
+    return findOutOfScopeBashPaths(
+      context.command,
+      context.cwd,
+      [...match.outsideRoots, ...additionalRoots],
+    ).length > 0;
+  }
+  throw new Error(i18n.t("moduleMustExportMatcher"));
+}
+
+/** 错误保留规则 ID，绝不按未命中继续执行。 */
+function ruleFailure(id: string, error: unknown): Error {
+  return new Error(i18n.t("ruleFailed", {
+    id,
+    error: error instanceof Error ? error.message : String(error),
+  }), { cause: error });
+}
+
+/** 评估所有规则并按 block > confirm > warn 合并，不能用前面的低风险动作绕过阻断。 */
+export async function evaluateRules(
+  rules: readonly CompiledRule[],
+  command: string,
+  cwd: string,
+  additionalRoots: readonly string[] = [],
+): Promise<PolicyDecision | undefined> {
+  if (rules.length === 0) return undefined;
+  const analysis = analyzeShellCommand(command);
+  if (analysis.errors.length) throw new Error(i18n.t("shellParseBlocked"));
+  const context = moduleContext(command, cwd, analysis);
+  const commandNames = new Set(analysis.commands.map(({ name }) => name));
+  const matches: SafetyRule[] = [];
+  for (const { rule, matcher } of rules) {
+    try {
+      const matched = matcher
+        ? await withDeadline(() => matcher(context))
+        : matchesBuiltin(rule.match, context, analysis, commandNames, additionalRoots);
+      if (typeof matched !== "boolean") throw new Error(i18n.t("matcherMustReturnBoolean"));
+      if (matched) matches.push(rule);
+    } catch (error) {
+      throw ruleFailure(rule.id, error);
+    }
+  }
+  const action = ACTION_ORDER.find((action) => matches.some((rule) => rule.action === action));
+  return action ? { action, matches } : undefined;
+}

package/src/i18n.ts

@@ -0,0 +1,3 @@
+import { createTranslator, loadCatalog } from "pi-extensions-i18n";
+
+export const i18n = createTranslator(loadCatalog(new URL("../locales/i18n.json", import.meta.url)));

package/src/presets.ts

@@ -0,0 +1,16 @@
+import type { SafetyRule } from "./types.ts";
+
+/** 预设只保存规则数据，检测器不决定动作或替代工具。 */
+export const PRESETS: Readonly<Record<string, readonly SafetyRule[]>> = {
+  "destructive-operations": [
+    { id: "filesystem.delete", action: "confirm", match: { commands: ["rm", "rmdir"] } },
+    { id: "filesystem.format", action: "confirm", match: { detector: "disk-format" } },
+    { id: "filesystem.ownership", action: "confirm", match: { commands: ["chown"] } },
+    { id: "shell.fork-bomb", action: "confirm", match: { detector: "fork-bomb" } },
+  ],
+  "workspace-boundary": [
+    { id: "paths.workspace", action: "block", match: { outsideRoots: ["."] } },
+  ],
+};
+
+export const DEFAULT_PRESETS = ["destructive-operations"] as const;