diff --git a/DESIGN.md b/DESIGN.md index 45e0720..b0759cc 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,5 +1,7 @@ # Architecture overview — Relicario +> **Audience:** anyone wanting to understand the system at the cross-codebase level. This doc owns the four-codebase map, inter-codebase contracts, the secrets map (what secret lives where), the build matrix, and the global code-map index. **Does NOT own:** crypto pipeline details (see [docs/CRYPTO.md](docs/CRYPTO.md)), wire formats (see [docs/FORMATS.md](docs/FORMATS.md)), threat model (see [docs/SECURITY.md](docs/SECURITY.md)), per-crate module maps (see [crates/relicario-core/ARCHITECTURE.md](crates/relicario-core/ARCHITECTURE.md), [crates/relicario-cli/ARCHITECTURE.md](crates/relicario-cli/ARCHITECTURE.md), and [extension/ARCHITECTURE.md](extension/ARCHITECTURE.md)). + This is the cross-codebase entry point. It describes how the four Relicario codebases fit together, the contracts that flow between them, and the conventions they share. It is **deliberately thin**; the deep content lives in per-codebase docs. > If you are about to make a change in a single codebase, read its `ARCHITECTURE.md` first: @@ -211,3 +213,7 @@ Core tests use **fast Argon2id params** (m=256, t=1, p=1) so they don't take for ## Stale spec docs The `docs/superpowers/specs/` tree is **historical** — it captures the design decisions made at planning time. Some specs (e.g. `Plan 1A`, `1B`, `1C-α`/`β`/`γ`) describe work that has shipped. Do not edit them as if they were the architecture docs; instead update the appropriate `ARCHITECTURE.md`. The specs are valuable for *why* (why XChaCha20-Poly1305, why central-embed DCT, why two-factor with steganography); the architecture docs are valuable for *what* (current invariants, current flows, current contracts). + +--- + +**Next:** [docs/CRYPTO.md](docs/CRYPTO.md) — the crypto pipeline that backs this design. diff --git a/README.md b/README.md index 6e0dfd5..8686b01 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ # Relicario +> **Audience:** users + evaluators. This doc owns the pitch, security-model summary, quick-start commands, reference-image explanation, recovery-QR overview, and roadmap teaser. Goes no deeper — for the system tour see [DESIGN.md](DESIGN.md), for crypto see [docs/CRYPTO.md](docs/CRYPTO.md). + A git-backed, self-hostable password manager where decryption requires two independent factors: a passphrase you memorize and a reference JPEG that carries a hidden secret. Compromise of either factor alone is insufficient. The server only ever sees opaque ciphertext. There is nothing else going on. This README is the security proof. @@ -135,34 +137,9 @@ Recommended practice: print the QR, store it offline (safe, deposit box), and fo ## Architecture -``` -relicario/ -├── crates/ -│ ├── relicario-core/ # Platform-agnostic library (no filesystem, no network) -│ │ ├── crypto.rs # Argon2id KDF + XChaCha20-Poly1305 AEAD -│ │ ├── imgsecret.rs # DCT steganography: embed/extract 256-bit secrets in JPEGs -│ │ ├── item.rs # Item, Field, Manifest data model (serde) -│ │ ├── item_types/ # Per-type cores (Login, SecureNote, Card, Identity, Key, Document, Totp) -│ │ ├── attachment.rs # Encrypted attachment helpers (content-addressed) -│ │ ├── settings.rs # VaultSettings (retention, generator defaults, caps) -│ │ ├── backup.rs # `.relbak` encrypted-backup envelope -│ │ ├── 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 -│ ├── relicario-cli/ # CLI binary: filesystem, git, terminal I/O -│ ├── relicario-wasm/ # Thin wasm-bindgen wrapper for the browser extension -│ └── relicario-server/ # Pre-receive hook: device-signature verification -├── extension/ # Chrome MV3 / Firefox WebExtension (TypeScript) -└── docs/ - ├── ARCHITECTURE.md # System overview + flow diagrams - ├── SECURITY.md # Manifest integrity model + threat notes - ├── architecture/ # Cross-codebase + per-codebase architecture docs - └── superpowers/ - └── specs/ # Design specifications with full threat model -``` +A short tour of the four codebases and how they fit together lives in [DESIGN.md](DESIGN.md). Crypto pipeline diagrams are in [docs/CRYPTO.md](docs/CRYPTO.md); the wire format reference is [docs/FORMATS.md](docs/FORMATS.md); the threat model is [docs/SECURITY.md](docs/SECURITY.md). -`relicario-core` takes bytes and returns bytes. It has no knowledge of filesystems, git, or networks. This makes it portable to WASM (browser extension), Android (JNI), and iOS (Swift bridge). +`relicario-core` is the platform-agnostic bytes-in/bytes-out heart — no filesystem, no network. The CLI binary and the browser-extension WASM bridge both consume it. See per-codebase deep-dives in `crates/*/ARCHITECTURE.md` and `extension/ARCHITECTURE.md`. ### Crypto primitives @@ -248,3 +225,7 @@ GPL-3.0-or-later — see [LICENSE](LICENSE). --- Built by [Aaron D. Lee](https://adlee.work). Design spec and threat model in `docs/superpowers/specs/`. + +--- + +**Next:** [DESIGN.md](DESIGN.md) — the system tour. diff --git a/crates/relicario-cli/ARCHITECTURE.md b/crates/relicario-cli/ARCHITECTURE.md index c3662a6..d1770ff 100644 --- a/crates/relicario-cli/ARCHITECTURE.md +++ b/crates/relicario-cli/ARCHITECTURE.md @@ -1,5 +1,7 @@ # Architecture: relicario-cli +> **Audience:** contributors editing the CLI. This doc owns the CLI module map, the clap command surface, per-command key flows, session/unlock semantics, and helpers. **Does NOT own:** crypto, wire formats, or threat model (see [../../docs/CRYPTO.md](../../docs/CRYPTO.md), [../../docs/FORMATS.md](../../docs/FORMATS.md), [../../docs/SECURITY.md](../../docs/SECURITY.md)). + ## What this crate is for The `relicario` binary is the platform layer for `relicario-core`: it adds @@ -613,3 +615,7 @@ applies to `relicario-core` unit tests, not these CLI integration tests. is why every `cmd_*` that takes a `query: String` (get, edit, history, rm, restore, purge, attach, attachments, extract, detach) works the same way. + +--- + +**Next:** [../../extension/ARCHITECTURE.md](../../extension/ARCHITECTURE.md) — the browser-side surface. diff --git a/crates/relicario-core/ARCHITECTURE.md b/crates/relicario-core/ARCHITECTURE.md index 193c3de..dc3c3da 100644 --- a/crates/relicario-core/ARCHITECTURE.md +++ b/crates/relicario-core/ARCHITECTURE.md @@ -1,5 +1,7 @@ # Architecture: relicario-core +> **Audience:** contributors editing or extending `relicario-core`. This doc owns the module map for this crate, module-level invariants (e.g., no filesystem, no network), key flows at the module level, and the crate's test architecture. **Does NOT own:** crypto primitives or threat model (see [../../docs/CRYPTO.md](../../docs/CRYPTO.md), [../../docs/SECURITY.md](../../docs/SECURITY.md)), wire formats (see [../../docs/FORMATS.md](../../docs/FORMATS.md)). + ## What this crate is for `relicario-core` is the platform-agnostic cryptographic and data-model heart of the @@ -544,3 +546,7 @@ round-trip, and the oversized-image-header rejection path. 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`. + +--- + +**Next:** [../relicario-cli/ARCHITECTURE.md](../relicario-cli/ARCHITECTURE.md) — how the CLI wraps the core. diff --git a/docs/CRYPTO.md b/docs/CRYPTO.md index b972fb5..04bac34 100644 --- a/docs/CRYPTO.md +++ b/docs/CRYPTO.md @@ -1,4 +1,6 @@ -# Relicario — Architecture +# Relicario — Crypto Pipeline + +> **Audience:** anyone evaluating or auditing the crypto. This doc owns Argon2id parameters and rationale, XChaCha20-Poly1305 rationale, vault creation/unlock flow diagrams, DCT-steganography embed and extract flows, and the high-level encrypted-file-format diagram. **Does NOT own:** byte-level schemas or JSON shapes (see [FORMATS.md](FORMATS.md)), attacker scenarios (see [SECURITY.md](SECURITY.md)), or per-module crypto implementation (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)). ## System Overview @@ -274,3 +276,7 @@ Stolen device: ████░░░░░░░░░░░░░ Both factors compromised: game over (same as every password manager) ``` + +--- + +**Next:** [FORMATS.md](FORMATS.md) — the byte-level wire formats. diff --git a/docs/FORMATS.md b/docs/FORMATS.md index 94d6373..74c851b 100644 --- a/docs/FORMATS.md +++ b/docs/FORMATS.md @@ -1,5 +1,7 @@ # Relicario Wire Formats +> **Audience:** anyone implementing a compatible client or reading raw vault bytes. This doc owns the `.enc` blob layout, `params.json` / `salt` / `devices.json` / `revoked.json` shapes, the manifest JSON schema, the `.relbak` envelope, item-ID formats, and the settings JSON schema. **Does NOT own:** why these formats look this way (see [CRYPTO.md](CRYPTO.md)), threat model around them (see [SECURITY.md](SECURITY.md)), or Rust struct internals (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)). + > Quick-reference for the load-bearing binary and JSON formats. Check this file before touching serialization, versioning, or storage layout code. Full diagrams and invariants live in the per-crate `ARCHITECTURE.md` files. ## Encrypted blob (`.enc` files) @@ -100,3 +102,7 @@ u64_be(len(passphrase)) || passphrase_bytes || u64_be(32) || image_secret ``` NFC-normalized before hashing. Covered in `crypto.rs:229-236` and tested in `tests/format_v2.rs:44-54`. + +--- + +**Next:** [SECURITY.md](SECURITY.md) — the threat model. diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 8676e9f..4899e35 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -1,5 +1,7 @@ # Relicario Security Model +> **Audience:** auditors and curious users. This doc owns the threat model, attacker-scenarios table, device-authentication model, env-var trust surface, and known limitations. **Does NOT own:** crypto primitive details (see [CRYPTO.md](CRYPTO.md)), wire formats (see [FORMATS.md](FORMATS.md)), or implementation (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md) and [../crates/relicario-cli/ARCHITECTURE.md](../crates/relicario-cli/ARCHITECTURE.md)). + ## Cryptographic Protection Relicario uses two-factor vault decryption: @@ -102,3 +104,7 @@ standard `--release` profile). | `RELICARIO_TEST_PASSPHRASE` | Bypass the `rpassword` prompt during integration tests. | | `RELICARIO_TEST_ITEM_SECRET` | Bypass the `rpassword` prompt for item-secret fields during integration tests. | | `RELICARIO_TEST_BACKUP_PASSPHRASE` | Bypass the `rpassword` prompt for backup export/restore passphrases during integration tests. | + +--- + +**Next:** [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md) — implementation, starting with the platform-agnostic core. diff --git a/extension/ARCHITECTURE.md b/extension/ARCHITECTURE.md index ded0478..152e354 100644 --- a/extension/ARCHITECTURE.md +++ b/extension/ARCHITECTURE.md @@ -1,10 +1,6 @@ # Architecture: relicario extension -> Strategic-depth doc for the `extension/` codebase. Pairs with `/CLAUDE.md` -> at the repo root (project-level summary) and the typed-items design spec -> under `docs/superpowers/specs/`. Things that are easy to recover from -> reading code are deliberately omitted; things that are not — invariants, -> multi-file control flow, design rationale — go here. +> **Audience:** contributors editing the browser extension. This doc owns the bundle structure (popup, vault tab, background SW, content scripts), the SW ↔ popup message contract, the component / pane architecture, routing, and the build pipeline. **Does NOT own:** WASM crypto internals (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)), wire formats (see [../docs/FORMATS.md](../docs/FORMATS.md)), or threat model (see [../docs/SECURITY.md](../docs/SECURITY.md)). ## What this codebase is for @@ -870,3 +866,7 @@ still required before shipping. next to `relicario_wasm_bg.wasm`. The runtime calls `WebAssembly.instantiateStreaming(fetch(URL))` against a hardcoded path; we just hand it that path. + +--- + +**End of tour.** For roadmap and in-flight work see [../STATUS.md](../STATUS.md) and [../ROADMAP.md](../ROADMAP.md).