vm-skills/backup-sovereign/references/recovery_notes.md

Recovery Notes

Overview

This document describes recovery procedures for backup-sovereign backups.

Prerequisites

• age installed (for decryption)
• Access to AGE_IDENTITY_FILE (private key)
• Sufficient disk space for extraction

Standard Recovery

1. Locate Backup

Find your encrypted backup:

ls ~/.claude/skills/backup-sovereign/outputs/runs/

2. Decrypt Archive

# Set identity file
export AGE_IDENTITY_FILE="$HOME/.config/age/identity.txt"

# Decrypt
age -d -i "$AGE_IDENTITY_FILE" \
    -o archive.tar.gz \
    archive.tar.gz.age

3. Extract

# Extract to current directory
tar -xzf archive.tar.gz

# Or extract to specific location
tar -xzf archive.tar.gz -C /path/to/restore/

4. Verify Integrity

Compare BLAKE3 hash with manifest:

# Compute hash of archive
b3sum archive.tar.gz

# Compare with value in manifest.json
cat manifest.json | grep blake3

Disaster Recovery

If you've lost access to your primary system:

1. Obtain encrypted backup from off-site storage
2. Obtain identity file from secure backup location
3. Follow standard recovery steps above

Verify ROOT

To verify the backup hasn't been tampered with:

# Compute manifest hash
MANIFEST_B3=$(b3sum manifest.json | awk '{print $1}')

# Compute encrypted archive hash
ENC_B3=$(b3sum archive.tar.gz.age | awk '{print $1}')

# Compute ROOT
echo -n "${MANIFEST_B3}${ENC_B3}" | b3sum

# Compare with ROOT.txt
cat ROOT.txt

Key Management

age Keys

• Identity file (private key): Keep secure, backed up separately
• Recipients file (public key): Can be shared, used for encryption

Generate New Keys

If you need new keys:

# Generate identity
age-keygen -o ~/.config/age/identity.txt

# Extract public key
age-keygen -y ~/.config/age/identity.txt > ~/.config/age/recipients.txt

Key Rotation

1. Generate new keypair
2. Add new public key to recipients file
3. Keep old identity file for decrypting old backups
4. New backups will be encrypted to all recipients

Troubleshooting

"age: error: no identity matched any of the recipients"

• Wrong identity file
• Backup was encrypted with different key
• Solution: Use correct identity file

"tar: Error opening archive"

• Corrupted archive
• Incomplete download
• Solution: Verify BLAKE3 hash, re-download if needed

"b3sum: command not found"

• Install b3sum: cargo install b3sum or use package manager
• Alternative: Use blake3 CLI if available

Security Considerations

1. Never store identity file with encrypted backups
2. Use passphrase-protected identity for extra security
3. Test restore drill regularly - backups that haven't been tested aren't backups
4. Store backups off-site - same location defeats the purpose

References

• age encryption
• BLAKE3 hash