dsh-desktop-kit 2.2.1 → 2.7.3

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

@@ -0,0 +1,592 @@
+/**
+ * Guardrails policy: built-in defaults, JSON file merge, protected-path
+ * matching, shell-command rules and the process-level kill switch.
+ *
+ * The effective policy is a plain JSON object. A user file at
+ * `<DSH_HOME>/guardrails.json` is merged onto the defaults: objects merge
+ * recursively and entries in `rules` / `protectedPaths` merge by `id`, so a
+ * user can adjust one rule (`{"id":"git-reset-hard","enabled":false}`) or
+ * append a new one without restating the entire policy. Arrays elsewhere
+ * replace the default value.
+ *
+ * Node built-ins only; no I/O beyond reading the policy file.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Current policy document version. */
+export const POLICY_VERSION = 1;
+
+/** Environment variable that disables every hook (documented bypass). */
+export const KILL_SWITCH_ENV = "DSH_GUARDRAILS";
+
+/** Name of the user policy file inside the DSH home. */
+export const POLICY_FILE_NAME = "guardrails.json";
+
+/** Policy files larger than this are ignored (never loaded unbounded). */
+const MAX_POLICY_BYTES = 1024 * 1024;
+
+/** Commands longer than this are truncated before rule matching. */
+const MAX_COMMAND_CHARS = 16 * 1024;
+
+/** Scan limits, clamped by `normalizeLimits`. */
+export const DEFAULT_LIMITS = Object.freeze({
+  maxFiles: 800,
+  maxFileSizeBytes: 262_144,
+  maxTotalBytes: 8_388_608,
+  maxFindings: 200,
+  maxDepth: 12,
+  maxScriptBytes: 131_072,
+  gitTimeoutMs: 5_000,
+});
+
+/**
+ * Protected paths for filesystem mutation hooks and the scanner. `match` is
+ * `segment` (one path component), `basename` (last component) or `path` (the
+ * whole normalized path). Patterns are regular-expression sources; `except`
+ * patterns exempt a path that also matches.
+ */
+export const DEFAULT_PROTECTED_PATHS = [
+  {
+    id: "git-metadata",
+    description: "Git metadata directory (.git)",
+    match: "segment",
+    pattern: "^\\.git$",
+  },
+  {
+    id: "ssh-directory",
+    description: "SSH directory (.ssh)",
+    match: "segment",
+    pattern: "^\\.ssh$",
+  },
+  {
+    id: "env-file",
+    description: "dotenv file (.env and variants)",
+    match: "basename",
+    pattern: "^\\.env(?:\\..+)?$",
+    except: ["^\\.env\\.(?:example|sample|template|dist)$"],
+  },
+  {
+    id: "dsh-credentials",
+    description: "DSH credentials file (~/.dsh/.credentials.yaml)",
+    match: "path",
+    pattern: "(?:^|/)\\.dsh/\\.credentials\\.yaml$",
+  },
+  {
+    id: "private-key-name",
+    description: "SSH private key file names (id_rsa, id_ed25519, …)",
+    match: "basename",
+    pattern: "^(?:id_rsa|id_dsa|id_ecdsa|id_ed25519)$",
+  },
+  {
+    id: "private-key-ext",
+    description: "private key and keystore extensions (.pem, .key, .p12, .pfx, .jks)",
+    match: "basename",
+    pattern: "\\.(?:pem|key|p12|pfx|jks)$",
+  },
+];
+
+/**
+ * Shell-command rules. `severity` is `deny` (block) or `ask` (route through
+ * the approval seam; degrades to a denial when no approval channel exists).
+ */
+export const DEFAULT_COMMAND_RULES = [
+  {
+    id: "rm-rf-root",
+    severity: "deny",
+    description: "recursive force delete of a filesystem root or home directory",
+    pattern:
+      "\\brm\\b(?=[^\\n]*[ \\t]-[A-Za-z]*(?:r|R))(?=[^\\n]*[ \\t]-[A-Za-z]*(?:f|F))[^\\n]*[ \\t](?:/(?=\\s|$)|/\\*(?=\\s|$)|~(?=\\s|$)|(?:\\$HOME|%USERPROFILE%)(?=\\s|$)|[A-Za-z]:[\\\\/](?:\\*)?(?=\\s|$))",
+  },
+  {
+    id: "pwsh-remove-root",
+    severity: "deny",
+    description: "Windows recursive force delete of a filesystem root",
+    pattern:
+      "\\b(?:Remove-Item|del|erase|rmdir|rd)\\b(?=[^\\n]*(?:-[Rr]ecurse\\b|-r\\b|/s\\b))(?=[^\\n]*(?:-[Ff]orce\\b|-fo\\b|/q\\b))[^\\n]*[ \\t](?:[A-Za-z]:[\\\\/](?:\\*)?(?=\\s|$)|/(?=\\s|$))",
+  },
+  {
+    id: "drop-database",
+    severity: "deny",
+    description: "DROP DATABASE / DROP SCHEMA statement",
+    pattern: "\\bDROP\\s+(?:DATABASE|SCHEMA)\\b",
+  },
+  {
+    id: "disk-format",
+    severity: "deny",
+    description: "disk format or raw device wipe (mkfs, dd of=/dev/*, format C:, diskpart)",
+    pattern:
+      "\\b(?:mkfs(?:\\.[a-z0-9]+)?|wipefs|diskpart)\\b|\\bdd\\b[^\\n]*\\bof\\s*=\\s*/dev/|\\bshred\\b[^\\n]*/dev/|\\bformat\\s+[A-Za-z]:|\\b(?:Format-Volume|Clear-Disk|Initialize-Disk)\\b|(?:^|[;&|]\\s*)format(?=\\s|$)",
+  },
+  {
+    id: "shell-overwrite-credentials",
+    severity: "deny",
+    description: "shell overwrite, truncation or removal of credentials or private keys",
+    pattern:
+      "(?:>{1,2}\\s*[\"']?[^\\s\"'|;&]*(?:\\.credentials(?:\\.yaml)?\\b|id_rsa\\b|id_ed25519\\b|id_ecdsa\\b|\\.pem\\b|\\.p12\\b|\\.pfx\\b|\\.ssh[\\\\/]))|(?:\\b(?:Set-Content|Add-Content|Out-File|New-Item|Remove-Item|rm|del|erase|truncate|shred|tee)\\b[^\\n]{0,200}?[ \\t\"'](?:[^\\s\"'|;&]*)(?:\\.credentials(?:\\.yaml)?\\b|id_rsa\\b|id_ed25519\\b|id_ecdsa\\b|\\.pem\\b|\\.p12\\b|\\.pfx\\b|\\.ssh[\\\\/]))",
+  },
+  {
+    id: "shell-copy-credentials",
+    severity: "ask",
+    description: "shell copy or move of credentials or private keys",
+    pattern:
+      "\\b(?:cp|copy|mv|move|scp|rsync)\\b[^\\n]{0,200}?[ \\t\"'](?:[^\\s\"'|;&]*)(?:\\.credentials(?:\\.yaml)?\\b|id_rsa\\b|id_ed25519\\b|id_ecdsa\\b|\\.pem\\b|\\.p12\\b|\\.pfx\\b|\\.ssh[\\\\/])",
+  },
+  {
+    id: "git-push-force",
+    severity: "ask",
+    description: "git push with --force (force-with-lease is allowed)",
+    pattern: "\\bgit\\s+push\\b[^\\n]*(?:--force(?!-with-lease)\\b|\\s-f(?=\\s|$))",
+  },
+  {
+    id: "git-reset-hard",
+    severity: "ask",
+    description: "git reset --hard discards uncommitted work",
+    pattern: "\\bgit\\s+reset\\s+--hard\\b",
+  },
+  {
+    id: "truncate-table",
+    severity: "ask",
+    description: "SQL TRUNCATE statement",
+    pattern: "\\bTRUNCATE\\s+(?:TABLE\\s+)?[A-Za-z0-9_\"`\\[\\].]+",
+  },
+  {
+    id: "shell-write-dotenv",
+    severity: "ask",
+    description: "shell write or removal of a dotenv file",
+    pattern:
+      "(?:>{1,2}\\s*[\"']?[^\\s\"'|;&]*\\.env\\b)|(?:\\b(?:Set-Content|Add-Content|Out-File|New-Item|Remove-Item|rm|del|erase|copy|cp|move|mv|tee|truncate)\\b[^\\n]{0,200}?[ \\t\"'](?:[^\\s\"'|;&]*)\\.env\\b)",
+    except: ["\\.env\\.(?:example|sample|template|dist)\\b"],
+  },
+  {
+    id: "sed-inplace-protected",
+    severity: "ask",
+    description: "in-place sed/perl edit of a dotenv or credential file",
+    pattern:
+      "\\b(?:sed\\b[^\\n]*(?:-i\\b|--in-place)|perl\\b[^\\n]*(?:-i\\b|-pi\\b))[^\\n]*(?:\\.env\\b|\\.credentials|\\.ssh[\\\\/]|id_rsa\\b|\\.pem\\b)",
+    except: ["\\.env\\.(?:example|sample|template|dist)\\b"],
+  },
+];
+
+/* ------------------------------------------------------------------ */
+/* Filesystem-independent helpers                                     */
+/* ------------------------------------------------------------------ */
+
+export function homeDirectory(env = process.env) {
+  const home = env?.USERPROFILE || env?.HOME;
+  return typeof home === "string" && home.trim().length > 0 ? home.trim() : os.homedir();
+}
+
+/** Root of local DSH state; honours `DSH_HOME` like the rest of the kit. */
+export function dshHome(env = process.env) {
+  const configured = env?.DSH_HOME;
+  return typeof configured === "string" && configured.trim().length > 0
+    ? configured.trim()
+    : path.join(homeDirectory(env), ".dsh");
+}
+
+/** Absolute path of the user policy file. */
+export function policyPath(env = process.env) {
+  return path.join(dshHome(env), POLICY_FILE_NAME);
+}
+
+/**
+ * The documented process-level bypass. Accepts `off`, `0`, `false` and
+ * `disabled` (case-insensitive) so a launcher script cannot accidentally
+ * half-disable the plugin.
+ */
+export function killSwitchActive(env = process.env) {
+  const raw = String(env?.[KILL_SWITCH_ENV] ?? "").trim().toLowerCase();
+  return raw === "off" || raw === "0" || raw === "false" || raw === "disabled";
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function clone(value) {
+  return value === undefined ? undefined : structuredClone(value);
+}
+
+/** Normalize a path for matching: forward slashes, expanded `~`, lower case on Windows. */
+export function normalizePathForMatch(value, env = process.env) {
+  let text = String(value ?? "").trim();
+  if (text.length === 0) return "";
+  text = text.replaceAll("\\", "/");
+  const home = homeDirectory(env).replaceAll("\\", "/").replace(/\/+$/u, "");
+  if (text === "~") text = home;
+  else if (text.startsWith("~/")) text = `${home}/${text.slice(2)}`;
+  text = text.replace(/\/{2,}/gu, "/");
+  if (process.platform === "win32") text = text.toLowerCase();
+  return text;
+}
+
+function basenameOf(normalizedPath) {
+  const parts = normalizedPath.split("/").filter((part) => part.length > 0);
+  return parts.length > 0 ? parts.at(-1) : "";
+}
+
+function segmentsOf(normalizedPath) {
+  return normalizedPath.split("/").filter((part) => part.length > 0);
+}
+
+/** Only stateless, case-insensitive regexes are supported for policy patterns. */
+function normalizeFlags(value) {
+  const flags = new Set(["i"]);
+  for (const flag of typeof value === "string" ? value : "") {
+    if ("imsu".includes(flag)) flags.add(flag);
+  }
+  return [...flags].join("");
+}
+
+const regexCache = new Map();
+
+function compileCached(source, flags) {
+  const key = `${source}\u0000${flags}`;
+  const cached = regexCache.get(key);
+  if (cached !== undefined) return cached;
+  let regex;
+  try {
+    regex = new RegExp(source, flags);
+  } catch {
+    regex = null;
+  }
+  if (regexCache.size > 500) regexCache.clear();
+  regexCache.set(key, regex);
+  return regex;
+}
+
+function ruleRegex(rule) {
+  return compileCached(rule.pattern, normalizeFlags(rule.flags));
+}
+
+function excludes(exclusions, text, flags) {
+  for (const source of exclusions ?? []) {
+    const regex = compileCached(source, normalizeFlags(flags));
+    if (regex !== null && regex.test(text)) return true;
+  }
+  return false;
+}
+
+/* ------------------------------------------------------------------ */
+/* Policy assembly                                                     */
+/* ------------------------------------------------------------------ */
+
+/** Built-in policy document. Callers receive a fresh clone. */
+export function defaultPolicy() {
+  return {
+    version: POLICY_VERSION,
+    enabled: true,
+    askBehavior: "ask",
+    limits: { ...DEFAULT_LIMITS },
+    hooks: { toolsPreExecute: true, fsIntents: true },
+    protectedPaths: clone(DEFAULT_PROTECTED_PATHS),
+    rules: clone(DEFAULT_COMMAND_RULES),
+  };
+}
+
+/** Merge entry arrays by `id`, keeping unmatched defaults and appending new ids. */
+function mergeEntries(baseEntries, overrideEntries) {
+  const result = Array.isArray(baseEntries) ? clone(baseEntries) : [];
+  if (!Array.isArray(overrideEntries)) return result;
+  for (const entry of overrideEntries) {
+    if (!isPlainObject(entry) || typeof entry.id !== "string" || entry.id.trim().length === 0) continue;
+    const id = entry.id.trim();
+    const index = result.findIndex((item) => isPlainObject(item) && item.id === id);
+    if (index >= 0) result[index] = { ...result[index], ...clone(entry), id };
+    else result.push({ ...clone(entry), id });
+  }
+  return result;
+}
+
+/** Deep-merge a user policy onto a base policy; `rules`/`protectedPaths` merge by id. */
+export function mergePolicy(base, override) {
+  const result = clone(base);
+  if (!isPlainObject(override)) return result;
+  for (const [key, value] of Object.entries(override)) {
+    if (key === "rules" || key === "protectedPaths") {
+      result[key] = mergeEntries(result[key], value);
+      continue;
+    }
+    if (isPlainObject(value)) result[key] = isPlainObject(result[key]) ? mergePolicy(result[key], value) : clone(value);
+    else result[key] = clone(value);
+  }
+  return result;
+}
+
+function integerWithin(value, fallback, minimum, maximum) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || !Number.isInteger(number)) return fallback;
+  return Math.min(maximum, Math.max(minimum, number));
+}
+
+function normalizeLimits(raw, warnings) {
+  if (raw !== undefined && !isPlainObject(raw)) warnings.push("limits: expected an object, using defaults");
+  const source = isPlainObject(raw) ? raw : {};
+  return {
+    maxFiles: integerWithin(source.maxFiles, DEFAULT_LIMITS.maxFiles, 1, 5_000),
+    maxFileSizeBytes: integerWithin(source.maxFileSizeBytes, DEFAULT_LIMITS.maxFileSizeBytes, 256, 16_777_216),
+    maxTotalBytes: integerWithin(source.maxTotalBytes, DEFAULT_LIMITS.maxTotalBytes, 1_024, 67_108_864),
+    maxFindings: integerWithin(source.maxFindings, DEFAULT_LIMITS.maxFindings, 1, 2_000),
+    maxDepth: integerWithin(source.maxDepth, DEFAULT_LIMITS.maxDepth, 1, 64),
+    maxScriptBytes: integerWithin(source.maxScriptBytes, DEFAULT_LIMITS.maxScriptBytes, 1_024, 2_097_152),
+    gitTimeoutMs: integerWithin(source.gitTimeoutMs, DEFAULT_LIMITS.gitTimeoutMs, 500, 60_000),
+  };
+}
+
+function normalizeHooks(raw, warnings) {
+  if (raw !== undefined && !isPlainObject(raw)) warnings.push("hooks: expected an object, using defaults");
+  const source = isPlainObject(raw) ? raw : {};
+  return {
+    toolsPreExecute: source.toolsPreExecute !== false,
+    fsIntents: source.fsIntents !== false,
+  };
+}
+
+function normalizeProtectedPaths(entries, warnings) {
+  const result = [];
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    if (!isPlainObject(entry)) {
+      warnings.push("protectedPaths: ignoring a non-object entry");
+      continue;
+    }
+    const id = typeof entry.id === "string" ? entry.id.trim() : "";
+    if (id.length === 0) {
+      warnings.push("protectedPaths: ignoring an entry without id");
+      continue;
+    }
+    const match = ["segment", "basename", "path"].includes(entry.match) ? entry.match : null;
+    if (match === null) {
+      warnings.push(`protectedPaths[${id}]: match must be segment, basename or path`);
+      continue;
+    }
+    const pattern = typeof entry.pattern === "string" ? entry.pattern : "";
+    const flags = normalizeFlags(entry.flags);
+    if (pattern.length === 0 || compileCached(pattern, flags) === null) {
+      warnings.push(`protectedPaths[${id}]: invalid pattern, rule disabled`);
+      continue;
+    }
+    const except = Array.isArray(entry.except) ? entry.except.filter((value) => typeof value === "string") : [];
+    for (const source of except) {
+      if (compileCached(source, flags) === null) warnings.push(`protectedPaths[${id}]: invalid except pattern ignored`);
+    }
+    result.push({
+      id,
+      description: typeof entry.description === "string" && entry.description.length > 0 ? entry.description : id,
+      match,
+      pattern,
+      flags,
+      except,
+      enabled: entry.enabled !== false,
+    });
+  }
+  return result;
+}
+
+function normalizeCommandRules(entries, warnings) {
+  const result = [];
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    if (!isPlainObject(entry)) {
+      warnings.push("rules: ignoring a non-object entry");
+      continue;
+    }
+    const id = typeof entry.id === "string" ? entry.id.trim() : "";
+    if (id.length === 0) {
+      warnings.push("rules: ignoring a rule without id");
+      continue;
+    }
+    const pattern = typeof entry.pattern === "string" ? entry.pattern : "";
+    const flags = normalizeFlags(entry.flags);
+    if (pattern.length === 0 || compileCached(pattern, flags) === null) {
+      warnings.push(`rules[${id}]: invalid pattern, rule disabled`);
+      continue;
+    }
+    const severity = entry.severity === "ask" ? "ask" : entry.severity === "deny" ? "deny" : "deny";
+    if (entry.severity !== "ask" && entry.severity !== "deny") {
+      warnings.push(`rules[${id}]: severity must be ask or deny; defaulting to deny`);
+    }
+    const except = Array.isArray(entry.except) ? entry.except.filter((value) => typeof value === "string") : [];
+    result.push({
+      id,
+      severity,
+      description: typeof entry.description === "string" && entry.description.length > 0 ? entry.description : id,
+      pattern,
+      flags,
+      except,
+      enabled: entry.enabled !== false,
+    });
+  }
+  return result;
+}
+
+/**
+ * Validate and clamp a raw policy document. Never throws: malformed entries are
+ * skipped with a warning and the defaults stay in force.
+ *
+ * @param {unknown} candidate - user policy document.
+ * @param {string[]} [warnings] - collector for non-fatal problems.
+ * @returns {object} effective policy.
+ */
+export function normalizePolicy(candidate, warnings = []) {
+  if (candidate !== undefined && candidate !== null && !isPlainObject(candidate)) {
+    warnings.push("policy: expected a JSON object, using defaults");
+    return normalizePolicy(undefined, warnings);
+  }
+  if (isPlainObject(candidate) && candidate.version !== undefined && candidate.version !== POLICY_VERSION) {
+    warnings.push(`policy: version ${JSON.stringify(candidate.version)} is not ${POLICY_VERSION}; merged anyway`);
+  }
+  const merged = mergePolicy(defaultPolicy(), candidate);
+  return {
+    version: POLICY_VERSION,
+    enabled: merged.enabled !== false,
+    askBehavior: merged.askBehavior === "deny" ? "deny" : "ask",
+    limits: normalizeLimits(merged.limits, warnings),
+    hooks: normalizeHooks(merged.hooks, warnings),
+    protectedPaths: normalizeProtectedPaths(merged.protectedPaths, warnings),
+    rules: normalizeCommandRules(merged.rules, warnings),
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Loading                                                             */
+/* ------------------------------------------------------------------ */
+
+const policyCache = new Map();
+
+function readPolicyFile(filePath) {
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    stat = null;
+  }
+  const signature = stat === null ? "missing" : `${stat.mtimeMs}:${stat.size}:${stat.ino}`;
+  const cached = policyCache.get(filePath);
+  if (cached !== undefined && cached.signature === signature) return cached.value;
+  let value;
+  if (stat === null) {
+    value = { exists: false, loadedFromFile: false, error: null, warnings: [], policy: normalizePolicy(undefined) };
+  } else if (stat.size > MAX_POLICY_BYTES) {
+    value = {
+      exists: true,
+      loadedFromFile: false,
+      error: `policy file is larger than ${MAX_POLICY_BYTES} bytes; defaults are in force`,
+      warnings: [],
+      policy: normalizePolicy(undefined),
+    };
+  } else {
+    const warnings = [];
+    try {
+      const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      if (!isPlainObject(parsed)) throw new Error("policy file must contain a JSON object");
+      value = { exists: true, loadedFromFile: true, error: null, warnings, policy: normalizePolicy(parsed, warnings) };
+    } catch (error) {
+      value = {
+        exists: true,
+        loadedFromFile: false,
+        error: error instanceof Error ? error.message : String(error),
+        warnings: [],
+        policy: normalizePolicy(undefined),
+      };
+    }
+  }
+  if (policyCache.size > 20) policyCache.delete(policyCache.keys().next().value);
+  policyCache.set(filePath, { signature, value });
+  return value;
+}
+
+/**
+ * Load the effective policy. Parse results are cached by file mtime/size; the
+ * kill switch is evaluated on every call so an environment change needs no
+ * reload.
+ *
+ * @param {{env?: Record<string, string|undefined>, filePath?: string}} [options] - environment and file override.
+ * @returns {{path: string, exists: boolean, loadedFromFile: boolean, error: string|null, warnings: string[], policy: object, killSwitch: boolean, enabled: boolean}} loaded state.
+ */
+export function loadPolicy(options = {}) {
+  const env = options.env ?? process.env;
+  const filePath = options.filePath ?? policyPath(env);
+  const base = readPolicyFile(filePath);
+  const killSwitch = killSwitchActive(env);
+  return {
+    path: filePath,
+    exists: base.exists,
+    loadedFromFile: base.loadedFromFile,
+    error: base.error,
+    warnings: base.warnings,
+    policy: base.policy,
+    killSwitch,
+    enabled: base.policy.enabled === true && !killSwitch,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Matching                                                            */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Find the protected-path entry matching a resolved display path.
+ *
+ * @param {string} displayPath - resolved or user-supplied path.
+ * @param {{policy: object, env?: Record<string, string|undefined>}} options - effective policy and environment.
+ * @returns {{id: string, description: string, match: string} | undefined} matching entry.
+ */
+export function matchProtectedPath(displayPath, options) {
+  const policy = options?.policy;
+  const env = options?.env ?? process.env;
+  const normalized = normalizePathForMatch(displayPath, env);
+  if (normalized.length === 0 || !policy || !Array.isArray(policy.protectedPaths)) return undefined;
+  for (const entry of policy.protectedPaths) {
+    if (entry.enabled === false) continue;
+    const regex = ruleRegex(entry);
+    if (regex === null) continue;
+    const candidates =
+      entry.match === "basename"
+        ? [basenameOf(normalized)]
+        : entry.match === "segment"
+          ? segmentsOf(normalized)
+          : [normalized];
+    if (!candidates.some((candidate) => regex.test(candidate))) continue;
+    if (excludes(entry.except, normalized, entry.flags)) continue;
+    return { id: entry.id, description: entry.description, match: entry.match };
+  }
+  return undefined;
+}
+
+/**
+ * Evaluate a shell command against the policy rules.
+ *
+ * @param {unknown} command - raw command text.
+ * @param {{policy: object}} options - effective policy.
+ * @returns {{action: "allow"|"ask"|"deny", hits: {id: string, severity: string, description: string}[], primary: object|null, truncated: boolean}} verdict.
+ */
+export function evaluateCommand(command, options) {
+  const policy = options?.policy;
+  const raw = String(command ?? "");
+  const truncated = raw.length > MAX_COMMAND_CHARS;
+  const text = truncated ? raw.slice(0, MAX_COMMAND_CHARS) : raw;
+  const hits = [];
+  if (!policy || !Array.isArray(policy.rules) || text.trim().length === 0) {
+    return { action: "allow", hits, primary: null, truncated };
+  }
+  for (const rule of policy.rules) {
+    if (rule.enabled === false) continue;
+    const regex = ruleRegex(rule);
+    if (regex === null || !regex.test(text)) continue;
+    if (excludes(rule.except, text, rule.flags)) continue;
+    hits.push({ id: rule.id, severity: rule.severity, description: rule.description });
+  }
+  const deny = hits.find((hit) => hit.severity === "deny");
+  if (deny !== undefined) return { action: "deny", hits, primary: deny, truncated };
+  if (hits.length > 0) {
+    const askBehavior = policy.askBehavior === "deny" ? "deny" : "ask";
+    return { action: askBehavior, hits, primary: hits[0], truncated };
+  }
+  return { action: "allow", hits, primary: null, truncated };
+}
+
+/** Absolute path of the DSH credentials file, for status output. */
+export function credentialsPath(env = process.env) {
+  return path.join(dshHome(env), ".credentials.yaml");
+}