Audit chain overview

What the audit chain records

Walwarden appends an audit event for every state transition in every job. Events are append-only — no event is modified after it is written. Each event includes:

• kind — the event type, for example backup.completed or restore.downloading
• seq — a monotonically increasing sequence number within the job
• at — ISO 8601 timestamp with sub-second precision
• job_id — the ID of the backup or restore job that produced the event
• payload — event-specific metadata (manifest hash, byte count, error classification, etc.)

Backup events (in order)

Kind	Meaning
backup.queued	Scheduler enqueued the job
backup.claimed	Worker claimed the job
backup.running	pg_dump subprocess started
backup.finalizing	Dump uploaded; manifest written; verification running
backup.completed	Manifest verified; artifact sealed
backup.failed	Job failed; payload includes error classification

Restore events (in order)

Kind	Meaning
restore.token_issued	Dashboard issued a restore token
restore.triggered	CLI called triggerRestore; restore_job row created
restore.claimed	CLI claimed the restore job
restore.downloading	CLI started downloading the dump from S3
restore.verifying	Dump fully downloaded; checksum verification running
restore.manifest_verified	Checksum matched; manifest confirmed
restore.restoring	pg_restore subprocess started
restore.finalizing	pg_restore completed; cleanup in progress
restore.completed	Restore job sealed
restore.failed	Job failed; payload includes retryable flag and error classification
restore.timed_out	Server watchdog detected an inactive job and sealed it
restore.token_rejected	A token was presented but rejected; payload includes reason

Dashboard view

The audit chain is surfaced in two places:

• Job timeline — on the backup or restore job detail page, every event in the chain is shown with its timestamp and payload.
• Evidence bundle — downloadable from the database detail page. Includes the signed manifest and every audit event for a given backup artifact, in a format the @walwarden/verifier package can verify offline.

Offline verification

You can verify a backup artifact offline without trusting the walwarden dashboard:

# Download walwarden's public Ed25519 verification key
curl -O https://walwarden.com/.well-known/walwarden-pubkey.pem

# Download the evidence bundle from the dashboard
# Then verify:
npx @walwarden/verifier \
  --bundle evidence-bundle.tgz \
  --pubkey walwarden-pubkey.pem

A successful verification prints:

OK: N manifests verified, M audit events chain-intact  (exit 0)

The verifier confirms:

• The Ed25519 signature over the manifest is valid against walwarden's published public key
• The audit event sequence numbers are contiguous with no gaps
• The manifest hash in the audit events matches the artifact on disk

The verifier is a zero-runtime-dependency npm package. It does not contact walwarden's servers. An auditor can run it on an air-gapped machine given only the evidence bundle and the public key.