@netcatty/dsh-guard 0.0.0-stage → 0.2.1

package/lib/preview.js

@@ -0,0 +1,152 @@
+// Human-readable previews for an approval prompt.
+//
+// The gate knows what the call is about to do but a three-button dialog cannot
+// show it. Before asking, this module turns the call into a short text block
+// that says what the file looks like now and what it will look like after —
+// enough to notice "it says it fixes a typo but deletes 40 lines".
+//
+// It never fails an approval: any unexpected argument shape yields no preview
+// rather than an error.
+
+const MAX_CHARS = 1600;
+const MAX_LINES = 6;
+const MAX_READ_BYTES = 128 * 1024;
+
+function lines(text) {
+  return text.split('\n');
+}
+
+function head(list, prefix) {
+  const shown = list.slice(0, MAX_LINES).map((line) => `${prefix} ${line}`).join('\n');
+  const rest = list.length - MAX_LINES;
+  return rest > 0 ? `${shown}\n${prefix} …（还有 ${rest} 行）` : shown;
+}
+
+/** Keep one preview block bounded so a huge rewrite cannot flood the dialog. */
+export function clamp(text) {
+  if (typeof text !== 'string' || text.length <= MAX_CHARS) return text;
+  return `${text.slice(0, MAX_CHARS)}\n…（预览截断）`;
+}
+
+/**
+ * Preview a `write` call: the current file against the content being written.
+ *
+ * @param {{before?: string, after?: string, path?: string}} input
+ * @returns {string} empty string when there is nothing useful to show
+ */
+export function writePreview(input) {
+  const after = input?.after;
+  if (typeof after !== 'string') return '';
+  const path = typeof input?.path === 'string' ? input.path : '文件';
+  const newLines = lines(after);
+  const before = input?.before;
+
+  if (typeof before !== 'string') {
+    return clamp(`新建 ${path}：${newLines.length} 行\n${head(newLines, '+')}`);
+  }
+
+  const oldLines = lines(before);
+  const delta = newLines.length - oldLines.length;
+  const sign = delta >= 0 ? `+${delta}` : String(delta);
+  const parts = [`改写 ${path}：${oldLines.length} → ${newLines.length} 行（${sign}）`];
+
+  // Identical content is worth saying out loud: a "write" that changes nothing
+  // is often a model mistake.
+  if (before === after) return `改写 ${path}：内容与当前完全相同（${newLines.length} 行）`;
+
+  // Showing the first six lines of each side says nothing about a change in the
+  // middle of a file, so window around the actual difference instead.
+  const window = changeWindow(oldLines, newLines);
+  if (window === undefined) {
+    parts.push(`（改动位于第 ${oldLines.length} 行之后）`);
+    return clamp(parts.join('\n'));
+  }
+  parts.push(`@@ 第 ${window.startLine} 行`);
+  for (const line of window.removed) parts.push(`- ${line}`);
+  for (const line of window.added) parts.push(`+ ${line}`);
+  return clamp(parts.join('\n'));
+}
+
+/**
+ * The span that actually differs, with a few lines of context on each side.
+ * Common prefix and suffix are trimmed, so a one-word edit shows the line it
+ * touches rather than the head of the file.
+ *
+ * @param {string[]} a
+ * @param {string[]} b
+ * @param {number} [context]
+ * @returns {{startLine: number, removed: string[], added: string[]} | undefined}
+ */
+export function changeWindow(a, b, context = 3) {
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start += 1;
+  let tailA = a.length - 1;
+  let tailB = b.length - 1;
+  while (tailA >= start && tailB >= start && a[tailA] === b[tailB]) {
+    tailA -= 1;
+    tailB -= 1;
+  }
+  if (start > tailA && start > tailB) return undefined; // identical
+  const from = Math.max(0, start - context);
+  const toA = Math.min(a.length - 1, tailA + context);
+  const toB = Math.min(b.length - 1, tailB + context);
+  return {
+    startLine: from + 1,
+    removed: a.slice(from, toA + 1).slice(0, MAX_LINES * 2),
+    added: b.slice(from, toB + 1).slice(0, MAX_LINES * 2),
+  };
+}
+
+/**
+ * Preview an `edit` call: the exact fragment being replaced.
+ *
+ * @param {{oldString?: string, newString?: string, replaceAll?: boolean, path?: string}} input
+ * @returns {string}
+ */
+export function editPreview(input) {
+  const oldString = input?.oldString;
+  const newString = input?.newString;
+  if (typeof oldString !== 'string' && typeof newString !== 'string') return '';
+  const path = typeof input?.path === 'string' ? input.path : '文件';
+  const scope = input?.replaceAll === true ? '全部匹配' : '一处匹配';
+  const parts = [`编辑 ${path}（${scope}）`];
+
+  if (typeof oldString === 'string' && oldString !== '') {
+    parts.push(`--- 删\n${head(lines(oldString), '-')}`);
+  }
+  if (typeof newString === 'string' && newString !== '') {
+    parts.push(`+++ 增\n${head(lines(newString), '+')}`);
+  }
+  if (typeof oldString === 'string' && oldString === newString) {
+    parts.push('（新旧内容相同）');
+  }
+  return clamp(parts.join('\n'));
+}
+
+/**
+ * Build the preview for one tool call, or '' when the tool is not a file write.
+ *
+ * @param {{name?: string, arguments?: object}} exec
+ * @param {(path: string) => string} readFile bounded file read supplied by the caller
+ * @returns {string}
+ */
+export function previewFor(exec, readFile) {
+  const args = exec?.arguments;
+  if (typeof args !== 'object' || args === null) return '';
+  const path = typeof args.file_path === 'string' ? args.file_path : (typeof args.path === 'string' ? args.path : undefined);
+  if (exec.name === 'write') {
+    const before = path === undefined ? undefined : readFile(path);
+    return writePreview({ before, after: args.content, path });
+  }
+  if (exec.name === 'edit') {
+    return editPreview({
+      oldString: args.old_string,
+      newString: args.new_string,
+      replaceAll: args.replace_all,
+      path,
+    });
+  }
+  return '';
+}
+
+export { MAX_READ_BYTES };

package/lib/shell.js

@@ -0,0 +1,127 @@
+// Lexical shell decomposition for permission matching.
+//
+// Splits one command line into simple commands (pipes, `;`, `&&`, `||`, `&`,
+// newlines), and each into command word, argument tokens and redirect targets.
+// Quote- and escape-aware; NOT a POSIX parser — command substitution, backticks
+// and brace expansion stay opaque.
+
+/**
+ * @typedef {{ command: string, args: string[], redirects: string[] }} SimpleCommand
+ * @typedef {{ commands: SimpleCommand[] }} Decomposition
+ */
+
+/**
+ * @param {string} text
+ * @returns {Decomposition}
+ */
+export function decomposeShellCommand(text) {
+  const commands = [];
+  let words = [];
+  let buffer = '';
+  let started = false;
+  let redirect = false;
+
+  const flush = () => {
+    if (!started) return;
+    words.push({ text: buffer, redirect });
+    buffer = '';
+    started = false;
+    redirect = false;
+  };
+
+  const endCommand = () => {
+    flush();
+    if (words.length === 0) return;
+    const commandIndex = words.findIndex((w) => !w.redirect);
+    const command = commandIndex < 0 ? '' : words[commandIndex].text;
+    const args = [];
+    const redirects = [];
+    words.forEach((word, index) => {
+      if (index === commandIndex) return;
+      if (word.redirect) redirects.push(word.text);
+      else args.push(word.text);
+    });
+    commands.push({ command, args, redirects });
+    words = [];
+  };
+
+  const endWordBeforeRedirect = () => {
+    if (started && /^\d+$/.test(buffer)) {
+      buffer = '';
+      started = false;
+      return;
+    }
+    flush();
+  };
+
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '\\' && process.platform !== 'win32') {
+      buffer += text[i + 1] ?? '\\';
+      started = true;
+      i += 2;
+      continue;
+    }
+    if (ch === "'") {
+      started = true;
+      i += 1;
+      while (i < text.length && text[i] !== "'") buffer += text[i++];
+      i += 1;
+      continue;
+    }
+    if (ch === '"') {
+      started = true;
+      i += 1;
+      while (i < text.length && text[i] !== '"') {
+        const next = text[i + 1];
+        if (text[i] === '\\' && (next === '"' || next === '\\' || next === '$' || next === '`')) {
+          buffer += next;
+          i += 2;
+        } else {
+          buffer += text[i++];
+        }
+      }
+      i += 1;
+      continue;
+    }
+    if (ch === ' ' || ch === '\t' || ch === '\r') {
+      flush();
+      i += 1;
+      continue;
+    }
+    if (ch === '\n') {
+      endCommand();
+      i += 1;
+      continue;
+    }
+    if (ch === ';' || ch === '&' || ch === '|') {
+      const pair = text.slice(i, i + 2);
+      if (pair === '&&' || pair === '||') {
+        endCommand();
+        i += 2;
+        continue;
+      }
+      if (ch === ';' || ch === '&' || ch === '|') {
+        endCommand();
+        i += 1;
+        continue;
+      }
+    }
+    if (ch === '>' || ch === '<') {
+      endWordBeforeRedirect();
+      let op = ch;
+      i += 1;
+      while (i < text.length && (text[i] === '>' || text[i] === '&' || text[i] === '<')) {
+        op += text[i++];
+      }
+      redirect = true;
+      continue;
+    }
+    buffer += ch;
+    started = true;
+    i += 1;
+  }
+  endCommand();
+  return { commands };
+}

package/lib/snapshots.js

@@ -0,0 +1,198 @@
+// Pre-write file snapshots and restore.
+//
+// A `write`/`edit` call is irreversible once it lands: the previous bytes are
+// gone. Before letting one through, dsh-guard copies every regular file the
+// call names into
+//
+//   $DSH_HOME/dsh-plugins/dsh-guard/snapshots/<id>/meta.json
+//   $DSH_HOME/dsh-plugins/dsh-guard/snapshots/<id>/0000.bin
+//
+// `meta.json` records, per file, whether it was `saved`, did not exist yet
+// (`absent`), or was refused as too large / not a regular file (`skipped`).
+// Restore rewrites the saved bytes, deletes the ones that were absent, and
+// reports the skipped ones instead of pretending they came back.
+//
+// The store is bounded by two knobs: `snapshotMaxFiles` per call and
+// `snapshotRetain` directories overall (oldest pruned first).
+
+import { readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+
+export const DEFAULT_MAX_FILES = 20;
+export const DEFAULT_MAX_BYTES = 256 * 1024;
+export const DEFAULT_RETAIN = 100;
+
+function mintId(tool, callId) {
+  const stamp = new Date().toISOString().replace(/[:.]/gu, '-');
+  const suffix = typeof callId === 'string' && callId !== '' ? callId.replace(/[^A-Za-z0-9_-]/gu, '').slice(0, 12) : '';
+  const random = Math.random().toString(16).slice(2, 8);
+  const label = typeof tool === 'string' ? tool.replace(/[^A-Za-z0-9_-]/gu, '').slice(0, 16) : 'tool';
+  return `${stamp}-${label}${suffix === '' ? '' : `-${suffix}`}-${random}`;
+}
+
+/**
+ * Capture the current bytes of every path.
+ *
+ * @param {string} root snapshots directory
+ * @param {{tool?: string, callId?: string, paths: string[], maxFiles?: number, maxBytes?: number, retain?: number}} request
+ * @returns {Promise<{id: string, at: string, tool: string|null, callId: string|null, files: Array<{path: string, status: string, size?: number, file?: string}>, dropped: number} | undefined>}
+ */
+export async function capture(root, request) {
+  const paths = (request.paths ?? []).filter((value) => typeof value === 'string' && value !== '');
+  if (paths.length === 0) return undefined;
+
+  const maxFiles = request.maxFiles ?? DEFAULT_MAX_FILES;
+  const maxBytes = request.maxBytes ?? DEFAULT_MAX_BYTES;
+  const id = mintId(request.tool, request.callId);
+  const dir = join(root, id);
+  const files = [];
+  let dropped = 0;
+
+  try {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    for (const path of paths) {
+      if (files.length >= maxFiles) {
+        dropped += 1;
+        continue;
+      }
+      let stat;
+      try {
+        stat = statSync(path);
+      } catch {
+        files.push({ path, status: 'absent' });
+        continue;
+      }
+      if (!stat.isFile()) {
+        files.push({ path, status: 'skipped' });
+        continue;
+      }
+      if (stat.size > maxBytes) {
+        files.push({ path, status: 'skipped', size: stat.size });
+        continue;
+      }
+      const name = `${String(files.length).padStart(4, '0')}.bin`;
+      try {
+        const bytes = await readFile(path);
+        await writeFile(join(dir, name), bytes, { mode: 0o600 });
+        files.push({ path, status: 'saved', size: bytes.length, file: name });
+      } catch {
+        files.push({ path, status: 'skipped' });
+      }
+    }
+
+    const meta = {
+      id,
+      at: new Date().toISOString(),
+      tool: request.tool ?? null,
+      callId: request.callId ?? null,
+      files,
+      dropped,
+    };
+    await writeFile(join(dir, 'meta.json'), JSON.stringify(meta, null, 2), { mode: 0o600 });
+    prune(root, request.retain ?? DEFAULT_RETAIN);
+    return meta;
+  } catch {
+    // A snapshot that cannot be completed is not worth failing the call over;
+    // drop the half-written directory so it never looks restorable.
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // Best effort.
+    }
+    return undefined;
+  }
+}
+
+/**
+ * Newest-first snapshot index.
+ * @param {string} root
+ * @returns {Array<{id: string, at: string, tool: string|null, paths: string[], saved: number, absent: number, skipped: number}>}
+ */
+export function listSnapshots(root) {
+  let names;
+  try {
+    names = readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const id of names) {
+    try {
+      const meta = JSON.parse(readFileSync(join(root, id, 'meta.json'), 'utf8'));
+      const files = Array.isArray(meta.files) ? meta.files : [];
+      out.push({
+        id,
+        at: typeof meta.at === 'string' ? meta.at : '',
+        tool: typeof meta.tool === 'string' ? meta.tool : null,
+        paths: files.map((file) => file.path),
+        saved: files.filter((file) => file.status === 'saved').length,
+        absent: files.filter((file) => file.status === 'absent').length,
+        skipped: files.filter((file) => file.status === 'skipped').length,
+      });
+    } catch {
+      // Unreadable entry: it is neither listed nor restorable.
+    }
+  }
+  return out.sort((left, right) => (left.at < right.at ? 1 : -1));
+}
+
+/** Keep only the newest `retain` snapshot directories. */
+export function prune(root, retain) {
+  try {
+    const entries = listSnapshots(root);
+    for (const entry of entries.slice(retain)) {
+      rmSync(join(root, entry.id), { recursive: true, force: true });
+    }
+  } catch {
+    // Pruning is housekeeping; never let it break a capture.
+  }
+}
+
+/**
+ * Put one snapshot back.
+ *
+ * @param {string} root
+ * @param {string} id
+ * @returns {Promise<{restored: string[], removed: string[], skipped: string[]}>}
+ */
+export async function restore(root, id) {
+  const dir = join(root, id);
+  const meta = JSON.parse(await readFile(join(dir, 'meta.json'), 'utf8'));
+  const result = { restored: [], removed: [], skipped: [] };
+  for (const file of meta.files ?? []) {
+    if (file.status === 'saved' && typeof file.file === 'string') {
+      const bytes = await readFile(join(dir, file.file));
+      await mkdir(dirname(file.path), { recursive: true });
+      await writeFile(file.path, bytes);
+      try {
+        await chmod(file.path, 0o644);
+      } catch {
+        // Mode restoration is cosmetic.
+      }
+      result.restored.push(file.path);
+    } else if (file.status === 'absent') {
+      await rm(file.path, { force: true });
+      result.removed.push(file.path);
+    } else {
+      result.skipped.push(file.path);
+    }
+  }
+  return result;
+}
+
+/** Absolute paths a write-capable call names. */
+export function snapshotTargets(args) {
+  if (typeof args !== 'object' || args === null) return [];
+  const raw = args.file_path ?? args.path;
+  if (typeof raw !== 'string' || raw === '') return [];
+  return [raw];
+}
+
+/** One line for `/guard-undo list`. */
+export function describeSnapshot(entry) {
+  const when = entry.at === '' ? entry.id : entry.at;
+  const names = entry.paths.map((path) => basename(path)).join(', ');
+  const extra = entry.skipped > 0 ? `  (${entry.skipped} skipped)` : '';
+  return `${entry.id}  ${when}  ${entry.tool ?? 'tool'}  ${names}${extra}`;
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Permission Guard",
+    "description": "allow / ask / deny gates for tool calls across path, shell, params, agents and network, with an approval dialog, pre-write snapshots, audit and rollback."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "权限守卫",
+    "description": "给工具调用加 allow / ask / deny 权限门：路径、命令行、参数、Agent、网络五个面，支持审批弹窗、写前快照、审计与回滚。"
+  }
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@netcatty/dsh-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "allow/ask/deny permission gates for DeepSeek Harness tools: path/params/agents surfaces, argv decomposition, network rules, redaction, grants, dry-run, fail-closed config",
+  "type": "module",
+  "main": "lib/index.js",
+  "license": "MIT",
+  "files": [
+    "lib/index.js",
+    "lib/shell.js",
+    "lib/mask.js",
+    "lib/paths.js",
+    "lib/match.js",
+    "lib/params.js",
+    "lib/snapshots.js",
+    "lib/jsonc.js",
+    "lib/preview.js",
+    "cordis.patch.yml",
+    "policy.json",
+    "policy.schema.json",
+    "README.md",
+    "lib/policy-edit.js",
+    "lib/presets.js",
+    "lib/client.js",
+    "lib/audit-log.js",
+    "lib/diff-view.js",
+    "locale/*.json",
+    "CHANGELOG.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  },
+  "engines": {
+    "dsh": ">=0.2.0"
+  },
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./mask": {
+      "default": "./lib/mask.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./locale/*.json": "./locale/*.json"
+  },
+  "author": "netcatty",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/netcatty/dsh-guard.git"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "permissions",
+    "guard",
+    "security"
+  ],
+  "scripts": {
+    "test": "node --test test/guard.test.mjs test/features.test.mjs test/snapshots.test.mjs test/audit-log.test.mjs test/diff-view.test.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}