@bookedsolid/rea 0.2.1 → 0.3.0

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/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { runAuditRotate, runAuditVerify } from './audit.js';
 import { runCheck } from './check.js';
 import { runDoctor } from './doctor.js';
 import { runFreeze, runUnfreeze } from './freeze.js';
@@ -76,6 +77,22 @@ async function main() {
         .action(() => {
         runCheck();
     });
+    const audit = program
+        .command('audit')
+        .description('Audit log operations — rotate and verify .rea/audit.jsonl (G1).');
+    audit
+        .command('rotate')
+        .description('Force-rotate .rea/audit.jsonl now. Preserves hash-chain via a marker record.')
+        .action(async () => {
+        await runAuditRotate({});
+    });
+    audit
+        .command('verify')
+        .description('Re-hash the audit chain; exit 0 on clean, 1 on the first tampered record.')
+        .option('--since <file>', 'verify starting at a rotated file (e.g. audit-YYYYMMDD-HHMMSS.jsonl), walking forward through the chain')
+        .action(async (opts) => {
+        await runAuditVerify({ ...(opts.since !== undefined ? { since: opts.since } : {}) });
+    });
     program
         .command('doctor')
         .description('Validate the install: policy parses, .rea/ layout, hooks, Codex plugin.')

package/dist/gateway/audit/rotator.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Audit rotation (G1). Size- and age-based rotation for `.rea/audit.jsonl`
+ * that preserves hash-chain continuity across the rotation boundary.
+ *
+ * ## Triggers
+ *
+ * Rotation fires when EITHER threshold is crossed:
+ *
+ * - `max_bytes` — the current `audit.jsonl` is at or above this many bytes.
+ *   Default when the policy block is present but `max_bytes` is unset:
+ *   `DEFAULT_MAX_BYTES` (50 MiB).
+ * - `max_age_days` — the first record's `timestamp` is older than this many
+ *   days. Default when unset: `DEFAULT_MAX_AGE_DAYS` (30).
+ *
+ * Back-compat: if the `audit.rotation` policy block is ABSENT entirely,
+ * rotation is DISABLED. Defaults only apply when the operator has opted in
+ * by declaring the block (even empty). This is deliberate — we do not want
+ * a 0.2.x install to observe new file-movement behavior on 0.3.0 upgrade
+ * without being asked.
+ *
+ * ## Rotation marker
+ *
+ * On rotation, the current file is renamed to `audit-YYYYMMDD-HHMMSS.jsonl`
+ * in the same directory. A fresh `audit.jsonl` is created containing EXACTLY
+ * one record: a rotation marker.
+ *
+ *     tool_name:          'audit.rotation'
+ *     server_name:        'rea'
+ *     status:             'allowed'
+ *     tier:               'read'
+ *     autonomy_level:     'system'
+ *     prev_hash:          hash of the LAST record in the rotated file
+ *     metadata.rotated_from: the rotated filename (basename)
+ *     metadata.rotated_at:   ISO-8601 instant of rotation
+ *
+ * The marker's `prev_hash` is the chain bridge — an operator verifying the
+ * chain with `rea audit verify --since <rotated-file>` walks rotated →
+ * marker → current and every transition must line up.
+ *
+ * ## Concurrency
+ *
+ * `maybeRotate` is called BEFORE the per-append lock is acquired. It takes
+ * its own short-lived lock on `.rea/` to perform the rename + marker write
+ * atomically. Callers that beat the rotator to the lock simply append to
+ * the (now fresh) file — correctness is preserved because the rotation
+ * marker is a legitimate chain anchor.
+ */
+import type { Policy, AuditRotationPolicy } from '../../policy/types.js';
+/** 50 MiB. Only applied when the operator has declared `audit.rotation`. */
+export declare const DEFAULT_MAX_BYTES: number;
+/** 30 days. Only applied when the operator has declared `audit.rotation`. */
+export declare const DEFAULT_MAX_AGE_DAYS = 30;
+export declare const ROTATION_TOOL_NAME = "audit.rotation";
+export declare const ROTATION_SERVER_NAME = "rea";
+export interface RotationResult {
+    rotated: boolean;
+    /** Absolute path of the rotated file (the `audit-TIMESTAMP.jsonl` file). */
+    rotatedTo?: string;
+}
+/** Resolve effective thresholds from policy. `undefined` thresholds disable that trigger. */
+interface EffectiveThresholds {
+    maxBytes: number | undefined;
+    maxAgeMs: number | undefined;
+}
+/**
+ * Compute the effective rotation thresholds from policy. If the operator has
+ * NOT declared an `audit.rotation` block, BOTH thresholds are undefined and
+ * rotation is disabled (back-compat with 0.2.x).
+ *
+ * If the block IS declared but individual knobs are missing, apply the
+ * documented defaults.
+ */
+declare function effectiveThresholds(policy: Policy | undefined): EffectiveThresholds;
+/**
+ * Build the rotation timestamp filename. UTC for sortability.
+ * Format: `audit-YYYYMMDD-HHMMSS.jsonl`. Collisions (two rotations in the
+ * same second) are resolved by appending `-1`, `-2`, etc.
+ */
+export declare function rotationFilename(at: Date): string;
+/**
+ * Decide whether the current audit file has crossed any rotation threshold.
+ * Exported for testing.
+ */
+export declare function shouldRotate(auditFile: string, thresholds: EffectiveThresholds, now?: Date): Promise<boolean>;
+/**
+ * Perform the rotation unconditionally. Assumes the caller has already
+ * determined rotation is warranted and holds (or is about to acquire) any
+ * outer locks. `performRotation` takes its own lock on `.rea/` to make the
+ * rename + marker write atomic w.r.t. other append-path lockers.
+ *
+ * Returns `{ rotated: false }` if the audit file is empty or missing — an
+ * empty file is a no-op by design (see `rea audit rotate` empty-case).
+ */
+export declare function performRotation(auditFile: string, now?: Date): Promise<RotationResult>;
+/**
+ * Called by the append path BEFORE acquiring its own lock. Cheap when no
+ * rotation is due (one stat, maybe one 64 KiB read for age check); idempotent
+ * when rotation IS due (performRotation re-checks under the lock).
+ *
+ * Never throws. On any error, logs to stderr and returns `rotated: false`
+ * — a broken rotator must NOT break the audit append.
+ */
+export declare function maybeRotate(auditFile: string, policy: Policy | undefined, now?: Date): Promise<RotationResult>;
+/**
+ * CLI-invoked force rotation (`rea audit rotate`). Unlike `maybeRotate` this
+ * DOES ignore thresholds — the operator asked explicitly — but empty files
+ * are still a no-op because rotating an empty chain produces a marker with
+ * no predecessor.
+ */
+export declare function forceRotate(auditFile: string, now?: Date): Promise<RotationResult>;
+/**
+ * Exposed for tests/callers that already know the policy shape. Tests that
+ * want to stub thresholds can call `performRotation` directly.
+ */
+export { effectiveThresholds as _effectiveThresholds };
+export type { EffectiveThresholds, AuditRotationPolicy };