The audit chain

What the append-only audit chain records, what the dashboard surfaces, and how to verify an artifact offline with its matching public key.

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 with the matching public key.

Offline verification with the matching public key

The verifier package ships and runs offline without trusting the walwarden dashboard. The production endpoint was observed ready on 2026-07-14, but a real customer Evidence verification additionally requires a bundle signed by the matching private key and a successful verifier run. Check the current key-readiness status on /api/health or the Evidence surface before downloading the matching public key:

Team and historical legacy chains

Team Evidence and historical legacy Evidence are separate proof objects. A Team export contains the active Team chain; a legacy export is labeled as a historical legacy chain and is available only when the authenticated caller has an active Team membership plus the preserved immutable Team-to-legacy lineage. Naming a raw WorkOS organization id does not grant access. Combined archives store each segment in its own file and the verifier checks each segment independently; Team rows are never filtered out of a legacy chain and the segments are never concatenated.

The original v1 audit_events.json format and the partial legacy sidecar remain supported for compatibility. Offline verification with the matching public key reports only the continuity and completeness the selected format declares; it does not infer authorization or promote a partial legacy segment to a complete chain.

# 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 --yes @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.