From 415d8ed9efe2a6bd8e6e873bcc8c8e60d3f859bb Mon Sep 17 00:00:00 2001 From: adlee-was-taken Date: Sat, 20 Jun 2026 22:00:29 -0400 Subject: [PATCH] docs(cli): document v0.8.1 org item-type parity surface in ARCHITECTURE.md - org.rs bullet: full Card/Key/Document/Totp org add/edit parity via the shared item_build builders + edit helpers; interactive per-type edit; --*-stdin secret convention; purge removes attachments. Replaces the stale 'Login/SecureNote/Identity only' + flag-driven-edit + deferred text. - org_session.rs bullet: collection-scoped attachment storage (attachment_path/ save/load/remove + DEFAULT_ORG_ATTACHMENT_MAX_BYTES). - main.rs bullet: OrgCommands + OrgAddKind clap surface. Source-line citations pinned per the code-constant-pinning discipline. --- crates/relicario-cli/ARCHITECTURE.md | 57 +++++++++++++++++++++------- 1 file changed, 43 insertions(+), 14 deletions(-) diff --git a/crates/relicario-cli/ARCHITECTURE.md b/crates/relicario-cli/ARCHITECTURE.md index 1259b00..ce79b7d 100644 --- a/crates/relicario-cli/ARCHITECTURE.md +++ b/crates/relicario-cli/ARCHITECTURE.md @@ -24,7 +24,10 @@ under `src/commands/`. Each source file has one job. - **`src/main.rs`** (`main.rs:1-492`) — clap surface and the flat dispatcher. Owns the top-level `Cli` / `Commands` enum and every subcommand enum (`AddKind`, `TrashAction`, `SettingsAction`, `BackupAction`, `ImportAction`, - `DeviceAction`, `RecoveryQrCmd`). `main()` is a single `match` that + `DeviceAction`, `RecoveryQrCmd`), plus the org clap surface `OrgCommands` + (`main.rs:448`) and `OrgAddKind` (`main.rs:556`) — the latter's Card / Key / + Document / Totp variants carry `--collection` and the `--*-stdin` secret flags. + `main()` is a single `match` that delegates each variant to `commands::::cmd_(...)`. Also owns the three test-only env-var hooks (`test_passphrase_override`, `test_item_secret_override`, `test_backup_passphrase_override`) — each is @@ -94,7 +97,14 @@ under `src/commands/`. Each source file has one job. (`items//.enc` — the leading slug is what the pre-receive hook authorizes against, never decrypting), fingerprint-based member matching (`relicario_core::fingerprint`, tolerant of OpenSSH whitespace/comment - differences), `atomic_write`, and `org_git_run`. Note `org_git_run` runs + differences), `atomic_write`, and `org_git_run`. As of v0.8.1 it also owns + **collection-scoped attachment storage** — `attachment_path` / + `save_attachment` / `load_attachment` / `remove_item_attachments` + (`org_session.rs:125-157`) at layout + `attachments///.enc` (the same leading slug + the pre-receive hook authorizes against as for `item_path`), capped + per-attachment by `DEFAULT_ORG_ATTACHMENT_MAX_BYTES` (10 MiB, + `org_session.rs:20`). Note `org_git_run` runs **bare git** — unlike `helpers::git_run` it does NOT inject `commit.gpgsign=false`, because org commits MUST be signed (the hook verifies every commit's signature); signing config is established by @@ -111,19 +121,38 @@ under `src/commands/`. Each source file has one job. concurrent-rotation abort), `transfer-ownership`, `delete-org`, `status` / `audit` (verified-signer attribution + `TAMPERED` flag). - *Item CRUD (7):* `org add` creates typed items via `OrgAddKind` - (`commands/org.rs:749`) — **Login / SecureNote / Identity only**; Card / - SshKey / Document / Totp creation is a deferred follow-up. `get` / `list` can - display any item type if present. `org get [--show]` masks secrets - unless `--show`; `org list [--trashed]` filters by the caller's collection - grants; `org edit ` is flag-driven (blank flags keep current values); - `org rm` soft-deletes, `org restore` undoes, `org purge` permanently removes - the encrypted blob. All item ops are collection-scoped and grant-enforced. The - audit trail emits `item-create` / `item-update` / `item-delete` / - `item-restore` / `item-purge`. + *Item CRUD (7):* full item-type parity with the personal vault (v0.8.1). + `org add` creates **all seven types** (Login / SecureNote / Identity / Card / + Key / Document / Totp) via `OrgAddKind` (`commands/org.rs:751`); each arm + delegates to the shared `item_build::build_*` builders through `build_org_item` + (`commands/org.rs:799`), and `run_add` (`commands/org.rs:823`) sets tags + post-build. Document is special-cased in `run_add` (`commands/org.rs:839`): its + builder also yields an `EncryptedAttachment` that is written via + `save_attachment` and git-staged before the signed commit. Single-line secrets + (card number/CVV/PIN, TOTP secret, login password) accept a `--*-stdin` flag; + multiline secrets (Key material, SecureNote body) read stdin to EOF — the same + `resolve_secret_line` / `resolve_secret_multiline` convention as personal `add` + (`commands/item_build.rs`). - Deferred: Card / SshKey / Document / Totp `org add` / `edit` parity; - extension org reads and writes (Dev-D). + `org edit ` (`run_edit`, `commands/org.rs:1004`) is **interactive + per-type** as of v0.8.1 (it was flag-driven before): it prompts Title, then + dispatches on `&mut item.core` to the shared `item_build::edit_*` helpers + ("blank keeps current", field-history capture via `push_history`), mirroring + personal `cmd_edit`. `--totp-qr` sets a Login TOTP from a QR image; `--file` + replaces a Document's primary attachment (`commands/org.rs:1039`, rejected for + non-Document items at `commands/org.rs:1018`). The edit commit carries + `Relicario-Action: item-update`. + + `org get [--show]` masks every secret unless `--show`; `org list + [--trashed]` filters by the caller's collection grants; `org rm` soft-deletes, + `org restore` undoes, `org purge` (`run_purge`, `commands/org.rs:1164`) + permanently removes the encrypted blob **and** the item's attachment directory + (`remove_item_attachments`, `commands/org.rs:1173`). All item ops are + collection-scoped and grant-enforced (`filter_for_member` over the manifest + + `ensure_grant` before any load/mutate). The audit trail emits `item-create` / + `item-update` / `item-delete` / `item-restore` / `item-purge`. + + Deferred: extension org reads and writes (Plan B-2 / phase 2). - **`src/helpers.rs`** (`helpers.rs:1-101`) — pure, no-state plumbing: `find_vault_dir_from` (`helpers.rs:14-28`) walks up parent directories