@bookedsolid/rea 0.33.0 → 0.35.0

package/dist/hooks/blocked-paths-enforcer/index.js

@@ -0,0 +1,287 @@
+/**
+ * Node-binary port of `hooks/blocked-paths-enforcer.sh`.
+ *
+ * 0.35.0 Phase 4 port (paired Write/Edit tier). Enforces
+ * `policy.blocked_paths` against Write/Edit/MultiEdit/NotebookEdit
+ * tool calls. Sibling of `blocked-paths-bash-gate` (Bash-tier) — same
+ * policy data, different surface.
+ *
+ * Behavioral contract — preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Read stdin, extract `tool_input.file_path` (or `notebook_path`).
+ *      Missing/empty → exit 0.
+ *   3. Load policy permissively (a partial / migrating policy.yaml
+ *      must NOT collapse the blocked_paths list).
+ *   4. Empty `blocked_paths` → exit 0.
+ *   5. §5a path-traversal rejection. Refuses any path with a `..`
+ *      segment in EITHER the raw form OR the normalized form. Also
+ *      catches URL-encoded traversal (`%2E%2E/`, `..%2F`, etc.)
+ *      against the raw input.
+ *   6. §5a-bis interior `/./` segment rejection (0.29.0 helix-/./-class).
+ *      NORMALIZED form only — `normalize_path` already strips leading
+ *      `./` segments, so anything remaining is interior by construction.
+ *   7. Agent-writable allow-list short-circuit (`.rea/tasks.jsonl`,
+ *      `.rea/audit/`) — even if blocked_paths includes `.rea/` as a
+ *      prefix block, these are PM-data writeables.
+ *   8. Match the normalized path against each blocked entry:
+ *        - directory prefix (entry ends with `/`)
+ *        - glob (entry contains `*`)
+ *        - exact (lower-case, case-INSENSITIVE)
+ *      Match → exit 2 with reason.
+ *   9. §H.2 intermediate-symlink resolution. If the parent dir exists,
+ *      resolve its realpath. If the resolved target falls inside a
+ *      blocked entry, refuse.
+ *
+ * Audit-log parity: emits a `rea.hook.blocked-paths-enforcer` 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 { parseWriteHookPayload, MalformedPayloadError, TypePayloadError, readStdinWithTimeout, } from '../_lib/payload.js';
+import { normalizePath, hasTraversalSegment, hasInteriorDotSegment, resolveCanonRoot, resolveParentRealpath, } from '../_lib/path-normalize.js';
+import { appendAuditRecord, InvocationStatus, Tier } from '../../audit/append.js';
+const AGENT_WRITABLE = ['.rea/tasks.jsonl', '.rea/audit/'];
+/** Match `pathLc` against a single blocked entry. Returns true on hit. */
+function matchBlockedEntry(pathLc, blockedEntry) {
+    const entryLc = blockedEntry.toLowerCase();
+    // Directory prefix.
+    if (entryLc.endsWith('/')) {
+        if (pathLc.startsWith(entryLc))
+            return true;
+        if (pathLc === entryLc.slice(0, -1))
+            return true;
+        return false;
+    }
+    // Glob (contains *).
+    if (entryLc.includes('*')) {
+        // Convert glob to regex: . → \., * → .*; anchor to whole string.
+        const escaped = entryLc.replace(/[.+^${}()|[\]\\]/g, (m) => `\\${m}`);
+        const re = '^' + escaped.replace(/\*/g, '.*') + '$';
+        try {
+            return new RegExp(re).test(pathLc);
+        }
+        catch {
+            return false;
+        }
+    }
+    // Exact.
+    return pathLc === entryLc;
+}
+function loadBlockedPathsPermissive(reaRoot) {
+    const policyPath = path.join(reaRoot, '.rea', 'policy.yaml');
+    if (!fs.existsSync(policyPath))
+        return [];
+    let raw;
+    try {
+        raw = fs.readFileSync(policyPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch {
+        return [];
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return [];
+    }
+    const obj = parsed;
+    const bp = obj['blocked_paths'];
+    if (!Array.isArray(bp))
+        return [];
+    const out = [];
+    for (const entry of bp) {
+        if (typeof entry === 'string' && entry.length > 0)
+            out.push(entry);
+    }
+    return out;
+}
+export async function runBlockedPathsEnforcer(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, matched: null };
+    }
+    // 2. Read + parse stdin.
+    const stdinRaw = options.stdinOverride !== undefined
+        ? options.stdinOverride
+        : await readStdinWithTimeout(5_000);
+    let filePath = '';
+    try {
+        const payload = parseWriteHookPayload(stdinRaw);
+        filePath = payload.filePath;
+    }
+    catch (err) {
+        if (err instanceof MalformedPayloadError || err instanceof TypePayloadError) {
+            writeStderr(`blocked-paths-enforcer: ${err.message} — refusing on uncertainty.\n`);
+            return { exitCode: 2, stderr, matched: null };
+        }
+        throw err;
+    }
+    if (filePath.length === 0) {
+        return { exitCode: 0, stderr, matched: null };
+    }
+    // 3. Load policy permissively.
+    const blockedPaths = loadBlockedPathsPermissive(reaRoot);
+    if (blockedPaths.length === 0) {
+        return { exitCode: 0, stderr, matched: null };
+    }
+    // 4. Normalize.
+    const normalized = normalizePath(filePath, reaRoot);
+    const lowerNorm = normalized.toLowerCase();
+    // 5. §5a path-traversal rejection. Both raw + normalized.
+    const rawTraversal = hasTraversalSegment(filePath.replace(/\\/g, '/'));
+    const normTraversal = hasTraversalSegment(normalized);
+    // URL-encoded traversal check on raw input.
+    const urlEncodedTraversal = /%2[Ee]%2[Ee]|%2[Ee]\.|\.%2[Ee]/.test(filePath);
+    if (rawTraversal || normTraversal || urlEncodedTraversal) {
+        writeStderr('BLOCKED PATH: path traversal rejected\n');
+        writeStderr('\n');
+        writeStderr(`  File: ${filePath}\n`);
+        writeStderr("  Rule: path contains a '..' segment; rewrite to a canonical\n");
+        writeStderr('        project-relative path without traversal.\n');
+        return { exitCode: 2, stderr, matched: null };
+    }
+    // 6. §5a-bis interior `/./` segment rejection.
+    if (hasInteriorDotSegment(normalized)) {
+        writeStderr('BLOCKED PATH: interior dot-segment rejected\n');
+        writeStderr('\n');
+        writeStderr(`  File: ${filePath}\n`);
+        writeStderr("  Rule: path contains an interior '/./' segment; rewrite to a\n");
+        writeStderr('        canonical project-relative path without dot segments.\n');
+        return { exitCode: 2, stderr, matched: null };
+    }
+    // 7. Agent-writable allow-list.
+    for (const writable of AGENT_WRITABLE) {
+        if (normalized === writable)
+            return { exitCode: 0, stderr, matched: null };
+        if (writable.endsWith('/') && normalized.startsWith(writable)) {
+            return { exitCode: 0, stderr, matched: null };
+        }
+    }
+    // 8. Match against blocked_paths.
+    let matched = null;
+    for (const blocked of blockedPaths) {
+        if (matchBlockedEntry(lowerNorm, blocked)) {
+            matched = blocked;
+            break;
+        }
+    }
+    if (matched !== null) {
+        const isGlob = matched.includes('*');
+        writeStderr('BLOCKED PATH: Write denied by policy\n');
+        writeStderr('\n');
+        writeStderr(`  File: ${filePath}\n`);
+        writeStderr(`  Blocked by: ${matched}${isGlob ? ' (glob pattern)' : ''}\n`);
+        writeStderr('  Source: .rea/policy.yaml → blocked_paths\n');
+        if (matched.endsWith('/')) {
+            writeStderr('\n');
+            writeStderr('  This path is protected by policy. To modify it, a human must\n');
+            writeStderr('  either update blocked_paths in policy.yaml or edit the file directly.\n');
+        }
+        await maybeAudit(reaRoot, 'denied', matched, filePath);
+        return { exitCode: 2, stderr, matched };
+    }
+    // 9. §H.2 intermediate-symlink resolution.
+    const symMatched = checkSymlinkResolution(filePath, blockedPaths, reaRoot);
+    if (symMatched !== null) {
+        writeStderr('BLOCKED PATH: intermediate-symlink resolution blocked\n');
+        writeStderr('\n');
+        writeStderr(`  Logical:  ${filePath}\n`);
+        writeStderr(`  Resolved: ${symMatched.resolvedTarget}\n`);
+        writeStderr(`  Blocked by: ${symMatched.entry}\n`);
+        writeStderr('  Source: .rea/policy.yaml → blocked_paths\n');
+        writeStderr('\n');
+        writeStderr('  Rule: an intermediate directory of the path is a symlink\n');
+        writeStderr('        whose target falls inside a blocked policy entry.\n');
+        await maybeAudit(reaRoot, 'denied', symMatched.entry, filePath);
+        return { exitCode: 2, stderr, matched: symMatched.entry };
+    }
+    await maybeAudit(reaRoot, 'allowed', null, filePath);
+    return { exitCode: 0, stderr, matched: null };
+}
+/**
+ * Symlink-resolution check — mirrors `hooks/blocked-paths-enforcer.sh`
+ * §H.2. Returns the matched entry + resolved target form, or null.
+ */
+function checkSymlinkResolution(filePath, blockedPaths, reaRoot) {
+    // Only attempt resolution if the target exists or its parent dir
+    // exists — matches the bash `if [[ -e "$FILE_PATH" || -d ... ]]`.
+    let targetExists = false;
+    try {
+        targetExists = fs.existsSync(filePath);
+    }
+    catch {
+        /* fall through */
+    }
+    const parentDir = path.dirname(filePath);
+    let parentExists = false;
+    try {
+        parentExists = fs.statSync(parentDir).isDirectory();
+    }
+    catch {
+        /* falls through */
+    }
+    if (!targetExists && !parentExists)
+        return null;
+    if (!parentExists)
+        return null;
+    const resolvedParent = resolveParentRealpath(filePath);
+    if (resolvedParent.length === 0)
+        return null;
+    const canonRoot = resolveCanonRoot(reaRoot);
+    // Resolved parent must be inside REA_ROOT for the check to be
+    // meaningful — external paths are out of scope (the logical-path
+    // matchers handle them).
+    if (resolvedParent !== canonRoot && !resolvedParent.startsWith(canonRoot + '/')) {
+        return null;
+    }
+    const relativeResolved = resolvedParent === canonRoot ? '' : resolvedParent.slice(canonRoot.length + 1);
+    const resolvedTarget = relativeResolved.length > 0
+        ? `${relativeResolved}/${path.basename(filePath)}`
+        : path.basename(filePath);
+    const resolvedTargetLc = resolvedTarget.toLowerCase();
+    for (const blocked of blockedPaths) {
+        if (matchBlockedEntry(resolvedTargetLc, blocked)) {
+            return { entry: blocked, resolvedTarget };
+        }
+    }
+    return null;
+}
+async function maybeAudit(reaRoot, status, matched, filePath) {
+    try {
+        await appendAuditRecord(reaRoot, {
+            tool_name: 'rea.hook.blocked-paths-enforcer',
+            server_name: 'rea',
+            tier: Tier.Write,
+            status: status === 'allowed' ? InvocationStatus.Allowed : InvocationStatus.Denied,
+            metadata: {
+                ...(matched !== null ? { matched } : {}),
+                file_path_preview: filePath.slice(0, 256),
+            },
+        });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+export async function runHookBlockedPathsEnforcer(options = {}) {
+    const result = await runBlockedPathsEnforcer({
+        ...options,
+        stderrWrite: (s) => process.stderr.write(s),
+    });
+    process.exit(result.exitCode);
+}

package/dist/hooks/dangerous-bash-interceptor/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Node-binary port of `hooks/dangerous-bash-interceptor.sh`.
+ *
+ * 0.34.0 Phase 2 port #1 (tier-2 medium-complexity hooks with enforcer
+ * logic). This is the agent-runaway gate — it refuses destructive Bash
+ * commands before Claude Code dispatches them. Every refusal class in
+ * the 414-LOC bash body must be preserved byte-for-byte; the bypass
+ * corpus pinned across 0.13–0.27 demands it.
+ *
+ * Behavioral contract — preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with the shared banner.
+ *   2. Read stdin, extract `tool_input.command`. Non-Bash payloads or
+ *      empty command → exit 0.
+ *   3. Compute smart exclusion flags:
+ *        - `CMD_IS_REBASE_SAFE` → segments that begin with
+ *          `git rebase --abort|--continue` skip the H2 rebase advisory.
+ *        - `CMD_IS_CLEAN_DRY` → segments that begin with
+ *          `git clean -n|--dry-run` skip the H5 destructive-clean check.
+ *   4. Run every HIGH check (H1–H17, M1) against the command. Each
+ *      check returns 0..N matches; matches are accumulated into the
+ *      violations table. The accumulator preserves the original bash
+ *      hook's first-match-wins-per-check semantics — H1 fires once
+ *      per command even if multiple push segments are unsafe.
+ *   5. If any HIGH match → emit "BASH INTERCEPTED" banner + exit 2.
+ *      Else if MEDIUM-only → emit "BASH ADVISORY" banner + exit 0.
+ *      Else exit 0 silently.
+ *
+ * The pattern catalog is in `RULES` below. Each rule is a self-
+ * contained closure with a stable identifier (`H1`, `H2`, …) so a
+ * future rule addition lands as a one-line array push, not a rewrite.
+ * Identifiers match the bash hook's `add_high "H<N>: …"` shape so
+ * audit/log consumers grepping for `H12` continue to work.
+ *
+ * Key parity choices:
+ *
+ *   - Segment-anchored detection via `anySegmentStartsWith` (and
+ *     `forEachSegment` for per-segment work). The bash 0.15.0 fix
+ *     (segment-aware instead of full-command grep) is reproduced here.
+ *   - Env-var-prefix shapes (H10 `HUSKY=0 git`, H15 `REA_BYPASS=…`,
+ *     H16 alias/function defs) use `anySegmentRawMatches` since the
+ *     prefix IS the signal — `stripSegmentPrefix` would eat it.
+ *   - H12 (`curl|sh` pipe-RCE) scans the whole command via
+ *     `quoteMaskedCmd` because pipe-RCE is a multi-segment property
+ *     (`|` is the separator that joins curl to sh). The bash hook's
+ *     `_rea_unwrap_nested_shells` is mirrored via `unwrapNestedShells`
+ *     so inner payloads of `bash -c "curl … | sh"` are also scanned.
+ *   - H17 (context-protection) reads
+ *     `policy.context_protection.delegate_to_subagent` via the canonical
+ *     YAML loader (matches the bash hook's 0.16.0 fix J.2).
+ */
+import type { Buffer } from 'node:buffer';
+export interface DangerousBashOptions {
+    reaRoot?: string;
+    stdinOverride?: string | Buffer;
+    stderrWrite?: (s: string) => void;
+}
+export interface DangerousBashResult {
+    exitCode: number;
+    stderr: string;
+    /** Test seam — violations the run accumulated, in catalog order. */
+    violations: Violation[];
+}
+export interface Violation {
+    severity: 'HIGH' | 'MEDIUM';
+    /** Stable identifier (`H1`, `H10`, `M1`, …) — matches bash labels. */
+    id: string;
+    /** Banner headline. */
+    label: string;
+    /** Banner explanation paragraph. */
+    detail: string;
+    /** Suggested alternatives. */
+    alternatives: string[];
+}
+/**
+ * Rule descriptor + execution closure. The closure receives the raw
+ * command + the active exclusion flags and returns 0..N violations
+ * for that rule.
+ */
+interface RuleContext {
+    cmd: string;
+    cmdIsRebaseSafe: boolean;
+    cmdIsCleanDry: boolean;
+    delegatePatterns: string[];
+}
+interface Rule {
+    id: string;
+    severity: 'HIGH' | 'MEDIUM';
+    run: (ctx: RuleContext) => Violation[];
+}
+/**
+ * Pure executor. Returns `{ exitCode, stderr, violations }`; the CLI
+ * wrapper translates them into `process.stderr.write` + `process.exit`.
+ */
+export declare function runDangerousBashInterceptor(options?: DangerousBashOptions): Promise<DangerousBashResult>;
+/**
+ * CLI entry point — `rea hook dangerous-bash-interceptor`.
+ */
+export declare function runHookDangerousBashInterceptor(options?: DangerousBashOptions): Promise<void>;
+export declare const __INTERNAL_FOR_TESTS: {
+    RULES: readonly Rule[];
+};
+export {};