Feature: Threshold Key Recovery (Shamir) for Master Key

Summary Add optional disaster-recovery via K-of-N secret sharing to reconstruct the repository master key if the passphrase is lost. Generates offline shares (files and/or QR PNGs), supports rotation, and reconstruction on a clean node. No network use; all local.

Why

• Removes single point of failure for encrypted backups.
• Fits decentralized model: distribute shares to trusted parties/devices.
• Industry-standard approach (Shamir) with simple UX via CLI.

Scope / Design sketch

• Introduce a random 32-byte Recovery Seed (RS) that derives a recovery KEK via HKDF.

• Master key envelope: MK_enc = AEAD_Encrypt(KEK(passphrase) ⊕ KEK(RS), MK).

• Split RS into N shares with Shamir (e.g., github.com/hashicorp/vault/shamir).

• Store MK_enc alongside existing metadata (bbolt).

• Shares are exported as:

  • ASCII share files (.svshare)
  • Optional QR code images (.png) for paper wallets

• Reconstruction: provide any K shares → rebuild RS → derive KEK(RS) → unwrap MK (passphrase path optional: if passphrase known, use; if not, allow recovery mode using only RS with admin flag).

CLI

# Generate shares
./bin/backup-agent key split --shares 5 --threshold 3 -o ./recovery --qr

# List envelope status
./bin/backup-agent key status

# Reconstruct (from files or interactive QR scan path)
./bin/backup-agent key combine ./recovery/*.svshare

# Rotate (re-wrap MK with new RS + shares)
./bin/backup-agent key rotate --shares 5 --threshold 3

Acceptance criteria

• Creating shares produces N artifacts and updates MK_enc without re-encrypting chunks.
• Any K shares successfully restore the repository: list snapshots, decrypt, and restore.
• < K shares fail with clear, non-leaky error.
• Shares never touch the network; memory holding RS/shares is zeroized.
• Unit tests: SSS round-trip, envelope open/close, QR encode/decode.
• Docs: bold warnings, printed checklist for cold storage.

Security notes

• Use crypto/rand; AEAD = AES-256-GCM already in project.
• Zeroize buffers (memguard optional) and disable shell history prompts unless --yes.
• Gate “passphrase-less recovery” behind --allow-recovery-without-pass + interactive confirm.

Out of scope (v1)

• Remote share escrow, MPC, or auto-distribution.
• UI/daemon RPC; CLI only.

Risks / mitigations

• Share leakage → keep K high; encourage QR + paper storage.
• Envelope drift → store versioned envelope header for future migrations.

Docs & DX

• Add docs/recovery.md with flow diagrams and threat model.
• Print a one-page “Recovery Card” when generating shares.