mcp-for-i 0.1.13 → 0.2.0

package/dist/mcp/audit.js

@@ -2,20 +2,38 @@ import crypto from "crypto";
 import fs from "fs/promises";
 import path from "path";
 import { getConfigDir } from "../config/store.js";
+import { isTransientFsError, readFileWithRetry, sleep, writeFileAtomic } from "../util/atomicWrite.js";
+import { redactSecrets } from "../security/redact.js";
+import { withFileLock } from "../util/fileLock.js";
+const LOCK_OPTIONS = { staleMs: 30_000, timeoutMs: 20_000 };
+const MAX_ANCHOR_RESETS = 20;
+// In-process chain of audit writes (appends and purges). Each link swallows its
+// own failure, so one failed write never stops later ones; the caller still
+// receives the error.
 let appendQueue = Promise.resolve();
+function enqueue(work) {
+    const run = appendQueue.then(work);
+    appendQueue = run.then(() => undefined, () => undefined);
+    return run;
+}
 export async function appendAuditRecord(input) {
     const paths = resolveAuditPaths();
-    await fs.mkdir(paths.dir, { recursive: true });
-    let created;
-    appendQueue = appendQueue.then(async () => {
-        const prevHash = await readHeadHash(paths.headPath);
-        const nowIso = new Date().toISOString();
-        const redactedArgs = redactSensitive(input.args);
-        const argsHash = sha256Hex(stableStringify(redactedArgs));
-        const base = {
-            version: 1,
+    const redactedArgs = redactSecrets(input.args);
+    const argsHash = sha256Hex(stableStringify(redactedArgs));
+    return enqueue(() => withAuditLock(paths, async () => {
+        // Everything below reads the current state from disk under the cross-process
+        // lock, so several MCP processes extend one chain instead of forking it.
+        const key = await loadOrCreateKey(paths);
+        const anchor = await ensureAnchor(paths, key);
+        const tail = await readTail(paths.logPath);
+        const prevHash = tail.last ? tail.last.hash : anchor.records === 0 ? anchor.lastHash : "";
+        const seq = Math.max(anchor.lastSeq, tail.last?.seq ?? 0) + 1;
+        const base = toJsonValue({
+            version: 2,
+            seq,
+            keyId: key.id,
             id: crypto.randomUUID(),
-            at: nowIso,
+            at: new Date().toISOString(),
             tool: input.tool,
             status: input.status,
             connectionName: input.connectionName,
@@ -27,23 +45,34 @@ export async function appendAuditRecord(input) {
             error: input.error,
             resultSummary: input.resultSummary,
             prevHash
+        });
+        const record = { ...base, hash: keyedHash(key.secret, prevHash, base) };
+        const prefix = tail.size > 0 && !tail.endsWithNewline ? "\n" : "";
+        await appendWithRetry(paths.logPath, `${prefix}${JSON.stringify(record)}\n`);
+        const next = {
+            ...stripMac(anchor),
+            records: anchor.records + 1,
+            lastSeq: seq,
+            lastHash: record.hash,
+            updatedAt: record.at
         };
-        const hash = sha256Hex(`${prevHash}|${stableStringify(base)}`);
-        const record = { ...base, hash };
-        await fs.appendFile(paths.logPath, `${JSON.stringify(record)}\n`, "utf8");
-        await fs.writeFile(paths.headPath, hash, "utf8");
-        created = record;
-    });
-    await appendQueue;
-    return created;
+        if (anchor.records === 0) {
+            next.firstHash = record.hash;
+            next.firstPrevHash = prevHash;
+            next.firstSeq = seq;
+        }
+        await writeAnchor(paths, key, next);
+        await writeHead(paths, record.hash);
+        return record;
+    }));
 }
 export async function listAuditRecords(filter = {}) {
     const paths = resolveAuditPaths();
     const limit = clampNumber(filter.limit, 200, 1, 5000);
-    const entries = await readAuditRecords(paths.logPath);
+    const parsed = await readAuditLog(paths.logPath);
     const sinceMs = filter.since ? Date.parse(filter.since) : Number.NaN;
     const hasSince = Number.isFinite(sinceMs);
-    const filtered = entries.filter(entry => {
+    const filtered = parsed.records.filter(entry => {
         if (filter.tool && entry.tool !== filter.tool)
             return false;
         if (filter.status && entry.status !== filter.status)
@@ -60,58 +89,139 @@ export async function listAuditRecords(filter = {}) {
     return {
         records: newestFirst,
         total: filtered.length,
-        limit
+        limit,
+        skippedLines: parsed.unparseableLines.length
     };
 }
 export async function verifyAuditChain() {
     const paths = resolveAuditPaths();
-    const records = await readAuditRecords(paths.logPath);
-    let previous = "";
-    let failures = 0;
-    const failureDetails = [];
-    for (const record of records) {
-        if (record.prevHash !== previous) {
-            failures += 1;
-            failureDetails.push({ id: record.id, reason: "prevHash mismatch" });
+    // Taken under the lock so the log and the anchor are read as one consistent snapshot.
+    return withAuditLock(paths, async () => {
+        const parsed = await readAuditLog(paths.logPath);
+        const records = parsed.records;
+        const key = await readKey(paths);
+        const anchorRead = await readAnchor(paths, key);
+        const anchor = anchorRead.anchor;
+        const failureDetails = [];
+        const fail = (id, reason) => {
+            failureDetails.push({ id, reason });
+        };
+        for (const lineNumber of parsed.unparseableLines) {
+            fail(`line ${lineNumber}`, "unparseable line");
+        }
+        if (anchorRead.problem)
+            fail("ANCHOR", anchorRead.problem);
+        for (const reset of anchor?.resets || []) {
+            fail("ANCHOR", `anchor was rebuilt at ${reset.at}: ${reset.reason}`);
+        }
+        let previous = anchor ? anchor.firstPrevHash : "";
+        let lastSeq;
+        let seenKeyed = false;
+        let legacyCount = 0;
+        let keyedCount = 0;
+        const segments = [];
+        records.forEach((record, index) => {
+            const before = failureDetails.length;
+            if (index === 0 && anchor && record.hash !== anchor.firstHash) {
+                fail(record.id, "first record does not match the anchor (records were removed from the start of the log)");
+            }
+            if (record.prevHash !== previous) {
+                fail(record.id, "prevHash mismatch");
+            }
+            let type;
+            if (record.version === 2) {
+                type = "keyed";
+                seenKeyed = true;
+                keyedCount += 1;
+                if (!key) {
+                    fail(record.id, "audit key file is missing; keyed record cannot be verified");
+                }
+                else if (record.keyId !== key.id) {
+                    fail(record.id, "record was signed with a different audit key");
+                }
+                else {
+                    const { hash: _hash, ...base } = record;
+                    if (!timingSafeEqualHex(keyedHash(key.secret, record.prevHash, base), record.hash)) {
+                        fail(record.id, "hash mismatch");
+                    }
+                }
+                if (typeof record.seq !== "number") {
+                    fail(record.id, "missing sequence number");
+                }
+                else {
+                    if (lastSeq !== undefined && record.seq !== lastSeq + 1) {
+                        fail(record.id, `sequence gap (expected ${lastSeq + 1}, found ${record.seq})`);
+                    }
+                    lastSeq = record.seq;
+                }
+            }
+            else {
+                type = "legacy";
+                legacyCount += 1;
+                if (seenKeyed) {
+                    fail(record.id, "legacy (unkeyed) record after keyed records");
+                }
+                if (legacyHash(record) !== record.hash) {
+                    fail(record.id, "hash mismatch");
+                }
+            }
+            const failed = failureDetails.length - before;
+            const current = segments[segments.length - 1];
+            if (current && current.type === type) {
+                current.lastId = record.id;
+                current.records += 1;
+                current.failures += failed;
+            }
+            else {
+                segments.push({ type, firstId: record.id, lastId: record.id, records: 1, failures: failed });
+            }
             previous = record.hash;
-            continue;
+        });
+        const headHash = await readHeadHash(paths.headPath);
+        const last = records[records.length - 1];
+        if (anchor) {
+            if (anchor.records !== records.length) {
+                fail("ANCHOR", `record count does not match the anchor (expected ${anchor.records}, found ${records.length})`);
+            }
+            if (last && last.hash !== anchor.lastHash) {
+                fail("ANCHOR", "last record does not match the anchor (records were removed from or added to the end of the log)");
+            }
+            if (last && last.version === 2 && last.seq !== anchor.lastSeq) {
+                fail("ANCHOR", `last sequence number does not match the anchor (expected ${anchor.lastSeq}, found ${last.seq})`);
+            }
         }
-        const base = {
-            version: record.version,
-            id: record.id,
-            at: record.at,
-            tool: record.tool,
-            status: record.status,
-            connectionName: record.connectionName,
-            approve: record.approve,
-            durationMs: record.durationMs,
-            correlationId: record.correlationId,
-            argsHash: record.argsHash,
-            args: record.args,
-            error: record.error,
-            resultSummary: record.resultSummary,
-            prevHash: record.prevHash
-        };
-        const expected = sha256Hex(`${record.prevHash}|${stableStringify(base)}`);
-        if (expected !== record.hash) {
-            failures += 1;
-            failureDetails.push({ id: record.id, reason: "hash mismatch" });
+        else if (!anchorRead.problem) {
+            if (keyedCount > 0) {
+                fail("ANCHOR", "anchor file is missing");
+            }
+            // Log written only by older versions: fall back to the legacy head check.
+            const headMatches = records.length === 0 ? headHash === "" : headHash === last.hash;
+            if (!headMatches) {
+                fail("HEAD", "head hash mismatch");
+            }
         }
-        previous = record.hash;
-    }
-    const headHash = await readHeadHash(paths.headPath);
-    const headMatches = records.length === 0 ? headHash === "" : headHash === records[records.length - 1].hash;
-    if (!headMatches) {
-        failures += 1;
-        failureDetails.push({ id: "HEAD", reason: "head hash mismatch" });
-    }
-    return {
-        ok: failures === 0,
-        records: records.length,
-        failures,
-        details: failureDetails.slice(0, 50),
-        headHash
-    };
+        return {
+            ok: failureDetails.length === 0,
+            records: records.length,
+            failures: failureDetails.length,
+            details: failureDetails.slice(0, 50),
+            headHash,
+            keyedRecords: keyedCount,
+            legacyRecords: legacyCount,
+            unparseableLines: parsed.unparseableLines.length,
+            segments,
+            anchor: anchor
+                ? {
+                    records: anchor.records,
+                    firstSeq: anchor.firstSeq,
+                    lastSeq: anchor.lastSeq,
+                    lastHash: anchor.lastHash,
+                    updatedAt: anchor.updatedAt,
+                    lastPurge: anchor.lastPurge
+                }
+                : null
+        };
+    });
 }
 export async function exportAuditRecords(options) {
     const paths = resolveAuditPaths();
@@ -158,7 +268,7 @@ export async function exportAuditRecords(options) {
                 row.hash,
                 row.error || ""
             ];
-            lines.push(values.map(csvEscape).join(","));
+            lines.push(values.map(value => csvEscape(String(value ?? ""))).join(","));
         }
         await fs.writeFile(outputPath, `${lines.join("\n")}\n`, "utf8");
     }
@@ -171,6 +281,7 @@ export async function exportAuditRecords(options) {
         outputPath,
         format,
         exported: records.length,
+        skippedLines: listing.skippedLines,
         sourcePath: paths.logPath
     };
 }
@@ -180,37 +291,48 @@ export async function purgeAuditRecords(options) {
     if (!Number.isFinite(cutoff)) {
         throw new Error(`Invalid before timestamp: ${options.before}`);
     }
-    const paths = resolveAuditPaths();
-    await fs.mkdir(paths.dir, { recursive: true });
-    const records = await readAuditRecords(paths.logPath);
-    const keep = records.filter(record => Date.parse(record.at) >= cutoff);
-    const purgeCount = records.length - keep.length;
     const dryRun = Boolean(options.dryRun);
-    if (dryRun || purgeCount === 0) {
-        return {
+    const paths = resolveAuditPaths();
+    // Read and rewrite inside the write queue and the cross-process lock, so records
+    // appended while the purge runs are never dropped.
+    return enqueue(() => withAuditLock(paths, async () => {
+        const parsed = await readAuditLog(paths.logPath);
+        // Unparseable lines are kept: they are evidence for verify, not ours to discard.
+        const keepLines = parsed.lines.filter(line => !line.record || !(Date.parse(line.record.at) < cutoff));
+        const keepRecords = keepLines.map(line => line.record).filter((r) => Boolean(r));
+        const total = parsed.records.length;
+        const purgeCount = total - keepRecords.length;
+        const summary = {
             ok: true,
             dryRun,
             before: new Date(cutoff).toISOString(),
-            total: records.length,
+            total,
             purged: purgeCount,
-            remaining: keep.length
+            remaining: keepRecords.length,
+            skippedLines: parsed.unparseableLines.length
         };
-    }
-    await queueWrite(async () => {
-        const rebuilt = rebuildAuditChain(keep);
-        const payload = rebuilt.map(row => JSON.stringify(row)).join("\n");
-        await fs.writeFile(paths.logPath, payload.length > 0 ? `${payload}\n` : "", "utf8");
-        const headHash = rebuilt.length > 0 ? rebuilt[rebuilt.length - 1].hash : "";
-        await fs.writeFile(paths.headPath, headHash, "utf8");
-    });
-    return {
-        ok: true,
-        dryRun: false,
-        before: new Date(cutoff).toISOString(),
-        total: records.length,
-        purged: purgeCount,
-        remaining: keep.length
-    };
+        if (dryRun || purgeCount === 0)
+            return summary;
+        const key = await loadOrCreateKey(paths);
+        const anchor = await ensureAnchor(paths, key);
+        // Kept records are not re-hashed: the anchor records where the chain now starts.
+        const payload = keepLines.map(line => line.raw).join("\n");
+        await writeFileAtomic(paths.logPath, payload.length > 0 ? `${payload}\n` : "");
+        const first = keepRecords[0];
+        const lastKept = keepRecords[keepRecords.length - 1];
+        const now = new Date().toISOString();
+        await writeAnchor(paths, key, {
+            ...stripMac(anchor),
+            records: keepRecords.length,
+            firstHash: first ? first.hash : "",
+            firstPrevHash: first ? first.prevHash : anchor.lastHash,
+            firstSeq: first && typeof first.seq === "number" ? first.seq : null,
+            updatedAt: now,
+            lastPurge: { at: now, before: summary.before, purged: purgeCount }
+        });
+        await writeHead(paths, lastKept ? lastKept.hash : "");
+        return summary;
+    }));
 }
 function resolveAuditPaths() {
     const explicit = process.env.MCP_FOR_I_AUDIT_LOG_PATH;
@@ -218,23 +340,120 @@ function resolveAuditPaths() {
         ? path.resolve(explicit)
         : path.join(getConfigDir(), "audit", "tool-audit.jsonl");
     const dir = path.dirname(logPath);
+    const explicitKey = process.env.MCP_FOR_I_AUDIT_KEY_PATH;
     return {
         dir,
         logPath,
-        headPath: path.join(dir, "tool-audit.head")
+        headPath: path.join(dir, "tool-audit.head"),
+        anchorPath: path.join(dir, "tool-audit.anchor.json"),
+        keyPath: explicitKey && explicitKey.trim().length > 0 ? path.resolve(explicitKey) : path.join(dir, "tool-audit.key"),
+        lockPath: path.join(dir, "tool-audit.lock")
     };
 }
-async function readAuditRecords(logPath) {
+async function withAuditLock(paths, work) {
+    await fs.mkdir(paths.dir, { recursive: true });
+    return withFileLock(paths.lockPath, work, LOCK_OPTIONS);
+}
+// ---------------------------------------------------------------------------
+// Reading the log
+async function readAuditLog(logPath) {
+    let raw = "";
+    try {
+        raw = await readFileWithRetry(logPath);
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT")
+            throw err;
+    }
+    const result = { records: [], unparseableLines: [], lines: [] };
+    raw.split(/\r?\n/).forEach((text, index) => {
+        const line = text.trim();
+        if (!line)
+            return;
+        const record = parseRecordLine(line);
+        result.lines.push({ raw: line, lineNumber: index + 1, record });
+        if (record)
+            result.records.push(record);
+        else
+            result.unparseableLines.push(index + 1);
+    });
+    return result;
+}
+function parseRecordLine(line) {
+    if (!line)
+        return undefined;
     try {
-        const raw = await fs.readFile(logPath, "utf8");
-        return raw
-            .split(/\r?\n/)
-            .map(line => line.trim())
-            .filter(Boolean)
-            .map(line => JSON.parse(line));
+        const value = JSON.parse(line);
+        if (value &&
+            typeof value === "object" &&
+            typeof value.hash === "string" &&
+            typeof value.prevHash === "string" &&
+            typeof value.at === "string") {
+            return value;
+        }
     }
     catch {
-        return [];
+        // fall through
+    }
+    return undefined;
+}
+/** Reads backwards from the end of the log to find the last valid record without loading the whole file. */
+async function readTail(logPath) {
+    let handle;
+    try {
+        handle = await fs.open(logPath, "r");
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return { size: 0, endsWithNewline: true };
+        throw err;
+    }
+    try {
+        const { size } = await handle.stat();
+        if (size === 0)
+            return { size, endsWithNewline: true };
+        const lastByte = Buffer.alloc(1);
+        await handle.read(lastByte, 0, 1, size - 1);
+        const endsWithNewline = lastByte[0] === 0x0a;
+        const chunkSize = 64 * 1024;
+        let position = size;
+        let carry = Buffer.alloc(0);
+        while (position > 0) {
+            const start = Math.max(0, position - chunkSize);
+            const chunk = Buffer.alloc(position - start);
+            await handle.read(chunk, 0, chunk.length, start);
+            position = start;
+            const buffer = Buffer.concat([chunk, carry]);
+            // Every byte range after a newline in the buffer is a complete line.
+            let end = buffer.length;
+            for (let i = buffer.length - 1; i >= 0; i--) {
+                if (buffer[i] !== 0x0a)
+                    continue;
+                const record = parseRecordLine(buffer.subarray(i + 1, end).toString("utf8").trim());
+                if (record)
+                    return { last: record, size, endsWithNewline };
+                end = i;
+            }
+            carry = buffer.subarray(0, end);
+        }
+        const record = parseRecordLine(carry.toString("utf8").trim());
+        return { last: record, size, endsWithNewline };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function appendWithRetry(filePath, content, retries = 8) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            await fs.appendFile(filePath, content, "utf8");
+            return;
+        }
+        catch (err) {
+            if (!isTransientFsError(err) || attempt >= retries)
+                throw err;
+            await sleep(20 * (attempt + 1));
+        }
     }
 }
 async function readHeadHash(headPath) {
@@ -246,38 +465,160 @@ async function readHeadHash(headPath) {
         return "";
     }
 }
-async function queueWrite(work) {
-    appendQueue = appendQueue.then(async () => {
-        await work();
-    });
-    await appendQueue;
-}
-function rebuildAuditChain(records) {
-    let previous = "";
-    const rebuilt = [];
-    for (const record of records) {
-        const base = {
-            version: record.version,
-            id: record.id,
-            at: record.at,
-            tool: record.tool,
-            status: record.status,
-            connectionName: record.connectionName,
-            approve: record.approve,
-            durationMs: record.durationMs,
-            correlationId: record.correlationId,
-            argsHash: record.argsHash,
-            args: record.args,
-            error: record.error,
-            resultSummary: record.resultSummary,
-            prevHash: previous
-        };
-        const hash = sha256Hex(`${previous}|${stableStringify(base)}`);
-        const next = { ...base, hash };
-        rebuilt.push(next);
-        previous = hash;
+async function writeHead(paths, hash) {
+    await writeFileAtomic(paths.headPath, hash, { fsync: false });
+}
+async function readKey(paths) {
+    try {
+        const raw = (await readFileWithRetry(paths.keyPath)).trim();
+        if (!/^[0-9a-f]{64}$/i.test(raw))
+            return undefined;
+        const secret = Buffer.from(raw, "hex");
+        return { secret, id: sha256Hex(secret).slice(0, 16) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Must be called while holding the audit lock, so only one process creates the key. */
+async function loadOrCreateKey(paths) {
+    const existing = await readKey(paths);
+    if (existing)
+        return existing;
+    let exists = true;
+    try {
+        await fs.access(paths.keyPath);
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT")
+            throw err;
+        exists = false;
     }
-    return rebuilt;
+    if (exists) {
+        throw new Error(`Audit key file ${paths.keyPath} does not contain a valid key; refusing to replace it.`);
+    }
+    const secret = crypto.randomBytes(32);
+    await fs.mkdir(path.dirname(paths.keyPath), { recursive: true });
+    await writeFileAtomic(paths.keyPath, secret.toString("hex"), { mode: 0o600 });
+    return { secret, id: sha256Hex(secret).slice(0, 16) };
+}
+// ---------------------------------------------------------------------------
+// Anchor
+async function readAnchor(paths, key) {
+    let raw;
+    try {
+        raw = await readFileWithRetry(paths.anchorPath);
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return { exists: false };
+        return { exists: true, problem: `anchor file could not be read (${err?.code || err?.message})` };
+    }
+    let anchor;
+    try {
+        anchor = JSON.parse(raw);
+    }
+    catch {
+        return { exists: true, problem: "anchor file is not valid JSON" };
+    }
+    if (!anchor || typeof anchor !== "object" || typeof anchor.mac !== "string") {
+        return { exists: true, problem: "anchor file has an unexpected format" };
+    }
+    if (!Array.isArray(anchor.resets))
+        anchor.resets = [];
+    if (!key)
+        return { exists: true, anchor, problem: "audit key file is missing; the anchor cannot be verified" };
+    if (anchor.keyId !== key.id)
+        return { exists: true, anchor, problem: "anchor was signed with a different audit key" };
+    if (!timingSafeEqualHex(anchorMac(key.secret, stripMac(anchor)), anchor.mac)) {
+        return { exists: true, anchor, problem: "anchor signature mismatch (the anchor file was modified)" };
+    }
+    return { exists: true, anchor };
+}
+/**
+ * Returns a trusted anchor, creating it the first time (from the existing log) or
+ * rebuilding it when it is missing or invalid. A rebuild after keyed records were
+ * written is recorded in `resets`, which verify keeps reporting as a failure.
+ */
+async function ensureAnchor(paths, key) {
+    const current = await readAnchor(paths, key);
+    if (current.anchor && !current.problem)
+        return current.anchor;
+    const parsed = await readAuditLog(paths.logPath);
+    const records = parsed.records;
+    const first = records[0];
+    const last = records[records.length - 1];
+    const lastSeq = records.reduce((max, r) => (typeof r.seq === "number" && r.seq > max ? r.seq : max), 0);
+    const hasKeyed = records.some(r => r.version === 2);
+    const resets = current.anchor?.resets ? [...current.anchor.resets] : [];
+    let reason;
+    if (current.problem)
+        reason = current.problem;
+    else if (!current.exists && hasKeyed)
+        reason = "anchor file was missing";
+    if (reason) {
+        resets.push({ at: new Date().toISOString(), reason });
+        while (resets.length > MAX_ANCHOR_RESETS)
+            resets.shift();
+    }
+    return writeAnchor(paths, key, {
+        version: 1,
+        keyId: key.id,
+        records: records.length,
+        firstHash: first ? first.hash : "",
+        firstPrevHash: first ? first.prevHash : "",
+        firstSeq: first && typeof first.seq === "number" ? first.seq : null,
+        lastSeq,
+        lastHash: last ? last.hash : "",
+        updatedAt: new Date().toISOString(),
+        resets
+    });
+}
+async function writeAnchor(paths, key, anchor) {
+    const unsigned = toJsonValue({ ...anchor, keyId: key.id });
+    const signed = { ...unsigned, mac: anchorMac(key.secret, unsigned) };
+    await writeFileAtomic(paths.anchorPath, `${JSON.stringify(signed, null, 2)}\n`, { mode: 0o600 });
+    return signed;
+}
+function stripMac(anchor) {
+    const { mac: _mac, ...rest } = anchor;
+    return rest;
+}
+function anchorMac(secret, anchor) {
+    return crypto.createHmac("sha256", secret).update(`anchor|${canonicalJson(anchor)}`).digest("hex");
+}
+// ---------------------------------------------------------------------------
+// Hashing
+function keyedHash(secret, prevHash, base) {
+    return crypto.createHmac("sha256", secret).update(`${prevHash}|${canonicalJson(base)}`).digest("hex");
+}
+function legacyHash(record) {
+    const base = {
+        version: record.version,
+        id: record.id,
+        at: record.at,
+        tool: record.tool,
+        status: record.status,
+        connectionName: record.connectionName,
+        approve: record.approve,
+        durationMs: record.durationMs,
+        correlationId: record.correlationId,
+        argsHash: record.argsHash,
+        args: record.args,
+        error: record.error,
+        resultSummary: record.resultSummary,
+        prevHash: record.prevHash
+    };
+    return sha256Hex(`${record.prevHash}|${stableStringify(base)}`);
+}
+function timingSafeEqualHex(a, b) {
+    const left = Buffer.from(String(a), "utf8");
+    const right = Buffer.from(String(b), "utf8");
+    return left.length === right.length && crypto.timingSafeEqual(left, right);
+}
+/** Round-trips through JSON so the hashed value is exactly what is stored and read back. */
+function toJsonValue(value) {
+    return JSON.parse(JSON.stringify(value));
 }
 function normalizeExportFormat(format) {
     const normalized = String(format || "jsonl").trim().toLowerCase();
@@ -286,8 +627,12 @@ function normalizeExportFormat(format) {
     }
     throw new Error(`Unsupported export format: ${format}`);
 }
-function csvEscape(value) {
-    if (value.includes(",") || value.includes("\"") || value.includes("\n")) {
+export function csvEscape(input) {
+    let value = String(input ?? "");
+    // Spreadsheet apps run cells that start with these characters as formulas.
+    if (/^[=+\-@\t\r]/.test(value))
+        value = `'${value}`;
+    if (value.includes(",") || value.includes("\"") || value.includes("\n") || value.includes("\r")) {
         return `"${value.replace(/"/g, "\"\"")}"`;
     }
     return value;
@@ -305,6 +650,7 @@ function clampNumber(value, fallback, min, max) {
 function sha256Hex(value) {
     return crypto.createHash("sha256").update(value).digest("hex");
 }
+/** Legacy canonical form (version 1 records and argsHash). Do not change: stored hashes depend on it. */
 function stableStringify(value) {
     if (value === null || typeof value !== "object")
         return JSON.stringify(value);
@@ -314,6 +660,17 @@ function stableStringify(value) {
     const props = entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
     return `{${props.join(",")}}`;
 }
+/** Canonical form for keyed records: keys sorted by code unit, undefined members omitted. */
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(v => canonicalJson(v === undefined ? null : v)).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+}
 function redactSensitive(input) {
     const secrets = ["password", "passphrase", "secret", "token", "apikey", "apiKey", "authorization"];
     if (Array.isArray(input)) {