From 822547f3496f7ce0584d0716383d8365483808a9 Mon Sep 17 00:00:00 2001 From: adlee-was-taken Date: Sun, 12 Apr 2026 00:15:33 -0400 Subject: [PATCH] docs: add Task 0 for heavy Rust code documentation Adds a pre-implementation task to thoroughly document all existing Rust code in idfoto-core and idfoto-cli with doc comments explaining the crypto pipeline, steganography algorithm, and vault data model. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../plans/2026-04-12-idfoto-wasm-extension.md | 113 +++++++++++++++++- 1 file changed, 112 insertions(+), 1 deletion(-) diff --git a/docs/superpowers/plans/2026-04-12-idfoto-wasm-extension.md b/docs/superpowers/plans/2026-04-12-idfoto-wasm-extension.md index 5ffdfac..806994a 100644 --- a/docs/superpowers/plans/2026-04-12-idfoto-wasm-extension.md +++ b/docs/superpowers/plans/2026-04-12-idfoto-wasm-extension.md @@ -70,6 +70,116 @@ extension/ --- +## Task 0: Add Heavy Comments to Existing Rust Code + +**Files:** +- Modify: `crates/idfoto-core/src/lib.rs` +- Modify: `crates/idfoto-core/src/error.rs` +- Modify: `crates/idfoto-core/src/crypto.rs` +- Modify: `crates/idfoto-core/src/entry.rs` +- Modify: `crates/idfoto-core/src/vault.rs` +- Modify: `crates/idfoto-core/src/imgsecret.rs` +- Modify: `crates/idfoto-cli/src/main.rs` + +Add thorough documentation comments to all existing Rust code. Every public function, struct, field, constant, and non-trivial private function should have doc comments explaining what it does, why it exists, and any important constraints. Module-level docs should explain the module's role in the overall architecture. + +Guidelines: +- Use `///` for public items and `//` for inline explanations of non-obvious logic +- Explain the "why" not just the "what" — e.g., why XChaCha20 over AES-GCM, why mid-frequency DCT coefficients, why majority voting +- Reference the crypto pipeline and threat model from the design spec where relevant +- Document parameters, return values, and error conditions +- For `imgsecret.rs`, explain the steganography algorithm step by step — this is the novel component and should read like a tutorial +- For `crypto.rs`, document the binary format and why each field exists +- For `entry.rs`, document the vault data model and serialization strategy +- For `main.rs`, document the CLI flow and unlock sequence + +- [ ] **Step 1: Add module-level docs and comments to `lib.rs`** + +```rust +//! # idfoto-core +//! +//! Platform-agnostic core library for the idfoto password manager. +//! +//! This crate is deliberately bytes-in/bytes-out — no filesystem, no network, +//! no git operations. This makes it portable to WASM (browser extension), +//! Android (JNI), and iOS (Swift bridge) without modification. +//! +//! ## Modules +//! +//! - [`crypto`] — Argon2id key derivation + XChaCha20-Poly1305 authenticated encryption +//! - [`entry`] — Entry, ManifestEntry, and Manifest data structures +//! - [`vault`] — High-level encrypt/decrypt operations for entries and manifests +//! - [`imgsecret`] — DCT-based 256-bit secret embedding in JPEG images +//! - [`error`] — Error types for all operations +``` + +- [ ] **Step 2: Add comments to `error.rs`** + +Document each error variant with when it occurs and what the caller should do about it. + +- [ ] **Step 3: Add comments to `crypto.rs`** + +Document: +- The binary ciphertext format (version byte + nonce + ciphertext + tag) and why each field exists +- Why XChaCha20-Poly1305 was chosen over AES-GCM (192-bit nonce eliminates collision risk, fast in WASM/ARM without AES-NI) +- The KDF pipeline: how passphrase + image_secret are concatenated as the Argon2id password input +- KdfParams and why they're configurable (future parameter upgrades, different hardware profiles) +- Constants and their significance (VERSION_BYTE, NONCE_LEN, TAG_LEN, HEADER_LEN) + +- [ ] **Step 4: Add comments to `entry.rs`** + +Document: +- The vault data model: Entry (full credential), ManifestEntry (index metadata), Manifest (entry index) +- Why the manifest exists (decrypt one file to list/search entries without decrypting every entry) +- `skip_serializing_if` strategy for optional fields (backwards compatibility, compact JSON) +- Entry ID format (random 8-char hex, 32 bits — sufficient for family vault sizes) +- The search implementation and its case-insensitive substring matching + +- [ ] **Step 5: Add comments to `vault.rs`** + +Document: +- The relationship between vault.rs and crypto.rs (vault = typed wrappers around raw encrypt/decrypt) +- The serialization path: struct → JSON → encrypt → ciphertext bytes (and reverse) +- Why a single master_key is used for both entries and manifest (simpler, sufficient for family vault sizes) + +- [ ] **Step 6: Add comments to `imgsecret.rs`** + +This is the technically novel component. Document heavily: +- Module-level doc explaining the DCT steganography approach and why it was chosen +- Constants: BLOCK_SIZE, QUANT_STEP (why 50.0 — higher than typical 25 to survive JPEG recompression), MIN_DIMENSION, SECRET_BITS, MIN_COPIES, BLOCKS_PER_COPY, EMBED_POSITIONS (mid-frequency DCT coefficients in zig-zag order) +- YChannel: what it represents, why only luminance (survives re-encoding best, Cb/Cr often subsampled) +- EmbedRegion: the central 70% concept, the 15% crumple zone for crop tolerance +- DCT functions: what DCT is, why 8x8 blocks (matches JPEG's own block size), the 2D DCT as row-then-column 1D DCTs +- QIM (Quantization Index Modulation): how it encodes bits by rounding to quantization grids, why it's robust to re-quantization +- The embedding process step by step: decode → extract Y → define region → block DCT → select blocks → encode with redundancy → QIM embed → reconstruct +- The extraction process: canonical try → crop recovery search → majority voting with confidence threshold +- Bit conversion helpers +- Block selection strategy (evenly spaced, fixed geometric pattern) +- The reconstruct_jpeg function and the YCbCr ↔ RGB color space conversion + +- [ ] **Step 7: Add comments to `main.rs` (CLI)** + +Document: +- Module-level doc explaining this is the platform layer (filesystem, git, terminal I/O) +- The unlock flow: passphrase prompt → read reference image → extract image_secret → read salt/params → derive master_key +- Each CLI command's purpose and flow +- Helper functions: why git_commit uses `git add -A`, why generate_password uses OsRng, why now_iso8601 uses UNIX epoch seconds +- Device management: ed25519 key generation, why device keys are separate from the KDF + +- [ ] **Step 8: Run tests to verify comments didn't break anything** + +Run: `cargo test` +Expected: All tests pass unchanged. + +- [ ] **Step 9: Commit** + +```bash +git add crates/idfoto-core/src/ crates/idfoto-cli/src/main.rs +git commit -m "docs: add heavy documentation comments to all Rust code" +``` + +--- + ## Task 1: Add `group` Field to Core Data Model **Files:** @@ -3164,7 +3274,8 @@ git commit -m "feat: complete WASM + Chrome MV3 extension build" | Task | Description | Dependencies | |------|-------------|--------------| -| 1 | Add `group` field to core data model | None | +| 0 | Add heavy comments to existing Rust code | None | +| 1 | Add `group` field to core data model | Task 0 | | 2 | Create `idfoto-wasm` crate | Task 1 | | 3 | Extension scaffolding | Task 2 | | 4 | Shared types and messages | Task 3 |