docs: add scope headers + Next: footers to all tour docs
Each of the eight tour docs (README, DESIGN, docs/CRYPTO, docs/FORMATS, docs/SECURITY, crates/relicario-core/ARCHITECTURE, crates/relicario-cli/ARCHITECTURE, extension/ARCHITECTURE) now declares its scope in a blockquote under its H1 and ends with a single-line "Next:" pointer to the next doc in the canonical reading order: README → DESIGN → CRYPTO → FORMATS → SECURITY → core → cli → extension. Also trimmed README's mid-section "Architecture" stub to a one- paragraph pointer at DESIGN.md (was duplicating cross-codebase content and referencing a non-existent docs/architecture/ tree). Renamed docs/CRYPTO.md's H1 from "Relicario — Architecture" to "Relicario — Crypto Pipeline" to match the file's renamed scope. Spec: docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md
This commit is contained in:
adlee-was-taken
@@ -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.
|
||||
|
||||
35
README.md
35
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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user