codex-toolkit 0.4.0

package/src/scope-guard.js

@@ -0,0 +1,180 @@
+// scope-guard — the core hook of codex-toolkit.
+//
+// Problem: AI coding agents (Codex CLI included) tend to expand their action
+// surface beyond the task you actually asked for. "Fix the bug in auth.ts"
+// turns into "while I'm here, let me also reformat 30 unrelated files and
+// rewrite the README." This hook is the line of defense.
+//
+// How it works:
+//   1. You declare the task scope in a config file (see examples/scope-guard.config.example.json).
+//      Examples: { allow: ["src/auth/**", "tests/auth/**"] }
+//   2. When Codex is about to mutate a file, the hook reads the target path
+//      and checks it against the declared scope.
+//   3. If the path is OUT of scope, the hook returns a `deny` decision with
+//      a human-readable reason. Codex's permission system then surfaces that
+//      to the user (or auto-blocks, depending on approval policy).
+//
+// Run modes:
+//   - "enforce"  -> deny out-of-scope edits outright (default)
+//   - "ask"      -> ask the user to confirm out-of-scope edits
+//   - "off"      -> disabled (the hook still logs the decision)
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {
+  DECISIONS,
+  FILE_MUTATING_TOOLS,
+  emitDecision,
+  emitError,
+  extractTargetPath,
+  parseHookInput,
+} from './hook-protocol.js';
+
+const DEFAULT_CONFIG = {
+  mode: 'enforce',
+  allow: ['**/*'],
+  deny: [],
+  log: true,
+};
+
+function loadConfig() {
+  // Config resolution order (closest wins):
+  //   1. $CODEX_TOOLKIT_SCOPE_GUARD_CONFIG  (explicit override)
+  //   2. <cwd>/.codex-toolkit/scope-guard.json
+  //   3. ~/.codex/scope-guard.json
+  const explicit = process.env.CODEX_TOOLKIT_SCOPE_GUARD_CONFIG;
+  const candidates = explicit
+    ? [explicit]
+    : [
+        path.join(process.cwd(), '.codex-toolkit', 'scope-guard.json'),
+        path.join(process.env.HOME || '', '.codex', 'scope-guard.json'),
+      ];
+  for (const file of candidates) {
+    if (!file) continue;
+    try {
+      const raw = fs.readFileSync(file, 'utf8');
+      const parsed = JSON.parse(raw);
+      return { ...DEFAULT_CONFIG, ...parsed, __source: file };
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        emitError(`scope-guard: failed to read config ${file}: ${err.message}`);
+      }
+    }
+  }
+  return { ...DEFAULT_CONFIG, __source: null };
+}
+
+// Minimal glob matching supporting **, *, ? and character classes.
+// We deliberately avoid pulling in a glob library — the scope of codex-toolkit
+// is "small and shippable", and a 30-line matcher covers 99% of real cases.
+function globToRegex(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*';
+        i++;
+        if (glob[i + 1] === '/') i++;
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else if (c === '.') {
+      re += '\\.';
+    } else if ('+(){}|^$\\'.includes(c)) {
+      re += '\\' + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+function matchesAny(target, patterns) {
+  const norm = target.split(path.sep).join('/');
+  return (patterns || []).some((p) => globToRegex(p).test(norm));
+}
+
+function decide(config, targetPath) {
+  if (!targetPath) {
+    return { decision: DECISIONS.ALLOW, reason: null };
+  }
+  if (matchesAny(targetPath, config.deny)) {
+    return {
+      decision: DECISIONS.DENY,
+      reason: `scope-guard: "${targetPath}" matches a deny pattern. Refusing the edit.`,
+    };
+  }
+  if (matchesAny(targetPath, config.allow)) {
+    return { decision: DECISIONS.ALLOW, reason: null };
+  }
+  if (config.mode === 'off') {
+    return { decision: DECISIONS.ALLOW, reason: null };
+  }
+  if (config.mode === 'ask') {
+    return {
+      decision: DECISIONS.ASK,
+      reason: `scope-guard: "${targetPath}" is outside the declared scope ${JSON.stringify(
+        config.allow
+      )}. Approve this out-of-scope edit?`,
+    };
+  }
+  return {
+    decision: DECISIONS.DENY,
+    reason: `scope-guard: "${targetPath}" is outside the declared scope ${JSON.stringify(
+      config.allow
+    )}. Update your .codex-toolkit/scope-guard.json if this edit is intentional.`,
+  };
+}
+
+export function evaluate(event) {
+  const config = loadConfig();
+  if (!FILE_MUTATING_TOOLS.has(event.toolName)) {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+  const target = extractTargetPath(event.toolInput);
+  const result = decide(config, target);
+  if (config.log) {
+    process.stderr.write(
+      `[scope-guard] tool=${event.toolName} target=${target ?? '(none)'} -> ${result.decision}\n`
+    );
+  }
+  return { ...result, config: { ...config, __source: undefined } };
+}
+
+// --- CLI entry point ---------------------------------------------------------
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+async function main() {
+  const raw = await readStdin();
+  const parsed = parseHookInput(raw);
+  if (!parsed.ok) {
+    emitError(`scope-guard: ${parsed.error}`);
+    return;
+  }
+  const result = evaluate(parsed);
+  emitDecision(result.decision, result.reason);
+  if (result.decision === DECISIONS.DENY) {
+    process.exit(2);
+  }
+}
+
+const isMain =
+  import.meta.url === `file://${process.argv[1]}` ||
+  process.argv[1]?.endsWith('scope-guard.js');
+if (isMain) {
+  main().catch((err) => emitError(err.stack || err.message));
+}
+
+export default { evaluate };

package/src/shield-destructive-cmd.js

@@ -0,0 +1,179 @@
+// shield-destructive-cmd — block the small set of shell commands that can
+// destroy a project (or worse, the whole home directory) in one keystroke.
+//
+// Philosophy: the goal is not to be a security product. The goal is to catch
+// the 1% of commands that, if Codex gets the syntax wrong, will take your
+// project with it. We default-deny on the canonical destructive patterns;
+// users can override per-project via config.
+//
+// Triggers on PreToolUse for shell-style tools (Bash, shell, exec).
+// Configuration: <cwd>/.codex-toolkit/shield-destructive-cmd.json
+//   {
+//     "mode": "enforce" | "ask" | "off",
+//     "extra_patterns": ["regex", ...],     // appended to the default list
+//     "allow_overrides": ["regex", ...],    // matched against the FULL command
+//   }
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {
+  DECISIONS,
+  SHELL_TOOLS,
+  emitDecision,
+  emitError,
+  extractShellCommand,
+  parseHookInput,
+} from './hook-protocol.js';
+
+// Default deny list. Each entry is [name, regex, why]. Order does not matter;
+// every matching pattern is reported.
+//
+// We use `(?=\s|$)` (or `(?=\s|;|$)`) at the end of patterns that may
+// terminate on a non-word character such as `~` or `.`. Plain `\b` does not
+// match between two non-word characters (e.g. between `~` and a space), so
+// the standard "end of argument" anchor would miss `rm -rf ~` and similar.
+const DEFAULT_DENY = [
+  ['rm-rf-root', /\brm\s+(-[rRfF]+\s+)*\/(?=\s|$|;)/i, 'recursively deleting root (/)'],
+  ['rm-rf-home', /\brm\s+(-[rRfF]+\s+)*(~|\$HOME|\/Users\/[^/\s]+)(?=\s|$|;)/i, 'recursively deleting the home directory'],
+  ['rm-rf-cwd', /\brm\s+(-[rRfF]+\s+)*\.(?=\s|$|;)/i, 'recursively deleting the current directory'],
+  ['rm-rf-star', /\brm\s+(-[rRfF]+\s+)*\*(?=\s|$|;)/i, 'rm with a bare glob can sweep more than you expect'],
+
+  ['git-force-push', /\bgit\s+push\s+(-[^\s]*\bf\b|--force(-with-lease)?)\b/i, 'force-push rewrites remote history'],
+  ['git-hard-reset', /\bgit\s+reset\s+--hard\b/i, 'hard reset discards uncommitted changes'],
+  ['git-clean-fd', /\bgit\s+clean\s+-[fFdD]+\b/i, 'git clean -fd removes untracked files'],
+
+  ['drop-database', /\bdrop\s+(database|schema)\b/i, 'DROP DATABASE/SCHEMA wipes data'],
+  ['drop-table', /\bdrop\s+table\b/i, 'DROP TABLE wipes a table'],
+  ['truncate', /\btruncate\s+(table\s+)?\w+/i, 'TRUNCATE wipes all rows in a table'],
+
+  ['kubectl-delete-pod', /\bkubectl\s+delete\s+(pod|deployment|namespace|ns)\b(?![^]*--dry-run)/i, 'kubectl delete on a live object (use --dry-run)'],
+  ['docker-system-prune', /\bdocker\s+system\s+prune\s+-a\b/i, 'docker system prune -a removes all stopped containers and images'],
+
+  ['fork-bomb', /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/, 'classic shell fork bomb'],
+  ['dd-zero', /\bdd\s+[^|;&]*\bif=\/dev\/zero\b[^|;&]*\bof=\/dev\/(sd|nvme|disk)\b/i, 'dd of=/dev/sd* with /dev/zero bricks the disk'],
+  ['chmod-777-recursive', /\bchmod\s+-R\s+777\s+\//, 'recursive chmod 777 on / exposes everything'],
+];
+
+const DEFAULT_CONFIG = {
+  mode: 'enforce',
+  extra_patterns: [],
+  allow_overrides: [],
+  log: true,
+};
+
+function loadConfig() {
+  const candidates = [
+    process.env.CODEX_TOOLKIT_SHIELD_DESTRUCTIVE_CONFIG,
+    path.join(process.cwd(), '.codex-toolkit', 'shield-destructive-cmd.json'),
+    path.join(process.env.HOME || '', '.codex', 'shield-destructive-cmd.json'),
+  ].filter(Boolean);
+  for (const file of candidates) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+      return { ...DEFAULT_CONFIG, ...parsed };
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        emitError(`shield-destructive-cmd: failed to read ${file}: ${err.message}`);
+      }
+    }
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+function compileUserPatterns(patterns) {
+  const out = [];
+  for (const p of patterns || []) {
+    try {
+      out.push(new RegExp(p, 'i'));
+    } catch (err) {
+      emitError(`shield-destructive-cmd: invalid pattern "${p}": ${err.message}`);
+    }
+  }
+  return out;
+}
+
+export function evaluate(event) {
+  const config = loadConfig();
+  if (config.mode === 'off') {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+  if (!SHELL_TOOLS.has(event.toolName)) {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+  const command = extractShellCommand(event.toolInput);
+  if (!command) {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+
+  // Allow overrides match the whole command; if any allow matches, the hook
+  // exits early (without consulting the deny list).
+  for (const re of compileUserPatterns(config.allow_overrides)) {
+    if (re.test(command)) {
+      if (config.log) {
+        process.stderr.write(`[shield-destructive-cmd] allowed by override: ${command}\n`);
+      }
+      return { decision: DECISIONS.ALLOW, reason: null, override: true };
+    }
+  }
+
+  // Deny list: built-in + user extras. Collect all matches for the report.
+  const deny = [
+    ...DEFAULT_DENY,
+    ...compileUserPatterns(config.extra_patterns).map((re, i) => [
+      `user-${i}`,
+      re,
+      'matched a user-defined destructive pattern',
+    ]),
+  ];
+  const hits = [];
+  for (const [name, re, why] of deny) {
+    if (re.test(command)) hits.push({ name, why });
+  }
+  if (hits.length === 0) {
+    return { decision: DECISIONS.ALLOW, reason: null };
+  }
+  const summary = hits.map((h) => `  - ${h.name}: ${h.why}`).join('\n');
+  const reason = `shield-destructive-cmd: refused command\n    ${command}\nMatched destructive pattern(s):\n${summary}\nIf this is intentional, set "allow_overrides" in .codex-toolkit/shield-destructive-cmd.json.`;
+  if (config.log) {
+    process.stderr.write(`[shield-destructive-cmd] deny: ${hits.map((h) => h.name).join(', ')}\n`);
+  }
+  if (config.mode === 'ask') {
+    return { decision: DECISIONS.ASK, reason };
+  }
+  return { decision: DECISIONS.DENY, reason };
+}
+
+// --- CLI entry point ---------------------------------------------------------
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+async function main() {
+  const raw = await readStdin();
+  const parsed = parseHookInput(raw);
+  if (!parsed.ok) {
+    emitError(`shield-destructive-cmd: ${parsed.error}`);
+    return;
+  }
+  const result = evaluate(parsed);
+  emitDecision(result.decision, result.reason);
+  if (result.decision === DECISIONS.DENY) {
+    process.exit(2);
+  }
+}
+
+const isMain =
+  import.meta.url === `file://${process.argv[1]}` ||
+  process.argv[1]?.endsWith('shield-destructive-cmd.js');
+if (isMain) {
+  main().catch((err) => emitError(err.stack || err.message));
+}
+
+export default { evaluate };

package/src/shield-env-guard.js

@@ -0,0 +1,192 @@
+// shield-env-guard — block writes to credential and secret files.
+//
+// We catch the canonical accidental-leak patterns: .env files, SSH keys,
+// PEMs, AWS / GCP / npm / pip credential files, and anything that looks
+// like a secrets directory. The deny list is intentionally conservative —
+// "are we sure this isn't a secret?" is a question we want the user to
+// answer explicitly, not the agent.
+//
+// Triggers on PreToolUse for file-mutating tools.
+// Configuration: <cwd>/.codex-toolkit/shield-env-guard.json
+//   {
+//     "mode": "enforce" | "ask" | "off",
+//     "extra_patterns": ["..."],   // append paths/globs to deny
+//     "allow_overrides": ["..."],  // paths/globs explicitly allowed
+//   }
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {
+  DECISIONS,
+  FILE_MUTATING_TOOLS,
+  emitDecision,
+  emitError,
+  extractTargetPath,
+  parseHookInput,
+} from './hook-protocol.js';
+
+// Sensitive path globs. Matched with case-insensitive shell-style globs.
+const DEFAULT_DENY_GLOBS = [
+  // dotenv
+  '.env',
+  '.env.*',
+  '**/.env',
+  '**/.env.*',
+  // SSH keys
+  '**/id_rsa',
+  '**/id_dsa',
+  '**/id_ecdsa',
+  '**/id_ed25519',
+  '**/id_ed25519-sk',
+  '**/id_ecdsa-sk',
+  '**/.ssh/id_*',
+  // PEM / cert / key files (broad)
+  '**/*.pem',
+  '**/*.key',
+  '**/*.p12',
+  '**/*.pfx',
+  // Cloud creds
+  '**/.aws/credentials',
+  '**/credentials.json',
+  '**/gcloud-service-account*.json',
+  '**/service-account*.json',
+  // Package manager tokens
+  '**/.npmrc',
+  '**/.pypirc',
+  '**/.netrc',
+  // Sealed-secrets directories
+  '**/secrets/**',
+  '**/credentials/**',
+  '**/.gnupg/**',
+];
+
+const DEFAULT_CONFIG = {
+  mode: 'enforce',
+  extra_patterns: [],
+  allow_overrides: [],
+  log: true,
+};
+
+function loadConfig() {
+  const candidates = [
+    process.env.CODEX_TOOLKIT_SHIELD_ENV_CONFIG,
+    path.join(process.cwd(), '.codex-toolkit', 'shield-env-guard.json'),
+    path.join(process.env.HOME || '', '.codex', 'shield-env-guard.json'),
+  ].filter(Boolean);
+  for (const file of candidates) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+      return { ...DEFAULT_CONFIG, ...parsed };
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        emitError(`shield-env-guard: failed to read ${file}: ${err.message}`);
+      }
+    }
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+function globToRegex(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*';
+        i++;
+        if (glob[i + 1] === '/') i++;
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else if (c === '.') {
+      re += '\\.';
+    } else if ('+(){}|^$\\'.includes(c)) {
+      re += '\\' + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp('^' + re + '$', 'i');
+}
+
+function compileGlobs(globs) {
+  return (globs || []).map((g) => globToRegex(g));
+}
+
+function matchesAny(target, regexes) {
+  if (!target) return false;
+  const norm = target.split(path.sep).join('/');
+  return regexes.some((re) => re.test(norm));
+}
+
+export function evaluate(event) {
+  const config = loadConfig();
+  if (config.mode === 'off') {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+  if (!FILE_MUTATING_TOOLS.has(event.toolName)) {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+  const target = extractTargetPath(event.toolInput);
+  if (!target) {
+    return { decision: DECISIONS.ALLOW, reason: null };
+  }
+
+  const allowRe = compileGlobs(config.allow_overrides);
+  if (matchesAny(target, allowRe)) {
+    if (config.log) {
+      process.stderr.write(`[shield-env-guard] allowed by override: ${target}\n`);
+    }
+    return { decision: DECISIONS.ALLOW, reason: null, override: true };
+  }
+
+  const denyRe = compileGlobs([...DEFAULT_DENY_GLOBS, ...(config.extra_patterns || [])]);
+  if (!matchesAny(target, denyRe)) {
+    return { decision: DECISIONS.ALLOW, reason: null };
+  }
+  const reason = `shield-env-guard: refused to write to "${target}" — matches a sensitive path (SSH key, .env, cloud cred, package-manager token, or secrets dir). If this is intentional, set "allow_overrides" in .codex-toolkit/shield-env-guard.json.`;
+  if (config.log) {
+    process.stderr.write(`[shield-env-guard] deny: ${target}\n`);
+  }
+  if (config.mode === 'ask') {
+    return { decision: DECISIONS.ASK, reason };
+  }
+  return { decision: DECISIONS.DENY, reason };
+}
+
+// --- CLI entry point ---------------------------------------------------------
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+async function main() {
+  const raw = await readStdin();
+  const parsed = parseHookInput(raw);
+  if (!parsed.ok) {
+    emitError(`shield-env-guard: ${parsed.error}`);
+    return;
+  }
+  const result = evaluate(parsed);
+  emitDecision(result.decision, result.reason);
+  if (result.decision === DECISIONS.DENY) {
+    process.exit(2);
+  }
+}
+
+const isMain =
+  import.meta.url === `file://${process.argv[1]}` ||
+  process.argv[1]?.endsWith('shield-env-guard.js');
+if (isMain) {
+  main().catch((err) => emitError(err.stack || err.message));
+}
+
+export default { evaluate };

package/src/state-store.js

@@ -0,0 +1,91 @@
+// state-store — tiny JSON-file-backed key/value store used by hooks that
+// need to remember things across hook invocations (diff-budget, tool-pace-check).
+//
+// Codex invokes each hook as a fresh subprocess, so any in-memory state would
+// be lost between calls. We persist to a small JSON file under the user's
+// project directory (or CODEX_HOME if no project is found).
+//
+// All operations are atomic-ish: we read, mutate, write to a temp file, then
+// rename. We never partially overwrite. If the file is corrupt, we recover
+// gracefully (treat as empty) and back the bad file up to `.corrupt-<ts>`.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import process from 'node:process';
+
+const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');function defaultStateDir() {
+  // Tests can override the location via CODEX_HOME. In production we prefer
+  // a project-level directory (one .codex-toolkit/ per repo), with CODEX_HOME
+  // as the fallback. Reading CODEX_HOME lazily (each call) so test fixtures
+  // can set the env var *after* importing this module.
+  if (process.env.CODEX_HOME) {
+    try {
+      fs.mkdirSync(process.env.CODEX_HOME, { recursive: true });
+      fs.accessSync(process.env.CODEX_HOME, fs.constants.W_OK);
+      return process.env.CODEX_HOME;
+    } catch {
+      /* fall through to project-level */
+    }
+  }
+  const projectDir = path.join(process.cwd(), '.codex-toolkit');
+  try {
+    fs.mkdirSync(projectDir, { recursive: true });
+    fs.accessSync(projectDir, fs.constants.W_OK);
+    return projectDir;
+  } catch {
+    return CODEX_HOME;
+  }
+}
+
+export function resolveStateFile(name) {
+  const safe = String(name).replace(/[^a-z0-9._-]/gi, '_');
+  return path.join(defaultStateDir(), `${safe}.json`);
+}
+
+export function readState(file) {
+  try {
+    const raw = fs.readFileSync(file, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    // Corrupt file: back it up, treat as empty.
+    try {
+      fs.renameSync(file, `${file}.corrupt-${Date.now()}`);
+    } catch {
+      /* swallow */
+    }
+    return {};
+  }
+}
+
+export function writeState(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+export function updateState(file, mutator, defaultValue = {}) {
+  const current = readState(file);
+  const next = mutator({ ...defaultValue, ...current }) || current;
+  writeState(file, next);
+  return next;
+}
+
+// Best-effort: extract a session/thread id from the event. We tolerate
+// several shapes; if none is present, we fall back to a per-cwd key.
+export function sessionKey(event) {
+  const candidates = [
+    event?.raw?.session_id,
+    event?.raw?.thread_id,
+    event?.raw?.sessionId,
+    event?.raw?.threadId,
+    event?.raw?.conversation_id,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'string' && c.length > 0) return c;
+  }
+  return `cwd:${process.cwd()}`;
+}