Implement native Rust peer proxy (#1)

Adds the production-shaped Rust peer proxy, injectable Freddie signaling, WebRTC and egress datagram relay, supervisor lifecycle, DTLS fingerprint randomization, and validated server-side QUIC migration behavior.

Author: myleshorton

Cargo.lock

@@ -6,16 +6,36 @@ rust-version = "1.85"
 license = "MIT OR Apache-2.0"
 description = "Rust implementation of the native Unbounded peer-proxy protocol"
 
+[features]
+default = ["native-client"]
+native-client = ["reqwest-client", "dep:env_logger"]
+reqwest-client = ["dep:reqwest", "dep:url"]
+
 [dependencies]
 base64 = "0.22"
+async-trait = "0.1"
 bytes = "1"
+env_logger = { version = "0.11", optional = true }
+futures-util = "0.3"
 quinn = { version = "0.11", default-features = false, features = ["runtime-tokio", "rustls-ring"] }
+reqwest = { version = "0.12", optional = true, default-features = false, features = ["http2", "rustls-tls-webpki-roots"] }
+rand = "0.9"
 serde = { version = "1", features = ["derive"] }
 serde_repr = "0.1"
 serde_json = "1"
 thiserror = "2"
-tokio = { version = "1", features = ["io-util", "macros", "rt", "sync", "time"] }
+tokio = { version = "1", features = ["io-util", "macros", "net", "rt-multi-thread", "signal", "sync", "time"] }
+tokio-tungstenite = { version = "0.28", default-features = false, features = ["connect", "rustls-tls-webpki-roots"] }
+tokio-util = "0.7"
+url = { version = "2", optional = true }
+webrtc = { git = "https://github.com/myleshorton/webrtc", rev = "a6a6d703037ca277df030ec7f882965c9da14577" }
+
+[[bin]]
+name = "peer-proxy"
+path = "src/bin/peer-proxy.rs"
+required-features = ["native-client"]
 
 [dev-dependencies]
 futures = "0.3"
 rcgen = "0.14"
+axum = "0.8"

Cargo.toml

@@ -20,11 +20,76 @@ churn; the Rust consumer only needs Quinn's server-side migration support.
 
 ## Status
 
-The initial milestone establishes the exact wire contracts and the stable
-virtual datagram socket that Quinn will run on. See
-[`docs/wire-protocol.md`](docs/wire-protocol.md).
+The protocol and migration foundation is complete. The native peer-proxy path
+now includes Freddie signaling, a Pion-compatible unreliable/unordered WebRTC
+DataChannel, the CSID-authenticated egress WebSocket, and bidirectional packet
+relay. See [`docs/wire-protocol.md`](docs/wire-protocol.md).
 
 ```sh
 cargo test
 ```
 
+The native peer proxy runs continuously, returning to Freddie discovery after
+each completed or failed sharing session. It shuts down cleanly on Ctrl-C and
+uses bounded exponential backoff with ±20% jitter between attempts:
+
+```sh
+UNBOUNDED_FREDDIE_ENDPOINT=http://localhost:9000/v1/signal \
+UNBOUNDED_EGRESS_URL=ws://localhost:8000/ws \
+UNBOUNDED_STUN_URLS=stun:stun.example.org:3478 \
+cargo run --bin peer-proxy
+```
+
+Operational settings are environment variables:
+
+| Variable | Default | Purpose |
+| --- | ---: | --- |
+| `UNBOUNDED_CONCURRENT_SESSIONS` | 5 | Independent consumer slots, matching the Go widget default |
+| `UNBOUNDED_NAT_TIMEOUT_SECONDS` | 10 | Time allowed for the WebRTC DataChannel to open |
+| `UNBOUNDED_RETRY_INITIAL_SECONDS` | 1 | Initial retry delay |
+| `UNBOUNDED_RETRY_MAX_SECONDS` | 30 | Maximum retry delay, including jitter |
+| `UNBOUNDED_STABLE_SESSION_SECONDS` | 30 | Session duration that resets retry backoff |
+| `UNBOUNDED_COVERT_DTLS` | unset (randomize) | Unset randomizes; truthy/`randomize` keeps it on, falsey/`disable` is diagnostic-only |
+| `UNBOUNDED_ENABLE_IPV6` | unset | Set to `1`, `true`, `yes`, or `on` to gather IPv6 ICE candidates |
+
+Library embedders can consume slot-tagged `PoolEvent` and `SupervisorEvent`
+values for attempt, session, failure, backoff, and shutdown reporting.
+Cancellation closes every active WebRTC peer connection before the pool exits.
+Third-party logs default to `error` to avoid exposing ICE candidate addresses;
+operators can opt into more detail with `RUST_LOG`.
+
+Embedders that already own an HTTP stack can exclude the native CLI and its
+`reqwest`/`env_logger` dependencies, then supply Freddie signaling through the
+object-safe `Signaler` trait:
+
+```toml
+lantern-unbounded = { version = "0.1", default-features = false }
+```
+
+The default `native-client` feature retains the standalone `peer-proxy` binary
+and the `FreddieClient` implementation used by the command above.
+
+DTLS ClientHello randomization is enabled by default. Cipher suites and
+extensions retain their negotiated contents but are independently reordered on
+each ClientHello flight, preventing the stable library-default fingerprint that
+has been filtered in deployed censored networks. The pinned WebRTC dependency
+contains the typed hook proposed upstream in
+[`webrtc-rs/webrtc#814`](https://github.com/webrtc-rs/webrtc/pull/814).
+
+The peer proxy uses IPv4 ICE candidates by default. This avoids advertising
+unroutable link-local IPv6 candidates on hosts such as macOS. Set
+`UNBOUNDED_ENABLE_IPV6=1` only where IPv6 routing is known to work.
+
+## Go interoperability
+
+The peer-proxy path has been exercised end to end against the Go Freddie,
+consumer, and egress implementations. A proxied 20 MiB HTTP response remained
+open while peer proxy A was stopped and peer proxy B joined with the same
+consumer session ID. The Go egress migrated its QUIC client connection to B,
+the transfer resumed, and the client received the exact response length with
+HTTP 200.
+
+This is the intended ownership boundary: Rust provides replacement datagram
+paths, while the infrastructure-owned Go egress decides when to probe and
+switch paths. See [`docs/interoperability.md`](docs/interoperability.md) for the
+validation contract.

README.md

@@ -0,0 +1,63 @@
+# Go interoperability contract
+
+The native peer proxy is compatible when it can replace the Go sharing peer
+without changing Freddie, the censored-user consumer, or the egress service.
+The essential live validation is stronger than a successful WebRTC handshake:
+an already-open QUIC stream must survive a peer change.
+
+## Migration scenario
+
+1. Start the Go Freddie and egress services.
+2. Start the Go consumer and wait for its SOCKS proxy.
+3. Start Rust peer proxy A and establish a proxied HTTP transfer large enough
+   to remain active during migration.
+4. Stop A and start Rust peer proxy B.
+5. Confirm B receives the same `ConsumerSessionID` and uses it as the egress
+   WebSocket subprotocol.
+6. Confirm the Go egress probes the replacement path and reports a successful
+   QUIC migration.
+7. Confirm the original HTTP request completes without reconnecting and its
+   status and byte count are unchanged.
+
+On 2026-07-11 this scenario completed with HTTP 200 and exactly 20 MiB received.
+The Go egress reported a successful migration after a 25.145-second probe, and
+the open stream resumed over peer B within the existing QUIC idle timeout.
+
+## Compatibility details found live
+
+- Pion encodes the ICE candidate `protocol` field numerically: `1` for UDP and
+  `2` for TCP. Rust converts those values before producing a W3C candidate.
+- The DataChannel label is `data`, with ordering disabled and zero retransmits.
+- The egress WebSocket subprotocols are ordered as `un80und3d`, the consumer
+  session ID, and `v2.3.0`.
+- IPv4-only ICE is the safe peer-proxy default. Link-local IPv6 interfaces on
+  macOS can produce candidates that pass signaling but never nominate.
+
+## Process lifecycle
+
+The Go producer treats each sharing slot as a resetting state machine. The Rust
+supervisor preserves that behavior: signaling errors, NAT timeouts, relay
+closure, and egress failures all return the slot to discovery. Retries use
+bounded exponential backoff with jitter, and a session that remains active for
+the configured stable interval resets the backoff.
+
+The process runs five independent slots by default, matching the Go widget's
+consumer table size. Each slot owns its WebRTC and egress lifecycles; only the
+shutdown token and event sink are shared.
+
+Cancellation is distinct from failure. It interrupts signaling, NAT traversal,
+an active relay, or a retry delay; closes the current WebRTC peer connection;
+and exits without incrementing the failed-attempt count.
+
+## DTLS fingerprint resistance
+
+The sharing peer is the WebRTC answerer and therefore the active DTLS endpoint
+that sends the ClientHello. The Rust peer randomizes cipher-suite and extension
+ordering for every ClientHello flight, including the retry carrying a
+HelloVerifyRequest cookie. This preserves the negotiated values and the DTLS
+state machine while avoiding a stable library-default fingerprint.
+
+The current Rust DTLS stack is DTLS 1.2. It deliberately does not claim to
+mimic current Chrome DTLS 1.3 fingerprints, which include unsupported cipher
+suites and post-quantum key-share structures. Browser mimicry should only be
+added when those messages can be represented faithfully end to end.

docs/interoperability.md

@@ -91,5 +91,17 @@ The parent signaling envelope uses Go field names and a numeric message type:
 | Answer | 2 | WebRTC session description |
 | ICE | 3 | `ICEMsg`, including `ConsumerSessionID` |
 
-The detailed HTTP exchange, SDP/ICE vectors, timeout behavior, and Freddie
-request identifiers are the next compatibility checkpoint.
+Every request carries `X-BF-Version: v2.3.0`. Signaling messages are posted as
+`application/x-www-form-urlencoded` with `data`, `send-to`, and numeric `type`
+fields. A `418` rejects the protocol version, `404` means the response request
+has expired, and `200` with an empty body means no peer replied before the
+server TTL. Consumer advertisement streams are newline-delimited signaling
+envelopes returned by `GET /v1/signal`.
+
+The peer-proxy exchange is:
+
+1. POST Genesis to `genesis`; wait for an Offer response.
+2. Apply the consumer's offer and gather local ICE candidates.
+3. POST the complete Answer to the offer's `ReplyTo`; wait for ICE.
+4. Convert the Pion candidate objects to W3C candidate strings and add them.
+5. Use `ConsumerSessionID` from the ICE payload when opening the egress socket.

docs/wire-protocol.md

@@ -0,0 +1,147 @@
+use std::env;
+use std::sync::Arc;
+use std::time::Duration;
+
+use lantern_unbounded::peer_proxy::PeerProxyConfig;
+use lantern_unbounded::signaling::FreddieClient;
+use lantern_unbounded::supervisor::{
+    supervise_peer_proxy_pool, PoolEvent, SupervisorConfig, SupervisorEvent,
+};
+use tokio::sync::mpsc;
+use tokio_util::sync::CancellationToken;
+
+fn required(name: &str) -> String {
+    env::var(name).unwrap_or_else(|_| panic!("{name} must be set"))
+}
+
+fn seconds(name: &str, default: u64) -> Duration {
+    Duration::from_secs(
+        env::var(name)
+            .ok()
+            .and_then(|value| value.parse().ok())
+            .unwrap_or(default),
+    )
+}
+
+fn count(name: &str, default: usize) -> usize {
+    env::var(name)
+        .ok()
+        .and_then(|value| value.parse().ok())
+        .filter(|value| *value > 0)
+        .unwrap_or(default)
+}
+
+fn boolean(name: &str, default: bool) -> bool {
+    env::var(name)
+        .map(|value| parse_boolean(&value, default))
+        .unwrap_or(default)
+}
+
+fn parse_boolean(value: &str, default: bool) -> bool {
+    match value.trim().to_ascii_lowercase().as_str() {
+        "1" | "true" | "yes" | "on" | "enable" | "enabled" | "randomize" => true,
+        "0" | "false" | "no" | "off" | "disable" | "disabled" => false,
+        _ => default,
+    }
+}
+
+#[tokio::main(flavor = "multi_thread")]
+async fn main() {
+    let _ = env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("error"))
+        .try_init();
+    let stun_urls = env::var("UNBOUNDED_STUN_URLS")
+        .unwrap_or_default()
+        .split(',')
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(str::to_owned)
+        .collect();
+    let cancellation = CancellationToken::new();
+    let signal_cancellation = cancellation.clone();
+    tokio::spawn(async move {
+        if tokio::signal::ctrl_c().await.is_ok() {
+            signal_cancellation.cancel();
+        }
+    });
+
+    let (events_tx, mut events_rx) = mpsc::unbounded_channel();
+    let reporter = tokio::spawn(async move {
+        while let Some(PoolEvent { slot, event }) = events_rx.recv().await {
+            match event {
+                SupervisorEvent::AttemptStarted { attempt } => {
+                    eprintln!("slot {slot}: starting peer proxy attempt {attempt}");
+                }
+                SupervisorEvent::SessionEnded {
+                    attempt,
+                    outcome,
+                    duration,
+                    retry_in,
+                } => eprintln!(
+                    "slot {slot}: attempt {attempt} session {} ended {:?} after {duration:?}; retrying in {retry_in:?}",
+                    outcome.consumer_session_id, outcome.relay_end
+                ),
+                SupervisorEvent::AttemptFailed {
+                    attempt,
+                    error,
+                    duration,
+                    retry_in,
+                } => eprintln!(
+                    "slot {slot}: attempt {attempt} failed after {duration:?}: {error}; retrying in {retry_in:?}"
+                ),
+                SupervisorEvent::Stopped { summary } => eprintln!(
+                    "slot {slot}: stopped after {} attempts ({} sessions, {} failures)",
+                    summary.attempts, summary.completed_sessions, summary.failed_attempts
+                ),
+            }
+        }
+    });
+
+    let slots = count("UNBOUNDED_CONCURRENT_SESSIONS", 5);
+    let signaler = Arc::new(
+        FreddieClient::new(required("UNBOUNDED_FREDDIE_ENDPOINT"))
+            .unwrap_or_else(|error| panic!("invalid Freddie configuration: {error}")),
+    );
+    let summary = supervise_peer_proxy_pool(
+        SupervisorConfig {
+            peer_proxy: PeerProxyConfig {
+                signaler,
+                egress_url: required("UNBOUNDED_EGRESS_URL"),
+                stun_urls,
+                nat_timeout: seconds("UNBOUNDED_NAT_TIMEOUT_SECONDS", 10),
+                enable_ipv6: boolean("UNBOUNDED_ENABLE_IPV6", false),
+                randomize_dtls: boolean("UNBOUNDED_COVERT_DTLS", true),
+            },
+            initial_backoff: seconds("UNBOUNDED_RETRY_INITIAL_SECONDS", 1),
+            max_backoff: seconds("UNBOUNDED_RETRY_MAX_SECONDS", 30),
+            stable_session: seconds("UNBOUNDED_STABLE_SESSION_SECONDS", 30),
+        },
+        slots,
+        cancellation,
+        Some(events_tx),
+    )
+    .await;
+    reporter.await.expect("event reporter failed");
+    eprintln!(
+        "peer proxy pool stopped: {slots} slots, {} attempts, {} sessions, {} failures",
+        summary.attempts(),
+        summary.completed_sessions(),
+        summary.failed_attempts()
+    );
+}
+
+#[cfg(test)]
+mod tests {
+    use super::parse_boolean;
+
+    #[test]
+    fn parses_boolean_aliases_and_preserves_default_for_unknown_values() {
+        for value in ["1", "true", "YES", "on", "enable", "randomize"] {
+            assert!(parse_boolean(value, false), "{value}");
+        }
+        for value in ["0", "false", "NO", "off", "disable", "disabled"] {
+            assert!(!parse_boolean(value, true), "{value}");
+        }
+        assert!(parse_boolean("unexpected", true));
+        assert!(!parse_boolean("unexpected", false));
+    }
+}