docs: add comprehensive doc comments to all Rust source files

Document every public function, struct, field, constant, and non-trivial
private function across idfoto-core and idfoto-cli. Module-level docs
explain each module's role in the architecture. Comments explain the "why"
(crypto choices, algorithm design, data model rationale) not just the "what".

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

crates/idfoto-core/src/vault.rs

@@ -1,23 +1,72 @@
+//! Typed encryption/decryption wrappers for vault entries and manifests.
+//!
+//! This module bridges the gap between the raw bytes-in/bytes-out layer in
+//! [`crate::crypto`] and the typed data model in [`crate::entry`]. Each function
+//! follows the same pattern:
+//!
+//! - **Encrypt**: serialize the struct to JSON via serde, then encrypt the JSON
+//!   bytes with [`crate::crypto::encrypt`].
+//! - **Decrypt**: decrypt the ciphertext with [`crate::crypto::decrypt`], then
+//!   deserialize the resulting JSON bytes back into the typed struct.
+//!
+//! ## Why a single master key
+//!
+//! All entries and the manifest are encrypted under the same `master_key`. This is
+//! simpler than a per-entry subkey hierarchy and sufficient for family-scale vaults
+//! (typically < 1000 entries). The security properties are equivalent: an attacker
+//! who compromises the master key can decrypt everything regardless of whether
+//! subkeys exist, and the vault's threat model already assumes the master key is
+//! the single point of trust (protected by the two-factor KDF).
+
 use crate::crypto;
 use crate::entry::{Entry, Manifest};
 use crate::error::Result;
 
+/// Serialize an [`Entry`] to JSON and encrypt it under the master key.
+///
+/// The resulting bytes are written to `entries/<id>.enc` by the CLI.
+///
+/// # Errors
+///
+/// - [`crate::IdfotoError::Json`] if JSON serialization fails (should not happen
+///   with well-formed Entry structs).
+/// - [`crate::IdfotoError::Encrypt`] if the underlying AEAD operation fails.
 pub fn encrypt_entry(master_key: &[u8; 32], entry: &Entry) -> Result<Vec<u8>> {
     let json = serde_json::to_vec(entry)?;
     crypto::encrypt(master_key, &json)
 }
 
+/// Decrypt an entry blob and deserialize it back into an [`Entry`].
+///
+/// # Errors
+///
+/// - [`crate::IdfotoError::Decrypt`] if the master key is wrong or the data is
+///   tampered.
+/// - [`crate::IdfotoError::Format`] if the ciphertext blob has an invalid header.
+/// - [`crate::IdfotoError::Json`] if the decrypted JSON is malformed.
 pub fn decrypt_entry(master_key: &[u8; 32], data: &[u8]) -> Result<Entry> {
     let json = crypto::decrypt(master_key, data)?;
     let entry: Entry = serde_json::from_slice(&json)?;
     Ok(entry)
 }
 
+/// Serialize a [`Manifest`] to JSON and encrypt it under the master key.
+///
+/// The resulting bytes are written to `manifest.enc` by the CLI.
+///
+/// # Errors
+///
+/// Same as [`encrypt_entry`].
 pub fn encrypt_manifest(master_key: &[u8; 32], manifest: &Manifest) -> Result<Vec<u8>> {
     let json = serde_json::to_vec(manifest)?;
     crypto::encrypt(master_key, &json)
 }
 
+/// Decrypt a manifest blob and deserialize it back into a [`Manifest`].
+///
+/// # Errors
+///
+/// Same as [`decrypt_entry`].
 pub fn decrypt_manifest(master_key: &[u8; 32], data: &[u8]) -> Result<Manifest> {
     let json = crypto::decrypt(master_key, data)?;
     let manifest: Manifest = serde_json::from_slice(&json)?;