@devrik-tools/claude-gates 0.1.2 → 0.2.0

package/plugins/gates/hooks/gates/root-whitelist/index.mjs

@@ -1,111 +1,116 @@
-// root-whitelist — denies creating a new file or folder at the project's ROOT unless it
-// is on the declared whitelist. Migrated from ~/.claude/hooks/guard-root-whitelist.mjs.
-// A root grows orphaned files silently: nothing else stops a stray file from landing next
-// to package.json. Only the top level of the project is governed — anything nested is
-// this gate's business only insofar as its first path segment is the new thing at the root.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   rootFilesWhitelist    root-level file names allowed to be created. Replaces the
-//                         built-in list wholesale.
-//   rootFoldersWhitelist  root-level folder names allowed to be created. Replaces the
-//                         built-in list wholesale.
-// The defaults live here, in the source, so a project reads them and knows exactly what
-// its override replaces. A dotfile/dotfolder (.gitignore, .claude) is always allowed —
-// dotfiles are a different, well-known convention this gate does not police.
-
-import { basename, normalize, sep } from 'node:path';
-import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'root-whitelist';
-const CONFIG_KEY = 'blockPathsOutsideRootWhitelist';
-
-const WRITE_TOOLS = new Set(TOOL_GROUPS.write);
-
-const DEFAULT_ROOT_FILES_WHITELIST = [
-  'AGENTS.md',
-  'CLAUDE.md',
-  'README.md',
-  'LICENSE',
-  'package.json',
-  'package-lock.json',
-  'tsconfig.json',
-  'eslint.config.mjs',
-  'eslint.config.js',
-  'eslint.config.cjs',
-  '.prettierrc',
-  '.prettierrc.json',
-  '.prettierignore',
-  '.eslintignore',
-  'cspell.json',
-  '.cspell.json',
-  '.gitignore',
-  '.env',
-  '.env.example',
-];
-
-const DEFAULT_ROOT_FOLDERS_WHITELIST = [
-  'src',
-  'tests',
-  'docs',
-  'scripts',
-  'plugins',
-];
-
-/** The path a write tool targets, across the field names different tools use. */
-function writeTargetFrom(toolInput) {
-  return String(
-    toolInput.TargetFile ??
-      toolInput.target_file ??
-      toolInput.file_path ??
-      toolInput.path ??
-      '',
-  );
-}
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: true,
-    defaultParams: {
-      rootFilesWhitelist: DEFAULT_ROOT_FILES_WHITELIST,
-      rootFoldersWhitelist: DEFAULT_ROOT_FOLDERS_WHITELIST,
-    },
-  },
-  ({ toolName, toolInput, parameters }) => {
-    if (!WRITE_TOOLS.has(toolName)) return;
-
-    const target = writeTargetFrom(toolInput);
-    if (!target) return;
-
-    const normalized = normalize(target);
-    const projectRoot = process.cwd() + sep;
-
-    // The whitelist describes the project's ROOT. A file outside the project (session
-    // scratchpad, system temp, another repo) is not at its root, and this rule does not
-    // govern it: letting it through is correct, not an exception.
-    if (!normalized.startsWith(projectRoot)) return;
-
-    const relativePath = normalized.slice(projectRoot.length);
-    const filesWhitelist = new Set(parameters.rootFilesWhitelist ?? []);
-    const foldersWhitelist = new Set(parameters.rootFoldersWhitelist ?? []);
-
-    if (!relativePath.includes(sep)) {
-      const fileName = basename(relativePath);
-      if (fileName.startsWith('.') || filesWhitelist.has(fileName)) return;
-      deny(
-        GATE_ID,
-        `'${fileName}' at the project root is not on the whitelist (${[...filesWhitelist].join(', ')}).`,
-      );
-      return;
-    }
-
-    const topDirectory = relativePath.split(sep)[0];
-    if (topDirectory.startsWith('.') || foldersWhitelist.has(topDirectory))
-      return;
-    deny(
-      GATE_ID,
-      `Folder '${topDirectory}' at the project root is not on the whitelist (${[...foldersWhitelist].join(', ')}).`,
-    );
-  },
-);
+// root-whitelist — denies creating a new file or folder at the project's ROOT unless it
+// is on the declared whitelist. Migrated from ~/.claude/hooks/guard-root-whitelist.mjs.
+// A root grows orphaned files silently: nothing else stops a stray file from landing next
+// to package.json. Only the top level of the project is governed — anything nested is
+// this gate's business only insofar as its first path segment is the new thing at the root.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   rootFilesWhitelist    root-level file names allowed to be created. Replaces the
+//                         built-in list wholesale.
+//   rootFoldersWhitelist  root-level folder names allowed to be created. Replaces the
+//                         built-in list wholesale.
+// The defaults live here, in the source, so a project reads them and knows exactly what
+// its override replaces. A dotfile/dotfolder (.gitignore, .claude) is always allowed —
+// dotfiles are a different, well-known convention this gate does not police.
+
+import { basename, isAbsolute, resolve, sep } from 'node:path';
+import { runGate, deny, toolInGroups, writtenPathOf } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'root-whitelist';
+const CONFIG_KEY = 'blockPathsOutsideRootWhitelist';
+
+const DEFAULT_ROOT_FILES_WHITELIST = [
+  'AGENTS.md',
+  'CLAUDE.md',
+  'README.md',
+  'LICENSE',
+  'package.json',
+  'package-lock.json',
+  'tsconfig.json',
+  'eslint.config.mjs',
+  'eslint.config.js',
+  'eslint.config.cjs',
+  '.prettierrc',
+  '.prettierrc.json',
+  '.prettierignore',
+  '.eslintignore',
+  'cspell.json',
+  '.cspell.json',
+  '.gitignore',
+  '.env',
+  '.env.example',
+];
+
+const DEFAULT_ROOT_FOLDERS_WHITELIST = [
+  'src',
+  'tests',
+  'docs',
+  'scripts',
+  'plugins',
+];
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      rootFilesWhitelist: DEFAULT_ROOT_FILES_WHITELIST,
+      rootFoldersWhitelist: DEFAULT_ROOT_FOLDERS_WHITELIST,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!toolInGroups(toolName, ['write'])) return;
+
+    const target = writtenPathOf(toolInput);
+    if (!target) return;
+
+    // Some tools send a path relative to cwd rather than absolute. resolve() leaves an
+    // already-absolute path merely normalized ('..' collapsed, separators fixed), and
+    // resolves a relative one against process.cwd() — so either shape lands on the same
+    // absolute path the root check below expects.
+    const normalized = isAbsolute(target)
+      ? resolve(target)
+      : resolve(process.cwd(), target);
+    const projectRoot = process.cwd() + sep;
+
+    // The whitelist describes the project's ROOT. A file outside the project (session
+    // scratchpad, system temp, another repo) is not at its root, and this rule does not
+    // govern it: letting it through is correct, not an exception. This check runs AFTER
+    // resolving relative paths, so a relative path is judged by where it actually lands.
+    if (!normalized.startsWith(projectRoot)) return;
+
+    const relativePath = normalized.slice(projectRoot.length);
+    // Windows filesystems are case-insensitive: 'Package.json' and 'package.json' are the
+    // same file. Comparing lowercase on both sides avoids denying a whitelisted name that
+    // merely differs in case (a false positive, not a real gap).
+    const filesWhitelist = new Set(
+      (parameters.rootFilesWhitelist ?? []).map((name) => name.toLowerCase()),
+    );
+    const foldersWhitelist = new Set(
+      (parameters.rootFoldersWhitelist ?? []).map((name) => name.toLowerCase()),
+    );
+
+    if (!relativePath.includes(sep)) {
+      const fileName = basename(relativePath);
+      if (fileName.startsWith('.') || filesWhitelist.has(fileName.toLowerCase()))
+        return;
+      deny(
+        GATE_ID,
+        `'${fileName}' at the project root is not on the whitelist (${[...filesWhitelist].join(', ')}).`,
+      );
+      return;
+    }
+
+    const topDirectory = relativePath.split(sep)[0];
+    if (
+      topDirectory.startsWith('.') ||
+      foldersWhitelist.has(topDirectory.toLowerCase())
+    )
+      return;
+    deny(
+      GATE_ID,
+      `Folder '${topDirectory}' at the project root is not on the whitelist (${[...foldersWhitelist].join(', ')}).`,
+    );
+  },
+);

package/plugins/gates/hooks/gates/root-whitelist/root-whitelist.edge.test.mjs

@@ -0,0 +1,97 @@
+// Edge-case audit for root-whitelist: bypasses and false positives.
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, sep } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const GATE = join(dirname(fileURLToPath(import.meta.url)), 'index.mjs');
+
+function project({ config } = {}) {
+  const root = mkdtempSync(join(tmpdir(), 'root-whitelist-edge-'));
+  mkdirSync(join(root, '.git'));
+  if (config) {
+    mkdirSync(join(root, '.ai'));
+    writeFileSync(join(root, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  return {
+    root,
+    run(payload) {
+      const out = execFileSync(process.execPath, [GATE], {
+        input: JSON.stringify(payload),
+        encoding: 'utf8',
+        cwd: root,
+        env: { ...process.env, HOME: root, USERPROFILE: root },
+      });
+      return out.trim() ? JSON.parse(out.trim()) : null;
+    },
+  };
+}
+
+function write(filePath) {
+  return { tool_name: 'Write', tool_input: { file_path: filePath } };
+}
+function mcpTool(name, input) {
+  return { tool_name: name, tool_input: input };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+// ── FIXED: toolInGroups classifies an MCP tool by its action segment, so an MCP write
+// tool creating an orphan root file is now recognized.
+test('FIXED: mcp filesystem write_file creating an orphan root file is now recognized', () => {
+  const { root, run } = project();
+  const result = run(
+    mcpTool('mcp__filesystem__write_file', {
+      path: join(root, 'orphan-mcp.txt'),
+      content: 'x',
+    }),
+  );
+  assert.ok(isDeny(result));
+});
+
+// ── FIXED: a relative (non-absolute) file_path is now resolved against process.cwd()
+// (the test runs the gate with cwd = root) before the root-prefix check, so it is judged
+// by where it actually lands instead of skipping the check entirely.
+test('FIXED: a relative file_path targeting the root is now caught by resolving it against cwd', () => {
+  const { run } = project();
+  const result = run(write('orphan-relative.txt'));
+  assert.ok(isDeny(result));
+});
+
+// ── BUG candidate: path traversal via ../ that resolves back into the root from a
+// nested absolute path, e.g. '<root>/src/../orphan.txt'. normalize() collapses '..'
+// segments, so this SHOULD reduce to '<root>/orphan.txt' and be caught. Confirm.
+test('OK: a traversal path that normalizes back to the root is still caught', () => {
+  const { root, run } = project();
+  const result = run(write(join(root, 'src', '..', 'orphan-traversal.txt')));
+  assert.ok(isDeny(result));
+});
+
+// ── BUG candidate: a whitelisted root FOLDER name used as a FILE at the root, e.g.
+// creating a file literally named 'src' (no extension) at the root. relativePath has no
+// sep, so it goes through the FILE branch and checks filesWhitelist, not
+// foldersWhitelist — 'src' is not in rootFilesWhitelist, so this is correctly denied,
+// not a bug. Confirm.
+test('OK: a root-level file named identically to a whitelisted folder is still denied under the file whitelist', () => {
+  const { root, run } = project();
+  const result = run(write(join(root, 'src')));
+  assert.ok(isDeny(result));
+});
+
+// ── FIXED: case-sensitivity. rootFilesWhitelist/rootFoldersWhitelist membership is now
+// compared lowercase on both sides, so 'Package.json' is recognized as the same entry as
+// the whitelisted 'package.json' — no more false positive on case-insensitive filesystems.
+test('FIXED: a root file matching the whitelist except for letter case is now allowed', () => {
+  const { root, run } = project();
+  const result = run(write(join(root, 'Package.json')));
+  assert.equal(result, null);
+});
+
+// ── BUG candidate: an MCP "write" tool with a `path` field only (not `file_path`,
+// `TargetFile`, or `target_file`) — writeTargetFrom does not recognize `path` alone
+// unless the tool is also in WRITE_TOOLS. Since MCP tools already fail the toolName
+// check, this compounds the same root bug; not a separate one worth a distinct test.

package/plugins/gates/hooks/gates/rule-skill-autodiscovery/index.mjs

@@ -1,99 +1,184 @@
-import { execFileSync } from 'node:child_process';
-import { existsSync, readdirSync } from 'node:fs';
-import { join, relative } from 'node:path';
-import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'rule-skill-autodiscovery';
-const CONFIG_KEY = 'autodiscoverRulesAndSkills';
-
-const DEFAULT_RULES_DIR = 'rules';
-const DEFAULT_GATE_FILE_NAMES = [
-  'gate.mjs',
-  'rules.mjs',
-  'check.mjs',
-  'verify.mjs',
-];
-
-function isGateFile(fileName, gateFileNames) {
-  return gateFileNames.includes(fileName) || fileName.endsWith('.gate.mjs');
-}
-
-function findScriptsIn(scriptsDirectory, gateFileNames) {
-  if (!existsSync(scriptsDirectory)) return [];
-  let entries;
-  try {
-    entries = readdirSync(scriptsDirectory, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries
-    .filter((entry) => entry.isFile())
-    .filter((entry) => /\.(mjs|js)$/.test(entry.name))
-    .filter((entry) => isGateFile(entry.name, gateFileNames))
-    .map((entry) => join(scriptsDirectory, entry.name));
-}
-
-function discoverScripts(projectRoot, rulesDirectoryName, gateFileNames) {
-  const scripts = [
-    ...findScriptsIn(join(projectRoot, rulesDirectoryName), gateFileNames),
-  ];
-
-  const skillsRoot = join(projectRoot, '.claude', 'skills');
-  if (existsSync(skillsRoot)) {
-    let skillDirectories;
-    try {
-      skillDirectories = readdirSync(skillsRoot, {
-        withFileTypes: true,
-      }).filter((entry) => entry.isDirectory());
-    } catch {
-      skillDirectories = [];
-    }
-    for (const skillDirectory of skillDirectories) {
-      scripts.push(
-        ...findScriptsIn(join(skillsRoot, skillDirectory.name), gateFileNames),
-      );
-    }
-  }
-
-  return scripts;
-}
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: false,
-    defaultParams: {
-      rulesDir: DEFAULT_RULES_DIR,
-      gateFileNames: DEFAULT_GATE_FILE_NAMES,
-    },
-  },
-  ({ toolName, parameters }) => {
-    const isExecution = TOOL_GROUPS.execution.includes(toolName);
-    const isDelegation = TOOL_GROUPS.delegation.includes(toolName);
-    if (!isExecution && !isDelegation) return;
-
-    const projectRoot = process.cwd();
-    const scripts = discoverScripts(
-      projectRoot,
-      parameters.rulesDir,
-      parameters.gateFileNames,
-    );
-    if (scripts.length === 0) return;
-
-    for (const script of scripts) {
-      try {
-        execFileSync(process.execPath, [script], {
-          stdio: 'ignore',
-          timeout: 5000,
-        });
-      } catch {
-        deny(
-          GATE_ID,
-          `Sub-gate failed: ${relative(projectRoot, script)}. Fix it before continuing.`,
-        );
-        return;
-      }
-    }
-  },
-);
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join, relative } from 'node:path';
+import { runGate, deny, toolInGroups } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'rule-skill-autodiscovery';
+const CONFIG_KEY = 'autodiscoverRulesAndSkills';
+
+const DEFAULT_RULES_DIR = 'rules';
+const DEFAULT_GATE_FILE_NAMES = [
+  'gate.mjs',
+  'rules.mjs',
+  'check.mjs',
+  'verify.mjs',
+];
+
+function isGateFile(fileName, gateFileNames) {
+  return gateFileNames.includes(fileName) || fileName.endsWith('.gate.mjs');
+}
+
+function findScriptsIn(scriptsDirectory, gateFileNames) {
+  if (!existsSync(scriptsDirectory)) return [];
+  let entries;
+  try {
+    entries = readdirSync(scriptsDirectory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isFile())
+    .filter((entry) => /\.(mjs|js)$/.test(entry.name))
+    .filter((entry) => isGateFile(entry.name, gateFileNames))
+    .map((entry) => join(scriptsDirectory, entry.name));
+}
+
+function discoverScripts(projectRoot, rulesDirectoryName, gateFileNames) {
+  const scripts = [
+    ...findScriptsIn(join(projectRoot, rulesDirectoryName), gateFileNames),
+  ];
+
+  const skillsRoot = join(projectRoot, '.claude', 'skills');
+  if (existsSync(skillsRoot)) {
+    let skillDirectories;
+    try {
+      skillDirectories = readdirSync(skillsRoot, {
+        withFileTypes: true,
+      }).filter((entry) => entry.isDirectory());
+    } catch {
+      skillDirectories = [];
+    }
+    for (const skillDirectory of skillDirectories) {
+      scripts.push(
+        ...findScriptsIn(join(skillsRoot, skillDirectory.name), gateFileNames),
+      );
+    }
+  }
+
+  return scripts;
+}
+
+// ── Security-surface protection ─────────────────────────────────────────────────────
+// A discovered script runs with full Node privileges (no sandbox is realistically
+// enforceable via execFileSync alone). The one privilege it must NEVER have is the
+// power to mutate the gate configuration that governs whether it (or any other gate)
+// runs at all — otherwise a discovered script can disable e.g.
+// `blockDestructiveShellCommands` in the same tool call it was meant to be gated by,
+// before any later gate could react. This is enforced deterministically: snapshot a
+// hash of both config files (project + global) before executing, and after every
+// script runs, compare. Any change is reverted immediately and the call is denied —
+// regardless of whether the script itself exited 0.
+const PROJECT_CONFIG_RELATIVE_PATH = join('.ai', 'config.json');
+
+function globalConfigPath() {
+  return join(homedir(), '.claude', 'claude-gates', 'config.json');
+}
+
+function securityConfigPaths(projectRoot) {
+  return [
+    join(projectRoot, PROJECT_CONFIG_RELATIVE_PATH),
+    globalConfigPath(),
+  ];
+}
+
+/** Reads raw bytes (or null if absent) and their hash, per watched config path. */
+function snapshotConfigs(paths) {
+  return paths.map((path) => {
+    let content = null;
+    try {
+      if (existsSync(path)) content = readFileSync(path);
+    } catch {
+      content = null;
+    }
+    const hash = content
+      ? createHash('sha256').update(content).digest('hex')
+      : null;
+    return { path, content, hash };
+  });
+}
+
+/** Restores every watched config file to its pre-execution content, best-effort. */
+function revertConfigs(snapshots) {
+  for (const snapshot of snapshots) {
+    try {
+      if (snapshot.content === null) {
+        if (existsSync(snapshot.path)) unlinkSync(snapshot.path);
+      } else {
+        writeFileSync(snapshot.path, snapshot.content);
+      }
+    } catch {
+      // Best-effort revert: if this fails there is nothing more this gate can do
+      // beyond having already denied the call.
+    }
+  }
+}
+
+/** Whether any watched config file's content changed since `before`. */
+function configsTampered(before, projectRoot) {
+  const after = snapshotConfigs(before.map((snapshot) => snapshot.path));
+  return before.some((snapshot, index) => snapshot.hash !== after[index].hash);
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      rulesDir: DEFAULT_RULES_DIR,
+      gateFileNames: DEFAULT_GATE_FILE_NAMES,
+    },
+  },
+  ({ toolName, parameters }) => {
+    if (!toolInGroups(toolName, ['execution', 'delegation'])) return;
+
+    const projectRoot = process.cwd();
+    const scripts = discoverScripts(
+      projectRoot,
+      parameters.rulesDir,
+      parameters.gateFileNames,
+    );
+    if (scripts.length === 0) return;
+
+    const watchedConfigPaths = securityConfigPaths(projectRoot);
+
+    for (const script of scripts) {
+      const before = snapshotConfigs(watchedConfigPaths);
+
+      let failed = false;
+      try {
+        execFileSync(process.execPath, [script], {
+          stdio: 'ignore',
+          timeout: 5000,
+        });
+      } catch {
+        failed = true;
+      }
+
+      if (configsTampered(before, projectRoot)) {
+        revertConfigs(before);
+        deny(
+          GATE_ID,
+          `Discovered rule/skill script ${relative(projectRoot, script)} attempted to modify gate security configuration (.ai/config.json or the global config). The change was reverted and the action is blocked.`,
+        );
+        return;
+      }
+
+      if (failed) {
+        deny(
+          GATE_ID,
+          `Sub-gate failed: ${relative(projectRoot, script)}. Fix it before continuing.`,
+        );
+        return;
+      }
+    }
+  },
+);