@bookedsolid/rea 0.33.0 → 0.35.0

package/dist/hooks/protected-paths-bash-gate/index.js

@@ -0,0 +1,168 @@
+/**
+ * Node-binary port of `hooks/protected-paths-bash-gate.sh`.
+ *
+ * 0.35.0 Phase 3 port (paired tier-1 scanner-shim). Like blocked-paths-
+ * bash-gate but uses `runProtectedScan` against the
+ * `policy.protected_writes` / `policy.protected_paths_relax` resolved
+ * set. The bash gate was already a thin shim over the parser-backed
+ * scanner; this port drops the shim → CLI → scanner subprocess hop.
+ *
+ * Behavioral contract — preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Read stdin via `parseHookPayload`. Empty/missing command → exit 0.
+ *   3. Non-Bash tool calls bypass.
+ *   4. REA_HOOK_PATCH_SESSION-class bypass: when the env var is set with
+ *      a non-empty reason, the scanner's protected-set is RELAXED for
+ *      .claude/hooks/ — the patch-session pattern. Implemented by
+ *      appending `.claude/hooks/` to the relax list when the env var is
+ *      live (this mirrors the bash gate's §6b semantics for the Bash
+ *      tier).
+ *   5. Load policy permissively (same lesson as 0.34.0 round-2 P2).
+ *   6. Run `runProtectedScan` with the resolved policy context.
+ *   7. Verdict `block` → exit 2; `allow` → exit 0.
+ *
+ * Audit-log parity: emits a `rea.hook.protected-paths-bash-gate` entry.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import { checkHalt, formatHaltBanner } from '../_lib/halt-check.js';
+import { parseHookPayload, MalformedPayloadError, TypePayloadError, readStdinWithTimeout, } from '../_lib/payload.js';
+import { runProtectedScan } from '../bash-scanner/index.js';
+import { appendAuditRecord, InvocationStatus, Tier } from '../../audit/append.js';
+function loadPolicyPermissive(reaRoot) {
+    const policyPath = path.join(reaRoot, '.rea', 'policy.yaml');
+    const empty = { protectedRelax: [] };
+    if (!fs.existsSync(policyPath))
+        return empty;
+    let raw;
+    try {
+        raw = fs.readFileSync(policyPath, 'utf8');
+    }
+    catch {
+        return empty;
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch {
+        return empty;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return empty;
+    }
+    const obj = parsed;
+    const out = { protectedRelax: [] };
+    if (Array.isArray(obj['protected_writes'])) {
+        out.protectedWrites = [];
+        for (const e of obj['protected_writes']) {
+            if (typeof e === 'string' && e.length > 0)
+                out.protectedWrites.push(e);
+        }
+    }
+    if (Array.isArray(obj['protected_paths_relax'])) {
+        for (const e of obj['protected_paths_relax']) {
+            if (typeof e === 'string' && e.length > 0)
+                out.protectedRelax.push(e);
+        }
+    }
+    return out;
+}
+export async function runProtectedPathsBashGate(options = {}) {
+    const reaRoot = options.reaRoot ?? process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd();
+    let stderr = '';
+    const writeStderr = (s) => {
+        stderr += s;
+        if (options.stderrWrite)
+            options.stderrWrite(s);
+    };
+    // 1. HALT check.
+    const halt = checkHalt(reaRoot);
+    if (halt.halted) {
+        writeStderr(formatHaltBanner(halt.reason));
+        return { exitCode: 2, stderr, verdict: { verdict: 'block', reason: 'rea HALT active' } };
+    }
+    // 2. Read + parse stdin.
+    const stdinRaw = options.stdinOverride !== undefined
+        ? options.stdinOverride
+        : await readStdinWithTimeout(5_000);
+    let toolName = '';
+    let cmd = '';
+    try {
+        const payload = parseHookPayload(stdinRaw);
+        toolName = payload.toolName;
+        cmd = payload.command;
+    }
+    catch (err) {
+        if (err instanceof MalformedPayloadError || err instanceof TypePayloadError) {
+            writeStderr(`protected-paths-bash-gate: ${err.message} — refusing on uncertainty.\n`);
+            return { exitCode: 2, stderr, verdict: { verdict: 'block', reason: err.message } };
+        }
+        throw err;
+    }
+    // 3. Non-Bash tool calls bypass.
+    if (toolName !== '' && toolName !== 'Bash') {
+        return { exitCode: 0, stderr, verdict: null };
+    }
+    // 4. Empty command → allow.
+    if (cmd.length === 0) {
+        return { exitCode: 0, stderr, verdict: null };
+    }
+    // 5. Load policy permissively.
+    const policy = loadPolicyPermissive(reaRoot);
+    const relax = [...policy.protectedRelax];
+    // 6. REA_HOOK_PATCH_SESSION — relax .claude/hooks/ when env var is
+    //    set with a non-empty reason. Mirrors settings-protection.sh §6b
+    //    posture (the Bash-tier counterpart wasn't enforcing this against
+    //    .claude/hooks/ until 0.35.0 — that gap is closed here).
+    const patchSession = options.patchSessionOverride ?? process.env['REA_HOOK_PATCH_SESSION'] ?? '';
+    if (patchSession.length > 0) {
+        relax.push('.claude/hooks/');
+    }
+    // 7. Scan.
+    const verdict = runProtectedScan({
+        reaRoot,
+        policy: {
+            ...(policy.protectedWrites !== undefined
+                ? { protected_writes: policy.protectedWrites }
+                : {}),
+            protected_paths_relax: relax,
+        },
+        stderr: (line) => writeStderr(line),
+    }, cmd);
+    // 8. Audit.
+    try {
+        await appendAuditRecord(reaRoot, {
+            tool_name: 'rea.hook.protected-paths-bash-gate',
+            server_name: 'rea',
+            tier: Tier.Read,
+            status: verdict.verdict === 'allow' ? InvocationStatus.Allowed : InvocationStatus.Denied,
+            metadata: {
+                verdict: verdict.verdict,
+                ...(verdict.detected_form !== undefined ? { detected_form: verdict.detected_form } : {}),
+                ...(verdict.hit_pattern !== undefined ? { hit_pattern: verdict.hit_pattern } : {}),
+                ...(patchSession.length > 0 ? { patch_session: true } : {}),
+                command_preview: cmd.slice(0, 256),
+            },
+        });
+    }
+    catch {
+        /* best-effort */
+    }
+    if (verdict.verdict === 'block') {
+        if (typeof verdict.reason === 'string' && verdict.reason.length > 0) {
+            writeStderr(verdict.reason + '\n');
+        }
+        return { exitCode: 2, stderr, verdict };
+    }
+    return { exitCode: 0, stderr, verdict };
+}
+export async function runHookProtectedPathsBashGate(options = {}) {
+    const result = await runProtectedPathsBashGate({
+        ...options,
+        stderrWrite: (s) => process.stderr.write(s),
+    });
+    process.exit(result.exitCode);
+}

package/dist/hooks/secret-scanner/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Node-binary port of `hooks/secret-scanner.sh`.
+ *
+ * 0.34.0 Phase 2 port #3 (tier-2 medium-complexity hooks with enforcer
+ * logic).
+ *
+ * Detects credential patterns in content about to be written via the
+ * Write/Edit/MultiEdit/NotebookEdit Claude Code tools and blocks (exit
+ * 2) when a HIGH-severity pattern matches a non-placeholder substring.
+ * Last-resort pre-write guard — gitleaks (pre-commit) is the primary
+ * gate; this hook stops the obvious credential-in-source-file shapes
+ * before they ever touch disk.
+ *
+ * Behavioral contract preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Read stdin via `parseWriteHookPayload`. Extracts `file_path` /
+ *      `notebook_path` and the canonical content priority:
+ *        content > new_string > edits[].new_string joined > new_source.
+ *      Empty content → exit 0.
+ *   3. Suffix-based file_path exclusion: `*.env.example` / `*.env.sample`
+ *      pass through silently. Test files are NOT excluded — the
+ *      placeholder filter handles legitimate test fixtures.
+ *   4. Apply the bash hook's awk line filter:
+ *        - Strip lines whose trimmed form starts with `#` (shell comment).
+ *        - Strip lines where `process.env.VAR` is the RHS of an
+ *          assignment (`= process.env.SOMETHING`).
+ *        - Strip lines mentioning `os.environ[`.
+ *      Anything left is the corpus the patterns run against.
+ *   5. Run each of the 17 patterns (12 HIGH + 5 MEDIUM) against the
+ *      filtered corpus. For each match:
+ *        - Apply `isPlaceholder()` filter (matches the bash hook's
+ *          `is_placeholder` shell function — placeholder forms like
+ *          `<your_key>`, `your_api_key`, `example_token`,
+ *          `aaaaaaa...`, etc. are dropped).
+ *        - Truncate the matching substring at 60 chars for display.
+ *        - Cap collected matches at 5 per pattern.
+ *   6. If ANY HIGH match remains → exit 2 with the "SECRET DETECTED"
+ *      banner. Else if MEDIUM matches → emit advisory + exit 0. No
+ *      matches → exit 0.
+ *
+ * MultiEdit handling: `parseWriteHookPayload` joins every `edits[i].
+ * new_string` with `\n`. This intentionally folds the fragments into
+ * one corpus for scanning; the joined newline boundary preserves
+ * line-anchored patterns. The bash counterpart used the same join
+ * shape via `extract_write_content` in `_lib/payload-read.sh`.
+ *
+ * 0.14.0 hardening — type-guard against malformed payloads (non-string
+ * `new_string`, non-array `edits`, etc.) lives in the shared
+ * `parseWriteHookPayload`. Defensive coercion means a crafted
+ * `{"edits":42}` payload doesn't throw at the boundary; it's treated as
+ * missing.
+ */
+import type { Buffer } from 'node:buffer';
+export interface SecretScannerOptions {
+    reaRoot?: string;
+    stdinOverride?: string | Buffer;
+    stderrWrite?: (s: string) => void;
+}
+export interface SecretScannerResult {
+    exitCode: number;
+    stderr: string;
+    /**
+     * Test seam — surfaces the matches the scanner accepted (post-
+     * placeholder filter, post-truncation). Ordered HIGH first, then
+     * MEDIUM. Useful for assertion-driven tests without grepping stderr.
+     */
+    matches: ScannerMatch[];
+}
+export interface ScannerMatch {
+    severity: 'HIGH' | 'MEDIUM';
+    label: string;
+    snippet: string;
+}
+/**
+ * Pattern descriptors. The bash hook used ERE strings via `grep -oE`;
+ * the JS port uses native RegExp. Each pattern carries:
+ *   - severity (HIGH = blocking; MEDIUM = advisory)
+ *   - label   (banner display string)
+ *   - regex   (compiled global; the `g` flag is required for matchAll)
+ *
+ * Pattern parity with the bash hook is line-by-line. Where the bash
+ * hook used POSIX character classes (`[[:space:]]`) we use `\s`; where
+ * it used `[A-Za-z0-9]` we keep that literal. Case-insensitive flags
+ * are applied per-pattern to match the bash hook's `grep -oE` posture
+ * — note that the bash `grep -oE` was case-SENSITIVE by default, so
+ * unless a pattern explicitly used `[Aa][Ww][Ss]_…` style alternation
+ * we keep the JS form case-sensitive too.
+ */
+export interface SecretPatternDescriptor {
+    severity: 'HIGH' | 'MEDIUM';
+    label: string;
+    regex: RegExp;
+}
+/**
+ * Filter content lines the same way the bash hook's awk preprocessor
+ * does:
+ *   - Strip lines whose leading-whitespace-stripped form starts with `#`.
+ *   - Strip lines where `process.env.VAR` is the RHS of an assignment.
+ *     The bash hook used two regexes (trailing-non-letter and
+ *     `;,)` punctuation forms) — we cover both.
+ *   - Strip lines mentioning `os.environ[`.
+ *
+ * Newline-preserving so multiline regex anchors (`^…$`) still work on
+ * the filtered corpus.
+ */
+export declare function filterContent(content: string): string;
+/**
+ * Bash `is_placeholder` parity. Returns true when the match is a known
+ * placeholder shape and should NOT be counted as a real secret.
+ *
+ * Lowercased once at the top; all sub-checks operate on the lower form.
+ */
+export declare function isPlaceholder(match: string): boolean;
+/**
+ * Scan filtered content against every pattern in the catalog. Returns
+ * the accepted matches in catalog order.
+ */
+export declare function scanContent(filtered: string): ScannerMatch[];
+/**
+ * Suffix-based file_path exclusion. `*.env.example` and `*.env.sample`
+ * skip the scan entirely — those are documentation files that
+ * intentionally carry placeholder credential shapes.
+ *
+ * Test files are NOT excluded. Real credentials in test fixtures must
+ * still be caught; the placeholder filter handles legitimate dummy
+ * keys.
+ */
+export declare function isExcludedSuffix(filePath: string): boolean;
+/**
+ * Pure executor. Returns `{ exitCode, stderr, matches }`; the CLI
+ * wrapper translates them into `process.stderr.write` + `process.exit`.
+ */
+export declare function runSecretScanner(options?: SecretScannerOptions): Promise<SecretScannerResult>;
+/**
+ * CLI entry point — `rea hook secret-scanner`.
+ */
+export declare function runHookSecretScanner(options?: SecretScannerOptions): Promise<void>;
+export declare const __INTERNAL_FOR_TESTS: {
+    SECRET_PATTERNS: readonly SecretPatternDescriptor[];
+    MAX_SNIPPET_LEN: number;
+    MAX_MATCHES_PER_PATTERN: number;
+};