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:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user