add missing docs

Author: lonerapier

README.md

@@ -115,32 +115,30 @@ cargo run --bin uniffi-bindgen generate --library target/debug/libmfkdf2.dylib -
 ## Usage
 
 ```rust
-use std::collections::HashMap;
+# use std::collections::HashMap;
 use mfkdf2::{derive, setup};
 use mfkdf2::setup::{factors::hotp::HOTPOptions, password::PasswordOptions, key::MFKDF2Options};
 use mfkdf2::derive::factors::{hotp::HOTPOptions, password::PasswordOptions};
 
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    // 1. Define factors
-    let password_factor = setup::password("my-super-secret-password", PasswordOptions::default())?;
-    let totp_factor = setup::hotp("base32-encoded-secret", HOTPOptions::default())?;
+// 1. Define factors
+let password_factor = setup::password("my-super-secret-password", PasswordOptions::default())?;
+let totp_factor = setup::hotp("base32-encoded-secret", HOTPOptions::default())?;
 
-    // 2. Set up the key with the policy
-    let key = setup::key(vec![password_factor, totp_factor], MFKDF2Options::default())?;
+// 2. Set up the key with the policy
+let key = setup::key(vec![password_factor, totp_factor], MFKDF2Options::default())?;
 
-    println!("Key: {:?}", key);
+println!("Key: {:?}", key);
 
-    let factors = HashMap::from([
-      ("password".to_string(), derive::factors::password("my-super-secret-password")?),
-      "hotp".to_string(), derive::factors::hotp("123456")?),
-    ]);
-    // 3. Derive the key using user inputs
-    let derived_key = derive::key(&key.policy, factors, true, false)?;
+let factors = HashMap::from([
+  ("password".to_string(), derive::factors::password("my-super-secret-password")?),
+  "hotp".to_string(), derive::factors::hotp("123456")?),
+]);
+// 3. Derive the key using user inputs
+let derived_key = derive::key(&key.policy, factors, true, false)?;
 
-    println!("Derived Key: {:?}", derived_key);
+println!("Derived Key: {:?}", derived_key);
 
-    Ok(())
-}
+# Ok::<(), mfkdf2::error::MFKDF2Error>(())
 ```
 
 ## Development

mfkdf2/src/constants.rs

@@ -1,2 +1,4 @@
+//! Constants for MFKDF2.
+
 /// Irreducible polynomial used in the secret sharing scheme: x⁸ + x⁴ + x³ + x + 1
 pub const SECRET_SHARING_POLY: u16 = 0x11B;

mfkdf2/src/crypto.rs

@@ -8,15 +8,15 @@ use sha1::Sha1;
 use sha2::Sha256;
 
 /// Derives a 32-byte key using HKDF-SHA256 with the given salt and info.
-pub fn hkdf_sha256_with_info(input: &[u8], salt: &[u8], info: &[u8]) -> [u8; 32] {
+pub(crate) fn hkdf_sha256_with_info(input: &[u8], salt: &[u8], info: &[u8]) -> [u8; 32] {
   let hk = Hkdf::<Sha256>::new(Some(salt), input);
   let mut okm = [0u8; 32];
   hk.expand(info, &mut okm).expect("HKDF expand");
   okm
 }
 
 /// Encrypts a buffer using AES256-ECB with the given 32-byte key.
-pub fn encrypt(data: &[u8], key: &[u8; 32]) -> Vec<u8> {
+pub(crate) fn encrypt(data: &[u8], key: &[u8; 32]) -> Vec<u8> {
   // Ensure the input is a multiple of 16 by zero-padding if necessary.
   let mut buf = {
     let mut v = data.to_vec();
@@ -35,21 +35,21 @@ pub fn encrypt(data: &[u8], key: &[u8; 32]) -> Vec<u8> {
 
 /// Decrypts a buffer using AES256-ECB with the given 32-byte key.
 // TODO (@lonerapier): check every use of decrypt and unpad properly or use assert.
-pub fn decrypt(mut data: Vec<u8>, key: &[u8; 32]) -> Vec<u8> {
+pub(crate) fn decrypt(mut data: Vec<u8>, key: &[u8; 32]) -> Vec<u8> {
   let cipher = Decryptor::<Aes256>::new_from_slice(key).expect("Invalid AES key");
   let _ = cipher.decrypt_padded_mut::<NoPadding>(&mut data).expect("ECB decrypt");
   data
 }
 
 /// Computes an HMAC-SHA1 over the given challenge using the provided secret.
-pub fn hmacsha1(secret: &[u8], challenge: &[u8]) -> [u8; 20] {
+pub(crate) fn hmacsha1(secret: &[u8], challenge: &[u8]) -> [u8; 20] {
   let mut mac = <Hmac<Sha1> as Mac>::new_from_slice(secret).unwrap();
   mac.update(challenge);
   mac.finalize().into_bytes().into()
 }
 
 /// Computes an HMAC-SHA256 over the given input using the provided secret.
-pub fn hmacsha256(secret: &[u8], input: &[u8]) -> [u8; 32] {
+pub(crate) fn hmacsha256(secret: &[u8], input: &[u8]) -> [u8; 32] {
   let mut mac = <Hmac<Sha256> as Mac>::new_from_slice(secret).unwrap();
   mac.update(input);
   mac.finalize().into_bytes().into()

mfkdf2/src/definitions/factor.rs

@@ -1,3 +1,10 @@
+//! # MFKDF2 Factor
+//!
+//!  A Factor represents an authentication primitive. Each factor has:
+//!
+//! - **Factor material**: the secret input (e.g., a password, TOTP secret, hardware key seed)
+//! - **Public state**: non-secret metadata the factor needs to operate (e.g., counters,
+//!   identifiers)
 use serde::{Deserialize, Serialize};
 
 use crate::setup::factors::{hmacsha1, hotp, ooba, passkey, password, question, stack, totp, uuid};
@@ -67,8 +74,10 @@ pub struct MFKDF2Factor {
 }
 
 impl MFKDF2Factor {
+  /// Returns the type of the factor.
   pub fn kind(&self) -> String { self.factor_type.kind() }
 
+  /// Returns the bytes of the factor material.
   pub fn data(&self) -> Vec<u8> { self.factor_type.bytes() }
 }
 
@@ -94,15 +103,25 @@ impl std::fmt::Debug for MFKDF2Factor {
 #[cfg_attr(feature = "bindings", derive(uniffi::Enum))]
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub enum FactorType {
+  /// [`password::Password`] factor.
   Password(password::Password),
+  /// [`hotp::HOTP`] factor.
   HOTP(hotp::HOTP),
+  /// [`question::Question`] factor.
   Question(question::Question),
+  /// [`uuid::UUIDFactor`] factor.
   UUID(uuid::UUIDFactor),
+  /// [`hmacsha1::HmacSha1`] factor.
   HmacSha1(hmacsha1::HmacSha1),
+  /// [`totp::TOTP`] factor.
   TOTP(totp::TOTP),
+  /// [`ooba::Ooba`] factor.
   OOBA(ooba::Ooba),
+  /// [`passkey::Passkey`] factor.
   Passkey(passkey::Passkey),
+  /// [`stack::Stack`] factor.
   Stack(stack::Stack),
+  /// [Persisted](`crate::derive::factors::persisted::Persisted`) factor.
   Persisted(crate::derive::factors::persisted::Persisted),
 }
 

mfkdf2/src/definitions/mfkdf_derived_key/hints.rs

@@ -97,15 +97,13 @@ impl MFKDF2DerivedKey {
   ///
   /// use mfkdf2::{
   ///   definitions::MFKDF2Options,
-  ///   derive::{self, factors::password as derive_password},
+  ///   derive,
   ///   error::MFKDF2Error,
   ///   setup::{
   ///     self,
   ///     factors::{password, password::PasswordOptions},
   ///   },
   /// };
-  ///
-  /// # fn main() -> Result<(), MFKDF2Error> {
   /// // Create a policy with a single password factor.
   /// let mut setup_key = setup::key(
   ///   &[password("correct horse battery staple", PasswordOptions {
@@ -125,14 +123,16 @@ impl MFKDF2DerivedKey {
   /// // hints and return `MFKDF2Error::HintMismatch` if they do not match.
   /// let derived_key = derive::key(
   ///   &setup_key.policy,
-  ///   HashMap::from([("password1".to_string(), derive_password("correct horse battery staple")?)]),
+  ///   HashMap::from([(
+  ///     "password1".to_string(),
+  ///     derive::factors::password("correct horse battery staple")?,
+  ///   )]),
   ///   true,  // integrity
   ///   false, // allow_partial
   /// )?;
   ///
   /// assert_eq!(derived_key.key, setup_key.key);
-  /// # Ok(())
-  /// # }
+  /// # Ok::<(), mfkdf2::error::MFKDF2Error>(())
   /// ```
   pub fn add_hint(&mut self, factor_id: &str, bits: Option<u8>) -> Result<(), MFKDF2Error> {
     let bits = bits.unwrap_or(7);

mfkdf2/src/definitions/mfkdf_derived_key/mod.rs

@@ -1,3 +1,14 @@
+//! # MFKDF2 Derived Key
+//!
+//! The security properties of MFKDF allow the derived key to itself be used to authenticate end
+//! users and implicitly verify all of their authentication factors. Because a properly-configured
+//! MFKDF key (`K`) cannot feasibly be derived without the presentation of all constituent factors,
+//! verifying a user’s derivation of `K` effectively constitutes verification of all factors.
+//!
+//! In practice, this means `MFKDF2DerivedKey` can safely serve as a high-entropy application root
+//! key, while the embedded [`Policy`] and threshold secret-sharing scheme enable flexible recovery
+//! flows (such as `t`‑of‑`n` factor policies) without weakening the guarantees provided by the
+//! underlying multi-factor construction.
 use std::collections::HashMap;
 
 use base64::engine::general_purpose;

mfkdf2/src/definitions/mfkdf_derived_key/persistence.rs

@@ -14,12 +14,10 @@ impl crate::definitions::MFKDF2DerivedKey {
   ///     factors::{password, password::PasswordOptions},
   ///   },
   /// };
-  /// # fn main() -> Result<(), MFKDF2Error> {
   /// let setup_key =
   ///   setup::key(&[password("password", PasswordOptions::default())?], MFKDF2Options::default())?;
   /// let share = setup_key.persist_factor("password");
-  /// #   Ok(())
-  /// # }
+  /// #   Ok::<(), mfkdf2::error::MFKDF2Error>(())
   /// ```
   pub fn persist_factor(&self, id: &str) -> Vec<u8> {
     let index = self.policy.factors.iter().position(|f| f.id == id).unwrap();

mfkdf2/src/derive/factors/hmacsha1.rs

@@ -91,18 +91,16 @@ impl FactorDerive for HmacSha1 {
 /// #   error::MFKDF2Result,
 /// #   setup::{
 /// #     self,
-/// #     factors::hmacsha1::{HmacSha1Options, hmacsha1 as setup_hmacsha1},
+/// #     factors::hmacsha1::{HmacSha1Options},
 /// #   },
 /// #   definitions::MFKDF2Options,
 /// #   derive,
 /// # };
 /// # use hmac::{Mac, Hmac};
 /// # use sha1::Sha1;
 /// # const HMACSHA1_SECRET: [u8; 20] = [0x11; 20];
-/// #
-/// # fn main() -> MFKDF2Result<()> {
 /// // KeySetup: build a policy with a single HMAC‑SHA1 factor
-/// let setup_factor = setup_hmacsha1(HmacSha1Options {
+/// let setup_factor = setup::factors::hmacsha1(HmacSha1Options {
 ///   secret: Some(HMACSHA1_SECRET.to_vec()),
 ///   ..Default::default()
 /// })?;
@@ -122,7 +120,7 @@ impl FactorDerive for HmacSha1 {
 ///   .into();
 ///
 /// // Build the derive‑time HMAC witness and run KeyDerive
-/// let derive_factor = crate::derive::factors::hmacsha1(response.into())?;
+/// let derive_factor = derive::factors::hmacsha1(response.into())?;
 /// let derived_key = derive::key(
 ///   &setup_key.policy,
 ///   HashMap::from([("hmacsha1".to_string(), derive_factor)]),
@@ -131,8 +129,7 @@ impl FactorDerive for HmacSha1 {
 /// )?;
 ///
 /// assert_eq!(derived_key.key, setup_key.key);
-/// # Ok(())
-/// # }
+/// # Ok::<(), mfkdf2::error::MFKDF2Error>(())
 /// ```
 pub fn hmacsha1(response: HmacSha1Response) -> MFKDF2Result<MFKDF2Factor> {
   Ok(MFKDF2Factor {

mfkdf2/src/derive/factors/hotp.rs

@@ -92,13 +92,11 @@ impl FactorDerive for HOTP {
 /// #   otpauth::HashAlgorithm,
 /// #   setup::{
 /// #     self,
-/// #     factors::hotp::{HOTPOptions, hotp as setup_hotp},
+/// #     factors::hotp::{HOTPOptions},
 /// #   },
 /// #   definitions::MFKDF2Options,
 /// #   derive,
 /// # };
-/// #
-/// # fn main() -> MFKDF2Result<()> {
 /// let secret = b"hello world mfkdf2!!".to_vec();
 /// let options = HOTPOptions {
 ///   id: Some("hotp".to_string()),
@@ -108,7 +106,7 @@ impl FactorDerive for HOTP {
 ///   ..Default::default()
 /// };
 ///
-/// let setup_factor = setup_hotp(options)?;
+/// let setup_factor = setup::factors::hotp(options)?;
 /// let hotp = if let mfkdf2::definitions::FactorType::HOTP(ref h) = setup_factor.factor_type {
 ///   h.clone()
 /// } else {
@@ -126,7 +124,7 @@ impl FactorDerive for HOTP {
 ///   hotp.config.digits,
 /// );
 ///
-/// let derive_factor = crate::derive::factors::hotp(code)?;
+/// let derive_factor = derive::factors::hotp(code)?;
 /// let derived_key = derive::key(
 ///   &setup_key.policy,
 ///   HashMap::from([("hotp".to_string(), derive_factor)]),
@@ -135,8 +133,7 @@ impl FactorDerive for HOTP {
 /// )?;
 ///
 /// assert_eq!(derived_key.key, setup_key.key);
-/// # Ok(())
-/// # }
+/// # Ok::<(), mfkdf2::error::MFKDF2Error>(())
 /// ```
 pub fn hotp(code: u32) -> MFKDF2Result<MFKDF2Factor> {
   // Create HOTP factor with the user-provided code

mfkdf2/src/derive/factors/ooba.rs

@@ -103,17 +103,12 @@ impl FactorDerive for Ooba {
 /// #   error::MFKDF2Result,
 /// #   setup::{
 /// #     self,
-/// #     factors::ooba::{ooba as setup_ooba, OobaOptions},
+/// #     factors::ooba::{OobaOptions},
 /// #   },
 /// #   definitions::MFKDF2Options,
 /// #   derive,
-/// #   derive::factors::ooba as derive_ooba,
 /// # };
 /// # use base64::Engine;
-/// # use sha2::Sha256;
-/// # use rsa::Oaep;
-/// #
-/// # fn main() -> MFKDF2Result<()> {
 /// let bits = 2048;
 /// let private_key =
 ///   RsaPrivateKey::new(&mut rsa::rand_core::OsRng, bits).expect("failed to generate a key");
@@ -128,7 +123,7 @@ impl FactorDerive for Ooba {
 ///   "e": e
 /// }))?;
 ///
-/// let setup_factor = setup_ooba(OobaOptions {
+/// let setup_factor = setup::factors::ooba(OobaOptions {
 ///   id:     Some("ooba".into()),
 ///   length: Some(8),
 ///   key:    Some(jwk),
@@ -141,11 +136,11 @@ impl FactorDerive for Ooba {
 ///   setup_key.policy.factors.iter().find(|f| f.id == "ooba").unwrap();
 /// let setup_params = &policy_factor.params;
 /// let ciphertext = hex::decode(setup_params["next"].as_str().unwrap()).unwrap();
-/// let plaintext = private_key.decrypt(Oaep::new::<Sha256>(), &ciphertext).unwrap();
+/// let plaintext = private_key.decrypt(rsa::Oaep::new::<sha2::Sha256>(), &ciphertext).unwrap();
 /// let decoded: serde_json::Value = serde_json::from_slice(&plaintext).unwrap();
 /// let code = decoded["code"].as_str().unwrap();
 ///
-/// let derive_factor = derive_ooba(code)?;
+/// let derive_factor = derive::factors::ooba(code)?;
 /// let derived_key = derive::key(
 ///   &setup_key.policy,
 ///   HashMap::from([("ooba".to_string(), derive_factor)]),
@@ -154,8 +149,7 @@ impl FactorDerive for Ooba {
 /// )?;
 ///
 /// assert_eq!(derived_key.key, setup_key.key);
-/// # Ok(())
-/// # }
+/// # Ok::<(), mfkdf2::error::MFKDF2Error>(())
 /// ```
 pub fn ooba(code: &str) -> MFKDF2Result<MFKDF2Factor> {
   if code.is_empty() {
@@ -216,7 +210,7 @@ mod tests {
       params: Some(json!({"foo":"bar"})),
     };
 
-    let result = crate::setup::factors::ooba::ooba(options);
+    let result = crate::setup::factors::ooba(options);
     assert!(result.is_ok());
 
     result.unwrap()
@@ -328,7 +322,7 @@ mod tests {
       key:    Some(jwk),
       params: Some(json!({"foo":"bar"})),
     };
-    let setup = crate::setup::factors::ooba::ooba(options).unwrap();
+    let setup = crate::setup::factors::ooba(options).unwrap();
 
     // Setup for derive
     let setup_params = setup.factor_type.setup().params([0u8; 32].into()).unwrap();