# Vaultwarden Restore Test Runbook

## Purpose

Prove that Vaultwarden backups can be restored without modifying or risking the production vault. Follow-up work is tracked in `tickets/active/2026-06-06-vaultwarden-recovery-restore-plan.md`.

## Restore-Test Rules

- Restore tests must use an isolated disposable target unless the user explicitly approves otherwise.
- Do not overwrite production Vaultwarden data during a test.
- Do not expose the restored test vault publicly.
- Do not record master passwords, recovery codes, backup keys, admin tokens, or vault item values in git.
- Destroy or preserve the restore target only according to user approval.

## Restore Test Record

Latest restore test: 2026-06-07.

- Restore-test target type: disposable Proxmox LXC.
- Target: CT 105 `vaultwarden-restore-test`, destroyed after successful test.
- Network isolation method: LAN-only disposable target, no DNS, no public exposure, temporary self-signed HTTPS on test IP.
- Backup artifact tested: `vaultwarden-20260607T022724Z.tar.age`.
- Encryption approach for test: fresh backup temporarily encrypted to both the user's permanent dedicated age recipient and a temporary age recipient generated inside CT 105; production recipient file was restored to the permanent recipient afterward.
- Recovery material owner: user owns permanent dedicated age private key outside Vaultwarden; temporary restore-test key existed only inside disposable CT 105 and was destroyed with the CT.
- Verification: backup decrypted, data restored, Vaultwarden started, HTTPS endpoint responded, user confirmed login, production remained healthy.
- Disposal/preservation plan: destroy disposable target after verification; completed.

## Isolated Target Requirements

The restore target should:

- be disposable or snapshotted
- not use the production DNS name
- not send real email notifications unless explicitly approved
- not expose the restored vault publicly
- have network access restricted enough to avoid client confusion
- be clearly marked as a restore-test instance

## Restore Test Checklist

1. Confirm production Vaultwarden is healthy before the test.
2. Confirm backup artifact exists and is approved for testing.
3. Confirm recovery material is available outside the vault.
4. Create or prepare isolated restore target.
5. Install the same or compatible Vaultwarden deployment method.
6. Restore data/config according to approved procedure.
7. Start restored service on test-only hostname/port.
8. Verify the restored service starts.
9. Verify expected vault metadata/data is present without exposing secret values in logs or repo.
10. Verify production vault remains unchanged.
11. Record test date, artifact reference, result, and issues.
12. Destroy or preserve restore target according to approved plan.
13. Log restore test in `docs/server-change-log.md` without secrets.

## Verification Criteria

A restore test passes when:

- restored service starts successfully
- expected users/items/metadata are present
- login/recovery path works for the authorized user
- production vault remains unchanged
- recovery did not require secrets that exist only inside the production vault
- rollback/disposal is complete or explicitly deferred

2026-06-07 result: passed.

## Failure Handling

If restore fails:

1. Stop the restored test service.
2. Preserve logs/artifacts if useful and safe.
3. Confirm production vault remains healthy.
4. Identify failure class: missing data, wrong version, bad backup, missing recovery material, permissions, TLS/DNS, or deployment mismatch.
5. Create a follow-up ticket before relying on the vault for critical secrets.
6. Do not migrate additional critical secrets until failure is resolved or user accepts the risk.

## Rollback / Cleanup

For disposable restore target:

1. Stop restored Vaultwarden service.
2. Destroy VM/LXC or revert snapshot.
3. Remove temporary DNS/reverse-proxy/firewall entries.
4. Confirm production vault endpoint still resolves normally.
5. Log cleanup.

For preserved restore target:

1. Disable automatic startup unless approved.
2. Restrict network access.
3. Label clearly as restore-test/non-production.
4. Record why it is preserved and when to remove it.