@opengsd/gsd-core 1.20.0 → 1.21.0

package/hooks/dist/gsd-secret-read-guard.js

@@ -78,6 +78,19 @@
 //   scans a `<( )` operand; and `find … | xargs cat` infers the upstream
 //   segment's names as the sub-command's read operands.
 //
+// Project exemptions (#4432): `hooks.secret_read_exempt` in the root project's
+// .planning/config.json lists repo-relative files that stay readable. An entry
+// takes effect only for a file that is a regular file on disk AND a regular
+// blob (100644/100755) in the commit HEAD names — read from `.git` directly,
+// no subprocess, no timer (hooks/lib/git-head-tree.js). Read and Grep honor an
+// absolute or cwd-relative path; Bash honors the absolute path only, and only
+// when EVERY command on the line is one of cat/head/tail/grep/egrep/fgrep/rg/
+// wc/diff/cmp/sort/uniq/cut/nl/od (after wrapper resolution) with no `$( )`/
+// backtick/`<( )` body, heredoc or file-writing redirect or option; any other
+// command (mv, ln, cp, git, sh, awk, sed, …) withdraws it for the whole line. A Grep
+// `glob` is never widened, and a colon-joined word (`HEAD:.env.production`)
+// never matches. An unreadable config or repository means no exemption.
+//
 // Grep globs are judged per brace alternative (never on the whole glob, so
 // `{.env.local,zzz.ts}` cannot hide behind a benign sibling): a pure-wildcard
 // alternative (`*`, `**`) is allowed — Grep already skips gitignored files,
@@ -107,7 +120,16 @@
 //   destination exemption can move a link prepared under a non-secret name
 //   onto a secret name (`ln -s .env.example l && mv l .env`), so a later
 //   edit of `.env` lands in the link target — a write redirection, the
-//   out-of-scope write class, not a read.)
+//   out-of-scope write class, not a read. #4432 adds three stated limits to
+//   the project exemptions: (1) an agent with Bash can rewrite local git state
+//   (force-add + commit, `update-ref`) to make a file committed; the
+//   committed-file rule stops the one-step "edit the config, then read" path
+//   and is the same class as the interpreter one-liner gap above — a
+//   guardrail, not a sandbox. (2) The guard vouches for the path, not for
+//   working-tree bytes that differ from HEAD; a content-hash check would block
+//   re-reading the template after each edit, the flow the issue asks for.
+//   (3) A file inside a git submodule cannot be exempted: the submodule's
+//   `.git` is a file the reader does not follow.)
 //
 // A second, unrelated contract is enforced on the Bash leg because this is the
 // one hook that already parses EVERY Bash command (#5214): a Bash command that
@@ -148,6 +170,95 @@ const MAX_NESTING_DEPTH = 3;
 // Brace-alternative budget for a Grep glob before it is denied as too complex.
 const MAX_GLOB_ALTERNATIVES = 64;
 
+// #4432: project exemptions (`hooks.secret_read_exempt` in the ROOT project's
+// .planning/config.json). `root`/`allowRelative` are set once per invocation by
+// the stdin handler; `checker` is built lazily on the first secret-classified
+// token. Any failure while building or calling it means NOT exempt — never an
+// allow, and never a throw into the fail-open crash path.
+const exemption = { root: null, allowRelative: false, checker: null, configured: false, bashLine: null, bashReadOnly: null };
+
+// F3: a Bash exemption holds only when every command on the line is one of
+// these read-only readers; any other command anywhere on the line withdraws it
+// for every token (`mv a b && cat <exempt>` re-anchors or launders the name).
+const READ_ONLY_COMMANDS = new Set([
+  'cat', 'head', 'tail', 'grep', 'egrep', 'fgrep', 'rg', 'wc', 'diff', 'cmp', 'sort', 'uniq', 'cut', 'nl', 'od',
+]);
+
+// Per-command options that write a file or run a program, so the command is
+// not read-only: `sort -o f`, `sort --compress-program`, `rg --pre`.
+function readOnlyOptionsOnly(base, operands) {
+  let positional = 0;
+  for (const w of operands) {
+    const t = w.text;
+    if (base === 'sort' && (/^-[A-Za-z]*o/.test(t) || /^--(output|compress-program|files0-from)/.test(t))) return false;
+    if (base === 'rg' && /^--(pre|pre-glob|hostname-bin)(=|$)/.test(t)) return false;
+    if (base === 'uniq' && !t.startsWith('-')) positional++;
+  }
+  return base !== 'uniq' || positional <= 1; // `uniq in out` writes `out`
+}
+
+// Fail closed: a substitution body, heredoc, process substitution, file
+// redirect out, unresolved or unlisted command word, or any exception is false.
+function lineIsReadOnly(command) {
+  try {
+    const { tokens, nested } = tokenize(command);
+    if (nested.length > 0) return false;
+    const bySeg = new Map();
+    for (const t of tokens) {
+      if (t.kind === 'heredoc') return false;
+      if (t.kind === 'sep') continue;
+      if (t.kind === 'word' && t.procsub !== undefined) return false;
+      if (!bySeg.has(t.seg)) bySeg.set(t.seg, []);
+      bySeg.get(t.seg).push(t);
+    }
+    for (const segTokens of bySeg.values()) {
+      const words = [];
+      for (let k = 0; k < segTokens.length; k++) {
+        const t = segTokens[k];
+        if (t.kind === 'op') {
+          if (t.dup) continue;
+          const target = segTokens[k + 1];
+          if (!target || target.kind !== 'word') return false;
+          k++;
+          if (!t.read && target.text !== '/dev/null') return false; // output to a file
+          if (t.text.endsWith('<<<')) return false;
+          continue;
+        }
+        words.push(t);
+      }
+      if (words.length === 0) return false;
+      const cmd = resolveCommand(words);
+      if (!cmd || !READ_ONLY_COMMANDS.has(cmd.base)) return false;
+      if (!readOnlyOptionsOnly(cmd.base, cmd.operands)) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isExemptSecret(tok) {
+  if (exemption.root === null) return false;
+  if (exemption.bashLine !== null) {
+    if (exemption.bashReadOnly === null) exemption.bashReadOnly = lineIsReadOnly(exemption.bashLine);
+    if (exemption.bashReadOnly !== true) return false;
+  }
+  try {
+    if (exemption.checker === null) {
+      const lib = require('./lib/secret-read-exemptions.js');
+      const entries = lib.readExemptEntries(exemption.root);
+      exemption.configured = entries.length > 0;
+      exemption.checker = entries.length === 0
+        ? () => false
+        : lib.createExemptionChecker({ root: exemption.root, entries, allowRelative: exemption.allowRelative });
+    }
+    return exemption.checker(tok) === true;
+  } catch {
+    exemption.checker = () => false;
+    return false;
+  }
+}
+
 // `.env.<suffix>` names that are templates, not secrets (case-insensitive).
 const NON_SECRET_ENV_SUFFIXES = new Set(['example', 'sample', 'template', 'dist']);
 
@@ -163,8 +274,11 @@ const NON_SECRET_ENV_SUFFIXES = new Set(['example', 'sample', 'template', 'dist'
 // stdbuf(1), setsid(1) and bash's `command`/`exec`. A wrong entry fails open
 // (the option's value becomes the command word), so keep it to the man pages.
 const WRAPPERS = new Map([
-  ['sudo', { short: 'CDghpRrTtUu', long: ['--close-from', '--chdir', '--group', '--host', '--prompt', '--chroot', '--role', '--command-timeout', '--type', '--other-user', '--user'] }],
-  ['doas', { short: 'Cu' }],
+  ['sudo', { short: 'aCcDghpRrTtUu', long: ['--auth-type', '--close-from', '--login-class', '--chdir', '--group', '--host', '--prompt', '--chroot', '--role', '--command-timeout', '--type', '--other-user', '--user'],
+    // No-value long options, so an exact one never prefix-matches a longer
+    // valued one (`--login` vs `--login-class`).
+    flags: ['--askpass', '--background', '--bell', '--edit', '--help', '--list', '--login', '--non-interactive', '--preserve-env', '--preserve-groups', '--remove-timestamp', '--reset-timestamp', '--set-home', '--shell', '--stdin', '--validate', '--version'] }],
+  ['doas', { short: 'aCu' }],
   ['env', { short: 'uCSaP', long: ['--unset', '--chdir', '--split-string', '--argv0'], assigns: true }],
   ['nice', { short: 'n', long: ['--adjustment'] }],
   ['nohup', {}],
@@ -309,7 +423,7 @@ function isSecretBasename(name) {
 // lower case once at the top so `.ENV` / `.Secrets` match on the
 // case-insensitive filesystems (macOS, Windows) where they ARE the secret file
 // — the same stance as the write guard's `/i` patterns.
-function namesSecret(tok) {
+function namesSecretByName(tok) {
   if (typeof tok !== 'string' || tok === '') return false;
   const lower = tok.toLowerCase();
   if (isSecretBasename(lastSegment(lower))) return true;
@@ -317,6 +431,15 @@ function namesSecret(tok) {
   return colon !== -1 && isSecretBasename(lastSegment(lower.slice(colon + 1)));
 }
 
+// A secret-by-name token is still allowed when the project listed that exact
+// committed file under `hooks.secret_read_exempt` (#4432). The exemption is
+// consulted only on the secret-classified branch, so an ordinary token costs
+// no I/O.
+function namesSecret(tok) {
+  if (!namesSecretByName(tok)) return false;
+  return !isExemptSecret(tok);
+}
+
 // ---------------------------------------------------------------------------
 // Grep glob analysis
 // ---------------------------------------------------------------------------
@@ -886,7 +1009,9 @@ const GROUPING_SEPS = new Set(['(', ')', '{', '}']);
 function wrapperOptionWidth(word, spec) {
   if (word.startsWith('--')) {
     if (word.includes('=')) return 1;
-    // getopt_long accepts any unambiguous prefix (`--adj 5`).
+    // getopt_long takes an exact match over any longer option it prefixes
+    // (`sudo --login` is not `--login-class`), else any unambiguous prefix (`--adj 5`).
+    if ((spec.flags || []).includes(word)) return 1;
     return word.length > 2 && (spec.long || []).some((l) => l.startsWith(word)) ? 2 : 1;
   }
   const valued = spec.short || '';
@@ -1410,7 +1535,10 @@ function reasonFor(code, tool, target) {
   return `Secret read guard: ${tool} would read '${target}', which matches a protected secret-file ` +
     `pattern (${PATTERN_TEXT}). Secret values must not be read into the conversation. ` +
     'If you need a specific value, ask the user for it; if you need the variable NAMES, ' +
-    'read the non-secret template (.env.example) instead.';
+    'read the non-secret template (.env.example) instead.' +
+    (tool === 'Bash' && exemption.configured
+      ? ' Files the project lists under hooks.secret_read_exempt are readable from Bash only by their absolute path.'
+      : '');
 }
 
 // stdout gets the typed JSON block; stderr gets the plain reason string
@@ -1532,6 +1660,12 @@ process.stdin.on('end', () => {
       allow(undefined);
     }
 
+    // #4432: exemptions resolve against the payload cwd (as the context
+    // monitor does), else the process cwd. Bash honors absolute paths only: a
+    // relative word there is re-anchored by cd/find/xargs/git -C.
+    exemption.root = typeof data.cwd === 'string' && data.cwd !== '' ? data.cwd : process.cwd();
+    exemption.allowRelative = tool === 'Read' || tool === 'Grep';
+
     // Every payload field is read TYPED in a single statement (#2547 class):
     // `[]`/`{}` are truthy and a non-string degrades to '' here.
     if (tool === 'Read') {
@@ -1556,6 +1690,7 @@ process.stdin.on('end', () => {
     const command = typeof data.tool_input.command === 'string' ? data.tool_input.command : '';
     if (command === '') allow(undefined);
     if (command.length > MAX_COMMAND_LENGTH) emitBlock('command-too-large', tool, '');
+    exemption.bashLine = command;
     const hit = findSecretRead(command, 0) || findSecretReadUnderOtherReadings(command);
     if (hit !== null) emitBlock('secret-read', tool, hit);
     const spawn = findDebuggerCliSpawn(command, 0);

package/hooks/dist/gsd-statusline.js

@@ -18,6 +18,7 @@ const os = require('os');
 // monkeypatching childProcess.execFileSync.
 const childProcess = require('child_process');
 const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
+const { readConfigFileBounded } = require('./lib/config-read.js');
 const { gitEnv } = require('./lib/git-probe.js');
 
 // This hook's build-seam outer catch (require.main guard just below) has
@@ -81,7 +82,7 @@ function readGsdConfig(dir) {
     const candidate = path.join(current, '.planning', 'config.json');
     if (fs.existsSync(candidate)) {
       try {
-        return JSON.parse(fs.readFileSync(candidate, 'utf8')) || {};
+        return JSON.parse(readConfigFileBounded(candidate, { required: true })) || {};
       } catch (e) {
         return {};
       }
@@ -254,7 +255,7 @@ const SETTINGS_FILE_MAX_BYTES = 1024 * 1024;
 function readSettingsFile(file) {
   let fd;
   try {
-    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK || 0));
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK || 0) | (fs.constants.O_NOCTTY || 0));
     const st = fs.fstatSync(fd);
     if (!st.isFile() || st.size > SETTINGS_FILE_MAX_BYTES) return null;
     // One byte past the checked size, so growth after the check shows as a longer read.

package/hooks/dist/gsd-workflow-guard.js

@@ -22,6 +22,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { tokenize, skipToSubcommand } = require('./lib/git-cmd.js');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
+const { readConfigFileBounded } = require('./lib/config-read.js');
 const { reportIfUndetermined, gitEnv, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // This guard is almost entirely advisory (fail open — a broken advisory must
@@ -179,7 +180,7 @@ function workflowGuardEnabled(cwd) {
   const configPath = path.join(cwd, '.planning', 'config.json');
   if (!fs.existsSync(configPath)) return false;
   try {
-    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const config = JSON.parse(readConfigFileBounded(configPath, { required: true }));
     return Boolean(config.hooks?.workflow_guard);
   } catch (e) {
     return false;

package/hooks/dist/lib/config-read.js

@@ -0,0 +1,49 @@
+'use strict';
+// hooks/lib/config-read.js — the one bounded reader for a project config.json used by every
+// hook (#5759). Hooks are standalone files staged at install, so this mirrors the built
+// gsd-core/bin/lib/config-file-read.cjs (a test pins that the two caps agree) instead of
+// requiring it.
+//
+// A config.json planted as a FIFO or device blocks a plain readFileSync forever, and a hook
+// runs inside the user's session on every tool call. The file is opened non-blocking and
+// checked through its own descriptor (O_NONBLOCK is absent on Windows, hence `|| 0`).
+const fs = require('node:fs');
+
+const CONFIG_MAX_BYTES = 1024 * 1024;
+
+function coded(message, code) {
+  return Object.assign(new Error(message), { code });
+}
+
+/**
+ * The UTF-8 text of `file`. A file that is absent returns null, or — with `{ required: true }` —
+ * throws an error with code ENOENT, so a caller that already treats any throw as "no usable
+ * config" keeps its exact semantics. A FIFO/device (ENXIO), directory (EISDIR), file over
+ * CONFIG_MAX_BYTES (EFBIG) or any other failure always throws with `.code` set.
+ */
+function readConfigFileBounded(file, options) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK || 0) | (fs.constants.O_NOCTTY || 0));
+  } catch (err) {
+    if (err && err.code === 'ENOENT' && !(options && options.required)) return null;
+    throw err;
+  }
+  try {
+    const st = fs.fstatSync(fd);
+    if (!st.isFile()) throw coded(`${file} is not a regular file`, st.isDirectory() ? 'EISDIR' : 'ENXIO');
+    if (st.size > CONFIG_MAX_BYTES) throw coded(`${file} exceeds ${CONFIG_MAX_BYTES} bytes`, 'EFBIG');
+    const buf = Buffer.allocUnsafe(st.size);
+    let off = 0;
+    while (off < st.size) {
+      const n = fs.readSync(fd, buf, off, st.size - off, off);
+      if (n <= 0) break;
+      off += n;
+    }
+    return buf.toString('utf8', 0, off);
+  } finally {
+    try { fs.closeSync(fd); } catch (e) { /* already closed */ }
+  }
+}
+
+module.exports = { CONFIG_MAX_BYTES, readConfigFileBounded };

package/hooks/dist/lib/git-cmd.js

@@ -49,6 +49,8 @@ const ARGUMENT_TAKING_FLAGS = new Set([
   '--man-path',
   '--info-path',
   '--list-cmds',
+  '--config-env',      // config from an env var: `--config-env=k=V` or `--config-env k=V` (#5821)
+  '--attr-source',     // tree-ish for attributes: `--attr-source=T` or `--attr-source T` (#5821)
 ]);
 
 /**
@@ -59,7 +61,7 @@ const BOOLEAN_FLAGS = new Set([
   '--no-replace-objects', '--bare',
   '--literal-pathspecs', '--glob-pathspecs', '--noglob-pathspecs',
   '--icase-pathspecs', '--no-optional-locks',
-  '-P', '--no-lazy-fetch',
+  '-P', '--no-lazy-fetch', '--no-advice',
   '--version', '--help',
 ]);