protocol/meek: domain-fronted meek outbound (draft)

[myleshorton]

Draft — companion to radiance#488 (fronted/scanner).

Summary

Adds a meek outbound type to lantern-box: a meek-v1 client that tunnels arbitrary TCP through chunked HTTPS POSTs to a meek server endpoint. Domain-fronted via per-dial random pick from a configured Fronts list. Session-keyed by a per-Conn random ID in X-Session-Id. meek originated in Tor's pluggable-transport framework but is architecturally distinct from Tor PTs; in practice the polling-over-HTTPS scheme implemented here is the one Psiphon and Lantern use.

Why

Today our domainfront is a control-plane mechanism only — it routes API calls (config fetch, bandit callbacks) to api.iantem.io through Akamai or CloudFront. User traffic still goes through whichever proxy was assigned. If all proxies are blocked, user traffic dies regardless of how well domainfront is working.

A meek transport closes that gap: bytes flow client → wrapped in HTTPS POST → CDN edge → meek server → unwrapped → routed to internet. When normal proxies are down, fronted traffic continues to flow.

Server-side topology

Important: the meek server is not intended to live on api.iantem.io. Plan is a dedicated domain on a Linode VPS (e.g. Frankfurt) — keeps user data-plane traffic off our API infrastructure. The outbound's URL and InnerHost are config knobs, not hardcoded; the lantern-cloud side / Linode deployment is tracked separately as getlantern/engineering#3526.

Wire format

POST <URL> HTTP/1.1
Host: <inner host>
X-Session-Id: <hex session id>
Content-Type: application/octet-stream
Content-Length: <N>

<N bytes of outbound payload>

---

200 OK
Content-Type: application/octet-stream

<up to MaxBodyBytes of inbound payload (or empty)>

Client polls every PollIntervalMs (default 100 ms) so the server can deliver queued inbound bytes even when the client has nothing to send.

Pieces

• option/meek.go — MeekOutboundOptions carries:

  • URL: meek server endpoint (e.g. https://meek.lantern.io/meek/)
  • Fronts []FrontSpec: candidate (IPAddress, SNI, VerifyHostname) tuples; one is picked at random per dial
  • Polling/buffering knobs: PollIntervalMs, MaxBodyBytes, SessionIDLen, ConnectTimeout, ReadTimeout
  • Header for fixed extra HTTP headers per request
  • SNI semantics: empty SNI sends no extension (Akamai-style); non-empty SNI is sent verbatim (CloudFront-style)

• protocol/meek/client.go — Dial(ctx, Config) (*Conn, error) produces a net.Conn. Background poll goroutine:

  • Drains writeBuf into the next POST body (capped at MaxBodyBytes)
  • Reads response body into readBuf so callers' Read unblocks
  • Ticks every PollInterval or immediately when Write signals
  • SetReadDeadline / SetWriteDeadline honored

• protocol/meek/outbound.go — sing-box adapter. Builds an *http.Client whose DialTLSContext:

  • Picks a random FrontSpec from Fronts
  • Dials FrontSpec.IPAddress:443 via the standard sing-box dialer (respects DialerOptions)
  • Sets ServerName = FrontSpec.SNI (or omits the extension if empty)
  • Verifies cert chain against FrontSpec.VerifyHostname

  DialContext then performs a SOCKS5 CONNECT to destination over the meek tunnel before returning the conn. sing-box treats meek as a terminal outbound and writes the application stream straight into the conn, so the destination has to be conveyed to the server's upstream — a SOCKS5 proxy (microsocks). Without the CONNECT, the upstream would read the app's opening bytes as a malformed SOCKS handshake. This makes the meek server's Upstream a SOCKS5-server contract (documented on ServerConfig.Upstream).

• Registration: constant.TypeMeek = "meek", plus the standard RegisterOutbound wiring in protocol/register.go. Added to supportedProtocols.

Sequence

sequenceDiagram
    participant App as app
    participant SB as sing-box
    participant MK as meek outbound
    participant Front as CDN edge
    participant Srv as meek server (Linode)

    App->>SB: TCP connect to destination
    SB->>MK: DialContext
    MK->>MK: Dial(ctx, Config)
    Note over MK: generate sessionID, start pollLoop
    MK-->>SB: net.Conn ready
    SB-->>App: stream open

    loop application bytes flow
        App->>SB: Write(bytes)
        SB->>MK: Write(bytes)
        Note over MK: buffer, signal pollReady
        MK->>Front: POST /meek/ Host:meek.lantern.io<br/>X-Session-Id: ...<br/>body=bytes
        Front->>Srv: route by inner Host
        Srv-->>Front: response body = upstream bytes
        Front-->>MK: response body
        Note over MK: append to readBuf
        SB-->>App: Read returns
    end

    loop on every PollInterval, even when client has nothing
        MK->>Front: POST (empty body)
        Front-->>MK: queued inbound bytes
    end

Loading

Server side (included in this PR)

• protocol/meek/server.go — Server (an http.Handler) implementing the meek-v1 server: per-session upstream TCP connection, request body → upstream, upstream bytes → response body, idle-session reaper. Optional AuthToken shared secret (X-Meek-Auth, constant-time compared) — when set, unauthenticated requests get 403; without it the server is an open relay into the upstream, so production on a public/fronted hostname must set it.
• cmd/meek-server — deployable binary wrapping the server (-listen, -upstream, -auth-token, -holdoff, -idle-timeout, …). Warns when -auth-token is unset.
• cmd/meek-server/smoketest/socks5.sh — end-to-end smoke test against the deployed server (SOCKS5 handshake + HTTP GET through the meek tunnel, asserts the proxy egress IP).

Security hardening (from review)

• Outbound rejects non-https URLs (would bypass the fronted TLS dialer) and fronts with no cert identity (verify_hostname/sni both empty → no real cert check).
• Bounded client write backlog (MaxWriteBufBytes, default 1 MiB) with backpressure, so a fast sender on a slow front can't OOM the process.
• Reserved request headers (Host, Content-Type, X-Session-Id) can't be overridden via the header config.
• Server read pump uses a sync.Cond instead of a sleep-based busy-wait under backpressure.

Second review pass:

• Destination routing: DialContext SOCKS5-CONNECTs to destination over the tunnel (see the outbound.go bullet above) — previously the destination was dropped and raw app bytes hit the SOCKS5 upstream.
• Oversized request bodies: the server returns 413 rather than silently truncating a POST larger than MaxBodyBytes and forwarding a corrupted prefix upstream.
• Read-pump liveness: the pump only blocks when pending is non-empty, so a single upstream read larger than MaxBodyBytes*4 can't deadlock delivery.
• Write-cap correctness: Write appends in remaining-capacity chunks, so one large slice can't grow writeBuf past MaxWriteBufBytes.

Tests

Unit tests against an in-process meek echo server plus the new hardening:

• TestConn_RoundTrip, TestConn_SessionPersistence, TestConn_RequiresHTTPClient/TestConn_RequiresURL — core protocol + config validation.
• TestConn_SetReadDeadlineUnblocksParkedRead, TestConn_ReservedHeadersNotOverridable — deadline wakeup + reserved-header protection.
• TestServer_AuthTokenRequired — 403 without/with wrong token, proceeds with the right one.
• TestNewOutbound_RejectsUnsafeConfig — http scheme + identity-less front rejected.
• TestServer_SOCKS5ConnectOverTunnel — full client→meek→SOCKS5→destination chain via the same ClientHandshake5 the outbound runs.
• TestServer_RejectsOversizedBody — 413 on a POST over MaxBodyBytes.
• TestServer_SmallMaxBodyBytesDelivers — read-pump liveness regression with a tiny cap and a 64 KiB upstream burst.
• TestConn_LargeWriteRespectsBacklogCap — a 1 MiB Write blocks at the cap instead of buffering wholesale.

What's NOT in this PR

• The meek server deployment: provisioning the Linode VPS + the systemd units (meek-server, Caddy TLS terminator, microsocks upstream) is operational, tracked separately. The server code is here.
• Front-list feed: Fronts comes from radiance/fronted/scanner (radiance#488) but the wiring between them is a follow-up. Today you'd hardcode Fronts in the JSON config.
• uTLS: the outbound uses stdlib crypto/tls for simplicity. Switching to refraction-networking/utls is a follow-up; the rest of lantern-box already uses it.
• Per-(ASN, country) bandit aggregation: covered by getlantern/engineering#3525.

Reference

• meek wire-format origin (David Fifield, in Tor's PT framework): https://gitlab.torproject.org/legacy/trac/-/wikis/doc/AChildsGardenOfPluggableTransports#meek
• Psiphon's meekServer.go (reference impl): https://github.com/Psiphon-Labs/psiphon-tunnel-core/blob/master/psiphon/server/meekServer.go
• Companion radiance PR: fronted/scanner: client-side CDN front discovery (draft) radiance#488
• Tracking issue: getlantern/engineering#3526

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new meek protocol to lantern-box: a Tor-style meek v1 TCP-over-HTTPS transport with a sing-box outbound adapter, plus a reference server/CLI and accompanying unit + smoke tests. This expands domain-fronting from control-plane-only to a potential user data-plane transport.

Changes:

• Register new outbound type meek (constant.TypeMeek) and expose it via SupportedProtocols().
• Implement meek client (net.Conn) + sing-box outbound adapter with per-dial random front selection and cert verification hooks.
• Add a meek server implementation and cmd/meek-server runnable, plus unit tests and an end-to-end smoke test script/docs.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
protocol/register.go	Wires the new meek outbound into protocol registration and the supported protocol list.
constant/proxy.go	Adds TypeMeek constant.
option/meek.go	Introduces MeekOutboundOptions and front selection specs in config schema.
protocol/meek/client.go	Implements meek client connection (polling HTTPS POST loop) as net.Conn.
protocol/meek/client_test.go	Unit tests for meek client behavior (round trip, session persistence, deadlines, config validation).
protocol/meek/outbound.go	sing-box outbound adapter + HTTP client transport that dials via randomly selected fronts.
protocol/meek/server.go	Implements meek-v1 server-side handler with session management and upstream relay.
protocol/meek/server_test.go	End-to-end unit tests for server behavior (echo, reaping, bad requests).
cmd/meek-server/main.go	Adds runnable meek server command with healthz endpoint and flags.
cmd/meek-server/smoketest/socks5.sh	Adds manual end-to-end smoke test script for a deployed fronted setup.
cmd/meek-server/smoketest/README.md	Documents reference deployment and smoke test usage.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.