Building an Audit-Grade Hash-Chain Ledger: Architecture & Trade-offs

The Problem with Mutable Ledgers

Paper drug logs can be altered with white-out. Most EMR controlled substance modules store records as mutable database rows — a database administrator with the right credentials can issue an UPDATE or DELETE query and leave no trace. Under DEA scrutiny, "the system allowed me to edit it" is not a legal defense.

DEA inspectors increasingly ask for exportable, verifiable audit trails rather than printed screenshots. A printout from a mutable system proves only that the current state was logged at some point — it says nothing about whether the record was modified after the fact.

What Is a Hash Chain?

A hash chain makes each record cryptographically dependent on every record that preceded it. The hash of event n is computed over the previous hash plus the event data:

hash(n) = SHA-256(
  prev_hash
  + event_type    // DRAW | WASTE | REVERSAL | BLIND_COUNT | ADJUSTMENT
  + vial_id
  + quantity
  + user_id
  + iso_timestamp
)

The chain anchors at a genesis block with a known constant hash. Every subsequent event is locked to the chain by including the prior hash in its own hash computation.

Fig. 1 — Each event includes the previous event's hash. Modifying any event breaks all subsequent links.

The critical property: if you modify Event #1 (changing its quantity, timestamp, or user ID), its hash changes. Event #2 references the original hash of Event #1 in its own hash. The chain verifier replays every event and reports the first broken link — making silent tampering detectable.

Append-Only Enforcement

VetRx Ledger's production-ready architecture uses an append-only event store. The demo tier uses a JSONL flat file (/tmp/vetrx-events.jsonl) to which events are only ever appended — never updated or deleted.

Every correction is a new event. If a tech records 0.5 mL but the correct amount was 0.3 mL, the correction workflow creates a REVERSAL event (adding 0.5 mL back to the balance) followed by a corrected DRAW event (subtracting 0.3 mL). The original erroneous entry remains in the chain — fully visible in the audit log — because DEA regulations require that corrections be traceable.

Hardware-Backed E-Signatures with WebAuthn

21 CFR Part 11 sets the baseline for electronic signature requirements in regulated industries. For controlled substance C-II events (the highest regulatory burden), VetRx Ledger uses WebAuthn (FIDO2) — the W3C standard for hardware-backed authentication.

When a DVM or credentialed tech initiates a DRAW or WASTE event, the WebAuthn signing operation executes inside the device's secure enclave — the dedicated security chip that holds private keys in hardware (Touch ID on Apple devices, Face ID on newer iPhones and iPads, YubiKey on desktop). The private key never leaves the secure enclave; only the signature is transmitted.

The signature is stored alongside the event hash in the chain record. This means each high-risk event carries a cryptographic attestation that a specific registered user authorized the action at a specific moment — and the attestation cannot be forged without physical access to the hardware token.

The Dual-Witness Token

WASTE events require a second authorized person. VetRx Ledger implements this with a one-time witness token — a UUID combined with an HMAC-SHA256 signature, valid for 10 minutes and usable exactly once.

The flow:

1. Primary tech submits the WASTE event — the server generates a witness session with the token
2. The token is displayed as a QR code and a 6-character alphanumeric code on the primary device
3. A second tech on their own device enters or scans the token
4. The server checks: token exists, not expired, not consumed, witness ≠ primary
5. The server marks the token consumed (one-time use enforced atomically)
6. Witness authenticates with their own biometric credential
7. Both identities are sealed into the event hash; the event is committed to the chain

Single-use enforcement prevents replay attacks: a malicious actor cannot reuse an expired or previously consumed token. The 10-minute window forces physical co-presence — retroactive witnessing is architecturally impossible.

Chain Verification

The GET /api/ledger/verify endpoint replays every event in the chain, recomputes each hash from scratch, and reports the result. This runs in O(n) time over the event log and produces a verifiable report:

// Chain verification — simplified TypeScript
const GENESIS_HASH = "0000000000000000000000000000000000000000";

let prevHash = GENESIS_HASH;
for (const event of events) {
  const payload = [
    prevHash,
    event.type,
    event.vialId,
    String(event.qty),
    event.userId,
    event.timestamp,
  ].join("|");

  const computed = sha256hex(payload);

  if (computed !== event.hash) {
    return {
      valid: false,
      brokenAt: event.id,
      checkedCount: idx + 1,
    };
  }
  prevHash = event.hash;
}

return { valid: true, checkedCount: events.length };

The verification report includes: total events checked, first broken link (if any), chain valid boolean, and the latest chain hash (a fingerprint of the entire log at that moment in time). You can view the live verification result at /ledger/verify.

Export and Chain-of-Custody

The GET /api/ledger/export endpoint produces a self-contained JSON package that includes every event with its hash, prev_hash, witness_token (if applicable), and webauthn_signature. This package is self-verifying: anyone who has the VetRx Ledger verification algorithm can confirm chain integrity offline without connecting to the app.

The export also includes a chain summary — the number of events, the final hash, and achain_valid: true/false flag computed at export time. This makes the export suitable for submission to a DEA investigator or compliance auditor.

Trade-offs and Honest Limitations

An honest engineering assessment of what this architecture does and does not provide:

• Not a blockchain. There is no distributed consensus. A full server compromise before a backup snapshot could theoretically allow an attacker to rewrite history — the hash chain would need to be recomputed from the tampered data. The value is deterrence and auditability, not absolute mathematical tamper-proof guarantee.
• Defense in depth. The hash chain should be treated as one layer of a broader security posture: alongside role-based access control, audit log monitoring, daily off-device export snapshots, and physical security.
• Production hardening. In production, each nightly snapshot is exported to immutable cloud storage (S3 Object Lock) signed with a KMS key. This means even a compromised server cannot retroactively alter the archived history.
• Scale considerations.JSONL is ideal for demo and small-practice volumes. High-volume practices (>500 events/day) should use PostgreSQL with append-only row-level security policies and periodic checkpoint snapshots.