docs(readme): document recovery QR + sync feature list with current code

- Quick start gains backup export and recovery-qr generate examples so
  first-time readers see those features without scrolling.
- New "Recovery: what if I lose my reference image?" section explains the
  recovery QR mitigation, domain-separation rationale (b"relicario-recovery-v1\0"
  prefix prevents wrap-key/master-key collision under passphrase reuse),
  salt+nonce freshness, and recommended offline-storage practice.
- Architecture core file list adds recovery_qr.rs and import_lastpass.rs
  (both pre-existing, both were missing from the README list).
- Roadmap marks Recovery QR as shipped, slotted next to Backup & restore.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
adlee-was-taken
2026-05-09 12:16:09 -04:00
parent 3759f6a5f0
commit 4bf5e1dc37

View File

@@ -89,6 +89,12 @@ relicario list
# Sync with your git remote # Sync with your git remote
relicario sync relicario sync
# Pack the vault into a single encrypted backup file
relicario backup export -o vault.relbak
# Print a recovery QR for your image_secret (see "Recovery" below)
relicario recovery-qr generate
# Generate a random password # Generate a random password
relicario generate -l 32 relicario generate -l 32
``` ```
@@ -108,6 +114,25 @@ The embedding survives:
This means your reference image can live on your Instagram, your personal website, or anywhere else. It's useless without your passphrase. This means your reference image can live on your Instagram, your personal website, or anywhere else. It's useless without your passphrase.
## Recovery: what if I lose my reference image?
Without your reference image, the vault is undecryptable — that's the security model. But it also makes a lost or corrupted image a single point of failure.
The mitigation is the **recovery QR**: a printable QR code that wraps your image secret behind a separate recovery passphrase you choose. If you ever lose access to the reference JPEG, scan or transcribe the QR, provide the recovery passphrase, and recover the 256-bit image secret. Combined with your normal vault passphrase, this restores access to the vault.
```bash
# Print a recovery QR (after the vault is unlocked).
# You'll be prompted for a separate recovery passphrase.
relicario recovery-qr generate
# Recover the image_secret from a stored QR payload.
relicario recovery-qr unwrap
```
The QR payload is an XChaCha20-Poly1305 envelope keyed by Argon2id over a domain-separated input (prefixed with `b"relicario-recovery-v1\0"`), so even if you reuse your vault passphrase as your recovery passphrase, the wrap key cannot collide with a vault master key. Both salt and nonce are freshly randomized per call, so two QRs printed from the same passphrase yield different bytes — the printed copy doesn't leak whether you've printed others.
Recommended practice: print the QR, store it offline (safe, deposit box), and forget about it. The recovery passphrase is what protects the printed copy from being useful to someone who finds it.
## Architecture ## Architecture
``` ```
@@ -122,6 +147,8 @@ relicario/
│ │ ├── settings.rs # VaultSettings (retention, generator defaults, caps) │ │ ├── settings.rs # VaultSettings (retention, generator defaults, caps)
│ │ ├── backup.rs # `.relbak` encrypted-backup envelope │ │ ├── backup.rs # `.relbak` encrypted-backup envelope
│ │ ├── device.rs # ed25519 device keys + revocation entries │ │ ├── device.rs # ed25519 device keys + revocation entries
│ │ ├── recovery_qr.rs # Paper-printable image_secret backup (XChaCha20-Poly1305 + Argon2id)
│ │ ├── import_lastpass.rs # LastPass CSV → typed items
│ │ └── vault.rs # Encrypt/decrypt items, manifest, settings │ │ └── vault.rs # Encrypt/decrypt items, manifest, settings
│ ├── relicario-cli/ # CLI binary: filesystem, git, terminal I/O │ ├── relicario-cli/ # CLI binary: filesystem, git, terminal I/O
│ ├── relicario-wasm/ # Thin wasm-bindgen wrapper for the browser extension │ ├── relicario-wasm/ # Thin wasm-bindgen wrapper for the browser extension
@@ -206,6 +233,7 @@ The binary is at `target/release/relicario`.
- [x] Typed items: Login, SecureNote, Identity, Card, Key, Document, TOTP - [x] Typed items: Login, SecureNote, Identity, Card, Key, Document, TOTP
- [x] Secure document storage (encrypted file attachments) - [x] Secure document storage (encrypted file attachments)
- [x] Backup & restore (`.relbak` encrypted envelope) - [x] Backup & restore (`.relbak` encrypted envelope)
- [x] Recovery QR (paper-printable image_secret backup with separate passphrase)
- [x] LastPass CSV import - [x] LastPass CSV import
- [x] Device authentication (ed25519 commit signing + pre-receive hook) - [x] Device authentication (ed25519 commit signing + pre-receive hook)
- [ ] Import from Bitwarden / 1Password - [ ] Import from Bitwarden / 1Password