refactor: Restructure platform module and enhance error handling system

This comprehensive refactoring overhauls the bitvault-common library architecture
with significant improvements to security, modularity, and cross-platform support:

- Platform Module:
  * Replaced single platform.rs with modular, OS-specific implementations
  * Implemented proper abstraction layer with provider interface
  * Added platform capabilities detection for feature availability
  * Created secure memory management utilities
  * Enhanced platform-specific path handling

- Error Handling:
  * Introduced BitVaultError system with standardized error types
  * Implemented context-aware error handling
  * Added security-focused error sanitization
  * Provided error conversion utilities

- UTXO Management:
  * Reimplemented selection using modular strategy pattern
  * Removed deprecated implementations
  * Enhanced organization for better maintainability

- Testing Framework:
  * Added comprehensive platform-specific tests
  * Implemented security boundary validation tests
  * Created diagnostic utilities for debugging
  * Enhanced test isolation with proper mocking

- Documentation:
  * Added detailed documentation for security boundaries
  * Improved module-level documentation
  * Created technical design documentation

This refactoring establishes a more robust foundation for the wallet's
cross-platform development while enhancing security through proper
boundary isolation and memory management.

Author: secsovereign

bitvault-common/Cargo.toml

@@ -5,6 +5,11 @@ edition = "2021"
 authors = ["BitVault Team"]
 description = "Common types and utilities for the BitVault Bitcoin wallet"
 
+# Define the run_all_tests binary
+[[bin]]
+name = "run_all_tests"
+path = "tests/run_all_tests.rs"
+
 [dependencies]
 lazy_static = { workspace = true }
 
@@ -34,6 +39,9 @@ chrono = { version = "0.4", features = ["serde"] }
 # Memory security
 zeroize = { workspace = true, features = ["zeroize_derive"] }  # Memory wiping to prevent key leakage
 
+# Utilities
+once_cell = "1.19"  # Thread-safe lazy initialization
+
 # Cryptography 
 argon2 = "0.5.0"      # Password hashing/key derivation
 pbkdf2 = "0.12.0"     # Key derivation
@@ -53,9 +61,6 @@ cfg-if = "1.0"
 hex = { workspace = true }
 rand = { workspace = true }     # Secure random number generation
 
-# Concurrency
-crossbeam-channel = { workspace = true }  # Thread-safe channels for event handling
-
 # Localization
 fluent = { workspace = true }             # Mozilla's internationalization framework
 unic-langid = { workspace = true }        # Language identifier handling
@@ -78,4 +83,6 @@ criterion = "0.3"               # Benchmarking framework
 quickcheck = "1.0"              # Property-based testing
 quickcheck_macros = "1.0"       # Macros for property-based testing
 lazy_static = { workspace = true }
+ctor = "0.1.22"                # Constructor attribute for test initialization
+log4rs = "1.2"                # Structured logging for tests
 

bitvault-common/docs/architecture/event_architecture.md

@@ -0,0 +1,216 @@
+# Event-Driven Architecture in BitVault
+
+This document describes the event-driven architecture used in the BitVault wallet, specifically focusing on the UTXO selection and management components.
+
+## Overview
+
+BitVault implements an event-driven architecture to provide:
+
+- Loose coupling between components
+- Better observability of system state changes
+- Enhanced testability
+- Improved modularity
+- Security boundary management
+
+The event system consists of two main components:
+
+1. **General Message Bus** (`MessageBus`) - For system-wide events
+2. **Domain-Specific Event Buses** - For targeted functionality (e.g., `UtxoEventBus`, `KeyManagementBus`)
+
+## Key Components
+
+### MessageBus
+
+The `MessageBus` is a general-purpose event bus that handles events of different types across the entire system. It provides:
+
+- Event publishing with priority levels
+- Subscription to specific event types
+- Rate limiting for event flow control
+- Dead letter channel for failed event delivery
+- Event persistence for critical events
+
+```rust
+// Create and start a message bus
+let mut message_bus = MessageBus::new();
+message_bus.start();
+
+// Subscribe to specific events
+let receiver = message_bus.subscribe(EventType::TransactionReceived);
+
+// Publish an event
+message_bus.publish(
+    EventType::TransactionReceived,
+    &json!({ "txid": "abc123", "amount": 10000 }).to_string(),
+    MessagePriority::High
+);
+```
+
+### Domain-Specific Event Buses
+
+Domain-specific event buses provide more targeted functionality for specific domains:
+
+- `UtxoEventBus` for UTXO-related events
+- `KeyManagementBus` for key management events
+
+These buses can operate independently or connect to the general message bus:
+
+```rust
+// Create a standalone UTXO event bus
+let utxo_bus = UtxoEventBus::new();
+
+// Or connect to the general message bus
+let utxo_bus = UtxoEventBus::with_general_bus(Arc::new(message_bus));
+
+// Subscribe to specific UTXO events
+let selected_receiver = utxo_bus.subscribe("selected");
+let all_receiver = utxo_bus.subscribe_all();
+
+// Publish a domain-specific event
+utxo_bus.publish(UtxoEvent::Frozen {
+    outpoint: OutPointInfo { txid: "abc123".to_string(), vout: 0 }
+});
+```
+
+## Event Types
+
+### General Events (EventType)
+
+System-wide events are classified by the `EventType` enum:
+
+- `WalletUpdate`, `TransactionReceived`, `TransactionSent`, etc. - General wallet events
+- `SecurityAlert` - Security-related events
+- `UtxoSelected`, `UtxoStatusChanged` - UTXO-related events
+- `ConfigUpdate` - Configuration changes
+- `CoreRequest`, `CoreResponse` - Events crossing security boundaries
+
+### Domain-Specific Events
+
+#### UTXO Events (UtxoEvent)
+
+- `Selected` - When UTXOs are selected for a transaction
+- `Frozen` - When a UTXO is marked as unavailable for selection
+- `Unfrozen` - When a UTXO is marked as available for selection
+- `SelectionFailed` - When UTXO selection fails (e.g., insufficient funds)
+- `StatusChanged` - When a UTXO's status changes
+
+#### Key Management Events (KeyManagementEvent)
+
+- `KeyGenerated` - When a new key is generated
+- `KeyEncrypted` - When a key is encrypted
+- `KeyDecryptionFailed` - When key decryption fails
+
+## Integration with UTXO Selection and Management
+
+### UtxoSelector
+
+The `UtxoSelector` uses the event system to publish events during UTXO selection:
+
+```rust
+// Create a selector and event bus
+let (selector, event_bus) = UtxoSelector::with_event_bus(Arc::new(UtxoEventBus::new()));
+
+// Select UTXOs with event publishing
+let result = selector.select_utxos(
+    &utxos,
+    amount,
+    strategy,
+    Some(&message_bus),
+    Some(&event_bus)
+);
+
+// Or use the simplified API
+let (result, created_bus) = selector.select_utxos_with_events(
+    &utxos,
+    amount,
+    strategy,
+    Some(&message_bus)
+);
+```
+
+### UtxoManager
+
+The `UtxoManager` uses the event system to publish events for all UTXO operations:
+
+```rust
+// Create a manager with event bus
+let (manager, event_bus) = UtxoManager::with_new_event_bus();
+
+// Subscribe to events
+let receiver = event_bus.subscribe_all();
+
+// Add UTXOs, freeze/unfreeze, and select UTXOs
+// Events will be published automatically
+manager.add_utxo(utxo);
+manager.freeze_utxo(&outpoint);
+let result = manager.select_utxos(amount, strategy, Some(&message_bus));
+```
+
+## Security Considerations
+
+The event-driven architecture provides several security benefits but also introduces considerations:
+
+- **Event Data Protection**: Events may contain sensitive information about wallet state
+- **Security Boundary Crossing**: Events marked as `CoreRequest` or `CoreResponse` cross security boundaries and require special handling
+- **Event Persistence**: Critical events are persisted and may contain sensitive data
+- **Rate Limiting**: Prevents excessive event flow that could lead to resource exhaustion
+
+## Best Practices
+
+1. **Always Subscribe Before Publishing**: Ensure subscribers are registered before events are published to avoid missing critical events
+
+2. **Error Handling**: Use try/catch when processing events to prevent cascading failures
+
+3. **Timeout Handling**: Always use timeouts when waiting for events to avoid blocking indefinitely
+
+4. **Event Granularity**: Create specific, granular events rather than general-purpose ones
+
+5. **Security-Aware Event Design**: Be mindful of what data is included in events, especially those crossing security boundaries
+
+## Example: Complete Event Flow
+
+```rust
+// 1. Create general message bus
+let mut message_bus = MessageBus::new();
+message_bus.start();
+
+// 2. Create domain-specific event bus
+let utxo_bus = Arc::new(UtxoEventBus::with_general_bus(Arc::new(message_bus.clone())));
+
+// 3. Create UTXO manager with event bus
+let mut manager = UtxoManager::with_event_bus(Arc::clone(&utxo_bus));
+
+// 4. Subscribe to events
+let selected_receiver = utxo_bus.subscribe("selected");
+let general_receiver = message_bus.subscribe(EventType::UtxoSelected);
+
+// 5. Add UTXOs and select them
+manager.add_utxo(utxo1);
+manager.add_utxo(utxo2);
+let result = manager.select_utxos(amount, strategy, Some(&message_bus));
+
+// 6. Process the selection result and handle events
+match result {
+    SelectionResult::Success { selected, fee_amount, change_amount } => {
+        // Use selected UTXOs to build transaction
+    },
+    SelectionResult::InsufficientFunds { available, required } => {
+        // Handle insufficient funds
+    }
+}
+
+// 7. Process events from receivers
+match selected_receiver.recv_timeout(Duration::from_millis(100)) {
+    Ok(event) => {
+        // Handle the event
+    },
+    Err(_) => {
+        // Handle timeout
+    }
+}
+```
+
+## Conclusion
+
+The event-driven architecture in BitVault provides a flexible and powerful foundation for building a secure, maintainable Bitcoin wallet. By separating concerns through domain-specific event buses and leveraging the publisher-subscriber pattern, components can communicate efficiently without tight coupling.
+
+This design enhances testability, allows for better security isolation, and provides a clear path for extending functionality while maintaining the integrity of the system. 

bitvault-common/docs/architecture/updated_architecture.md

@@ -0,0 +1,92 @@
+# BitVault Architecture Overview
+
+This document outlines the architecture of the BitVault wallet application, providing a high-level overview of its components and their interactions.
+
+## Overview
+
+The BitVault wallet architecture consists of several key components, each with specific responsibilities:
+
+- **Core Components**
+  - Key Management Module - Handles cryptographic operations and secrets
+  - UTXO Management System - Manages Bitcoin UTXOs and transaction building
+  - Platform Abstractions - Provides platform-specific functionality
+  - Configuration System - Manages wallet settings and preferences
+
+- **Cross-cutting Concerns**
+  - Event System - Enables loose coupling between components
+  - Logging Framework - Provides secure, contextual logging
+  - Error Handling - Consistent error propagation and handling
+  - Security Boundaries - Clear separation of security domains
+
+## Component Interactions
+
+Components interact primarily through a well-defined event system that respects security boundaries. The event-driven architecture (described in detail in [Event Architecture](event_architecture.md)) ensures:
+
+1. Loose coupling between components
+2. Clear communication patterns
+3. Testability of component interactions
+4. Security boundary enforcement
+
+### Communication Flow Example
+
+A typical communication flow for a transaction:
+
+1. User Interface → Event System: "Create Transaction" request
+2. Event System → UTXO Manager: Request for UTXO selection
+3. UTXO Manager → Event System: Selected UTXOs
+4. Event System → Key Manager: Request for transaction signing
+5. Key Manager → Event System: Signed transaction
+6. Event System → Network Module: Transaction broadcast
+
+## Security Model
+
+Security is a primary concern in the BitVault architecture. The wallet implements several security patterns:
+
+- **Explicit Security Boundaries** - Clear demarcation between security domains
+- **Minimal Privilege** - Components only have access to what they need
+- **Memory Protection** - Secure handling of cryptographic secrets
+- **Defensive Coding** - Validation at trust boundaries
+- **Event Security** - Security-aware event propagation
+
+See [Security Boundaries](../security/security_boundaries.md) for detailed information on security implementation.
+
+## Module Structure
+
+The codebase is organized into the following major modules:
+
+- **bitvault-common** - Core functionality shared across platforms
+  - `key_management.rs` - Cryptographic keys and secrets management
+  - `utxo_management.rs` - UTXO handling and transaction building
+  - `platform/` - Platform-specific abstractions
+  - `events.rs` - Event system implementation
+  - `types.rs` - Core data types
+  - `error.rs` - Error types and handling
+
+- **bitvault-ui** - User interface implementation
+- **bitvault-node** - Bitcoin node interaction
+- **bitvault-app** - Application entry points for different platforms
+
+## Cross-platform Strategy
+
+BitVault is designed for cross-platform compatibility:
+
+- Core functionality in Rust for security and performance
+- Platform-specific code isolated in dedicated modules
+- UI adaptations for different platforms while maintaining core experience
+- Consistent security model across all platforms
+
+## Future Directions
+
+The architecture is designed to accommodate future enhancements:
+
+1. Lightning Network integration
+2. Hardware wallet support
+3. Multi-signature wallet support
+4. Advanced privacy features
+
+## Related Documentation
+
+- [Event-Driven Architecture](event_architecture.md) - Detailed information on the event system
+- [Security Boundaries](../security/security_boundaries.md) - Security model implementation
+- [UTXO Management](../utxo/utxo_management.md) - UTXO handling details
+- [Key Management](../key_management/key_management_overview.md) - Cryptographic operations