Audit checkpoints and receipts

​

Overview

• An inclusion proof shows one row is a leaf of the tree the checkpoint committed to.
• A consistency proof shows a newer checkpoint extends an older one, with no earlier row changed.
• A receipt bundles a decision, an inclusion proof and the checkpoint into one JSON object.

​

Sign a checkpoint

import {
  createCheckpoint,
  generateCheckpointKeyPair,
  createMemoryCheckpointStore,
} from "@glinr/theauth";

const keys = await generateCheckpointKeyPair("audit-2026-10");
// Keep keys.privateKeyJwk in your secret store. Publish keys.publicKey.

const store = createMemoryCheckpointStore();
const result = await createCheckpoint(db, { signer: keys.signer, store });
if (!result.success) throw new Error(result.error.message);
const checkpoint = result.data; // { size, rootHash, timestamp, keyId, signature, ... }

​

Mint and verify a receipt

import { createReceipt, verifyReceipt } from "@glinr/theauth";

const made = await createReceipt(db, rowId, checkpoint, {
  reveal: ["action", "resource", "result", "timestamp"],
});
if (!made.success) throw new Error(made.error.message);
const json = JSON.stringify(made.data); // send this

// Counterparty, no database:
const verdict = await verifyReceipt(JSON.parse(json), publicKey);
// { valid: true } or { valid: false, reason: "bad_signature" | "leaf_mismatch" | ... }

const proof = await createConsistencyProof(db, older, newer);
if (proof.success) {
  const ok = await verifyConsistencyProof(proof.data, older, newer, publicKey);
}

​

What a receipt proves

• The operator signed a log head with that key at that time.
• A row with the revealed values was a leaf of that log, bound to the row’s chain hash.
• If you hold two checkpoints and a consistency proof, the newer log kept every row of the older one unchanged and in place.

​

What it does not prove

• That the log is complete. A row that was never written, or was left out of a checkpoint, is invisible. Checkpoints cover rows that exist at signing time.
• That the operator showed everyone the same log. A signer could sign two different heads for two parties. Catching that needs the checkpoint published somewhere many parties read, and someone comparing what they saw.
• That a hidden field is what the operator says. A hidden field is only a commitment. Reveal it with its salt to prove it.
• That the decision was right. It proves the record, not the judgment behind it.
• Time precision. The checkpoint timestamp is the signer’s clock. It is not an independent time stamp.
• Who a pseudonym is. Version 2 rows commit to keyed pseudonyms of user, agent and approver ids, not raw ids. Revealing idPseudonyms shows the pseudonyms. Someone holding the audit key can confirm an id matches one; a counterparty without it cannot.

​

Redaction and its limits

• Hidden fields stay hidden as long as the audit key stays secret. Anyone with the key can recompute salts and test guesses.
• Revealing a field reveals exactly that value. There is no partial reveal inside parameters; reveal it whole or not at all.
• The set of field names, the row id, the row’s chain hash and its position in the log are visible in every receipt.

​

Keep checkpoints where a counterparty trusts them

​

Key rotation

​

Operating notes

• Log order. Leaves are ordered by row timestamp (whole seconds), then row id, across all agents. Rows written later with an earlier or equal timestamp can sort before rows an older checkpoint already covered; then proofs against that checkpoint fail with LOG_MISMATCH, an alarm and not a missed tamper. Use until to checkpoint only rows old enough to be settled.
• Unchained rows (written before tamperEvident was on) are not in the tree.
• Cleanup and key changes. Deleting old rows with retention cleanup changes the tree, so older checkpoints can no longer be proved against the live database; keep the receipts you issued. Changing audit.hmacKey changes every salt, which changes the tree the same way.
• Cost. Building a checkpoint or proof reads and hashes every row in range. Run it on a schedule, not per request. Leaf hashes are cached in process per database and reused for rows whose content has not changed (a row is re-hashed whenever any covered field differs), so repeated proofs and receipts cost a read of the range, not a full re-hash. createCheckpoint returns INVALID_RANGE for a since or until that is not a valid date.
• Storage. CheckpointStore is an interface with an in-memory implementation. There is no database-backed store yet.

​

Related

• Tutorial: give a counterparty a receipt they can verify offline
• Tamper evident audit trail: the hash chain that checkpoints sign.
• Agent accountability
• Find and remove unused permissions