Noise Protocol Implementation
Relevant source files
The following files were used as context for generating this wiki page:
The Noise Protocol Implementation provides encrypted, authenticated communication between Muse gadgets (ESP32 and Linux) and the Muse Virtual Machine (VM). It utilizes the Noise XX handshake pattern to establish a secure session over a WebSocket transport. This implementation ensures that command results, voice notes, and chat streams remain confidential and tamper-proof during transmission.
Sources: linux/AGENTS.md:27-27, esp32/components/muse/muse_chat_session.cpp:24-28
Protocol Architecture
The system implements the Noise_XX_25519_AESGCM_SHA256 protocol. This specific pattern performs a three-step handshake to mutually authenticate the initiator and responder while establishing forward-secure encryption keys.
Handshake Sequence
The handshake follows a structured exchange of three messages (Msg1, Msg2, and Msg3). The initiator starts the process, and the responder answers with its identity and ephemeral keys.
Transport and Framing
Noise messages wrap inside WebSocket binary frames. Each Noise payload is further structured using a framing layer that includes a length prefix.
| Component | Description |
|---|---|
| Transport | Secure WebSocket (wss://) over port 443. |
| Handshake Pattern | Noise XX (Initiator and Responder both share static keys). |
| Cipher Suite | AES-256-GCM for encryption; SHA-256 for hashing. |
| Framing | Little-endian U32 length prefix for each message. |
Sources: linux/AGENTS.md:95-103, esp32/components/muse/muse_chat_session.cpp:78-83
ESP32 Implementation
On ESP32 devices, the Noise session manages multiplexed request streams for dictation, chat, and text-to-speech (TTS) services.
Session Lifecycle
The noise_ctrl module handles the session state, including connection maintenance and heartbeat monitoring.
- Heartbeat: A heartbeat occurs every 24 hours (86,400,000,000 microseconds).
- Power Management: The session can enter a power-save mode where it polls for traffic less frequently when the screen is off.
- Reconnection: The system automatically attempts to reconnect if the session drops, using an authentication-failure backoff if credentials are rejected.
Sources: esp32/main/noise_control.h:43-100, esp32/tests/test_link_noise_session.py:117-124
Multiplexed Streams
The ESP32 client manages multiple concurrent streams over a single Noise connection.
| Stream Kind | Role |
|---|---|
K_SUB | Long-lived subscription for chat events. |
K_DICT | Streams 24 kHz PCM audio for voice dictation. |
K_CHAT | Sends user messages (text or voice notes). |
K_TTS | Receives MP3 audio data for speech synthesis. |
Sources: esp32/components/muse/muse_chat_session.cpp:115-125
Linux Implementation
The Linux implementation (written in Python) follows the same protocol logic as the ESP32 version to maintain compatibility with the Muse VM.
Identity and Authentication
The Linux client identifies itself with a unique node ID (e.g., homelink-xxxxxx) and uses a Bearer token obtained from the Muse API for the initial WebSocket upgrade.
Sources: linux/AGENTS.md:27-38, linux/AGENTS.md:95-100
Framing Logic
The Python framing.py module handles the encapsulation of Noise payloads into the length-prefixed format required by the service.
# Conceptual framing logic from noise implementation
def encode_frame(payload):
length = len(payload).to_bytes(4, 'little')
return length + payload
Sources: linux/src/musegadget/noise/framing.py:1-15, linux/AGENTS.md:100-101
Error Handling and Security
Session Authentication Failures
If a WebSocket upgrade returns HTTP 401 or 403, the client classifies this as a SESSION_AUTH_FAILED. This triggers a 60-second backoff and a refresh of VM credentials.
Sources: esp32/tests/test_link_noise_session.py:117-133
Buffer Constraints
The VM accepts a maximum of 256 KB per message. If a frame exceeds the board's allocated buffers, the session terminates with a NOISE_CTRL_REQ_TOO_LARGE error.
Sources: linux/AGENTS.md:109-110, esp32/main/noise_control.h:118-120
Summary
The Noise Protocol implementation provides the foundational security layer for Muse Gadgets. By combining standard cryptographic primitives (X25519, AES-GCM, SHA-256) with the Noise XX handshake pattern, the system establishes a secure tunnel over WebSockets. This allows for both real-time audio streaming (dictation/TTS) and structured command/control communication between the gadget and the Muse cloud infrastructure.