Trust boundary

What walwarden holds, what walwarden never holds, and how the architecture enforces it.

The invariant

The restore trust boundary is the load-bearing architectural invariant of the product. It is enforced by the system design, not by policy.

What walwarden holds:

Backup job state and scheduling configuration (stored in walwarden's Postgres metadata database)
Ed25519-signed backup manifests (checksums, sizes, Postgres version metadata — not the dump bytes)
The audit event chain (state transitions and timestamps — not data content)
Short-lived HMAC-signed restore tokens (signed with a secret held by the walwarden control plane, valid for 1 hour, single-use)
Presigned S3 URLs (valid for a bounded window, scoped to a single artifact)
The walwarden-to-S3 IAM role credentials (used to write backup artifacts and to generate presigned read URLs for restores)

What walwarden never holds:

The customer's target-DB write credentials. The --target DSN passed to the CLI is processed entirely on the customer's machine and is not transmitted to walwarden's servers.
The dump bytes. The backup worker writes bytes from pg_dump directly to the customer's S3 bucket. The restore CLI downloads bytes from the customer's S3 bucket via presigned URL directly to the restore machine. Walwarden's servers are not in the data path.
The customer's raw database rows. Walwarden never reads the data it backs up beyond what pg_dump produces; pg_dump output is treated as opaque bytes.
The customer's AWS root credentials or any credentials beyond the scoped IAM role the customer creates.

How the architecture enforces it

Backup path

pg_dump (on walwarden worker)
  → streams bytes to customer S3 bucket via walwarden's assumed IAM role
  → walwarden worker never holds bytes in memory beyond a streaming buffer
  → manifest written to S3, signed with walwarden's Ed25519 key
  → audit event written to walwarden's metadata DB (hash + size only, not bytes)

The customer's S3 bucket is the primary storage. Walwarden's metadata DB holds the receipt (manifest), not the asset.

Restore path

Customer clicks "Restore from this backup" in dashboard
  → walwarden control plane issues a short-lived HMAC token + presigned S3 URL
  → customer copies one-liner to their machine
  → CLI on customer machine calls triggerRestore (token auth only)
  → CLI downloads dump from S3 via presigned URL (no walwarden proxy)
  → CLI pipes bytes to pg_restore on customer machine
  → CLI posts state transitions to walwarden (state labels only, no data)
  → walwarden writes audit events

The presigned URL gives the CLI direct S3 read access, scoped to the specific artifact and bounded in time. No walwarden proxy is involved.

Token design

Restore tokens are HMAC-signed by the walwarden control plane. The payload contains:

orgId — the team that owns the database
databaseId — the specific protected database
manifestHash — the SHA256 of the artifact being restored
mode — new_database or in_place
jobIntentId — a unique identifier that makes the token single-use
exp — expiration timestamp (1 hour from issuance)

The server verifies the HMAC signature on every API call. A token cannot be forged without the HMAC secret. Once triggerRestore is called, the jobIntentId is marked as used; subsequent calls with the same token are rejected.

What this means for your security posture

A walwarden credential leak does not expose your database contents. The credentials walwarden holds (the IAM role, the HMAC signing key) allow walwarden to write new backups and issue restore tokens, but do not allow reading existing backup bytes without a valid token and a presigned URL in the active window.
A walwarden outage does not affect your existing backups. Your backup artifacts are in your S3 bucket under your IAM account. If walwarden is unavailable, you can restore directly from S3 using pg_restore with your own AWS credentials, bypassing the CLI entirely.
Your target database credentials are not in walwarden's threat model. They never leave your restore machine.

Source

This section is derived from docs/decompositions/2026-05-26-walwarden-cli-restore-design.md (Trust boundaries section). If the architecture changes, update that document and this page together.