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) <noreply@anthropic.com>
This commit is contained in:
adlee-was-taken
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user