@goodandready/dsh-approval-gate 0.1.21 → 0.1.23

package/lib/escalation.js

@@ -0,0 +1,151 @@
+// lib/escalation.js
+// Redundant sandbox recovery (#101) and privilege escalation justification (#107).
+// Prevents unnecessary danger-full-access requests and enforces accountable escalation justifications.
+
+import { isSystemLevelExecution } from "./measure-kinds.js";
+
+export const REDUNDANT_SANDBOX_REASON = "redundant-sandbox-privilege";
+export const MISSING_JUSTIFICATION_REASON = "missing-escalation-justification";
+export const INSUFFICIENT_JUSTIFICATION_REASON = "insufficient-escalation-justification";
+
+const PLACEHOLDER_JUSTIFICATIONS = new Set([
+  "none",
+  "n/a",
+  "na",
+  "test",
+  "testing",
+  "sudo",
+  "fix",
+  "run",
+  "escalate",
+  "please",
+  "bypass",
+  "temp",
+]);
+
+const INTERNAL_SAFE_COMMAND_REGEX = /^(?:git\s+(?:status|diff|log|branch|show)|npm\s+(?:test|run\s+test|run\s+lint)|pnpm\s+(?:test|run\s+test)|node\s+[\w\-./]+\.m?[jt]s|cat\s+|head\s+|tail\s+|grep\s+|find\s+|ls\b|pwd\b|echo\b)/i;
+
+/**
+ * Checks whether an elevated sandbox request is redundant for a safe internal command (#101).
+ *
+ * @param {string} [command]
+ * @param {string} [requestedMode]
+ * @param {{ toolName?: string, args?: any }} [options]
+ * @returns {boolean}
+ */
+export function isRedundantSandboxRequest(command, requestedMode, options = {}) {
+  const mode = String(requestedMode || options.sandboxMode || "").toLowerCase();
+  const isElevated = mode === "danger-full-access" || mode === "full-access" || mode === "danger" || mode === "unrestricted";
+  if (!isElevated) return false;
+
+  const cmd = String(command || "").trim();
+  if (!cmd) return false;
+
+  // If command is system-level, escalation might be genuine (not redundant)
+  if (isSystemLevelExecution(cmd, options.toolName, options.args)) {
+    return false;
+  }
+
+  // If command contains explicit dangerous tokens, it's not a redundant request
+  if (/\b(?:sudo|docker|systemctl|service|apt|apt-get|apk|dnf|pacman|chown|chmod\s+-R)\b/i.test(cmd)) {
+    return false;
+  }
+
+  // Safe internal commands: reading, status, unit testing
+  return INTERNAL_SAFE_COMMAND_REGEX.test(cmd);
+}
+
+/**
+ * Builds actionable remediation advice for redundant sandbox requests (#101).
+ *
+ * @param {string} command
+ * @param {"en" | "ru" | "zh"} [lang="en"]
+ * @returns {string}
+ */
+export function buildRedundantSandboxRemediation(command, lang = "en") {
+  const cmd = String(command || "").trim();
+  if (lang === "ru") {
+    return `Избыточный запрос привилегий песочницы: команда '${cmd}' является безопасной внутрипроектной операцией. Повторите вызов в стандартном режиме песочницы без 'danger-full-access'.`;
+  }
+  if (lang === "zh") {
+    return `请求了冗余的沙箱提权：命令 '${cmd}' 为工作区内部安全操作。请以普通沙箱模式重新执行，无需 'danger-full-access'。`;
+  }
+  return `Redundant sandbox elevation requested: command '${cmd}' is workspace-internal and safe. Repeat the command in standard sandbox mode without 'danger-full-access'.`;
+}
+
+/**
+ * Checks whether privilege escalation requires justification and whether provided justification is valid (#107).
+ *
+ * @param {string} [command]
+ * @param {string} [toolName]
+ * @param {any} [args]
+ * @param {{
+ *   justification?: string,
+ *   context?: any,
+ *   requireJustification?: boolean,
+ *   lang?: "en" | "ru" | "zh"
+ * }} [options]
+ * @returns {{
+ *   required: boolean,
+ *   valid: boolean,
+ *   reason?: string,
+ *   detail?: string,
+ *   advice?: string
+ * }}
+ */
+export function checkEscalationJustification(command, toolName, args, options = {}) {
+  const cmd = String(command || "").trim();
+  const execObj = { name: toolName || "bash", arguments: { ...(args || {}), command: cmd } };
+  const isSystem = isSystemLevelExecution(execObj, options.context);
+  const explicitRequire = options.requireJustification === true || options.context?.requireJustification === true;
+  const isEscalatedSandbox = Boolean(options.context?.sandboxMode && options.context.sandboxMode !== "sandboxed");
+
+  // Escalation justification is required when explicitly required OR when escalated sandbox mode is requested for system operations
+  const escalationRequired = explicitRequire || (isEscalatedSandbox && isSystem);
+  if (!escalationRequired) {
+    return { required: false, valid: true };
+  }
+
+  const rawJustification =
+    (typeof options.justification === "string" && options.justification) ||
+    (typeof args?.justification === "string" && args.justification) ||
+    (typeof options.context?.justification === "string" && options.context.justification) ||
+    "";
+
+  const justification = rawJustification.trim();
+  const lang = options.lang || "en";
+
+  if (!justification) {
+    return {
+      required: true,
+      valid: false,
+      reason: MISSING_JUSTIFICATION_REASON,
+      detail: `Privilege escalation for '${cmd || toolName}' requires an explicit justification.`,
+      advice: lang === "ru"
+        ? "Укажите поле 'justification' с объяснением необходимости системных привилегий."
+        : lang === "zh"
+        ? "执行系统级操作必须提供 'justification' 理由说明。"
+        : "Provide a 'justification' field explaining why elevated privileges are necessary.",
+    };
+  }
+
+  if (justification.length < 10 || PLACEHOLDER_JUSTIFICATIONS.has(justification.toLowerCase())) {
+    return {
+      required: true,
+      valid: false,
+      reason: INSUFFICIENT_JUSTIFICATION_REASON,
+      detail: `Justification '${justification}' is too short or generic (minimum 10 non-placeholder characters required).`,
+      advice: lang === "ru"
+        ? "Обоснование слишком короткое или шаблонное. Опишите конкретную причину эскалации."
+        : lang === "zh"
+        ? "理由说明过短或为占位符。请详细描述提权的实际原因（至少10个字符）。"
+        : "Justification is too brief or placeholder. Describe the specific reason for privilege escalation.",
+    };
+  }
+
+  return {
+    required: true,
+    valid: true,
+    justification,
+  };
+}

package/lib/guidance.js

@@ -0,0 +1,119 @@
+// lib/guidance.js
+// Dynamic security guidance for system prompts (AUTO_MODE_AGENT_GUIDANCE) (#99).
+// Injects structured execution expectations and gate constraints directly into agent context.
+
+export const GUIDANCE_MARKER = "<!-- dsh-approval-gate:guidance -->";
+
+/**
+ * Generates structured agent safety guidance.
+ *
+ * @param {{
+ *   language?: "en" | "ru" | "zh",
+ *   failClosed?: boolean,
+ *   trashEnabled?: boolean,
+ *   snapshotsEnabled?: boolean,
+ *   justificationRequired?: boolean,
+ *   redundantSandboxRecovery?: boolean,
+ *   workspaceDir?: string
+ * }} [options]
+ * @returns {string}
+ */
+export function generateAgentGuidance(options = {}) {
+  const lang = options.language || "en";
+  const failClosed = options.failClosed !== false;
+  const trash = options.trashEnabled !== false;
+  const snapshots = options.snapshotsEnabled !== false;
+  const justification = options.justificationRequired !== false;
+
+  if (lang === "ru") {
+    return [
+      GUIDANCE_MARKER,
+      "### Инструкции безопасности среды выполнения (dsh-approval-gate)",
+      failClosed
+        ? "- **Режим выполнения**: Включен строгий контроль (fail-closed). Нераспознанные шелл-команды требуют ручного подтверждения."
+        : "- **Режим выполнения**: Стандартный контроль команд.",
+      snapshots
+        ? "- **Снимки файлов**: Перед изменением файлов автоматически создаются pre-execution снимки. Избегайте слепой перезаписи."
+        : "",
+      trash
+        ? "- **Удаление файлов**: Запрещено безусловное `rm -rf`. Используйте перемещение в сессионную корзину `.dsh/trash/<session>/` или очистку сессионных артефактов."
+        : "- **Удаление файлов**: Удаляйте файлы строго в границах текущего рабочего каталога.",
+      "- **Песочница**: Не запрашивайте `danger-full-access` или выход из песочницы для стандартных задач внутри проекта.",
+      justification
+        ? "- **Эскалация привилегий**: Любая системная операция (apt, systemctl, сетевые вызовы) требует обязательного поля `justification` с обоснованием."
+        : "",
+      "- **Безопасные команды**: Чтение файлов, `git status`, `git diff`, `npm test` выполняются быстро и без запроса подтверждения.",
+    ].filter(Boolean).join("\n");
+  }
+
+  if (lang === "zh") {
+    return [
+      GUIDANCE_MARKER,
+      "### 执行环境安全指引 (dsh-approval-gate)",
+      failClosed
+        ? "- **执行模式**: 已启用严格安全保护 (fail-closed)。未识别的命令需人工确认。"
+        : "- **执行模式**: 标准命令控制。",
+      snapshots
+        ? "- **文件快照**: 修改文件前会自动生成执行前快照。请避免盲目覆盖文件。"
+        : "",
+      trash
+        ? "- **文件删除**: 禁止盲目运行 `rm -rf`。优先移动至会话回收站 `.dsh/trash/<session>/`。"
+        : "- **文件删除**: 请确保仅在项目工作区内删除文件。",
+      "- **沙箱权限**: 请勿对常规项目任务请求 `danger-full-access` 或沙箱提升。",
+      justification
+        ? "- **权限提升**: 任何系统级操作或跨目录访问必须附带明确的 `justification` 说明。"
+        : "",
+      "- **安全检查**: `git status`、`git diff`、`npm test` 等检查操作自动放行。",
+    ].filter(Boolean).join("\n");
+  }
+
+  // Default: English
+  return [
+    GUIDANCE_MARKER,
+    "### Security & Execution Guidance (dsh-approval-gate)",
+    failClosed
+      ? "- **Execution Mode**: Strict fail-closed policy is active. Unrecognized shell commands require human approval."
+      : "- **Execution Mode**: Standard execution controls active.",
+    snapshots
+      ? "- **File Mutations**: Pre-execution snapshots are captured automatically before writes. Avoid blind destructive overwrites."
+      : "",
+    trash
+      ? "- **Deletion Policy**: Do NOT run unconditional `rm -rf`. Prefer moving to session trash `.dsh/trash/<session>/` or safe artifact cleanup."
+      : "- **Deletion Policy**: Keep all deletions strictly within the workspace boundary.",
+    "- **Sandbox Boundaries**: Do NOT request `danger-full-access` or sandbox elevation for standard internal project tasks.",
+    justification
+      ? "- **Privilege Escalation**: Any system-level command or out-of-workspace access requires an explicit `justification` explanation."
+      : "",
+    "- **Safe Inspection**: Inspection commands (`git status`, `git diff`, `npm test`, `cat`, `ls`) are fast-tracked and safe.",
+  ].filter(Boolean).join("\n");
+}
+
+/**
+ * Injects guidance into system prompt idempotently.
+ *
+ * @param {string} systemPrompt
+ * @param {Parameters<typeof generateAgentGuidance>[0]} [options]
+ * @returns {string}
+ */
+export function injectAgentGuidance(systemPrompt, options = {}) {
+  if (typeof systemPrompt !== "string") {
+    return generateAgentGuidance(options);
+  }
+  if (systemPrompt.includes(GUIDANCE_MARKER)) {
+    return systemPrompt;
+  }
+  const guidance = generateAgentGuidance(options);
+  return `${systemPrompt.trimEnd()}\n\n${guidance}`;
+}
+
+/**
+ * Extracts injected guidance block from prompt if present.
+ * @param {string} prompt
+ * @returns {string|null}
+ */
+export function extractGuidance(prompt) {
+  if (typeof prompt !== "string") return null;
+  const idx = prompt.indexOf(GUIDANCE_MARKER);
+  if (idx === -1) return null;
+  return prompt.slice(idx);
+}

package/lib/index.js

@@ -8,6 +8,9 @@ import { assertHarnessCompatibility, provideServicePolyfill } from "./compat.js"
 import { extractFilePath } from "./dispatcher.js";
 import { SnapshotManager } from "./snapshots.js";
 import { MEASURE_KINDS, classifyMeasureKind } from "./measure-kinds.js";
+import { LineageManager } from "./lineage.js";
+import { generateAgentGuidance, injectAgentGuidance, extractGuidance, GUIDANCE_MARKER } from "./guidance.js";
+import { isRedundantSandboxRequest, buildRedundantSandboxRemediation, checkEscalationJustification } from "./escalation.js";
 import Schema from "@deepseek-ai/schemastery";
 
 if (typeof Schema.prototype?.volatile !== "function") {
@@ -183,6 +186,16 @@ export function readKnobs(ctx, execution) {
     }
   }
 
+  // 5b. Lineage authority inheritance (#98)
+  if (!policy && session && (session.parentSession || session.parentId || session.parentSessionId)) {
+    const parent = session.parentSession || { id: session.parentId || session.parentSessionId };
+    if (typeof parent.approvalPolicy === "string") {
+      policy = parent.approvalPolicy;
+    } else if (approval && typeof approval.effectivePolicy === "function") {
+      try { policy = approval.effectivePolicy(parent) || ""; } catch {}
+    }
+  }
+
   // 6. Global static fallback from approval service config
   if (!policy && approval && approval.config && approval.config.policy) {
     policy = approval.config.policy;
@@ -253,6 +266,10 @@ export const Config = Schema.object({
   agentsRules: Schema.boolean().default(true).volatile(),
   /** Enforce human confirmation on breaking major dependency bumps in package.json (#95). */
   versionGuard: Schema.boolean().default(true).volatile(),
+  /** Require explicit justification for privilege escalation (#107). */
+  requireJustification: Schema.boolean().default(false).volatile(),
+  /** Enable automatic remediation advice for redundant sandbox privilege requests (#101). */
+  enableRedundantSandboxRecovery: Schema.boolean().default(true).volatile(),
   /** Security engine instance (internal/testing). */
   engine: Schema.any().hidden(),
 });
@@ -321,6 +338,8 @@ export function apply(ctx, config) {
       slaMs: cfg.classifierSlaMs !== undefined ? cfg.classifierSlaMs : 2000,
     }),
     defaultVerdict: cfg.defaultVerdict || "ask",
+    requireJustification: cfg.requireJustification === true,
+    enableRedundantSandboxRecovery: cfg.enableRedundantSandboxRecovery !== false,
     snapshotManager: new SnapshotManager({ workspaceDir: cfg.workspaceDir || "", maxSnapshotsPerSession: cfg.maxSnapshotsPerSession, maxSnapshotBytes: cfg.maxSnapshotBytes }),
     dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
     auditFailClosed: Boolean(cfg.auditFailClosed),
@@ -356,6 +375,20 @@ export function apply(ctx, config) {
     clearSnapshots: (sessionId) => (engine.clearSnapshots ? engine.clearSnapshots(sessionId) : { cleared: 0 }),
     clearAllSnapshots: () => (engine.clearAllSnapshots ? engine.clearAllSnapshots() : { cleared: 0 }),
     getSnapshotStats: () => (engine.snapshotManager ? engine.snapshotManager.getStats() : null),
+    lineage: engine.lineage,
+    registerLineage: (child, parent, root) => engine.registerLineage(child, parent, root),
+    getLineage: (id) => engine.getLineage(id),
+    guidance: {
+      generate: (opts) => generateAgentGuidance(opts),
+      inject: (prompt, opts) => injectAgentGuidance(prompt, opts),
+      extract: (prompt) => extractGuidance(prompt),
+    },
+    getAgentGuidance: (opts) => generateAgentGuidance(opts),
+    redundantSandbox: {
+      check: (cmd, mode, opts) => isRedundantSandboxRequest(cmd, mode, opts),
+      remediation: (cmd, lang) => buildRedundantSandboxRemediation(cmd, lang),
+    },
+    checkEscalationJustification: (cmd, tool, args, opts) => checkEscalationJustification(cmd, tool, args, opts),
     getSnapshot: () => ({
       active: true,
       dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
@@ -379,9 +412,12 @@ export function apply(ctx, config) {
       const knobs = readKnobs(ctx, execution);
       const who = sessionTag(execution);
       const sessionId = resolveSessionId(execution);
+      const callId = execution?.callId || execution?.id || null;
+      const agentId = execution?.agent?.id || execution?.agentId || null;
+      const subagentId = execution?.agent?.subagentId || execution?.subagentId || null;
       let decision;
       try {
-        decision = engine.decide(execution, { sessionId, knobs });
+        decision = engine.decide(execution, { sessionId, knobs, callId, agentId, subagentId, sandboxMode: knobs.sandbox, preset: knobs.preset });
       } catch (err) {
         const hit = {
           ask: true,
@@ -444,9 +480,12 @@ export function apply(ctx, config) {
   const guard = function (execution) {
     const who = sessionTag(execution);
     const sessionId = resolveSessionId(execution);
+    const callId = execution?.callId || execution?.id || null;
+    const agentId = execution?.agent?.id || execution?.agentId || null;
+    const subagentId = execution?.agent?.subagentId || execution?.subagentId || null;
     let decision;
     try {
-      decision = engine.decide(execution, { sessionId });
+      decision = engine.decide(execution, { sessionId, callId, agentId, subagentId });
     } catch (err) {
       const hit = {
         deny: true,
@@ -493,12 +532,7 @@ export function apply(ctx, config) {
 
 export { SecurityEngine } from "./engine.js";
 export { BandsEngine } from "./bands.js";
-export {
-  CircuitBreaker,
-  CIRCUIT_STATE_ACTIVE,
-  CIRCUIT_STATE_TRIPPED,
-  CIRCUIT_STATE_RESUMED,
-} from "./breaker.js";
+export { CircuitBreaker, CIRCUIT_STATE_ACTIVE, CIRCUIT_STATE_TRIPPED, CIRCUIT_STATE_RESUMED } from "./breaker.js";
 export { SessionGrantStore, DEFAULT_GRANT_TTL_MS, DEFAULT_GRANT_MAX_USES, matchGrantCriteria } from "./grants.js";
 export { canonicalizeCall, canonicalString, hashCall, sortKeys } from "./canonical.js";
 export { expandHome, resolveSafePath, isPathTraversal, canonicalizeFsPath } from "./paths.js";
@@ -511,7 +545,7 @@ export { isLoopbackHost, isLoopbackUrl, isLoopbackCommand } from "./loopback.js"
 export { computeFingerprint, computeFingerprintHash, normalizeCommandString } from "./fingerprint.js";
 export { VerdictCache, DEFAULT_CACHE_MAX_SIZE, DEFAULT_CACHE_TTL_MS } from "./cache.js";
 export { RetryExhaustionGuard, DEFAULT_MAX_RETRY_ATTEMPTS } from "./retry-exhaustion.js";
-export { QualityLedger, MAX_LEDGER_EVENTS_PER_SESSION } from "./ledger.js";
+export { QualityLedger, MAX_LEDGER_EVENTS_PER_SESSION, CURRENT_SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSIONS, migrateVerdictRecord } from "./ledger.js";
 export { AuditLogger, DEFAULT_AUDIT_LOG_RELATIVE, DEFAULT_MAX_AUDIT_BYTES, DEFAULT_MAX_AUDIT_LINES, DEFAULT_RETAIN_LINES, auditRotateContent } from "./audit-log.js";
 export { BlockCounters, categorizeReason } from "./counters.js";
 export { isCriticalOperation } from "./engine.js";
@@ -533,6 +567,10 @@ export { detectHarnessCapabilities, assertHarnessCompatibility, provideServicePo
 export { parseSemver, isMajorBump, inspectPackageJsonDiff, VersionGuard } from "./version-guard.js";
 export { SnapshotManager, DEFAULT_MAX_SNAPSHOTS_PER_SESSION, DEFAULT_MAX_SNAPSHOT_BYTES } from "./snapshots.js";
 export { MEASURE_KINDS, classifyMeasureKind, isSystemLevelExecution, isWorkspaceWideExecution } from "./measure-kinds.js";
-
-
-
+export { LineageManager } from "./lineage.js";
+export { generateAgentGuidance, injectAgentGuidance, extractGuidance, GUIDANCE_MARKER } from "./guidance.js";
+export { isRedundantSandboxRequest, buildRedundantSandboxRemediation, checkEscalationJustification, REDUNDANT_SANDBOX_REASON, MISSING_JUSTIFICATION_REASON, INSUFFICIENT_JUSTIFICATION_REASON } from "./escalation.js";
+export { TRACK_TYPES, classifyTrack, isInternalTrack, isExternalTrack } from "./dualtrack.js";
+export { GATE_MODES, PRESET_MODE_MAP, resolveSessionGateMode, applySessionModePolicy, SessionModeRegistry } from "./session-modes.js";
+export { buildEvidenceDossier, formatDossierSummary, MAX_PROMPT_CHARS, MAX_DIFF_CHARS, MAX_OUTPUT_CHARS } from "./dossier.js";
+export { DRIFT_CATEGORIES, detectTrajectoryDrift, TrajectoryTracker } from "./drift.js";