MEHS configuration reference

This is the authoritative schema 1 reference for the client session file and server deployment file shipped in 0.9.x. It lists accepted field names, JSON types, defaults, constraints, and validation rules. Examples are copy-ready except for deployment-specific paths and credentials. Unknown fields are rejected, including inside nested objects; a file must match the schema implemented by the binary that reads it.

• 1. Client session config (--session-config, FFI mehs_config_validate_json)
• 2. TUN settings
• 3. Client command-line and embedding arguments
• 4. Server config
• 5. Server policy
• 6. Ready-made profiles

Server policy wins. The client states what it wants; the server returns the effective values and any corrections (printed as server policy adjusted ...). For example a client asking for 1 UDP connection against a server limited to 0 gets 0.

Schema 1 contract and evolution

Client session configuration and server deployment configuration are separate files, but both use schema_version: 1. The client currently defaults an omitted schema_version to 1; the server requires it explicitly. Include the field in all new files. Both parsers reject unknown fields and unknown enum values, including keys nested under tun, apps, policy, and each clients item. Missing optional fields use the defaults in the tables below. Invalid types, out-of-range values, incompatible transport-pool combinations, malformed CIDRs, and unsupported profile names fail validation or server startup; they are not silently ignored.

Schema 1 core field names are soft-frozen: do not silently rename, remove, or change their interpretation. A future field may be added to schema 1 only when it is optional, has a default that preserves existing behavior, and does not invalidate configurations that omit it. Because unknown fields are rejected, a config that uses a newly added field requires a binary that implements that field; keep config and binary versions aligned and retain old config examples for older releases. Renaming/removing a core field, changing its type or meaning, or changing its omission default in a behavior-changing way requires a deliberate schema_version: 2 for the affected config, changelog migration notes, updated examples, and paired client/server upgrade guidance. A new profile identifier may be needed for a changed transport profile, but it does not replace a schema version change. Do not add speculative keys for future features to schema 1.

The downloadable JSON examples are maintained schema 1 examples. Keep configuration files aligned with the release that consumes them.

Future extension areas, not schema 1 fields: multi-exit/peer relay/LAN discovery/BLE and distributed store backend URIs.

1. Client session config (mehs-client.json)

All fields are optional; omitted fields use the default.

All duration values except transport_cache_ttl_seconds are integers from 1 through 300. selection_improvement_percent is an integer from 1 through 100; selection_windows_required is an integer from 1 through 32. Reassembly and unacknowledged-data limits cannot be smaller than max_frame_payload_bytes. Unsupported enum values, out-of-range values, both connection pools being zero, or a disabled pool required by mode reject the configuration.

apps object

The two lists cannot both be nonempty. Per-app routing currently supports Linux and Windows; other platforms accept the fields but do not provide the same routing behavior.

Example (client JSON example):

{
  "schema_version": 1,
  "mode": "tcp_tls",
  "e2e_crypto": "off",
  "client_mode": "proxy",
  "tcp_connection_count": 1,
  "udp_connection_count": 1,
  "connect_timeout_seconds": 15,
  "inf_reconnect": false,
  "keepalive_seconds": 15
}

TLS fingerprint presets apply to HTTPS control connections and TCP/TLS data connections. QUIC data connections continue to use rustls because their TLS implementation is provided by Quinn. Without a fingerprint, rustls continues to use its embedded Mozilla root set. With a fingerprint, the browser-capable backend loads native platform trust roots; specifying --ca-file replaces those defaults with the supplied roots. For HTTP requests, the User-Agent follows the selected preset; custom profiles may supply their own, otherwise the existing default is used. Preset templates and user-agent versions can age out; update or replace the profile without changing the MEHS wire protocol.

Custom profiles are strict JSON files (unknown keys are rejected). alpn is a preference list; the client adds the ALPN required by the selected MEHS transport profile so the server can keep selecting mehs-data/1 without a wire-protocol change. See TLS fingerprint JSON example for all fields.

2. TUN settings (the tun object)

Used when client_mode is tun (or --mode tun).

name must contain 1–15 bytes and no NUL. mtu must be 576–9000. Every route must be a parseable IPv4 CIDR with prefix 0–32 or IPv6 CIDR with prefix 0–128. The client validates these fields even when TUN mode is not selected.

{
  "client_mode": "tun",
  "tun": { "name": "mehs0", "mtu": 1400, "routes": [], "exclude_routes": [], "manage_routes": true, "block_quic": true }
}

Limits of TUN mode: connections to private/LAN addresses are refused by the server (its outbound_block_private); IPv6 destinations work only if the server has IPv6 egress; half-closed TCP connections close both directions; in-flight connections are reset on reconnect (the interface and routes stay up).

3. Client arguments (CLI and FFI)

The same arguments drive the mehs binary and mehs_runtime_start (as a JSON array of strings). Flags override the session-config file.

Reconnect behaviour: after a session has been up, network failures reconnect with delays of 1, 2, 4, 8, 16, then 30 seconds. By default, only retries at 30 seconds count toward the five-attempt limit: ten retries and 181 seconds of scheduled waiting total, excluding connection-attempt duration. After the final unsuccessful retry, the CLI exits 1 and the FFI reports failed. Set "inf_reconnect": true in the client session file to disable this attempt limit and continue retrying at 30-second intervals. A session lasting at least 60 seconds resets the backoff and retry budget; shorter sessions do not. Any failure of the first connection is fatal, including connection refusal or timeout. Authorization, certificate, configuration and policy failures during session setup are fatal even when reconnecting; inf_reconnect does not change error classification.

4. Server config (mehs-server.json)

Pointed to by the MEHS_SERVER_CONFIG environment variable. The file must not be group/world-readable on Unix.

listen, data_listen, and quic_data_listen must parse as socket addresses (IP literal and port); data_listen is derived from listen when omitted or null. The config file is limited to 1 MiB and must not be group/world-readable on Unix. credential_store_file and session_store_file require file-store support; the clients array seeds an empty credential store, and an already-populated store takes precedence. After loading stores, the server requires at least one local credential or external_auth_url.

Operational metrics are available at https://<listen-address>/metrics in Prometheus text format in release packages, with no configuration required. The endpoint shares the control listener's TLS certificate and access policy; see server operations and metric definitions.

External authorization contract (external_auth_url)

The following request and response fields are the frozen external authorization contract. Integrations must use these exact, case-sensitive names and JSON types. Changing their names, types, requiredness, or meaning requires an explicitly versioned contract; the version request field is not contract-version negotiation.

When configured, this endpoint replaces local credential checks for POST /v1/authorize; there is no fallback to local credentials on denial or failure. The server sends an HTTP/1.1 POST to the configured URL's path and query (/ if no path is supplied), with Content-Type: application/json, Accept: application/json, Content-Length, and Connection: close. Credentials are sent in the JSON body, not as HTTP authorization headers or added query parameters.

Sent JSON body

{
  "username": "client-893651",
  "password": "example-password",
  "version": "0.1.0"
}

The version value above is illustrative; integrations must not assume that exact value. No transport policy, session ID, or other JSON fields are sent.

Expected JSON response

The endpoint must return HTTP 200 with a JSON object containing exactly these two fields. Both fields are required even when authorization is denied; unknown fields, missing fields, nulls, and incorrect types are rejected.

Acceptance:

{
  "authorized": true,
  "username": "canonical-alice"
}

Denial:

{
  "authorized": false,
  "username": ""
}

The canonical username becomes the account identity; the originally submitted username remains bound to the client data-channel handshake. External acceptance does not bypass the MEHS server's policy or capacity checks.

A valid denial returns HTTP 401 with {"code":"unauthorized"} to the MEHS client. A non-200 response (including 401/403 or a redirect), invalid JSON/schema, an invalid canonical username on acceptance, connection/TLS failure, or timeout returns HTTP 502 with {"code":"external_auth_unavailable"}. Redirects are not followed and requests are not retried. The TCP connect timeout is 3 seconds and the entire external authorization operation has a 5-second timeout.

Responses are limited to 16 KiB in total, including HTTP headers and any chunked encoding overhead. Content-Length, chunked transfer encoding, and connection-close-delimited bodies are supported. The endpoint must close the connection after its response: the server reads until EOF even when a Content-Length is present.

Use HTTPS in production; HTTP exposes the password in transit. HTTPS uses public WebPKI trust roots and server-name verification, without a client certificate. The endpoint is trusted to assert account identities and must protect credentials.

Client-side HTTP profile / per-app options. transport_profile (client, --transport-profile) selects the carrier; --http-path sets the path. apps.bypass (--app-bypass NAME, repeatable): listed apps connect directly outside the tunnel. apps.only (--app-only NAME): only listed apps are tunnelled, all others go direct. The two cannot be combined; names are executable names or full paths (max 64 entries, 1–260 chars). Supported on Linux and Windows in proxy mode (TCP via SOCKS5 CONNECT / HTTP CONNECT; UDP ASSOCIATE stays tunnelled) and TUN mode (TCP and UDP). The owning process is found from the connection's local port; unknown owners stay tunnelled. Linux needs root to see other users' processes. block_quic still applies to direct apps in TUN mode.

{
  "schema_version": 1,
  "listen": "0.0.0.0:8443",
  "data_listen": "0.0.0.0:8444",
  "quic_data_listen": "0.0.0.0:8444",
  "certificate_chain": "/etc/mehs/server-chain.pem",
  "private_key": "/etc/mehs/server-key.pem",
  "clients": [{ "id": "client-1", "secret": "<openssl rand -base64 32>" }],
  "max_flows_per_session": 1024,
  "policy": { "allowed_modes": ["tcp_tls", "quic"], "max_tcp_connections": 2, "max_udp_connections": 2, "e2e_crypto": "off" }
}

5. Server policy (the policy object)

The policy object rejects unknown fields. It also rejects an empty or unsupported allowed_modes list, a policy that leaves no usable carrier, and a pinned_mode that is not allowed or has a zero connection limit. Unsupported E2E suite identifiers or protocol versions are rejected rather than downgraded.

E2E is negotiated on each data connection before any flow is opened and works over TCP/TLS, QUIC, and HTTP-shaped carriers. With both sides off, the existing authentication and frame path is unchanged. When enabled, complete MEHS frames (including their headers) are encrypted; the outer frame exposes only the session epoch and per-direction record counter. The ML-KEM exchange is authenticated by the existing TLS/QUIC channel. Continue validating or pinning the server certificate: this is defense in depth, not protection from an active TLS-terminating intermediary.

6. Ready-made profiles

Defaults and recommendation

The CLI defaults remain unchanged for schema 1: proxy mode, SOCKS5 UDP ASSOCIATE off, and proxy destination-name resolution local (--remote-dns off). In particular, --remote-dns is opt-in because the server must support domain destinations and older servers reject them. This avoids changing existing CLI or config behavior; no wire-protocol change is made by these recommendations. Enable remote DNS only when the server supports it. It avoids local resolution of proxied destination names, but the client still resolves its own control/data endpoints locally.

For everyday whole-device VPN use, choose TUN mode and preserve access to the actual LAN prefixes in use on that network. For app-based proxy use, keep the listeners on loopback, enable remote DNS to avoid local lookup of proxied names, and add --udp-associate only when SOCKS5 UDP traffic (such as calls or games) is needed. HTTP CONNECT does not use SOCKS5 UDP ASSOCIATE. TUN forwards DNS and UDP transparently; these proxy flags do not configure TUN DNS behavior.

Copy-ready profiles

Daily system-wide VPN (Linux/Windows/macOS; adjust LAN exclusions to match your network):

mehs --control vpn.example.com:8443 --client-id laptop --ca-file ca.pem \
  --transport tcp --mode tun \
  --tun-exclude 192.168.0.0/16 --tun-exclude 10.0.0.0/8 \
  --tun-exclude 172.16.0.0/12

The server addresses are automatically excluded from TUN routes. Add or remove --tun-exclude entries for the local networks you want to reach outside the VPN; do not use the example CIDRs blindly if they overlap networks that should go through your VPN.

Local proxy (works without admin rights; SOCKS5 UDP is optional):

mehs --control vpn.example.com:8443 --client-id laptop --ca-file ca.pem \
  --socks-bind 127.0.0.1:1080 --http-bind 127.0.0.1:8080 --remote-dns

Add --udp-associate to this command if SOCKS5 UDP is needed for voice calls or games. It is off by default; HTTP CONNECT remains TCP-only.

Lossy mobile network: --transport quic --data vpn.example.com:8444 with "connect_timeout_seconds": 20.

Split tunnel (only selected ranges): --mode tun --tun-route 91.108.4.0/22 --tun-route 149.154.160.0/20.

Android app (host owns the VPN): see flutter-integration.md: --mode tun --tun-fd <fd> (implies no route management).