feat: add XX/NN patterns, secure-mem, handshake-queue, path normalization

- Implement full XX pattern (TOFU) with identity binding
- Add NN pattern with explicit security warnings
- Add HandshakeQueue for async storage-backed handshakes
- Add secure-mem feature with LockedBytes (RAII mlock)
- Fix path normalization to prevent // in storage paths
- Align FFI mutex poisoning with availability-first strategy
- Regenerate Swift/Kotlin bindings
- Add fuzz targets for XX and NN patterns
- Fix docs to clarify reconnection is app-implemented

Author: JOHN

Cargo.toml

@@ -13,8 +13,8 @@ crate-type = ["cdylib", "staticlib", "rlib"]
 default = []
 pkarr = []
 trace = ["tracing"]
-# secure-mem: Reserved for future mlock-based memory protection.
-# Currently a no-op; applications should use platform secure storage for keys.
+# secure-mem: Best-effort mlock-based memory protection for key material.
+# Uses region crate for platform-specific memory locking. Falls back silently if unavailable.
 secure-mem = ["region"]
 pubky-sdk = ["dep:pubky"]
 storage-queue = ["dep:pubky", "dep:async-trait", "dep:tokio"]
@@ -42,7 +42,7 @@ tracing = { version = "0.1", optional = true }
 region = { version = "3", optional = true }
 pubky = { git = "https://github.com/BitcoinErrorLog/pubky-core", rev = "290d801", optional = true }
 async-trait = { version = "0.1", optional = true }
-tokio = { version = "1", features = ["rt"], optional = true }
+tokio = { version = "1", features = ["rt", "time"], optional = true }
 uniffi = { version = "0.29.4", optional = true }
 uniffi_bindgen = { version = "0.29.4", optional = true }
 camino = { version = "1.1", optional = true }

README.md

@@ -25,15 +25,15 @@ Direct client↔server Noise sessions for Pubky using `snow`. Default build is d
 ## Specs and suites
 
 * Noise revision: 34 (as implemented by current `snow`).
-* Suites: `Noise_XX_25519_ChaChaPoly_BLAKE2s` and `Noise_IK_25519_ChaChaPoly_BLAKE2s`.
+* Suites: `Noise_XX_25519_ChaChaPoly_BLAKE2s`, `Noise_IK_25519_ChaChaPoly_BLAKE2s`, and `Noise_NN_25519_ChaChaPoly_BLAKE2s`.
 * Hash: BLAKE2s. AEAD: ChaCha20-Poly1305. DH: X25519.
 
 ## Features
 
 * `default = []`: direct-only, no PKARR, no extra dependencies.
 * `pkarr`: optional signed metadata fetch and verification for server static and epoch.
 * `trace`: opt-in `tracing` for non-sensitive logs.
-* `secure-mem`: reserved for future best-effort memory hardening (currently a no-op).
+* `secure-mem`: Best-effort memory hardening using platform mlock. Use `LockedBytes<N>` wrapper for sensitive key material.
 * `pubky-sdk`: Convenience wrapper for `RingKeyProvider` using Pubky SDK `Keypair`.
 * `storage-queue`: Support for storage-backed messaging using Pubky storage as a queue (requires `pubky` and `async-trait`).
 
@@ -149,19 +149,69 @@ queue = queue.with_retry_config(retry_config);
 
 ## Handshake flows
 
-### First contact (TOFU or OOB token)
+### IK Pattern: Pinned server static (recommended)
 
-* Pattern: `XX`.
-* Client: `NoiseClient::build_initiator_xx_tofu(hint) -> (HandshakeState, first_msg)`.
-* Server: `NoiseServer::build_responder_read_xx(first_msg) -> HandshakeState`.
-* Caller pins the server static post-handshake through an out-of-band path, then uses IK for future connections.
-
-### Pinned server static
+When you already know the server's static key (from a previous XX handshake or out-of-band):
 
 * Pattern: `IK`.
 * Client: `NoiseClient::build_initiator_ik_direct(server_static_pub, hint) -> (HandshakeState, first_msg)`.
 * Server: `NoiseServer::build_responder_read_ik(first_msg) -> (HandshakeState, IdentityPayload)`.
 
+### XX Pattern: First contact (TOFU)
+
+For first contact when the server's static key is unknown:
+
+* Pattern: `XX`.
+* Client: `NoiseClient::build_initiator_xx_tofu(hint) -> (HandshakeState, first_msg, hint)`.
+* Server: `NoiseServer::build_responder_xx(first_msg) -> (HandshakeState, response, server_pk)`.
+* Client: `NoiseClient::complete_initiator_xx(hs, response, hint) -> (HandshakeState, final_msg, server_identity, server_pk)`.
+* Server: `NoiseServer::complete_responder_xx(hs, final_msg, server_pk) -> (HandshakeState, client_identity)`.
+* **After handshake**: Pin the learned `server_pk` and use IK for future connections.
+
+```rust
+use pubky_noise::datalink_adapter::{
+    client_start_xx_tofu, server_accept_xx, client_complete_xx, server_complete_xx
+};
+
+// Step 1: Client initiates (no server key needed)
+let init = client_start_xx_tofu(&client, Some("server.example.com"))?;
+
+// Step 2: Server accepts and responds with identity
+let (s_hs, response, server_pk) = server_accept_xx(&server, &init.first_msg)?;
+
+// Step 3a: Client completes and learns server's key
+let (result, final_msg) = client_complete_xx(&client, init.hs, &response, init.server_hint.as_deref())?;
+
+// Step 3b: Server completes
+let (s_link, client_id) = server_complete_xx(&server, s_hs, &final_msg, &server_pk)?;
+
+// Pin server_pk for future IK connections!
+save_pinned_key(result.server_static_pk);
+```
+
+### NN Pattern: Ephemeral-only (NO AUTHENTICATION)
+
+> ⚠️ **Security Warning**: The NN pattern provides **forward secrecy only** with NO identity binding. An active attacker can trivially MITM this connection. Use ONLY when:
+> - The transport layer provides authentication (e.g., TLS with pinned certs)
+> - You are building a higher-level authenticated protocol on top
+> - You explicitly accept the MITM risk for your use case
+
+* Pattern: `NN`.
+* Client: `NoiseClient::build_initiator_nn() -> (HandshakeState, first_msg)`.
+* Server: `NoiseServer::build_responder_nn(first_msg) -> (HandshakeState, response)`.
+* Client: `NoiseClient::complete_initiator_nn(hs, response) -> HandshakeState`.
+
+```rust
+use pubky_noise::datalink_adapter::{client_start_nn, server_accept_nn, client_complete_nn, server_complete_nn};
+
+// WARNING: NO AUTHENTICATION!
+let (c_hs, first_msg) = client_start_nn(&client)?;
+let (s_hs, response) = server_accept_nn(&server, &first_msg)?;
+let c_link = client_complete_nn(&client, c_hs, &response)?;
+let s_link = server_complete_nn(s_hs)?;
+// DANGER: You have NO cryptographic proof of who you're talking to!
+```
+
 ## Quick start
 
 ### Build and test

THREAT_MODEL.md

@@ -34,8 +34,9 @@
 │  └─────────────────────────────────────────┘   │
 │  ┌─────────────────────────────────────────┐   │
 │  │   Noise Protocol (via snow library)     │   │
-│  │   - XX pattern (first contact)          │   │
 │  │   - IK pattern (known server)           │   │
+│  │   - XX pattern (first contact/TOFU)     │   │
+│  │   - NN pattern (ephemeral-only)*        │   │
 │  └─────────────────────────────────────────┘   │
 │  ┌─────────────────────────────────────────┐   │
 │  │   Key Management (Ring/Pubky SDK)       │   │
@@ -498,6 +499,41 @@ FFI errors are mapped to structured error codes:
 
 ---
 
+### 5. NN Pattern (Ephemeral-Only) ⚠️ HIGH RISK
+
+**CRITICAL WARNING**: The NN pattern provides **ZERO AUTHENTICATION**.
+
+**Security Properties**:
+- ✅ Forward secrecy (ephemeral keys)
+- ❌ NO identity binding
+- ❌ NO impersonation protection
+- ❌ Trivial MITM attacks possible
+
+**Attack Scenario**:
+```
+Client ←→ [Active Attacker] ←→ Server
+```
+An active attacker can:
+1. Intercept client's ephemeral key
+2. Complete handshake with client using attacker's ephemeral
+3. Complete separate handshake with server using attacker's ephemeral
+4. Decrypt all traffic, re-encrypt for the other party
+
+**Valid Use Cases**:
+- Transport layer already provides authentication (TLS with pinned certs)
+- Building higher-level authenticated protocol on top
+- Testing/development environments
+- Explicit acceptance of MITM risk for specific use case
+
+**NEVER Use For**:
+- Production systems without external authentication
+- Any system requiring identity verification
+- Financial or sensitive data transfer
+
+**Recommendation**: Use IK (known peer) or XX (TOFU) patterns instead. NN is included only for completeness and specific transport-layer integration scenarios.
+
+---
+
 ## Security Checklist for Applications
 
 ### ✅ MUST Implement

docs/MOBILE_INTEGRATION.md

@@ -24,7 +24,7 @@ This guide explains how to integrate `pubky-noise` into mobile applications (iOS
 ├─────────────────────────────────────────────────┤
 │  NoiseManager (High-level lifecycle)            │
 │    ├─ Session State Persistence                 │
-│    ├─ Automatic Reconnection                    │
+│    ├─ Reconnection Hints (app-implemented)      │
 │    └─ Mobile Configuration                      │
 ├─────────────────────────────────────────────────┤
 │  StorageBackedMessaging (Optional)              │

docs/archive/IMPLEMENTATION_SUMMARY.md

@@ -144,7 +144,7 @@ See `docs/FFI_IMPLEMENTATION_SUMMARY.md` for detailed FFI implementation specifi
 ### 4. Mobile Optimization
 - Battery saver mode
 - Mobile-friendly chunk sizes (32KB default)
-- Automatic reconnection
+- Reconnection hints (app-implemented)
 - Memory-efficient operation
 
 ### 5. Error Handling

fuzz/Cargo.toml

@@ -51,3 +51,17 @@ test = false
 doc = false
 bench = false
 
+[[bin]]
+name = "fuzz_xx_handshake"
+path = "fuzz_targets/fuzz_xx_handshake.rs"
+test = false
+doc = false
+bench = false
+
+[[bin]]
+name = "fuzz_nn_handshake"
+path = "fuzz_targets/fuzz_nn_handshake.rs"
+test = false
+doc = false
+bench = false
+

fuzz/fuzz_targets/fuzz_nn_handshake.rs

@@ -0,0 +1,109 @@
+#![no_main]
+
+//! Fuzz target for NN pattern handshake message parsing.
+//!
+//! Tests that the server gracefully handles malformed NN handshake messages
+//! without panicking.
+//!
+//! # Security Note
+//!
+//! The NN pattern provides NO authentication. This fuzz target tests
+//! implementation robustness, not security properties.
+
+use arbitrary::Arbitrary;
+use libfuzzer_sys::fuzz_target;
+use pubky_noise::{NoiseClient, NoiseError, NoiseServer, RingKeyProvider};
+use std::sync::Arc;
+
+/// A simple key provider for fuzzing
+struct FuzzRing {
+    seed: [u8; 32],
+}
+
+impl RingKeyProvider for FuzzRing {
+    fn derive_device_x25519(
+        &self,
+        _kid: &str,
+        device_id: &[u8],
+        epoch: u32,
+    ) -> Result<[u8; 32], NoiseError> {
+        pubky_noise::kdf::derive_x25519_for_device_epoch(&self.seed, device_id, epoch)
+    }
+
+    fn ed25519_pubkey(&self, _kid: &str) -> Result<[u8; 32], NoiseError> {
+        use sha2::{Digest, Sha256};
+        let mut hasher = Sha256::new();
+        hasher.update(&self.seed);
+        hasher.update(b"ed25519_pubkey");
+        let result = hasher.finalize();
+        let mut pk = [0u8; 32];
+        pk.copy_from_slice(&result[..32]);
+        Ok(pk)
+    }
+
+    fn sign_ed25519(&self, _kid: &str, _msg: &[u8]) -> Result<[u8; 64], NoiseError> {
+        Ok([0x42u8; 64])
+    }
+}
+
+/// Arbitrary input for NN handshake fuzzing
+#[derive(Debug, Arbitrary)]
+struct NnInput {
+    client_seed: [u8; 32],
+    server_seed: [u8; 32],
+    /// Fuzzed first message (should be ephemeral key only)
+    malformed_first_msg: Vec<u8>,
+    /// Fuzzed response (should be server ephemeral + ee)
+    malformed_response: Vec<u8>,
+}
+
+fuzz_target!(|input: NnInput| {
+    // Skip very large messages to avoid OOM
+    if input.malformed_first_msg.len() > 65536 || input.malformed_response.len() > 65536 {
+        return;
+    }
+
+    let client_ring = Arc::new(FuzzRing {
+        seed: input.client_seed,
+    });
+    let server_ring = Arc::new(FuzzRing {
+        seed: input.server_seed,
+    });
+
+    let client = NoiseClient::<_, ()>::new_direct("fuzz_client", b"client", client_ring);
+    let server = NoiseServer::<_, ()>::new_direct("fuzz_server", b"server", server_ring);
+
+    // Test 1: Server handling malformed NN first message
+    // This should NOT panic, just return an error
+    let nn_result = server.build_responder_nn(&input.malformed_first_msg);
+    match nn_result {
+        Ok((_hs, _response)) => {
+            // If somehow valid, that's fine - NN is lenient
+        }
+        Err(_) => {
+            // Expected - malformed messages should be rejected gracefully
+        }
+    }
+
+    // Test 2: Valid NN initiation followed by malformed response handling
+    let init_result = client.build_initiator_nn();
+    if let Ok((hs, first_msg)) = init_result {
+        // Server processes valid first message
+        if let Ok((_server_hs, response)) = server.build_responder_nn(&first_msg) {
+            // Client tries to complete with fuzzed data instead of valid response
+            let complete_result = client.complete_initiator_nn(hs, &input.malformed_response);
+            // Should not panic
+            let _ = complete_result;
+        }
+    }
+
+    // Test 3: Test with random first message, valid response flow
+    if let Ok((hs, _)) = client.build_initiator_nn() {
+        // Pass malformed data as first message to server
+        if let Ok((_, valid_response)) = server.build_responder_nn(&input.malformed_first_msg) {
+            // Client completes with this response (may fail, but shouldn't panic)
+            let _ = client.complete_initiator_nn(hs, &valid_response);
+        }
+    }
+});
+