@cyd-prc/dsh-audit-chain 0.1.0

package/test/core.test.mjs

@@ -0,0 +1,478 @@
+/**
+ * Behavioural tests for the shared audit chain.
+ *
+ * The suite is the union of the anchors that pinned the two implementations this
+ * package was extracted from: entropy-guard's defects 14/15/16/19/20 and
+ * shape-guard's I7–I13 / S1–S4, rewritten against `ChainLog` so the shared
+ * implementation cannot drift from either history. The chain-grading contract
+ * (docs/CHAIN-GRADING-CONTRACT.md) is the prose; this file is the recomputable
+ * definition.
+ *
+ * Run: node --test test/core.test.mjs
+ *      (pass the file: the directory form `node --test test/` reports nothing on
+ *       Node 24, which has twice been mistaken for a broken suite)
+ */
+
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { appendFileSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, it } from 'node:test';
+import { gzipSync } from 'node:zlib';
+
+import {
+  ChainLog,
+  auditReplacer,
+  chainStem,
+  encodeEntry,
+  hashEntry,
+  resolveChainDir,
+  verifyChain,
+} from '../index.js';
+import {
+  jsonEquivalent,
+  looksLikeText,
+  matchesReference,
+  readTarGz,
+  sameTextModuloLineEndings,
+  scanShippedReferences,
+  treeHeadOf,
+} from '../tools/verify-release.mjs';
+
+/** The repository root, for driving the shipped tools in a subprocess. */
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** A hand-built entry with a self-consistent hash, for branch/tamper fixtures. */
+function branchEntry(seq, prev, fields = {}) {
+  const base = { ts: 1, seq, ...fields, kind: fields.kind ?? 'gate_decision', prev };
+  return { ...base, hash: hashEntry(base) };
+}
+
+describe('writing', () => {
+  it('chains entries with monotonic seqs and hash links', () => {
+    const audit = new ChainLog();
+    const first = audit.record('gate_decision', { admitted: true });
+    const second = audit.record('gate_decision', { admitted: false });
+    assert.equal(first.seq, 0);
+    assert.equal(first.prev, null);
+    assert.equal(second.seq, 1);
+    assert.equal(second.prev, first.hash);
+    assert.match(first.hash, /^[0-9a-f]{64}$/);
+  });
+
+  it('sanitizes non-finite numbers so the chain stays strict JSON', () => {
+    const audit = new ChainLog();
+    const entry = audit.record('gate_decision', { utility: Number.NaN, nested: { v: Number.POSITIVE_INFINITY } });
+    assert.equal(entry.utility, null);
+    assert.equal(entry.utility_nonfinite, 'nan');
+    assert.equal(entry.nested.v, '+inf');
+    assert.doesNotThrow(() => JSON.parse(JSON.stringify(entry)));
+  });
+
+  it('degrades unknown values to their string form and survives cycles', () => {
+    const audit = new ChainLog();
+    const cyclic = { name: 'x' };
+    cyclic.self = cyclic;
+    const entry = audit.record('probe', { cyclic, fn: () => 1, big: 10n });
+    assert.equal(entry.cyclic.self, '<truncated:depth-or-cycle>');
+    assert.equal(entry.fn, '() => 1');
+    assert.equal(entry.big, '10');
+  });
+
+  it('returns deep copies so a caller cannot mutate the ledger', () => {
+    const audit = new ChainLog();
+    const returned = audit.record('probe', { nested: { a: 1 } });
+    returned.nested.a = 99;
+    assert.equal(audit.entries[0].nested.a, 1);
+  });
+
+  it('continues an existing on-disk chain instead of restarting it', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'chain-continue-'));
+    const path = join(dir, 'chain.jsonl');
+    try {
+      const first = new ChainLog(path);
+      const a = first.record('one', {});
+      const b = first.record('two', {});
+      const reopened = new ChainLog(path);
+      const c = reopened.record('three', {});
+      assert.equal(a.prev, null);
+      assert.equal(c.seq, 2);
+      assert.equal(c.prev, b.hash);
+      assert.equal(reopened.verify().chained, 3);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('serialises two writers on one chain file: no duplicate seqs (defect 14)', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'chain-lock-'));
+    const path = join(dir, 'chain.jsonl');
+    try {
+      const first = new ChainLog(path);
+      const second = new ChainLog(path);
+      first.record('a', {});
+      second.record('b', {});
+      first.record('c', {});
+      // A writer that cached the tail once per instance resumed from a stale
+      // tail here and wrote a duplicate seq 1.
+      const seqs = readFileSync(path, 'utf8').trim().split('\n').map((line) => JSON.parse(line).seq);
+      assert.deepEqual(seqs, [0, 1, 2]);
+      const reading = new ChainLog(path).verify();
+      assert.equal(reading.status, 'verified');
+      assert.equal(reading.forks, 0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('terminates a crash-torn tail line before appending (defect 19)', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'chain-torn-'));
+    const path = join(dir, 'chain.jsonl');
+    try {
+      const audit = new ChainLog(path);
+      audit.record('a', {});
+      // A crash mid-write leaves a tail line with no trailing newline.
+      writeFileSync(path, `${readFileSync(path, 'utf8')}{"ts":1,"kind":"gate_dec`, 'utf8');
+      audit.record('b', {});
+      // Without termination the append fuses into the torn line: the entry is
+      // lost and the line count does not even grow.
+      const lines = readFileSync(path, 'utf8').split('\n').filter((line) => line.trim().length > 0);
+      assert.equal(lines.length, 3, 'torn line terminated, new entry on its own line');
+      const last = JSON.parse(lines[2]);
+      assert.equal(last.kind, 'b');
+      assert.equal(last.seq, 1, 'the chain continues from the last good entry');
+      const reading = new ChainLog(path).verify();
+      assert.equal(reading.status, 'verified');
+      assert.equal(reading.chained, 2);
+      assert.equal(reading.corrupt, 1, 'the torn line is reported, not silently absorbed');
+      assert.match(reading.reason, /unparsable/, 'clause 8: the reason names the corrupt line');
+      // Sealing a torn-tail chain writes a parseable entry (the M4 shape).
+      const before = audit.seal('after a torn tail');
+      assert.equal(before.corrupt, 1);
+      const afterSeal = readFileSync(path, 'utf8').split('\n').filter((line) => line.trim().length > 0);
+      assert.equal(JSON.parse(afterSeal.at(-1)).kind, 'chain_seal');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('grading (the contract, pinned)', () => {
+  it('verifies an untouched chain', () => {
+    const audit = new ChainLog();
+    audit.record('a', {});
+    audit.record('b', {});
+    const reading = audit.verify();
+    assert.equal(reading.status, 'verified');
+    assert.equal(reading.ok, true);
+    assert.equal(reading.chained, 2);
+    assert.equal(reading.brokenAt, null);
+  });
+
+  it('detects an edited entry', () => {
+    const audit = new ChainLog();
+    audit.record('a', {});
+    audit.record('b', {});
+    audit._buffer[0].admitted = false;
+    const reading = audit.verify();
+    assert.equal(reading.status, 'tampered');
+    assert.equal(reading.brokenAt, 0);
+    assert.match(reading.reason, /modified/);
+  });
+
+  it('detects a dropped entry twice: the link dangles and the sequence gaps', () => {
+    const audit = new ChainLog();
+    audit.record('a', {});
+    audit.record('b', {});
+    audit.record('c', {});
+    audit._buffer.splice(1, 1);
+    const reading = audit.verify();
+    assert.equal(reading.status, 'tampered');
+    assert.match(reading.reason, /names a hash no entry carries/);
+  });
+
+  it('grades a repeated seq as a fork between writers, not as a rewrite', () => {
+    const audit = new ChainLog();
+    audit.record('a', {});
+    audit.record('b', {});
+    // A second writer that loaded the same tail: a valid entry, bytes intact,
+    // hash correct — which is exactly why a fork is not a rewrite.
+    audit._buffer.push({ ...audit._buffer[1] });
+    const reading = audit.verify();
+    assert.equal(reading.status, 'forked');
+    assert.equal(reading.forks, 1);
+    assert.equal(reading.tampered, false);
+    assert.match(reading.reason, /duplicate seq 1/);
+  });
+
+  it('counts every fork instead of stopping at the first (S2/M2)', () => {
+    const audit = new ChainLog();
+    audit.record('a', {});
+    audit.record('b', {});
+    audit.record('c', {});
+    audit._buffer.push({ ...audit._buffer[1] });
+    audit._buffer.push({ ...audit._buffer[2] });
+    const reading = audit.verify();
+    assert.equal(reading.status, 'forked');
+    assert.equal(reading.forks, 2, 'a walk that stops at the first fork undercounts');
+    assert.equal(reading.liveForks, 2);
+  });
+
+  it('keeps checking links after a fork: a deleted branch entry is a rewrite', () => {
+    const a0 = branchEntry(0, null);
+    const a1 = branchEntry(1, a0.hash);
+    const b1 = branchEntry(1, a0.hash, { tool: 'writer-2' });
+    const b2 = branchEntry(2, b1.hash, { tool: 'writer-2' });
+    const audit = new ChainLog();
+    audit._buffer.push(a0, a1, b1, b2);
+    assert.equal(audit.verify().status, 'forked', 'control: the branch itself is a fork, not a rewrite');
+
+    audit._buffer.splice(2, 1);
+    const reading = audit.verify();
+    assert.equal(reading.status, 'tampered', 'a deletion after the fork must still be caught');
+    assert.match(reading.reason, /names a hash no entry carries/);
+  });
+
+  it('seals acknowledged history without dropping it', () => {
+    const audit = new ChainLog();
+    audit.record('a', {});
+    audit.record('b', {});
+    audit._buffer.push({ ...audit._buffer[1] });
+    assert.equal(audit.verify().status, 'forked');
+    const before = audit.seal('acknowledged a test fork');
+    assert.equal(before.status, 'forked');
+    const sealed = audit.verify();
+    assert.equal(sealed.status, 'verified', 'the acknowledged fork stops colouring the reading');
+    assert.equal(sealed.forks, 1, 'history is counted, not dropped');
+    assert.equal(sealed.liveForks, 0);
+    assert.equal(sealed.sealed.forks, 1);
+    assert.match(sealed.reason, /sealed as history/);
+  });
+
+  it('never seals a tamper away', () => {
+    const audit = new ChainLog();
+    audit.record('a', {});
+    audit.record('b', {});
+    audit.seal('clean at sealing time');
+    audit._buffer[0].name = 'rewritten';
+    const reading = audit.verify();
+    assert.equal(reading.status, 'tampered');
+    assert.equal(reading.ok, false);
+  });
+
+  it('still reports a fork on a live seq written after the seal', () => {
+    const audit = new ChainLog();
+    audit.record('a', {});
+    audit.seal('');
+    audit.record('b', {});
+    audit._buffer.push({ ...audit._buffer[2] });
+    const reading = audit.verify();
+    assert.equal(reading.status, 'forked');
+    assert.equal(reading.liveForks, 1);
+  });
+
+  it('keeps a sealed seq sealed even when the branch entry is written after the seal (contract §3)', () => {
+    const audit = new ChainLog();
+    audit.record('a', {});
+    audit.record('b', {});
+    audit._buffer.push({ ...audit._buffer[1] });
+    audit.seal('acknowledged the fork');
+    // A stale writer wakes up *after* the seal and appends another copy of the
+    // seq the seal already covers: acknowledged history, not a new finding.
+    audit._buffer.push({ ...audit._buffer[1] });
+    const reading = audit.verify();
+    assert.equal(reading.status, 'verified');
+    assert.equal(reading.forks, 2);
+    assert.equal(reading.liveForks, 0);
+  });
+
+  it('reports a sequence gap inside sealed history without grading it', () => {
+    const a0 = branchEntry(0, null);
+    const a1 = branchEntry(1, a0.hash);
+    const a5 = branchEntry(5, a1.hash);
+    const audit = new ChainLog();
+    audit._buffer.push(a0, a1, a5);
+    assert.equal(audit.verify().status, 'tampered', 'control: a live gap is a missing entry');
+    assert.match(audit.verify().reason, /seq jumped from 1 to 5/);
+    audit.seal('the gap is acknowledged history');
+    const reading = audit.verify();
+    assert.equal(reading.status, 'verified', 'the seal covers the seq the gap resumes at');
+    assert.equal(reading.discontinuities, 1, 'the gap is still reported');
+  });
+
+  it('grades a live interleaved generation as a discontinuity, and a sealed one as history', () => {
+    const audit = new ChainLog();
+    audit.record('a', {});
+    audit._buffer.push({ ts: 9, kind: 'gate_decision' }); // an unchained generation
+    audit.record('b', {});
+    const live = audit.verify();
+    assert.equal(live.status, 'discontinuity');
+    assert.equal(live.interleaved, 1);
+    assert.equal(live.liveInterleaved, 1);
+    audit.seal('upgrade acknowledged');
+    const sealed = audit.verify();
+    assert.equal(sealed.status, 'verified');
+    assert.equal(sealed.interleaved, 1, 'reported, not dropped');
+    assert.equal(sealed.liveInterleaved, 0);
+  });
+
+  it('keeps an unchained legacy prefix visible instead of trusted', () => {
+    const audit = new ChainLog();
+    audit._buffer.push({ ts: 1, kind: 'gate_decision', admitted: true });
+    audit.record('gate_decision', { admitted: true });
+    const reading = audit.verify();
+    assert.equal(reading.legacy, 1);
+    assert.equal(reading.chained, 1);
+    assert.equal(reading.status, 'verified');
+  });
+
+  it('reads a missing chain file as empty and counts corrupt lines', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'chain-missing-'));
+    const path = join(dir, 'chain.jsonl');
+    try {
+      assert.equal(new ChainLog(path).verify().entries, 0);
+      writeFileSync(path, `${JSON.stringify({ ts: 1, kind: 'a' })}\nnot json\n`);
+      const reading = new ChainLog(path).verify();
+      assert.equal(reading.entries, 1);
+      assert.equal(reading.corrupt, 1);
+      assert.equal(reading.status, 'verified', 'clause 8: corrupt alone never grades hostile');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('format compatibility with the historical writers', () => {
+  it('the hash payload is byte-identical under both serialisations', () => {
+    // entropy-guard hashed `JSON.stringify(base, auditReplacer)`; shape-guard
+    // hashed `encodeEntry(base, false)`. For the plain-JSON entries every
+    // writer stores, the two strings must be the same bytes — or chains written
+    // before this package existed would stop verifying.
+    const base = { ts: 1791000605.278, seq: 659, tool: 'pwsh', nested: { a: [1, 2, null], b: 'x' }, kind: 'call_rejected', prev: null };
+    assert.equal(JSON.stringify(base, auditReplacer), encodeEntry(base, false));
+    assert.equal(hashEntry(base), createHash('sha256').update(encodeEntry(base, false)).digest('hex'));
+    assert.equal(hashEntry({ ...base, hash: 'f'.repeat(64) }), hashEntry(base), 'a stored hash never re-enters its own payload');
+  });
+});
+
+describe('naming and directory helpers', () => {
+  it('turns agent ids into chain-file stems the way the guards do', () => {
+    assert.equal(chainStem('session-42'), 'session-42');
+    assert.equal(chainStem('a/b c'), 'a_b_c');
+    assert.equal(chainStem(null), 'process');
+    assert.equal(resolveChainDir({ audit: { dir: '' } }, 'x'), null, 'empty string disables the chain');
+    assert.equal(resolveChainDir({ audit: { dir: null } }, join('C:', 'dsh')), join('C:', 'dsh', 'entropy-guard'));
+  });
+});
+
+describe('release tooling', () => {
+  /** A minimal tar.gz writer, so the reader is exercised against real bytes. */
+  function buildTarGz(files) {
+    const blocks = [];
+    for (const [path, text] of Object.entries(files)) {
+      const body = Buffer.from(text, 'utf8');
+      const header = Buffer.alloc(512);
+      header.write(path, 0, 'utf8');
+      header.write(body.length.toString(8).padStart(11, '0'), 124, 'utf8');
+      header[156] = 48;
+      header.write('ustar', 257, 'utf8');
+      header.write('        ', 148, 'utf8');
+      let sum = 0;
+      for (const byte of header) sum += byte;
+      header.write(sum.toString(8).padStart(6, '0'), 148, 'utf8');
+      blocks.push(header, body, Buffer.alloc((512 - (body.length % 512)) % 512));
+    }
+    blocks.push(Buffer.alloc(1024));
+    return gzipSync(Buffer.concat(blocks));
+  }
+
+  it('treats a packer-rewritten package.json as equivalent, not as a difference', () => {
+    assert.equal(jsonEquivalent('{\n  "a": 1\n}\n', '{\n  "a": 1\n}'), true);
+    assert.equal(jsonEquivalent('{"a":1,"b":2}', '{"b":2,"a":1}'), true);
+    assert.equal(jsonEquivalent('{"a":1}', '{"a":2}'), false);
+  });
+
+  it('resolves metadata references as files, directories or globs', () => {
+    const paths = ['index.js', 'lib/chain.js', 'docs/CONTRACT.md'];
+    assert.equal(matchesReference('./index.js', paths), true);
+    assert.equal(matchesReference('lib', paths), true);
+    assert.equal(matchesReference('./docs/*.md', paths), true);
+    assert.equal(matchesReference('./missing.js', paths), false);
+  });
+
+  it('reads a .tar.gz in process, without tar', () => {
+    const artifact = readTarGz(buildTarGz({ 'package/index.js': 'export const a = 1;\n' }));
+    assert.equal(artifact.get('index.js').toString('utf8'), 'export const a = 1;\n');
+  });
+
+  it('compares text modulo line endings, so a Windows checkout cannot fake a DIFF', () => {
+    assert.equal(sameTextModuloLineEndings('a\nb\n', 'a\r\nb\r\n'), true);
+    assert.equal(sameTextModuloLineEndings('a\nb\n', 'a\nc\n'), false);
+    assert.equal(looksLikeText(Buffer.from('MIT License\n', 'utf8')), true, 'LICENSE has no extension and is text');
+    assert.equal(looksLikeText(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x00])), false, 'a PNG header is not text');
+  });
+
+  it('scans shipped code for references the artifact does not carry', () => {
+    const artifact = readTarGz(buildTarGz({
+      'package/lib/tool.mjs': 'const x = readFileSync(join(root, \'DESIGN-v1.md\'));\n',
+      'package/index.js': 'export {};\n',
+    }));
+    assert.deepEqual(scanShippedReferences(artifact).unresolved, [{ file: 'lib/tool.mjs', reference: 'DESIGN-v1.md' }]);
+  });
+
+  it('names the tree HEAD it compared against', () => {
+    const probe = spawnSync('git', ['rev-parse', '--short=7', 'HEAD'], { cwd: REPO_ROOT, encoding: 'utf8' });
+    const expected = probe.status === 0 ? probe.stdout.trim() : null;
+    assert.equal(treeHeadOf(REPO_ROOT), expected);
+    assert.equal(treeHeadOf(join(tmpdir(), 'definitely-not-a-repo')), null);
+  });
+
+  it('refuses to verify a different package with this copy', () => {
+    const tool = join(REPO_ROOT, 'tools', 'verify-release.mjs');
+    const result = spawnSync(process.execPath, [tool, '--spec', '@cyd-prc/dsh-shape-guard@0.1.6'], { encoding: 'utf8' });
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /names "@cyd-prc\/dsh-shape-guard" but this copy ships with/);
+  });
+
+  it('validates --wait as a non-negative number of seconds', () => {
+    const tool = join(REPO_ROOT, 'tools', 'verify-release.mjs');
+    const result = spawnSync(process.execPath, [tool, '--wait', '-5'], { encoding: 'utf8' });
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /--wait wants a non-negative number/);
+  });
+});
+
+describe('tools/verify-chain.mjs', () => {
+  it('never writes to the chain it audits, and grades by exit code (defect 16)', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'chain-tool-'));
+    const path = join(dir, 'chain.jsonl');
+    try {
+      const audit = new ChainLog(path);
+      audit.record('gate_decision', { admitted: true });
+      audit.record('gate_decision', { admitted: false });
+      const digest = () => createHash('sha256').update(readFileSync(path)).digest('hex');
+      const before = digest();
+      const tool = join(REPO_ROOT, 'tools', 'verify-chain.mjs');
+      for (let run = 0; run < 2; run += 1) {
+        const result = spawnSync(process.execPath, [tool, path], { encoding: 'utf8' });
+        assert.equal(result.status, 0, result.stderr);
+        assert.match(result.stdout, /^VERIFIED · entries 2 · chained 2/u);
+      }
+      assert.equal(digest(), before, 'the audited chain is byte-identical after two runs');
+      // A forked chain exits 1 and says why: duplicate the second entry — its
+      // prev resolves, so this is a branch, not a mid-file root.
+      const secondLine = readFileSync(path, 'utf8').trim().split('\n')[1];
+      appendFileSync(path, `${secondLine}\n`, 'utf8');
+      const forked = spawnSync(process.execPath, [tool, path], { encoding: 'utf8' });
+      assert.equal(forked.status, 1);
+      assert.match(forked.stdout, /^FORKED · /u);
+      const json = spawnSync(process.execPath, [tool, path, '--json'], { encoding: 'utf8' });
+      assert.equal(JSON.parse(json.stdout).status, 'forked');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/tools/verify-chain.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * Offline chain verifier.
+ *
+ * Lets anyone check the accountability claim without a running Harness: point it
+ * at an audit chain and it re-walks the SHA-256 chain, grading it by the shared
+ * contract. Read-only by construction — the tool never constructs a writer over
+ * the target, so the audited file's bytes are the same after the run as before
+ * (entropy-guard's defect 16 is why this tool has no report mode at all).
+ *
+ * Usage:
+ *   node tools/verify-chain.mjs <chain.jsonl>          # one greppable line
+ *   node tools/verify-chain.mjs <chain.jsonl> --json   # the full reading
+ *
+ * Exit code 0 = `verified`, 1 = any louder grade (or a usage failure).
+ *
+ * @module dsh-audit-chain/tools/verify-chain
+ */
+
+import { verifyChain } from '../index.js';
+
+const [target, flag] = process.argv.slice(2);
+
+if (target === undefined || target.startsWith('--')) {
+  process.stderr.write('usage: node tools/verify-chain.mjs <chain.jsonl> [--json]\n');
+  process.exit(2);
+}
+
+const reading = verifyChain(target);
+
+if (flag === '--json') {
+  process.stdout.write(`${JSON.stringify(reading, null, 2)}\n`);
+} else {
+  process.stdout.write(
+    `${reading.status.toUpperCase()} · entries ${reading.entries} · chained ${reading.chained} · `
+    + `legacy ${reading.legacy} · interleaved ${reading.interleaved} (live ${reading.liveInterleaved}) · `
+    + `forks ${reading.forks} (live ${reading.liveForks}) · corrupt ${reading.corrupt}`
+    + (reading.sealed === null ? '' : ` · sealed ${reading.sealed.count} through seq ${reading.sealed.throughSeq}`)
+    + (reading.reason.length > 0 ? ` · ${reading.reason}` : '')
+    + '\n',
+  );
+}
+
+// The operator's question is "is there anything left to look at": a sealed or
+// mixed-history chain is fine, a forked or tampered one is not.
+process.exitCode = reading.clean ? 0 : 1;