@netcatty/dsh-guard 0.0.0-stage → 0.2.0

package/lib/jsonc.js

@@ -0,0 +1,140 @@
+// JSON with comments, for hand-edited policy files.
+//
+// A policy is something a person writes and re-reads later, so it needs to
+// explain itself: `// deny everything under ~/.ssh`, a blank line between
+// groups, a trailing comma after the last rule. Strict JSON rejects all three
+// and the error points at a line that looks fine, which is exactly why people
+// stop editing the file.
+//
+// This parser strips `//` and `/* */` comments and a single trailing comma per
+// object/array, then hands the result to `JSON.parse`. It is a character
+// scanner, not a regex: `https://example.com` and `"a // b"` survive because a
+// comment starts only outside a string.
+//
+// Accepted extras are limited to trivia. Anything else — unquoted keys, single
+// quotes, NaN — still fails, so a typo cannot silently become a rule.
+
+/** @param {string} text @returns {string} */
+export function stripJsonc(text) {
+  if (typeof text !== 'string') return text;
+  let out = '';
+  let index = 0;
+  let inString = false;
+  let quote = '"';
+  let inLineComment = false;
+  let inBlockComment = false;
+
+  while (index < text.length) {
+    const ch = text[index];
+    const next = text[index + 1];
+
+    if (inLineComment) {
+      if (ch === '\n') {
+        inLineComment = false;
+        out += ch;
+      }
+      index += 1;
+      continue;
+    }
+    if (inBlockComment) {
+      if (ch === '*' && next === '/') {
+        inBlockComment = false;
+        index += 2;
+        continue;
+      }
+      if (ch === '\n') out += '\n';
+      index += 1;
+      continue;
+    }
+    if (inString) {
+      out += ch;
+      if (ch === '\\') {
+        out += next ?? '';
+        index += 2;
+        continue;
+      }
+      if (ch === quote) inString = false;
+      index += 1;
+      continue;
+    }
+
+    if (ch === '"') {
+      inString = true;
+      quote = ch;
+      out += ch;
+      index += 1;
+      continue;
+    }
+    if (ch === '/' && next === '/') {
+      inLineComment = true;
+      index += 2;
+      continue;
+    }
+    if (ch === '/' && next === '*') {
+      inBlockComment = true;
+      index += 2;
+      continue;
+    }
+    out += ch;
+    index += 1;
+  }
+
+  return removeTrailingCommas(out);
+}
+
+/**
+ * Drop a comma that is followed only by whitespace and a closing bracket.
+ * Done after comment removal, so `[1, // last\n]` is already `[1,\n]`.
+ * @param {string} text
+ * @returns {string}
+ */
+function removeTrailingCommas(text) {
+  let out = '';
+  let index = 0;
+  let inString = false;
+  let quote = '"';
+
+  while (index < text.length) {
+    const ch = text[index];
+    if (inString) {
+      out += ch;
+      if (ch === '\\') {
+        out += text[index + 1] ?? '';
+        index += 2;
+        continue;
+      }
+      if (ch === quote) inString = false;
+      index += 1;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      quote = ch;
+      out += ch;
+      index += 1;
+      continue;
+    }
+    if (ch === ',') {
+      // Look ahead past whitespace for a closing bracket.
+      let look = index + 1;
+      while (look < text.length && /\s/u.test(text[look])) look += 1;
+      if (text[look] === '}' || text[look] === ']') {
+        index += 1;
+        continue;
+      }
+    }
+    out += ch;
+    index += 1;
+  }
+  return out;
+}
+
+/**
+ * Parse a JSONC document.
+ * @param {string} text
+ * @returns {unknown}
+ * @throws {SyntaxError} with the same message JSON.parse would give.
+ */
+export function parseJsonc(text) {
+  return JSON.parse(stripJsonc(text));
+}

package/lib/mask.js

@@ -0,0 +1,22 @@
+// dsh-guard/mask — agent-scope tool masking.
+//
+// Mount this row INSIDE an agent preset (its ctx is the agent scope). It calls
+// ctx.tools.restrict, which is the only way to hide tools from one agent;
+// a profile-root plugin cannot reach that scope.
+//
+// Example preset row:
+//   - id: guard-mask
+//     name: dsh-guard/mask
+//     config: { denyTools: [write, edit] }
+
+export const name = 'guard-mask';
+
+export function apply(ctx, config = {}) {
+  const deny = Array.isArray(config.denyTools) ? config.denyTools : ['write', 'edit'];
+  if (deny.length === 0) return;
+  try {
+    ctx.tools.restrict({ deny });
+  } catch (error) {
+    ctx.logger?.warn?.(`dsh-guard/mask: restrict failed: ${String(error)}`);
+  }
+}

package/lib/match.js

@@ -0,0 +1,119 @@
+// Pattern compilation for dsh-guard rules.
+//
+// Two dialects share one evaluator:
+//   glob  — `*` (greedy, crosses `/`), `?` (one character), everything else
+//           literal. Anchored at both ends.
+//   regex — an unanchored JavaScript regular expression, so `git\s+push`
+//           matches a substring.
+//
+// Glob patterns are bounded by `maxStars`: each run of `*` becomes one `.*`,
+// and a pattern with more than that many runs is refused. `*a*a*a*a` compiles
+// to nested greedy quantifiers that backtrack exponentially on a long
+// non-matching input, so an untrusted rule file must not be able to install it.
+
+const MAX_CACHE = 1024;
+const cache = new Map();
+
+export class PatternError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'PatternError';
+  }
+}
+
+export const DEFAULT_MAX_STARS = 2;
+
+/** Number of unbounded `*` runs in a glob pattern. `**` counts as one run. */
+export function countStarRuns(pattern) {
+  let runs = 0;
+  let inRun = false;
+  for (const ch of pattern) {
+    if (ch === '*') {
+      if (!inRun) runs += 1;
+      inRun = true;
+    } else {
+      inRun = false;
+    }
+  }
+  return runs;
+}
+
+// Structural backtracking guard for regex mode: a quantified group that is
+// itself quantified (`(a+)+`, `(\w*)*`) is the classic ReDoS shape. This is a
+// heuristic, not a proof; the documented rule is "prefer glob for untrusted
+// files".
+const NESTED_QUANTIFIER = /\([^)]*[+*][^)]*\)[+*{]/;
+
+function escapeRegExp(ch) {
+  return ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+
+function compileGlob(pattern, caseInsensitive, maxStars) {
+  const runs = countStarRuns(pattern);
+  if (maxStars > 0 && runs > maxStars) {
+    throw new PatternError(`glob "${pattern}" has ${runs} unbounded '*' runs (max ${maxStars})`);
+  }
+  let out = '^';
+  for (const ch of pattern) {
+    if (ch === '*') out += '.*';
+    else if (ch === '?') out += '.';
+    else out += escapeRegExp(ch);
+  }
+  return new RegExp(out + '$', caseInsensitive ? 'iu' : 'u');
+}
+
+function compileRegex(pattern, caseInsensitive) {
+  if (NESTED_QUANTIFIER.test(pattern)) {
+    throw new PatternError(`regex "${pattern}" nests a quantified group (ReDoS risk)`);
+  }
+  try {
+    return new RegExp(pattern, caseInsensitive ? 'iu' : 'u');
+  } catch (error) {
+    throw new PatternError(`regex "${pattern}" is invalid: ${String(error?.message ?? error)}`);
+  }
+}
+
+/**
+ * Compile one pattern through the cache.
+ * @param {string} pattern
+ * @param {{mode?: 'glob'|'regex', caseInsensitive?: boolean, maxStars?: number}} [options]
+ * @returns {RegExp}
+ */
+export function compile(pattern, options = {}) {
+  const mode = options.mode === 'regex' ? 'regex' : 'glob';
+  const caseInsensitive = options.caseInsensitive === true;
+  const maxStars = options.maxStars ?? DEFAULT_MAX_STARS;
+  const key = `${mode}\u0000${caseInsensitive ? 1 : 0}\u0000${maxStars}\u0000${pattern}`;
+  const hit = cache.get(key);
+  if (hit !== undefined) return hit;
+  const compiled = mode === 'regex'
+    ? compileRegex(pattern, caseInsensitive)
+    : compileGlob(pattern, caseInsensitive, maxStars);
+  if (cache.size >= MAX_CACHE) cache.clear();
+  cache.set(key, compiled);
+  return compiled;
+}
+
+/**
+ * Test one value. Pattern errors are *not* thrown at call time: a rule file
+ * that slipped past validation must not take the whole gate down, so an
+ * uncompilable pattern simply never matches.
+ */
+export function test(pattern, value, options = {}) {
+  if (typeof pattern !== 'string' || typeof value !== 'string') return false;
+  try {
+    return compile(pattern, options).test(value);
+  } catch {
+    return false;
+  }
+}
+
+/** Returns a validation error message, or undefined when the pattern compiles. */
+export function check(pattern, options = {}) {
+  try {
+    compile(pattern, options);
+    return undefined;
+  } catch (error) {
+    return error instanceof PatternError ? error.message : String(error);
+  }
+}

package/lib/params.js

@@ -0,0 +1,105 @@
+// Argument flattening and agent identity for dsh-guard's `params` and `agents`
+// surfaces.
+//
+// `flattenArguments` walks a tool's argument object to a bounded depth and
+// emits one entry per scalar value, carrying two candidate keys: the full
+// dotted path (`arguments.command`, `steps.0.content`) and its last segment
+// (`command`, `content`). A rule may therefore name a key at either granularity
+// — `command` is shorthand, `arguments.command` is the exact path — and get the
+// same value.
+//
+// Numbers and booleans are stringified; arrays contribute an index segment;
+// null/undefined contribute nothing. Depth and count are capped so a hostile
+// or huge argument object cannot turn one tool call into unbounded work.
+
+const MAX_DEPTH = 4;
+const MAX_ENTRIES = 256;
+
+/**
+ * @typedef {{ path: string, key: string, value: string }} ArgumentEntry
+ */
+
+/**
+ * @param {unknown} value
+ * @returns {ArgumentEntry[]}
+ */
+export function flattenArguments(value) {
+  const out = [];
+  walk(value, '', 0, out);
+  return out;
+}
+
+function walk(value, prefix, depth, out) {
+  if (out.length >= MAX_ENTRIES || depth > MAX_DEPTH) return;
+  if (value === null || value === undefined) return;
+
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    const key = prefix === '' ? '' : (prefix.split('.').at(-1) ?? '');
+    out.push({ path: prefix, key, value: String(value) });
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      const child = prefix === '' ? String(index) : `${prefix}.${index}`;
+      walk(value[index], child, depth + 1, out);
+    }
+    return;
+  }
+
+  if (typeof value === 'object') {
+    for (const [name, child] of Object.entries(value)) {
+      if (child === undefined) continue;
+      const path = prefix === '' ? name : `${prefix}.${name}`;
+      walk(child, path, depth + 1, out);
+    }
+  }
+}
+
+/** Candidate keys one entry is matched by, most specific first. */
+export function entryKeys(entry) {
+  if (entry.path === '') return [];
+  const keys = new Set([entry.path]);
+  if (entry.key !== '' && !/^\d+$/u.test(entry.key)) keys.add(entry.key);
+  // Ancestor paths keep array members reachable by their container's name:
+  // `queries.0` is also addressable as the `queries` argument.
+  const parts = entry.path.split('.');
+  for (let length = parts.length - 1; length > 0; length -= 1) {
+    keys.add(parts.slice(0, length).join('.'));
+  }
+  return [...keys];
+}
+
+/**
+ * Stable identity strings for one agent, most specific first. The `agents`
+ * surface evaluates them in this order and the first matching rule wins, so a
+ * `preset:<name>` rule beats the broad `main`/`subagent` fallback.
+ *
+ * `subagent` follows durable session metadata (`origin: 'subagent'`), so a
+ * forked session — which also carries a `parentSession` — is not mistaken for
+ * a delegated child. `preset:<name>` names the agent preset that composed the
+ * session, when the host recorded one.
+ *
+ * @param {any} agent
+ * @returns {string[]}
+ */
+export function agentCandidates(agent) {
+  const meta = agent?.session?.meta;
+  const subagent = meta?.origin === 'subagent' || (typeof meta?.delegationDepth === 'number' && meta.delegationDepth > 0);
+  const preset = typeof meta?.agentPreset === 'string' && meta.agentPreset !== '' ? meta.agentPreset : undefined;
+  const candidates = [];
+  if (preset !== undefined) {
+    candidates.push(`preset:${preset}`);
+    if (subagent) candidates.push(`subagent:${preset}`);
+  }
+  candidates.push(subagent ? 'subagent' : 'main');
+  return candidates;
+}
+
+/** The agent's own reviewable label, used in audit rows. */
+export function agentLabel(agent) {
+  const meta = agent?.session?.meta;
+  const preset = typeof meta?.agentPreset === 'string' ? meta.agentPreset : undefined;
+  const kind = meta?.origin === 'subagent' ? 'subagent' : 'main';
+  return preset === undefined ? kind : `${kind}/${preset}`;
+}

package/lib/paths.js

@@ -0,0 +1,140 @@
+// One directory for every file this plugin owns:
+//   $DSH_HOME/dsh-plugins/dsh-guard/policy.json   the live permission policy
+//   $DSH_HOME/dsh-plugins/dsh-guard/audit.jsonl   decision audit trail
+//   $DSH_HOME/dsh-plugins/dsh-guard/status.json   live status projection
+//
+// `$DSH_HOME/storages/` belongs to the storage backend and the home root belongs
+// to the platform, so every plugin of this author keeps its data under
+// `$DSH_HOME/dsh-plugins/<plugin>/`. `migrateLegacy` moves the files earlier
+// versions wrote into the home root.
+//
+// The repository ships a `policy.json` too, but only as the seed and fallback:
+// user edits belong in the data directory so they neither dirty the checkout
+// nor lose to a `git pull`.
+
+import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const PLUGINS_DIR = 'dsh-plugins';
+export const APP_DIR = 'dsh-guard';
+export const AUDIT_FILE = 'audit.jsonl';
+export const STATUS_FILE = 'status.json';
+export const POLICY_FILE = 'policy.json';
+
+export function dshHome() {
+  const fromEnv = process.env.DSH_HOME;
+  return typeof fromEnv === 'string' && fromEnv !== '' ? fromEnv : join(homedir(), '.dsh');
+}
+
+export function configDir() {
+  return join(dshHome(), PLUGINS_DIR, APP_DIR);
+}
+
+export function auditPath() {
+  return join(configDir(), AUDIT_FILE);
+}
+
+export function statusPath() {
+  return join(configDir(), STATUS_FILE);
+}
+
+/** The live policy: user-owned, inside the data directory. */
+export function policyPath() {
+  return join(configDir(), POLICY_FILE);
+}
+
+/** Pre-write file snapshots, one directory per captured call. */
+export function snapshotsDir() {
+  return join(configDir(), 'snapshots');
+}
+
+/** Where every file this plugin writes lives. Created on demand, owner-only. */
+export function ensureConfigDir() {
+  const dir = configDir();
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+/**
+ * Copy the shipped policy and its schema into the data directory once, when the
+ * user has not written a policy yet. The schema travels with it so the
+ * `"$schema": "./policy.schema.json"` line an editor reads resolves next to the
+ * file. Returns true when a seed was written.
+ */
+export function seedPolicy(builtinPath, log, schemaPath) {
+  const target = policyPath();
+  if (existsSync(target)) return false;
+  try {
+    const raw = readFileSync(builtinPath, 'utf8');
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+    writeFileSync(target, raw, { mode: 0o600 });
+    if (typeof schemaPath === 'string' && schemaPath !== '') {
+      const schemaTarget = join(configDir(), 'policy.schema.json');
+      if (!existsSync(schemaTarget)) {
+        try {
+          writeFileSync(schemaTarget, readFileSync(schemaPath, 'utf8'), { mode: 0o600 });
+        } catch {
+          // A missing schema only costs editor completion.
+        }
+      }
+    }
+    log?.(`dsh-guard: seeded ${target}`);
+    return true;
+  } catch (error) {
+    log?.(`dsh-guard: policy seed failed: ${String(error)}`);
+    return false;
+  }
+}
+
+/** Earlier locations, newest first. */
+export function legacyPaths() {
+  const home = dshHome();
+  return {
+    audit: [join(home, 'guard-audit.jsonl')],
+    status: [join(home, 'guard-status.json')],
+  };
+}
+
+function moveFirst(sources, to) {
+  const from = sources.find((candidate) => existsSync(candidate));
+  if (from === undefined) return null;
+  mkdirSync(dirname(to), { recursive: true, mode: 0o700 });
+  if (existsSync(to)) {
+    // The new file already exists: the old audit trail was written before the
+    // migration and its tail would otherwise be lost. Append, then drop it.
+    try {
+      appendFileSync(to, readFileSync(from));
+      rmSync(from);
+      return from;
+    } catch {
+      return null;
+    }
+  }
+  copyFileSync(from, to);
+  try {
+    // Preserve the owner bits but never wider than 0600: the audit trail can
+    // quote command lines and file paths.
+    chmodSync(to, (statSync(from).mode & 0o700) | 0o600);
+  } catch {
+    // Mode tightening is best-effort; the write path sets 0600 anyway.
+  }
+  try {
+    rmSync(from);
+  } catch {
+    // Leaving the old file behind is harmless: the new one wins.
+  }
+  return from;
+}
+
+/** Move earlier files into the app directory. Returns the sources that moved. */
+export function migrateLegacy(log) {
+  const legacy = legacyPaths();
+  const moved = [];
+  const audit = moveFirst(legacy.audit, auditPath());
+  if (audit !== null) moved.push(audit);
+  const status = moveFirst(legacy.status, statusPath());
+  if (status !== null) moved.push(status);
+  if (moved.length > 0) log?.(`dsh-guard: moved ${moved.length} file(s) to ${configDir()}`);
+  return moved;
+}

package/lib/policy-edit.js

@@ -0,0 +1,74 @@
+// Editing the live policy from a command line.
+//
+// The policy is a nested document: `bash: { "rm *": ask }`, `tools: { "mcp__x__*":
+// { "*/secrets/*": deny } }`, `toolParams: { tool: { key: { value: state } } }`.
+// A `set surface key value` grammar needs three different arities and breaks on
+// any key containing the separator.
+//
+// So the command takes a JSON fragment and deep-merges it. One grammar covers
+// every shape, keys keep their exact spelling, and `null` deletes:
+//
+//   { "bash": { "rm *": "ask" } }
+//   { "toolParams": { "navigate_page": { "url": { "https://prod-*": "deny" } } } }
+//   { "bash": { "rm *": null } }          // remove the rule
+//
+// The merge is applied in memory, validated, and only then written — a bad
+// fragment leaves the file untouched.
+
+/** Deep-merge `patch` into `base`; `null` removes a key. Arrays replace wholesale. */
+export function deepMerge(base, patch) {
+  const out = { ...(base ?? {}) };
+  for (const [key, value] of Object.entries(patch ?? {})) {
+    if (value === null) {
+      delete out[key];
+      continue;
+    }
+    const current = out[key];
+    if (
+      typeof value === 'object' && value !== null && !Array.isArray(value)
+      && typeof current === 'object' && current !== null && !Array.isArray(current)
+    ) {
+      out[key] = deepMerge(current, value);
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Apply one fragment to a policy body.
+ * @param {object} current the current `permission` object
+ * @param {object} patch the JSON fragment
+ * @returns {{ next: object, changed: boolean }}
+ */
+export function applyPatch(current, patch) {
+  if (typeof patch !== 'object' || patch === null || Array.isArray(patch)) {
+    throw new Error('补丁必须是一个 JSON 对象');
+  }
+  const next = deepMerge(current, patch);
+  const changed = JSON.stringify(next) !== JSON.stringify(current);
+  return { next, changed };
+}
+
+/** Short human summary of what a merged policy now says, for the command reply. */
+export function summarize(permission) {
+  const parts = [];
+  for (const [name, value] of Object.entries(permission ?? {})) {
+    if (typeof value === 'string') {
+      parts.push(`${name} = ${value}`);
+      continue;
+    }
+    if (Array.isArray(value)) {
+      parts.push(`${name}: ${value.length} 条`);
+      continue;
+    }
+    if (typeof value === 'object' && value !== null) {
+      const keys = Object.keys(value);
+      parts.push(`${name}: ${keys.length} 条`);
+      continue;
+    }
+    parts.push(`${name} = ${String(value)}`);
+  }
+  return parts.join(' · ');
+}

package/lib/presets.js

@@ -0,0 +1,50 @@
+// Named policy templates.
+//
+// The alternative to a form full of per-category dropdowns: a template is one
+// JSON fragment, applied through the same validated merge as `/guard-policy`,
+// so a template can never write something a hand edit could not. Applying one
+// is additive — it merges into the current policy and leaves everything else
+// alone, so a template narrows or widens one area without erasing the rest.
+//
+// `off` is the exception worth understanding: it sets `enforce: false`, which
+// makes the gate audit-only. Turning enforcement back on is `true`, and a
+// template is the only thing here that touches that switch.
+
+/** @type {Record<string, {summary: string, permission: object}>} */
+export const PRESETS = {
+  baseline: {
+    summary: '外部目录要问、破坏性命令要问、写 .env 拒绝、子代理要问',
+    permission: {
+      externalDirectory: { '*': 'ask' },
+      bash: { 'rm *': 'ask', 'git push *': 'ask', 'sudo *': 'ask' },
+      pathWrite: { '*.env': 'deny' },
+      agents: { subagent: 'ask' },
+      repeatLimit: 5,
+    },
+  },
+  strict: {
+    summary: '所有命令与写入都要问、外部目录拒绝、子代理拒绝',
+    permission: {
+      bash: { '*': 'ask' },
+      pathWrite: { '*': 'ask' },
+      externalDirectory: { '*': 'deny' },
+      agents: { subagent: 'deny' },
+      repeatLimit: 3,
+    },
+  },
+  off: {
+    summary: '只审计不拦截（enforce: false），循环检测关闭',
+    permission: {
+      enforce: false,
+      repeatLimit: 0,
+    },
+  },
+};
+
+export function getPreset(name) {
+  return Object.prototype.hasOwnProperty.call(PRESETS, name) ? PRESETS[name] : undefined;
+}
+
+export function listPresets() {
+  return Object.entries(PRESETS).map(([name, preset]) => `${name.padEnd(10)} ${preset.summary}`);
+}