Architecture

Data path

Application
    |
    +-- SOCKS5 (TCP CONNECT / UDP ASSOCIATE) / HTTP CONNECT
    |       |
    |       v
    |   proxy accepts and relays streams and datagrams
    |       |
    +-- IP traffic (TUN mode)
            |
        TUN device + userspace TCP/UDP stack
            |  (each connection / UDP flow becomes one MEHS flow)
            v
     MEHS session reliability
            |
     TCP/TLS or QUIC frame path
            |
      remote MEHS data peer

A client session maintains reliable send and receive state, processes acknowledgements and retransmissions, and relays accepted SOCKS5 or HTTP CONNECT traffic through an attached frame path. It sends a FlowOpen message containing an address or domain name and waits for destination-connect success before acknowledging the local proxy request. The server's TCP/TLS and optional QUIC data listeners authenticate the finalized client ID and epoch, open the requested TCP or UDP destination, and forward frames in both directions. Client data paths use corresponding authenticated handshakes, including optional ML-KEM-768/AES-256-GCM protection.

In TUN mode, the operating system's TCP and UDP connections terminate in a userspace stack, which opens one MEHS flow per connection; the server therefore needs no raw-IP gateway. A legacy packet-bridge mode instead forwards raw IP packets to a remote gateway and is not used by TUN mode. Reconnection uses backoff while keeping the TUN engine alive across reconnects; the same behavior is used by the command-line client and the Flutter embedding.

Current boundaries

• The protocol uses bounded 36-byte framing, ACK ranges, error codes, data authentication, TCP/UDP flow opening (including domain destinations), and version selection. The wire profile is evolving; older peers reject unknown frame types, and there is no finalized interoperability guarantee.
• Transport options include client TLS 1.3 over TCP, authenticated MEHS data-session setup, optional ML-KEM-768 key agreement and AES-256-GCM frame protection, and certificate-verified QUIC paths with bounded frame I/O. HTTP/2 and HTTP/3 carriers implement the xhttp, trusttunnel, and notmehs profiles. Per-application routing can resolve the process that owns a connection.
• SOCKS5 CONNECT, UDP ASSOCIATE, HTTP CONNECT, and opt-in remote DNS are supported.
• Sessions provide bounded reliability, authorization, path selection, probes, and migration. Retransmission is driven by the session runtime. Each data connection runs as an independent session behind a client-side multiplexer. The client measures carriers with Probe frames, keeps a standby link on the other carrier, and performs make-before-break migration; the server only echoes Probe frames.
• The legacy packet bridge defines packet and lifecycle contracts; TUN mode instead uses the userspace stack directly on Linux, Windows (Wintun), macOS (utun), Android (a host descriptor), and iOS (NEPacketTunnelFlow callbacks). The host owns tunnel settings and must keep the MEHS carrier outside TUN routes. Hosts should preserve the logical session across network changes and revalidate the carrier after wake.
• The foreign-function interface lifecycle retains logical session state and exposes a network-generation counter. The embedding is responsible for cache invalidation, health checks, and reconnection.
• The server exposes HTTPS control endpoints and TLS TCP plus optional QUIC data listeners. Credentials and sessions default to in-memory stores; optional file-backed stores are available.

Non-goals for the first milestone

• Independent authentication of the end-to-end KEM exchange from the existing TLS/QUIC trust policy.
• Assuming UDP or QUIC is available on every network.
• Claiming store-ready multi-OS VPN apps before per-platform product integration.
• Optimizing published end-to-end benchmarks before correctness and safety coverage are complete.
• An independent production security audit has not been completed.

Probe data flow

1. The caller supplies authenticated, server-permitted candidate paths that support probing (for example, TCP echo or QUIC echo paths). Unpermitted or unauthenticated paths are never probed.
2. For each path and round, the probe worker sends 5 numbered RTT probes and 3 throughput probes with bounded payload, a per-probe timeout, and a minimum interval between rounds per path. Failed probes count toward loss only.
3. Results become candidate measurements and are passed to transport selection. Scoring weights are loss 50, RTT 30, jitter 15, and throughput 5. Migration requires at least 15% improvement over two windows, subject to a 10 s cooldown; the active path is reselected immediately if it fails (all probes lost or the path is missing). Rate-limited rounds reuse cached data and do not count as hysteresis windows.
4. Platforms pass the lifecycle probe-enable state into each probe round. While sleeping, no probes are sent; after wake, probes run only until a healthy path is confirmed by the wake health check.
5. Probes carry only sequence numbers and zero-filled payload. No secrets are logged or emitted in status events.