added metadata encryption

Author: ehsan6sha

README.md

@@ -233,6 +233,9 @@ cargo run --example security_verification
 # Sharing Demo
 cargo run --example sharing_demo
 
+# Metadata Privacy
+cargo run --example metadata_privacy
+
 ```
 
 ## Security

crates/fula-client/src/encryption.rs

@@ -1,36 +1,77 @@
 //! Client-side encryption support
+//!
+//! Provides end-to-end encryption for Fula storage including:
+//! - Content encryption (AES-256-GCM)
+//! - Key wrapping (HPKE)
+//! - Metadata privacy (file names, sizes, timestamps)
 
 use crate::{ClientError, FulaClient, Result, Config};
 use crate::types::*;
 use bytes::Bytes;
 use fula_crypto::{
-    keys::{KeyManager},
+    keys::KeyManager,
     hpke::{Encryptor, Decryptor, EncryptedData},
     symmetric::{Aead, Nonce},
+    private_metadata::{PrivateMetadata, EncryptedPrivateMetadata, KeyObfuscation, obfuscate_key},
 };
 use std::sync::Arc;
+use std::collections::HashMap;
 
 /// Configuration for client-side encryption
 pub struct EncryptionConfig {
     /// Key manager for encryption keys (wrapped in Arc for sharing)
     key_manager: Arc<KeyManager>,
+    /// Whether to enable metadata privacy (file name obfuscation)
+    metadata_privacy: bool,
+    /// Key obfuscation mode
+    obfuscation_mode: KeyObfuscation,
 }
 
 impl EncryptionConfig {
-    /// Create with a new random key
+    /// Create with a new random key (metadata privacy enabled by default)
     pub fn new() -> Self {
         Self {
             key_manager: Arc::new(KeyManager::new()),
+            metadata_privacy: true,
+            obfuscation_mode: KeyObfuscation::DeterministicHash,
+        }
+    }
+
+    /// Create without metadata privacy (filenames visible to server)
+    pub fn new_without_privacy() -> Self {
+        Self {
+            key_manager: Arc::new(KeyManager::new()),
+            metadata_privacy: false,
+            obfuscation_mode: KeyObfuscation::DeterministicHash,
         }
     }
 
     /// Create from an existing secret key
     pub fn from_secret_key(secret: fula_crypto::keys::SecretKey) -> Self {
         Self {
             key_manager: Arc::new(KeyManager::from_secret_key(secret)),
+            metadata_privacy: true,
+            obfuscation_mode: KeyObfuscation::DeterministicHash,
         }
     }
 
+    /// Enable or disable metadata privacy
+    pub fn with_metadata_privacy(mut self, enabled: bool) -> Self {
+        self.metadata_privacy = enabled;
+        self
+    }
+
+    /// Set the key obfuscation mode
+    pub fn with_obfuscation_mode(mut self, mode: KeyObfuscation) -> Self {
+        self.obfuscation_mode = mode;
+        self
+    }
+
+    /// Check if metadata privacy is enabled
+    pub fn has_metadata_privacy(&self) -> bool {
+        self.metadata_privacy
+    }
+
     /// Get the public key for sharing
     pub fn public_key(&self) -> &fula_crypto::keys::PublicKey {
         self.key_manager.public_key()
@@ -40,6 +81,11 @@ impl EncryptionConfig {
     pub fn export_secret_key(&self) -> &fula_crypto::keys::SecretKey {
         self.key_manager.keypair().secret_key()
     }
+
+    /// Get the key manager
+    pub fn key_manager(&self) -> &KeyManager {
+        &self.key_manager
+    }
 }
 
 impl Default for EncryptionConfig {
@@ -71,14 +117,16 @@ impl EncryptedClient {
         &self.encryption
     }
 
-    /// Put an encrypted object
-    pub async fn put_object_encrypted(
+    /// Put an encrypted object with optional content type
+    pub async fn put_object_encrypted_with_type(
         &self,
         bucket: &str,
         key: &str,
         data: impl Into<Bytes>,
+        content_type: Option<&str>,
     ) -> Result<PutObjectResult> {
         let data = data.into();
+        let original_size = data.len() as u64;
 
         // Generate a DEK for this object
         let dek = self.encryption.key_manager.generate_dek();
@@ -94,35 +142,102 @@ impl EncryptedClient {
         let wrapped_dek = encryptor.encrypt_dek(&dek)
             .map_err(ClientError::Encryption)?;
 
+        // Determine the storage key and metadata based on privacy settings
+        let (storage_key, private_metadata_json) = if self.encryption.metadata_privacy {
+            // Create private metadata with original info
+            let private_meta = PrivateMetadata::new(key, original_size)
+                .with_content_type(content_type.unwrap_or("application/octet-stream"));
+            
+            // Encrypt private metadata with the per-file DEK
+            let encrypted_meta = EncryptedPrivateMetadata::encrypt(&private_meta, &dek)
+                .map_err(ClientError::Encryption)?;
+            
+            // Generate obfuscated storage key using PATH-DERIVED DEK (not per-file DEK)
+            // This ensures we can compute the same storage key later for retrieval
+            let path_dek = self.encryption.key_manager.derive_path_key(key);
+            let storage_key = obfuscate_key(key, &path_dek, self.encryption.obfuscation_mode.clone());
+            
+            (storage_key, Some(encrypted_meta.to_json().map_err(ClientError::Encryption)?))
+        } else {
+            (key.to_string(), None)
+        };
+
         // Serialize encryption metadata
-        let enc_metadata = serde_json::json!({
-            "version": 1,
+        let mut enc_metadata = serde_json::json!({
+            "version": 2,
             "algorithm": "AES-256-GCM",
             "nonce": base64::Engine::encode(&base64::engine::general_purpose::STANDARD, nonce.as_bytes()),
             "wrapped_key": serde_json::to_value(&wrapped_dek).unwrap(),
+            "metadata_privacy": self.encryption.metadata_privacy,
         });
 
-        // Upload with encryption metadata
+        // Add encrypted private metadata if enabled
+        if let Some(private_meta) = private_metadata_json {
+            enc_metadata["private_metadata"] = serde_json::Value::String(private_meta);
+        }
+
+        // Upload with encryption metadata (server sees obfuscated key)
         let metadata = ObjectMetadata::new()
-            .with_content_type("application/octet-stream")
+            .with_content_type("application/octet-stream") // Server always sees generic type
             .with_metadata("x-fula-encrypted", "true")
             .with_metadata("x-fula-encryption", &enc_metadata.to_string());
 
         self.inner.put_object_with_metadata(
             bucket,
-            key,
+            &storage_key,
             Bytes::from(ciphertext),
             Some(metadata),
         ).await
     }
 
-    /// Get and decrypt an object
+    /// Put an encrypted object (convenience method)
+    pub async fn put_object_encrypted(
+        &self,
+        bucket: &str,
+        key: &str,
+        data: impl Into<Bytes>,
+    ) -> Result<PutObjectResult> {
+        self.put_object_encrypted_with_type(bucket, key, data, None).await
+    }
+
+    /// Get and decrypt an object using the original key
+    /// 
+    /// If metadata privacy is enabled, this will automatically compute the
+    /// storage key from the original key using deterministic hashing.
     pub async fn get_object_decrypted(
         &self,
         bucket: &str,
         key: &str,
     ) -> Result<Bytes> {
-        let result = self.inner.get_object_with_metadata(bucket, key).await?;
+        // For metadata privacy, we need to find the storage key
+        // Since we use deterministic hashing, we can compute it
+        // But we need the DEK first, which creates a chicken-and-egg problem
+        // 
+        // Solution: If metadata privacy is enabled, we use the path-derived DEK
+        // to compute the storage key, fetch the object, then use the wrapped DEK
+        // to decrypt the actual data.
+        
+        let storage_key = if self.encryption.metadata_privacy {
+            // Use a path-derived DEK for key obfuscation lookup
+            let path_dek = self.encryption.key_manager.derive_path_key(key);
+            obfuscate_key(key, &path_dek, self.encryption.obfuscation_mode.clone())
+        } else {
+            key.to_string()
+        };
+
+        self.get_object_decrypted_by_storage_key(bucket, &storage_key).await
+    }
+
+    /// Get and decrypt an object using the storage key directly
+    /// 
+    /// Use this when you already have the obfuscated storage key
+    /// (e.g., from list_objects_decrypted)
+    pub async fn get_object_decrypted_by_storage_key(
+        &self,
+        bucket: &str,
+        storage_key: &str,
+    ) -> Result<Bytes> {
+        let result = self.inner.get_object_with_metadata(bucket, storage_key).await?;
 
         // Check if object is encrypted
         let is_encrypted = result.metadata
@@ -179,6 +294,94 @@ impl EncryptedClient {
         Ok(Bytes::from(plaintext))
     }
 
+    /// Decrypted object info with private metadata
+    pub async fn get_object_with_private_metadata(
+        &self,
+        bucket: &str,
+        storage_key: &str,
+    ) -> Result<DecryptedObjectInfo> {
+        let result = self.inner.get_object_with_metadata(bucket, storage_key).await?;
+        
+        let is_encrypted = result.metadata
+            .get("x-fula-encrypted")
+            .map(|v| v == "true")
+            .unwrap_or(false);
+
+        if !is_encrypted {
+            let size = result.data.len() as u64;
+            return Ok(DecryptedObjectInfo {
+                data: result.data,
+                original_key: storage_key.to_string(),
+                original_size: size,
+                content_type: result.metadata.get("content-type").cloned(),
+                user_metadata: HashMap::new(),
+            });
+        }
+
+        let enc_metadata_str = result.metadata
+            .get("x-fula-encryption")
+            .ok_or_else(|| ClientError::Encryption(
+                fula_crypto::CryptoError::Decryption("Missing encryption metadata".to_string())
+            ))?;
+
+        let enc_metadata: serde_json::Value = serde_json::from_str(enc_metadata_str)
+            .map_err(|e| ClientError::Encryption(
+                fula_crypto::CryptoError::Decryption(e.to_string())
+            ))?;
+
+        // Unwrap the DEK
+        let wrapped_key: EncryptedData = serde_json::from_value(
+            enc_metadata["wrapped_key"].clone()
+        ).map_err(|e| ClientError::Encryption(
+            fula_crypto::CryptoError::Decryption(e.to_string())
+        ))?;
+
+        let decryptor = Decryptor::new(self.encryption.key_manager.keypair());
+        let dek = decryptor.decrypt_dek(&wrapped_key)
+            .map_err(ClientError::Encryption)?;
+
+        // Decrypt data
+        let nonce_b64 = enc_metadata["nonce"].as_str().unwrap();
+        let nonce_bytes = base64::Engine::decode(
+            &base64::engine::general_purpose::STANDARD,
+            nonce_b64,
+        ).map_err(|e| ClientError::Encryption(
+            fula_crypto::CryptoError::Decryption(e.to_string())
+        ))?;
+        let nonce = Nonce::from_bytes(&nonce_bytes)
+            .map_err(ClientError::Encryption)?;
+
+        let aead = Aead::new_default(&dek);
+        let plaintext = aead.decrypt(&nonce, &result.data)
+            .map_err(ClientError::Encryption)?;
+
+        // Decrypt private metadata if present
+        let (original_key, original_size, content_type, user_metadata) = 
+            if let Some(private_meta_str) = enc_metadata["private_metadata"].as_str() {
+                let encrypted_meta = EncryptedPrivateMetadata::from_json(private_meta_str)
+                    .map_err(ClientError::Encryption)?;
+                let private_meta = encrypted_meta.decrypt(&dek)
+                    .map_err(ClientError::Encryption)?;
+                
+                (
+                    private_meta.original_key,
+                    private_meta.actual_size,
+                    private_meta.content_type,
+                    private_meta.user_metadata,
+                )
+            } else {
+                (storage_key.to_string(), plaintext.len() as u64, None, HashMap::new())
+            };
+
+        Ok(DecryptedObjectInfo {
+            data: Bytes::from(plaintext),
+            original_key,
+            original_size,
+            content_type,
+            user_metadata,
+        })
+    }
+
     // Delegate non-encrypted operations to inner client
 
     /// List buckets
@@ -196,7 +399,7 @@ impl EncryptedClient {
         self.inner.delete_bucket(bucket).await
     }
 
-    /// List objects
+    /// List objects (returns obfuscated keys if metadata privacy is enabled)
     pub async fn list_objects(
         &self,
         bucket: &str,
@@ -205,12 +408,38 @@ impl EncryptedClient {
         self.inner.list_objects(bucket, options).await
     }
 
-    /// Delete object
+    /// Delete object using original key
     pub async fn delete_object(&self, bucket: &str, key: &str) -> Result<()> {
-        self.inner.delete_object(bucket, key).await
+        let storage_key = if self.encryption.metadata_privacy {
+            let path_dek = self.encryption.key_manager.derive_path_key(key);
+            obfuscate_key(key, &path_dek, self.encryption.obfuscation_mode.clone())
+        } else {
+            key.to_string()
+        };
+        self.inner.delete_object(bucket, &storage_key).await
+    }
+
+    /// Delete object using storage key directly
+    pub async fn delete_object_by_storage_key(&self, bucket: &str, storage_key: &str) -> Result<()> {
+        self.inner.delete_object(bucket, storage_key).await
     }
 }
 
+/// Decrypted object information including private metadata
+#[derive(Debug, Clone)]
+pub struct DecryptedObjectInfo {
+    /// Decrypted file data
+    pub data: Bytes,
+    /// Original file name/path (decrypted from private metadata)
+    pub original_key: String,
+    /// Original file size (not ciphertext size)
+    pub original_size: u64,
+    /// Original content type
+    pub content_type: Option<String>,
+    /// User-defined metadata
+    pub user_metadata: HashMap<String, String>,
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/fula-client/src/lib.rs

@@ -46,7 +46,10 @@ mod types;
 
 pub use client::FulaClient;
 pub use config::Config;
-pub use encryption::{EncryptedClient, EncryptionConfig};
+pub use encryption::{EncryptedClient, EncryptionConfig, DecryptedObjectInfo};
 pub use error::{ClientError, Result};
 pub use multipart::{MultipartUpload, UploadProgress, ProgressCallback, upload_large_file};
 pub use types::*;
+
+// Re-export useful crypto types for encryption configuration
+pub use fula_crypto::private_metadata::KeyObfuscation;