Security Policy & Versioning
Relevant source files
The following files were used as context for generating this wiki page:
This page describes the security architecture, data protection mechanisms, and versioning standards for the Muse Gadget firmware. The project implements multi-layered security including encrypted transport sessions, secure pairing protocols, and flash encryption to protect user credentials and device integrity. Versioning follows a structured support lifecycle for security updates and uses specific project tags for release builds.
Security Architecture & Data Protection
The system secures communication and stored data through several integrated components. All remote communication with the Muse VM occurs over an encrypted Noise session.
Transport Security
Devices establish a WebSocket connection to hatch.metaaivm.com which is then upgraded to a Noise protocol session. This session multiplexes control commands and home-network tunnel data. The Noise handshake ensures mutual authentication and perfect forward secrecy.
The diagram shows the multi-stage connection process from initial TLS to the final encrypted Noise session.
Sources: board-port/esp32/main/noise_control.cpp:52-54, board-port/esp32/main/noise_control.cpp:445-515
Data at Rest
Sensitive information, including Wi-Fi credentials and device tokens, is stored in Non-Volatile Storage (NVS). The firmware supports NVS encryption derived from an HMAC key in eFuse to prevent physical data extraction.
| Security Feature | Implementation | Description |
|---|---|---|
| NVS Encryption | CONFIG_HOMEHUB_NVS_ENCRYPTION | Encrypts Wi-Fi and tokens in flash using eFuse keys. |
| Secure Boot | Disabled by default | Allows developers to reflash boards freely during community development. |
| App Signing | dev_signing_key.pem | Builds are signed with a development key to ensure image integrity. |
| Memory Isolation | MALLOC_CAP_INTERNAL | Forces sensitive stack allocations into internal RAM to avoid PSRAM exposure. |
Sources: board-port/esp32/README.md:270-285, board-port/esp32/main/app.c:1320-1340
Pairing & Authentication
The project uses "Community Pairing v5" for device setup. This process involves Bluetooth Low Energy (BLE) for credential provisioning and a physical interaction requirement to prevent remote hijacking.
Pairing Flow
- The device enters Orange breathing state, advertising via BLE.
- The user identifies the device in the Muse app.
- The device enters Blue breathing state when a pairing request is received.
- The user must provide a physical button press (or screen tap on supported boards) to confirm the pairing.
- Successful pairing generates a fresh encrypted session and stores a device token.
This flowchart illustrates the transition from an unprovisioned state to a secure, paired connection.
Sources: board-port/esp32/README.md:148-165, board-port/esp32/main/app.c:640-700, board-port/esp32/AGENTS.md:370-385
Credential Management
The system utilizes a dual-token system (Access and Refresh tokens). The firmware performs proactive token refreshes based on device uptime to ensure continuous connectivity without re-pairing.
Sources: board-port/esp32/main/app.c:70-85, board-port/esp32/main/app.c:450-480
Versioning & Support
The project maintains specific support tiers and build versioning logic.
Supported Versions
The project explicitly defines which versions receive security updates.
| Version | Support Status |
|---|---|
| 5.1.x | Supported :white_check_mark: |
| 5.0.x | Unsupported :x: |
| 4.0.x | Supported :white_check_mark: |
| < 4.0 | Unsupported :x: |
Sources: SECURITY.md:8-15
Build Versioning
- Development Builds: Default to version
999.0.0. - Release Builds: Versions are set during the build process using
idf.py -DPROJECT_VER=X.X.X build. - OTA Updates: Over-the-air updates are disabled by default (
CONFIG_HOMEHUB_OTA_ENABLED=n) to prevent unauthorized firmware modification, but can be enabled for specific UI-enabled boards.
Sources: board-port/esp32/README.md:280-285, board-port/esp32/AGENTS.md:435-440
Release Workflow
Automated builds are handled via GitHub Actions, which clones a pinned commit of the SDK, applies board-specific overlays, and injects the GADGET_SDK_TOKEN as a repository secret.
The diagram outlines the CI/CD pipeline for producing secure, versioned firmware releases.
Sources: workflows/build-release.yml:25-55
Conclusion
Security in the Muse Gadget project is centered on the Noise protocol for transport and NVS encryption for storage. While community builds prioritize flexibility by leaving Secure Boot disabled, the pairing process requires physical verification to maintain user control. Security updates are strictly limited to the 5.1.x and 4.0.x version branches.