rmux

The rmux web-share end-to-end-encrypted (E2EE) protocol (version 1) provides confidentiality and integrity for terminal payloads sent from a browser client to a local rmux daemon (the host) over an untrusted relay (e.g., a Cloudflare tunnel).

Key characteristics:

• Hybrid Post-Quantum Security: Protects against future quantum threats by combining X25519 and ML-KEM-768. Confidentiality holds as long as the 256-bit share token remains secret and at least one of the key agreement algorithms remains unbroken.
• Transport: Uses WebSockets. Handshake messages are sent as Text frames (UTF-8 JSON), while all subsequent data is sent as Binary frames containing encrypted records.
• Trust Model: The relay (tunnel/proxy) is considered untrusted and can only observe ciphertext. The protocol is designed to protect against passive observers, active network attackers, MitM, and 'harvest now, decrypt later' quantum attacks.

rmux-web-crypto is a single-crate cryptographic core designed for the rmux web-share End-to-End Encryption (E2EE) protocol. It handles the low-level primitives required for secure communication without being tied to specific transport layers like WebSockets, TCP, or HTTP.

Key cryptographic capabilities include:

• Ephemeral X25519: Key generation and Diffie-Hellman.
• ML-KEM-768: Post-quantum hybrid shared secret wrappers.
• Session Derivation: Derives sessions using a Pre-Shared Key (PSK), X25519 DH shared secret, ML-KEM shared secret, and the exact handshake transcript bytes.
• Authenticated Encryption: Uses ChaCha20-Poly1305 with monotonic sequence numbers.
• Framing: Implements web-share text/binary "kind byte" framing on top of opaque records.

Security properties:

• Forward Secrecy: Provided by per-connection X25519 and ML-KEM secrets.
• Authentication: Derived from a high-entropy PSK mixed into the key schedule via SHA-256(256-bit token).

The RMUX web-share End-to-End Encryption (E2EE) protocol establishes a secure session between a browser client and an RMUX daemon via an untrusted relay. The handshake uses a combination of X25519 Diffie-Hellman and ML-KEM-768 to derive session keys.

Handshake Flow:

1. client_hello (Client $\rightarrow$ Relay $\rightarrow$ Daemon): The client sends a JSON message containing its ephemeral public keys and a token_id.
2. server_challenge (Daemon $\rightarrow$ Relay $\rightarrow$ Client): The daemon responds with its own ephemeral public keys and ML-KEM ciphertext.
3. Encrypted Authentication (Client $\rightarrow$ Daemon): The client sends a binary WebSocket frame containing encrypted authentication data to prove possession of the token_id.
4. Ready (Daemon $\rightarrow$ Client): The daemon confirms the session is established.
5. Encrypted Records: Terminal I/O flows in both directions using the derived session keys.

The relay only sees the initial JSON handshake messages and opaque ciphertext; it cannot derive session keys without the token_id.

browser client                relay (untrusted)              rmux daemon (host)
  ───────────────                ─────────────────              ──────────────────
        │                                │                                │
        │ WS Text: client_hello (JSON) ─►│ ─────────────────────────────► │  parse, lookup token_id,
        │                                │                                │  ML-KEM encapsulate, X25519 DH,
        │ ◄──────── WS Text: server_challenge (JSON) ◄────────────────────│  derive session keys
        │                                │                                │
        │ WS Binary: encrypted auth ───►│ ─────────────────────────────► │  open auth frame (proves token),
        │   frame {type:"auth",...}      │                                │  PIN+backoff+capacity checks
        │                                │                                │
        │ ◄──────── WS Binary: encrypted "ready" ◄────────────────────────│  session established
        │                                │                                │
        │ ◄═══════ encrypted records (terminal I/O, both directions) ═════► │

The rmux web-share protocol uses a hybrid end-to-end encryption (E2EE) layer to protect terminal content from untrusted relays (like share.rmux.io). It provides forward secrecy and post-quantum defense by combining multiple key agreement primitives.

Key Security Properties

• Hybrid Key Agreement: Combines ephemeral X25519 and ML-KEM-768 shared secrets. The key schedule mixes these with a high-entropy 256-bit share token using the formula: ikm = x25519_dh || ml_kem_shared_secret || SHA256(token).
• Forward Secrecy: Even if a relay records traffic and later obtains the share token, they cannot decrypt past sessions because the per-connection X25519 and ML-KEM secrets are discarded.
• Post-Quantum Defense: The channel remains secure against future quantum attacks on X25519 as long as ML-KEM-768 remains secure.
• Authentication: The 256-bit share token is mixed into the key schedule. A relay cannot perform a Man-in-the-Middle (MITM) attack because they lack the token, which is never sent over the wire (only a truncated token_id is exposed).
• PIN Security: The PIN is a secondary factor checked after the token-authenticated handshake. It is not fed into the Key Derivation Function (KDF), preventing offline brute-force attacks by a relay. Incorrect PIN attempts trigger exponential backoff via registry.rs.

RMUX uses a split CLI architecture to balance performance and capability:

1. Tiny Dispatcher (Public CLI): A lightweight binary that parses a narrow allowlist of tmux-compatible commands and sends a single direct IPC request to the daemon. This is the primary rmux binary.
2. Full CLI Helper (Private): A more robust binary located at libexec/rmux/rmux (Unix) or libexec/rmux/rmux.exe (Windows). It handles complex command forms, config loading, attached terminal setup, command queues, hooks, and long-lived streaming commands.

Important for Packagers/Installers:

• You must ship both the public tiny binary and the private helper together.
• On Unix, install.sh typically installs the private helper and daemon before replacing the public tiny binary to maintain the bin/ and libexec/ layout.
• On Windows (0.9 release), the split consists of rmux.exe (public), libexec/rmux/rmux.exe (private helper), and rmux-daemon.exe (daemon).

Debugging: If you encounter compatibility issues with the tiny-path dispatcher, you can force the public binary to execute the full helper by setting the environment variable: RMUX_DISABLE_TINY_CLI=1