sovereign-sensor 0.1.0__tar.gz

sovereign_sensor-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: sovereign-sensor
+Version: 0.1.0
+Summary: Bare-metal Write-Side Custody enforcement for MicroPython sensor nodes with hardware crypto abstraction
+License: MIT
+Project-URL: Homepage, https://github.com/kenwalger/sovereign-sdk
+Project-URL: Repository, https://github.com/kenwalger/sovereign-sdk
+Project-URL: Changelog, https://github.com/kenwalger/sovereign-sdk/blob/main/CHANGELOG.md
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: MicroPython
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# sovereign-sensor — Phase 9
+
+A lightweight, MicroPython-compatible Hardware Abstraction Layer (HAL) that enforces
+data custody at the **Point of Genesis** by sealing each sensor observation into a
+versioned, tamper-evident, replay-protected JSON transmission envelope before any
+network transit or cloud ingestion occurs.
+
+Zero external dependencies.  Internal library code is restricted to standard MicroPython
+built-ins (`json`, `sys`, `hashlib`, `hmac`, `binascii`).  Targets ESP32 and Raspberry Pi
+Pico via MicroPython; fully exercisable on CPython 3.12 for desktop CI.
+
+---
+
+## Architecture
+
+### Hardware Abstraction Layer
+
+`SovereignCryptoDriver` (`interface.py`) defines a three-method contract:
+
+| Method | Contract |
+|---|---|
+| `initialize_hardware() -> None` | Load key material; configure accelerator subsystem. |
+| `sign(payload: bytes) -> bytes` | Return raw binary signature bytes (no encoding). |
+| `algorithm() -> str` | Return a canonical algorithm identifier string. |
+
+Two concrete drivers are provided:
+
+- **`SoftwareFallbackDriver`** — HMAC-SHA256 over a VFS-resident binary key file.
+  Used on all non-ESP32 targets (desktop CI, Raspberry Pi Pico, etc.).
+  The class-level `MOCK_KEY_SENTINEL = "/mock/test_gateway.key"` opts into a
+  deterministic stub key for desktop testing; every other path that cannot be opened
+  raises `RuntimeError` immediately, eliminating silent key substitution.  A zero-byte
+  key file raises `ValueError` to prevent HMAC keyed with `b""`.
+
+- **`ESP32HardwareDriver`** — Skeleton placeholder for the on-chip ECC accelerator.
+  `initialize_hardware()` raises `NotImplementedError` until register-level engineering
+  is complete; `bootstrap_sensor_node()` catches this and falls back to
+  `SoftwareFallbackDriver` automatically so the sealing and VFS layers remain
+  exercisable on the workbench.
+
+### Seven-Step Sealing Pipeline (`SovereignEnvelope.seal()`)
+
+1. **Monotonic sequence counter** — computed transiently as `_sequence + 1` and bound
+   into the preimage.  The in-memory counter and VFS file (default `.sovereign_sequence`)
+   are advanced only after signing succeeds, so a `sign()` failure never consumes a
+   sequence position or introduces a gap in the on-disk custody timeline.  A truncated
+   (0-byte) file resets to 0; a negative stored value is clamped to 0.  VFS write
+   failures degrade gracefully to RAM-only tracking.
+
+2. **Algorithm identifier** — queried from the active driver via `algorithm()` and
+   embedded in the authenticated preimage, providing protocol agility without
+   a schema change.
+
+3. **Canonical payload serialization** — `json.dumps(payload, separators=(",", ":"), sort_keys=True, ensure_ascii=False)`
+   guarantees a byte-identical preimage for semantically equivalent payloads
+   regardless of key insertion order.  `ensure_ascii=False` forces raw UTF-8 output
+   for all characters, eliminating the `\uXXXX`-vs-raw-UTF-8 split-brain divergence
+   that would cause cross-platform HMAC verification to fail silently on any payload
+   containing characters outside U+007F.
+
+4. **UTF-8 byte-count-prefixed preimage assembly** — `node_id`, `timestamp`, and the
+   `algorithm` identifier are each encoded to UTF-8 independently; the prefix for each
+   field is the UTF-8 byte count (not the Unicode character count).  The preimage is
+   assembled from raw byte slices:
+
+   ```
+   1|{len(node_bytes)}:{node_id}|{len(time_bytes)}:{timestamp}|{seq}|{len(algo_bytes)}:{algo}|{canonical}
+   ```
+
+   Byte-count prefixes close all variable-length field injection surfaces: delimiter
+   injection (any two inputs that differ only in where a `|` character falls produce
+   identical naive pipe-joined preimage bytes without prefixes) and multi-byte encoding
+   ambiguity (a receiver using character-count semantics parses field boundaries at the
+   wrong byte offset for any non-ASCII field value).
+
+5. **Driver signing** — raw preimage bytes traverse `driver.sign()`, returning raw
+   binary output from the underlying cryptographic primitive.
+
+6. **Hex encoding** — `binascii.hexlify()` maps all byte values `0x00–0xFF` to
+   the lowercase alphanumeric characters `0–9`, `a–f`, preventing
+   `UnicodeDecodeError` on constrained MicroPython silicon.
+
+7. **Wire frame serialization** — all seven envelope fields (`v`, `n`, `t`, `q`,
+   `alg`, `d`, `s`) are packed into a dict and serialized with
+   `json.dumps(..., separators=(",", ":"), sort_keys=True, ensure_ascii=False)`,
+   freezing the alphabetical key sequence and enforcing raw UTF-8 wire encoding
+   independently of MicroPython allocator-driven insertion order.
+
+---
+
+## Quick Start
+
+```python
+from sovereign_sensor import bootstrap_sensor_node
+
+# Auto-selects ESP32HardwareDriver or SoftwareFallbackDriver at runtime.
+# Falls back to SoftwareFallbackDriver with a warning if hardware crypto
+# is not yet implemented on the target.
+envelope = bootstrap_sensor_node(
+    node_id="node-temperature-01",
+    private_key_path="/flash/keys/node.key",
+    sequence_file="/flash/.sovereign_sequence",
+)
+
+observation = {"sensor": "temperature", "value": 21.4, "unit": "C"}
+wire_bytes = envelope.seal("2026-06-16T12:00:00Z", observation)
+# → b'{"alg":"hmac-sha256","d":{"sensor":"temperature","unit":"C","value":21.4},'
+#     '"n":"node-temperature-01","q":1,"s":"<64-char hex>","t":"2026-06-16T12:00:00Z","v":1}'
+```
+
+### Desktop / CI (mock key sentinel)
+
+```python
+from sovereign_sensor import bootstrap_sensor_node
+from sovereign_sensor.drivers.software_fallback import SoftwareFallbackDriver
+
+envelope = bootstrap_sensor_node(
+    node_id="ci-node-001",
+    private_key_path=SoftwareFallbackDriver.MOCK_KEY_SENTINEL,
+)
+wire = envelope.seal("2026-06-16T00:00:00Z", {"ping": True})
+```
+
+---
+
+## Invariants
+
+| Property | Guarantee |
+|---|---|
+| **Replay protection** | Monotonic `q` counter persisted to VFS; resumes across reboots. |
+| **Sequence atomicity** | Counter advanced only after `sign()` succeeds; a signing failure leaves the on-disk counter unchanged with no gap. |
+| **Key material safety** | Missing or empty key file raises immediately; no silent substitution. |
+| **Preimage determinism** | `sort_keys=True` and `ensure_ascii=False` on payload; byte-count length prefixes on all three variable-length fields. |
+| **Wire frame determinism** | `sort_keys=True` and `ensure_ascii=False` on the outer frame; byte-identical UTF-8 output across CPython and MicroPython builds. |
+| **Encoding safety** | `binascii.hexlify` prevents `UnicodeDecodeError` on raw binary digest bytes. |
+| **Zero dependencies** | No network calls, no PyTorch, no external packages at runtime. |

sovereign_sensor-0.1.0/README.md

@@ -0,0 +1,136 @@
+# sovereign-sensor — Phase 9
+
+A lightweight, MicroPython-compatible Hardware Abstraction Layer (HAL) that enforces
+data custody at the **Point of Genesis** by sealing each sensor observation into a
+versioned, tamper-evident, replay-protected JSON transmission envelope before any
+network transit or cloud ingestion occurs.
+
+Zero external dependencies.  Internal library code is restricted to standard MicroPython
+built-ins (`json`, `sys`, `hashlib`, `hmac`, `binascii`).  Targets ESP32 and Raspberry Pi
+Pico via MicroPython; fully exercisable on CPython 3.12 for desktop CI.
+
+---
+
+## Architecture
+
+### Hardware Abstraction Layer
+
+`SovereignCryptoDriver` (`interface.py`) defines a three-method contract:
+
+| Method | Contract |
+|---|---|
+| `initialize_hardware() -> None` | Load key material; configure accelerator subsystem. |
+| `sign(payload: bytes) -> bytes` | Return raw binary signature bytes (no encoding). |
+| `algorithm() -> str` | Return a canonical algorithm identifier string. |
+
+Two concrete drivers are provided:
+
+- **`SoftwareFallbackDriver`** — HMAC-SHA256 over a VFS-resident binary key file.
+  Used on all non-ESP32 targets (desktop CI, Raspberry Pi Pico, etc.).
+  The class-level `MOCK_KEY_SENTINEL = "/mock/test_gateway.key"` opts into a
+  deterministic stub key for desktop testing; every other path that cannot be opened
+  raises `RuntimeError` immediately, eliminating silent key substitution.  A zero-byte
+  key file raises `ValueError` to prevent HMAC keyed with `b""`.
+
+- **`ESP32HardwareDriver`** — Skeleton placeholder for the on-chip ECC accelerator.
+  `initialize_hardware()` raises `NotImplementedError` until register-level engineering
+  is complete; `bootstrap_sensor_node()` catches this and falls back to
+  `SoftwareFallbackDriver` automatically so the sealing and VFS layers remain
+  exercisable on the workbench.
+
+### Seven-Step Sealing Pipeline (`SovereignEnvelope.seal()`)
+
+1. **Monotonic sequence counter** — computed transiently as `_sequence + 1` and bound
+   into the preimage.  The in-memory counter and VFS file (default `.sovereign_sequence`)
+   are advanced only after signing succeeds, so a `sign()` failure never consumes a
+   sequence position or introduces a gap in the on-disk custody timeline.  A truncated
+   (0-byte) file resets to 0; a negative stored value is clamped to 0.  VFS write
+   failures degrade gracefully to RAM-only tracking.
+
+2. **Algorithm identifier** — queried from the active driver via `algorithm()` and
+   embedded in the authenticated preimage, providing protocol agility without
+   a schema change.
+
+3. **Canonical payload serialization** — `json.dumps(payload, separators=(",", ":"), sort_keys=True, ensure_ascii=False)`
+   guarantees a byte-identical preimage for semantically equivalent payloads
+   regardless of key insertion order.  `ensure_ascii=False` forces raw UTF-8 output
+   for all characters, eliminating the `\uXXXX`-vs-raw-UTF-8 split-brain divergence
+   that would cause cross-platform HMAC verification to fail silently on any payload
+   containing characters outside U+007F.
+
+4. **UTF-8 byte-count-prefixed preimage assembly** — `node_id`, `timestamp`, and the
+   `algorithm` identifier are each encoded to UTF-8 independently; the prefix for each
+   field is the UTF-8 byte count (not the Unicode character count).  The preimage is
+   assembled from raw byte slices:
+
+   ```
+   1|{len(node_bytes)}:{node_id}|{len(time_bytes)}:{timestamp}|{seq}|{len(algo_bytes)}:{algo}|{canonical}
+   ```
+
+   Byte-count prefixes close all variable-length field injection surfaces: delimiter
+   injection (any two inputs that differ only in where a `|` character falls produce
+   identical naive pipe-joined preimage bytes without prefixes) and multi-byte encoding
+   ambiguity (a receiver using character-count semantics parses field boundaries at the
+   wrong byte offset for any non-ASCII field value).
+
+5. **Driver signing** — raw preimage bytes traverse `driver.sign()`, returning raw
+   binary output from the underlying cryptographic primitive.
+
+6. **Hex encoding** — `binascii.hexlify()` maps all byte values `0x00–0xFF` to
+   the lowercase alphanumeric characters `0–9`, `a–f`, preventing
+   `UnicodeDecodeError` on constrained MicroPython silicon.
+
+7. **Wire frame serialization** — all seven envelope fields (`v`, `n`, `t`, `q`,
+   `alg`, `d`, `s`) are packed into a dict and serialized with
+   `json.dumps(..., separators=(",", ":"), sort_keys=True, ensure_ascii=False)`,
+   freezing the alphabetical key sequence and enforcing raw UTF-8 wire encoding
+   independently of MicroPython allocator-driven insertion order.
+
+---
+
+## Quick Start
+
+```python
+from sovereign_sensor import bootstrap_sensor_node
+
+# Auto-selects ESP32HardwareDriver or SoftwareFallbackDriver at runtime.
+# Falls back to SoftwareFallbackDriver with a warning if hardware crypto
+# is not yet implemented on the target.
+envelope = bootstrap_sensor_node(
+    node_id="node-temperature-01",
+    private_key_path="/flash/keys/node.key",
+    sequence_file="/flash/.sovereign_sequence",
+)
+
+observation = {"sensor": "temperature", "value": 21.4, "unit": "C"}
+wire_bytes = envelope.seal("2026-06-16T12:00:00Z", observation)
+# → b'{"alg":"hmac-sha256","d":{"sensor":"temperature","unit":"C","value":21.4},'
+#     '"n":"node-temperature-01","q":1,"s":"<64-char hex>","t":"2026-06-16T12:00:00Z","v":1}'
+```
+
+### Desktop / CI (mock key sentinel)
+
+```python
+from sovereign_sensor import bootstrap_sensor_node
+from sovereign_sensor.drivers.software_fallback import SoftwareFallbackDriver
+
+envelope = bootstrap_sensor_node(
+    node_id="ci-node-001",
+    private_key_path=SoftwareFallbackDriver.MOCK_KEY_SENTINEL,
+)
+wire = envelope.seal("2026-06-16T00:00:00Z", {"ping": True})
+```
+
+---
+
+## Invariants
+
+| Property | Guarantee |
+|---|---|
+| **Replay protection** | Monotonic `q` counter persisted to VFS; resumes across reboots. |
+| **Sequence atomicity** | Counter advanced only after `sign()` succeeds; a signing failure leaves the on-disk counter unchanged with no gap. |
+| **Key material safety** | Missing or empty key file raises immediately; no silent substitution. |
+| **Preimage determinism** | `sort_keys=True` and `ensure_ascii=False` on payload; byte-count length prefixes on all three variable-length fields. |
+| **Wire frame determinism** | `sort_keys=True` and `ensure_ascii=False` on the outer frame; byte-identical UTF-8 output across CPython and MicroPython builds. |
+| **Encoding safety** | `binascii.hexlify` prevents `UnicodeDecodeError` on raw binary digest bytes. |
+| **Zero dependencies** | No network calls, no PyTorch, no external packages at runtime. |

sovereign_sensor-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sovereign-sensor"
+version = "0.1.0"
+description = "Bare-metal Write-Side Custody enforcement for MicroPython sensor nodes with hardware crypto abstraction"
+readme = "README.md"
+requires-python = ">=3.12" # Enforces CPython 3.12+ for desktop development/CI test suites; package library code remains strictly bare-metal MicroPython compatible.
+license = { text = "MIT" }
+dependencies = []
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: Implementation :: MicroPython",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+    "Topic :: System :: Hardware",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/kenwalger/sovereign-sdk"
+Repository = "https://github.com/kenwalger/sovereign-sdk"
+Changelog = "https://github.com/kenwalger/sovereign-sdk/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]

sovereign_sensor-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sovereign_sensor-0.1.0/src/sovereign_sensor/__init__.py

@@ -0,0 +1,83 @@
+# packages/sovereign-sensor/src/sovereign_sensor/__init__.py
+"""sovereign-sensor — Bare-metal Write-Side Custody enforcement for MicroPython sensor nodes.
+
+Provides a Hardware Abstraction Layer that selects between on-chip hardware
+cryptography and pure-Python software fallbacks at runtime, then seals each
+sensor observation into a tamper-evident, versioned, minified JSON transmission
+envelope with monotonic replay protection that survives hardware reboots.
+Zero external dependencies; targets ESP32 and Raspberry Pi Pico via MicroPython.
+"""
+import sys
+
+from .envelope import SovereignEnvelope
+from .interface import SovereignCryptoDriver
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SovereignCryptoDriver",
+    "SovereignEnvelope",
+    "bootstrap_sensor_node",
+]
+
+
+def bootstrap_sensor_node(
+    node_id: str,
+    private_key_path: str,
+    sequence_file: str = ".sovereign_sequence",
+) -> SovereignEnvelope:
+    """Instantiate and configure a platform-appropriate sensor envelope factory.
+
+    Inspects ``sys.platform`` to route between the ESP32 hardware-accelerated
+    driver and the pure-Python software fallback.  The selected driver is
+    initialized (loading key material from ``private_key_path``) before the
+    envelope is constructed, guaranteeing the signing subsystem is ready on
+    the first ``seal()`` call.
+
+    If the selected driver's ``initialize_hardware()`` raises
+    ``NotImplementedError`` — indicating that hardware crypto acceleration is
+    still a skeleton placeholder — a warning is printed and the node falls back
+    to ``SoftwareFallbackDriver`` so that the sealing, sequencing, and VFS
+    serialization layers remain exercisable on the workbench before
+    register-level engineering is complete.
+
+    :param node_id: Immutable identifier string for this sensor node.
+    :type node_id: str
+    :param private_key_path: Filesystem path to the node's private signing key,
+        or ``SoftwareFallbackDriver.MOCK_KEY_SENTINEL`` for desktop testing.
+    :type private_key_path: str
+    :param sequence_file: VFS path used to persist the monotonic sequence
+        counter across reboots.  Defaults to ``".sovereign_sequence"`` in the
+        current working directory.
+    :type sequence_file: str
+    :return: A fully configured ``SovereignEnvelope`` bound to the active driver.
+    :rtype: SovereignEnvelope
+    """
+    platform: str = sys.platform.lower()
+    if "esp32" in platform:
+        from .drivers.esp32_hardware import ESP32HardwareDriver
+        driver: SovereignCryptoDriver = ESP32HardwareDriver(private_key_path)
+    else:
+        from .drivers.software_fallback import SoftwareFallbackDriver
+        driver = SoftwareFallbackDriver(private_key_path)
+    _hw_not_implemented: bool = False
+    try:
+        driver.initialize_hardware()
+    except NotImplementedError:
+        _hw_not_implemented = True
+
+    if _hw_not_implemented:
+        # Emit the warning outside the except block so the fallback initialization
+        # path carries no implicit exception context.  Any exception raised by the
+        # SoftwareFallbackDriver below will surface with a clean traceback rather
+        # than chaining the original NotImplementedError, preventing doubled
+        # tracebacks from flooding the serial monitor on constrained MicroPython targets.
+        print(
+            "WARNING: Hardware crypto accelerator is not yet implemented "
+            "(pending low-level register engineering in the next sprint). "
+            "Falling back to SoftwareFallbackDriver for this node instance."
+        )
+        from .drivers.software_fallback import SoftwareFallbackDriver
+        driver = SoftwareFallbackDriver(private_key_path)
+        driver.initialize_hardware()
+    return SovereignEnvelope(node_id, driver, sequence_file=sequence_file)

sovereign_sensor-0.1.0/src/sovereign_sensor/drivers/__init__.py

@@ -0,0 +1,2 @@
+# packages/sovereign-sensor/src/sovereign_sensor/drivers/__init__.py
+"""Platform-specific cryptographic signing driver implementations."""

sovereign_sensor-0.1.0/src/sovereign_sensor/drivers/esp32_hardware.py

@@ -0,0 +1,67 @@
+# packages/sovereign-sensor/src/sovereign_sensor/drivers/esp32_hardware.py
+"""ESP32 hardware-accelerated cryptographic signing driver.
+
+Shell implementation targeting the ESP32's on-chip SHA and RSA/ECC
+accelerator peripherals via the MicroPython ``machine`` and ``hashlib``
+HAL bindings.  Full low-level register engineering is deferred to the
+next sprint; this module establishes the class contract and import
+surface so the bootstrap router can bind it without modification.
+"""
+from ..interface import SovereignCryptoDriver
+
+
+class ESP32HardwareDriver(SovereignCryptoDriver):
+    """Hardware-accelerated signing driver for ESP32 targets.
+
+    On initialization, this driver will configure the on-chip crypto
+    accelerator and load key material from the eFuse or external flash
+    partition pointed to by ``private_key_path``.
+
+    :param private_key_path: Path to the private key in the ESP32 VFS
+        (e.g. ``/flash/keys/node.key``).
+    :type private_key_path: str
+    """
+
+    def __init__(self, private_key_path: str) -> None:
+        self._key_path: str = private_key_path
+        self._initialized: bool = False
+
+    def initialize_hardware(self) -> None:
+        """Configure the ESP32 hardware crypto accelerator subsystem.
+
+        :rtype: None
+        :raises NotImplementedError: Until low-level register engineering is complete.
+        """
+        raise NotImplementedError(
+            "ESP32 hardware crypto drivers are pending low-level register engineering "
+            "in the next sprint."
+        )
+
+    def algorithm(self) -> str:
+        """Return the canonical algorithm identifier for this driver.
+
+        Next sprint: finalize the identifier once the hardware signing
+        primitive (ECDSA P-256 via the ESP32 ECC accelerator) is confirmed.
+
+        :return: ``"ecdsa-p256"`` — forward-looking placeholder for the
+                 ESP32 on-chip ECC accelerator signing primitive.
+        :rtype: str
+        """
+        return "ecdsa-p256"
+
+    def sign(self, payload: bytes) -> bytes:
+        """Produce a hardware-accelerated signature over ``payload``.
+
+        Next sprint: delegate to the ESP32 SHA/ECC hardware engine via
+        MicroPython ``hashlib`` acceleration bindings.  Returns raw binary
+        signature bytes; hex encoding is the envelope layer's responsibility.
+
+        :param payload: Raw preimage bytes to authenticate.
+        :type payload: bytes
+        :return: Raw binary signature bytes (no encoding applied).
+        :rtype: bytes
+        :raises NotImplementedError: Until hardware signing is implemented.
+        """
+        raise NotImplementedError(
+            "ESP32 hardware crypto signing is pending next-sprint implementation."
+        )

sovereign_sensor-0.1.0/src/sovereign_sensor/drivers/software_fallback.py

@@ -0,0 +1,110 @@
+# packages/sovereign-sensor/src/sovereign_sensor/drivers/software_fallback.py
+"""Pure-Python software fallback signing driver.
+
+Used on any platform that does not expose on-chip hardware crypto
+acceleration (desktop CI, Raspberry Pi Pico without accelerator, etc.).
+Produces a keyed HMAC-SHA256 digest of the preimage using key material
+read from the VFS at initialization time.  Raw bytes are returned;
+hex encoding is the responsibility of the envelope serialization layer.
+Not suitable for production custody chains; intended for structural
+validation and desktop integration testing only.
+"""
+import hashlib
+import hmac
+
+from ..interface import SovereignCryptoDriver
+
+
+class SoftwareFallbackDriver(SovereignCryptoDriver):
+    """HMAC-SHA256–based software signing driver for non-accelerated platforms.
+
+    Key material is loaded from ``private_key_path`` during ``initialize_hardware()``.
+    If ``private_key_path`` equals ``MOCK_KEY_SENTINEL``, the fixed deterministic
+    ``_MOCK_KEY`` stub is substituted so lightweight desktop tests can operate without
+    a provisioned key store.  Any other path that cannot be opened raises
+    ``RuntimeError`` immediately — there is no silent key substitution for
+    non-sentinel paths.
+
+    :param private_key_path: Filesystem path to the binary HMAC key material, or
+        ``SoftwareFallbackDriver.MOCK_KEY_SENTINEL`` to opt into the deterministic
+        mock key for desktop testing.
+    :type private_key_path: str
+    """
+
+    # Explicit opt-in sentinel for desktop testing without a provisioned key store.
+    # Any path other than this that cannot be opened raises RuntimeError immediately.
+    MOCK_KEY_SENTINEL: str = "/mock/test_gateway.key"
+
+    # Fixed stub keyed exclusively to MOCK_KEY_SENTINEL paths.  Never deploy in
+    # production — this value provides zero cryptographic uniqueness guarantees.
+    _MOCK_KEY: bytes = b"sovereign-sensor-mock-key-v1-do-not-use-in-production"
+
+    def __init__(self, private_key_path: str) -> None:
+        self._key_path: str = private_key_path
+        self._initialized: bool = False
+        self._secret_key: bytes = b""
+
+    def initialize_hardware(self) -> None:
+        """Load HMAC key material from the VFS and mark the driver ready.
+
+        If ``private_key_path`` equals ``MOCK_KEY_SENTINEL``, substitutes the
+        fixed deterministic ``_MOCK_KEY`` stub so lightweight desktop tests operate
+        without a provisioned key store.  For all other paths, opens the file in
+        read-binary mode, re-raises any ``OSError`` as ``RuntimeError``, and raises
+        ``ValueError`` if the file exists but contains zero bytes — a zero-length
+        key produces an HMAC keyed with ``b""``, which is deterministic across all
+        nodes that share the same empty-file failure and provides no cryptographic
+        uniqueness.
+
+        :rtype: None
+        :raises RuntimeError: If ``private_key_path`` is not the mock sentinel and
+            the key file cannot be opened or read.
+        :raises ValueError: If the key file exists but contains zero bytes.
+        """
+        if self._key_path == self.MOCK_KEY_SENTINEL:
+            self._secret_key = self._MOCK_KEY
+            self._initialized = True
+            return
+        try:
+            with open(self._key_path, "rb") as f:
+                key_bytes: bytes = f.read()
+        except OSError as exc:
+            raise RuntimeError(
+                f"Key material loading failed: '{self._key_path}' could not be read: {exc}"
+            ) from exc
+        if not key_bytes:
+            raise ValueError(
+                f"Key material at '{self._key_path}' is empty; a non-zero-byte key is "
+                "strictly required for secure HMAC authentication."
+            )
+        self._secret_key = key_bytes
+        self._initialized = True
+
+    def algorithm(self) -> str:
+        """Return the canonical algorithm identifier for this driver.
+
+        :return: ``"hmac-sha256"`` — the HMAC-SHA256 keyed signing primitive.
+        :rtype: str
+        """
+        return "hmac-sha256"
+
+    def sign(self, payload: bytes) -> bytes:
+        """Return the raw 32-byte HMAC-SHA256 digest of ``payload``.
+
+        The digest is keyed with the secret material loaded during
+        ``initialize_hardware()``.  Hex encoding is intentionally deferred to
+        the envelope serialization layer so that this driver's return type is
+        identical to the raw binary output expected from hardware accelerators.
+
+        :param payload: Raw preimage bytes to authenticate.
+        :type payload: bytes
+        :return: Raw 32-byte HMAC-SHA256 digest.
+        :rtype: bytes
+        :raises RuntimeError: If ``initialize_hardware()`` has not been called
+            prior to this invocation.
+        """
+        if not self._initialized:
+            raise RuntimeError(
+                "Driver must be initialized via initialize_hardware() before generating signatures."
+            )
+        return hmac.new(self._secret_key, payload, hashlib.sha256).digest()