VNOX-Client/docs/maintenance/protocol-interop.md
2026-10-24 16:51:15 +02:00

2.6 KiB

Native client and gateway interoperability

The client uses LNEx v2 protobuf payloads generated from protocol/lnex.proto. This is a verbatim snapshot of the gateway's canonical schema; run python3 scripts/sync-protocol.py --check with the adjacent server checkout, or --server /path/to/lnex.proto. The client builds independently using its checked-in snapshot. Internal payload aliases exist for application compatibility, but no JSON is sent on LNEx.

Remote addresses use verified TLS 1.3, including certificate chain and hostname checks. Use lnexs://host:7600 explicitly; bare remote hosts also use TLS. Development plaintext is restricted to actual connected loopback peers (127.0.0.1:7600, [::1]:7600, or explicit lnex://localhost:7600). Certificate failures never trigger a plaintext fallback. Self-signed remote certificates need a separately designed explicit trust workflow; verification is never bypassed.

The v2 handshake verifies the server's signed HELLO and binds the client's identity signature to the complete HELLO and AUTH transcript, including both ephemeral X25519 keys. Control encryption retains ChaCha20-Poly1305 and HKDF-SHA256 with the v2 domain; it authenticates the entire 12-byte header. Sequence numbers are checked in order and never wrap. A dedicated bounded reader keeps partial frames intact while other commands and timers run and is cancelled when its session closes.

Voice receives independent random credentials through encrypted control (VoiceSession, 0x0012). UDP authenticates its full 28-byte header, explicit 64-bit sequence and protobuf frame, uses direction-specific keys, and permits bounded reordering without accepting duplicates. The receiver checks the selected relay endpoint and authenticated user/channel attribution. Empty encrypted Opus frames register the source and maintain it every five seconds. Leaving or disconnecting drops credentials and stops the receiver task. This replaces the incompatible legacy encrypted-guess-sequence client/plaintext relay combination.

Run focused verification:

cargo test --lib --no-default-features
VNOX_GATEWAY_BIN=/path/to/current/vnox-gateway cargo test --test gateway_interop --no-default-features -- --ignored
cargo run --bin vnox-e2e-voice --no-default-features -- 127.0.0.1:7600

The ignored interoperability test launches its own loopback gateway and temporary database using an in-memory identity, without reading or writing the user's profile. The voice smoke command requires the combined vnox-serverd daemon so gateway credentials reach the UDP relay through the in-process bridge.