@crewhaus/audit-log 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/audit-log",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Per-tenant hash-chained JSONL audit trail for the managed-daemon target",
   "main": "src/index.ts",
@@ -12,13 +12,13 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.1"
+    "@crewhaus/errors": "0.1.2"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -30,12 +30,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,8 +1,17 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { type AuditLog, GENESIS_HASH, openAuditLog, verify } from "./index";
+import {
+  type AnchorRecord,
+  type AnchorStore,
+  type AuditLog,
+  AuditLogError,
+  GENESIS_HASH,
+  InMemoryAnchorStore,
+  openAuditLog,
+  verify,
+} from "./index";
 
 let tmp: string;
 
@@ -54,14 +63,19 @@ describe("append + read", () => {
 });
 
 describe("verify (T4)", () => {
-  test("clean chain reports ok=true", async () => {
+  test("clean chain reports ok=true and matches the tail anchor", async () => {
     const log = await makeLog();
     for (let i = 0; i < 10; i += 1) {
       await log.append({ kind: "policy_decision", payload: { i } });
     }
     const r = await verify(tmp);
     expect(r.ok).toBe(true);
-    if (r.ok) expect(r.recordsChecked).toBe(10);
+    if (r.ok) {
+      expect(r.recordsChecked).toBe(10);
+      // The _chain-tail.json anchor exists and matches the surviving tail,
+      // so the truncation guard actually ran (not the missing-anchor path).
+      expect(r.anchorChecked).toBe(true);
+    }
   });
 
   test("empty rootDir reports ok=true with 0 records", async () => {
@@ -130,6 +144,144 @@ describe("verify (T4)", () => {
       expect(r.reason).toMatch(/malformed JSON/);
     }
   });
+
+  test("a corrupt _chain-tail.json is reported, not thrown (no verifier DoS)", async () => {
+    const log = await makeLog();
+    await log.append({ kind: "model_call", payload: 1 });
+    await log.append({ kind: "model_call", payload: 2 });
+
+    // Garble the on-host anchor (a crash mid-write, or a one-byte attacker
+    // edit, leaves invalid JSON). verify must surface this as a broken link
+    // rather than crash with an unhandled JSON.parse throw.
+    writeFileSync(join(tmp, "_chain-tail.json"), "{ this is not valid json");
+
+    const r = await verify(tmp);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.reason).toMatch(/chain-tail anchor unreadable/);
+      expect(r.file).toMatch(/_chain-tail\.json$/);
+      // The chain walk itself completed before the anchor was consulted.
+      expect(r.recordsChecked).toBe(2);
+    }
+  });
+});
+
+describe("tail-truncation detection (CWE-345)", () => {
+  const readLines = (file: string): string[] =>
+    readFileSync(file, "utf8")
+      .split("\n")
+      .filter((l) => l !== "");
+
+  test("every record carries a 0-based, gapless seq", async () => {
+    const log = await makeLog();
+    for (let i = 0; i < 5; i += 1) {
+      await log.append({ kind: "model_call", payload: i });
+    }
+    const seqs: number[] = [];
+    for await (const r of log.read()) seqs.push(r.seq);
+    expect(seqs).toEqual([0, 1, 2, 3, 4]);
+  });
+
+  test("the persisted chain-tail anchor records the last seq", async () => {
+    const log = await makeLog();
+    await log.append({ kind: "model_call", payload: "a" });
+    await log.append({ kind: "model_call", payload: "b" });
+    await log.append({ kind: "model_call", payload: "c" });
+    const anchor = JSON.parse(readFileSync(join(tmp, "_chain-tail.json"), "utf8"));
+    expect(anchor.seq).toBe(2);
+    expect(anchor.day).toBe(FIXED_DAY);
+    expect(anchor.hash).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test("truncating the last record is detected via the tail anchor", async () => {
+    const log = await makeLog();
+    await log.append({ kind: "secrets_access", payload: "sensitive-1" });
+    await log.append({ kind: "secrets_access", payload: "sensitive-2" });
+    await log.append({ kind: "secrets_access", payload: "sensitive-3" });
+
+    // Attacker deletes the trailing record to erase their activity, but
+    // leaves _chain-tail.json untouched. The survivors still chain cleanly
+    // and their seq run (0,1) is gapless — only the independent anchor,
+    // which still commits to the dropped record, reveals the truncation.
+    const file = join(tmp, `${FIXED_DAY}.jsonl`);
+    const lines = readLines(file);
+    writeFileSync(file, `${lines.slice(0, -1).join("\n")}\n`);
+
+    const r = await verify(tmp);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.reason).toMatch(/chain-tail anchor mismatch/);
+      expect(r.recordsChecked).toBe(2);
+    }
+  });
+
+  test("deleting the entire newest-day file is detected", async () => {
+    const log = await makeLog();
+    await log.append({ kind: "gateway_request", payload: 1 });
+    await log.append({ kind: "gateway_request", payload: 2 });
+
+    // rm the only day file but keep the anchor: the surviving chain is now
+    // empty (ends at GENESIS) yet the anchor still points at a real hash.
+    unlinkSync(join(tmp, `${FIXED_DAY}.jsonl`));
+
+    const r = await verify(tmp);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toMatch(/chain-tail anchor mismatch/);
+  });
+
+  test("deleting a record from the middle is detected as a seq gap", async () => {
+    const log = await makeLog();
+    await log.append({ kind: "model_call", payload: 0 });
+    await log.append({ kind: "model_call", payload: 1 });
+    await log.append({ kind: "model_call", payload: 2 });
+
+    // Remove the middle line. prevHash linkage would also break, but the
+    // gapless-seq assertion fires first on the now-missing seq 1.
+    const file = join(tmp, `${FIXED_DAY}.jsonl`);
+    const lines = readLines(file);
+    writeFileSync(file, `${[lines[0], lines[2]].join("\n")}\n`);
+
+    const r = await verify(tmp);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toMatch(/seq gap|prevHash mismatch/);
+  });
+
+  test("a missing anchor is reported as a limitation, not a clean pass", async () => {
+    const log = await makeLog();
+    await log.append({ kind: "model_call", payload: 1 });
+    await log.append({ kind: "model_call", payload: 2 });
+
+    // Without the independent anchor, tail-truncation cannot be ruled out:
+    // the surviving chain is internally consistent, so verify still reports
+    // ok, but flags anchorChecked=false so callers know it is not proof of
+    // completeness.
+    unlinkSync(join(tmp, "_chain-tail.json"));
+
+    const r = await verify(tmp);
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.recordsChecked).toBe(2);
+      expect(r.anchorChecked).toBe(false);
+    }
+  });
+
+  test("a legit append after verify still chains and verifies", async () => {
+    const log = await makeLog();
+    await log.append({ kind: "model_call", payload: 1 });
+    const first = await verify(tmp);
+    expect(first.ok).toBe(true);
+
+    // Guard against over-blocking: continuing to append must keep seq
+    // monotone and the anchor in sync, so a fresh verify still passes.
+    await log.append({ kind: "model_call", payload: 2 });
+    await log.append({ kind: "model_call", payload: 3 });
+    const second = await verify(tmp);
+    expect(second.ok).toBe(true);
+    if (second.ok) {
+      expect(second.recordsChecked).toBe(3);
+      expect(second.anchorChecked).toBe(true);
+    }
+  });
 });
 
 describe("file mode (T8)", () => {
@@ -143,3 +295,324 @@ describe("file mode (T8)", () => {
     expect(mode).toBe(0o600);
   });
 });
+
+describe("off-host anchor (#156-followup)", () => {
+  const readLines = (file: string): string[] =>
+    readFileSync(file, "utf8")
+      .split("\n")
+      .filter((l) => l !== "");
+
+  const makeLogWith = (store: AnchorStore): Promise<AuditLog> =>
+    openAuditLog({ rootDir: tmp, now: fixedNow(), day: () => FIXED_DAY, anchorStore: store });
+
+  // Simulate a same-uid attacker who not only truncates the JSONL but ALSO
+  // rewrites _chain-tail.json to commit to the new (shorter) survivors — so
+  // the on-host anchor check is defeated and only the off-host store can tell.
+  const truncateAndRewriteOnHostAnchor = (keep: number): void => {
+    const file = join(tmp, `${FIXED_DAY}.jsonl`);
+    const lines = readLines(file);
+    const survivors = lines.slice(0, keep);
+    writeFileSync(file, `${survivors.join("\n")}\n`);
+    const last = JSON.parse(survivors[survivors.length - 1] as string);
+    writeFileSync(
+      join(tmp, "_chain-tail.json"),
+      JSON.stringify({ day: FIXED_DAY, hash: last.hash, seq: last.seq }),
+    );
+  };
+
+  test("append best-effort mirrors the tail to the store", async () => {
+    const store = new InMemoryAnchorStore();
+    const log = await makeLogWith(store);
+    const a = await log.append({ kind: "model_call", payload: 1 });
+    const b = await log.append({ kind: "model_call", payload: 2 });
+
+    const anchor = await store.getAnchor(tmp);
+    expect(anchor).toEqual({ seq: b.seq, hash: b.hash });
+    // The mirrored hash is the live tail, not a stale earlier record.
+    expect(anchor?.hash).not.toBe(a.hash);
+  });
+
+  test("THREAT: external anchor ahead of a truncated+rewritten chain fails verify", async () => {
+    const store = new InMemoryAnchorStore();
+    const log = await makeLogWith(store);
+    await log.append({ kind: "secrets_access", payload: "sensitive-1" });
+    await log.append({ kind: "secrets_access", payload: "sensitive-2" });
+    await log.append({ kind: "secrets_access", payload: "sensitive-3" });
+
+    // The external store now witnesses seq 2. Attacker drops the last record
+    // AND rewrites the on-host anchor to match the survivors (seq 1).
+    truncateAndRewriteOnHostAnchor(2);
+
+    // On-host-only verify is fooled — the lockstep rewrite makes survivors +
+    // _chain-tail.json mutually consistent. This is the gap the follow-up closes.
+    const fooled = await verify(tmp);
+    expect(fooled.ok).toBe(true);
+    if (fooled.ok) expect(fooled.externalAnchorChecked).toBe(false);
+
+    // With the off-host anchor consulted, the dropped seq 2 is caught.
+    const caught = await verify(tmp, { anchorStore: store });
+    expect(caught.ok).toBe(false);
+    if (!caught.ok) {
+      expect(caught.reason).toMatch(/external anchor mismatch/);
+      expect(caught.reason).toMatch(/seq 2/);
+      expect(caught.recordsChecked).toBe(2);
+    }
+  });
+
+  test("external anchor catches a wholesale delete that also removed the on-host anchor", async () => {
+    const store = new InMemoryAnchorStore();
+    const log = await makeLogWith(store);
+    await log.append({ kind: "gateway_request", payload: 1 });
+    await log.append({ kind: "gateway_request", payload: 2 });
+
+    // Attacker rm's the day file AND the on-host anchor — nothing local is
+    // left to contradict an empty trail. The external anchor still witnesses seq 1.
+    unlinkSync(join(tmp, `${FIXED_DAY}.jsonl`));
+    unlinkSync(join(tmp, "_chain-tail.json"));
+
+    const r = await verify(tmp, { anchorStore: store });
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toMatch(/external anchor mismatch/);
+  });
+
+  test("external anchor catches a same-seq in-place tail rewrite", async () => {
+    const store = new InMemoryAnchorStore();
+    const log = await makeLogWith(store);
+    await log.append({ kind: "model_call", payload: "a" });
+    const tail = await log.append({ kind: "model_call", payload: "b" });
+
+    // Re-forge the tail record's payload and re-chain it so the local walk +
+    // on-host anchor accept it; the external anchor still pins the old hash.
+    const file = join(tmp, `${FIXED_DAY}.jsonl`);
+    const lines = readLines(file);
+    const forged = JSON.parse(lines[1] as string);
+    forged.payload = "forged";
+    // Recompute a valid hash for the forged body so the hash-chain walk passes.
+    const { createHash } = await import("node:crypto");
+    const body = {
+      ts: forged.ts,
+      version: forged.version,
+      kind: forged.kind,
+      seq: forged.seq,
+      payload: forged.payload,
+    };
+    forged.hash = createHash("sha256")
+      .update(forged.prevHash)
+      .update("|")
+      .update(JSON.stringify(body))
+      .digest("hex");
+    lines[1] = JSON.stringify(forged);
+    writeFileSync(file, `${lines.join("\n")}\n`);
+    // Rewrite on-host anchor to the forged tip (lockstep), same seq.
+    writeFileSync(
+      join(tmp, "_chain-tail.json"),
+      JSON.stringify({ day: FIXED_DAY, hash: forged.hash, seq: forged.seq }),
+    );
+
+    expect(forged.hash).not.toBe(tail.hash);
+    const r = await verify(tmp, { anchorStore: store });
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toMatch(/external anchor mismatch/);
+  });
+
+  test("NO-REGRESSION: a chain that legitimately extends past a lagging anchor verifies", async () => {
+    // Anchor lags behind newer appends (benign best-effort put lag): verify
+    // must NOT flag it, or normal operation would be over-blocked.
+    const store = new InMemoryAnchorStore();
+    const log = await makeLogWith(store);
+    await log.append({ kind: "model_call", payload: 1 });
+    await log.append({ kind: "model_call", payload: 2 });
+    // Snapshot the store as it was at seq 1, then append more "live" records.
+    const lagging = await store.getAnchor(tmp);
+    const stale = new InMemoryAnchorStore();
+    await stale.putAnchor(tmp, lagging as AnchorRecord);
+    await log.append({ kind: "model_call", payload: 3 });
+    await log.append({ kind: "model_call", payload: 4 });
+
+    const r = await verify(tmp, { anchorStore: stale });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.recordsChecked).toBe(4);
+      expect(r.externalAnchorChecked).toBe(true);
+      expect(r.anchorChecked).toBe(true);
+    }
+  });
+
+  test("clean chain with a matching store reports externalAnchorChecked=true", async () => {
+    const store = new InMemoryAnchorStore();
+    const log = await makeLogWith(store);
+    for (let i = 0; i < 4; i += 1) await log.append({ kind: "policy_decision", payload: i });
+    const r = await verify(tmp, { anchorStore: store });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.recordsChecked).toBe(4);
+      expect(r.externalAnchorChecked).toBe(true);
+    }
+  });
+
+  test("verify without a store leaves externalAnchorChecked=false (no-op default)", async () => {
+    const log = await makeLog();
+    await log.append({ kind: "model_call", payload: 1 });
+    const r = await verify(tmp);
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.anchorChecked).toBe(true);
+      expect(r.externalAnchorChecked).toBe(false);
+    }
+  });
+
+  test("a store with no anchor yet is reported as not-checked, not a failure", async () => {
+    const log = await makeLog(); // opened WITHOUT a store, so nothing was published
+    await log.append({ kind: "model_call", payload: 1 });
+    const emptyStore = new InMemoryAnchorStore();
+    const r = await verify(tmp, { anchorStore: emptyStore });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.externalAnchorChecked).toBe(false);
+  });
+
+  test("a getAnchor that throws degrades to not-checked (never fabricates tamper)", async () => {
+    const log = await makeLog();
+    await log.append({ kind: "model_call", payload: 1 });
+    const flaky: AnchorStore = {
+      async putAnchor(): Promise<void> {},
+      async getAnchor(): Promise<AnchorRecord | undefined> {
+        throw new Error("anchor backend offline");
+      },
+    };
+    const r = await verify(tmp, { anchorStore: flaky });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.externalAnchorChecked).toBe(false);
+  });
+
+  test("a putAnchor that throws does not break the durable local append", async () => {
+    const flaky: AnchorStore = {
+      async putAnchor(): Promise<void> {
+        throw new Error("WORM bucket unreachable");
+      },
+      async getAnchor(): Promise<AnchorRecord | undefined> {
+        return undefined;
+      },
+    };
+    const log = await makeLogWith(flaky);
+    // The append must still succeed and the local chain remain verifiable.
+    const rec = await log.append({ kind: "model_call", payload: "durable" });
+    expect(rec.seq).toBe(0);
+    const r = await verify(tmp);
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.recordsChecked).toBe(1);
+  });
+
+  test("InMemoryAnchorStore is monotonic — a stale put cannot regress the tip", async () => {
+    const store = new InMemoryAnchorStore();
+    await store.putAnchor("log-a", { seq: 5, hash: "h5" });
+    // A late/replayed lower-seq put is ignored so the witnessed tip never regresses.
+    await store.putAnchor("log-a", { seq: 2, hash: "h2" });
+    expect(await store.getAnchor("log-a")).toEqual({ seq: 5, hash: "h5" });
+    // Distinct logIds are independent.
+    expect(await store.getAnchor("log-b")).toBeUndefined();
+  });
+});
+
+describe("openAuditLog input validation", () => {
+  test("an empty rootDir throws AuditLogError", async () => {
+    await expect(openAuditLog({ rootDir: "" })).rejects.toBeInstanceOf(AuditLogError);
+  });
+
+  test("a non-string rootDir throws AuditLogError with the config code", async () => {
+    // The guard is `typeof rootDir !== "string" || rootDir === ""`; exercise the
+    // typeof branch (distinct from the empty-string branch above).
+    await expect(
+      // biome-ignore lint/suspicious/noExplicitAny: deliberately bad input for the guard
+      openAuditLog({ rootDir: undefined as any }),
+    ).rejects.toMatchObject({ name: "AuditLogError", code: "config" });
+  });
+});
+
+describe("default clock + day selector", () => {
+  test("openAuditLog works with the built-in Date.now()/today defaults", async () => {
+    // Opening WITHOUT `now`/`day` exercises the default `() => Date.now()`
+    // clock and the default `todayStr` day selector (UTC ISO date). We assert
+    // structural invariants rather than a fixed value so the test stays
+    // deterministic despite using the real clock.
+    const log = await openAuditLog({ rootDir: tmp });
+    const before = Date.now();
+    const rec = await log.append({ kind: "model_call", payload: { ok: true } });
+    const after = Date.now();
+    expect(rec.seq).toBe(0);
+    expect(rec.prevHash).toBe(GENESIS_HASH);
+    expect(rec.ts).toBeGreaterThanOrEqual(before);
+    expect(rec.ts).toBeLessThanOrEqual(after);
+
+    // The day file is named for today's UTC date (what `todayStr` returns).
+    const today = new Date().toISOString().slice(0, 10);
+    const lines = readFileSync(join(tmp, `${today}.jsonl`), "utf8")
+      .split("\n")
+      .filter((l) => l !== "");
+    expect(lines).toHaveLength(1);
+
+    // read() with the default day selector must round-trip the record back.
+    const out: unknown[] = [];
+    for await (const r of log.read()) out.push(r.payload);
+    expect(out).toEqual([{ ok: true }]);
+
+    const v = await verify(tmp);
+    expect(v.ok).toBe(true);
+  });
+});
+
+describe("read with an explicit day", () => {
+  test("read({ day }) targets that day's file and round-trips its records", async () => {
+    const log = await openAuditLog({ rootDir: tmp, now: fixedNow(), day: () => FIXED_DAY });
+    await log.append({ kind: "model_call", payload: "x" });
+    await log.append({ kind: "model_call", payload: "y" });
+
+    // Explicitly request the known day instead of relying on the default.
+    const out: unknown[] = [];
+    for await (const r of log.read({ day: FIXED_DAY })) out.push(r.payload);
+    expect(out).toEqual(["x", "y"]);
+  });
+
+  test("read({ day }) for a day with no file yields nothing", async () => {
+    const log = await openAuditLog({ rootDir: tmp, now: fixedNow(), day: () => FIXED_DAY });
+    await log.append({ kind: "model_call", payload: "x" });
+
+    const out: unknown[] = [];
+    for await (const r of log.read({ day: "1999-01-01" })) out.push(r.payload);
+    expect(out).toEqual([]);
+  });
+});
+
+describe("append evaluates the day selector once (midnight-boundary safety)", () => {
+  test("the JSONL filename and the chain-tail day stay consistent across a boundary", async () => {
+    // A `day` selector that flips on its SECOND call simulates an append that
+    // straddles midnight. The record file and the persisted anchor's `day`
+    // must agree (both the FIRST value), and the chain must still verify.
+    const days = ["2026-05-08", "2026-05-09"];
+    let calls = 0;
+    const flippingDay = (): string => {
+      const d = days[Math.min(calls, days.length - 1)] as string;
+      calls += 1;
+      return d;
+    };
+
+    const log = await openAuditLog({ rootDir: tmp, now: fixedNow(), day: flippingDay });
+    const rec = await log.append({ kind: "model_call", payload: "boundary" });
+
+    // The record landed in the FIRST day's file...
+    const firstDayLines = readFileSync(join(tmp, "2026-05-08.jsonl"), "utf8")
+      .split("\n")
+      .filter((l) => l !== "");
+    expect(firstDayLines).toHaveLength(1);
+
+    // ...and the anchor's `day` matches that same file (not the flipped value).
+    const anchor = JSON.parse(readFileSync(join(tmp, "_chain-tail.json"), "utf8"));
+    expect(anchor.day).toBe("2026-05-08");
+    expect(anchor.hash).toBe(rec.hash);
+
+    // No second-day file was created by the single append.
+    expect(() => readFileSync(join(tmp, "2026-05-09.jsonl"), "utf8")).toThrow();
+
+    // The single append consumed exactly one `day()` evaluation post-fix.
+    expect(calls).toBe(1);
+  });
+});

package/src/index.ts

@@ -7,14 +7,53 @@
  *
  *   {
  *     ts: <ms epoch>, version: 1, kind: "policy_decision" | …,
+ *     seq: <0-based strictly-increasing per-log counter>,
  *     payload: <opaque JSON>,
  *     prevHash: <hex of prior line, or "GENESIS">,
- *     hash: <SHA-256(prevHash || JSON.stringify({ts,version,kind,payload}))>
+ *     hash: <SHA-256(prevHash || JSON.stringify({ts,version,kind,seq,payload}))>
  *   }
  *
  * `verify(rootDir)` walks the chain and reports the first broken link
  * (line number + reason). The chain is per-day; the previous day's
- * tail seeds the next day's `prevHash` via a one-line index file.
+ * tail seeds the next day's `prevHash` AND `seq` via a one-line index
+ * file (`_chain-tail.json` = `{ day, hash, seq }`).
+ *
+ * Tail-truncation detection. A pure hash chain is only tamper-evident
+ * for *interior* edits: deleting a suffix of the newest day file (or
+ * `rm`-ing the whole newest day) leaves the survivors internally
+ * consistent, so a naive walk would still pass. Two commitments close
+ * that gap: (1) the per-record `seq` lets `verify` assert the chain is
+ * gapless from 0 — a hole proves records were removed from the middle;
+ * (2) `verify` reads the `_chain-tail.json` anchor and fails if the
+ * surviving chain's last `{ hash, seq }` does not match the recorded
+ * tail, which catches a truncation that drops trailing records.
+ *
+ * IMPORTANT — on-host files are NOT tamper-proof against a same-uid
+ * attacker. The 0o600 mode only blocks *other* users; the gateway's own
+ * uid (or anything that compromises it) can rewrite both the JSONL and
+ * `_chain-tail.json` in lockstep, defeating the on-host anchor check
+ * above. True non-repudiation requires an anchor the audit-writer cannot
+ * rewrite — an off-host / WORM bucket, a separate-privilege service, or
+ * periodic publication to an external transparency log. A *missing*
+ * on-host anchor is therefore reported by `verify` as a known limitation
+ * (`anchorChecked: false`), never silently treated as a pass.
+ *
+ * Off-host anchor hook (`AnchorStore`). To close the same-uid lockstep
+ * gap, `openAuditLog` and `verify` accept an OPTIONAL pluggable
+ * `AnchorStore` — `{ putAnchor(logId, {seq, hash}), getAnchor(logId) }`.
+ * On each `append`, the new tail `{ seq, hash }` is *best-effort* mirrored
+ * to the store (a put failure never blocks the durable local write). On
+ * `verify`, the external anchor is consulted IN ADDITION to
+ * `_chain-tail.json`: if it witnesses a `seq` the surviving chain no
+ * longer reaches — or a tip hash that disagrees at the anchored seq —
+ * verify FAILS, catching a tail truncation that ALSO rewrote the on-host
+ * `_chain-tail.json` in lockstep (the attacker cannot reach back into the
+ * external store). An anchor that merely lags behind newer appends (the
+ * benign best-effort case) is NOT treated as a failure. This package
+ * ships only an in-memory `InMemoryAnchorStore` reference implementation
+ * for tests/dev; PRODUCTION DEPLOYMENTS SHOULD SUPPLY A WORM-BACKED STORE
+ * (object-lock bucket, append-only/separate-privilege service, or
+ * transparency log) so the audit writer's own uid cannot rewrite it.
  *
  * Files are created with mode 0o600 (owner-only) so the audit trail
  * cannot be read by other users on the host. Append uses
@@ -59,17 +98,32 @@ export type AuditKind =
   // summary. The egress-classifier's `summarizeEgress(result)` produces
   // the human-readable form that lands in the `payload_summary` field.
   | "egress_decision"
-  // Pillar 3 intent gate — permission-engine emits one event per
-  // justification-evaluated tool call. Payload shape (opaque JSON):
-  //   { toolName, justification, verdict: "allow"|"deny", reason, judgeModel }
+  // Pillar 3 intent gate — `runtime-core`'s justification gate appends one
+  // record per justification-evaluated tool call (allow OR deny) when a
+  // durable sink is wired via `runChatLoop({ justificationAuditSink })`. The
+  // CLI `run`/browser paths open a real audit-log rooted at `.crewhaus/audit`
+  // and pass it (disable with `--no-justification-audit`); the ephemeral
+  // `permission_decision` trace-bus event mirrors the same verdict + judge
+  // identity for live observability. Payload shape (opaque JSON):
+  //   { toolName, justification, verdict: "allow"|"deny", reason, judgeModel,
+  //     confidence? }
   // Stored verbatim because the justification IS the audit artifact;
-  // redacting it would defeat the purpose.
+  // redacting it would defeat the purpose. (`runtime-core` declares a minimal
+  // structural `JustificationAuditSink` rather than importing this package, to
+  // avoid a dependency cycle; this `AuditLog` satisfies that seam.)
   | "permission_justification_evaluated";
 
 export type AuditRecord = {
   readonly ts: number;
   readonly version: 1;
   readonly kind: AuditKind;
+  /**
+   * Strictly-increasing per-log sequence number, 0-based and gapless.
+   * Committed into `hash` so it cannot be rewritten without breaking the
+   * chain; `verify` asserts the run starts at 0 and has no holes, which
+   * surfaces records removed from the middle of the chain.
+   */
+  readonly seq: number;
   readonly payload: unknown;
   readonly prevHash: string;
   readonly hash: string;
@@ -84,10 +138,75 @@ export class AuditLogError extends CrewhausError {
   }
 }
 
+/**
+ * Off-host anchor commitment for a single log: the latest `{ seq, hash }`
+ * the writer has published externally. Deliberately minimal so a
+ * deployment can back it with a WORM bucket, an append-only/separate-
+ * privilege service, or a transparency log.
+ */
+export type AnchorRecord = { readonly seq: number; readonly hash: string };
+
+/**
+ * Pluggable hook for mirroring the hash-chain tail to an anchor the audit
+ * writer's own uid CANNOT rewrite. `append` calls `putAnchor` best-effort
+ * after the local write; `verify` calls `getAnchor` to cross-check the
+ * surviving chain (see file header). `logId` namespaces multiple logs in
+ * one store — `openAuditLog` defaults it to the absolute `rootDir`.
+ *
+ * Implementations should make `putAnchor` monotonic (never regress to a
+ * lower `seq`) when the backing store permits; a stale/lagging anchor is
+ * benign for `verify`, but a regressed one weakens truncation detection.
+ * PRODUCTION SHOULD SUPPLY A WORM-BACKED IMPLEMENTATION — the bundled
+ * {@link InMemoryAnchorStore} is for tests/dev only and offers no
+ * tamper-resistance on its own.
+ */
+export interface AnchorStore {
+  putAnchor(logId: string, anchor: AnchorRecord): Promise<void>;
+  getAnchor(logId: string): Promise<AnchorRecord | undefined>;
+}
+
+/**
+ * Reference {@link AnchorStore} that keeps the latest anchor per `logId`
+ * in process memory, monotonic on `seq`. Useful for tests and for wiring
+ * the `verify` cross-check in a single process; it provides NO durability
+ * or tamper-resistance and MUST NOT be relied on for non-repudiation in
+ * production — back the seam with a WORM store instead.
+ */
+export class InMemoryAnchorStore implements AnchorStore {
+  private readonly anchors: Map<string, AnchorRecord>;
+
+  constructor() {
+    this.anchors = new Map<string, AnchorRecord>();
+  }
+
+  async putAnchor(logId: string, anchor: AnchorRecord): Promise<void> {
+    const existing = this.anchors.get(logId);
+    // Monotonic: never let a later put regress the committed tip backwards.
+    if (existing !== undefined && anchor.seq < existing.seq) return;
+    this.anchors.set(logId, { seq: anchor.seq, hash: anchor.hash });
+  }
+
+  async getAnchor(logId: string): Promise<AnchorRecord | undefined> {
+    return this.anchors.get(logId);
+  }
+}
+
 export type OpenAuditLogOptions = {
   readonly rootDir: string;
   readonly now?: () => number;
   readonly day?: () => string;
+  /**
+   * Optional off-host anchor store. When supplied, every `append`
+   * best-effort mirrors the new tail `{ seq, hash }` to it (a put failure
+   * is swallowed so the durable local write is never blocked). Pass the
+   * same store + `logId` to {@link verify} to cross-check the chain.
+   */
+  readonly anchorStore?: AnchorStore;
+  /**
+   * Key under which this log's anchor is stored in `anchorStore`. Defaults
+   * to the absolute `rootDir`, letting one store hold many logs.
+   */
+  readonly logId?: string;
 };
 
 export interface AuditLog {
@@ -96,7 +215,7 @@ export interface AuditLog {
 }
 
 function hashBody(
-  body: { ts: number; version: 1; kind: AuditKind; payload: unknown },
+  body: { ts: number; version: 1; kind: AuditKind; seq: number; payload: unknown },
   prevHash: string,
 ): string {
   return createHash("sha256")
@@ -106,6 +225,24 @@ function hashBody(
     .digest("hex");
 }
 
+/**
+ * Recompute a record's hash from its own fields — the exact derivation
+ * `append` and `verify` use. Lets an external consumer (e.g.
+ * `@crewhaus/compliance-controls`) re-check a record's body↔hash consistency
+ * without re-reading the log files. Compare the result against `record.hash`:
+ * a mismatch means the body (payload/kind/ts/seq) was altered after signing.
+ */
+export function recomputeRecordHash(record: AuditRecord): string {
+  const body = {
+    ts: record.ts,
+    version: record.version,
+    kind: record.kind,
+    seq: record.seq,
+    payload: record.payload,
+  };
+  return hashBody(body, record.prevHash);
+}
+
 function todayStr(): string {
   return new Date().toISOString().slice(0, 10);
 }
@@ -114,7 +251,7 @@ function indexPath(rootDir: string): string {
   return join(rootDir, "_chain-tail.json");
 }
 
-type ChainTail = { readonly day: string; readonly hash: string };
+type ChainTail = { readonly day: string; readonly hash: string; readonly seq: number };
 
 function readChainTail(rootDir: string): ChainTail | undefined {
   const p = indexPath(rootDir);
@@ -122,9 +259,9 @@ function readChainTail(rootDir: string): ChainTail | undefined {
   return JSON.parse(readFileSync(p, "utf8")) as ChainTail;
 }
 
-function writeChainTail(rootDir: string, day: string, hash: string): void {
+function writeChainTail(rootDir: string, day: string, hash: string, seq: number): void {
   const p = indexPath(rootDir);
-  writeFileSync(p, JSON.stringify({ day, hash }), { mode: 0o600 });
+  writeFileSync(p, JSON.stringify({ day, hash, seq }), { mode: 0o600 });
 }
 
 export async function openAuditLog(opts: OpenAuditLogOptions): Promise<AuditLog> {
@@ -134,17 +271,46 @@ export async function openAuditLog(opts: OpenAuditLogOptions): Promise<AuditLog>
   mkdirSync(opts.rootDir, { recursive: true, mode: 0o700 });
   const now = opts.now ?? ((): number => Date.now());
   const day = opts.day ?? todayStr;
+  const anchorStore = opts.anchorStore;
+  const logId = opts.logId ?? opts.rootDir;
 
   return {
     async append(input: AppendInput): Promise<AuditRecord> {
       const tail = readChainTail(opts.rootDir);
       const prevHash = tail?.hash ?? GENESIS_HASH;
-      const body = { ts: now(), version: 1 as const, kind: input.kind, payload: input.payload };
+      // First record gets seq 0; thereafter strictly increment the tail's
+      // seq. A pre-`seq` anchor (`seq` absent) is treated as -1 so the next
+      // record starts the gapless run at 0.
+      const seq = (tail?.seq ?? -1) + 1;
+      const body = {
+        ts: now(),
+        version: 1 as const,
+        kind: input.kind,
+        seq,
+        payload: input.payload,
+      };
       const hash = hashBody(body, prevHash);
       const record: AuditRecord = { ...body, prevHash, hash };
-      const file = join(opts.rootDir, `${day()}.jsonl`);
+      // Evaluate the day selector exactly once: a second call could straddle
+      // a midnight boundary (with the default UTC-date `day`), writing the
+      // record to one day's file while committing the tail under the next
+      // day — leaving the JSONL filename and the anchor's `day` inconsistent.
+      const today = day();
+      const file = join(opts.rootDir, `${today}.jsonl`);
       appendFileSync(file, `${JSON.stringify(record)}\n`, { mode: 0o600 });
-      writeChainTail(opts.rootDir, day(), hash);
+      writeChainTail(opts.rootDir, today, hash, seq);
+      // Best-effort: mirror the new tail to the off-host anchor. A failure
+      // here (network/WORM hiccup) must NOT fail the durable local append —
+      // the chain remains internally verifiable, and a lagging external
+      // anchor is benign for `verify` (it only ever flags an anchor that is
+      // AHEAD of a truncated chain, never one that trails).
+      if (anchorStore !== undefined) {
+        try {
+          await anchorStore.putAnchor(logId, { seq, hash });
+        } catch {
+          // Swallowed by design — see comment above.
+        }
+      }
       return record;
     },
     read(readOpts: { day?: string } = {}): AsyncIterable<AuditRecord> {
@@ -178,7 +344,30 @@ async function* readDay(rootDir: string, day: string): AsyncIterable<AuditRecord
 }
 
 export type VerifyResult =
-  | { readonly ok: true; readonly recordsChecked: number }
+  | {
+      readonly ok: true;
+      readonly recordsChecked: number;
+      /**
+       * Whether the surviving chain was matched against the independent
+       * on-host `_chain-tail.json` anchor. `false` means the anchor was
+       * absent, so tail-truncation could NOT be ruled out — `ok: true` here
+       * attests only that the survivors are internally consistent and
+       * gapless from 0, not that nothing was dropped off the end. Callers
+       * that need non-repudiation must treat `ok && !anchorChecked` as a
+       * limitation, not a clean bill of health. (And see the file header:
+       * even a present on-host anchor is rewritable by a same-uid attacker.)
+       */
+      readonly anchorChecked: boolean;
+      /**
+       * Whether an off-host {@link AnchorStore} was supplied AND held an
+       * anchor that was cross-checked against the surviving chain. `false`
+       * means no store was passed, or it had no anchor yet — so a same-uid
+       * lockstep rewrite of the on-host anchor could NOT be ruled out. Only
+       * `ok && externalAnchorChecked` attests that an anchor the writer
+       * cannot rewrite agreed with the chain tip.
+       */
+      readonly externalAnchorChecked: boolean;
+    }
   | {
       readonly ok: false;
       readonly recordsChecked: number;
@@ -187,19 +376,69 @@ export type VerifyResult =
       readonly reason: string;
     };
 
+/**
+ * Optional cross-check inputs for {@link verify}. Supply the same
+ * `anchorStore` (and matching `logId`) used when the log was opened to
+ * have `verify` consult the off-host anchor in addition to the on-host
+ * `_chain-tail.json`. Both are optional and back-compatible — calling
+ * `verify(rootDir)` keeps the original on-host-only behaviour.
+ */
+export type VerifyOptions = {
+  readonly anchorStore?: AnchorStore;
+  readonly logId?: string;
+};
+
 /**
  * Walk every `<rootDir>/*.jsonl` chain, verifying each record's
- * `hash` against `SHA-256(prevHash || canonical-body)` and that
- * `prevHash` matches the previous record's `hash`. Returns the first
- * broken link (file + line number + reason) or `{ ok: true }` if the
- * full chain is intact.
+ * `hash` against `SHA-256(prevHash || canonical-body)`, that `prevHash`
+ * matches the previous record's `hash`, and that `seq` is gapless from
+ * 0. After the walk, the surviving chain's last `{ hash, seq }` is
+ * matched against the independent on-host `_chain-tail.json` anchor so a
+ * dropped suffix (tail truncation / newest-day deletion) is caught.
+ *
+ * If a `{ anchorStore }` is supplied (see {@link VerifyOptions}), the
+ * off-host anchor is consulted IN ADDITION to `_chain-tail.json`: when it
+ * witnesses a `seq` the surviving chain no longer reaches — or a tip hash
+ * that disagrees at the anchored seq — verify FAILS. This catches a tail
+ * truncation that ALSO rewrote the on-host anchor in lockstep, since a
+ * same-uid attacker cannot reach into the external (ideally WORM) store.
+ * An external anchor that merely lags BEHIND newer appends (the benign
+ * best-effort case) is not a failure.
+ *
+ * Returns the first broken link (file + line number + reason), or
+ * `{ ok: true }` if the chain is intact. On success, `anchorChecked`
+ * reports whether the on-host tail anchor was present and matched, and
+ * `externalAnchorChecked` whether an off-host anchor was supplied and
+ * cross-checked; `false` on either means that gap could not be ruled out
+ * (a limitation, not a pass — see the file header on same-uid tamper).
  */
-export async function verify(rootDir: string): Promise<VerifyResult> {
-  if (!existsSync(rootDir)) return { ok: true, recordsChecked: 0 };
+export async function verify(rootDir: string, options: VerifyOptions = {}): Promise<VerifyResult> {
+  if (!existsSync(rootDir)) {
+    // No local chain at all. Even so, an external anchor may witness records
+    // that a wholesale deletion (rootDir rm'd) destroyed — cross-check it
+    // against the empty (GENESIS-tipped, seq -1) chain before passing.
+    const empty = await crossCheckExternalAnchor(rootDir, options, GENESIS_HASH, -1);
+    if (empty !== undefined && !empty.ok) {
+      return {
+        ok: false,
+        recordsChecked: 0,
+        file: empty.file,
+        line: empty.line,
+        reason: empty.reason,
+      };
+    }
+    return {
+      ok: true,
+      recordsChecked: 0,
+      anchorChecked: false,
+      externalAnchorChecked: empty?.externalAnchorChecked ?? false,
+    };
+  }
   const files = readdirSync(rootDir)
     .filter((f) => f.endsWith(".jsonl"))
     .sort();
   let prevHash = GENESIS_HASH;
+  let expectedSeq = 0;
   let recordsChecked = 0;
   for (const f of files) {
     const file = join(rootDir, f);
@@ -235,7 +474,18 @@ export async function verify(rootDir: string): Promise<VerifyResult> {
             reason: `prevHash mismatch — expected "${prevHash}", got "${r.prevHash}"`,
           };
         }
-        const body = { ts: r.ts, version: r.version, kind: r.kind, payload: r.payload };
+        if (r.seq !== expectedSeq) {
+          stream.close();
+          rl.close();
+          return {
+            ok: false,
+            recordsChecked,
+            file,
+            line: lineNumber,
+            reason: `seq gap — expected ${expectedSeq}, got ${r.seq}`,
+          };
+        }
+        const body = { ts: r.ts, version: r.version, kind: r.kind, seq: r.seq, payload: r.payload };
         const expected = hashBody(body, r.prevHash);
         if (r.hash !== expected) {
           stream.close();
@@ -249,6 +499,7 @@ export async function verify(rootDir: string): Promise<VerifyResult> {
           };
         }
         prevHash = r.hash;
+        expectedSeq = r.seq + 1;
         recordsChecked += 1;
       }
     } finally {
@@ -256,5 +507,143 @@ export async function verify(rootDir: string): Promise<VerifyResult> {
       stream.close();
     }
   }
-  return { ok: true, recordsChecked };
+
+  const lastSeq = expectedSeq - 1;
+
+  // Off-host anchor check FIRST: the external store is the only commitment a
+  // same-uid attacker cannot rewrite, so it is what catches a truncation that
+  // also rewrote `_chain-tail.json` in lockstep. (See file header.)
+  const external = await crossCheckExternalAnchor(rootDir, options, prevHash, lastSeq);
+  if (external !== undefined && !external.ok) {
+    return {
+      ok: false,
+      recordsChecked,
+      file: external.file,
+      line: external.line,
+      reason: external.reason,
+    };
+  }
+  const externalAnchorChecked = external?.externalAnchorChecked ?? false;
+
+  // On-host anchor check: compare the surviving chain's last { hash, seq }
+  // against the independent _chain-tail.json. A truncation that drops trailing
+  // records leaves the survivors internally consistent, so this anchor — not
+  // the walk above — is what catches it. A missing anchor is reported
+  // (anchorChecked: false), never silently treated as a clean pass. NOTE: an
+  // on-host anchor is rewritable by a same-uid attacker (see header); it
+  // defends only against truncation by a party that does NOT also rewrite the
+  // anchor in lockstep — which is exactly what the external anchor above adds.
+  // A corrupt/partially-written `_chain-tail.json` (truncated by a crash, or
+  // garbled by an attacker) must be REPORTED as a broken link, not crash the
+  // verifier with an unhandled JSON.parse throw — mirroring how a malformed
+  // JSONL line is surfaced above. Throwing here would let a one-byte anchor
+  // corruption turn `verify` into a denial of service.
+  let tail: ChainTail | undefined;
+  try {
+    tail = readChainTail(rootDir);
+  } catch (err) {
+    return {
+      ok: false,
+      recordsChecked,
+      file: indexPath(rootDir),
+      line: 0,
+      reason: `chain-tail anchor unreadable — ${(err as Error).message}`,
+    };
+  }
+  if (tail === undefined) {
+    return { ok: true, recordsChecked, anchorChecked: false, externalAnchorChecked };
+  }
+  if (tail.hash !== prevHash) {
+    return {
+      ok: false,
+      recordsChecked,
+      file: indexPath(rootDir),
+      line: 0,
+      reason:
+        `chain-tail anchor mismatch — anchor records hash "${tail.hash}" ` +
+        `but surviving chain ends at "${prevHash}" (records were dropped from the tail)`,
+    };
+  }
+  // The seq field is optional in legacy anchors; only assert when present.
+  if (typeof tail.seq === "number" && tail.seq !== lastSeq) {
+    return {
+      ok: false,
+      recordsChecked,
+      file: indexPath(rootDir),
+      line: 0,
+      reason:
+        `chain-tail anchor mismatch — anchor records seq ${tail.seq} ` +
+        `but surviving chain ends at seq ${lastSeq} (records were dropped from the tail)`,
+    };
+  }
+  return { ok: true, recordsChecked, anchorChecked: true, externalAnchorChecked };
+}
+
+/**
+ * Cross-check the surviving chain tip (`tipHash` at `lastSeq`; an empty
+ * chain is `GENESIS_HASH` at `-1`) against an off-host {@link AnchorStore}.
+ *
+ * Threat model — the store witnesses the highest tail the writer published.
+ *  - external `seq > lastSeq`  → the chain no longer reaches a record the
+ *    anchor saw ⇒ tail truncation (even if `_chain-tail.json` was rewritten
+ *    in lockstep, which the attacker cannot do to the external store) → FAIL.
+ *  - external `seq === lastSeq` but `hash !== tipHash` → the tip was rewritten
+ *    in place at the anchored height → FAIL.
+ *  - external `seq < lastSeq` → the anchor merely lags behind newer appends
+ *    (benign best-effort `putAnchor` lag) → pass.
+ *
+ * Returns `undefined` when no store was supplied; otherwise a partial result
+ * carrying `externalAnchorChecked` (true once an anchor was actually read and
+ * compared) plus, on mismatch, the failure fields. A `getAnchor` that throws
+ * is treated as "anchor unavailable" (not consulted), not as tamper.
+ */
+type ExternalAnchorCheck =
+  | { readonly ok: true; readonly externalAnchorChecked: boolean }
+  | {
+      readonly ok: false;
+      readonly file: string;
+      readonly line: number;
+      readonly reason: string;
+      readonly externalAnchorChecked: boolean;
+    };
+
+async function crossCheckExternalAnchor(
+  rootDir: string,
+  options: VerifyOptions,
+  tipHash: string,
+  lastSeq: number,
+): Promise<ExternalAnchorCheck | undefined> {
+  const store = options.anchorStore;
+  if (store === undefined) return undefined;
+  const logId = options.logId ?? rootDir;
+  let anchor: AnchorRecord | undefined;
+  try {
+    anchor = await store.getAnchor(logId);
+  } catch {
+    // Anchor backend unavailable: cannot rule the truncation gap in OR out,
+    // so report "not checked" rather than fabricating a pass or a failure.
+    return { ok: true, externalAnchorChecked: false };
+  }
+  if (anchor === undefined) return { ok: true, externalAnchorChecked: false };
+
+  if (anchor.seq > lastSeq) {
+    return {
+      ok: false,
+      file: "<external-anchor>",
+      line: 0,
+      reason: `external anchor mismatch — store witnesses seq ${anchor.seq} (hash "${anchor.hash}") but surviving chain ends at seq ${lastSeq} (records were dropped from the tail and the on-host anchor rewritten in lockstep)`,
+      externalAnchorChecked: true,
+    };
+  }
+  if (anchor.seq === lastSeq && anchor.hash !== tipHash) {
+    return {
+      ok: false,
+      file: "<external-anchor>",
+      line: 0,
+      reason: `external anchor mismatch — store records hash "${anchor.hash}" at seq ${anchor.seq} but surviving chain tip is "${tipHash}" (the tail record was rewritten in place)`,
+      externalAnchorChecked: true,
+    };
+  }
+  // anchor.seq < lastSeq → benign lag; or matched tip → consistent.
+  return { ok: true, externalAnchorChecked: true };
 }