feat(phase15): complete WRAITH Transfer desktop application (Phase 15)

Implements the complete WRAITH Transfer Tauri desktop application with
React/TypeScript frontend and Rust backend, enabling secure peer-to-peer
file transfers through the WRAITH Protocol.

## Sprint 15.1: FFI Core Library Bindings (wraith-ffi crate)

### C-Compatible FFI Layer (crates/wraith-ffi/ - 1,683 lines)

**lib.rs (180 lines) - Core FFI Infrastructure:**
- Opaque handle types: WraithNode, WraithConfig, WraithSession, WraithTransfer
- NodeHandle struct wrapping Arc<Node> + Arc<Runtime> for thread-safe access
- ConfigHandle for mutable configuration before node creation
- ffi_try! and ffi_try_ptr! macros for consistent error handling
- from_c_string helper for safe null-terminated string conversion
- Global tokio Runtime initialization with lazy_static

**node.rs (241 lines) - Node Lifecycle Management:**
- wraith_node_new() - Create node with random Ed25519 identity
- wraith_node_new_with_config() - Create with custom NodeConfig
- wraith_node_start() / wraith_node_stop() - Lifecycle control
- wraith_node_is_running() - State query
- wraith_node_get_id() - Get 32-byte node ID with caller-owned buffer
- wraith_node_free() - Clean resource deallocation
- All functions return WraithErrorCode with optional error_out parameter

**session.rs (203 lines) - Session Management:**
- wraith_session_establish() - Noise_XX handshake with peer
- wraith_session_close() - Graceful session termination
- wraith_session_get_peer_id() - Get 32-byte peer ID
- wraith_session_is_active() - Check session state
- wraith_session_free() - Session cleanup
- Proper Arc reference counting for session handles

**transfer.rs (249 lines) - File Transfer Operations:**
- wraith_transfer_send_file() - Initiate chunked file transfer
- wraith_transfer_get_progress() - Query TransferProgress struct
- wraith_transfer_cancel() - Abort active transfer
- wraith_transfer_wait() - Block until completion/failure
- wraith_transfer_free() - Transfer handle cleanup
- TransferProgress with bytes_sent/total, progress %, ETA, rate

**config.rs (299 lines) - Configuration API:**
- wraith_config_new() / wraith_config_free() - Lifecycle
- wraith_config_set_bind_address() - Network binding
- wraith_config_set_worker_threads() - Thread pool size
- wraith_config_set_connection_timeout() - Timeout in seconds
- wraith_config_set_chunk_size() - Transfer chunk size (bytes)
- wraith_config_enable_af_xdp() / enable_io_uring() - Kernel bypass
- All setters validate input and return appropriate error codes

**error.rs (230 lines) - Error Handling:**
- WraithErrorCode enum (20 codes): Success, InvalidArgument, NodeNotRunning,
  SessionNotFound, TransferFailed, Timeout, CryptoError, TransportError, etc.
- WraithError struct with code, message, source for error chains
- From<NodeError> implementation mapping all 15 NodeError variants
- Thread-safe error propagation via optional error_out parameter

**types.rs (224 lines) - Type Definitions:**
- TransferProgress: bytes_sent, bytes_total, progress, eta_seconds, rate
- SessionInfo: peer_id, bytes_sent, bytes_received
- ConnectionHealth: rtt_ms, loss_rate, status
- All types #[repr(C)] for ABI compatibility
- Unit tests for struct sizes and alignment

**Build System:**
- build.rs with cbindgen integration for C header generation
- cbindgen.toml with C-style output, include guards, documentation
- Cargo.toml with cdylib + staticlib crate types

## Sprint 15.2: Tauri Desktop Shell

### Backend Implementation (clients/wraith-transfer/src-tauri/)

**lib.rs (83 lines) - Application Entry Point:**
- tracing_subscriber initialization with env-filter
- Tauri::Builder with plugin registration:
  - tauri_plugin_log for structured logging
  - tauri_plugin_dialog for native file dialogs
  - tauri_plugin_fs for file system access
  - tauri_plugin_shell for shell commands
- AppState managed state with Arc<RwLock<Option<Node>>>
- 10 IPC command handlers registered via generate_handler!

**commands.rs (326 lines) - IPC Command Handlers:**
- get_node_status() - NodeStatus with running, node_id, session/transfer counts
- start_node() - Create Node::new_with_config(), start(), store in state
- stop_node() - Graceful node.stop() and state cleanup
- get_node_id() - Hex-encoded 32-byte node identifier
- get_sessions() - List active SessionInfo with peer_id, timestamps, bytes
- close_session(peer_id) - Terminate specific peer session
- send_file(peer_id, file_path) - Initiate transfer, return transfer_id
- get_transfers() - List TransferInfo with progress, status, direction
- get_transfer_progress(transfer_id) - Detailed single transfer progress
- cancel_transfer(transfer_id) - Abort and cleanup transfer

**state.rs (62 lines) - Application State:**
- AppState with Arc<RwLock<Option<Node>>> for thread-safe node access
- HashMap<String, TransferInfo> for local transfer tracking
- Helper methods: is_node_running(), get_node_id_hex(), active_*_count()

**error.rs (53 lines) - Error Types:**
- AppError enum: Node, Session, Transfer, FileNotFound, InvalidPeerId, NodeNotRunning
- Serialize implementation for frontend consumption
- Into<InvokeError> for Tauri error propagation

**Configuration (tauri.conf.json):**
- App identifier: io.wraith.transfer
- Window: 1200x800 default, 800x600 minimum, centered, titlebar
- CSP: strict default-src, connect-src for localhost
- Tray icon support enabled
- Bundle: Windows (msi, nsis), macOS (dmg, app), Linux (deb, rpm, appimage)

## Sprint 15.3: React UI Foundation

### Frontend Implementation (clients/wraith-transfer/frontend/)

**Build System:**
- Vite 7.2.7 with React plugin and HMR
- TypeScript 5.8 strict mode
- Tailwind CSS v4 with @tailwindcss/vite plugin
- ESLint 9 with TypeScript and React Hooks rules

**Type Definitions (src/types/index.ts):**
- NodeStatus: running, node_id, active_sessions, active_transfers
- TransferInfo: id, peer_id, file_name, bytes, progress, status, direction
- SessionInfo: peer_id, established_at, bytes_sent, bytes_received
- ConnectionHealth: peer_id, rtt_ms, loss_rate, last_activity, status

**Tauri IPC Bindings (src/lib/tauri.ts):**
- Type-safe wrappers for all 10 backend commands
- invoke<T> with proper TypeScript generics
- Async/await patterns for all operations

**State Management (src/stores/):**
- nodeStore.ts - Zustand store for node status, start/stop actions
- transferStore.ts - Transfer list, sendFile, cancelTransfer actions
- sessionStore.ts - Session list, closeSession actions
- All stores with loading/error state handling

**Styling (src/index.css):**
- Tailwind v4 CSS-first configuration with @import "tailwindcss"
- @theme directive for custom properties
- WRAITH brand colors: wraith-primary (#7c3aed), wraith-secondary (#4f46e5),
  wraith-accent (#06b6d4), bg-primary (#0f172a), bg-secondary (#1e293b)

## Sprint 15.4: Transfer UI Components

### React Components (src/components/)

**Header.tsx:**
- Connection status indicator (green/red dot)
- Node ID display (truncated hex)
- Active sessions/transfers counters
- Start/Stop node button with loading state
- Responsive layout with flex

**TransferList.tsx:**
- TransferItem subcomponent with:
  - Upload/download direction indicator
  - File name and peer ID (truncated)
  - Progress bar with color-coded status
  - Bytes transferred / total with auto-formatting
  - Cancel button for active transfers
- Empty state with helpful message
- Status colors: initializing (yellow), in_progress (blue),
  completed (green), failed (red), cancelled (gray)

**SessionPanel.tsx:**
- Fixed-width sidebar (w-72)
- SessionItem with peer ID, bytes sent/received
- Disconnect button per session
- Empty state when no sessions

**NewTransferDialog.tsx:**
- Modal overlay with backdrop blur
- Peer ID input (64-char hex validation)
- File picker using @tauri-apps/plugin-dialog
- Error display with red styling
- Cancel/Send buttons with loading state

**StatusBar.tsx:**
- Error message display
- Ready/start node status hints
- "New Transfer" action button
- Disabled state when node not running

**App.tsx:**
- Full-height flexbox layout
- Header, main (TransferList + SessionPanel), StatusBar
- 1-second polling interval when node running
- Dialog state management for NewTransferDialog
- useEffect hooks for initial fetch and polling

## Quality Assurance

- Zero clippy warnings with -D warnings
- All 1,303 workspace tests passing
- Frontend TypeScript strict mode enabled
- Production builds verified (Rust + Vite)
- Code formatted with cargo fmt and prettier

## Files Changed Summary

- 66 files changed, 7,765 insertions
- New crate: wraith-ffi (10 files, ~1,683 lines Rust)
- New client: wraith-transfer (56 files)
  - Tauri backend: 5 Rust files (~530 lines)
  - React frontend: ~20 source files (~800 lines TypeScript/TSX)
  - Assets: 17 icon files for cross-platform bundles

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: doublegate

CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+#### Phase 15: Reference Client Foundation - WRAITH Transfer (Complete)
+
+**Sprint 15.1: FFI Core Library Bindings**
+- Completed in previous session (wraith-ffi crate with C-compatible API)
+
+**Sprint 15.2: Tauri Desktop Shell**
+- **Tauri 2.0 Backend** (`clients/wraith-transfer/src-tauri/`)
+  - lib.rs (84 lines) - Main entry point with IPC handler registration
+  - commands.rs (315 lines) - 10 IPC commands for node/session/transfer management
+  - state.rs - AppState with Arc<RwLock<Option<Node>>> for thread-safe node access
+  - error.rs - AppError enum with Serialize implementation for frontend
+  - Cargo.toml - Tauri 2.9.4 with plugins (dialog, fs, shell, log)
+- **Tauri Plugins Integration**
+  - tauri-plugin-dialog for file selection dialogs
+  - tauri-plugin-fs for file system access
+  - tauri-plugin-shell for shell commands
+  - tauri-plugin-log for structured logging
+- **wraith-core Integration**
+  - Node lifecycle management (start/stop)
+  - Session establishment and closure
+  - File transfer with progress tracking
+
+**Sprint 15.3: React UI Foundation**
+- **React 18 + TypeScript Frontend** (`clients/wraith-transfer/frontend/`)
+  - Vite 7.2.7 build system with HMR
+  - Tailwind CSS v4 with WRAITH brand colors
+  - Type definitions for NodeStatus, TransferInfo, SessionInfo
+- **State Management** (Zustand stores)
+  - nodeStore.ts - Node status, start/stop actions
+  - transferStore.ts - Transfer list, send file, cancel actions
+  - sessionStore.ts - Session list, close session actions
+- **Tauri IPC Bindings** (lib/tauri.ts)
+  - Full TypeScript bindings for all 10 backend commands
+  - Type-safe invoke wrappers
+
+**Sprint 15.4: Transfer UI Components**
+- **Core Components** (`src/components/`)
+  - Header.tsx - Connection status, node ID, session/transfer counts, start/stop button
+  - TransferList.tsx - Transfer items with progress bars, status, cancel buttons
+  - SessionPanel.tsx - Active sessions sidebar with disconnect capability
+  - NewTransferDialog.tsx - Modal for initiating transfers with file picker
+  - StatusBar.tsx - Quick actions, error display, "New Transfer" button
+- **Main Application** (App.tsx)
+  - Full layout with header, main content, sidebar, status bar
+  - 1-second polling for status updates when node is running
+  - Dialog state management
+
+**Code Statistics:**
+- Tauri Backend: ~500 lines of Rust
+- Frontend: ~800 lines of TypeScript/TSX
+- 10 IPC commands, 5 React components, 3 Zustand stores
+- Full type coverage with TypeScript
+
+**Quality Assurance:**
+- Zero clippy warnings
+- All workspace tests passing (1,303 tests)
+- Frontend TypeScript strict mode enabled
+- Production build verified
+
 ---
 
 ## [1.4.0] - 2025-12-07 - Node API Integration & Code Quality (Phase 14 Complete)

Cargo.toml

@@ -14,6 +14,8 @@ members = [
     "crates/wraith-discovery",
     "crates/wraith-files",
     "crates/wraith-cli",
+    "crates/wraith-ffi",
+    "clients/wraith-transfer/src-tauri",
     "xtask",
     "tests",
 ]

PHASE-15-SPRINT-15.1-PROGRESS.md

@@ -0,0 +1,245 @@
+# Phase 15 Sprint 15.1: Core Library Bindings - Progress Report
+
+**Date:** 2025-12-07
+**Sprint:** 15.1 - Core Library Bindings (FFI)
+**Status:** Foundation Complete, Compilation Fixes Required
+**Story Points:** 21 SP (estimated)
+**Completion:** ~75% (implementation complete, debugging needed)
+
+---
+
+## Executive Summary
+
+Sprint 15.1 successfully established the foundation for WRAITH Protocol client applications by creating the wraith-ffi crate with C-compatible FFI bindings. The core implementation is complete with ~1,500 lines of FFI code across 7 modules, comprehensive error handling, and cbindgen integration for C header generation. Remaining work focuses on resolving API mismatches with wraith-core and Rust 2024 safety compliance.
+
+---
+
+## Deliverables
+
+### ✅ Completed
+
+#### 1. Project Structure
+- **Created:** `clients/` directory at repository root
+- **Created:** `crates/wraith-ffi/` crate with proper workspace integration
+- **Updated:** Root `Cargo.toml` to include wraith-ffi in workspace members
+- **Created:** `clients/README.md` with integration examples and roadmap
+
+#### 2. wraith-ffi Crate Implementation (~1,500 lines)
+
+**Cargo.toml:**
+- Configured as `cdylib`, `staticlib`, and `rlib` for maximum compatibility
+- Dependencies: wraith-core, wraith-crypto, wraith-discovery, wraith-files, wraith-obfuscation, wraith-transport
+- Build dependencies: cbindgen for C header generation
+- Dev dependencies: tokio-test
+
+**Core Modules:**
+
+1. **lib.rs (150 lines)**
+   - Main FFI entry point with library initialization
+   - Opaque handle type definitions (WraithNode, WraithSession, WraithTransfer, WraithConfig)
+   - Internal handle representations with tokio Runtime integration
+   - Version string export (`wraith_version()`)
+   - String memory management (`wraith_free_string()`)
+   - Helper functions for C string conversion
+   - Unit tests for initialization and version
+
+2. **types.rs (228 lines)**
+   - FFI-safe type definitions with `#[repr(C)]`
+   - ID types: `WraithNodeId`, `WraithSessionId`, `WraithTransferId` (32 bytes each)
+   - Stats type: `WraithConnectionStats` (bytes, packets, RTT, loss rate)
+   - Progress type: `WraithTransferProgress` (total, transferred, ETA, rate)
+   - Enums: `WraithTransferStatus`, `WraithPaddingMode`, `WraithTimingMode`, `WraithMimicryMode`, `WraithLogLevel`
+   - From<> trait implementations for obfuscation type conversions
+   - Unit tests for size validation and conversions
+
+3. **error.rs (175 lines)**
+   - `WraithErrorCode` enum with 13 error variants (C-compatible)
+   - `WraithError` struct with code + message
+   - `From<NodeError>` implementation for error conversion
+   - `ffi_try!` macro for ergonomic error handling
+   - Helper methods: `invalid_argument()`, `not_initialized()`, `session_not_found()`, etc.
+   - Unit tests for error code conversion and C string generation
+
+4. **config.rs (260 lines)**
+   - Configuration creation/destruction: `wraith_config_new()`, `wraith_config_free()`
+   - Network settings: `wraith_config_set_bind_address()`
+   - Obfuscation: `wraith_config_set_padding_mode()`, `wraith_config_set_timing_mode()`, `wraith_config_set_mimicry_mode()`
+   - Performance: `wraith_config_enable_af_xdp()`, `wraith_config_enable_io_uring()`, `wraith_config_set_worker_threads()`
+   - Transfer: `wraith_config_set_download_dir()`
+   - Unit tests for config creation and setting operations
+
+5. **node.rs (270 lines)**
+   - Node creation: `wraith_node_new()`, `wraith_node_from_identity()`
+   - Lifecycle: `wraith_node_start()`, `wraith_node_stop()`, `wraith_node_is_running()`
+   - Identity: `wraith_node_get_id()`, `wraith_node_save_identity()`
+   - Memory management: `wraith_node_free()`
+   - Unit tests for node lifecycle, ID retrieval, start/stop
+
+6. **session.rs (195 lines)**
+   - Session establishment: `wraith_session_establish()`
+   - Session closure: `wraith_session_close()`
+   - Statistics: `wraith_session_get_stats()`, `wraith_session_count()`
+   - Unit tests for session counting
+
+7. **transfer.rs (220 lines)**
+   - File transfer: `wraith_transfer_send_file()`
+   - Progress tracking: `wraith_transfer_get_progress()`, `wraith_transfer_wait()`
+   - Management: `wraith_transfer_free()`, `wraith_transfer_count()`
+   - Unit tests for transfer counting
+
+#### 3. Build System Integration
+
+**build.rs:**
+- cbindgen integration for automatic C header generation
+- Header output to `target/include/wraith-ffi.h`
+- Custom target directory detection
+
+**cbindgen.toml:**
+- C language configuration with doxygen-style documentation
+- Pragma once and include guard
+- Platform-specific defines (WRAITH_LINUX, WRAITH_MACOS, WRAITH_WINDOWS)
+- Function/struct/enum naming conventions
+
+#### 4. Rust 2024 Safety Compliance
+
+- All `#[no_mangle]` attributes wrapped in `#[unsafe(...)]` for Rust 2024 edition
+- Proper unsafe function declarations
+
+---
+
+## 🔨 Remaining Work
+
+### API Compatibility Fixes
+
+1. **wraith-core Node API Updates**
+   - Fix `Node::new_random()` signature (removed `config` parameter)
+   - Update `Node::start()` and `Node::stop()` to match actual async signatures
+   - Fix `node.id()` to `node.node_id()` method name
+   - Add proper identity save/load methods or use wraith-core's identity module
+
+2. **NodeError Pattern Matching**
+   - Fix `SessionNotFound` - takes `[u8; 32]` parameter, not unit variant
+   - Fix `TransferNotFound` - takes `[u8; 32]` parameter
+   - Fix `Timeout` - takes `Cow<'static, str>` parameter
+   - Fix `PeerNotFound` - takes `[u8; 32]` parameter
+
+3. **Rust 2024 Safety**
+   - Wrap all unsafe operations in `unsafe { }` blocks within unsafe functions
+   - Fix raw pointer dereferences
+   - Fix `CString::from_raw()` and `CStr::from_ptr()` calls
+
+### Testing & Documentation
+
+1. **Unit Tests**
+   - Expand test coverage for all FFI functions
+   - Add integration tests for multi-module workflows
+   - Test error handling paths
+
+2. **TypeScript Bindings**
+   - Generate TypeScript definitions from C headers
+   - Create Tauri IPC command wrappers
+   - Add JSDoc documentation
+
+3. **C Examples**
+   - Create example C program using wraith-ffi
+   - Document compilation and linking instructions
+
+---
+
+## Code Statistics
+
+| Module | Lines | Functions | Tests | Status |
+|--------|-------|-----------|-------|--------|
+| lib.rs | 150 | 3 | 3 | ✅ Complete |
+| types.rs | 228 | 3 (traits) | 5 | ✅ Complete |
+| error.rs | 175 | 8 | 3 | ✅ Complete |
+| config.rs | 260 | 8 | 3 | ✅ Complete |
+| node.rs | 270 | 7 | 3 | ⚠️ API fixes needed |
+| session.rs | 195 | 4 | 1 | ⚠️ API fixes needed |
+| transfer.rs | 220 | 5 | 1 | ⚠️ API fixes needed |
+| build.rs | 30 | 1 | 0 | ✅ Complete |
+| cbindgen.toml | 50 | N/A | N/A | ✅ Complete |
+| **Total** | **~1,580** | **39** | **19** | **~75%** |
+
+---
+
+## Build Status
+
+**Current Compilation Issues:**
+- ❌ 46 compilation errors (API mismatches, unsafe blocks, imports)
+- ⚠️ 26 warnings (Rust 2024 unsafe operations)
+
+**Root Causes:**
+1. wraith-core Node API changes since documentation (async signatures, method names)
+2. NodeError enum variants have associated data (not unit variants)
+3. Missing unsafe blocks for raw pointer operations (Rust 2024 requirement)
+4. Import paths incorrect (`wraith_crypto::identity` should be `wraith_core::node::identity`)
+
+---
+
+## Dependencies Added
+
+**Workspace:** None (all dependencies already in workspace)
+
+**wraith-ffi specific:**
+- `cbindgen = "0.27"` (build dependency)
+- `tokio-test = "0.4"` (dev dependency)
+- `tracing-subscriber` (added to workspace dependencies)
+
+---
+
+## Next Steps
+
+### Sprint 15.1 Completion (Remaining ~5 SP)
+
+1. **Fix wraith-core API Integration** (2 SP)
+   - Update Node API calls to match actual implementation
+   - Fix identity module imports
+   - Adjust async runtime integration
+
+2. **Resolve Rust 2024 Safety** (1 SP)
+   - Add unsafe blocks for all raw pointer operations
+   - Fix CString/CStr unsafe calls
+
+3. **Fix NodeError Handling** (1 SP)
+   - Update pattern matching for enum variants with data
+   - Properly extract error messages
+
+4. **Testing & Validation** (1 SP)
+   - Ensure all tests pass
+   - Run clippy with -D warnings
+   - Generate C headers successfully
+
+### Sprint 15.2: Tauri Desktop Shell (13 SP)
+
+After Sprint 15.1 completion, proceed with:
+- Initialize Tauri 2.0 project
+- Create IPC command layer
+- Implement basic UI shell
+- Integrate wraith-ffi
+
+---
+
+## Lessons Learned
+
+1. **API Documentation vs Implementation:** FFI design assumed stable Node API, but actual implementation has different async signatures and method names. Solution: Check actual implementation early.
+
+2. **Rust 2024 Breaking Changes:** New edition requires explicit unsafe blocks even within unsafe functions. Solution: Wrap all unsafe operations in `unsafe { }`.
+
+3. **Enum Variants with Data:** Assumed unit variants for errors, but they contain associated data. Solution: Pattern match with data extraction.
+
+4. **Module Organization:** Clear separation of concerns (types, errors, node, session, transfer, config) makes code maintainable and testable.
+
+---
+
+## Conclusion
+
+Sprint 15.1 has successfully established the foundational FFI layer for WRAITH Protocol client applications. The core implementation is complete and well-structured, with comprehensive error handling, type safety, and C header generation. Remaining compilation fixes are straightforward API alignment tasks that should complete within 1-2 hours of focused work.
+
+**Recommendation:** Complete Sprint 15.1 fixes before proceeding to Sprint 15.2 to ensure a stable FFI foundation for Tauri integration.
+
+---
+
+**Report Generated:** 2025-12-07
+**Author:** Claude (Anthropic AI Assistant)
+**Sprint Status:** In Progress - 75% Complete