@bookedsolid/rea 0.31.0 → 0.33.0

package/dist/hooks/_lib/payload.js

@@ -0,0 +1,245 @@
+/**
+ * Shared stdin payload primitive for the Node-binary hook tier.
+ *
+ * 0.32.0 — extracts the `INPUT=$(cat) ; jq -r '.tool_input.command'`
+ * pattern that every bash hook in `hooks/` repeats. The Node-binary
+ * scan-bash already does this work in `runHookScanBash` (lines 225-258
+ * of `src/cli/hook.ts`); the Phase 1 pilots landing in 0.32.0 need
+ * the same primitive without copy-pasting the parsing + type-guard +
+ * fail-closed-on-malformed-JSON dance into each new hook.
+ *
+ * The shape mirrors the bash hooks' contract verbatim:
+ *
+ *   - `tool_input.command` is the only field we read; bash hooks only
+ *     ever ran `jq -r '.tool_input.command // ""'` against this payload.
+ *   - `tool_name` is also surfaced because two bash hooks
+ *     (`pr-issue-link-gate.sh` and `security-disclosure-gate.sh`)
+ *     short-circuit when the tool isn't `Bash`.
+ *
+ * Failure modes:
+ *
+ *   - Empty stdin → `{ command: '', toolName: '' }`. The bash hooks
+ *     allow on empty command (`[[ -z "$CMD" ]] && exit 0`); the Node
+ *     port preserves this by returning empty strings rather than
+ *     throwing.
+ *   - Malformed JSON → throws `MalformedPayloadError`. The caller
+ *     decides whether to fail-closed (block) or fail-open (allow);
+ *     `runHookScanBash` chose fail-closed (block) and the Phase 1
+ *     pilots match that posture for consistency.
+ *   - `tool_input.command` is non-string → throws `TypePayloadError`.
+ *     A crafted payload like `{"tool_input":{"command":["rm","-rf"]}}`
+ *     would silently coerce to `''` if we used `String(c)`; that
+ *     would translate into a free allow. Refuse instead.
+ */
+import { Buffer } from 'node:buffer';
+/**
+ * Thrown when stdin contains content that is not valid JSON.
+ *
+ * Distinct error class so callers can `instanceof` discriminate without
+ * leaning on string matching of the message.
+ */
+export class MalformedPayloadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MalformedPayloadError';
+    }
+}
+/**
+ * Thrown when the JSON parses but `tool_input.command` is present and
+ * has the wrong type (anything other than `string` / `undefined`).
+ */
+export class TypePayloadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TypePayloadError';
+    }
+}
+/**
+ * Parse a Claude Code PreToolUse stdin payload. Pure function — no I/O.
+ *
+ * @param raw Bytes / string read from the hook's stdin (the `INPUT=$(cat)`
+ *            equivalent).
+ * @returns A normalized `HookPayload` with both fields always defined.
+ * @throws MalformedPayloadError if the input is not parseable JSON.
+ * @throws TypePayloadError if `tool_input.command` is present with a
+ *         non-string type.
+ */
+export function parseHookPayload(raw) {
+    const text = typeof raw === 'string' ? raw : raw.toString('utf8');
+    if (text.trim().length === 0) {
+        return { toolName: '', command: '' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new MalformedPayloadError(`hook payload is not valid JSON: ${detail}`);
+    }
+    if (parsed === null) {
+        // Top-level `null` mirrors `jq -r '.tool_name // ""'` returning ``
+        // — the bash hooks treated this as "no tool, allow on empty cmd".
+        return { toolName: '', command: '' };
+    }
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        // Top-level primitives (number, string, boolean) and arrays are
+        // unambiguously malformed — Claude Code never emits these shapes.
+        // Fail-closed so a crafted payload can't sneak past as a no-op.
+        throw new MalformedPayloadError(`hook payload top-level is ${Array.isArray(parsed) ? 'array' : typeof parsed}, expected object`);
+    }
+    const toolName = typeof parsed.tool_name === 'string' ? parsed.tool_name : '';
+    const ti = parsed.tool_input;
+    let command = '';
+    if (ti !== undefined && ti !== null) {
+        if (typeof ti !== 'object') {
+            throw new TypePayloadError(`hook payload tool_input is ${typeof ti}, expected object`);
+        }
+        const c = ti.command;
+        if (c !== undefined && typeof c !== 'string') {
+            throw new TypePayloadError(`hook payload tool_input.command is ${typeof c}, expected string`);
+        }
+        if (typeof c === 'string')
+            command = c;
+    }
+    return { toolName, command };
+}
+/**
+ * Parse a Claude Code Write/Edit/MultiEdit/NotebookEdit stdin payload.
+ *
+ * Same fail-closed posture as `parseHookPayload`: malformed JSON →
+ * throws `MalformedPayloadError`; type-mismatched fields → throws
+ * `TypePayloadError`. Callers fail-closed on these for blocking-tier
+ * gates (changeset-security-gate refuses on uncertainty).
+ */
+export function parseWriteHookPayload(raw) {
+    const text = typeof raw === 'string' ? raw : raw.toString('utf8');
+    if (text.trim().length === 0) {
+        return { toolName: '', filePath: '', content: '' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new MalformedPayloadError(`hook payload is not valid JSON: ${detail}`);
+    }
+    if (parsed === null) {
+        return { toolName: '', filePath: '', content: '' };
+    }
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new MalformedPayloadError(`hook payload top-level is ${Array.isArray(parsed) ? 'array' : typeof parsed}, expected object`);
+    }
+    const toolName = typeof parsed.tool_name === 'string' ? parsed.tool_name : '';
+    const ti = parsed.tool_input;
+    let filePath = '';
+    let content = '';
+    if (ti !== undefined && ti !== null) {
+        if (typeof ti !== 'object') {
+            throw new TypePayloadError(`hook payload tool_input is ${typeof ti}, expected object`);
+        }
+        // file_path or notebook_path. Both are optional; either string or absent.
+        if (ti.file_path !== undefined) {
+            if (typeof ti.file_path !== 'string') {
+                throw new TypePayloadError(`hook payload tool_input.file_path is ${typeof ti.file_path}, expected string`);
+            }
+            filePath = ti.file_path;
+        }
+        else if (ti.notebook_path !== undefined) {
+            if (typeof ti.notebook_path !== 'string') {
+                throw new TypePayloadError(`hook payload tool_input.notebook_path is ${typeof ti.notebook_path}, expected string`);
+            }
+            filePath = ti.notebook_path;
+        }
+        // Content extraction — same priority order as the bash hook.
+        if (typeof ti.content === 'string' && ti.content.length > 0) {
+            content = ti.content;
+        }
+        else if (typeof ti.new_string === 'string' && ti.new_string.length > 0) {
+            content = ti.new_string;
+        }
+        else if (Array.isArray(ti.edits) && ti.edits.length > 0) {
+            // Defensive: non-string `new_string` fragments collapse to ''
+            // (matches the bash helper's `// ""` + `tostring`). The
+            // concatenation order is bash hook's `join("\n")`.
+            const parts = [];
+            for (const edit of ti.edits) {
+                if (edit === null || typeof edit !== 'object')
+                    continue;
+                const e = edit;
+                if (typeof e.new_string === 'string') {
+                    parts.push(e.new_string);
+                }
+                else {
+                    parts.push('');
+                }
+            }
+            content = parts.join('\n');
+        }
+        else if (typeof ti.new_source === 'string' && ti.new_source.length > 0) {
+            content = ti.new_source;
+        }
+    }
+    return { toolName, filePath, content };
+}
+/**
+ * Read all of stdin into a string with a soft byte cap and a hard
+ * timeout. Mirrors the `readStdinWithTimeout` helper in
+ * `src/cli/hook.ts` (which scans a fixed timeout but no byte cap).
+ *
+ * The cap (default 1 MiB) defends against a misbehaving caller piping
+ * an unbounded payload — we'd otherwise sit in the read loop forever
+ * even if the caller eventually closed stdin.
+ *
+ * @param timeoutMs How long to wait for stdin to close before resolving
+ *                  with whatever we have. Default 5_000 ms.
+ * @param maxBytes Soft cap on total bytes accepted. Default 1 MiB.
+ *                 Once reached, additional chunks are dropped silently
+ *                 (the caller still gets a parseable string back).
+ */
+export function readStdinWithTimeout(timeoutMs = 5_000, maxBytes = 1024 * 1024) {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY) {
+            resolve('');
+            return;
+        }
+        let buf = '';
+        let bytesRead = 0;
+        let resolved = false;
+        const finish = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            try {
+                process.stdin.removeAllListeners('data');
+                process.stdin.removeAllListeners('end');
+                process.stdin.removeAllListeners('error');
+            }
+            catch {
+                /* best effort */
+            }
+            resolve(buf);
+        };
+        const timer = setTimeout(finish, timeoutMs);
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            const chunkBytes = Buffer.byteLength(chunk, 'utf8');
+            if (bytesRead + chunkBytes > maxBytes) {
+                // Truncate to the cap; further chunks are dropped silently.
+                const remaining = Math.max(0, maxBytes - bytesRead);
+                if (remaining > 0) {
+                    buf += chunk.slice(0, remaining);
+                    bytesRead = maxBytes;
+                }
+                finish();
+                return;
+            }
+            buf += chunk;
+            bytesRead += chunkBytes;
+        });
+        process.stdin.on('end', finish);
+        process.stdin.on('error', finish);
+    });
+}

package/dist/hooks/_lib/segments.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Quote-aware shell-segment splitter for the Node-binary hook tier.
+ *
+ * 0.32.0 — port of the relevant primitives in
+ * `hooks/_lib/cmd-segments.sh`. The bash helper is 1002 LOC of
+ * defense-in-depth (heredoc unwrapping, nested-shell recursion,
+ * env-var-assignment stripping, etc.) — most of those branches exist
+ * to defend against bypass attempts in WRITE-tier gates (`dangerous-
+ * bash-interceptor`, `dependency-audit-gate`). The Phase 1 pilots
+ * landing in 0.32.0 (`security-disclosure-gate`,
+ * `attribution-advisory`) only need the SUBSET of segment behavior
+ * those two hooks actually exercise:
+ *
+ *   1. Split the input on shell command separators (`;`, `&&`, `||`,
+ *      `|`, `&`, newline) while masking separators that appear inside
+ *      matched `"..."` and `'...'` quote spans.
+ *   2. For each segment, strip leading `sudo`, `exec`, `time`, `then`,
+ *      `do`, `else`, `fi`, and `VAR=value` env-prefixes so the
+ *      caller's regex can anchor at the segment's actual command head.
+ *   3. Expose two query primitives:
+ *        - `anySegmentStartsWith(cmd, regexHead)`
+ *            true if any segment's prefix-stripped head matches the
+ *            head-anchored regex.
+ *        - `anySegmentMatches(cmd, regex)`
+ *            true if any segment's raw (non-stripped) text contains a
+ *            match for the regex (used for content scans like
+ *            `Co-Authored-By:` markers inside `git commit -m "..."`).
+ *
+ * Out-of-scope vs. the bash helper:
+ *
+ *   - No heredoc body extraction. The pilots match on the command
+ *     line, not on heredoc contents. (Body-file resolution in
+ *     `security-disclosure-gate` is done separately by reading the
+ *     file path off the command.)
+ *   - No nested-shell unwrapping (`bash -c 'PAYLOAD'`). The
+ *     bash-scanner walker already handles that for the WRITE gates;
+ *     the Phase 1 pilots inherit the SECURITY guarantee that any
+ *     hostile nested shell would have been refused by the bash-scanner
+ *     tier BEFORE this advisory tier ran.
+ *   - No backtick/command-substitution recursion.
+ *
+ * If a future pilot needs those branches, port them here in a
+ * subsequent release. The CURRENT pilots' bash counterparts call only
+ * `any_segment_starts_with` and `any_segment_matches` against
+ * direct-stdin commands.
+ *
+ * Quote-handling parity with cmd-segments.sh:
+ *
+ *   - Double-quoted spans (`"..."`): `\"` and `\\` are literal escapes;
+ *     all other characters are literal.
+ *   - Single-quoted spans (`'...'`): no escape semantics; every
+ *     character is literal until the next `'`.
+ *   - Unterminated quote spans extend to end-of-input (caller's bug —
+ *     we still emit a single segment for it rather than throwing).
+ *   - Backslash outside quotes escapes the following character (so
+ *     `git commit \&\& foo` parses as a single segment, matching
+ *     bash's behavior).
+ */
+/**
+ * A single emitted segment. `raw` preserves the original (post-
+ * unmasking) text; `head` is the prefix-stripped form used for
+ * head-anchored matchers.
+ */
+export interface CommandSegment {
+    raw: string;
+    head: string;
+}
+/**
+ * Split `cmd` into segments using the quote-aware masking → split →
+ * unmask pipeline. Returns an array of `{ raw, head }` tuples in the
+ * order they appeared in the original command.
+ *
+ * 0.33.0 — nested-shell unwrapping was added on top of the original
+ * 0.32.0 splitter. When a segment's head is `bash -c|-lc|--c PAYLOAD`
+ * or `sh -c|-lc|--c PAYLOAD` (any combination of `-l` and `-c` flags),
+ * the PAYLOAD inside the quoted arg becomes additional segments
+ * appended after the wrapper segment. Mirrors the bash counterpart's
+ * `_rea_unwrap_nested_shells` (helix-017 #3 fix). Recurses up to
+ * `MAX_NESTED_DEPTH` levels.
+ */
+export declare function splitSegments(cmd: string): CommandSegment[];
+/**
+ * Returns true if any segment's prefix-stripped head matches the
+ * head-anchored regex. The regex must NOT include a `^` anchor —
+ * we anchor by testing against the head of the segment via
+ * `regex.test(head.slice(0, match.length))` simulation. In practice
+ * we just run the regex against the head with the regex already
+ * head-anchored by virtue of `head` containing only the prefix-
+ * stripped form.
+ *
+ * The bash counterpart uses `grep -qiE PATTERN <<<"$head"` so we
+ * match the same posture: case-INSENSITIVE, extended regex.
+ *
+ * @param regexSource ERE source. We compile with case-insensitive
+ *                    flag. Caller passes the same string they would
+ *                    have passed to `any_segment_starts_with` in bash.
+ *                    The regex is internally anchored with `^`.
+ */
+export declare function anySegmentStartsWith(cmd: string, regexSource: string): boolean;
+/**
+ * Returns true if any segment's RAW text contains a match for the
+ * regex (no head anchoring). Mirrors `any_segment_matches` — used for
+ * content-scan patterns like `Co-Authored-By:` markers inside
+ * quoted `git commit -m "..."` arguments.
+ *
+ * Case-INSENSITIVE, extended regex. Same posture as the bash helper.
+ */
+export declare function anySegmentMatches(cmd: string, regexSource: string): boolean;
+/**
+ * Returns true if any single segment's RAW text contains matches for
+ * BOTH `regexA` AND `regexB`. Mirrors `any_segment_matches_both` from
+ * the bash counterpart — used by `env-file-protection` to require that
+ * a text-reading utility AND an `.env*` filename co-occur within the
+ * same shell segment (a multi-segment construction like
+ * `echo "log: cat .env stuff" ; touch foo.env` must NOT fire because
+ * the utility and filename live in different segments).
+ *
+ * Case-INSENSITIVE, extended regex on both patterns. Same posture as
+ * the bash helper.
+ *
+ * 0.33.0 port. The bash helper was introduced in 0.16.2 to fix the
+ * helix-017 P2 false-positive class where two independent booleans
+ * (any-utility OR any-env) were AND'd across segments.
+ */
+export declare function anySegmentMatchesBoth(cmd: string, regexA: string, regexB: string): boolean;