resolved offline download userid issue

Author: ehsan6sha

Cargo.lock

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

Cargo.toml

@@ -99,13 +99,16 @@ pub use health_gate::{HealthCallback, MasterHealthEvent};
 #[cfg(not(target_arch = "wasm32"))]
 pub use block_cache::{BlockCache, BlockCacheError};
 
-/// Phase 3.3 — `derive_user_key_from_email` available on EVERY
-/// target (wasm + native). Apps compute the userKey at sign-in
-/// time from the OAuth-provided email and stash it in
-/// `Config::users_index_user_key`. The same function is also
-/// re-exported via `registry_resolver` on native for backward
-/// compatibility with code that imports it from there.
-pub use user_key::derive_user_key_from_email;
+/// Phase 3.3 — userKey derivation, available on EVERY target
+/// (wasm + native). See `user_key.rs` module-level docs for which
+/// function to call:
+///
+/// - **`derive_user_key_from_jwt_sub`** (preferred) — matches master
+///   byte-for-byte. Pass the JWT `sub` claim through unchanged.
+/// - **`derive_user_key_from_email`** (legacy) — broken for
+///   pre-migration-011 users whose JWT sub is plaintext email.
+///   Kept for source compatibility with already-shipped apps.
+pub use user_key::{derive_user_key_from_email, derive_user_key_from_jwt_sub};
 
 /// Phase 3.3 — cold-start hybrid resolver public API. Native-only;
 /// the resolver itself is gated to `cfg(not(target_arch = "wasm32"))`.

crates/fula-client/src/lib.rs

@@ -1,43 +1,92 @@
 //! Phase 3.3 — userKey derivation, available on every target.
 //!
-//! `derive_user_key_from_email` was originally inlined in
-//! `registry_resolver.rs`, but that module is gated to native via
-//! `#![cfg(not(target_arch = "wasm32"))]` because it depends on
-//! `reqwest`, `parking_lot`, and other crates that don't compile on
-//! wasm. The userKey computation itself is pure: just `sha2` +
-//! `blake3` + `hex` — all of which build cleanly on wasm32 (these
-//! are already transitive deps of the wasm SDK build).
-//!
-//! Extracting the helper here lets the FRB and wasm-bindgen
-//! bindings expose `derive_user_key_from_email` without having to
-//! re-implement the algorithm. Master and SDK both produce the
-//! same `userKey` for the same email, regardless of which target
-//! the SDK was built for.
-//!
-//! **Algorithm (must stay in lockstep with master's `state.rs::hash_user_id`):**
+//! Two functions live here, and choosing the right one matters — getting
+//! it wrong produces a silent cold-start failure (master publishes under
+//! userKey A, SDK looks up userKey B, lookup misses, "user has not
+//! written yet" error even though they have).
 //!
+//! ### `derive_user_key_from_jwt_sub` (PREFERRED — matches master exactly)
+//!
+//! Master's `crates/fula-cli/src/state.rs::hash_user_id` does:
+//! ```text
+//! BLAKE3.derive_key("fula:user_id:", claims.sub.as_bytes())[..16].hex()
+//! ```
+//! `claims.sub` is fed in as-is, no transformation. Whatever string the
+//! JWT carries as `sub` IS the hash input. This function mirrors that
+//! exactly. Apps that have access to the JWT sub at sign-in (which is
+//! always — they just received the token) should call THIS one.
+//!
+//! For pre-migration-011 users, `claims.sub` is plaintext email.
+//! For post-migration users, `claims.sub` is `sha256(email).hex()`.
+//! Either way, hashing the sub directly matches master.
+//!
+//! ### `derive_user_key_from_email` (LEGACY — breaks for pre-migration users)
+//!
+//! Originally written assuming all users would be post-migration-011
+//! (where `claims.sub == sha256(email).hex()`). That assumption is
+//! WRONG for pre-migration users — their JWTs still carry plaintext
+//! email as `sub`, and master's `hash_user_id(claims.sub)` therefore
+//! produces a different value than the one this function returns.
+//! Result: pre-migration users' cold-start lookups always miss.
+//!
+//! Kept for backward compatibility with apps that have already shipped
+//! using it. Apps SHOULD migrate to `derive_user_key_from_jwt_sub`.
+//!
+//! **Algorithm (legacy, post-migration-only):**
 //! ```text
 //! email_lower = email.to_lowercase()
 //! user_id_digest = sha256(email_lower.as_bytes())
 //! user_id_hex = hex(user_id_digest)
-//! domain_separated = "fula:user_id:" || user_id_hex
-//! user_key = hex( blake3(domain_separated)[..16] )
+//! user_key = hex( BLAKE3.derive_key("fula:user_id:", user_id_hex.as_bytes())[..16] )
 //! ```
 //!
-//! Drift here vs. master = silent cold-start failure (master
-//! publishes under userKey A, SDK looks up userKey B). The
-//! `derive_user_key_matches_master_state_rs_algorithm` test in
-//! `registry_resolver.rs` reproduces master's algorithm step-by-step
-//! and asserts equality.
+//! Both functions are pure (sha2 + blake3 + hex), build cleanly on
+//! wasm32, and are exposed through FRB and wasm-bindgen. Master and
+//! SDK produce the same userKey when each side uses its correct input.
 
 use sha2::{Digest, Sha256};
 
-/// Compute the canonical fula `userKey` for cold-start config from a
-/// plaintext email. Returns 32 hex chars (16-byte BLAKE3 truncated digest).
+/// Compute the canonical fula `userKey` directly from a JWT `sub` claim.
+///
+/// **Use this for cold-start config whenever the app has access to the
+/// JWT sub** — which it does at sign-in (the issued token carries it).
+///
+/// Mirrors master's `crates/fula-cli/src/state.rs::hash_user_id` byte-for-byte:
+/// the input bytes go straight into `BLAKE3.derive_key` with no
+/// transformation. Returns 32 hex chars (first 16 bytes of the digest).
 ///
-/// Apps call this at sign-in time (the OAuth flow has plaintext email)
-/// and pass the returned string into `Config::users_index_user_key`.
-/// The SDK never persists or transmits the raw email.
+/// Works correctly for BOTH pre-migration users (whose `sub` is plaintext
+/// email) AND post-migration users (whose `sub` is `sha256(email).hex()`).
+/// The caller passes the JWT sub through unchanged; this function does
+/// not normalize, lowercase, or pre-hash.
+///
+/// Apps should cache the JWT sub at sign-in and pass it to this function
+/// when (re-)configuring `Config::users_index_user_key`. The SDK never
+/// persists or transmits the raw sub.
+pub fn derive_user_key_from_jwt_sub(jwt_sub: &str) -> String {
+    let mut hasher = blake3::Hasher::new();
+    hasher.update(b"fula:user_id:");
+    hasher.update(jwt_sub.as_bytes());
+    hex::encode(&hasher.finalize().as_bytes()[..16])
+}
+
+/// **DEPRECATED — breaks for pre-migration-011 users.** Use
+/// [`derive_user_key_from_jwt_sub`] instead and pass the JWT `sub` claim.
+///
+/// Computes the userKey from a plaintext email by first applying
+/// `sha256(email.lowercase()).hex()` and then hashing that hex string
+/// via `BLAKE3.derive_key("fula:user_id:", ...)`. Returns 32 hex chars.
+///
+/// This produces the correct userKey for users whose JWT `sub` is
+/// `sha256(email).hex()` (post-migration-011) by accident — the SDK's
+/// extra `sha256` step happens to match what master's auth chain
+/// already did upstream. For users whose JWT `sub` is plaintext email
+/// (pre-migration-011), the SDK applies `sha256` but master does not,
+/// and the two derivations diverge.
+///
+/// Kept for source compatibility with apps that have already shipped
+/// using it. Cold-start may fail for pre-migration users; switch to
+/// [`derive_user_key_from_jwt_sub`] to fix.
 pub fn derive_user_key_from_email(email: &str) -> String {
     let user_id_digest = Sha256::digest(email.to_lowercase().as_bytes());
     let user_id_hex = hex::encode(user_id_digest);
@@ -46,3 +95,58 @@ pub fn derive_user_key_from_email(email: &str) -> String {
     hasher.update(user_id_hex.as_bytes());
     hex::encode(&hasher.finalize().as_bytes()[..16])
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Pinned test vector reproducing the bug observed in production
+    /// for pre-migration-011 user `ehsan@fx.land`. Master stored
+    /// `4da2c0616b1d39660f9f94e145fbce4f` (BLAKE3 over the plaintext
+    /// email), but the SDK was computing
+    /// `d2df90894e237aa4ef50618e514e0e37` (BLAKE3 over sha256(email)).
+    /// Cold-start lookup missed because of this mismatch.
+    ///
+    /// `derive_user_key_from_jwt_sub` with the plaintext email as the
+    /// argument MUST produce the master-stored value.
+    #[test]
+    fn derive_user_key_from_jwt_sub_matches_master_for_plaintext_email_sub() {
+        let key = derive_user_key_from_jwt_sub("ehsan@fx.land");
+        assert_eq!(key, "4da2c0616b1d39660f9f94e145fbce4f");
+    }
+
+    /// For post-migration-011 users the JWT sub is `sha256(email).hex()`.
+    /// Calling `derive_user_key_from_jwt_sub` with that sub must produce
+    /// the SAME value as the legacy `derive_user_key_from_email(email)`,
+    /// because `derive_user_key_from_email` does `sha256(email).hex()`
+    /// internally before hashing — same input bytes flowing into the
+    /// same `BLAKE3.derive_key("fula:user_id:", ...)` call.
+    #[test]
+    fn derive_user_key_from_jwt_sub_matches_legacy_for_sha256_email_sub() {
+        let email = "ehsan@fx.land";
+        let sha256_hex = hex::encode(Sha256::digest(email.to_lowercase().as_bytes()));
+        let from_sub = derive_user_key_from_jwt_sub(&sha256_hex);
+        let from_email_legacy = derive_user_key_from_email(email);
+        assert_eq!(from_sub, from_email_legacy);
+    }
+
+    /// Pinned reference for the legacy function. Documents the value
+    /// it returns for `ehsan@fx.land` so future refactors can't
+    /// silently change the algorithm.
+    #[test]
+    fn derive_user_key_from_email_pinned_value() {
+        assert_eq!(
+            derive_user_key_from_email("ehsan@fx.land"),
+            "d2df90894e237aa4ef50618e514e0e37"
+        );
+    }
+
+    /// Empty input must not panic (defense-in-depth — the input
+    /// shouldn't ever be empty in practice, but BLAKE3 must not be
+    /// called in a way that aborts on edge inputs).
+    #[test]
+    fn derive_user_key_from_jwt_sub_empty_does_not_panic() {
+        let key = derive_user_key_from_jwt_sub("");
+        assert_eq!(key.len(), 32);  // still 32 hex chars (16 bytes)
+    }
+}

crates/fula-client/src/user_key.rs

@@ -224,21 +224,48 @@ pub fn create_encrypted_client_with_pinning(
 }
 
 // ============================================================================
-// Phase 3.3 — derive_user_key_from_email
+// Phase 3.3 — userKey derivation
 // ============================================================================
 
-/// Compute the canonical fula `userKey` for cold-start config from a
-/// plaintext email. Mirrors `fula_client::derive_user_key_from_email`
-/// — same domain separator, same hash chain (sha256(lower(email))
-/// → BLAKE3("fula:user_id:" || _).bytes[..16] → hex-encode).
+/// **PREFERRED** — derive the canonical fula `userKey` directly from a
+/// JWT `sub` claim. Mirrors `fula_client::derive_user_key_from_jwt_sub`.
 ///
-/// Apps call this once at sign-in (the OAuth flow has plaintext
-/// email), then set `FulaConfig::users_index_user_key` to the
-/// returned string. The SDK never sees the raw email.
+/// Use this whenever the app has access to the JWT (which is at every
+/// sign-in — the issued token carries the sub). Works correctly for
+/// BOTH pre-migration-011 users (sub = plaintext email) and modern
+/// users (sub = sha256(email).hex()), because master's
+/// `state.rs::hash_user_id` does not transform the sub before hashing
+/// — and this function does not transform either.
 ///
-/// Native-only — wasm32 surfaces this via the JS-side `deriveKey`
-/// helper because the cold-start resolver (Phase 3.3) itself isn't
-/// wired on wasm.
+/// Apps should cache the JWT sub at sign-in and pass it here whenever
+/// (re-)setting `FulaConfig::users_index_user_key`. The SDK never sees
+/// the raw email.
+#[cfg(not(target_arch = "wasm32"))]
+pub fn derive_user_key_from_jwt_sub(jwt_sub: String) -> String {
+    fula_client::derive_user_key_from_jwt_sub(&jwt_sub)
+}
+
+#[cfg(target_arch = "wasm32")]
+pub fn derive_user_key_from_jwt_sub(_jwt_sub: String) -> String {
+    // wasm32 doesn't run the cold-start resolver natively; return an
+    // empty key so resolver self-disables. Mirrors the wasm stub for
+    // `derive_user_key_from_email` below.
+    String::new()
+}
+
+/// **DEPRECATED — broken for pre-migration-011 users.** Use
+/// [`derive_user_key_from_jwt_sub`] instead.
+///
+/// Apps that have already shipped using this function continue to
+/// work for post-migration users by accident (the SDK's internal
+/// `sha256(email)` step happens to match what those users' JWT sub
+/// already is). Pre-migration users hit a silent cold-start failure
+/// because their JWT sub is plaintext email and master hashes it
+/// without the sha256 step.
+///
+/// Same wire format and length (32 hex chars) as
+/// `derive_user_key_from_jwt_sub`; switching the call is a one-line
+/// app change.
 #[cfg(not(target_arch = "wasm32"))]
 pub fn derive_user_key_from_email(email: String) -> String {
     fula_client::derive_user_key_from_email(&email)

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

@@ -1058,20 +1058,38 @@ pub async fn is_flat_namespace(client: &EncryptedClient) -> bool {
 // Phase 3.3 — userKey derivation
 // ============================================================================
 
-/// Compute the canonical fula `userKey` for cold-start config from a
-/// plaintext email. Mirrors `fula_client::derive_user_key_from_email`
-/// — same domain separator + double-hash chain (sha256(lower(email))
-/// → BLAKE3("fula:user_id:" || _).bytes[..16] → hex).
+/// **PREFERRED** — derive the canonical fula `userKey` directly from a
+/// JWT `sub` claim. Mirrors `fula_client::derive_user_key_from_jwt_sub`
+/// and matches master's `state.rs::hash_user_id` byte-for-byte: the
+/// JWT sub bytes feed straight into `BLAKE3.derive_key`, no
+/// transformation.
 ///
-/// Apps call this once at sign-in (the OAuth flow has plaintext
-/// email), then set `users_index_user_key` on the config object
-/// passed to `createEncryptedClient`. The SDK never persists or
-/// transmits the raw email.
+/// Works correctly for BOTH pre-migration-011 users (sub = plaintext
+/// email) and post-migration users (sub = sha256(email).hex()). Apps
+/// should cache the JWT sub at sign-in and pass it here whenever
+/// (re-)setting `users_index_user_key`. The SDK never sees the raw
+/// email.
 ///
-/// On wasm32 the cold-start RESOLVER itself isn't wired (it depends
-/// on reqwest + parking_lot which aren't compiled for browsers), so
-/// this helper is exposed for API symmetry — apps can compute the
-/// userKey on web for sharing across native + web identity flows.
+/// Use this in preference to `deriveUserKeyFromEmail` — the email
+/// variant is broken for pre-migration users.
+#[wasm_bindgen(js_name = deriveUserKeyFromJwtSub)]
+pub fn derive_user_key_from_jwt_sub(jwt_sub: String) -> String {
+    fula_client::derive_user_key_from_jwt_sub(&jwt_sub)
+}
+
+/// **DEPRECATED — broken for pre-migration-011 users.** Use
+/// `deriveUserKeyFromJwtSub` instead.
+///
+/// Computes the userKey by first applying `sha256(email.lowercase())`
+/// before BLAKE3. This happens to match master ONLY for
+/// post-migration users whose JWT sub is itself `sha256(email).hex()`.
+/// For pre-migration users whose JWT sub is plaintext email, master's
+/// derivation skips the sha256 step and the two values diverge —
+/// silent cold-start failure.
+///
+/// On wasm32 the cold-start RESOLVER isn't wired (depends on reqwest
+/// + parking_lot which aren't compiled for browsers), so this helper
+/// remains exposed for API symmetry with the native binding.
 #[wasm_bindgen(js_name = deriveUserKeyFromEmail)]
 pub fn derive_user_key_from_email(email: String) -> String {
     fula_client::derive_user_key_from_email(&email)