closed gaps in flutter and wasm for offline download

Author: ehsan6sha

crates/fula-client/Cargo.toml

@@ -35,6 +35,14 @@ url = "2.5"
 base64 = { workspace = true }
 hex = { workspace = true }
 blake3 = { workspace = true }
+# Phase 3.3 — `derive_user_key_from_email` lives in `src/user_key.rs`
+# and is exposed on every target (wasm + native) so the wasm-bindgen
+# binding can compute the user_key without round-tripping through
+# `fula-crypto::derive_key_argon2id`. sha2 is a pure-Rust dep that
+# builds cleanly on wasm32; was previously gated to native-only when
+# the helper still lived inside the native-gated `registry_resolver`
+# module, but with the helper extracted we need cross-target.
+sha2 = { workspace = true }
 mime_guess = "2.0"
 tokio = { version = "1.42", default-features = false, features = ["sync"] }
 dashmap = { workspace = true }
@@ -52,8 +60,6 @@ dirs = "5"
 # Native-only — wasm builds skip the cache (no persistent storage there anyway).
 redb = { workspace = true }
 cid = { workspace = true }
-# CID verification on gateway-fetched bytes (Phase 2.3 of master-independent reads).
-sha2 = { workspace = true }
 # Mutex for per-gateway state in gateway_fetch (Phase 2.3).
 parking_lot = { workspace = true }
 # Phase 3.3 cold-start hybrid resolver — parses the master-published

crates/fula-client/src/lib.rs

@@ -50,6 +50,11 @@ mod multipart;
 #[cfg(not(target_arch = "wasm32"))]
 mod registry_resolver;
 mod types;
+/// Phase 3.3 helper module — wasm-friendly userKey derivation
+/// extracted from `registry_resolver.rs` so the wasm-bindgen
+/// binding can expose it. Source-of-truth lives here; the
+/// resolver re-exports it on native.
+mod user_key;
 #[cfg(not(target_arch = "wasm32"))]
 mod orphan_queue;
 #[cfg(not(target_arch = "wasm32"))]
@@ -86,16 +91,24 @@ pub use types::*;
 /// callbacks without depending on internal module paths.
 pub use health_gate::{HealthCallback, MasterHealthEvent};
 
+/// 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 — cold-start hybrid resolver public API. Native-only;
 /// the resolver itself is gated to `cfg(not(target_arch = "wasm32"))`.
-/// The free helper `derive_user_key_from_email` is also re-exported
-/// so JS / Flutter bindings can compute the user_key without holding
-/// a client.
+/// `derive_user_key_from_email` is re-exported above (cross-target);
+/// callers using the `fula_client::registry_resolver::derive_user_key_from_email`
+/// path also still resolve through the in-module `pub use`.
 #[cfg(not(target_arch = "wasm32"))]
 pub use registry_resolver::{
     decode_user_buckets_index, default_ipfs_gateway_urls, default_ipns_gateway_urls,
-    derive_user_key_from_email, fetch_cid_via_gateways, BucketEntry, GlobalUsersIndex,
-    ResolutionSource, ResolvedUsersIndex, ResolverConfig, UserBucketsIndex, UsersIndexResolver,
+    fetch_cid_via_gateways, BucketEntry, GlobalUsersIndex, ResolutionSource,
+    ResolvedUsersIndex, ResolverConfig, UserBucketsIndex, UsersIndexResolver,
 };
 
 /// Process-wide count of WAL append failures (F11).

crates/fula-client/src/registry_resolver.rs

@@ -217,15 +217,15 @@ impl ResolverConfig {
 /// stay in lockstep with the master's `hash_user_id`; the
 /// `derive_user_key_matches_master_state_rs_algorithm` test below
 /// reproduces the master algorithm step-by-step and asserts equality.
-pub fn derive_user_key_from_email(email: &str) -> String {
-    use sha2::{Digest, Sha256};
-    let user_id_digest = Sha256::digest(email.to_lowercase().as_bytes());
-    let user_id_hex = hex::encode(user_id_digest);
-    let mut hasher = blake3::Hasher::new();
-    hasher.update(b"fula:user_id:");
-    hasher.update(user_id_hex.as_bytes());
-    hex::encode(&hasher.finalize().as_bytes()[..16])
-}
+///
+/// Source-of-truth lives in `crate::user_key` (extracted there so the
+/// wasm-bindgen binding can expose it — the `registry_resolver`
+/// module itself is gated to native targets). This re-export keeps
+/// the historical `fula_client::registry_resolver::derive_user_key_from_email`
+/// import path working for native callers AND lets the test module
+/// in this file (line 1485+) call the function via `use super::*;`.
+#[allow(unused_imports)]
+pub use crate::user_key::derive_user_key_from_email;
 
 /// Default IPNS-aware gateway list. Excludes
 /// `trustless-gateway.link` (only serves `/ipfs/`, not `/ipns/`).

crates/fula-client/src/user_key.rs

@@ -0,0 +1,48 @@
+//! 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`):**
+//!
+//! ```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] )
+//! ```
+//!
+//! 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.
+
+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).
+///
+/// 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.
+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);
+    let mut hasher = blake3::Hasher::new();
+    hasher.update(b"fula:user_id:");
+    hasher.update(user_id_hex.as_bytes());
+    hex::encode(&hasher.finalize().as_bytes()[..16])
+}

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

@@ -16,12 +16,19 @@ use async_lock::RwLock;
 use crate::api::types::*;
 
 /// Build the underlying `fula_client::Config` from the Dart-facing
-/// `FulaConfig`, plumbing every Phase 1.2 / 2.x field through. Used by
-/// `create_client`, `create_encrypted_client`, and
-/// `create_encrypted_client_with_pinning` to keep the three constructors
-/// in lockstep — adding a new field to FulaConfig only requires a
-/// change here.
-fn build_inner_config(config: &FulaConfig) -> fula_client::Config {
+/// `FulaConfig`, plumbing every Phase 1.2 / 2.x / 3.3 / 19 field
+/// through. Used by `create_client`, `create_encrypted_client`, and
+/// `create_encrypted_client_with_pinning` to keep the three
+/// constructors in lockstep — adding a new field to FulaConfig only
+/// requires a change here.
+///
+/// `dispatcher` is the per-handle dispatcher that the FRB layer
+/// always wires into `Config::health_callback` so apps can subscribe
+/// to `MasterHealthEvent` events via `subscribe_master_health_events`.
+fn build_inner_config(
+    config: &FulaConfig,
+    dispatcher: &Arc<HealthEventDispatcher>,
+) -> fula_client::Config {
     let mut inner = fula_client::Config::new(&config.endpoint)
         .with_timeout(Duration::from_secs(config.timeout_seconds));
 
@@ -50,6 +57,45 @@ fn build_inner_config(config: &FulaConfig) -> fula_client::Config {
     inner.gateway_fallback_urls = config.gateway_fallback_urls.clone();
     inner.gateway_race_concurrency = config.gateway_race_concurrency as usize;
 
+    // Phase 3.3 — cold-start hybrid resolver. The resolver activates
+    // iff all four required strings (rpc_url, anchor_address,
+    // ipns_name, user_key) are non-empty AND the user_key is `Some`.
+    // Empty strings collapse to "disabled" — same default behavior as
+    // pre-Phase-3.3 builds.
+    inner.users_index_chain_rpc_url = config.users_index_chain_rpc_url.clone();
+    inner.users_index_anchor_address = config.users_index_anchor_address.clone();
+    inner.users_index_ipns_name = config.users_index_ipns_name.clone();
+    inner.users_index_user_key = if config.users_index_user_key.is_empty() {
+        None
+    } else {
+        Some(config.users_index_user_key.clone())
+    };
+    inner.users_index_ipns_gateway_urls =
+        config.users_index_ipns_gateway_urls.clone();
+    inner.users_index_ipfs_gateway_urls =
+        config.users_index_ipfs_gateway_urls.clone();
+
+    // Phase 19 — always wire a forwarding callback into the gate so
+    // Dart-side subscribers can observe health transitions. The
+    // dispatcher is per-handle, so events from this client never
+    // leak to a different client's subscribers. Native-only — wasm
+    // doesn't include the health-callback Arc in fula_client::Config
+    // because `Arc<dyn Fn>` doesn't cross wasm-bindgen cleanly; the
+    // wasm path surfaces via typed errors.
+    #[cfg(not(target_arch = "wasm32"))]
+    {
+        let dispatcher = Arc::clone(dispatcher);
+        let cb: fula_client::HealthCallback = Arc::new(move |ev| {
+            dispatcher.dispatch(ev);
+        });
+        inner.health_callback = Some(cb);
+    }
+    // Suppress unused-variable warning on wasm where we don't read
+    // `dispatcher` at config-build time (subscribers still register;
+    // they just never receive events because no callback fires).
+    #[cfg(target_arch = "wasm32")]
+    let _ = dispatcher;
+
     if let Some(token) = &config.access_token {
         inner = inner.with_token(token.clone());
     }
@@ -63,11 +109,13 @@ fn build_inner_config(config: &FulaConfig) -> fula_client::Config {
 
 /// Create a new Fula client with the given configuration
 pub fn create_client(config: FulaConfig) -> anyhow::Result<FulaClientHandle> {
-    let inner_config = build_inner_config(&config);
+    let dispatcher = Arc::new(HealthEventDispatcher::new());
+    let inner_config = build_inner_config(&config, &dispatcher);
     let client = fula_client::FulaClient::new(inner_config)?;
 
     Ok(FulaClientHandle {
         inner: Arc::new(client),
+        health_dispatcher: dispatcher,
     })
 }
 
@@ -76,7 +124,8 @@ pub fn create_encrypted_client(
     config: FulaConfig,
     encryption: EncryptionConfig,
 ) -> anyhow::Result<EncryptedClientHandle> {
-    let inner_config = build_inner_config(&config);
+    let dispatcher = Arc::new(HealthEventDispatcher::new());
+    let inner_config = build_inner_config(&config, &dispatcher);
 
     // Create encryption config
     let enc_config = if let Some(secret_key) = encryption.secret_key {
@@ -113,6 +162,7 @@ pub fn create_encrypted_client(
 
     Ok(EncryptedClientHandle {
         inner: Arc::new(RwLock::new(client)),
+        health_dispatcher: dispatcher,
     })
 }
 
@@ -122,7 +172,8 @@ pub fn create_encrypted_client_with_pinning(
     encryption: EncryptionConfig,
     pinning: PinningConfig,
 ) -> anyhow::Result<EncryptedClientHandle> {
-    let inner_config = build_inner_config(&config);
+    let dispatcher = Arc::new(HealthEventDispatcher::new());
+    let inner_config = build_inner_config(&config, &dispatcher);
 
     // Create encryption config
     let enc_config = if let Some(secret_key) = encryption.secret_key {
@@ -168,9 +219,137 @@ pub fn create_encrypted_client_with_pinning(
 
     Ok(EncryptedClientHandle {
         inner: Arc::new(RwLock::new(client)),
+        health_dispatcher: dispatcher,
     })
 }
 
+// ============================================================================
+// Phase 3.3 — derive_user_key_from_email
+// ============================================================================
+
+/// 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).
+///
+/// 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.
+///
+/// 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.
+#[cfg(not(target_arch = "wasm32"))]
+pub fn derive_user_key_from_email(email: String) -> String {
+    fula_client::derive_user_key_from_email(&email)
+}
+
+#[cfg(target_arch = "wasm32")]
+pub fn derive_user_key_from_email(_email: String) -> String {
+    // The Rust cold-start resolver isn't wired on wasm32; expose
+    // the function for API symmetry but emit an empty key so the
+    // resolver self-disables (per build_inner_config: empty user_key
+    // → users_index_user_key=None → resolver inactive).
+    String::new()
+}
+
+// ============================================================================
+// Phase 19 — health-event subscription
+// ============================================================================
+
+/// Drain every `MasterHealthEvent` observed since the last call to
+/// this function. Returns events in the order they fired (oldest
+/// first). After draining the buffer is empty.
+///
+/// Apps poll this on a timer (or on UI rebuilds) and update their
+/// online/offline indicator. Internal buffer is bounded at 64
+/// entries — if an app falls so far behind that the buffer
+/// overflows, the oldest events are dropped first; the latest state
+/// is preserved. For latest-only consumers, see
+/// [`get_last_master_health_event`].
+///
+/// Events delivered:
+///   - `Online` — master went Up after being Down
+///   - `OfflineFallbackActive { reason }` — master went Down
+///   - `SeverelyDegraded { reason }` — both master AND cold-start
+///     channels (IPNS + chain) are unreachable; cold-start GETs
+///     will fail
+///
+/// Native-only at runtime: on wasm32 the function compiles for API
+/// symmetry but never returns events because the health-callback
+/// Arc isn't wired on wasm (`Arc<dyn Fn>` doesn't cross
+/// wasm-bindgen cleanly).
+pub fn poll_master_health_events(
+    client: &FulaClientHandle,
+) -> Vec<MasterHealthEvent> {
+    client.health_dispatcher.drain_events()
+}
+
+/// Same as `poll_master_health_events` for an `EncryptedClientHandle`.
+/// Exposed separately because Dart-side the encrypted client has
+/// its own handle type and FRB doesn't auto-reflect "this method
+/// works on either handle".
+pub fn poll_master_health_events_encrypted(
+    client: &EncryptedClientHandle,
+) -> Vec<MasterHealthEvent> {
+    client.health_dispatcher.drain_events()
+}
+
+/// Read the most recent `MasterHealthEvent` observed by the SDK
+/// without draining the buffer. Returns `None` if no transition has
+/// happened yet (master has been Up the whole session). Useful for
+/// apps that build UI state from a single field on mount.
+pub fn get_last_master_health_event(
+    client: &FulaClientHandle,
+) -> Option<MasterHealthEvent> {
+    client.health_dispatcher.last_event()
+}
+
+/// Encrypted-client variant of `get_last_master_health_event`.
+pub fn get_last_master_health_event_encrypted(
+    client: &EncryptedClientHandle,
+) -> Option<MasterHealthEvent> {
+    client.health_dispatcher.last_event()
+}
+
+// ============================================================================
+// Phase 19 — get_object_with_offline_fallback
+// ============================================================================
+
+/// Phase 19 GET wrapper that returns transparency fields alongside
+/// the bytes. Routes through the SDK's full Phase 2.x + 3.3 stack:
+///
+/// | State                             | Returns                                   |
+/// |-----------------------------------|-------------------------------------------|
+/// | Master up                         | source = Master, freshness = Live         |
+/// | Master down + warm cache hit      | source = LocalCache or Gateway(url),      |
+/// |                                   | freshness = Cached { observed_at }        |
+/// | Master down + cold-start          | source = Gateway(url),                    |
+/// |                                   | freshness = Cached { observed_at }        |
+/// | Master down + cache miss + no     | Err(UsersIndexResolutionFailed)           |
+/// | resolver configured               |                                           |
+///
+/// Apps that don't care about transparency can read `result.inner.data`.
+/// Apps that surface "you're offline" UI inspect `result.source` /
+/// `result.freshness`.
+///
+/// Native-only at runtime: on wasm32 the SDK currently only wraps
+/// `get_object_with_metadata` (no offline fallback infrastructure on
+/// browsers — block_cache + gateway_fetch are gated out). The wasm
+/// path returns `OfflineGetResult` with `source = Master, freshness =
+/// Live` so the API shape is identical across platforms.
+pub async fn get_object_with_offline_fallback(
+    client: &FulaClientHandle,
+    bucket: String,
+    key: String,
+) -> anyhow::Result<OfflineGetResult> {
+    let result = client
+        .inner
+        .get_object_with_offline_fallback(&bucket, &key)
+        .await?;
+    Ok(result.into())
+}
+
 // ============================================================================
 // Bucket Operations
 // ============================================================================