Add Argon2id key derivation for cross-platform encryption

Introduces a memory-hard Argon2id-based key derivation function to fula-crypto, fula-flutter, and fula-js for secure, brute-force resistant key generation from user credentials. Updates derive_key implementations in Flutter and JS bindings to use Argon2id for consistent encryption key derivation across platforms. Bumps workspace and Flutter client versions to 0.2.24.

Author: ehsan6sha

Cargo.lock

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

Cargo.toml

@@ -29,6 +29,7 @@ sha2 = { workspace = true }
 md-5 = { workspace = true }
 x25519-dalek = { workspace = true }
 ed25519-dalek = { workspace = true }
+argon2 = "0.5"
 
 # Post-Quantum Cryptography (NIST FIPS 203 ML-KEM)
 # Using Cryspen's formally verified implementation for WASM + native support

crates/fula-crypto/Cargo.toml

@@ -197,13 +197,66 @@ where
     hasher.finalize()
 }
 
-/// Derive a key from the given input and context
+/// Derive a key from the given input and context using BLAKE3 KDF
+///
+/// Note: For password-based or credential-based key derivation where brute-force
+/// resistance is needed, use `derive_key_argon2id` instead.
 pub fn derive_key(context: &str, input: &[u8]) -> Blake3Hash {
     let mut hasher = IncrementalHasher::new_derive_key(context);
     hasher.update(input);
     hasher.finalize()
 }
 
+/// Derive a key from the given input and context using Argon2id
+///
+/// This provides brute-force resistance for credential-based key derivation.
+/// Uses memory-hard Argon2id algorithm with secure parameters:
+/// - Memory: 64 MiB
+/// - Iterations: 3
+/// - Parallelism: 1 (for cross-platform consistency)
+/// - Output: 32 bytes
+///
+/// The context string is used as the salt to provide domain separation.
+///
+/// # Example
+/// ```
+/// use fula_crypto::hashing::derive_key_argon2id;
+///
+/// let key = derive_key_argon2id("fula-files-v1", b"google:123456:user@example.com");
+/// assert_eq!(key.len(), 32);
+/// ```
+pub fn derive_key_argon2id(context: &str, input: &[u8]) -> [u8; 32] {
+    use argon2::{Argon2, Algorithm, Version, Params};
+
+    // Secure parameters for credential-based key derivation
+    // Memory: 64 MiB (65536 KiB) - provides memory-hardness
+    // Iterations: 3 - time cost
+    // Parallelism: 1 - for consistent cross-platform results
+    let params = Params::new(65536, 3, 1, Some(32))
+        .expect("Invalid Argon2 parameters");
+
+    let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, params);
+
+    let mut output = [0u8; 32];
+
+    // Use context as salt for domain separation
+    // Pad or hash the context to ensure minimum 8-byte salt requirement
+    let salt = if context.len() >= 8 {
+        context.as_bytes().to_vec()
+    } else {
+        // Pad short contexts with zeros
+        let mut padded = vec![0u8; 8];
+        padded[..context.len()].copy_from_slice(context.as_bytes());
+        padded
+    };
+
+    argon2
+        .hash_password_into(input, &salt, &mut output)
+        .expect("Argon2 hashing failed");
+
+    output
+}
+
 /// Calculate an MD5 hash for S3 ETag compatibility
 pub fn md5_hash(data: &[u8]) -> String {
     use md5::{Md5, Digest};
@@ -308,4 +361,30 @@ mod tests {
         let key2 = derive_key("context2", b"input");
         assert_ne!(key1, key2);
     }
+
+    #[test]
+    fn test_derive_key_argon2id() {
+        // Test basic functionality
+        let key1 = derive_key_argon2id("fula-files-v1", b"google:123456:user@example.com");
+        assert_eq!(key1.len(), 32);
+
+        // Test consistency - same input produces same output
+        let key2 = derive_key_argon2id("fula-files-v1", b"google:123456:user@example.com");
+        assert_eq!(key1, key2);
+
+        // Test different context produces different key
+        let key3 = derive_key_argon2id("fula-files-v2", b"google:123456:user@example.com");
+        assert_ne!(key1, key3);
+
+        // Test different input produces different key
+        let key4 = derive_key_argon2id("fula-files-v1", b"google:789012:other@example.com");
+        assert_ne!(key1, key4);
+    }
+
+    #[test]
+    fn test_derive_key_argon2id_short_context() {
+        // Test with short context (< 8 bytes) - should still work
+        let key = derive_key_argon2id("short", b"input");
+        assert_eq!(key.len(), 32);
+    }
 }

crates/fula-crypto/src/hashing.rs

@@ -205,6 +205,38 @@ pub fn derive_public_key_from_secret(secret_key_bytes: Vec<u8>) -> anyhow::Resul
     Ok(public.as_bytes().to_vec())
 }
 
+/// Derive a 32-byte key using Argon2id (memory-hard KDF)
+///
+/// **IMPORTANT**: Use this function to derive encryption keys from user credentials
+/// instead of platform-specific PBKDF2 implementations.
+///
+/// This ensures both FxFiles (Flutter) and WebUI (WASM) derive the exact same key
+/// from the same inputs, with brute-force resistance from Argon2id's memory-hardness.
+///
+/// Parameters:
+/// - Memory: 64 MiB
+/// - Iterations: 3
+/// - Parallelism: 1 (for cross-platform consistency)
+///
+/// # Arguments
+/// * `context` - A context string used as salt (e.g., "fula-files-v1")
+/// * `input` - The input bytes (e.g., UTF-8 encoded "google:{userId}:{email}")
+///
+/// # Returns
+/// * 32-byte derived key
+///
+/// # Example
+/// ```dart
+/// // Derive encryption key from Google credentials (same as WebUI):
+/// final input = utf8.encode('google:${userId}:${email}');
+/// final secretKey = await deriveKey(context: 'fula-files-v1', input: input);
+///
+/// // Use secretKey for createEncryptedClient
+/// ```
+pub fn derive_key(context: String, input: Vec<u8>) -> Vec<u8> {
+    fula_crypto::hashing::derive_key_argon2id(&context, &input).to_vec()
+}
+
 /// Check if client uses FlatNamespace mode
 pub async fn is_flat_namespace(client: &EncryptedClientHandle) -> bool {
     let guard = client.inner.read().await;

crates/fula-flutter/src/api/encrypted.rs

@@ -52,6 +52,8 @@ pub use encrypted::{
     list_directory,
     export_secret_key,
     get_public_key,
+    derive_key,
+    derive_public_key_from_secret,
     is_flat_namespace,
     enc_list_buckets,
     enc_create_bucket,

crates/fula-flutter/src/api/mod.rs

@@ -456,15 +456,24 @@ pub async fn get_public_key(client: &EncryptedClient) -> Vec<u8> {
     guard.encryption_config().public_key().as_bytes().to_vec()
 }
 
-/// Derive a 32-byte key from context and input
+/// Derive a 32-byte key from context and input using Argon2id (memory-hard KDF)
 ///
-/// Use this to derive encryption keys from Google credentials:
+/// Use this to derive encryption keys from Google credentials with brute-force resistance:
 /// ```javascript
-/// const key = deriveKey('my-app-v1', new TextEncoder().encode(userId + email));
+/// const key = deriveKey('fula-files-v1', new TextEncoder().encode(`google:${userId}:${email}`));
 /// ```
+///
+/// Parameters:
+/// - Memory: 64 MiB
+/// - Iterations: 3
+/// - Parallelism: 1 (for cross-platform consistency)
+///
+/// @param context - Context string used as salt (e.g., "fula-files-v1")
+/// @param input - Input bytes (e.g., UTF-8 encoded credentials)
+/// @returns 32-byte derived key
 #[wasm_bindgen(js_name = deriveKey)]
 pub fn derive_key(context: &str, input: &[u8]) -> Vec<u8> {
-    fula_crypto::hashing::derive_key(context, input).as_bytes().to_vec()
+    fula_crypto::hashing::derive_key_argon2id(context, input).to_vec()
 }
 
 /// Derive X25519 public key from private key bytes
@@ -611,14 +620,15 @@ mod tests {
     wasm_bindgen_test_configure!(run_in_browser);
 
     #[wasm_bindgen_test]
-    fn test_derive_key() {
-        let key1 = derive_key("test-context", b"input1");
-        let key2 = derive_key("test-context", b"input2");
-        let key3 = derive_key("test-context", b"input1");
+    fn test_derive_key_argon2id() {
+        // Test Argon2id key derivation
+        let key1 = derive_key("fula-files-v1", b"google:123:user@test.com");
+        let key2 = derive_key("fula-files-v1", b"google:456:other@test.com");
+        let key3 = derive_key("fula-files-v1", b"google:123:user@test.com");
 
         assert_eq!(key1.len(), 32);
-        assert_ne!(key1, key2);
-        assert_eq!(key1, key3); // Deterministic
+        assert_ne!(key1, key2); // Different input -> different key
+        assert_eq!(key1, key3); // Same input -> same key (deterministic)
     }
 
     #[wasm_bindgen_test]

crates/fula-js/src/lib.rs

@@ -1,6 +1,6 @@
 name: fula_client
 description: Flutter SDK for Fula decentralized storage with client-side encryption, metadata privacy, and secure sharing.
-version: 0.2.23
+version: 0.2.24
 homepage: https://fx.land
 repository: https://github.com/functionland/fula-api
 issue_tracker: https://github.com/functionland/fula-api/issues