Feature/observable callback coverage

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to ESPressio Security are documented in this file.
 
+## [0.2.0] - 2026-08-20
+
+### Added
+
+- Added `ITransportSecurityObserver` for externally meaningful transport-security lifecycle notifications.
+- Added observable notifications for configuration changes, security-session reset/establishment, replay-protection reset, and security failures.
+- Added ESPressio Observable as the foundational observer dependency.
+- Added optional ESPressio Event bridge support through ESPressio Event 5.8.0.
+
+### Changed
+
+- Security failure paths now publish observer notifications without changing existing return-value semantics.
+
 ## [0.1.0] - 2026-08-20
 
 ### Added

README.md

@@ -4,6 +4,24 @@ Transport-neutral authenticated encryption, authentication, replay protection an
 
 ESPressio Security protects **opaque transport payloads** without knowing whether they contain Events, Commands, clock synchronization messages, application packets, or another protocol. Concrete transports such as ESP-NOW, UDP, TCP and WebSockets can therefore opt into the same security layer while higher-level application protocols remain independent of cryptography.
 
+## 0.2.0 Development Update — Observable Callback Coverage
+
+The `feature/observable-callback-coverage` branch targets **ESPressio Security 0.2.0**. The stable-release information below remains the historical 0.1.0 documentation until 0.2.0 is released.
+
+For 0.2.0, ESPressio Security adds a required dependency on **ESPressio Observable >= 3.0.1 and < 4.0.0** and introduces `ITransportSecurityObserver`. `TransportSecurity` now exposes synchronous observations for material configuration changes, security-session reset/establishment, replay-protection reset, and Security failures while preserving the existing `SecurityResult` return contract.
+
+ESPressio Event remains **optional**. ESPressio Event 5.8.0 adds `TransportSecurityEventBridge`, which binds to a specific `TransportSecurity` instance and converts those observations into asynchronous Events without making Event a Security dependency. Key material is never exposed through the observer or Event surfaces.
+
+Development-branch PlatformIO dependencies are therefore:
+
+```ini
+lib_deps =
+    https://github.com/Flowduino/ESPressio-Security.git#feature/observable-callback-coverage
+    flowduino/ESPressio-Observable@^3.0.1
+```
+
+The 0.2.0 host-test suite includes dedicated observable lifecycle coverage. See [CHANGELOG.md](CHANGELOG.md) for the complete 0.2.0 change list.
+
 ## Latest Stable Version
 
 ESPressio Security is currently **0.1.0**.
@@ -39,7 +57,7 @@ See [LICENSE](LICENSE) for details.
 
 ## ESPressio Library Dependencies
 
-ESPressio Security has **no required ESPressio dependencies**.
+ESPressio Security has **no required ESPressio dependencies** in the stable 0.1.0 release. **The 0.2.0 development branch adds ESPressio Observable >= 3.0.1 and < 4.0.0 as a required dependency**, as described in the development update above.
 
 It is intentionally foundational and transport-neutral. Concrete communication libraries should depend optionally on Security, rather than Security depending on them:
 
@@ -49,7 +67,7 @@ ESPressio Sockets  - - -> ESPressio Security
 future transports  - - -> ESPressio Security
 ```
 
-Event, Command and Timing do not need to depend directly on Security merely because their messages may be transported securely.
+Event, Command and Timing do not need to depend directly on Security merely because their messages may be transported securely. ESPressio Event 5.8.0's Security bridge remains opt-in.
 
 See [ESPRESSIO_DEPENDENCY_CHART.md](ESPRESSIO_DEPENDENCY_CHART.md).
 
@@ -73,10 +91,11 @@ Principal public types include:
 - `ReplayWindow` — per-sender/per-key/per-session sliding replay detector.
 - `ITransportSecurityCarrier` — minimal concrete-transport adapter contract.
 - `SecureTransportDecorator` — generic secure wrapper for a carrier.
+- `ITransportSecurityObserver` — 0.2.0 synchronous observer for externally meaningful Security lifecycle changes.
 
 ## PlatformIO
 
-Add the published library with:
+For the stable 0.1.0 release:
 
 ```ini
 lib_deps =
@@ -89,6 +108,8 @@ build_unflags =
     -std=gnu++11
 ```
 
+For the 0.2.0 release generation, add ESPressio Observable 3.x as shown in the development update above.
+
 To deliberately consume the current repository instead of a release:
 
 ```ini
@@ -136,7 +157,7 @@ Algorithms are resolved through `AeadCipherRegistry`, allowing new implementatio
 
 ## Included AEAD Implementations
 
-When supported by the platform's mbedTLS build, 0.1.0 provides:
+When supported by the platform's mbedTLS build, Security provides:
 
 | Algorithm | Key | Nonce | Tag | Class |
 | --- | ---: | ---: | ---: | --- |
@@ -220,6 +241,33 @@ boot B: sender X / session B / sequence 1, 2, 3 ...
 
 The restarted sequence is accepted because session B is a distinct authenticated replay domain; replaying either session's already-seen packets is still rejected.
 
+## Observable Security Lifecycle (0.2.0)
+
+`TransportSecurity` now accepts `ITransportSecurityObserver` registrations:
+
+```cpp
+class SecurityObserver final :
+    public ESPressio::Security::ITransportSecurityObserver {
+public:
+    void OnTransportSecuritySessionEstablished(uint64_t sessionID) override {
+        // Session lifecycle observation.
+    }
+
+    void OnTransportSecurityFailure(
+        const ESPressio::Security::SecurityResult& result
+    ) override {
+        // Diagnostics / metrics / audit handling.
+    }
+};
+
+SecurityObserver observer;
+auto observerHandle = security.RegisterObserver(&observer);
+```
+
+The observer surface supplements rather than replaces `SecurityResult`. Observer exceptions are isolated from Security processing so a diagnostics consumer cannot interrupt a cryptographic state transition.
+
+When ESPressio Event 5.8.0 is selected, `ESPressio_TransportSecurityEventBridge.hpp` converts the same observations into asynchronous Event instances without changing Security's dependency direction.
+
 ## Protecting a Payload
 
 ```cpp
@@ -292,7 +340,7 @@ Example keys are demonstration-only. Do not copy hard-coded example key material
 
 Host-side CMake/CTest coverage uses a deterministic **test-only** AEAD implementation contained exclusively under `tests/`.
 
-Coverage includes protect/open round trips, authenticated metadata, ciphertext/tag/header/session tampering, protocol binding, replay rejection, in-window reordering, sender reboot/session rollover, explicit and automatically generated sessions, key rotation, Required/Preferred/Disabled policy behavior, malformed envelopes, payload limits and generic decorator flow.
+Coverage includes protect/open round trips, authenticated metadata, ciphertext/tag/header/session tampering, protocol binding, replay rejection, in-window reordering, sender reboot/session rollover, explicit and automatically generated sessions, key rotation, Required/Preferred/Disabled policy behavior, malformed envelopes, payload limits, generic decorator flow, and 0.2.0 observable lifecycle behavior.
 
 A separate production-cipher contract target instantiates all included mbedTLS-backed cipher classes against API-compatible host stubs. GitHub Actions also compile the ESP32 examples so the actual Arduino-ESP32 mbedTLS API surface is validated in addition to host abstraction tests.
 

component.mk

@@ -3,6 +3,6 @@ COMPONENT_SRCDIRS :=
 CXXFLAGS += -std=gnu++17
 
 ESPRESSIO_SECURITY_VERSION_MAJOR := 0
-ESPRESSIO_SECURITY_VERSION_MINOR := 1
+ESPRESSIO_SECURITY_VERSION_MINOR := 2
 ESPRESSIO_SECURITY_VERSION_PATCH := 0
-ESPRESSIO_SECURITY_VERSION := 0.1.0
+ESPRESSIO_SECURITY_VERSION := 0.2.0

library.json

@@ -1,12 +1,19 @@
 {
   "name": "ESPressio-Security",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Transport-neutral authenticated encryption, authentication and replay protection for the ESPressio Development Platform",
-  "keywords": "espressio,security,encryption,aead,aes,gcm,ccm,chacha20,poly1305,transport,authentication,replay",
+  "keywords": "espressio,security,encryption,aead,aes,gcm,ccm,chacha20,poly1305,transport,authentication,replay,observable",
   "repository": {"type": "git", "url": "https://github.com/Flowduino/ESPressio-Security.git"},
   "authors": {"name": "Flowduino", "maintainer": true, "url": "https://flowduino.com"},
   "license": "Apache-2.0",
   "frameworks": "*",
   "platforms": "*",
-  "build": {"flags": ["-std=gnu++17", "-DESPRESSIO_SECURITY"]}
+  "build": {"flags": ["-std=gnu++17", "-DESPRESSIO_SECURITY"]},
+  "dependencies": [
+    {
+      "name": "Flowduino ESPressio-Observable",
+      "version": ">=3.0.1 <4.0.0",
+      "url": "https://github.com/Flowduino/ESPressio-Observable.git"
+    }
+  ]
 }

library.properties

@@ -1,10 +1,11 @@
 name=ESPressio-Security
-version=0.1.0
+version=0.2.0
 author=Flowduino
 maintainer=Flowduino
 sentence=Transport-neutral authenticated encryption and replay protection for ESPressio.
-paragraph=Provides pluggable AEAD algorithms, key providers, authenticated transport envelopes, replay protection, security policies, and generic secure transport decoration. Includes mbedTLS AES-GCM, AES-CCM and ChaCha20-Poly1305 implementations when available.
+paragraph=Provides pluggable AEAD algorithms, key providers, authenticated transport envelopes, replay protection, security policies, observable security lifecycle notifications, and generic secure transport decoration. Includes mbedTLS AES-GCM, AES-CCM and ChaCha20-Poly1305 implementations when available.
 category=Communication
 url=https://github.com/Flowduino/ESPressio-Security
 architectures=*
 includes=ESPressio_Security.hpp
+depends=Flowduino ESPressio-Observable (>=3.0.1)

src/ESPressio_ITransportSecurityObserver.hpp

@@ -0,0 +1,36 @@
+#pragma once
+
+#include <cstdint>
+
+#include <ESPressio_IObserver.hpp>
+
+#include "ESPressio_SecurityTypes.hpp"
+
+namespace ESPressio::Security {
+
+class ITransportSecurityObserver :
+    public virtual Observable::IObserver {
+public:
+    virtual ~ITransportSecurityObserver() = default;
+
+    virtual void OnTransportSecurityConfigurationChanged(
+        const TransportSecurityConfig&,
+        const TransportSecurityConfig&
+    ) {}
+
+    virtual void OnTransportSecuritySessionReset(
+        uint64_t
+    ) {}
+
+    virtual void OnTransportSecuritySessionEstablished(
+        uint64_t
+    ) {}
+
+    virtual void OnTransportSecurityReplayProtectionReset() {}
+
+    virtual void OnTransportSecurityFailure(
+        const SecurityResult&
+    ) {}
+};
+
+} // namespace ESPressio::Security

src/ESPressio_Security.hpp

@@ -7,6 +7,7 @@
 #include "ESPressio_StaticKeyProvider.hpp"
 #include "ESPressio_IRandomSource.hpp"
 #include "ESPressio_ReplayWindow.hpp"
+#include "ESPressio_ITransportSecurityObserver.hpp"
 #include "ESPressio_TransportSecurity.hpp"
 #include "ESPressio_ISecureTransportCarrier.hpp"
 #include "ESPressio_SecureTransportDecorator.hpp"

src/ESPressio_SecurityTypes.hpp

@@ -9,9 +9,9 @@
 namespace ESPressio::Security {
 
 constexpr uint32_t ESPRESSIO_SECURITY_VERSION_MAJOR = 0;
-constexpr uint32_t ESPRESSIO_SECURITY_VERSION_MINOR = 1;
+constexpr uint32_t ESPRESSIO_SECURITY_VERSION_MINOR = 2;
 constexpr uint32_t ESPRESSIO_SECURITY_VERSION_PATCH = 0;
-constexpr const char* ESPRESSIO_SECURITY_VERSION = "0.1.0";
+constexpr const char* ESPRESSIO_SECURITY_VERSION = "0.2.0";
 
 enum class AeadAlgorithm : uint8_t {
     Unknown = 0,