docs: update CLAUDE.md for the typed-item module layout

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
adlee-was-taken
2026-04-20 18:47:08 -04:00
parent c3edf9d413
commit 65e0d3cb80

View File

@@ -10,8 +10,10 @@ relicario is a git-backed, self-hostable password manager with a Rust core. Two-
cargo build # build everything cargo build # build everything
cargo test # run all tests (unit + integration) cargo test # run all tests (unit + integration)
cargo test -p relicario-core # core library tests only cargo test -p relicario-core # core library tests only
cargo run -- --help # CLI help cargo test -p relicario-cli --test basic_flows # CLI integration tests
cargo run -- generate -l 32 # quick smoke test cargo build -p relicario-wasm --target wasm32-unknown-unknown # WASM target
cargo run -p relicario-cli -- --help # CLI help
cargo run -p relicario-cli -- generate --length 32 # quick smoke test
``` ```
## Project structure ## Project structure
@@ -22,15 +24,26 @@ crates/
│ ├── src/ │ ├── src/
│ │ ├── lib.rs # Re-exports public API │ │ ├── lib.rs # Re-exports public API
│ │ ├── error.rs # RelicarioError enum (thiserror) │ │ ├── error.rs # RelicarioError enum (thiserror)
│ │ ├── crypto.rs # Argon2id KDF + XChaCha20-Poly1305 encrypt/decrypt │ │ ├── crypto.rs # Argon2id KDF (length-prefixed, Zeroizing) + XChaCha20-Poly1305
│ │ ├── entry.rs # Entry, ManifestEntry, Manifest structs (serde) │ │ ├── ids.rs # ItemId, FieldId, content-addressed AttachmentId
│ │ ├── vault.rs # encrypt_entry, decrypt_entry, encrypt_manifest, decrypt_manifest │ │ ├── time.rs # now_unix, MonthYear
│ │ ── imgsecret.rs # DCT-based 256-bit secret embedding in JPEGs │ │ ── item_types/ # per-type cores + ItemType/ItemCore enums
── tests/ │ ├── item.rs # Item envelope, Field, FieldKind, FieldValue, Section
── integration.rs # Full-workflow and two-factor independence tests ── attachment.rs # AttachmentRef, EncryptedAttachment, encrypt/decrypt helpers
└── relicario-cli/ # CLI binary │ │ ├── manifest.rs # Browse-without-decrypt index (schema_version 2)
└── src/ │ ├── settings.rs # VaultSettings: retention, generator defaults, caps
── main.rs # clap CLI: init, add, get, list, edit, rm, sync, generate, device ── generators.rs # CSPRNG password + BIP39 + zxcvbn gate
│ │ ├── vault.rs # JSON ↔ AEAD wrappers for Item/Manifest/VaultSettings
│ │ └── imgsecret.rs # DCT steganography (MAX_DIMENSION cap)
│ └── tests/ # integration.rs, attachments.rs, generators.rs, format_v2.rs, field_history.rs
├── relicario-cli/ # `relicario` binary
│ ├── src/main.rs # clap surface + command handlers
│ ├── src/helpers.rs # vault_dir, git_command, iso8601
│ ├── src/session.rs # UnlockedVault (master key in Zeroizing)
│ └── tests/ # basic_flows, edit_and_history, attachments, settings, vault_detection
└── relicario-wasm/ # WASM bindings for the extension
├── src/lib.rs # #[wasm_bindgen] surface
└── src/session.rs # opaque SessionHandle → Zeroizing<[u8;32]>
``` ```
## Key design decisions ## Key design decisions
@@ -49,14 +62,14 @@ passphrase (UTF-8 bytes) || image_secret (32 bytes from reference JPEG)
→ Argon2id(salt=vault_salt, m=64MiB, t=3, p=4) → Argon2id(salt=vault_salt, m=64MiB, t=3, p=4)
→ master_key (32 bytes) → master_key (32 bytes)
→ XChaCha20-Poly1305(nonce=random 24 bytes) → XChaCha20-Poly1305(nonce=random 24 bytes)
→ encrypted entry/manifest → encrypted Item/Manifest/VaultSettings
``` ```
## Conventions ## Conventions
- Tests use fast Argon2id params (m=256, t=1, p=1) so they don't take forever. - Tests use fast Argon2id params (m=256, t=1, p=1) so they don't take forever.
- Test JPEGs are generated synthetically via `make_test_jpeg()` — no binary test fixtures. - Test JPEGs are generated synthetically via `make_test_jpeg()` — no binary test fixtures.
- Entry IDs are random 8-char hex strings. - Item IDs are random 8-char hex strings.
- Git history is preserved as an audit log — no squashing. - Git history is preserved as an audit log — no squashing.
- The CLI shells out to `git` for sync — no libgit2/gitoxide dependency. - The CLI shells out to `git` for sync — no libgit2/gitoxide dependency.