@bookedsolid/rea 0.2.1 → 0.4.0

package/dist/gateway/middleware/audit.js

@@ -1,11 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import crypto from 'node:crypto';
 import { Tier, InvocationStatus } from '../../policy/types.js';
-function computeHash(record) {
-    const payload = JSON.stringify(record);
-    return crypto.createHash('sha256').update(payload).digest('hex');
-}
+import { computeHash, fsyncFile, readLastRecord, withAuditLock, } from '../../audit/fs.js';
+import { maybeRotate } from '../audit/rotator.js';
 /**
  * Post-execution middleware: appends a hash-chained JSONL audit record.
  *
@@ -14,15 +11,42 @@ function computeHash(record) {
  * SECURITY: Wraps next() in try/finally to ensure audit runs even on middleware exceptions.
  * SECURITY: Placed as outermost middleware so audit records ALL invocations, including denials.
  * PERFORMANCE: All fs operations are async to avoid blocking the event loop.
+ *
+ * CONCURRENCY (G1):
+ *   - Per-process: the writeQueue below serializes writes within the Node process.
+ *   - Cross-process: each write acquires a `proper-lockfile` lock on `.rea/`.
+ *     Stale locks are reclaimed after 10s. Lock-acquisition failure falls back
+ *     to the current best-effort behavior — the tool call proceeds and the
+ *     failure is logged. Breaking the invocation because the auditor failed
+ *     would let an audit outage take down the gateway.
+ *
+ * ROTATION (G1):
+ *   - `maybeRotate` runs before each write's lock acquisition. Rotation writes
+ *     a marker record whose `prev_hash` preserves hash-chain continuity across
+ *     the rotation boundary. When no `audit.rotation` block is set in policy,
+ *     rotation is a no-op — 0.2.x behavior is preserved.
  */
-export function createAuditMiddleware(baseDir, policy) {
+export function createAuditMiddleware(baseDir, policy, 
+/**
+ * Optional metrics registry. When supplied, the
+ * `rea_audit_lines_appended_total` counter is incremented on every
+ * successful append (post-fsync). When omitted, no metrics are emitted —
+ * keeps the middleware usable in unit tests that don't exercise the
+ * observability surface.
+ */
+metrics) {
     // REA writes to a single .rea/audit.jsonl file (not dated per-day files).
     const reaDir = path.join(baseDir, '.rea');
     const auditFile = path.join(reaDir, 'audit.jsonl');
-    let prevHash = '0000000000000000000000000000000000000000000000000000000000000000';
     let dirEnsured = false;
     // SECURITY: Use a write queue to serialize audit writes, ensuring the hash chain is linear.
     let writeQueue = Promise.resolve();
+    async function ensureDir() {
+        if (!dirEnsured) {
+            await fs.mkdir(reaDir, { recursive: true });
+            dirEnsured = true;
+        }
+    }
     return async (ctx, next) => {
         let nextError;
         try {
@@ -40,64 +64,85 @@ export function createAuditMiddleware(baseDir, policy) {
         // kill-switch denied before policy middleware ran).
         const duration_ms = Date.now() - ctx.start_time;
         const autonomyLevel = ctx.metadata.autonomy_level ?? policy?.autonomy_level ?? 'unknown';
+        // Cap ctx.error before writing the audit record. A downstream MCP server
+        // can produce arbitrarily long error strings; if the audit record grows
+        // beyond ~64 KiB, `rea status` misreports it as corrupt because the tail
+        // window in summarizeAudit cannot contain the full record. 4096 bytes is
+        // generous for any legitimate error description.
+        const MAX_AUDIT_ERROR_BYTES = 4096;
+        if (ctx.error && ctx.error.length > MAX_AUDIT_ERROR_BYTES) {
+            ctx.error = ctx.error.slice(0, MAX_AUDIT_ERROR_BYTES) + '\u2026[truncated]';
+        }
         // Serialize audit writes via a queue to maintain hash chain linearity under concurrency.
-        // Each write awaits the previous one before computing its hash, ensuring a linear chain.
+        // Each write awaits the previous one before running its lock-scoped append.
         const writePromise = writeQueue.then(async () => {
             try {
-                const now = new Date().toISOString();
-                const recordBase = {
-                    timestamp: now,
-                    session_id: ctx.session_id,
-                    tool_name: ctx.tool_name,
-                    server_name: ctx.server_name,
-                    tier: ctx.tier ?? Tier.Write,
-                    status: ctx.status,
-                    autonomy_level: autonomyLevel,
-                    duration_ms,
-                    prev_hash: prevHash,
-                };
-                if (ctx.error) {
-                    recordBase.error = ctx.error;
-                }
-                if (ctx.redacted_fields?.length) {
-                    recordBase.redacted_fields = ctx.redacted_fields;
-                }
-                // Attach caller-supplied metadata when the middleware context carries any.
-                // The `autonomy_level` key is reserved for internal bookkeeping (see above)
-                // and is excluded from the exported metadata payload.
-                if (ctx.metadata !== undefined) {
-                    const exported = {};
-                    for (const [k, v] of Object.entries(ctx.metadata)) {
-                        if (k === 'autonomy_level')
-                            continue;
-                        exported[k] = v;
+                await ensureDir();
+                // G1: Attempt rotation BEFORE acquiring the append lock. No-op when the
+                // policy's audit.rotation block is absent. Errors are swallowed inside
+                // maybeRotate so rotation can never take down the gateway.
+                await maybeRotate(auditFile, policy);
+                await withAuditLock(auditFile, async () => {
+                    const { hash: prevHash } = await readLastRecord(auditFile);
+                    const now = new Date().toISOString();
+                    const recordBase = {
+                        timestamp: now,
+                        session_id: ctx.session_id,
+                        tool_name: ctx.tool_name,
+                        server_name: ctx.server_name,
+                        tier: ctx.tier ?? Tier.Write,
+                        status: ctx.status,
+                        autonomy_level: autonomyLevel,
+                        duration_ms,
+                        prev_hash: prevHash,
+                    };
+                    if (ctx.error) {
+                        recordBase.error = ctx.error;
+                    }
+                    if (ctx.redacted_fields?.length) {
+                        recordBase.redacted_fields = ctx.redacted_fields;
+                    }
+                    // Attach caller-supplied metadata when the middleware context carries any.
+                    // The `autonomy_level` key is reserved for internal bookkeeping (see above)
+                    // and is excluded from the exported metadata payload.
+                    if (ctx.metadata !== undefined) {
+                        const exported = {};
+                        for (const [k, v] of Object.entries(ctx.metadata)) {
+                            if (k === 'autonomy_level')
+                                continue;
+                            exported[k] = v;
+                        }
+                        if (Object.keys(exported).length > 0) {
+                            recordBase.metadata = exported;
+                        }
+                    }
+                    const hash = computeHash(recordBase);
+                    const record = { ...recordBase, hash };
+                    const line = JSON.stringify(record) + '\n';
+                    try {
+                        await fs.appendFile(auditFile, line);
+                    }
+                    catch {
+                        // Directory may have been deleted externally — retry once with mkdir
+                        dirEnsured = false;
+                        await ensureDir();
+                        await fs.appendFile(auditFile, line);
+                    }
+                    await fsyncFile(auditFile);
+                    // Only increment after fsync — a counter advance for a line that
+                    // was never durable on disk would be a lie.
+                    try {
+                        metrics?.incAuditLines(1);
                     }
-                    if (Object.keys(exported).length > 0) {
-                        recordBase.metadata = exported;
+                    catch {
+                        // Metrics failures must never crash the gateway.
                     }
-                }
-                const hash = computeHash(recordBase);
-                const record = { ...recordBase, hash };
-                prevHash = hash;
-                const line = JSON.stringify(record) + '\n';
-                // Ensure .rea dir exists (cached, with retry on failure)
-                if (!dirEnsured) {
-                    await fs.mkdir(reaDir, { recursive: true });
-                    dirEnsured = true;
-                }
-                try {
-                    await fs.appendFile(auditFile, line);
-                }
-                catch {
-                    // Directory may have been deleted externally — retry once with mkdir
-                    dirEnsured = false;
-                    await fs.mkdir(reaDir, { recursive: true });
-                    dirEnsured = true;
-                    await fs.appendFile(auditFile, line);
-                }
+                });
             }
             catch (auditErr) {
-                // SECURITY: Never crash the gateway on audit failure — log to stderr
+                // SECURITY: Never crash the gateway on audit failure — log to stderr.
+                // This catches lock-acquisition failures, EEXIST-without-stale, and
+                // any other I/O failure. The tool call itself continues.
                 dirEnsured = false;
                 console.error('[rea] AUDIT WRITE FAILED:', auditErr instanceof Error ? auditErr.message : auditErr);
             }

package/dist/gateway/middleware/blocked-paths.d.ts

@@ -1,12 +1,3 @@
 import type { Policy } from '../../policy/types.js';
 import type { Middleware } from './chain.js';
-/**
- * Pre-execution middleware: denies tool invocations whose arguments
- * reference paths that are in the policy's blocked_paths list.
- *
- * SECURITY: Inspects all string values in arguments (including nested objects/arrays).
- * SECURITY: Always blocks .rea/ regardless of policy configuration.
- * SECURITY: Normalizes URL-encoded characters, path separators, and case before comparison.
- * SECURITY: Re-reads blocked_paths from policy.yaml when baseDir is provided (hot-reload).
- */
 export declare function createBlockedPathsMiddleware(initialPolicy: Policy, baseDir?: string): Middleware;