diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 297cf47..557b7ce 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -1,6 +1,6 @@ # Architecture overview — Relicario -This is the cross-codebase entry point. It describes how the three 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. +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: > @@ -10,44 +10,48 @@ This is the cross-codebase entry point. It describes how the three Relicario cod > > If you want historical *why*, see `docs/superpowers/specs/` — those are time-stamped decision artifacts. This overview describes what *is*. -## The three codebases +## The four codebases ``` - ┌─────────────────────┐ - │ relicario-core │ - │ (Rust, no I/O) │ - │ crypto · items │ - │ manifest · stego │ - └──────────┬──────────┘ - │ - ┌─────────────────────┼─────────────────────┐ - │ │ │ - ▼ ▼ ▼ - ┌────────────────┐ ┌────────────────────┐ (compiled to WASM - │ relicario-cli │ │ relicario-wasm │ inside the ) - │ (Rust binary) │ │ (#[wasm_bindgen] │ extension │ - │ │ │ bindings) │ │ - │ filesystem + │ │ │ │ - │ git + │ └────────┬───────────┘ │ - │ clap UX │ │ │ - └────────────────┘ ▼ │ - ┌─────────────────────┐ │ - │ extension │ │ - │ (TypeScript) │ │ - │ popup · vault │ │ - │ setup · content │ │ - │ service worker │ │ - └─────────────────────┘ + ┌─────────────────────┐ + │ relicario-core │ + │ (Rust, no I/O) │ + │ crypto · items │ + │ manifest · stego │ + │ device keys + fp │ + └──┬───────────┬──────┘ + │ │ + ┌────────────────┼───────────┴──────┬────────────────────┐ + │ │ │ │ + ▼ ▼ ▼ ▼ + ┌────────────────┐ ┌──────────────────┐ ┌────────────────────┐ + │ relicario-cli │ │ relicario-server │ │ relicario-wasm │ + │ (Rust binary) │ │ (Rust binary) │ │ (#[wasm_bindgen] │ + │ │ │ │ │ bindings) │ + │ filesystem + │ │ pre-receive hook │ │ │ + │ git + │ │ verify-commit + │ │ compiled to WASM │ + │ clap UX │ │ generate-hook │ │ for the extension │ + └────────────────┘ └──────────────────┘ └──────────┬─────────┘ + │ + ▼ + ┌─────────────────────┐ + │ extension │ + │ (TypeScript) │ + │ popup · vault │ + │ setup · content │ + │ service worker │ + └─────────────────────┘ ``` | Codebase | Language | Role | Key boundary | |---|---|---|---| -| `relicario-core` | Rust | Crypto, item types, manifest, attachments, imgsecret, generators. Pure, no I/O. | Only `bytes-in / bytes-out`. No filesystem, no git, no network. | +| `relicario-core` | Rust | Crypto, item types, manifest, attachments, imgsecret, generators, device keys / fingerprints. Pure, no I/O. | Only `bytes-in / bytes-out`. No filesystem, no git, no network. | | `relicario-cli` | Rust binary | Wraps core with filesystem ops, git plumbing, clap UX. | Only entry point that runs without a browser; sole working interface during disaster recovery. | | `relicario-wasm` | Rust → WASM | Thin `#[wasm_bindgen]` exports from core for the extension. | Compiles `relicario-core` to WASM; no extra logic. | +| `relicario-server` | Rust binary | Pre-receive Git hook (`verify-commit`) plus hook installer (`generate-hook`) running on the vault remote. Verifies SSH-signed commits against `.relicario/devices.json` and `.relicario/revoked.json`. | Lives on the git server, not on a client device. The only Relicario component the user does not run themselves. Sees only public key material. | | `extension` | TypeScript | Browser-resident UI. Five entry-point bundles (popup, vault tab, setup, content script, service worker). | The service worker is the only crypto holder; popup/vault/content/setup never touch the master key. | -The CLI and the extension are **at parity**: every user-facing capability lands in both surfaces together. Diverging is allowed only with a documented reason. See the per-codebase docs for which surface owns which user flow. +The CLI and the extension are **at parity**: every user-facing capability lands in both surfaces together. Diverging is allowed only with a documented reason. See the per-codebase docs for which surface owns which user flow. The server has no user-facing surface — it is a server-side enforcer of the device-auth invariant the clients already agreed to. ## Inter-codebase contracts @@ -151,6 +155,7 @@ The CLI keeps its master key in process memory; if the process exits or crashes, | Target | Tool | Output | When to run | |---|---|---|---| | Native CLI | `cargo build` (debug or `--release`) | `target/{debug,release}/relicario` | After CLI changes; for distribution | +| Server hook | `cargo build -p relicario-server --release` | `target/release/relicario-server` | After server changes; deploy onto the git remote | | Native test suites | `cargo test` (workspace) | — | After any Rust change | | WASM module | `wasm-pack build --target web` (via `npm run build:wasm`) | `extension/wasm/relicario_wasm{,_bg.wasm,.js}` | After core or wasm crate changes | | Chrome extension | `webpack` (`npm run build`) | `extension/dist/` | After TS or WASM changes; for Chrome distribution | @@ -196,6 +201,7 @@ Core tests use **fast Argon2id params** (m=256, t=1, p=1) so they don't take for | A new popup view, vault tab feature, or autofill change | [`extension/ARCHITECTURE.md`](../../extension/ARCHITECTURE.md) | | A new SW message type | `extension/src/shared/messages.ts` (capability sets), then [`extension/ARCHITECTURE.md § Invariants`](../../extension/ARCHITECTURE.md) | | A new GitHost (e.g. GitLab support) | `extension/src/service-worker/git-host.ts` (interface) and existing implementations | +| The pre-receive hook / device-auth enforcement | `crates/relicario-server/src/main.rs`, then `docs/superpowers/specs/2026-05-02-device-authentication-design.md` for rationale | | Adding a new item type | core's `item_types/` mod, then CLI's `build_*_item`/`edit_*` helpers, then extension's `popup/components/types/.ts` | | Threat model / why a primitive was chosen | `docs/superpowers/specs/2026-04-11-relicario-design.md` (historical, but authoritative for rationale) | | Format of the import/export feature | `docs/superpowers/specs/2026-04-27-relicario-import-export-design.md` (designed but not yet implemented) |