Hash-chain integrity specification

What the chain proves

Korvos cannot retroactively edit AML evidence even if the application layer were compromised. Every append-only table records each row’s SHA-256 over a payload of business fields plus the previous row’s hash. A single byte changed anywhere in the history breaks the chain at the next export, in a way the auditor can detect without trusting us.

The database itself enforces the contract: UPDATE, DELETE, and TRUNCATE are revoked on every chained table for every role including service. A BEFORE INSERT trigger computes the hash inside Postgres; the application has no ability to forge a row with a falsified hash because the trigger overwrites whatever the application sent. This page documents the algorithm an auditor can use to confirm what we say is true.

Algorithm

For each chained table, every row carries three integrity fields:sequence_no (monotonic per chain), prev_hash (the previous row’s record_hash, or 32 zero bytes at genesis), and record_hash (SHA-256 over prev_hash concatenated with a per-table payload). The export bundle includes the exact payload bytes that were hashed at INSERT time as __chain_payload_hex on each JSONL row, so offline verification has no dependency on the database that produced it.

genesis_prev_hash = bytes(32)   # 32 zero bytes

for each row in chain (ordered by sequence_no ascending):
    payload  = bytes.fromhex(row.__chain_payload_hex)
    expected = sha256( bytes.fromhex(row.prev_hash) || payload )
    assert expected.hex() == row.record_hash

    # The next row's prev_hash must equal this row's record_hash:
    next_prev_hash = row.record_hash

The payload itself is whatever the table’s {table}_chain_payload(row) function returns — a stable JSONB serialisation of the business-meaningful columns, wrapped with a __table and __version marker so payload-format changes re-epoch a chain rather than silently invalidating prior hashes. Schema versions are part of the audit story; the public spec at this URL is updated whenever a payload version bumps.

The verifier script

Every export bundle ships verify.py in the ZIP. The same source is published at this URL so an auditor can compare the in-bundle copy against the publicly- committed canonical copy — if they match, the script that ran against the bundle is the script Korvos publishes.

#!/usr/bin/env python3
"""Korvos AUSTRAC export bundle integrity verifier.

Reproduces the integrity checks documented at:
    https://korvos.com.au/trust/hash-chain

Uses only the Python standard library (>= 3.10). Runs offline.

Usage:
    python3 verify.py path/to/korvos-austrac-export.zip

Exit codes:
    0  every check passed
    1  one or more file SHA-256s drifted from the manifest
    2  one or more rows failed the chain recomputation
    3  bundle is malformed or missing required files
    4  chain head in chain_verifications.json disagrees with the JSONL tail
"""
# Full source: /trust/hash-chain/verify.py

Chained tables

54 append-only tables carry a compute_hash_chain BEFORE INSERT trigger and a corresponding {table}_chain_payload function. The bundle exports every row from every chain within the requested date range. The list below is the canonical set (committed at src/lib/audit/hash-chained-tables.ts); the migration log under supabase/migrations/ is the operational record of which table acquired its trigger in which release.