From a2db8058e73d9d2dd71917695dc27441005a9173 Mon Sep 17 00:00:00 2001 From: sjat Date: Fri, 5 Jun 2026 09:45:27 +0200 Subject: [PATCH] rotate-secrets: document offline vault break-glass for ubongo --- docs/runbooks/rotate-secrets.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/runbooks/rotate-secrets.md b/docs/runbooks/rotate-secrets.md index 05dfd59..f9a7859 100644 --- a/docs/runbooks/rotate-secrets.md +++ b/docs/runbooks/rotate-secrets.md @@ -30,6 +30,27 @@ clear "run: rbw unlock" error rather than a hang. --- +## Break-glass — vault access during a full cluster outage + +The control node `ubongo` (ADR-015) is the tool used to rebuild the cluster, so it +must be able to decrypt the vault even when Vaultwarden (if hosted on the cluster) +is down. `rbw` keeps a **local encrypted copy** of the Vaultwarden vault and decrypts +it **offline** with your Vaultwarden master password — no live server needed for +entries it has already synced. The recovery design therefore requires: + +- `rbw` on `ubongo` (and on `mamba`, the break-glass laptop) has **synced at least + once** while Vaultwarden was reachable (`rbw sync`). +- Your **Vaultwarden master password** is kept **offline** — in a password manager on + `mamba` and on paper in a safe — independent of any cluster-hosted Vaultwarden. + +There is always exactly one irreducible offline root secret; here it is the +Vaultwarden master password. Keep it recoverable without the cluster. + +> **To verify (ADR-014, security-relevant):** confirm `rbw` actually decrypts its +> local cache fully offline on your pinned `rbw` version before relying on this. + +--- + ## Rotating a single secret value 1. Ensure the agent is unlocked: `rbw unlock`