@goodandready/dsh-approval-gate 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.12
+
+- Fix: корректная регистрация сервиса `approvalGate` в Cordis через `ctx.provide('approvalGate', ...)` и экспорт `export const provide = ['approvalGate']`, устраняющая ошибку `cannot set property "approvalGate" without provide` при старте хоста DSH.
+- Policy: надежное определение режима «Полный доступ» (`danger-full-access` / `never`) в `readKnobs` и `isUnattended` даже при отсутствии предварительного события `approval/policy` в сессии (приоритет пресета и sandbox режима над дефолтным `ask` от `ApprovalService`), предотвращающая ложный отказ `the user rejected tool` на всех командах агента.
+- Localization: удаление захардкоженного русского словаря из `lib/messages.js` в строгом соответствии со стандартом разработки DSH плагинов (только `en` и `zh`, русская локализация централизованно обслуживается `dsh-russian-lang`) с защитной обработкой `locale.register` в `apply` (Refs: #153, #162).
+- Bands: динамическое расширение списка read-only инструментов из хостового `toolRegistry` (`options.toolRegistry`) с поддержкой аннотаций `readOnly` / `readonly` (Refs: #156).
+- Engine: настраиваемый дефолтный вердикт для нераспознанных команд `defaultVerdict` (`allow` по умолчанию, опциональный fail-closed `ask`) с добавлением в схему `Config` (Refs: #163).
+- Session: гарантированное извлечение строкового `sessionId` в `resolveSessionId` для любых структур объекта `agent` / `session`.
+
 ## 0.1.11
 
 - Security: проверка абсолютных путей перенаправлений shell на выход за пределы рабочего каталога `workspaceDir` с исключением canonical устройств (`/dev/null`) и временных каталогов (`/tmp`) (Refs: #143).

package/lib/bands.js

@@ -134,6 +134,22 @@ export class BandsEngine {
       typeof g === "string" ? compileGlob(g) : g
     );
     this.readOnlyTools = new Set(options.readOnlyTools || DEFAULT_READ_ONLY_TOOLS);
+
+    // Derive read-only tools dynamically from host tool registry if provided (#156)
+    if (options.toolRegistry) {
+      try {
+        const tools = typeof options.toolRegistry.getTools === "function"
+          ? options.toolRegistry.getTools()
+          : (Array.isArray(options.toolRegistry) ? options.toolRegistry : []);
+        for (const t of tools) {
+          if (t && (t.readOnly || t.readonly || t.isReadOnly) && typeof t.name === "string") {
+            this.readOnlyTools.add(t.name);
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
   }
 
   /**

package/lib/engine.js

@@ -28,6 +28,7 @@ export class SecurityEngine {
     this.inspectConfig = options.inspectConfig || {};
     this.classifier = options.classifier || null;
     this.grantRegistry = options.grantRegistry || new SessionGrantStore(options);
+    this.defaultVerdict = options.defaultVerdict || "allow";
   }
 
   /**
@@ -114,7 +115,11 @@ export class SecurityEngine {
       }
     }
 
-    // Safe default for unclassified commands
+    // Default verdict for unclassified commands (#163)
+    if (this.defaultVerdict === "ask") {
+      const askHit = { ask: true, reason: "unmatched-ask", snippet: command || toolName };
+      return { verdict: "ask", stage: "P4", reason: "unmatched-ask", hit: askHit };
+    }
     return { verdict: "allow", stage: "P2", reason: "unmatched-allow", hit };
     } catch (err) {
       return {

package/lib/index.js

@@ -1,17 +1,5 @@
 import { SecurityEngine } from "./engine.js";
-// dsh-approval-gate - approval gate for DeepSeek Harness.
-//
-// Registers tools.guard on the tool runtime and denies dangerous bash
-// commands and writes to secret files even when sandbox mode would allow
-// them. A guard return value (non-undefined) denies execution, so the
-// dangerous call never runs on its own - it needs an explicit owner
-// Approval is handled by DSH's native flow; no separate word is implemented. When the
-// effective approval policy cannot be answered ("never", i.e. the full-access preset),
-// the gate does not raise an ask at all: an allowed command proceeds instead of dying as
-// a rejection nobody could consent to. Denials never depend on the policy.
-//
-// Only the agent tool calls pass through the guard (cron/systemd scripts
-// do not), so legitimate unattended operations are unaffected.
+import { BandsEngine } from "./bands.js";
 import Schema from "@deepseek-ai/schemastery";
 
 if (typeof Schema.prototype?.volatile !== "function") {
@@ -45,6 +33,7 @@ import { LOCALE_NS, MESSAGES } from "./messages.js";
 
 export const name = "dsh-approval-gate";
 export const inject = ["tools"];
+export const provide = ["approvalGate"];
 
 /** Policies under which a prompt cannot be answered, so raising one is a silent denial. */
 export const DEFAULT_UNATTENDED_POLICIES = ["never"];
@@ -52,25 +41,48 @@ export const DEFAULT_UNATTENDED_POLICIES = ["never"];
 /**
  * Whether a raised ask would be answerable in this session.
  *
- * `policy` comes from the approval service (`ctx.approval.config.policy`); an empty value
- * means the knob is unknown and the gate keeps asking, which is the safe direction.
- * @param {{policy?: string, unattendedPolicies?: string[]}} knobs
+ * Checks explicit unattended policies, as well as preset and sandbox modes.
+ * In 'danger-full-access' mode, approval prompts are disabled by host design.
+ * @param {{policy?: string, preset?: string, sandbox?: string, unattendedPolicies?: string[]}} knobs
  * @returns {boolean}
  */
 export function isUnattended(knobs) {
-  const policy = knobs && knobs.policy;
+  if (!knobs) return false;
+  if (knobs.preset === "danger-full-access" || knobs.sandbox === "danger-full-access") return true;
+  const policy = knobs.policy;
   const policies = (knobs && knobs.unattendedPolicies) || DEFAULT_UNATTENDED_POLICIES;
   if (typeof policy !== "string" || policy === "") return false;
   return policies.includes(policy);
 }
 
+/**
+ * Extracts a clean string session identifier from an execution object.
+ * @param {any} execution
+ * @returns {string}
+ */
+export function resolveSessionId(execution) {
+  const agent = execution && execution.agent;
+  const session = agent && agent.session;
+  if (session) {
+    if (typeof session === "string") return session;
+    if (typeof session.id === "string") return session.id;
+    if (typeof session.sessionId === "string") return session.sessionId;
+    if (typeof session.sessionKey === "string") return session.sessionKey;
+  }
+  if (agent) {
+    if (typeof agent === "string") return agent;
+    if (typeof agent.id === "string") return agent.id;
+  }
+  return "default";
+}
+
 /**
  * Effective permission knobs, as the harness exposes them.
- * Resolves session-level approval policy if an active execution carrying a session is provided.
+ * Resolves session-level approval policy, preset, and sandbox mode.
  *
  * @param {any} ctx - Cordis context
  * @param {any} [execution] - Optional tool execution carrying agent/session
- * @returns {{ policy: string, sandbox: string }}
+ * @returns {{ policy: string, sandbox: string, preset: string }}
  */
 export function readKnobs(ctx, execution) {
   const read = (name) => {
@@ -87,75 +99,96 @@ export function readKnobs(ctx, execution) {
   const session = agent && (agent.session || (typeof agent === "object" && typeof agent.eventAt === "function" ? agent : undefined));
 
   let policy = "";
+  let preset = "";
+  let sessionSandbox = "";
 
-  // 1. Live approval service effectivePolicy(session)
-  if (approval && session && typeof approval.effectivePolicy === "function") {
-    try {
-      policy = approval.effectivePolicy(session) || "";
-    } catch {
-      // ignore
-    }
-  }
-
-  // 2. Direct session property fallback
-  if (!policy && session && typeof session.approvalPolicy === "string") {
-    policy = session.approvalPolicy;
-  }
-
-  // 3. Fallback: inspect session events backwards for approval/policy and danger-full-access
-  if (!policy && session && typeof session.eventAt === "function" && typeof session.seq === "number") {
+  // 1. Inspect session events backwards (bounded to last 100 events) with sequence caching
+  if (session && typeof session.eventAt === "function" && typeof session.seq === "number") {
     if (session._gateCachedSeq === session.seq && session._gateCachedPolicy !== undefined) {
       policy = session._gateCachedPolicy;
+      preset = session._gateCachedPreset || "";
+      sessionSandbox = session._gateCachedSandbox || "";
     } else {
       try {
         const minSeq = Math.max(0, session.seq - 100);
         for (let seq = session.seq - 1; seq >= minSeq; seq -= 1) {
           const event = session.eventAt(seq);
-          if (event && event.type === "approval/policy" && event.data && event.data.policy) {
+          if (!policy && event && event.type === "approval/policy" && event.data && event.data.policy) {
             policy = event.data.policy;
-            break;
           }
-          if (event && event.type === "permission/preset" && event.data && event.data.preset === "danger-full-access") {
-            policy = "never";
-            break;
+          if (!preset && event && event.type === "permission/preset" && event.data && event.data.preset) {
+            preset = event.data.preset;
           }
+          if (!sessionSandbox && event && event.type === "sandbox/mode" && event.data && event.data.mode) {
+            sessionSandbox = event.data.mode;
+          }
+          if (policy && preset && sessionSandbox) break;
         }
         session._gateCachedSeq = session.seq;
         session._gateCachedPolicy = policy || "";
+        session._gateCachedPreset = preset || "";
+        session._gateCachedSandbox = sessionSandbox || "";
       } catch {
         // ignore
       }
     }
   }
 
-  // 4. In-memory session.events array fallback (common in mocks / tests)
-  if (!policy && session && Array.isArray(session.events)) {
+  // 2. In-memory session.events array fallback (common in mocks / tests)
+  if (session && Array.isArray(session.events)) {
     try {
       const minIdx = Math.max(0, session.events.length - 100);
       for (let i = session.events.length - 1; i >= minIdx; i -= 1) {
         const event = session.events[i];
-        if (event && event.type === "approval/policy" && event.data && event.data.policy) {
+        if (!policy && event && event.type === "approval/policy" && event.data && event.data.policy) {
           policy = event.data.policy;
-          break;
         }
-        if (event && event.type === "permission/preset" && event.data && event.data.preset === "danger-full-access") {
-          policy = "never";
-          break;
+        if (!preset && event && event.type === "permission/preset" && event.data && event.data.preset) {
+          preset = event.data.preset;
+        }
+        if (!sessionSandbox && event && event.type === "sandbox/mode" && event.data && event.data.mode) {
+          sessionSandbox = event.data.mode;
         }
+        if (policy && preset && sessionSandbox) break;
       }
     } catch {
       // ignore
     }
   }
 
+  // 3. Preset / sandbox direct values: danger-full-access implies "never" approval
+  if (preset === "danger-full-access" || sessionSandbox === "danger-full-access") {
+    policy = "never";
+  }
+
+  // 4. Direct session property fallback
+  if (!policy && session && typeof session.approvalPolicy === "string") {
+    policy = session.approvalPolicy;
+  }
+
+  // 5. Live approval service effectivePolicy(session)
+  if (!policy && approval && session && typeof approval.effectivePolicy === "function") {
+    try {
+      policy = approval.effectivePolicy(session) || "";
+    } catch {
+      // ignore
+    }
+  }
+
   // 6. Global static fallback from approval service config
   if (!policy && approval && approval.config && approval.config.policy) {
     policy = approval.config.policy;
   }
 
+  const sandbox = sessionSandbox || (shell && shell.sandboxMode) || "";
+  if (sandbox === "danger-full-access" && !policy) {
+    policy = "never";
+  }
+
   return {
     policy: policy || "",
-    sandbox: (shell && shell.sandboxMode) || "",
+    sandbox: sandbox || "",
+    preset: preset || "",
   };
 }
 
@@ -170,6 +203,8 @@ export const Config = Schema.object({
   unattended: Schema.boolean().default(false).volatile(),
   /** Workspace directory for path traversal boundary checks. */
   workspaceDir: Schema.string().default("").volatile(),
+  /** Default verdict for unclassified commands: 'allow' (default) or 'ask' (fail-closed) (#163). */
+  defaultVerdict: Schema.union(["allow", "ask"]).default("allow").volatile(),
   /** Security engine instance (internal/testing). */
   engine: Schema.any().hidden(),
 });
@@ -189,7 +224,15 @@ export function apply(ctx, config) {
   };
   const registerLocale = function () {
     const locale = getLocale();
-    if (locale && typeof locale.register === "function") return locale.register(LOCALE_NS, MESSAGES);
+    if (locale && typeof locale.register === "function") {
+      try {
+        return locale.register(LOCALE_NS, MESSAGES);
+      } catch (err) {
+        if (ctx && ctx.logger && typeof ctx.logger.warn === "function") {
+          ctx.logger.warn("[dsh-approval-gate] locale registration skipped: " + (err && err.message || err));
+        }
+      }
+    }
   };
   if (ctx && typeof ctx.effect === "function") ctx.effect(registerLocale, "dsh-approval-gate: dictionaries");
   else registerLocale();
@@ -203,13 +246,21 @@ export function apply(ctx, config) {
   const forcedUnattended = cfg.unattended === true;
   const engine = (config && config.engine) || cfg.engine || new SecurityEngine({
     inspectConfig: { toolName: toolName, fileWriteTools: fileWriteTools, workspaceDir: cfg.workspaceDir || "" },
+    bands: new BandsEngine({ toolRegistry: ctx && ctx.tools }),
+    defaultVerdict: cfg.defaultVerdict || "allow",
   });
+
+  const gateService = {
+    engine,
+    addGrant: (options) => engine.addGrant(options),
+    resume: (sessionId, reason) => engine.resume(sessionId, reason),
+  };
   if (ctx && typeof ctx === "object") {
-    ctx.approvalGate = {
-      engine,
-      addGrant: (options) => engine.addGrant(options),
-      resume: (sessionId, reason) => engine.resume(sessionId, reason),
-    };
+    if (typeof ctx.provide === "function") {
+      ctx.provide("approvalGate", gateService);
+    } else {
+      ctx.approvalGate = gateService;
+    }
   }
 
   const hasPreExecute = ctx && typeof ctx.on === "function";
@@ -217,7 +268,7 @@ export function apply(ctx, config) {
     ctx.on("tools/pre-execute", function (execution, next) {
       const knobs = readKnobs(ctx, execution);
       const who = sessionTag(execution);
-      const sessionId = (execution && execution.agent && (execution.agent.session || execution.agent)) || "default";
+      const sessionId = resolveSessionId(execution);
       let decision;
       try {
         decision = engine.decide(execution, { sessionId, knobs });
@@ -242,7 +293,7 @@ export function apply(ctx, config) {
           logBlocked(ctx, hit, who);
           return denyMessage(hit, who, translate, ctx && ctx.logger);
         }
-        if (forcedUnattended || isUnattended({ policy: knobs.policy, unattendedPolicies })) {
+        if (forcedUnattended || isUnattended({ policy: knobs.policy, preset: knobs.preset, sandbox: knobs.sandbox, unattendedPolicies })) {
           return next();
         }
         const hit = decision.hit || {
@@ -259,7 +310,7 @@ export function apply(ctx, config) {
 
   const guard = function (execution) {
     const who = sessionTag(execution);
-    const sessionId = (execution && execution.agent && (execution.agent.session || execution.agent)) || "default";
+    const sessionId = resolveSessionId(execution);
     let decision;
     try {
       decision = engine.decide(execution, { sessionId });
@@ -318,6 +369,4 @@ export {
 } from "./canonical.js";
 export { expandHome, resolveSafePath, isPathTraversal, canonicalizeFsPath } from "./paths.js";
 export { splitSubcommands } from "./tokenizer.js";
-
-
 export { redactCredentials, redactUrl } from "./redact.js";

package/lib/messages.js

@@ -116,63 +116,6 @@ export const MESSAGES = Object.freeze({
     hintDestructiveSql: "请使用版本化数据库迁移，或执行非破坏性查询",
     hintCurlPipe: "先将脚本下载到本地检查内容，再安全执行",
   },
-  ru: {
-    blockedPrefix: "Заблокировано правилом dsh-approval-gate",
-    detectedLabel: "Обнаружено",
-    commandLabel: "Команда",
-    parseReasonLabel: "Причина разбора",
-    hintPrefix: "Подсказка",
-    detailProcessSubstitution: "подстановка процесса требует подтверждения",
-    detailUnclosedProcessSubstitution: "незакрытая подстановка процесса",
-    detailUnclosedCommandSubstitution: "незакрытая подстановка команды",
-    detailUnclosedBacktick: "незакрытая подстановка в обратных кавычках",
-    detailUnclosedParameterExpansion: "незакрытое расширение параметра",
-    detailUnclosedSingleQuote: "незакрытая одинарная кавычка",
-    detailUnclosedDoubleQuote: "незакрытая двойная кавычка",
-    detailDanglingEscape: "незавершённое экранирование",
-    detailInvalidHeredoc: "неверный разделитель here-document",
-    detailUnterminatedHeredoc: "ограничитель here-document не найден",
-    detailUnsupportedGrouping: "группировка shell не поддерживается анализатором",
-    detailUnsupported: "неподдерживаемый синтаксис shell",
-    approvalRequired: "Требуется подтверждение",
-    askUnknown: "Команда не может быть проверена полностью; проверьте её перед подтверждением",
-    askUnparseable: "Синтаксис shell не может быть проверен полностью; проверьте его перед подтверждением",
-    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: "Небезопасный исполняемый код интерпретатора",
-    ruleEnvDumpLeak: "Попытка утечки переменных окружения и секретов",
-    rulePathTraversal: "Обнаружена попытка обхода каталогов (path traversal)",
-    ruleBandHardDeny: "Команда заблокирована критическим списком безопасности Band 0",
-    ruleCircuitBreakerTripped: "Предохранитель сессии сработал из-за повторяющихся блокировок",
-    hintRecursiveRm: "Указывайте конкретные файлы вместо рекурсивного удаления",
-    hintPathTraversal: "Ограничьте операции пределами рабочего каталога проекта",
-    hintSecretWrite: "Изменяйте настройки через UI или переменные окружения, не перезаписывайте секретные файлы напрямую",
-    hintEnvDumpLeak: "Запрашивайте конкретные несекретные переменные по отдельности",
-    hintCircuitBreakerTripped: "Запросите подтверждение оператора перед повторной отправкой системных команд",
-    hintDestructiveSql: "Используйте версионированные миграции или выполняйте неразрушающие запросы",
-    hintCurlPipe: "Скачайте скрипт локально, проверьте его содержимое и выполните безопасно",
-  },
 });
 
 export function sessionTag(execution) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "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",