feat: add client expiry, CLI improvements, tests, and CHANGELOG

- Implement client-side expiry with now_unix and expiry_secs fields
- Add with_now_unix() and with_expiry_secs() builder methods
- Replace panics in uniffi-bindgen with proper error handling
- Add --help flag and usage documentation to CLI
- Create timeout_and_validation.rs test file
- Update CHANGELOG with v1.1.0 breaking changes

Author: JOHN

CHANGELOG.md

@@ -5,6 +5,63 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2025-12-22
+
+### Breaking Changes
+
+- **HKDF Key Derivation**: `derive_x25519_for_device_epoch()` now returns `Result<[u8; 32], NoiseError>` instead of panicking
+  - All call sites must handle the `Result` type
+  - Affected: `RingKeyProvider::derive_device_x25519()` implementations
+  - FFI: `derive_device_key()` now returns `Result<Vec<u8>, FfiNoiseError>`
+
+- **Rate Limit Error**: `NoiseError::RateLimited` changed from tuple variant to struct variant
+  - Old: `RateLimited(String)`
+  - New: `RateLimited { message: String, retry_after_ms: Option<u64> }`
+  - FFI: `FfiNoiseError::RateLimited` also updated with same structure
+
+- **Storage Path Validation**: `StorageBackedMessaging::new()` now returns `Result<Self, NoiseError>`
+  - Validates paths for safety (no traversal, valid characters, length limits)
+  - Invalid paths return `NoiseError::Storage` error
+
+### Added
+
+- **Client-Side Expiry**: `NoiseClient` now supports handshake expiry
+  - Set `now_unix` to enable `expires_at` computation in identity payloads
+  - Default expiry: 300 seconds (5 minutes)
+  - Builder methods: `with_now_unix(u64)` and `with_expiry_secs(u64)`
+
+- **Timeout Enforcement**: Storage operations now enforce timeouts (non-WASM only)
+  - Uses `operation_timeout_ms` from `RetryConfig` (default: 30 seconds)
+  - Returns `NoiseError::Timeout` on timeout with exhausted retries
+  - Documented WASM limitation (no timeout enforcement)
+
+- **Path Validation**: Strict validation for `StorageBackedMessaging` paths
+  - Must start with `/`
+  - Maximum 1024 characters
+  - Allowed: alphanumeric, `/`, `-`, `_`, `.`
+  - Rejects `..` (path traversal) and `//` (double slashes)
+
+- **CLI Improvements**: `uniffi-bindgen` CLI now has proper error handling
+  - Usage help with `--help` flag
+  - Descriptive error messages instead of panics
+  - Examples for Swift and Kotlin binding generation
+
+- **Test Coverage**: New `timeout_and_validation.rs` test file
+  - Path validation tests
+  - HKDF error handling tests
+  - Rate limit error structure tests
+  - Client expiry computation tests
+
+### Fixed
+
+- **Error Propagation**: HKDF errors now propagate properly instead of panicking
+- **Panic Removal**: Removed all panics from `uniffi-bindgen` CLI
+
+### Documentation
+
+- Updated `storage_queue` module docs with timeout and path validation info
+- Added doc comments for new `NoiseClient` expiry fields and methods
+
 ## [1.0.1] - 2025-12-12
 
 ### Security Improvements

src/bin/uniffi_bindgen.rs

@@ -1,19 +1,65 @@
+//! UniFFI binding generator CLI for pubky-noise.
+//!
+//! Generates Swift or Kotlin bindings from the compiled library.
+//!
+//! # Usage
+//!
+//! ```bash
+//! cargo run --bin uniffi_bindgen -- generate \
+//!     --library target/debug/libpubky_noise.dylib \
+//!     --language swift \
+//!     --out-dir ./generated
+//! ```
+
 use camino::Utf8Path;
 use std::path::PathBuf;
 use uniffi_bindgen::{
+    bindings::{KotlinBindingGenerator, SwiftBindingGenerator},
     library_mode::generate_bindings,
     EmptyCrateConfigSupplier,
-    bindings::{SwiftBindingGenerator, KotlinBindingGenerator},
 };
 
+const USAGE: &str = r#"UniFFI Binding Generator for pubky-noise
+
+USAGE:
+    uniffi_bindgen generate --library <PATH> --language <LANG> --out-dir <DIR>
+
+ARGUMENTS:
+    --library <PATH>    Path to the compiled library (.dylib, .so, or .a)
+    --language <LANG>   Target language: 'swift' or 'kotlin'
+    --out-dir <DIR>     Output directory for generated bindings
+
+OPTIONS:
+    -h, --help          Show this help message
+
+EXAMPLES:
+    # Generate Swift bindings
+    cargo run --bin uniffi_bindgen -- generate \
+        --library target/debug/libpubky_noise.dylib \
+        --language swift \
+        --out-dir ./platforms/ios/Sources
+
+    # Generate Kotlin bindings
+    cargo run --bin uniffi_bindgen -- generate \
+        --library target/debug/libpubky_noise.so \
+        --language kotlin \
+        --out-dir ./platforms/android/src/main/kotlin
+"#;
+
 fn main() -> anyhow::Result<()> {
     let args: Vec<String> = std::env::args().collect();
 
+    // Check for help flag
+    if args.iter().any(|a| a == "-h" || a == "--help") {
+        println!("{}", USAGE);
+        return Ok(());
+    }
+
     // Parse arguments manually
     let mut library_path: Option<PathBuf> = None;
     let mut language: Option<String> = None;
     let mut out_dir: Option<PathBuf> = None;
-    
+
     let mut i = 1;
     while i < args.len() {
         match args[i].as_str() {
@@ -41,14 +87,28 @@ fn main() -> anyhow::Result<()> {
         i += 1;
     }
 
-    let library = library_path.expect("Missing --library argument");
-    let lang = language.expect("Missing --language argument");
-    let output = out_dir.expect("Missing --out-dir argument");
+    let library = library_path.ok_or_else(|| {
+        eprintln!("Error: Missing --library argument\n");
+        eprintln!("{}", USAGE);
+        anyhow::anyhow!("Missing --library argument")
+    })?;
+
+    let lang = language.ok_or_else(|| {
+        eprintln!("Error: Missing --language argument\n");
+        eprintln!("{}", USAGE);
+        anyhow::anyhow!("Missing --language argument")
+    })?;
+
+    let output = out_dir.ok_or_else(|| {
+        eprintln!("Error: Missing --out-dir argument\n");
+        eprintln!("{}", USAGE);
+        anyhow::anyhow!("Missing --out-dir argument")
+    })?;
 
     let lib_path = Utf8Path::from_path(&library)
-        .ok_or_else(|| anyhow::anyhow!("Invalid UTF-8 in library path"))?;
+        .ok_or_else(|| anyhow::anyhow!("Invalid UTF-8 in library path: {:?}", library))?;
     let out_path = Utf8Path::from_path(&output)
-        .ok_or_else(|| anyhow::anyhow!("Invalid UTF-8 in output path"))?;
+        .ok_or_else(|| anyhow::anyhow!("Invalid UTF-8 in output path: {:?}", output))?;
 
     match lang.to_lowercase().as_str() {
         "swift" => {
@@ -73,7 +133,14 @@ fn main() -> anyhow::Result<()> {
                 false,
             )?;
         }
-        other => panic!("Unsupported language: {}", other),
+        other => {
+            eprintln!("Error: Unsupported language '{}'\n", other);
+            eprintln!("Supported languages: swift, kotlin");
+            return Err(anyhow::anyhow!(
+                "Unsupported language '{}'. Use 'swift' or 'kotlin'.",
+                other
+            ));
+        }
     }
 
     println!("Bindings generated successfully at {:?}", output);

src/client.rs

@@ -7,14 +7,27 @@ use zeroize::Zeroizing;
 /// Internal epoch value - always 0 (epoch is not a user-facing concept).
 const INTERNAL_EPOCH: u32 = 0;
 
+/// Default handshake expiry duration in seconds (5 minutes).
+///
+/// When `now_unix` is set on the client, this value is added to compute `expires_at`.
+/// Servers MUST reject payloads with timestamps in the past, which provides
+/// replay protection for handshake initiation.
+const DEFAULT_HANDSHAKE_EXPIRY_SECS: u64 = 300;
+
 pub struct NoiseClient<R: RingKeyProvider, P = ()> {
     pub kid: String,
     pub device_id: Vec<u8>,
     pub ring: std::sync::Arc<R>,
     _phantom: PhantomData<P>,
     pub prologue: Vec<u8>,
     pub suite: String,
+    /// Current Unix timestamp in seconds. When set, enables handshake expiry.
+    ///
+    /// Setting this causes the client to include `expires_at = now_unix + 300` in the
+    /// identity payload, providing replay protection for handshake messages.
     pub now_unix: Option<u64>,
+    /// Custom expiry duration in seconds. Defaults to 300 (5 minutes).
+    pub expiry_secs: u64,
 }
 
 impl<R: RingKeyProvider, P> NoiseClient<R, P> {
@@ -31,9 +44,25 @@ impl<R: RingKeyProvider, P> NoiseClient<R, P> {
             prologue: b"pubky-noise-v1".to_vec(),
             suite: "Noise_IK_25519_ChaChaPoly_BLAKE2s".into(),
             now_unix: None,
+            expiry_secs: DEFAULT_HANDSHAKE_EXPIRY_SECS,
         }
     }
 
+    /// Set the current Unix timestamp to enable handshake expiry.
+    ///
+    /// When set, the handshake payload will include `expires_at = now_unix + expiry_secs`,
+    /// which servers can use to reject replayed handshake messages.
+    pub fn with_now_unix(mut self, now_unix: u64) -> Self {
+        self.now_unix = Some(now_unix);
+        self
+    }
+
+    /// Set a custom expiry duration (default is 300 seconds / 5 minutes).
+    pub fn with_expiry_secs(mut self, secs: u64) -> Self {
+        self.expiry_secs = secs;
+        self
+    }
+
     /// Build an IK pattern initiator handshake.
     ///
     /// # Arguments
@@ -78,9 +107,9 @@ impl<R: RingKeyProvider, P> NoiseClient<R, P> {
         )??;
         let ed_pub = self.ring.ed25519_pubkey(&self.kid)?;
 
-        // No expiration by default for backward compatibility
-        // Clients can set now_unix to enable expiration if desired
-        let expires_at: Option<u64> = None;
+        // Compute expiration if now_unix is set (enables replay protection)
+        // When now_unix is None, expires_at is None for backward compatibility
+        let expires_at: Option<u64> = self.now_unix.map(|now| now + self.expiry_secs);
 
         let msg32 = make_binding_message(&BindingMessageParams {
             pattern_tag: "IK",