@goodandready/dsh-approval-gate 0.1.20 → 0.1.22

package/lib/messages.js

@@ -22,6 +22,7 @@ export const MESSAGES = Object.freeze({
     detailUnsupported: "unsupported shell syntax",
     approvalRequired: "Approval required",
     askUnknown: "The command could not be fully inspected; review it before allowing",
+    askUnmatched: "The operation was not recognized by safety rules; human confirmation is required by default",
     askUnparseable: "Shell syntax could not be fully inspected; review it before allowing",
     askUnknownFormat: "The tool call format could not be inspected; review it before allowing",
     askUnknownWriteTarget: "The file write target could not be identified; review it before allowing",
@@ -81,6 +82,12 @@ export const MESSAGES = Object.freeze({
     ruleAgentsMdProhibitedPath: "File modification prohibited by rules in AGENTS.md",
     askMajorVersionBump: "Package.json modification contains major dependency bump; review before allowing",
     ruleMajorVersionBump: "Unauthorized major dependency version bump",
+    askRedundantSandbox: "Redundant sandbox elevation requested for safe workspace operation; review or execute in sandboxed mode",
+    ruleRedundantSandbox: "Unnecessary sandbox elevation requested for workspace-internal task",
+    askMissingJustification: "Privilege escalation requires an explicit justification; review before allowing",
+    ruleMissingJustification: "System privilege escalation requested without justification",
+    askInsufficientJustification: "Privilege escalation justification is too brief or generic; review before allowing",
+    ruleInsufficientJustification: "Insufficient privilege escalation justification",
     hintRecursiveRm: "Specify exact target files instead of recursive deletion",
     hintPathTraversal: "Keep operations strictly within the project directory",
     hintSecretWrite: "Modify configuration via settings or environment variables, not raw file overwrite",
@@ -107,6 +114,10 @@ export const MESSAGES = Object.freeze({
     hintTrashAlternative: "Move files to reversible .dsh/trash/<session>/ directory instead of rm",
     hintAgentsMdProhibited: "Review project-specific guidelines and constraints defined in AGENTS.md",
     hintMajorVersionBump: "Verify compatibility before bumping major dependency versions in package.json",
+    hintUnmatchedAsk: "Unrecognized operations default to fail-closed approval under defaultVerdict='ask'",
+    hintRedundantSandbox: "Execute the command in standard sandbox mode without danger-full-access",
+    hintMissingJustification: "Provide a justification field with at least 10 non-placeholder characters",
+    hintInsufficientJustification: "Describe the specific operational reason for privilege escalation",
   },
   zh: {
     blockedPrefix: "dsh-approval-gate 规则已阻止",
@@ -128,6 +139,7 @@ export const MESSAGES = Object.freeze({
     detailUnsupported: "不支持的 shell 语法",
     approvalRequired: "需要批准",
     askUnknown: "命令无法完整检查；请在允许前进行审查",
+    askUnmatched: "该操作未被安全规则识别；默认需要人工确认",
     askUnparseable: "Shell 语法无法完整检查；请在允许前进行审查",
     askUnknownFormat: "工具调用格式无法检查；请在允许前进行审查",
     askUnknownWriteTarget: "无法识别文件写入目标；请在允许前进行审查",
@@ -187,6 +199,12 @@ export const MESSAGES = Object.freeze({
     ruleAgentsMdProhibitedPath: "文件修改被 AGENTS.md 中的规则明确禁止",
     askMajorVersionBump: "package.json 包含破坏性依赖主版本升级；请在允许前进行审查",
     ruleMajorVersionBump: "未授权的依赖包主版本升级",
+    askRedundantSandbox: "对安全的内部操作请求了冗余的沙箱提权；请在允许前审查或以标准沙箱模式执行",
+    ruleRedundantSandbox: "工作区内部任务请求了不必要的沙箱提权",
+    askMissingJustification: "特权提升需要明确的理由说明；请在允许前进行审查",
+    ruleMissingJustification: "未提供理由即请求系统提权",
+    askInsufficientJustification: "特权提升理由过短或为占位符；请在允许前进行审查",
+    ruleInsufficientJustification: "特权提升理由不充分",
     hintRecursiveRm: "请指定具体目标文件，避免递归删除",
     hintPathTraversal: "请将操作限制在项目根目录内",
     hintSecretWrite: "请通过设置或环境变量修改配置，不要直接覆盖敏感配置文件",
@@ -213,6 +231,10 @@ export const MESSAGES = Object.freeze({
     hintTrashAlternative: "建议将文件移动到可逆的 .dsh/trash/<session>/ 目录，避免直接 rm",
     hintAgentsMdProhibited: "请核对项目根目录 AGENTS.md 中定义的安全约束和禁止指令",
     hintMajorVersionBump: "在升级 package.json 依赖主版本前请确认破坏性变更与兼容性",
+    hintUnmatchedAsk: "在 defaultVerdict='ask' 模式下，未识别的操作默认需要人工审核确认",
+    hintRedundantSandbox: "在标准沙箱模式下重新执行该命令，无需申请 danger-full-access",
+    hintMissingJustification: "请提供至少10个字符的有效理由说明字段",
+    hintInsufficientJustification: "请详细说明提权操作的具体业务或技术原因",
   },
 });
 
@@ -287,6 +309,9 @@ const RULE_KEYS = Object.freeze({
   "agents-md-prohibited-command": "ruleAgentsMdProhibitedCommand",
   "agents-md-prohibited-path": "ruleAgentsMdProhibitedPath",
   "major-version-bump": "askMajorVersionBump",
+  "redundant-sandbox-privilege": "ruleRedundantSandbox",
+  "missing-escalation-justification": "ruleMissingJustification",
+  "insufficient-escalation-justification": "ruleInsufficientJustification",
 });
 
 const HINT_KEYS = Object.freeze({
@@ -317,12 +342,20 @@ const HINT_KEYS = Object.freeze({
   "agents-md-prohibited-command": "hintAgentsMdProhibited",
   "agents-md-prohibited-path": "hintAgentsMdProhibited",
   "major-version-bump": "hintMajorVersionBump",
+  "unmatched-ask": "hintUnmatchedAsk",
+  "redundant-sandbox-privilege": "hintRedundantSandbox",
+  "missing-escalation-justification": "hintMissingJustification",
+  "insufficient-escalation-justification": "hintInsufficientJustification",
 });
 
 const ASK_KEYS = Object.freeze({
   unparseable: "askUnparseable",
   "unknown-format": "askUnknownFormat",
   "unknown-write-target": "askUnknownWriteTarget",
+  "unmatched-ask": "askUnmatched",
+  "redundant-sandbox-privilege": "askRedundantSandbox",
+  "missing-escalation-justification": "askMissingJustification",
+  "insufficient-escalation-justification": "askInsufficientJustification",
   "dynamic-command": "askDynamicCommand",
   "dynamic-arguments": "askDynamicArguments",
   "dynamic-redirect": "askDynamicRedirect",

package/lib/snapshots.js

@@ -0,0 +1,268 @@
+// lib/snapshots.js
+// Pre-execution Snapshots (#77), Undo/Rollback (#76), and Dual-level Cleanup (#78).
+// Zero external dependencies; safe filesystem operations with in-memory metadata.
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+export const DEFAULT_MAX_SNAPSHOTS_PER_SESSION = 50;
+export const DEFAULT_MAX_SNAPSHOT_BYTES = 1024 * 1024; // 1 MB
+
+export class SnapshotManager {
+  /**
+   * @param {Record<string, any>} [options]
+   */
+  constructor(options = {}) {
+    this.maxSnapshotsPerSession = Number(options.maxSnapshotsPerSession) || DEFAULT_MAX_SNAPSHOTS_PER_SESSION;
+    this.maxSnapshotBytes = Number(options.maxSnapshotBytes) || DEFAULT_MAX_SNAPSHOT_BYTES;
+    this.workspaceDir = options.workspaceDir ? path.resolve(options.workspaceDir) : "";
+
+    /** @type {Map<string, Record<string, any>>} snapshotId -> Snapshot */
+    this.snapshots = new Map();
+    /** @type {Map<string, string[]>} sessionId -> [snapshotId, ...] */
+    this.sessionIndex = new Map();
+    /** @type {Map<string, string>} callId -> snapshotId */
+    this.callIndex = new Map();
+  }
+
+  /**
+   * Resolves absolute file path within workspace or host.
+   * @param {string} targetPath
+   * @returns {string}
+   */
+  resolvePath(targetPath) {
+    if (!targetPath || typeof targetPath !== "string") return "";
+    if (path.isAbsolute(targetPath)) return path.normalize(targetPath);
+    if (this.workspaceDir) return path.resolve(this.workspaceDir, targetPath);
+    return path.resolve(targetPath);
+  }
+
+  /**
+   * Captures a pre-execution snapshot before file mutation (#77).
+   * @param {string} targetPath - Relative or absolute path to target file
+   * @param {Record<string, any>} [meta] - Metadata (sessionId, callId, tool)
+   * @returns {Record<string, any>} Created snapshot record
+   */
+  takeSnapshot(targetPath, meta = {}) {
+    const resolved = this.resolvePath(targetPath);
+    if (!resolved) {
+      return { success: false, error: "invalid-target-path" };
+    }
+
+    const sessionId = String(meta.sessionId || "default");
+    const callId = meta.callId ? String(meta.callId) : null;
+    const tool = meta.tool ? String(meta.tool) : "unknown";
+
+    let existed = false;
+    let content = null;
+    let tooLarge = false;
+    let size = 0;
+
+    try {
+      if (fs.existsSync(resolved)) {
+        existed = true;
+        const stat = fs.statSync(resolved);
+        size = stat.size;
+        if (size > this.maxSnapshotBytes) {
+          tooLarge = true;
+        } else {
+          content = fs.readFileSync(resolved, "utf8");
+        }
+      }
+    } catch {
+      // If file unreadable or permission error, proceed safely
+      existed = false;
+    }
+
+    const id = "snap_" + Date.now() + "_" + crypto.randomBytes(4).toString("hex");
+    const snapshot = {
+      id,
+      sessionId,
+      callId,
+      tool,
+      targetPath: resolved,
+      originalPath: targetPath,
+      existed,
+      content,
+      size,
+      tooLarge,
+      createdAt: Date.now(),
+      rolledBack: false,
+      rolledBackAt: null,
+    };
+
+    this.snapshots.set(id, snapshot);
+
+    if (callId) {
+      this.callIndex.set(callId, id);
+    }
+
+    if (!this.sessionIndex.has(sessionId)) {
+      this.sessionIndex.set(sessionId, []);
+    }
+    const sessionList = this.sessionIndex.get(sessionId);
+    sessionList.push(id);
+
+    // Evict oldest if exceeding maxSnapshotsPerSession
+    if (sessionList.length > this.maxSnapshotsPerSession) {
+      const evictedId = sessionList.shift();
+      if (evictedId) {
+        const evicted = this.snapshots.get(evictedId);
+        if (evicted && evicted.callId) {
+          this.callIndex.delete(evicted.callId);
+        }
+        this.snapshots.delete(evictedId);
+      }
+    }
+
+    return snapshot;
+  }
+
+  /**
+   * Retrieves a snapshot by ID.
+   * @param {string} id
+   * @returns {Record<string, any> | null}
+   */
+  getSnapshot(id) {
+    return this.snapshots.get(id) || null;
+  }
+
+  /**
+   * Retrieves a snapshot by tool callId.
+   * @param {string} callId
+   * @returns {Record<string, any> | null}
+   */
+  getSnapshotByCallId(callId) {
+    const id = this.callIndex.get(String(callId));
+    return id ? this.getSnapshot(id) : null;
+  }
+
+  /**
+   * Retrieves all snapshots for a session.
+   * @param {string} sessionId
+   * @returns {Record<string, any>[]}
+   */
+  getSnapshots(sessionId) {
+    const ids = this.sessionIndex.get(String(sessionId)) || [];
+    const res = [];
+    for (const id of ids) {
+      const snap = this.snapshots.get(id);
+      if (snap) res.push(snap);
+    }
+    return res;
+  }
+
+  /**
+   * Undoes a file change by rolling back to its pre-execution snapshot (#76).
+   * @param {string} snapshotIdOrCallback - Snapshot ID or Call ID
+   * @returns {{ success: boolean, error?: string, snapshotId?: string, targetPath?: string, restoredExisted?: boolean }}
+   */
+  rollbackSnapshot(snapshotIdOrCallback) {
+    if (!snapshotIdOrCallback) {
+      return { success: false, error: "snapshot-id-required" };
+    }
+
+    let snap = this.snapshots.get(snapshotIdOrCallback);
+    if (!snap) {
+      const id = this.callIndex.get(String(snapshotIdOrCallback));
+      if (id) snap = this.snapshots.get(id);
+    }
+
+    if (!snap) {
+      return { success: false, error: "snapshot-not-found" };
+    }
+
+    if (snap.rolledBack) {
+      return { success: false, error: "snapshot-already-rolled-back", snapshotId: snap.id };
+    }
+
+    if (snap.tooLarge) {
+      return { success: false, error: "snapshot-size-limit-exceeded", snapshotId: snap.id };
+    }
+
+    try {
+      if (snap.existed && snap.content !== null) {
+        // Restore previous content
+        const dir = path.dirname(snap.targetPath);
+        if (!fs.existsSync(dir)) {
+          fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(snap.targetPath, snap.content, "utf8");
+      } else if (!snap.existed) {
+        // File was newly created by this call: delete it to undo
+        if (fs.existsSync(snap.targetPath)) {
+          fs.unlinkSync(snap.targetPath);
+        }
+      }
+
+      snap.rolledBack = true;
+      snap.rolledBackAt = Date.now();
+
+      return {
+        success: true,
+        snapshotId: snap.id,
+        targetPath: snap.targetPath,
+        restoredExisted: snap.existed,
+        rolledBackAt: snap.rolledBackAt,
+      };
+    } catch (err) {
+      return {
+        success: false,
+        error: "rollback-io-error",
+        detail: String(err && err.message || err),
+        snapshotId: snap.id,
+      };
+    }
+  }
+
+  /**
+   * Cleans up snapshots for a single session safely (#78).
+   * @param {string} sessionId
+   * @returns {{ cleared: number, sessionId: string }}
+   */
+  clearSnapshots(sessionId) {
+    const sId = String(sessionId || "default");
+    const ids = this.sessionIndex.get(sId) || [];
+    let cleared = 0;
+    for (const id of ids) {
+      const snap = this.snapshots.get(id);
+      if (snap && snap.callId) {
+        this.callIndex.delete(snap.callId);
+      }
+      if (this.snapshots.delete(id)) {
+        cleared++;
+      }
+    }
+    this.sessionIndex.delete(sId);
+    return { cleared, sessionId: sId };
+  }
+
+  /**
+   * Cleans up snapshots globally across all sessions (#78).
+   * @returns {{ cleared: number }}
+   */
+  clearAllSnapshots() {
+    const total = this.snapshots.size;
+    this.snapshots.clear();
+    this.sessionIndex.clear();
+    this.callIndex.clear();
+    return { cleared: total };
+  }
+
+  /**
+   * Returns snapshot usage metrics and statistics.
+   * @returns {{ totalSnapshots: number, sessionCount: number, totalBytes: number }}
+   */
+  getStats() {
+    let totalBytes = 0;
+    for (const snap of this.snapshots.values()) {
+      totalBytes += snap.size || 0;
+    }
+    return {
+      totalSnapshots: this.snapshots.size,
+      sessionCount: this.sessionIndex.size,
+      totalBytes,
+    };
+  }
+}

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.20",
-  "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",
-  "exports": {
-    ".": "./lib/index.js",
-    "./package.json": "./package.json",
-    "./cordis.patch.yml": "./cordis.patch.yml"
-  },
-  "files": [
-    "lib",
-    "rules",
-    "cordis.patch.yml",
-    "README.md",
-    "README.zh.md",
-    "README.ru.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "license": "MIT",
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/schemastery": "^3.18.1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/GooDAnDReaDY/dsh-approval-gate.git"
-  },
-  "homepage": "https://github.com/GooDAnDReaDY/dsh-approval-gate#readme",
-  "bugs": {
-    "url": "https://github.com/GooDAnDReaDY/dsh-approval-gate/issues"
-  },
-  "scripts": {
-    "test": "node --test test/*.test.mjs"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public"
-  },
-  "keywords": [
-    "dsh",
-    "dsh-plugin",
-    "deepseek-harness",
-    "security",
-    "approval-gate",
-    "safety"
-  ]
-}
+{
+  "name": "@goodandready/dsh-approval-gate",
+  "version": "0.1.22",
+  "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",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib",
+    "rules",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "README.ru.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GooDAnDReaDY/dsh-approval-gate.git"
+  },
+  "homepage": "https://github.com/GooDAnDReaDY/dsh-approval-gate#readme",
+  "bugs": {
+    "url": "https://github.com/GooDAnDReaDY/dsh-approval-gate/issues"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "security",
+    "approval-gate",
+    "safety"
+  ]
+}