@cyd-prc/dsh-audit-chain 0.1.0

package/lib/chain.js

@@ -0,0 +1,642 @@
+/**
+ * dsh-audit-chain — the one tamper-evident JSONL chain every guard shares.
+ *
+ * Extracted from two published implementations that had drifted onto one file:
+ * `dsh-entropy-guard`'s `AuditLog` (the writer the control face uses) and
+ * `dsh-shape-guard`'s `ShapeLedger` + `verifyChain` (the lock and the
+ * contract-conformant grader). The defects that forced the extraction, all
+ * measured on live chains before they were fixed at the source:
+ *
+ * - two writers caching the tail once per instance forked the chain
+ *   (`seq 245 repeats after 245`; entropy-guard defect 14);
+ * - a verifier that stopped at the first fork undercounted 8 forks as 1 and let
+ *   a deleted entry pass as `verified` (defect 15 / shape-guard S1, S2);
+ * - a verifier that *wrote* to the chain it audited (+2 entries per run,
+ *   defect 16);
+ * - a crash-torn tail line swallowed the next append (defect 19) and was graded
+ *   as hostile on its own (shape-guard S4).
+ *
+ * The grading semantics are the shared `CHAIN-GRADING-CONTRACT.md` (eight
+ * clauses; a mirror ships in `docs/` with its fingerprint noted in the README).
+ * The hash payload is byte-compatible with both historical writers, so chains
+ * written before this package existed verify unchanged.
+ *
+ * @module dsh-audit-chain/chain
+ */
+
+import { createHash } from 'node:crypto';
+import {
+  appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/** How long an append waits for the chain lock before failing closed, in ms. */
+export const LOCK_TIMEOUT_MS = 5000;
+
+/** How long to nap between lock attempts, in ms. */
+export const LOCK_BACKOFF_MS = 2;
+
+/** How much of the chain tail to read when recovering `seq` and `prev`. */
+const TAIL_READ_BYTES = 65536;
+
+/** Depth cap for the recursive non-finite sanitizer (guards against deep nesting). */
+const SANITIZE_MAX_DEPTH = 32;
+
+/**
+ * Render one non-finite number with its sign, preserving information the way the
+ * SDK's `_nonfinite` markers do.
+ * @param value - a non-finite number.
+ * @returns `'nan'`, `'+inf'`, or `'-inf'`.
+ */
+function nonFiniteLabel(value) {
+  return Number.isNaN(value) ? 'nan' : (value > 0 ? '+inf' : '-inf');
+}
+
+/**
+ * Recursively replace non-finite numbers inside an audit field with string
+ * markers, degrading unknown types to `String(value)`. Cycle- and depth-safe.
+ * @param value - the field value.
+ * @param depth - internal recursion depth.
+ * @param seen - internal identity set for the current path.
+ * @returns a JSON-safe value.
+ */
+function sanitizeNonFinite(value, depth = 0, seen = undefined) {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : nonFiniteLabel(value);
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return value;
+  if (Array.isArray(value) || (typeof value === 'object' && value !== null)) {
+    const path = seen ?? new Set();
+    if (depth >= SANITIZE_MAX_DEPTH || path.has(value)) return '<truncated:depth-or-cycle>';
+    path.add(value);
+    try {
+      if (Array.isArray(value)) return value.map((item) => sanitizeNonFinite(item, depth + 1, path));
+      const out = {};
+      const seenKeys = new Set();
+      let collision = false;
+      for (const [key, item] of Object.entries(value)) {
+        const renderKey = typeof key === 'string' ? key : String(key);
+        if (seenKeys.has(renderKey)) {
+          collision = true;
+          continue;
+        }
+        seenKeys.add(renderKey);
+        out[renderKey] = sanitizeNonFinite(item, depth + 1, path);
+      }
+      // `_audit_meta` is a reserved namespace; a user field of that name is
+      // preserved under `user_field_shadowed` rather than overwritten.
+      if (collision) {
+        out._audit_meta = '_audit_meta' in out
+          ? { user_field_shadowed: out._audit_meta, key_collision: true }
+          : { key_collision: true };
+      }
+      return out;
+    } finally {
+      path.delete(value);
+    }
+  }
+  return String(value);
+}
+
+/**
+ * JSON replacer retaining the "unknown types become their string form" contract.
+ * For plain-JSON values (everything on a chain, by construction) this is a
+ * pass-through, so the payload matches the sibling writers byte for byte.
+ */
+export function auditReplacer(_key, value) {
+  if (typeof value === 'bigint') return value.toString();
+  if (typeof value === 'function' || typeof value === 'symbol') return String(value);
+  return value;
+}
+
+/**
+ * The JSON encoding of an entry, on the chain or as hashed. `includeHash: false`
+ * reproduces the payload a hash is taken over — the `prev` link stays in, the
+ * entry's own `hash` is dropped, and key order is preserved.
+ *
+ * For plain-JSON entries this string is byte-identical to
+ * `JSON.stringify(entry)` — the property the two historical writers' hash
+ * payloads share, pinned by the suite so the formats can never drift apart again.
+ * @param {Record<string, unknown>} entry - the entry.
+ * @param {boolean} includeHash - whether to serialise the entry's own `hash`.
+ * @returns {string} the JSON line payload.
+ */
+export function encodeEntry(entry, includeHash) {
+  const parts = [];
+  for (const [key, value] of Object.entries(entry)) {
+    if (key === 'hash' && !includeHash) continue;
+    parts.push(`${JSON.stringify(key)}:${JSON.stringify(value)}`);
+  }
+  return `{${parts.join(',')}}`;
+}
+
+/**
+ * The SHA-256 of an entry's payload (everything but its own `hash`).
+ * @param entry - the entry without `hash`, or with it (dropped either way).
+ * @returns the hex digest.
+ */
+export function hashEntry(entry) {
+  const { hash: _drop, ...rest } = entry;
+  return createHash('sha256').update(JSON.stringify(rest, auditReplacer)).digest('hex');
+}
+
+/**
+ * Append-only, tamper-evident JSONL audit chain, safe for multiple writers.
+ *
+ * Every file-backed append does all three of these under an exclusive lock:
+ * re-read the on-disk tail (never a cached one), take `seq`/`prev` from it,
+ * append — terminating a crash-torn tail line first so the new entry is never
+ * fused into it. Reads are cached on `(mtimeMs, size)`; every read is
+ * deep-copied so a caller cannot mutate the ledger.
+ */
+export class ChainLog {
+  /**
+   * @param path - absolute JSONL path, or `null` for the in-memory ledger.
+   */
+  constructor(path = null) {
+    /** @type {string|null} */
+    this.path = path ?? null;
+    /** @type {Record<string, unknown>[]} */
+    this._buffer = [];
+    /** Bad lines skipped by the most recent disk read. */
+    this.corruptLines = 0;
+    this._cacheKey = null;
+    this._cacheEntries = [];
+    /** Append failures observed — an operational alarm, surfaced by the hosts. */
+    this.failures = 0;
+    /** @type {string|null} */
+    this.lastError = null;
+  }
+
+  /**
+   * Append one entry, serialised against any other writer of the same chain.
+   * @param kind - the event kind (`gate_decision`, `shape_flag`, …).
+   * @param fields - JSON-compatible fields.
+   * @returns a deep copy of the appended entry.
+   * @throws {Error} when the chain cannot be locked or written (fail-closed).
+   */
+  record(kind, fields = {}) {
+    const clean = {};
+    for (const [key, value] of Object.entries(fields)) {
+      if (typeof value === 'number' && !Number.isFinite(value)) {
+        clean[key] = null;
+        clean[`${key}_nonfinite`] = nonFiniteLabel(value);
+      } else {
+        clean[key] = sanitizeNonFinite(value);
+      }
+    }
+
+    if (this.path === null) {
+      // In-memory: one buffer has exactly one writer, so no lock is taken.
+      const tail = this._tail();
+      const base = { ts: Date.now() / 1000, seq: tail.seq, ...clean, kind, prev: tail.hash };
+      const entry = { ...base, hash: hashEntry(base) };
+      this._buffer.push(entry);
+      return structuredClone(entry);
+    }
+
+    const release = this._lock();
+    try {
+      const tail = this._tail();
+      // The event kind is spread after the caller's fields, so a field named
+      // `kind` cannot silently rewrite the entry's own type.
+      const base = {
+        ts: Date.now() / 1000,
+        seq: tail.seq,
+        ...clean,
+        kind,
+        prev: tail.hash,
+      };
+      const entry = { ...base, hash: hashEntry(base) };
+      mkdirSync(dirname(this.path), { recursive: true });
+      // A crash-torn tail line has no trailing newline; terminate it before
+      // appending or the new entry fuses into the corrupt line and is itself
+      // lost (defect 19; contract clause 8's writer half).
+      const line = `${JSON.stringify(entry, auditReplacer)}\n`;
+      appendFileSync(this.path, tail.tornTail ? `\n${line}` : line, 'utf8');
+      return structuredClone(entry);
+    } catch (error) {
+      this.failures += 1;
+      this.lastError = error?.message ?? String(error);
+      throw error;
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * Acknowledge the operational history up to here, inside the chain itself.
+   *
+   * A fork or a mixed-generation run is not a rewrite, and letting it colour the
+   * standing reading forever is how a grade stops being read. Sealing records the
+   * boundary *and* the counts as an ordinary entry, so the acknowledgement is
+   * auditable rather than a configuration flag someone can flip — and `verify()`
+   * never lets a seal hide a tamper finding.
+   * @param note - optional human note recorded with the seal.
+   * @returns the verification reading taken just before sealing.
+   */
+  seal(note = '') {
+    const before = this.verify();
+    // Read the tail fresh: the seq the seal names must be the chain's own, not
+    // a per-instance cache that a second writer may have moved past.
+    const tail = this._tail();
+    this.record('chain_seal', {
+      // Informational: `verify()` bounds unchained entries on the seal entry's
+      // file position, since they carry no seq to compare against.
+      sealed_through_seq: tail.seq - 1,
+      sealed_forks: before.forks - before.liveForks,
+      sealed_interleaved: before.interleaved - before.liveInterleaved,
+      chained_before: before.chained,
+      ...(note.length > 0 ? { note } : {}),
+    });
+    return before;
+  }
+
+  /**
+   * Walk the chain and grade what it finds — the shared contract, eight clauses.
+   *
+   * - `tampered` — the entry's bytes changed after it was written (the content
+   *   re-hash disagrees), a `prev` link dangles (it names a hash no entry in the
+   *   file carries, so an entry that existed is gone), a chained root appears
+   *   mid-file, or a sequence gap resumes in live history. Rewrite-shaped, the
+   *   only grade an operator must treat as hostile, and **never suppressed by a
+   *   seal**: acknowledging history must not launder a rewrite.
+   * - `forked` — a `seq` repeats: two writers appended from the same tail and
+   *   the history branched. Operational, not adversarial. The walk never stops
+   *   at the first one: every duplicate is counted, on every branch.
+   * - `discontinuity` — unchained entries sit among chained ones, which is what
+   *   an in-place upgrade looks like while two generations write one file.
+   * - `verified` — nothing to note.
+   *
+   * The three checks are kept separate, and the walk always completes:
+   *
+   * - **Content** — every chained entry is re-hashed, always, on any branch.
+   * - **Link** — fork-aware: `prev` is resolved against every hash the file
+   *   carries rather than compared to the previous line. A resolvable
+   *   non-predecessor is a branch; a dangling one means an entry that existed
+   *   is gone. Link checking pauses across an interleaved block and resumes at
+   *   the next chained entry.
+   * - **Sequence** — a repeated `seq` is a fork, never a rewrite. A gap means a
+   *   missing entry: `tampered` when it resumes in live history, reported-only
+   *   when wholly inside sealed history.
+   *
+   * Seal semantics: a `chain_seal` is a person's acknowledgement. Fork and gap
+   * membership is decided by `seq` (a branch entry written after the seal can
+   * still carry a seq the seal covers); interleaved entries carry no `seq`, so
+   * their side of the seal is decided by file position. Findings at or below the
+   * last seal are reported as `sealed*` and excluded from the live grade.
+   *
+   * Corrupt lines (clause 8): always reported in `corrupt`, never graded on
+   * their own — a torn final line after a crash is an availability event, and a
+   * mid-chain deletion is already caught by the link check. The `reason` names
+   * them whenever there is nothing louder to say.
+   * @returns the verification reading.
+   */
+  verify() {
+    const entries = this._readAll();
+    let legacy = 0;
+    let chained = 0;
+    let interleaved = 0;
+    let firstChainedIndex = -1;
+    let lastChainedIndex = -1;
+
+    // Findings, with the seal boundary applied at the end. A tamper is kept
+    // unfiltered — whichever side of a seal it falls on.
+    const tampered = [];
+    const forks = [];
+    const sealedGaps = [];
+
+    // Pass 0 — every hash the file actually carries, so a link can be resolved
+    // instead of only compared to the previous line.
+    const knownHashes = new Set();
+    for (const entry of entries) {
+      if (typeof entry?.hash === 'string') knownHashes.add(entry.hash);
+    }
+
+    // Seal bookkeeping. The fork axis bounds by seq; the interleaved axis has
+    // no seq and bounds by file position.
+    let sealedCount = 0;
+    let lastSealIndex = -1;
+    let sealedThroughSeq = null;
+
+    let linkPaused = false;
+    /** File positions of the interleaved (unchained) entries. */
+    const interleavedAt = [];
+    const seenSeq = new Set();
+
+    for (let index = 0; index < entries.length; index += 1) {
+      const entry = entries[index];
+      const chainedEntry = typeof entry?.seq === 'number' && typeof entry?.hash === 'string';
+      if (!chainedEntry) {
+        // Before anything chained it is the legacy prefix; afterwards it is an
+        // interleaved generation, which is what an in-place upgrade looks like
+        // while two writers share one file.
+        if (chained === 0) legacy += 1;
+        else {
+          interleaved += 1;
+          interleavedAt.push(index);
+          linkPaused = true;
+        }
+        continue;
+      }
+      if (firstChainedIndex < 0) firstChainedIndex = index;
+      lastChainedIndex = index;
+      chained += 1;
+
+      if (entry.kind === 'chain_seal') {
+        sealedCount += 1;
+        lastSealIndex = index;
+        const through = typeof entry.sealed_through_seq === 'number'
+          ? entry.sealed_through_seq
+          : entry.seq - 1;
+        sealedThroughSeq = sealedThroughSeq === null ? through : Math.max(sealedThroughSeq, through);
+      }
+
+      // Content: always, for every chained entry, on any branch.
+      if (hashEntry(entry) !== entry.hash) {
+        tampered.push({ seq: entry.seq, reason: `seq ${entry.seq} was modified after it was written` });
+      }
+
+      // Link: dangling is a rewrite; a resolvable non-predecessor is a branch.
+      const prev = entry.prev ?? null;
+      if (prev !== null && !knownHashes.has(prev)) {
+        tampered.push({ seq: entry.seq, reason: `the link into seq ${entry.seq} names a hash no entry carries — an entry that existed is gone` });
+      } else if (prev === null && !linkPaused && index > 0 && seenSeq.size > 0) {
+        // A chained entry claiming to be a root, mid-file, with no interleaving
+        // to explain it: an earlier entry is gone.
+        tampered.push({ seq: entry.seq, reason: `seq ${entry.seq} restarts the chain mid-file — an earlier entry is gone` });
+      }
+      linkPaused = false;
+
+      // Sequence: a repeat is a fork, and the count never stops early.
+      if (seenSeq.has(entry.seq)) {
+        forks.push({ seq: entry.seq, reason: `duplicate seq ${entry.seq} — a second writer branched this chain` });
+      } else {
+        seenSeq.add(entry.seq);
+      }
+    }
+
+    // Pass 2 — a sequence gap means an entry is missing. Graded as a rewrite
+    // when it resumes in live history; reported-only inside sealed history.
+    const sortedSeq = [...seenSeq].sort((a, b) => a - b);
+    for (let index = 1; index < sortedSeq.length; index += 1) {
+      if (sortedSeq[index] === sortedSeq[index - 1] + 1) continue;
+      const gap = {
+        seq: sortedSeq[index],
+        reason: `seq jumped from ${sortedSeq[index - 1]} to ${sortedSeq[index]} — an entry is missing`,
+      };
+      if (sealedThroughSeq !== null && sortedSeq[index] <= sealedThroughSeq) sealedGaps.push(gap);
+      else tampered.push(gap);
+    }
+
+    // A finding is live when it belongs to sequence history above the seal
+    // boundary — by `seq`, not by file position. Interleaved entries have no
+    // `seq`, so the seal is applied to them by position.
+    const isLive = (finding) => sealedThroughSeq === null || finding.seq > sealedThroughSeq;
+    const liveForks = forks.filter(isLive);
+    const liveInterleaved = lastSealIndex < 0
+      ? interleaved
+      : interleavedAt.filter((at) => at > lastSealIndex).length;
+
+    const sealedForks = forks.length - liveForks.length;
+    const sealedInterleaved = interleaved - liveInterleaved;
+    const sealedNote = sealedCount === 0
+      ? ''
+      : `${sealedForks} fork${sealedForks === 1 ? '' : 's'} and ${sealedInterleaved} interleaved `
+        + `entr${sealedInterleaved === 1 ? 'y' : 'ies'} sealed as history`
+        + `${sealedThroughSeq === null ? '' : ` through seq ${sealedThroughSeq}`}`;
+    // Clause 8: corrupt lines are never graded on their own, but the reason
+    // names them whenever there is nothing louder to say.
+    const corruptNote = this.corruptLines > 0
+      ? `${this.corruptLines} unparsable line(s) (reported, not graded)`
+      : '';
+    const quietNote = [sealedNote, corruptNote].filter((note) => note.length > 0).join('; ');
+
+    const status = tampered.length > 0
+      ? 'tampered'
+      : (liveForks.length > 0
+        ? 'forked'
+        : (liveInterleaved > 0 ? 'discontinuity' : 'verified'));
+    return {
+      status,
+      // `ok` answers the operator's question — was anything rewritten? — while
+      // `clean` additionally requires that there is nothing left to look at, now
+      // that sealed history is no longer something to look at.
+      ok: status !== 'tampered',
+      tampered: status === 'tampered',
+      clean: status === 'verified',
+      entries: entries.length,
+      chained,
+      legacy,
+      interleaved,
+      liveInterleaved,
+      forks: forks.length,
+      liveForks: liveForks.length,
+      // Sequence gaps resuming in live history are graded `tampered` (a missing
+      // entry is rewrite-shaped), so this pair reports the sealed ones only.
+      discontinuities: sealedGaps.length,
+      liveDiscontinuities: 0,
+      corrupt: this.corruptLines,
+      brokenAt: tampered.length > 0
+        ? tampered[0].seq
+        : (liveForks.length > 0 ? liveForks[0].seq : null),
+      reason: tampered.length > 0
+        ? tampered[0].reason
+        : (liveForks.length > 0
+          ? liveForks[0].reason
+          : (liveInterleaved > 0
+            ? `${liveInterleaved} unchained entr${liveInterleaved === 1 ? 'y' : 'ies'} among chained ones (two generations wrote this chain)`
+            : quietNote)),
+      sealed: sealedCount === 0
+        ? null
+        : {
+          count: sealedCount,
+          boundaryIndex: lastSealIndex,
+          throughSeq: sealedThroughSeq,
+          forks: sealedForks,
+          interleaved: sealedInterleaved,
+        },
+      chainedRange: firstChainedIndex < 0 ? null : [firstChainedIndex, lastChainedIndex],
+    };
+  }
+
+  /**
+   * Every entry, oldest first, as detached copies.
+   * @returns the entries.
+   */
+  get entries() {
+    return this._readAll().map((entry) => structuredClone(entry));
+  }
+
+  /** @returns {Record<string, unknown>[]} the cached read. */
+  _readAll() {
+    if (this.path !== null) {
+      let stats;
+      try {
+        stats = statSync(this.path);
+      } catch {
+        // A missing chain file reads as empty; deployers should alert on it.
+        this.corruptLines = 0;
+        return [];
+      }
+      const key = `${stats.mtimeMs}:${stats.size}`;
+      if (key !== this._cacheKey) {
+        const entries = [];
+        let corrupt = 0;
+        for (const line of readFileSync(this.path, 'utf8').split('\n')) {
+          const trimmed = line.trim();
+          if (trimmed.length === 0) continue;
+          try {
+            entries.push(JSON.parse(trimmed));
+          } catch {
+            corrupt += 1;
+          }
+        }
+        this._cacheKey = key;
+        this._cacheEntries = entries;
+        this.corruptLines = corrupt;
+      }
+      return this._cacheEntries;
+    }
+    this.corruptLines = 0;
+    return this._buffer;
+  }
+
+  /**
+   * Read the chain's continuation state — the last entry carrying `seq` and
+   * `hash` — fresh from the source, never from a per-instance cache. Also
+   * reports whether the file ends mid-line (a crash-torn tail), so the next
+   * append can terminate the torn line instead of fusing into it.
+   * @returns {{ seq: number, hash: string|null, tornTail: boolean }} the next `seq` and `prev`.
+   */
+  _tail() {
+    if (this.path === null) {
+      const last = [...this._buffer].reverse()
+        .find((entry) => typeof entry?.seq === 'number' && typeof entry?.hash === 'string');
+      return last === undefined
+        ? { seq: this._buffer.length, hash: null, tornTail: false }
+        : { seq: last.seq + 1, hash: String(last.hash), tornTail: false };
+    }
+    let text = '';
+    try {
+      const size = statSync(this.path).size;
+      if (size > 0) {
+        const length = Math.min(size, TAIL_READ_BYTES);
+        const handle = openSync(this.path, 'r');
+        try {
+          const buffer = Buffer.alloc(length);
+          let offset = 0;
+          while (offset < length) {
+            const read = readSync(handle, buffer, offset, length - offset, size - length + offset);
+            if (read <= 0) break;
+            offset += read;
+          }
+          text = buffer.subarray(0, offset).toString('utf8');
+        } finally {
+          closeSync(handle);
+        }
+      }
+    } catch {
+      return { seq: 0, hash: null, tornTail: false };
+    }
+    const tornTail = text.length > 0 && !text.endsWith('\n');
+    const lines = text.split('\n').filter((line) => line.trim().length > 0);
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+      try {
+        const entry = JSON.parse(lines[index]);
+        if (typeof entry?.seq === 'number' && typeof entry?.hash === 'string') {
+          return { seq: entry.seq + 1, hash: entry.hash, tornTail };
+        }
+      } catch {
+        // A torn or corrupt trailing line is skipped: the verifier reports it
+        // rather than the writer refusing to continue.
+      }
+    }
+    // No chained entry in the tail window: the next entry becomes the root of
+    // the verifiable suffix, numbered after every line already there. The full
+    // line count is read only on this path — the common case never pays for it.
+    let count = 0;
+    try {
+      count = readFileSync(this.path, 'utf8').split('\n').filter((line) => line.trim().length > 0).length;
+    } catch {
+      count = 0;
+    }
+    return { seq: count, hash: null, tornTail };
+  }
+
+  /**
+   * Take the chain lock, retrying briefly.
+   *
+   * `wx` is the atomic create — it fails when the lock already exists, which is
+   * the mutual exclusion. A stale lock older than the timeout is broken, so a
+   * crashed process cannot wedge every future append.
+   * @returns {() => void} the release function.
+   */
+  _lock() {
+    const lockPath = `${this.path}.lock`;
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    mkdirSync(dirname(this.path), { recursive: true });
+    for (;;) {
+      try {
+        closeSync(openSync(lockPath, 'wx'));
+        return () => {
+          try {
+            unlinkSync(lockPath);
+          } catch {
+            // Another writer already cleared it; nothing to release.
+          }
+        };
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw error;
+        try {
+          if (Date.now() - statSync(lockPath).mtimeMs > LOCK_TIMEOUT_MS) {
+            unlinkSync(lockPath);
+            continue;
+          }
+        } catch {
+          continue; // The lock vanished between the check and the stat: retry.
+        }
+        if (Date.now() > deadline) {
+          throw new Error(`dsh-audit-chain: chain lock ${lockPath} held longer than ${LOCK_TIMEOUT_MS}ms`);
+        }
+        // A short synchronous nap: `record` is called from a synchronous guard,
+        // so there is no event loop to yield to here.
+        const until = Date.now() + LOCK_BACKOFF_MS;
+        while (Date.now() < until) { /* spin */ }
+      }
+    }
+  }
+}
+
+/**
+ * Re-walk a chain and grade it — the functional twin of `ChainLog.verify()`,
+ * for callers that only ever read.
+ * @param path - the chain path, or `null` to verify nothing.
+ * @returns the verification reading.
+ */
+export function verifyChain(path) {
+  return new ChainLog(path).verify();
+}
+
+/**
+ * Resolve the chain directory the way the guards do, so all plugins can land
+ * in one chain by default.
+ * @param config - a resolved policy with an `audit.dir` field.
+ * @param defaultRoot - the fallback root (`$DSH_HOME` or `~/.dsh`).
+ * @returns the directory, or `null` to disable the on-disk chain.
+ */
+export function resolveChainDir(config, defaultRoot) {
+  const dir = config.audit.dir;
+  if (dir === '') return null;
+  if (typeof dir === 'string' && dir.length > 0) return dir;
+  return join(defaultRoot, 'entropy-guard');
+}
+
+/**
+ * Turn one agent id into the same chain-file stem the guards use, so that
+ * "same chain" is literally the same file.
+ * @param agentId - the session/agent id.
+ * @returns the file stem.
+ */
+export function chainStem(agentId) {
+  if (agentId === null) return 'process';
+  return String(agentId).replace(/[^A-Za-z0-9._-]/gu, '_').slice(0, 96) || 'agent';
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@cyd-prc/dsh-audit-chain",
+  "version": "0.1.0",
+  "private": false,
+  "description": "The one tamper-evident JSONL audit chain every dsh guard shares: a multi-writer-safe writer (exclusive lock, fresh tail, torn-tail termination) and the chain-grading contract verifier. Extracted from dsh-entropy-guard and dsh-shape-guard, where the copies drifted; one chain, one implementation.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Wang Miaosheng (https://orcid.org/0009-0003-2767-2421)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CYD-PRC/dsh-audit-chain.git"
+  },
+  "homepage": "https://github.com/CYD-PRC/dsh-audit-chain#readme",
+  "bugs": {
+    "url": "https://github.com/CYD-PRC/dsh-audit-chain/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "lib",
+    "tools",
+    "test",
+    "docs",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "audit-chain",
+    "tamper-evident",
+    "jsonl",
+    "sha256",
+    "chain-grading",
+    "entropy-guard",
+    "shape-guard",
+    "threat-gate"
+  ]
+}