feat(cli): headless tglock-cli, GUI behind a feature, deep test coverage (#25)

Реализует направление PR #15 поверх архитектуры 2.0. Сам PR смерджить нельзя:
он патчит src/bypass.rs, src/network.rs и src/ws_proxy.rs, которых больше нет,
и правит системный DNS — в 2.0 это не нужно, потому что адреса Telegram зашиты
в маршрутах, а SNI остаётся настоящим. Взято разделение GUI/CLI и произвольный
bind-адрес, отброшены DNS-менеджмент и проверка root: CLI не требует прав.

Closes #10, #17 — GUI не создаёт окно без 3D-ускорения, на машине без монитора
и в виртуалке. Причина в WebView под Tauri, поэтому лечится не программным
рендером, а бинарём, в котором WebView нет вовсе: при выключенной фиче gui
Tauri и фронтенд в сборку не попадают. Отдельная задача CI собирает и гоняет
CLI на голом ubuntu без Node.js и без libwebkit2gtk.

Структура:
- src/lib.rs — ядро (mtproto, proxy, transport, config), без Tauri
- src/main.rs — GUI, required-features = ["gui"]
- src/bin/cli.rs — headless-бинарь на clap
- build.rs вызывает tauri_build только при включённой фиче gui

Исправлено по пути:
- Определение протокола: SOCKS5 и MTProto различались по первому байту, но
  is_reserved_init не исключает 0x05, поэтому примерно одно соединение из 256
  уезжало в SOCKS5-ветку и умирало. Теперь неоднозначный первый байт решается
  по полному 64-байтному init и секрету.
- Ярлык маршрута в UI: код 2 подписывался как «Cloudflare Worker», хотя это
  запасной Telegram IP, а системный DNS и настоящий Worker оба показывались
  как «Автоматический маршрут». Метки переехали в transport::route_label,
  общий для обоих интерфейсов.
- Секрет прокси: под DynamicUser и ProtectHome домашней папки нет, secret_path
  возвращает None и секрет генерировался заново при каждом старте, ломая всем
  настроенным клиентам tg://-ссылку. Добавлен --secret-file.
- README обещал Rust 1.75+, тогда как Cargo.toml требует 1.88 и CI это
  проверяет. Это и есть первопричина #3.

Политика доступа: прямые не-Telegram соединения разрешены только на loopback,
на любом сетевом адресе нужен явный --allow-direct. Правило из ISSUE_AUDIT о
том, что LAN не должен становиться открытым SOCKS5, теперь выражено в типе
ListenConfig и покрыто тестами.

Тесты: 46 в библиотеке + 12 в CLI. Появился сквозной тест туннеля против
мок-релея, который реализует сторону Telegram по obfuscated2 — проверяется
не внутренняя консистентность, а что реле получает ровно тот открытый текст,
который отправил клиент, и обратно. Плюс расписание backoff, фолбэк при всех
маршрутах в cooldown, валидация Worker-доменов, отказы SOCKS5, устойчивость
секрета к перезапуску и корректная остановка по SIGTERM.

Документация: секция CLI в README с юнитом systemd и Dockerfile.

Co-authored-by: by-sonic <171230345+by-sonic@users.noreply.github.com>

src/bin/cli.rs

@@ -0,0 +1,333 @@
+//! TGLock without a graphical interface.
+//!
+//! Built with `--no-default-features` this binary links neither Tauri nor a
+//! system WebView, so it runs on servers, in containers and on machines with no
+//! GPU or monitor — the cases that make the GUI fail to start at all
+//! (by-sonic/tglock#10, by-sonic/tglock#17).
+
+use clap::Parser;
+use std::net::IpAddr;
+use std::path::PathBuf;
+use std::process::ExitCode;
+use std::sync::atomic::Ordering;
+use std::sync::Arc;
+use std::time::Duration;
+use tglock::config::ListenConfig;
+use tglock::{mtproto, proxy, transport};
+
+const STATUS_POLL: Duration = Duration::from_secs(1);
+
+#[derive(Debug, Parser)]
+#[command(
+    name = "tglock-cli",
+    version,
+    about = "TGLock без графического интерфейса: локальный MTProto-прокси через WebSocket"
+)]
+struct Args {
+    /// Адрес для прослушивания. 127.0.0.1 — только этот компьютер
+    #[arg(short, long, value_name = "IP", default_value = "127.0.0.1")]
+    bind: IpAddr,
+
+    /// Порт локального прокси
+    #[arg(short, long, value_name = "PORT", default_value_t = proxy::DEFAULT_PORT)]
+    port: u16,
+
+    /// То же, что --bind 0.0.0.0: доступ с других устройств в локальной сети
+    #[arg(long, conflicts_with = "bind")]
+    lan: bool,
+
+    /// Домен своего Cloudflare Worker как резервный маршрут. Можно повторять
+    #[arg(long, value_name = "DOMAIN")]
+    worker: Vec<String>,
+
+    /// Проксировать и не-Telegram адреса. На сетевом адресе это открытый SOCKS5
+    #[arg(long)]
+    allow_direct: bool,
+
+    /// Файл с секретом прокси. Обязателен для сервиса: иначе после перезапуска
+    /// секрет будет новым и уже настроенные клиенты перестанут подключаться
+    #[arg(long, value_name = "PATH")]
+    secret_file: Option<PathBuf>,
+
+    /// Печатать только ошибки
+    #[arg(short, long)]
+    quiet: bool,
+}
+
+impl Args {
+    fn stats(&self) -> Arc<proxy::Stats> {
+        match &self.secret_file {
+            Some(path) => proxy::Stats::with_secret(mtproto::load_or_create_secret_at(path)),
+            None => proxy::Stats::new(),
+        }
+    }
+
+    fn listen(&self) -> ListenConfig {
+        let base = if self.lan {
+            ListenConfig::lan(self.port)
+        } else {
+            ListenConfig::new(self.bind, self.port)
+        };
+        if self.allow_direct {
+            base.with_allow_direct(true)
+        } else {
+            base
+        }
+    }
+
+    fn worker_domains(&self) -> String {
+        self.worker.join(",")
+    }
+}
+
+fn main() -> ExitCode {
+    let args = Args::parse();
+    let runtime = match tokio::runtime::Runtime::new() {
+        Ok(runtime) => runtime,
+        Err(error) => {
+            eprintln!("tglock-cli: не удалось запустить среду выполнения: {error}");
+            return ExitCode::FAILURE;
+        }
+    };
+
+    match runtime.block_on(serve(args)) {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(error) => {
+            eprintln!("tglock-cli: {error}");
+            ExitCode::FAILURE
+        }
+    }
+}
+
+async fn serve(args: Args) -> Result<(), String> {
+    let listen = args.listen();
+    let stats = args.stats();
+    stats.set_worker_domain(&args.worker_domains());
+
+    // Bind before printing anything: a busy port must be an error, not a
+    // daemon that reports success and silently does nothing.
+    let listener = proxy::bind(listen).await?;
+
+    if !args.quiet {
+        println!("Слушаю {}", listen.addr);
+        println!(
+            "Ссылка для Telegram: {}",
+            listen.telegram_link(&stats.telegram_secret())
+        );
+        if listen.allow_direct && !listen.addr.ip().is_loopback() {
+            println!(
+                "Внимание: --allow-direct на адресе {} превращает TGLock в открытый SOCKS5-прокси",
+                listen.addr.ip()
+            );
+        } else if !listen.allow_direct {
+            println!("Пропускаю только адреса Telegram");
+        }
+        if !args.worker.is_empty() {
+            println!("Резервные Worker-домены: {}", args.worker_domains());
+        }
+    }
+
+    let server_stats = stats.clone();
+    let mut server =
+        tokio::spawn(
+            async move { proxy::serve(server_stats, listener, listen.allow_direct).await },
+        );
+    let watcher = (!args.quiet).then(|| tokio::spawn(watch_status(stats.clone())));
+
+    let outcome = tokio::select! {
+        joined = &mut server => joined.map_err(|error| format!("рабочая задача упала: {error}"))?,
+        signal = shutdown_signal() => {
+            signal.map_err(|error| format!("обработчик сигналов: {error}"))?;
+            if !args.quiet {
+                println!("Получен сигнал остановки, закрываю соединения…");
+            }
+            stats.stop();
+            server
+                .await
+                .map_err(|error| format!("рабочая задача упала: {error}"))?
+        }
+    };
+
+    if let Some(watcher) = watcher {
+        watcher.abort();
+    }
+    outcome
+}
+
+/// Print a line whenever the tunnel state changes.
+///
+/// This is the text equivalent of the GUI diagnostics tab: without it a daemon
+/// gives journald nothing to show when Telegram stops working.
+async fn watch_status(stats: Arc<proxy::Stats>) {
+    let mut previous = None;
+    loop {
+        tokio::time::sleep(STATUS_POLL).await;
+        let current = (
+            stats.active.load(Ordering::Relaxed),
+            stats.ws.load(Ordering::Relaxed),
+            stats.last_dc.load(Ordering::Relaxed),
+            stats.last_route.load(Ordering::Relaxed),
+            stats.ws_failures.load(Ordering::Relaxed),
+        );
+        if previous.as_ref() == Some(&current) {
+            continue;
+        }
+        let (active, tunnels, dc, route, failures) = current;
+        println!(
+            "соединений {active} · туннелей {tunnels} · {} · {} · сбоев {failures}",
+            if dc > 0 {
+                format!("DC{dc}")
+            } else {
+                "DC не определён".to_owned()
+            },
+            transport::route_label(route)
+        );
+        previous = Some(current);
+    }
+}
+
+/// Ctrl+C everywhere, plus SIGTERM on unix so `systemctl stop` shuts the
+/// tunnel down cleanly instead of killing it.
+#[cfg(unix)]
+async fn shutdown_signal() -> std::io::Result<()> {
+    use tokio::signal::unix::{signal, SignalKind};
+
+    let mut terminate = signal(SignalKind::terminate())?;
+    tokio::select! {
+        result = tokio::signal::ctrl_c() => result,
+        _ = terminate.recv() => Ok(()),
+    }
+}
+
+#[cfg(not(unix))]
+async fn shutdown_signal() -> std::io::Result<()> {
+    tokio::signal::ctrl_c().await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use clap::CommandFactory;
+
+    fn parse(args: &[&str]) -> Args {
+        Args::try_parse_from(std::iter::once("tglock-cli").chain(args.iter().copied())).unwrap()
+    }
+
+    #[test]
+    fn command_definition_is_valid() {
+        Args::command().debug_assert();
+    }
+
+    #[test]
+    fn defaults_to_loopback_on_the_default_port() {
+        let listen = parse(&[]).listen();
+        assert_eq!(listen.addr.to_string(), "127.0.0.1:1080");
+        assert!(listen.allow_direct);
+    }
+
+    #[test]
+    fn lan_flag_matches_explicit_wildcard_bind() {
+        assert_eq!(
+            parse(&["--lan"]).listen(),
+            parse(&["-b", "0.0.0.0"]).listen()
+        );
+    }
+
+    #[test]
+    fn lan_does_not_relay_non_telegram_traffic() {
+        let listen = parse(&["--lan"]).listen();
+        assert_eq!(listen.addr.to_string(), "0.0.0.0:1080");
+        assert!(!listen.allow_direct);
+    }
+
+    #[test]
+    fn allow_direct_is_the_only_way_to_open_a_network_listener() {
+        assert!(!parse(&["-b", "192.168.1.10"]).listen().allow_direct);
+        assert!(
+            parse(&["-b", "192.168.1.10", "--allow-direct"])
+                .listen()
+                .allow_direct
+        );
+    }
+
+    #[test]
+    fn bind_and_port_are_honoured() {
+        let listen = parse(&["--bind", "10.0.0.7", "--port", "1443"]).listen();
+        assert_eq!(listen.addr.to_string(), "10.0.0.7:1443");
+    }
+
+    #[test]
+    fn ipv6_bind_is_accepted() {
+        let listen = parse(&["-b", "::1", "-p", "2080"]).listen();
+        assert_eq!(listen.addr.to_string(), "[::1]:2080");
+        assert!(listen.allow_direct);
+    }
+
+    #[test]
+    fn repeated_worker_flags_collapse_into_one_list() {
+        let args = parse(&["--worker", "a.workers.dev", "--worker", "b.workers.dev"]);
+        assert_eq!(args.worker_domains(), "a.workers.dev,b.workers.dev");
+    }
+
+    #[test]
+    fn no_worker_flag_means_no_domains() {
+        assert!(parse(&[]).worker_domains().is_empty());
+    }
+
+    #[test]
+    fn lan_and_explicit_bind_cannot_be_combined() {
+        assert!(Args::try_parse_from(["tglock-cli", "--lan", "-b", "127.0.0.1"]).is_err());
+    }
+
+    #[test]
+    fn a_pinned_secret_file_survives_a_restart() {
+        let path = std::env::temp_dir().join(format!(
+            "tglock-cli-secret-{}-{:?}",
+            std::process::id(),
+            std::thread::current().id()
+        ));
+        let _ = std::fs::remove_file(&path);
+
+        let first = parse(&["--secret-file", path.to_str().unwrap()])
+            .stats()
+            .telegram_secret();
+        let second = parse(&["--secret-file", path.to_str().unwrap()])
+            .stats()
+            .telegram_secret();
+
+        assert_eq!(
+            first, second,
+            "a restart must advertise the same tg:// secret"
+        );
+        assert!(first.starts_with("dd"));
+
+        // A corrupted file must not wedge the daemon: it is replaced.
+        std::fs::write(&path, "garbage").unwrap();
+        let third = parse(&["--secret-file", path.to_str().unwrap()])
+            .stats()
+            .telegram_secret();
+        assert_ne!(third, first);
+        let fourth = parse(&["--secret-file", path.to_str().unwrap()])
+            .stats()
+            .telegram_secret();
+        assert_eq!(third, fourth, "the replacement must be persisted in turn");
+
+        let _ = std::fs::remove_file(&path);
+    }
+
+    #[test]
+    fn rejects_malformed_values() {
+        for bad in [
+            vec!["-b", "not-an-ip"],
+            vec!["-p", "70000"],
+            vec!["-p", "-1"],
+            vec!["--unknown"],
+        ] {
+            assert!(
+                Args::try_parse_from(std::iter::once("tglock-cli").chain(bad.iter().copied()))
+                    .is_err(),
+                "{bad:?} must be rejected"
+            );
+        }
+    }
+}

src/config.rs

@@ -0,0 +1,135 @@
+//! Listener configuration shared by the GUI and the CLI.
+
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+
+/// Where the local proxy listens and whether it is allowed to relay anything
+/// other than Telegram.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct ListenConfig {
+    pub addr: SocketAddr,
+    /// Relay non-Telegram destinations as a plain SOCKS5 proxy.
+    ///
+    /// Loopback listeners get this for free because only local processes can
+    /// reach them. A listener the network can reach must opt in explicitly, so
+    /// that sharing TGLock across a flat never silently turns the machine into
+    /// an open SOCKS5 relay.
+    pub allow_direct: bool,
+}
+
+impl ListenConfig {
+    /// Listener with the default policy for the given address.
+    pub fn new(ip: IpAddr, port: u16) -> Self {
+        Self {
+            addr: SocketAddr::new(ip, port),
+            allow_direct: ip.is_loopback(),
+        }
+    }
+
+    /// `127.0.0.1` — only this machine, non-Telegram traffic relayed.
+    pub fn loopback(port: u16) -> Self {
+        Self::new(IpAddr::V4(Ipv4Addr::LOCALHOST), port)
+    }
+
+    /// `0.0.0.0` — reachable from the local network, Telegram destinations only.
+    pub fn lan(port: u16) -> Self {
+        Self::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), port)
+    }
+
+    /// Override the direct-relay policy. Used by `--allow-direct`.
+    pub fn with_allow_direct(mut self, allow_direct: bool) -> Self {
+        self.allow_direct = allow_direct;
+        self
+    }
+
+    /// Host to advertise in a `tg://proxy` link for this listener.
+    ///
+    /// A wildcard bind is not a usable destination, so it is resolved to the
+    /// address this machine uses to reach the network.
+    pub fn advertised_host(&self) -> String {
+        let ip = self.addr.ip();
+        if ip.is_unspecified() {
+            outbound_ip().unwrap_or_else(|| Ipv4Addr::LOCALHOST.to_string())
+        } else {
+            ip.to_string()
+        }
+    }
+
+    /// `tg://proxy` link that points Telegram at this listener.
+    pub fn telegram_link(&self, secret: &str) -> String {
+        format!(
+            "tg://proxy?server={}&port={}&secret={}",
+            self.advertised_host(),
+            self.addr.port(),
+            secret
+        )
+    }
+}
+
+/// Local address of the interface that reaches the default route.
+///
+/// No packet is sent: connecting a UDP socket only makes the OS pick a route.
+fn outbound_ip() -> Option<String> {
+    let socket = std::net::UdpSocket::bind("0.0.0.0:0").ok()?;
+    socket.connect("8.8.8.8:80").ok()?;
+    Some(socket.local_addr().ok()?.ip().to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn loopback_relays_direct_traffic() {
+        let config = ListenConfig::loopback(1080);
+        assert_eq!(config.addr.to_string(), "127.0.0.1:1080");
+        assert!(config.allow_direct);
+    }
+
+    #[test]
+    fn lan_restricts_to_telegram_by_default() {
+        let config = ListenConfig::lan(1080);
+        assert_eq!(config.addr.to_string(), "0.0.0.0:1080");
+        assert!(!config.allow_direct);
+    }
+
+    #[test]
+    fn any_routable_address_restricts_to_telegram() {
+        for ip in ["192.168.1.10", "10.0.0.5", "::"] {
+            let config = ListenConfig::new(ip.parse().unwrap(), 1080);
+            assert!(
+                !config.allow_direct,
+                "{ip} must not relay non-Telegram traffic without an explicit opt-in"
+            );
+        }
+    }
+
+    #[test]
+    fn ipv6_loopback_is_treated_as_local() {
+        let config = ListenConfig::new("::1".parse().unwrap(), 1080);
+        assert!(config.allow_direct);
+        assert_eq!(config.addr.to_string(), "[::1]:1080");
+    }
+
+    #[test]
+    fn allow_direct_override_is_explicit_in_both_directions() {
+        assert!(ListenConfig::lan(1080).with_allow_direct(true).allow_direct);
+        assert!(
+            !ListenConfig::loopback(1080)
+                .with_allow_direct(false)
+                .allow_direct
+        );
+    }
+
+    #[test]
+    fn link_uses_concrete_host_and_port() {
+        let link = ListenConfig::new("192.168.1.10".parse().unwrap(), 1443).telegram_link("ddaa");
+        assert_eq!(link, "tg://proxy?server=192.168.1.10&port=1443&secret=ddaa");
+    }
+
+    #[test]
+    fn wildcard_bind_never_advertises_itself() {
+        let host = ListenConfig::lan(1080).advertised_host();
+        assert_ne!(host, "0.0.0.0");
+        assert!(!host.is_empty());
+    }
+}

src/lib.rs

@@ -0,0 +1,11 @@
+//! TGLock core: the MTProto/WebSocket transport shared by the desktop GUI and
+//! the headless CLI.
+//!
+//! Nothing in this crate depends on Tauri or on a windowing system, so the
+//! `tglock-cli` binary can be built with `--no-default-features` on a server
+//! that has neither a GPU nor a monitor.
+
+pub mod config;
+pub mod mtproto;
+pub mod proxy;
+pub mod transport;

src/main.rs

@@ -1,15 +1,13 @@
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
 
-mod mtproto;
-mod proxy;
-mod transport;
-
 use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
 use std::sync::atomic::Ordering;
 use std::sync::{Arc, Mutex};
 use std::time::{Instant, SystemTime, UNIX_EPOCH};
 use tauri::{Manager, State};
+use tglock::config::ListenConfig;
+use tglock::{proxy, transport};
 
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[serde(rename_all = "camelCase")]
@@ -90,11 +88,7 @@ impl AppState {
 
     fn snapshot(&self) -> StatusSnapshot {
         let data_center = self.stats.last_dc.load(Ordering::Relaxed);
-        let route = match self.stats.last_route.load(Ordering::Relaxed) {
-            1 => "Telegram WebSocket",
-            2 => "Cloudflare Worker",
-            _ => "Автоматический маршрут",
-        };
+        let route = transport::route_label(self.stats.last_route.load(Ordering::Relaxed));
         StatusSnapshot {
             running: self.stats.running.load(Ordering::SeqCst),
             active_connections: self.stats.active.load(Ordering::Relaxed),
@@ -173,10 +167,14 @@ fn start_proxy(state: State<'_, AppState>) -> Result<StatusSnapshot, String> {
     *state.started_at.lock().unwrap() = Some(Instant::now());
     state.log("Запускаю защищённый маршрут…", false);
 
+    let listen = if settings.lan_mode {
+        ListenConfig::lan(settings.port)
+    } else {
+        ListenConfig::loopback(settings.port)
+    };
+
     let stats = state.stats.clone();
     let logs = state.logs.clone();
-    let lan_mode = settings.lan_mode;
-    let port = settings.port;
     std::thread::spawn(move || {
         let runtime = match tokio::runtime::Runtime::new() {
             Ok(runtime) => runtime,
@@ -185,7 +183,7 @@ fn start_proxy(state: State<'_, AppState>) -> Result<StatusSnapshot, String> {
                 return;
             }
         };
-        if let Err(error) = runtime.block_on(proxy::run(stats, lan_mode, port)) {
+        if let Err(error) = runtime.block_on(proxy::run(stats, listen)) {
             push_log(&logs, format!("Ошибка подключения: {error}"), true);
         }
     });
@@ -202,28 +200,8 @@ fn start_proxy(state: State<'_, AppState>) -> Result<StatusSnapshot, String> {
             .unwrap_or_else(|| "Не удалось запустить прокси".into()));
     }
 
-    state.log(
-        format!(
-            "Прокси запущен на {}:{}",
-            if settings.lan_mode {
-                "0.0.0.0"
-            } else {
-                "127.0.0.1"
-            },
-            settings.port
-        ),
-        false,
-    );
-    let host = if settings.lan_mode {
-        local_ip().unwrap_or_else(|| "127.0.0.1".into())
-    } else {
-        "127.0.0.1".into()
-    };
-    let _ = open::that(format!(
-        "tg://proxy?server={host}&port={}&secret={}",
-        settings.port,
-        state.stats.telegram_secret()
-    ));
+    state.log(format!("Прокси запущен на {}", listen.addr), false);
+    let _ = open::that(listen.telegram_link(&state.stats.telegram_secret()));
     state.log("Открываю подключение в Telegram…", false);
     Ok(state.snapshot())
 }
@@ -244,12 +222,6 @@ fn push_log(logs: &Arc<Mutex<Vec<LogLine>>>, message: String, error: bool) {
     });
 }
 
-fn local_ip() -> Option<String> {
-    let socket = std::net::UdpSocket::bind("0.0.0.0:0").ok()?;
-    socket.connect("8.8.8.8:80").ok()?;
-    Some(socket.local_addr().ok()?.ip().to_string())
-}
-
 fn main() {
     tauri::Builder::default()
         .setup(|app| {

src/mtproto.rs

@@ -2,6 +2,7 @@ use aes::Aes256;
 use cipher::{KeyIvInit, StreamCipher};
 use rand::{rngs::OsRng, RngCore};
 use sha2::{Digest, Sha256};
+use std::path::Path;
 #[cfg(not(test))]
 use std::path::PathBuf;
 
@@ -50,12 +51,13 @@ pub fn generate_secret() -> [u8; 16] {
     secret
 }
 
-#[cfg(not(test))]
-pub fn load_or_create_secret() -> [u8; 16] {
-    let Some(path) = secret_path() else {
-        return generate_secret();
-    };
-    if let Ok(value) = std::fs::read_to_string(&path) {
+/// Reuse the secret stored at `path`, creating it if it is missing or unusable.
+///
+/// A daemon needs this: the secret is half of the `tg://proxy` link, so a
+/// service that invents a new one on every restart silently invalidates every
+/// client that was already configured.
+pub fn load_or_create_secret_at(path: &Path) -> [u8; 16] {
+    if let Ok(value) = std::fs::read_to_string(path) {
         if let Some(secret) = parse_secret_hex(value.trim()) {
             return secret;
         }
@@ -65,10 +67,18 @@ pub fn load_or_create_secret() -> [u8; 16] {
     if let Some(parent) = path.parent() {
         let _ = std::fs::create_dir_all(parent);
     }
-    write_secret_file(&path, &secret_hex(&secret));
+    write_secret_file(path, &secret_hex(&secret));
     secret
 }
 
+#[cfg(not(test))]
+pub fn load_or_create_secret() -> [u8; 16] {
+    match secret_path() {
+        Some(path) => load_or_create_secret_at(&path),
+        None => generate_secret(),
+    }
+}
+
 #[cfg(not(test))]
 fn secret_path() -> Option<PathBuf> {
     #[cfg(target_os = "windows")]
@@ -94,8 +104,8 @@ fn secret_path() -> Option<PathBuf> {
     }
 }
 
-#[cfg(all(not(test), unix))]
-fn write_secret_file(path: &std::path::Path, value: &str) {
+#[cfg(unix)]
+fn write_secret_file(path: &Path, value: &str) {
     use std::io::Write;
     use std::os::unix::fs::OpenOptionsExt;
     if let Ok(mut file) = std::fs::OpenOptions::new()
@@ -109,8 +119,8 @@ fn write_secret_file(path: &std::path::Path, value: &str) {
     }
 }
 
-#[cfg(all(not(test), not(unix)))]
-fn write_secret_file(path: &std::path::Path, value: &str) {
+#[cfg(not(unix))]
+fn write_secret_file(path: &Path, value: &str) {
     let _ = std::fs::write(path, value);
 }
 
@@ -255,6 +265,66 @@ pub(crate) fn test_client_init(secret: &[u8; 16], dc_index: i16) -> [u8; INIT_LE
     tests::generate_client_init(secret, PADDED_INTERMEDIATE, dc_index)
 }
 
+/// One end of an obfuscated2 stream, built the way the real peer builds it.
+///
+/// Lets tests assert on the bytes the peer actually observes rather than on the
+/// proxy's own view of them, so a mistake that is symmetric inside
+/// [`CryptoContext`] still fails the test.
+#[cfg(test)]
+pub(crate) struct TestPeer {
+    encrypt: AesCtr,
+    decrypt: AesCtr,
+}
+
+#[cfg(test)]
+impl TestPeer {
+    pub(crate) fn encrypt(&mut self, data: &mut [u8]) {
+        self.encrypt.apply_keystream(data);
+    }
+
+    pub(crate) fn decrypt(&mut self, data: &mut [u8]) {
+        self.decrypt.apply_keystream(data);
+    }
+}
+
+/// The Telegram client: its keys come from the init it sent, salted with the
+/// shared secret.
+#[cfg(test)]
+pub(crate) fn test_client_peer(init: &[u8; INIT_LEN], secret: &[u8; 16]) -> TestPeer {
+    let key = secret_key(&init[KEY_START..KEY_END], secret);
+    let iv: [u8; 16] = init[KEY_END..IV_END].try_into().unwrap();
+    let mut encrypt = AesCtr::new((&key).into(), (&iv).into());
+    encrypt.apply_keystream(&mut [0; INIT_LEN]);
+
+    let reversed: Vec<u8> = init[KEY_START..IV_END].iter().rev().copied().collect();
+    let decrypt_key = secret_key(&reversed[..32], secret);
+    let decrypt_iv: [u8; 16] = reversed[32..].try_into().unwrap();
+    let decrypt = AesCtr::new((&decrypt_key).into(), (&decrypt_iv).into());
+
+    TestPeer { encrypt, decrypt }
+}
+
+/// The Telegram relay: no shared secret, keys come straight from the init the
+/// proxy generated for it.
+#[cfg(test)]
+pub(crate) fn test_relay_peer(relay_init: &[u8; INIT_LEN]) -> TestPeer {
+    let key: [u8; 32] = relay_init[KEY_START..KEY_END].try_into().unwrap();
+    let iv: [u8; 16] = relay_init[KEY_END..IV_END].try_into().unwrap();
+    let mut decrypt = AesCtr::new((&key).into(), (&iv).into());
+    decrypt.apply_keystream(&mut [0; INIT_LEN]);
+
+    let reversed: Vec<u8> = relay_init[KEY_START..IV_END]
+        .iter()
+        .rev()
+        .copied()
+        .collect();
+    let encrypt_key: [u8; 32] = reversed[..32].try_into().unwrap();
+    let encrypt_iv: [u8; 16] = reversed[32..].try_into().unwrap();
+    let encrypt = AesCtr::new((&encrypt_key).into(), (&encrypt_iv).into());
+
+    TestPeer { encrypt, decrypt }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -304,6 +374,133 @@ mod tests {
         );
     }
 
+    #[test]
+    fn accepts_every_supported_protocol_tag() {
+        let secret = [7; 16];
+        for tag in [ABRIDGED, INTERMEDIATE, PADDED_INTERMEDIATE] {
+            let init = generate_client_init(&secret, tag, 2);
+            let parsed = parse_client_init(&init, &secret)
+                .unwrap_or_else(|| panic!("tag {tag:02x?} must be accepted"));
+            assert_eq!(parsed.dc, 2);
+            assert!(!parsed.media);
+        }
+    }
+
+    #[test]
+    fn relay_init_carries_the_clients_protocol_tag_and_dc() {
+        let secret = [3; 16];
+        for (tag, dc_index) in [
+            (ABRIDGED, 1_i16),
+            (INTERMEDIATE, -5),
+            (PADDED_INTERMEDIATE, 203),
+        ] {
+            let init = generate_client_init(&secret, tag, dc_index);
+            let parsed = parse_client_init(&init, &secret).unwrap();
+
+            // The relay init is freshly generated, never the client's bytes.
+            assert_ne!(parsed.relay_init, init);
+
+            // Decoding the relay init the way Telegram does must recover the
+            // same protocol and data centre the client asked for.
+            let key: [u8; 32] = parsed.relay_init[KEY_START..KEY_END].try_into().unwrap();
+            let iv: [u8; 16] = parsed.relay_init[KEY_END..IV_END].try_into().unwrap();
+            let mut cipher = AesCtr::new((&key).into(), (&iv).into());
+            let mut decoded = parsed.relay_init;
+            cipher.apply_keystream(&mut decoded);
+
+            assert_eq!(decoded[TAG_START..DC_START], tag);
+            assert_eq!(
+                i16::from_le_bytes([decoded[DC_START], decoded[DC_START + 1]]),
+                dc_index
+            );
+        }
+    }
+
+    #[test]
+    fn rejects_data_centers_outside_the_known_range() {
+        let secret = [11; 16];
+        for dc_index in [0_i16, 6, -6, 204, -204, 1000] {
+            let init = generate_client_init(&secret, INTERMEDIATE, dc_index);
+            assert!(
+                parse_client_init(&init, &secret).is_none(),
+                "DC index {dc_index} must be rejected"
+            );
+        }
+    }
+
+    #[test]
+    fn negative_index_marks_media_and_keeps_the_data_center() {
+        let secret = [13; 16];
+        for dc in [1_u16, 2, 3, 4, 5, 203] {
+            let index = -(dc as i16);
+            let parsed =
+                parse_client_init(&generate_client_init(&secret, ABRIDGED, index), &secret)
+                    .unwrap();
+            assert_eq!(parsed.dc, dc);
+            assert!(parsed.media);
+
+            let parsed =
+                parse_client_init(&generate_client_init(&secret, ABRIDGED, dc as i16), &secret)
+                    .unwrap();
+            assert_eq!(parsed.dc, dc);
+            assert!(!parsed.media);
+        }
+    }
+
+    #[test]
+    fn plaintext_survives_the_trip_to_the_relay_and_back() {
+        let secret = [42; 16];
+        let init = generate_client_init(&secret, ABRIDGED, 2);
+        let mut parsed = parse_client_init(&init, &secret).unwrap();
+        let mut client = test_client_peer(&init, &secret);
+        let mut relay = test_relay_peer(&parsed.relay_init);
+
+        let request = b"exactly what Telegram must receive".to_vec();
+        let mut wire = request.clone();
+        client.encrypt(&mut wire);
+        assert_ne!(wire, request, "the wire must not carry plaintext");
+        parsed.crypto.client_to_telegram(&mut wire);
+        assert_ne!(wire, request, "the upstream wire must not carry plaintext");
+        relay.decrypt(&mut wire);
+        assert_eq!(wire, request);
+
+        let response = b"exactly what the client must receive".to_vec();
+        let mut wire = response.clone();
+        relay.encrypt(&mut wire);
+        parsed.crypto.telegram_to_client(&mut wire);
+        client.decrypt(&mut wire);
+        assert_eq!(wire, response);
+    }
+
+    #[test]
+    fn keystream_advances_across_chunks() {
+        let secret = [5; 16];
+        let init = generate_client_init(&secret, INTERMEDIATE, 3);
+        let mut parsed = parse_client_init(&init, &secret).unwrap();
+        let mut client = test_client_peer(&init, &secret);
+        let mut relay = test_relay_peer(&parsed.relay_init);
+
+        // A stream cipher is only correct if both ends stay in lockstep across
+        // arbitrary chunk boundaries, which is how TCP actually delivers data.
+        let chunks: [&[u8]; 4] = [b"one", b"", b"the third chunk is longer", b"4"];
+        for chunk in chunks {
+            let mut wire = chunk.to_vec();
+            client.encrypt(&mut wire);
+            parsed.crypto.client_to_telegram(&mut wire);
+            relay.decrypt(&mut wire);
+            assert_eq!(wire, chunk);
+        }
+    }
+
+    #[test]
+    fn reserved_prefixes_never_leave_the_generator() {
+        // A relay init that starts with an HTTP verb or a protocol tag would be
+        // misread by Telegram's frontend.
+        for _ in 0..2_000 {
+            assert!(!is_reserved_init(&generate_relay_init(ABRIDGED, 2)));
+        }
+    }
+
     #[test]
     fn parses_persisted_secret() {
         assert_eq!(

src/proxy.rs

@@ -1,3 +1,4 @@
+use crate::config::ListenConfig;
 use std::net::Ipv4Addr;
 use std::sync::atomic::{AtomicBool, AtomicU16, AtomicU32, AtomicU8, Ordering};
 use std::sync::{Arc, Mutex};
@@ -8,6 +9,12 @@ use tokio_tungstenite::tungstenite;
 
 pub const DEFAULT_PORT: u16 = 1080;
 const IO_TIMEOUT: Duration = Duration::from_secs(10);
+const INIT_LEN: usize = 64;
+const SOCKS5_VERSION: u8 = 0x05;
+/// How long to wait for a full MTProto init before treating an ambiguous first
+/// byte as the start of a SOCKS5 greeting.
+const PROTOCOL_PROBE_TIMEOUT: Duration = Duration::from_millis(250);
+const PROTOCOL_PROBE_INTERVAL: Duration = Duration::from_millis(5);
 
 pub struct Stats {
     pub running: AtomicBool,
@@ -25,6 +32,14 @@ pub struct Stats {
 
 impl Stats {
     pub fn new() -> Arc<Self> {
+        Self::with_secret(initial_secret())
+    }
+
+    /// Build with an explicit proxy secret.
+    ///
+    /// A daemon must pin this: the secret is half of the `tg://proxy` link, so
+    /// generating a fresh one on restart breaks every configured client.
+    pub fn with_secret(secret: [u8; 16]) -> Arc<Self> {
         Arc::new(Self {
             running: AtomicBool::new(false),
             active: AtomicU32::new(0),
@@ -34,7 +49,7 @@ impl Stats {
             ws_failures: AtomicU32::new(0),
             last_route: AtomicU8::new(0),
             transport: crate::transport::TransportEngine::new(),
-            secret: initial_secret(),
+            secret,
             shutdown: Mutex::new(None),
         })
     }
@@ -69,13 +84,28 @@ fn initial_secret() -> [u8; 16] {
     crate::mtproto::generate_secret()
 }
 
-pub async fn run(stats: Arc<Stats>, lan: bool, port: u16) -> Result<(), String> {
-    let host = if lan { "0.0.0.0" } else { "127.0.0.1" };
-    let addr = format!("{}:{}", host, port);
-    let listener = TcpListener::bind(&addr)
+/// Claim the local port.
+///
+/// Separated from [`serve`] so a caller can report a port conflict before it
+/// tells the user the proxy is running.
+pub async fn bind(listen: ListenConfig) -> Result<TcpListener, String> {
+    TcpListener::bind(listen.addr)
         .await
-        .map_err(|e| format!("Port {} busy: {}", port, e))?;
+        .map_err(|error| format!("Cannot listen on {}: {}", listen.addr, error))
+}
 
+/// Bind and serve until [`Stats::stop`] is called.
+pub async fn run(stats: Arc<Stats>, listen: ListenConfig) -> Result<(), String> {
+    let listener = bind(listen).await?;
+    serve(stats, listener, listen.allow_direct).await
+}
+
+/// Accept clients on an already bound listener.
+pub async fn serve(
+    stats: Arc<Stats>,
+    listener: TcpListener,
+    allow_direct: bool,
+) -> Result<(), String> {
     stats.running.store(true, Ordering::SeqCst);
     let (shutdown_tx, mut shutdown_rx) = tokio::sync::watch::channel(false);
     *stats.shutdown.lock().unwrap() = Some(shutdown_tx);
@@ -90,7 +120,7 @@ pub async fn run(stats: Arc<Stats>, lan: bool, port: u16) -> Result<(), String>
                         s.active.fetch_add(1, Ordering::Relaxed);
                         s.total.fetch_add(1, Ordering::Relaxed);
                         tasks.spawn(async move {
-                            let _ = handle(stream, &s, !lan).await;
+                            let _ = handle(stream, &s, allow_direct).await;
                             s.active.fetch_sub(1, Ordering::Relaxed);
                         });
                     }
@@ -115,22 +145,67 @@ pub async fn run(stats: Arc<Stats>, lan: bool, port: u16) -> Result<(), String>
 
 // -- SOCKS5 -----------------------------------------------------------------
 
+#[derive(Debug, Eq, PartialEq)]
+enum Protocol {
+    Socks5,
+    MtProto,
+    Empty,
+}
+
 async fn handle(
     s: TcpStream,
     stats: &Stats,
     allow_direct: bool,
 ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
-    let mut first = [0; 1];
-    let peeked = tokio::time::timeout(IO_TIMEOUT, s.peek(&mut first))
+    match detect_protocol(&s, stats).await? {
+        Protocol::Socks5 => handle_socks5(s, stats, allow_direct).await,
+        Protocol::MtProto => handle_mtproto(s, stats).await,
+        Protocol::Empty => Ok(()),
+    }
+}
+
+/// Decide which protocol a fresh client is speaking without consuming anything.
+///
+/// A SOCKS5 greeting starts with `0x05` — but so does one in every 256 MTProto
+/// init packets, because the client fills those 64 bytes at random and
+/// `mtproto::is_reserved_init` only avoids `0xef`, `0xee`, `0xdd`, HTTP verbs
+/// and the TLS record header. Deciding on the first byte alone therefore sends
+/// roughly one connection in 256 down the SOCKS5 path, where it dies. From the
+/// outside that looks exactly like Telegram sending messages every other try.
+///
+/// When the first byte is ambiguous, wait briefly: a real SOCKS5 client sends a
+/// short greeting and then blocks on our reply, so only MTProto produces a full
+/// 64-byte init that decodes under our secret.
+async fn detect_protocol(
+    stream: &TcpStream,
+    stats: &Stats,
+) -> Result<Protocol, Box<dyn std::error::Error + Send + Sync>> {
+    let mut probe = [0; INIT_LEN];
+    let peeked = tokio::time::timeout(IO_TIMEOUT, stream.peek(&mut probe[..1]))
         .await
         .map_err(|_| "client protocol detection timeout")??;
     if peeked == 0 {
-        return Ok(());
+        return Ok(Protocol::Empty);
     }
-    if first[0] == 0x05 {
-        handle_socks5(s, stats, allow_direct).await
-    } else {
-        handle_mtproto(s, stats).await
+    if probe[0] != SOCKS5_VERSION {
+        return Ok(Protocol::MtProto);
+    }
+
+    let deadline = tokio::time::Instant::now() + PROTOCOL_PROBE_TIMEOUT;
+    loop {
+        if stream.peek(&mut probe).await? == INIT_LEN {
+            return Ok(
+                if crate::mtproto::parse_client_init(&probe, &stats.secret).is_some() {
+                    Protocol::MtProto
+                } else {
+                    Protocol::Socks5
+                },
+            );
+        }
+        if tokio::time::Instant::now() >= deadline {
+            return Ok(Protocol::Socks5);
+        }
+        tokio::time::sleep(PROTOCOL_PROBE_INTERVAL).await;
     }
 }
 
@@ -397,6 +472,132 @@ async fn tcp_relay(a: TcpStream, b: TcpStream) {
 mod tests {
     use super::*;
     use tokio::io::{AsyncReadExt, AsyncWriteExt};
+    use tokio_tungstenite::tungstenite::handshake::server::{Request, Response};
+    use tokio_tungstenite::tungstenite::Message;
+
+    /// Start the proxy on a kernel-assigned port.
+    ///
+    /// Binding first and reading the port back removes the reserve-then-rebind
+    /// race that a `port 0` helper would otherwise introduce.
+    async fn start_proxy(
+        stats: Arc<Stats>,
+        allow_direct: bool,
+    ) -> (u16, tokio::task::JoinHandle<Result<(), String>>) {
+        let listener = bind(ListenConfig::loopback(0)).await.unwrap();
+        let port = listener.local_addr().unwrap().port();
+        let server = tokio::spawn(async move { serve(stats, listener, allow_direct).await });
+        (port, server)
+    }
+
+    async fn wait_until(label: &str, mut condition: impl FnMut() -> bool) {
+        tokio::time::timeout(Duration::from_secs(5), async {
+            while !condition() {
+                tokio::time::sleep(Duration::from_millis(2)).await;
+            }
+        })
+        .await
+        .unwrap_or_else(|_| panic!("timed out waiting for {label}"));
+    }
+
+    /// Perform a SOCKS5 greeting, send `request`, return the 10-byte reply.
+    async fn socks5_exchange(port: u16, request: &[u8]) -> (TcpStream, [u8; 10]) {
+        let mut client = TcpStream::connect(("127.0.0.1", port)).await.unwrap();
+        client.write_all(&[0x05, 0x01, 0x00]).await.unwrap();
+        let mut greeting = [0; 2];
+        client.read_exact(&mut greeting).await.unwrap();
+        assert_eq!(greeting, [0x05, 0x00]);
+        client.write_all(request).await.unwrap();
+        let mut reply = [0; 10];
+        client.read_exact(&mut reply).await.unwrap();
+        (client, reply)
+    }
+
+    fn socks5_ipv4_request(command: u8, ip: [u8; 4], port: u16) -> Vec<u8> {
+        let mut request = vec![0x05, command, 0x00, 0x01];
+        request.extend_from_slice(&ip);
+        request.extend_from_slice(&port.to_be_bytes());
+        request
+    }
+
+    /// A client init whose first byte is not the SOCKS5 version, so the test
+    /// exercises the unambiguous detection path.
+    fn unambiguous_client_init(secret: &[u8; 16], dc_index: i16) -> [u8; INIT_LEN] {
+        loop {
+            let init = crate::mtproto::test_client_init(secret, dc_index);
+            if init[0] != SOCKS5_VERSION {
+                return init;
+            }
+        }
+    }
+
+    fn ambiguous_client_init(secret: &[u8; 16], dc_index: i16) -> [u8; INIT_LEN] {
+        loop {
+            let init = crate::mtproto::test_client_init(secret, dc_index);
+            if init[0] == SOCKS5_VERSION {
+                return init;
+            }
+        }
+    }
+
+    /// Stand-in for `kwsN.web.telegram.org`: a plaintext WebSocket that behaves
+    /// like an obfuscated2 relay.
+    ///
+    /// Returns the raw init frame it was handed and the plaintext it recovered,
+    /// so a test can assert on what Telegram would really have seen.
+    // The handshake callback's error type is tungstenite's own `ErrorResponse`,
+    // whose size is not ours to change.
+    #[allow(clippy::result_large_err)]
+    async fn mock_relay(
+        listener: TcpListener,
+        response: Vec<u8>,
+    ) -> Result<(Vec<u8>, Vec<u8>), String> {
+        use futures_util::{SinkExt, StreamExt};
+
+        let (tcp, _) = listener.accept().await.map_err(|e| e.to_string())?;
+        // Telegram confirms the `binary` subprotocol the proxy asks for, and
+        // tungstenite refuses a handshake that silently drops it. A mock that
+        // does not answer it would only ever test the failure path.
+        let mut websocket =
+            tokio_tungstenite::accept_hdr_async(tcp, |_: &Request, mut response: Response| {
+                response.headers_mut().insert(
+                    "Sec-WebSocket-Protocol",
+                    "binary".parse().expect("static header value"),
+                );
+                Ok(response)
+            })
+            .await
+            .map_err(|e| e.to_string())?;
+
+        let init = match websocket.next().await {
+            Some(Ok(Message::Binary(data))) => data,
+            other => return Err(format!("expected an init frame, got {other:?}")),
+        };
+        let header: [u8; INIT_LEN] = init
+            .as_slice()
+            .try_into()
+            .map_err(|_| format!("init frame is {} bytes, not {INIT_LEN}", init.len()))?;
+        let mut relay = crate::mtproto::test_relay_peer(&header);
+
+        let mut request = Vec::new();
+        while request.is_empty() {
+            match websocket.next().await {
+                Some(Ok(Message::Binary(mut data))) => {
+                    relay.decrypt(&mut data);
+                    request.extend_from_slice(&data);
+                }
+                Some(Ok(_)) => {}
+                _ => break,
+            }
+        }
+
+        let mut wire = response;
+        relay.encrypt(&mut wire);
+        websocket
+            .send(Message::Binary(wire))
+            .await
+            .map_err(|e| e.to_string())?;
+        Ok((init, request))
+    }
 
     #[tokio::test]
     async fn parses_fragmented_ipv4_socks5_handshake() {
@@ -451,7 +652,8 @@ mod tests {
 
         let stats = Stats::new();
         let server_stats = stats.clone();
-        let server = tokio::spawn(async move { run(server_stats, false, port).await });
+        let server =
+            tokio::spawn(async move { run(server_stats, ListenConfig::loopback(port)).await });
 
         tokio::time::timeout(Duration::from_secs(2), async {
             while !stats.running.load(Ordering::SeqCst) {
@@ -470,6 +672,263 @@ mod tests {
         assert!(!stats.running.load(Ordering::SeqCst));
     }
 
+    #[tokio::test]
+    async fn parses_domain_and_ipv6_socks5_targets() {
+        let domain = "web.telegram.org";
+        let mut domain_payload = vec![u8::try_from(domain.len()).unwrap()];
+        domain_payload.extend_from_slice(domain.as_bytes());
+
+        for (address_type, payload, expected) in
+            [(0x03_u8, domain_payload, domain), (0x04, vec![0; 16], "::")]
+        {
+            let (mut client, mut server) = tokio::io::duplex(256);
+            let task = tokio::spawn(async move { read_socks5_request(&mut server).await.unwrap() });
+
+            client.write_all(&[0x05, 0x01, 0x00]).await.unwrap();
+            let mut greeting = [0; 2];
+            client.read_exact(&mut greeting).await.unwrap();
+
+            let mut request = vec![0x05, 0x01, 0x00, address_type];
+            request.extend_from_slice(&payload);
+            request.extend_from_slice(&443_u16.to_be_bytes());
+            client.write_all(&request).await.unwrap();
+
+            assert_eq!(task.await.unwrap(), (expected.to_owned(), 443));
+        }
+    }
+
+    #[tokio::test]
+    async fn rejects_malformed_and_unsupported_socks5_requests() {
+        // (request after the greeting, expected reply status, why)
+        let cases: [(Vec<u8>, Option<u8>, &str); 5] = [
+            (
+                vec![0x05, 0x03, 0x00, 0x01, 1, 1, 1, 1, 0x01, 0xbb],
+                Some(0x07),
+                "UDP ASSOCIATE is not implemented, so it must be refused rather than half-served",
+            ),
+            (
+                vec![0x05, 0x02, 0x00, 0x01, 1, 1, 1, 1, 0x01, 0xbb],
+                Some(0x07),
+                "BIND is not implemented",
+            ),
+            (
+                vec![0x05, 0x01, 0x00, 0x09, 1, 1, 1, 1, 0x01, 0xbb],
+                Some(0x08),
+                "unknown address type",
+            ),
+            (
+                vec![0x05, 0x01, 0x00, 0x03, 0x00, 0x01, 0xbb],
+                None,
+                "empty domain",
+            ),
+            (
+                vec![0x04, 0x01, 0x00, 0x01, 1, 1, 1, 1, 0x01, 0xbb],
+                None,
+                "wrong protocol version in the request",
+            ),
+        ];
+
+        for (request, expected_status, reason) in cases {
+            let (mut client, mut server) = tokio::io::duplex(256);
+            let task = tokio::spawn(async move { read_socks5_request(&mut server).await.is_err() });
+
+            client.write_all(&[0x05, 0x01, 0x00]).await.unwrap();
+            let mut greeting = [0; 2];
+            client.read_exact(&mut greeting).await.unwrap();
+            client.write_all(&request).await.unwrap();
+
+            if let Some(status) = expected_status {
+                let mut reply = [0; 10];
+                client.read_exact(&mut reply).await.unwrap();
+                assert_eq!(reply[0], 0x05, "{reason}");
+                assert_eq!(reply[1], status, "{reason}");
+            }
+            assert!(task.await.unwrap(), "{reason}");
+        }
+    }
+
+    #[tokio::test]
+    async fn reports_a_busy_port_instead_of_pretending_to_run() {
+        let taken = bind(ListenConfig::loopback(0)).await.unwrap();
+        let port = taken.local_addr().unwrap().port();
+
+        let error = bind(ListenConfig::loopback(port)).await.unwrap_err();
+        assert!(
+            error.contains(&port.to_string()),
+            "the error must name the port that is busy, got {error:?}"
+        );
+    }
+
+    #[tokio::test]
+    async fn mtproto_init_beginning_with_the_socks5_version_is_not_misrouted() {
+        // One init in 256 starts with 0x05. Routing it to the SOCKS5 handler is
+        // what makes Telegram work only every other attempt.
+        let stats = Stats::new();
+        let init = ambiguous_client_init(&stats.secret, 2);
+        let (port, server) = start_proxy(stats.clone(), true).await;
+        let mut client = TcpStream::connect(("127.0.0.1", port)).await.unwrap();
+        client.write_all(&init).await.unwrap();
+
+        // Detection must land on MTProto, which records the data centre. The
+        // SOCKS5 path would instead answer with a handshake reply.
+        wait_until("the MTProto data centre to be recorded", || {
+            stats.last_dc.load(Ordering::Relaxed) == 2
+        })
+        .await;
+
+        stats.stop();
+        let _ = server.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn fragmented_socks5_greeting_is_still_detected() {
+        let stats = Stats::new();
+        let (port, server) = start_proxy(stats.clone(), true).await;
+
+        let mut client = TcpStream::connect(("127.0.0.1", port)).await.unwrap();
+        // Byte-at-a-time, the way a small greeting can actually arrive.
+        for byte in [0x05, 0x01, 0x00] {
+            client.write_all(&[byte]).await.unwrap();
+            tokio::time::sleep(Duration::from_millis(1)).await;
+        }
+        let mut greeting = [0; 2];
+        tokio::time::timeout(Duration::from_secs(5), client.read_exact(&mut greeting))
+            .await
+            .expect("the proxy must answer the greeting")
+            .unwrap();
+        assert_eq!(greeting, [0x05, 0x00]);
+
+        stats.stop();
+        let _ = server.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn network_listener_refuses_non_telegram_destinations() {
+        let stats = Stats::new();
+        let (port, server) = start_proxy(stats.clone(), false).await;
+
+        let (_client, reply) =
+            socks5_exchange(port, &socks5_ipv4_request(0x01, [1, 1, 1, 1], 443)).await;
+        assert_eq!(
+            reply[1], 0x02,
+            "a shared listener must not relay arbitrary destinations"
+        );
+
+        stats.stop();
+        let _ = server.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn loopback_listener_relays_direct_destinations() {
+        let echo = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let echo_port = echo.local_addr().unwrap().port();
+        tokio::spawn(async move {
+            let (mut stream, _) = echo.accept().await.unwrap();
+            let mut buffer = [0; 5];
+            stream.read_exact(&mut buffer).await.unwrap();
+            stream.write_all(&buffer).await.unwrap();
+        });
+
+        let stats = Stats::new();
+        let (port, server) = start_proxy(stats.clone(), true).await;
+
+        let (mut client, reply) =
+            socks5_exchange(port, &socks5_ipv4_request(0x01, [127, 0, 0, 1], echo_port)).await;
+        assert_eq!(reply[1], 0x00);
+
+        client.write_all(b"hello").await.unwrap();
+        let mut echoed = [0; 5];
+        client.read_exact(&mut echoed).await.unwrap();
+        assert_eq!(&echoed, b"hello");
+
+        stats.stop();
+        let _ = server.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn tunnels_mtproto_through_a_websocket_relay() {
+        let relay_listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let relay_port = relay_listener.local_addr().unwrap().port();
+        let response = b"a reply that only Telegram could have sent".to_vec();
+        let relay = tokio::spawn(mock_relay(relay_listener, response.clone()));
+
+        let stats = Stats::new();
+        stats.transport.force_local_route(relay_port);
+        let (port, server) = start_proxy(stats.clone(), false).await;
+
+        let init = unambiguous_client_init(&stats.secret, -4);
+        let mut peer = crate::mtproto::test_client_peer(&init, &stats.secret);
+        let mut client = TcpStream::connect(("127.0.0.1", port)).await.unwrap();
+        client.write_all(&init).await.unwrap();
+
+        let request = b"a request that must reach Telegram unchanged".to_vec();
+        let mut wire = request.clone();
+        peer.encrypt(&mut wire);
+        client.write_all(&wire).await.unwrap();
+
+        let mut received = vec![0; response.len()];
+        tokio::time::timeout(Duration::from_secs(10), client.read_exact(&mut received))
+            .await
+            .expect("the relay's answer must come back through the tunnel")
+            .unwrap();
+        peer.decrypt(&mut received);
+        assert_eq!(
+            received, response,
+            "the client must see Telegram's plaintext"
+        );
+
+        let (init_frame, relayed) = relay.await.unwrap().unwrap();
+        assert_eq!(init_frame.len(), INIT_LEN);
+        assert_ne!(
+            init_frame.as_slice(),
+            init.as_slice(),
+            "the upstream init must be freshly generated, not the client's own"
+        );
+        assert_eq!(
+            relayed, request,
+            "Telegram must receive exactly the client's plaintext"
+        );
+
+        assert_eq!(stats.last_dc.load(Ordering::Relaxed), 4);
+        assert_eq!(
+            stats.last_route.load(Ordering::Relaxed),
+            crate::transport::RouteKind::TelegramIp.ui_code()
+        );
+        assert_eq!(stats.ws_failures.load(Ordering::Relaxed), 0);
+
+        stats.stop();
+        let _ = server.await.unwrap();
+    }
+
+    #[tokio::test]
+    async fn counts_a_failure_when_no_route_answers() {
+        let dead = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let dead_port = dead.local_addr().unwrap().port();
+        drop(dead);
+
+        let stats = Stats::new();
+        stats.transport.force_local_route(dead_port);
+        let (port, server) = start_proxy(stats.clone(), false).await;
+
+        let init = unambiguous_client_init(&stats.secret, 2);
+        let mut client = TcpStream::connect(("127.0.0.1", port)).await.unwrap();
+        client.write_all(&init).await.unwrap();
+
+        wait_until("the failed tunnel to be counted", || {
+            stats.ws_failures.load(Ordering::Relaxed) > 0
+        })
+        .await;
+        assert_eq!(
+            stats.last_route.load(Ordering::Relaxed),
+            0,
+            "a route must not be reported as working when every attempt failed"
+        );
+        assert_eq!(stats.ws.load(Ordering::Relaxed), 0);
+
+        stats.stop();
+        let _ = server.await.unwrap();
+    }
+
     #[tokio::test]
     #[ignore = "requires live Telegram network access"]
     async fn accepts_mtproto_and_builds_live_media_tunnel() {
@@ -479,7 +938,8 @@ mod tests {
 
         let stats = Stats::new();
         let server_stats = stats.clone();
-        let server = tokio::spawn(async move { run(server_stats, false, port).await });
+        let server =
+            tokio::spawn(async move { run(server_stats, ListenConfig::loopback(port)).await });
         while !stats.running.load(Ordering::SeqCst) {
             tokio::task::yield_now().await;
         }

src/transport.rs

@@ -9,6 +9,7 @@ use tokio_tungstenite::{MaybeTlsStream, WebSocketStream};
 const CONNECT_TIMEOUT: Duration = Duration::from_secs(4);
 const FAILURE_BACKOFF_INITIAL: Duration = Duration::from_secs(30);
 const FAILURE_BACKOFF_MAX: Duration = Duration::from_secs(30 * 60);
+const HTTPS_PORT: u16 = 443;
 
 pub type TelegramWebSocket = WebSocketStream<MaybeTlsStream<TcpStream>>;
 
@@ -29,6 +30,34 @@ impl RouteKind {
             Self::CloudflareWorker => 4,
         }
     }
+
+    pub fn from_ui_code(code: u8) -> Option<Self> {
+        match code {
+            1 => Some(Self::TelegramIp),
+            2 => Some(Self::AlternateTelegramIp),
+            3 => Some(Self::SystemDns),
+            4 => Some(Self::CloudflareWorker),
+            _ => None,
+        }
+    }
+
+    /// Human-readable name of the route, shown by both frontends.
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::TelegramIp => "Telegram IP",
+            Self::AlternateTelegramIp => "Запасной Telegram IP",
+            Self::SystemDns => "Системный DNS",
+            Self::CloudflareWorker => "Cloudflare Worker",
+        }
+    }
+}
+
+/// Label for a route code as stored in `Stats::last_route`.
+///
+/// Code `0` means no tunnel has been established yet, which must never be
+/// reported as a working route.
+pub fn route_label(ui_code: u8) -> &'static str {
+    RouteKind::from_ui_code(ui_code).map_or("Маршрут ещё не выбран", RouteKind::label)
 }
 
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
@@ -37,6 +66,24 @@ pub struct Route {
     pub websocket_host: String,
     pub path: String,
     pub kind: RouteKind,
+    /// TCP port to dial. Always 443 for Telegram and for Cloudflare Workers.
+    pub port: u16,
+    /// Wrap the connection in TLS. Always true outside tests.
+    pub secure: bool,
+}
+
+impl Route {
+    /// A production route: TLS on 443.
+    fn https(connect_host: String, websocket_host: String, path: String, kind: RouteKind) -> Self {
+        Self {
+            connect_host,
+            websocket_host,
+            path,
+            kind,
+            port: HTTPS_PORT,
+            secure: true,
+        }
+    }
 }
 
 #[derive(Clone, Debug)]
@@ -66,6 +113,24 @@ struct HealthState {
 pub struct TransportEngine {
     health: Mutex<HealthState>,
     worker_domains: Mutex<Vec<String>>,
+    #[cfg(test)]
+    forced_routes: Mutex<Vec<Route>>,
+}
+
+#[cfg(test)]
+impl TransportEngine {
+    /// Point every data centre at a local plaintext WebSocket server so the
+    /// whole tunnel can be exercised without reaching Telegram.
+    pub(crate) fn force_local_route(&self, port: u16) {
+        *self.forced_routes.lock().unwrap() = vec![Route {
+            connect_host: "127.0.0.1".to_owned(),
+            websocket_host: format!("127.0.0.1:{}", port),
+            path: "/apiws".to_owned(),
+            kind: RouteKind::TelegramIp,
+            port,
+            secure: false,
+        }];
+    }
 }
 
 impl TransportEngine {
@@ -159,17 +224,25 @@ impl TransportEngine {
     }
 
     fn routes_for_key(&self, key: DcKey) -> Vec<Route> {
+        #[cfg(test)]
+        {
+            let forced = self.forced_routes.lock().unwrap();
+            if !forced.is_empty() {
+                return forced.clone();
+            }
+        }
+
         let mut routes = routes_for_dc(key.dc, key.media);
         let Some(destination) = telegram_ips(key.dc).first() else {
             return routes;
         };
         for domain in self.worker_domains.lock().unwrap().iter() {
-            routes.push(Route {
-                connect_host: domain.clone(),
-                websocket_host: domain.clone(),
-                path: format!("/apiws?dst={}&dc={}", destination, key.dc),
-                kind: RouteKind::CloudflareWorker,
-            });
+            routes.push(Route::https(
+                domain.clone(),
+                domain.clone(),
+                format!("/apiws?dst={}&dc={}", destination, key.dc),
+                RouteKind::CloudflareWorker,
+            ));
         }
         routes
     }
@@ -234,23 +307,23 @@ pub fn routes_for_dc(dc: u16, media: bool) -> Vec<Route> {
 
     for websocket_host in &websocket_hosts {
         for (index, ip) in ips.iter().enumerate() {
-            routes.push(Route {
-                connect_host: (*ip).to_owned(),
-                websocket_host: websocket_host.clone(),
-                path: "/apiws".to_owned(),
-                kind: if index == 0 {
+            routes.push(Route::https(
+                (*ip).to_owned(),
+                websocket_host.clone(),
+                "/apiws".to_owned(),
+                if index == 0 {
                     RouteKind::TelegramIp
                 } else {
                     RouteKind::AlternateTelegramIp
                 },
-            });
+            ));
         }
-        routes.push(Route {
-            connect_host: websocket_host.clone(),
-            websocket_host: websocket_host.clone(),
-            path: "/apiws".to_owned(),
-            kind: RouteKind::SystemDns,
-        });
+        routes.push(Route::https(
+            websocket_host.clone(),
+            websocket_host.clone(),
+            "/apiws".to_owned(),
+            RouteKind::SystemDns,
+        ));
     }
     routes
 }
@@ -258,7 +331,7 @@ pub fn routes_for_dc(dc: u16, media: bool) -> Vec<Route> {
 async fn connect_route(route: &Route) -> Result<TelegramWebSocket, String> {
     let tcp = tokio::time::timeout(
         CONNECT_TIMEOUT,
-        TcpStream::connect((route.connect_host.as_str(), 443)),
+        TcpStream::connect((route.connect_host.as_str(), route.port)),
     )
     .await
     .map_err(|_| "TCP connect timeout".to_owned())?
@@ -266,7 +339,8 @@ async fn connect_route(route: &Route) -> Result<TelegramWebSocket, String> {
     tcp.set_nodelay(true)
         .map_err(|error| format!("TCP_NODELAY: {}", error))?;
 
-    let url = format!("wss://{}{}", route.websocket_host, route.path);
+    let scheme = if route.secure { "wss" } else { "ws" };
+    let url = format!("{}://{}{}", scheme, route.websocket_host, route.path);
     let mut request = url
         .as_str()
         .into_client_request()
@@ -278,6 +352,19 @@ async fn connect_route(route: &Route) -> Result<TelegramWebSocket, String> {
             .map_err(|error| format!("WebSocket protocol header: {}", error))?,
     );
 
+    if !route.secure {
+        // Only reachable from tests, which run a local WebSocket server without
+        // a certificate. Production routes are always built by `Route::https`.
+        return tokio::time::timeout(
+            CONNECT_TIMEOUT,
+            tokio_tungstenite::client_async(request, MaybeTlsStream::Plain(tcp)),
+        )
+        .await
+        .map_err(|_| "WebSocket timeout".to_owned())?
+        .map(|(websocket, _)| websocket)
+        .map_err(|error| format!("WebSocket handshake: {}", error));
+    }
+
     // The URI host remains the real Telegram hostname even when the TCP socket
     // is opened to a pinned IP. Native TLS therefore validates Telegram's
     // certificate and sends the correct SNI.
@@ -373,6 +460,202 @@ mod tests {
         );
     }
 
+    #[test]
+    fn every_production_route_is_tls_on_443() {
+        let engine = TransportEngine::new();
+        engine.set_worker_domains(&["fallback.workers.dev".to_owned()]);
+        for dc in [1, 2, 3, 4, 5, 203] {
+            for media in [false, true] {
+                let routes = engine.routes_for_key(DcKey { dc, media });
+                assert!(!routes.is_empty(), "DC{dc} must have at least one route");
+                for route in routes {
+                    assert_eq!(route.port, 443, "{route:?}");
+                    assert!(route.secure, "{route:?}");
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn every_data_center_offers_a_pinned_ip_and_a_dns_route() {
+        for dc in [1, 2, 3, 4, 5, 203] {
+            let routes = routes_for_dc(dc, false);
+            assert!(
+                routes
+                    .iter()
+                    .any(|route| route.kind == RouteKind::TelegramIp),
+                "DC{dc} must keep a pinned-IP route so a poisoned DNS answer is survivable"
+            );
+            assert!(
+                routes
+                    .iter()
+                    .any(|route| route.kind == RouteKind::SystemDns),
+                "DC{dc} must keep a DNS route so a stale pinned IP is survivable"
+            );
+        }
+    }
+
+    #[test]
+    fn backoff_grows_with_each_failure_and_stops_at_the_ceiling() {
+        let engine = TransportEngine::new();
+        let route = routes_for_dc(2, false)[0].clone();
+
+        // 30s doubling per failure, flattening at the 30-minute ceiling.
+        let expected_seconds = [30, 60, 120, 240, 480, 960, 1800, 1800, 1800, 1800];
+        for (index, expected) in expected_seconds.iter().enumerate() {
+            let attempt = u32::try_from(index).unwrap() + 1;
+            let before = Instant::now();
+            engine.record_failure(&route);
+
+            let health = engine.health.lock().unwrap();
+            let entry = health.routes.get(&route).unwrap();
+            assert_eq!(entry.failures, attempt);
+            assert_eq!(
+                entry.retry_at.saturating_duration_since(before).as_secs(),
+                *expected,
+                "attempt {attempt} must wait {expected}s"
+            );
+        }
+        assert_eq!(
+            *expected_seconds.last().unwrap(),
+            FAILURE_BACKOFF_MAX.as_secs(),
+            "the schedule must flatten at the declared ceiling"
+        );
+    }
+
+    #[test]
+    fn success_clears_the_penalty_accumulated_by_failures() {
+        let engine = TransportEngine::new();
+        let key = DcKey {
+            dc: 2,
+            media: false,
+        };
+        let route = routes_for_dc(2, false)[0].clone();
+
+        engine.record_failure(&route);
+        engine.record_failure(&route);
+        assert!(!engine.ordered_candidates(key).contains(&route));
+
+        engine.record_success(key, &route);
+        assert!(!engine.health.lock().unwrap().routes.contains_key(&route));
+        assert_eq!(engine.ordered_candidates(key)[0], route);
+    }
+
+    #[test]
+    fn all_routes_cooling_down_still_yields_the_soonest_retry() {
+        let engine = TransportEngine::new();
+        let key = DcKey {
+            dc: 5,
+            media: false,
+        };
+        let routes = routes_for_dc(5, false);
+
+        // Fail the first route once and the rest twice, so the first one is the
+        // one that becomes available again soonest.
+        engine.record_failure(&routes[0]);
+        for route in &routes[1..] {
+            engine.record_failure(route);
+            engine.record_failure(route);
+        }
+
+        let candidates = engine.ordered_candidates(key);
+        assert_eq!(
+            candidates.len(),
+            1,
+            "a fully cooling table must offer exactly one retry, not give up"
+        );
+        assert_eq!(candidates[0], routes[0]);
+    }
+
+    #[test]
+    fn worker_domains_are_rejected_unless_they_are_plain_hostnames() {
+        let engine = TransportEngine::new();
+        engine.set_worker_domains(&[
+            "https://scheme.workers.dev".to_owned(),
+            "with.a/path".to_owned(),
+            "no-dot".to_owned(),
+            "-leading.workers.dev".to_owned(),
+            "trailing-.workers.dev".to_owned(),
+            "under_score.workers.dev".to_owned(),
+            "spaces here.dev".to_owned(),
+            String::new(),
+            "good.workers.dev".to_owned(),
+        ]);
+
+        let workers: Vec<_> = engine
+            .routes_for_key(DcKey {
+                dc: 2,
+                media: false,
+            })
+            .into_iter()
+            .filter(|route| route.kind == RouteKind::CloudflareWorker)
+            .collect();
+        assert_eq!(workers.len(), 1, "only the valid hostname may survive");
+        assert_eq!(workers[0].websocket_host, "good.workers.dev");
+    }
+
+    #[test]
+    fn worker_domains_are_replaced_not_appended() {
+        let engine = TransportEngine::new();
+        let key = DcKey {
+            dc: 2,
+            media: false,
+        };
+        engine.set_worker_domains(&["first.workers.dev".to_owned()]);
+        engine.set_worker_domains(&["second.workers.dev".to_owned()]);
+
+        let workers: Vec<_> = engine
+            .routes_for_key(key)
+            .into_iter()
+            .filter(|route| route.kind == RouteKind::CloudflareWorker)
+            .collect();
+        assert_eq!(workers.len(), 1);
+        assert_eq!(workers[0].websocket_host, "second.workers.dev");
+    }
+
+    #[test]
+    fn worker_is_the_last_resort() {
+        let engine = TransportEngine::new();
+        engine.set_worker_domains(&["fallback.workers.dev".to_owned()]);
+        let key = DcKey {
+            dc: 2,
+            media: false,
+        };
+        let candidates = engine.ordered_candidates(key);
+        assert_eq!(
+            candidates.last().unwrap().kind,
+            RouteKind::CloudflareWorker,
+            "third-party infrastructure must never be tried before Telegram itself"
+        );
+    }
+
+    #[test]
+    fn route_codes_and_labels_round_trip() {
+        for kind in [
+            RouteKind::TelegramIp,
+            RouteKind::AlternateTelegramIp,
+            RouteKind::SystemDns,
+            RouteKind::CloudflareWorker,
+        ] {
+            assert_eq!(RouteKind::from_ui_code(kind.ui_code()), Some(kind));
+            assert_eq!(route_label(kind.ui_code()), kind.label());
+        }
+    }
+
+    #[test]
+    fn code_zero_is_never_reported_as_a_working_route() {
+        assert_eq!(RouteKind::from_ui_code(0), None);
+        assert_eq!(RouteKind::from_ui_code(9), None);
+        for kind in [
+            RouteKind::TelegramIp,
+            RouteKind::AlternateTelegramIp,
+            RouteKind::SystemDns,
+            RouteKind::CloudflareWorker,
+        ] {
+            assert_ne!(route_label(0), kind.label());
+        }
+    }
+
     #[tokio::test]
     #[ignore = "requires live Telegram network access"]
     async fn connects_to_all_production_data_centers() {