security improvements

Author: ehsan6sha

.gitignore

@@ -23,3 +23,4 @@ Thumbs.db
 /wasm-package
 /target
 /__pycache__
+/target

Cargo.lock

@@ -74,7 +74,7 @@ name = "encrypted_upload_test"
 path = "examples/encrypted_upload_test.rs"
 
 [workspace.package]
-version = "0.2.25"
+version = "0.2.26"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/functionland/fula-api"

Cargo.toml

@@ -29,6 +29,7 @@ url = "2.5"
 base64 = { workspace = true }
 hex = { workspace = true }
 mime_guess = "2.0"
+tokio = { version = "1.42", default-features = false, features = ["sync"] }
 
 # Platform-specific dependencies
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]

crates/fula-client/Cargo.toml

@@ -18,8 +18,9 @@ use fula_crypto::{
     rotation::{KeyRotationManager, WrappedKeyInfo},
     ChunkedEncoder, ChunkedFileMetadata, should_use_chunked,
 };
-use std::sync::{Arc, RwLock};
+use std::sync::Arc;
 use std::collections::HashMap;
+use tokio::sync::RwLock;
 
 /// Configuration for client-side encryption
 pub struct EncryptionConfig {
@@ -479,7 +480,10 @@ impl EncryptedClient {
             .map_err(ClientError::Encryption)?;
 
         // Decrypt data
-        let nonce_b64 = enc_metadata["nonce"].as_str().unwrap();
+        let nonce_b64 = enc_metadata["nonce"].as_str()
+            .ok_or_else(|| ClientError::Encryption(
+                fula_crypto::CryptoError::Decryption("Missing nonce in encryption metadata".to_string())
+            ))?;
         let nonce_bytes = base64::Engine::decode(
             &base64::engine::general_purpose::STANDARD,
             nonce_b64,
@@ -765,7 +769,7 @@ impl EncryptedClient {
     pub async fn load_forest(&self, bucket: &str) -> Result<PrivateForest> {
         // Check cache first
         {
-            let cache = self.forest_cache.read().unwrap();
+            let cache = self.forest_cache.read().await;
             if let Some(forest) = cache.get(bucket) {
                 return Ok(forest.clone());
             }
@@ -788,19 +792,19 @@ impl EncryptedClient {
 
                 // Cache it
                 {
-                    let mut cache = self.forest_cache.write().unwrap();
+                    let mut cache = self.forest_cache.write().await;
                     cache.insert(bucket.to_string(), forest.clone());
                 }
-                
+
                 Ok(forest)
             }
             Err(_) => {
                 // No forest exists yet - create empty one
                 let forest = PrivateForest::new();
-                
+
                 // Cache it
                 {
-                    let mut cache = self.forest_cache.write().unwrap();
+                    let mut cache = self.forest_cache.write().await;
                     cache.insert(bucket.to_string(), forest.clone());
                 }
 
@@ -835,7 +839,7 @@ impl EncryptedClient {
 
         // Update cache
         {
-            let mut cache = self.forest_cache.write().unwrap();
+            let mut cache = self.forest_cache.write().await;
             cache.insert(bucket.to_string(), forest.clone());
         }
 
@@ -966,7 +970,7 @@ impl EncryptedClient {
 
         // Update cache (but don't save to storage yet)
         {
-            let mut cache = self.forest_cache.write().unwrap();
+            let mut cache = self.forest_cache.write().await;
             cache.insert(bucket.to_string(), forest);
         }
 
@@ -1076,7 +1080,7 @@ impl EncryptedClient {
     /// This persists the in-memory forest index to encrypted storage.
     pub async fn flush_forest(&self, bucket: &str) -> Result<()> {
         let forest = {
-            let cache = self.forest_cache.read().unwrap();
+            let cache = self.forest_cache.read().await;
             cache.get(bucket).cloned()
         };
 
@@ -1088,8 +1092,8 @@ impl EncryptedClient {
     }
 
     /// Check if there are unsaved forest changes
-    pub fn has_pending_forest_changes(&self, bucket: &str) -> bool {
-        let cache = self.forest_cache.read().unwrap();
+    pub async fn has_pending_forest_changes(&self, bucket: &str) -> bool {
+        let cache = self.forest_cache.read().await;
         cache.contains_key(bucket)
     }
 
@@ -1717,7 +1721,8 @@ impl EncryptedClient {
         ).await?;
 
         // Update forest cache if we have one
-        if let Ok(mut cache) = self.forest_cache.write() {
+        {
+            let mut cache = self.forest_cache.write().await;
             if let Some(forest) = cache.get_mut(bucket) {
                 let now = chrono::Utc::now().timestamp();
                 forest.upsert_file(ForestFileEntry {

crates/fula-client/src/encryption.rs

@@ -15,6 +15,7 @@ use crate::{
     keys::{DekKey, KekKeyPair, PublicKey, SecretKey},
     symmetric::AeadCipher,
 };
+use zeroize::Zeroizing;
 use hpke::{
     Deserializable, Kem, Serializable,
     aead::ChaCha20Poly1305,
@@ -54,7 +55,12 @@ pub const ENCAPSULATED_KEY_SIZE: usize = 32;
 /// HPKE configuration
 #[derive(Clone, Debug, Serialize, SerdeDeserialize)]
 pub struct HpkeConfig {
-    /// The AEAD cipher to use
+    /// The AEAD cipher preference.
+    ///
+    /// **Note:** This field is currently ignored by the HPKE encryption logic.
+    /// The actual AEAD algorithm is hardcoded to ChaCha20Poly1305 as part of the
+    /// RFC 9180 cipher suite (X25519HkdfSha256 + HkdfSha256 + ChaCha20Poly1305).
+    /// This field is retained for forward compatibility and configuration display.
     pub aead: AeadCipher,
     /// Key derivation context
     pub context: String,
@@ -328,7 +334,7 @@ impl Decryptor {
     /// Decrypt a wrapped DEK
     /// Uses AAD context "fula:v2:dek-wrap" (must match encryption)
     pub fn decrypt_dek(&self, encrypted: &EncryptedData) -> Result<DekKey> {
-        let bytes = self.decrypt_with_aad(encrypted, b"fula:v2:dek-wrap")?;
+        let bytes = Zeroizing::new(self.decrypt_with_aad(encrypted, b"fula:v2:dek-wrap")?);
         DekKey::from_bytes(&bytes)
     }
 }

crates/fula-crypto/src/hpke.rs

@@ -156,17 +156,27 @@ pub struct HybridSecretKey {
 
 impl HybridSecretKey {
     /// Generate a new random hybrid key pair
+    ///
+    /// # Panics
+    /// Panics if the OS random number generator is unavailable.
     pub fn generate() -> (Self, HybridPublicKey) {
+        Self::try_generate().expect("getrandom failed during hybrid key generation")
+    }
+
+    /// Generate a new random hybrid key pair, returning an error if OS entropy is unavailable.
+    pub fn try_generate() -> Result<(Self, HybridPublicKey)> {
         // Generate X25519 keypair using getrandom (WASM compatible)
         let mut x25519_bytes = [0u8; 32];
-        getrandom::getrandom(&mut x25519_bytes).expect("getrandom failed");
+        getrandom::getrandom(&mut x25519_bytes)
+            .map_err(|e| CryptoError::KeyGeneration(format!("getrandom failed: {}", e)))?;
         let x25519_secret = StaticSecret::from(x25519_bytes);
         let x25519_public = X25519Public::from(&x25519_secret);
 
         // Generate ML-KEM-768 keypair using libcrux (FIPS 203)
         // libcrux uses explicit 64-byte randomness instead of callback RNG
         let mut keygen_randomness = [0u8; 64];
-        getrandom::getrandom(&mut keygen_randomness).expect("getrandom failed");
+        getrandom::getrandom(&mut keygen_randomness)
+            .map_err(|e| CryptoError::KeyGeneration(format!("getrandom failed: {}", e)))?;
         let mlkem_keypair = mlkem_generate_key_pair(keygen_randomness);
 
         // Extract raw bytes from libcrux types
@@ -185,7 +195,7 @@ impl HybridSecretKey {
             mlkem: mlkem_pk,
         };
 
-        (secret, public)
+        Ok((secret, public))
     }
 
     /// Create from raw bytes
@@ -350,6 +360,10 @@ impl std::fmt::Debug for HybridEncapsulatedKey {
 /// 3. HKDF-SHA256 to derive the final shared secret
 ///
 /// Returns the encapsulated key (to send to recipient) and the shared secret
+///
+/// # Panics
+/// Panics if the OS random number generator is unavailable.
+/// Use [`try_encapsulate()`] for a fallible alternative.
 pub fn encapsulate(recipient_public: &HybridPublicKey) -> Result<(HybridEncapsulatedKey, [u8; SHARED_SECRET_SIZE])> {
     // X25519: Generate ephemeral keypair using getrandom (WASM compatible)
     let mut ephemeral_bytes = [0u8; 32];
@@ -393,6 +407,49 @@ pub fn encapsulate(recipient_public: &HybridPublicKey) -> Result<(HybridEncapsul
     Ok((encapsulated, shared_secret))
 }
 
+/// Fallible version of [`encapsulate()`] that returns an error instead of panicking
+/// if OS entropy is unavailable.
+pub fn try_encapsulate(recipient_public: &HybridPublicKey) -> Result<(HybridEncapsulatedKey, [u8; SHARED_SECRET_SIZE])> {
+    // X25519: Generate ephemeral keypair
+    let mut ephemeral_bytes = [0u8; 32];
+    getrandom::getrandom(&mut ephemeral_bytes)
+        .map_err(|e| CryptoError::KeyGeneration(format!("getrandom failed: {}", e)))?;
+    let x25519_ephemeral_secret = StaticSecret::from(ephemeral_bytes);
+    let x25519_ephemeral_public = X25519Public::from(&x25519_ephemeral_secret);
+    let x25519_recipient_public = X25519Public::from(recipient_public.x25519);
+    let x25519_shared = x25519_ephemeral_secret.diffie_hellman(&x25519_recipient_public);
+
+    // ML-KEM-768: Encapsulate
+    let mut encaps_randomness = [0u8; 32];
+    getrandom::getrandom(&mut encaps_randomness)
+        .map_err(|e| CryptoError::KeyGeneration(format!("getrandom failed: {}", e)))?;
+
+    let mlkem_pk = MlKem768PublicKey::from(recipient_public.mlkem);
+    let (ct, mlkem_shared_secret) = mlkem_encapsulate(&mlkem_pk, encaps_randomness);
+
+    let mut mlkem_ciphertext = [0u8; MLKEM_CIPHERTEXT_SIZE];
+    mlkem_ciphertext.copy_from_slice(ct.as_ref());
+
+    // Combine shared secrets using HKDF-SHA256
+    let mut ikm = Vec::with_capacity(32 + SHARED_SECRET_SIZE);
+    ikm.extend_from_slice(x25519_shared.as_bytes());
+    ikm.extend_from_slice(&mlkem_shared_secret);
+
+    let hk = Hkdf::<Sha256>::new(None, &ikm);
+    let mut shared_secret = [0u8; SHARED_SECRET_SIZE];
+    hk.expand(HKDF_INFO, &mut shared_secret)
+        .map_err(|e| CryptoError::Encryption(format!("HKDF expansion failed: {:?}", e)))?;
+
+    ikm.zeroize();
+
+    let encapsulated = HybridEncapsulatedKey {
+        x25519_ephemeral: *x25519_ephemeral_public.as_bytes(),
+        mlkem_ciphertext,
+    };
+
+    Ok((encapsulated, shared_secret))
+}
+
 /// Decapsulate a shared secret (recipient side)
 ///
 /// This uses the recipient's secret key to recover: