@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/hooks/block_credential_reads.ts

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard: refuse reading a credential-class file, and refuse a
+ * command that prints the process environment — road-to-one-detector-and-the-
+ * senders-we-own 1.1.
+ *
+ * Prevention ahead of the egress stage: a value that is never read cannot reach
+ * a model provider through any later bug, and everything the session reads goes
+ * into the conversation, so a `.env` read is a `.env` sent. It is a best-effort
+ * guard over the shapes it recognises, not a boundary: it allows what it cannot
+ * decide (`fail_closed: false`), and the residue below is not caught.
+ *
+ * What it refuses, with the class list in `_lib/credential_files.ts` (shared
+ * with the installer's native deny tier):
+ *
+ *   - a file tool (Read, Edit, Grep, …) whose target path is an environment
+ *     file (`.env`, `.env.*`, `.envrc` — `.env.example` and the other template
+ *     names pass), a private key, a cloud or CLI credential file, or a
+ *     package-registry credential file;
+ *   - a shell command that hands such a path — as an argument, a redirect or an
+ *     option value (`--config=.env`) — to anything but a short list of commands
+ *     that neither print nor run it (`ls`, `rm`, `chmod`, …), looking through
+ *     `sudo`/`command`/`nice`-style wrappers, `sh -c`, `eval` and command
+ *     substitutions;
+ *   - a shell command that prints the environment (`env`, `printenv`, a bare
+ *     `export`, a bare `set`, `declare -x`).
+ *
+ * What it allows: a write-only tool (the value is the model's own), a tool that
+ * returns names rather than content (Glob, LS), and a guard it cannot decide —
+ * a malformed envelope or any crash allows (`fail_closed: false`), so this
+ * guard is never the reason an unrelated call fails. Not caught, and recorded
+ * as the residue `tests/fixtures/egress-prevention-gaps/` names: a program that
+ * reads the file itself (`node -e "…readFileSync('.env')"`), a value printed by
+ * a running process, a secret typed by the user — and a search or glob that
+ * never names the file (`Grep path=.`, `grep -r KEY .`, `rg KEY`, `cat .e*`).
+ * The last returns the file's lines as tool output, which is the
+ * `program-output` fixture's channel: the stage sees it, this guard does not.
+ *
+ * Kill switch: `AGENT_CONFIG_ALLOW_CREDENTIAL_READS=1`.
+ *
+ * Only a host that binds `pre_tool_use` AND honours a deny refuses; elsewhere
+ * the dispatcher lowers the block to a warning (`host_semantics.ts`), and
+ * `agent-config hooks:status` answers which applies on the host in use.
+ *
+ * Exit codes (docs/contracts/hook-architecture-v1.md): 0 allow · 1 block.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    CREDENTIAL_CLASS_LABEL,
+    credentialBasename,
+    credentialFileClass,
+    HOST,
+    segmentVerdict,
+    type CredentialFileClass,
+    type PathHost,
+} from '../_lib/credential_files.js';
+import { isEnvKillSwitchActive } from '../_lib/env_kill_switch.js';
+import { invokedSegments } from './git_command_classifier.js';
+import { readHookStdin } from './hook_stdin.js';
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+export const KILL_SWITCH = 'AGENT_CONFIG_ALLOW_CREDENTIAL_READS';
+
+const PATH_KEYS: ReadonlySet<string> = new Set([
+    'file_path', 'path', 'target_file', 'filename', 'filePath', 'notebook_path', 'paths', 'files', 'file_paths',
+]);
+
+/** Every string held under a path key, at any depth and inside arrays. */
+function pathValues(v: JsonValue | undefined, underPathKey: boolean, out: string[]): string[] {
+    if (typeof v === 'string') {
+        if (underPathKey && v !== '') out.push(v);
+    } else if (Array.isArray(v)) {
+        for (const x of v) pathValues(x, underPathKey, out);
+    } else if (isObject(v)) {
+        for (const [k, x] of Object.entries(v)) pathValues(x, underPathKey || PATH_KEYS.has(k), out);
+    }
+    return out;
+}
+
+/** Tools that write a value the model already has, or list names without content. */
+const NON_READING_TOOLS: ReadonlySet<string> = new Set(['write', 'create_file', 'glob', 'ls', 'list_dir', 'file_search']);
+
+function isObject(v: JsonValue | undefined): v is JsonObject {
+    return v !== null && v !== undefined && typeof v === 'object' && !Array.isArray(v);
+}
+
+export interface Refusal {
+    readonly class: CredentialFileClass;
+    readonly what: string;
+}
+
+/** The refusal for one tool call, or null. Pure: the host whose paths are judged is an argument. */
+export function verdictFor(toolName: string, input: JsonObject, host: PathHost = HOST): Refusal | null {
+    const tool = toolName.trim().toLowerCase();
+    if (!NON_READING_TOOLS.has(tool)) {
+        for (const v of pathValues(input, false, [])) {
+            const cls = credentialFileClass(v, host);
+            if (cls !== null) return { class: cls, what: `\`${credentialBasename(v)}\`` };
+        }
+    }
+    const cmd = input['command'];
+    if (typeof cmd === 'string' && cmd !== '') {
+        for (const segment of invokedSegments(cmd)) {
+            const r = segmentVerdict(segment, host);
+            if (r !== null) return r;
+        }
+    }
+    return null;
+}
+
+export function denyMessage(r: Refusal): string {
+    const alternative =
+        r.class === 'process-environment'
+            ? 'Print one variable you need by name, and only one that holds no secret.'
+            : 'Reference the variable by name (`$NAME`, `process.env.NAME`) instead of reading its value; `.env.example` lists the keys.';
+    return (
+        `Blocked: ${r.what} is ${CREDENTIAL_CLASS_LABEL[r.class]}. What a session reads is sent to the model ` +
+        `provider, so a credential read is a credential sent. ${alternative} ` +
+        `(block-credential-reads; maintainer override: ${KILL_SWITCH}=1)\n`
+    );
+}
+
+export function main(): number {
+    if (isEnvKillSwitchActive(KILL_SWITCH)) return 0;
+    let envelope: JsonObject;
+    try {
+        const raw = readHookStdin();
+        if (!raw) return 0;
+        envelope = JSON.parse(raw) as JsonObject;
+    } catch {
+        return 0;
+    }
+    try {
+        const payload = isObject(envelope['payload']) ? envelope['payload'] : envelope;
+        const input = isObject(payload['tool_input']) ? payload['tool_input'] : isObject(envelope['tool_input']) ? envelope['tool_input'] : null;
+        if (input === null) return 0;
+        const rawTool = payload['tool_name'] ?? envelope['tool_name'];
+        const r = verdictFor(typeof rawTool === 'string' ? rawTool : '', input);
+        if (r === null) return 0;
+        process.stderr.write(denyMessage(r));
+        return 1;
+    } catch {
+        return 0;
+    }
+}
+
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/hooks/block_no_verify.ts

@@ -62,6 +62,19 @@ const _GIT_GLOBAL_OPTS_WITH_VALUE: ReadonlySet<string> = new Set([
     '--exec-path',
     '--super-prefix',
 ]);
+/** Refusal fragments shared by the three hook-bypass branches, stored once. */
+const _BYPASSES = ' bypasses git hooks (git-history-discipline).';
+const _REMEDY =
+    ' Let the hooks run and fix what they report; that is the only path this guard leaves open.';
+/**
+ * Builtins where `git <sub> -h` verified short `-n` cannot bypass a hook.
+ * An ALLOWLIST, not a denylist of `commit`/`am`: with `ci = commit` aliased,
+ * `git ci -n` resolves to `ci`, which a denylist would miss. Git never lets
+ * an alias shadow a builtin, so aliases stay blocked. `am` is absent on
+ * purpose — unverified is not safe, and it carries `--no-verify`.
+ */
+const _SHORT_N_UNRELATED =
+    /^(add|branch|cherry-pick|clean|fetch|grep|log|merge|mv|pull|push|rebase|revert|rev-list|rm|shortlog|show|tag)$/;
 const _CONFIG_READ_OR_RESTORE: ReadonlySet<string> = new Set([
     '--get',
     '--get-all',
@@ -258,6 +271,24 @@ function _git_base(tokens: string[]): string[] | null {
     return null;
 }
 
+/**
+ * Index of the subcommand inside `git`'s arguments: the first token that is
+ * neither a global option nor the VALUE of one, so `git -C /repo config …`
+ * resolves to `config` and not to `/repo`. -1 when there is none.
+ */
+function _git_subcommand_index(rest: string[]): number {
+    for (let k = 0; k < rest.length; k += 1) {
+        const tok = rest[k] as string;
+        if (!tok.startsWith('-')) {
+            return k;
+        }
+        if (_GIT_GLOBAL_OPTS_WITH_VALUE.has(tok)) {
+            k += 1; // consume its value
+        }
+    }
+    return -1;
+}
+
 /**
  * `git config … core.hooksPath <value>` — the subcommand form of the hooksPath
  * override, distinct from the `-c` / `--config` global-option form handled in
@@ -281,20 +312,7 @@ function _git_base(tokens: string[]): string[] | null {
  */
 function _is_config_hookspath_write(git_tokens: string[]): [boolean, string] {
     const rest = git_tokens.slice(1);
-    // The subcommand is the first token that is neither a global option nor
-    // the VALUE of one — `git -C /repo config …` must still resolve to
-    // `config`, not to `/repo`.
-    let subIdx = -1;
-    for (let k = 0; k < rest.length; k += 1) {
-        const tok = rest[k] as string;
-        if (!tok.startsWith('-')) {
-            subIdx = k;
-            break;
-        }
-        if (_GIT_GLOBAL_OPTS_WITH_VALUE.has(tok)) {
-            k += 1; // consume its value
-        }
-    }
+    const subIdx = _git_subcommand_index(rest);
     if (subIdx === -1 || rest[subIdx] !== 'config') {
         return [false, ''];
     }
@@ -332,26 +350,32 @@ function _is_blocked(git_tokens: string[]): [boolean, string] {
     if (cfgBlocked) {
         return [cfgBlocked, cfgReason];
     }
+    // The long `--no-verify` stays unscoped below; only the SHORT forms are
+    // read against the subcommand, because only there does `-n` mean
+    // something else. An unresolved subcommand (`git -n`) is not in the set,
+    // so it stays blocked: unresolved is not safe.
+    const rest = git_tokens.slice(1);
+    const subIdx = _git_subcommand_index(rest);
+    const shortNIsUnrelated = subIdx !== -1 && _SHORT_N_UNRELATED.test(rest[subIdx] as string);
     let i = 1; // skip 'git'
     while (i < git_tokens.length) {
         const tok = git_tokens[i] as string;
-        if (_NO_VERIFY_FLAGS.has(tok)) {
-            return [true, `'${tok}' bypasses git hooks (git-history-discipline).`
-                    + ' Let the hooks run and fix what they report; that is the only path this guard leaves open.'];
+        // git resolves any unambiguous prefix of a long option, so `--no-verif`
+        // is `--no-verify`; an ambiguous one git refuses itself.
+        if (_NO_VERIFY_FLAGS.has(tok) || (tok.length > 5 && '--no-verify'.startsWith(tok))) {
+            return [true, `'${tok}'` + _BYPASSES + _REMEDY];
         }
-        if (_NO_VERIFY_SHORT.has(tok)) {
+        if (!shortNIsUnrelated && _NO_VERIFY_SHORT.has(tok)) {
             return [
                 true,
-                `'${tok}' is short for --no-verify and bypasses git hooks (git-history-discipline).`
-                    + ' Let the hooks run and fix what they report; that is the only path this guard leaves open.',
+                `'${tok}' is short for --no-verify and` + _BYPASSES + _REMEDY,
             ];
         }
         // Short flag bundles containing 'n': -nm, -mn, etc.
-        if (/^-[a-zA-Z]*n[a-zA-Z]*$/.test(tok) && !tok.startsWith('--')) {
+        if (!shortNIsUnrelated && /^-[a-zA-Z]*n[a-zA-Z]*$/.test(tok) && !tok.startsWith('--')) {
             return [
                 true,
-                `'${tok}' contains -n (--no-verify) and bypasses git hooks (git-history-discipline).`
-                    + ' Let the hooks run and fix what they report; that is the only path this guard leaves open.',
+                `'${tok}' contains -n (--no-verify) and` + _BYPASSES + _REMEDY,
             ];
         }
         if (tok === '-c') {

package/src/scripts/hooks/block_speaking_inbox_dir.ts

@@ -37,8 +37,9 @@
  * 2. **A directory that already exists.** Blocking every later write into an
  *    already-created speaking directory would wedge a session mid-round without
  *    removing the name — the fix there is a rename, which the deny message of
- *    the creating call already asked for. This is the one filesystem read the
- *    guard performs.
+ *    the creating call already asked for. A path-keyed tool's relative path
+ *    is probed against the tool's own `cwd` and nothing else; a shell
+ *    command's token is probed only when absolute.
  * 3. **An opaque round identifier** — `isOpaqueRoundId` in
  *    `_lib/source_shape.ts` is the single authority, shared with the gate, so
  *    the guard and the CI check can never disagree about what "opaque" means.
@@ -149,11 +150,26 @@ function isGlobOverAcceptableInboxDir(name: string): boolean {
     if (!/[*?[\]]/.test(name)) {
         return false;
     }
-    const literal = name.replace(/[*?]|\[[^\]]*\]/g, '');
+    // Only a generic class is stripped. Any other bracket payload stays in the
+    // literal and is judged: `[acme]` names a source, and so does a run of
+    // singleton ranges like `[a-a][c-c]`.
+    const literal = name.replace(/[*?]|\[(?:a-z|0-9|a-f|0-9a-f|a-z0-9)\]/gi, '');
+    if (OPAQUE_FAMILY_WILDCARD_RE.test(name)) {
+        return true;
+    }
     const trimmed = literal.replace(/-+$/, '');
     return trimmed !== '' && isAcceptableInboxDir(trimmed);
 }
 
+/**
+ * The fixed head of an opaque identifier family followed by wildcards only.
+ * `round-*` lists hex rounds; as a literal it would create `round-*`, which
+ * carries no source. Brackets are excluded because their payload survives as
+ * literal text: `round-[acme]-*` must not pass by stripping to `round`.
+ */
+const OPAQUE_FAMILY_WILDCARD_RE =
+    /^(?:(?:inbox|round|src-set|source-set)(?:-\d{4}(?:-\d{2})?)?|set)-[*?]+$/i;
+
 /**
  * The paths a redirect inside one segment would create.
  *
@@ -348,9 +364,14 @@ export function denyMessage(dir: string): string {
         '  round-a91f3c         content-free hex (also set-, src-set-, source-set-)\n' +
         '  S17                  a set number\n' +
         '\n' +
-        'Record the true source ONCE, encrypted, in the round\'s intake note:\n' +
+        'Record the true source ONCE, encrypted, in the round\'s intake note — the source\n' +
+        'itself (its URL or name), never an agents/tmp path, which this guard judges:\n' +
         "  printf '%s' '<the real source>' | ./scripts-run src/scripts/_lib/link_crypto encrypt\n" +
         '\n' +
+        'Already created? Rename it. Until then, this guard recognizes it in shell commands\n' +
+        'only when referenced by absolute path; relative arguments may resolve elsewhere\n' +
+        'and are judged as new.\n' +
+        '\n' +
         'Naming rule: /analyze:inbox Phase 1. Rule: src/rules/source-confidentiality.md.\n' +
         `Maintainer kill switch: ${KILL_SWITCH}=1.\n`
     );
@@ -380,7 +401,16 @@ export function main(): number {
         if (ti === null) {
             return 0;
         }
-        const repoRoot = typeof envelope['project_dir'] === 'string' ? envelope['project_dir'] : '';
+        // The base a relative path resolves against is the tool's own working
+        // directory: the native payload's `cwd`, where a path-keyed tool's
+        // relative path lands. `project_dir` (no producer sets it)
+        // and the dispatcher's `workspace_root` (the hook's cwd, the parent
+        // checkout in a worktree session) name other trees, and a field that
+        // can outrank the real base lets `mkdir` create in one tree what the
+        // probe found in another — so neither is read. No `cwd` → '' → the
+        // hook process cwd, the behaviour before this field was read.
+        const rawCwd = payload['cwd'];
+        const cwd = typeof rawCwd === 'string' && path.isAbsolute(rawCwd) ? rawCwd : '';
         const rawTool = payload['tool_name'] ?? envelope['tool_name'];
         const toolName = typeof rawTool === 'string' ? rawTool.trim().toLowerCase() : '';
         const candidates: string[] = [];
@@ -402,13 +432,29 @@ export function main(): number {
         // decision logic is shared rather than duplicated — see
         // `creatableTokens` for why "every whitespace token" was too many.
         const cmd = ti['command'] ?? (_isObject(envelope['payload']) ? (envelope['payload'] as JsonObject)['command'] : undefined);
+        // A shell command's relative token gets no exists-probe: whatever it
+        // invokes may change directory first (a script, a function, an alias),
+        // so its existence under `cwd` says nothing about where it lands. An
+        // absolute token names its own base and is probed.
+        const shellTokens: string[] = [];
         if (typeof cmd === 'string' && cmd) {
-            candidates.push(...creatableTokens(cmd));
+            shellTokens.push(...creatableTokens(cmd));
         }
-        for (const v of candidates) {
-            const verdict = verdictFor(v, (p) => fs.existsSync(p), repoRoot);
+        const judge = (v: string, exists: (p: string) => boolean): boolean => {
+            const verdict = verdictFor(v, exists, cwd);
             if (verdict.block && verdict.dir !== null) {
                 process.stderr.write(denyMessage(verdict.dir));
+                return true;
+            }
+            return false;
+        };
+        for (const v of shellTokens) {
+            if (judge(v, (p) => path.isAbsolute(v) && fs.existsSync(p))) {
+                return 1;
+            }
+        }
+        for (const v of candidates) {
+            if (judge(v, (p) => fs.existsSync(p))) {
                 return 1;
             }
         }