Tamper-evident audit log
The audit log of the API (audit_log, T12) is append-only and chained per organization.
The chain
Each event carries seq (contiguous from 1 per organization), prev_hash and
event_hash = SHA-256( prev_hash (32 bytes) || JCS( event without prev_hash and event_hash ) )
(RFC 8785 for the canonical JSON; seq is part of the hashed document, so reordering changes the
hash). The first event chains to 64 zeros. The writer locks the organization's
audit_chain_head row (SELECT … FOR UPDATE) in the same transaction as the change it records:
a rollback removes the event and the head move together; writers of the same organization are
serialized, other organizations do not wait (budget: 100 events/s per organization, p95 of the
write < 100 ms).
Events hold ids, hashes and enumerations only: before_hash/after_hash are SHA-256 of
snapshots, metadata is validated by the contract schemas/governance/audit-event-1.0.json; no
extracted value and no document text can be put in an event.
Checkpoints
A signed checkpoint {tenant_id, seq_from, seq_to, head_hash, prev_checkpoint_hash, ts} (detached
JWS, RFC 7515 App. F) is created when 1 000 events are not covered yet or 10 minutes passed
with events pending (the cron workflow runs every minute). It is stored in audit_checkpoint and
written to the object store under t/{tenant}/audit/checkpoints/ with Object Lock COMPLIANCE
retention when the backend supports it (anchored = true); otherwise it is written normally and
reported anchored = false (GET /v1/audit/verify, the Audit page and extractit audit status).
The trigger and the revoked privileges (REVOKE UPDATE, DELETE, TRUNCATE … FROM dx_app plus a
BEFORE UPDATE OR DELETE trigger) stop mistakes and an application-level attacker. They do not
stop the owner of the database, who can disable the trigger. The guarantee against that attacker is
the chain plus the checkpoints stored outside the database: rewriting history requires
re-signing every later checkpoint.
Verify
- Online:
GET /v1/audit/verify, orextractit audit verify --org <id>. - Offline, from an export and the public keys, without database or network:
$ extractit audit export --org org_01… --out events.ndjson # or GET /v1/audit-events/export
$ curl -s https://api.example/.well-known/dx-audit-jwks.json > keys.json
$ extractit audit verify --export events.ndjson --jwks keys.json
{"anchored": false, "checkpoints_checked": 3, "events_checked": 2650, "first_break_seq": null, "ok": true, "reason": null}
Exit codes: 0 intact, 1 broken, 2 incorrect usage. reason is one of hash_mismatch (an event
was edited: first_break_seq is its seq), continuity_broken (an event is missing: the seq that
should be there), prev_hash_mismatch, checkpoint_signature_invalid, checkpoint_unknown_kid,
checkpoint_chain_broken, checkpoint_mismatch, missing_events_since_checkpoint (events removed
from the end: detected against a checkpoint or against the chain head) and head_mismatch.
The NDJSON export has one record per line: event, checkpoint and a final head. The head
line is not signed: it is how truncation of the tail, after the last checkpoint, is noticed; only a
checkpoint is cryptographic evidence.
Not in scope
OCSF export, SIEM forwarding, RFC 3161 timestamps, Merkle trees and table partitioning are not planned. A tenant that outgrows the per-organization lock moves to batching per transaction or to chains per partition.