claude-mpm 5.4.55__py3-none-any.whl → 5.4.85__py3-none-any.whl

claude_mpm/skills/bundled/tauri/tauri-file-system.md

@@ -0,0 +1,673 @@
+---
+name: tauri-file-system
+description: Safe file system operations in Tauri including path validation, file dialogs, directory operations, and secure file access patterns
+version: 1.0.0
+category: development
+author: Claude MPM Team
+license: MIT
+progressive_disclosure:
+  entry_point:
+    summary: "Secure file operations: path validation, scoped access, file dialogs, directory management, safe read/write patterns"
+    when_to_use: "When implementing file operations, document management, or any file system access in Tauri apps"
+    quick_start: "1. Configure fs allowlist 2. Validate paths 3. Use app directories 4. Implement dialogs 5. Handle errors"
+context_limit: 600
+tags:
+  - tauri
+  - filesystem
+  - security
+  - file-operations
+  - path-validation
+requires_tools: []
+---
+
+# Tauri File System Operations
+
+## Security Configuration
+
+### Allowlist Setup
+
+```json
+// src-tauri/tauri.conf.json
+{
+  "tauri": {
+    "allowlist": {
+      "fs": {
+        "all": false,
+        "readFile": true,
+        "writeFile": true,
+        "readDir": true,
+        "createDir": true,
+        "removeFile": true,
+        "removeDir": true,
+        "renameFile": true,
+        "exists": true,
+        "scope": [
+          "$APPDATA/**",
+          "$DOCUMENT/**",
+          "$DOWNLOAD/**",
+          "$HOME/Documents/**"
+        ]
+      }
+    }
+  }
+}
+```
+
+**Path Variables**:
+- `$APPDATA` - Application data directory
+- `$DOCUMENT` - User documents directory
+- `$DOWNLOAD` - User downloads directory
+- `$HOME` - User home directory
+- `$TEMP` - Temporary directory
+
+## Safe Path Handling
+
+### Path Validation Pattern
+
+```rust
+use std::path::{Path, PathBuf};
+
+fn validate_path(base_dir: &Path, user_path: &str) -> Result<PathBuf, String> {
+    // Resolve the path
+    let full_path = base_dir.join(user_path);
+
+    // Canonicalize to resolve .. and symlinks
+    let canonical = full_path.canonicalize()
+        .map_err(|e| format!("Invalid path: {}", e))?;
+
+    // CRITICAL: Ensure path is within base directory
+    if !canonical.starts_with(base_dir) {
+        return Err("Path traversal attempt detected".to_string());
+    }
+
+    Ok(canonical)
+}
+
+#[tauri::command]
+async fn read_app_file(
+    filename: String,
+    app: tauri::AppHandle,
+) -> Result<String, String> {
+    let app_dir = app.path_resolver()
+        .app_data_dir()
+        .ok_or("Failed to get app data dir")?;
+
+    let safe_path = validate_path(&app_dir, &filename)?;
+
+    tokio::fs::read_to_string(safe_path)
+        .await
+        .map_err(|e| e.to_string())
+}
+```
+
+### App Directory Helpers
+
+```rust
+use tauri::Manager;
+
+#[tauri::command]
+async fn get_app_paths(app: tauri::AppHandle) -> Result<AppPaths, String> {
+    let resolver = app.path_resolver();
+
+    Ok(AppPaths {
+        app_data: resolver.app_data_dir()
+            .map(|p| p.to_string_lossy().to_string()),
+        app_config: resolver.app_config_dir()
+            .map(|p| p.to_string_lossy().to_string()),
+        app_cache: resolver.app_cache_dir()
+            .map(|p| p.to_string_lossy().to_string()),
+        app_log: resolver.app_log_dir()
+            .map(|p| p.to_string_lossy().to_string()),
+    })
+}
+
+#[derive(serde::Serialize)]
+struct AppPaths {
+    app_data: Option<String>,
+    app_config: Option<String>,
+    app_cache: Option<String>,
+    app_log: Option<String>,
+}
+```
+
+## File Operations
+
+### Reading Files
+
+```rust
+use tokio::fs;
+
+#[tauri::command]
+async fn read_document(
+    filename: String,
+    app: tauri::AppHandle,
+) -> Result<String, String> {
+    let app_data = app.path_resolver()
+        .app_data_dir()
+        .ok_or("Failed to get app data dir")?;
+
+    let file_path = validate_path(&app_data, &filename)?;
+
+    // Check if file exists
+    if !file_path.exists() {
+        return Err(format!("File not found: {}", filename));
+    }
+
+    // Read file
+    fs::read_to_string(file_path)
+        .await
+        .map_err(|e| format!("Failed to read file: {}", e))
+}
+
+#[tauri::command]
+async fn read_binary_file(
+    filename: String,
+    app: tauri::AppHandle,
+) -> Result<Vec<u8>, String> {
+    let app_data = app.path_resolver()
+        .app_data_dir()
+        .ok_or("Failed to get app data dir")?;
+
+    let file_path = validate_path(&app_data, &filename)?;
+
+    fs::read(file_path)
+        .await
+        .map_err(|e| e.to_string())
+}
+```
+
+### Writing Files
+
+```rust
+#[tauri::command]
+async fn save_document(
+    filename: String,
+    content: String,
+    app: tauri::AppHandle,
+) -> Result<(), String> {
+    let app_data = app.path_resolver()
+        .app_data_dir()
+        .ok_or("Failed to get app data dir")?;
+
+    // Ensure directory exists
+    fs::create_dir_all(&app_data)
+        .await
+        .map_err(|e| format!("Failed to create directory: {}", e))?;
+
+    let file_path = validate_path(&app_data, &filename)?;
+
+    // Write file
+    fs::write(file_path, content)
+        .await
+        .map_err(|e| format!("Failed to write file: {}", e))
+}
+
+#[tauri::command]
+async fn append_to_file(
+    filename: String,
+    content: String,
+    app: tauri::AppHandle,
+) -> Result<(), String> {
+    use tokio::io::AsyncWriteExt;
+
+    let app_data = app.path_resolver()
+        .app_data_dir()
+        .ok_or("Failed to get app data dir")?;
+
+    let file_path = validate_path(&app_data, &filename)?;
+
+    let mut file = fs::OpenOptions::new()
+        .append(true)
+        .create(true)
+        .open(file_path)
+        .await
+        .map_err(|e| e.to_string())?;
+
+    file.write_all(content.as_bytes())
+        .await
+        .map_err(|e| e.to_string())?;
+
+    Ok(())
+}
+```
+
+## Directory Operations
+
+### Listing Directories
+
+```rust
+#[derive(serde::Serialize)]
+struct FileEntry {
+    name: String,
+    path: String,
+    is_dir: bool,
+    size: u64,
+    modified: Option<u64>,
+}
+
+#[tauri::command]
+async fn list_directory(
+    directory: String,
+    app: tauri::AppHandle,
+) -> Result<Vec<FileEntry>, String> {
+    let app_data = app.path_resolver()
+        .app_data_dir()
+        .ok_or("Failed to get app data dir")?;
+
+    let dir_path = validate_path(&app_data, &directory)?;
+
+    let mut entries = Vec::new();
+    let mut read_dir = fs::read_dir(dir_path)
+        .await
+        .map_err(|e| e.to_string())?;
+
+    while let Some(entry) = read_dir.next_entry()
+        .await
+        .map_err(|e| e.to_string())? {
+
+        let metadata = entry.metadata()
+            .await
+            .map_err(|e| e.to_string())?;
+
+        let modified = metadata.modified()
+            .ok()
+            .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
+            .map(|d| d.as_secs());
+
+        entries.push(FileEntry {
+            name: entry.file_name().to_string_lossy().to_string(),
+            path: entry.path().to_string_lossy().to_string(),
+            is_dir: metadata.is_dir(),
+            size: metadata.len(),
+            modified,
+        });
+    }
+
+    Ok(entries)
+}
+```
+
+### Creating Directories
+
+```rust
+#[tauri::command]
+async fn create_directory(
+    directory: String,
+    app: tauri::AppHandle,
+) -> Result<(), String> {
+    let app_data = app.path_resolver()
+        .app_data_dir()
+        .ok_or("Failed to get app data dir")?;
+
+    let dir_path = validate_path(&app_data, &directory)?;
+
+    fs::create_dir_all(dir_path)
+        .await
+        .map_err(|e| format!("Failed to create directory: {}", e))
+}
+
+#[tauri::command]
+async fn remove_directory(
+    directory: String,
+    recursive: bool,
+    app: tauri::AppHandle,
+) -> Result<(), String> {
+    let app_data = app.path_resolver()
+        .app_data_dir()
+        .ok_or("Failed to get app data dir")?;
+
+    let dir_path = validate_path(&app_data, &directory)?;
+
+    if recursive {
+        fs::remove_dir_all(dir_path)
+            .await
+            .map_err(|e| e.to_string())
+    } else {
+        fs::remove_dir(dir_path)
+            .await
+            .map_err(|e| e.to_string())
+    }
+}
+```
+
+## File Dialogs
+
+### Open File Dialog
+
+```rust
+use tauri::api::dialog::FileDialogBuilder;
+
+#[tauri::command]
+async fn select_file() -> Result<Option<String>, String> {
+    let result = tokio::task::spawn_blocking(|| {
+        FileDialogBuilder::new()
+            .add_filter("Text Files", &["txt", "md", "json"])
+            .add_filter("All Files", &["*"])
+            .set_title("Select a file")
+            .pick_file()
+    })
+    .await
+    .map_err(|e| e.to_string())?;
+
+    Ok(result.map(|p| p.to_string_lossy().to_string()))
+}
+
+#[tauri::command]
+async fn select_multiple_files() -> Result<Vec<String>, String> {
+    let result = tokio::task::spawn_blocking(|| {
+        FileDialogBuilder::new()
+            .add_filter("Documents", &["txt", "pdf", "doc", "docx"])
+            .pick_files()
+    })
+    .await
+    .map_err(|e| e.to_string())?;
+
+    Ok(result.map(|files| {
+        files.iter()
+            .map(|p| p.to_string_lossy().to_string())
+            .collect()
+    }).unwrap_or_default())
+}
+```
+
+### Save File Dialog
+
+```rust
+#[tauri::command]
+async fn save_file_dialog(
+    default_name: String,
+    content: String,
+) -> Result<Option<String>, String> {
+    let path = tokio::task::spawn_blocking(move || {
+        FileDialogBuilder::new()
+            .set_file_name(&default_name)
+            .add_filter("Text Files", &["txt"])
+            .save_file()
+    })
+    .await
+    .map_err(|e| e.to_string())?;
+
+    if let Some(file_path) = path {
+        tokio::fs::write(&file_path, content)
+            .await
+            .map_err(|e| e.to_string())?;
+
+        Ok(Some(file_path.to_string_lossy().to_string()))
+    } else {
+        Ok(None)
+    }
+}
+```
+
+### Folder Selection Dialog
+
+```rust
+#[tauri::command]
+async fn select_folder() -> Result<Option<String>, String> {
+    let result = tokio::task::spawn_blocking(|| {
+        FileDialogBuilder::new()
+            .set_title("Select a folder")
+            .pick_folder()
+    })
+    .await
+    .map_err(|e| e.to_string())?;
+
+    Ok(result.map(|p| p.to_string_lossy().to_string()))
+}
+```
+
+## Advanced File Operations
+
+### File Watching
+
+```rust
+use notify::{Watcher, RecursiveMode, Event};
+
+#[tauri::command]
+async fn watch_file(
+    filepath: String,
+    window: tauri::Window,
+    app: tauri::AppHandle,
+) -> Result<(), String> {
+    let app_data = app.path_resolver()
+        .app_data_dir()
+        .ok_or("Failed to get app data dir")?;
+
+    let safe_path = validate_path(&app_data, &filepath)?;
+
+    let (tx, mut rx) = tokio::sync::mpsc::channel(100);
+
+    // Create watcher
+    let mut watcher = notify::recommended_watcher(move |res: Result<Event, _>| {
+        if let Ok(event) = res {
+            let _ = tx.blocking_send(event);
+        }
+    }).map_err(|e| e.to_string())?;
+
+    watcher.watch(&safe_path, RecursiveMode::NonRecursive)
+        .map_err(|e| e.to_string())?;
+
+    // Spawn task to handle events
+    tokio::spawn(async move {
+        while let Some(event) = rx.recv().await {
+            let _ = window.emit("file-changed", event);
+        }
+    });
+
+    Ok(())
+}
+```
+
+### Atomic File Operations
+
+```rust
+use tokio::fs;
+use uuid::Uuid;
+
+#[tauri::command]
+async fn atomic_write(
+    filename: String,
+    content: String,
+    app: tauri::AppHandle,
+) -> Result<(), String> {
+    let app_data = app.path_resolver()
+        .app_data_dir()
+        .ok_or("Failed to get app data dir")?;
+
+    let target_path = validate_path(&app_data, &filename)?;
+
+    // Write to temporary file
+    let temp_filename = format!("{}.tmp.{}", filename, Uuid::new_v4());
+    let temp_path = validate_path(&app_data, &temp_filename)?;
+
+    fs::write(&temp_path, content)
+        .await
+        .map_err(|e| format!("Failed to write temp file: {}", e))?;
+
+    // Atomic rename
+    fs::rename(temp_path, target_path)
+        .await
+        .map_err(|e| format!("Failed to rename file: {}", e))?;
+
+    Ok(())
+}
+```
+
+### Batch File Operations
+
+```rust
+#[derive(serde::Deserialize)]
+struct BatchOperation {
+    operation: String,  // "copy", "move", "delete"
+    source: String,
+    destination: Option<String>,
+}
+
+#[tauri::command]
+async fn batch_file_operations(
+    operations: Vec<BatchOperation>,
+    app: tauri::AppHandle,
+) -> Result<Vec<String>, String> {
+    let app_data = app.path_resolver()
+        .app_data_dir()
+        .ok_or("Failed to get app data dir")?;
+
+    let mut results = Vec::new();
+
+    for op in operations {
+        let source_path = validate_path(&app_data, &op.source)?;
+
+        let result = match op.operation.as_str() {
+            "copy" => {
+                if let Some(dest) = op.destination {
+                    let dest_path = validate_path(&app_data, &dest)?;
+                    fs::copy(source_path, dest_path)
+                        .await
+                        .map(|_| "Success".to_string())
+                        .map_err(|e| e.to_string())
+                } else {
+                    Err("Missing destination".to_string())
+                }
+            }
+            "move" => {
+                if let Some(dest) = op.destination {
+                    let dest_path = validate_path(&app_data, &dest)?;
+                    fs::rename(source_path, dest_path)
+                        .await
+                        .map(|_| "Success".to_string())
+                        .map_err(|e| e.to_string())
+                } else {
+                    Err("Missing destination".to_string())
+                }
+            }
+            "delete" => {
+                fs::remove_file(source_path)
+                    .await
+                    .map(|_| "Success".to_string())
+                    .map_err(|e| e.to_string())
+            }
+            _ => Err(format!("Unknown operation: {}", op.operation))
+        };
+
+        results.push(result.unwrap_or_else(|e| format!("Error: {}", e)));
+    }
+
+    Ok(results)
+}
+```
+
+## Frontend Integration
+
+### File Service Pattern
+
+```typescript
+import { invoke } from '@tauri-apps/api/core';
+
+export class FileService {
+    async readFile(filename: string): Promise<string> {
+        return await invoke<string>('read_document', { filename });
+    }
+
+    async saveFile(filename: string, content: string): Promise<void> {
+        await invoke('save_document', { filename, content });
+    }
+
+    async listFiles(directory: string): Promise<FileEntry[]> {
+        return await invoke<FileEntry[]>('list_directory', { directory });
+    }
+
+    async selectFile(): Promise<string | null> {
+        return await invoke<string | null>('select_file');
+    }
+
+    async saveFileDialog(
+        defaultName: string,
+        content: string
+    ): Promise<string | null> {
+        return await invoke<string | null>('save_file_dialog', {
+            defaultName,
+            content
+        });
+    }
+}
+
+export const fileService = new FileService();
+```
+
+## Best Practices
+
+1. **Always validate paths** - Use `validate_path()` for all user inputs
+2. **Use app directories** - Never hardcode paths, use path resolver
+3. **Configure scopes strictly** - Only allow necessary directories
+4. **Handle errors gracefully** - Provide meaningful error messages
+5. **Use atomic writes** - For critical data, write to temp then rename
+6. **Spawn blocking for dialogs** - File dialogs block thread
+7. **Check file existence** - Before read/write operations
+8. **Use relative paths** - Store relative to app directories
+9. **Implement proper cleanup** - Remove temp files
+10. **Test path traversal** - Ensure security with `../` attacks
+
+## Security Checklist
+
+- [ ] Allowlist configured with minimal permissions
+- [ ] All paths validated with `starts_with()` check
+- [ ] No hardcoded absolute paths
+- [ ] User input paths go through `validate_path()`
+- [ ] Scopes defined in tauri.conf.json
+- [ ] File operations use tokio::fs (async)
+- [ ] Error messages don't leak path information
+- [ ] Temporary files cleaned up
+- [ ] Symlink attacks prevented with canonicalize()
+
+## Common Pitfalls
+
+❌ **Not validating paths**:
+```rust
+// WRONG - path traversal vulnerability
+#[tauri::command]
+async fn read_file_unsafe(path: String) -> Result<String, String> {
+    tokio::fs::read_to_string(path).await.map_err(|e| e.to_string())
+}
+
+// CORRECT - validate first
+#[tauri::command]
+async fn read_file_safe(
+    filename: String,
+    app: tauri::AppHandle,
+) -> Result<String, String> {
+    let app_dir = app.path_resolver().app_data_dir().unwrap();
+    let safe_path = validate_path(&app_dir, &filename)?;
+    tokio::fs::read_to_string(safe_path).await.map_err(|e| e.to_string())
+}
+```
+
+❌ **Using blocking fs in async**:
+```rust
+// WRONG - blocks async runtime
+std::fs::read_to_string(path)?;
+
+// CORRECT - use tokio::fs
+tokio::fs::read_to_string(path).await?;
+```
+
+❌ **Not using spawn_blocking for dialogs**:
+```rust
+// WRONG - blocks async runtime
+FileDialogBuilder::new().pick_file();
+
+// CORRECT - spawn blocking
+tokio::task::spawn_blocking(|| {
+    FileDialogBuilder::new().pick_file()
+}).await?
+```
+
+## Summary
+
+- **Always validate paths** - Prevent path traversal attacks
+- **Use app directories** - Via path resolver, not hardcoded
+- **Configure allowlist** - Minimum necessary permissions
+- **Async file operations** - Use tokio::fs, not std::fs
+- **File dialogs** - Spawn in blocking context
+- **Error handling** - Provide user-friendly messages
+- **Atomic operations** - Write to temp, then rename
+- **Security first** - Validate, scope, sanitize all inputs