feat: improve error handling and add path validation

- Change derive_x25519_for_device_epoch to return Result
- Add structured RateLimited error with retry_after_ms field
- Add path validation in StorageBackedMessaging::new()
- Update all call sites and tests

Author: JOHN

examples/error_handling.rs

@@ -181,10 +181,19 @@ fn main() {
                 // In production: back off, respect limits
             }
 
-            NoiseError::RateLimited(msg) => {
+            NoiseError::RateLimited {
+                message,
+                retry_after_ms,
+            } => {
                 // Rate limited - retry after delay
-                eprintln!("[RATE_LIMITED] {}: {} - will retry later", context, msg);
-                // In production: parse retry-after and wait
+                if let Some(delay_ms) = retry_after_ms {
+                    eprintln!(
+                        "[RATE_LIMITED] {}: {} - retry after {}ms",
+                        context, message, delay_ms
+                    );
+                } else {
+                    eprintln!("[RATE_LIMITED] {}: {} - will retry later", context, message);
+                }
             }
 
             NoiseError::MaxSessionsExceeded => {

fuzz/fuzz_targets/fuzz_handshake.rs

@@ -18,9 +18,7 @@ impl RingKeyProvider for FuzzRing {
         device_id: &[u8],
         epoch: u32,
     ) -> Result<[u8; 32], NoiseError> {
-        Ok(pubky_noise::kdf::derive_x25519_for_device_epoch(
-            &self.seed, device_id, epoch,
-        ))
+        pubky_noise::kdf::derive_x25519_for_device_epoch(&self.seed, device_id, epoch)
     }
 
     fn ed25519_pubkey(&self, _kid: &str) -> Result<[u8; 32], NoiseError> {

fuzz/fuzz_targets/fuzz_kdf.rs

@@ -16,15 +16,17 @@ struct KdfInput {
 
 fuzz_target!(|input: KdfInput| {
     // Test derive_x25519_for_device_epoch
-    let sk = derive_x25519_for_device_epoch(&input.seed, &input.device_id, input.epoch);
+    let sk = derive_x25519_for_device_epoch(&input.seed, &input.device_id, input.epoch)
+        .expect("HKDF should never fail with valid inputs");
 
     // Verify the key is clamped correctly (X25519 requirements)
     assert_eq!(sk[0] & 7, 0, "Low 3 bits should be cleared");
     assert_eq!(sk[31] & 128, 0, "High bit should be cleared");
     assert_eq!(sk[31] & 64, 64, "Bit 6 should be set");
 
     // Verify determinism
-    let sk2 = derive_x25519_for_device_epoch(&input.seed, &input.device_id, input.epoch);
+    let sk2 = derive_x25519_for_device_epoch(&input.seed, &input.device_id, input.epoch)
+        .expect("HKDF should never fail with valid inputs");
     assert_eq!(sk, sk2);
 
     // Test x25519_pk_from_sk doesn't panic

fuzz/fuzz_targets/fuzz_noise_link.rs

@@ -20,9 +20,7 @@ impl RingKeyProvider for FuzzRing {
         device_id: &[u8],
         epoch: u32,
     ) -> Result<[u8; 32], NoiseError> {
-        Ok(pubky_noise::kdf::derive_x25519_for_device_epoch(
-            &self.seed, device_id, epoch,
-        ))
+        pubky_noise::kdf::derive_x25519_for_device_epoch(&self.seed, device_id, epoch)
     }
 
     fn ed25519_pubkey(&self, _kid: &str) -> Result<[u8; 32], NoiseError> {

src/errors.rs

@@ -66,8 +66,13 @@ pub enum NoiseError {
     #[error("policy violation: {0}")]
     Policy(String),
 
-    #[error("rate limited: {0}")]
-    RateLimited(String),
+    #[error("rate limited: {message}")]
+    RateLimited {
+        message: String,
+        /// Optional retry delay in milliseconds.
+        /// When present, the client should wait at least this long before retrying.
+        retry_after_ms: Option<u64>,
+    },
 
     #[error("maximum sessions exceeded for this identity")]
     MaxSessionsExceeded,
@@ -108,7 +113,7 @@ impl NoiseError {
             Self::IdentityVerify => NoiseErrorCode::IdentityVerify,
             Self::RemoteStaticMissing => NoiseErrorCode::RemoteStaticMissing,
             Self::Policy(_) => NoiseErrorCode::Policy,
-            Self::RateLimited(_) => NoiseErrorCode::RateLimited,
+            Self::RateLimited { .. } => NoiseErrorCode::RateLimited,
             Self::MaxSessionsExceeded => NoiseErrorCode::MaxSessionsExceeded,
             Self::SessionExpired(_) => NoiseErrorCode::SessionExpired,
             Self::InvalidPeerKey => NoiseErrorCode::InvalidPeerKey,
@@ -133,18 +138,15 @@ impl NoiseError {
             Self::Network(_)
                 | Self::Timeout(_)
                 | Self::ConnectionReset(_)
-                | Self::RateLimited(_)
+                | Self::RateLimited { .. }
                 | Self::Storage(_)
         )
     }
 
     /// Returns a suggested retry delay in milliseconds, if applicable.
     pub fn retry_after_ms(&self) -> Option<u64> {
         match self {
-            Self::RateLimited(msg) => {
-                // Try to parse retry-after from message if encoded
-                msg.parse().ok()
-            }
+            Self::RateLimited { retry_after_ms, .. } => *retry_after_ms,
             Self::Network(_) | Self::Timeout(_) | Self::ConnectionReset(_) => Some(1000),
             Self::Storage(_) => Some(500),
             _ => None,

src/ffi/config.rs

@@ -1,3 +1,4 @@
+use crate::ffi::errors::FfiNoiseError;
 use crate::ffi::types::FfiMobileConfig;
 use crate::mobile_manager::MobileConfig;
 
@@ -30,13 +31,23 @@ pub fn performance_config() -> FfiMobileConfig {
     .into()
 }
 
+/// Derive an X25519 device key from seed, device ID, and epoch.
+///
+/// # Errors
+///
+/// Returns `FfiNoiseError::Other` if key derivation fails (extremely rare).
 #[uniffi::export]
-pub fn derive_device_key(seed: Vec<u8>, device_id: Vec<u8>, epoch: u32) -> Vec<u8> {
+pub fn derive_device_key(
+    seed: Vec<u8>,
+    device_id: Vec<u8>,
+    epoch: u32,
+) -> Result<Vec<u8>, FfiNoiseError> {
     let mut seed_arr = [0u8; 32];
     if seed.len() >= 32 {
         seed_arr.copy_from_slice(&seed[0..32]);
     }
-    crate::kdf::derive_x25519_for_device_epoch(&seed_arr, &device_id, epoch).to_vec()
+    let sk = crate::kdf::derive_x25519_for_device_epoch(&seed_arr, &device_id, epoch)?;
+    Ok(sk.to_vec())
 }
 
 #[uniffi::export]

src/ffi/errors.rs

@@ -39,7 +39,11 @@ pub enum FfiNoiseError {
     Decryption { message: String },
 
     #[error("Rate limited: {message}")]
-    RateLimited { message: String },
+    RateLimited {
+        message: String,
+        /// Optional retry delay in milliseconds.
+        retry_after_ms: Option<u64>,
+    },
 
     #[error("Maximum sessions exceeded")]
     MaxSessionsExceeded,
@@ -69,7 +73,13 @@ impl From<NoiseError> for FfiNoiseError {
             NoiseError::Timeout(msg) => FfiNoiseError::Timeout { message: msg },
             NoiseError::Storage(msg) => FfiNoiseError::Storage { message: msg },
             NoiseError::Decryption(msg) => FfiNoiseError::Decryption { message: msg },
-            NoiseError::RateLimited(msg) => FfiNoiseError::RateLimited { message: msg },
+            NoiseError::RateLimited {
+                message,
+                retry_after_ms,
+            } => FfiNoiseError::RateLimited {
+                message,
+                retry_after_ms,
+            },
             NoiseError::MaxSessionsExceeded => FfiNoiseError::MaxSessionsExceeded,
             NoiseError::SessionExpired(msg) => FfiNoiseError::SessionExpired { message: msg },
             NoiseError::ConnectionReset(msg) => FfiNoiseError::ConnectionReset { message: msg },

src/kdf.rs

@@ -1,19 +1,34 @@
+use crate::errors::NoiseError;
 use hkdf::Hkdf;
 use sha2::Sha512;
 use zeroize::Zeroizing;
 
-pub fn derive_x25519_for_device_epoch(seed: &[u8; 32], device_id: &[u8], epoch: u32) -> [u8; 32] {
+/// Derive an X25519 secret key from a seed, device ID, and epoch.
+///
+/// Uses HKDF-SHA512 with a fixed salt to derive keys deterministically.
+/// The resulting key is clamped for X25519 compatibility.
+///
+/// # Errors
+///
+/// Returns `NoiseError::Other` if HKDF expansion fails (should never happen
+/// with valid 32-byte output, but we handle it explicitly for robustness).
+pub fn derive_x25519_for_device_epoch(
+    seed: &[u8; 32],
+    device_id: &[u8],
+    epoch: u32,
+) -> Result<[u8; 32], NoiseError> {
     let salt = b"pubky-noise-x25519:v1";
     let hk = Hkdf::<Sha512>::new(Some(salt), seed);
     let mut info = Vec::with_capacity(device_id.len() + 4);
     info.extend_from_slice(device_id);
     info.extend_from_slice(&epoch.to_le_bytes());
     let mut sk = [0u8; 32];
-    hk.expand(&info, &mut sk).expect("hkdf expand");
+    hk.expand(&info, &mut sk)
+        .map_err(|e| NoiseError::Other(format!("HKDF expand failed: {:?}", e)))?;
     sk[0] &= 248;
     sk[31] &= 127;
     sk[31] |= 64;
-    sk
+    Ok(sk)
 }
 
 pub fn x25519_pk_from_sk(sk: &[u8; 32]) -> [u8; 32] {

src/mobile_manager.rs

@@ -453,8 +453,8 @@ impl<R: RingKeyProvider> NoiseManager<R> {
             .get(session_id)
             .ok_or_else(|| NoiseError::Other("Session state not found".to_string()))?;
 
-        let mut messaging =
-            StorageBackedMessaging::new(link, session, public_client, write_path, read_path);
+        let messaging =
+            StorageBackedMessaging::new(link, session, public_client, write_path, read_path)?;
 
         // Configure with retry settings appropriate for mobile
         let retry_config = RetryConfig {
@@ -468,7 +468,7 @@ impl<R: RingKeyProvider> NoiseManager<R> {
             operation_timeout_ms: 30000,
         };
 
-        messaging = messaging
+        let messaging = messaging
             .with_counters(state.write_counter, state.read_counter)
             .with_retry_config(retry_config);
 

src/pubky_ring.rs

@@ -27,8 +27,7 @@ impl RingKeyProvider for PubkyRingProvider {
         epoch: u32,
     ) -> Result<[u8; 32], NoiseError> {
         let seed = self.keypair.secret_key();
-        let sk = crate::kdf::derive_x25519_for_device_epoch(&seed, device_id, epoch);
-        Ok(sk)
+        crate::kdf::derive_x25519_for_device_epoch(&seed, device_id, epoch)
     }
 
     fn ed25519_pubkey(&self, _kid: &str) -> Result<[u8; 32], NoiseError> {