@bookedsolid/rea 0.22.0 → 0.23.0

package/dist/hooks/bash-scanner/verdict.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Verdict shape — the contract between the bash-shim hooks and the
+ * `rea hook scan-bash` CLI.
+ *
+ * Stability: this JSON shape is part of the public hook protocol from
+ * 0.23.0 onward. The shim hooks under `hooks/protected-paths-bash-gate.sh`
+ * and `hooks/blocked-paths-bash-gate.sh` shell out to `rea hook scan-bash`
+ * and parse this exact shape with `jq`. Any change here that the bash
+ * shims don't survive is a breaking change — bump the major or stage
+ * with a fallback shape.
+ *
+ * Snapshot tests in `__tests__/hooks/bash-scanner/verdict-shape.test.ts`
+ * lock the wire format to keep this honest.
+ */
+/**
+ * The form of write the walker detected. New shapes can land at the
+ * end; the bash shims do not branch on these — they only forward the
+ * verdict — so adding a new tag is non-breaking.
+ *
+ * Naming convention: `<utility>_<role>` for argv-driven detections,
+ * `redirect` for shell I/O redirects (covers `>`, `>>`, `>|`, `&>`,
+ * fd-prefixed variants), `nested_shell_inner` for unwrapped
+ * `bash -c`/`sh -c` payloads.
+ */
+export type DetectedForm = 'redirect' | 'cp_dest' | 'cp_t_flag' | 'mv_dest' | 'mv_t_flag' | 'tee_arg' | 'sed_i' | 'dd_of' | 'truncate_arg' | 'install_dest' | 'ln_dest' | 'awk_inplace' | 'awk_source' | 'ed_target' | 'ex_target' | 'find_exec_inner' | 'find_exec_placeholder_unresolvable' | 'xargs_unresolvable' | 'parallel_stdin_unresolvable' | 'git_filter_branch_inner' | 'git_rebase_exec_inner' | 'git_bisect_run_inner' | 'git_commit_template' | 'git_rm_dest' | 'git_mv_src' | 'archive_extract_dest' | 'archive_extract_unresolvable' | 'archive_member_dest' | 'archive_create_dest' | 'gzip_compress_dest' | 'cmake_e_dest' | 'mkfifo_dest' | 'mknod_dest' | 'node_e_path' | 'python_c_path' | 'ruby_e_path' | 'perl_e_path' | 'php_r_path' | 'process_subst_inner' | 'nested_shell_inner';
+/**
+ * Source position for a detected write. 1-indexed (matches the parser's
+ * convention) so the operator-facing error message reads naturally.
+ */
+export interface SourcePosition {
+    line: number;
+    col: number;
+}
+/**
+ * The single verdict the scanner returns to its caller. Allow paths
+ * leave reason/hit_pattern/detected_form/source_position unset; block
+ * paths set all four where determinable.
+ *
+ * `parse_failure_reason` is set ONLY when the parser itself rejected
+ * the input — distinct from a successfully-parsed but policy-violating
+ * command. Lets the operator-facing error tell the difference between
+ * "you wrote bad bash" and "you tried to write to .rea/HALT".
+ */
+export interface Verdict {
+    verdict: 'allow' | 'block';
+    reason?: string;
+    hit_pattern?: string;
+    detected_form?: DetectedForm;
+    source_position?: SourcePosition;
+    /**
+     * Set on parse-failure blocks only. Format: parser library's raw
+     * error message verbatim, prefixed with "parser: ". Operators can
+     * paste this into a bug report without further redaction.
+     */
+    parse_failure_reason?: string;
+}
+/** Construct a uniform allow verdict. */
+export declare function allowVerdict(): Verdict;
+/**
+ * Construct a uniform block verdict for a successful-parse + policy
+ * violation. All four explanation fields are required so the operator
+ * gets actionable context.
+ */
+export declare function blockVerdict(args: {
+    reason: string;
+    hitPattern: string;
+    detectedForm: DetectedForm;
+    sourcePosition?: SourcePosition;
+}): Verdict;
+/**
+ * Construct a uniform block verdict for a parse-failure event. We
+ * always block — the alternative is "scanner can't tell, assume safe"
+ * which is the entire bug class this rewrite exists to close.
+ *
+ * `parserMessage` flows through to the operator. We DO NOT sanitize
+ * it — the parser's messages are static (no user-controlled
+ * interpolation in modern mvdan-sh) and including them helps debug
+ * malformed payloads in the field.
+ */
+export declare function parseFailureVerdict(parserMessage: string): Verdict;

package/dist/hooks/bash-scanner/verdict.js

@@ -0,0 +1,49 @@
+/**
+ * Verdict shape — the contract between the bash-shim hooks and the
+ * `rea hook scan-bash` CLI.
+ *
+ * Stability: this JSON shape is part of the public hook protocol from
+ * 0.23.0 onward. The shim hooks under `hooks/protected-paths-bash-gate.sh`
+ * and `hooks/blocked-paths-bash-gate.sh` shell out to `rea hook scan-bash`
+ * and parse this exact shape with `jq`. Any change here that the bash
+ * shims don't survive is a breaking change — bump the major or stage
+ * with a fallback shape.
+ *
+ * Snapshot tests in `__tests__/hooks/bash-scanner/verdict-shape.test.ts`
+ * lock the wire format to keep this honest.
+ */
+/** Construct a uniform allow verdict. */
+export function allowVerdict() {
+    return { verdict: 'allow' };
+}
+/**
+ * Construct a uniform block verdict for a successful-parse + policy
+ * violation. All four explanation fields are required so the operator
+ * gets actionable context.
+ */
+export function blockVerdict(args) {
+    return {
+        verdict: 'block',
+        reason: args.reason,
+        hit_pattern: args.hitPattern,
+        detected_form: args.detectedForm,
+        ...(args.sourcePosition !== undefined ? { source_position: args.sourcePosition } : {}),
+    };
+}
+/**
+ * Construct a uniform block verdict for a parse-failure event. We
+ * always block — the alternative is "scanner can't tell, assume safe"
+ * which is the entire bug class this rewrite exists to close.
+ *
+ * `parserMessage` flows through to the operator. We DO NOT sanitize
+ * it — the parser's messages are static (no user-controlled
+ * interpolation in modern mvdan-sh) and including them helps debug
+ * malformed payloads in the field.
+ */
+export function parseFailureVerdict(parserMessage) {
+    return {
+        verdict: 'block',
+        reason: 'rea: bash parser failed; refusing on uncertainty',
+        parse_failure_reason: `parser: ${parserMessage}`,
+    };
+}

package/dist/hooks/bash-scanner/walker.d.ts

@@ -0,0 +1,165 @@
+/**
+ * AST walker — given a parsed `BashFile`, yield every detected write
+ * target with its form classification and source position.
+ *
+ * The walker is the closed surface this scanner is built around. Every
+ * regex/heuristic the bash gates used (and there were many; see
+ * `hooks/_lib/cmd-segments.sh` and `hooks/_lib/interpreter-scanner.sh`
+ * pre-0.23.0) is replaced here by an AST-driven match. The argument
+ * grammar is already correct because the parser rebuilt the tree from
+ * shell tokenization rules; we never re-tokenize a string.
+ *
+ * Detection forms covered (matching `verdict.ts::DetectedForm`):
+ *
+ *   - `redirect`             — Stmt-level Redirs whose Op is a write
+ *   - `cp_dest` / `cp_t_flag` — POSIX-cp tail destination, plus -t / --target-directory
+ *   - `mv_dest` / `mv_t_flag` — same for mv
+ *   - `tee_arg`              — every non-flag arg to tee
+ *   - `sed_i`                — sed -i / -i'' /-iEXT trailing target
+ *   - `dd_of`                — `of=` named arg
+ *   - `truncate_arg`         — first non-flag arg
+ *   - `install_dest` / `ln_dest` — last positional
+ *   - `awk_inplace`          — awk/gawk -i inplace target
+ *   - `ed_target` / `ex_target` — first non-flag positional
+ *   - `find_exec_inner`      — recurse the inner -exec / -execdir / -ok cmd
+ *   - `xargs_unresolvable`   — xargs is destination-via-stdin; refuse
+ *   - `node_e_path`          — node -e payload string-scanned for fs.write*
+ *   - `python_c_path`        — python -c payload scanned for open(...,'w'/'a')
+ *   - `ruby_e_path`          — ruby -e File.write/.open(...'w')
+ *   - `perl_e_path`          — perl -e open(FH,'>FILE')
+ *   - `process_subst_inner`  — recurse `>(...)` / `<(...)` inner stmts
+ *   - `nested_shell_inner`   — recurse bash -c / sh -c / zsh -c payloads
+ *
+ * Dynamic targets (containing $VAR, `cmd`, $(cmd), arithmetic, etc.)
+ * are emitted with `dynamic: true`. The compositor refuses on dynamic
+ * by default — fail-closed parity with the 0.21.2/0.22.0 sentinel
+ * `__rea_unresolved_expansion__`. Process substitutions and nested
+ * shells are NOT considered dynamic targets themselves; they're
+ * recursed.
+ */
+import type { BashFile } from 'mvdan-sh';
+import type { DetectedForm, SourcePosition } from './verdict.js';
+/**
+ * One detected write. The compositor pairs `path` against the policy
+ * (protected or blocked) to decide allow/block.
+ *
+ * `dynamic: true` means the target's value depends on shell expansion
+ * (`$VAR`, `$(cmd)`, backticks, arithmetic, brace expansion) we did not
+ * fully resolve. Fail-closed semantics: the compositor always BLOCKS
+ * dynamic targets. The detected_form on a dynamic emit is whatever
+ * shape was in argv position.
+ *
+ * `isDirTarget: true` means the target is semantically a directory —
+ * `cp -t DIR ...` / `cp --target-directory=DIR ...` / `install -t DIR
+ * ...` / `mv -t DIR ...` / `ln -t DIR ...`. The matcher treats dir-
+ * targets as `<DIR>/`-shaped: writes INTO that directory may hit any
+ * file under it, so a protected file inside the dir matches even when
+ * the input lacks a trailing slash. Codex round 1 F-7.
+ *
+ * `originSrc` is the bash source-substring for the offending node —
+ * useful when the operator-facing error message wants to show
+ * "Segment: ..." like the bash gates did. It is NOT guaranteed
+ * verbatim from the input (the parser may normalize whitespace);
+ * treat it as best-effort.
+ */
+export interface DetectedWrite {
+    path: string;
+    form: DetectedForm;
+    position: SourcePosition;
+    dynamic: boolean;
+    /**
+     * The target is a directory (the write semantics are "into this
+     * directory"). Set on `cp -t`, `mv -t`, `install -t`, `ln -t`,
+     * `--target-directory=`. False for ordinary file destinations.
+     */
+    isDirTarget?: boolean;
+    /**
+     * The detection is a destructive operation (recursive removal,
+     * unlink, rmdir, find -delete, FileUtils.rm_rf, shutil.rmtree, etc).
+     * Codex round 4 Finding 1: when set, a target that is an ANCESTOR
+     * directory of any protected file matches via protected-ancestry —
+     * `rm -rf .rea` is treated as a write to every file under .rea/.
+     * Without this flag, the scanner only matches exact patterns or
+     * dir-shape inputs (-t flags, trailing slash); plain `.rea` argv
+     * positionals walked unchecked because they are neither.
+     */
+    isDestructive?: boolean;
+    originSrc?: string;
+}
+/**
+ * Walk the AST and return every detected write.
+ *
+ * 0.23.0 round-6 architectural refactor: deny-by-default generic
+ * `syntax.Walk()` traversal. Pre-refactor the walker dispatched on
+ * specific Cmd kinds (`case 'WhileClause':`, `case 'ForClause':`,
+ * `case 'DeclClause':`, etc.) and manually traversed each kind's
+ * specific fields. Any field NOT enumerated in the case branch was
+ * silently dropped — that pattern produced six rounds of P0 bypasses
+ * (DeclClause.Args round 5, CaseClause.Word round 5, WhileClause.Cond
+ * round 6, ForClause.CStyleLoop.Init/Cond/Post round 6, etc).
+ *
+ * The round-6 design closes OUR-DISPATCH field-omission structurally.
+ * We use `mvdan-sh`'s built-in `syntax.Walk(node, visit)` for
+ * traversal — every Cmd kind's inner Stmts / CallExprs / BinaryCmds
+ * reach our dispatcher when Walk descends into them. Our dispatch is
+ * preserved (per-utility cp/mv/sed/find/etc.), but the TRAVERSAL is
+ * no longer a denylist of OUR shapes. A new mvdan-sh Cmd type, or a
+ * new field on an existing Cmd, automatically gets visited from our
+ * side.
+ *
+ * 0.23.0 round-7 P0 closure: the round-6 framing "Walk visits every
+ * field" was OVERCLAIM. mvdan-sh@0.10.1's `syntax.Walk` itself has
+ * field gaps. Empirically verified (see `walk-probe-slice.mjs`):
+ * `ParamExp.Slice.Offset` and `ParamExp.Slice.Length` (Word nodes)
+ * are NOT recursed into by Walk. Pre-fix every `${X:$(...)}` /
+ * `${X:0:$(...)}` / `${arr[@]:$(...)}` / `${@:$(...)}` form bypassed
+ * every detector — a regression vs 0.22.0's bash regex.
+ *
+ * Round-7 fix: this function declares its visitor up front and
+ * manually re-enters `syntax.Walk` on the missed Slice subtrees via
+ * `recurseParamExpSlice` whenever the visitor sees a `ParamExp`. The
+ * re-entry uses the SAME visitor, so nested forms (e.g.
+ * `${X:${Y:$(rm)}}`) recurse to fixed point.
+ *
+ * Round-7 structural pin: the Class O exhaustiveness contract test
+ * (`__tests__/hooks/bash-scanner/walker-exhaustiveness.contract.test.ts`)
+ * names every (node-type, field) Word-bearing position mvdan-sh
+ * populates and asserts the walker reaches each one. If
+ * mvdan-sh@0.11.0+ adds a new node type or field that Walk skips,
+ * that test fails CI before any runtime regression — the fix is
+ * always a one-line manual recursion in the visit callback below.
+ *
+ * What this closes by construction:
+ *   - WhileClause / UntilClause `.Cond` → visited (round 6)
+ *   - ForClause `.CStyleLoop.{Init,Cond,Post}` → visited (round 6)
+ *   - DeclClause `.Args[*].Value` → visited (round 5 redux)
+ *   - CaseClause `.Word` and `.Items[*].Patterns` → visited (round 5 redux)
+ *   - TestClause arbitrary nesting → visited
+ *   - ArithmCmd / LetClause / SelectClause → visited
+ *   - Stmt.Redirs[*].Word with embedded CmdSubst → visited
+ *   - Function bodies, if/else branches, subshells → visited
+ *   - Anything we add in mvdan-sh@0.11.0+ → reaches our dispatcher
+ *     IF Walk visits it; if Walk skips it, Class O fails CI first
+ *
+ * What we still maintain explicitly (because they require argv-level
+ * inspection or string-level re-parse):
+ *   - CallExpr → detector dispatch on the command head
+ *   - Stmt-level redirects (`>`, `>>`, etc.) → emit per redirect Op
+ *   - BinaryCmd pipe-into-bare-shell detection
+ *   - heredoc-into-shell payload re-parse
+ *   - eval / trap / nested-shell payload re-parse
+ *   - ParamExp.Slice.{Offset,Length} → manual Walk re-entry
+ *     (round 7 P0 — Walk's own gap, NOT our dispatch gap)
+ *
+ * The walker NEVER throws on shape oddities — it gracefully ignores
+ * nodes whose shape doesn't match what we expect. Parse-level failures
+ * are upstream (the parser wrapper). Walker-level failures would be a
+ * bug in this file; defensively continue.
+ *
+ * Performance: O(N) over AST nodes; allocation-light. `syntax.Walk`
+ * is a pure-traversal pass that calls our visitor once per node.
+ * Visited-node-set tracking is unnecessary because mvdan-sh's
+ * tree is acyclic by construction (re-parsed payloads are separate
+ * BashFile trees walked via fresh `walkForWrites` invocations).
+ */
+export declare function walkForWrites(file: BashFile): DetectedWrite[];