docs: refresh per-crate ARCHITECTURE — missing core modules + CLI commands

Punch items from doc audit:
- relicario-core: module map missing 5 public modules (backup,
  device, import_lastpass, recovery_qr, tar_safe); added with
  1-2 sentence descriptions in the existing voice.
- relicario-core: "ed25519-dalek is a dependency placeholder" was
  stale — device.rs now consumes it for signing/verify/keypair.
- relicario-cli: Rate (zxcvbn scoring) and RecoveryQr (generate/unwrap)
  commands were absent from Key flows; added.
- relicario-cli: "Backup-passphrase-style commands (none yet)" rewritten
  — Backup (export/restore .relbak) and Import (lastpass) both shipped.
- relicario-cli: module map refreshed — handlers moved out of main.rs
  into commands/, plus prompt.rs/parse.rs/device.rs/gitea.rs surfaced.

Stale main.rs:NNNN line citations on individual flows are not fixed
here — those handlers now live in commands/*.rs and warrant a deeper
pass later.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
adlee-was-taken
2026-05-30 13:24:49 -04:00
parent 210232d156
commit cf7478d178
2 changed files with 134 additions and 26 deletions

View File

@@ -101,6 +101,38 @@ Pipeline" and "Crate Layout").
auth factor. Owns its own `YChannel`, `EmbedRegion`, 8×8 DCT/IDCT,
Quantization Index Modulation, and crop-recovery extractor. No other module
imports it; it is consumed only via the public re-export from `lib.rs`.
- **`backup.rs`** — `.relbak` v1 container format: `pack_backup` /
`unpack_backup` plus the `BackupInput` / `BackupOutput` / `BackupItem` /
`BackupAttachment` shapes. Wraps a zstd-compressed JSON envelope of vault
bytes (salt, params.json, devices.json, manifest, settings, items,
attachments, optional reference JPEG, optional `.git/` tar) in an
XChaCha20-Poly1305 envelope keyed by Argon2id over a user-chosen *backup*
passphrase. The backup key is independent of any vault master key, and
Argon2id parameters are pinned to the v1 values (m=64MiB, t=3, p=4) so a v1
reader doesn't need to negotiate them.
- **`import_lastpass.rs`** — `parse_lastpass_csv` plus `ImportWarning`. Pure
bytes-in / `Vec<Item>`-out LastPass CSV importer: validates the fixed
8-column header, mints fresh IDs and timestamps for each row, downgrades or
skips malformed rows into `ImportWarning`s instead of aborting the import.
Only fatal error is a missing/malformed header.
- **`device.rs`** — Device-identity surface: `DeviceEntry`, `RevokedEntry`,
`generate_keypair`, `sign`, `verify`, `fingerprint`. ed25519 in OpenSSH
format (so private keys are interchangeable with `ssh-keygen`-produced
keys); the same module backs both `.relicario/devices.json` entries and the
server's pre-receive commit-verification hook.
- **`tar_safe.rs`** — `safe_unpack_git_archive` + `DEFAULT_MAX_UNCOMPRESSED`
(1 GiB). Hardened tar reader used by `backup::unpack_backup` for the
bundled `.git/` directory: rejects `..` components, absolute paths, Windows
drive prefixes, symlinks, hardlinks, and any entry whose declared size
(or running total across all entries) exceeds the supplied cap.
- **`recovery_qr.rs`** — `generate_recovery_qr` / `unwrap_recovery_qr` plus
`recovery_qr_to_svg`. Produces a 109-byte XChaCha20-Poly1305 envelope
around the 32-byte image_secret, keyed by Argon2id over a user-chosen
recovery passphrase with the domain-separation prefix
`b"relicario-recovery-v1\0"`. Parameters are pinned at module scope —
changing them invalidates every printed QR — and both salt and nonce are
freshly randomized per call so two QRs printed from the same inputs are
different bytes.
## Invariants & contracts
@@ -386,11 +418,11 @@ when subsequent `decrypt_*` returns `RelicarioError::Decrypt`.
`generators::bip39_passphrase`. A single `rand::thread_rng()` call exists
inside an `imgsecret` test (`imgsecret.rs:1033`) to generate a random test
secret; production code is `OsRng` only.
- **`ed25519-dalek` is a dependency placeholder.** Listed in
`Cargo.toml:17` but unused in `src/`. It exists for the future
device-key surface (`RelicarioError::DeviceKey` is the reserved variant,
`error.rs:84-88`); device-key signing currently happens in
`relicario-cli` instead.
- **`ed25519-dalek` is consumed by `device.rs`.** Together with `ssh-key` (for
OpenSSH wire encoding) it backs `generate_keypair`, `sign`, and `verify`
the same primitives the CLI uses to populate `.relicario/devices.json` and
the server uses to verify pre-receive commit signatures. The corresponding
error variant is `RelicarioError::DeviceKey`.
## Test architecture