feat(v2): complete v2 reimplementation

2026-07-31 13:33:39 +02:00
parent 396219e776
commit bd107d6a30
137 changed files with 20737 additions and 155 deletions
@@ -0,0 +1,70 @@
+# Recovery bundle export and validation
+
+M11 recovery exports an offline, passphrase-encrypted catalog and key bundle.
+Import is a local CLI operation that reconstructs only the metadata required to
+restore existing encrypted backups; it does not reactivate backup scheduling.
+
+## Export
+
+Choose an absolute path in a trusted, non-symlinked directory. The destination
+must not already exist; export creates it with mode `0600` and never overwrites
+it.
+
+```sh
+read -r -s recovery_passphrase
+printf '\n'
+printf '%s\n' "$recovery_passphrase" | \
+  backup-tool admin recovery export \
+  --output /secure/offline/backup-tool-recovery.btrec \
+  --passphrase-fd 0
+unset recovery_passphrase
+```
+
+The passphrase is read from the inherited file descriptor. It is never a CLI
+argument. Store the resulting `BTREC` file away from the host and away from the
+live repository-key directories.
+
+## Validate
+
+Validation authenticates and decrypts the bundle, checks the versioned Argon2id
+and AES-GCM format, and verifies the included catalog/key relationships. It
+prints only a status and repository count.
+
+```sh
+read -r -s recovery_passphrase
+printf '\n'
+printf '%s\n' "$recovery_passphrase" | \
+  backup-tool admin recovery validate \
+  --input /secure/offline/backup-tool-recovery.btrec \
+  --passphrase-fd 0
+unset recovery_passphrase
+```
+
+Wrong passphrases, tampering, malformed headers, unsupported KDF parameters,
+and invalid encrypted payloads intentionally produce the same validation error.
+Do not use a failed validation result to diagnose which of those conditions
+occurred.
+
+## Fresh-host import
+
+Before importing, run migrations on the replacement host and configure its
+repository allowlist to include the surviving repository directory. The
+repository must pass normal metadata/path inspection. The replacement metadata
+database must be current and otherwise empty; import rejects a non-empty
+destination and any existing/conflicting key files.
+
+```sh
+backup-tool migrate upgrade
+read -r -s recovery_passphrase
+printf '\n'
+printf '%s\n' "$recovery_passphrase" | \
+  backup-tool admin recovery import \
+  --input /secure/offline/backup-tool-recovery.btrec \
+  --passphrase-fd 0
+unset recovery_passphrase
+```
+
+Import installs signing and data keys with restrictive modes, restores the
+repository/source/job/execution/backup catalog needed for restore, and marks
+sources unavailable plus jobs archived and disabled. Reconfigure sources and
+explicitly create or enable new jobs before taking another backup.