Include encryption nonce in share tokens for proxy-based decryption

Author: ehsan6sha

Cargo.lock

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

Cargo.toml

@@ -1240,6 +1240,7 @@ impl EncryptedClient {
     ///
     /// # Note
     /// Handles both single-block and chunked files automatically.
+    /// Uses nonce from share token if available, otherwise falls back to metadata headers.
     pub async fn get_object_with_share(
         &self,
         bucket: &str,
@@ -1269,7 +1270,35 @@ impl EncryptedClient {
             ));
         }
 
-        // Fetch the object
+        // Check if share token includes encryption metadata (nonce or chunked info)
+        // If so, we can decrypt using just the raw data without needing S3 metadata headers
+        if accepted_share.chunked_metadata.is_some() {
+            // CHUNKED FILE: Use chunked metadata from share token
+            return self.get_object_chunked_with_share_token(bucket, storage_key, accepted_share).await;
+        }
+
+        if let Some(ref nonce_b64) = accepted_share.nonce {
+            // SINGLE FILE: Use nonce from share token - fetch raw data only
+            let data = self.inner.get_object(bucket, storage_key).await?;
+
+            let nonce_bytes = base64::Engine::decode(
+                &base64::engine::general_purpose::STANDARD,
+                nonce_b64,
+            ).map_err(|e| ClientError::Encryption(
+                fula_crypto::CryptoError::Decryption(format!("Invalid nonce in share token: {}", e))
+            ))?;
+            let nonce = Nonce::from_bytes(&nonce_bytes)
+                .map_err(ClientError::Encryption)?;
+
+            let aead = Aead::new_default(&accepted_share.dek);
+            let plaintext = aead.decrypt(&nonce, &data)
+                .map_err(ClientError::Encryption)?;
+
+            return Ok(Bytes::from(plaintext));
+        }
+
+        // FALLBACK: Share token doesn't have encryption metadata, try to get it from S3 headers
+        // This is for backwards compatibility with old share tokens
         let result = self.inner.get_object_with_metadata(bucket, storage_key).await?;
 
         // Check if encrypted
@@ -1288,11 +1317,11 @@ impl EncryptedClient {
             .map(|v| v == "true")
             .unwrap_or(false);
 
-        // Parse encryption metadata
+        // Parse encryption metadata from S3 headers
         let enc_metadata_str = result.metadata
             .get("x-fula-encryption")
             .ok_or_else(|| ClientError::Encryption(
-                fula_crypto::CryptoError::Decryption("Missing encryption metadata".to_string())
+                fula_crypto::CryptoError::Decryption("Missing encryption metadata (not in share token or S3 headers)".to_string())
             ))?;
 
         let enc_metadata: serde_json::Value = serde_json::from_str(enc_metadata_str)
@@ -1302,12 +1331,12 @@ impl EncryptedClient {
 
         if is_chunked {
             // CHUNKED DOWNLOAD: Download and decrypt each chunk using the share's DEK
-            self.get_object_chunked_with_share(bucket, storage_key, &enc_metadata, &accepted_share.dek).await
+            self.get_object_chunked_with_share_metadata(bucket, storage_key, &enc_metadata, &accepted_share.dek).await
         } else {
             // SINGLE OBJECT: Decrypt directly
             let nonce_b64 = enc_metadata["nonce"].as_str()
                 .ok_or_else(|| ClientError::Encryption(
-                    fula_crypto::CryptoError::Decryption("Missing nonce".to_string())
+                    fula_crypto::CryptoError::Decryption("Missing nonce in encryption metadata".to_string())
                 ))?;
             let nonce_bytes = base64::Engine::decode(
                 &base64::engine::general_purpose::STANDARD,
@@ -1327,8 +1356,46 @@ impl EncryptedClient {
         }
     }
 
-    /// Internal: Download and decrypt a chunked file using a share's DEK
-    async fn get_object_chunked_with_share(
+    /// Internal: Download and decrypt a chunked file using metadata from share token
+    async fn get_object_chunked_with_share_token(
+        &self,
+        bucket: &str,
+        storage_key: &str,
+        accepted_share: &AcceptedShare,
+    ) -> Result<Bytes> {
+        let chunked_json = accepted_share.chunked_metadata.as_ref()
+            .ok_or_else(|| ClientError::Encryption(
+                fula_crypto::CryptoError::Decryption("Missing chunked metadata in share token".to_string())
+            ))?;
+
+        let chunked_meta: ChunkedFileMetadata = serde_json::from_str(chunked_json)
+            .map_err(|e| ClientError::Encryption(
+                fula_crypto::CryptoError::Decryption(format!("Invalid chunked metadata in share token: {}", e))
+            ))?;
+
+        // Create decoder
+        let mut decoder = fula_crypto::ChunkedDecoder::new(accepted_share.dek.clone(), chunked_meta.clone());
+
+        // Pre-allocate result buffer
+        let mut plaintext = Vec::with_capacity(chunked_meta.total_size as usize);
+
+        // Download and decrypt each chunk in order
+        for chunk_index in 0..chunked_meta.num_chunks {
+            let chunk_key = ChunkedFileMetadata::chunk_key(storage_key, chunk_index);
+
+            let chunk_result = self.inner.get_object(bucket, &chunk_key).await?;
+
+            let chunk_plaintext = decoder.decrypt_chunk(chunk_index, &chunk_result)
+                .map_err(ClientError::Encryption)?;
+
+            plaintext.extend_from_slice(&chunk_plaintext);
+        }
+
+        Ok(Bytes::from(plaintext))
+    }
+
+    /// Internal: Download and decrypt a chunked file using metadata from S3 headers
+    async fn get_object_chunked_with_share_metadata(
         &self,
         bucket: &str,
         storage_key: &str,

crates/fula-client/src/encryption.rs

@@ -160,6 +160,13 @@ pub struct ShareToken {
     /// Snapshot binding (required for Snapshot mode)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub snapshot_binding: Option<SnapshotBinding>,
+    /// Encryption nonce (base64 encoded) - included so recipient can decrypt
+    /// without needing to fetch metadata headers from S3
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub nonce: Option<String>,
+    /// Chunked file metadata (JSON) - for files > 768KB that use per-chunk nonces
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub chunked_metadata: Option<String>,
 }
 
 impl ShareToken {
@@ -264,6 +271,10 @@ pub struct ShareBuilder<'a> {
     permissions: SharePermissions,
     mode: ShareMode,
     snapshot_binding: Option<SnapshotBinding>,
+    /// Encryption nonce (base64) for single-block files
+    nonce: Option<String>,
+    /// Chunked file metadata (JSON) for files > 768KB
+    chunked_metadata: Option<String>,
 }
 
 impl<'a> ShareBuilder<'a> {
@@ -282,9 +293,25 @@ impl<'a> ShareBuilder<'a> {
             permissions: SharePermissions::read_only(),
             mode: ShareMode::Temporal,
             snapshot_binding: None,
+            nonce: None,
+            chunked_metadata: None,
         }
     }
 
+    /// Set the encryption nonce (base64 encoded) for single-block files
+    /// This allows recipients to decrypt without needing S3 metadata headers
+    pub fn nonce(mut self, nonce_b64: impl Into<String>) -> Self {
+        self.nonce = Some(nonce_b64.into());
+        self
+    }
+
+    /// Set chunked file metadata (JSON) for files > 768KB
+    /// This allows recipients to decrypt chunked files without needing S3 metadata headers
+    pub fn chunked_metadata(mut self, metadata_json: impl Into<String>) -> Self {
+        self.chunked_metadata = Some(metadata_json.into());
+        self
+    }
+
     /// Set the path scope for this share
     pub fn path_scope(mut self, path: impl Into<String>) -> Self {
         self.path_scope = path.into();
@@ -381,9 +408,11 @@ impl<'a> ShareBuilder<'a> {
             expires_at: self.expires_at,
             created_at: current_timestamp(),
             permissions: self.permissions,
-            version: 2, // Bump version for new format with mode
+            version: 3, // Bump version for new format with nonce
             mode: self.mode,
             snapshot_binding: self.snapshot_binding,
+            nonce: self.nonce,
+            chunked_metadata: self.chunked_metadata,
         })
     }
 }
@@ -543,6 +572,8 @@ impl ShareRecipient {
             path_scope: token.path_scope.clone(),
             expires_at: token.expires_at,
             permissions: token.permissions,
+            nonce: token.nonce.clone(),
+            chunked_metadata: token.chunked_metadata.clone(),
         })
     }
 }
@@ -557,6 +588,10 @@ pub struct AcceptedShare {
     pub expires_at: Option<i64>,
     /// Permissions
     pub permissions: SharePermissions,
+    /// Encryption nonce (base64 encoded) - for single-block files
+    pub nonce: Option<String>,
+    /// Chunked file metadata (JSON) - for files > 768KB
+    pub chunked_metadata: Option<String>,
 }
 
 impl AcceptedShare {

crates/fula-crypto/src/sharing.rs

@@ -78,6 +78,18 @@ pub async fn create_share_token(
         builder = builder.expires_at(ts);
     }
 
+    // Include nonce in share token so recipient can decrypt without S3 metadata headers
+    if let Some(nonce_str) = enc_metadata["nonce"].as_str() {
+        builder = builder.nonce(nonce_str);
+    }
+
+    // Include chunked metadata for large files (> 768KB)
+    if enc_metadata.get("chunked").is_some() {
+        let chunked_json = serde_json::to_string(&enc_metadata["chunked"])
+            .map_err(|e| anyhow::anyhow!("Failed to serialize chunked metadata: {}", e))?;
+        builder = builder.chunked_metadata(chunked_json);
+    }
+
     let token = builder.build()
         .map_err(|e| anyhow::anyhow!("Failed to build share token: {}", e))?;
 
@@ -171,6 +183,22 @@ pub async fn create_share_token_with_mode(
         builder
     };
 
+    // Include nonce in share token so recipient can decrypt without S3 metadata headers
+    let builder = if let Some(nonce_str) = enc_metadata["nonce"].as_str() {
+        builder.nonce(nonce_str)
+    } else {
+        builder
+    };
+
+    // Include chunked metadata for large files (> 768KB)
+    let builder = if enc_metadata.get("chunked").is_some() {
+        let chunked_json = serde_json::to_string(&enc_metadata["chunked"])
+            .map_err(|e| anyhow::anyhow!("Failed to serialize chunked metadata: {}", e))?;
+        builder.chunked_metadata(chunked_json)
+    } else {
+        builder
+    };
+
     let token = builder.build()
         .map_err(|e| anyhow::anyhow!("Failed to build share token: {}", e))?;
 

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

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.17] - 2026-01-13
+
+### Fixed
+
+- **CRITICAL: Share tokens missing encryption nonce - decryption produces garbage**
+  - Share tokens only contained wrapped DEK but not the nonce needed for decryption
+  - Web UI proxy doesn't forward S3 metadata headers (`x-fula-encryption`)
+  - Without the nonce, decryption "succeeds" but produces garbage data
+  - **Fix**: Share tokens now include `nonce` (for single-block files) and `chunked_metadata` (for chunked files)
+  - Recipients can now decrypt using just the share token without needing S3 metadata headers
+
+### Changed
+
+- `ShareToken` struct now includes optional `nonce` and `chunked_metadata` fields
+- `ShareBuilder` has new `.nonce()` and `.chunked_metadata()` builder methods
+- `AcceptedShare` now carries nonce and chunked metadata through to decryption
+- `get_object_with_share` uses nonce from share token if available, falls back to S3 headers for backwards compatibility
+- Share token version bumped to 3
+
+### Migration Guide for FxFiles
+
+Share tokens created with v0.2.17+ will automatically include the nonce.
+No code changes needed - just rebuild FxFiles with the new fula_client SDK.
+
+Old share tokens (without nonce) will continue to work if the proxy forwards S3 headers correctly.
+
 ## [0.2.16] - 2026-01-13
 
 ### Fixed

packages/fula_client/CHANGELOG.md

@@ -6,7 +6,7 @@
 
 Pod::Spec.new do |s|
   s.name             = 'fula_client'
-  s.version          = '0.2.16'
+  s.version          = '0.2.17'
   s.summary          = 'Flutter SDK for Fula decentralized storage'
   s.description      = <<-DESC
     A Flutter plugin providing client-side encryption, metadata privacy,

packages/fula_client/ios/fula_client.podspec

@@ -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.16
+version: 0.2.17
 homepage: https://fx.land
 repository: https://github.com/functionland/fula-api
 issue_tracker: https://github.com/functionland/fula-api/issues