railiance-infra/docs/s1-backup-recovery.md

S1 encrypted backup and isolated recovery

This repository can collect only the declared S1 operating-system configuration and Debian package-selection evidence. It does not back up Kubernetes state, databases, Forgejo, application data, user homes, secrets, or private keys. The machine-readable boundary is spec/s1-backup.yaml.

Safe source gate

Run this without root, host access, or an age private key:

make validate-s1-backup

The declaration must agree exactly with the public age recipients in .sops.yaml. Fixture tests prove encrypted atomic publication, failure cleanup, receipt integrity, isolated restore, traversal rejection, freshness, and exact retention approval. This command never installs or starts a timer.

Backup and status

On a host, root can create one bundle:

sudo tools/cmd/railiance-backup-s1
make s1-backup-status

A final s1-backup-YYYYMMDDTHHMMSSZ/ directory appears only after both artifacts are encrypted and the manifest and receipt are durable. The receipt contains hashes, sizes, host identity, source revision, declaration digest, and the retention decision, but no decrypted content or secret material. Status fails for missing, stale, over-budget, over-retained, or tampered newest evidence.

Retention is deliberately not an unattended delete. Render the current exact candidate set, review it, and pass back the one-use approval derived from the candidate receipt hashes:

make s1-backup-prune-plan
make s1-backup-prune APPROVE_S1_BACKUP_PRUNE=PRUNE-S1-BACKUPS-...

If the set changes between those commands, pruning fails closed. Candidates are atomically moved beneath a quarantine directory inside the declared backup root before removal; paths outside that root are never accepted.

Inspection and isolated restore

Inspection verifies receipt, manifest, declaration, encrypted hashes, sizes, and membership without a private key:

make s1-restore-inspect BUNDLE=/opt/backup/railiance/infra/s1-backup-...

An attended operator may then extract into an explicit absent or empty staging directory outside this repository:

make s1-restore-isolated \
  BUNDLE=/opt/backup/railiance/infra/s1-backup-... \
  DEST=/tmp/s1-restore-drill \
  IDENTITY=/operator-controlled/path/identity.age

The command suppresses decryption output, validates every archive member and mode before extraction, rejects escaping links and traversal, and writes a metadata-only restore receipt. It refuses /, /etc, /home, /root, /var, repository paths, and non-empty destinations. There is no live restore mode.

Timer deployment approval interface

The timer runs daily at 02:15 UTC with up to 30 minutes of jitter. Its service can write only the declared backup root under systemd's filesystem controls. Deployment is a host mutation and is separate from bootstrap and verification:

make s1-backup-deploy \
  HOST=Railiance01 \
  APPROVE_S1_BACKUP_DEPLOY=DEPLOY-RAIL-HO-WP-0012-S1-BACKUP-TIMER

The Make target also refuses a dirty source tree. The playbook independently checks the approval and pins the deployed wrapper to the reviewed 40-character source revision. This approval installs and enables the timer only; it does not authorize pruning, off-host upload, private-key access, or a restore.

Off-host transfer remains RAIL-HO-WP-0012-T05 and belongs to the governed railiance-backup-offsite-lane. An attended off-host isolated drill remains RAIL-HO-WP-0012-T06; neither action is implemented or implied here.