Backup, Recovery & MFA Recovery Codes #
TsubameMail separates data backup/recovery (/v1/platform/ops/recovery/*) from operator MFA loss recovery (/v1/platform/auth/recovery/*).
Isolated Backup & Restore Rules #
- Cryptographic Integrity: Backups produce manifests signed with SHA-256 and HMAC verification (
ErrRecoveryArchiveCorrupton tampering) plus schema version checks (ErrRecoverySchemaMismatch). - Sandbox Target Protection: Restore targets must be empty directories (
ErrRecoveryTargetNotEmpty) and can never overlap live data roots such as/var/mail,/data/live, orCELL_DATA_ROOT(ErrRecoveryTargetLive). - Serialized Execution: Only one recovery job runs at a time (
ErrRecoveryBusy); track progress viaGET /v1/platform/ops/recovery/jobs/:id.
Standard Backup & Verification Workflow #
- Open Recovery Wizard in
https://admin.<your-domain>(requiressuper_adminorstorage_admin+ Step-Up). - Run Backup (
POST /v1/platform/ops/recovery/backup) to export database state and blob metadata to your archive path. - Run Verify Archive (
POST /v1/platform/ops/recovery/verify) before storing offsite to validate checksums and HMAC signatures. - During disaster drills, run Restore to Sandbox (
POST /v1/platform/ops/recovery/restore) pointing to an empty staging directory (for example,/var/lib/tsubame/restore-staging/<timestamp>), validate readability, and promote only after verification.
Operator MFA Loss Recovery #
If a super_admin or operator loses all enrolled Passkeys:
- Consume Single-Use Recovery Code: Call
POST /v1/platform/auth/recovery/consumewithlogin,password, and one of the 10 offline recovery codes (xxxx-xxxx-xxxx-xxxx). - Automatic Containment: Consuming a recovery code atomically: - Marks that recovery code as used (SHA-256 hash stored server-side; single-use only). - Revokes all existing sessions and Passkeys for the account. - Issues a restricted session (
re_enroll_required). - Restricted Session Isolation: While in
re_enroll_requiredstate, all normal/v1/platform/*endpoints return403 Forbidden. Only/v1/platform/auth/recovery/re-enroll/*endpoints are allowed. - Re-Enroll Passkey: Complete WebAuthn registration on the recovery screen to restore full
AAL2access, then regenerate a fresh set of 10 recovery codes.