Every code path in this library falls into one of four AST branch classes. An agent must identify which class it is modifying before writing code.
Class A — Production-ready core (trust and extend)
LibEmiddle/Protocol/— X3DH + Double Ratchet; real crypto, real state machinesLibEmiddle/Crypto/— CryptoProvider, AES, Nonce; P/Invoke wrappers over libsodiumLibEmiddle/Core/SecureMemory.cs— pinned GC memory, sodium_memzero; do not touch without understanding unsafe pinningLibEmiddle/Messaging/Chat/ChatSession.cs— SemaphoreSlim state machine, bounded replay bufferLibEmiddle/KeyManagement/— KeyManager, OPKManager, KeyStorage; real TTL caching and OPK lifecycleLibEmiddle/Sessions/SessionManager.cs— real session orchestrationLibEmiddle.Domain/— all models, DTOs, enums; no logic, safe to read freely
Class B — Structurally sound, async contracts complete as of v2.6.1
LibEmiddle/Sessions/SessionPersistenceManager.cs— all 9 public methods acceptCancellationToken;_ioLock.WaitAsync(ct)withlockAcquiredguard; path traversal fixed with base64 encoding +Path.GetFullPathcontainment assertionLibEmiddle/Protocol/DoubleRatchetProtocol.cs— renamed to syncEncrypt/Decrypt; all(null, null)failure paths replaced with typedLibEmiddleException(LibEmiddleErrorCode.*)LibEmiddle/Infrastructure/ResilienceManager.cs— real implementation: exponential backoff retry, Closed/HalfOpen/Open circuit breaker, per-call timeout via linkedCancellationTokenSource, lock-freeInterlockedstats
Class C — Stub: interface only, zero implementation (deferred to v3.0 — do not ship) These files compile and pass the interface contract but perform no real work. They are wired into the DI builder and will silently succeed in production:
| File | What the stub does instead of real work | v3.0 target |
|---|---|---|
Infrastructure/AdvancedKeyRotationManagerStub.cs |
Sleeps with Task.Delay, returns fake KeyRotationResult; no keys are ever rotated |
v3.0 |
Infrastructure/ConnectionPoolStub.cs |
Returns a PooledConnectionStub that echoes sends back as receives; #pragma warning disable 67 suppresses unused event warnings |
v3.0 |
Infrastructure/SessionBackupManagerStub.cs |
Creates BackupInfo objects with hardcoded "stub-checksum-*" and simulated file sizes; nothing is written to disk |
v3.0 |
Infrastructure/WebRTCTransportStub.cs |
Echoes sent bytes back as received bytes; Random (non-cryptographic) used for stats simulation |
v3.0 |
Crypto/PostQuantum/PostQuantumCryptoStub.cs |
GenerateRandomBytes used as placeholder for all Kyber/Dilithium/Falcon operations; VerifyAsync returns true for any non-empty signature |
v3.0 |
Class D — Dead API surface (deferred to v3.0)
PostQuantumOptions— stored, validated, stub instantiated; no actual PQ crypto path existsBatchingOptions.IsValid()— checked at construction, not enforced at encryption time
- ✅ CancellationToken propagation — added
ct = defaultto all async methods inSessionPersistenceManager; allSemaphoreSlim.WaitAsync()→WaitAsync(ct)withlockAcquiredguard;when (ex is not OperationCanceledException)on all catch blocks - ✅ Path traversal —
GetSessionFilePathnow base64-encodes session IDs (URL-safe variant);Path.GetFullPath+ prefix assertion provides defense-in-depth;ListSessionsAsyncdecodes back to original IDs - ✅ Silent tuple failure —
DoubleRatchetProtocol.Encrypt/Decryptnow throwLibEmiddleExceptionwithLibEmiddleErrorCode.InvalidMessage/DecryptionFailedinstead of returning(null, null); callers wrap incatch (LibEmiddleException)to preserve their own null-on-failure contracts - ✅ ResilienceManagerStub replaced —
ResilienceManager(real) implements full retry/circuit-breaker/timeout; stub deleted - ✅ CLAUDE.md violations — Array.Clear → SecureClear, SequenceEqual on secrets → sodium_memcmp, lock() in async → SemaphoreSlim, swallowed exceptions → logged warnings, Task.FromResult no-ops removed, unsafe blocks outside permitted files removed
- WebRTC transport (real ICE/STUN/TURN, DataChannel framing)
- Post-quantum crypto (Kyber, Dilithium, Falcon via liboqs or similar)
- Session backup manager (real encrypted backup/restore, checksum verification)
- Connection pool (real pooling with health checks, eviction policy)
- Advanced key rotation manager (real rotation schedules, key ceremony support)