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.

The source database DSN is different from the CLI-local restore target DSN: walwarden's backup worker needs the source credential to run pg_dump, so the dashboard transmits it to the control plane when you submit the protected- database form. Before submission, the dashboard keeps the value only in the page's in-memory form state. It is never autosaved to localStorage or sessionStorage, and legacy browser draft entries are removed when the form loads and when you sign out.

This browser-storage guarantee does not make a claim about server-side encryption. Server-side credential storage is a separate control and must be evaluated against the deployment's configured secret-storage implementation.

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 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 leak of the AWS destination role or restore-token signing path does not expose target database credentials. For AWS BYO S3, the external-ID-protected destination role is backup-and-restore capable: while walwarden holds valid assumed-role credentials, it can read walwarden backup artifacts in the configured bucket scope to issue restore downloads. The restore token still controls customer-initiated CLI restores, and the role must stay scoped to the dedicated backup bucket with Object Lock, TLS-only access, public-access block, and the external-ID trust policy enabled.
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.