F-A1 Phase 1: derive_key_argon2id_with_salt (Rust crypto + FFI)

Adds the cryptographic primitive and the FFI entry point that Mode B
sign-up will rely on. See issue #14 for the full design context.

The existing `derive_key_argon2id(context, input)` uses the `context`
bytes as the Argon2 salt — which is a constant string for FxFiles
(`"fula-files-v1"`). Every input component (`provider:sub:email`) is
a public identity attribute, so anyone who obtains a single artifact
carrying all three computes the master key in one Argon2id invocation
— that is the F-A1 finding. The fix is to add a Mode B opt-in that
introduces a per-user random salt and a user-entered seed.

This commit lands the crypto + FFI side only:

- `fula_crypto::hashing::derive_key_argon2id_with_salt(context, input, salt)`:
  new function taking an explicit salt. Internally it BLAKE3-hashes
  `(context || 0x00 || salt)` to produce a 16-byte effective salt for
  Argon2, preserving both domain separation (context is consumed) and
  cross-platform consistency (effective salt is always 16 bytes
  regardless of caller-salt length).
- `derive_key_argon2id_with_salt_checked` is the non-panicking variant
  returning `Result<[u8; 32], &'static str>` for short-salt rejection.
- 7 unit tests cover: basic shape, distinct salts → distinct keys,
  distinct contexts → distinct keys, determinism, short-salt rejection,
  panic-on-short-salt convenience variant, and the explicit
  non-equivalence to the legacy function (so Mode A and Mode B never
  share a derived key even given byte-equivalent inputs — Mode B
  users go through the rotation).
- `fula_flutter::api::encrypted::derive_key_with_salt(context, input, salt)`:
  additive FFI surface that delegates to the new crypto function and
  surfaces the short-salt error as a `Result<Vec<u8>, String>`.

Mode A users are not affected — the legacy `derive_key_argon2id` and
the legacy `derive_key` FFI are kept in place and unchanged. A Mode A
user's derivation continues to produce the same bytes as before.

What this commit does NOT do (Phase 1.5 follow-up):

- Regenerate the `packages/fula_client/lib/src` Dart bindings — the
  dev environment needs LLVM / libclang for `flutter_rust_bridge_codegen`
  to complete (ffigen step). The Rust FFI is in place; once codegen is
  run on an LLVM-equipped dev environment, the Dart binding
  `deriveKeyWithSalt` will appear in `encrypted.dart` and the
  FxFiles app can call it.
- FxFiles `auth_service.dart` Mode B service-layer wiring — gated on
  the Dart binding being available. The audit-findings doc records
  the call-site changes; once the binding is generated, applying them
  is mechanical.
- Server-side derivation-profile API for cross-device — Phase 2,
  to be sequenced after the client-side Mode B opt-in is functional.
- UI screens (tier-action layout per Gemini advisor's UX review,
  partial mnemonic verification, less-secure / recommended labels) —
  Phase 2.

What ships in this commit IS safe in isolation: the new function is
additive, has no callers in production paths yet, and is exercised
only by unit tests. Mode A users see no behavior change.

Refs:
- Audit finding F-A1 in fula-client-audit-findings.md
- Issue #14 (the design + phasing)
- Gemini advisor UX review (2026-05-18) — informs Phase 2 UI
- Codex advisor correctness review (2026-05-18) — confirmed
  `derive_key_with_salt` as the right FFI shape (over encoding salt
  in input) and the staged-migration pattern for the eventual A→B
  rotation

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: ehsan6sha

crates/fula-crypto/src/hashing.rs

@@ -257,6 +257,93 @@ pub fn derive_key_argon2id(context: &str, input: &[u8]) -> [u8; 32] {
     output
 }
 
+/// Derive a key from the given input, context, and an EXPLICIT salt
+/// using Argon2id.
+///
+/// Compared to [`derive_key_argon2id`], which uses the `context` bytes
+/// as the salt, this variant takes the salt as a separate parameter so
+/// callers can supply a per-user random salt. This is the load-bearing
+/// piece of the audit F-A1 fix (Mode B sign-up): a per-user random
+/// salt ensures that the master key is not derivable from public
+/// identity attributes alone, even when an attacker knows the input.
+///
+/// Salt requirements (validated):
+/// - Minimum 8 bytes (Argon2 spec)
+/// - Recommended 16+ bytes; 32 bytes is what Mode B uses
+///
+/// # Panics
+///
+/// Panics if `salt.len() < 8` (caller error — surface this in tests).
+/// Use [`derive_key_argon2id_with_salt_checked`] for a non-panicking
+/// variant.
+///
+/// # Example
+/// ```
+/// use fula_crypto::hashing::derive_key_argon2id_with_salt;
+///
+/// let salt = [0u8; 32]; // Production: 32 random bytes per user.
+/// let key = derive_key_argon2id_with_salt(
+///     "fula-files-v1-google-pw",
+///     b"google:123456:user@example.com:passphrase",
+///     &salt,
+/// );
+/// assert_eq!(key.len(), 32);
+/// ```
+pub fn derive_key_argon2id_with_salt(context: &str, input: &[u8], salt: &[u8]) -> [u8; 32] {
+    derive_key_argon2id_with_salt_checked(context, input, salt)
+        .expect("derive_key_argon2id_with_salt: salt must be >= 8 bytes")
+}
+
+/// Non-panicking variant of [`derive_key_argon2id_with_salt`].
+/// Returns `Err` if the salt is shorter than 8 bytes.
+///
+/// `context` is incorporated into the salt as a domain-separation
+/// prefix: `actual_salt = blake3_keyed("fula-argon2id-v2:"||context)(salt)[..16]`
+/// — concretely, we hash `(context || 0x00 || salt)` with BLAKE3 and
+/// take the first 16 bytes as the Argon2 salt. This way:
+///   1. Distinct contexts derive distinct keys even from the same
+///      (input, salt) pair — preserves the domain-separation property
+///      of the original `derive_key_argon2id`.
+///   2. The caller-supplied salt is consumed.
+///   3. The Argon2 salt is always exactly 16 bytes regardless of the
+///      caller's salt length, so cross-platform consistency is
+///      preserved (FxFiles is on native, WebUI on WASM).
+pub fn derive_key_argon2id_with_salt_checked(
+    context: &str,
+    input: &[u8],
+    salt: &[u8],
+) -> std::result::Result<[u8; 32], &'static str> {
+    use argon2::{Algorithm, Argon2, Params, Version};
+
+    if salt.len() < 8 {
+        return Err("salt must be at least 8 bytes");
+    }
+
+    let params = Params::new(65536, 3, 1, Some(32)).expect("Invalid Argon2 parameters");
+    let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, params);
+
+    // Build a deterministic 16-byte effective salt that incorporates
+    // BOTH the context (domain separation) and the caller's salt. See
+    // doc comment above for the rationale.
+    let mut effective_salt = [0u8; 16];
+    let combined = {
+        let mut buf = Vec::with_capacity(context.len() + 1 + salt.len());
+        buf.extend_from_slice(context.as_bytes());
+        buf.push(0u8);
+        buf.extend_from_slice(salt);
+        buf
+    };
+    let h = blake3::hash(&combined);
+    effective_salt.copy_from_slice(&h.as_bytes()[..16]);
+
+    let mut output = [0u8; 32];
+    argon2
+        .hash_password_into(input, &effective_salt, &mut output)
+        .expect("Argon2 hashing failed");
+
+    Ok(output)
+}
+
 /// Calculate an MD5 hash for S3 ETag compatibility
 pub fn md5_hash(data: &[u8]) -> String {
     use md5::{Md5, Digest};
@@ -387,4 +474,87 @@ mod tests {
         let key = derive_key_argon2id("short", b"input");
         assert_eq!(key.len(), 32);
     }
+
+    // ---------------------------------------------------------------
+    // Tests for `derive_key_argon2id_with_salt` (audit F-A1 / issue #14).
+    //
+    // The Mode B fix relies on this function consuming a per-user
+    // random salt so the master key is not derivable from public
+    // identity attributes alone.
+    // ---------------------------------------------------------------
+
+    #[test]
+    fn argon2id_with_salt_basic_shape() {
+        let salt = [0u8; 32];
+        let key = derive_key_argon2id_with_salt(
+            "fula-files-v1-google-pw",
+            b"google:123:user@example.com:passphrase",
+            &salt,
+        );
+        assert_eq!(key.len(), 32);
+    }
+
+    #[test]
+    fn argon2id_with_salt_distinct_salts_produce_distinct_keys() {
+        let input = b"google:123:user@example.com:passphrase";
+        let salt_a = [0xAAu8; 32];
+        let salt_b = [0xBBu8; 32];
+        let key_a = derive_key_argon2id_with_salt("ctx", input, &salt_a);
+        let key_b = derive_key_argon2id_with_salt("ctx", input, &salt_b);
+        assert_ne!(
+            key_a, key_b,
+            "salt is the load-bearing parameter for the F-A1 fix"
+        );
+    }
+
+    #[test]
+    fn argon2id_with_salt_distinct_contexts_produce_distinct_keys() {
+        // Same input + same salt, different context → different key.
+        // Preserves domain separation from the legacy function.
+        let input = b"google:123:user@example.com:passphrase";
+        let salt = [0x11u8; 32];
+        let key_a = derive_key_argon2id_with_salt("ctx-a", input, &salt);
+        let key_b = derive_key_argon2id_with_salt("ctx-b", input, &salt);
+        assert_ne!(key_a, key_b);
+    }
+
+    #[test]
+    fn argon2id_with_salt_deterministic() {
+        let input = b"google:123:user@example.com:passphrase";
+        let salt = [0x55u8; 32];
+        let key_a = derive_key_argon2id_with_salt("ctx", input, &salt);
+        let key_b = derive_key_argon2id_with_salt("ctx", input, &salt);
+        assert_eq!(key_a, key_b);
+    }
+
+    #[test]
+    fn argon2id_with_salt_rejects_short_salt() {
+        let res = derive_key_argon2id_with_salt_checked("ctx", b"input", &[0u8; 7]);
+        assert!(res.is_err());
+    }
+
+    #[test]
+    #[should_panic(expected = "salt must be >= 8 bytes")]
+    fn argon2id_with_salt_panics_on_short_salt() {
+        let _ = derive_key_argon2id_with_salt("ctx", b"input", &[0u8; 7]);
+    }
+
+    #[test]
+    fn argon2id_with_salt_does_not_match_legacy_even_with_context_as_salt() {
+        // The new function applies a BLAKE3 domain-separation step to
+        // the (context, salt) pair before passing to Argon2, so it is
+        // intentionally NOT byte-equivalent to the legacy function. The
+        // legacy function is kept in place for Mode A users (unchanged).
+        let input = b"google:123:user@example.com";
+        let legacy = derive_key_argon2id("fula-files-v1", input);
+        let with_salt = derive_key_argon2id_with_salt(
+            "fula-files-v1",
+            input,
+            b"fula-files-v1\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0",
+        );
+        assert_ne!(
+            legacy, with_salt,
+            "Mode A and Mode B derive distinct keys even given byte-equivalent inputs — Mode B users go through the rotation"
+        );
+    }
 }

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

@@ -275,6 +275,43 @@ pub fn derive_key(context: String, input: Vec<u8>) -> Vec<u8> {
     fula_crypto::hashing::derive_key_argon2id(&context, &input).to_vec()
 }
 
+/// Derive a 32-byte key using Argon2id with an EXPLICIT per-user salt.
+///
+/// This is the audit F-A1 / issue #14 Mode B variant. Compared to
+/// [`derive_key`], which uses the `context` bytes as the salt, this
+/// variant takes the salt as a separate parameter so callers can
+/// supply a per-user random salt — closing the F-A1 finding (the
+/// master key is no longer derivable from public identity attributes
+/// alone).
+///
+/// Cross-platform parity: the underlying
+/// `fula_crypto::hashing::derive_key_argon2id_with_salt` is pure Rust
+/// and is reachable from both native (FxFiles) and WASM (WebUI) so the
+/// derived key is byte-identical across platforms for the same
+/// (context, input, salt) triple.
+///
+/// Mode A users continue to call [`derive_key`] (legacy behavior,
+/// unchanged). Mode B users call this function with their per-user
+/// random salt.
+///
+/// # Arguments
+/// * `context` — domain-separation tag (e.g., `"fula-files-v1-google-pw"`)
+/// * `input`   — UTF-8 bytes of the identity-plus-seed string
+///               (e.g., `"google:<sub>:<email>:<seed>"`)
+/// * `salt`    — per-user random salt; minimum 8 bytes, recommended 32
+///
+/// # Returns
+/// * 32-byte derived key, or an error string if the salt is too short
+pub fn derive_key_with_salt(
+    context: String,
+    input: Vec<u8>,
+    salt: Vec<u8>,
+) -> Result<Vec<u8>, String> {
+    fula_crypto::hashing::derive_key_argon2id_with_salt_checked(&context, &input, &salt)
+        .map(|k| k.to_vec())
+        .map_err(|e| e.to_string())
+}
+
 /// Check if client uses FlatNamespace mode
 pub async fn is_flat_namespace(client: &EncryptedClientHandle) -> bool {
     let guard = client.inner.read().await;