# Architecture: relicario-core

## What this crate is for

`relicario-core` is the platform-agnostic cryptographic and data-model heart of the
relicario password manager. It is strictly **bytes-in / bytes-out**: every public
function takes byte slices or owned typed structs and returns byte vectors or typed
structs. The crate performs no filesystem I/O, no network I/O, no git operations,
and no time-of-day reads beyond `chrono::Utc::now()` for timestamping items
(`time.rs:6`). This boundary is what lets the same compiled artifact serve the
native CLI (`relicario-cli`), a `wasm32-unknown-unknown` build embedded in the
Chrome MV3 / Firefox WebExtension popup (`relicario-wasm`), and (eventually) ARM
mobile builds — without conditional compilation. Anything that touches a
`Path`, opens a socket, or shells out belongs in `relicario-cli` or the
extension layer, never here. The historical rationale is in
`docs/superpowers/specs/2026-04-11-relicario-design.md` (sections "Crypto
Pipeline" and "Crate Layout").

## Module map

- **`lib.rs`** — Public API surface. Re-exports the symbols that callers actually
  need (`encrypt_item`, `derive_master_key`, `Item`, `ItemCore`, etc.). The
  module list here is the contract; everything else is internal.
- **`error.rs`** — `RelicarioError` (a `thiserror`-derived enum) plus the crate
  alias `Result<T> = std::result::Result<T, RelicarioError>`. One error type
  for the whole crate so FFI / WASM bindings and CLI handlers each have a single
  exhaustive `match` to maintain. `Decrypt` is intentionally opaque (no inner
  detail string) — see "Cross-cutting concerns".
- **`crypto.rs`** — KDF (`derive_master_key`, Argon2id with NFC-normalized,
  length-prefixed inputs) and AEAD (`encrypt`, `decrypt`, XChaCha20-Poly1305
  with `VERSION_BYTE = 0x02`). Owns the on-disk ciphertext layout. The KDF
  parameters (`KdfParams`) are an owned struct that callers persist however
  they like (CLI puts them in `.relicario/params.json`); the crate has no
  opinion about storage.
- **`ids.rs`** — `ItemId`, `FieldId` (random 64-bit hex from `OsRng`,
  `ids.rs:26-32`, `ids.rs:38-49`) and content-addressed `AttachmentId`
  (first 8 bytes of `SHA-256(plaintext)`, `ids.rs:51-57`). Three separate
  newtypes rather than `String` so misuses can't compile.
- **`time.rs`** — `now_unix()` and `MonthYear` (the validated 1..=12 / 2000..=2099
  card-expiry type). Trivially small; broken out only because every other module
  needs `now_unix()` and `MonthYear` is used by both `item.rs` and
  `item_types/card.rs`.
- **`item_types/mod.rs`** — `ItemType` enum (snake-case wire tag) and `ItemCore`
  (internally tagged `#[serde(tag = "type")]` enum), with one variant per item
  type. The "extension via match exhaustiveness" pattern is documented at
  `item_types/mod.rs:1-7`: adding an item type is a `cargo check` walk through
  every match arm. Re-exports each per-type core.
- **`item_types/login.rs`** — `LoginCore` (username, password as
  `Zeroizing<String>`, optional `Url`, optional `TotpConfig`).
- **`item_types/secure_note.rs`** — `SecureNoteCore` (single `Zeroizing<String>`
  body).
- **`item_types/identity.rs`** — `IdentityCore` (full name, address, phone,
  email, DOB; all optional, none `Zeroizing` — they're personal data, not
  secret material).
- **`item_types/card.rs`** — `CardCore` plus `CardKind` (Credit/Debit/Gift/
  Loyalty/Other). `number`, `cvv`, `pin` are `Zeroizing`; `holder` is plain
  `String`.
- **`item_types/key.rs`** — `KeyCore`: opaque `Zeroizing<String>` `key_material`
  with optional label / public key / algorithm. Used for SSH keys, GPG keys,
  arbitrary blobs.
- **`item_types/document.rs`** — `DocumentCore`: filename + mime + a single
  `AttachmentId` pointing at the primary blob. The body lives in the
  attachment store, not the item.
- **`item_types/totp.rs`** — `TotpCore`, `TotpConfig`, `TotpAlgorithm`
  (Sha1/Sha256/Sha512), `TotpKind` (Totp / Hotp{counter} / Steam), and the
  `compute_totp_code()` function. Includes the Steam Mobile Authenticator
  5-character alphabet and its conversion (`item_types/totp.rs:103-110`).
  The same `TotpConfig` is reused as a sub-struct of `LoginCore` (so a Login
  item can carry its own TOTP without spawning a separate item).
- **`item.rs`** — The `Item` envelope. Holds the parallel `FieldKind` /
  `FieldValue` enums (kept parallel so callers can ask the kind without
  inspecting the value, `item.rs:1-6`), `Field`, `Section`, `FieldHistoryEntry`,
  and the `Item` struct itself with its `set_field_value` / `soft_delete` /
  `restore` / `prune_history` mutators. Custom-fields and field-history live
  here, not in the per-type cores.
- **`attachment.rs`** — `AttachmentRef` (full record carried on `Item`),
  `AttachmentSummary` (compact form carried in `Manifest`),
  `EncryptedAttachment`, and the `encrypt_attachment` / `decrypt_attachment`
  helpers. The size cap is enforced **before** any crypto work (`attachment.rs:69-74`).
- **`manifest.rs`** — The browse-without-decrypt index: `Manifest`,
  `ManifestEntry`, `MANIFEST_SCHEMA_VERSION = 2`. `upsert(&item)` rebuilds the
  entry from the item — there is no path for the manifest to drift from the
  source-of-truth item file. Includes case-insensitive title/tag search
  (`manifest.rs:59-68`) and Login icon-hint derivation (host of the URL,
  `manifest.rs:93-99`).
- **`settings.rs`** — `VaultSettings` and its sub-types: `TrashRetention`,
  `HistoryRetention`, `GeneratorRequest` (`Random` or `Bip39`),
  `AttachmentCaps`, plus the `autofill_origin_acks` map for the extension's
  TOFU prompt.
- **`generators.rs`** — Random-password and BIP-39 passphrase generation, both
  driven by `GeneratorRequest` from `settings.rs`. zxcvbn-backed
  `rate_passphrase` and the `validate_passphrase_strength` gate that rejects
  any score < 3.
- **`vault.rs`** — Typed wrappers around `crypto::{encrypt, decrypt}`:
  `encrypt_item`/`decrypt_item`, `encrypt_manifest`/`decrypt_manifest`,
  `encrypt_settings`/`decrypt_settings`. Each does
  `serde_json::to_vec → encrypt` (or the inverse). The plaintext `Vec<u8>` is
  wrapped in `Zeroizing` between serde and the cipher
  (`vault.rs:18-19`, `vault.rs:24-26`).
- **`imgsecret.rs`** — Self-contained DCT-based steganography for the second
  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`.

## Invariants & contracts

- **No filesystem, no network, no git, no spawn.** Verified by inspecting
  imports; the only I/O-shaped types in use are in-memory `Cursor<&[u8]>`
  for image decoding (`imgsecret.rs:243`).
- **No `unsafe`.** Confirmed by `grep` over `src/`. The crate compiles to WASM
  unmodified for that reason.
- **No `async`.** All operations are pure compute on byte slices. Async lives
  in `relicario-cli` (process spawning) and in the extension's service worker
  (message channels), not here.
- **`VERSION_BYTE = 0x02`** (`crypto.rs:59`). Every blob produced by
  `encrypt()` starts with this byte; `decrypt()` rejects any other value with
  `RelicarioError::UnsupportedFormatVersion { found, expected }`
  (`crypto.rs:127-132`). v1 blobs (the pre-rewrite format) are explicitly
  tested for rejection (`tests/format_v2.rs:28-42`).
- **AEAD blob layout** is fixed at `version(1) || nonce(24) || ciphertext+tag(≥16)`
  (`crypto.rs:18-32`). Minimum valid blob length is 41 bytes
  (`crypto.rs:118-124`).
- **Nonces are always fresh from `OsRng`** (`crypto.rs:87-89`). There is no
  caller-supplied nonce path. With 192 bits of randomness, collision risk is
  negligible across the lifetime of any vault.
- **`MANIFEST_SCHEMA_VERSION = 2`** (`manifest.rs:12`). v1 manifests (which
  predate typed items) are not handled here and are rejected at the JSON-parse
  step.
- **KDF input is length-prefixed.** `derive_master_key` builds the password
  buffer as `u64_be(len(passphrase)) || passphrase || u64_be(32) || image_secret`
  (`crypto.rs:229-236`). This eliminates the (`"abc"`, `0x44…`) vs (`"abcD"`,
  `…`) collision, and is exercised in
  `crypto.rs:352-368` and `tests/format_v2.rs:44-54`.
- **Passphrases are NFC-normalized before hashing.** Bytes that aren't valid
  UTF-8 pass through unchanged (`crypto.rs:223-227`). This keeps "café"
  (precomposed) and "café" (combining acute) from producing different keys
  (`crypto.rs:370-385`).
- **Master key only ever lives in `Zeroizing<[u8; 32]>`.** Returned that way
  by `derive_master_key` (`crypto.rs:212`) and accepted that way by
  `encrypt_item` / `encrypt_attachment` / friends. No public function in
  `vault.rs` or `attachment.rs` accepts a raw `[u8; 32]`.
- **Plaintext is wrapped in `Zeroizing` between serde and the cipher.** See
  `vault.rs:18-19`, `vault.rs:24-26`, `vault.rs:31-32`, `vault.rs:37-38`,
  `vault.rs:44-45`, `vault.rs:50-51`. The serde JSON intermediate buffer is the
  most exposed point, so it is wiped on drop.
- **`AttachmentId` is content-addressed** to the first 8 bytes (= 16 hex chars)
  of `SHA-256(plaintext)` (`ids.rs:51-57`). Identical plaintexts deduplicate
  in git automatically — proven in `tests/attachments.rs:28-35`. The 64-bit
  prefix is used (rather than the full digest) to keep filenames short; the
  collision space is still adequate for the expected vault size.
- **`ItemId` and `FieldId` are 16 hex chars** = 64 bits of `OsRng` entropy
  (`ids.rs:25-32`, `ids.rs:38-49`). The audit (M8) bumped them from the
  original 8-char / 32-bit format.
- **Field kind/value discriminants must agree.** `Field::new` derives `kind`
  from `value` (`item.rs:85-94`); `Field::validate` (called after deserialize)
  rejects any mismatch (`item.rs:97-107`). `set_field_value` further refuses
  to change a field's kind (`item.rs:184-189`).
- **Field-history capture is restricted to three kinds:** `Password`,
  `Concealed`, `Totp` (`item.rs:68-71`). Any other kind's update silently
  skips history. The TOTP secret is base32-encoded for the history entry
  (`item.rs:245-249`) so a user reading their history sees a recognizable
  string.
- **History captures the *previous* value, not the new one** (`item.rs:190-197`):
  `set_field_value` serializes `field.value` *before* assigning the new value.
- **`hidden_by_default` is set automatically** when the field's kind is
  `Password` or `Concealed` (`item.rs:92`). The extension and CLI both honor
  this hint when rendering.
- **Attachment cap is checked before encryption** (`attachment.rs:69-74`).
  An oversize blob fails with `RelicarioError::AttachmentTooLarge { size, max }`
  without ever calling `encrypt`. The CLI/extension are expected to read the
  cap from `VaultSettings::attachment_caps`.
- **`Item::soft_delete` does not erase data.** It sets `trashed_at` and bumps
  `modified` (`item.rs:205-208`). Purging is the caller's responsibility,
  driven by `TrashRetention::should_purge` (`settings.rs:38-44`).
- **`prune_history` is idempotent and explicit.** Items keep all history until
  the caller invokes it with a `HistoryRetention` policy (`item.rs:219-237`).
  Last-N drops oldest first; Days drops anything older than `now - days·86400`.
- **`item_type()` is the single source of truth** for the type tag stored on
  `Item`. `Item::new` derives `r#type` from the supplied `ItemCore`
  (`item.rs:159-164`). Manual construction can violate this — the JSON
  round-trip does not re-validate beyond serde's tag matching.
- **Reserved serde key:** no `*Core` may have a JSON-serialized field named
  `"type"` — that name is reserved for serde's discriminator on `ItemCore`
  (`item_types/mod.rs:38-40`). Use `"kind"` instead (see `CardKind`,
  `TotpKind`).
- **`MAX_DIMENSION = 10_000`** for imgsecret (`imgsecret.rs:71`). Enforced via
  a header-only peek (`imgsecret.rs:127-176`) at the entry of both `embed` and
  `extract` so an attacker-supplied 32000×32000 JPEG is rejected without
  decoding pixels (audit M3).
- **`MIN_DIMENSION = 100`** plus a "must hold ≥5 redundant copies" floor
  (`imgsecret.rs:66`, `imgsecret.rs:78`, `imgsecret.rs:682-689`). Smaller
  carriers are rejected with `ImageTooSmall`.
- **Strength gate is `score >= 3`** (`generators.rs:124-130`). Vault-creation
  callers must invoke `validate_passphrase_strength` themselves; the crate
  does not internally call it inside `derive_master_key` (since that path is
  also used to derive the key for *unlock*, not just create).
- **`SymbolCharset::Custom` must be ASCII-only** (`generators.rs:46-52`).
  Non-ASCII custom charsets are rejected with `RelicarioError::Format`.

## Key flows

### Vault unlock — key derivation

1. Caller obtains `passphrase: &[u8]` (UTF-8) and `image_secret: &[u8; 32]`
   (typically from `imgsecret::extract` over the user's reference JPEG).
2. Caller loads `salt: [u8; 32]` and `KdfParams` from out-of-band storage
   (CLI: `.relicario/salt` and `.relicario/params.json`).
3. `derive_master_key(passphrase, &image_secret, &salt, &params)` —
   `crypto.rs:207-244`:
   - NFC-normalize the passphrase if it parses as UTF-8 (`crypto.rs:223-227`).
   - Build the length-prefixed password buffer in a `Zeroizing<Vec<u8>>`
     (`crypto.rs:229-236`).
   - Run `Argon2id` with `Algorithm::Argon2id`, `Version::V0x13`,
     output length 32 (`crypto.rs:213-221`, `crypto.rs:238-241`).
4. Returns `Zeroizing<[u8; 32]>` — automatically wiped on drop.

A wrong passphrase or wrong image produces a *different* derived key. The crate
cannot tell them apart at this stage; the caller learns "wrong factor" only
when subsequent `decrypt_*` returns `RelicarioError::Decrypt`.

### Item write

1. Caller mutates an `Item` (e.g. `item.set_field_value(&fid, new_value)` —
   `item.rs:181-203`). `set_field_value` captures previous value into
   `field_history` if the kind is history-tracked, then bumps `modified`.
2. Caller calls `encrypt_item(&item, &master_key)` — `vault.rs:16-20`:
   `serde_json::to_vec(item)` → wrap in `Zeroizing` → `crypto::encrypt`.
3. Caller calls `manifest.upsert(&item)` (`manifest.rs:45-48`) to refresh the
   browse-index entry; then `encrypt_manifest(&manifest, &master_key)`
   (`vault.rs:29-33`).
4. The two ciphertext blobs are returned to the caller, who writes them to disk
   (or commits them, or sends them over a sync channel).

### Item read (browse-without-decrypt path)

1. Caller calls `decrypt_manifest(&manifest_blob, &master_key)`
   (`vault.rs:35-40`). One AEAD decryption gets the entire searchable index.
2. `Manifest::search(query)` does a case-insensitive substring match over title
   and tags (`manifest.rs:59-68`). `manifest.items.values()` gives every
   `ManifestEntry` with `title`, `tags`, `favorite`, `group`, `icon_hint`,
   `modified`, `trashed_at`, and `attachment_summaries` — enough to render a
   list UI without touching any item file.
3. When the user picks an entry, the caller reads `entries/<id>.enc` and calls
   `decrypt_item(&blob, &master_key)` (`vault.rs:22-27`) to get the full
   `Item` including secret fields and `field_history`.

### Attachment encryption

1. Caller has `plaintext: &[u8]`, the `master_key`, and the active
   `VaultSettings::attachment_caps.per_attachment_max_bytes`.
2. `encrypt_attachment(plaintext, &master_key, max_bytes)` —
   `attachment.rs:64-78`:
   - If `plaintext.len() > max_bytes`, return `AttachmentTooLarge` *immediately*
     before any crypto.
   - `AttachmentId::from_plaintext(plaintext)` (SHA-256, `ids.rs:51-57`).
   - `crypto::encrypt(master_key, plaintext)`.
3. Returns `EncryptedAttachment { id, bytes }`. The caller persists `bytes` at
   `attachments/<id>.enc` and adds an `AttachmentRef { id, filename, mime_type,
   size, created }` (`attachment.rs:11-20`) to the owning `Item`. On
   `Manifest::upsert`, an `AttachmentSummary` (no `created` field) is derived
   automatically (`manifest.rs:87`).

### Field-history capture

1. Triggered exclusively by `Item::set_field_value` (`item.rs:181-203`). Direct
   mutation of `field.value` bypasses history — the type system does not
   prevent this.
2. The check `field.value.is_history_tracked()` runs *on the existing value*
   (`item.rs:190`), so adding the *first* password value to a previously-empty
   field does not create a history entry; updating an already-set password
   does.
3. The previous value is serialized via `serialize_history_value`
   (`item.rs:241-253`):
   - `Password(p)` and `Concealed(c)` clone the inner string into a fresh
     `Zeroizing<String>`.
   - `Totp(cfg)` base32-encodes the raw secret bytes
     (`item.rs:245-249`, `item.rs:256-275`).
   - Any other kind would error (`item.rs:250`), but is unreachable because
     `is_history_tracked` already gated the call.
4. Pruning is *not* automatic. Callers (CLI commit hook, extension save handler)
   call `item.prune_history(&settings.field_history_retention, now_unix())`
   when they want to enforce the policy.

### imgsecret embed

1. Caller passes a JPEG byte slice and a 32-byte secret to
   `imgsecret::embed(carrier_jpeg, &secret)` (`imgsecret.rs:666-726`).
2. `enforce_dimension_cap` walks JPEG markers (`imgsecret.rs:127-161`) to read
   the SOF dimensions; rejects > 10_000 × 10_000 before any pixel decode.
3. `extract_y_channel` decodes via `image::ImageReader` and converts each pixel
   to BT.601 luminance (`imgsecret.rs:242-265`).
4. `central_region` picks the inner 70% of the image as the embed region; the
   15% margin per side is the "crumple zone" for crops
   (`imgsecret.rs:268-293`).
5. `compute_embed_positions` / `select_embed_blocks` lay out
   `num_copies × BLOCKS_PER_COPY` 8×8 blocks evenly across the region, with
   `num_copies` = `min(50, total_blocks / 22)` (`imgsecret.rs:530-575`).
6. For each block: 2D DCT (`dct2_8x8`, `imgsecret.rs:393-412`) → embed 12 bits
   into the 12 mid-frequency coefficients listed in `EMBED_POSITIONS`
   (zig-zag positions 6–17, `imgsecret.rs:105-118`) via QIM with
   `QUANT_STEP = 50.0` (`imgsecret.rs:462-467`) → 2D inverse DCT → write
   back into Y.
7. `reconstruct_jpeg` (`imgsecret.rs:590-640`) re-derives Cb/Cr per pixel from
   the original RGB (so chrominance is preserved), combines with the modified
   Y, and re-encodes at JPEG quality 92.

### imgsecret extract (with crop recovery)

1. `extract(jpeg_bytes)` enforces the dimension cap, then delegates to
   `extract_with_crop_recovery` (`imgsecret.rs:738-741`,
   `imgsecret.rs:849-899`).
2. **Try 1** — assume uncropped: `try_extract_with_layout(&y, w, h, 0, 0)`.
   This is the hot path; for a freshly embedded image it always succeeds.
3. **Try 2** — width-only crop, block-aligned: iterate `orig_w` from current
   width up to `1.20 × current_w` in 8-px steps, with `dx = 0`
   (assume right-edge crop).
4. **Try 3** — height-only crop, block-aligned: same strategy on the vertical
   axis.
5. **Try 4** — width crops at non-block-aligned 1-px steps, skipping any
   already covered in Try 2.
6. `try_extract_with_layout` (`imgsecret.rs:754-834`) tallies QIM votes for
   each of the 256 bit positions across all `num_copies` copies. Each bit
   must reach **≥60% confidence** (`imgsecret.rs:824`); below that, the
   whole extraction fails with `ExtractionFailed` (no partial result is
   ever returned).
7. The 60% threshold is per-bit, not aggregate — a single unconfident bit
   aborts the whole try. This makes false-positive extractions from
   never-embedded images vanishingly unlikely.

## Cross-cutting concerns

- **Error model.** `RelicarioError` (`error.rs:15-89`) is a single
  `thiserror`-derived enum. `Decrypt` is the deliberately-opaque "wrong key
  or tampered ciphertext" variant (audit M4 — `error.rs:28-30`,
  `tests/integration.rs:99-111`): the message is just `"decryption failed"`
  with no inner string, and it does not distinguish wrong-passphrase from
  wrong-image-secret from corrupted ciphertext. `Format` is the
  "input bytes don't make sense" variant (e.g. blob too short, schema
  mismatch). `UnsupportedFormatVersion` is the structured "wrong version
  byte" variant — separate from `Format` because callers want to react to
  it differently (offer migration, etc.).
- **Where secrets live.** Every secret type wraps `Zeroizing<...>`:
  - The derived master key: `Zeroizing<[u8; 32]>` (`crypto.rs:212`).
  - Field values: `FieldValue::Password(Zeroizing<String>)` and
    `FieldValue::Concealed(Zeroizing<String>)` (`item.rs:39-40`).
  - `FieldHistoryEntry::value`: `Zeroizing<String>` (`item.rs:127`).
  - Per-type cores: `LoginCore::password`, `CardCore::{number,cvv,pin}`,
    `KeyCore::key_material`, `SecureNoteCore::body`, `TotpConfig::secret`
    (a `Zeroizing<Vec<u8>>` of the raw HMAC key).
  - Decrypted attachment plaintext: `Zeroizing<Vec<u8>>`
    (`attachment.rs:88-92`).
  - Argon2id input buffer (`crypto.rs:232`) and JSON serialization buffers in
    `vault.rs` are wrapped in `Zeroizing` to wipe the intermediate plaintext.
- **Format versioning.** Three independent version channels exist, each
  gating something different:
  - `crypto::VERSION_BYTE = 0x02` (`crypto.rs:59`) — gates the AEAD blob
    layout. Bumped if the nonce length, header layout, or cipher changes.
    A v1 blob is rejected with a typed
    `UnsupportedFormatVersion { found: 0x01, expected: 0x02 }`.
  - `manifest::MANIFEST_SCHEMA_VERSION = 2` (`manifest.rs:12`) — gates the
    JSON-level shape of the manifest. v1 manifests had a different layout
    and would fail to parse against the current `Manifest` struct.
  - The `.relbak` import/export format defined in
    `docs/superpowers/specs/2026-04-27-relicario-import-export-design.md`
    will introduce a third version channel for backups; that surface lives
    outside this crate.
- **KDF parameter handling.** `KdfParams` (`crypto.rs:156-168`) is just a
  serializable struct. The crate has no opinion about where it is stored,
  how it is rotated, or who increments it. `Default` gives the production
  values (`m=65536`, `t=3`, `p=4` — `crypto.rs:175-183`) calibrated for
  ~0.5–1 s on a modern desktop. Tests universally use the fast triplet
  `(m=256, t=1, p=1)` defined as a `fn fast_params()` near the top of every
  test file.
- **NFC normalization is the only Unicode op.** All passphrase canonicalization
  happens in one place (`crypto.rs:223-227`). Item titles, field labels,
  tags, etc. are stored verbatim — only the passphrase fed to the KDF is
  normalized.
- **No per-entry subkeys.** Every encrypted blob (item, manifest, settings,
  attachment) is encrypted with the *same* master key. The design rationale
  is in `docs/superpowers/specs/2026-04-11-relicario-design.md` lines 66:
  per-entry subkey derivation would add complexity for no real-world benefit
  given the expected family-vault size.
- **CSPRNG is `OsRng` everywhere.** `ItemId::new`, `FieldId::new`,
  `derive_master_key` (no-op — the salt is caller-supplied),
  `crypto::encrypt` (nonce), `generators::random_password`,
  `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.

## Test architecture

All `tests/` files use the fast Argon2id triplet `m=256, t=1, p=1` so the
suite runs in seconds, not minutes. Test JPEGs are synthesized at runtime via
`make_test_jpeg(width, height)` (`imgsecret.rs:908-924`) — a deterministic RGB
pattern at quality 92 — so no binary fixtures live in git.

- **`tests/integration.rs`** — End-to-end vault workflows: encrypt+decrypt a
  Login and a SecureNote through `Manifest`/`VaultSettings`, two-factor
  independence (different passphrase or different image_secret yields
  different keys), field-history surviving an encrypt/decrypt round-trip,
  and the wrong-key-→-`Decrypt` opaqueness contract.
- **`tests/attachments.rs`** — Round-trip a 5 KB blob, prove identical
  plaintexts produce identical `AttachmentId`s (despite different ciphertext
  bytes due to fresh nonces), and exercise the cap boundary at exactly the
  max byte and one over.
- **`tests/field_history.rs`** — Sequential `set_field_value` calls accumulate
  history in oldest→newest order; `prune_history(LastN(3))` keeps the most
  recent 3; field-history survives `encrypt_item` →`decrypt_item`.
- **`tests/format_v2.rs`** — `VERSION_BYTE == 0x02`, fresh ciphertext starts
  with `0x02`, a v1-shaped blob (`[0x01][24 nonce][16 tag]`) is rejected with
  the typed `UnsupportedFormatVersion`, and the length-prefix construction
  prevents `("abc", 0x44…)` / `("abcD", …)` collisions.
- **`tests/generators.rs`** — Aggregates 80 × 128 = 10,240 chars from
  `generate_password` to assert per-character-class proportions are within
  ±5 pp of the expected uniform distribution; verifies that 5-word BIP-39
  passes the strength gate while common weak passwords ("password",
  "12345678", "letmein", "qwertyui", "hunter2") all fail; asserts uniqueness
  across 1000 default-config calls. The opening doc comment
  (`tests/generators.rs:1-13`) explains why the original "10,000-char single
  call" plan switched to aggregation: `generate_password` enforces
  `length ≤ 128`.

In-module `#[cfg(test)] mod tests` blocks cover unit-level invariants (kind/
value mismatches, snake-case serde tags, base32 round-trips, `MonthYear`
constructor bounds, the Steam alphabet ambiguity audit). The `imgsecret`
test block additionally proves DCT round-tripping, QIM noise tolerance below
`Q/4 = 12.5`, embed→Q85-recompress→extract round-trip, embed→10%-crop→extract
round-trip, and the oversized-image-header rejection path.

## Gotchas & non-obvious decisions

- **`QUANT_STEP = 50.0` is intentionally double the academic value of 25**
  (`imgsecret.rs:62`). Higher quantization steps make the watermark more robust
  to JPEG recompression at Q85 and below — at the cost of more visible
  artifacts in the carrier. The reference image is a personal photo, not a
  publication, so the trade-off favors robustness.
- **The embed region is the *central 70%* (15% margin per side, "crumple
  zone")** — `imgsecret.rs:212-218`, `imgsecret.rs:276-293`. Anything in the
  outer 15% is sacrificed so that mild edge crops (e.g. social-media platform
  trims) leave the embedded data intact. Tested up to 10% crop in
  `imgsecret.rs:1108-1137`.
- **Per-bit majority voting with a 60% confidence floor.**
  `try_extract_with_layout` tallies votes from every redundant copy and
  fails the entire extraction if any single bit position is below 60%
  agreement (`imgsecret.rs:824`). This is more conservative than a global
  threshold and is what makes false positives from never-embedded images
  essentially zero — see `extract_from_non_embedded_image_fails`
  (`imgsecret.rs:1041-1045`).
- **Number of redundant copies is capped at 50** (`imgsecret.rs:536`,
  `imgsecret.rs:692-693`). Beyond that, per-block visual artifacts compound
  faster than the error-correction benefit grows.
- **`peek_jpeg_dimensions` walks JPEG markers manually instead of using the
  `image` crate.** `imgsecret.rs:127-161`. A full `ImageReader::decode` of an
  attacker-supplied 30 000 × 30 000 JPEG would allocate ~3.6 GB of pixel
  buffer in the WASM service worker before failing — the manual walk reads
  only the SOF segment and bails in O(marker-count) (audit M3).
- **`bip39` always generates 128 bits of entropy** (12 mnemonic words) and
  truncates to `word_count` (`generators.rs:82-89`). This is because
  `bip39 v2` rejects entropy below 128 bits, but we want to support 3–12 word
  passphrases. Truncation preserves the per-word independence — the words
  the user sees still come from a uniformly-sampled-then-truncated 12-word
  draw.
- **Steam TOTP output is exactly 5 characters from a 26-glyph alphabet,
  regardless of the `digits` field on `TotpConfig`** (`item_types/totp.rs:103-110`,
  asserted in `item_types/totp.rs:240-253`). The alphabet
  (`23456789BCDFGHJKMNPQRTVWXY`) excludes `0/O`, `1/I/L`, `S` (so `5` is
  unambiguous), `A`, `E`, `U`, `Z` — all glyphs Valve considered ambiguous
  in the Steam Mobile Authenticator. Verified at
  `item_types/totp.rs:274-283`.
- **`ItemCore` is internally-tagged with `#[serde(tag = "type")]`** — the
  outer JSON object gets a `"type"` key. This means *no* `*Core` struct may
  have a field literally named `type`. The convention chosen for
  type-discriminant fields *inside* a core is `kind` — see `CardKind`,
  `TotpKind` (`item_types/mod.rs:38-40`).
- **The TOTP base32 in field-history strips padding.** `base32_encode`
  (`item.rs:256-275`) is RFC-4648 with no `=` padding — appropriate because
  the value is for human display in history, not for re-decoding.
- **`AttachmentId::from_plaintext` uses only the first 8 bytes (= 16 hex
  chars) of the SHA-256 digest** (`ids.rs:51-57`). 64 bits of collision
  resistance is sufficient for a personal-vault attachment count; it keeps
  filenames short. If a future use case demands collision resistance against
  motivated adversaries (e.g. dedup across untrusted vaults), this width is
  the lever.
- **`Field::new` derives `kind` from `value`, but the public struct still
  stores both** (`item.rs:73-94`). The duplication exists so callers can
  match on `kind` without inspecting (and potentially decrypting / cloning)
  `value`. `validate()` is the safety net that runs after deserialization.
- **`set_field_value` refuses to change a field's kind** (`item.rs:184-189`).
  The intent is that fields are conceptually fixed-shape after creation;
  changing a `Text` to a `Password` should be done by deleting the old field
  and creating a new one (so history doesn't get confused).
- **`hidden_by_default` is *not* `Zeroize`.** It's purely a UI hint — the
  rendering layer (CLI output, popup card) decides whether to mask the value
  on initial display. Secrecy at rest is enforced by the `Zeroizing` wrappers
  on the value itself, not this flag.
- **`Manifest::upsert` rebuilds the entry from scratch every call**
  (`manifest.rs:45-48`, `manifest.rs:75-89`). There is no "patch the
  existing entry" path. This means the manifest can never carry a stale
  `icon_hint` or `attachment_summaries` — they are derived freshly from the
  source `Item` each time.
- **The strength gate is *not* called inside `derive_master_key`.** It must
  be invoked separately by the caller during *vault creation* only — not
  during unlock, where calling it would let an attacker probe whether a
  wrong passphrase happens to be "strong enough" before the Argon2id work
  even starts. See `generators.rs:124-130`.
- **`now_unix()` is `chrono::Utc::now().timestamp()` and is the single time
  source in this crate** (`time.rs:6-8`). Tests that need determinism pass an
  explicit `now: i64` to `prune_history` (`item.rs:219`) and similar — they
  do not stub `now_unix`.