dsh-desktop-kit 2.2.1 → 2.7.3

package/plugins/dsh-guardrails/lib/hooks.js

@@ -0,0 +1,262 @@
+/**
+ * Real Host hooks for the guardrails plugin.
+ *
+ * Two extension points are used, both verified against the live DSH Event
+ * contracts (see README "Event contracts"):
+ *
+ *  - `tools/pre-execute` is a waterfall `(exec, next) => PreToolDecision`.
+ *    Returning `next()` delegates; a `deny`/`ask` decision short-circuits.
+ *    The plugin uses it for shell commands (bash/pwsh, …) and as defence in
+ *    depth for file-mutating tool arguments (write/edit/apply_patch).
+ *
+ *  - `fs/write-intent`, `fs/edit-intent`, `fs/delete-intent` are single-slot
+ *    waterfalls `(target, actor, next) => guard | undefined`. Their contract
+ *    has no deny decision: `undefined`/`next()` allows and an intent owns the
+ *    mutation. A refusal is therefore a thrown `Error` — the same mechanism the
+ *    shipped `dsh-fs-observation-policy` uses (`FS_NOT_OBSERVED`). The plugin
+ *    only throws for a path matched by the policy and delegates otherwise, so
+ *    normal editing keeps working (documented conservative-allow fallback).
+ *
+ * Node built-ins only. Logs never include command text, target paths or secret
+ * values: they carry the rule id and the tool/event name only.
+ */
+import { evaluateCommand, loadPolicy, matchProtectedPath } from "./policy.js";
+import { modeDecision, resolveMode } from "./modes.js";
+
+/** Tool names whose command text is checked by the shell-command rules. */
+export const SHELL_TOOL_NAMES = new Set(["bash", "pwsh", "powershell", "shell", "sh", "zsh", "cmd", "terminal"]);
+
+/** File-mutating tool names whose path arguments are checked as defence in depth. */
+export const PROTECTED_PATH_TOOLS = new Set(["write", "edit", "apply_patch", "patch"]);
+
+const MAX_PATHS_PER_CALL = 200;
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Fresh hook registration state, reported by the `status` action. */
+export function createHookState() {
+  return {
+    toolsPreExecute: false,
+    fsWriteIntent: false,
+    fsEditIntent: false,
+    fsDeleteIntent: false,
+    errors: [],
+  };
+}
+
+/**
+ * Extract the command text from shell-tool arguments. Both the shipped bash and
+ * pwsh tools use the `command` field; `cmd`/`script` are accepted for other
+ * shell providers.
+ *
+ * @param {unknown} args - parsed tool arguments.
+ * @returns {string} command text, or an empty string.
+ */
+export function extractShellCommand(args) {
+  if (typeof args === "string") return args;
+  if (args === null || typeof args !== "object") return "";
+  for (const key of ["command", "cmd", "script"]) {
+    const value = args[key];
+    if (typeof value === "string" && value.trim().length > 0) return value;
+  }
+  return "";
+}
+
+/**
+ * Extract the paths a file-mutating tool plans to touch. For `apply_patch` the
+ * Codex-style patch headers are read; the mutation itself is still enforced by
+ * the authoritative `fs/*-intent` hooks.
+ *
+ * @param {string} toolName - tool name from `tools/pre-execute`.
+ * @param {unknown} args - parsed tool arguments.
+ * @returns {string[]} unique requested paths, bounded per call.
+ */
+export function requestedWritePaths(toolName, args) {
+  const paths = [];
+  if (args === null || typeof args !== "object") return paths;
+  if (toolName === "write" || toolName === "edit") {
+    for (const key of ["file_path", "path"]) {
+      const value = args[key];
+      if (typeof value === "string" && value.trim().length > 0) paths.push(value.trim());
+    }
+  } else if (PROTECTED_PATH_TOOLS.has(toolName)) {
+    const patchText = typeof args.input === "string" ? args.input : typeof args.patch === "string" ? args.patch : "";
+    for (const line of patchText.split(/\r?\n/u)) {
+      if (paths.length >= MAX_PATHS_PER_CALL) break;
+      const match = /^\*\*\*\s+(?:Add File|Update File|Delete File|Move to):\s*(.+)$/u.exec(line);
+      if (match !== null) paths.push(match[1].trim());
+    }
+  }
+  return [...new Set(paths)];
+}
+
+function policyHint() {
+  return "(bypass: DSH_GUARDRAILS=off, or edit ~/.dsh/guardrails.json)";
+}
+
+function denyDecision(reason, ruleId) {
+  return {
+    kind: "deny",
+    reason,
+    info: {
+      name: "GuardrailsDenied",
+      code: "GUARDRAILS_DENIED",
+      ...(typeof ruleId === "string" ? { reason: ruleId } : {}),
+    },
+  };
+}
+
+function askDecision(reason, ruleId) {
+  return {
+    kind: "ask",
+    reason,
+    displayReason: {
+      en: reason,
+      ru: `Guardrails: команда требует подтверждения (правило ${ruleId}).`,
+    },
+  };
+}
+
+/**
+ * Build the decision functions used by the event hooks. Pure state is read from
+ * `env` and from the policy file; the returned object is safe to share between
+ * listeners.
+ *
+ * @param {{env?: object, policyFile?: string, logger?: object}} [options] - environment, optional policy path override and logger.
+ * @returns {{load: () => object, preExecute: Function, fsIntent: Function}} guard.
+ */
+export function createGuard(options = {}) {
+  const env = options.env ?? process.env;
+  const policyFile = options.policyFile;
+  const logger = options.logger;
+  const load = () => loadPolicy({ env, ...(policyFile === undefined ? {} : { filePath: policyFile }) });
+  async function allowPreTool(next) {
+    return typeof next === "function" ? next() : { kind: "allow" };
+  }
+
+  async function preExecute(exec, next) {
+    let loaded;
+    try {
+      loaded = load();
+    } catch (error) {
+      logger?.warn?.(`[guardrails] policy load failed; allowing call: ${errorMessage(error)}`);
+      return allowPreTool(next);
+    }
+    if (!loaded.enabled || loaded.policy.hooks.toolsPreExecute === false) return allowPreTool(next);
+    try {
+      const toolName = typeof exec?.name === "string" ? exec.name : "";
+      if (SHELL_TOOL_NAMES.has(toolName)) {
+        const command = extractShellCommand(exec?.arguments);
+        if (command.length > 0) {
+          const verdict = evaluateCommand(command, { policy: loaded.policy });
+          if (verdict.action === "deny" || verdict.action === "ask") {
+            const ruleId = verdict.primary?.id ?? "policy";
+            logger?.debug?.(`[guardrails] pre-execute ${verdict.action} tool=${toolName} rule=${ruleId}`);
+            if (verdict.action === "deny") {
+              return denyDecision(
+                `guardrails: command denied by rule "${ruleId}" (${verdict.primary?.description ?? "policy"}). ${policyHint()}`,
+                ruleId,
+              );
+            }
+            return askDecision(
+              `guardrails: command requires confirmation by rule "${ruleId}" (${verdict.primary?.description ?? "policy"})`,
+              ruleId,
+            );
+          }
+        }
+      }
+      if (PROTECTED_PATH_TOOLS.has(toolName)) {
+        for (const requestedPath of requestedWritePaths(toolName, exec?.arguments)) {
+          const hit = matchProtectedPath(requestedPath, { policy: loaded.policy, env });
+          if (hit === undefined) continue;
+          logger?.debug?.(`[guardrails] pre-execute deny tool=${toolName} rule=${hit.id}`);
+          return denyDecision(
+            `guardrails: modifying a protected path is not allowed: ${requestedPath} (rule: ${hit.id}). ${policyHint()}`,
+            hit.id,
+          );
+        }
+      }
+      const mode = typeof options.modeFor === "function" ? options.modeFor(exec?.agent) : undefined;
+      const modeHit = modeDecision(mode, exec, exec?.agent?.session?.header?.cwd ?? process.cwd());
+      if (modeHit) {
+        logger?.debug?.(`[guardrails] pre-execute mode=${mode?.name ?? "?"} action=${modeHit.kind} tool=${toolName}`);
+        if (modeHit.kind === "ask") return askDecision(modeHit.reason, "permission-mode");
+        return denyDecision(modeHit.reason, "permission-mode");
+      }
+      return allowPreTool(next);
+    } catch (error) {
+      // Conservative allow: a guard failure must never break a normal call.
+      logger?.warn?.(`[guardrails] pre-execute check skipped: ${errorMessage(error)}`);
+      return allowPreTool(next);
+    }
+  }
+
+  async function allowIntent(next) {
+    return typeof next === "function" ? next() : undefined;
+  }
+
+  async function fsIntent(kind, target, next) {
+    let loaded;
+    try {
+      loaded = load();
+    } catch (error) {
+      logger?.warn?.(`[guardrails] policy load failed; allowing fs/${kind}: ${errorMessage(error)}`);
+      return allowIntent(next);
+    }
+    if (!loaded.enabled || loaded.policy.hooks.fsIntents === false) return allowIntent(next);
+    try {
+      const displayPath = typeof target?.displayPath === "string" ? target.displayPath : "";
+      if (displayPath.length === 0) return allowIntent(next);
+      const hit = matchProtectedPath(displayPath, { policy: loaded.policy, env });
+      if (hit === undefined) return allowIntent(next);
+      logger?.debug?.(`[guardrails] fs/${kind} protected rule=${hit.id}`);
+      const error = new Error(
+        `guardrails: ${kind} of a protected path is not allowed (rule: ${hit.id}). ${policyHint()}`,
+      );
+      error.name = "GuardrailsProtectedPathError";
+      error.code = "GUARDRAILS_PROTECTED_PATH";
+      error.ruleId = hit.id;
+      throw error;
+    } catch (error) {
+      if (error?.code === "GUARDRAILS_PROTECTED_PATH") throw error;
+      logger?.warn?.(`[guardrails] fs/${kind} check skipped: ${errorMessage(error)}`);
+      return allowIntent(next);
+    }
+  }
+
+  return { load, preExecute, fsIntent };
+}
+
+/**
+ * Register all four Host listeners on a Cordis context. Registration failures
+ * are recorded in `state.errors` instead of taking the plugin down; the
+ * `status` action reports what is actually installed.
+ *
+ * @param {object} ctx - Cordis context with `on()`.
+ * @param {ReturnType<typeof createGuard>} guard - guard from `createGuard`.
+ * @param {ReturnType<typeof createHookState>} state - mutable registration state.
+ * @returns {ReturnType<typeof createHookState>} the same state.
+ */
+export function registerHooks(ctx, guard, state) {
+  const on = (event, handler) => {
+    try {
+      ctx.on(event, handler);
+      return true;
+    } catch (error) {
+      state.errors.push({ event, message: errorMessage(error) });
+      try {
+        ctx.logger?.warn?.(`[guardrails] hook ${event} was not registered: ${errorMessage(error)}`);
+      } catch {
+        /* logging must never break activation */
+      }
+      return false;
+    }
+  };
+  state.toolsPreExecute = on("tools/pre-execute", (exec, next) => guard.preExecute(exec, next));
+  state.fsWriteIntent = on("fs/write-intent", (target, actor, next) => guard.fsIntent("write", target, next));
+  state.fsEditIntent = on("fs/edit-intent", (target, actor, next) => guard.fsIntent("edit", target, next));
+  state.fsDeleteIntent = on("fs/delete-intent", (target, actor, next) => guard.fsIntent("delete", target, next));
+  return state;
+}

package/plugins/dsh-guardrails/lib/modes.js

@@ -0,0 +1,77 @@
+/**
+ * Bridge DSH permission presets into the kit's tool guard.
+ *
+ * DSH already owns the picker and the approval card. The kit must not create a
+ * second one; it only enforces hard limits for the effective preset.
+ */
+import path from "node:path";
+
+const MUTATING_TOOLS = new Set(["write", "edit", "apply_patch", "delete", "move"]);
+const SHELL_TOOLS = new Set(["bash", "pwsh", "shell"]);
+const MUTATING_SHELL = /(?:^|[;&|]\s*|\s)(?:rm|rmdir|mv|cp|mkdir|touch|truncate|tee|dd|chmod|chown|Set-Content|Add-Content|Out-File|New-Item|Remove-Item|Move-Item|Copy-Item|git\s+(?:commit|push|reset|checkout|clean|merge|rebase)|npm\s+(?:install|uninstall|update)|pnpm\s+(?:add|remove|install)|composer\s+(?:install|update)|php\s+artisan\s+(?:migrate|db:)|dropdb|createdb|psql\b[^\n]*(?:insert|update|delete|drop|truncate|alter))/iu;
+
+export function requestedPaths(toolName, args) {
+  if (!args || typeof args !== "object") return [];
+  const values = [];
+  for (const key of ["file_path", "path", "cwd", "target", "source", "destination"]) {
+    if (typeof args[key] === "string" && args[key].length > 0) values.push(args[key]);
+  }
+  if (Array.isArray(args.paths)) values.push(...args.paths.filter((value) => typeof value === "string"));
+  return values;
+}
+
+export function isMutatingShell(command) {
+  return typeof command === "string" && MUTATING_SHELL.test(command);
+}
+
+function isInside(cwd, target) {
+  if (!cwd || !target) return false;
+  try {
+    const root = path.resolve(cwd);
+    const value = path.isAbsolute(target) ? path.resolve(target) : path.resolve(root, target);
+    return value === root || value.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {{name?: string, sandbox?: string, approval?: string}|null} mode
+ * @param {{name?: string, arguments?: unknown}} exec
+ * @param {string} cwd
+ * @returns {{kind:'deny'|'ask', reason:string}|null}
+ */
+export function modeDecision(mode, exec, cwd) {
+  if (!mode || mode.sandbox === "danger-full-access") return null;
+  const tool = String(exec?.name ?? "");
+  const args = exec?.arguments && typeof exec.arguments === "object" ? exec.arguments : {};
+  if (mode.sandbox === "read-only") {
+    if (MUTATING_TOOLS.has(tool)) {
+      return { kind: "deny", reason: `permission ${mode.name ?? "read-only"}: изменение файлов запрещено` };
+    }
+    if (SHELL_TOOLS.has(tool)) {
+      const command = typeof args.command === "string" ? args.command : "";
+      if (isMutatingShell(command)) return { kind: "deny", reason: `permission ${mode.name ?? "read-only"}: изменяющая shell-команда запрещена` };
+    }
+  }
+  if (mode.sandbox === "workspace-write") {
+    if (MUTATING_TOOLS.has(tool)) {
+      const paths = requestedPaths(tool, args);
+      const outside = paths.find((target) => !isInside(cwd, target));
+      if (outside) return { kind: "ask", reason: `permission ${mode.name ?? "workspace-write"}: запись вне рабочей папки — ${outside}` };
+    }
+  }
+  return null;
+}
+
+export function resolveMode(ctx, agent) {
+  try {
+    const service = ctx?.get?.("permissionPresets");
+    const session = agent?.session;
+    if (!service || !session) return null;
+    const name = service.current(session);
+    return { name, ...service.resolve(name) };
+  } catch {
+    return null;
+  }
+}