Production-ready sprint: security hardening, persistence, and structured errors

Stories delivered (520 tests, all passing):
- STORY-001: Auto-start mailbox listener in StartListeningAsync
- STORY-002: SenderIdentityKey field on EncryptedMessage for O(1) session routing
- STORY-003: Prekey bundle API (IKeyBundleTransport, fetch/upload/cache with 72h TTL)
- STORY-004: OPK consumption tracking and auto-replenishment
- STORY-005: Group replay protection (per-sender message ID deduplication)
- STORY-006: Post-removal forward secrecy (chain key rotation on member removal)
- STORY-007: Chat session replay protection (500-entry sliding window)
- STORY-008: Encrypted device list persistence (AES-GCM, atomic writes, lazy load)
- STORY-009: SendToDeviceAsync for multi-device message routing
- STORY-010: Explicit CreateChatSessionAsync overloads (identity key vs full bundle)
- STORY-011: IAsyncDisposable on LibEmiddleClient
- STORY-012: LibEmiddleException with LibEmiddleErrorCode enum (12 error codes)

Security improvements: replay attack prevention, encrypted device persistence,
structured transport exceptions, post-removal group forward secrecy.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: rbenzing

CHANGELOG.md

@@ -12,6 +12,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Password KDF Overload**: New `CryptoProvider.DeriveKeyFromPassword(string password, byte[] salt)` overload accepting a caller-supplied random salt for non-deterministic key derivation
 - **Shared Key Conversion Helper**: New `LibEmiddle.Core.KeyConversion.ConvertEd25519PublicKeyToX25519()` consolidating duplicate Ed25519→X25519 conversion logic previously spread across `DeviceManager` and `DeviceLinkingService`
 - **Unit Tests**: Added 60+ new unit tests covering `MessageSigning`, `AES` detached encryption, `Nonce` thread-safety, `EnhancedFileStorageProvider`, `PostQuantumCrypto`, stub infrastructure visibility, and `SessionManager` bundle/group session paths
+- **Group Replay Protection**: `GroupSession` now detects and rejects duplicate messages using a per-sender `_seenMessageIds` set (capped at 1 000 entries) checked before decryption; replay attempts return `null` without exposing ciphertext errors
+- **Group Member-Removal Key Rotation**: `GroupSession.RemoveMemberAsync()` automatically rotates the chain key via `RotateKeyInternalAsync()` after each successful removal, ensuring forward secrecy for the remaining group; attempting to remove a non-member is a no-op and does not rotate the key
+- **Chat Session Replay Protection**: `ChatSession` tracks processed message IDs in a 500-entry FIFO ring buffer (`_processedMessageIds`); duplicate messages return `null` by default or throw `InvalidOperationException` when `throwOnReplay: true` is passed to `DecryptAsync`
+- **Device List Persistence**: New `DeviceStorage` class persists the linked-device list to an AES-GCM–encrypted file (fresh key and nonce per write, atomic temp-then-rename) so devices survive process restarts; `DeviceManager` accepts an optional `storagePath` and lazily loads the list on first access via double-checked locking
+- **`LibEmiddleException`**: New domain exception type (`LibEmiddle.Domain.Exceptions.LibEmiddleException`) inheriting from `Exception`, carrying a typed `ErrorCode` property (`LibEmiddleErrorCode` enum with 12 values: `Unknown`, `InvalidBundle`, `ReplayDetected`, `DecryptionFailed`, `TransportError`, `KeyNotFound`, `SessionNotFound`, `DeviceNotFound`, `OPKExhausted`, `InvalidKey`, `InvalidMessage`, `PermissionDenied`)
+- **Mailbox Listener Auto-Start**: `LibEmiddleClient.StartListeningAsync()` now automatically calls `_mailboxManager.Start()` so incoming-message polling begins without a separate call
+- **Sender Identity Routing**: `EncryptedMessage` now carries a `SenderIdentityKey` field; `ProcessChatMessageAsync` uses it for O(1) session lookup by sender key rather than iterating all sessions
+- **OPK Consumption Tracking**: `OPKManager.TryConsume()` marks one-time prekeys as consumed and triggers automatic replenishment when the available count falls below the configured threshold
+- **`IAsyncDisposable` on `LibEmiddleClient`**: `LibEmiddleClient` now implements `IAsyncDisposable` in addition to `IDisposable`, using the canonical `DisposeAsync → Dispose(true) → GC.SuppressFinalize` pattern for safe `await using` cleanup
 
 ### Changed
 - **Password Key Derivation**: Migrated from HKDF with a fixed static salt to **Argon2id** (via libsodium's `crypto_pwhash`) for memory-hard password-based key derivation (64 MB, 2 passes). The deterministic overload uses a fixed application-specific salt; the new overload accepts a random salt
@@ -20,6 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Batch Serialization**: Replaced reflection-based `MakeGenericMethod` in `BatchAsync` with the BCL's `JsonSerializer.Serialize(object?, Type, JsonSerializerOptions?)` overload, eliminating runtime reflection
 - **Disposal Guards**: Changed all `bool _disposed` fields to `volatile bool _disposed` across all `IDisposable` classes for correct thread-safe disposal checks
 - **Timer Callback**: `EnhancedFileStorageProvider.CleanupExpiredItems` refactored to `async void` + inner `DoCleanupExpiredItemsAsync()` pattern, eliminating the `.Wait()` call that could deadlock on synchronization contexts
+- **`SecureWebSocketClient` Exceptions**: Transport-layer failures now throw `LibEmiddleException` with `LibEmiddleErrorCode.TransportError` (wrapping the original exception as `InnerException`) instead of generic `Exception`, giving callers structured error handling
 
 ### Fixed
 - **AES-GCM Detached Decryption**: Corrected the P/Invoke signature for `crypto_aead_aes256gcm_decrypt_detached_afternm` in `Sodium.cs` — removed the erroneous `out ulong mlen_p` second parameter that does not exist in this libsodium entry point, which was causing all AES-GCM detached decryption to fail
@@ -28,6 +38,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 - **Argon2id Password Hardening**: The Argon2id KDF (64 MB memory, 2 iterations) is orders of magnitude more resistant to GPU/ASIC brute-force attacks than the previous HKDF-with-fixed-salt approach
+- **Group Replay Attack Prevention**: Each `GroupSession` maintains per-sender message ID sets; replayed or duplicated ciphertexts are silently dropped before decryption is attempted
+- **Post-Removal Forward Secrecy**: Removing a group member immediately generates a new cryptographically independent chain key; the removed member's previously held key material cannot decrypt any subsequent message
+- **Chat Replay Attack Prevention**: `ChatSession` rejects message-ID duplicates within a 500-message sliding window, preventing replay of captured ciphertexts
+- **Encrypted Device Persistence**: Linked-device lists are stored with AES-GCM authenticated encryption; any tampered or corrupted file is rejected at load time
 
 ## [2.5.1] - 2025-12-22
 

LibEmiddle.Abstractions/IMailboxTransport.cs

@@ -2,6 +2,32 @@
 
 namespace LibEmiddle.Abstractions;
 
+/// <summary>
+/// Optional capability interface for transports that support publishing and fetching
+/// X3DH key bundles. Implement this interface alongside <see cref="IMailboxTransport"/>
+/// to enable <c>UploadKeyBundleAsync</c> / <c>FetchRecipientKeyBundleAsync</c> on the client.
+/// </summary>
+public interface IKeyBundleTransport
+{
+    /// <summary>
+    /// Uploads the caller's public key bundle to the transport server so that
+    /// other parties can initiate X3DH sessions without a pre-cached bundle.
+    /// </summary>
+    /// <param name="bundle">The public bundle to publish.</param>
+    /// <returns>A task that completes when the bundle has been uploaded.</returns>
+    Task UploadKeyBundleAsync(X3DHPublicBundle bundle);
+
+    /// <summary>
+    /// Fetches the public key bundle for the specified recipient identity key.
+    /// </summary>
+    /// <param name="recipientIdentityKey">The Ed25519 identity public key of the recipient.</param>
+    /// <returns>
+    /// The recipient's <see cref="X3DHPublicBundle"/>, or <c>null</c> if no bundle is
+    /// registered for that identity key.  Callers must check for <c>null</c> before use.
+    /// </returns>
+    Task<X3DHPublicBundle> FetchKeyBundleAsync(byte[] recipientIdentityKey);
+}
+
 /// <summary>
 /// Defines the contract for mailbox transport implementations that handle
 /// sending, receiving, and managing encrypted messages through various transport mechanisms.

LibEmiddle.Domain/EncryptedMessage.cs

@@ -19,6 +19,14 @@ public class EncryptedMessage
         /// </summary>
         public string SessionId { get; set; } = string.Empty;
 
+        /// <summary>
+        /// Gets or sets the sender's long-term identity public key (Ed25519, 32 bytes).
+        /// Used for O(1) session routing on the receiver side.
+        /// Nullable for backwards compatibility with messages created before this field was added.
+        /// </summary>
+        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+        public byte[]? SenderIdentityKey { get; set; }
+
         /// <summary>
         /// Gets or sets the sender's DH ratchet public key.
         /// Used for the Double Ratchet protocol.
@@ -63,6 +71,7 @@ public EncryptedMessage Clone()
             {
                 MessageId = MessageId,
                 SessionId = SessionId,
+                SenderIdentityKey = SenderIdentityKey?.ToArray(),
                 SenderDHKey = SenderDHKey?.ToArray(),
                 SenderMessageNumber = SenderMessageNumber,
                 Ciphertext = Ciphertext?.ToArray(),
@@ -114,6 +123,7 @@ public int GetEstimatedSize()
             size += SessionId.Length * sizeof(char);
 
             // Byte arrays
+            size += SenderIdentityKey?.Length ?? 0;
             size += SenderDHKey?.Length ?? 0;
             size += Ciphertext?.Length ?? 0;
             size += Nonce?.Length ?? 0;
@@ -239,6 +249,12 @@ public static EncryptedMessage FromDictionary(Dictionary<string, object>? dictio
                     message.SessionId = sessionId;
                 }
 
+                // Optional: SenderIdentityKey (new field, nullable for backwards compatibility)
+                if (dictionary.TryGetValue("SenderIdentityKey", out var senderIdentityKeyObj) && senderIdentityKeyObj is string senderIdentityKeyBase64)
+                {
+                    message.SenderIdentityKey = Convert.FromBase64String(senderIdentityKeyBase64);
+                }
+
                 return message;
             }
             catch (FormatException)
@@ -334,6 +350,11 @@ public Dictionary<string, object> ToDictionary()
                 ["Timestamp"] = Timestamp
             };
 
+            if (SenderIdentityKey != null && SenderIdentityKey.Length > 0)
+            {
+                dictionary["SenderIdentityKey"] = Convert.ToBase64String(SenderIdentityKey);
+            }
+
             if (!string.IsNullOrEmpty(MessageId))
             {
                 dictionary["MessageId"] = MessageId;

LibEmiddle.Domain/Exceptions/LibEmiddleErrorCode.cs

@@ -0,0 +1,46 @@
+namespace LibEmiddle.Domain.Exceptions
+{
+    /// <summary>
+    /// Error codes for <see cref="LibEmiddleException"/>, allowing callers to
+    /// distinguish transient failures from permanent ones and to route errors
+    /// to the appropriate recovery path.
+    /// </summary>
+    public enum LibEmiddleErrorCode
+    {
+        /// <summary>An unclassified or unexpected error occurred.</summary>
+        Unknown = 0,
+
+        /// <summary>The supplied key bundle is missing required fields or is structurally invalid.</summary>
+        InvalidBundle,
+
+        /// <summary>A replayed message was detected and rejected.</summary>
+        ReplayDetected,
+
+        /// <summary>Decryption of a message or payload failed.</summary>
+        DecryptionFailed,
+
+        /// <summary>A transport-level error occurred (e.g. WebSocket send/receive failure).</summary>
+        TransportError,
+
+        /// <summary>The requested cryptographic key could not be found.</summary>
+        KeyNotFound,
+
+        /// <summary>The requested session could not be found.</summary>
+        SessionNotFound,
+
+        /// <summary>The requested device could not be found.</summary>
+        DeviceNotFound,
+
+        /// <summary>All one-time pre-keys (OPKs) have been exhausted.</summary>
+        OPKExhausted,
+
+        /// <summary>A supplied key is invalid (wrong length, wrong curve, corrupt data, etc.).</summary>
+        InvalidKey,
+
+        /// <summary>A supplied message is invalid (malformed, missing fields, etc.).</summary>
+        InvalidMessage,
+
+        /// <summary>The operation is not permitted given the caller's current privileges.</summary>
+        PermissionDenied,
+    }
+}

LibEmiddle.Domain/Exceptions/LibEmiddleException.cs

@@ -0,0 +1,28 @@
+namespace LibEmiddle.Domain.Exceptions
+{
+    /// <summary>
+    /// The base exception type for LibEmiddle. Carries a <see cref="LibEmiddleErrorCode"/>
+    /// so callers can distinguish transient failures (e.g. <see cref="LibEmiddleErrorCode.TransportError"/>)
+    /// from permanent ones (e.g. <see cref="LibEmiddleErrorCode.InvalidKey"/>).
+    /// </summary>
+    public class LibEmiddleException : Exception
+    {
+        /// <summary>Gets the structured error code that describes the failure.</summary>
+        public LibEmiddleErrorCode ErrorCode { get; }
+
+        /// <summary>
+        /// Initialises a new instance of <see cref="LibEmiddleException"/>.
+        /// </summary>
+        /// <param name="message">A human-readable description of the error.</param>
+        /// <param name="code">The structured error code.</param>
+        /// <param name="innerException">An optional inner exception that caused this error.</param>
+        public LibEmiddleException(
+            string message,
+            LibEmiddleErrorCode code,
+            Exception? innerException = null)
+            : base(message, innerException)
+        {
+            ErrorCode = code;
+        }
+    }
+}