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 #

  1. Cryptographic Integrity: Backups produce manifests signed with SHA-256 and HMAC verification (ErrRecoveryArchiveCorrupt on tampering) plus schema version checks (ErrRecoverySchemaMismatch).
  2. Sandbox Target Protection: Restore targets must be empty directories (ErrRecoveryTargetNotEmpty) and can never overlap live data roots such as /var/mail, /data/live, or CELL_DATA_ROOT (ErrRecoveryTargetLive).
  3. Serialized Execution: Only one recovery job runs at a time (ErrRecoveryBusy); track progress via GET /v1/platform/ops/recovery/jobs/:id.

Standard Backup & Verification Workflow #

  1. Open Recovery Wizard in https://admin.<your-domain> (requires super_admin or storage_admin + Step-Up).
  2. Run Backup (POST /v1/platform/ops/recovery/backup) to export database state and blob metadata to your archive path.
  3. Run Verify Archive (POST /v1/platform/ops/recovery/verify) before storing offsite to validate checksums and HMAC signatures.
  4. 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:

  1. Consume Single-Use Recovery Code: Call POST /v1/platform/auth/recovery/consume with login, password, and one of the 10 offline recovery codes (xxxx-xxxx-xxxx-xxxx).
  2. 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).
  3. Restricted Session Isolation: While in re_enroll_required state, all normal /v1/platform/* endpoints return 403 Forbidden. Only /v1/platform/auth/recovery/re-enroll/* endpoints are allowed.
  4. Re-Enroll Passkey: Complete WebAuthn registration on the recovery screen to restore full AAL2 access, then regenerate a fresh set of 10 recovery codes.