updated some docs

Author: ehsan6sha

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

@@ -69,6 +69,12 @@ pub fn create_encrypted_client(
         ObfuscationMode::Random => {
             enc_config.with_obfuscation_mode(fula_client::KeyObfuscation::RandomUuid)
         }
+        ObfuscationMode::FlatNamespace => {
+            enc_config.with_obfuscation_mode(fula_client::KeyObfuscation::FlatNamespace)
+        }
+        ObfuscationMode::PreserveStructure => {
+            enc_config.with_obfuscation_mode(fula_client::KeyObfuscation::PreserveStructure)
+        }
     };
 
     let client = fula_client::EncryptedClient::new(inner_config, enc_config)?;
@@ -110,6 +116,20 @@ pub fn create_encrypted_client_with_pinning(
     };
 
     let enc_config = enc_config.with_metadata_privacy(encryption.enable_metadata_privacy);
+    let enc_config = match encryption.obfuscation_mode {
+        ObfuscationMode::Deterministic => {
+            enc_config.with_obfuscation_mode(fula_client::KeyObfuscation::DeterministicHash)
+        }
+        ObfuscationMode::Random => {
+            enc_config.with_obfuscation_mode(fula_client::KeyObfuscation::RandomUuid)
+        }
+        ObfuscationMode::FlatNamespace => {
+            enc_config.with_obfuscation_mode(fula_client::KeyObfuscation::FlatNamespace)
+        }
+        ObfuscationMode::PreserveStructure => {
+            enc_config.with_obfuscation_mode(fula_client::KeyObfuscation::PreserveStructure)
+        }
+    };
 
     let pinning_creds = fula_client::PinningCredentials::new(
         pinning.endpoint,

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

@@ -56,13 +56,35 @@ impl Default for EncryptionConfig {
 }
 
 /// Obfuscation mode for file name privacy
+///
+/// Controls how file paths are obfuscated before sending to the server.
+/// This affects what the server can learn about your file structure.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub enum ObfuscationMode {
-    /// Same input always produces same output (allows deduplication)
+    /// Hash the key with a secret prefix (deterministic - same key = same hash)
+    /// Allows server-side deduplication but reveals if same file uploaded twice.
+    /// Server sees: `e/a7c3f9b2e8d14a6f` (reveals "e/" prefix)
     #[default]
     Deterministic,
-    /// Random obfuscation (maximum privacy)
+    /// Random UUID for each upload (non-deterministic)
+    /// Maximum privacy but no dedup.
+    /// Server sees: `e/random-uuid-here`
     Random,
+    /// Flat namespace - complete structure hiding (RECOMMENDED)
+    ///
+    /// Inspired by WNFS and Peergos:
+    /// - All keys look like random CID-style hashes
+    /// - No prefixes or structure hints
+    /// - File tree stored in encrypted index (PrivateForest)
+    /// - Server cannot determine folder structure, parent/child relationships
+    ///
+    /// Server sees: `QmX7a8f3e2d1c9b4a5e6f7d8c9a0b1e2f3a4b5c6d7e8f9`
+    FlatNamespace,
+    /// Preserve path structure but hash filenames
+    /// e.g., "/photos/vacation/" + hash(filename)
+    /// Allows folder-like organization while hiding filenames.
+    /// Server sees: `/photos/vacation/e_a7c3f9b2`
+    PreserveStructure,
 }
 
 /// Configuration for IPFS pinning service

docs/website/sdk.html

@@ -883,10 +883,11 @@ <h3>Key Features</h3>
     maxRetries: 3,
   );
 
+  // FlatNamespace is RECOMMENDED for maximum privacy
   final encConfig = EncryptionConfig(
     secretKey: null, // Generate new key
     enableMetadataPrivacy: true,
-    obfuscationMode: ObfuscationMode.deterministic,
+    obfuscationMode: ObfuscationMode.flatNamespace,
   );
 
   final client = await createEncryptedClient(config, encConfig);
@@ -985,6 +986,36 @@ <h3>Key Features</h3>
   storageKey,
   acceptedShare,
 );</code></pre>
+
+                    <div class="example-header">
+                        <span class="lang-label">Obfuscation Modes</span>
+                        <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+                    </div>
+                    <pre><code class="language-dart">// Available obfuscation modes for metadata privacy:
+
+// FlatNamespace (RECOMMENDED) - complete structure hiding
+// Server sees: QmX7a8f3e2d1c9b4... (CID-like hash)
+final encConfig = EncryptionConfig(
+  obfuscationMode: ObfuscationMode.flatNamespace,
+);
+
+// Deterministic - same path = same hash (allows server deduplication)
+// Server sees: e/a7c3f9b2e8d14a6f
+final encConfig = EncryptionConfig(
+  obfuscationMode: ObfuscationMode.deterministic,
+);
+
+// Random - new UUID for each upload (max privacy, no dedup)
+// Server sees: e/random-uuid-here
+final encConfig = EncryptionConfig(
+  obfuscationMode: ObfuscationMode.random,
+);
+
+// PreserveStructure - keep folder paths, hash filenames only
+// Server sees: /photos/vacation/e_a7c3f9b2
+final encConfig = EncryptionConfig(
+  obfuscationMode: ObfuscationMode.preserveStructure,
+);</code></pre>
                 </div>
             </div>
         </section>

packages/fula_client/README.md

@@ -37,9 +37,10 @@ Future<void> main() async {
     accessToken: 'your-jwt-token',
   );
 
+  // FlatNamespace is RECOMMENDED for maximum privacy
   final encConfig = EncryptionConfig(
     enableMetadataPrivacy: true,
-    obfuscationMode: ObfuscationMode.deterministic,
+    obfuscationMode: ObfuscationMode.flatNamespace,
   );
 
   final client = await createEncryptedClient(config, encConfig);
@@ -134,6 +135,39 @@ application/wasm
 - `createRotationManager(client)` - Create key rotation manager
 - `rotateBucket(client, bucket, manager)` - Rotate all keys in bucket
 
+## Obfuscation Modes
+
+The SDK supports 4 obfuscation modes for metadata privacy:
+
+| Mode | Server Sees | Privacy Level | Use Case |
+|------|-------------|---------------|----------|
+| `flatNamespace` | `QmX7a8f3e2d1c9b4...` | **Highest** | Default, recommended |
+| `deterministic` | `e/a7c3f9b2e8d14a6f` | Medium | Server deduplication |
+| `random` | `e/random-uuid-here` | High | Max privacy, no dedup |
+| `preserveStructure` | `/photos/vacation/e_a7c3` | Low | Folder organization |
+
+```dart
+// FlatNamespace (RECOMMENDED) - complete structure hiding
+final encConfig = EncryptionConfig(
+  obfuscationMode: ObfuscationMode.flatNamespace,
+);
+
+// Deterministic - same file = same hash (allows deduplication)
+final encConfig = EncryptionConfig(
+  obfuscationMode: ObfuscationMode.deterministic,
+);
+
+// Random - new UUID for each upload (maximum privacy)
+final encConfig = EncryptionConfig(
+  obfuscationMode: ObfuscationMode.random,
+);
+
+// PreserveStructure - keep folder paths, hash filenames
+final encConfig = EncryptionConfig(
+  obfuscationMode: ObfuscationMode.preserveStructure,
+);
+```
+
 ## Documentation
 
 - [Full API Documentation](https://functionland.github.io/fula-api/)