@bookedsolid/rea 0.2.1 → 0.4.0

package/dist/audit/fs.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared audit filesystem primitives (G1). Both the gateway audit middleware
+ * (`src/gateway/middleware/audit.ts`) and the public append helper
+ * (`src/audit/append.ts`) funnel through this module so locking, partial-write
+ * recovery, and rotation semantics stay in lockstep.
+ *
+ * ## Locking
+ *
+ * Every append acquires a `proper-lockfile` lock on the audit file's parent
+ * directory (`.rea/`) — NOT on `audit.jsonl` directly, because `proper-lockfile`
+ * refuses to lock a file that does not yet exist. The lock is taken BEFORE the
+ * read-last-record → compute-hash → append → fsync sequence, so two processes
+ * on the same filesystem can append concurrently without interleaving.
+ *
+ * Stale-lock detection: `proper-lockfile` handles `EEXIST` with `stale: 10000`
+ * (10s). A crashed writer that leaves a stale lockfile frees itself on the
+ * next append attempt.
+ *
+ * ## Partial-write recovery
+ *
+ * An append that crashes mid-write leaves a trailing line WITHOUT a newline.
+ * `readLastRecord()` detects this signal (file doesn't end with `\n`) and
+ * truncates the partial line before returning the previous record's hash.
+ * This recovery is idempotent and runs on every read.
+ *
+ * ## Locking contract
+ *
+ * Callers invoke `withAuditLock(auditFile, async () => { ... })`. The callback
+ * MUST perform its read → compute → append → fsync inside the lock scope. On
+ * lock acquisition failure the callback does NOT run — the caller receives
+ * the error and decides whether to fall back (middleware logs and continues;
+ * the public helper propagates).
+ */
+import type { AuditRecord } from '../gateway/middleware/audit-types.js';
+export declare const GENESIS_HASH: string;
+/**
+ * Acquire an exclusive lock on the audit file's parent directory and run
+ * `fn` inside it. The parent directory must exist before calling this.
+ *
+ * The lock is released even if `fn` throws. Lock-acquisition failures
+ * surface as the caller's rejection — middleware catches and logs, the
+ * public helper propagates.
+ */
+export declare function withAuditLock<T>(auditFile: string, fn: () => Promise<T>): Promise<T>;
+export declare function computeHash(record: Omit<AuditRecord, 'hash'>): string;
+/**
+ * Read the last complete JSON record from the audit file. Returns the parsed
+ * record plus its hash (the value a new append should use for `prev_hash`).
+ *
+ * Recovers from three tail states:
+ *   - File does not exist → genesis.
+ *   - File exists but is empty (or only whitespace) → genesis.
+ *   - File tail does not end in `\n` → treat the trailing partial line as a
+ *     crash signal, truncate it, and return the record before it.
+ *
+ * Never throws on read-side issues except raw I/O errors (permission, ENOSPC,
+ * etc.) that the caller should surface.
+ */
+export declare function readLastRecord(auditFile: string): Promise<{
+    record: AuditRecord | null;
+    hash: string;
+}>;
+/**
+ * Open-and-fsync the audit file. Called after an append to flush the write
+ * to durable storage. fsync failure is not fatal — the append itself
+ * already succeeded; durability is best-effort.
+ */
+export declare function fsyncFile(filePath: string): Promise<void>;

package/dist/audit/fs.js

@@ -0,0 +1,171 @@
+/**
+ * Shared audit filesystem primitives (G1). Both the gateway audit middleware
+ * (`src/gateway/middleware/audit.ts`) and the public append helper
+ * (`src/audit/append.ts`) funnel through this module so locking, partial-write
+ * recovery, and rotation semantics stay in lockstep.
+ *
+ * ## Locking
+ *
+ * Every append acquires a `proper-lockfile` lock on the audit file's parent
+ * directory (`.rea/`) — NOT on `audit.jsonl` directly, because `proper-lockfile`
+ * refuses to lock a file that does not yet exist. The lock is taken BEFORE the
+ * read-last-record → compute-hash → append → fsync sequence, so two processes
+ * on the same filesystem can append concurrently without interleaving.
+ *
+ * Stale-lock detection: `proper-lockfile` handles `EEXIST` with `stale: 10000`
+ * (10s). A crashed writer that leaves a stale lockfile frees itself on the
+ * next append attempt.
+ *
+ * ## Partial-write recovery
+ *
+ * An append that crashes mid-write leaves a trailing line WITHOUT a newline.
+ * `readLastRecord()` detects this signal (file doesn't end with `\n`) and
+ * truncates the partial line before returning the previous record's hash.
+ * This recovery is idempotent and runs on every read.
+ *
+ * ## Locking contract
+ *
+ * Callers invoke `withAuditLock(auditFile, async () => { ... })`. The callback
+ * MUST perform its read → compute → append → fsync inside the lock scope. On
+ * lock acquisition failure the callback does NOT run — the caller receives
+ * the error and decides whether to fall back (middleware logs and continues;
+ * the public helper propagates).
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import properLockfile from 'proper-lockfile';
+export const GENESIS_HASH = '0'.repeat(64);
+/**
+ * Lock-file retry envelope. `stale: 10000` lets a crashed holder's lock be
+ * reclaimed after 10s of inactivity. Retries are generous because individual
+ * appends are cheap (single-digit milliseconds) and under heavy cross-process
+ * contention we would rather wait than surface EEXIST to the caller. The
+ * budget is bounded (`retries: 40`, max ~300ms per retry) so a truly
+ * compromised lockfile still surfaces quickly.
+ */
+const LOCK_OPTIONS = {
+    stale: 10_000,
+    retries: {
+        retries: 40,
+        factor: 1.3,
+        minTimeout: 15,
+        maxTimeout: 300,
+        randomize: true,
+    },
+    // Lock the parent directory (the audit file may not exist yet on first
+    // write). proper-lockfile's `realpath: false` avoids a symlink check that
+    // fails when the file itself hasn't been created.
+    realpath: false,
+};
+/**
+ * Acquire an exclusive lock on the audit file's parent directory and run
+ * `fn` inside it. The parent directory must exist before calling this.
+ *
+ * The lock is released even if `fn` throws. Lock-acquisition failures
+ * surface as the caller's rejection — middleware catches and logs, the
+ * public helper propagates.
+ */
+export async function withAuditLock(auditFile, fn) {
+    const lockTarget = path.dirname(auditFile);
+    const release = await properLockfile.lock(lockTarget, LOCK_OPTIONS);
+    try {
+        return await fn();
+    }
+    finally {
+        try {
+            await release();
+        }
+        catch {
+            // Releasing a lock can fail if the lockfile was already cleaned up
+            // by stale-detection. That's not a correctness problem for the caller
+            // — the work already completed. Swallow.
+        }
+    }
+}
+export function computeHash(record) {
+    return crypto.createHash('sha256').update(JSON.stringify(record)).digest('hex');
+}
+/**
+ * Read the last complete JSON record from the audit file. Returns the parsed
+ * record plus its hash (the value a new append should use for `prev_hash`).
+ *
+ * Recovers from three tail states:
+ *   - File does not exist → genesis.
+ *   - File exists but is empty (or only whitespace) → genesis.
+ *   - File tail does not end in `\n` → treat the trailing partial line as a
+ *     crash signal, truncate it, and return the record before it.
+ *
+ * Never throws on read-side issues except raw I/O errors (permission, ENOSPC,
+ * etc.) that the caller should surface.
+ */
+export async function readLastRecord(auditFile) {
+    let data;
+    try {
+        data = await fs.readFile(auditFile, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return { record: null, hash: GENESIS_HASH };
+        }
+        throw err;
+    }
+    if (data.length === 0) {
+        return { record: null, hash: GENESIS_HASH };
+    }
+    // Partial-write recovery: a crash mid-append leaves the file without a
+    // trailing newline. Truncate the unterminated tail before consulting the
+    // chain. This is the only way a partial line can reach disk — every clean
+    // append writes `JSON.stringify(record) + '\n'`.
+    const endsWithNewline = data.endsWith('\n');
+    if (!endsWithNewline) {
+        const lastNewline = data.lastIndexOf('\n');
+        if (lastNewline === -1) {
+            // Whole file is a partial write — truncate to empty.
+            await fs.truncate(auditFile, 0);
+            return { record: null, hash: GENESIS_HASH };
+        }
+        // Keep everything through the last newline (inclusive); drop the partial
+        // tail. +1 to include the newline itself.
+        const keepLength = Buffer.byteLength(data.slice(0, lastNewline + 1), 'utf8');
+        await fs.truncate(auditFile, keepLength);
+        data = data.slice(0, lastNewline + 1);
+    }
+    const trimmed = data.replace(/\n+$/, '');
+    if (trimmed.length === 0) {
+        return { record: null, hash: GENESIS_HASH };
+    }
+    const lastNewline = trimmed.lastIndexOf('\n');
+    const lastLine = lastNewline === -1 ? trimmed : trimmed.slice(lastNewline + 1);
+    try {
+        const parsed = JSON.parse(lastLine);
+        if (typeof parsed.hash === 'string' && parsed.hash.length === 64) {
+            return { record: parsed, hash: parsed.hash };
+        }
+    }
+    catch {
+        // Corrupt tail — fall through. We do NOT throw: refusing to append would
+        // mask every subsequent event. The chain-verify command (`rea audit
+        // verify`) will flag the break point for the operator.
+    }
+    return { record: null, hash: GENESIS_HASH };
+}
+/**
+ * Open-and-fsync the audit file. Called after an append to flush the write
+ * to durable storage. fsync failure is not fatal — the append itself
+ * already succeeded; durability is best-effort.
+ */
+export async function fsyncFile(filePath) {
+    let fh;
+    try {
+        fh = await fs.open(filePath, 'r');
+        await fh.sync();
+    }
+    catch {
+        // fsync failure is not fatal — the write itself already succeeded.
+    }
+    finally {
+        if (fh)
+            await fh.close();
+    }
+}

package/dist/cli/audit.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `rea audit` — operator-facing subcommands for the durability story (G1).
+ *
+ * Two verbs:
+ *   - `rotate`                   force-rotate the current `.rea/audit.jsonl`.
+ *   - `verify [--since <file>]`  re-hash the chain and exit 0 on clean, 1
+ *                                naming the first tampered record.
+ *
+ * Neither command reads policy defaults for thresholds — force rotation is
+ * explicit by definition, and verify operates on existing files regardless
+ * of policy.
+ */
+/**
+ * Reserved for future rotate knobs (e.g. `--retain N` to prune old rotated
+ * files). Empty today — kept as a typed record so the call site's option
+ * object stays self-documenting.
+ */
+export type AuditRotateOptions = Record<string, never>;
+export interface AuditVerifyOptions {
+    /**
+     * Optional rotated-file basename (e.g. `audit-20260418-193200.jsonl`).
+     * When set, verification walks forward through all rotated files in
+     * timestamp order starting at this one, then through the current
+     * `audit.jsonl`. When unset, verification runs over the current file
+     * only.
+     */
+    since?: string | undefined;
+}
+/**
+ * `rea audit rotate`. Forces a rotation now regardless of thresholds.
+ * Empty audit files are a no-op — rotating an empty chain would produce a
+ * rotation marker with no meaningful predecessor.
+ */
+export declare function runAuditRotate(_options: AuditRotateOptions): Promise<void>;
+/**
+ * `rea audit verify [--since <rotated-file>]`. Exits 0 on clean chain, 1 on
+ * first tampered record. All diagnostic output goes to stderr so the
+ * exit code is the primary signal.
+ */
+export declare function runAuditVerify(options: AuditVerifyOptions): Promise<void>;

package/dist/cli/audit.js

@@ -0,0 +1,205 @@
+/**
+ * `rea audit` — operator-facing subcommands for the durability story (G1).
+ *
+ * Two verbs:
+ *   - `rotate`                   force-rotate the current `.rea/audit.jsonl`.
+ *   - `verify [--since <file>]`  re-hash the chain and exit 0 on clean, 1
+ *                                naming the first tampered record.
+ *
+ * Neither command reads policy defaults for thresholds — force rotation is
+ * explicit by definition, and verify operates on existing files regardless
+ * of policy.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { forceRotate } from '../gateway/audit/rotator.js';
+import { computeHash, GENESIS_HASH } from '../audit/fs.js';
+import { AUDIT_FILE, REA_DIR, err, log, reaPath } from './utils.js';
+/**
+ * `rea audit rotate`. Forces a rotation now regardless of thresholds.
+ * Empty audit files are a no-op — rotating an empty chain would produce a
+ * rotation marker with no meaningful predecessor.
+ */
+export async function runAuditRotate(_options) {
+    const baseDir = process.cwd();
+    const auditFile = reaPath(baseDir, AUDIT_FILE);
+    let exists = true;
+    try {
+        const stat = await fs.stat(auditFile);
+        if (!stat.isFile() || stat.size === 0)
+            exists = false;
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            exists = false;
+        }
+        else {
+            err(`Cannot stat ${auditFile}: ${e.message}`);
+            process.exit(1);
+        }
+    }
+    if (!exists) {
+        log('Audit log empty or missing — nothing to rotate.');
+        console.log(`       File: ${path.relative(baseDir, auditFile)}`);
+        return;
+    }
+    const result = await forceRotate(auditFile);
+    if (!result.rotated) {
+        log('Audit log empty — nothing to rotate.');
+        return;
+    }
+    const rotated = result.rotatedTo;
+    log('Audit log rotated.');
+    console.log(`       Rotated to: ${path.relative(baseDir, rotated)}`);
+    console.log(`       Fresh file: ${path.relative(baseDir, auditFile)}`);
+    console.log(`       A rotation marker anchors the new chain on the old tail's hash.`);
+}
+/**
+ * Load a JSONL audit file as a record array + per-line raw text, so we can
+ * re-hash against the exact serialization that was written. Throws on read
+ * errors; returns an empty array for an empty file.
+ */
+async function loadRecords(filePath) {
+    const raw = await fs.readFile(filePath, 'utf8');
+    // Drop a single trailing newline but preserve blank lines inside the file
+    // so index numbers line up with real record positions.
+    const trimmedTail = raw.replace(/\n$/, '');
+    if (trimmedTail.length === 0)
+        return { records: [], rawLines: [] };
+    const rawLines = trimmedTail.split('\n');
+    const records = rawLines.map((line, i) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch (e) {
+            throw new Error(`Cannot parse JSON at ${path.basename(filePath)} line ${i + 1}: ${e.message}`);
+        }
+    });
+    return { records, rawLines };
+}
+function verifyChain(fileBasename, records, expectedStartPrev) {
+    let prev = expectedStartPrev;
+    for (let i = 0; i < records.length; i++) {
+        const r = records[i];
+        if (r.prev_hash !== prev) {
+            return {
+                file: fileBasename,
+                lineIndex: i,
+                reason: 'prev_hash does not match previous record',
+                expected: prev,
+                actual: r.prev_hash,
+            };
+        }
+        // Recompute hash across the canonical serialization of the record
+        // minus the `hash` field.
+        const { hash, ...rest } = r;
+        const recomputed = computeHash(rest);
+        if (recomputed !== hash) {
+            return {
+                file: fileBasename,
+                lineIndex: i,
+                reason: 'stored hash does not match recomputed hash over record body',
+                expected: recomputed,
+                actual: hash,
+            };
+        }
+        prev = hash;
+    }
+    return null;
+}
+/**
+ * Find all rotated audit files in `reaDir`, in timestamp-ascending order.
+ * Filenames follow `audit-YYYYMMDD-HHMMSS.jsonl` (with optional `-N` suffix
+ * for intra-second collisions). Lexicographic sort handles both cases.
+ */
+async function listRotatedFiles(reaDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(reaDir);
+    }
+    catch {
+        return [];
+    }
+    const rotated = entries.filter((n) => /^audit-\d{8}-\d{6}(-\d+)?\.jsonl$/.test(n));
+    rotated.sort();
+    return rotated;
+}
+/**
+ * `rea audit verify [--since <rotated-file>]`. Exits 0 on clean chain, 1 on
+ * first tampered record. All diagnostic output goes to stderr so the
+ * exit code is the primary signal.
+ */
+export async function runAuditVerify(options) {
+    const baseDir = process.cwd();
+    const reaDir = path.join(baseDir, REA_DIR);
+    const currentAudit = path.join(reaDir, AUDIT_FILE);
+    // Assemble the file walk.
+    const filesToVerify = [];
+    if (options.since !== undefined && options.since.length > 0) {
+        const sinceName = path.basename(options.since);
+        if (!/^audit-\d{8}-\d{6}(-\d+)?\.jsonl$/.test(sinceName)) {
+            err(`--since must name a rotated audit file (audit-YYYYMMDD-HHMMSS.jsonl); got ${JSON.stringify(options.since)}`);
+            process.exit(1);
+        }
+        const allRotated = await listRotatedFiles(reaDir);
+        const startIdx = allRotated.indexOf(sinceName);
+        if (startIdx === -1) {
+            err(`Rotated file not found: ${path.join(REA_DIR, sinceName)}`);
+            process.exit(1);
+        }
+        for (const name of allRotated.slice(startIdx)) {
+            filesToVerify.push(path.join(reaDir, name));
+        }
+    }
+    // The current audit.jsonl is ALWAYS the tail of the walk (unless it
+    // doesn't exist — then the caller either asked for --since only or has
+    // a fresh install).
+    try {
+        const stat = await fs.stat(currentAudit);
+        if (stat.isFile())
+            filesToVerify.push(currentAudit);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT') {
+            err(`Cannot stat ${currentAudit}: ${e.message}`);
+            process.exit(1);
+        }
+    }
+    if (filesToVerify.length === 0) {
+        err('No audit files to verify.');
+        console.error(`       Expected: ${path.relative(baseDir, currentAudit)}`);
+        process.exit(1);
+    }
+    let expectedPrev = GENESIS_HASH;
+    let totalRecords = 0;
+    for (const filePath of filesToVerify) {
+        let records;
+        try {
+            ({ records } = await loadRecords(filePath));
+        }
+        catch (e) {
+            err(`${e.message}`);
+            process.exit(1);
+        }
+        const basename = path.basename(filePath);
+        const failure = verifyChain(basename, records, expectedPrev);
+        if (failure !== null) {
+            err(`Audit chain TAMPER DETECTED in ${failure.file}`);
+            console.error(`       Record index:  ${failure.lineIndex} (0-based within file)`);
+            console.error(`       Reason:        ${failure.reason}`);
+            if (failure.expected !== undefined) {
+                console.error(`       Expected:      ${failure.expected}`);
+            }
+            if (failure.actual !== undefined) {
+                console.error(`       Actual:        ${failure.actual}`);
+            }
+            process.exit(1);
+        }
+        // Advance the cross-file anchor for the next file.
+        if (records.length > 0) {
+            expectedPrev = records[records.length - 1].hash;
+        }
+        totalRecords += records.length;
+    }
+    log(`Audit chain verified: ${totalRecords} records across ${filesToVerify.length} file(s) — clean.`);
+}

package/dist/cli/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type CodexProbeState } from '../gateway/observability/codex-probe.js';
+import { type PrePushDoctorState } from './install/pre-push.js';
 export interface CheckResult {
     label: string;
     /**
@@ -9,6 +10,15 @@ export interface CheckResult {
     status: 'pass' | 'fail' | 'warn' | 'info';
     detail?: string;
 }
+/**
+ * G7: report the TOFU fingerprint-store state. Pass = every enabled server
+ * in the registry has a matching stored fingerprint. Warn = at least one
+ * server would be first-seen or drifted at next `rea serve`. Info = no
+ * enabled servers (nothing to fingerprint). Fail only for unreadable store.
+ *
+ * Exported so tests can drive this without spinning up the full `runDoctor`.
+ */
+export declare function checkFingerprintStore(baseDir: string): Promise<CheckResult>;
 /**
  * Translate a `CodexProbeState` into two doctor CheckResults: one for
  * responsiveness (pass/warn) and one informational line about the last
@@ -22,11 +32,16 @@ export declare function checksFromProbeState(state: CodexProbeState): CheckResul
  * `runDoctor`.
  *
  * `codexProbeState` is consulted ONLY when Codex is required by policy.
- * Callers that already have a fresh probe state (e.g. `runDoctor`) should
- * pass it; callers that don't (e.g. unit tests of the existing doctor
- * surface) can omit it and the probe-derived fields are skipped.
+ * `prePushState` is the pre-computed G6 pre-push inspection; when omitted
+ * the pre-push check is skipped entirely (older call sites that don't yet
+ * thread the state through keep working without behavioural change).
+ * Callers that already have fresh state (e.g. `runDoctor`) should pass
+ * both; callers that don't (e.g. unit tests of the existing doctor
+ * surface) can omit them and those checks are skipped.
+ *
+ * `activeForeign` always yields `fail` — a foreign hook bypassing the gate is a hard governance gap.
  */
-export declare function collectChecks(baseDir: string, codexProbeState?: CodexProbeState): CheckResult[];
+export declare function collectChecks(baseDir: string, codexProbeState?: CodexProbeState, prePushState?: PrePushDoctorState): CheckResult[];
 export interface RunDoctorOptions {
     /** When true, print a 7-day telemetry summary after the checks (G11.5). */
     metrics?: boolean;