@goodandready/dsh-approval-gate 0.1.4 → 0.1.6

package/lib/messages.js

@@ -91,4 +91,144 @@ export const MESSAGES = Object.freeze({
     ruleNestedShell: "嵌套 shell 超出检查深度",
     ruleInterpreterPayload: "不安全的解释器代码",
   },
+  ru: {
+    blockedPrefix: "Заблокировано правилом dsh-approval-gate",
+    detectedLabel: "Обнаружено",
+    commandLabel: "Команда",
+    parseReasonLabel: "Причина синтаксического анализа",
+    detailProcessSubstitution: "процессная подстановка требует подтверждения",
+    detailUnclosedProcessSubstitution: "незакрытая процессная подстановка",
+    detailUnclosedCommandSubstitution: "незакрытая подстановка команды",
+    detailUnclosedBacktick: "незакрытая подстановка команды в обратных кавычках",
+    detailUnclosedParameterExpansion: "незакрытое расширение параметров",
+    detailUnclosedSingleQuote: "незакрытая одинарная кавычка",
+    detailUnclosedDoubleQuote: "незакрытая двойная кавычка",
+    detailDanglingEscape: "незавершённое экранирование",
+    detailInvalidHeredoc: "неверный разделитель here-document",
+    detailUnterminatedHeredoc: "завершитель here-document не найден",
+    detailUnsupportedGrouping: "группировка шелла не поддерживается анализатором",
+    detailUnsupported: "неподдерживаемый синтаксис шелла",
+    approvalRequired: "Требуется подтверждение",
+    askUnknown: "Команда не может быть проверена полностью; проверьте её перед подтверждением",
+    askUnparseable: "Синтаксис шелла не может быть проверен полностью; проверьте его перед подтверждением",
+    askUnknownFormat: "Формат вызова инструмента не может быть проверен; проверьте его перед подтверждением",
+    askUnknownWriteTarget: "Целевой файл для записи не определён; проверьте его перед подтверждением",
+    askDynamicCommand: "Развёрнутое имя команды не может быть проверено; проверьте его перед подтверждением",
+    askDynamicArguments: "Развёрнутые аргументы чувствительной команды не могут быть проверены; проверьте их перед подтверждением",
+    askDynamicRedirect: "Развёрнутая цель перенаправления не может быть проверена; проверьте её перед подтверждением",
+    askScriptFile: "Содержимое файла скрипта недоступно для гейта; проверьте его перед подтверждением",
+    askShellStdin: "Ввод шелла недоступен для гейта в полном объёме; проверьте его перед подтверждением",
+    askInterpreterPayload: "Побочные эффекты интерпретатора не могут быть полностью проанализированы; проверьте их перед подтверждением",
+    askCredentialInArgv: "Развёрнутые учётные данные передаются как аргументы процесса; используйте безопасный API или проверьте перед подтверждением",
+    ruleUnknown: "Сработало защитное правило блокировки",
+    ruleRecursiveRm: "Рекурсивное удаление файлов",
+    ruleProcessSignal: "Завершение процесса",
+    ruleServiceControl: "Изменение состояния службы",
+    ruleGitClean: "Разрушительный git clean",
+    ruleGitResetHard: "Разрушительный git reset --hard",
+    ruleFindDelete: "find -delete",
+    ruleDestructiveSql: "Разрушительный SQL",
+    ruleSecretWrite: "Запись в защищённый файл с секретами",
+    ruleDeviceWrite: "Запись в системное устройство или защищённый файл",
+    ruleMkfsDevice: "Форматирование файловой системы",
+    ruleCurlPipe: "Передача скачанного содержимого в шелл",
+    ruleEval: "Динамическое выполнение шелла (eval)",
+    ruleNestedShell: "Превышен лимит вложенности шелла",
+    ruleInterpreterPayload: "Небезопасный исполняемый код интерпретатора",
+  },
+});
+
+export function sessionTag(execution) {
+  const agent = execution && execution.agent;
+  if (typeof agent === "string") return " (session " + agent + ")";
+  if (agent && agent.session) return " (session " + String(agent.session) + ")";
+  return "";
+}
+
+function safeSnippet(value) {
+  return String(value || "")
+    .replace(/[\r\n\t\u0000-\u001f]+/g, " ")
+    .replace(/(authorization\s*:\s*(?:bearer|token)\s+)\S+/gi, "$1[redacted]")
+    .replace(/((?:password|passwd|secret|token|api[_-]?key)\s*[:=]\s*)[^\s,;]+/gi, "$1[redacted]")
+    .slice(0, 120);
+}
+
+function translated(translate, key, logger) {
+  if (typeof translate === "function") {
+    try {
+      const value = translate(key);
+      if (value && value !== key) return value;
+    } catch {
+      if (logger && typeof logger.warn === "function") {
+        logger.warn("[dsh-approval-gate] localization lookup failed; using English fallback");
+      }
+    }
+  }
+  return MESSAGES.en[key] || key;
+}
+
+const RULE_KEYS = Object.freeze({
+  "recursive-rm": "ruleRecursiveRm",
+  "process-signal": "ruleProcessSignal",
+  "service-control": "ruleServiceControl",
+  "git-clean": "ruleGitClean",
+  "git-reset-hard": "ruleGitResetHard",
+  "find-delete": "ruleFindDelete",
+  "destructive-sql": "ruleDestructiveSql",
+  "secret-write": "ruleSecretWrite",
+  "device-write": "ruleDeviceWrite",
+  "mkfs-device": "ruleMkfsDevice",
+  "curl-pipe": "ruleCurlPipe",
+  "eval": "ruleEval",
+  "nested-shell": "ruleNestedShell",
+  "interpreter-payload": "ruleInterpreterPayload",
 });
+
+const ASK_KEYS = Object.freeze({
+  unparseable: "askUnparseable",
+  "unknown-format": "askUnknownFormat",
+  "unknown-write-target": "askUnknownWriteTarget",
+  "dynamic-command": "askDynamicCommand",
+  "dynamic-arguments": "askDynamicArguments",
+  "dynamic-redirect": "askDynamicRedirect",
+  "script-file": "askScriptFile",
+  "shell-stdin": "askShellStdin",
+  "interpreter-payload": "askInterpreterPayload",
+  "credential-in-argv": "askCredentialInArgv",
+});
+
+const DETAIL_KEYS = Object.freeze({
+  "process-substitution": "detailProcessSubstitution",
+  "unclosed-process-substitution": "detailUnclosedProcessSubstitution",
+  "unclosed-command-substitution": "detailUnclosedCommandSubstitution",
+  "unclosed-backtick-substitution": "detailUnclosedBacktick",
+  "unclosed-parameter-expansion": "detailUnclosedParameterExpansion",
+  "unclosed-single-quote": "detailUnclosedSingleQuote",
+  "unclosed-double-quote": "detailUnclosedDoubleQuote",
+  "dangling-backslash": "detailDanglingEscape",
+  "invalid-heredoc-delimiter": "detailInvalidHeredoc",
+  "unterminated-heredoc": "detailUnterminatedHeredoc",
+  "unsupported-shell-grouping": "detailUnsupportedGrouping",
+});
+
+export function denyMessage(hit, who, translate, logger) {
+  const key = RULE_KEYS[hit && hit.reason] || "ruleUnknown";
+  const snippet = safeSnippet(hit && hit.snippet);
+  const parts = [translated(translate, "blockedPrefix", logger), translated(translate, key, logger)];
+  if (snippet) parts.push(translated(translate, "detectedLabel", logger) + ": " + snippet);
+  if (who) parts.push(who.trim());
+  return parts.join(" — ") + ".";
+}
+
+export function askMessage(hit, who, translate, logger) {
+  const key = ASK_KEYS[hit && hit.reason] || "askUnknown";
+  const snippet = safeSnippet(hit && hit.snippet);
+  const parts = [translated(translate, "approvalRequired", logger), translated(translate, key, logger)];
+  if (hit && hit.reason === "unparseable") {
+    const detailKey = DETAIL_KEYS[hit.detail] || "detailUnsupported";
+    parts.push(translated(translate, "parseReasonLabel", logger) + ": " + translated(translate, detailKey, logger));
+  }
+  if (snippet) parts.push(translated(translate, "commandLabel", logger) + ": " + snippet);
+  if (who) parts.push(who.trim());
+  return parts.join(" — ") + ".";
+}

package/lib/paths.js

@@ -0,0 +1,25 @@
+// lib/paths.js
+// Home path expansion and path boundary helpers for dsh-approval-gate.
+
+/**
+ * Expand `~`, `${HOME}`, `$HOME`, and `%USERPROFILE%` at the start of or within a path.
+ *
+ * @param {string} p - Path or string containing path references
+ * @param {Record<string, string|undefined>} [env] - Environment dictionary (defaults to process.env)
+ * @returns {string} Normalized path with home expanded
+ */
+export function expandHome(p, env = process.env) {
+  if (typeof p !== "string" || p.trim() === "") return p;
+  const home = (env && (env.HOME || env.USERPROFILE)) || "";
+  if (!home) return p;
+  const cleanHome = home.replace(/[/\\]+$/, "");
+
+  let res = p;
+  // Expand leading ~ or ~/ or ~\
+  res = res.replace(/^~(?=$|[/\\])/, cleanHome);
+  // Expand ${HOME} and $HOME
+  res = res.replace(/\$\{HOME\}|\$HOME/g, cleanHome);
+  // Expand %USERPROFILE% (Windows)
+  res = res.replace(/%USERPROFILE%/gi, cleanHome);
+  return res;
+}

package/lib/tokenizer.js

@@ -0,0 +1,380 @@
+// Pure bash lexer and tokenizer for dsh-approval-gate.
+
+export const SPLIT_OPS = new Set(["|", "|&", "||", "&&", ";", "&"]);
+export const REDIR_OPS = new Set([">", ">>", ">|", "<>", "2>", "2>>", "&>", "&>>"]);
+export const HEREDOC_OPS = new Set(["<<", "<<-"]);
+export const DYNAMIC_MARKER = "__shell_dynamic__";
+
+function opAt(s, i) {
+  const rest = s.slice(i);
+  if (rest.startsWith("<(") || rest.startsWith(">(")) return null;
+  const candidates = ["2>&", "2>>", "&>>", "<<<", "<<-", "2>", ">>", ">|", "|&", "&&", "||", "&>", ">&", "<&", "<>", "<<", ">", "<", "|", ";", "&"];
+  for (const op of candidates) {
+    if (rest.startsWith(op)) return op;
+  }
+  return null;
+}
+
+export function readCommandSubstitution(src, start) {
+  let depth = 1;
+  let quote = "";
+  let escaped = false;
+  for (let i = start + 2; i < src.length; i += 1) {
+    const c = src[i];
+    if (escaped) { escaped = false; continue; }
+    if (c === "\\") { escaped = true; continue; }
+    if (quote) {
+      if (c === quote) quote = "";
+      continue;
+    }
+    if (c === "'" || c === '"') { quote = c; continue; }
+    if (c === String.fromCharCode(96)) {
+      const end = readBacktick(src, i);
+      if (!end) return null;
+      i = end.end;
+      continue;
+    }
+    if (src.startsWith("$(", i)) { depth += 1; i += 1; continue; }
+    if (c === "(") { depth += 1; continue; }
+    if (c === ")") {
+      depth -= 1;
+      if (depth === 0) return { script: src.slice(start + 2, i), end: i + 1 };
+    }
+  }
+  return null;
+}
+
+export function readBacktick(src, start) {
+  let escaped = false;
+  for (let i = start + 1; i < src.length; i += 1) {
+    if (escaped) { escaped = false; continue; }
+    if (src[i] === "\\") { escaped = true; continue; }
+    if (src[i] === String.fromCharCode(96)) return { script: src.slice(start + 1, i), end: i + 1 };
+  }
+  return null;
+}
+
+export function readParameterExpansion(src, start) {
+  if (src[start + 1] !== "{") {
+    let i = start + 1;
+    if (/[A-Za-z_]/.test(src[i] || "")) {
+      i += 1;
+      while (i < src.length && /[A-Za-z0-9_]/.test(src[i])) i += 1;
+    } else if (i < src.length) i += 1;
+    return { end: i };
+  }
+  let depth = 1;
+  let quote = "";
+  for (let i = start + 2; i < src.length; i += 1) {
+    const c = src[i];
+    if (c === "\\") { i += 1; continue; }
+    if (quote) {
+      if (c === quote) quote = "";
+      continue;
+    }
+    if (c === "'" || c === '"') { quote = c; continue; }
+    if (c === String.fromCharCode(96)) {
+      const nested = readBacktick(src, i);
+      if (!nested) return null;
+      i = nested.end - 1;
+      continue;
+    }
+    if (src.startsWith("$" + "(", i)) {
+      const nested = readCommandSubstitution(src, i);
+      if (!nested) return null;
+      i = nested.end - 1;
+      continue;
+    }
+    if (src.startsWith("$" + "{", i)) {
+      const nested = readParameterExpansion(src, i);
+      if (!nested) return null;
+      i = nested.end - 1;
+      continue;
+    }
+    if (c === "{") depth += 1;
+    if (c === "}") {
+      depth -= 1;
+      if (depth === 0) return { end: i + 1, body: src.slice(start + 2, i) };
+    }
+  }
+  return null;
+}
+
+function lexFail(src, index, reason, tokens) {
+  return { ok: false, reason: reason, snippet: src.slice(Math.max(0, index - 32), index + 96), tokens: tokens };
+}
+
+function readHeredocDelimiter(src, index) {
+  let i = index;
+  while (i < src.length && (src[i] === " " || src[i] === "\t")) i += 1;
+  if (i >= src.length || src[i] === "\n" || src[i] === "\r") return null;
+  let delimiter = "";
+  let quote = "";
+  let started = false;
+  let quoted = false;
+  while (i < src.length && !/\s/.test(src[i]) && !opAt(src, i)) {
+    const c = src[i];
+    if (c === "'" || c === '"') {
+      if (!quote) { quote = c; quoted = true; started = true; i += 1; continue; }
+      if (quote === c) { quote = ""; i += 1; continue; }
+    }
+    if (c === "\\") {
+      if (i + 1 >= src.length) return null;
+      quoted = true;
+      delimiter += src[i + 1];
+      started = true;
+      i += 2;
+      continue;
+    }
+    delimiter += c;
+    started = true;
+    i += 1;
+  }
+  if (quote || !started || !delimiter) return null;
+  return { delimiter: delimiter, end: i, quoted: quoted };
+}
+
+export function tokenize(src) {
+  if (typeof src !== "string") return { ok: false, reason: "not-a-string", snippet: "", tokens: [] };
+  const tokens = [];
+  const pendingHeredocs = [];
+  let i = 0;
+  const n = src.length;
+
+  function flushWord(value, started, dynamic, substitutions) {
+    if (started) tokens.push({ kind: "word", value: value, dynamic: dynamic, substitutions: substitutions });
+  }
+
+  while (i < n) {
+    if (src.startsWith("\\\n", i)) { i += 2; continue; }
+    if (src[i] === "\r" || src[i] === "\n") {
+      if (src[i] === "\r" && src[i + 1] === "\n") i += 2;
+      else i += 1;
+      if (pendingHeredocs.length) {
+        for (const heredoc of pendingHeredocs) {
+          let body = "";
+          let found = false;
+          while (i <= n) {
+            const lineEnd = src.indexOf("\n", i);
+            const hasNewline = lineEnd !== -1;
+            let line = src.slice(i, hasNewline ? lineEnd : n);
+            if (line.endsWith("\r")) line = line.slice(0, -1);
+            const compare = heredoc.stripTabs ? line.replace(/^\t+/, "") : line;
+            if (compare === heredoc.delimiter) {
+              i = hasNewline ? lineEnd + 1 : n;
+              found = true;
+              break;
+            }
+            body += (heredoc.stripTabs ? line.replace(/^\t+/, "") : line) + (hasNewline ? "\n" : "");
+            if (!hasNewline) { i = n; break; }
+            i = lineEnd + 1;
+          }
+          if (!found) return lexFail(src, i, "unterminated-heredoc", tokens);
+          tokens.push({ kind: "heredoc", body: body, quoted: heredoc.quoted });
+        }
+        pendingHeredocs.length = 0;
+        tokens.push({ kind: "op", value: ";" });
+      } else {
+        tokens.push({ kind: "op", value: ";" });
+      }
+      continue;
+    }
+    if (/\s/.test(src[i])) { i += 1; continue; }
+    if (src[i] === "#" && (tokens.length === 0 || tokens[tokens.length - 1].kind === "op")) {
+      while (i < n && src[i] !== "\n") i += 1;
+      continue;
+    }
+
+    const op = opAt(src, i);
+    if (op) {
+      tokens.push({ kind: "op", value: op });
+      i += op.length;
+      if (HEREDOC_OPS.has(op)) {
+        const parsed = readHeredocDelimiter(src, i);
+        if (!parsed) return lexFail(src, i, "invalid-heredoc-delimiter", tokens);
+        tokens.push({ kind: "heredoc-delimiter", value: parsed.delimiter });
+        pendingHeredocs.push({ delimiter: parsed.delimiter, stripTabs: op === "<<-", quoted: parsed.quoted });
+        i = parsed.end;
+      }
+      continue;
+    }
+
+    let word = "";
+    let started = false;
+    let dynamic = false;
+    const substitutions = [];
+    while (i < n && !/\s/.test(src[i]) && !opAt(src, i)) {
+      const c = src[i];
+      if (src.startsWith("<(", i) || src.startsWith(">(", i)) {
+        const sub = readCommandSubstitution(src, i);
+        if (!sub) return lexFail(src, i, "unclosed-process-substitution", tokens);
+        substitutions.push({ kind: "process-substitution", script: sub.script });
+        word += DYNAMIC_MARKER;
+        dynamic = true;
+        started = true;
+        i = sub.end;
+        continue;
+      }
+      if (c === "(" || c === ")") return lexFail(src, i, "unsupported-shell-grouping", tokens);
+      if (c === "\\") {
+        if (i + 1 >= n) return lexFail(src, i, "dangling-backslash", tokens);
+        word += src[i + 1];
+        started = true;
+        i += 2;
+        continue;
+      }
+      if (c === "'") {
+        const j = src.indexOf("'", i + 1);
+        if (j < 0) return lexFail(src, i, "unclosed-single-quote", tokens);
+        word += src.slice(i + 1, j);
+        started = true;
+        i = j + 1;
+        continue;
+      }
+      if (c === '"') {
+        started = true;
+        i += 1;
+        let closed = false;
+        while (i < n) {
+          if (src[i] === '"') { i += 1; closed = true; break; }
+          if (src[i] === "\\") {
+            if (i + 1 >= n) return lexFail(src, i, "dangling-backslash", tokens);
+            word += src[i + 1];
+            i += 2;
+            continue;
+          }
+          if (src.startsWith("$(", i)) {
+            const sub = readCommandSubstitution(src, i);
+            if (!sub) return lexFail(src, i, "unclosed-command-substitution", tokens);
+            substitutions.push({ kind: "command-substitution", script: sub.script });
+            word += DYNAMIC_MARKER;
+            dynamic = true;
+            i = sub.end;
+            continue;
+          }
+          if (src[i] === String.fromCharCode(96)) {
+            const sub = readBacktick(src, i);
+            if (!sub) return lexFail(src, i, "unclosed-backtick-substitution", tokens);
+            substitutions.push({ kind: "backtick-substitution", script: sub.script });
+            word += DYNAMIC_MARKER;
+            dynamic = true;
+            i = sub.end;
+            continue;
+          }
+          if (src[i] === "$") {
+            const expansion = readParameterExpansion(src, i);
+            if (!expansion) return lexFail(src, i, "unclosed-parameter-expansion", tokens);
+            word += DYNAMIC_MARKER;
+            dynamic = true;
+            if (expansion.body !== undefined) substitutions.push({ kind: "parameter-expansion", script: expansion.body });
+            i = expansion.end;
+            continue;
+          }
+          word += src[i];
+          i += 1;
+        }
+        if (!closed) return lexFail(src, i, "unclosed-double-quote", tokens);
+        continue;
+      }
+      if (src.startsWith("$(", i)) {
+        const sub = readCommandSubstitution(src, i);
+        if (!sub) return lexFail(src, i, "unclosed-command-substitution", tokens);
+        substitutions.push({ kind: "command-substitution", script: sub.script });
+        word += DYNAMIC_MARKER;
+        dynamic = true;
+        started = true;
+        i = sub.end;
+        continue;
+      }
+      if (c === String.fromCharCode(96)) {
+        const sub = readBacktick(src, i);
+        if (!sub) return lexFail(src, i, "unclosed-backtick-substitution", tokens);
+        substitutions.push({ kind: "backtick-substitution", script: sub.script });
+        word += DYNAMIC_MARKER;
+        dynamic = true;
+        started = true;
+        i = sub.end;
+        continue;
+      }
+      if (c === "$") {
+        const expansion = readParameterExpansion(src, i);
+        if (!expansion) return lexFail(src, i, "unclosed-parameter-expansion", tokens);
+        word += DYNAMIC_MARKER;
+        dynamic = true;
+        started = true;
+        if (expansion.body !== undefined) substitutions.push({ kind: "parameter-expansion", script: expansion.body });
+        i = expansion.end;
+        continue;
+      }
+      if (c === "*" || c === "?") dynamic = true;
+      word += c;
+      started = true;
+      i += 1;
+    }
+    flushWord(word, started, dynamic, substitutions);
+  }
+  if (pendingHeredocs.length) return lexFail(src, n, "unterminated-heredoc", tokens);
+  return { ok: true, tokens: tokens };
+}
+
+
+/**
+ * Splits a complex shell command line into individual subcommands across pipeline
+ * and sequence operators (&&, ||, ;, |, &).
+ * Respects single quotes, double quotes, subshells $(...), backticks, and heredocs.
+ *
+ * @param {string} command - Raw shell command
+ * @returns {Array<{ command: string, argv: string[], operator: string|null, tokens: Array<any>, ok: boolean }>}
+ */
+export function splitSubcommands(command) {
+  if (typeof command !== "string" || command.trim() === "") return [];
+  const tok = tokenize(command);
+  const result = [];
+  let currentTokens = [];
+  let prevOp = null;
+
+  function pushSub(tokens, op) {
+    if (!tokens.length) return;
+    const words = tokens
+      .filter((t) => t.kind === "word")
+      .map((t) => t.value);
+    const subStr = tokens
+      .map((t) => {
+        if (t.kind === "heredoc") return `<<${t.marker}`;
+        return t.value;
+      })
+      .join(" ")
+      .trim();
+    result.push({
+      command: subStr,
+      argv: words,
+      operator: op,
+      tokens: tokens,
+      ok: tok.ok,
+    });
+  }
+
+  for (const t of tok.tokens) {
+    if (t.kind === "op" && SPLIT_OPS.has(t.value)) {
+      pushSub(currentTokens, prevOp);
+      currentTokens = [];
+      prevOp = t.value;
+      continue;
+    }
+    currentTokens.push(t);
+  }
+
+  pushSub(currentTokens, prevOp);
+
+  if (result.length === 0 && command.trim().length > 0) {
+    result.push({
+      command: command.trim(),
+      argv: command.trim().split(/\s+/),
+      operator: null,
+      tokens: [],
+      ok: false,
+    });
+  }
+
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Host-only command safety gate for DeepSeek Harness: blocks recognized dangerous operations and requests DSH approval when a command cannot be inspected.",
   "type": "module",
   "main": "lib/index.js",