Data integrity and audit trail specification

1. Purpose

This document specifies the audit trail of Countersign 1.0.0 precisely enough for an auditor to verify a trail without the application, states what the integrity mechanisms detect and what they do not, maps the design to the ALCOA+ attributes, and gives the procedures for anchoring and review. Sources: lib/types.ts, lib/engine.ts (commit, stable, hashEntry, replay, verifyChain), lib/sha256.ts, server/service.ts, server/storage/*.ts, db/postgres.sql.

The central design fact: the audit trail is the system of record. Nothing else is stored. The records, their versions and the configuration in effect are computed by replaying the trail. There is no second copy of the data that could disagree with its history.

2. The audit entry

One entry is written for every accepted command, and none for a refused one. Entries are JSON objects.

Content of before and after per action:

What an entry does not contain: the IP address or device of the person; a record of what was displayed; anything about refused commands or about reading.

3. How the hash is computed

3.1 Definition

hash = lowercase_hex( SHA-256( UTF-8( prevHash + canonical(entry without "hash") ) ) )

• prevHash is the 64-character string stored in the entry. It appears twice in the hashed text: once as the prefix and once inside the canonical JSON as the member prevHash.
• + is string concatenation with nothing in between.
• For entry 1, prevHash is the genesis value 0000000000000000000000000000000000000000000000000000000000000000.

3.2 Canonical JSON (stable in lib/engine.ts)

The purpose of sorting is that the hash does not depend on the order in which a database returns the members (FR-INT-05). The entry as stored may have its members in any order.

3.3 Worked example

Entry 2 of the fleet demo data, as stored:

{"seq":2,"at":"2026-02-03T07:11:53.793Z","actor":"greta","actorName":"Greta Novak","actorRoles":["regional-lead"],"action":"create","recordId":"RG-0001","recordType":"region","v":1,"before":null,"after":{"name":"North","code":"NO"},"command":{"kind":"create","type":"region","data":{"name":"North","code":"NO"}},"prevHash":"006570ac9d454018effe7aec7ad3fef179154d9d66b6fbfb922e6460eddcbdc6","hash":"a8a7651120e3e7126fb7b8d203e9a35b8e0feff2513357977ed824190587509e"}

The text that is hashed (one line, no line break at the end):

006570ac9d454018effe7aec7ad3fef179154d9d66b6fbfb922e6460eddcbdc6{"action":"create","actor":"greta","actorName":"Greta Novak","actorRoles":["regional-lead"],"after":{"code":"NO","name":"North"},"at":"2026-02-03T07:11:53.793Z","before":null,"command":{"data":{"code":"NO","name":"North"},"kind":"create","type":"region"},"prevHash":"006570ac9d454018effe7aec7ad3fef179154d9d66b6fbfb922e6460eddcbdc6","recordId":"RG-0001","recordType":"region","seq":2,"v":1}

Its SHA-256 is a8a7651120e3e7126fb7b8d203e9a35b8e0feff2513357977ed824190587509e, the entry's hash. You can check this with any SHA-256 tool, for example by saving the text without a trailing newline and running sha256sum.

3.4 Related fingerprint

The configuration's SHA-256 shown by countersign status, countersign config validate and /api/health is SHA-256(UTF-8(canonical(configuration document))) (configHash), with the same canonical form and no prefix.

3.5 Implementation note

The application computes SHA-256 with its own synchronous implementation in lib/sha256.ts, so that the same code runs in the browser and on the server, not with the platform's cryptographic library. The test [FR-INT-01] in lib/engine.test.ts checks that implementation against published SHA-256 known answers and against node:crypto. The standalone script in section 6.2 also uses node:crypto and so checks every hash of a real trail independently.

4. What the software checks

4.1 When an entry is written

4.2 When entries are read: replay (replay)

Every server process replays every entry it reads from the store, and countersign verify replays the whole trail from entry 1 on an empty state. For each entry, in order:

1. The entry must be an object with a command; otherwise "the entry is not readable".
2. The stored command is run again through the engine as the stored actor (actor, actorName, actorRoles), at the stored time at, with the stored auth, on the state built from all earlier entries. If the engine refuses it, the entry "breaks a rule" (for example an approval by the author, an action by someone without the permission, a time before the previous entry).
3. The entry the engine produces is hashed and compared with the stored hash, and the stored entry's own contents are hashed and compared with its stored hash. A difference is reported as one of: "its contents were changed after it was written (the hash no longer matches)", "the chain is broken: it doesn't point at the entry before it", or "re-running its command gives a different result".

Because the engine computes seq, prevHash, recordId, v, before and after itself during replay, a stored entry cannot claim a result that its command does not produce. This is what catches a forged entry whose hash was recomputed correctly (FR-INT-03): changing the approver's name in an approval and rehashing it yields a consistent chain link, but replay shows the result differs or breaks four eyes.

verifyChain is the lighter check without replay: each row is a readable entry (otherwise "the entry is not readable", with its position), each prevHash equals the previous hash, and each entry's contents hash to its hash. countersign verify runs both and reports them on separate lines.

4.3 While a server runs (Service.sync)

Before every read and write the server asks the store for its head (number and hash of the newest entry):

On a fault the server keeps serving the state before the faulty entry for reading, refuses every write with HTTP 503, and /api/health answers 503 with status: "integrity-fault" and the entry number and message. The fault stays until the process is restarted against a store that verifies.

5. How the store enforces append-only, and the limits

What is detected, by what, and when:

In short: the trail is tamper-evident for anyone who verifies, not tamper-proof against a privileged administrator; and evidence of truncation or wholesale replacement requires a reference kept outside that administrator's reach.

6. Independent verification

6.1 With the command-line tool

countersign verify

reads every entry directly from the store (not from a running server), and prints:

entries read    <n>
hash chain      intact
replay          all <n> entries reproduce
head hash       <64 hex>

or hash chain BROKEN at #<n>: <message> and replay FAILED at #<n>: <message>, with exit code 1. Two options compare with an anchor (section 7), each exiting with 1 on a mismatch:

• --expect-entry <n>:<hash> checks that entry n still has that hash, however much the trail has grown since. It adds the line anchor #<n> matches, or anchor #<n> DOES NOT MATCH (entry #<n> has <hash>), or … (entry #<n> does not exist) when the trail is shorter than the anchor.
• --expect-head <hash> compares with the newest entry only: expected head matches or expected head DOES NOT MATCH <hash>. Use it when the trail must not have grown, for example on a backup restored into a scratch database.

countersign status prints the number of entries, the head hash, the configuration's SHA-256 and integrity ok or integrity FAULT at #<n>: <message>.

Run verify on a host and under an account that the database administrators do not control, against a read-only database account if possible.

6.2 Standalone script

The script below uses no Countersign code. It needs Node.js (any current version) and an export made with countersign export --what audit --format jsonl --out audit.jsonl, or a dump of the entry column ordered by seq, one entry per line. It checks numbering, chain, content hashes and time order, and optionally that a given entry has an anchored hash. It does not re-run the rules; that is what countersign verify adds.

// verify-chain.mjs: node verify-chain.mjs audit.jsonl [<anchored seq> <anchored hash>]
import { createHash } from "node:crypto";
import fs from "node:fs";

// Canonical JSON: object keys sorted, no whitespace, undefined members left out.
const canonical = (v) => {
  if (v === null || typeof v !== "object") return JSON.stringify(v) ?? "null";
  if (Array.isArray(v)) return `[${v.map(canonical).join(",")}]`;
  return `{${Object.keys(v).filter((k) => v[k] !== undefined).sort()
    .map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`).join(",")}}`;
};

const [file, anchorSeq, anchorHash] = process.argv.slice(2);
const fail = (msg) => { console.error(`FAILED: ${msg}`); process.exit(1); };
let prev = "0".repeat(64); // the genesis value
let n = 0;
let lastAt = "";
let anchorSeen = false;
for (const line of fs.readFileSync(file, "utf8").split("\n")) {
  if (!line.trim()) continue;
  const entry = JSON.parse(line);
  n++;
  const { hash, ...rest } = entry;
  const expected = createHash("sha256").update(entry.prevHash + canonical(rest), "utf8").digest("hex");
  if (entry.seq !== n) fail(`entry ${n} carries the number ${entry.seq}`);
  if (entry.prevHash !== prev) fail(`entry ${n} does not point at the entry before it`);
  if (hash !== expected) fail(`entry ${n}: its contents do not match its hash`);
  if (Date.parse(entry.at) < Date.parse(lastAt)) fail(`entry ${n} is dated before entry ${n - 1}`);
  if (anchorSeq && n === Number(anchorSeq)) {
    if (hash !== anchorHash) fail(`entry ${n} is not the anchored one: ${hash}`);
    anchorSeen = true;
  }
  prev = hash;
  lastAt = entry.at;
}
if (anchorSeq && !anchorSeen) fail(`the trail has only ${n} entries; the anchored entry ${anchorSeq} is missing`);
console.log(`${n} entries, chain intact${anchorSeq ? `, anchor #${anchorSeq} confirmed` : ""}, head ${prev}`);

Expected output on an intact trail: <n> entries, chain intact, head <hash>, with the same number and hash as countersign status.

6.3 Re-implementing it in another language

The algorithm, for an auditor who wants no dependence on JavaScript:

1. Read the entries in order of seq. Set prev to 64 zeros and n to 0.
2. For each entry: increase n; require entry.seq = n and entry.prevHash = prev.
3. Remove the member hash from a copy of the entry. Serialise the copy as canonical JSON (section 3.2).
4. Compute SHA-256 over the UTF-8 bytes of entry.prevHash followed by that text. Require the lowercase hexadecimal digest to equal entry.hash.
5. Set prev to entry.hash. After the last entry, prev is the head hash.

Two points need care outside JavaScript. Numbers must be written as JavaScript writes them (a float such as 1e-7 is 1e-7, not 1e-07); integers and ordinary decimals are unproblematic. Strings must not be escaped beyond what section 3.2 lists (in Python: json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False), which reproduces the hashes of the demo data).

6.4 SQL checks on PostgreSQL

These complement, and do not replace, the checks above. Run them with a read-only account.

The plain columns exist for indexes and ad-hoc queries and are not covered by the hash chain. The view countersign_audit_trail does not use them (it reads the hashed entry, and adds signature_meaning and inserted_at), so reports should be built on the view. Plain columns equal the hashed entry (expected: no row):

SELECT seq FROM countersign_entries
WHERE (entry::jsonb ->> 'seq')::bigint <> seq
   OR (entry::jsonb ->> 'at')::timestamptz <> at
   OR entry::jsonb ->> 'actor' <> actor
   OR entry::jsonb ->> 'action' <> action
   OR entry::jsonb ->> 'recordId' <> record_id
   OR entry::jsonb ->> 'recordType' <> record_type
   OR entry::jsonb ->> 'prevHash' <> prev_hash::text
   OR entry::jsonb ->> 'hash' <> hash::text;

Numbering without gaps (expected: true):

SELECT count(*) = max(seq) AND min(seq) = 1 FROM countersign_entries;

Application time against the database's own clock (expected: no row beyond your tolerance; entries written by an import of historical demo data are an exception):

SELECT seq, at, inserted_at, inserted_at - at AS difference
FROM countersign_entries
WHERE abs(extract(epoch FROM inserted_at - at)) > 5
ORDER BY seq;

Triggers present and enabled: see the IQ protocol, step 6.2.

7. Head-hash anchoring

Purpose: to make truncation, rollback to an old backup and wholesale replacement of the trail evident. The head hash depends on every entry before it, so a head hash recorded where the database administrators cannot change it pins the whole history up to that entry.

7.1 Taking an anchor

1. Run countersign status (or read /api/health). Note entries (the number N of the newest entry) and head hash (H). Confirm integrity ok.
2. Record the date and time, N, H, the configuration SHA-256 and who took the anchor.
3. Store the record in at least one place that people with write access to the database cannot alter. Examples: a signed entry in a paper logbook; a ticket or document in the quality system; an e-mail to a quality mailbox; a write-once storage bucket; a qualified time-stamp over the record.

Interval: by risk; daily or weekly for an active system, and always before and after a backup restore, a migration, a software upgrade and a configuration change. An anchor is only as good as the independence of where it is kept.

7.2 Verifying against an anchor

• Run countersign verify --expect-entry N:H. Expected: hash chain intact, replay all <n> entries reproduce and anchor #N matches, exit code 0. This proves that entry N still has hash H, that everything before and after it is one unbroken chain, and that every command still passes the rules. It works whether or not the trail has grown.
• Independent method, without Countersign code: export the trail (countersign export --what audit --format jsonl --out audit.jsonl) and run node verify-chain.mjs audit.jsonl N H. Expected: chain intact, anchor #N confirmed. Use it at least at each audit trail review, on a host the database administrators do not control.
• A mismatch or a missing entry N means entries up to N were changed or removed after the anchor was taken: treat as an integrity incident (SOP templates, SOP 6).

7.3 Anchor register (template)

8. ALCOA+ mapping

9. Audit trail review checklist

Use with the review procedure (SOP templates, SOP 2). Period reviewed: ________ to ________. Entries ________ to ________. Reviewer: ________________.

9.1 Integrity of the trail

9.2 Content of the trail

9.3 Outcome