Skip to content

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, or extractit 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.