Merge pull request #14 from BitcoinErrorLog/fix/code-quality-improvements

Add comprehensive demo app improvements

Author: BitcoinErrorLog

DEMO_APPS_REVIEW.md

@@ -0,0 +1,162 @@
+# PubkyNoise Rust Examples
+
+This directory contains standalone Rust examples demonstrating various features of the `pubky-noise` library.
+
+## Running Examples
+
+All examples can be run with:
+
+```bash
+cargo run --example <example_name>
+```
+
+## Available Examples
+
+### basic_handshake.rs
+
+Complete IK pattern handshake between client and server with encrypted message exchange.
+
+```bash
+cargo run --example basic_handshake
+```
+
+**Demonstrates:**
+- Client and server setup
+- 3-step IK handshake
+- Encryption/decryption
+- Session ID verification
+
+### server_example.rs
+
+Server-side implementation handling multiple client connections.
+
+```bash
+cargo run --example server_example
+```
+
+**Demonstrates:**
+- Server initialization
+- Public key distribution
+- Multiple client sessions with `NoiseSessionManager`
+- Mobile-optimized server with `NoiseManager`
+- Error handling for invalid messages and decryption failures
+- Rate limiting patterns
+- Client disconnection handling
+- Connection timeout management
+- Graceful shutdown procedures
+
+### error_handling.rs
+
+Comprehensive error handling patterns for all failure scenarios.
+
+```bash
+cargo run --example error_handling
+```
+
+**Demonstrates:**
+- Invalid peer key detection
+- Decryption failure handling
+- Error codes for FFI integration
+- Error recovery strategies
+
+### streaming.rs
+
+Large message handling with automatic chunking.
+
+```bash
+cargo run --example streaming
+```
+
+**Demonstrates:**
+- `StreamingNoiseLink` usage
+- Custom chunk sizes
+- Automatic splitting and reassembly
+- Mobile-friendly chunk size recommendations
+
+### mobile_manager.rs
+
+Mobile-optimized API with lifecycle management and state persistence.
+
+```bash
+cargo run --example mobile_manager
+```
+
+**Demonstrates:**
+- `NoiseManager` API
+- `MobileConfig` options
+- State save/restore for app lifecycle
+- Connection status tracking
+- Multiple session management
+
+### xx_pattern.rs
+
+XX pattern (Trust On First Use) handshake demonstration.
+
+```bash
+cargo run --example xx_pattern
+```
+
+**Demonstrates:**
+- XX pattern handshake flow (3 messages)
+- Server key learning during handshake
+- Key pinning for future IK connections
+- Transition from XX to IK pattern
+- Comparison of XX vs IK patterns
+- Security considerations for TOFU
+
+### storage_queue.rs
+
+Storage-backed messaging with async operations and retry configuration.
+
+```bash
+cargo run --example storage_queue --features storage-queue
+```
+
+**Note**: Requires the `storage-queue` feature and Pubky infrastructure.
+
+**Demonstrates:**
+- `StorageBackedMessaging` setup
+- `RetryConfig` configuration
+- Counter persistence (critical for production)
+- Async message sending and receiving
+- Error handling for storage operations
+- Best practices for production use
+
+## Example Structure
+
+Each example follows this pattern:
+
+1. **Setup** - Initialize keys, clients, and servers
+2. **Handshake** - Demonstrate the 3-step handshake
+3. **Usage** - Show the specific feature
+4. **Summary** - Key points and best practices
+
+## Adding New Examples
+
+When creating a new example:
+
+1. Add the `.rs` file to this directory
+2. The file must have a `fn main()` function
+3. Use `println!` for output (no external dependencies needed)
+4. Include comprehensive comments
+5. Add documentation header with `//!` comments
+6. Update this README
+
+## Dependencies
+
+Most examples use only the main `pubky-noise` crate. The `storage_queue.rs` example requires:
+- The `storage-queue` feature to be enabled
+- Pubky infrastructure (PubkySession, PublicStorage)
+
+Run with feature:
+```bash
+cargo run --example storage_queue --features storage-queue
+```
+
+## See Also
+
+- `tests/adapter_demo.rs` - Integration tests that double as examples
+- `tests/mobile_integration.rs` - Comprehensive mobile feature tests
+- Platform examples:
+  - `platforms/android/example/MainActivity.kt`
+  - `platforms/ios/example/BasicExample.swift`

examples/README.md

@@ -0,0 +1,143 @@
+//! Basic IK Handshake Example
+//!
+//! This example demonstrates a complete IK pattern handshake between
+//! a client and server, followed by encrypted message exchange.
+//!
+//! ## Running
+//!
+//! ```bash
+//! cargo run --example basic_handshake
+//! ```
+//!
+//! ## Overview
+//!
+//! The IK pattern is used when the client knows the server's static
+//! public key in advance. This is the most common pattern for
+//! connecting to a known server.
+//!
+//! ## 3-Step Handshake Flow
+//!
+//! 1. Client: Create first message with encrypted identity
+//! 2. Server: Process and create response
+//! 3. Client: Process response, both now have transport keys
+
+use pubky_noise::datalink_adapter::{
+    client_complete_ik, client_start_ik_direct, server_accept_ik, server_complete_ik,
+};
+use pubky_noise::{DummyRing, NoiseClient, NoiseServer, RingKeyProvider};
+use std::sync::Arc;
+
+fn main() {
+    println!("=== PubkyNoise Basic Handshake Example ===\n");
+
+    // =========================================================================
+    // Setup
+    // =========================================================================
+
+    println!("1. Setting up client and server...");
+
+    // Create key providers with unique seeds
+    // In production, use secure random seeds from key storage
+    let client_seed = [1u8; 32];
+    let server_seed = [2u8; 32];
+
+    let ring_client = Arc::new(DummyRing::new(client_seed, "client-key-id"));
+    let ring_server = Arc::new(DummyRing::new(server_seed, "server-key-id"));
+
+    // Create client and server instances
+    let client = NoiseClient::<_, ()>::new_direct("client-key-id", b"client-device", ring_client);
+    let server =
+        NoiseServer::<_, ()>::new_direct("server-key-id", b"server-device", ring_server.clone());
+
+    // Get server's static public key
+    // In production, this would be distributed securely
+    let server_sk = ring_server
+        .derive_device_x25519("server-key-id", b"server-device", 0)
+        .expect("Failed to derive server key");
+    let server_static_pk = pubky_noise::kdf::x25519_pk_from_sk(&server_sk);
+
+    println!("   Client and server initialized");
+    println!(
+        "   Server public key: {}...",
+        hex::encode(&server_static_pk[..8])
+    );
+
+    // =========================================================================
+    // 3-Step Handshake
+    // =========================================================================
+
+    println!("\n2. Performing 3-step handshake...");
+
+    // Step 1: Client initiates
+    println!("   Step 1: Client creates first message");
+    let (client_hs, first_msg) = client_start_ik_direct(&client, &server_static_pk, None)
+        .expect("Client initiation failed");
+    println!("   First message: {} bytes", first_msg.len());
+
+    // Step 2: Server processes and responds
+    println!("   Step 2: Server processes and responds");
+    let (server_hs, client_identity, response) =
+        server_accept_ik(&server, &first_msg).expect("Server accept failed");
+    println!(
+        "   Client identity: {:?}",
+        hex::encode(&client_identity.ed25519_pub[..8])
+    );
+    println!("   Response: {} bytes", response.len());
+
+    // Step 3: Both complete handshake
+    println!("   Step 3: Both complete handshake");
+    let mut client_link =
+        client_complete_ik(client_hs, &response).expect("Client completion failed");
+    let mut server_link = server_complete_ik(server_hs).expect("Server completion failed");
+
+    // Verify session IDs match
+    assert_eq!(client_link.session_id(), server_link.session_id());
+    println!(
+        "   Session established: {}",
+        client_link.session_id()
+    );
+
+    // =========================================================================
+    // Encrypted Communication
+    // =========================================================================
+
+    println!("\n3. Testing encrypted communication...");
+
+    // Client sends message to server
+    let client_message = b"Hello, server! This is encrypted.";
+    let ciphertext = client_link
+        .encrypt(client_message)
+        .expect("Encryption failed");
+    println!(
+        "   Client encrypted: {} bytes -> {} bytes",
+        client_message.len(),
+        ciphertext.len()
+    );
+
+    // Server decrypts
+    let decrypted = server_link.decrypt(&ciphertext).expect("Decryption failed");
+    assert_eq!(client_message.to_vec(), decrypted);
+    println!("   Server decrypted: {:?}", String::from_utf8_lossy(&decrypted));
+
+    // Server sends response
+    let server_response = b"Hello, client! Message received.";
+    let response_ct = server_link
+        .encrypt(server_response)
+        .expect("Encryption failed");
+    let response_pt = client_link
+        .decrypt(&response_ct)
+        .expect("Decryption failed");
+    assert_eq!(server_response.to_vec(), response_pt);
+    println!("   Client received: {:?}", String::from_utf8_lossy(&response_pt));
+
+    // =========================================================================
+    // Summary
+    // =========================================================================
+
+    println!("\n=== Handshake and communication successful! ===");
+    println!("\nKey points:");
+    println!("- IK pattern requires knowing server's public key upfront");
+    println!("- 3-step handshake: initiate -> accept -> complete");
+    println!("- After handshake, both parties can encrypt/decrypt");
+    println!("- Session ID is derived from handshake hash (unique per session)");
+}