Merge pull request #840 from telemt/flow

Restore single-record TLS-F primary application flight + Fix SYN limiter lifecycle and default burst

CONTRIBUTING.md

@@ -52,6 +52,10 @@ By submitting a PR, you confirm that:
 
 AI-generated code is treated as **draft** and must be validated like any other external contribution.
 
+The problem isn’t AI as a tool, but the dilution of responsibility. If the commit history says "Claude/GPT authored this", then who is accountable for the bug? Claude? GPT? Anthropic? OpenAI? Samuel Altman?
+
+The user who didn’t read the diff? No one? But, in a sensitive system, *"no one"* is an unacceptable maintainer model.
+
 PRs that look like unverified AI dumps WILL be closed
 
 ---

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "telemt"
-version = "3.4.11"
+version = "3.4.18"
 edition = "2024"
 
 [features]
@@ -27,6 +27,7 @@ crc32c = "0.6"
 zeroize = { version = "1.8", features = ["derive"] }
 subtle = "2.6"
 static_assertions = "1.1"
+ml-kem = { version = "0.3.2", default-features = false, features = ["alloc", "zeroize"] }
 
 # Network
 socket2 = { version = "0.6", features = ["all"] }
@@ -90,6 +91,7 @@ tokio-test = "0.4"
 criterion = "0.8"
 proptest = "1.4"
 futures = "0.3"
+tempfile = "3.27.0"
 
 [[bench]]
 name = "crypto_bench"

README.md

@@ -4,13 +4,13 @@
 
 [🇷🇺 README на русском](https://github.com/telemt/telemt/blob/main/README.ru.md)
 
-***Löst Probleme, bevor andere überhaupt wissen, dass sie existieren*** / ***It solves problems before others even realize they exist***
-
 > [!NOTE]
 >
-> Fixed TLS ClientHello is now available in official clients for Desktop / Android / iOS
+> From June 5th, 2026: we are already analyzing the causes of a new wave of "malfunctions"
 > 
-> To work with EE-MTProxy, please update your client!
+> Telegram Clients TLS ClientHello has been banned by JA3 Fingerprint: we are already looking for ways to solve this problem
+>
+> You can try build your client with our Telegram Devlibrary - [tdlib-obf](https://github.com/telemt/tdlib-obf)
 
 <p align="center">
   <a href="https://t.me/telemtrs">

README.ru.md

@@ -1,57 +1,52 @@
 # Telemt — MTProxy на Rust + Tokio
 
-[![Latest Release](https://img.shields.io/github/v/release/telemt/telemt?color=neon)](https://github.com/telemt/telemt/releases/latest) [![Stars](https://img.shields.io/github/stars/telemt/telemt?style=social)](https://github.com/telemt/telemt/stargazers) [![Forks](https://img.shields.io/github/forks/telemt/telemt?style=social)](https://github.com/telemt/telemt/network/members) [![Telegram](https://img.shields.io/badge/Telegram-Chat-24a1de?logo=telegram&logoColor=24a1de)](https://t.me/telemtrs)
-
-***Решает проблемы раньше, чем другие узнают об их существовании***
+[![Latest Release](https://img.shields.io/github/v/release/telemt/telemt?color=neon)](https://github.com/telemt/telemt/releases/latest) [![Stars](https://img.shields.io/github/stars/telemt/telemt?style=social)](https://github.com/telemt/telemt/stargazers) [![Forks](https://img.shields.io/github/forks/telemt/telemt?style=social)](https://github.com/telemt/telemt/network/members)
 
 > [!NOTE]
 >
-> Исправленный TLS ClientHello доступен в Telegram для настольных ПК, Android и iOS.
+> Клиенты Telegram подвергаются блокировке по JA3-отпечатку; мы ищем варианты решения этой проблемы
 > 
-> Пожалуйста, обновите клиентское приложение для работы с EE-MTProxy.
+> Вы можете попробовать собрать свой клиент с нашей Telegram Devlibrary — [tdlib-obf](https://github.com/telemt/tdlib-obf)
 
 <p align="center">
   <a href="https://t.me/telemtrs">
-    <img src="/docs/assets/telegram_button.svg" width="150"/>
+    <img src="https://github.com/user-attachments/assets/30b7e7b9-974a-4e3d-aab6-b58a85de4507" width="240"/>
   </a>
 </p>
 
-**Telemt** — это быстрый, безопасный и функциональный сервер, написанный на Rust. Он полностью реализует официальный алгоритм прокси Telegram и добавляет множество улучшений для продакшена:
+**Telemt** — это быстрый, безопасный и функциональный сервер, написанный на Rust: он полностью реализует официальный алгоритм Telegram прокси и добавляет множество различных улучшений
 
 ## Установка и обновление одной командой
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
 ```
-
 - [Инструкция по быстрому запуску](docs/Quick_start/QUICK_START_GUIDE.ru.md)
-- [Quick Start Guide](docs/Quick_start/QUICK_START_GUIDE.en.md)
 
-Реализация **TLS-fronting** максимально приближена к поведению реального HTTPS-трафика (подробнее - [FAQ](docs/FAQ.ru.md#распознаваемость-для-dpi-и-сканеров)).
+## Функционал
+Наша реализация **TLS-fronting** одна из наиболее глубоко отлаженных, продвинутых и почти поведенчески неотличима от настоящего: мы уверены, что сделали это правильно - [см. доказательства в нашей проверке](docs/FAQ.ru.md#распознаваемость-для-dpi-и-сканеров).
 
-***Middle-End Pool*** оптимизирован для высокой производительности.
+Наша архитектура ***Middle-End Pool*** в стандартных сценариях самая производительная, по сравнению с другими реализациями подключения к Middle-End прокси: не кардинально, но достаточно
 
-- Поддержка всех режимов MTProto proxy:
+- Полная поддержа всех официальных режимов MTProto proxy:
   - Classic;
-  - Secure (префикс `dd`);
-  - Fake TLS (префикс `ee` + SNI fronting);
+  - Secure — с префиксом `dd`;
+  - Fake TLS — с префиксом `ee` + SNI fronting;
 - Защита от replay-атак;
-- Маскировка трафика (перенаправление неизвестных подключений на реальные сайты);
-- Настраиваемые keepalive, таймауты, IPv6 и «быстрый режим»;
+- Опциональная маскировка трафика: перенаправление неизвестных подключений на реальные сайты;
+- Настраиваемые keepalive, таймауты, IPv6 и "быстрый режим";
 - Корректное завершение работы (Ctrl+C);
-- Подробное логирование через `trace` и `debug`.
+- Подробное логирование через `trace` и `debug` с помощью `RUST_LOG`.
 
-# Подробнее о Telemt
-- [FAQ](#faq)
-- [Архитектура](docs/Architecture)
-- [Параметры конфигурационного файла](docs/Config_params)
-- [Сборка](#build)
-- [Установка на BSD](#%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0-%D0%BD%D0%B0-bsd)
-- [Почему Rust?](#why-rust)
+## ЧаВо
+- [Часто задаваемые вопросы](docs/FAQ.ru.md)
 
-## FAQ
-- [FAQ RU](docs/FAQ.ru.md)
-- [FAQ EN](docs/FAQ.en.md)
+# Узнайте больше о Telemt
+- [Наша архитектура](docs/Architecture)
+- [Все конфигурационные параметры](docs/Config_params)
+- [Как собрать Telemt самостоятельно?](#сборка)
+- [Установка на BSD](docs/Quick_start/OPENBSD_QUICK_START_GUIDE.en.md)
+- [Почему Rust?](#почему-rust)
 
 ## Сборка
 ```bash
@@ -63,7 +58,7 @@ cd telemt
 cargo build --release
 
 # В текущем release-профиле используется lto = "fat" для максимальной оптимизации (см. Cargo.toml).
-# На системах с малым объёмом RAM (~1 ГБ) можно переопределить это значение на "thin".
+# На системах с малым объёмом ОЗУ (~1 ГБ) можно переопределить это значение на "thin".
 
 # Перейдите в каталог /bin
 mv ./target/release/telemt /bin
@@ -73,24 +68,19 @@ chmod +x /bin/telemt
 telemt config.toml
 ```
 
-## Установка на BSD
-- Руководство по сборке и настройке на английском языке [OpenBSD Guide (EN)](docs/Quick_start/OPENBSD_QUICK_START_GUIDE.en.md);
-- Пример rc.d скрипта: [contrib/openbsd/telemt.rcd](contrib/openbsd/telemt.rcd);
-- Поддержка sandbox с `pledge(2)` и `unveil(2)` пока не реализована.
-
 ## Почему Rust?
-- Надёжность для долгоживущих процессов;
-- Детерминированное управление ресурсами (RAII);
+- Надёжность при длительной работе и идемпотентное поведение;
+- Детерминированное управление ресурсами — RAII;
 - Отсутствие сборщика мусора;
-- Безопасность памяти;
+- Безопасность памяти и меньше поверхность атаки;
 - Асинхронная архитектура Tokio.
 
 ## Поддержать Telemt
 
-Telemt — это бесплатное программное обеспечение с открытым исходным кодом, разработанное в свободное время.
+Telemt — это бесплатное программное обеспечение с открытым исходным кодом, разрабатываемое в свободное время.
 Если оно оказалось вам полезным, вы можете поддержать дальнейшую разработку.
 
-Принимаемые криптовалюты (BTC, ETH, USDT, 350+ и другие):
+Любая криптовалюта (BTC, ETH, USDT и 350+ других):
 
 <p align="center">
   <a href="https://nowpayments.io/donation?api_key=2bf1afd2-abc2-49f9-a012-f1e715b37223" target="_blank" rel="noreferrer noopener">

docker-compose.yml

@@ -10,12 +10,15 @@ services:
       - "443:443"
       - "127.0.0.1:9090:9090"
       - "127.0.0.1:9091:9091"
-    # Allow caching 'proxy-secret' in read-only container
-    working_dir: /etc/telemt
+    # Working dir uses tmpfs for caching 'proxy-secret' at runtime.
+    # Config is mounted as a directory (not a single file) so the API can
+    # atomically update config.toml via write-temp → rename within the same FS.
+    working_dir: /run/telemt
+    command: ["/etc/telemt/config.toml"]
     volumes:
-      - ./config.toml:/etc/telemt/config.toml:ro
+      - ./config:/etc/telemt:rw
     tmpfs:
-      - /etc/telemt:rw,mode=1777,size=4m
+      - /run/telemt:rw,mode=1777,size=4m
     environment:
       - RUST_LOG=info
     healthcheck:
@@ -24,8 +27,6 @@ services:
       timeout: 5s
       retries: 3
       start_period: 20s
-    # Uncomment this line if you want to use host network for IPv6, but bridge is default and usually better
-    # network_mode: host
     cap_drop:
       - ALL
     cap_add:
@@ -37,3 +38,8 @@ services:
       nofile:
         soft: 65536
         hard: 262144
+    logging:
+      driver: json-file
+      options:
+        max-size: "50m"
+        max-file: "5"

docs/Advanced_settings/TUNING.de.md

@@ -86,6 +86,9 @@ Die unten angegebenen `Default`-Werte sind Code-Defaults (bei fehlendem Schlüss
 | `[[upstreams]].weight` | alle Upstreams | `u16` | nein | `1` | Basisgewicht für weighted-random Auswahl. |
 | `[[upstreams]].enabled` | alle Upstreams | `bool` | nein | `true` | Deaktivierte Einträge werden beim Start ignoriert. |
 | `[[upstreams]].scopes` | alle Upstreams | `String` | nein | `""` | Komma-separierte Scope-Tags für Request-Routing. |
+| `[[upstreams]].ipv4` | alle Upstreams | `Option<bool>` | nein | `auto` | Erlaubt IPv4-DC-Ziele für diesen Upstream. |
+| `[[upstreams]].ipv6` | alle Upstreams | `Option<bool>` | nein | `auto` | Erlaubt IPv6-DC-Ziele für diesen Upstream, inklusive Proxy-Egress unabhängig vom Host-IPv6. |
+| `[[upstreams]].prefer` | alle Upstreams | `Option<4 \| 6>` | nein | effective `[network].prefer` | Pro-Upstream-Präferenz für die DC-Ziel-Adressfamilie. |
 | `interface` | `direct` | `Option<String>` | nein | `null` | Interface-Name (z. B. `eth0`) oder lokale Literal-IP. |
 | `bind_addresses` | `direct` | `Option<Vec<IpAddr>>` | nein | `null` | Explizite Source-IP-Kandidaten (strikter Vorrang vor `interface`). |
 | `address` | `socks4` | `String` | ja | n/a | SOCKS4-Server (`ip:port` oder `host:port`). |

docs/Advanced_settings/TUNING.en.md

@@ -86,6 +86,9 @@ Defaults below are code defaults (used when a key is omitted), not necessarily v
 | `[[upstreams]].weight` | all upstreams | `u16` | no | `1` | Base weight for weighted-random selection. |
 | `[[upstreams]].enabled` | all upstreams | `bool` | no | `true` | Disabled entries are ignored at startup. |
 | `[[upstreams]].scopes` | all upstreams | `String` | no | `""` | Comma-separated scope tags for request-level routing. |
+| `[[upstreams]].ipv4` | all upstreams | `Option<bool>` | no | `auto` | Allow IPv4 DC targets for this upstream. |
+| `[[upstreams]].ipv6` | all upstreams | `Option<bool>` | no | `auto` | Allow IPv6 DC targets for this upstream, including proxy egress independent of host IPv6. |
+| `[[upstreams]].prefer` | all upstreams | `Option<4 \| 6>` | no | effective `[network].prefer` | Per-upstream DC target family preference. |
 | `interface` | `direct` | `Option<String>` | no | `null` | Interface name (e.g. `eth0`) or literal local IP for bind selection. |
 | `bind_addresses` | `direct` | `Option<Vec<IpAddr>>` | no | `null` | Explicit local source IP candidates (strict priority over `interface`). |
 | `address` | `socks4` | `String` | yes | n/a | SOCKS4 server endpoint (`ip:port` or `host:port`). |

docs/Advanced_settings/TUNING.ru.md

@@ -86,6 +86,9 @@
 | `[[upstreams]].weight` | все upstream | `u16` | нет | `1` | Базовый вес в weighted-random выборе. |
 | `[[upstreams]].enabled` | все upstream | `bool` | нет | `true` | Выключенные записи игнорируются на старте. |
 | `[[upstreams]].scopes` | все upstream | `String` | нет | `""` | Список scope-токенов через запятую для маршрутизации. |
+| `[[upstreams]].ipv4` | все upstream | `Option<bool>` | нет | `auto` | Разрешает IPv4 DC-targets для этого upstream. |
+| `[[upstreams]].ipv6` | все upstream | `Option<bool>` | нет | `auto` | Разрешает IPv6 DC-targets для этого upstream, включая proxy egress независимо от IPv6 на хосте. |
+| `[[upstreams]].prefer` | все upstream | `Option<4 \| 6>` | нет | эффективный `[network].prefer` | Предпочтительное семейство DC-target для конкретного upstream. |
 | `interface` | `direct` | `Option<String>` | нет | `null` | Имя интерфейса (например `eth0`) или literal локальный IP. |
 | `bind_addresses` | `direct` | `Option<Vec<IpAddr>>` | нет | `null` | Явные кандидаты source IP (имеют приоритет над `interface`). |
 | `address` | `socks4` | `String` | да | n/a | Адрес SOCKS4 сервера (`ip:port` или `host:port`). |

docs/Architecture/API/API.md

@@ -103,14 +103,19 @@ Notes:
 | `GET` | `/v1/runtime/me-selftest` | none | `200` | `RuntimeMeSelftestData` |
 | `GET` | `/v1/runtime/connections/summary` | none | `200` | `RuntimeEdgeConnectionsSummaryData` |
 | `GET` | `/v1/runtime/events/recent` | none | `200` | `RuntimeEdgeEventsData` |
+| `GET` | `/v1/runtime/tls-fingerprints` | optional `limit=1..1000` | `200` | `RuntimeEdgeTlsFingerprintsData` |
 | `GET` | `/v1/stats/users/active-ips` | none | `200` | `UserActiveIps[]` |
 | `GET` | `/v1/stats/users` | none | `200` | `UserInfo[]` |
+| `GET` | `/v1/config` | none | `200` | `ConfigData` |
+| `PATCH` | `/v1/config` | sparse JSON object | `200` | `PatchConfigResponse` |
 | `GET` | `/v1/users` | none | `200` | `UserInfo[]` |
 | `POST` | `/v1/users` | `CreateUserRequest` | `201` or `202` | `CreateUserResponse` |
 | `GET` | `/v1/users/{username}` | none | `200` | `UserInfo` |
 | `PATCH` | `/v1/users/{username}` | `PatchUserRequest` | `200` or `202` | `UserInfo` |
 | `DELETE` | `/v1/users/{username}` | none | `200` or `202` | `DeleteUserResponse` |
 | `POST` | `/v1/users/{username}/rotate-secret` | `RotateSecretRequest` or empty body | `200` or `202` | `CreateUserResponse` |
+| `POST` | `/v1/users/{username}/enable` | empty body | `200` or `202` | `UserInfo` |
+| `POST` | `/v1/users/{username}/disable` | empty body | `200` or `202` | `UserInfo` |
 | `POST` | `/v1/users/{username}/reset-quota` | empty body | `200` | `ResetUserQuotaResponse` |
 
 ## Endpoint Behavior
@@ -140,12 +145,16 @@ Notes:
 | `GET /v1/runtime/events/recent` | Returns recent API/runtime event records with optional `limit` query. |
 | `GET /v1/stats/users/active-ips` | Returns users that currently have non-empty active source-IP lists. |
 | `GET /v1/stats/users` | Alias of `GET /v1/users`; returns disk-first user views with runtime lag flag. |
+| `GET /v1/config` | Returns the current editable config sections as JSON (no `access.*`) plus the revision. |
+| `PATCH /v1/config` | Applies a sparse patch to editable config sections; validates, writes, and reports restart impact. |
 | `GET /v1/users` | Returns disk-first user views sorted by username. |
 | `POST /v1/users` | Creates a user and returns the effective user view plus secret. |
 | `GET /v1/users/{username}` | Returns one disk-first user view or `404` when absent. |
 | `PATCH /v1/users/{username}` | Updates selected per-user fields with JSON Merge Patch semantics. |
 | `DELETE /v1/users/{username}` | Deletes one user and related per-user access-map entries. |
 | `POST /v1/users/{username}/rotate-secret` | Rotates one user's secret and returns the effective secret. |
+| `POST /v1/users/{username}/enable` | Enables one user, removing any disabled override from config. |
+| `POST /v1/users/{username}/disable` | Disables one user and closes active runtime sessions for that user. |
 | `POST /v1/users/{username}/reset-quota` | Resets one user's runtime quota counter and persists quota state. |
 
 ## Common Error Codes
@@ -153,6 +162,8 @@ Notes:
 | HTTP | `error.code` | Trigger |
 | --- | --- | --- |
 | `400` | `bad_request` | Invalid JSON, validation failures, malformed request body. |
+| `400` | `access_not_editable` | `PATCH /v1/config` body contains an `access` key (managed via users API). |
+| `400` | `section_not_editable` | `PATCH /v1/config` body contains `server`, `network`, or an unknown top-level key. |
 | `401` | `unauthorized` | Missing/invalid `Authorization` when `auth_header` is configured. |
 | `403` | `forbidden` | Source IP is not allowed by whitelist. |
 | `403` | `read_only` | Mutating endpoint called while `read_only=true`. |
@@ -172,9 +183,12 @@ Notes:
 | Path matching | Exact match on `req.uri().path()`. Query string does not affect route matching. |
 | Trailing slash | Trimmed for route matching when path length is greater than 1. Example: `/v1/users/` matches `/v1/users`. |
 | Username route with extra slash | `/v1/users/{username}/...` is not treated as user route and returns `404`. |
+| `DELETE /v1/config` (or any method not in `GET`, `PATCH`) | `405 method_not_allowed` with `Allow: GET, PATCH`. |
 | `PUT /v1/users/{username}` | `405 method_not_allowed`. |
 | `POST /v1/users/{username}` | `404 not_found`. |
 | `POST /v1/users/{username}/rotate-secret/` | Trailing slash is trimmed and the route matches `rotate-secret`. |
+| `POST /v1/users/{username}/enable/` | Trailing slash is trimmed and the route matches `enable`. |
+| `POST /v1/users/{username}/disable/` | Trailing slash is trimmed and the route matches `disable`. |
 | `POST /v1/users/{username}/reset-quota/` | Trailing slash is trimmed and the route matches `reset-quota`. |
 
 ## Body and JSON Semantics
@@ -205,9 +219,10 @@ Notes:
 | `max_tcp_conns` | `usize` | no | Per-user concurrent TCP limit. |
 | `expiration_rfc3339` | `string` | no | RFC3339 expiration timestamp. |
 | `data_quota_bytes` | `u64` | no | Per-user traffic quota. |
-| `rate_limit_up_bps` | `u64` | no | Per-user upload rate limit in bytes per second. |
-| `rate_limit_down_bps` | `u64` | no | Per-user download rate limit in bytes per second. |
+| `rate_limit_up_bps` | `u64` | no | Per-user upload rate limit in bits per second. |
+| `rate_limit_down_bps` | `u64` | no | Per-user download rate limit in bits per second. |
 | `max_unique_ips` | `usize` | no | Per-user unique source IP limit. |
+| `enabled` | `bool` | no | User enable flag. Missing means enabled. `false` persists a disabled override. |
 
 ### `PatchUserRequest`
 | Field | Type | Required | Description |
@@ -217,9 +232,10 @@ Notes:
 | `max_tcp_conns` | `usize|null` | no | Per-user concurrent TCP limit; `null` removes the per-user override. |
 | `expiration_rfc3339` | `string|null` | no | RFC3339 expiration timestamp; `null` removes the expiration. |
 | `data_quota_bytes` | `u64|null` | no | Per-user traffic quota; `null` removes the per-user quota. |
-| `rate_limit_up_bps` | `u64|null` | no | Per-user upload rate limit in bytes per second; `null` removes the upload direction limit. |
-| `rate_limit_down_bps` | `u64|null` | no | Per-user download rate limit in bytes per second; `null` removes the download direction limit. |
+| `rate_limit_up_bps` | `u64|null` | no | Per-user upload rate limit in bits per second; `null` removes the upload direction limit. |
+| `rate_limit_down_bps` | `u64|null` | no | Per-user download rate limit in bits per second; `null` removes the download direction limit. |
 | `max_unique_ips` | `usize|null` | no | Per-user unique source IP limit; `null` removes the per-user override. |
+| `enabled` | `bool|null` | no | `false` disables the user. `true` or `null` removes the disabled override, so the user is enabled. |
 
 ### `access.user_source_deny` via API
 - In current API surface, per-user deny-list is **not** exposed as a dedicated field in `CreateUserRequest` / `PatchUserRequest`.
@@ -236,6 +252,20 @@ alice = ["203.0.113.0/24", "2001:db8:abcd::/48"]
 bob = ["198.51.100.42/32"]
 ```
 
+### `PatchConfigRequest`
+
+A sparse JSON object containing only the top-level config sections to modify. Each key must be one of the editable sections (`general`, `timeouts`, `censorship`, `upstreams`, `show_link`, `dc_overrides`). Tables within a section are deep-merged field-by-field into the existing config; arrays and scalar values replace the existing value wholesale. Untouched sections and file comments are preserved.
+
+**Rejected keys:**
+- `access` → `400 access_not_editable` (users/secrets are managed via `POST/PATCH /v1/users`).
+- `server`, `network`, or any unknown top-level key → `400 section_not_editable`.
+- An object with no editable keys → `400 bad_request` (empty patch).
+
+Example — patch only the SNI domain:
+```json
+{"censorship": {"tls_domain": "front.example.com"}}
+```
+
 ### `RotateSecretRequest`
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
@@ -245,6 +275,31 @@ An empty request body is accepted and generates a new secret automatically.
 
 ## Response Data Contracts
 
+### `ConfigData`
+
+Returned by `GET /v1/config` as the envelope `data`. The fields are exactly the editable TOML sections. The current revision is returned in the envelope `revision` field (same value as `config_hash` in `SystemInfoData`), **not** inside `data`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `general` | `object?` | `[general]` section, if present in config. |
+| `timeouts` | `object?` | `[timeouts]` section, if present. |
+| `censorship` | `object?` | `[censorship]` section, if present. |
+| `upstreams` | `object?` | `[upstreams]` section, if present. |
+| `show_link` | `object?` | `[show_link]` section, if present. |
+| `dc_overrides` | `object?` | `[dc_overrides]` section, if present. |
+
+Sections absent from the config file are absent from the response (not `null`). Only the editable sections above are returned; `access` (users/secrets), `server` (carries the API `auth_header` and per-node identity), and `network` (per-node addresses) are always excluded.
+
+### `PatchConfigResponse`
+
+Returned by `PATCH /v1/config` on success (`200`).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `revision` | `string` | SHA-256 hex of the config file after the patch was written. |
+| `restart_required` | `bool` | `true` when one or more changed fields require a process restart to take effect. Hot-reloadable fields (e.g. `general.log_level`) are applied automatically by the config file watcher; restart-required fields (e.g. any `censorship.*`, `timeouts.*`, `upstreams`, or `general.modes` change) are written to disk but only take effect after the Telemt process is restarted. The caller is responsible for triggering a restart when this flag is `true`. |
+| `changed` | `string[]` | Top-level section names that differed between the old and new config (e.g. `["censorship"]`). |
+
 ### `HealthData`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -807,6 +862,43 @@ An empty request body is accepted and generates a new secret automatically.
 | `event_type` | `string` | Event kind identifier. |
 | `context` | `string` | Context text (truncated to implementation-defined max length). |
 
+### `RuntimeEdgeTlsFingerprintsData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Endpoint availability under `runtime_edge_enabled`. |
+| `reason` | `string?` | `feature_disabled` when endpoint is disabled. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeEdgeTlsFingerprintsPayload?` | Null when unavailable. |
+
+#### `RuntimeEdgeTlsFingerprintsPayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `limit` | `usize` | Effective Top-N row count. |
+| `retention_secs` | `u64` | In-memory retention window, derived from `general.beobachten_minutes`. |
+| `capacity` | `usize` | Maximum retained fingerprint buckets. |
+| `dropped_total` | `u64` | Buckets dropped because the collector was full. |
+| `parse_error_total` | `u64` | Complete ClientHello records that could not be fingerprinted. |
+| `by_fingerprint` | `RuntimeEdgeTlsFingerprintRow[]` | Global JA3/JA4 leaderboard. |
+| `by_ip` | `RuntimeEdgeTlsFingerprintRow[]` | Source-IP scoped leaderboard. |
+| `by_cidr` | `RuntimeEdgeTlsFingerprintRow[]` | Source CIDR scoped leaderboard (`/24` for IPv4, `/56` for IPv6). |
+| `by_user` | `RuntimeEdgeTlsFingerprintRow[]` | Authenticated user scoped leaderboard. |
+
+#### `RuntimeEdgeTlsFingerprintRow`
+| Field | Type | Description |
+| --- | --- | --- |
+| `scope` | `string?` | IP, CIDR, or username; absent in `by_fingerprint`. |
+| `ja3` | `string` | JA3 MD5 hash. |
+| `ja3_raw` | `string` | Raw JA3 field string. |
+| `ja4` | `string` | JA4 TLS client fingerprint. |
+| `ja4_raw` | `string` | Raw JA4 material used for the hashed parts. |
+| `total` | `u64` | Complete ClientHello observations for this bucket. |
+| `auth_success` | `u64` | TLS-authenticated observations for this bucket. |
+| `bad_or_probe` | `u64` | Complete ClientHello observations later classified as bad/probe. |
+| `first_seen_epoch_secs` | `u64` | First observation timestamp. |
+| `last_seen_epoch_secs` | `u64` | Last observation timestamp. |
+
+JA3 follows the Salesforce ClientHello field order. JA4 follows the FoxIO TLS-client `a_b_c` format; GREASE values are excluded and no high-cardinality Prometheus labels are emitted for fingerprints.
+
 ### `ZeroAllData`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -1165,13 +1257,14 @@ An empty request body is accepted and generates a new secret automatically.
 | Field | Type | Description |
 | --- | --- | --- |
 | `username` | `string` | Username. |
+| `enabled` | `bool` | Effective user enable flag. Missing config entry is reported as `true`. |
 | `in_runtime` | `bool` | Whether current runtime config already contains this user. |
 | `user_ad_tag` | `string?` | Optional ad tag (32 hex chars). |
 | `max_tcp_conns` | `usize?` | Optional max concurrent TCP limit. |
 | `expiration_rfc3339` | `string?` | Optional expiration timestamp. |
 | `data_quota_bytes` | `u64?` | Optional data quota. |
-| `rate_limit_up_bps` | `u64?` | Optional upload rate limit in bytes per second. |
-| `rate_limit_down_bps` | `u64?` | Optional download rate limit in bytes per second. |
+| `rate_limit_up_bps` | `u64?` | Optional upload rate limit in bits per second. |
+| `rate_limit_down_bps` | `u64?` | Optional download rate limit in bits per second. |
 | `max_unique_ips` | `usize?` | Optional unique IP limit. |
 | `current_connections` | `u64` | Current live connections. |
 | `active_unique_ips` | `usize` | Current active unique source IPs. |
@@ -1232,13 +1325,106 @@ Link generation uses active config and enabled modes:
 | `used_bytes` | `u64` | Current used bytes after reset; always `0` on success. |
 | `last_reset_epoch_secs` | `u64` | Unix timestamp of the reset operation. |
 
+## Config Endpoints
+
+### `GET /v1/config`
+
+Returns the current editable config sections as TOML-shaped JSON, plus the current revision. The `access` section (users and secrets) is always stripped and never appears in the response.
+
+**Auth:** requires `Authorization` header when `auth_header` is configured (same as all other endpoints).
+
+**Success `200` response body** (`data` field of the standard envelope):
+```json
+{
+  "revision": "<sha256-hex>",
+  "censorship": {"tls_domain": "front.example.com"},
+  "general": {"log_level": "normal"}
+}
+```
+
+Top-level sections absent from the config file are absent from the response. Only `GET` and `PATCH` are accepted; any other method returns `405 Method Not Allowed` with `Allow: GET, PATCH`.
+
+---
+
+### `PATCH /v1/config`
+
+Applies a sparse patch to the editable config sections. The merged config is fully validated before writing; if validation fails the file is not modified.
+
+**Auth:** requires `Authorization` header when `auth_header` is configured.
+
+**Headers:**
+
+| Header | Required | Description |
+| --- | --- | --- |
+| `Authorization` | when configured | Same token as all other endpoints. |
+| `Content-Type: application/json` | recommended | Not enforced, but body must be valid JSON. |
+| `If-Match: <revision>` | no | Optimistic concurrency. `<revision>` is the `revision` value from `GET /v1/config` or `config_hash` from `GET /v1/system/info`. If supplied and it does not match the current on-disk revision, returns `409 revision_conflict`. If omitted, the patch applies unconditionally. |
+
+**Editable sections:** `general`, `timeouts`, `censorship`, `upstreams`, `show_link`, `dc_overrides`.
+
+**Rejected keys and their error codes:**
+
+| Key | HTTP | `error.code` |
+| --- | --- | --- |
+| `access` | `400` | `access_not_editable` |
+| `server`, `network`, or any unknown key | `400` | `section_not_editable` |
+| Object with no editable key | `400` | `bad_request` |
+
+**Merge semantics:** tables are deep-merged field-by-field; arrays and scalar values replace the existing value wholesale. File comments and untouched sections are preserved.
+
+**Validation:** the merged config is deserialized into the full `ProxyConfig` type and validated before writing. Failures return `400` with a descriptive message; the file is not modified.
+
+**Read-only mode:** returns `403 read_only` when the API runs with `read_only = true`.
+
+**Success `200` response body** (`data` field of the standard envelope):
+```json
+{
+  "revision": "<new-sha256-hex>",
+  "restart_required": true,
+  "changed": ["censorship"]
+}
+```
+
+- `revision` — SHA-256 hex of the config file after the write.
+- `restart_required` — `true` when the change affects a field that Telemt cannot hot-reload (e.g. `censorship.*`, `timeouts.*`, `upstreams`, `general.modes`). Hot-reloadable fields (e.g. `general.log_level`) are applied automatically by the config file watcher. Restart-required fields are written to disk but only take effect after the Telemt process is restarted; the caller is responsible for triggering the restart.
+- `changed` — list of top-level section names that differed.
+
+**Status codes:**
+
+| HTTP | `error.code` | Condition |
+| --- | --- | --- |
+| `200` | — | Patch applied successfully. |
+| `400` | `bad_request` | Invalid JSON, empty patch, or config validation/deserialization failure. |
+| `400` | `access_not_editable` | Patch contains an `access` key. |
+| `400` | `section_not_editable` | Patch contains `server`, `network`, or an unknown top-level key. |
+| `401` | `unauthorized` | Missing or invalid `Authorization` header. |
+| `403` | `read_only` | API is in read-only mode. |
+| `405` | `method_not_allowed` | Method other than `GET` or `PATCH` used on `/v1/config`. |
+| `409` | `revision_conflict` | `If-Match` header supplied but does not match current revision. |
+| `500` | `internal_error` | I/O or serialization failure. |
+
+**curl example:**
+```bash
+# get current revision
+curl -s -H "Authorization: <token>" http://127.0.0.1:<api>/v1/system/info | jq -r .config_hash
+
+# patch the SNI domain with optimistic concurrency
+curl -s -X PATCH -H "Authorization: <token>" -H "If-Match: <revision>" \
+  -H "Content-Type: application/json" \
+  -d '{"censorship":{"tls_domain":"front.example.com"}}' \
+  http://127.0.0.1:<api>/v1/config
+```
+
 ## Mutation Semantics
 
 | Endpoint | Notes |
 | --- | --- |
+| `PATCH /v1/config` | Deep-merges the patch into editable config sections (tables merged per-field; arrays/scalars replaced wholesale). Validates the merged result before writing. Writes only the touched sections via atomic `tmp + rename`. Returns the new revision and which sections changed. |
 | `POST /v1/users` | Creates user, validates config, then atomically updates only affected `access.*` TOML tables (`access.users` always, plus optional per-user tables present in request). |
 | `PATCH /v1/users/{username}` | Partial update of provided fields only. Missing fields remain unchanged; explicit `null` removes optional per-user entries. The write path updates only affected `access.*` TOML tables. |
 | `POST /v1/users/{username}/rotate-secret` | Replaces the user's secret with a provided valid 32-hex value or a generated value, then returns the effective secret in `CreateUserResponse`. |
+| `POST /v1/users/{username}/enable` | Enables the user idempotently by removing the `access.user_enabled[username]` override and updating the runtime admission state immediately. |
+| `POST /v1/users/{username}/disable` | Disables the user idempotently by writing `access.user_enabled[username] = false`, updating runtime admission immediately, and cancelling active sessions for that username. |
 | `POST /v1/users/{username}/reset-quota` | Resets the runtime quota counter for the route username, persists quota state to `general.quota_state_path`, and does not modify user config. |
 | `DELETE /v1/users/{username}` | Deletes only specified user, removes this user from related optional `access.user_*` maps, blocks last-user deletion, and atomically updates only related `access.*` TOML tables. |
 
@@ -1282,6 +1468,7 @@ Additional runtime endpoint behavior:
 | `/v1/runtime/me-selftest` | No | ME pool unavailable => `enabled=false`, `reason=source_unavailable` | `enabled=true`, full payload |
 | `/v1/runtime/connections/summary` | `runtime_edge_enabled=false` => `enabled=false`, `reason=feature_disabled` | Recompute lock contention with no cache entry => `enabled=true`, `reason=source_unavailable` | `enabled=true`, full payload |
 | `/v1/runtime/events/recent` | `runtime_edge_enabled=false` => `enabled=false`, `reason=feature_disabled` | Not used in current implementation | `enabled=true`, full payload |
+| `/v1/runtime/tls-fingerprints` | `runtime_edge_enabled=false` => `enabled=false`, `reason=feature_disabled` | Not used in current implementation | `enabled=true`, full payload |
 
 ## ME Fallback Behavior Exposed Via API
 

docs/Architecture/Fronting-splitting/TLS_JA3_JA4_ANALYSIS.ru.md

@@ -0,0 +1,507 @@
+# JA3 и JA4 анализ в Telemt
+
+Этот документ описывает, как использовать JA3/JA4 telemetry в Telemt для диагностики блокировок, которые происходят на основе TLS ClientHello, особенно JA4 TLS client fingerprint.
+
+Цель документа практическая: помочь оператору понять, какой клиентский TLS-отпечаток реально доходит до Telemt, как он распределён по IP/CIDR/пользователям, и как отделить JA4-based фильтрацию от блокировки по IP, SNI, домену, server flight или активному сканированию.
+
+## Коротко
+
+JA3 и JA4 описывают форму TLS ClientHello. ClientHello отправляет клиент, поэтому JA3/JA4 в этом контексте являются fingerprint'ами клиентской TLS-реализации, а не Telemt как сервера.
+
+Telemt собирает JA3/JA4 только из уже прочитанного полного ClientHello:
+
+- без packet capture;
+- без MITM;
+- без расшифровки TLS;
+- без дополнительных сетевых чтений;
+- без Prometheus labels с высокой кардинальностью;
+- с ограниченным in-memory TTL/cap collector.
+
+Собранные данные доступны:
+
+- через API: `GET /v1/runtime/tls-fingerprints`;
+- через `/beobachten`, если `general.beobachten=true`.
+
+Основная польза:
+
+- увидеть, какие JA4 реально используют клиенты;
+- понять, один ли fingerprint страдает у всех пользователей;
+- отделить проблему клиента от проблемы IP/ASN/домена;
+- увидеть, доходят ли проблемные соединения до Telemt вообще;
+- сравнить successful TLS-auth и bad/probe поток для одного fingerprint;
+- собрать evidence для последующего изменения клиента, маршрута или deployment-профиля.
+
+## Что такое JA3
+
+JA3 - старый и широко совместимый способ получить hash от TLS ClientHello.
+
+JA3 строится из ClientHello fields:
+
+```text
+SSLVersion,Cipher,SSLExtension,EllipticCurve,EllipticCurvePointFormat
+```
+
+Значения внутри полей записываются в порядке, в котором они пришли в ClientHello. GREASE values исключаются. Итоговая строка хэшируется MD5, поэтому в API есть два поля:
+
+- `ja3` - MD5 hash;
+- `ja3_raw` - исходная строка, из которой получен hash.
+
+Практическое значение JA3 в 2026 году ограничено тем, что современные TLS-клиенты и браузерные стеки могут менять порядок extensions. Поэтому JA3 полезен как совместимый исторический сигнал, но для диагностики современных блокировок обычно важнее JA4.
+
+## Что такое JA4
+
+JA4 TLS client fingerprint - более структурированный fingerprint ClientHello.
+
+JA4 в Telemt считается для TLS-over-TCP ClientHello и имеет форму:
+
+```text
+t<version><sni_marker><cipher_count><extension_count><alpn_marker>_<cipher_hash>_<extension_hash>
+```
+
+Пример:
+
+```text
+t13d1516h2_8daaf6152771_e5627efa2ab1
+```
+
+Части JA4:
+
+| Часть | Смысл |
+| --- | --- |
+| `t` | TLS over TCP. Telemt сейчас не считает JA4 для QUIC/DTLS. |
+| `13`, `12`, `11`, `10` | TLS version, предпочтительно из `supported_versions`. |
+| `d` / `i` | Есть SNI domain (`d`) или SNI отсутствует (`i`). |
+| `15` | Количество cipher suites без GREASE, capped до `99`. |
+| `16` | Количество extensions без GREASE, capped до `99`. |
+| `h2`, `h1`, `00` | ALPN marker: первый и последний символ первого ALPN value или `00`. |
+| `cipher_hash` | SHA256 от отсортированного списка ciphers, первые 12 hex chars. |
+| `extension_hash` | SHA256 от отсортированных extensions плюс signature algorithms, первые 12 hex chars. |
+
+Важное отличие JA4 от JA3: JA4 нормализует часть полей, поэтому он устойчивее к простому изменению порядка extensions. Это делает JA4 удобным для фильтров и одновременно полезным для диагностики таких фильтров.
+
+## Где Telemt видит ClientHello
+
+В TLS/FakeTLS режиме Telemt получает первые bytes соединения и определяет, похоже ли оно на TLS handshake. Если record является полным ClientHello и проходит bounds checks, Telemt один раз парсит его для JA3/JA4.
+
+Дальше возможны три исхода:
+
+1. **Успешный MTProxy/FakeTLS клиент**
+   - Telemt принимает TLS-auth;
+   - fingerprint записывается в global/IP/CIDR scopes;
+   - после успешной TLS-auth Telemt добавляет user scope.
+
+2. **Bad client или probe**
+   - ClientHello полный, но auth не проходит;
+   - fingerprint записывается в global/IP/CIDR scopes;
+   - user scope не записывается;
+   - `bad_or_probe` увеличивается.
+
+3. **Неполный или обрезанный ClientHello**
+   - fingerprint не считается;
+   - такие случаи остаются в существующих bad-class counters.
+
+Если фильтр режет трафик до того, как TCP connection или ClientHello дошли до процесса Telemt, Telemt не увидит этот fingerprint. Это важнейшее диагностическое отличие: отсутствие fingerprint'а во время жалобы пользователя часто означает блокировку до приложения, а не проблему внутри Telemt.
+
+## Включение сбора
+
+Collector включается, когда включён хотя бы один потребитель:
+
+```toml
+[general]
+beobachten = true
+beobachten_minutes = 10
+```
+
+или:
+
+```toml
+[server.api]
+runtime_edge_enabled = true
+runtime_edge_top_n = 50
+```
+
+Практически:
+
+- для файлового/metrics endpoint анализа достаточно `general.beobachten=true`;
+- для API snapshot нужен `server.api.runtime_edge_enabled=true`;
+- `general.beobachten_minutes` задаёт retention window для fingerprint buckets;
+- `server.api.runtime_edge_top_n` задаёт default Top-N размер API snapshot.
+
+## API snapshot
+
+Endpoint:
+
+```bash
+curl -s http://127.0.0.1:9091/v1/runtime/tls-fingerprints
+```
+
+С явным лимитом:
+
+```bash
+curl -s 'http://127.0.0.1:9091/v1/runtime/tls-fingerprints?limit=100'
+```
+
+Если API защищён header'ом:
+
+```bash
+curl -s \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  'http://127.0.0.1:9091/v1/runtime/tls-fingerprints?limit=100'
+```
+
+Если `runtime_edge_enabled=false`, endpoint возвращает payload с:
+
+```json
+{
+  "enabled": false,
+  "reason": "feature_disabled"
+}
+```
+
+### Структура payload
+
+Основные поля:
+
+| Поле | Смысл |
+| --- | --- |
+| `retention_secs` | Текущее TTL окно collector'а. |
+| `capacity` | Максимум retained buckets. |
+| `dropped_total` | Сколько новых buckets отброшено из-за cap. |
+| `parse_error_total` | Сколько полных ClientHello не удалось распарсить. |
+| `by_fingerprint` | Top fingerprints глобально. |
+| `by_ip` | Top fingerprints по exact source IP. |
+| `by_cidr` | Top fingerprints по source prefix: IPv4 `/24`, IPv6 `/56`. |
+| `by_user` | Top fingerprints по authenticated user. |
+
+Строка snapshot:
+
+| Поле | Смысл |
+| --- | --- |
+| `scope` | IP, CIDR или username. В `by_fingerprint` отсутствует. |
+| `ja3` | JA3 hash. |
+| `ja3_raw` | Raw JA3 string. |
+| `ja4` | JA4 TLS client fingerprint. |
+| `ja4_raw` | Raw JA4 material. |
+| `total` | Сколько полных ClientHello попало в этот bucket. |
+| `auth_success` | Сколько из них успешно прошли TLS-auth. |
+| `bad_or_probe` | Сколько были bad/probe после полного ClientHello. |
+| `first_seen_epoch_secs` | Первый timestamp bucket'а. |
+| `last_seen_epoch_secs` | Последний timestamp bucket'а. |
+
+### Быстрый просмотр через jq
+
+Top JA4 глобально:
+
+```bash
+curl -s http://127.0.0.1:9091/v1/runtime/tls-fingerprints \
+  | jq -r '.data.data.by_fingerprint[] | [.ja4, .total, .auth_success, .bad_or_probe] | @tsv'
+```
+
+Top JA4 по пользователям:
+
+```bash
+curl -s http://127.0.0.1:9091/v1/runtime/tls-fingerprints?limit=100 \
+  | jq -r '.data.data.by_user[] | [.scope, .ja4, .total, .auth_success] | @tsv'
+```
+
+Top JA4 по CIDR:
+
+```bash
+curl -s http://127.0.0.1:9091/v1/runtime/tls-fingerprints?limit=100 \
+  | jq -r '.data.data.by_cidr[] | [.scope, .ja4, .total, .auth_success, .bad_or_probe] | @tsv'
+```
+
+Ошибки парсинга и drops:
+
+```bash
+curl -s http://127.0.0.1:9091/v1/runtime/tls-fingerprints \
+  | jq '.data.data | {retention_secs, capacity, dropped_total, parse_error_total}'
+```
+
+## Beobachten output
+
+Если включён endpoint metrics, `/beobachten` содержит обычные forensic buckets и, когда есть данные, append-only секцию TLS fingerprints:
+
+```bash
+curl -s http://127.0.0.1:9090/beobachten
+```
+
+Фрагмент:
+
+```text
+[tls_fingerprints]
+retention_secs=600 capacity=65536 dropped_total=0 parse_error_total=0
+[tls_fingerprints.by_fingerprint]
+ja4=t13d1516h2_8daaf6152771_e5627efa2ab1 ja3=... total=42 auth_success=41 bad_or_probe=1 first_seen=... last_seen=...
+[tls_fingerprints.by_cidr]
+scope=203.0.113.0/24 ja4=t13d1516h2_8daaf6152771_e5627efa2ab1 ja3=... total=10 auth_success=10 bad_or_probe=0 first_seen=... last_seen=...
+```
+
+`/beobachten` удобен для быстрой операторской диагностики без API client. API удобнее для автоматической корреляции.
+
+## Как анализировать JA4-based блокировку
+
+### 1. Зафиксировать симптом
+
+Перед анализом нужно записать:
+
+- какие пользователи жалуются;
+- какая версия Telegram client используется;
+- какая платформа: Desktop, Android, iOS;
+- какой источник сети: mobile ISP, home ISP, corporate network, country/region;
+- работает ли тот же пользователь через другой network path;
+- работает ли другой пользователь с того же IP/CIDR;
+- видит ли Telemt новые ClientHello от проблемного пользователя в момент попытки.
+
+JA4 без контекста почти всегда недостаточен. Фильтры часто используют сочетание:
+
+- JA4;
+- destination IP;
+- SNI;
+- порт;
+- ASN/source network;
+- rate или connection pattern;
+- reputation домена/IP;
+- active probing result.
+
+### 2. Проверить, доходит ли ClientHello до Telemt
+
+Во время попытки подключения проблемного пользователя смотрите:
+
+```bash
+curl -s 'http://127.0.0.1:9091/v1/runtime/tls-fingerprints?limit=200' \
+  | jq '.data.data.by_user, .data.data.by_ip, .data.data.by_cidr'
+```
+
+Интерпретация:
+
+| Наблюдение | Вероятный вывод |
+| --- | --- |
+| Нет новых rows для IP/CIDR пользователя | Блокировка до Telemt: routing, firewall, ISP/DPI drop, IP block, SYN/TCP reset, UDP/TCP path issue. |
+| Есть `by_ip`/`by_cidr`, но нет `by_user` | ClientHello дошёл, но TLS-auth/MTProxy layer не дошёл до успешного пользователя. Возможны bad key, probe, wrong client, active scanner, обрыв после ClientHello. |
+| Есть `by_user.auth_success` | Клиентский JA4 дошёл и был принят Telemt. Если пользователь всё равно видит проблему, искать нужно дальше: relay path, Telegram upstream, quota, route mode, session cancellation, ME/direct routing. |
+| Резко растёт `bad_or_probe` для одного JA4 | Вероятны сканеры или неправильные клиенты с тем же fingerprint family. |
+
+### 3. Сравнить working и blocked случаи
+
+Снимите snapshot во время working case и blocked case:
+
+```bash
+curl -s 'http://127.0.0.1:9091/v1/runtime/tls-fingerprints?limit=500' > tls-fp-working.json
+curl -s 'http://127.0.0.1:9091/v1/runtime/tls-fingerprints?limit=500' > tls-fp-blocked.json
+```
+
+Сравните:
+
+- появился ли тот же `ja4` в blocked сети;
+- меняется ли `ja4` между версиями клиента;
+- меняется ли только IP/CIDR при том же `ja4`;
+- есть ли `auth_success` для того же `ja4` из других сетей;
+- отличается ли `bad_or_probe` между сетями.
+
+Ключевая матрица:
+
+| Working JA4 | Blocked JA4 | Вывод |
+| --- | --- | --- |
+| Same | Same, но blocked network не доходит до Telemt | Вероятна фильтрация по JA4 + destination/IP/SNI/network до приложения. |
+| Same | Same, доходит и `auth_success>0` | JA4 ClientHello не является точкой отказа; искать post-auth проблему. |
+| Different | Blocked только один JA4 | Вероятен client-version/platform-specific fingerprint block. |
+| Same | `bad_or_probe` растёт, `auth_success=0` | Возможно, доходит не тот клиент/secret или фильтр/прокси ломает поток после ClientHello. |
+
+### 4. Разделить client JA4 и server fingerprint
+
+JA4 ClientHello - это клиентская сторона. Настройки Telemt вроде TLS-front server flight, `mask_host`, ticket-tail или CCS replay не меняют ClientHello, который отправляет Telegram client.
+
+Если фильтр принимает решение строго после ClientHello, то серверные улучшения могут не помочь. В этом случае полезные действия:
+
+- проверить обновление Telegram client;
+- сравнить платформы и версии клиента;
+- проверить, меняется ли JA4 на другой версии;
+- проверить, блокируется ли тот же JA4 к другому destination;
+- проверить, блокируется ли другой JA4 к тому же Telemt IP/SNI;
+- собрать evidence для client-side fingerprint fix.
+
+Если ClientHello проходит, а блокировка возникает после server response, тогда уже важны:
+
+- форма FakeTLS server flight;
+- TLS front profile fidelity;
+- `mask_host` поведение для non-auth clients;
+- certificate/provenance fallback для сканеров;
+- TCP relay behavior;
+- upstream route к Telegram.
+
+### 5. Коррелировать с packet capture
+
+Telemt collector показывает только то, что процесс увидел. Для подтверждения фильтрации до Telemt нужен внешний capture.
+
+На сервере:
+
+```bash
+sudo tcpdump -i any -w telemt-clienthello.pcap host CLIENT_IP and port 443
+```
+
+Быстрый tshark вывод ClientHello fields:
+
+```bash
+tshark -r telemt-clienthello.pcap -Y "tls.handshake.type == 1" -T fields \
+  -e frame.time_epoch \
+  -e ip.src \
+  -e ip.dst \
+  -e tcp.srcport \
+  -e tcp.dstport \
+  -e tls.handshake.extensions_server_name \
+  -e tls.handshake.extensions_alpn_str
+```
+
+Если на клиентской стороне capture видит ClientHello, а серверный capture не видит, проблема в сети между клиентом и сервером. Если серверный capture видит ClientHello, но Telemt API не видит fingerprint, проверьте порт, listener, PROXY protocol, TLS record fragmentation и bounds/errors.
+
+## Практические сценарии
+
+### Сценарий A: один JA4 перестал работать у многих пользователей
+
+Признаки:
+
+- один `ja4` доминирует в жалобах;
+- у разных source CIDR нет `auth_success`;
+- working пользователи используют другой JA4;
+- обновление клиента меняет поведение.
+
+Вероятный вывод: фильтр на стороне сети научился распознавать конкретный ClientHello family.
+
+Действия:
+
+- сравнить Telegram client versions;
+- проверить, не используют ли пользователи старые клиенты;
+- собрать `ja4`, `ja4_raw`, platform/version, source network;
+- проверить тот же client через другую сеть;
+- проверить другой client version через ту же сеть.
+
+### Сценарий B: один CIDR не работает, JA4 обычный
+
+Признаки:
+
+- тот же `ja4` успешно работает из других сетей;
+- проблемный `/24` или `/56` не доходит до Telemt или не получает `auth_success`;
+- нет общей корреляции по версии клиента.
+
+Вероятный вывод: проблема не в JA4 alone, а в source network policy или destination reputation.
+
+Действия:
+
+- сменить route/VPS/IP;
+- проверить port;
+- проверить SNI/domain reputation;
+- сравнить с другим Telemt endpoint;
+- смотреть server-side packet capture.
+
+### Сценарий C: много `bad_or_probe` на одном JA4
+
+Признаки:
+
+- `bad_or_probe` высокий;
+- `by_user` пустой или слабый;
+- source IP/CIDR разнообразные;
+- попытки не соответствуют реальным пользователям.
+
+Вероятный вывод: активное сканирование или нерелевантный TLS traffic с похожим ClientHello.
+
+Действия:
+
+- смотреть `/beobachten` по IP classes;
+- проверить `unknown_tls_sni` и bad-client counters;
+- убедиться, что fallback `mask_host` отвечает правдоподобно;
+- не делать вывод о блокировке пользователей только по global `bad_or_probe`.
+
+### Сценарий D: `auth_success` есть, но пользователь жалуется
+
+Признаки:
+
+- fingerprint присутствует в `by_user`;
+- `auth_success` растёт;
+- соединение проходит TLS-auth.
+
+Вероятный вывод: JA4 ClientHello не является причиной отказа в этом случае.
+
+Действия:
+
+- проверить user enabled/disabled status;
+- проверить quota;
+- проверить direct/ME route;
+- проверить upstream health;
+- проверить runtime events;
+- смотреть relay/session logs.
+
+## Что нельзя вывести из JA3/JA4
+
+JA3/JA4 не говорят:
+
+- почему сеть приняла решение о блокировке;
+- какой именно vendor DPI используется;
+- был ли block только по JA4 или по связке JA4+IP+SNI;
+- что произошло с соединением после TLS-auth;
+- как выглядит server-side TLS fingerprint;
+- как ведёт себя HTTP layer после TLS.
+
+JA3/JA4 также не являются уникальной идентичностью человека. Это fingerprint клиентской TLS-реализации и её настроек. Один fingerprint может быть у большого числа пользователей.
+
+## Ограничения collector'а Telemt
+
+- Считается только TLS ClientHello, который полностью дошёл до Telemt.
+- QUIC/DTLS/HTTP JA4 variants не собираются.
+- Truncated ClientHello не fingerprint'ится.
+- User scope появляется только после успешной TLS-auth.
+- `by_ip` и `by_cidr` отражают source address после нормализации/PROXY protocol path, если он используется.
+- Collector bounded: при большом количестве уникальных buckets возможен рост `dropped_total`.
+- Retention зависит от `general.beobachten_minutes`.
+- Данные runtime in-memory; это snapshot для диагностики, а не долговременное хранилище.
+
+## Рекомендованный workflow расследования
+
+1. Включить `runtime_edge_enabled=true` и разумный `runtime_edge_top_n`, например `100`.
+2. Зафиксировать baseline в период нормальной работы.
+3. Во время жалобы снять API snapshot и `/beobachten`.
+4. Сравнить `by_user`, `by_ip`, `by_cidr`, `by_fingerprint`.
+5. Проверить, появляется ли problematic source в Telemt вообще.
+6. Если не появляется, снять packet capture на сервере и клиенте.
+7. Если появляется без `auth_success`, проверить secret/client/proxy link и bad/probe counters.
+8. Если появляется с `auth_success`, исключить JA4 ClientHello как primary cause и перейти к relay/upstream/runtime диагностике.
+9. Если один JA4 стабильно коррелирует с block, собрать client version/platform evidence.
+10. Проверить, меняет ли обновление клиента JA4 и результат подключения.
+
+## Минимальный incident report
+
+Для полезного отчёта по JA4-based блокировке соберите:
+
+```text
+time_window:
+telemt_version:
+server_ip:
+server_port:
+tls_domain:
+mask_host:
+client_platform:
+client_version:
+source_network:
+source_ip_or_cidr:
+ja4:
+ja4_raw:
+ja3:
+total:
+auth_success:
+bad_or_probe:
+seen_in_by_user: yes/no
+seen_in_by_ip: yes/no
+seen_in_by_cidr: yes/no
+server_tcpdump_seen_clienthello: yes/no
+client_tcpdump_sent_clienthello: yes/no
+works_from_other_network: yes/no
+works_with_other_client_version: yes/no
+```
+
+Этот набор обычно достаточен, чтобы отличить client fingerprint block от IP/SNI/reputation block и от post-auth проблем Telemt.
+
+## Источники форматов
+
+- JA3 reference: https://github.com/salesforce/ja3
+- JA4 technical details: https://github.com/FoxIO-LLC/ja4/blob/main/technical_details/JA4.md
+

docs/FAQ.en.md

@@ -172,7 +172,7 @@ Those cross-DC requests are normal and happen constantly.
 > If your home DC is DC2 and DC2 goes down, you **cannot** reach DC5 even though DC5 itself is perfectly healthy.  
 > The client has no valid session to route the request through.  
 
-This is also why an MTProxy only needs to reach Telegram's DC infrastructure as a whole.  
+This is also why it is required for MTProxy to reach Telegram's DC infrastructure as a whole.  
 The proxy itself doesn't care which DC your account lives on. The client negotiates the correct DC through the proxy after connecting.
 
 ### How many people can use one link

docs/FAQ.ru.md

@@ -40,6 +40,8 @@ hello2 = "ad_tag2"
 > Проблема с TLS отпечатком исправлена в последних версиях клиентов Telegram для Desktop / Android / iOS.  
 > Обновите свой клиент для корректной работы с MTProxy Fake-TLS!
 
+- Для расследования блокировок на базе JA4 ClientHello используйте отдельную инструкцию: [`JA3 и JA4 анализ в Telemt`](Architecture/Fronting-splitting/TLS_JA3_JA4_ANALYSIS.ru.md).
+
 - Мы считаем это прорывом, которому на сегодняшний день нет стабильных аналогов;
 - Исходя из этого: если `telemt` настроен правильно, **режим TLS полностью идентичен реальному «рукопожатию» + обмену данными** с указанным хостом;
 - Вот наши доказательства:
@@ -157,7 +159,7 @@ https://github.com/telemt/telemt/discussions/167
 
 ## Как клиенты взаимодействуют с дата-центрами Telegram
 При регистрации аккаунта Telegram он навсегда привязывается к одному из дата-центров (DC).  
-Telegram заранее определяет к какому DC привязать аккаунт исходя из региона, к которому относиться номер телефона.  
+Telegram заранее определяет к какому DC привязать аккаунт исходя из региона, к которому относится номер телефона.  
 Этот DC становится вашим **домашним**: именно там хранится весь контент, который вы загружаете (фото, видео, файлы, сообщения).  
 И именно на нем клиент авторизуется при каждом подключении.  
 
@@ -170,7 +172,7 @@ Telegram заранее определяет к какому DC привязат
 > Если ваш домашний DC — DC2, и DC2 лежит, вы **не сможете** достучаться  и до DC5, даже если сам DC5 полностью исправен.  
 > У клиента просто нет валидной сессии, через которую можно было бы направить запрос.  
 
-По той же причине MTProxy достаточно иметь доступ к инфраструктуре Telegram в целом.  
+По той же причине MTProxy необходимо иметь доступ к инфраструктуре Telegram целиком, а не частично.  
 Cамому MTProxy всё равно, на каком DC живёт ваш аккаунт. Клиент cам договаривается о нужном DC через прокси уже после подключения.  
 
 ## Что такое dd и ee в контексте MTProxy?

docs/Quick_start/QUICK_START_GUIDE.ru.md

@@ -235,7 +235,10 @@ curl -s http://127.0.0.1:9091/v1/users | jq -r '.data[] | "[\(.username)]", (.li
 
 # Telemt через Docker Compose
 
-**1. Отредактируйте `config.toml` в корневом каталоге репозитория (как минимум: порт, пользовательские секреты, tls_domain)**  
+**1. Создайте директорию `config/` и поместите в неё отрдеактированный `config.toml` (указав как минимум: порт, пользовательские секреты, tls_domain):**
+```bash
+mkdir config && mv config.toml config/
+```
 **2. Запустите контейнер:**
 ```bash
 docker compose up -d --build
@@ -249,7 +252,7 @@ docker compose logs -f telemt
 docker compose down
 ```
 > [!NOTE]
-> - В `docker-compose.yml` файл `./config.toml` монтируется в `/app/config.toml` (доступно только для чтения)  
+> - Директория `./config/` монтируется в `/etc/telemt/` (read-write), что позволяет API атомарно обновлять config.toml
 > - По умолчанию публикуются порты 443:443, а контейнер запускается со сброшенными привилегиями (добавлена только `NET_BIND_SERVICE`)  
 > - Если вам действительно нужна сеть хоста (обычно это требуется только для некоторых конфигураций IPv6), раскомментируйте `network_mode: host`
 

docs/Setup_examples/XRAY_DOUBLE_HOP.en.md

@@ -206,7 +206,7 @@ File content:
           "publicKey": "<SERVER_B_PUBLIC_KEY>",
           "shortId": "<SHORT_ID>",
           "spiderX": "/",
-          "fingerprint": "chrome"
+          "fingerprint": "firefox"
         },
         "xhttpSettings": {
           "path": "/<YOUR_RANDOM_PATH>"

docs/Setup_examples/XRAY_DOUBLE_HOP.ru.md

@@ -206,7 +206,7 @@ nano /usr/local/etc/xray/config.json
           "publicKey": "<SERVER_B_PUBLIC_KEY>",
           "shortId": "<SHORT_ID>",
           "spiderX": "/",
-          "fingerprint": "chrome"
+          "fingerprint": "firefox"
         },
         "xhttpSettings": {
           "path": "/<YOUR_RANDOM_PATH>"

install.sh

@@ -84,27 +84,29 @@ set_language() {
             L_INFO_KEEP_CONF="Примечание: Конфигурация сохранена. Используйте 'purge' для очистки."
             L_INFO_I_START="Начинается установка"
             L_I_STAGE_1=">>> Этап 1: Проверка окружения и зависимостей"
-            L_I_STAGE_1_5=">>> Этап 1.5: Интерактивная настройка"
+            L_I_STAGE_2=">>> Этап 2: Интерактивная настройка"
             L_I_PROMPT_DOM="\nПожалуйста, укажите домен TLS\nНажмите Enter, чтобы оставить по умолчанию [%s]: "
+            L_I_PROMPT_PORT="\nПожалуйста, укажите порт сервера\nНажмите Enter, чтобы оставить по умолчанию [%s]: "
             L_WARN_NO_TTY="Интерактивный режим недоступен (нет TTY). Используется:"
-            L_I_STAGE_2=">>> Этап 2: Загрузка архива"
+            L_I_STAGE_3=">>> Этап 3: Загрузка архива"
             L_ERR_TMP_DIR="Не удалось создать временную директорию"
             L_ERR_TMP_INV="Временная директория недействительна"
             L_INFO_FALLBACK="Сборка x86_64-v3 не найдена, откат к стандартной x86_64..."
             L_ERR_DL_FAIL="Ошибка загрузки архива"
-            L_I_STAGE_3=">>> Этап 3: Распаковка архива"
+            L_I_STAGE_4=">>> Этап 4: Распаковка архива"
             L_ERR_EXTRACT="Ошибка распаковки архива."
             L_ERR_BIN_NOT_FOUND="Бинарный файл не найден в архиве"
-            L_I_STAGE_4=">>> Этап 4: Настройка окружения (Юзер, Группа, Папки)"
-            L_I_STAGE_5=">>> Этап 5: Установка бинарного файла"
-            L_I_STAGE_6=">>> Этап 6: Генерация/Обновление конфигурации"
-            L_I_STAGE_7=">>> Этап 7: Установка и запуск службы"
+            L_I_STAGE_5=">>> Этап 5: Настройка окружения (Юзер, Группа, Папки)"
+            L_I_STAGE_6=">>> Этап 6: Установка бинарного файла"
+            L_I_STAGE_7=">>> Этап 7: Генерация/Обновление конфигурации"
+            L_I_STAGE_8=">>> Этап 8: Установка и запуск службы"
             L_OUT_WARN_H="УСТАНОВКА ЗАВЕРШЕНА С ПРЕДУПРЕЖДЕНИЯМИ"
             L_OUT_WARN_D="Служба установлена, но не запустилась.\nПожалуйста, проверьте логи.\n"
             L_OUT_SUCC_H="УСТАНОВКА УСПЕШНО ЗАВЕРШЕНА"
             L_OUT_UNINST_H="УДАЛЕНИЕ ЗАВЕРШЕНО"
             L_OUT_LINK="Ваша ссылка для подключения к Telegram Proxy:\n"
             L_ERR_INCORR_ROOT_LOGIN="Используйте 'su -' или 'sudo -i' для входа под пользователем root"
+            L_OUT_LOGS="Чтобы посмотреть логи (в случае проблем), используйте команду:"
             ;;
         *)
             L_ERR_DOMAIN_REQ="requires a domain argument."
@@ -159,27 +161,29 @@ set_language() {
             L_INFO_KEEP_CONF="Note: Configuration kept. Run with 'purge' to remove completely."
             L_INFO_I_START="Starting installation of"
             L_I_STAGE_1=">>> Stage 1: Verifying environment and dependencies"
-            L_I_STAGE_1_5=">>> Stage 1.5: Interactive Setup"
+            L_I_STAGE_2=">>> Stage 2: Interactive Setup"
             L_I_PROMPT_DOM="\nPlease specify the TLS Domain\nPress Enter to keep default [%s]: "
+            L_I_PROMPT_PORT="\nPlease specify the Server Port\nPress Enter to keep default [%s]: "
             L_WARN_NO_TTY="Interactive mode unavailable (no TTY). Using:"
-            L_I_STAGE_2=">>> Stage 2: Downloading archive"
+            L_I_STAGE_3=">>> Stage 3: Downloading archive"
             L_ERR_TMP_DIR="Temp directory creation failed"
             L_ERR_TMP_INV="Temp directory is invalid or was not created"
             L_INFO_FALLBACK="x86_64-v3 build not found, falling back to standard x86_64..."
             L_ERR_DL_FAIL="Download failed"
-            L_I_STAGE_3=">>> Stage 3: Extracting archive"
+            L_I_STAGE_4=">>> Stage 4: Extracting archive"
             L_ERR_EXTRACT="Extraction failed."
             L_ERR_BIN_NOT_FOUND="Binary not found in archive"
-            L_I_STAGE_4=">>> Stage 4: Setting up environment (User, Group, Directories)"
-            L_I_STAGE_5=">>> Stage 5: Installing binary"
-            L_I_STAGE_6=">>> Stage 6: Generating/Updating configuration"
-            L_I_STAGE_7=">>> Stage 7: Installing and starting service"
+            L_I_STAGE_5=">>> Stage 5: Setting up environment (User, Group, Directories)"
+            L_I_STAGE_6=">>> Stage 6: Installing binary"
+            L_I_STAGE_7=">>> Stage 7: Generating/Updating configuration"
+            L_I_STAGE_8=">>> Stage 8: Installing and starting service"
             L_OUT_WARN_H="INSTALLATION COMPLETED WITH WARNINGS"
             L_OUT_WARN_D="The service was installed but failed to start.\nPlease check the logs to determine the issue.\n"
             L_OUT_SUCC_H="INSTALLATION SUCCESS"
             L_OUT_UNINST_H="UNINSTALLATION COMPLETE"
             L_OUT_LINK="Your Telegram Proxy connection link:\n"
             L_ERR_INCORR_ROOT_LOGIN="Use 'su -' or 'sudo -i' to login under root"
+            L_OUT_LOGS="To view logs (in case of issues), use the following command:"
             ;;
     esac
 }
@@ -267,7 +271,10 @@ say() {
     if [ "$#" -eq 0 ] || [ -z "${1:-}" ]; then
         printf '\n'
     else
-        printf '[INFO] %s\n' "$*"
+        case "$*" in
+            \[*\]*) printf '%s\n' "$*" ;;
+            *) printf '[INFO] %s\n' "$*" ;;
+        esac
     fi
 }
 die() { printf '[ERROR] %s\n' "$*" >&2; exit 1; }
@@ -392,7 +399,7 @@ verify_common() {
 
     if [ "$(id -u)" -eq 0 ]; then
         SUDO=""
-        if [ "$(id -u)" -ne 0 ]; then
+        if [ "${USER:-}" != "root" ] && [ "${LOGNAME:-}" != "root" ]; then
             die "$L_ERR_INCORR_ROOT_LOGIN"
         fi
     else
@@ -525,9 +532,9 @@ setup_dirs() {
 
 stop_service() {
     svc="$(get_svc_mgr)"
-    if [ "$svc" = "systemd" ] && systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then
+    if [ "$svc" = "systemd" ] && $SUDO systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then
         $SUDO systemctl stop "$SERVICE_NAME" 2>/dev/null || true
-    elif [ "$svc" = "openrc" ] && rc-service "$SERVICE_NAME" status >/dev/null 2>&1; then
+    elif [ "$svc" = "openrc" ] && $SUDO rc-service "$SERVICE_NAME" status >/dev/null 2>&1; then
         $SUDO rc-service "$SERVICE_NAME" stop 2>/dev/null || true
     fi
 }
@@ -830,10 +837,36 @@ case "$ACTION" in
             fi
         fi
 
-        check_port_availability
+        if [ "$PORT_PROVIDED" -eq 0 ] || [ "$DOMAIN_PROVIDED" -eq 0 ]; then
+            say "$L_I_STAGE_2"
+        fi
+
+        if [ "$PORT_PROVIDED" -eq 0 ]; then
+            if [ -t 0 ] || [ -c /dev/tty ]; then
+                while true; do
+                    printf "$L_I_PROMPT_PORT" "$SERVER_PORT"
+                    read -r input_port </dev/tty || input_port=""
+                    if [ -z "$input_port" ]; then
+                        break
+                    fi
+                    case "$input_port" in
+                        *[!0-9]*) printf '[ERROR] %s\n' "$L_ERR_PORT_NUM" >&2; continue ;;
+                    esac
+                    port_num="$(printf '%s\n' "$input_port" | sed 's/^0*//')"
+                    [ -z "$port_num" ] && port_num="0"
+                    if [ "${#port_num}" -gt 5 ] || [ "$port_num" -lt 1 ] || [ "$port_num" -gt 65535 ]; then
+                        printf '[ERROR] %s\n' "$L_ERR_PORT_RANGE" >&2; continue
+                    fi
+                    SERVER_PORT="$port_num"
+                    break
+                done
+            else
+                say "[WARNING] $L_WARN_NO_TTY $SERVER_PORT"
+            fi
+            PORT_PROVIDED=1
+        fi
 
         if [ "$DOMAIN_PROVIDED" -eq 0 ]; then
-            say "$L_I_STAGE_1_5"
             if [ -t 0 ] || [ -c /dev/tty ]; then
                 printf "$L_I_PROMPT_DOM" "$TLS_DOMAIN"
                 read -r input_domain </dev/tty || input_domain=""
@@ -846,6 +879,8 @@ case "$ACTION" in
             DOMAIN_PROVIDED=1
         fi
 
+        check_port_availability
+
         if [ "$TARGET_VERSION" != "latest" ]; then
             TARGET_VERSION="${TARGET_VERSION#v}"
         fi
@@ -859,7 +894,7 @@ case "$ACTION" in
             DL_URL="https://github.com/${REPO}/releases/download/${TARGET_VERSION}/${FILE_NAME}"
         fi
 
-        say "$L_I_STAGE_2"
+        say "$L_I_STAGE_3"
         TEMP_DIR="$(mktemp -d)" || die "$L_ERR_TMP_DIR"
         if [ -z "$TEMP_DIR" ] || [ ! -d "$TEMP_DIR" ]; then
             die "$L_ERR_TMP_INV"
@@ -881,7 +916,7 @@ case "$ACTION" in
             fi
         fi
 
-        say "$L_I_STAGE_3"
+        say "$L_I_STAGE_4"
         if ! gzip -dc "${TEMP_DIR}/${FILE_NAME}" | tar -xf - -C "$TEMP_DIR" 2>/dev/null; then
             die "$L_ERR_EXTRACT"
         fi
@@ -889,16 +924,16 @@ case "$ACTION" in
         EXTRACTED_BIN="$(find "$TEMP_DIR" -type f -name "$BIN_NAME" -print 2>/dev/null | head -n 1 || true)"
         [ -n "$EXTRACTED_BIN" ] || die "$L_ERR_BIN_NOT_FOUND"
 
-        say "$L_I_STAGE_4"
+        say "$L_I_STAGE_5"
         ensure_user_group; setup_dirs; stop_service
 
-        say "$L_I_STAGE_5"
+        say "$L_I_STAGE_6"
         install_binary "$EXTRACTED_BIN" "${INSTALL_DIR}/${BIN_NAME}"
 
-        say "$L_I_STAGE_6"
+        say "$L_I_STAGE_7"
         install_config
 
-        say "$L_I_STAGE_7"
+        say "$L_I_STAGE_8"
         install_service
 
         if [ "${SERVICE_START_FAILED:-0}" -eq 1 ]; then
@@ -927,6 +962,15 @@ case "$ACTION" in
         printf '%b\n' "$L_OUT_LINK"
         printf '  tg://proxy?server=%s&port=%s&secret=%s\n\n' "$SERVER_IP" "$SERVER_PORT" "$CLIENT_SECRET"
 
+        svc="$(get_svc_mgr)"
+        if [ "$svc" = "systemd" ]; then
+            printf '%s\n' "$L_OUT_LOGS"
+            printf '  sudo journalctl -u %s -f\n\n' "$SERVICE_NAME"
+        elif [ "$svc" = "openrc" ]; then
+            printf '%s\n' "$L_OUT_LOGS"
+            printf '  sudo tail -f /var/log/messages /var/log/syslog 2>/dev/null | grep -i %s\n\n' "$SERVICE_NAME"
+        fi
+
         printf '====================================================================\n'
         ;;
 esac

src/api/config_edit.rs

@@ -0,0 +1,334 @@
+//! Config-editing API: read managed sections and apply sparse field patches.
+//! `access.*` is intentionally not editable here (owned by the users API).
+
+use serde_json::Value as Json;
+use toml::Value as Toml;
+
+use super::ApiShared;
+use super::config_store::{
+    EDITABLE_SECTIONS, compute_revision, current_revision, save_sections_to_disk,
+};
+use super::model::ApiFailure;
+use crate::config::ProxyConfig;
+use crate::config::hot_reload::classify_config_changes;
+use serde::Serialize;
+use std::path::Path;
+
+#[derive(Debug, Serialize)]
+pub(super) struct PatchConfigResponse {
+    pub revision: String,
+    pub restart_required: bool,
+    pub changed: Vec<String>,
+}
+
+/// Shared-state wrapper around [`apply_patch_to_path`]: serializes config
+/// mutations behind `mutation_lock`, then records a runtime event. The route
+/// handler calls this; the core logic stays decoupled for unit tests.
+pub(super) async fn patch_config(
+    patch_json: Json,
+    expected_revision: Option<String>,
+    shared: &ApiShared,
+) -> Result<PatchConfigResponse, ApiFailure> {
+    let _guard = shared.mutation_lock.lock().await;
+    let resp = apply_patch_to_path(&shared.config_path, &patch_json, expected_revision).await?;
+    drop(_guard);
+    shared
+        .runtime_events
+        .record("api.config.patch.ok", format!("changed={:?}", resp.changed));
+    Ok(resp)
+}
+
+/// Core patch logic, decoupled from hyper/shared-state so it is unit-testable
+/// against a temp file. The route handler holds `mutation_lock` while calling this.
+pub(super) async fn apply_patch_to_path(
+    config_path: &Path,
+    patch_json: &Json,
+    expected_revision: Option<String>,
+) -> Result<PatchConfigResponse, ApiFailure> {
+    // 1. optimistic concurrency
+    let current = current_revision(config_path).await?;
+    if expected_revision.is_some_and(|expected| expected != current) {
+        return Err(ApiFailure::new(
+            hyper::StatusCode::CONFLICT,
+            "revision_conflict",
+            "Config revision mismatch",
+        ));
+    }
+
+    // 2. convert + reject access / unknown sections
+    let patch_toml = json_to_toml(patch_json)
+        .map_err(|e| ApiFailure::bad_request(format!("invalid patch: {}", e)))?;
+    let patch_table = patch_toml
+        .as_table()
+        .ok_or_else(|| ApiFailure::bad_request("patch must be a JSON object"))?;
+    if patch_table.contains_key("access") {
+        return Err(ApiFailure::new(
+            hyper::StatusCode::BAD_REQUEST,
+            "access_not_editable",
+            "access.* is managed via the users API, not editable here",
+        ));
+    }
+    for key in patch_table.keys() {
+        if !EDITABLE_SECTIONS.contains(&key.as_str()) {
+            return Err(ApiFailure::new(
+                hyper::StatusCode::BAD_REQUEST,
+                "section_not_editable",
+                format!("section not editable: {}", key),
+            ));
+        }
+    }
+    let touched: Vec<&str> = patch_table
+        .keys()
+        .map(|k| k.as_str())
+        .filter(|k| EDITABLE_SECTIONS.contains(k))
+        .collect();
+    if touched.is_empty() {
+        return Err(ApiFailure::bad_request("empty patch: no editable sections"));
+    }
+
+    // 3. Parse old + merged from the SAME deserialize path so the classifier
+    //    sees only the delta this patch introduces. `ProxyConfig::load` applies
+    //    include-expansion / legacy-compat / normalization that a bare
+    //    `try_into` does not; mixing the two paths would make unrelated fields
+    //    compare unequal and spuriously force `restart_required`.
+    let original = tokio::fs::read_to_string(config_path)
+        .await
+        .map_err(|e| ApiFailure::internal(format!("failed to read config: {}", e)))?;
+    let original_toml: Toml = toml::from_str(&original)
+        .map_err(|e| ApiFailure::internal(format!("failed to parse config: {}", e)))?;
+    let old_cfg: ProxyConfig = original_toml
+        .clone()
+        .try_into()
+        .map_err(|e| ApiFailure::internal(format!("config does not deserialize: {}", e)))?;
+
+    let mut merged = original_toml;
+    deep_merge(&mut merged, &patch_toml);
+
+    let new_cfg: ProxyConfig = merged
+        .clone()
+        .try_into()
+        .map_err(|e| ApiFailure::bad_request(format!("config does not deserialize: {}", e)))?;
+    new_cfg
+        .validate()
+        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
+
+    // 4. classify changes (Telemt's own hot/restart rule)
+    let class = classify_config_changes(&old_cfg, &new_cfg);
+
+    // 5. write only the touched top-level sections
+    let revision = save_sections_to_disk(config_path, &new_cfg, &touched).await?;
+
+    Ok(PatchConfigResponse {
+        revision,
+        restart_required: class.restart_required,
+        changed: class.changed,
+    })
+}
+
+/// Return only the editable config sections + current revision.
+pub(super) async fn read_managed_config(config_path: &Path) -> Result<(Toml, String), ApiFailure> {
+    let original = tokio::fs::read_to_string(config_path)
+        .await
+        .map_err(|e| ApiFailure::internal(format!("failed to read config: {}", e)))?;
+    let parsed: Toml = toml::from_str(&original)
+        .map_err(|e| ApiFailure::internal(format!("failed to parse config: {}", e)))?;
+
+    let parsed_table = parsed
+        .as_table()
+        .cloned()
+        .unwrap_or_else(toml::value::Table::new);
+    // Whitelist: return ONLY the editable sections. A blacklist (just removing
+    // `access`) would leak `server` (carries the API `auth_header` + per-node
+    // identity) and `network` (per-node addresses). Mirror the PATCH contract.
+    let mut table = toml::value::Table::new();
+    for section in EDITABLE_SECTIONS {
+        if let Some(value) = parsed_table.get(*section) {
+            table.insert((*section).to_string(), value.clone());
+        }
+    }
+
+    let revision = compute_revision(&original);
+    Ok((Toml::Table(table), revision))
+}
+
+/// Convert a serde_json value to a toml value. `null` is dropped from objects
+/// (a patch never sets a key to TOML-null). Numbers become integers when exact,
+/// otherwise floats.
+fn json_to_toml(j: &Json) -> Result<Toml, String> {
+    Ok(match j {
+        Json::Null => return Err("null is not representable in TOML".into()),
+        Json::Bool(b) => Toml::Boolean(*b),
+        Json::Number(n) => {
+            if let Some(i) = n.as_i64() {
+                Toml::Integer(i)
+            } else if let Some(f) = n.as_f64() {
+                Toml::Float(f)
+            } else {
+                return Err(format!("unrepresentable number: {}", n));
+            }
+        }
+        Json::String(s) => Toml::String(s.clone()),
+        Json::Array(items) => {
+            let mut out = Vec::with_capacity(items.len());
+            for item in items {
+                out.push(json_to_toml(item)?);
+            }
+            Toml::Array(out)
+        }
+        Json::Object(map) => {
+            let mut table = toml::value::Table::new();
+            for (k, v) in map {
+                if v.is_null() {
+                    continue; // skip nulls instead of erroring at object level
+                }
+                table.insert(k.clone(), json_to_toml(v)?);
+            }
+            Toml::Table(table)
+        }
+    })
+}
+
+/// Recursively overlay `patch` onto `base`. Tables merge key-by-key; every
+/// other value type (scalars, arrays) replaces wholesale.
+fn deep_merge(base: &mut Toml, patch: &Toml) {
+    match (base, patch) {
+        (Toml::Table(b), Toml::Table(p)) => {
+            for (k, pv) in p {
+                match b.get_mut(k) {
+                    Some(bv) => deep_merge(bv, pv),
+                    None => {
+                        b.insert(k.clone(), pv.clone());
+                    }
+                }
+            }
+        }
+        (b, p) => *b = p.clone(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn json_object_converts_to_toml_table() {
+        let j: Json = serde_json::json!({"censorship": {"tls_domain": "a.com"}, "default_dc": 2});
+        let t = json_to_toml(&j).expect("convertible");
+        let table = t.as_table().unwrap();
+        assert_eq!(table["censorship"]["tls_domain"].as_str(), Some("a.com"));
+        assert_eq!(table["default_dc"].as_integer(), Some(2));
+    }
+
+    #[test]
+    fn deep_merge_overlays_tables_and_replaces_scalars() {
+        let mut base: Toml =
+            toml::from_str("[censorship]\ntls_domain = \"old\"\nfake_cert_len = 100\n").unwrap();
+        let patch: Toml = toml::from_str("[censorship]\ntls_domain = \"new\"\n").unwrap();
+
+        deep_merge(&mut base, &patch);
+
+        let cens = base["censorship"].as_table().unwrap();
+        assert_eq!(cens["tls_domain"].as_str(), Some("new")); // overlaid
+        assert_eq!(cens["fake_cert_len"].as_integer(), Some(100)); // preserved
+    }
+
+    use std::path::PathBuf;
+
+    fn temp_config(body: &str) -> (PathBuf, tempfile::TempDir) {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(&path, body).unwrap();
+        (path, dir)
+    }
+
+    #[tokio::test]
+    async fn patch_rejects_access_section() {
+        let (path, _d) = temp_config("[censorship]\ntls_domain = \"a\"\n");
+        let patch: Json = serde_json::json!({"access": {"users": {"x": "y"}}});
+        let err = apply_patch_to_path(&path, &patch, None).await.unwrap_err();
+        assert_eq!(err.code, "access_not_editable");
+    }
+
+    #[tokio::test]
+    async fn patch_revision_conflict() {
+        let (path, _d) = temp_config("[censorship]\ntls_domain = \"a\"\n");
+        let patch: Json = serde_json::json!({"censorship": {"tls_domain": "b"}});
+        let err = apply_patch_to_path(&path, &patch, Some("deadbeef".into()))
+            .await
+            .unwrap_err();
+        assert_eq!(err.code, "revision_conflict");
+    }
+
+    #[tokio::test]
+    async fn patch_sni_reports_restart_required() {
+        let (path, _d) =
+            temp_config("[censorship]\ntls_domain = \"a.com\"\n[server]\nport = 443\n");
+        let patch: Json = serde_json::json!({"censorship": {"tls_domain": "b.com"}});
+        let resp = apply_patch_to_path(&path, &patch, None).await.unwrap();
+        assert!(resp.restart_required);
+        assert!(resp.changed.iter().any(|c| c == "censorship"));
+        let written = std::fs::read_to_string(&path).unwrap();
+        assert!(written.contains("tls_domain = \"b.com\""));
+        assert_eq!(
+            resp.revision,
+            crate::api::config_store::compute_revision(&written)
+        );
+    }
+
+    #[tokio::test]
+    async fn read_managed_config_strips_access() {
+        let (path, _d) = temp_config(
+            "[censorship]\ntls_domain = \"a.com\"\n[access.users]\nbob = \"deadbeef\"\n",
+        );
+        let (value, revision) = read_managed_config(&path).await.unwrap();
+        let table = value.as_table().unwrap();
+        assert!(table.contains_key("censorship"));
+        assert!(!table.contains_key("access")); // secrets never leave the box here
+        assert_eq!(revision, current_revision(&path).await.unwrap());
+    }
+
+    #[tokio::test]
+    async fn read_managed_config_returns_only_editable_sections() {
+        // server carries the API auth_header + per-node identity; network carries
+        // per-node addresses. Neither must be exposed by GET /v1/config.
+        let (path, _d) = temp_config(concat!(
+            "[censorship]\ntls_domain = \"a\"\n",
+            "[server]\nport = 443\n[server.api]\nauth_header = \"SECRET\"\n",
+            "[network]\nipv4 = \"1.2.3.4\"\n",
+            "[access.users]\nbob = \"deadbeef\"\n",
+        ));
+        let (value, _rev) = read_managed_config(&path).await.unwrap();
+        let table = value.as_table().unwrap();
+        assert!(table.contains_key("censorship"));
+        assert!(!table.contains_key("server")); // no API auth_header / identity leak
+        assert!(!table.contains_key("network")); // no per-node identity leak
+        assert!(!table.contains_key("access")); // no users/secrets
+    }
+
+    #[tokio::test]
+    async fn patch_rejects_server_section() {
+        let (path, _d) = temp_config("[censorship]\ntls_domain = \"a\"\n");
+        let patch: Json = serde_json::json!({"server": {"port": 1}});
+        let err = apply_patch_to_path(&path, &patch, None).await.unwrap_err();
+        assert_eq!(err.code, "section_not_editable");
+    }
+
+    #[tokio::test]
+    async fn patch_empty_is_rejected() {
+        let (path, _d) = temp_config("[censorship]\ntls_domain = \"a\"\n");
+        let patch: Json = serde_json::json!({});
+        assert!(apply_patch_to_path(&path, &patch, None).await.is_err());
+    }
+
+    #[tokio::test]
+    async fn patch_log_level_is_hot() {
+        // general.log_level is hot-reloadable -> a patch changing only it must
+        // report restart_required = false (exercises the full apply path, not
+        // just the classifier). Default LogLevel is Normal; patch to "debug".
+        let (path, _d) = temp_config("[censorship]\ntls_domain = \"a\"\n");
+        let patch: Json = serde_json::json!({"general": {"log_level": "debug"}});
+        let resp = apply_patch_to_path(&path, &patch, None).await.unwrap();
+        assert!(!resp.restart_required);
+        assert!(resp.changed.iter().any(|c| c == "general"));
+    }
+}

src/api/config_store.rs

@@ -14,6 +14,7 @@ use super::model::ApiFailure;
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(super) enum AccessSection {
     Users,
+    UserEnabled,
     UserAdTags,
     UserMaxTcpConns,
     UserExpirations,
@@ -26,6 +27,7 @@ impl AccessSection {
     fn table_name(self) -> &'static str {
         match self {
             Self::Users => "access.users",
+            Self::UserEnabled => "access.user_enabled",
             Self::UserAdTags => "access.user_ad_tags",
             Self::UserMaxTcpConns => "access.user_max_tcp_conns",
             Self::UserExpirations => "access.user_expirations",
@@ -95,6 +97,81 @@ pub(super) async fn save_config_to_disk(
     Ok(compute_revision(&serialized))
 }
 
+/// Top-level config tables that may be edited via the config API.
+///
+/// Intentionally excluded (defense-in-depth, enforces the spec's per-node
+/// identity invariant at the Telemt layer too):
+///
+///   - `access`  : owned by the users API.
+///   - `server`  : carries per-node identity (`port`, `api`/`api_bind`, listeners).
+///   - `network` : carries per-node identity (`ipv4`/`ipv6`).
+///
+/// A future field-level allowlist can re-admit specific safe fields
+/// (e.g. `network.dns_overrides`) without opening the whole section.
+pub(super) const EDITABLE_SECTIONS: &[&str] = &[
+    "general",
+    "timeouts",
+    "censorship",
+    "upstreams",
+    "show_link",
+    "dc_overrides",
+];
+
+/// Re-render the given top-level tables from `cfg` and upsert each into the
+/// on-disk file, preserving every untouched section (and its comments).
+pub(super) async fn save_sections_to_disk(
+    config_path: &Path,
+    cfg: &ProxyConfig,
+    sections: &[&str],
+) -> Result<String, ApiFailure> {
+    let mut content = tokio::fs::read_to_string(config_path)
+        .await
+        .map_err(|e| ApiFailure::internal(format!("failed to read config: {}", e)))?;
+
+    for section in sections {
+        let rendered = render_top_level_section(cfg, section)?;
+        content = upsert_toml_table(&content, section, &rendered);
+    }
+
+    write_atomic(config_path.to_path_buf(), content.clone()).await?;
+    Ok(compute_revision(&content))
+}
+
+/// Render one top-level table as `[section]\n...\n` (or `[[upstreams]]` array
+/// of tables) from the typed `cfg`. Serializes via the `toml` crate so the
+/// output matches the canonical format Telemt parses.
+fn render_top_level_section(cfg: &ProxyConfig, section: &str) -> Result<String, ApiFailure> {
+    let value = toml::Value::try_from(cfg)
+        .map_err(|e| ApiFailure::internal(format!("failed to serialize config: {}", e)))?;
+    let table = value
+        .get(section)
+        .ok_or_else(|| ApiFailure::internal(format!("unknown section: {}", section)))?;
+
+    // upstreams is an array-of-tables -> render as [[upstreams]] blocks.
+    if let toml::Value::Array(items) = table {
+        let mut out = String::new();
+        for item in items {
+            out.push_str(&format!("[[{}]]\n", section));
+            out.push_str(&toml::to_string(item).map_err(|e| {
+                ApiFailure::internal(format!("failed to serialize {}: {}", section, e))
+            })?);
+            if !out.ends_with('\n') {
+                out.push('\n');
+            }
+        }
+        return Ok(out);
+    }
+
+    let body = toml::to_string(table)
+        .map_err(|e| ApiFailure::internal(format!("failed to serialize {}: {}", section, e)))?;
+    let mut out = format!("[{}]\n", section);
+    out.push_str(&body);
+    if !out.ends_with('\n') {
+        out.push('\n');
+    }
+    Ok(out)
+}
+
 pub(super) async fn save_access_sections_to_disk(
     config_path: &Path,
     cfg: &ProxyConfig,
@@ -135,6 +212,15 @@ fn render_access_section(cfg: &ProxyConfig, section: AccessSection) -> Result<St
                 .collect();
             serialize_table_body(&rows)?
         }
+        AccessSection::UserEnabled => {
+            let rows: BTreeMap<String, bool> = cfg
+                .access
+                .user_enabled
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
         AccessSection::UserAdTags => {
             let rows: BTreeMap<String, String> = cfg
                 .access
@@ -204,6 +290,7 @@ fn render_access_section(cfg: &ProxyConfig, section: AccessSection) -> Result<St
 fn access_section_is_empty(cfg: &ProxyConfig, section: AccessSection) -> bool {
     match section {
         AccessSection::Users => cfg.access.users.is_empty(),
+        AccessSection::UserEnabled => cfg.access.user_enabled.is_empty(),
         AccessSection::UserAdTags => cfg.access.user_ad_tags.is_empty(),
         AccessSection::UserMaxTcpConns => cfg.access.user_max_tcp_conns.is_empty(),
         AccessSection::UserExpirations => cfg.access.user_expirations.is_empty(),
@@ -261,17 +348,22 @@ fn upsert_toml_table(source: &str, table_name: &str, replacement: &str) -> Strin
 }
 
 fn find_toml_table_bounds(source: &str, table_name: &str) -> Option<(usize, usize)> {
-    let target = format!("[{}]", table_name);
+    let single = format!("[{}]", table_name);
+    let array = format!("[[{}]]", table_name);
     let mut offset = 0usize;
     let mut start = None;
 
     for line in source.split_inclusive('\n') {
-        let trimmed = line.trim();
+        // Drop any inline comment so a hand-edited header like
+        // `[censorship] # note` still matches. Section names never contain `#`.
+        let header = line.trim().split('#').next().unwrap_or("").trim();
         if let Some(start_offset) = start {
-            if trimmed.starts_with('[') {
+            let is_same_array = header == array;
+            let is_new_header = header.starts_with('[');
+            if is_new_header && !is_same_array {
                 return Some((start_offset, offset));
             }
-        } else if trimmed == target {
+        } else if header == single || header == array {
             start = Some(offset);
         }
         offset = offset.saturating_add(line.len());
@@ -324,6 +416,57 @@ fn write_atomic_sync(path: &Path, contents: &str) -> std::io::Result<()> {
 mod tests {
     use super::*;
 
+    #[tokio::test]
+    async fn save_sections_preserves_other_tables_and_comments() {
+        let dir = std::env::temp_dir().join(format!("cfgtest-{}", rand::random::<u64>()));
+        std::fs::create_dir_all(&dir).unwrap();
+        let path = dir.join("config.toml");
+        std::fs::write(
+            &path,
+            "# top comment\n[censorship]\ntls_domain = \"old.example\"\n\n[server]\nport = 443\n",
+        )
+        .unwrap();
+
+        let mut cfg = ProxyConfig::default();
+        cfg.censorship.tls_domain = "new.example".to_string();
+        cfg.server.port = 443;
+
+        let rev = save_sections_to_disk(&path, &cfg, &["censorship"])
+            .await
+            .unwrap();
+
+        let written = std::fs::read_to_string(&path).unwrap();
+        assert!(written.contains("tls_domain = \"new.example\""));
+        assert!(written.contains("# top comment")); // untouched comment kept
+        assert!(written.contains("[server]\nport = 443")); // untouched table kept
+        assert_eq!(rev, compute_revision(&written));
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn find_bounds_matches_array_of_tables() {
+        let src =
+            "[server]\nport = 1\n\n[[upstreams]]\nkind = \"a\"\n\n[[upstreams]]\nkind = \"b\"\n";
+        let bounds = find_toml_table_bounds(src, "upstreams");
+        assert!(bounds.is_some(), "should locate [[upstreams]] block start");
+        let (start, end) = bounds.unwrap();
+        let slice = &src[start..end];
+        assert!(slice.starts_with("[[upstreams]]"));
+        assert!(slice.contains("kind = \"b\"")); // spans through the last upstream block
+    }
+
+    #[test]
+    fn find_bounds_matches_header_with_inline_comment() {
+        let src = "[censorship] # notes\ntls_domain = \"a\"\n\n[server]\nport = 1\n";
+        let bounds = find_toml_table_bounds(src, "censorship");
+        assert!(bounds.is_some(), "commented header must still match");
+        let (start, end) = bounds.unwrap();
+        let slice = &src[start..end];
+        assert!(slice.starts_with("[censorship] # notes"));
+        assert!(slice.contains("tls_domain"));
+        assert!(!slice.contains("[server]")); // terminates at the next header
+    }
+
     #[test]
     fn render_user_rate_limits_section() {
         let mut cfg = ProxyConfig::default();

src/api/http_utils.rs

@@ -1,6 +1,7 @@
 use http_body_util::{BodyExt, Full};
 use hyper::StatusCode;
 use hyper::body::{Bytes, Incoming};
+use hyper::header::ALLOW;
 use serde::Serialize;
 use serde::de::DeserializeOwned;
 
@@ -25,6 +26,8 @@ pub(super) fn success_response<T: Serialize>(
 }
 
 pub(super) fn error_response(request_id: u64, failure: ApiFailure) -> hyper::Response<Full<Bytes>> {
+    let status = failure.status;
+    let allow = failure.allow;
     let payload = ErrorResponse {
         ok: false,
         error: ErrorBody {
@@ -40,11 +43,13 @@ pub(super) fn error_response(request_id: u64, failure: ApiFailure) -> hyper::Res
         )
         .into_bytes()
     });
-    hyper::Response::builder()
-        .status(failure.status)
-        .header("content-type", "application/json; charset=utf-8")
-        .body(Full::new(Bytes::from(body)))
-        .unwrap()
+    let mut builder = hyper::Response::builder()
+        .status(status)
+        .header("content-type", "application/json; charset=utf-8");
+    if let Some(allow) = allow {
+        builder = builder.header(ALLOW, allow);
+    }
+    builder.body(Full::new(Bytes::from(body))).unwrap()
 }
 
 pub(super) async fn read_json<T: DeserializeOwned>(

src/api/mod.rs

@@ -22,11 +22,13 @@ use tracing::{debug, info, warn};
 use crate::config::{ApiGrayAction, ProxyConfig};
 use crate::ip_tracker::UserIpTracker;
 use crate::proxy::route_mode::RouteRuntimeController;
+use crate::proxy::shared_state::ProxySharedState;
 use crate::startup::StartupTracker;
 use crate::stats::Stats;
 use crate::transport::UpstreamManager;
 use crate::transport::middle_proxy::MePool;
 
+mod config_edit;
 mod config_store;
 mod events;
 mod http_utils;
@@ -41,7 +43,9 @@ mod runtime_watch;
 mod runtime_zero;
 mod users;
 
-use config_store::{current_revision, load_config_from_disk, parse_if_match};
+use config_store::{
+    current_revision, ensure_expected_revision, load_config_from_disk, parse_if_match,
+};
 use events::ApiEventStore;
 use http_utils::{error_response, read_json, read_optional_json, success_response};
 use model::{
@@ -49,9 +53,10 @@ use model::{
     PatchUserRequest, ResetUserQuotaResponse, RotateSecretRequest, SummaryData, UserActiveIps,
     is_valid_username,
 };
+use patch::Patch;
 use runtime_edge::{
     EdgeConnectionsCacheEntry, build_runtime_connections_summary_data,
-    build_runtime_events_recent_data,
+    build_runtime_events_recent_data, build_runtime_tls_fingerprints_data,
 };
 use runtime_init::build_runtime_initialization_data;
 use runtime_min::{
@@ -69,12 +74,18 @@ use runtime_zero::{
     build_system_info_data,
 };
 use users::{
-    build_user_quota_list, create_user, delete_user, patch_user, rotate_secret, users_from_config,
+    build_user_quota_list, create_user, delete_user, patch_user, rotate_secret, set_user_enabled,
+    users_from_config,
 };
 
 const API_MAX_CONTROL_CONNECTIONS: usize = 1024;
 const API_HTTP_CONNECTION_TIMEOUT: Duration = Duration::from_secs(15);
 const ROUTE_USERNAME_ERROR: &str = "username must match [A-Za-z0-9_.-] and be 1..64 chars";
+const ALLOW_GET: &str = "GET";
+const ALLOW_POST: &str = "POST";
+const ALLOW_GET_POST: &str = "GET, POST";
+const ALLOW_GET_PATCH_DELETE: &str = "GET, PATCH, DELETE";
+const ALLOW_GET_PATCH: &str = "GET, PATCH";
 
 pub(super) struct ApiRuntimeState {
     pub(super) process_started_at_epoch_secs: u64,
@@ -101,6 +112,7 @@ pub(super) struct ApiShared {
     pub(super) runtime_state: Arc<ApiRuntimeState>,
     pub(super) startup_tracker: Arc<StartupTracker>,
     pub(super) route_runtime: Arc<RouteRuntimeController>,
+    pub(super) proxy_shared: Arc<ProxySharedState>,
 }
 
 impl ApiShared {
@@ -125,12 +137,68 @@ fn parse_route_username(user: &str) -> Result<&str, ApiFailure> {
     }
 }
 
+fn user_action_route_matches(path: &str, suffix: &str) -> bool {
+    path.strip_prefix("/v1/users/")
+        .and_then(|path| path.strip_suffix(suffix))
+        .map(|user| !user.is_empty() && !user.contains('/'))
+        .unwrap_or(false)
+}
+
+fn allowed_methods_for_path(path: &str) -> Option<&'static str> {
+    match path {
+        "/v1/health"
+        | "/v1/health/ready"
+        | "/v1/system/info"
+        | "/v1/runtime/gates"
+        | "/v1/runtime/initialization"
+        | "/v1/limits/effective"
+        | "/v1/security/posture"
+        | "/v1/security/whitelist"
+        | "/v1/stats/summary"
+        | "/v1/stats/zero/all"
+        | "/v1/stats/upstreams"
+        | "/v1/stats/minimal/all"
+        | "/v1/stats/me-writers"
+        | "/v1/stats/dcs"
+        | "/v1/runtime/me-pool-state"
+        | "/v1/runtime/me_pool_state"
+        | "/v1/runtime/me-quality"
+        | "/v1/runtime/me_quality"
+        | "/v1/runtime/upstream-quality"
+        | "/v1/runtime/upstream_quality"
+        | "/v1/runtime/nat-stun"
+        | "/v1/runtime/nat_stun"
+        | "/v1/runtime/me-selftest"
+        | "/v1/runtime/connections/summary"
+        | "/v1/runtime/events/recent"
+        | "/v1/runtime/tls-fingerprints"
+        | "/v1/stats/users/active-ips"
+        | "/v1/stats/users/quota"
+        | "/v1/stats/users" => Some(ALLOW_GET),
+        "/v1/users" => Some(ALLOW_GET_POST),
+        "/v1/config" => Some(ALLOW_GET_PATCH),
+        _ if user_action_route_matches(path, "/reset-quota") => Some(ALLOW_POST),
+        _ if user_action_route_matches(path, "/rotate-secret") => Some(ALLOW_POST),
+        _ if user_action_route_matches(path, "/enable") => Some(ALLOW_POST),
+        _ if user_action_route_matches(path, "/disable") => Some(ALLOW_POST),
+        _ if path
+            .strip_prefix("/v1/users/")
+            .map(|user| !user.is_empty() && !user.contains('/'))
+            .unwrap_or(false) =>
+        {
+            Some(ALLOW_GET_PATCH_DELETE)
+        }
+        _ => None,
+    }
+}
+
 pub async fn serve(
     listen: SocketAddr,
     stats: Arc<Stats>,
     ip_tracker: Arc<UserIpTracker>,
     me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
     route_runtime: Arc<RouteRuntimeController>,
+    proxy_shared: Arc<ProxySharedState>,
     upstream_manager: Arc<UpstreamManager>,
     config_rx: watch::Receiver<Arc<ProxyConfig>>,
     admission_rx: watch::Receiver<bool>,
@@ -180,6 +248,7 @@ pub async fn serve(
         runtime_state: runtime_state.clone(),
         startup_tracker,
         route_runtime,
+        proxy_shared,
     });
 
     spawn_runtime_watchers(
@@ -435,22 +504,22 @@ async fn handle(
                 let data = build_dcs_data(shared.as_ref(), api_cfg).await;
                 Ok(success_response(StatusCode::OK, data, revision))
             }
-            ("GET", "/v1/runtime/me_pool_state") => {
+            ("GET", "/v1/runtime/me-pool-state") | ("GET", "/v1/runtime/me_pool_state") => {
                 let revision = current_revision(&shared.config_path).await?;
                 let data = build_runtime_me_pool_state_data(shared.as_ref()).await;
                 Ok(success_response(StatusCode::OK, data, revision))
             }
-            ("GET", "/v1/runtime/me_quality") => {
+            ("GET", "/v1/runtime/me-quality") | ("GET", "/v1/runtime/me_quality") => {
                 let revision = current_revision(&shared.config_path).await?;
                 let data = build_runtime_me_quality_data(shared.as_ref()).await;
                 Ok(success_response(StatusCode::OK, data, revision))
             }
-            ("GET", "/v1/runtime/upstream_quality") => {
+            ("GET", "/v1/runtime/upstream-quality") | ("GET", "/v1/runtime/upstream_quality") => {
                 let revision = current_revision(&shared.config_path).await?;
                 let data = build_runtime_upstream_quality_data(shared.as_ref()).await;
                 Ok(success_response(StatusCode::OK, data, revision))
             }
-            ("GET", "/v1/runtime/nat_stun") => {
+            ("GET", "/v1/runtime/nat-stun") | ("GET", "/v1/runtime/nat_stun") => {
                 let revision = current_revision(&shared.config_path).await?;
                 let data = build_runtime_nat_stun_data(shared.as_ref()).await;
                 Ok(success_response(StatusCode::OK, data, revision))
@@ -475,6 +544,15 @@ async fn handle(
                 );
                 Ok(success_response(StatusCode::OK, data, revision))
             }
+            ("GET", "/v1/runtime/tls-fingerprints") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_runtime_tls_fingerprints_data(
+                    shared.as_ref(),
+                    cfg.as_ref(),
+                    query.as_deref(),
+                );
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
             ("GET", "/v1/stats/users/active-ips") => {
                 let revision = current_revision(&shared.config_path).await?;
                 let usernames: Vec<_> = cfg.access.users.keys().cloned().collect();
@@ -506,7 +584,7 @@ async fn handle(
                 .await;
                 Ok(success_response(StatusCode::OK, users, revision))
             }
-            ("GET", "/v1/users/quota") => {
+            ("GET", "/v1/stats/users/quota") => {
                 let revision = current_revision(&shared.config_path).await?;
                 let disk_cfg = load_config_from_disk(&shared.config_path).await?;
                 let data = build_user_quota_list(&disk_cfg, shared.stats.as_ref());
@@ -525,6 +603,7 @@ async fn handle(
                 }
                 let expected_revision = parse_if_match(req.headers());
                 let body = read_json::<CreateUserRequest>(req.into_body(), body_limit).await?;
+                let requested_enabled = body.enabled;
                 let result = create_user(body, expected_revision, &shared).await;
                 let (mut data, revision) = match result {
                     Ok(ok) => ok,
@@ -537,6 +616,25 @@ async fn handle(
                 };
                 let runtime_cfg = config_rx.borrow().clone();
                 data.user.in_runtime = runtime_cfg.access.users.contains_key(&data.user.username);
+                if let Some(enabled) = requested_enabled {
+                    shared
+                        .proxy_shared
+                        .set_user_enabled(&data.user.username, enabled);
+                    if !enabled {
+                        let cancelled = shared
+                            .proxy_shared
+                            .cancel_user_sessions(&data.user.username);
+                        if cancelled > 0 {
+                            shared.runtime_events.record(
+                                "api.user.disable.runtime",
+                                format!(
+                                    "username={} cancelled_sessions={}",
+                                    data.user.username, cancelled
+                                ),
+                            );
+                        }
+                    }
+                }
                 shared.runtime_events.record(
                     "api.user.create.ok",
                     format!("username={}", data.user.username),
@@ -548,7 +646,131 @@ async fn handle(
                 };
                 Ok(success_response(status, data, revision))
             }
+            ("GET", "/v1/config") => {
+                let (value, revision) =
+                    config_edit::read_managed_config(&shared.config_path).await?;
+                Ok(success_response(StatusCode::OK, value, revision))
+            }
+            ("PATCH", "/v1/config") => {
+                if api_cfg.read_only {
+                    return Ok(error_response(
+                        request_id,
+                        ApiFailure::new(
+                            StatusCode::FORBIDDEN,
+                            "read_only",
+                            "API runs in read-only mode",
+                        ),
+                    ));
+                }
+                let expected_revision = parse_if_match(req.headers());
+                let body = read_json::<serde_json::Value>(req.into_body(), body_limit).await?;
+                match config_edit::patch_config(body, expected_revision, &shared).await {
+                    Ok(resp) => {
+                        let revision = resp.revision.clone();
+                        Ok(success_response(StatusCode::OK, resp, revision))
+                    }
+                    Err(error) => {
+                        shared
+                            .runtime_events
+                            .record("api.config.patch.failed", error.code);
+                        Err(error)
+                    }
+                }
+            }
             _ => {
+                if method == Method::POST
+                    && let Some(base_user) = normalized_path
+                        .strip_prefix("/v1/users/")
+                        .and_then(|path| path.strip_suffix("/enable"))
+                    && !base_user.is_empty()
+                    && !base_user.contains('/')
+                {
+                    let base_user = parse_route_username(base_user)?;
+                    if api_cfg.read_only {
+                        return Ok(error_response(
+                            request_id,
+                            ApiFailure::new(
+                                StatusCode::FORBIDDEN,
+                                "read_only",
+                                "API runs in read-only mode",
+                            ),
+                        ));
+                    }
+                    let expected_revision = parse_if_match(req.headers());
+                    let result =
+                        set_user_enabled(base_user, true, expected_revision, &shared).await;
+                    let (mut data, revision) = match result {
+                        Ok(ok) => ok,
+                        Err(error) => {
+                            shared.runtime_events.record(
+                                "api.user.enable.failed",
+                                format!("username={} code={}", base_user, error.code),
+                            );
+                            return Err(error);
+                        }
+                    };
+                    let runtime_cfg = config_rx.borrow().clone();
+                    data.in_runtime = runtime_cfg.access.users.contains_key(&data.username);
+                    shared.proxy_shared.set_user_enabled(base_user, true);
+                    shared
+                        .runtime_events
+                        .record("api.user.enable.ok", format!("username={}", base_user));
+                    let status = if data.in_runtime {
+                        StatusCode::OK
+                    } else {
+                        StatusCode::ACCEPTED
+                    };
+                    return Ok(success_response(status, data, revision));
+                }
+                if method == Method::POST
+                    && let Some(base_user) = normalized_path
+                        .strip_prefix("/v1/users/")
+                        .and_then(|path| path.strip_suffix("/disable"))
+                    && !base_user.is_empty()
+                    && !base_user.contains('/')
+                {
+                    let base_user = parse_route_username(base_user)?;
+                    if api_cfg.read_only {
+                        return Ok(error_response(
+                            request_id,
+                            ApiFailure::new(
+                                StatusCode::FORBIDDEN,
+                                "read_only",
+                                "API runs in read-only mode",
+                            ),
+                        ));
+                    }
+                    let expected_revision = parse_if_match(req.headers());
+                    let result =
+                        set_user_enabled(base_user, false, expected_revision, &shared).await;
+                    let (mut data, revision) = match result {
+                        Ok(ok) => ok,
+                        Err(error) => {
+                            shared.runtime_events.record(
+                                "api.user.disable.failed",
+                                format!("username={} code={}", base_user, error.code),
+                            );
+                            return Err(error);
+                        }
+                    };
+                    let runtime_cfg = config_rx.borrow().clone();
+                    data.in_runtime = runtime_cfg.access.users.contains_key(&data.username);
+                    let newly_disabled = shared.proxy_shared.set_user_enabled(base_user, false);
+                    let cancelled = shared.proxy_shared.cancel_user_sessions(base_user);
+                    shared.runtime_events.record(
+                        "api.user.disable.ok",
+                        format!(
+                            "username={} newly_disabled={} cancelled_sessions={}",
+                            base_user, newly_disabled, cancelled
+                        ),
+                    );
+                    let status = if data.in_runtime {
+                        StatusCode::OK
+                    } else {
+                        StatusCode::ACCEPTED
+                    };
+                    return Ok(success_response(status, data, revision));
+                }
                 if method == Method::POST
                     && let Some(user) = normalized_path
                         .strip_prefix("/v1/users/")
@@ -567,6 +789,16 @@ async fn handle(
                             ),
                         ));
                     }
+                    let expected_revision = parse_if_match(req.headers());
+                    let disk_cfg = load_config_from_disk(&shared.config_path).await?;
+                    ensure_expected_revision(&shared.config_path, expected_revision.as_deref())
+                        .await?;
+                    if !disk_cfg.access.users.contains_key(user) {
+                        return Ok(error_response(
+                            request_id,
+                            ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "User not found"),
+                        ));
+                    }
                     let snapshot = match crate::quota_state::reset_user_quota(
                         &shared.quota_state_path,
                         shared.stats.as_ref(),
@@ -696,6 +928,11 @@ async fn handle(
                         let expected_revision = parse_if_match(req.headers());
                         let body =
                             read_json::<PatchUserRequest>(req.into_body(), body_limit).await?;
+                        let enabled_update = match &body.enabled {
+                            Patch::Unchanged => None,
+                            Patch::Remove => Some(true),
+                            Patch::Set(enabled) => Some(*enabled),
+                        };
                         let result = patch_user(user, body, expected_revision, &shared).await;
                         let (mut data, revision) = match result {
                             Ok(ok) => ok,
@@ -709,6 +946,22 @@ async fn handle(
                         };
                         let runtime_cfg = config_rx.borrow().clone();
                         data.in_runtime = runtime_cfg.access.users.contains_key(&data.username);
+                        if let Some(enabled) = enabled_update {
+                            shared
+                                .proxy_shared
+                                .set_user_enabled(&data.username, enabled);
+                            if !enabled {
+                                let cancelled =
+                                    shared.proxy_shared.cancel_user_sessions(&data.username);
+                                shared.runtime_events.record(
+                                    "api.user.disable.runtime",
+                                    format!(
+                                        "username={} cancelled_sessions={}",
+                                        data.username, cancelled
+                                    ),
+                                );
+                            }
+                        }
                         shared
                             .runtime_events
                             .record("api.user.patch.ok", format!("username={}", data.username));
@@ -742,9 +995,12 @@ async fn handle(
                                 return Err(error);
                             }
                         };
-                        shared
-                            .runtime_events
-                            .record("api.user.delete.ok", format!("username={}", deleted_user));
+                        shared.proxy_shared.set_user_enabled(&deleted_user, true);
+                        let cancelled = shared.proxy_shared.cancel_user_sessions(&deleted_user);
+                        shared.runtime_events.record(
+                            "api.user.delete.ok",
+                            format!("username={} cancelled_sessions={}", deleted_user, cancelled),
+                        );
                         let runtime_cfg = config_rx.borrow().clone();
                         let in_runtime = runtime_cfg.access.users.contains_key(&deleted_user);
                         let response = DeleteUserResponse {
@@ -761,16 +1017,18 @@ async fn handle(
                     if method == Method::POST {
                         return Ok(error_response(
                             request_id,
-                            ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "Route not found"),
+                            ApiFailure::method_not_allowed(ALLOW_GET_PATCH_DELETE),
                         ));
                     }
                     return Ok(error_response(
                         request_id,
-                        ApiFailure::new(
-                            StatusCode::METHOD_NOT_ALLOWED,
-                            "method_not_allowed",
-                            "Unsupported HTTP method for this route",
-                        ),
+                        ApiFailure::method_not_allowed(ALLOW_GET_PATCH_DELETE),
+                    ));
+                }
+                if let Some(allow) = allowed_methods_for_path(normalized_path) {
+                    return Ok(error_response(
+                        request_id,
+                        ApiFailure::method_not_allowed(allow),
                     ));
                 }
                 debug!(

src/api/model.rs

@@ -15,6 +15,7 @@ pub(super) struct ApiFailure {
     pub(super) status: StatusCode,
     pub(super) code: &'static str,
     pub(super) message: String,
+    pub(super) allow: Option<&'static str>,
 }
 
 impl ApiFailure {
@@ -23,6 +24,7 @@ impl ApiFailure {
             status,
             code,
             message: message.into(),
+            allow: None,
         }
     }
 
@@ -33,6 +35,15 @@ impl ApiFailure {
     pub(super) fn bad_request(message: impl Into<String>) -> Self {
         Self::new(StatusCode::BAD_REQUEST, "bad_request", message)
     }
+
+    pub(super) fn method_not_allowed(allow: &'static str) -> Self {
+        Self {
+            status: StatusCode::METHOD_NOT_ALLOWED,
+            code: "method_not_allowed",
+            message: "Unsupported HTTP method for this route".to_string(),
+            allow: Some(allow),
+        }
+    }
 }
 
 #[derive(Serialize)]
@@ -468,6 +479,7 @@ pub(super) struct TlsDomainLink {
 #[derive(Serialize)]
 pub(super) struct UserInfo {
     pub(super) username: String,
+    pub(super) enabled: bool,
     pub(super) in_runtime: bool,
     pub(super) user_ad_tag: Option<String>,
     pub(super) max_tcp_conns: Option<usize>,
@@ -534,6 +546,7 @@ pub(super) struct CreateUserRequest {
     pub(super) rate_limit_up_bps: Option<u64>,
     pub(super) rate_limit_down_bps: Option<u64>,
     pub(super) max_unique_ips: Option<usize>,
+    pub(super) enabled: Option<bool>,
 }
 
 #[derive(Deserialize)]
@@ -553,6 +566,8 @@ pub(super) struct PatchUserRequest {
     pub(super) rate_limit_down_bps: Patch<u64>,
     #[serde(default, deserialize_with = "patch_field")]
     pub(super) max_unique_ips: Patch<usize>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) enabled: Patch<bool>,
 }
 
 #[derive(Default, Deserialize)]

src/api/runtime_edge.rs

@@ -12,6 +12,8 @@ const FEATURE_DISABLED_REASON: &str = "feature_disabled";
 const SOURCE_UNAVAILABLE_REASON: &str = "source_unavailable";
 const EVENTS_DEFAULT_LIMIT: usize = 50;
 const EVENTS_MAX_LIMIT: usize = 1000;
+const TLS_FINGERPRINTS_MAX_LIMIT: usize = 1000;
+const RUNTIME_EDGE_RETENTION_MAX_MINUTES: u64 = 24 * 60;
 
 #[derive(Clone, Serialize)]
 pub(super) struct RuntimeEdgeConnectionUserData {
@@ -90,6 +92,44 @@ pub(super) struct RuntimeEdgeEventsData {
     pub(super) data: Option<RuntimeEdgeEventsPayload>,
 }
 
+#[derive(Serialize)]
+pub(super) struct RuntimeEdgeTlsFingerprintRow {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) scope: Option<String>,
+    pub(super) ja3: String,
+    pub(super) ja3_raw: String,
+    pub(super) ja4: String,
+    pub(super) ja4_raw: String,
+    pub(super) total: u64,
+    pub(super) auth_success: u64,
+    pub(super) bad_or_probe: u64,
+    pub(super) first_seen_epoch_secs: u64,
+    pub(super) last_seen_epoch_secs: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeEdgeTlsFingerprintsPayload {
+    pub(super) limit: usize,
+    pub(super) retention_secs: u64,
+    pub(super) capacity: usize,
+    pub(super) dropped_total: u64,
+    pub(super) parse_error_total: u64,
+    pub(super) by_fingerprint: Vec<RuntimeEdgeTlsFingerprintRow>,
+    pub(super) by_ip: Vec<RuntimeEdgeTlsFingerprintRow>,
+    pub(super) by_cidr: Vec<RuntimeEdgeTlsFingerprintRow>,
+    pub(super) by_user: Vec<RuntimeEdgeTlsFingerprintRow>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeEdgeTlsFingerprintsData {
+    pub(super) enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) data: Option<RuntimeEdgeTlsFingerprintsPayload>,
+}
+
 pub(super) async fn build_runtime_connections_summary_data(
     shared: &ApiShared,
     cfg: &ProxyConfig,
@@ -162,6 +202,65 @@ pub(super) fn build_runtime_events_recent_data(
     }
 }
 
+pub(super) fn build_runtime_tls_fingerprints_data(
+    shared: &ApiShared,
+    cfg: &ProxyConfig,
+    query: Option<&str>,
+) -> RuntimeEdgeTlsFingerprintsData {
+    let now_epoch_secs = now_epoch_secs();
+    let api_cfg = &cfg.server.api;
+    if !api_cfg.runtime_edge_enabled {
+        return RuntimeEdgeTlsFingerprintsData {
+            enabled: false,
+            reason: Some(FEATURE_DISABLED_REASON),
+            generated_at_epoch_secs: now_epoch_secs,
+            data: None,
+        };
+    }
+
+    let limit = parse_recent_events_limit(
+        query,
+        api_cfg.runtime_edge_top_n.max(1),
+        TLS_FINGERPRINTS_MAX_LIMIT,
+    );
+    let snapshot = shared
+        .stats
+        .tls_fingerprint_snapshot(runtime_edge_retention(cfg), limit);
+
+    RuntimeEdgeTlsFingerprintsData {
+        enabled: true,
+        reason: None,
+        generated_at_epoch_secs: now_epoch_secs,
+        data: Some(RuntimeEdgeTlsFingerprintsPayload {
+            limit,
+            retention_secs: snapshot.retention_secs,
+            capacity: snapshot.capacity,
+            dropped_total: snapshot.dropped_total,
+            parse_error_total: snapshot.parse_error_total,
+            by_fingerprint: snapshot
+                .by_fingerprint
+                .into_iter()
+                .map(runtime_tls_fingerprint_row)
+                .collect(),
+            by_ip: snapshot
+                .by_ip
+                .into_iter()
+                .map(runtime_tls_fingerprint_row)
+                .collect(),
+            by_cidr: snapshot
+                .by_cidr
+                .into_iter()
+                .map(runtime_tls_fingerprint_row)
+                .collect(),
+            by_user: snapshot
+                .by_user
+                .into_iter()
+                .map(runtime_tls_fingerprint_row)
+                .collect(),
+        }),
+    }
+}
+
 async fn get_connections_payload_cached(
     shared: &ApiShared,
     cache_ttl_ms: u64,
@@ -286,6 +385,35 @@ fn parse_recent_events_limit(query: Option<&str>, default_limit: usize, max_limi
     default_limit
 }
 
+fn runtime_edge_retention(cfg: &ProxyConfig) -> Duration {
+    let minutes = cfg
+        .general
+        .beobachten_minutes
+        .clamp(1, RUNTIME_EDGE_RETENTION_MAX_MINUTES);
+    Duration::from_secs(minutes.saturating_mul(60))
+}
+
+fn runtime_tls_fingerprint_row(
+    row: crate::stats::TlsFingerprintSnapshotRow,
+) -> RuntimeEdgeTlsFingerprintRow {
+    RuntimeEdgeTlsFingerprintRow {
+        scope: if row.scope_key.is_empty() {
+            None
+        } else {
+            Some(row.scope_key)
+        },
+        ja3: row.ja3,
+        ja3_raw: row.ja3_raw,
+        ja4: row.ja4,
+        ja4_raw: row.ja4_raw,
+        total: row.total,
+        auth_success: row.auth_success,
+        bad_or_probe: row.bad_or_probe,
+        first_seen_epoch_secs: row.first_seen_epoch_secs,
+        last_seen_epoch_secs: row.last_seen_epoch_secs,
+    }
+}
+
 fn now_epoch_secs() -> u64 {
     SystemTime::now()
         .duration_since(UNIX_EPOCH)

src/api/users.rs

@@ -32,6 +32,7 @@ pub(super) async fn create_user(
     let touches_user_rate_limits =
         body.rate_limit_up_bps.is_some() || body.rate_limit_down_bps.is_some();
     let touches_user_max_unique_ips = body.max_unique_ips.is_some();
+    let touches_user_enabled = matches!(body.enabled, Some(false));
 
     if !is_valid_username(&body.username) {
         return Err(ApiFailure::bad_request(
@@ -111,6 +112,9 @@ pub(super) async fn create_user(
             .user_max_unique_ips
             .insert(body.username.clone(), limit);
     }
+    if matches!(body.enabled, Some(false)) {
+        cfg.access.user_enabled.insert(body.username.clone(), false);
+    }
 
     cfg.validate()
         .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
@@ -134,6 +138,9 @@ pub(super) async fn create_user(
     if touches_user_max_unique_ips {
         touched_sections.push(AccessSection::UserMaxUniqueIps);
     }
+    if touches_user_enabled {
+        touched_sections.push(AccessSection::UserEnabled);
+    }
 
     let revision =
         save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
@@ -161,6 +168,7 @@ pub(super) async fn create_user(
         .find(|entry| entry.username == body.username)
         .unwrap_or(UserInfo {
             username: body.username.clone(),
+            enabled: cfg.access.is_user_enabled(&body.username),
             in_runtime: false,
             user_ad_tag: None,
             max_tcp_conns: cfg
@@ -202,6 +210,7 @@ pub(super) async fn patch_user(
     let touches_user_rate_limits = !matches!(&body.rate_limit_up_bps, Patch::Unchanged)
         || !matches!(&body.rate_limit_down_bps, Patch::Unchanged);
     let touches_user_max_unique_ips = !matches!(&body.max_unique_ips, Patch::Unchanged);
+    let touches_user_enabled = !matches!(&body.enabled, Patch::Unchanged);
 
     if let Some(secret) = body.secret.as_ref()
         && !is_valid_user_secret(secret)
@@ -313,6 +322,15 @@ pub(super) async fn patch_user(
             Some(Some(limit))
         }
     };
+    match body.enabled {
+        Patch::Unchanged => {}
+        Patch::Remove | Patch::Set(true) => {
+            cfg.access.user_enabled.remove(user);
+        }
+        Patch::Set(false) => {
+            cfg.access.user_enabled.insert(user.to_string(), false);
+        }
+    }
 
     cfg.validate()
         .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
@@ -339,6 +357,9 @@ pub(super) async fn patch_user(
     if touches_user_max_unique_ips {
         touched_sections.push(AccessSection::UserMaxUniqueIps);
     }
+    if touches_user_enabled {
+        touched_sections.push(AccessSection::UserEnabled);
+    }
 
     let revision = if touched_sections.is_empty() {
         current_revision(&shared.config_path).await?
@@ -399,6 +420,7 @@ pub(super) async fn rotate_secret(
         .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
     let touched_sections = [
         AccessSection::Users,
+        AccessSection::UserEnabled,
         AccessSection::UserAdTags,
         AccessSection::UserMaxTcpConns,
         AccessSection::UserExpirations,
@@ -434,6 +456,55 @@ pub(super) async fn rotate_secret(
     ))
 }
 
+pub(super) async fn set_user_enabled(
+    user: &str,
+    enabled: bool,
+    expected_revision: Option<String>,
+    shared: &ApiShared,
+) -> Result<(UserInfo, String), ApiFailure> {
+    let _guard = shared.mutation_lock.lock().await;
+    let mut cfg = load_config_from_disk(&shared.config_path).await?;
+    ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
+
+    if !cfg.access.users.contains_key(user) {
+        return Err(ApiFailure::new(
+            StatusCode::NOT_FOUND,
+            "not_found",
+            "User not found",
+        ));
+    }
+
+    if enabled {
+        cfg.access.user_enabled.remove(user);
+    } else {
+        cfg.access.user_enabled.insert(user.to_string(), false);
+    }
+
+    cfg.validate()
+        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
+    let revision =
+        save_access_sections_to_disk(&shared.config_path, &cfg, &[AccessSection::UserEnabled])
+            .await?;
+    drop(_guard);
+
+    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
+    let users = users_from_config(
+        &cfg,
+        &shared.stats,
+        &shared.ip_tracker,
+        detected_ip_v4,
+        detected_ip_v6,
+        None,
+    )
+    .await;
+    let user_info = users
+        .into_iter()
+        .find(|entry| entry.username == user)
+        .ok_or_else(|| ApiFailure::internal("failed to build updated user view"))?;
+
+    Ok((user_info, revision))
+}
+
 pub(super) async fn delete_user(
     user: &str,
     expected_revision: Option<String>,
@@ -459,6 +530,7 @@ pub(super) async fn delete_user(
     }
 
     cfg.access.users.remove(user);
+    cfg.access.user_enabled.remove(user);
     cfg.access.user_ad_tags.remove(user);
     cfg.access.user_max_tcp_conns.remove(user);
     cfg.access.user_expirations.remove(user);
@@ -470,6 +542,7 @@ pub(super) async fn delete_user(
         .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
     let touched_sections = [
         AccessSection::Users,
+        AccessSection::UserEnabled,
         AccessSection::UserAdTags,
         AccessSection::UserMaxTcpConns,
         AccessSection::UserExpirations,
@@ -518,6 +591,7 @@ pub(super) async fn users_from_config(
             })
             .unwrap_or_else(empty_user_links);
         users.push(UserInfo {
+            enabled: cfg.access.is_user_enabled(&username),
             in_runtime: runtime_cfg
                 .map(|runtime| runtime.access.users.contains_key(&username))
                 .unwrap_or(false),
@@ -876,6 +950,43 @@ mod tests {
         assert_eq!(alice.rate_limit_down_bps, None);
     }
 
+    #[tokio::test]
+    async fn users_from_config_reports_user_enabled_default_and_override() {
+        let mut cfg = ProxyConfig::default();
+        cfg.access.users.insert(
+            "alice".to_string(),
+            "0123456789abcdef0123456789abcdef".to_string(),
+        );
+        cfg.access.users.insert(
+            "bob".to_string(),
+            "fedcba9876543210fedcba9876543210".to_string(),
+        );
+        cfg.access.user_enabled.insert("bob".to_string(), false);
+
+        let stats = Stats::new();
+        let tracker = UserIpTracker::new();
+        let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+        let alice = users
+            .iter()
+            .find(|entry| entry.username == "alice")
+            .expect("alice must be present");
+        let bob = users
+            .iter()
+            .find(|entry| entry.username == "bob")
+            .expect("bob must be present");
+
+        assert!(alice.enabled);
+        assert!(!bob.enabled);
+
+        cfg.access.user_enabled.insert("bob".to_string(), true);
+        let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+        let bob = users
+            .iter()
+            .find(|entry| entry.username == "bob")
+            .expect("bob must be present");
+        assert!(bob.enabled);
+    }
+
     #[tokio::test]
     async fn users_from_config_marks_runtime_membership_when_snapshot_is_provided() {
         let mut disk_cfg = ProxyConfig::default();

src/cli.rs

@@ -705,6 +705,9 @@ ignore_time_skew = false
 type = "direct"
 enabled = true
 weight = 10
+# Optional per-upstream DC family policy:
+# ipv6 = true
+# prefer = 6
 "#,
         username = username,
         secret = secret,

src/config/defaults.rs

@@ -54,6 +54,9 @@ const DEFAULT_CONNTRACK_CONTROL_ENABLED: bool = true;
 const DEFAULT_CONNTRACK_PRESSURE_HIGH_WATERMARK_PCT: u8 = 85;
 const DEFAULT_CONNTRACK_PRESSURE_LOW_WATERMARK_PCT: u8 = 70;
 const DEFAULT_CONNTRACK_DELETE_BUDGET_PER_SEC: u64 = 4096;
+const DEFAULT_SYNLIMIT_SECONDS: u32 = 1;
+const DEFAULT_SYNLIMIT_HITCOUNT: u32 = 1;
+const DEFAULT_SYNLIMIT_BURST: u32 = 2;
 const DEFAULT_UPSTREAM_CONNECT_RETRY_ATTEMPTS: u32 = 2;
 const DEFAULT_UPSTREAM_UNHEALTHY_FAIL_THRESHOLD: u32 = 5;
 const DEFAULT_UPSTREAM_CONNECT_BUDGET_MS: u64 = 3000;
@@ -243,6 +246,18 @@ pub(crate) fn default_conntrack_delete_budget_per_sec() -> u64 {
     DEFAULT_CONNTRACK_DELETE_BUDGET_PER_SEC
 }
 
+pub(crate) fn default_synlimit_seconds() -> u32 {
+    DEFAULT_SYNLIMIT_SECONDS
+}
+
+pub(crate) fn default_synlimit_hitcount() -> u32 {
+    DEFAULT_SYNLIMIT_HITCOUNT
+}
+
+pub(crate) fn default_synlimit_burst() -> u32 {
+    DEFAULT_SYNLIMIT_BURST
+}
+
 pub(crate) fn default_prefer_4() -> u8 {
     4
 }

src/config/hot_reload.rs

@@ -16,10 +16,12 @@
 //! | `general` | `telemetry` / `me_*_policy`    | Applied immediately                            |
 //! | `network` | `dns_overrides`                | Applied immediately                            |
 //! | `access`  | All user/quota fields          | Effective immediately                          |
+//! | `server.listeners` | `synlimit*` for existing endpoints | Netfilter rules reconciled immediately |
 //!
 //! Fields that require re-binding sockets (`server.listeners`, legacy
 //! `server.port`, `censorship.*`, `network.*`, `use_middle_proxy`) are **not**
-//! applied; a warning is emitted.
+//! applied, except for SYN limiter fields on unchanged listener endpoints; a
+//! warning is emitted.
 //! Non-hot changes are never mixed into the runtime config snapshot.
 
 use std::collections::BTreeSet;
@@ -34,7 +36,8 @@ use tracing::{error, info, warn};
 
 use super::load::{LoadedConfig, ProxyConfig};
 use crate::config::{
-    LogLevel, MeBindStaleMode, MeFloorMode, MeSocksKdfPolicy, MeTelemetryLevel, MeWriterPickMode,
+    ListenerConfig, LogLevel, MeBindStaleMode, MeFloorMode, MeSocksKdfPolicy, MeTelemetryLevel,
+    MeWriterPickMode, SynLimitMode,
 };
 
 const HOT_RELOAD_DEBOUNCE: Duration = Duration::from_millis(50);
@@ -118,6 +121,7 @@ pub struct HotFields {
     pub me_admission_poll_ms: u64,
     pub me_warn_rate_limit_ms: u64,
     pub users: std::collections::HashMap<String, String>,
+    pub user_enabled: std::collections::HashMap<String, bool>,
     pub user_ad_tags: std::collections::HashMap<String, String>,
     pub user_max_tcp_conns: std::collections::HashMap<String, usize>,
     pub user_max_tcp_conns_global_each: usize,
@@ -130,6 +134,17 @@ pub struct HotFields {
     pub user_max_unique_ips_global_each: usize,
     pub user_max_unique_ips_mode: crate::config::UserMaxUniqueIpsMode,
     pub user_max_unique_ips_window_secs: u64,
+    pub listener_synlimit: Vec<ListenerSynLimitHotFields>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ListenerSynLimitHotFields {
+    pub ip: IpAddr,
+    pub port: Option<u16>,
+    pub synlimit: SynLimitMode,
+    pub synlimit_seconds: u32,
+    pub synlimit_hitcount: u32,
+    pub synlimit_burst: u32,
 }
 
 impl HotFields {
@@ -247,6 +262,7 @@ impl HotFields {
             me_admission_poll_ms: cfg.general.me_admission_poll_ms,
             me_warn_rate_limit_ms: cfg.general.me_warn_rate_limit_ms,
             users: cfg.access.users.clone(),
+            user_enabled: cfg.access.user_enabled.clone(),
             user_ad_tags: cfg.access.user_ad_tags.clone(),
             user_max_tcp_conns: cfg.access.user_max_tcp_conns.clone(),
             user_max_tcp_conns_global_each: cfg.access.user_max_tcp_conns_global_each,
@@ -258,6 +274,25 @@ impl HotFields {
             user_max_unique_ips_global_each: cfg.access.user_max_unique_ips_global_each,
             user_max_unique_ips_mode: cfg.access.user_max_unique_ips_mode,
             user_max_unique_ips_window_secs: cfg.access.user_max_unique_ips_window_secs,
+            listener_synlimit: cfg
+                .server
+                .listeners
+                .iter()
+                .map(ListenerSynLimitHotFields::from_listener)
+                .collect(),
+        }
+    }
+}
+
+impl ListenerSynLimitHotFields {
+    fn from_listener(listener: &ListenerConfig) -> Self {
+        Self {
+            ip: listener.ip,
+            port: listener.port,
+            synlimit: listener.synlimit,
+            synlimit_seconds: listener.synlimit_seconds,
+            synlimit_hitcount: listener.synlimit_hitcount,
+            synlimit_burst: listener.synlimit_burst,
         }
     }
 }
@@ -310,6 +345,7 @@ fn listeners_equal(
     lhs.iter().zip(rhs.iter()).all(|(a, b)| {
         a.ip == b.ip
             && a.port == b.port
+            && a.client_mss == b.client_mss
             && a.announce == b.announce
             && a.announce_ip == b.announce_ip
             && a.proxy_protocol == b.proxy_protocol
@@ -551,6 +587,7 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
     cfg.general.me_warn_rate_limit_ms = new.general.me_warn_rate_limit_ms;
 
     cfg.access.users = new.access.users.clone();
+    cfg.access.user_enabled = new.access.user_enabled.clone();
     cfg.access.user_ad_tags = new.access.user_ad_tags.clone();
     cfg.access.user_max_tcp_conns = new.access.user_max_tcp_conns.clone();
     cfg.access.user_max_tcp_conns_global_each = new.access.user_max_tcp_conns_global_each;
@@ -562,6 +599,7 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
     cfg.access.user_max_unique_ips_global_each = new.access.user_max_unique_ips_global_each;
     cfg.access.user_max_unique_ips_mode = new.access.user_max_unique_ips_mode;
     cfg.access.user_max_unique_ips_window_secs = new.access.user_max_unique_ips_window_secs;
+    overlay_listener_synlimit_fields(&mut cfg.server.listeners, &new.server.listeners);
 
     if cfg.rebuild_runtime_user_auth().is_err() {
         cfg.runtime_user_auth = None;
@@ -570,6 +608,21 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
     cfg
 }
 
+fn overlay_listener_synlimit_fields(old: &mut [ListenerConfig], new: &[ListenerConfig]) {
+    if old.len() != new.len() {
+        return;
+    }
+    for (old_listener, new_listener) in old.iter_mut().zip(new.iter()) {
+        if old_listener.ip != new_listener.ip || old_listener.port != new_listener.port {
+            continue;
+        }
+        old_listener.synlimit = new_listener.synlimit;
+        old_listener.synlimit_seconds = new_listener.synlimit_seconds;
+        old_listener.synlimit_hitcount = new_listener.synlimit_hitcount;
+        old_listener.synlimit_burst = new_listener.synlimit_burst;
+    }
+}
+
 /// Warn if any non-hot fields changed (require restart).
 fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: bool) {
     let mut warned = false;
@@ -605,6 +658,7 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
         || old.server.listen_addr_ipv4 != new.server.listen_addr_ipv4
         || old.server.listen_addr_ipv6 != new.server.listen_addr_ipv6
         || old.server.listen_tcp != new.server.listen_tcp
+        || old.server.client_mss != new.server.client_mss
         || old.server.listen_unix_sock != new.server.listen_unix_sock
         || old.server.listen_unix_sock_perm != new.server.listen_unix_sock_perm
     {
@@ -615,6 +669,7 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
         || old.censorship.tls_domains != new.censorship.tls_domains
         || old.censorship.tls_fetch_scope != new.censorship.tls_fetch_scope
         || old.censorship.mask != new.censorship.mask
+        || old.censorship.mask_dynamic != new.censorship.mask_dynamic
         || old.censorship.mask_host != new.censorship.mask_host
         || old.censorship.mask_port != new.censorship.mask_port
         || old.censorship.exclusive_mask != new.censorship.exclusive_mask
@@ -844,6 +899,13 @@ fn log_changes(
         );
     }
 
+    if old_hot.listener_synlimit != new_hot.listener_synlimit {
+        info!(
+            "config reload: server.listeners SYN limiter updated ({} listeners)",
+            new_hot.listener_synlimit.len()
+        );
+    }
+
     if old_hot.desync_all_full != new_hot.desync_all_full {
         info!(
             "config reload: desync_all_full: {} → {}",
@@ -1178,6 +1240,16 @@ fn log_changes(
         }
     }
 
+    if old_hot.user_enabled != new_hot.user_enabled {
+        info!(
+            "config reload: user_enabled updated ({} disabled overrides)",
+            new_hot
+                .user_enabled
+                .values()
+                .filter(|enabled| !**enabled)
+                .count()
+        );
+    }
     if old_hot.user_max_tcp_conns != new_hot.user_max_tcp_conns {
         info!(
             "config reload: user_max_tcp_conns updated ({} entries)",
@@ -1474,6 +1546,48 @@ pub fn spawn_config_watcher(
     (config_rx, log_rx)
 }
 
+// ── Change classification ─────────────────────────────────────────────────────
+
+/// Which top-level config sections changed and whether any require a restart.
+#[derive(Debug, Default, Clone, serde::Serialize)]
+pub struct ChangeClassification {
+    pub changed: Vec<String>,
+    pub restart_required: bool,
+}
+
+/// Classify old->new using Telemt's OWN reload rule: overlay the hot fields and
+/// see if anything non-hot remains different. This guarantees `restart_required`
+/// matches actual runtime behavior and never drifts as new fields are added.
+pub fn classify_config_changes(old: &ProxyConfig, new: &ProxyConfig) -> ChangeClassification {
+    let applied = overlay_hot_fields(old, new);
+    let restart_required = !config_equal(&applied, new);
+    ChangeClassification {
+        changed: changed_sections(old, new),
+        restart_required,
+    }
+}
+
+/// Top-level config sections whose canonical serialized form differs between
+/// old and new. Uses the same serialize+canonicalize path as `config_equal`.
+fn changed_sections(old: &ProxyConfig, new: &ProxyConfig) -> Vec<String> {
+    let mut lhs = serde_json::to_value(old).unwrap_or(serde_json::Value::Null);
+    let mut rhs = serde_json::to_value(new).unwrap_or(serde_json::Value::Null);
+    canonicalize_json(&mut lhs);
+    canonicalize_json(&mut rhs);
+
+    let mut out = Vec::new();
+    if let (Some(lo), Some(ro)) = (lhs.as_object(), rhs.as_object()) {
+        let mut keys: std::collections::BTreeSet<&String> = lo.keys().collect();
+        keys.extend(ro.keys());
+        for key in keys {
+            if lo.get(key) != ro.get(key) {
+                out.push(key.clone());
+            }
+        }
+    }
+    out
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -1646,6 +1760,41 @@ mod tests {
         let _ = std::fs::remove_file(path);
     }
 
+    #[test]
+    fn classify_sni_change_requires_restart() {
+        // censorship.* is not in overlay_hot_fields -> restart.
+        let old = ProxyConfig::default();
+        let mut new = ProxyConfig::default();
+        new.censorship.tls_domain = "front.example".to_string();
+
+        let class = classify_config_changes(&old, &new);
+        assert!(class.restart_required);
+        assert!(class.changed.iter().any(|c| c == "censorship"));
+    }
+
+    #[test]
+    fn classify_dns_overrides_change_is_hot() {
+        // network.dns_overrides IS in overlay_hot_fields -> no restart.
+        let old = ProxyConfig::default();
+        let mut new = ProxyConfig::default();
+        new.network.dns_overrides.push("1.1.1.1".to_string());
+
+        let class = classify_config_changes(&old, &new);
+        assert!(!class.restart_required);
+        assert!(class.changed.iter().any(|c| c == "network"));
+    }
+
+    #[test]
+    fn classify_timeouts_change_requires_restart() {
+        // timeouts.* is NOT in overlay_hot_fields -> restart.
+        let old = ProxyConfig::default();
+        let mut new = ProxyConfig::default();
+        new.timeouts.client_handshake = old.timeouts.client_handshake + 1;
+
+        let class = classify_config_changes(&old, &new);
+        assert!(class.restart_required);
+    }
+
     #[test]
     fn reload_recovers_after_parse_error_on_next_attempt() {
         let initial_tag = "cccccccccccccccccccccccccccccccc";

src/config/load.rs

@@ -57,7 +57,10 @@ fn normalize_mask_host_to_ascii(host: &str, field: &str) -> Result<String> {
     if host.starts_with('[') && host.ends_with(']') {
         let inner = &host[1..host.len() - 1];
         let ip = inner.parse::<std::net::IpAddr>().map_err(|_| {
-            ProxyError::Config(format!("Invalid {field}: '{}'. IPv6 literal is invalid", host))
+            ProxyError::Config(format!(
+                "Invalid {field}: '{}'. IPv6 literal is invalid",
+                host
+            ))
         })?;
         return match ip {
             std::net::IpAddr::V6(v6) => Ok(format!("[{v6}]")),
@@ -296,6 +299,7 @@ const SERVER_CONFIG_KEYS: &[&str] = &[
     "listen_unix_sock",
     "listen_unix_sock_perm",
     "listen_tcp",
+    "client_mss",
     "proxy_protocol",
     "proxy_protocol_header_timeout_ms",
     "proxy_protocol_trusted_cidrs",
@@ -341,6 +345,11 @@ const CONNTRACK_CONTROL_CONFIG_KEYS: &[&str] = &[
 const LISTENER_CONFIG_KEYS: &[&str] = &[
     "ip",
     "port",
+    "client_mss",
+    "synlimit",
+    "synlimit_seconds",
+    "synlimit_hitcount",
+    "synlimit_burst",
     "announce",
     "announce_ip",
     "proxy_protocol",
@@ -367,6 +376,7 @@ const CENSORSHIP_CONFIG_KEYS: &[&str] = &[
     "tls_fetch_scope",
     "tls_fetch",
     "mask",
+    "mask_dynamic",
     "mask_host",
     "mask_port",
     "exclusive_mask",
@@ -408,6 +418,7 @@ const TLS_FETCH_CONFIG_KEYS: &[&str] = &[
 
 const ACCESS_CONFIG_KEYS: &[&str] = &[
     "users",
+    "user_enabled",
     "user_ad_tags",
     "user_max_tcp_conns",
     "user_max_tcp_conns_global_each",
@@ -1003,6 +1014,14 @@ fn validate_upstreams(config: &ProxyConfig) -> Result<()> {
                 "upstream.ipv4 and upstream.ipv6 cannot both be false".to_string(),
             ));
         }
+        if let Some(prefer) = upstream.prefer
+            && prefer != 4
+            && prefer != 6
+        {
+            return Err(ProxyError::Config(
+                "upstream.prefer must be 4 or 6".to_string(),
+            ));
+        }
 
         if let UpstreamType::Shadowsocks { url, .. } = &upstream.upstream_type {
             let parsed = ShadowsocksServerConfig::from_url(url)
@@ -1018,6 +1037,26 @@ fn validate_upstreams(config: &ProxyConfig) -> Result<()> {
     Ok(())
 }
 
+fn normalize_upstream_family_policy(config: &mut ProxyConfig) {
+    for (idx, upstream) in config.upstreams.iter_mut().enumerate() {
+        if matches!(upstream.ipv4, Some(false)) && upstream.prefer == Some(4) {
+            warn!(
+                upstream = idx,
+                "upstream.prefer=4 but upstream.ipv4=false; forcing prefer=6"
+            );
+            upstream.prefer = Some(6);
+        }
+
+        if matches!(upstream.ipv6, Some(false)) && upstream.prefer == Some(6) {
+            warn!(
+                upstream = idx,
+                "upstream.prefer=6 but upstream.ipv6=false; forcing prefer=4"
+            );
+            upstream.prefer = Some(4);
+        }
+    }
+}
+
 // ============= Main Config =============
 
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
@@ -1901,6 +1940,35 @@ impl ProxyConfig {
             ));
         }
 
+        config
+            .server
+            .client_mss_value()
+            .map_err(|error| ProxyError::Config(format!("server.client_mss {error}")))?;
+        for (idx, listener) in config.server.listeners.iter().enumerate() {
+            if listener.client_mss.is_some() {
+                listener
+                    .effective_client_mss(&config.server)
+                    .map_err(|error| {
+                        ProxyError::Config(format!("server.listeners[{idx}].client_mss {error}"))
+                    })?;
+            }
+            if listener.synlimit_seconds == 0 {
+                return Err(ProxyError::Config(format!(
+                    "server.listeners[{idx}].synlimit_seconds must be > 0"
+                )));
+            }
+            if listener.synlimit_hitcount == 0 {
+                return Err(ProxyError::Config(format!(
+                    "server.listeners[{idx}].synlimit_hitcount must be > 0"
+                )));
+            }
+            if listener.synlimit_burst == 0 {
+                return Err(ProxyError::Config(format!(
+                    "server.listeners[{idx}].synlimit_burst must be > 0"
+                )));
+            }
+        }
+
         if config.server.accept_permit_timeout_ms > 60_000 {
             return Err(ProxyError::Config(
                 "server.accept_permit_timeout_ms must be within [0, 60000]".to_string(),
@@ -1999,11 +2067,6 @@ impl ProxyConfig {
             *mask_host = normalize_mask_host_to_ascii(mask_host, "censorship.mask_host")?;
         }
 
-        // Default mask_host to tls_domain if not set and no unix socket configured.
-        if config.censorship.mask_host.is_none() && config.censorship.mask_unix_sock.is_none() {
-            config.censorship.mask_host = Some(config.censorship.tls_domain.clone());
-        }
-
         for (domain, target) in &config.censorship.exclusive_mask {
             if !is_valid_tls_domain_name(domain) {
                 return Err(ProxyError::Config(format!(
@@ -2063,18 +2126,29 @@ impl ProxyConfig {
         }
 
         let mut exclusive_mask = HashMap::with_capacity(config.censorship.exclusive_mask.len());
+        let mut exclusive_mask_targets =
+            HashMap::with_capacity(config.censorship.exclusive_mask.len());
         for (domain, target) in std::mem::take(&mut config.censorship.exclusive_mask) {
-            let domain = normalize_domain_to_ascii(
-                &domain,
-                "censorship.exclusive_mask domain",
-            )?;
-            let target = normalize_exclusive_mask_target(
-                &target,
-                "censorship.exclusive_mask target",
-            )?;
+            let domain = normalize_domain_to_ascii(&domain, "censorship.exclusive_mask domain")?;
+            let target =
+                normalize_exclusive_mask_target(&target, "censorship.exclusive_mask target")?;
+            let Some((host, port)) = parse_exclusive_mask_target(&target) else {
+                return Err(ProxyError::Config(format!(
+                    "Invalid censorship.exclusive_mask target for '{}': '{}'. Expected host:port with port > 0",
+                    domain, target
+                )));
+            };
+            exclusive_mask_targets.insert(
+                domain.clone(),
+                ExclusiveMaskTarget {
+                    host: host.to_string(),
+                    port,
+                },
+            );
             exclusive_mask.insert(domain, target);
         }
         config.censorship.exclusive_mask = exclusive_mask;
+        config.censorship.exclusive_mask_targets = exclusive_mask_targets;
 
         // Migration: prefer_ipv6 -> network.prefer.
         if config.general.prefer_ipv6 {
@@ -2130,6 +2204,11 @@ impl ProxyConfig {
                 config.server.listeners.push(ListenerConfig {
                     ip: ipv4,
                     port: Some(config.server.port),
+                    client_mss: None,
+                    synlimit: SynLimitMode::default(),
+                    synlimit_seconds: default_synlimit_seconds(),
+                    synlimit_hitcount: default_synlimit_hitcount(),
+                    synlimit_burst: default_synlimit_burst(),
                     announce: None,
                     announce_ip: None,
                     proxy_protocol: None,
@@ -2142,6 +2221,11 @@ impl ProxyConfig {
                 config.server.listeners.push(ListenerConfig {
                     ip: ipv6,
                     port: Some(config.server.port),
+                    client_mss: None,
+                    synlimit: SynLimitMode::default(),
+                    synlimit_seconds: default_synlimit_seconds(),
+                    synlimit_hitcount: default_synlimit_hitcount(),
+                    synlimit_burst: default_synlimit_burst(),
                     announce: None,
                     announce_ip: None,
                     proxy_protocol: None,
@@ -2185,8 +2269,10 @@ impl ProxyConfig {
                 selected_scope: String::new(),
                 ipv4: None,
                 ipv6: None,
+                prefer: None,
             });
         }
+        normalize_upstream_family_policy(&mut config);
 
         // Ensure default DC203 override is present.
         config
@@ -2415,6 +2501,7 @@ mod tests {
         assert_eq!(cfg.general.update_every, default_update_every());
         assert_eq!(cfg.server.listen_addr_ipv4, default_listen_addr_ipv4());
         assert_eq!(cfg.server.listen_addr_ipv6, default_listen_addr_ipv6_opt());
+        assert_eq!(cfg.server.client_mss_value(), Ok(None));
         assert_eq!(
             cfg.server.proxy_protocol_trusted_cidrs,
             default_proxy_protocol_trusted_cidrs()
@@ -3742,6 +3829,153 @@ mod tests {
         let _ = std::fs::remove_file(path);
     }
 
+    #[test]
+    fn client_mss_presets_and_listener_override_are_resolved() {
+        let toml = r#"
+            [server]
+            client_mss = "tspu"
+
+            [[server.listeners]]
+            ip = "127.0.0.1"
+            port = 1443
+
+            [[server.listeners]]
+            ip = "127.0.0.2"
+            port = 1444
+            client_mss = "2in8"
+
+            [[server.listeners]]
+            ip = "127.0.0.3"
+            port = 1445
+            client_mss = ""
+
+            [[server.listeners]]
+            ip = "127.0.0.4"
+            port = 1446
+            client_mss = "extreme-low"
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_client_mss_valid_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let cfg = ProxyConfig::load(&path).unwrap();
+
+        assert_eq!(cfg.server.client_mss_value(), Ok(Some(92)));
+        assert_eq!(
+            cfg.server.listeners[0].effective_client_mss(&cfg.server),
+            Ok(Some(92))
+        );
+        assert_eq!(
+            cfg.server.listeners[1].effective_client_mss(&cfg.server),
+            Ok(Some(256))
+        );
+        assert_eq!(
+            cfg.server.listeners[2].effective_client_mss(&cfg.server),
+            Ok(None)
+        );
+        assert_eq!(
+            cfg.server.listeners[3].effective_client_mss(&cfg.server),
+            Ok(Some(88))
+        );
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn client_mss_custom_value_is_accepted() {
+        let toml = r#"
+            [server]
+            client_mss = "4096"
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_client_mss_custom_valid_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let cfg = ProxyConfig::load(&path).unwrap();
+
+        assert_eq!(cfg.server.client_mss_value(), Ok(Some(4096)));
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn client_mss_out_of_range_is_rejected() {
+        for value in ["87", "4097"] {
+            let toml = format!(
+                r#"
+                [server]
+                client_mss = "{value}"
+
+                [censorship]
+                tls_domain = "example.com"
+
+                [access.users]
+                user = "00000000000000000000000000000000"
+            "#
+            );
+            let dir = std::env::temp_dir();
+            let path = dir.join(format!("telemt_client_mss_out_of_range_{value}_test.toml"));
+            std::fs::write(&path, toml).unwrap();
+            let err = ProxyConfig::load(&path).unwrap_err().to_string();
+
+            assert!(err.contains("server.client_mss custom value must be within [88, 4096]"));
+            let _ = std::fs::remove_file(path);
+        }
+    }
+
+    #[test]
+    fn client_mss_unquoted_number_is_rejected() {
+        let toml = r#"
+            [server]
+            client_mss = 256
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_client_mss_unquoted_number_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+
+        assert!(err.contains("client_mss"));
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn listener_client_mss_invalid_preset_is_rejected() {
+        let toml = r#"
+            [[server.listeners]]
+            ip = "127.0.0.1"
+            port = 1443
+            client_mss = "tiny"
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_listener_client_mss_invalid_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+
+        assert!(err.contains("server.listeners[0].client_mss"));
+        assert!(err.contains("must be \"\", extreme-low, tspu, 2in8"));
+        let _ = std::fs::remove_file(path);
+    }
+
     #[test]
     fn api_runtime_edge_cache_ttl_out_of_range_is_rejected() {
         let toml = r#"

src/config/tests/load_mask_shape_security_tests.rs

@@ -1,14 +1,21 @@
 use super::*;
 use std::fs;
 use std::path::PathBuf;
+use std::sync::atomic::{AtomicU64, Ordering};
 use std::time::{SystemTime, UNIX_EPOCH};
 
+static TEMP_CONFIG_COUNTER: AtomicU64 = AtomicU64::new(0);
+
 fn write_temp_config(contents: &str) -> PathBuf {
     let nonce = SystemTime::now()
         .duration_since(UNIX_EPOCH)
         .expect("system time must be after unix epoch")
         .as_nanos();
-    let path = std::env::temp_dir().join(format!("telemt-load-mask-shape-security-{nonce}.toml"));
+    let seq = TEMP_CONFIG_COUNTER.fetch_add(1, Ordering::Relaxed);
+    let pid = std::process::id();
+    let path = std::env::temp_dir().join(format!(
+        "telemt-load-mask-shape-security-{pid}-{seq}-{nonce}.toml"
+    ));
     fs::write(&path, contents).expect("temp config write must succeed");
     path
 }

src/config/types.rs

@@ -1369,6 +1369,77 @@ impl ConntrackPressureProfile {
     }
 }
 
+/// Per-listener SYN limiter mode.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum SynLimitMode {
+    /// Disable SYN limiting for this listener.
+    #[default]
+    Off,
+    /// Use iptables/ip6tables filter rules with the hashlimit match.
+    Iptables,
+    /// Use nftables rules with per-source token-bucket meters.
+    Nftables,
+}
+
+impl Serialize for SynLimitMode {
+    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        match self {
+            Self::Off => serializer.serialize_bool(false),
+            Self::Iptables => serializer.serialize_str("iptables"),
+            Self::Nftables => serializer.serialize_str("nftables"),
+        }
+    }
+}
+
+impl<'de> Deserialize<'de> for SynLimitMode {
+    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        struct SynLimitModeVisitor;
+
+        impl<'de> serde::de::Visitor<'de> for SynLimitModeVisitor {
+            type Value = SynLimitMode;
+
+            fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                formatter.write_str("false, iptables, or nftables")
+            }
+
+            fn visit_bool<E>(self, value: bool) -> std::result::Result<Self::Value, E>
+            where
+                E: serde::de::Error,
+            {
+                if value {
+                    Err(E::custom(
+                        "synlimit=true is ambiguous; use \"iptables\" or \"nftables\"",
+                    ))
+                } else {
+                    Ok(SynLimitMode::Off)
+                }
+            }
+
+            fn visit_str<E>(self, value: &str) -> std::result::Result<Self::Value, E>
+            where
+                E: serde::de::Error,
+            {
+                match value.trim().to_ascii_lowercase().as_str() {
+                    "false" | "off" | "disabled" | "none" => Ok(SynLimitMode::Off),
+                    "iptables" => Ok(SynLimitMode::Iptables),
+                    "nftables" => Ok(SynLimitMode::Nftables),
+                    _ => Err(E::custom(
+                        "synlimit must be false, \"iptables\", or \"nftables\"",
+                    )),
+                }
+            }
+        }
+
+        deserializer.deserialize_any(SynLimitModeVisitor)
+    }
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ConntrackControlConfig {
     /// Enables runtime conntrack-control worker for pressure mitigation.
@@ -1451,6 +1522,11 @@ pub struct ServerConfig {
     #[serde(default)]
     pub listen_tcp: Option<bool>,
 
+    /// Client-facing TCP MSS preset or custom value for all TCP listeners.
+    /// Empty string or omitted value keeps the kernel default.
+    #[serde(default)]
+    pub client_mss: Option<String>,
+
     /// Accept HAProxy PROXY protocol headers on incoming connections.
     /// When enabled, real client IPs are extracted from PROXY v1/v2 headers.
     #[serde(default)]
@@ -1517,6 +1593,7 @@ impl Default for ServerConfig {
             listen_unix_sock: None,
             listen_unix_sock_perm: None,
             listen_tcp: None,
+            client_mss: None,
             proxy_protocol: false,
             proxy_protocol_header_timeout_ms: default_proxy_protocol_header_timeout_ms(),
             proxy_protocol_trusted_cidrs: default_proxy_protocol_trusted_cidrs(),
@@ -1687,6 +1764,14 @@ impl Default for TlsFetchConfig {
     }
 }
 
+#[derive(Debug, Clone)]
+pub struct ExclusiveMaskTarget {
+    /// Target host after IDNA/IP normalization.
+    pub host: String,
+    /// TCP port for the selected target.
+    pub port: u16,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AntiCensorshipConfig {
     #[serde(default = "default_tls_domain")]
@@ -1712,6 +1797,10 @@ pub struct AntiCensorshipConfig {
     #[serde(default = "default_true")]
     pub mask: bool,
 
+    /// Use the ClientHello SNI as the mask TCP target for configured TLS domains.
+    #[serde(default = "default_true")]
+    pub mask_dynamic: bool,
+
     #[serde(default)]
     pub mask_host: Option<String>,
 
@@ -1722,6 +1811,10 @@ pub struct AntiCensorshipConfig {
     #[serde(default)]
     pub exclusive_mask: HashMap<String, String>,
 
+    /// Parsed runtime cache for per-SNI TCP mask targets.
+    #[serde(skip)]
+    pub exclusive_mask_targets: HashMap<String, ExclusiveMaskTarget>,
+
     #[serde(default)]
     pub mask_unix_sock: Option<String>,
 
@@ -1843,9 +1936,11 @@ impl Default for AntiCensorshipConfig {
             tls_fetch_scope: default_tls_fetch_scope(),
             tls_fetch: TlsFetchConfig::default(),
             mask: default_true(),
+            mask_dynamic: default_true(),
             mask_host: None,
             mask_port: default_mask_port(),
             exclusive_mask: HashMap::new(),
+            exclusive_mask_targets: HashMap::new(),
             mask_unix_sock: None,
             fake_cert_len: default_fake_cert_len(),
             tls_emulation: true,
@@ -1879,6 +1974,9 @@ pub struct AccessConfig {
     #[serde(default = "default_access_users")]
     pub users: HashMap<String, String>,
 
+    #[serde(default)]
+    pub user_enabled: HashMap<String, bool>,
+
     /// Per-user ad_tag (32 hex chars from @MTProxybot).
     #[serde(default)]
     pub user_ad_tags: HashMap<String, String>,
@@ -1950,6 +2048,7 @@ impl Default for AccessConfig {
     fn default() -> Self {
         Self {
             users: default_access_users(),
+            user_enabled: HashMap::new(),
             user_ad_tags: HashMap::new(),
             user_max_tcp_conns: HashMap::new(),
             user_max_tcp_conns_global_each: default_user_max_tcp_conns_global_each(),
@@ -1970,6 +2069,10 @@ impl Default for AccessConfig {
 }
 
 impl AccessConfig {
+    pub fn is_user_enabled(&self, username: &str) -> bool {
+        self.user_enabled.get(username).copied().unwrap_or(true)
+    }
+
     /// Returns true if `ip` is contained in any CIDR listed for `username` under `user_source_deny`.
     pub fn is_user_source_ip_denied(&self, username: &str, ip: IpAddr) -> bool {
         self.user_source_deny
@@ -2044,6 +2147,20 @@ pub struct UpstreamConfig {
     /// `None` means auto-detect from runtime connectivity state.
     #[serde(default)]
     pub ipv6: Option<bool>,
+    /// Per-upstream IP family preference for Telegram DC targets.
+    /// `None` inherits the effective global `[network].prefer` decision.
+    #[serde(default)]
+    pub prefer: Option<u8>,
+}
+
+impl UpstreamConfig {
+    pub fn prefer_ipv6(&self, default_prefer_ipv6: bool) -> bool {
+        match self.prefer {
+            Some(6) => true,
+            Some(4) => false,
+            _ => default_prefer_ipv6,
+        }
+    }
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -2052,6 +2169,22 @@ pub struct ListenerConfig {
     /// Per-listener TCP port. If omitted, falls back to legacy `server.port`.
     #[serde(default)]
     pub port: Option<u16>,
+    /// Per-listener client-facing TCP MSS preset or custom value.
+    /// Empty string disables MSS shaping for this listener.
+    #[serde(default)]
+    pub client_mss: Option<String>,
+    /// Per-listener SYN limiter mode.
+    #[serde(default)]
+    pub synlimit: SynLimitMode,
+    /// Token-bucket rate interval for the per-listener SYN limiter.
+    #[serde(default = "default_synlimit_seconds")]
+    pub synlimit_seconds: u32,
+    /// Token-bucket rate amount for the per-listener SYN limiter.
+    #[serde(default = "default_synlimit_hitcount")]
+    pub synlimit_hitcount: u32,
+    /// Token-bucket burst size for the per-listener SYN limiter.
+    #[serde(default = "default_synlimit_burst")]
+    pub synlimit_burst: u32,
     /// IP address or hostname to announce in proxy links.
     /// Takes precedence over `announce_ip` if both are set.
     #[serde(default)]
@@ -2069,6 +2202,64 @@ pub struct ListenerConfig {
     pub reuse_allow: bool,
 }
 
+/// Client-facing TCP MSS preset for extreme-low fragmentation profiles.
+pub const CLIENT_MSS_EXTREME_LOW: u16 = 88;
+/// Client-facing TCP MSS preset matching TSPU-oriented deployments.
+pub const CLIENT_MSS_TSPU: u16 = 92;
+/// Client-facing TCP MSS preset for 2-in-8 segment shaping.
+pub const CLIENT_MSS_2IN8: u16 = 256;
+/// Minimum accepted custom client-facing TCP MSS value.
+pub const CLIENT_MSS_MIN: u16 = CLIENT_MSS_EXTREME_LOW;
+/// Maximum accepted custom client-facing TCP MSS value.
+pub const CLIENT_MSS_MAX: u16 = 4096;
+
+impl ServerConfig {
+    /// Resolves the global client-facing TCP MSS setting.
+    pub fn client_mss_value(&self) -> std::result::Result<Option<u16>, String> {
+        parse_client_mss(self.client_mss.as_deref())
+    }
+}
+
+impl ListenerConfig {
+    /// Resolves the listener MSS override, falling back to the global server value.
+    pub fn effective_client_mss(
+        &self,
+        server: &ServerConfig,
+    ) -> std::result::Result<Option<u16>, String> {
+        match self.client_mss.as_deref() {
+            Some(value) => parse_client_mss(Some(value)),
+            None => server.client_mss_value(),
+        }
+    }
+}
+
+fn parse_client_mss(raw: Option<&str>) -> std::result::Result<Option<u16>, String> {
+    let Some(raw) = raw else {
+        return Ok(None);
+    };
+    let value = raw.trim();
+    if value.is_empty() {
+        return Ok(None);
+    }
+
+    match value.to_ascii_lowercase().as_str() {
+        "extreme-low" => return Ok(Some(CLIENT_MSS_EXTREME_LOW)),
+        "tspu" => return Ok(Some(CLIENT_MSS_TSPU)),
+        "2in8" => return Ok(Some(CLIENT_MSS_2IN8)),
+        _ => {}
+    }
+
+    let parsed = value
+        .parse::<u16>()
+        .map_err(|_| "must be \"\", extreme-low, tspu, 2in8, or a decimal value".to_string())?;
+    if !(CLIENT_MSS_MIN..=CLIENT_MSS_MAX).contains(&parsed) {
+        return Err(format!(
+            "custom value must be within [{CLIENT_MSS_MIN}, {CLIENT_MSS_MAX}]"
+        ));
+    }
+    Ok(Some(parsed))
+}
+
 // ============= ShowLink =============
 
 /// Controls which users' proxy links are displayed at startup.

src/conntrack_control.rs

@@ -705,7 +705,7 @@ fn nofile_soft_limit() -> Option<u64> {
         if rc != 0 {
             return None;
         }
-        return Some(lim.rlim_cur);
+        return Some(lim.rlim_cur.into());
     }
     #[cfg(not(target_os = "linux"))]
     {

src/error.rs

@@ -245,6 +245,9 @@ pub enum ProxyError {
     InvalidSecret { user: String, reason: String },
 
     // ============= User Errors =============
+    #[error("User {user} disabled")]
+    UserDisabled { user: String },
+
     #[error("User {user} expired")]
     UserExpired { user: String },
 

src/ip_tracker/admission.rs

@@ -0,0 +1,173 @@
+use super::*;
+
+impl UserIpTracker {
+    pub async fn set_limit_policy(&self, mode: UserMaxUniqueIpsMode, window_secs: u64) {
+        self.limit_mode
+            .store(Self::mode_to_u8(mode), Ordering::Relaxed);
+        self.limit_window_secs
+            .store(window_secs.max(1), Ordering::Relaxed);
+    }
+
+    pub async fn set_user_limit(&self, username: &str, max_ips: usize) {
+        self.max_ips.insert(username.to_string(), max_ips);
+    }
+
+    pub async fn remove_user_limit(&self, username: &str) {
+        self.max_ips.remove(username);
+    }
+
+    pub async fn load_limits(&self, default_limit: usize, limits: &HashMap<String, usize>) {
+        self.default_max_ips.store(default_limit, Ordering::Relaxed);
+        self.max_ips.clear();
+        for (username, limit) in limits {
+            self.max_ips.insert(username.clone(), *limit);
+        }
+    }
+
+    pub(super) fn prune_recent(
+        user_recent: &mut HashMap<IpAddr, Instant>,
+        now: Instant,
+        window: Duration,
+    ) -> usize {
+        if user_recent.is_empty() {
+            return 0;
+        }
+        let before = user_recent.len();
+        user_recent.retain(|_, seen_at| now.duration_since(*seen_at) <= window);
+        before.saturating_sub(user_recent.len())
+    }
+
+    pub async fn check_and_add(&self, username: &str, ip: IpAddr) -> Result<(), String> {
+        self.drain_cleanup_for_user(username).await;
+        self.maybe_compact_empty_users().await;
+        let limit = self.user_limit(username);
+        let mode = Self::mode_from_u8(self.limit_mode.load(Ordering::Relaxed));
+        let window = self.limit_window();
+        let now = Instant::now();
+
+        let shard_idx = Self::shard_idx(username);
+        let mut shard = self.shards[shard_idx].write().await;
+        let user_active = shard.active_ips.entry(username.to_string()).or_default();
+        let active_contains_ip = user_active.contains_key(&ip);
+        let active_len = user_active.len();
+        let user_recent = shard.recent_ips.entry(username.to_string()).or_default();
+        let pruned_recent_entries = Self::prune_recent(user_recent, now, window);
+        Self::decrement_counter(&self.recent_entry_count, pruned_recent_entries);
+        let recent_contains_ip = user_recent.contains_key(&ip);
+        let recent_len = user_recent.len();
+
+        if active_contains_ip {
+            if !recent_contains_ip
+                && !Self::try_increment_counter(&self.recent_entry_count, MAX_RECENT_IP_ENTRIES)
+            {
+                self.recent_cap_rejects.fetch_add(1, Ordering::Relaxed);
+                return Err(format!(
+                    "IP tracker recent entry cap reached: entries={}/{}",
+                    self.recent_entry_count.load(Ordering::Relaxed),
+                    MAX_RECENT_IP_ENTRIES
+                ));
+            }
+            let Some(count) = shard
+                .active_ips
+                .get_mut(username)
+                .and_then(|user_active| user_active.get_mut(&ip))
+            else {
+                return Err(format!(
+                    "IP tracker active entry unavailable for user '{username}'"
+                ));
+            };
+            *count = count.saturating_add(1);
+            if let Some(user_recent) = shard.recent_ips.get_mut(username) {
+                user_recent.insert(ip, now);
+            }
+            return Ok(());
+        }
+
+        let is_new_ip = !recent_contains_ip;
+
+        if let Some(limit) = limit {
+            let active_limit_reached = active_len >= limit;
+            let recent_limit_reached = recent_len >= limit && is_new_ip;
+            let deny = match mode {
+                UserMaxUniqueIpsMode::ActiveWindow => active_limit_reached,
+                UserMaxUniqueIpsMode::TimeWindow => recent_limit_reached,
+                UserMaxUniqueIpsMode::Combined => active_limit_reached || recent_limit_reached,
+            };
+
+            if deny {
+                return Err(format!(
+                    "IP limit reached for user '{}': active={}/{} recent={}/{} mode={:?}",
+                    username, active_len, limit, recent_len, limit, mode
+                ));
+            }
+        }
+
+        if !Self::try_increment_counter(&self.active_entry_count, MAX_ACTIVE_IP_ENTRIES) {
+            self.active_cap_rejects.fetch_add(1, Ordering::Relaxed);
+            return Err(format!(
+                "IP tracker active entry cap reached: entries={}/{}",
+                self.active_entry_count.load(Ordering::Relaxed),
+                MAX_ACTIVE_IP_ENTRIES
+            ));
+        }
+        let mut reserved_recent = false;
+        if is_new_ip {
+            if !Self::try_increment_counter(&self.recent_entry_count, MAX_RECENT_IP_ENTRIES) {
+                Self::decrement_counter(&self.active_entry_count, 1);
+                self.recent_cap_rejects.fetch_add(1, Ordering::Relaxed);
+                return Err(format!(
+                    "IP tracker recent entry cap reached: entries={}/{}",
+                    self.recent_entry_count.load(Ordering::Relaxed),
+                    MAX_RECENT_IP_ENTRIES
+                ));
+            }
+            reserved_recent = true;
+        }
+
+        let Some(user_active) = shard.active_ips.get_mut(username) else {
+            Self::decrement_counter(&self.active_entry_count, 1);
+            if reserved_recent {
+                Self::decrement_counter(&self.recent_entry_count, 1);
+            }
+            return Err(format!(
+                "IP tracker active entry unavailable for user '{username}'"
+            ));
+        };
+        if user_active.insert(ip, 1).is_some() {
+            Self::decrement_counter(&self.active_entry_count, 1);
+        }
+        let Some(user_recent) = shard.recent_ips.get_mut(username) else {
+            Self::decrement_counter(&self.active_entry_count, 1);
+            if reserved_recent {
+                Self::decrement_counter(&self.recent_entry_count, 1);
+            }
+            return Err(format!(
+                "IP tracker recent entry unavailable for user '{username}'"
+            ));
+        };
+        if user_recent.insert(ip, now).is_some() && reserved_recent {
+            Self::decrement_counter(&self.recent_entry_count, 1);
+        }
+        Ok(())
+    }
+
+    pub async fn remove_ip(&self, username: &str, ip: IpAddr) {
+        self.maybe_compact_empty_users().await;
+        let shard_idx = Self::shard_idx(username);
+        let mut shard = self.shards[shard_idx].write().await;
+        let mut removed_active_entries = 0usize;
+        if let Some(user_ips) = shard.active_ips.get_mut(username) {
+            if let Some(count) = user_ips.get_mut(&ip) {
+                if *count > 1 {
+                    *count -= 1;
+                } else if user_ips.remove(&ip).is_some() {
+                    removed_active_entries = 1;
+                }
+            }
+            if user_ips.is_empty() {
+                shard.active_ips.remove(username);
+            }
+        }
+        Self::decrement_counter(&self.active_entry_count, removed_active_entries);
+    }
+}

src/ip_tracker/cleanup.rs

@@ -0,0 +1,148 @@
+use super::*;
+
+impl UserIpTracker {
+    /// Queues a deferred active IP cleanup for a later async drain.
+    pub fn enqueue_cleanup(&self, user: String, ip: IpAddr) {
+        self.observe_cleanup_poison_for_tests();
+        let shard_idx = Self::shard_idx(&user);
+        let cleanup_shard = &self.cleanup_shards[shard_idx];
+        match cleanup_shard.queue.lock() {
+            Ok(mut queue) => {
+                let user_queue = queue.entry(user).or_default();
+                let count = user_queue.entry(ip).or_insert(0);
+                if *count == 0 {
+                    self.cleanup_queue_len.fetch_add(1, Ordering::Relaxed);
+                }
+                *count = count.saturating_add(1);
+                self.cleanup_deferred_releases
+                    .fetch_add(1, Ordering::Relaxed);
+            }
+            Err(poisoned) => {
+                let mut queue = poisoned.into_inner();
+                let user_queue = queue.entry(user.clone()).or_default();
+                let count = user_queue.entry(ip).or_insert(0);
+                if *count == 0 {
+                    self.cleanup_queue_len.fetch_add(1, Ordering::Relaxed);
+                }
+                *count = count.saturating_add(1);
+                self.cleanup_deferred_releases
+                    .fetch_add(1, Ordering::Relaxed);
+                cleanup_shard.queue.clear_poison();
+                tracing::warn!(
+                    "UserIpTracker cleanup_queue lock poisoned; recovered and enqueued IP cleanup for {} ({})",
+                    user,
+                    ip
+                );
+            }
+        }
+    }
+
+    #[cfg(test)]
+    pub(crate) fn cleanup_queue_len_for_tests(&self) -> usize {
+        self.cleanup_queue_len.load(Ordering::Relaxed) as usize
+    }
+
+    #[cfg(test)]
+    pub(crate) fn cleanup_queue_mutex_for_tests(
+        &self,
+    ) -> Arc<Mutex<HashMap<(String, IpAddr), usize>>> {
+        Arc::clone(&self.cleanup_queue_poison_probe)
+    }
+
+    pub(crate) async fn drain_cleanup_queue(&self) {
+        if self.cleanup_queue_len.load(Ordering::Relaxed) == 0 {
+            return;
+        }
+        for shard_idx in 0..USER_IP_TRACKER_SHARDS {
+            self.drain_cleanup_shard(shard_idx).await;
+        }
+    }
+
+    pub(super) async fn drain_cleanup_for_user(&self, user: &str) {
+        if self.cleanup_queue_len.load(Ordering::Relaxed) == 0 {
+            return;
+        }
+        let shard_idx = Self::shard_idx(user);
+        let cleanup_shard = &self.cleanup_shards[shard_idx];
+        let to_remove = match cleanup_shard.queue.lock() {
+            Ok(mut queue) => queue.remove(user).unwrap_or_default(),
+            Err(poisoned) => {
+                let mut queue = poisoned.into_inner();
+                let drained = queue.remove(user).unwrap_or_default();
+                cleanup_shard.queue.clear_poison();
+                drained
+            }
+        };
+        if to_remove.is_empty() {
+            return;
+        }
+        self.cleanup_queue_len
+            .fetch_sub(to_remove.len() as u64, Ordering::Relaxed);
+        let mut shard = self.shards[shard_idx].write().await;
+        let mut removed_active_entries = 0usize;
+        for (ip, pending_count) in to_remove {
+            removed_active_entries = removed_active_entries.saturating_add(
+                Self::apply_active_cleanup(&mut shard.active_ips, user, ip, pending_count),
+            );
+        }
+        Self::decrement_counter(&self.active_entry_count, removed_active_entries);
+    }
+
+    pub(super) async fn drain_cleanup_shard(&self, shard_idx: usize) {
+        let Ok(_drain_guard) = self.cleanup_drain_locks[shard_idx].try_lock() else {
+            return;
+        };
+
+        let cleanup_shard = &self.cleanup_shards[shard_idx];
+        let to_remove = {
+            match cleanup_shard.queue.lock() {
+                Ok(mut queue) => {
+                    if queue.is_empty() {
+                        return;
+                    }
+                    let mut drained =
+                        HashMap::with_capacity(queue.len().min(CLEANUP_DRAIN_BATCH_LIMIT));
+                    for _ in 0..CLEANUP_DRAIN_BATCH_LIMIT {
+                        let Some((user, ip, count)) = Self::pop_one_cleanup(&mut queue) else {
+                            break;
+                        };
+                        self.cleanup_queue_len.fetch_sub(1, Ordering::Relaxed);
+                        drained.insert((user, ip), count);
+                    }
+                    drained
+                }
+                Err(poisoned) => {
+                    let mut queue = poisoned.into_inner();
+                    if queue.is_empty() {
+                        cleanup_shard.queue.clear_poison();
+                        return;
+                    }
+                    let mut drained =
+                        HashMap::with_capacity(queue.len().min(CLEANUP_DRAIN_BATCH_LIMIT));
+                    for _ in 0..CLEANUP_DRAIN_BATCH_LIMIT {
+                        let Some((user, ip, count)) = Self::pop_one_cleanup(&mut queue) else {
+                            break;
+                        };
+                        self.cleanup_queue_len.fetch_sub(1, Ordering::Relaxed);
+                        drained.insert((user, ip), count);
+                    }
+                    cleanup_shard.queue.clear_poison();
+                    drained
+                }
+            }
+        };
+        drop(_drain_guard);
+        if to_remove.is_empty() {
+            return;
+        }
+
+        let mut shard = self.shards[shard_idx].write().await;
+        let mut removed_active_entries = 0usize;
+        for ((user, ip), pending_count) in to_remove {
+            removed_active_entries = removed_active_entries.saturating_add(
+                Self::apply_active_cleanup(&mut shard.active_ips, &user, ip, pending_count),
+            );
+        }
+        Self::decrement_counter(&self.active_entry_count, removed_active_entries);
+    }
+}

src/ip_tracker/snapshot.rs

@@ -0,0 +1,309 @@
+use super::*;
+
+impl UserIpTracker {
+    pub(super) async fn maybe_compact_empty_users(&self) {
+        const COMPACT_INTERVAL_SECS: u64 = 60;
+        let now_epoch_secs = Self::now_epoch_secs();
+        let last_compact_epoch_secs = self.last_compact_epoch_secs.load(Ordering::Relaxed);
+        if now_epoch_secs.saturating_sub(last_compact_epoch_secs) < COMPACT_INTERVAL_SECS {
+            return;
+        }
+        if self
+            .last_compact_epoch_secs
+            .compare_exchange(
+                last_compact_epoch_secs,
+                now_epoch_secs,
+                Ordering::AcqRel,
+                Ordering::Relaxed,
+            )
+            .is_err()
+        {
+            return;
+        }
+
+        let window = self.limit_window();
+        let now = Instant::now();
+        for shard_lock in self.shards.iter() {
+            let mut shard = shard_lock.write().await;
+            let mut pruned_recent_entries = 0usize;
+            for user_recent in shard.recent_ips.values_mut() {
+                pruned_recent_entries = pruned_recent_entries.saturating_add(Self::prune_recent(
+                    user_recent,
+                    now,
+                    window,
+                ));
+            }
+            Self::decrement_counter(&self.recent_entry_count, pruned_recent_entries);
+
+            let mut users = Vec::<String>::with_capacity(
+                shard
+                    .active_ips
+                    .len()
+                    .saturating_add(shard.recent_ips.len()),
+            );
+            users.extend(shard.active_ips.keys().cloned());
+            for user in shard.recent_ips.keys() {
+                if !shard.active_ips.contains_key(user) {
+                    users.push(user.clone());
+                }
+            }
+
+            for user in users {
+                let active_empty = shard
+                    .active_ips
+                    .get(&user)
+                    .map(|ips| ips.is_empty())
+                    .unwrap_or(true);
+                let recent_empty = shard
+                    .recent_ips
+                    .get(&user)
+                    .map(|ips| ips.is_empty())
+                    .unwrap_or(true);
+                if active_empty && recent_empty {
+                    shard.active_ips.remove(&user);
+                    shard.recent_ips.remove(&user);
+                }
+            }
+        }
+    }
+
+    pub async fn run_periodic_maintenance(self: Arc<Self>) {
+        let mut interval = tokio::time::interval(Duration::from_secs(1));
+        loop {
+            interval.tick().await;
+            self.drain_cleanup_queue().await;
+            self.maybe_compact_empty_users().await;
+        }
+    }
+
+    pub async fn memory_stats(&self) -> UserIpTrackerMemoryStats {
+        let cleanup_queue_len = self.cleanup_queue_len.load(Ordering::Relaxed) as usize;
+        let mut active_users = 0usize;
+        let mut recent_users = 0usize;
+        let mut active_entries = 0usize;
+        let mut recent_entries = 0usize;
+        for shard_lock in self.shards.iter() {
+            let shard = shard_lock.read().await;
+            active_users = active_users.saturating_add(shard.active_ips.len());
+            recent_users = recent_users.saturating_add(shard.recent_ips.len());
+            active_entries =
+                active_entries.saturating_add(shard.active_ips.values().map(HashMap::len).sum());
+            recent_entries =
+                recent_entries.saturating_add(shard.recent_ips.values().map(HashMap::len).sum());
+        }
+
+        UserIpTrackerMemoryStats {
+            active_users,
+            recent_users,
+            active_entries,
+            recent_entries,
+            cleanup_queue_len,
+            active_cap_rejects: self.active_cap_rejects.load(Ordering::Relaxed),
+            recent_cap_rejects: self.recent_cap_rejects.load(Ordering::Relaxed),
+            cleanup_deferred_releases: self.cleanup_deferred_releases.load(Ordering::Relaxed),
+        }
+    }
+
+    pub async fn get_recent_counts_for_users(&self, users: &[String]) -> HashMap<String, usize> {
+        self.drain_cleanup_queue().await;
+        self.get_recent_counts_for_users_snapshot(users).await
+    }
+
+    pub(crate) async fn get_recent_counts_for_users_snapshot(
+        &self,
+        users: &[String],
+    ) -> HashMap<String, usize> {
+        let window = self.limit_window();
+        let now = Instant::now();
+
+        let mut counts = HashMap::with_capacity(users.len());
+        for user in users {
+            let shard_idx = Self::shard_idx(user);
+            let shard = self.shards[shard_idx].read().await;
+            let count = if let Some(user_recent) = shard.recent_ips.get(user) {
+                user_recent
+                    .values()
+                    .filter(|seen_at| now.duration_since(**seen_at) <= window)
+                    .count()
+            } else {
+                0
+            };
+            counts.insert(user.clone(), count);
+        }
+        counts
+    }
+
+    pub async fn get_active_ips_for_users(&self, users: &[String]) -> HashMap<String, Vec<IpAddr>> {
+        self.drain_cleanup_queue().await;
+        let mut out = HashMap::with_capacity(users.len());
+        for user in users {
+            let shard_idx = Self::shard_idx(user);
+            let shard = self.shards[shard_idx].read().await;
+            let mut ips = shard
+                .active_ips
+                .get(user)
+                .map(|per_ip| per_ip.keys().copied().collect::<Vec<_>>())
+                .unwrap_or_else(Vec::new);
+            ips.sort();
+            out.insert(user.clone(), ips);
+        }
+        out
+    }
+
+    pub async fn get_recent_ips_for_users(&self, users: &[String]) -> HashMap<String, Vec<IpAddr>> {
+        self.drain_cleanup_queue().await;
+        let window = self.limit_window();
+        let now = Instant::now();
+
+        let mut out = HashMap::with_capacity(users.len());
+        for user in users {
+            let shard_idx = Self::shard_idx(user);
+            let shard = self.shards[shard_idx].read().await;
+            let mut ips = if let Some(user_recent) = shard.recent_ips.get(user) {
+                user_recent
+                    .iter()
+                    .filter(|(_, seen_at)| now.duration_since(**seen_at) <= window)
+                    .map(|(ip, _)| *ip)
+                    .collect::<Vec<_>>()
+            } else {
+                Vec::new()
+            };
+            ips.sort();
+            out.insert(user.clone(), ips);
+        }
+        out
+    }
+
+    pub async fn get_active_ip_count(&self, username: &str) -> usize {
+        self.drain_cleanup_queue().await;
+        let shard_idx = Self::shard_idx(username);
+        let shard = self.shards[shard_idx].read().await;
+        shard
+            .active_ips
+            .get(username)
+            .map(|ips| ips.len())
+            .unwrap_or(0)
+    }
+
+    pub async fn get_active_ips(&self, username: &str) -> Vec<IpAddr> {
+        self.drain_cleanup_queue().await;
+        let shard_idx = Self::shard_idx(username);
+        let shard = self.shards[shard_idx].read().await;
+        shard
+            .active_ips
+            .get(username)
+            .map(|ips| ips.keys().copied().collect())
+            .unwrap_or_else(Vec::new)
+    }
+
+    pub async fn get_stats(&self) -> Vec<(String, usize, usize)> {
+        self.drain_cleanup_queue().await;
+        self.get_stats_snapshot().await
+    }
+
+    pub(crate) async fn get_stats_snapshot(&self) -> Vec<(String, usize, usize)> {
+        let mut active_counts = Vec::new();
+        for shard_lock in self.shards.iter() {
+            let shard = shard_lock.read().await;
+            active_counts.extend(
+                shard
+                    .active_ips
+                    .iter()
+                    .map(|(username, user_ips)| (username.clone(), user_ips.len())),
+            );
+        }
+
+        let mut stats = Vec::with_capacity(active_counts.len());
+        for (username, active_count) in active_counts {
+            let limit = self.user_limit(&username).unwrap_or(0);
+            stats.push((username, active_count, limit));
+        }
+
+        stats.sort_by(|a, b| a.0.cmp(&b.0));
+        stats
+    }
+
+    pub async fn clear_user_ips(&self, username: &str) {
+        let shard_idx = Self::shard_idx(username);
+        let mut shard = self.shards[shard_idx].write().await;
+        let removed_active_entries = shard
+            .active_ips
+            .remove(username)
+            .map(|ips| ips.len())
+            .unwrap_or(0);
+        Self::decrement_counter(&self.active_entry_count, removed_active_entries);
+
+        let removed_recent_entries = shard
+            .recent_ips
+            .remove(username)
+            .map(|ips| ips.len())
+            .unwrap_or(0);
+        Self::decrement_counter(&self.recent_entry_count, removed_recent_entries);
+    }
+
+    pub async fn clear_all(&self) {
+        for shard_lock in self.shards.iter() {
+            let mut shard = shard_lock.write().await;
+            shard.active_ips.clear();
+            shard.recent_ips.clear();
+        }
+        self.active_entry_count.store(0, Ordering::Relaxed);
+        self.recent_entry_count.store(0, Ordering::Relaxed);
+        for cleanup_shard in self.cleanup_shards.iter() {
+            match cleanup_shard.queue.lock() {
+                Ok(mut queue) => queue.clear(),
+                Err(poisoned) => {
+                    poisoned.into_inner().clear();
+                    cleanup_shard.queue.clear_poison();
+                }
+            }
+        }
+        self.cleanup_queue_len.store(0, Ordering::Relaxed);
+    }
+
+    pub async fn is_ip_active(&self, username: &str, ip: IpAddr) -> bool {
+        self.drain_cleanup_queue().await;
+        let shard_idx = Self::shard_idx(username);
+        let shard = self.shards[shard_idx].read().await;
+        shard
+            .active_ips
+            .get(username)
+            .map(|ips| ips.contains_key(&ip))
+            .unwrap_or(false)
+    }
+
+    pub async fn get_user_limit(&self, username: &str) -> Option<usize> {
+        self.user_limit(username)
+    }
+
+    pub async fn format_stats(&self) -> String {
+        let stats = self.get_stats().await;
+
+        if stats.is_empty() {
+            return String::from("No active users");
+        }
+
+        let mut output = String::from("User IP Statistics:\n");
+        output.push_str("==================\n");
+
+        for (username, active_count, limit) in stats {
+            output.push_str(&format!(
+                "User: {:<20} Active IPs: {}/{}\n",
+                username,
+                active_count,
+                if limit > 0 {
+                    limit.to_string()
+                } else {
+                    "unlimited".to_string()
+                }
+            ));
+
+            let ips = self.get_active_ips(&username).await;
+            for ip in ips {
+                output.push_str(&format!("  - {}\n", ip));
+            }
+        }
+
+        output
+    }
+}

src/ip_tracker/tests.rs

@@ -0,0 +1,385 @@
+use super::*;
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+use std::sync::atomic::Ordering;
+
+fn test_ipv4(oct1: u8, oct2: u8, oct3: u8, oct4: u8) -> IpAddr {
+    IpAddr::V4(Ipv4Addr::new(oct1, oct2, oct3, oct4))
+}
+
+fn test_ipv6() -> IpAddr {
+    IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1))
+}
+
+#[tokio::test]
+async fn test_basic_ip_limit() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 2).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+    let ip3 = test_ipv4(192, 168, 1, 3);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip3).await.is_err());
+
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 2);
+}
+
+#[tokio::test]
+async fn test_active_window_rejects_new_ip_and_keeps_existing_session() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::ActiveWindow, 30)
+        .await;
+
+    let ip1 = test_ipv4(10, 10, 10, 1);
+    let ip2 = test_ipv4(10, 10, 10, 2);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.is_ip_active("test_user", ip1).await);
+    assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+
+    // Existing session remains active; only new unique IP is denied.
+    assert!(tracker.is_ip_active("test_user", ip1).await);
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+}
+
+#[tokio::test]
+async fn test_reconnection_from_same_ip() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 2).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+}
+
+#[tokio::test]
+async fn test_same_ip_disconnect_keeps_active_while_other_session_alive() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 2).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+
+    tracker.remove_ip("test_user", ip1).await;
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+
+    tracker.remove_ip("test_user", ip1).await;
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 0);
+}
+
+#[tokio::test]
+async fn test_ip_removal() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 2).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+    let ip3 = test_ipv4(192, 168, 1, 3);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip3).await.is_err());
+
+    tracker.remove_ip("test_user", ip1).await;
+
+    assert!(tracker.check_and_add("test_user", ip3).await.is_ok());
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 2);
+}
+
+#[tokio::test]
+async fn test_no_limit() {
+    let tracker = UserIpTracker::new();
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+    let ip3 = test_ipv4(192, 168, 1, 3);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip3).await.is_ok());
+
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 3);
+}
+
+#[tokio::test]
+async fn test_multiple_users() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("user1", 2).await;
+    tracker.set_user_limit("user2", 1).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+
+    assert!(tracker.check_and_add("user1", ip1).await.is_ok());
+    assert!(tracker.check_and_add("user1", ip2).await.is_ok());
+
+    assert!(tracker.check_and_add("user2", ip1).await.is_ok());
+    assert!(tracker.check_and_add("user2", ip2).await.is_err());
+}
+
+#[tokio::test]
+async fn test_ipv6_support() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 2).await;
+
+    let ipv4 = test_ipv4(192, 168, 1, 1);
+    let ipv6 = test_ipv6();
+
+    assert!(tracker.check_and_add("test_user", ipv4).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ipv6).await.is_ok());
+
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 2);
+}
+
+#[tokio::test]
+async fn test_get_active_ips() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 3).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+
+    tracker.check_and_add("test_user", ip1).await.unwrap();
+    tracker.check_and_add("test_user", ip2).await.unwrap();
+
+    let active_ips = tracker.get_active_ips("test_user").await;
+    assert_eq!(active_ips.len(), 2);
+    assert!(active_ips.contains(&ip1));
+    assert!(active_ips.contains(&ip2));
+}
+
+#[tokio::test]
+async fn test_stats() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("user1", 3).await;
+    tracker.set_user_limit("user2", 2).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+
+    tracker.check_and_add("user1", ip1).await.unwrap();
+    tracker.check_and_add("user2", ip2).await.unwrap();
+
+    let stats = tracker.get_stats().await;
+    assert_eq!(stats.len(), 2);
+
+    assert!(stats.iter().any(|(name, _, _)| name == "user1"));
+    assert!(stats.iter().any(|(name, _, _)| name == "user2"));
+}
+
+#[tokio::test]
+async fn test_clear_user_ips() {
+    let tracker = UserIpTracker::new();
+    let ip1 = test_ipv4(192, 168, 1, 1);
+
+    tracker.check_and_add("test_user", ip1).await.unwrap();
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+
+    tracker.clear_user_ips("test_user").await;
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 0);
+}
+
+#[tokio::test]
+async fn test_is_ip_active() {
+    let tracker = UserIpTracker::new();
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+
+    tracker.check_and_add("test_user", ip1).await.unwrap();
+
+    assert!(tracker.is_ip_active("test_user", ip1).await);
+    assert!(!tracker.is_ip_active("test_user", ip2).await);
+}
+
+#[tokio::test]
+async fn test_load_limits_from_config() {
+    let tracker = UserIpTracker::new();
+
+    let mut config_limits = HashMap::new();
+    config_limits.insert("user1".to_string(), 5);
+    config_limits.insert("user2".to_string(), 3);
+
+    tracker.load_limits(0, &config_limits).await;
+
+    assert_eq!(tracker.get_user_limit("user1").await, Some(5));
+    assert_eq!(tracker.get_user_limit("user2").await, Some(3));
+    assert_eq!(tracker.get_user_limit("user3").await, None);
+}
+
+#[tokio::test]
+async fn test_load_limits_replaces_previous_map() {
+    let tracker = UserIpTracker::new();
+
+    let mut first = HashMap::new();
+    first.insert("user1".to_string(), 2);
+    first.insert("user2".to_string(), 3);
+    tracker.load_limits(0, &first).await;
+
+    let mut second = HashMap::new();
+    second.insert("user2".to_string(), 5);
+    tracker.load_limits(0, &second).await;
+
+    assert_eq!(tracker.get_user_limit("user1").await, None);
+    assert_eq!(tracker.get_user_limit("user2").await, Some(5));
+}
+
+#[tokio::test]
+async fn test_global_each_limit_applies_without_user_override() {
+    let tracker = UserIpTracker::new();
+    tracker.load_limits(2, &HashMap::new()).await;
+
+    let ip1 = test_ipv4(172, 16, 0, 1);
+    let ip2 = test_ipv4(172, 16, 0, 2);
+    let ip3 = test_ipv4(172, 16, 0, 3);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip3).await.is_err());
+    assert_eq!(tracker.get_user_limit("test_user").await, Some(2));
+}
+
+#[tokio::test]
+async fn test_user_override_wins_over_global_each_limit() {
+    let tracker = UserIpTracker::new();
+    let mut limits = HashMap::new();
+    limits.insert("test_user".to_string(), 1);
+    tracker.load_limits(3, &limits).await;
+
+    let ip1 = test_ipv4(172, 17, 0, 1);
+    let ip2 = test_ipv4(172, 17, 0, 2);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+    assert_eq!(tracker.get_user_limit("test_user").await, Some(1));
+}
+
+#[tokio::test]
+async fn test_time_window_mode_blocks_recent_ip_churn() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 30)
+        .await;
+
+    let ip1 = test_ipv4(10, 0, 0, 1);
+    let ip2 = test_ipv4(10, 0, 0, 2);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    tracker.remove_ip("test_user", ip1).await;
+    assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+}
+
+#[tokio::test]
+async fn test_combined_mode_enforces_active_and_recent_limits() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::Combined, 30)
+        .await;
+
+    let ip1 = test_ipv4(10, 0, 1, 1);
+    let ip2 = test_ipv4(10, 0, 1, 2);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+
+    tracker.remove_ip("test_user", ip1).await;
+    assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+}
+
+#[tokio::test]
+async fn test_time_window_expires() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 1)
+        .await;
+
+    let ip1 = test_ipv4(10, 1, 0, 1);
+    let ip2 = test_ipv4(10, 1, 0, 2);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    tracker.remove_ip("test_user", ip1).await;
+    assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+
+    tokio::time::sleep(Duration::from_millis(1100)).await;
+    assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+}
+
+#[tokio::test]
+async fn test_memory_stats_reports_queue_and_entry_counts() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 4).await;
+    let ip1 = test_ipv4(10, 2, 0, 1);
+    let ip2 = test_ipv4(10, 2, 0, 2);
+
+    tracker.check_and_add("test_user", ip1).await.unwrap();
+    tracker.check_and_add("test_user", ip2).await.unwrap();
+    tracker.enqueue_cleanup("test_user".to_string(), ip1);
+
+    let snapshot = tracker.memory_stats().await;
+    assert_eq!(snapshot.active_users, 1);
+    assert_eq!(snapshot.recent_users, 1);
+    assert_eq!(snapshot.active_entries, 2);
+    assert_eq!(snapshot.recent_entries, 2);
+    assert_eq!(snapshot.cleanup_queue_len, 1);
+}
+
+#[tokio::test]
+async fn test_compact_prunes_stale_recent_entries() {
+    let tracker = UserIpTracker::new();
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 1)
+        .await;
+
+    let stale_user = "stale-user".to_string();
+    let stale_ip = test_ipv4(10, 3, 0, 1);
+    {
+        let shard_idx = UserIpTracker::shard_idx(&stale_user);
+        let mut shard = tracker.shards[shard_idx].write().await;
+        shard
+            .recent_ips
+            .entry(stale_user.clone())
+            .or_insert_with(HashMap::new)
+            .insert(stale_ip, Instant::now() - Duration::from_secs(5));
+    }
+
+    tracker.last_compact_epoch_secs.store(0, Ordering::Relaxed);
+    tracker
+        .check_and_add("trigger-user", test_ipv4(10, 3, 0, 2))
+        .await
+        .unwrap();
+
+    let shard_idx = UserIpTracker::shard_idx(&stale_user);
+    let shard = tracker.shards[shard_idx].read().await;
+    let stale_exists = shard
+        .recent_ips
+        .get(&stale_user)
+        .map(|ips| ips.contains_key(&stale_ip))
+        .unwrap_or(false);
+    assert!(!stale_exists);
+}
+
+#[tokio::test]
+async fn test_time_window_allows_same_ip_reconnect() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 1)
+        .await;
+
+    let ip1 = test_ipv4(10, 4, 0, 1);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    tracker.remove_ip("test_user", ip1).await;
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+}

src/maestro/connectivity.rs

@@ -147,7 +147,7 @@ pub(crate) async fn run_startup_connectivity(
             .any(|r| r.rtt_ms.is_some());
 
         if upstream_result.both_available {
-            if prefer_ipv6 {
+            if upstream_result.prefer_ipv6 {
                 info!("  IPv6 in use / IPv4 is fallback");
             } else {
                 info!("  IPv4 in use / IPv6 is fallback");

src/maestro/helpers.rs

@@ -1,6 +1,7 @@
 #![allow(clippy::items_after_test_module)]
 
 use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::Duration;
 
 use tokio::sync::watch;
@@ -18,8 +19,27 @@ use crate::transport::middle_proxy::{
 const MAESTRO_COLOR: &str = "\x1b[92m";
 const COLOR_RESET: &str = "\x1b[0m";
 
+static MAESTRO_COLORS_ENABLED: AtomicBool = AtomicBool::new(true);
+
+/// Enables or disables ANSI color in direct MAESTRO status lines.
+pub(crate) fn set_maestro_colors_enabled(enabled: bool) {
+    MAESTRO_COLORS_ENABLED.store(enabled, Ordering::Relaxed);
+}
+
+fn format_maestro_line(message: impl AsRef<str>, colors_enabled: bool) -> String {
+    if colors_enabled {
+        format!("{MAESTRO_COLOR}MAESTRO{COLOR_RESET}: {}", message.as_ref())
+    } else {
+        format!("MAESTRO: {}", message.as_ref())
+    }
+}
+
+/// Prints a direct MAESTRO status line outside the tracing subscriber.
 pub(crate) fn print_maestro_line(message: impl AsRef<str>) {
-    eprintln!("{MAESTRO_COLOR}MAESTRO{COLOR_RESET}: {}", message.as_ref());
+    eprintln!(
+        "{}",
+        format_maestro_line(message, MAESTRO_COLORS_ENABLED.load(Ordering::Relaxed))
+    );
 }
 
 pub(crate) fn resolve_runtime_config_path(
@@ -274,11 +294,24 @@ mod tests {
     use std::path::{Path, PathBuf};
 
     use super::{
-        expected_handshake_close_description, is_expected_handshake_eof, peer_close_description,
-        resolve_runtime_base_dir, resolve_runtime_config_path,
+        expected_handshake_close_description, format_maestro_line, is_expected_handshake_eof,
+        peer_close_description, resolve_runtime_base_dir, resolve_runtime_config_path,
     };
     use crate::error::{ProxyError, StreamError};
 
+    #[test]
+    fn maestro_line_formatter_respects_disabled_colors() {
+        let plain = format_maestro_line("boot", false);
+        assert_eq!(plain, "MAESTRO: boot");
+        assert!(!plain.contains('\x1b'));
+    }
+
+    #[test]
+    fn maestro_line_formatter_keeps_color_when_enabled() {
+        let colored = format_maestro_line("boot", true);
+        assert!(colored.contains("\x1b[92mMAESTRO\x1b[0m"));
+    }
+
     #[test]
     fn resolve_runtime_config_path_anchors_relative_to_startup_cwd() {
         let nonce = std::time::SystemTime::now()

src/maestro/listeners.rs

@@ -47,6 +47,10 @@ fn default_link_port(config: &ProxyConfig) -> u16 {
         .unwrap_or(config.server.port)
 }
 
+fn mss_segment_multiplier(client_mss: u16) -> u16 {
+    1460u16.div_ceil(client_mss)
+}
+
 #[allow(clippy::too_many_arguments)]
 pub(crate) async fn bind_listeners(
     config: &Arc<ProxyConfig>,
@@ -90,10 +94,22 @@ pub(crate) async fn bind_listeners(
             warn!(%addr, "Skipping IPv6 listener: IPv6 disabled by [network]");
             continue;
         }
+        let client_mss = match listener_conf.effective_client_mss(&config.server) {
+            Ok(value) => value,
+            Err(error) => {
+                warn!(
+                    %addr,
+                    error = %error,
+                    "Invalid listener client MSS after config validation; using kernel default"
+                );
+                None
+            }
+        };
         let options = ListenOptions {
             reuse_port: listener_conf.reuse_allow,
             ipv6_only: listener_conf.ip.is_ipv6(),
             backlog: config.server.listen_backlog,
+            client_mss,
             ..Default::default()
         };
 
@@ -101,6 +117,14 @@ pub(crate) async fn bind_listeners(
             Ok(socket) => {
                 let listener = TcpListener::from_std(socket.into())?;
                 info!("Listening on {}", addr);
+                if let Some(client_mss) = client_mss {
+                    info!(
+                        %addr,
+                        client_mss,
+                        segment_multiplier = mss_segment_multiplier(client_mss),
+                        "Client-facing TCP MSS configured"
+                    );
+                }
                 let listener_proxy_protocol = listener_conf
                     .proxy_protocol
                     .unwrap_or(config.server.proxy_protocol);

src/maestro/mod.rs

@@ -45,9 +45,13 @@ use crate::stats::beobachten::BeobachtenStore;
 use crate::stats::telemetry::TelemetryPolicy;
 use crate::stats::{ReplayChecker, Stats};
 use crate::stream::BufferPool;
+use crate::synlimit_control;
 use crate::transport::UpstreamManager;
 use crate::transport::middle_proxy::MePool;
-use helpers::{parse_cli, print_maestro_line, resolve_runtime_base_dir, resolve_runtime_config_path};
+use helpers::{
+    parse_cli, print_maestro_line, resolve_runtime_base_dir, resolve_runtime_config_path,
+    set_maestro_colors_enabled,
+};
 
 #[cfg(unix)]
 use crate::daemon::{DaemonOptions, PidFile, drop_privileges};
@@ -312,6 +316,7 @@ async fn run_telemt_core(
         eprintln!("[telemt] Invalid network.dns_overrides: {}", e);
         std::process::exit(1);
     }
+    set_maestro_colors_enabled(!config.general.disable_colors);
     startup_tracker
         .complete_component(COMPONENT_CONFIG_LOAD, Some("config is ready".to_string()))
         .await;
@@ -460,11 +465,16 @@ async fn run_telemt_core(
             config.network.dns_overrides.len()
         );
     }
+    let shared_state = ProxySharedState::new();
+    shared_state.apply_user_enabled_config(&config.access.user_enabled);
+    shared_state.traffic_limiter.apply_policy(
+        config.access.user_rate_limits.clone(),
+        config.access.cidr_rate_limits.clone(),
+    );
 
     let (api_config_tx, api_config_rx) = watch::channel(Arc::new(config.clone()));
     let (detected_ips_tx, detected_ips_rx) = watch::channel((None::<IpAddr>, None::<IpAddr>));
-    let initial_direct_first =
-        config.general.use_middle_proxy && config.general.me2dc_fallback;
+    let initial_direct_first = config.general.use_middle_proxy && config.general.me2dc_fallback;
     let initial_admission_open = !config.general.use_middle_proxy || initial_direct_first;
     let (admission_tx, admission_rx) = watch::channel(initial_admission_open);
     let initial_route_mode = if !config.general.use_middle_proxy || initial_direct_first {
@@ -499,6 +509,7 @@ async fn run_telemt_core(
             let me_pool_api = api_me_pool.clone();
             let upstream_manager_api = upstream_manager.clone();
             let route_runtime_api = route_runtime.clone();
+            let proxy_shared_api = shared_state.clone();
             let config_rx_api = api_config_rx.clone();
             let admission_rx_api = admission_rx.clone();
             let config_path_api = config_path.clone();
@@ -512,6 +523,7 @@ async fn run_telemt_core(
                     ip_tracker_api,
                     me_pool_api,
                     route_runtime_api,
+                    proxy_shared_api,
                     upstream_manager_api,
                     config_rx_api,
                     admission_rx_api,
@@ -694,7 +706,9 @@ async fn run_telemt_core(
     if direct_first_startup {
         startup_tracker.set_transport_mode("direct").await;
         startup_tracker.set_degraded(true).await;
-        info!("Transport: Direct DC startup fallback active; Middle-End bootstrap continues in background");
+        info!(
+            "Transport: Direct DC startup fallback active; Middle-End bootstrap continues in background"
+        );
     } else if me_pool.is_some() {
         startup_tracker.set_transport_mode("middle_proxy").await;
         startup_tracker.set_degraded(false).await;
@@ -727,11 +741,6 @@ async fn run_telemt_core(
     ));
 
     let buffer_pool = Arc::new(BufferPool::with_config(64 * 1024, 4096));
-    let shared_state = ProxySharedState::new();
-    shared_state.traffic_limiter.apply_policy(
-        config.access.user_rate_limits.clone(),
-        config.access.cidr_rate_limits.clone(),
-    );
 
     if direct_first_startup {
         startup_tracker
@@ -840,7 +849,9 @@ async fn run_telemt_core(
                 if let Some(pool) = api_me_pool_ready.read().await.as_ref() {
                     pool.set_runtime_ready(true);
                 }
-                startup_tracker_ready.set_transport_mode("middle_proxy").await;
+                startup_tracker_ready
+                    .set_transport_mode("middle_proxy")
+                    .await;
                 startup_tracker_ready.set_degraded(false).await;
                 info!("Transport: Middle-End Proxy restored for new sessions");
             }
@@ -899,6 +910,9 @@ async fn run_telemt_core(
     // On Unix, caller supplies privilege drop after bind (may require root for port < 1024).
     drop_after_bind();
 
+    synlimit_control::reconcile_synlimit_rules(&config).await;
+    synlimit_control::spawn_synlimit_controller(config_rx.clone());
+
     runtime_tasks::apply_runtime_log_filter(
         has_rust_log,
         &effective_log_level,

src/maestro/runtime_tasks.rs

@@ -3,7 +3,7 @@ use std::path::Path;
 use std::sync::Arc;
 
 use tokio::sync::{mpsc, watch};
-use tracing::{debug, warn};
+use tracing::{debug, info, warn};
 use tracing_subscriber::EnvFilter;
 use tracing_subscriber::reload;
 
@@ -234,6 +234,27 @@ pub(crate) async fn spawn_runtime_tasks(
         }
     });
 
+    let shared_user_enabled = shared_state.clone();
+    let mut config_rx_user_enabled = config_rx.clone();
+    tokio::spawn(async move {
+        loop {
+            if config_rx_user_enabled.changed().await.is_err() {
+                break;
+            }
+            let cfg = config_rx_user_enabled.borrow_and_update().clone();
+            for user in shared_user_enabled.apply_user_enabled_config(&cfg.access.user_enabled) {
+                let cancelled = shared_user_enabled.cancel_user_sessions(&user);
+                if cancelled > 0 {
+                    info!(
+                        user = %user,
+                        cancelled,
+                        "Disabled user sessions cancelled after config reload"
+                    );
+                }
+            }
+        }
+    });
+
     let beobachten_writer = beobachten.clone();
     let config_rx_beobachten = config_rx.clone();
     tokio::spawn(async move {

src/maestro/shutdown.rs

@@ -19,6 +19,7 @@ use tokio::signal::unix::{SignalKind, signal};
 use tracing::{info, warn};
 
 use crate::stats::Stats;
+use crate::synlimit_control;
 use crate::transport::middle_proxy::MePool;
 
 use super::helpers::{format_uptime, unit_label};
@@ -102,6 +103,10 @@ async fn perform_shutdown(
     let uptime_secs = process_started_at.elapsed().as_secs();
     info!("Uptime: {}", format_uptime(uptime_secs));
 
+    if let Err(error) = synlimit_control::clear_synlimit_rules_all_backends().await {
+        warn!(error = %error, "Failed to clear SYN limiter rules during shutdown");
+    }
+
     // Graceful ME pool shutdown
     if let Some(pool) = &me_pool {
         match tokio::time::timeout(Duration::from_secs(2), pool.shutdown_send_close_conn_all())

src/main.rs

@@ -30,6 +30,7 @@ mod service;
 mod startup;
 mod stats;
 mod stream;
+mod synlimit_control;
 mod tls_front;
 mod transport;
 mod util;

src/metrics.rs

@@ -55,8 +55,10 @@ pub async fn serve(
                 return;
             }
         };
-        let is_ipv6 = addr.is_ipv6();
-        match bind_metrics_listener(addr, is_ipv6, listen_backlog) {
+        // Match `server.api.listen`: `[::]:port` is a dual-stack wildcard
+        // on Linux when `net.ipv6.bindv6only=0`.
+        let ipv6_only = addr.is_ipv6() && !addr.ip().is_unspecified();
+        match bind_metrics_listener(addr, ipv6_only, listen_backlog) {
             Ok(listener) => {
                 info!("Metrics endpoint: http://{}/metrics and /beobachten", addr);
                 serve_listener(
@@ -286,7 +288,7 @@ async fn handle<B>(
     }
 
     if req.uri().path() == "/beobachten" {
-        let body = render_beobachten(beobachten, config);
+        let body = render_beobachten(stats, beobachten, config);
         let resp = Response::builder()
             .status(StatusCode::OK)
             .header("content-type", "text/plain; charset=utf-8")
@@ -302,13 +304,22 @@ async fn handle<B>(
     Ok(resp)
 }
 
-fn render_beobachten(beobachten: &BeobachtenStore, config: &ProxyConfig) -> String {
+fn render_beobachten(stats: &Stats, beobachten: &BeobachtenStore, config: &ProxyConfig) -> String {
     if !config.general.beobachten {
         return "beobachten disabled\n".to_string();
     }
 
     let ttl = Duration::from_secs(config.general.beobachten_minutes.saturating_mul(60));
-    beobachten.snapshot_text(ttl)
+    let mut body = beobachten.snapshot_text(ttl);
+    let tls_text = stats.tls_fingerprint_snapshot_text(ttl, 20);
+    if !tls_text.is_empty() {
+        if !body.ends_with('\n') {
+            body.push('\n');
+        }
+        body.push('\n');
+        body.push_str(&tls_text);
+    }
+    body
 }
 
 fn tls_front_domains(config: &ProxyConfig) -> Vec<String> {
@@ -370,11 +381,32 @@ async fn render_tls_front_profile_health(
         "# HELP telemt_tls_front_profile_info TLS front profile source and feature flags per configured domain"
     );
     let _ = writeln!(out, "# TYPE telemt_tls_front_profile_info gauge");
+    let _ = writeln!(
+        out,
+        "# HELP telemt_tls_front_profile_quality_info TLS front profile quality and key-share group per configured domain"
+    );
+    let _ = writeln!(out, "# TYPE telemt_tls_front_profile_quality_info gauge");
     let _ = writeln!(
         out,
         "# HELP telemt_tls_front_profile_age_seconds Age of cached TLS front profile data per configured domain"
     );
     let _ = writeln!(out, "# TYPE telemt_tls_front_profile_age_seconds gauge");
+    let _ = writeln!(
+        out,
+        "# HELP telemt_tls_front_profile_server_hello_bytes TLS front cached ServerHello record body bytes per configured domain"
+    );
+    let _ = writeln!(
+        out,
+        "# TYPE telemt_tls_front_profile_server_hello_bytes gauge"
+    );
+    let _ = writeln!(
+        out,
+        "# HELP telemt_tls_front_profile_server_hello_extensions TLS front cached visible ServerHello extension count per configured domain"
+    );
+    let _ = writeln!(
+        out,
+        "# TYPE telemt_tls_front_profile_server_hello_extensions gauge"
+    );
     let _ = writeln!(
         out,
         "# HELP telemt_tls_front_profile_app_data_records TLS front cached app-data record count per configured domain"
@@ -409,11 +441,26 @@ async fn render_tls_front_profile_health(
             "telemt_tls_front_profile_info{{domain=\"{}\",source=\"{}\",is_default=\"{}\",has_cert_info=\"{}\",has_cert_payload=\"{}\"}} 1",
             domain, item.source, item.is_default, item.has_cert_info, item.has_cert_payload
         );
+        let _ = writeln!(
+            out,
+            "telemt_tls_front_profile_quality_info{{domain=\"{}\",quality=\"{}\",key_share_group=\"{}\"}} 1",
+            domain, item.quality, item.key_share_group
+        );
         let _ = writeln!(
             out,
             "telemt_tls_front_profile_age_seconds{{domain=\"{}\"}} {}",
             domain, item.age_seconds
         );
+        let _ = writeln!(
+            out,
+            "telemt_tls_front_profile_server_hello_bytes{{domain=\"{}\"}} {}",
+            domain, item.server_hello_record_len
+        );
+        let _ = writeln!(
+            out,
+            "telemt_tls_front_profile_server_hello_extensions{{domain=\"{}\"}} {}",
+            domain, item.server_hello_extensions
+        );
         let _ = writeln!(
             out,
             "telemt_tls_front_profile_app_data_records{{domain=\"{}\"}} {}",
@@ -726,6 +773,37 @@ async fn render_metrics(
         }
     );
 
+    let _ = writeln!(
+        out,
+        "# HELP telemt_route_cutover_parked_current Sessions currently parked in route cutover stagger delay"
+    );
+    let _ = writeln!(out, "# TYPE telemt_route_cutover_parked_current gauge");
+    let _ = writeln!(
+        out,
+        "telemt_route_cutover_parked_current{{route=\"direct\"}} {}",
+        stats.get_route_cutover_parked_direct_current()
+    );
+    let _ = writeln!(
+        out,
+        "telemt_route_cutover_parked_current{{route=\"middle\"}} {}",
+        stats.get_route_cutover_parked_middle_current()
+    );
+    let _ = writeln!(
+        out,
+        "# HELP telemt_route_cutover_parked_total Sessions parked in route cutover stagger delay"
+    );
+    let _ = writeln!(out, "# TYPE telemt_route_cutover_parked_total counter");
+    let _ = writeln!(
+        out,
+        "telemt_route_cutover_parked_total{{route=\"direct\"}} {}",
+        stats.get_route_cutover_parked_direct_total()
+    );
+    let _ = writeln!(
+        out,
+        "telemt_route_cutover_parked_total{{route=\"middle\"}} {}",
+        stats.get_route_cutover_parked_middle_total()
+    );
+
     let _ = writeln!(
         out,
         "# HELP telemt_quota_refund_bytes_total Reserved quota bytes returned before commit"
@@ -3859,7 +3937,20 @@ mod tests {
                         session_id: Vec::new(),
                         cipher_suite: [0x13, 0x01],
                         compression: 0,
-                        extensions: Vec::new(),
+                        extensions: {
+                            let mut key_share = vec![0x00, 0x1d, 0x00, 0x20];
+                            key_share.resize(36, 0x42);
+                            vec![
+                                crate::tls_front::types::TlsExtension {
+                                    ext_type: 0x002b,
+                                    data: vec![0x03, 0x04],
+                                },
+                                crate::tls_front::types::TlsExtension {
+                                    ext_type: 0x0033,
+                                    data: key_share,
+                                },
+                            ]
+                        },
                     },
                     cert_info: None,
                     cert_payload: Some(TlsCertPayload {
@@ -3873,6 +3964,7 @@ mod tests {
                         app_data_record_sizes: vec![1024, 512],
                         ticket_record_sizes: vec![69],
                         source: TlsProfileSource::Merged,
+                        ..TlsBehaviorProfile::default()
                     },
                     fetched_at: SystemTime::now(),
                     domain: "primary.example".to_string(),
@@ -3891,6 +3983,18 @@ mod tests {
         assert!(
             output.contains("telemt_tls_front_profile_info{domain=\"fallback.example\",source=\"default\",is_default=\"true\",has_cert_info=\"false\",has_cert_payload=\"false\"} 1")
         );
+        assert!(
+            output.contains("telemt_tls_front_profile_quality_info{domain=\"primary.example\",quality=\"raw_strict\",key_share_group=\"x25519\"} 1")
+        );
+        assert!(
+            output.contains("telemt_tls_front_profile_quality_info{domain=\"fallback.example\",quality=\"fallback\",key_share_group=\"none\"} 1")
+        );
+        assert!(output.contains(
+            "telemt_tls_front_profile_server_hello_bytes{domain=\"primary.example\"} 90"
+        ));
+        assert!(output.contains(
+            "telemt_tls_front_profile_server_hello_extensions{domain=\"primary.example\"} 2"
+        ));
         assert!(
             output.contains(
                 "telemt_tls_front_profile_app_data_records{domain=\"primary.example\"} 2"
@@ -4003,7 +4107,10 @@ mod tests {
         );
         assert!(output.contains("# TYPE telemt_tls_front_profile_domains gauge"));
         assert!(output.contains("# TYPE telemt_tls_front_profile_info gauge"));
+        assert!(output.contains("# TYPE telemt_tls_front_profile_quality_info gauge"));
         assert!(output.contains("# TYPE telemt_tls_front_profile_age_seconds gauge"));
+        assert!(output.contains("# TYPE telemt_tls_front_profile_server_hello_bytes gauge"));
+        assert!(output.contains("# TYPE telemt_tls_front_profile_server_hello_extensions gauge"));
         assert!(output.contains("# TYPE telemt_tls_front_profile_app_data_records gauge"));
         assert!(output.contains("# TYPE telemt_tls_front_profile_ticket_records gauge"));
         assert!(

src/protocol/mod.rs

@@ -4,6 +4,7 @@ pub mod constants;
 pub mod frame;
 pub mod obfuscation;
 pub mod tls;
+pub mod tls_fingerprint;
 
 #[allow(unused_imports)]
 pub use constants::*;
@@ -13,3 +14,5 @@ pub use frame::*;
 pub use obfuscation::*;
 #[allow(unused_imports)]
 pub use tls::*;
+#[allow(unused_imports)]
+pub use tls_fingerprint::*;

src/protocol/tests/tls_security_tests.rs

@@ -1239,6 +1239,18 @@ fn test_gen_fake_x25519_key() {
     assert_ne!(key1, key2);
 }
 
+#[test]
+fn test_gen_fake_x25519mlkem768_server_key_share_shape() {
+    let rng = crate::crypto::SecureRandom::new();
+    let key_share = gen_fake_x25519mlkem768_server_key_share(&rng);
+
+    assert_eq!(key_share.len(), X25519MLKEM768_SERVER_KEY_SHARE_LEN);
+    assert!(
+        key_share.iter().any(|byte| *byte != 0),
+        "hybrid ServerHello key_share must not collapse to all-zero bytes"
+    );
+}
+
 #[test]
 fn test_fake_x25519_key_is_nonzero_and_varies() {
     let rng = crate::crypto::SecureRandom::new();
@@ -1325,6 +1337,69 @@ fn server_hello_extension_types(record: &[u8]) -> Vec<u16> {
     out
 }
 
+fn server_hello_key_share(record: &[u8]) -> Option<(u16, usize)> {
+    if record.len() < 9 || record[0] != TLS_RECORD_HANDSHAKE || record[5] != 0x02 {
+        return None;
+    }
+
+    let record_len = u16::from_be_bytes([record[3], record[4]]) as usize;
+    if record.len() < 5 + record_len {
+        return None;
+    }
+
+    let hs_len = u32::from_be_bytes([0, record[6], record[7], record[8]]) as usize;
+    let hs_start = 5;
+    let hs_end = hs_start + 4 + hs_len;
+    if hs_end > record.len() {
+        return None;
+    }
+
+    let mut pos = hs_start + 4 + 2 + 32;
+    if pos >= hs_end {
+        return None;
+    }
+    let sid_len = record[pos] as usize;
+    pos += 1 + sid_len;
+    if pos + 2 + 1 + 2 > hs_end {
+        return None;
+    }
+
+    pos += 2 + 1;
+    let ext_len = u16::from_be_bytes([record[pos], record[pos + 1]]) as usize;
+    pos += 2;
+    let ext_end = pos + ext_len;
+    if ext_end > hs_end {
+        return None;
+    }
+
+    while pos + 4 <= ext_end {
+        let etype = u16::from_be_bytes([record[pos], record[pos + 1]]);
+        let elen = u16::from_be_bytes([record[pos + 2], record[pos + 3]]) as usize;
+        pos += 4;
+        if pos + elen > ext_end {
+            return None;
+        }
+        if etype == extension_type::KEY_SHARE {
+            if elen < 4 {
+                return None;
+            }
+            let group = u16::from_be_bytes([record[pos], record[pos + 1]]);
+            let key_exchange_len = u16::from_be_bytes([record[pos + 2], record[pos + 3]]) as usize;
+            if 4 + key_exchange_len != elen {
+                return None;
+            }
+            return Some((group, key_exchange_len));
+        }
+        pos += elen;
+    }
+
+    None
+}
+
+fn test_server_key_share(group: u16, len: usize) -> ServerHelloKeyShare {
+    ServerHelloKeyShare::new(group, vec![0x42; len])
+}
+
 #[test]
 fn build_server_hello_never_places_alpn_in_server_hello_extensions() {
     let secret = b"alpn_sh_forbidden";
@@ -1372,6 +1447,7 @@ fn emulated_server_hello_never_places_alpn_in_server_hello_extensions() {
             app_data_record_sizes: vec![1024],
             ticket_record_sizes: Vec::new(),
             source: TlsProfileSource::Default,
+            ..TlsBehaviorProfile::default()
         },
         fetched_at: SystemTime::now(),
         domain: "example.com".to_string(),
@@ -1385,6 +1461,11 @@ fn emulated_server_hello_never_places_alpn_in_server_hello_extensions() {
         false,
         true,
         ClientHelloTlsVersion::Tls13,
+        [0x13, 0x01],
+        &test_server_key_share(
+            TLS_NAMED_GROUP_X25519MLKEM768,
+            X25519MLKEM768_SERVER_KEY_SHARE_LEN,
+        ),
         &rng,
         Some(b"h2".to_vec()),
         0,
@@ -1394,14 +1475,21 @@ fn emulated_server_hello_never_places_alpn_in_server_hello_extensions() {
         !exts.contains(&0x0010),
         "ALPN extension must not appear in emulated ServerHello"
     );
+    assert_eq!(
+        server_hello_key_share(&response),
+        Some((
+            TLS_NAMED_GROUP_X25519MLKEM768,
+            X25519MLKEM768_SERVER_KEY_SHARE_LEN
+        ))
+    );
 }
 
 #[test]
 fn test_tls_extension_builder() {
-    let key = [0x42u8; 32];
+    let key = vec![0x42u8; X25519MLKEM768_SERVER_KEY_SHARE_LEN];
 
     let mut builder = TlsExtensionBuilder::new();
-    builder.add_key_share(&key);
+    builder.add_key_share(TLS_NAMED_GROUP_X25519MLKEM768, &key);
     builder.add_supported_versions(0x0304);
 
     let result = builder.build();
@@ -1414,10 +1502,10 @@ fn test_tls_extension_builder() {
 #[test]
 fn test_server_hello_builder() {
     let session_id = vec![0x01, 0x02, 0x03, 0x04];
-    let key = [0x55u8; 32];
+    let key = vec![0x55u8; X25519MLKEM768_SERVER_KEY_SHARE_LEN];
 
     let builder = ServerHelloBuilder::new(session_id.clone())
-        .with_x25519_key(&key)
+        .with_key_share(TLS_NAMED_GROUP_X25519MLKEM768, &key)
         .with_tls13_version();
 
     let record = builder.build_record();
@@ -1451,6 +1539,41 @@ fn test_build_server_hello_structure() {
     let app_start = ccs_start + ccs_len;
     assert!(response.len() > app_start + 5);
     assert_eq!(response[app_start], TLS_RECORD_APPLICATION);
+
+    assert_eq!(
+        server_hello_key_share(&response),
+        Some((
+            TLS_NAMED_GROUP_X25519MLKEM768,
+            X25519MLKEM768_SERVER_KEY_SHARE_LEN
+        ))
+    );
+}
+
+#[test]
+fn test_build_server_hello_with_cipher_uses_selected_key_share_group() {
+    let secret = b"test secret";
+    let client_digest = [0x42u8; 32];
+    let session_id = vec![0xAA; 32];
+    let key_share =
+        ServerHelloKeyShare::new(TLS_NAMED_GROUP_X25519, vec![0x55u8; X25519_KEY_SHARE_LEN]);
+
+    let rng = crate::crypto::SecureRandom::new();
+    let response = build_server_hello_with_cipher(
+        secret,
+        &client_digest,
+        &session_id,
+        2048,
+        &rng,
+        [0x13, 0x01],
+        &key_share,
+        None,
+        0,
+    );
+
+    assert_eq!(
+        server_hello_key_share(&response),
+        Some((TLS_NAMED_GROUP_X25519, X25519_KEY_SHARE_LEN))
+    );
 }
 
 #[test]
@@ -1473,10 +1596,10 @@ fn test_build_server_hello_digest() {
 #[test]
 fn test_server_hello_extensions_length() {
     let session_id = vec![0x01; 32];
-    let key = [0x55u8; 32];
+    let key = vec![0x55u8; X25519MLKEM768_SERVER_KEY_SHARE_LEN];
 
     let builder = ServerHelloBuilder::new(session_id)
-        .with_x25519_key(&key)
+        .with_key_share(TLS_NAMED_GROUP_X25519MLKEM768, &key)
         .with_tls13_version();
 
     let record = builder.build_record();
@@ -1509,12 +1632,55 @@ fn test_validate_tls_handshake_format() {
 }
 
 fn build_client_hello_with_exts(exts: Vec<(u16, Vec<u8>)>, host: &str) -> Vec<u8> {
+    build_client_hello_with_ciphers_and_exts(&[[0x13, 0x01]], exts, host)
+}
+
+fn client_key_share_extension(entries: &[(u16, usize)]) -> Vec<u8> {
+    let mut shares = Vec::new();
+    for (group, key_exchange_len) in entries {
+        assert!(*key_exchange_len <= u16::MAX as usize);
+        shares.extend_from_slice(&group.to_be_bytes());
+        shares.extend_from_slice(&(*key_exchange_len as u16).to_be_bytes());
+        let start = shares.len();
+        shares.resize(start + *key_exchange_len, 0x42);
+    }
+
+    assert!(shares.len() <= u16::MAX as usize);
+    let mut extension = Vec::new();
+    extension.extend_from_slice(&(shares.len() as u16).to_be_bytes());
+    extension.extend_from_slice(&shares);
+    extension
+}
+
+fn client_key_share_extension_with_payloads(entries: &[(u16, &[u8])]) -> Vec<u8> {
+    let mut shares = Vec::new();
+    for (group, key_exchange) in entries {
+        assert!(key_exchange.len() <= u16::MAX as usize);
+        shares.extend_from_slice(&group.to_be_bytes());
+        shares.extend_from_slice(&(key_exchange.len() as u16).to_be_bytes());
+        shares.extend_from_slice(key_exchange);
+    }
+
+    assert!(shares.len() <= u16::MAX as usize);
+    let mut extension = Vec::new();
+    extension.extend_from_slice(&(shares.len() as u16).to_be_bytes());
+    extension.extend_from_slice(&shares);
+    extension
+}
+
+fn build_client_hello_with_ciphers_and_exts(
+    cipher_suites: &[[u8; 2]],
+    exts: Vec<(u16, Vec<u8>)>,
+    host: &str,
+) -> Vec<u8> {
     let mut body = Vec::new();
     body.extend_from_slice(&TLS_VERSION);
     body.extend_from_slice(&[0u8; 32]);
     body.push(0);
-    body.extend_from_slice(&2u16.to_be_bytes());
-    body.extend_from_slice(&[0x13, 0x01]);
+    body.extend_from_slice(&((cipher_suites.len() * 2) as u16).to_be_bytes());
+    for suite in cipher_suites {
+        body.extend_from_slice(suite);
+    }
     body.push(1);
     body.push(0);
 
@@ -1654,6 +1820,244 @@ fn detect_client_hello_tls_version_rejects_malformed_supported_versions() {
     assert!(detect_client_hello_tls_version(&ch).is_none());
 }
 
+#[test]
+fn select_server_hello_cipher_suite_keeps_profile_cipher_when_offered() {
+    let ch = build_client_hello_with_ciphers_and_exts(
+        &[[0x13, 0x01], [0x13, 0x03]],
+        Vec::new(),
+        "example.com",
+    );
+    assert_eq!(
+        select_server_hello_cipher_suite(&ch, [0x13, 0x03]),
+        Some([0x13, 0x03])
+    );
+}
+
+#[test]
+fn select_server_hello_cipher_suite_ignores_profile_tls12_cipher() {
+    let ch = build_client_hello_with_ciphers_and_exts(
+        &[[0xc0, 0x2f], [0x13, 0x03]],
+        Vec::new(),
+        "example.com",
+    );
+    assert_eq!(
+        select_server_hello_cipher_suite(&ch, [0xc0, 0x2f]),
+        Some([0x13, 0x03])
+    );
+}
+
+#[test]
+fn select_server_hello_cipher_suite_rejects_without_offered_tls13_suite() {
+    let ch = build_client_hello_with_ciphers_and_exts(&[[0xc0, 0x2f]], Vec::new(), "example.com");
+    assert_eq!(select_server_hello_cipher_suite(&ch, [0x13, 0x01]), None);
+}
+
+#[test]
+fn select_server_hello_cipher_suite_falls_back_to_offered_tls13_suite() {
+    let ch = build_client_hello_with_ciphers_and_exts(&[[0x13, 0x03]], Vec::new(), "example.com");
+    assert_eq!(
+        select_server_hello_cipher_suite(&ch, [0x13, 0x01]),
+        Some([0x13, 0x03])
+    );
+}
+
+#[test]
+fn select_server_hello_cipher_suite_rejects_malformed_clienthello() {
+    let mut ch =
+        build_client_hello_with_ciphers_and_exts(&[[0x13, 0x03]], Vec::new(), "example.com");
+    ch.truncate(12);
+    assert_eq!(select_server_hello_cipher_suite(&ch, [0x13, 0x01]), None);
+}
+
+#[test]
+fn select_server_hello_key_share_group_prefers_hybrid_when_valid_share_is_offered() {
+    let key_share = client_key_share_extension(&[
+        (0x0a0a, 1),
+        (
+            TLS_NAMED_GROUP_X25519MLKEM768,
+            X25519MLKEM768_CLIENT_KEY_SHARE_LEN,
+        ),
+        (TLS_NAMED_GROUP_X25519, X25519_KEY_SHARE_LEN),
+    ]);
+    let ch = build_client_hello_with_exts(vec![(0x0033, key_share)], "example.com");
+
+    assert_eq!(
+        select_server_hello_key_share_group(&ch),
+        Some(TLS_NAMED_GROUP_X25519MLKEM768)
+    );
+}
+
+#[test]
+fn select_server_hello_key_share_group_prefers_profiled_x25519_when_valid_share_is_offered() {
+    let key_share = client_key_share_extension(&[
+        (
+            TLS_NAMED_GROUP_X25519MLKEM768,
+            X25519MLKEM768_CLIENT_KEY_SHARE_LEN,
+        ),
+        (TLS_NAMED_GROUP_X25519, X25519_KEY_SHARE_LEN),
+    ]);
+    let ch = build_client_hello_with_exts(vec![(0x0033, key_share)], "example.com");
+
+    assert_eq!(
+        select_server_hello_key_share_group_with_preference(&ch, Some(TLS_NAMED_GROUP_X25519)),
+        Some(TLS_NAMED_GROUP_X25519)
+    );
+}
+
+#[test]
+fn build_x25519mlkem768_server_key_share_accepts_tdesktop_canonical_share() {
+    let key_share = client_key_share_extension(&[
+        (
+            TLS_NAMED_GROUP_X25519MLKEM768,
+            X25519MLKEM768_CLIENT_KEY_SHARE_LEN,
+        ),
+        (TLS_NAMED_GROUP_X25519, X25519_KEY_SHARE_LEN),
+    ]);
+    let ch = build_client_hello_with_exts(vec![(0x0033, key_share)], "example.com");
+    let rng = crate::crypto::SecureRandom::new();
+
+    let server_key_share = build_x25519mlkem768_server_key_share(&ch, &rng)
+        .expect("tdesktop-like canonical share must build a ServerHello share");
+
+    assert_eq!(server_key_share.len(), X25519MLKEM768_SERVER_KEY_SHARE_LEN);
+    assert!(
+        server_key_share[..MLKEM768_SERVER_CIPHERTEXT_LEN]
+            .iter()
+            .any(|byte| *byte != 0),
+        "ML-KEM ciphertext must not be all zero"
+    );
+    assert!(
+        server_key_share[MLKEM768_SERVER_CIPHERTEXT_LEN..]
+            .iter()
+            .any(|byte| *byte != 0),
+        "X25519 server share must not be all zero"
+    );
+}
+
+#[test]
+fn build_x25519_server_key_share_accepts_tdesktop_fallback_share() {
+    let key_share = client_key_share_extension(&[
+        (
+            TLS_NAMED_GROUP_X25519MLKEM768,
+            X25519MLKEM768_CLIENT_KEY_SHARE_LEN,
+        ),
+        (TLS_NAMED_GROUP_X25519, X25519_KEY_SHARE_LEN),
+    ]);
+    let ch = build_client_hello_with_exts(vec![(0x0033, key_share)], "example.com");
+    let rng = crate::crypto::SecureRandom::new();
+
+    let server_key_share = build_x25519_server_key_share(&ch, &rng)
+        .expect("tdesktop-like X25519 share must build a ServerHello share");
+
+    assert_eq!(server_key_share.len(), X25519_KEY_SHARE_LEN);
+    assert!(
+        server_key_share.iter().any(|byte| *byte != 0),
+        "X25519 server share must not be all zero"
+    );
+}
+
+#[test]
+fn build_server_hello_key_share_prefers_profiled_x25519() {
+    let key_share = client_key_share_extension(&[
+        (
+            TLS_NAMED_GROUP_X25519MLKEM768,
+            X25519MLKEM768_CLIENT_KEY_SHARE_LEN,
+        ),
+        (TLS_NAMED_GROUP_X25519, X25519_KEY_SHARE_LEN),
+    ]);
+    let ch = build_client_hello_with_exts(vec![(0x0033, key_share)], "example.com");
+    let rng = crate::crypto::SecureRandom::new();
+
+    let server_key_share = build_server_hello_key_share(&ch, Some(TLS_NAMED_GROUP_X25519), &rng)
+        .expect("profiled X25519 share must be selected when client offers it");
+
+    assert_eq!(server_key_share.group(), TLS_NAMED_GROUP_X25519);
+    assert_eq!(server_key_share.key_exchange().len(), X25519_KEY_SHARE_LEN);
+}
+
+#[test]
+fn build_server_hello_key_share_falls_back_from_bad_profiled_x25519_to_hybrid() {
+    let key_share = client_key_share_extension(&[(
+        TLS_NAMED_GROUP_X25519MLKEM768,
+        X25519MLKEM768_CLIENT_KEY_SHARE_LEN,
+    )]);
+    let ch = build_client_hello_with_exts(vec![(0x0033, key_share)], "example.com");
+    let rng = crate::crypto::SecureRandom::new();
+
+    let server_key_share = build_server_hello_key_share(&ch, Some(TLS_NAMED_GROUP_X25519), &rng)
+        .expect("hybrid share must be selected when profiled X25519 is unavailable");
+
+    assert_eq!(server_key_share.group(), TLS_NAMED_GROUP_X25519MLKEM768);
+    assert_eq!(
+        server_key_share.key_exchange().len(),
+        X25519MLKEM768_SERVER_KEY_SHARE_LEN
+    );
+}
+
+#[test]
+fn build_x25519mlkem768_server_key_share_rejects_noncanonical_mlkem_key() {
+    let mut key_exchange = vec![0x42; X25519MLKEM768_CLIENT_KEY_SHARE_LEN];
+    key_exchange[..3].copy_from_slice(&[0xff, 0xff, 0xff]);
+    let key_share = client_key_share_extension_with_payloads(&[(
+        TLS_NAMED_GROUP_X25519MLKEM768,
+        &key_exchange,
+    )]);
+    let ch = build_client_hello_with_exts(vec![(0x0033, key_share)], "example.com");
+    let rng = crate::crypto::SecureRandom::new();
+
+    assert!(build_x25519mlkem768_server_key_share(&ch, &rng).is_none());
+}
+
+#[test]
+fn build_x25519mlkem768_server_key_share_rejects_all_zero_x25519_share() {
+    let mut key_exchange = vec![0x42; X25519MLKEM768_CLIENT_KEY_SHARE_LEN];
+    key_exchange[MLKEM768_CLIENT_ENCAPSULATION_KEY_LEN..].fill(0);
+    let key_share = client_key_share_extension_with_payloads(&[(
+        TLS_NAMED_GROUP_X25519MLKEM768,
+        &key_exchange,
+    )]);
+    let ch = build_client_hello_with_exts(vec![(0x0033, key_share)], "example.com");
+    let rng = crate::crypto::SecureRandom::new();
+
+    assert!(build_x25519mlkem768_server_key_share(&ch, &rng).is_none());
+}
+
+#[test]
+fn select_server_hello_key_share_group_accepts_x25519_when_hybrid_is_absent() {
+    let key_share = client_key_share_extension(&[(TLS_NAMED_GROUP_X25519, X25519_KEY_SHARE_LEN)]);
+    let ch = build_client_hello_with_exts(vec![(0x0033, key_share)], "example.com");
+
+    assert_eq!(
+        select_server_hello_key_share_group(&ch),
+        Some(TLS_NAMED_GROUP_X25519)
+    );
+}
+
+#[test]
+fn select_server_hello_key_share_group_rejects_malformed_hybrid_len() {
+    let key_share = client_key_share_extension(&[(
+        TLS_NAMED_GROUP_X25519MLKEM768,
+        X25519MLKEM768_CLIENT_KEY_SHARE_LEN - 1,
+    )]);
+    let ch = build_client_hello_with_exts(vec![(0x0033, key_share)], "example.com");
+
+    assert_eq!(select_server_hello_key_share_group(&ch), None);
+}
+
+#[test]
+fn select_server_hello_key_share_group_rejects_malformed_key_share_tail() {
+    let mut key_share = client_key_share_extension(&[(
+        TLS_NAMED_GROUP_X25519MLKEM768,
+        X25519MLKEM768_CLIENT_KEY_SHARE_LEN,
+    )]);
+    let shares_len = u16::from_be_bytes([key_share[0], key_share[1]]) + 1;
+    key_share[0..2].copy_from_slice(&shares_len.to_be_bytes());
+    key_share.push(0);
+    let ch = build_client_hello_with_exts(vec![(0x0033, key_share)], "example.com");
+
+    assert_eq!(select_server_hello_key_share_group(&ch), None);
+}
+
 #[test]
 fn extract_sni_rejects_zero_length_host_name() {
     let mut sni_ext = Vec::new();
@@ -2179,7 +2583,7 @@ fn light_fuzz_boot_time_timestamp_matrix_with_short_replay_window_obeys_boot_cap
 }
 
 #[test]
-fn server_hello_application_data_contains_alpn_marker_when_selected() {
+fn server_hello_application_data_omits_alpn_marker_when_selected() {
     let secret = b"alpn_marker_test";
     let client_digest = [0x55u8; TLS_DIGEST_LEN];
     let session_id = vec![0xAB; 32];
@@ -2206,8 +2610,8 @@ fn server_hello_application_data_contains_alpn_marker_when_selected() {
     assert!(
         app_payload
             .windows(expected.len())
-            .any(|window| window == expected),
-        "first application payload must carry ALPN marker for selected protocol"
+            .all(|window| window != expected),
+        "first application payload must not expose plaintext ALPN marker bytes"
     );
 }
 
@@ -2303,14 +2707,14 @@ fn server_hello_ignores_oversized_alpn_when_marker_would_not_fit() {
 }
 
 #[test]
-fn server_hello_embeds_full_alpn_marker_when_it_exactly_fits_fake_cert_len() {
+fn server_hello_omits_alpn_marker_even_when_it_would_fit_fake_cert_len() {
     let secret = b"alpn_exact_fit_test";
     let client_digest = [0x58u8; TLS_DIGEST_LEN];
     let session_id = vec![0xA5; 32];
     let rng = crate::crypto::SecureRandom::new();
     let proto = vec![b'z'; 57];
 
-    // marker_len = 4 + (2 + (1 + proto_len)) = 7 + proto_len = 64
+    // marker_len = 4 + (2 + (1 + proto_len)) = 7 + proto_len = 64.
     let response = build_server_hello(
         secret,
         &client_digest,
@@ -2336,7 +2740,7 @@ fn server_hello_embeds_full_alpn_marker_when_it_exactly_fits_fake_cert_len() {
     expected_marker.extend_from_slice(&proto);
 
     assert_eq!(app_payload.len(), expected_marker.len());
-    assert_eq!(app_payload, expected_marker.as_slice());
+    assert_ne!(app_payload, expected_marker.as_slice());
 }
 
 #[test]

src/protocol/tls.rs

@@ -65,6 +65,7 @@ use super::constants::*;
 use crate::crypto::{SecureRandom, sha256_hmac};
 #[cfg(test)]
 use crate::error::ProxyError;
+use ml_kem::{B32, EncapsulationKey as MlKemEncapsulationKey, Key as MlKemKey, MlKem768};
 use std::time::{SystemTime, UNIX_EPOCH};
 use subtle::ConstantTimeEq;
 use x25519_dalek::{X25519_BASEPOINT_BYTES, x25519};
@@ -105,11 +106,49 @@ mod extension_type {
 /// TLS Cipher Suites
 mod cipher_suite {
     pub const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    pub const TLS_AES_256_GCM_SHA384: [u8; 2] = [0x13, 0x02];
+    pub const TLS_CHACHA20_POLY1305_SHA256: [u8; 2] = [0x13, 0x03];
 }
 
-/// TLS Named Curves
+/// TLS named groups used in KeyShare extensions.
 mod named_curve {
     pub const X25519: u16 = 0x001d;
+    pub const X25519MLKEM768: u16 = 0x11ec;
+}
+
+/// TLS X25519 named group.
+pub(crate) const TLS_NAMED_GROUP_X25519: u16 = named_curve::X25519;
+/// TLS X25519MLKEM768 named group.
+pub(crate) const TLS_NAMED_GROUP_X25519MLKEM768: u16 = named_curve::X25519MLKEM768;
+
+const X25519_KEY_SHARE_LEN: usize = 32;
+const X25519MLKEM768_CLIENT_KEY_SHARE_LEN: usize = 1216;
+const X25519MLKEM768_SERVER_KEY_SHARE_LEN: usize = 1120;
+const MLKEM768_CLIENT_ENCAPSULATION_KEY_LEN: usize = 1184;
+const MLKEM768_SERVER_CIPHERTEXT_LEN: usize = 1088;
+
+/// ServerHello key_share selected for the authenticated ClientHello.
+#[derive(Clone, Debug)]
+pub(crate) struct ServerHelloKeyShare {
+    group: u16,
+    key_exchange: Vec<u8>,
+}
+
+impl ServerHelloKeyShare {
+    pub(crate) fn new(group: u16, key_exchange: Vec<u8>) -> Self {
+        Self {
+            group,
+            key_exchange,
+        }
+    }
+
+    pub(crate) fn group(&self) -> u16 {
+        self.group
+    }
+
+    pub(crate) fn key_exchange(&self) -> &[u8] {
+        &self.key_exchange
+    }
 }
 
 // ============= TLS Validation Result =============
@@ -142,26 +181,28 @@ impl TlsExtensionBuilder {
         }
     }
 
-    /// Add Key Share extension with X25519 key
-    fn add_key_share(&mut self, public_key: &[u8; 32]) -> &mut Self {
+    /// Add KeyShare extension with the selected named group.
+    fn add_key_share(&mut self, group: u16, key_exchange: &[u8]) -> &mut Self {
+        let Ok(key_exchange_len) = u16::try_from(key_exchange.len()) else {
+            return self;
+        };
+        let Some(entry_len) = key_exchange.len().checked_add(4) else {
+            return self;
+        };
+        let Ok(entry_len) = u16::try_from(entry_len) else {
+            return self;
+        };
+
         // Extension type: key_share (0x0033)
         self.extensions
             .extend_from_slice(&extension_type::KEY_SHARE.to_be_bytes());
 
-        // Key share entry: curve (2) + key_len (2) + key (32) = 36 bytes
-        // Extension data length
-        let entry_len: u16 = 2 + 2 + 32; // curve + length + key
+        // ServerHello key_share data is exactly one KeyShareEntry.
         self.extensions.extend_from_slice(&entry_len.to_be_bytes());
-
-        // Named curve: x25519
+        self.extensions.extend_from_slice(&group.to_be_bytes());
         self.extensions
-            .extend_from_slice(&named_curve::X25519.to_be_bytes());
-
-        // Key length
-        self.extensions.extend_from_slice(&(32u16).to_be_bytes());
-
-        // Key data
-        self.extensions.extend_from_slice(public_key);
+            .extend_from_slice(&key_exchange_len.to_be_bytes());
+        self.extensions.extend_from_slice(key_exchange);
 
         self
     }
@@ -230,8 +271,8 @@ impl ServerHelloBuilder {
         }
     }
 
-    fn with_x25519_key(mut self, key: &[u8; 32]) -> Self {
-        self.extensions.add_key_share(key);
+    fn with_key_share(mut self, group: u16, key_exchange: &[u8]) -> Self {
+        self.extensions.add_key_share(group, key_exchange);
         self
     }
 
@@ -241,6 +282,13 @@ impl ServerHelloBuilder {
         self
     }
 
+    fn with_cipher_suite(mut self, cipher_suite: [u8; 2]) -> Self {
+        if cipher_suite != [0, 0] {
+            self.cipher_suite = cipher_suite;
+        }
+        self
+    }
+
     /// Build ServerHello message (without record header)
     fn build_message(&self) -> Vec<u8> {
         let Ok(session_id_len) = u8::try_from(self.session_id.len()) else {
@@ -499,9 +547,137 @@ fn validate_tls_handshake_at_time_with_boot_cap(
 /// Uses RFC 7748 X25519 scalar multiplication over the canonical basepoint,
 /// yielding distribution-consistent public keys for anti-fingerprinting.
 pub fn gen_fake_x25519_key(rng: &SecureRandom) -> [u8; 32] {
-    let mut scalar = [0u8; 32];
-    scalar.copy_from_slice(&rng.bytes(32));
-    x25519(scalar, X25519_BASEPOINT_BYTES)
+    let (_scalar, public_key) = gen_x25519_key_pair(rng);
+    public_key
+}
+
+fn gen_x25519_key_pair(rng: &SecureRandom) -> ([u8; 32], [u8; 32]) {
+    let mut scalar = [0u8; X25519_KEY_SHARE_LEN];
+    rng.fill(&mut scalar);
+    let public_key = x25519(scalar, X25519_BASEPOINT_BYTES);
+    (scalar, public_key)
+}
+
+/// Generate a fake X25519MLKEM768 ServerHello key_share payload.
+pub(crate) fn gen_fake_x25519mlkem768_server_key_share(rng: &SecureRandom) -> Vec<u8> {
+    let mut key_share = vec![0u8; X25519MLKEM768_SERVER_KEY_SHARE_LEN];
+    // FakeTLS never derives TLS traffic secrets from this payload; only the
+    // externally visible named group and vector lengths are protocol-facing.
+    rng.fill(&mut key_share[..MLKEM768_SERVER_CIPHERTEXT_LEN]);
+    let x25519_key = gen_fake_x25519_key(rng);
+    key_share[MLKEM768_SERVER_CIPHERTEXT_LEN..].copy_from_slice(&x25519_key);
+    key_share
+}
+
+fn mlkem768_encapsulate_to_client(client_key: &[u8], rng: &SecureRandom) -> Option<Vec<u8>> {
+    let key_bytes = MlKemKey::<MlKemEncapsulationKey<MlKem768>>::try_from(client_key).ok()?;
+    let encapsulation_key = MlKemEncapsulationKey::<MlKem768>::new(&key_bytes).ok()?;
+    let mut randomness = [0u8; 32];
+    rng.fill(&mut randomness);
+    let randomness = B32::try_from(randomness.as_slice()).ok()?;
+    let (ciphertext, _shared_key) = encapsulation_key.encapsulate_deterministic(&randomness);
+    let ciphertext = ciphertext.as_slice().to_vec();
+    if ciphertext.len() == MLKEM768_SERVER_CIPHERTEXT_LEN {
+        Some(ciphertext)
+    } else {
+        None
+    }
+}
+
+/// Build a valid X25519MLKEM768 ServerHello key_share for the authenticated ClientHello.
+pub(crate) fn build_x25519mlkem768_server_key_share(
+    handshake: &[u8],
+    rng: &SecureRandom,
+) -> Option<Vec<u8>> {
+    let client_key_exchange = client_hello_key_share_group_entry(
+        handshake,
+        TLS_NAMED_GROUP_X25519MLKEM768,
+        X25519MLKEM768_CLIENT_KEY_SHARE_LEN,
+    )?;
+    let client_mlkem_key = client_key_exchange.get(..MLKEM768_CLIENT_ENCAPSULATION_KEY_LEN)?;
+    let client_x25519_key = client_key_exchange.get(MLKEM768_CLIENT_ENCAPSULATION_KEY_LEN..)?;
+    let mlkem_ciphertext = mlkem768_encapsulate_to_client(client_mlkem_key, rng)?;
+
+    let mut client_x25519 = [0u8; X25519_KEY_SHARE_LEN];
+    client_x25519.copy_from_slice(client_x25519_key);
+    let (server_x25519_scalar, server_x25519_key) = gen_x25519_key_pair(rng);
+    let x25519_shared = x25519(server_x25519_scalar, client_x25519);
+    if bool::from(x25519_shared.ct_eq(&[0u8; X25519_KEY_SHARE_LEN])) {
+        return None;
+    }
+
+    let mut key_share = Vec::with_capacity(X25519MLKEM768_SERVER_KEY_SHARE_LEN);
+    key_share.extend_from_slice(&mlkem_ciphertext);
+    key_share.extend_from_slice(&server_x25519_key);
+    Some(key_share)
+}
+
+/// Build a valid X25519 ServerHello key_share for the authenticated ClientHello.
+pub(crate) fn build_x25519_server_key_share(
+    handshake: &[u8],
+    rng: &SecureRandom,
+) -> Option<Vec<u8>> {
+    let client_key_exchange = client_hello_key_share_group_entry(
+        handshake,
+        TLS_NAMED_GROUP_X25519,
+        X25519_KEY_SHARE_LEN,
+    )?;
+    let mut client_x25519 = [0u8; X25519_KEY_SHARE_LEN];
+    client_x25519.copy_from_slice(client_key_exchange);
+    let (server_x25519_scalar, server_x25519_key) = gen_x25519_key_pair(rng);
+    let x25519_shared = x25519(server_x25519_scalar, client_x25519);
+    if bool::from(x25519_shared.ct_eq(&[0u8; X25519_KEY_SHARE_LEN])) {
+        return None;
+    }
+
+    Some(server_x25519_key.to_vec())
+}
+
+fn build_server_hello_key_share_for_group(
+    handshake: &[u8],
+    group: u16,
+    rng: &SecureRandom,
+) -> Option<ServerHelloKeyShare> {
+    let expected_key_exchange_len = client_hello_key_share_group_len(group)?;
+    client_hello_key_share_group_entry(handshake, group, expected_key_exchange_len)?;
+
+    // FakeTLS clients validate ServerHello shape and digest, not TLS traffic
+    // secrets, so the response must mirror the offered group without binding to
+    // the camouflage key bytes embedded in ClientHello.
+    match group {
+        TLS_NAMED_GROUP_X25519MLKEM768 => Some(ServerHelloKeyShare::new(
+            group,
+            gen_fake_x25519mlkem768_server_key_share(rng),
+        )),
+        TLS_NAMED_GROUP_X25519 => Some(ServerHelloKeyShare::new(
+            group,
+            gen_fake_x25519_key(rng).to_vec(),
+        )),
+        _ => None,
+    }
+}
+
+fn server_hello_key_share_candidate_order(preferred_group: Option<u16>) -> [u16; 2] {
+    if preferred_group == Some(TLS_NAMED_GROUP_X25519) {
+        [TLS_NAMED_GROUP_X25519, TLS_NAMED_GROUP_X25519MLKEM768]
+    } else {
+        [TLS_NAMED_GROUP_X25519MLKEM768, TLS_NAMED_GROUP_X25519]
+    }
+}
+
+/// Build a ServerHello key_share using a profile-preferred group when possible.
+pub(crate) fn build_server_hello_key_share(
+    handshake: &[u8],
+    preferred_group: Option<u16>,
+    rng: &SecureRandom,
+) -> Option<ServerHelloKeyShare> {
+    for group in server_hello_key_share_candidate_order(preferred_group) {
+        if let Some(key_share) = build_server_hello_key_share_for_group(handshake, group, rng) {
+            return Some(key_share);
+        }
+    }
+
+    None
 }
 
 /// Build TLS ServerHello response
@@ -520,15 +696,48 @@ pub fn build_server_hello(
     rng: &SecureRandom,
     alpn: Option<Vec<u8>>,
     new_session_tickets: u8,
+) -> Vec<u8> {
+    let server_key_share = ServerHelloKeyShare::new(
+        TLS_NAMED_GROUP_X25519MLKEM768,
+        gen_fake_x25519mlkem768_server_key_share(rng),
+    );
+    build_server_hello_with_cipher(
+        secret,
+        client_digest,
+        session_id,
+        fake_cert_len,
+        rng,
+        cipher_suite::TLS_AES_128_GCM_SHA256,
+        &server_key_share,
+        alpn,
+        new_session_tickets,
+    )
+}
+
+/// Build TLS ServerHello response with a caller-selected cipher suite.
+///
+/// The caller is responsible for selecting a suite that is compatible with the
+/// already-authenticated ClientHello. Keeping the selection outside this
+/// builder avoids extra ClientHello parsing in the response construction path.
+pub(crate) fn build_server_hello_with_cipher(
+    secret: &[u8],
+    client_digest: &[u8; TLS_DIGEST_LEN],
+    session_id: &[u8],
+    fake_cert_len: usize,
+    rng: &SecureRandom,
+    selected_cipher_suite: [u8; 2],
+    server_key_share: &ServerHelloKeyShare,
+    alpn: Option<Vec<u8>>,
+    new_session_tickets: u8,
 ) -> Vec<u8> {
     const MIN_APP_DATA: usize = 64;
     const MAX_APP_DATA: usize = MAX_TLS_CIPHERTEXT_SIZE;
     let fake_cert_len = fake_cert_len.clamp(MIN_APP_DATA, MAX_APP_DATA);
-    let x25519_key = gen_fake_x25519_key(rng);
 
     // Build ServerHello
     let server_hello = ServerHelloBuilder::new(session_id.to_vec())
-        .with_x25519_key(&x25519_key)
+        .with_cipher_suite(selected_cipher_suite)
+        .with_key_share(server_key_share.group(), server_key_share.key_exchange())
         .with_tls13_version()
         .build_record();
 
@@ -538,28 +747,14 @@ pub fn build_server_hello(
         TLS_VERSION[0],
         TLS_VERSION[1],
         0x00,
-        0x01, // length = 1
-        0x01, // CCS byte
+        0x01,
+        0x01,
     ];
 
     // Build first encrypted flight mimic as opaque ApplicationData bytes.
-    // Embed a compact EncryptedExtensions-like ALPN block when selected.
+    // ALPN belongs inside encrypted EncryptedExtensions in real TLS 1.3.
     let mut fake_cert = Vec::with_capacity(fake_cert_len);
-    if let Some(proto) = alpn
-        .as_ref()
-        .filter(|p| !p.is_empty() && p.len() <= u8::MAX as usize)
-    {
-        let proto_list_len = 1usize + proto.len();
-        let ext_data_len = 2usize + proto_list_len;
-        let marker_len = 4usize + ext_data_len;
-        if marker_len <= fake_cert_len {
-            fake_cert.extend_from_slice(&0x0010u16.to_be_bytes());
-            fake_cert.extend_from_slice(&(ext_data_len as u16).to_be_bytes());
-            fake_cert.extend_from_slice(&(proto_list_len as u16).to_be_bytes());
-            fake_cert.push(proto.len() as u8);
-            fake_cert.extend_from_slice(proto);
-        }
-    }
+    let _ = alpn;
     if fake_cert.len() < fake_cert_len {
         fake_cert.extend_from_slice(&rng.bytes(fake_cert_len - fake_cert.len()));
     } else if fake_cert.len() > fake_cert_len {
@@ -580,7 +775,7 @@ pub fn build_server_hello(
     let ticket_count = new_session_tickets.min(4);
     if ticket_count > 0 {
         for _ in 0..ticket_count {
-            let ticket_len: usize = rng.range(48) + 48; // 48-95 bytes
+            let ticket_len: usize = rng.range(48) + 48;
             let mut record = Vec::with_capacity(5 + ticket_len);
             record.push(TLS_RECORD_APPLICATION);
             record.extend_from_slice(&TLS_VERSION);
@@ -927,6 +1122,289 @@ pub fn detect_client_hello_tls_version(handshake: &[u8]) -> Option<ClientHelloTl
     }
 }
 
+fn client_hello_cipher_suites_range(handshake: &[u8]) -> Option<(usize, usize)> {
+    if handshake.len() < 5 || handshake[0] != TLS_RECORD_HANDSHAKE {
+        return None;
+    }
+
+    let record_len = u16::from_be_bytes([handshake[3], handshake[4]]) as usize;
+    let record_end = 5usize.checked_add(record_len)?;
+    if record_end > handshake.len() {
+        return None;
+    }
+
+    let mut pos = 5;
+    if handshake.get(pos) != Some(&0x01) {
+        return None;
+    }
+    pos += 1;
+
+    if pos + 3 > record_end {
+        return None;
+    }
+    let handshake_len = ((handshake[pos] as usize) << 16)
+        | ((handshake[pos + 1] as usize) << 8)
+        | handshake[pos + 2] as usize;
+    pos += 3;
+    let handshake_end = pos.checked_add(handshake_len)?;
+    if handshake_end > record_end {
+        return None;
+    }
+
+    if pos + 2 + 32 > handshake_end {
+        return None;
+    }
+    pos += 2 + 32;
+
+    let session_id_len = *handshake.get(pos)? as usize;
+    pos = pos.checked_add(1)?.checked_add(session_id_len)?;
+    if pos + 2 > handshake_end {
+        return None;
+    }
+
+    let cipher_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
+    if cipher_len == 0 || cipher_len % 2 != 0 {
+        return None;
+    }
+    pos += 2;
+    let cipher_end = pos.checked_add(cipher_len)?;
+    if cipher_end > handshake_end {
+        return None;
+    }
+
+    Some((pos, cipher_end))
+}
+
+fn client_hello_extensions_range(handshake: &[u8]) -> Option<(usize, usize)> {
+    if handshake.len() < 5 || handshake[0] != TLS_RECORD_HANDSHAKE {
+        return None;
+    }
+
+    let record_len = u16::from_be_bytes([handshake[3], handshake[4]]) as usize;
+    let record_end = 5usize.checked_add(record_len)?;
+    if record_end > handshake.len() {
+        return None;
+    }
+
+    let mut pos = 5;
+    if handshake.get(pos) != Some(&0x01) {
+        return None;
+    }
+    pos += 1;
+
+    if pos + 3 > record_end {
+        return None;
+    }
+    let handshake_len = ((handshake[pos] as usize) << 16)
+        | ((handshake[pos + 1] as usize) << 8)
+        | handshake[pos + 2] as usize;
+    pos += 3;
+    let handshake_end = pos.checked_add(handshake_len)?;
+    if handshake_end > record_end {
+        return None;
+    }
+
+    if pos + 2 + 32 > handshake_end {
+        return None;
+    }
+    pos += 2 + 32;
+
+    let session_id_len = *handshake.get(pos)? as usize;
+    pos = pos.checked_add(1)?.checked_add(session_id_len)?;
+    if pos + 2 > handshake_end {
+        return None;
+    }
+
+    let cipher_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
+    if cipher_len == 0 || cipher_len % 2 != 0 {
+        return None;
+    }
+    pos += 2;
+    pos = pos.checked_add(cipher_len)?;
+    if pos + 1 > handshake_end {
+        return None;
+    }
+
+    let compression_len = *handshake.get(pos)? as usize;
+    pos = pos.checked_add(1)?.checked_add(compression_len)?;
+    if pos == handshake_end {
+        return Some((handshake_end, handshake_end));
+    }
+    if pos + 2 > handshake_end {
+        return None;
+    }
+
+    let extensions_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
+    pos += 2;
+    let extensions_end = pos.checked_add(extensions_len)?;
+    if extensions_end > handshake_end {
+        return None;
+    }
+
+    Some((pos, extensions_end))
+}
+
+fn key_share_extension_group_entry<'a>(
+    data: &'a [u8],
+    group: u16,
+    expected_key_exchange_len: usize,
+) -> Option<&'a [u8]> {
+    if data.len() < 2 {
+        return None;
+    }
+
+    let shares_len = u16::from_be_bytes([data[0], data[1]]) as usize;
+    if shares_len != data.len().saturating_sub(2) {
+        return None;
+    }
+
+    let mut pos = 2usize;
+    let shares_end = 2 + shares_len;
+    let mut found_group = None;
+    while pos + 4 <= shares_end {
+        let entry_group = u16::from_be_bytes([data[pos], data[pos + 1]]);
+        let key_exchange_len = u16::from_be_bytes([data[pos + 2], data[pos + 3]]) as usize;
+        pos += 4;
+        let Some(key_exchange_end) = pos.checked_add(key_exchange_len) else {
+            return None;
+        };
+        if key_exchange_end > shares_end {
+            return None;
+        }
+        if entry_group == group {
+            if key_exchange_len != expected_key_exchange_len || found_group.is_some() {
+                return None;
+            }
+            found_group = Some(&data[pos..key_exchange_end]);
+        }
+        pos = key_exchange_end;
+    }
+
+    if pos == shares_end { found_group } else { None }
+}
+
+fn client_hello_key_share_group_entry<'a>(
+    handshake: &'a [u8],
+    group: u16,
+    expected_key_exchange_len: usize,
+) -> Option<&'a [u8]> {
+    let Some((mut pos, extensions_end)) = client_hello_extensions_range(handshake) else {
+        return None;
+    };
+
+    while pos + 4 <= extensions_end {
+        let ext_type = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]);
+        let ext_len = u16::from_be_bytes([handshake[pos + 2], handshake[pos + 3]]) as usize;
+        pos += 4;
+        let Some(ext_end) = pos.checked_add(ext_len) else {
+            return None;
+        };
+        if ext_end > extensions_end {
+            return None;
+        }
+
+        if ext_type == extension_type::KEY_SHARE {
+            return key_share_extension_group_entry(
+                &handshake[pos..ext_end],
+                group,
+                expected_key_exchange_len,
+            );
+        }
+
+        pos = ext_end;
+    }
+
+    None
+}
+
+fn client_hello_offers_cipher_suite(
+    handshake: &[u8],
+    range: (usize, usize),
+    suite: [u8; 2],
+) -> bool {
+    let mut pos = range.0;
+    while pos + 1 < range.1 {
+        if handshake[pos] == suite[0] && handshake[pos + 1] == suite[1] {
+            return true;
+        }
+        pos += 2;
+    }
+    false
+}
+
+fn is_tls13_cipher_suite(suite: [u8; 2]) -> bool {
+    suite == cipher_suite::TLS_AES_128_GCM_SHA256
+        || suite == cipher_suite::TLS_AES_256_GCM_SHA384
+        || suite == cipher_suite::TLS_CHACHA20_POLY1305_SHA256
+}
+
+/// Select the ServerHello cipher suite from the already-received ClientHello.
+///
+/// This is intentionally a borrowed, zero-allocation scan. It runs only for an
+/// authenticated success response and fails closed for malformed or unsupported
+/// ClientHello shapes that cannot produce a DPI-consistent ServerHello.
+pub(crate) fn select_server_hello_cipher_suite(
+    handshake: &[u8],
+    preferred: [u8; 2],
+) -> Option<[u8; 2]> {
+    let preferred = if is_tls13_cipher_suite(preferred) {
+        preferred
+    } else {
+        cipher_suite::TLS_AES_128_GCM_SHA256
+    };
+    let Some(range) = client_hello_cipher_suites_range(handshake) else {
+        return None;
+    };
+
+    if client_hello_offers_cipher_suite(handshake, range, preferred) {
+        return Some(preferred);
+    }
+
+    for fallback in [
+        cipher_suite::TLS_AES_128_GCM_SHA256,
+        cipher_suite::TLS_CHACHA20_POLY1305_SHA256,
+        cipher_suite::TLS_AES_256_GCM_SHA384,
+    ] {
+        if client_hello_offers_cipher_suite(handshake, range, fallback) {
+            return Some(fallback);
+        }
+    }
+
+    None
+}
+
+fn client_hello_key_share_group_len(group: u16) -> Option<usize> {
+    match group {
+        TLS_NAMED_GROUP_X25519MLKEM768 => Some(X25519MLKEM768_CLIENT_KEY_SHARE_LEN),
+        TLS_NAMED_GROUP_X25519 => Some(X25519_KEY_SHARE_LEN),
+        _ => None,
+    }
+}
+
+/// Select the ServerHello key_share named group from the authenticated ClientHello.
+///
+/// Malformed key_share structures fail closed so authenticated but
+/// DPI-inconsistent ClientHellos take the ordinary masking fallback path.
+pub(crate) fn select_server_hello_key_share_group(handshake: &[u8]) -> Option<u16> {
+    select_server_hello_key_share_group_with_preference(handshake, None)
+}
+
+/// Select the ServerHello key_share named group with an origin-profile preference.
+pub(crate) fn select_server_hello_key_share_group_with_preference(
+    handshake: &[u8],
+    preferred_group: Option<u16>,
+) -> Option<u16> {
+    for group in server_hello_key_share_candidate_order(preferred_group) {
+        let expected_key_exchange_len = client_hello_key_share_group_len(group)?;
+        if client_hello_key_share_group_entry(handshake, group, expected_key_exchange_len).is_some()
+        {
+            return Some(group);
+        }
+    }
+
+    None
+}
+
 /// Check if bytes look like a TLS ClientHello
 pub fn is_tls_handshake(first_bytes: &[u8]) -> bool {
     if first_bytes.len() < 3 {

src/protocol/tls_fingerprint.rs

@@ -0,0 +1,450 @@
+//! Passive JA3 / JA4 TLS ClientHello fingerprinting.
+
+use crate::crypto::hash::md5;
+use crate::crypto::sha256;
+use crate::protocol::constants::TLS_RECORD_HANDSHAKE;
+
+const EXT_SNI: u16 = 0x0000;
+const EXT_SUPPORTED_GROUPS: u16 = 0x000a;
+const EXT_EC_POINT_FORMATS: u16 = 0x000b;
+const EXT_SIGNATURE_ALGORITHMS: u16 = 0x000d;
+const EXT_ALPN: u16 = 0x0010;
+const EXT_SUPPORTED_VERSIONS: u16 = 0x002b;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct TlsClientFingerprint {
+    pub ja3: String,
+    pub ja3_raw: String,
+    pub ja4: String,
+    pub ja4_raw: String,
+}
+
+#[derive(Default)]
+struct ParsedClientHello {
+    legacy_version: u16,
+    ciphers: Vec<u16>,
+    extensions: Vec<u16>,
+    supported_groups: Vec<u16>,
+    ec_point_formats: Vec<u8>,
+    signature_algorithms: Vec<u16>,
+    supported_versions: Vec<u16>,
+    alpn_first: Option<Vec<u8>>,
+    sni_present: bool,
+}
+
+pub fn fingerprint_client_hello(handshake: &[u8]) -> Option<TlsClientFingerprint> {
+    let parsed = parse_client_hello(handshake)?;
+    let ja3_raw = ja3_raw(&parsed);
+    let ja3 = hex::encode(md5(ja3_raw.as_bytes()));
+    let (ja4, ja4_raw) = ja4(&parsed);
+
+    Some(TlsClientFingerprint {
+        ja3,
+        ja3_raw,
+        ja4,
+        ja4_raw,
+    })
+}
+
+fn parse_client_hello(handshake: &[u8]) -> Option<ParsedClientHello> {
+    if handshake.len() < 5 || handshake[0] != TLS_RECORD_HANDSHAKE {
+        return None;
+    }
+
+    let record_len = read_u16_at(handshake, 3)? as usize;
+    let record_end = 5usize.checked_add(record_len)?;
+    if record_end > handshake.len() {
+        return None;
+    }
+
+    let mut pos = 5usize;
+    if *handshake.get(pos)? != 0x01 {
+        return None;
+    }
+    pos = pos.checked_add(1)?;
+
+    if pos + 3 > record_end {
+        return None;
+    }
+    let handshake_len = ((usize::from(handshake[pos])) << 16)
+        | ((usize::from(handshake[pos + 1])) << 8)
+        | usize::from(handshake[pos + 2]);
+    pos = pos.checked_add(3)?;
+    let handshake_end = pos.checked_add(handshake_len)?;
+    if handshake_end > record_end {
+        return None;
+    }
+
+    if pos + 2 + 32 > handshake_end {
+        return None;
+    }
+    let legacy_version = read_u16_at(handshake, pos)?;
+    pos = pos.checked_add(2 + 32)?;
+
+    let session_id_len = usize::from(*handshake.get(pos)?);
+    pos = pos.checked_add(1)?.checked_add(session_id_len)?;
+    if pos + 2 > handshake_end {
+        return None;
+    }
+
+    let cipher_len = read_u16_at(handshake, pos)? as usize;
+    pos = pos.checked_add(2)?;
+    let cipher_end = pos.checked_add(cipher_len)?;
+    if cipher_end > handshake_end || cipher_len % 2 != 0 {
+        return None;
+    }
+    let mut ciphers = Vec::with_capacity(cipher_len / 2);
+    while pos + 1 < cipher_end {
+        let value = read_u16_at(handshake, pos)?;
+        if !is_grease(value) {
+            ciphers.push(value);
+        }
+        pos = pos.checked_add(2)?;
+    }
+
+    let comp_len = usize::from(*handshake.get(pos)?);
+    pos = pos.checked_add(1)?.checked_add(comp_len)?;
+    if pos > handshake_end {
+        return None;
+    }
+
+    let mut parsed = ParsedClientHello {
+        legacy_version,
+        ciphers,
+        ..ParsedClientHello::default()
+    };
+
+    if pos == handshake_end {
+        return Some(parsed);
+    }
+    if pos + 2 > handshake_end {
+        return None;
+    }
+
+    let ext_len = read_u16_at(handshake, pos)? as usize;
+    pos = pos.checked_add(2)?;
+    let ext_end = pos.checked_add(ext_len)?;
+    if ext_end > handshake_end {
+        return None;
+    }
+
+    while pos + 4 <= ext_end {
+        let etype = read_u16_at(handshake, pos)?;
+        let elen = read_u16_at(handshake, pos + 2)? as usize;
+        pos = pos.checked_add(4)?;
+        let data_end = pos.checked_add(elen)?;
+        if data_end > ext_end {
+            return None;
+        }
+        let data = handshake.get(pos..data_end)?;
+
+        if !is_grease(etype) {
+            parsed.extensions.push(etype);
+            match etype {
+                EXT_SNI => parsed.sni_present = true,
+                EXT_SUPPORTED_GROUPS => {
+                    parsed.supported_groups = parse_u16_vector(data, 2)?;
+                }
+                EXT_EC_POINT_FORMATS => {
+                    parsed.ec_point_formats = parse_u8_vector(data)?;
+                }
+                EXT_SIGNATURE_ALGORITHMS => {
+                    parsed.signature_algorithms = parse_u16_vector(data, 2)?;
+                }
+                EXT_ALPN => {
+                    parsed.alpn_first = parse_alpn_first(data)?;
+                }
+                EXT_SUPPORTED_VERSIONS => {
+                    parsed.supported_versions = parse_u16_vector(data, 1)?;
+                }
+                _ => {}
+            }
+        }
+
+        pos = data_end;
+    }
+
+    if pos != ext_end {
+        return None;
+    }
+
+    Some(parsed)
+}
+
+fn parse_u16_vector(data: &[u8], len_prefix_len: usize) -> Option<Vec<u16>> {
+    let (list_len, mut pos) = match len_prefix_len {
+        1 => (usize::from(*data.first()?), 1usize),
+        2 => (read_u16_at(data, 0)? as usize, 2usize),
+        _ => return None,
+    };
+    let list_end = pos.checked_add(list_len)?;
+    if list_end > data.len() || list_len % 2 != 0 {
+        return None;
+    }
+
+    let mut out = Vec::with_capacity(list_len / 2);
+    while pos + 1 < list_end {
+        let value = read_u16_at(data, pos)?;
+        if !is_grease(value) {
+            out.push(value);
+        }
+        pos = pos.checked_add(2)?;
+    }
+    Some(out)
+}
+
+fn parse_u8_vector(data: &[u8]) -> Option<Vec<u8>> {
+    let list_len = usize::from(*data.first()?);
+    let list_start = 1usize;
+    let list_end = list_start.checked_add(list_len)?;
+    if list_end > data.len() {
+        return None;
+    }
+    Some(data.get(list_start..list_end)?.to_vec())
+}
+
+fn parse_alpn_first(data: &[u8]) -> Option<Option<Vec<u8>>> {
+    if data.len() < 2 {
+        return None;
+    }
+    let list_len = read_u16_at(data, 0)? as usize;
+    let mut pos = 2usize;
+    let list_end = pos.checked_add(list_len)?;
+    if list_end > data.len() {
+        return None;
+    }
+    if pos == list_end {
+        return Some(None);
+    }
+
+    let protocol_len = usize::from(*data.get(pos)?);
+    pos = pos.checked_add(1)?;
+    let protocol_end = pos.checked_add(protocol_len)?;
+    if protocol_end > list_end {
+        return None;
+    }
+    if protocol_len == 0 {
+        return Some(None);
+    }
+    Some(Some(data.get(pos..protocol_end)?.to_vec()))
+}
+
+fn ja3_raw(parsed: &ParsedClientHello) -> String {
+    format!(
+        "{},{},{},{},{}",
+        parsed.legacy_version,
+        join_decimal_u16(&parsed.ciphers),
+        join_decimal_u16(&parsed.extensions),
+        join_decimal_u16(&parsed.supported_groups),
+        join_decimal_u8(&parsed.ec_point_formats)
+    )
+}
+
+fn ja4(parsed: &ParsedClientHello) -> (String, String) {
+    let a = format!(
+        "t{}{}{:02}{:02}{}",
+        ja4_version_code(parsed),
+        if parsed.sni_present { "d" } else { "i" },
+        count_ja4(parsed.ciphers.len()),
+        count_ja4(parsed.extensions.len()),
+        ja4_alpn_marker(parsed.alpn_first.as_deref())
+    );
+
+    let mut ciphers = parsed.ciphers.clone();
+    ciphers.sort_unstable();
+    let cipher_raw = join_hex_u16(&ciphers);
+    let cipher_hash = if ciphers.is_empty() {
+        "000000000000".to_string()
+    } else {
+        sha256_truncated_12(&cipher_raw)
+    };
+
+    let mut extensions_for_hash = parsed
+        .extensions
+        .iter()
+        .copied()
+        .filter(|value| *value != EXT_SNI && *value != EXT_ALPN)
+        .collect::<Vec<_>>();
+    extensions_for_hash.sort_unstable();
+    let extension_raw = join_hex_u16(&extensions_for_hash);
+    let signature_raw = join_hex_u16(&parsed.signature_algorithms);
+    let extension_hash_input = if signature_raw.is_empty() {
+        extension_raw.clone()
+    } else {
+        format!("{extension_raw}_{signature_raw}")
+    };
+    let extension_hash = if extensions_for_hash.is_empty() {
+        "000000000000".to_string()
+    } else {
+        sha256_truncated_12(&extension_hash_input)
+    };
+
+    (
+        format!("{a}_{cipher_hash}_{extension_hash}"),
+        format!("{a}_{cipher_raw}_{extension_hash_input}"),
+    )
+}
+
+fn ja4_version_code(parsed: &ParsedClientHello) -> &'static str {
+    let version = parsed
+        .supported_versions
+        .iter()
+        .copied()
+        .max()
+        .unwrap_or(parsed.legacy_version);
+    match version {
+        0x0304 => "13",
+        0x0303 => "12",
+        0x0302 => "11",
+        0x0301 => "10",
+        0x0300 => "s3",
+        0x0002 => "s2",
+        0xfeff => "d1",
+        0xfefd => "d2",
+        0xfefc => "d3",
+        _ => "00",
+    }
+}
+
+fn ja4_alpn_marker(alpn_first: Option<&[u8]>) -> String {
+    let Some(value) = alpn_first else {
+        return "00".to_string();
+    };
+    let Some(first) = value.first().copied() else {
+        return "00".to_string();
+    };
+    let last = value.last().copied().unwrap_or(first);
+    if first.is_ascii_alphanumeric() && last.is_ascii_alphanumeric() {
+        return format!("{}{}", first as char, last as char);
+    }
+
+    let encoded = hex::encode(value);
+    if encoded.is_empty() {
+        return "00".to_string();
+    }
+    let first_hex = encoded.as_bytes()[0] as char;
+    let last_hex = encoded.as_bytes()[encoded.len().saturating_sub(1)] as char;
+    format!("{first_hex}{last_hex}")
+}
+
+fn count_ja4(count: usize) -> usize {
+    count.min(99)
+}
+
+fn sha256_truncated_12(input: &str) -> String {
+    let mut encoded = hex::encode(sha256(input.as_bytes()));
+    encoded.truncate(12);
+    encoded
+}
+
+fn join_decimal_u16(values: &[u16]) -> String {
+    values
+        .iter()
+        .map(u16::to_string)
+        .collect::<Vec<_>>()
+        .join("-")
+}
+
+fn join_decimal_u8(values: &[u8]) -> String {
+    values
+        .iter()
+        .map(u8::to_string)
+        .collect::<Vec<_>>()
+        .join("-")
+}
+
+fn join_hex_u16(values: &[u16]) -> String {
+    values
+        .iter()
+        .map(|value| format!("{value:04x}"))
+        .collect::<Vec<_>>()
+        .join(",")
+}
+
+fn read_u16_at(buf: &[u8], pos: usize) -> Option<u16> {
+    Some(u16::from_be_bytes([
+        *buf.get(pos)?,
+        *buf.get(pos.checked_add(1)?)?,
+    ]))
+}
+
+fn is_grease(value: u16) -> bool {
+    let high = (value >> 8) as u8;
+    let low = value as u8;
+    high == low && (high & 0x0f) == 0x0a
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample_client_hello() -> Vec<u8> {
+        let mut body = Vec::new();
+        body.extend_from_slice(&[0x03, 0x03]);
+        body.extend_from_slice(&[0x11; 32]);
+        body.push(0);
+        body.extend_from_slice(&10u16.to_be_bytes());
+        body.extend_from_slice(&[0x0a, 0x0a, 0x13, 0x01, 0x13, 0x02, 0xc0, 0x2f, 0x00, 0xff]);
+        body.push(1);
+        body.push(0);
+
+        let mut extensions = Vec::new();
+        append_ext(&mut extensions, EXT_SNI, &[0, 0]);
+        append_ext(&mut extensions, EXT_ALPN, &[0, 3, 2, b'h', b'2']);
+        append_ext(
+            &mut extensions,
+            EXT_SUPPORTED_GROUPS,
+            &[0, 6, 0x0a, 0x0a, 0x00, 0x17, 0x00, 0x1d],
+        );
+        append_ext(&mut extensions, EXT_EC_POINT_FORMATS, &[1, 0]);
+        append_ext(
+            &mut extensions,
+            EXT_SIGNATURE_ALGORITHMS,
+            &[0, 4, 0x04, 0x03, 0x08, 0x04],
+        );
+        append_ext(
+            &mut extensions,
+            EXT_SUPPORTED_VERSIONS,
+            &[4, 0x03, 0x04, 0x03, 0x03],
+        );
+        body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+        body.extend_from_slice(&extensions);
+
+        let mut record = Vec::new();
+        record.push(TLS_RECORD_HANDSHAKE);
+        record.extend_from_slice(&[0x03, 0x01]);
+        record.extend_from_slice(&((body.len() + 4) as u16).to_be_bytes());
+        record.push(0x01);
+        record.extend_from_slice(&[
+            ((body.len() >> 16) & 0xff) as u8,
+            ((body.len() >> 8) & 0xff) as u8,
+            (body.len() & 0xff) as u8,
+        ]);
+        record.extend_from_slice(&body);
+        record
+    }
+
+    fn append_ext(out: &mut Vec<u8>, etype: u16, data: &[u8]) {
+        out.extend_from_slice(&etype.to_be_bytes());
+        out.extend_from_slice(&(data.len() as u16).to_be_bytes());
+        out.extend_from_slice(data);
+    }
+
+    #[test]
+    fn ja3_and_ja4_ignore_grease_and_remain_stable() {
+        let fp = fingerprint_client_hello(&sample_client_hello())
+            .expect("sample ClientHello must fingerprint");
+        assert_eq!(
+            fp.ja3_raw,
+            "771,4865-4866-49199-255,0-16-10-11-13-43,23-29,0"
+        );
+        assert!(fp.ja4.starts_with("t13d0406h2_"));
+    }
+
+    #[test]
+    fn malformed_client_hello_returns_none() {
+        let mut hello = sample_client_hello();
+        hello.truncate(12);
+        assert!(fingerprint_client_hello(&hello).is_none());
+    }
+}

src/proxy/client.rs

@@ -98,6 +98,7 @@ use crate::error::{HandshakeResult, ProxyError, Result, StreamError};
 use crate::ip_tracker::UserIpTracker;
 use crate::protocol::constants::*;
 use crate::protocol::tls;
+use crate::protocol::tls_fingerprint::{self, TlsClientFingerprint};
 use crate::stats::beobachten::BeobachtenStore;
 use crate::stats::{ReplayChecker, Stats};
 use crate::stream::{BufferPool, CryptoReader, CryptoWriter};
@@ -350,6 +351,60 @@ fn record_beobachten_class(
     beobachten.record(class, peer_ip, beobachten_ttl(config));
 }
 
+fn tls_fingerprint_collection_enabled(config: &ProxyConfig) -> bool {
+    config.general.beobachten || config.server.api.runtime_edge_enabled
+}
+
+fn observe_tls_client_fingerprint(
+    stats: &Stats,
+    config: &ProxyConfig,
+    peer_ip: IpAddr,
+    handshake: &[u8],
+) -> Option<TlsClientFingerprint> {
+    if !tls_fingerprint_collection_enabled(config) {
+        return None;
+    }
+
+    match tls_fingerprint::fingerprint_client_hello(handshake) {
+        Some(fingerprint) => {
+            stats.record_tls_fingerprint_observed(&fingerprint, peer_ip, beobachten_ttl(config));
+            Some(fingerprint)
+        }
+        None => {
+            stats.increment_tls_fingerprint_parse_error();
+            None
+        }
+    }
+}
+
+fn record_tls_fingerprint_auth_success(
+    stats: &Stats,
+    config: &ProxyConfig,
+    peer_ip: IpAddr,
+    fingerprint: Option<&TlsClientFingerprint>,
+    user: &str,
+) {
+    if let Some(fingerprint) = fingerprint {
+        stats.record_tls_fingerprint_auth_success(
+            fingerprint,
+            peer_ip,
+            user,
+            beobachten_ttl(config),
+        );
+    }
+}
+
+fn record_tls_fingerprint_bad_or_probe(
+    stats: &Stats,
+    config: &ProxyConfig,
+    peer_ip: IpAddr,
+    fingerprint: Option<&TlsClientFingerprint>,
+) {
+    if let Some(fingerprint) = fingerprint {
+        stats.record_tls_fingerprint_bad_or_probe(fingerprint, peer_ip, beobachten_ttl(config));
+    }
+}
+
 fn classify_expected_64_got_0(kind: std::io::ErrorKind) -> Option<&'static str> {
     match kind {
         std::io::ErrorKind::UnexpectedEof => Some("expected_64_got_0_unexpected_eof"),
@@ -705,6 +760,9 @@ where
                 ));
             }
 
+            let tls_fingerprint =
+                observe_tls_client_fingerprint(stats.as_ref(), &config, real_peer.ip(), &handshake);
+
             let (read_half, write_half) = tokio::io::split(stream);
 
             let (mut tls_reader, tls_writer, tls_user) = match handle_tls_handshake_with_shared(
@@ -715,6 +773,12 @@ where
                 HandshakeResult::Success(result) => result,
                 HandshakeResult::BadClient { reader, writer } => {
                     stats.increment_connects_bad_with_class("tls_handshake_bad_client");
+                    record_tls_fingerprint_bad_or_probe(
+                        stats.as_ref(),
+                        &config,
+                        real_peer.ip(),
+                        tls_fingerprint.as_ref(),
+                    );
                     return Ok(masking_outcome(
                         reader,
                         writer,
@@ -726,10 +790,23 @@ where
                     ));
                 }
                 HandshakeResult::Error(e) => {
+                    record_tls_fingerprint_bad_or_probe(
+                        stats.as_ref(),
+                        &config,
+                        real_peer.ip(),
+                        tls_fingerprint.as_ref(),
+                    );
                     increment_bad_on_unknown_tls_sni(stats.as_ref(), &e);
                     return Err(e);
                 }
             };
+            record_tls_fingerprint_auth_success(
+                stats.as_ref(),
+                &config,
+                real_peer.ip(),
+                tls_fingerprint.as_ref(),
+                tls_user.as_str(),
+            );
 
             debug!(peer = %peer, "Reading MTProto handshake through TLS");
             let mtproto_data = tls_reader.read_exact(HANDSHAKE_LEN).await?;
@@ -1295,6 +1372,13 @@ impl RunningClientHandler {
             ));
         }
 
+        let tls_fingerprint = observe_tls_client_fingerprint(
+            self.stats.as_ref(),
+            &self.config,
+            peer.ip(),
+            &handshake,
+        );
+
         let config = self.config.clone();
         let replay_checker = self.replay_checker.clone();
         let stats = self.stats.clone();
@@ -1318,6 +1402,12 @@ impl RunningClientHandler {
             HandshakeResult::Success(result) => result,
             HandshakeResult::BadClient { reader, writer } => {
                 stats.increment_connects_bad_with_class("tls_handshake_bad_client");
+                record_tls_fingerprint_bad_or_probe(
+                    stats.as_ref(),
+                    &config,
+                    peer.ip(),
+                    tls_fingerprint.as_ref(),
+                );
                 return Ok(masking_outcome(
                     reader,
                     writer,
@@ -1329,10 +1419,23 @@ impl RunningClientHandler {
                 ));
             }
             HandshakeResult::Error(e) => {
+                record_tls_fingerprint_bad_or_probe(
+                    stats.as_ref(),
+                    &config,
+                    peer.ip(),
+                    tls_fingerprint.as_ref(),
+                );
                 increment_bad_on_unknown_tls_sni(stats.as_ref(), &e);
                 return Err(e);
             }
         };
+        record_tls_fingerprint_auth_success(
+            stats.as_ref(),
+            &config,
+            peer.ip(),
+            tls_fingerprint.as_ref(),
+            tls_user.as_str(),
+        );
 
         debug!(peer = %peer, "Reading MTProto handshake through TLS");
         let mtproto_data = tls_reader.read_exact(HANDSHAKE_LEN).await?;
@@ -1558,6 +1661,11 @@ impl RunningClientHandler {
     {
         let user = success.user.clone();
 
+        if !shared.is_user_enabled(&user) {
+            warn!(user = %user, "Disabled user rejected");
+            return Err(ProxyError::UserDisabled { user });
+        }
+
         let user_limit_reservation = match Self::acquire_user_connection_reservation_static(
             &user,
             &config,
@@ -1576,6 +1684,8 @@ impl RunningClientHandler {
 
         let route_snapshot = route_runtime.snapshot();
         let session_id = rng.u64();
+        let _user_session = shared.register_user_session(&user, session_id);
+        let session_cancel = _user_session.token();
         let selected_me_pool = if config.general.use_middle_proxy
             && matches!(route_snapshot.mode, RelayRouteMode::Middle)
         {
@@ -1607,6 +1717,7 @@ impl RunningClientHandler {
                     route_runtime.subscribe(),
                     route_snapshot,
                     session_id,
+                    session_cancel.clone(),
                     shared.clone(),
                 )
                 .await
@@ -1625,6 +1736,7 @@ impl RunningClientHandler {
                     route_snapshot,
                     session_id,
                     local_addr,
+                    session_cancel.clone(),
                     shared.clone(),
                 )
                 .await
@@ -1644,6 +1756,7 @@ impl RunningClientHandler {
                 route_snapshot,
                 session_id,
                 local_addr,
+                session_cancel,
                 shared.clone(),
             )
             .await

src/proxy/direct_relay.rs

@@ -10,6 +10,7 @@ use std::time::Duration;
 
 use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt, ReadHalf, WriteHalf, split};
 use tokio::sync::watch;
+use tokio_util::sync::CancellationToken;
 use tracing::{debug, info, warn};
 
 use crate::config::ProxyConfig;
@@ -258,6 +259,7 @@ where
         route_snapshot,
         session_id,
         SocketAddr::from(([0, 0, 0, 0], config.server.port)),
+        CancellationToken::new(),
         ProxySharedState::new(),
     )
     .await
@@ -276,6 +278,7 @@ pub(crate) async fn handle_via_direct_with_shared<R, W>(
     route_snapshot: RouteCutoverState,
     session_id: u64,
     local_addr: SocketAddr,
+    session_cancel: CancellationToken,
     shared: Arc<ProxySharedState>,
 ) -> Result<()>
 where
@@ -302,14 +305,25 @@ where
             "Ignoring invalid scope hint and falling back to default upstream selection"
         );
     }
-    let tg_stream = upstream_manager
-        .connect(dc_addr, Some(success.dc_idx), scope_hint)
-        .await?;
+    let tg_stream = tokio::select! {
+        result = upstream_manager.connect(dc_addr, Some(success.dc_idx), scope_hint) => result?,
+        _ = session_cancel.cancelled() => {
+            return Err(ProxyError::UserDisabled {
+                user: user.to_string(),
+            });
+        }
+    };
 
     debug!(peer = %success.peer, dc_addr = %dc_addr, "Connected, performing TG handshake");
 
-    let (tg_reader, tg_writer) =
-        do_tg_handshake_static(tg_stream, &success, &config, rng.as_ref()).await?;
+    let (tg_reader, tg_writer) = tokio::select! {
+        result = do_tg_handshake_static(tg_stream, &success, &config, rng.as_ref()) => result?,
+        _ = session_cancel.cancelled() => {
+            return Err(ProxyError::UserDisabled {
+                user: user.to_string(),
+            });
+        }
+    };
 
     debug!(peer = %success.peer, "TG handshake complete, starting relay");
 
@@ -331,20 +345,22 @@ where
     } else {
         Duration::from_secs(1800)
     };
-    let relay_result = crate::proxy::relay::relay_bidirectional_with_activity_timeout_and_lease(
-        client_reader,
-        client_writer,
-        tg_reader,
-        tg_writer,
-        config.general.direct_relay_copy_buf_c2s_bytes,
-        config.general.direct_relay_copy_buf_s2c_bytes,
-        user,
-        Arc::clone(&stats),
-        config.access.user_data_quota.get(user).copied(),
-        buffer_pool,
-        traffic_lease,
-        relay_activity_timeout,
-    );
+    let relay_result =
+        crate::proxy::relay::relay_bidirectional_with_activity_timeout_lease_and_cancel(
+            client_reader,
+            client_writer,
+            tg_reader,
+            tg_writer,
+            config.general.direct_relay_copy_buf_c2s_bytes,
+            config.general.direct_relay_copy_buf_s2c_bytes,
+            user,
+            Arc::clone(&stats),
+            config.access.user_data_quota.get(user).copied(),
+            buffer_pool,
+            traffic_lease,
+            relay_activity_timeout,
+            session_cancel.clone(),
+        );
     tokio::pin!(relay_result);
     let relay_result = loop {
         if let Some(cutover) =
@@ -358,6 +374,7 @@ where
                 delay_ms = delay.as_millis() as u64,
                 "Cutover affected direct session, closing client connection"
             );
+            let _cutover_park_lease = stats.acquire_direct_cutover_park_lease();
             tokio::time::sleep(delay).await;
             break Err(ProxyError::RouteSwitched);
         }
@@ -370,6 +387,11 @@ where
                     break relay_result.await;
                 }
             }
+            _ = session_cancel.cancelled() => {
+                break Err(ProxyError::UserDisabled {
+                    user: user.to_string(),
+                });
+            }
         }
     };
 

src/proxy/handshake.rs

@@ -1473,14 +1473,60 @@ where
         return HandshakeResult::BadClient { reader, writer };
     }
 
-    let cached = if config.censorship.tls_emulation {
+    let cached_entry = if config.censorship.tls_emulation {
         if let Some(cache) = tls_cache.as_ref() {
             let selected_domain =
                 matched_tls_domain.unwrap_or(config.censorship.tls_domain.as_str());
             let cached_entry = cache.get(selected_domain).await;
-            let use_full_cert_payload = if config.censorship.serverhello_compact
-                && matches!(client_tls_version, tls::ClientHelloTlsVersion::Tls12)
-            {
+            Some(cached_entry)
+        } else {
+            None
+        }
+    } else {
+        None
+    };
+
+    let preferred_key_share_group = cached_entry
+        .as_ref()
+        .and_then(|cached_entry| emulator::profiled_server_hello_key_share_group(cached_entry));
+    let Some(server_key_share) =
+        tls::build_server_hello_key_share(handshake, preferred_key_share_group, rng)
+    else {
+        auth_probe_record_failure_in(shared, peer.ip(), Instant::now());
+        maybe_apply_server_hello_delay(config).await;
+        debug!(
+            peer = %peer,
+            "TLS handshake rejected: ClientHello did not offer a usable TLS 1.3 key_share"
+        );
+        return HandshakeResult::BadClient { reader, writer };
+    };
+
+    let preferred_cipher_suite = if let Some(cached_entry) = cached_entry.as_ref() {
+        if cached_entry.server_hello_template.cipher_suite == [0, 0] {
+            [0x13, 0x01]
+        } else {
+            cached_entry.server_hello_template.cipher_suite
+        }
+    } else {
+        [0x13, 0x01]
+    };
+    let Some(selected_cipher_suite) =
+        tls::select_server_hello_cipher_suite(handshake, preferred_cipher_suite)
+    else {
+        auth_probe_record_failure_in(shared, peer.ip(), Instant::now());
+        maybe_apply_server_hello_delay(config).await;
+        debug!(
+            peer = %peer,
+            "TLS handshake rejected: ClientHello did not offer a supported TLS 1.3 cipher suite"
+        );
+        return HandshakeResult::BadClient { reader, writer };
+    };
+
+    let cached = if let Some(cached_entry) = cached_entry {
+        let use_full_cert_payload = if config.censorship.serverhello_compact
+            && matches!(client_tls_version, tls::ClientHelloTlsVersion::Tls12)
+        {
+            if let Some(cache) = tls_cache.as_ref() {
                 cache
                     .take_full_cert_budget_for_ip(
                         peer.ip(),
@@ -1489,11 +1535,11 @@ where
                     .await
             } else {
                 true
-            };
-            Some((cached_entry, use_full_cert_payload))
+            }
         } else {
-            None
-        }
+            true
+        };
+        Some((cached_entry, use_full_cert_payload))
     } else {
         None
     };
@@ -1512,17 +1558,21 @@ where
             use_full_cert_payload,
             config.censorship.serverhello_compact,
             client_tls_version,
+            selected_cipher_suite,
+            &server_key_share,
             rng,
             selected_alpn.clone(),
             config.censorship.tls_new_session_tickets,
         )
     } else {
-        tls::build_server_hello(
+        tls::build_server_hello_with_cipher(
             &validated_secret,
             &validation_digest,
             validation_session_id_slice,
             config.censorship.fake_cert_len,
             rng,
+            selected_cipher_suite,
+            &server_key_share,
             selected_alpn.clone(),
             config.censorship.tls_new_session_tickets,
         )

src/proxy/masking.rs

@@ -385,7 +385,7 @@ mod tls_domain_mask_host_tests {
         let mut config = ProxyConfig::default();
         config.censorship.tls_domain = "a.com".to_string();
         config.censorship.tls_domains = vec!["b.com".to_string(), "c.com".to_string()];
-        config.censorship.mask_host = Some("a.com".to_string());
+        config.censorship.mask_host = None;
         config
     }
 
@@ -419,6 +419,15 @@ mod tls_domain_mask_host_tests {
         assert_eq!(mask_host_for_initial_data(&config, &initial_data), "b.com");
     }
 
+    #[test]
+    fn mask_host_uses_primary_domain_when_dynamic_masking_is_disabled() {
+        let mut config = config_with_tls_domains();
+        config.censorship.mask_dynamic = false;
+        let initial_data = client_hello_with_sni("b.com");
+
+        assert_eq!(mask_host_for_initial_data(&config, &initial_data), "a.com");
+    }
+
     #[test]
     fn exclusive_mask_target_overrides_only_matching_sni() {
         let mut config = config_with_tls_domains();
@@ -515,12 +524,28 @@ fn exclusive_mask_target_for_sni<'a>(
     config: &'a ProxyConfig,
     sni: &str,
 ) -> Option<MaskTcpTarget<'a>> {
+    if let Some(target) = config.censorship.exclusive_mask_targets.get(sni) {
+        return Some(MaskTcpTarget {
+            host: target.host.as_str(),
+            port: target.port,
+        });
+    }
     if let Some(target) = config.censorship.exclusive_mask.get(sni) {
         return parse_exclusive_mask_target(target);
     }
 
     if sni.bytes().any(|byte| byte.is_ascii_uppercase()) {
         let normalized_sni = sni.to_ascii_lowercase();
+        if let Some(target) = config
+            .censorship
+            .exclusive_mask_targets
+            .get(&normalized_sni)
+        {
+            return Some(MaskTcpTarget {
+                host: target.host.as_str(),
+                port: target.port,
+            });
+        }
         if let Some(target) = config.censorship.exclusive_mask.get(&normalized_sni) {
             return parse_exclusive_mask_target(target);
         }
@@ -561,24 +586,32 @@ fn default_mask_tcp_target_for_initial_data<'a>(
         .as_deref()
         .unwrap_or(&config.censorship.tls_domain);
 
-    if !configured_mask_host.eq_ignore_ascii_case(&config.censorship.tls_domain) {
+    if config.censorship.mask_host.is_none() && config.censorship.mask_dynamic {
+        let extracted_sni = if sni.is_none() {
+            tls::extract_sni_from_client_hello(initial_data)
+        } else {
+            None
+        };
+        if let Some(host) = sni
+            .or(extracted_sni.as_deref())
+            .and_then(|sni| matching_tls_domain_for_sni(config, sni))
+        {
+            return MaskTcpTarget {
+                host,
+                port: config.censorship.mask_port,
+            };
+        }
+    }
+
+    if let Some(mask_host) = config.censorship.mask_host.as_deref() {
         return MaskTcpTarget {
-            host: configured_mask_host,
+            host: mask_host,
             port: config.censorship.mask_port,
         };
     }
 
-    let extracted_sni = if sni.is_none() {
-        tls::extract_sni_from_client_hello(initial_data)
-    } else {
-        None
-    };
-    let host = sni
-        .or(extracted_sni.as_deref())
-        .and_then(|sni| matching_tls_domain_for_sni(config, sni))
-        .unwrap_or(configured_mask_host);
     MaskTcpTarget {
-        host,
+        host: configured_mask_host,
         port: config.censorship.mask_port,
     }
 }

src/proxy/middle_relay/c2me.rs

@@ -0,0 +1,104 @@
+use super::*;
+
+pub(in crate::proxy::middle_relay) enum C2MeCommand {
+    Data {
+        payload: PooledBuffer,
+        flags: u32,
+        _permit: OwnedSemaphorePermit,
+    },
+    Close,
+}
+
+pub(super) fn should_yield_c2me_sender(sent_since_yield: usize, has_backlog: bool) -> bool {
+    has_backlog && sent_since_yield >= C2ME_SENDER_FAIRNESS_BUDGET
+}
+
+pub(super) fn c2me_payload_permits(payload_len: usize) -> u32 {
+    payload_len
+        .max(1)
+        .div_ceil(C2ME_QUEUED_BYTE_PERMIT_UNIT)
+        .min(u32::MAX as usize) as u32
+}
+
+pub(super) fn c2me_queued_permit_budget(channel_capacity: usize, frame_limit: usize) -> usize {
+    channel_capacity
+        .saturating_mul(C2ME_QUEUED_PERMITS_PER_SLOT)
+        .max(c2me_payload_permits(frame_limit) as usize)
+        .max(1)
+}
+
+pub(super) async fn acquire_c2me_payload_permit(
+    semaphore: &Arc<Semaphore>,
+    payload_len: usize,
+    send_timeout: Option<Duration>,
+    stats: &Stats,
+) -> Result<OwnedSemaphorePermit> {
+    let permits = c2me_payload_permits(payload_len);
+    let acquire = semaphore.clone().acquire_many_owned(permits);
+    match send_timeout {
+        Some(send_timeout) => match timeout(send_timeout, acquire).await {
+            Ok(Ok(permit)) => Ok(permit),
+            Ok(Err(_)) => Err(ProxyError::Proxy("ME sender byte budget closed".into())),
+            Err(_) => {
+                stats.increment_me_c2me_send_timeout_total();
+                Err(ProxyError::Proxy("ME sender byte budget timeout".into()))
+            }
+        },
+        None => acquire
+            .await
+            .map_err(|_| ProxyError::Proxy("ME sender byte budget closed".into())),
+    }
+}
+
+pub(super) async fn enqueue_c2me_command_in(
+    shared: &ProxySharedState,
+    tx: &mpsc::Sender<C2MeCommand>,
+    cmd: C2MeCommand,
+    send_timeout: Option<Duration>,
+    stats: &Stats,
+) -> std::result::Result<(), mpsc::error::SendError<C2MeCommand>> {
+    match tx.try_send(cmd) {
+        Ok(()) => Ok(()),
+        Err(mpsc::error::TrySendError::Closed(cmd)) => Err(mpsc::error::SendError(cmd)),
+        Err(mpsc::error::TrySendError::Full(cmd)) => {
+            stats.increment_me_c2me_send_full_total();
+            stats.increment_me_c2me_send_high_water_total();
+            note_relay_pressure_event_in(shared);
+            // Cooperative yield reduces burst catch-up when the per-conn queue is near saturation.
+            if tx.capacity() <= C2ME_SOFT_PRESSURE_MIN_FREE_SLOTS {
+                tokio::task::yield_now().await;
+            }
+            let reserve_result = match send_timeout {
+                Some(send_timeout) => match timeout(send_timeout, tx.reserve()).await {
+                    Ok(result) => result,
+                    Err(_) => {
+                        stats.increment_me_c2me_send_timeout_total();
+                        return Err(mpsc::error::SendError(cmd));
+                    }
+                },
+                None => tx.reserve().await,
+            };
+            match reserve_result {
+                Ok(permit) => {
+                    permit.send(cmd);
+                    Ok(())
+                }
+                Err(_) => {
+                    stats.increment_me_c2me_send_timeout_total();
+                    Err(mpsc::error::SendError(cmd))
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+pub(crate) async fn enqueue_c2me_command(
+    tx: &mpsc::Sender<C2MeCommand>,
+    cmd: C2MeCommand,
+    send_timeout: Option<Duration>,
+    stats: &Stats,
+) -> std::result::Result<(), mpsc::error::SendError<C2MeCommand>> {
+    let shared = ProxySharedState::new();
+    enqueue_c2me_command_in(shared.as_ref(), tx, cmd, send_timeout, stats).await
+}

src/proxy/middle_relay/d2c.rs

@@ -0,0 +1,458 @@
+use super::*;
+
+#[derive(Clone, Copy)]
+pub(super) struct MeD2cFlushPolicy {
+    pub(super) max_frames: usize,
+    pub(super) max_bytes: usize,
+    pub(super) max_delay: Duration,
+    pub(super) ack_flush_immediate: bool,
+    pub(super) quota_soft_overshoot_bytes: u64,
+    pub(super) frame_buf_shrink_threshold_bytes: usize,
+}
+
+impl MeD2cFlushPolicy {
+    pub(super) fn from_config(config: &ProxyConfig) -> Self {
+        Self {
+            max_frames: config
+                .general
+                .me_d2c_flush_batch_max_frames
+                .max(ME_D2C_FLUSH_BATCH_MAX_FRAMES_MIN),
+            max_bytes: config
+                .general
+                .me_d2c_flush_batch_max_bytes
+                .max(ME_D2C_FLUSH_BATCH_MAX_BYTES_MIN),
+            max_delay: Duration::from_micros(config.general.me_d2c_flush_batch_max_delay_us),
+            ack_flush_immediate: config.general.me_d2c_ack_flush_immediate,
+            quota_soft_overshoot_bytes: config.general.me_quota_soft_overshoot_bytes,
+            frame_buf_shrink_threshold_bytes: config
+                .general
+                .me_d2c_frame_buf_shrink_threshold_bytes
+                .max(4096),
+        }
+    }
+}
+
+pub(super) fn classify_me_d2c_flush_reason(
+    flush_immediately: bool,
+    batch_frames: usize,
+    max_frames: usize,
+    batch_bytes: usize,
+    max_bytes: usize,
+    max_delay_fired: bool,
+) -> MeD2cFlushReason {
+    if flush_immediately {
+        return MeD2cFlushReason::AckImmediate;
+    }
+    if batch_frames >= max_frames {
+        return MeD2cFlushReason::BatchFrames;
+    }
+    if batch_bytes >= max_bytes {
+        return MeD2cFlushReason::BatchBytes;
+    }
+    if max_delay_fired {
+        return MeD2cFlushReason::MaxDelay;
+    }
+    MeD2cFlushReason::QueueDrain
+}
+
+pub(super) fn observe_me_d2c_flush_event(
+    stats: &Stats,
+    reason: MeD2cFlushReason,
+    batch_frames: usize,
+    batch_bytes: usize,
+    flush_duration_us: Option<u64>,
+) {
+    stats.increment_me_d2c_flush_reason(reason);
+    if batch_frames > 0 || batch_bytes > 0 {
+        stats.increment_me_d2c_batches_total();
+        stats.add_me_d2c_batch_frames_total(batch_frames as u64);
+        stats.add_me_d2c_batch_bytes_total(batch_bytes as u64);
+        stats.observe_me_d2c_batch_frames(batch_frames as u64);
+        stats.observe_me_d2c_batch_bytes(batch_bytes as u64);
+    }
+    if let Some(duration_us) = flush_duration_us {
+        stats.observe_me_d2c_flush_duration_us(duration_us);
+    }
+}
+
+pub(super) enum MeWriterResponseOutcome {
+    Continue {
+        frames: usize,
+        bytes: usize,
+        flush_immediately: bool,
+    },
+    Close,
+}
+
+#[cfg(test)]
+pub(crate) async fn process_me_writer_response<W>(
+    response: MeResponse,
+    client_writer: &mut CryptoWriter<W>,
+    proto_tag: ProtoTag,
+    rng: &SecureRandom,
+    frame_buf: &mut Vec<u8>,
+    stats: &Stats,
+    user: &str,
+    quota_user_stats: Option<&UserStats>,
+    quota_limit: Option<u64>,
+    quota_soft_overshoot_bytes: u64,
+    bytes_me2c: &AtomicU64,
+    conn_id: u64,
+    ack_flush_immediate: bool,
+    batched: bool,
+) -> Result<MeWriterResponseOutcome>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    process_me_writer_response_with_traffic_lease(
+        response,
+        client_writer,
+        proto_tag,
+        rng,
+        frame_buf,
+        stats,
+        user,
+        quota_user_stats,
+        quota_limit,
+        quota_soft_overshoot_bytes,
+        None,
+        &CancellationToken::new(),
+        bytes_me2c,
+        conn_id,
+        ack_flush_immediate,
+        batched,
+    )
+    .await
+}
+
+pub(crate) async fn process_me_writer_response_with_traffic_lease<W>(
+    response: MeResponse,
+    client_writer: &mut CryptoWriter<W>,
+    proto_tag: ProtoTag,
+    rng: &SecureRandom,
+    frame_buf: &mut Vec<u8>,
+    stats: &Stats,
+    user: &str,
+    quota_user_stats: Option<&UserStats>,
+    quota_limit: Option<u64>,
+    quota_soft_overshoot_bytes: u64,
+    traffic_lease: Option<&Arc<TrafficLease>>,
+    cancel: &CancellationToken,
+    bytes_me2c: &AtomicU64,
+    conn_id: u64,
+    ack_flush_immediate: bool,
+    batched: bool,
+) -> Result<MeWriterResponseOutcome>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    match response {
+        MeResponse::Data { flags, data, .. } => {
+            if batched {
+                trace!(conn_id, bytes = data.len(), flags, "ME->C data (batched)");
+            } else {
+                trace!(conn_id, bytes = data.len(), flags, "ME->C data");
+            }
+            let data_len = data.len() as u64;
+            if let (Some(limit), Some(user_stats)) = (quota_limit, quota_user_stats) {
+                let soft_limit = quota_soft_cap(limit, quota_soft_overshoot_bytes);
+                match reserve_user_quota_with_yield(
+                    user_stats, data_len, soft_limit, stats, cancel, None,
+                )
+                .await
+                {
+                    Ok(_) => {}
+                    Err(MiddleQuotaReserveError::LimitExceeded) => {
+                        stats.increment_me_d2c_quota_reject_total(MeD2cQuotaRejectStage::PreWrite);
+                        return Err(ProxyError::DataQuotaExceeded {
+                            user: user.to_string(),
+                        });
+                    }
+                    Err(MiddleQuotaReserveError::Contended) => {
+                        return Err(ProxyError::Proxy(
+                            "ME D->C quota reservation contended".into(),
+                        ));
+                    }
+                    Err(MiddleQuotaReserveError::Cancelled) => {
+                        return Err(ProxyError::Proxy(
+                            "ME D->C quota reservation cancelled".into(),
+                        ));
+                    }
+                    Err(MiddleQuotaReserveError::DeadlineExceeded) => {
+                        return Err(ProxyError::Proxy(
+                            "ME D->C quota reservation deadline exceeded".into(),
+                        ));
+                    }
+                }
+            }
+            wait_for_traffic_budget_or_cancel(
+                traffic_lease,
+                RateDirection::Down,
+                data_len,
+                cancel,
+                stats,
+                None,
+            )
+            .await?;
+
+            let write_mode = match write_client_payload(
+                client_writer,
+                proto_tag,
+                flags,
+                &data,
+                rng,
+                frame_buf,
+                cancel,
+            )
+            .await
+            {
+                Ok(mode) => mode,
+                Err(err) => {
+                    if quota_limit.is_some() {
+                        stats.add_quota_write_fail_bytes_total(data_len);
+                        stats.increment_quota_write_fail_events_total();
+                    }
+                    return Err(err);
+                }
+            };
+
+            bytes_me2c.fetch_add(data_len, Ordering::Relaxed);
+            if let Some(user_stats) = quota_user_stats {
+                stats.add_user_octets_to_handle(user_stats, data_len);
+            } else {
+                stats.add_user_octets_to(user, data_len);
+            }
+            stats.increment_me_d2c_data_frames_total();
+            stats.add_me_d2c_payload_bytes_total(data_len);
+            stats.increment_me_d2c_write_mode(write_mode);
+
+            Ok(MeWriterResponseOutcome::Continue {
+                frames: 1,
+                bytes: data.len(),
+                flush_immediately: false,
+            })
+        }
+        MeResponse::Ack(confirm) => {
+            if batched {
+                trace!(conn_id, confirm, "ME->C quickack (batched)");
+            } else {
+                trace!(conn_id, confirm, "ME->C quickack");
+            }
+            wait_for_traffic_budget_or_cancel(
+                traffic_lease,
+                RateDirection::Down,
+                4,
+                cancel,
+                stats,
+                None,
+            )
+            .await?;
+            write_client_ack(client_writer, proto_tag, confirm, cancel).await?;
+            stats.increment_me_d2c_ack_frames_total();
+
+            Ok(MeWriterResponseOutcome::Continue {
+                frames: 1,
+                bytes: 4,
+                flush_immediately: ack_flush_immediate,
+            })
+        }
+        MeResponse::Close => {
+            if batched {
+                debug!(conn_id, "ME sent close (batched)");
+            } else {
+                debug!(conn_id, "ME sent close");
+            }
+            Ok(MeWriterResponseOutcome::Close)
+        }
+    }
+}
+
+/// Computes the intermediate/secure wire length while rejecting lossy casts.
+pub(in crate::proxy::middle_relay) fn compute_intermediate_secure_wire_len(
+    data_len: usize,
+    padding_len: usize,
+    quickack: bool,
+) -> Result<(u32, usize)> {
+    let wire_len = data_len
+        .checked_add(padding_len)
+        .ok_or_else(|| ProxyError::Proxy("Frame length overflow".into()))?;
+    if wire_len > 0x7fff_ffffusize {
+        return Err(ProxyError::Proxy(format!(
+            "Intermediate/Secure frame too large: {wire_len}"
+        )));
+    }
+
+    let total = 4usize
+        .checked_add(wire_len)
+        .ok_or_else(|| ProxyError::Proxy("Frame buffer size overflow".into()))?;
+    let mut len_val = u32::try_from(wire_len)
+        .map_err(|_| ProxyError::Proxy("Frame length conversion overflow".into()))?;
+    if quickack {
+        len_val |= 0x8000_0000;
+    }
+    Ok((len_val, total))
+}
+
+pub(super) async fn write_client_payload<W>(
+    client_writer: &mut CryptoWriter<W>,
+    proto_tag: ProtoTag,
+    flags: u32,
+    data: &[u8],
+    rng: &SecureRandom,
+    frame_buf: &mut Vec<u8>,
+    cancel: &CancellationToken,
+) -> Result<MeD2cWriteMode>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    let quickack = (flags & RPC_FLAG_QUICKACK) != 0;
+
+    let write_mode = match proto_tag {
+        ProtoTag::Abridged => {
+            if !data.len().is_multiple_of(4) {
+                return Err(ProxyError::Proxy(format!(
+                    "Abridged payload must be 4-byte aligned, got {}",
+                    data.len()
+                )));
+            }
+
+            let len_words = data.len() / 4;
+            if len_words < 0x7f {
+                let mut first = len_words as u8;
+                if quickack {
+                    first |= 0x80;
+                }
+                let wire_len = 1usize.saturating_add(data.len());
+                if wire_len <= ME_D2C_SINGLE_WRITE_COALESCE_MAX_BYTES {
+                    frame_buf.clear();
+                    frame_buf.reserve(wire_len);
+                    frame_buf.push(first);
+                    frame_buf.extend_from_slice(data);
+                    write_all_client_or_cancel(client_writer, frame_buf.as_slice(), cancel).await?;
+                    MeD2cWriteMode::Coalesced
+                } else {
+                    let header = [first];
+                    write_all_client_or_cancel(client_writer, &header, cancel).await?;
+                    write_all_client_or_cancel(client_writer, data, cancel).await?;
+                    MeD2cWriteMode::Split
+                }
+            } else if len_words < (1 << 24) {
+                let mut first = 0x7fu8;
+                if quickack {
+                    first |= 0x80;
+                }
+                let lw = (len_words as u32).to_le_bytes();
+                let wire_len = 4usize.saturating_add(data.len());
+                if wire_len <= ME_D2C_SINGLE_WRITE_COALESCE_MAX_BYTES {
+                    frame_buf.clear();
+                    frame_buf.reserve(wire_len);
+                    frame_buf.extend_from_slice(&[first, lw[0], lw[1], lw[2]]);
+                    frame_buf.extend_from_slice(data);
+                    write_all_client_or_cancel(client_writer, frame_buf.as_slice(), cancel).await?;
+                    MeD2cWriteMode::Coalesced
+                } else {
+                    let header = [first, lw[0], lw[1], lw[2]];
+                    write_all_client_or_cancel(client_writer, &header, cancel).await?;
+                    write_all_client_or_cancel(client_writer, data, cancel).await?;
+                    MeD2cWriteMode::Split
+                }
+            } else {
+                return Err(ProxyError::Proxy(format!(
+                    "Abridged frame too large: {}",
+                    data.len()
+                )));
+            }
+        }
+        ProtoTag::Intermediate | ProtoTag::Secure => {
+            let padding_len = if proto_tag == ProtoTag::Secure {
+                if !is_valid_secure_payload_len(data.len()) {
+                    return Err(ProxyError::Proxy(format!(
+                        "Secure payload must be 4-byte aligned, got {}",
+                        data.len()
+                    )));
+                }
+                secure_padding_len(data.len(), rng)
+            } else {
+                0
+            };
+
+            let (len_val, total) =
+                compute_intermediate_secure_wire_len(data.len(), padding_len, quickack)?;
+            if total <= ME_D2C_SINGLE_WRITE_COALESCE_MAX_BYTES {
+                frame_buf.clear();
+                frame_buf.reserve(total);
+                frame_buf.extend_from_slice(&len_val.to_le_bytes());
+                frame_buf.extend_from_slice(data);
+                if padding_len > 0 {
+                    let start = frame_buf.len();
+                    frame_buf.resize(start + padding_len, 0);
+                    rng.fill(&mut frame_buf[start..]);
+                }
+                write_all_client_or_cancel(client_writer, frame_buf.as_slice(), cancel).await?;
+                MeD2cWriteMode::Coalesced
+            } else {
+                let header = len_val.to_le_bytes();
+                write_all_client_or_cancel(client_writer, &header, cancel).await?;
+                write_all_client_or_cancel(client_writer, data, cancel).await?;
+                if padding_len > 0 {
+                    frame_buf.clear();
+                    if frame_buf.capacity() < padding_len {
+                        frame_buf.reserve(padding_len);
+                    }
+                    frame_buf.resize(padding_len, 0);
+                    rng.fill(frame_buf.as_mut_slice());
+                    write_all_client_or_cancel(client_writer, frame_buf.as_slice(), cancel).await?;
+                }
+                MeD2cWriteMode::Split
+            }
+        }
+    };
+
+    Ok(write_mode)
+}
+
+pub(super) async fn write_client_ack<W>(
+    client_writer: &mut CryptoWriter<W>,
+    proto_tag: ProtoTag,
+    confirm: u32,
+    cancel: &CancellationToken,
+) -> Result<()>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    let bytes = if proto_tag == ProtoTag::Abridged {
+        confirm.to_be_bytes()
+    } else {
+        confirm.to_le_bytes()
+    };
+    write_all_client_or_cancel(client_writer, &bytes, cancel).await
+}
+
+pub(super) async fn write_all_client_or_cancel<W>(
+    client_writer: &mut CryptoWriter<W>,
+    bytes: &[u8],
+    cancel: &CancellationToken,
+) -> Result<()>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    tokio::select! {
+        biased;
+        _ = cancel.cancelled() => Err(ProxyError::MiddleClientWriterCancelled),
+        result = client_writer.write_all(bytes) => result.map_err(ProxyError::Io),
+    }
+}
+
+pub(super) async fn flush_client_or_cancel<W>(
+    client_writer: &mut CryptoWriter<W>,
+    cancel: &CancellationToken,
+) -> Result<()>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    tokio::select! {
+        biased;
+        _ = cancel.cancelled() => Err(ProxyError::MiddleClientWriterCancelled),
+        result = client_writer.flush() => result.map_err(ProxyError::Io),
+    }
+}

src/proxy/middle_relay/desync.rs

@@ -0,0 +1,406 @@
+use super::*;
+
+#[derive(Default)]
+pub(crate) struct DesyncDedupRotationState {
+    current_started_at: Option<Instant>,
+}
+
+pub(in crate::proxy::middle_relay) struct RelayForensicsState {
+    pub(in crate::proxy::middle_relay) trace_id: u64,
+    pub(in crate::proxy::middle_relay) conn_id: u64,
+    pub(in crate::proxy::middle_relay) user: String,
+    pub(in crate::proxy::middle_relay) peer: SocketAddr,
+    pub(in crate::proxy::middle_relay) peer_hash: u64,
+    pub(in crate::proxy::middle_relay) started_at: Instant,
+    pub(in crate::proxy::middle_relay) bytes_c2me: u64,
+    pub(in crate::proxy::middle_relay) bytes_me2c: Arc<AtomicU64>,
+    pub(in crate::proxy::middle_relay) desync_all_full: bool,
+}
+
+#[cfg(test)]
+pub(crate) fn hash_value<T: Hash>(value: &T) -> u64 {
+    let mut hasher = DefaultHasher::new();
+    value.hash(&mut hasher);
+    hasher.finish()
+}
+
+fn hash_value_in<T: Hash>(shared: &ProxySharedState, value: &T) -> u64 {
+    shared.middle_relay.desync_hasher.hash_one(value)
+}
+
+#[cfg(test)]
+pub(crate) fn hash_ip(ip: IpAddr) -> u64 {
+    hash_value(&ip)
+}
+
+pub(super) fn hash_ip_in(shared: &ProxySharedState, ip: IpAddr) -> u64 {
+    hash_value_in(shared, &ip)
+}
+
+fn should_emit_full_desync_in(
+    shared: &ProxySharedState,
+    key: u64,
+    all_full: bool,
+    now: Instant,
+) -> bool {
+    if all_full {
+        return true;
+    }
+
+    let dedup_current = &shared.middle_relay.desync_dedup;
+    let dedup_previous = &shared.middle_relay.desync_dedup_previous;
+    let rotation_state = &shared.middle_relay.desync_dedup_rotation_state;
+
+    let mut state = match rotation_state.lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => {
+            let mut guard = poisoned.into_inner();
+            *guard = DesyncDedupRotationState::default();
+            rotation_state.clear_poison();
+            guard
+        }
+    };
+
+    let rotate_now = match state.current_started_at {
+        Some(current_started_at) => match now.checked_duration_since(current_started_at) {
+            Some(elapsed) => elapsed >= DESYNC_DEDUP_WINDOW,
+            None => true,
+        },
+        None => true,
+    };
+    if rotate_now {
+        dedup_previous.clear();
+        for entry in dedup_current.iter() {
+            dedup_previous.insert(*entry.key(), *entry.value());
+        }
+        dedup_current.clear();
+        state.current_started_at = Some(now);
+    }
+
+    if let Some(seen_at) = dedup_current.get(&key).map(|entry| *entry.value()) {
+        let within_window = match now.checked_duration_since(seen_at) {
+            Some(elapsed) => elapsed < DESYNC_DEDUP_WINDOW,
+            None => true,
+        };
+        if within_window {
+            return false;
+        }
+        dedup_current.insert(key, now);
+        return true;
+    }
+
+    if let Some(seen_at) = dedup_previous.get(&key).map(|entry| *entry.value()) {
+        let within_window = match now.checked_duration_since(seen_at) {
+            Some(elapsed) => elapsed < DESYNC_DEDUP_WINDOW,
+            None => true,
+        };
+        if within_window {
+            dedup_current.insert(key, seen_at);
+            return false;
+        }
+        dedup_previous.remove(&key);
+    }
+
+    if dedup_current.len() >= DESYNC_DEDUP_MAX_ENTRIES {
+        dedup_previous.clear();
+        for entry in dedup_current.iter() {
+            dedup_previous.insert(*entry.key(), *entry.value());
+        }
+        dedup_current.clear();
+        state.current_started_at = Some(now);
+        dedup_current.insert(key, now);
+        should_emit_full_desync_full_cache_in(shared, now)
+    } else {
+        dedup_current.insert(key, now);
+        true
+    }
+}
+
+fn should_emit_full_desync_full_cache_in(shared: &ProxySharedState, now: Instant) -> bool {
+    let gate = &shared.middle_relay.desync_full_cache_last_emit_at;
+    let Ok(mut last_emit_at) = gate.lock() else {
+        return false;
+    };
+
+    match *last_emit_at {
+        None => {
+            *last_emit_at = Some(now);
+            true
+        }
+        Some(last) => {
+            let Some(elapsed) = now.checked_duration_since(last) else {
+                *last_emit_at = Some(now);
+                return true;
+            };
+            if elapsed >= DESYNC_FULL_CACHE_EMIT_MIN_INTERVAL {
+                *last_emit_at = Some(now);
+                true
+            } else {
+                false
+            }
+        }
+    }
+}
+
+pub(crate) fn desync_forensics_len_bytes(len: usize) -> ([u8; 4], bool) {
+    match u32::try_from(len) {
+        Ok(value) => (value.to_le_bytes(), false),
+        Err(_) => (u32::MAX.to_le_bytes(), true),
+    }
+}
+
+pub(super) fn report_desync_frame_too_large_in(
+    shared: &ProxySharedState,
+    state: &RelayForensicsState,
+    proto_tag: ProtoTag,
+    frame_counter: u64,
+    max_frame: usize,
+    len: usize,
+    raw_len_bytes: Option<[u8; 4]>,
+    stats: &Stats,
+) -> ProxyError {
+    let (fallback_len_buf, len_buf_truncated) = desync_forensics_len_bytes(len);
+    let len_buf = raw_len_bytes.unwrap_or(fallback_len_buf);
+    let looks_like_tls = raw_len_bytes
+        .map(|b| b[0] == 0x16 && b[1] == 0x03)
+        .unwrap_or(false);
+    let looks_like_http = raw_len_bytes
+        .map(|b| matches!(b[0], b'G' | b'P' | b'H' | b'C' | b'D'))
+        .unwrap_or(false);
+    let now = Instant::now();
+    let dedup_key = hash_value_in(
+        shared,
+        &(
+            state.user.as_str(),
+            state.peer_hash,
+            proto_tag,
+            DESYNC_ERROR_CLASS,
+        ),
+    );
+    let emit_full = should_emit_full_desync_in(shared, dedup_key, state.desync_all_full, now);
+    let duration_ms = state.started_at.elapsed().as_millis() as u64;
+    let bytes_me2c = state.bytes_me2c.load(Ordering::Relaxed);
+
+    stats.increment_desync_total();
+    stats.increment_relay_protocol_desync_close_total();
+    stats.observe_desync_frames_ok(frame_counter);
+    if emit_full {
+        stats.increment_desync_full_logged();
+        warn!(
+            trace_id = format_args!("0x{:016x}", state.trace_id),
+            conn_id = state.conn_id,
+            user = %state.user,
+            peer_hash = format_args!("0x{:016x}", state.peer_hash),
+            proto = ?proto_tag,
+            mode = "middle_proxy",
+            is_tls = true,
+            duration_ms,
+            bytes_c2me = state.bytes_c2me,
+            bytes_me2c,
+            raw_len = len,
+            raw_len_hex = format_args!("0x{:08x}", len),
+            raw_len_bytes_truncated = len_buf_truncated,
+            raw_bytes = format_args!(
+                "{:02x} {:02x} {:02x} {:02x}",
+                len_buf[0], len_buf[1], len_buf[2], len_buf[3]
+            ),
+            max_frame,
+            tls_like = looks_like_tls,
+            http_like = looks_like_http,
+            frames_ok = frame_counter,
+            dedup_window_secs = DESYNC_DEDUP_WINDOW.as_secs(),
+            desync_all_full = state.desync_all_full,
+            full_reason = if state.desync_all_full { "desync_all_full" } else { "first_in_dedup_window" },
+            error_class = DESYNC_ERROR_CLASS,
+            "Frame too large — crypto desync forensics"
+        );
+        debug!(
+            trace_id = format_args!("0x{:016x}", state.trace_id),
+            conn_id = state.conn_id,
+            user = %state.user,
+            peer = %state.peer,
+            "Frame too large forensic peer detail"
+        );
+    } else {
+        stats.increment_desync_suppressed();
+        debug!(
+            trace_id = format_args!("0x{:016x}", state.trace_id),
+            conn_id = state.conn_id,
+            user = %state.user,
+            peer_hash = format_args!("0x{:016x}", state.peer_hash),
+            proto = ?proto_tag,
+            duration_ms,
+            bytes_c2me = state.bytes_c2me,
+            bytes_me2c,
+            raw_len = len,
+            frames_ok = frame_counter,
+            dedup_window_secs = DESYNC_DEDUP_WINDOW.as_secs(),
+            error_class = DESYNC_ERROR_CLASS,
+            "Frame too large — crypto desync forensic suppressed"
+        );
+    }
+
+    ProxyError::Proxy(format!(
+        "Frame too large: {len} (max {max_frame}), frames_ok={frame_counter}, conn_id={}, trace_id=0x{:016x}",
+        state.conn_id, state.trace_id
+    ))
+}
+
+#[cfg(test)]
+pub(crate) fn report_desync_frame_too_large(
+    state: &RelayForensicsState,
+    proto_tag: ProtoTag,
+    frame_counter: u64,
+    max_frame: usize,
+    len: usize,
+    raw_len_bytes: Option<[u8; 4]>,
+    stats: &Stats,
+) -> ProxyError {
+    let shared = ProxySharedState::new();
+    report_desync_frame_too_large_in(
+        shared.as_ref(),
+        state,
+        proto_tag,
+        frame_counter,
+        max_frame,
+        len,
+        raw_len_bytes,
+        stats,
+    )
+}
+
+#[cfg(test)]
+pub(crate) fn should_emit_full_desync_for_testing(
+    shared: &ProxySharedState,
+    key: u64,
+    all_full: bool,
+    now: Instant,
+) -> bool {
+    if all_full {
+        return true;
+    }
+
+    let dedup_current = &shared.middle_relay.desync_dedup;
+    let dedup_previous = &shared.middle_relay.desync_dedup_previous;
+
+    let Ok(mut state) = shared.middle_relay.desync_dedup_rotation_state.lock() else {
+        return false;
+    };
+
+    let rotate_now = match state.current_started_at {
+        Some(current_started_at) => match now.checked_duration_since(current_started_at) {
+            Some(elapsed) => elapsed >= DESYNC_DEDUP_WINDOW,
+            None => true,
+        },
+        None => true,
+    };
+    if rotate_now {
+        dedup_previous.clear();
+        for entry in dedup_current.iter() {
+            dedup_previous.insert(*entry.key(), *entry.value());
+        }
+        dedup_current.clear();
+        state.current_started_at = Some(now);
+    }
+
+    if let Some(seen_at) = dedup_current.get(&key).map(|entry| *entry.value()) {
+        let within_window = match now.checked_duration_since(seen_at) {
+            Some(elapsed) => elapsed < DESYNC_DEDUP_WINDOW,
+            None => true,
+        };
+        if within_window {
+            return false;
+        }
+        dedup_current.insert(key, now);
+        return true;
+    }
+
+    if let Some(seen_at) = dedup_previous.get(&key).map(|entry| *entry.value()) {
+        let within_window = match now.checked_duration_since(seen_at) {
+            Some(elapsed) => elapsed < DESYNC_DEDUP_WINDOW,
+            None => true,
+        };
+        if within_window {
+            dedup_current.insert(key, seen_at);
+            return false;
+        }
+        dedup_previous.remove(&key);
+    }
+
+    if dedup_current.len() >= DESYNC_DEDUP_MAX_ENTRIES {
+        dedup_previous.clear();
+        for entry in dedup_current.iter() {
+            dedup_previous.insert(*entry.key(), *entry.value());
+        }
+        dedup_current.clear();
+        state.current_started_at = Some(now);
+        dedup_current.insert(key, now);
+        let Ok(mut last_emit_at) = shared.middle_relay.desync_full_cache_last_emit_at.lock() else {
+            return false;
+        };
+        return match *last_emit_at {
+            None => {
+                *last_emit_at = Some(now);
+                true
+            }
+            Some(last) => {
+                let Some(elapsed) = now.checked_duration_since(last) else {
+                    *last_emit_at = Some(now);
+                    return true;
+                };
+                if elapsed >= DESYNC_FULL_CACHE_EMIT_MIN_INTERVAL {
+                    *last_emit_at = Some(now);
+                    true
+                } else {
+                    false
+                }
+            }
+        };
+    }
+
+    dedup_current.insert(key, now);
+    true
+}
+
+#[cfg(test)]
+pub(crate) fn clear_desync_dedup_for_testing_in_shared(shared: &ProxySharedState) {
+    shared.middle_relay.desync_dedup.clear();
+    shared.middle_relay.desync_dedup_previous.clear();
+    if let Ok(mut rotation_state) = shared.middle_relay.desync_dedup_rotation_state.lock() {
+        *rotation_state = DesyncDedupRotationState::default();
+    }
+    if let Ok(mut last_emit_at) = shared.middle_relay.desync_full_cache_last_emit_at.lock() {
+        *last_emit_at = None;
+    }
+}
+
+#[cfg(test)]
+pub(crate) fn desync_dedup_len_for_testing(shared: &ProxySharedState) -> usize {
+    shared.middle_relay.desync_dedup.len()
+}
+
+#[cfg(test)]
+pub(crate) fn desync_dedup_insert_for_testing(shared: &ProxySharedState, key: u64, at: Instant) {
+    shared.middle_relay.desync_dedup.insert(key, at);
+}
+
+#[cfg(test)]
+pub(crate) fn desync_dedup_get_for_testing(shared: &ProxySharedState, key: u64) -> Option<Instant> {
+    shared
+        .middle_relay
+        .desync_dedup
+        .get(&key)
+        .map(|entry| *entry.value())
+}
+
+#[cfg(test)]
+pub(crate) fn desync_dedup_keys_for_testing(
+    shared: &ProxySharedState,
+) -> std::collections::HashSet<u64> {
+    shared
+        .middle_relay
+        .desync_dedup
+        .iter()
+        .map(|entry| *entry.key())
+        .collect()
+}

src/proxy/middle_relay/idle.rs

@@ -0,0 +1,335 @@
+use super::*;
+use dashmap::DashMap;
+
+mod read;
+
+pub(crate) use self::read::read_client_payload_with_idle_policy_in;
+#[cfg(test)]
+pub(crate) use self::read::{
+    read_client_payload, read_client_payload_legacy, read_client_payload_with_idle_policy,
+};
+
+#[derive(Default)]
+pub(crate) struct RelayIdleCandidateRegistry {
+    pub(in crate::proxy::middle_relay) by_conn_id: DashMap<u64, RelayIdleCandidateMeta>,
+    pub(in crate::proxy::middle_relay) ordered: parking_lot::Mutex<BTreeSet<(u64, u64)>>,
+    pressure_event_seq: AtomicU64,
+    pressure_consumed_seq: AtomicU64,
+}
+
+/// Queue metadata used to preserve FIFO ordering for idle relay eviction.
+#[derive(Clone, Copy)]
+pub(in crate::proxy::middle_relay) struct RelayIdleCandidateMeta {
+    pub(in crate::proxy::middle_relay) mark_order_seq: u64,
+    pub(in crate::proxy::middle_relay) mark_pressure_seq: u64,
+}
+
+pub(super) fn mark_relay_idle_candidate_in(shared: &ProxySharedState, conn_id: u64) -> bool {
+    let registry = &shared.middle_relay.relay_idle_registry;
+
+    if registry.by_conn_id.contains_key(&conn_id) {
+        return false;
+    }
+
+    let mark_order_seq = shared
+        .middle_relay
+        .relay_idle_mark_seq
+        .fetch_add(1, Ordering::Relaxed)
+        .saturating_add(1);
+    let meta = RelayIdleCandidateMeta {
+        mark_order_seq,
+        mark_pressure_seq: registry.pressure_event_seq.load(Ordering::Relaxed),
+    };
+    match registry.by_conn_id.entry(conn_id) {
+        dashmap::mapref::entry::Entry::Occupied(_) => false,
+        dashmap::mapref::entry::Entry::Vacant(entry) => {
+            entry.insert(meta);
+            registry
+                .ordered
+                .lock()
+                .insert((meta.mark_order_seq, conn_id));
+            true
+        }
+    }
+}
+
+pub(super) fn clear_relay_idle_candidate_in(shared: &ProxySharedState, conn_id: u64) {
+    let registry = &shared.middle_relay.relay_idle_registry;
+
+    if let Some((_, meta)) = registry.by_conn_id.remove(&conn_id) {
+        registry
+            .ordered
+            .lock()
+            .remove(&(meta.mark_order_seq, conn_id));
+    }
+}
+
+pub(super) fn note_relay_pressure_event_in(shared: &ProxySharedState) {
+    shared
+        .middle_relay
+        .relay_idle_registry
+        .pressure_event_seq
+        .fetch_add(1, Ordering::Relaxed);
+}
+
+pub(crate) fn note_global_relay_pressure(shared: &ProxySharedState) {
+    note_relay_pressure_event_in(shared);
+}
+
+pub(super) fn relay_pressure_event_seq_in(shared: &ProxySharedState) -> u64 {
+    shared
+        .middle_relay
+        .relay_idle_registry
+        .pressure_event_seq
+        .load(Ordering::Relaxed)
+}
+
+pub(super) fn maybe_evict_idle_candidate_on_pressure_in(
+    shared: &ProxySharedState,
+    conn_id: u64,
+    seen_pressure_seq: &mut u64,
+    stats: &Stats,
+) -> bool {
+    let registry = &shared.middle_relay.relay_idle_registry;
+
+    let latest_pressure_seq = registry.pressure_event_seq.load(Ordering::Relaxed);
+    if latest_pressure_seq == *seen_pressure_seq {
+        return false;
+    }
+    *seen_pressure_seq = latest_pressure_seq;
+
+    let consumed_pressure_seq = registry.pressure_consumed_seq.load(Ordering::Relaxed);
+    if latest_pressure_seq == consumed_pressure_seq {
+        return false;
+    }
+
+    let oldest = {
+        let mut ordered = registry.ordered.lock();
+        loop {
+            let Some((mark_order_seq, candidate_conn_id)) = ordered.iter().next().copied() else {
+                // Empty queues consume the event so later candidates cannot replay stale pressure.
+                let _ = registry.pressure_consumed_seq.compare_exchange(
+                    consumed_pressure_seq,
+                    latest_pressure_seq,
+                    Ordering::Relaxed,
+                    Ordering::Relaxed,
+                );
+                return false;
+            };
+            let Some(candidate_meta) = registry.by_conn_id.get(&candidate_conn_id) else {
+                ordered.remove(&(mark_order_seq, candidate_conn_id));
+                continue;
+            };
+            if candidate_meta.mark_order_seq != mark_order_seq {
+                ordered.remove(&(mark_order_seq, candidate_conn_id));
+                continue;
+            }
+            break Some(candidate_conn_id);
+        }
+    };
+    if oldest != Some(conn_id) {
+        return false;
+    }
+
+    let Some(candidate_meta) = registry
+        .by_conn_id
+        .get(&conn_id)
+        .map(|entry| *entry.value())
+    else {
+        return false;
+    };
+
+    if latest_pressure_seq == candidate_meta.mark_pressure_seq {
+        return false;
+    }
+
+    // Claim the global pressure budget before removal; otherwise racing sessions
+    // can observe the next FIFO item and spend the same event more than once.
+    if registry
+        .pressure_consumed_seq
+        .compare_exchange(
+            consumed_pressure_seq,
+            latest_pressure_seq,
+            Ordering::Relaxed,
+            Ordering::Relaxed,
+        )
+        .is_err()
+    {
+        return false;
+    }
+
+    if let Some((_, meta)) = registry.by_conn_id.remove(&conn_id) {
+        registry
+            .ordered
+            .lock()
+            .remove(&(meta.mark_order_seq, conn_id));
+    }
+    stats.increment_relay_pressure_evict_total();
+    true
+}
+
+#[derive(Clone, Copy)]
+pub(in crate::proxy::middle_relay) struct RelayClientIdlePolicy {
+    pub(in crate::proxy::middle_relay) enabled: bool,
+    pub(in crate::proxy::middle_relay) soft_idle: Duration,
+    pub(in crate::proxy::middle_relay) hard_idle: Duration,
+    pub(in crate::proxy::middle_relay) grace_after_downstream_activity: Duration,
+    pub(in crate::proxy::middle_relay) legacy_frame_read_timeout: Duration,
+}
+
+impl RelayClientIdlePolicy {
+    pub(super) fn from_config(config: &ProxyConfig) -> Self {
+        let frame_read_timeout =
+            Duration::from_secs(config.timeouts.relay_client_idle_hard_secs.max(1));
+        if !config.timeouts.relay_idle_policy_v2_enabled {
+            return Self::disabled(frame_read_timeout);
+        }
+
+        let soft_idle = Duration::from_secs(config.timeouts.relay_client_idle_soft_secs.max(1));
+        let hard_idle = Duration::from_secs(config.timeouts.relay_client_idle_hard_secs.max(1));
+        let grace_after_downstream_activity = Duration::from_secs(
+            config
+                .timeouts
+                .relay_idle_grace_after_downstream_activity_secs,
+        );
+
+        Self {
+            enabled: true,
+            soft_idle,
+            hard_idle,
+            grace_after_downstream_activity,
+            legacy_frame_read_timeout: frame_read_timeout,
+        }
+    }
+
+    pub(in crate::proxy::middle_relay) fn disabled(frame_read_timeout: Duration) -> Self {
+        Self {
+            enabled: false,
+            soft_idle: frame_read_timeout,
+            hard_idle: frame_read_timeout,
+            grace_after_downstream_activity: Duration::ZERO,
+            legacy_frame_read_timeout: frame_read_timeout,
+        }
+    }
+
+    pub(super) fn apply_pressure_caps(&mut self, profile: ConntrackPressureProfile) {
+        let pressure_soft_idle_cap = Duration::from_secs(profile.middle_soft_idle_cap_secs());
+        let pressure_hard_idle_cap = Duration::from_secs(profile.middle_hard_idle_cap_secs());
+
+        self.soft_idle = self.soft_idle.min(pressure_soft_idle_cap);
+        self.hard_idle = self.hard_idle.min(pressure_hard_idle_cap);
+        if self.soft_idle > self.hard_idle {
+            self.soft_idle = self.hard_idle;
+        }
+        self.legacy_frame_read_timeout = self.legacy_frame_read_timeout.min(pressure_hard_idle_cap);
+        if self.grace_after_downstream_activity > self.hard_idle {
+            self.grace_after_downstream_activity = self.hard_idle;
+        }
+    }
+}
+
+#[derive(Clone, Copy)]
+pub(in crate::proxy::middle_relay) struct RelayClientIdleState {
+    pub(in crate::proxy::middle_relay) last_client_frame_at: Instant,
+    pub(in crate::proxy::middle_relay) soft_idle_marked: bool,
+    pub(in crate::proxy::middle_relay) tiny_frame_debt: u32,
+}
+
+impl RelayClientIdleState {
+    pub(super) fn new(now: Instant) -> Self {
+        Self {
+            last_client_frame_at: now,
+            soft_idle_marked: false,
+            tiny_frame_debt: 0,
+        }
+    }
+
+    pub(super) fn on_client_frame(&mut self, now: Instant) {
+        self.last_client_frame_at = now;
+        self.soft_idle_marked = false;
+    }
+
+    pub(super) fn on_client_tiny_frame(&mut self, now: Instant) {
+        self.last_client_frame_at = now;
+    }
+}
+
+#[cfg(test)]
+pub(crate) fn mark_relay_idle_candidate_for_testing(
+    shared: &ProxySharedState,
+    conn_id: u64,
+) -> bool {
+    mark_relay_idle_candidate_in(shared, conn_id)
+}
+
+#[cfg(test)]
+pub(crate) fn oldest_relay_idle_candidate_for_testing(shared: &ProxySharedState) -> Option<u64> {
+    let registry = &shared.middle_relay.relay_idle_registry;
+    registry
+        .ordered
+        .lock()
+        .iter()
+        .next()
+        .map(|(_, conn_id)| *conn_id)
+}
+
+#[cfg(test)]
+pub(crate) fn clear_relay_idle_candidate_for_testing(shared: &ProxySharedState, conn_id: u64) {
+    clear_relay_idle_candidate_in(shared, conn_id);
+}
+
+#[cfg(test)]
+pub(crate) fn clear_relay_idle_pressure_state_for_testing_in_shared(shared: &ProxySharedState) {
+    let registry = &shared.middle_relay.relay_idle_registry;
+    registry.by_conn_id.clear();
+    registry.ordered.lock().clear();
+    registry.pressure_event_seq.store(0, Ordering::Relaxed);
+    registry.pressure_consumed_seq.store(0, Ordering::Relaxed);
+    shared
+        .middle_relay
+        .relay_idle_mark_seq
+        .store(0, Ordering::Relaxed);
+}
+
+#[cfg(test)]
+pub(crate) fn note_relay_pressure_event_for_testing(shared: &ProxySharedState) {
+    note_relay_pressure_event_in(shared);
+}
+
+#[cfg(test)]
+pub(crate) fn relay_pressure_event_seq_for_testing(shared: &ProxySharedState) -> u64 {
+    relay_pressure_event_seq_in(shared)
+}
+
+#[cfg(test)]
+pub(crate) fn relay_idle_mark_seq_for_testing(shared: &ProxySharedState) -> u64 {
+    shared
+        .middle_relay
+        .relay_idle_mark_seq
+        .load(Ordering::Relaxed)
+}
+
+#[cfg(test)]
+pub(crate) fn maybe_evict_idle_candidate_on_pressure_for_testing(
+    shared: &ProxySharedState,
+    conn_id: u64,
+    seen_pressure_seq: &mut u64,
+    stats: &Stats,
+) -> bool {
+    maybe_evict_idle_candidate_on_pressure_in(shared, conn_id, seen_pressure_seq, stats)
+}
+
+#[cfg(test)]
+pub(crate) fn set_relay_pressure_state_for_testing(
+    shared: &ProxySharedState,
+    pressure_event_seq: u64,
+    pressure_consumed_seq: u64,
+) {
+    let registry = &shared.middle_relay.relay_idle_registry;
+    registry
+        .pressure_event_seq
+        .store(pressure_event_seq, Ordering::Relaxed);
+    registry
+        .pressure_consumed_seq
+        .store(pressure_consumed_seq, Ordering::Relaxed);
+}

src/proxy/middle_relay/idle/read.rs

@@ -0,0 +1,442 @@
+use super::*;
+
+pub(crate) async fn read_client_payload_with_idle_policy_in<R>(
+    client_reader: &mut CryptoReader<R>,
+    proto_tag: ProtoTag,
+    max_frame: usize,
+    buffer_pool: &Arc<BufferPool>,
+    forensics: &RelayForensicsState,
+    frame_counter: &mut u64,
+    stats: &Stats,
+    shared: &ProxySharedState,
+    idle_policy: &RelayClientIdlePolicy,
+    idle_state: &mut RelayClientIdleState,
+    last_downstream_activity_ms: &AtomicU64,
+    session_started_at: Instant,
+) -> Result<Option<(PooledBuffer, bool)>>
+where
+    R: AsyncRead + Unpin + Send + 'static,
+{
+    const LEGACY_MAX_CONSECUTIVE_ZERO_LEN_FRAMES: u32 = 4;
+
+    async fn read_exact_with_policy<R>(
+        client_reader: &mut CryptoReader<R>,
+        buf: &mut [u8],
+        idle_policy: &RelayClientIdlePolicy,
+        idle_state: &mut RelayClientIdleState,
+        last_downstream_activity_ms: &AtomicU64,
+        session_started_at: Instant,
+        forensics: &RelayForensicsState,
+        stats: &Stats,
+        shared: &ProxySharedState,
+        read_label: &'static str,
+    ) -> Result<()>
+    where
+        R: AsyncRead + Unpin + Send + 'static,
+    {
+        fn hard_deadline(
+            idle_policy: &RelayClientIdlePolicy,
+            idle_state: &RelayClientIdleState,
+            session_started_at: Instant,
+            last_downstream_activity_ms: u64,
+        ) -> Instant {
+            let mut deadline = idle_state.last_client_frame_at + idle_policy.hard_idle;
+            if idle_policy.grace_after_downstream_activity.is_zero() {
+                return deadline;
+            }
+
+            let downstream_at =
+                session_started_at + Duration::from_millis(last_downstream_activity_ms);
+            if downstream_at > idle_state.last_client_frame_at {
+                let grace_deadline = downstream_at + idle_policy.grace_after_downstream_activity;
+                if grace_deadline > deadline {
+                    deadline = grace_deadline;
+                }
+            }
+            deadline
+        }
+
+        let mut filled = 0usize;
+        while filled < buf.len() {
+            let timeout_window = if idle_policy.enabled {
+                let now = Instant::now();
+                let downstream_ms = last_downstream_activity_ms.load(Ordering::Relaxed);
+                let hard_deadline =
+                    hard_deadline(idle_policy, idle_state, session_started_at, downstream_ms);
+                if !idle_state.soft_idle_marked
+                    && now.saturating_duration_since(idle_state.last_client_frame_at)
+                        >= idle_policy.soft_idle
+                {
+                    idle_state.soft_idle_marked = true;
+                    if mark_relay_idle_candidate_in(shared, forensics.conn_id) {
+                        stats.increment_relay_idle_soft_mark_total();
+                    }
+                    info!(
+                        trace_id = format_args!("0x{:016x}", forensics.trace_id),
+                        conn_id = forensics.conn_id,
+                        user = %forensics.user,
+                        read_label,
+                        soft_idle_secs = idle_policy.soft_idle.as_secs(),
+                        hard_idle_secs = idle_policy.hard_idle.as_secs(),
+                        grace_secs = idle_policy.grace_after_downstream_activity.as_secs(),
+                        "Middle-relay soft idle mark"
+                    );
+                }
+
+                let soft_deadline = idle_state.last_client_frame_at + idle_policy.soft_idle;
+                let next_deadline = if idle_state.soft_idle_marked {
+                    hard_deadline
+                } else {
+                    soft_deadline.min(hard_deadline)
+                };
+                let mut remaining = next_deadline.saturating_duration_since(now);
+                if remaining.is_zero() {
+                    remaining = Duration::from_millis(1);
+                }
+                remaining.min(RELAY_IDLE_IO_POLL_MAX)
+            } else {
+                idle_policy.legacy_frame_read_timeout
+            };
+
+            let read_result = timeout(timeout_window, client_reader.read(&mut buf[filled..])).await;
+            match read_result {
+                Ok(Ok(0)) => {
+                    return Err(ProxyError::Io(std::io::Error::from(
+                        std::io::ErrorKind::UnexpectedEof,
+                    )));
+                }
+                Ok(Ok(n)) => {
+                    filled = filled.saturating_add(n);
+                }
+                Ok(Err(e)) => return Err(ProxyError::Io(e)),
+                Err(_) if !idle_policy.enabled => {
+                    return Err(ProxyError::Io(std::io::Error::new(
+                        std::io::ErrorKind::TimedOut,
+                        format!(
+                            "middle-relay client frame read timeout while reading {read_label}"
+                        ),
+                    )));
+                }
+                Err(_) => {
+                    let now = Instant::now();
+                    let downstream_ms = last_downstream_activity_ms.load(Ordering::Relaxed);
+                    let hard_deadline =
+                        hard_deadline(idle_policy, idle_state, session_started_at, downstream_ms);
+                    if now >= hard_deadline {
+                        clear_relay_idle_candidate_in(shared, forensics.conn_id);
+                        stats.increment_relay_idle_hard_close_total();
+                        let client_idle_secs = now
+                            .saturating_duration_since(idle_state.last_client_frame_at)
+                            .as_secs();
+                        let downstream_idle_secs = now
+                            .saturating_duration_since(
+                                session_started_at + Duration::from_millis(downstream_ms),
+                            )
+                            .as_secs();
+                        warn!(
+                            trace_id = format_args!("0x{:016x}", forensics.trace_id),
+                            conn_id = forensics.conn_id,
+                            user = %forensics.user,
+                            read_label,
+                            client_idle_secs,
+                            downstream_idle_secs,
+                            soft_idle_secs = idle_policy.soft_idle.as_secs(),
+                            hard_idle_secs = idle_policy.hard_idle.as_secs(),
+                            grace_secs = idle_policy.grace_after_downstream_activity.as_secs(),
+                            "Middle-relay hard idle close"
+                        );
+                        return Err(ProxyError::Io(std::io::Error::new(
+                            std::io::ErrorKind::TimedOut,
+                            format!(
+                                "middle-relay hard idle timeout while reading {read_label}: client_idle_secs={client_idle_secs}, downstream_idle_secs={downstream_idle_secs}, soft_idle_secs={}, hard_idle_secs={}, grace_secs={}",
+                                idle_policy.soft_idle.as_secs(),
+                                idle_policy.hard_idle.as_secs(),
+                                idle_policy.grace_after_downstream_activity.as_secs(),
+                            ),
+                        )));
+                    }
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    let mut consecutive_zero_len_frames = 0u32;
+    loop {
+        let (len, quickack, raw_len_bytes) = match proto_tag {
+            ProtoTag::Abridged => {
+                let mut first = [0u8; 1];
+                match read_exact_with_policy(
+                    client_reader,
+                    &mut first,
+                    idle_policy,
+                    idle_state,
+                    last_downstream_activity_ms,
+                    session_started_at,
+                    forensics,
+                    stats,
+                    shared,
+                    "abridged.first_len_byte",
+                )
+                .await
+                {
+                    Ok(()) => {}
+                    Err(ProxyError::Io(e)) if e.kind() == std::io::ErrorKind::UnexpectedEof => {
+                        return Ok(None);
+                    }
+                    Err(e) => return Err(e),
+                }
+
+                let quickack = (first[0] & 0x80) != 0;
+                let len_words = if (first[0] & 0x7f) == 0x7f {
+                    let mut ext = [0u8; 3];
+                    read_exact_with_policy(
+                        client_reader,
+                        &mut ext,
+                        idle_policy,
+                        idle_state,
+                        last_downstream_activity_ms,
+                        session_started_at,
+                        forensics,
+                        stats,
+                        shared,
+                        "abridged.extended_len",
+                    )
+                    .await?;
+                    u32::from_le_bytes([ext[0], ext[1], ext[2], 0]) as usize
+                } else {
+                    (first[0] & 0x7f) as usize
+                };
+
+                let len = len_words
+                    .checked_mul(4)
+                    .ok_or_else(|| ProxyError::Proxy("Abridged frame length overflow".into()))?;
+                (len, quickack, None)
+            }
+            ProtoTag::Intermediate | ProtoTag::Secure => {
+                let mut len_buf = [0u8; 4];
+                match read_exact_with_policy(
+                    client_reader,
+                    &mut len_buf,
+                    idle_policy,
+                    idle_state,
+                    last_downstream_activity_ms,
+                    session_started_at,
+                    forensics,
+                    stats,
+                    shared,
+                    "len_prefix",
+                )
+                .await
+                {
+                    Ok(()) => {}
+                    Err(ProxyError::Io(e)) if e.kind() == std::io::ErrorKind::UnexpectedEof => {
+                        return Ok(None);
+                    }
+                    Err(e) => return Err(e),
+                }
+                let quickack = (len_buf[3] & 0x80) != 0;
+                (
+                    (u32::from_le_bytes(len_buf) & 0x7fff_ffff) as usize,
+                    quickack,
+                    Some(len_buf),
+                )
+            }
+        };
+
+        if len == 0 {
+            idle_state.on_client_tiny_frame(Instant::now());
+            idle_state.tiny_frame_debt = idle_state
+                .tiny_frame_debt
+                .saturating_add(TINY_FRAME_DEBT_PER_TINY);
+            if idle_state.tiny_frame_debt >= TINY_FRAME_DEBT_LIMIT {
+                stats.increment_relay_protocol_desync_close_total();
+                return Err(ProxyError::Proxy(format!(
+                    "Tiny frame overhead limit exceeded: debt={}, conn_id={}",
+                    idle_state.tiny_frame_debt, forensics.conn_id
+                )));
+            }
+
+            if !idle_policy.enabled {
+                consecutive_zero_len_frames = consecutive_zero_len_frames.saturating_add(1);
+                if consecutive_zero_len_frames > LEGACY_MAX_CONSECUTIVE_ZERO_LEN_FRAMES {
+                    stats.increment_relay_protocol_desync_close_total();
+                    return Err(ProxyError::Proxy(
+                        "Excessive zero-length abridged frames".to_string(),
+                    ));
+                }
+            }
+            continue;
+        }
+        if len < 4 && proto_tag != ProtoTag::Abridged {
+            warn!(
+                trace_id = format_args!("0x{:016x}", forensics.trace_id),
+                conn_id = forensics.conn_id,
+                user = %forensics.user,
+                len,
+                proto = ?proto_tag,
+                "Frame too small — corrupt or probe"
+            );
+            stats.increment_relay_protocol_desync_close_total();
+            return Err(ProxyError::Proxy(format!("Frame too small: {len}")));
+        }
+
+        if len > max_frame {
+            return Err(report_desync_frame_too_large_in(
+                shared,
+                forensics,
+                proto_tag,
+                *frame_counter,
+                max_frame,
+                len,
+                raw_len_bytes,
+                stats,
+            ));
+        }
+
+        let secure_payload_len = if proto_tag == ProtoTag::Secure {
+            match secure_payload_len_from_wire_len(len) {
+                Some(payload_len) => payload_len,
+                None => {
+                    stats.increment_secure_padding_invalid();
+                    stats.increment_relay_protocol_desync_close_total();
+                    return Err(ProxyError::Proxy(format!(
+                        "Invalid secure frame length: {len}"
+                    )));
+                }
+            }
+        } else {
+            len
+        };
+
+        let mut payload = buffer_pool.get();
+        payload.clear();
+        let current_cap = payload.capacity();
+        if current_cap < len {
+            payload.reserve(len - current_cap);
+        }
+        payload.resize(len, 0);
+        read_exact_with_policy(
+            client_reader,
+            &mut payload[..len],
+            idle_policy,
+            idle_state,
+            last_downstream_activity_ms,
+            session_started_at,
+            forensics,
+            stats,
+            shared,
+            "payload",
+        )
+        .await?;
+
+        // Secure Intermediate: strip validated trailing padding bytes.
+        if proto_tag == ProtoTag::Secure {
+            payload.truncate(secure_payload_len);
+        }
+        *frame_counter += 1;
+        idle_state.on_client_frame(Instant::now());
+        idle_state.tiny_frame_debt = idle_state.tiny_frame_debt.saturating_sub(1);
+        clear_relay_idle_candidate_in(shared, forensics.conn_id);
+        return Ok(Some((payload, quickack)));
+    }
+}
+
+#[cfg(test)]
+pub(crate) async fn read_client_payload_with_idle_policy<R>(
+    client_reader: &mut CryptoReader<R>,
+    proto_tag: ProtoTag,
+    max_frame: usize,
+    buffer_pool: &Arc<BufferPool>,
+    forensics: &RelayForensicsState,
+    frame_counter: &mut u64,
+    stats: &Stats,
+    idle_policy: &RelayClientIdlePolicy,
+    idle_state: &mut RelayClientIdleState,
+    last_downstream_activity_ms: &AtomicU64,
+    session_started_at: Instant,
+) -> Result<Option<(PooledBuffer, bool)>>
+where
+    R: AsyncRead + Unpin + Send + 'static,
+{
+    let shared = ProxySharedState::new();
+    read_client_payload_with_idle_policy_in(
+        client_reader,
+        proto_tag,
+        max_frame,
+        buffer_pool,
+        forensics,
+        frame_counter,
+        stats,
+        shared.as_ref(),
+        idle_policy,
+        idle_state,
+        last_downstream_activity_ms,
+        session_started_at,
+    )
+    .await
+}
+
+#[cfg(test)]
+pub(crate) async fn read_client_payload_legacy<R>(
+    client_reader: &mut CryptoReader<R>,
+    proto_tag: ProtoTag,
+    max_frame: usize,
+    frame_read_timeout: Duration,
+    buffer_pool: &Arc<BufferPool>,
+    forensics: &RelayForensicsState,
+    frame_counter: &mut u64,
+    stats: &Stats,
+) -> Result<Option<(PooledBuffer, bool)>>
+where
+    R: AsyncRead + Unpin + Send + 'static,
+{
+    let now = Instant::now();
+    let shared = ProxySharedState::new();
+    let mut idle_state = RelayClientIdleState::new(now);
+    let last_downstream_activity_ms = AtomicU64::new(0);
+    let idle_policy = RelayClientIdlePolicy::disabled(frame_read_timeout);
+    read_client_payload_with_idle_policy_in(
+        client_reader,
+        proto_tag,
+        max_frame,
+        buffer_pool,
+        forensics,
+        frame_counter,
+        stats,
+        shared.as_ref(),
+        &idle_policy,
+        &mut idle_state,
+        &last_downstream_activity_ms,
+        now,
+    )
+    .await
+}
+
+#[cfg(test)]
+pub(crate) async fn read_client_payload<R>(
+    client_reader: &mut CryptoReader<R>,
+    proto_tag: ProtoTag,
+    max_frame: usize,
+    frame_read_timeout: Duration,
+    buffer_pool: &Arc<BufferPool>,
+    forensics: &RelayForensicsState,
+    frame_counter: &mut u64,
+    stats: &Stats,
+) -> Result<Option<(PooledBuffer, bool)>>
+where
+    R: AsyncRead + Unpin + Send + 'static,
+{
+    read_client_payload_legacy(
+        client_reader,
+        proto_tag,
+        max_frame,
+        frame_read_timeout,
+        buffer_pool,
+        forensics,
+        frame_counter,
+        stats,
+    )
+    .await
+}

src/proxy/middle_relay/quota.rs

@@ -0,0 +1,153 @@
+use super::*;
+
+pub(super) enum MiddleQuotaReserveError {
+    LimitExceeded,
+    Contended,
+    Cancelled,
+    DeadlineExceeded,
+}
+
+pub(super) fn quota_soft_cap(limit: u64, overshoot: u64) -> u64 {
+    limit.saturating_add(overshoot)
+}
+
+pub(super) async fn reserve_user_quota_with_yield(
+    user_stats: &UserStats,
+    bytes: u64,
+    limit: u64,
+    stats: &Stats,
+    cancel: &CancellationToken,
+    deadline: Option<Instant>,
+) -> std::result::Result<u64, MiddleQuotaReserveError> {
+    let mut backoff_ms = QUOTA_RESERVE_BACKOFF_MIN_MS;
+    let mut backoff_rounds = 0usize;
+    loop {
+        for _ in 0..QUOTA_RESERVE_SPIN_RETRIES {
+            match user_stats.quota_try_reserve(bytes, limit) {
+                Ok(total) => return Ok(total),
+                Err(QuotaReserveError::LimitExceeded) => {
+                    return Err(MiddleQuotaReserveError::LimitExceeded);
+                }
+                Err(QuotaReserveError::Contended) => {
+                    stats.increment_quota_contention_total();
+                    std::hint::spin_loop();
+                }
+            }
+        }
+
+        tokio::task::yield_now().await;
+        if deadline.is_some_and(|deadline| Instant::now() >= deadline) {
+            stats.increment_quota_contention_timeout_total();
+            return Err(MiddleQuotaReserveError::DeadlineExceeded);
+        }
+        tokio::select! {
+            biased;
+            _ = cancel.cancelled() => {
+                stats.increment_quota_acquire_cancelled_total();
+                return Err(MiddleQuotaReserveError::Cancelled);
+            }
+            _ = tokio::time::sleep(Duration::from_millis(backoff_ms)) => {}
+        }
+        backoff_rounds = backoff_rounds.saturating_add(1);
+        if backoff_rounds >= QUOTA_RESERVE_MAX_BACKOFF_ROUNDS {
+            stats.increment_quota_contention_timeout_total();
+            return Err(MiddleQuotaReserveError::Contended);
+        }
+        backoff_ms = backoff_ms
+            .saturating_mul(2)
+            .min(QUOTA_RESERVE_BACKOFF_MAX_MS);
+    }
+}
+
+pub(super) async fn wait_for_traffic_budget(
+    lease: Option<&Arc<TrafficLease>>,
+    direction: RateDirection,
+    bytes: u64,
+    deadline: Option<Instant>,
+) -> Result<()> {
+    if bytes == 0 {
+        return Ok(());
+    }
+    let Some(lease) = lease else {
+        return Ok(());
+    };
+
+    let mut remaining = bytes;
+    while remaining > 0 {
+        let consume = lease.try_consume(direction, remaining);
+        if consume.granted > 0 {
+            remaining = remaining.saturating_sub(consume.granted);
+            continue;
+        }
+
+        let wait_started_at = Instant::now();
+        if deadline.is_some_and(|deadline| wait_started_at >= deadline) {
+            return Err(ProxyError::TrafficBudgetWaitDeadlineExceeded);
+        }
+        tokio::time::sleep(next_refill_delay()).await;
+        let wait_ms = wait_started_at
+            .elapsed()
+            .as_millis()
+            .min(u128::from(u64::MAX)) as u64;
+        lease.observe_wait_ms(
+            direction,
+            consume.blocked_user,
+            consume.blocked_cidr,
+            wait_ms,
+        );
+    }
+
+    Ok(())
+}
+
+pub(super) async fn wait_for_traffic_budget_or_cancel(
+    lease: Option<&Arc<TrafficLease>>,
+    direction: RateDirection,
+    bytes: u64,
+    cancel: &CancellationToken,
+    stats: &Stats,
+    deadline: Option<Instant>,
+) -> Result<()> {
+    if bytes == 0 {
+        return Ok(());
+    }
+    let Some(lease) = lease else {
+        return Ok(());
+    };
+
+    let mut remaining = bytes;
+    while remaining > 0 {
+        let consume = lease.try_consume(direction, remaining);
+        if consume.granted > 0 {
+            remaining = remaining.saturating_sub(consume.granted);
+            continue;
+        }
+
+        let wait_started_at = Instant::now();
+        if deadline.is_some_and(|deadline| wait_started_at >= deadline) {
+            stats.increment_flow_wait_middle_rate_limit_cancelled_total();
+            return Err(ProxyError::TrafficBudgetWaitDeadlineExceeded);
+        }
+        tokio::select! {
+            biased;
+            _ = cancel.cancelled() => {
+                stats.increment_flow_wait_middle_rate_limit_cancelled_total();
+                return Err(ProxyError::TrafficBudgetWaitCancelled);
+            }
+            _ = tokio::time::sleep(next_refill_delay()) => {}
+        }
+        let wait_ms = wait_started_at
+            .elapsed()
+            .as_millis()
+            .min(u128::from(u64::MAX)) as u64;
+        lease.observe_wait_ms(
+            direction,
+            consume.blocked_user,
+            consume.blocked_cidr,
+            wait_ms,
+        );
+        stats.observe_flow_wait_middle_rate_limit_ms(wait_ms);
+    }
+
+    Ok(())
+}

src/proxy/middle_relay/session.rs

@@ -0,0 +1,854 @@
+use super::*;
+
+pub(crate) async fn handle_via_middle_proxy<R, W>(
+    mut crypto_reader: CryptoReader<R>,
+    crypto_writer: CryptoWriter<W>,
+    success: HandshakeSuccess,
+    me_pool: Arc<MePool>,
+    stats: Arc<Stats>,
+    config: Arc<ProxyConfig>,
+    buffer_pool: Arc<BufferPool>,
+    local_addr: SocketAddr,
+    rng: Arc<SecureRandom>,
+    mut route_rx: watch::Receiver<RouteCutoverState>,
+    route_snapshot: RouteCutoverState,
+    session_id: u64,
+    session_cancel: CancellationToken,
+    shared: Arc<ProxySharedState>,
+) -> Result<()>
+where
+    R: AsyncRead + Unpin + Send + 'static,
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    let user = success.user.clone();
+    if session_cancel.is_cancelled() {
+        return Err(ProxyError::UserDisabled { user });
+    }
+
+    let quota_limit = config.access.user_data_quota.get(&user).copied();
+    let quota_user_stats = quota_limit.map(|_| stats.get_or_create_user_stats_handle(&user));
+    let peer = success.peer;
+    let traffic_lease = shared.traffic_limiter.acquire_lease(&user, peer.ip());
+    let proto_tag = success.proto_tag;
+    let pool_generation = me_pool.current_generation();
+
+    debug!(
+        user = %user,
+        peer = %peer,
+        dc = success.dc_idx,
+        proto = ?proto_tag,
+        mode = "middle_proxy",
+        pool_generation,
+        "Routing via Middle-End"
+    );
+
+    let (conn_id, me_rx) = me_pool.registry().register().await;
+    let trace_id = session_id;
+    let bytes_me2c = Arc::new(AtomicU64::new(0));
+    let mut forensics = RelayForensicsState {
+        trace_id,
+        conn_id,
+        user: user.clone(),
+        peer,
+        peer_hash: hash_ip_in(shared.as_ref(), peer.ip()),
+        started_at: Instant::now(),
+        bytes_c2me: 0,
+        bytes_me2c: bytes_me2c.clone(),
+        desync_all_full: config.general.desync_all_full,
+    };
+
+    stats.increment_user_connects(&user);
+    let _me_connection_lease = stats.acquire_me_connection_lease();
+
+    if let Some(cutover) =
+        affected_cutover_state(&route_rx, RelayRouteMode::Middle, route_snapshot.generation)
+    {
+        let delay = cutover_stagger_delay(session_id, cutover.generation);
+        warn!(
+            conn_id,
+            target_mode = cutover.mode.as_str(),
+            cutover_generation = cutover.generation,
+            delay_ms = delay.as_millis() as u64,
+            "Cutover affected middle session before relay start, closing client connection"
+        );
+        let _cutover_park_lease = stats.acquire_middle_cutover_park_lease();
+        tokio::time::sleep(delay).await;
+        let _ = me_pool.send_close(conn_id).await;
+        me_pool.registry().unregister(conn_id).await;
+        return Err(ProxyError::RouteSwitched);
+    }
+
+    // Per-user ad_tag from access.user_ad_tags; fallback to general.ad_tag (hot-reloadable)
+    let user_tag: Option<Vec<u8>> = config
+        .access
+        .user_ad_tags
+        .get(&user)
+        .and_then(|s| hex::decode(s).ok())
+        .filter(|v| v.len() == 16);
+    let global_tag: Option<Vec<u8>> = config
+        .general
+        .ad_tag
+        .as_ref()
+        .and_then(|s| hex::decode(s).ok())
+        .filter(|v| v.len() == 16);
+    let effective_tag = user_tag.or(global_tag);
+
+    let proto_flags = proto_flags_for_tag(proto_tag, effective_tag.is_some());
+    let effective_tag_array = effective_tag
+        .as_deref()
+        .and_then(|tag| <[u8; 16]>::try_from(tag).ok());
+    debug!(
+        trace_id = format_args!("0x{:016x}", trace_id),
+        user = %user,
+        conn_id,
+        peer_hash = format_args!("0x{:016x}", forensics.peer_hash),
+        desync_all_full = forensics.desync_all_full,
+        proto_flags = format_args!("0x{:08x}", proto_flags),
+        pool_generation,
+        "ME relay started"
+    );
+
+    let translated_local_addr = me_pool.translate_our_addr(local_addr);
+
+    let frame_limit = config.general.max_client_frame;
+    let mut relay_idle_policy = RelayClientIdlePolicy::from_config(&config);
+    let mut pressure_caps_applied = false;
+    if shared.conntrack_pressure_active() {
+        relay_idle_policy.apply_pressure_caps(config.server.conntrack_control.profile);
+        pressure_caps_applied = true;
+    }
+    let session_started_at = forensics.started_at;
+    let mut relay_idle_state = RelayClientIdleState::new(session_started_at);
+    let last_downstream_activity_ms = Arc::new(AtomicU64::new(0));
+
+    let c2me_channel_capacity = config
+        .general
+        .me_c2me_channel_capacity
+        .max(C2ME_CHANNEL_CAPACITY_FALLBACK);
+    let c2me_send_timeout = match config.general.me_c2me_send_timeout_ms {
+        0 => None,
+        timeout_ms => Some(Duration::from_millis(timeout_ms)),
+    };
+    let c2me_byte_budget = c2me_queued_permit_budget(c2me_channel_capacity, frame_limit);
+    let c2me_byte_semaphore = Arc::new(Semaphore::new(c2me_byte_budget));
+    let (c2me_tx, mut c2me_rx) = mpsc::channel::<C2MeCommand>(c2me_channel_capacity);
+    let me_pool_c2me = me_pool.clone();
+    let mut c2me_sender = tokio::spawn(async move {
+        let mut sent_since_yield = 0usize;
+        while let Some(cmd) = c2me_rx.recv().await {
+            match cmd {
+                C2MeCommand::Data {
+                    payload,
+                    flags,
+                    _permit,
+                } => {
+                    me_pool_c2me
+                        .send_proxy_req_pooled(
+                            conn_id,
+                            success.dc_idx,
+                            peer,
+                            translated_local_addr,
+                            payload,
+                            flags,
+                            effective_tag_array,
+                        )
+                        .await?;
+                    sent_since_yield = sent_since_yield.saturating_add(1);
+                    if should_yield_c2me_sender(sent_since_yield, !c2me_rx.is_empty()) {
+                        sent_since_yield = 0;
+                        tokio::task::yield_now().await;
+                    }
+                }
+                C2MeCommand::Close => {
+                    let _ = me_pool_c2me.send_close(conn_id).await;
+                    return Ok(());
+                }
+            }
+        }
+        Ok(())
+    });
+
+    let (stop_tx, mut stop_rx) = oneshot::channel::<()>();
+    let flow_cancel = CancellationToken::new();
+    let mut me_rx_task = me_rx;
+    let stats_clone = stats.clone();
+    let rng_clone = rng.clone();
+    let user_clone = user.clone();
+    let quota_user_stats_me_writer = quota_user_stats.clone();
+    let traffic_lease_me_writer = traffic_lease.clone();
+    let flow_cancel_me_writer = flow_cancel.clone();
+    let last_downstream_activity_ms_clone = last_downstream_activity_ms.clone();
+    let bytes_me2c_clone = bytes_me2c.clone();
+    let d2c_flush_policy = MeD2cFlushPolicy::from_config(&config);
+    let mut me_writer = tokio::spawn(async move {
+        let mut writer = crypto_writer;
+        let mut frame_buf = Vec::with_capacity(16 * 1024);
+        let shrink_threshold = d2c_flush_policy.frame_buf_shrink_threshold_bytes;
+
+        fn shrink_session_vec(buf: &mut Vec<u8>, threshold: usize) {
+            if buf.capacity() > threshold {
+                buf.clear();
+                buf.shrink_to(threshold);
+            } else {
+                buf.clear();
+            }
+        }
+
+        loop {
+            tokio::select! {
+                msg = me_rx_task.recv() => {
+                    let Some(first) = msg else {
+                        debug!(conn_id, "ME channel closed");
+                        shrink_session_vec(&mut frame_buf, shrink_threshold);
+                        return Err(ProxyError::MiddleConnectionLost);
+                    };
+
+                    let mut batch_frames = 0usize;
+                    let mut batch_bytes = 0usize;
+                    let mut flush_immediately;
+                    let mut max_delay_fired = false;
+
+                    let first_is_downstream_activity =
+                        matches!(&first, MeResponse::Data { .. } | MeResponse::Ack(_));
+                    match process_me_writer_response_with_traffic_lease(
+                        first,
+                        &mut writer,
+                        proto_tag,
+                        rng_clone.as_ref(),
+                        &mut frame_buf,
+                        stats_clone.as_ref(),
+                        &user_clone,
+                        quota_user_stats_me_writer.as_deref(),
+                        quota_limit,
+                        d2c_flush_policy.quota_soft_overshoot_bytes,
+                        traffic_lease_me_writer.as_ref(),
+                        &flow_cancel_me_writer,
+                        bytes_me2c_clone.as_ref(),
+                        conn_id,
+                        d2c_flush_policy.ack_flush_immediate,
+                        false,
+                    ).await? {
+                        MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                            if first_is_downstream_activity {
+                                last_downstream_activity_ms_clone
+                                    .store(session_started_at.elapsed().as_millis() as u64, Ordering::Relaxed);
+                            }
+                            batch_frames = batch_frames.saturating_add(frames);
+                            batch_bytes = batch_bytes.saturating_add(bytes);
+                            flush_immediately = immediate;
+                        }
+                        MeWriterResponseOutcome::Close => {
+                            let flush_started_at = if stats_clone.telemetry_policy().me_level.allows_debug() {
+                                Some(Instant::now())
+                            } else {
+                                None
+                            };
+                            let _ = flush_client_or_cancel(&mut writer, &flow_cancel_me_writer).await;
+                            let flush_duration_us = flush_started_at.map(|started| {
+                                started
+                                    .elapsed()
+                                    .as_micros()
+                                    .min(u128::from(u64::MAX)) as u64
+                            });
+                            observe_me_d2c_flush_event(
+                                stats_clone.as_ref(),
+                                MeD2cFlushReason::Close,
+                                batch_frames,
+                                batch_bytes,
+                                flush_duration_us,
+                            );
+                            shrink_session_vec(&mut frame_buf, shrink_threshold);
+                            return Ok(());
+                        }
+                    }
+
+                    while !flush_immediately
+                        && batch_frames < d2c_flush_policy.max_frames
+                        && batch_bytes < d2c_flush_policy.max_bytes
+                    {
+                        let Ok(next) = me_rx_task.try_recv() else {
+                            break;
+                        };
+
+                        let next_is_downstream_activity =
+                            matches!(&next, MeResponse::Data { .. } | MeResponse::Ack(_));
+                        match process_me_writer_response_with_traffic_lease(
+                            next,
+                            &mut writer,
+                            proto_tag,
+                            rng_clone.as_ref(),
+                            &mut frame_buf,
+                            stats_clone.as_ref(),
+                            &user_clone,
+                            quota_user_stats_me_writer.as_deref(),
+                            quota_limit,
+                            d2c_flush_policy.quota_soft_overshoot_bytes,
+                            traffic_lease_me_writer.as_ref(),
+                            &flow_cancel_me_writer,
+                            bytes_me2c_clone.as_ref(),
+                            conn_id,
+                            d2c_flush_policy.ack_flush_immediate,
+                            true,
+                        ).await? {
+                            MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                                if next_is_downstream_activity {
+                                    last_downstream_activity_ms_clone
+                                        .store(session_started_at.elapsed().as_millis() as u64, Ordering::Relaxed);
+                                }
+                                batch_frames = batch_frames.saturating_add(frames);
+                                batch_bytes = batch_bytes.saturating_add(bytes);
+                                flush_immediately |= immediate;
+                            }
+                            MeWriterResponseOutcome::Close => {
+                                let flush_started_at =
+                                    if stats_clone.telemetry_policy().me_level.allows_debug() {
+                                        Some(Instant::now())
+                                    } else {
+                                        None
+                                    };
+                                let _ =
+                                    flush_client_or_cancel(&mut writer, &flow_cancel_me_writer).await;
+                                let flush_duration_us = flush_started_at.map(|started| {
+                                    started
+                                        .elapsed()
+                                        .as_micros()
+                                        .min(u128::from(u64::MAX))
+                                        as u64
+                                });
+                                observe_me_d2c_flush_event(
+                                    stats_clone.as_ref(),
+                                    MeD2cFlushReason::Close,
+                                    batch_frames,
+                                    batch_bytes,
+                                    flush_duration_us,
+                                );
+                                shrink_session_vec(&mut frame_buf, shrink_threshold);
+                                return Ok(());
+                            }
+                        }
+                    }
+
+                    if !flush_immediately
+                        && !d2c_flush_policy.max_delay.is_zero()
+                        && batch_frames < d2c_flush_policy.max_frames
+                        && batch_bytes < d2c_flush_policy.max_bytes
+                    {
+                        stats_clone.increment_me_d2c_batch_timeout_armed_total();
+                        match tokio::time::timeout(d2c_flush_policy.max_delay, me_rx_task.recv()).await {
+                            Ok(Some(next)) => {
+                                let next_is_downstream_activity =
+                                    matches!(&next, MeResponse::Data { .. } | MeResponse::Ack(_));
+                                match process_me_writer_response_with_traffic_lease(
+                                    next,
+                                    &mut writer,
+                                    proto_tag,
+                                    rng_clone.as_ref(),
+                                    &mut frame_buf,
+                                    stats_clone.as_ref(),
+                                    &user_clone,
+                                    quota_user_stats_me_writer.as_deref(),
+                                    quota_limit,
+                                    d2c_flush_policy.quota_soft_overshoot_bytes,
+                                    traffic_lease_me_writer.as_ref(),
+                                    &flow_cancel_me_writer,
+                                    bytes_me2c_clone.as_ref(),
+                                    conn_id,
+                                    d2c_flush_policy.ack_flush_immediate,
+                                    true,
+                                ).await? {
+                                    MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                                        if next_is_downstream_activity {
+                                            last_downstream_activity_ms_clone
+                                                .store(session_started_at.elapsed().as_millis() as u64, Ordering::Relaxed);
+                                        }
+                                        batch_frames = batch_frames.saturating_add(frames);
+                                        batch_bytes = batch_bytes.saturating_add(bytes);
+                                        flush_immediately |= immediate;
+                                    }
+                                    MeWriterResponseOutcome::Close => {
+                                        let flush_started_at = if stats_clone
+                                            .telemetry_policy()
+                                            .me_level
+                                            .allows_debug()
+                                        {
+                                            Some(Instant::now())
+                                        } else {
+                                            None
+                                        };
+                                        let _ = flush_client_or_cancel(
+                                            &mut writer,
+                                            &flow_cancel_me_writer,
+                                        )
+                                        .await;
+                                        let flush_duration_us = flush_started_at.map(|started| {
+                                            started
+                                                .elapsed()
+                                                .as_micros()
+                                                .min(u128::from(u64::MAX))
+                                                as u64
+                                        });
+                                        observe_me_d2c_flush_event(
+                                            stats_clone.as_ref(),
+                                            MeD2cFlushReason::Close,
+                                            batch_frames,
+                                            batch_bytes,
+                                            flush_duration_us,
+                                        );
+                                        shrink_session_vec(&mut frame_buf, shrink_threshold);
+                                        return Ok(());
+                                    }
+                                }
+
+                                while !flush_immediately
+                                    && batch_frames < d2c_flush_policy.max_frames
+                                    && batch_bytes < d2c_flush_policy.max_bytes
+                                {
+                                    let Ok(extra) = me_rx_task.try_recv() else {
+                                        break;
+                                    };
+
+                                    let extra_is_downstream_activity =
+                                        matches!(&extra, MeResponse::Data { .. } | MeResponse::Ack(_));
+                                    match process_me_writer_response_with_traffic_lease(
+                                        extra,
+                                        &mut writer,
+                                        proto_tag,
+                                        rng_clone.as_ref(),
+                                        &mut frame_buf,
+                                        stats_clone.as_ref(),
+                                        &user_clone,
+                                        quota_user_stats_me_writer.as_deref(),
+                                        quota_limit,
+                                        d2c_flush_policy.quota_soft_overshoot_bytes,
+                                        traffic_lease_me_writer.as_ref(),
+                                        &flow_cancel_me_writer,
+                                        bytes_me2c_clone.as_ref(),
+                                        conn_id,
+                                        d2c_flush_policy.ack_flush_immediate,
+                                        true,
+                                    ).await? {
+                                        MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                                            if extra_is_downstream_activity {
+                                                last_downstream_activity_ms_clone
+                                                    .store(session_started_at.elapsed().as_millis() as u64, Ordering::Relaxed);
+                                            }
+                                            batch_frames = batch_frames.saturating_add(frames);
+                                            batch_bytes = batch_bytes.saturating_add(bytes);
+                                            flush_immediately |= immediate;
+                                        }
+                                        MeWriterResponseOutcome::Close => {
+                                            let flush_started_at = if stats_clone
+                                                .telemetry_policy()
+                                                .me_level
+                                                .allows_debug()
+                                            {
+                                                Some(Instant::now())
+                                            } else {
+                                                None
+                                            };
+                                            let _ = flush_client_or_cancel(
+                                                &mut writer,
+                                                &flow_cancel_me_writer,
+                                            )
+                                            .await;
+                                            let flush_duration_us = flush_started_at.map(|started| {
+                                                started
+                                                    .elapsed()
+                                                    .as_micros()
+                                                    .min(u128::from(u64::MAX))
+                                                    as u64
+                                            });
+                                            observe_me_d2c_flush_event(
+                                                stats_clone.as_ref(),
+                                                MeD2cFlushReason::Close,
+                                                batch_frames,
+                                                batch_bytes,
+                                                flush_duration_us,
+                                            );
+                                            shrink_session_vec(&mut frame_buf, shrink_threshold);
+                                            return Ok(());
+                                        }
+                                    }
+                                }
+                            }
+                            Ok(None) => {
+                                debug!(conn_id, "ME channel closed");
+                                shrink_session_vec(&mut frame_buf, shrink_threshold);
+                                return Err(ProxyError::MiddleConnectionLost);
+                            }
+                            Err(_) => {
+                                max_delay_fired = true;
+                                stats_clone.increment_me_d2c_batch_timeout_fired_total();
+                            }
+                        }
+                    }
+
+                    let flush_reason = classify_me_d2c_flush_reason(
+                        flush_immediately,
+                        batch_frames,
+                        d2c_flush_policy.max_frames,
+                        batch_bytes,
+                        d2c_flush_policy.max_bytes,
+                        max_delay_fired,
+                    );
+                    let flush_started_at = if stats_clone.telemetry_policy().me_level.allows_debug() {
+                        Some(Instant::now())
+                    } else {
+                        None
+                    };
+                    flush_client_or_cancel(&mut writer, &flow_cancel_me_writer).await?;
+                    let flush_duration_us = flush_started_at.map(|started| {
+                        started
+                            .elapsed()
+                            .as_micros()
+                            .min(u128::from(u64::MAX)) as u64
+                    });
+                    observe_me_d2c_flush_event(
+                        stats_clone.as_ref(),
+                        flush_reason,
+                        batch_frames,
+                        batch_bytes,
+                        flush_duration_us,
+                    );
+                    let shrink_threshold = d2c_flush_policy.frame_buf_shrink_threshold_bytes;
+                    let shrink_trigger = shrink_threshold
+                        .saturating_mul(ME_D2C_FRAME_BUF_SHRINK_HYSTERESIS_FACTOR);
+                    if frame_buf.capacity() > shrink_trigger {
+                        let cap_before = frame_buf.capacity();
+                        frame_buf.shrink_to(shrink_threshold);
+                        let cap_after = frame_buf.capacity();
+                        let bytes_freed = cap_before.saturating_sub(cap_after) as u64;
+                        stats_clone.observe_me_d2c_frame_buf_shrink(bytes_freed);
+                    }
+                }
+                _ = &mut stop_rx => {
+                    debug!(conn_id, "ME writer stop signal");
+                    shrink_session_vec(&mut frame_buf, shrink_threshold);
+                    return Ok(());
+                }
+            }
+        }
+    });
+
+    let mut main_result: Result<()> = Ok(());
+    let mut client_closed = false;
+    let mut frame_counter: u64 = 0;
+    let mut route_watch_open = true;
+    let mut seen_pressure_seq = relay_pressure_event_seq_in(shared.as_ref());
+    loop {
+        if shared.conntrack_pressure_active() && !pressure_caps_applied {
+            relay_idle_policy.apply_pressure_caps(config.server.conntrack_control.profile);
+            pressure_caps_applied = true;
+        }
+
+        if relay_idle_policy.enabled
+            && maybe_evict_idle_candidate_on_pressure_in(
+                shared.as_ref(),
+                conn_id,
+                &mut seen_pressure_seq,
+                stats.as_ref(),
+            )
+        {
+            info!(
+                conn_id,
+                trace_id = format_args!("0x{:016x}", trace_id),
+                user = %user,
+                "Middle-relay pressure eviction for idle-candidate session"
+            );
+            let _ = enqueue_c2me_command_in(
+                shared.as_ref(),
+                &c2me_tx,
+                C2MeCommand::Close,
+                c2me_send_timeout,
+                stats.as_ref(),
+            )
+            .await;
+            main_result = Err(ProxyError::Proxy(
+                "middle-relay session evicted under pressure (idle-candidate)".to_string(),
+            ));
+            break;
+        }
+
+        if let Some(cutover) =
+            affected_cutover_state(&route_rx, RelayRouteMode::Middle, route_snapshot.generation)
+        {
+            let delay = cutover_stagger_delay(session_id, cutover.generation);
+            warn!(
+                conn_id,
+                target_mode = cutover.mode.as_str(),
+                cutover_generation = cutover.generation,
+                delay_ms = delay.as_millis() as u64,
+                "Cutover affected middle session, closing client connection"
+            );
+            let _cutover_park_lease = stats.acquire_middle_cutover_park_lease();
+            tokio::time::sleep(delay).await;
+            let _ = enqueue_c2me_command_in(
+                shared.as_ref(),
+                &c2me_tx,
+                C2MeCommand::Close,
+                c2me_send_timeout,
+                stats.as_ref(),
+            )
+            .await;
+            main_result = Err(ProxyError::RouteSwitched);
+            break;
+        }
+
+        tokio::select! {
+            _ = session_cancel.cancelled() => {
+                warn!(
+                    user = %user,
+                    conn_id,
+                    "Disabled user middle session cancelled"
+                );
+                let _ = enqueue_c2me_command_in(
+                    shared.as_ref(),
+                    &c2me_tx,
+                    C2MeCommand::Close,
+                    c2me_send_timeout,
+                    stats.as_ref(),
+                )
+                .await;
+                main_result = Err(ProxyError::UserDisabled {
+                    user: user.clone(),
+                });
+                break;
+            }
+            changed = route_rx.changed(), if route_watch_open => {
+                if changed.is_err() {
+                    route_watch_open = false;
+                }
+            }
+            payload_result = read_client_payload_with_idle_policy_in(
+                &mut crypto_reader,
+                proto_tag,
+                frame_limit,
+                &buffer_pool,
+                &forensics,
+                &mut frame_counter,
+                &stats,
+                shared.as_ref(),
+                &relay_idle_policy,
+                &mut relay_idle_state,
+                last_downstream_activity_ms.as_ref(),
+                session_started_at,
+            ) => {
+                match payload_result {
+                    Ok(Some((payload, quickack))) => {
+                        trace!(conn_id, bytes = payload.len(), "C->ME frame");
+                        wait_for_traffic_budget(
+                            traffic_lease.as_ref(),
+                            RateDirection::Up,
+                            payload.len() as u64,
+                            None,
+                        )
+                        .await?;
+                        forensics.bytes_c2me = forensics
+                            .bytes_c2me
+                            .saturating_add(payload.len() as u64);
+                        if let (Some(limit), Some(user_stats)) =
+                            (quota_limit, quota_user_stats.as_deref())
+                        {
+                            match reserve_user_quota_with_yield(
+                                user_stats,
+                                payload.len() as u64,
+                                limit,
+                                stats.as_ref(),
+                                &flow_cancel,
+                                None,
+                            )
+                            .await
+                            {
+                                Ok(_) => {}
+                                Err(MiddleQuotaReserveError::LimitExceeded) => {
+                                    main_result = Err(ProxyError::DataQuotaExceeded {
+                                        user: user.clone(),
+                                    });
+                                    break;
+                                }
+                                Err(MiddleQuotaReserveError::Contended) => {
+                                    main_result = Err(ProxyError::Proxy(
+                                        "ME C->ME quota reservation contended".into(),
+                                    ));
+                                    break;
+                                }
+                                Err(MiddleQuotaReserveError::Cancelled) => {
+                                    main_result = Err(ProxyError::Proxy(
+                                        "ME C->ME quota reservation cancelled".into(),
+                                    ));
+                                    break;
+                                }
+                                Err(MiddleQuotaReserveError::DeadlineExceeded) => {
+                                    main_result = Err(ProxyError::Proxy(
+                                        "ME C->ME quota reservation deadline exceeded".into(),
+                                    ));
+                                    break;
+                                }
+                            }
+                            stats.add_user_octets_from_handle(user_stats, payload.len() as u64);
+                        } else {
+                            stats.add_user_octets_from(&user, payload.len() as u64);
+                        }
+                        let mut flags = proto_flags;
+                        if quickack {
+                            flags |= RPC_FLAG_QUICKACK;
+                        }
+                        if payload.len() >= 8 && payload[..8].iter().all(|b| *b == 0) {
+                            flags |= RPC_FLAG_NOT_ENCRYPTED;
+                        }
+                        let payload_permit = match acquire_c2me_payload_permit(
+                            &c2me_byte_semaphore,
+                            payload.len(),
+                            c2me_send_timeout,
+                            stats.as_ref(),
+                        )
+                        .await
+                        {
+                            Ok(permit) => permit,
+                            Err(e) => {
+                                main_result = Err(e);
+                                break;
+                            }
+                        };
+                        // Keep client read loop lightweight: route heavy ME send path via a dedicated task.
+                        if enqueue_c2me_command_in(
+                            shared.as_ref(),
+                            &c2me_tx,
+                            C2MeCommand::Data {
+                                payload,
+                                flags,
+                                _permit: payload_permit,
+                            },
+                            c2me_send_timeout,
+                            stats.as_ref(),
+                        )
+                        .await
+                            .is_err()
+                        {
+                            main_result = Err(ProxyError::Proxy("ME sender channel closed".into()));
+                            break;
+                        }
+                    }
+                    Ok(None) => {
+                        debug!(conn_id, "Client EOF");
+                        client_closed = true;
+                        let _ = enqueue_c2me_command_in(
+                            shared.as_ref(),
+                            &c2me_tx,
+                            C2MeCommand::Close,
+                            c2me_send_timeout,
+                            stats.as_ref(),
+                        )
+                        .await;
+                        break;
+                    }
+                    Err(e) => {
+                        main_result = Err(e);
+                        break;
+                    }
+                }
+            }
+        }
+    }
+
+    drop(c2me_tx);
+    let c2me_result = match timeout(ME_CHILD_JOIN_TIMEOUT, &mut c2me_sender).await {
+        Ok(joined) => {
+            joined.unwrap_or_else(|e| Err(ProxyError::Proxy(format!("ME sender join error: {e}"))))
+        }
+        Err(_) => {
+            stats.increment_me_child_join_timeout_total();
+            stats.increment_me_child_abort_total();
+            c2me_sender.abort();
+            Err(ProxyError::Proxy("ME sender join timeout".into()))
+        }
+    };
+
+    flow_cancel.cancel();
+    let _ = stop_tx.send(());
+    let mut writer_result = match timeout(ME_CHILD_JOIN_TIMEOUT, &mut me_writer).await {
+        Ok(joined) => {
+            joined.unwrap_or_else(|e| Err(ProxyError::Proxy(format!("ME writer join error: {e}"))))
+        }
+        Err(_) => {
+            stats.increment_me_child_join_timeout_total();
+            stats.increment_me_child_abort_total();
+            me_writer.abort();
+            Err(ProxyError::Proxy("ME writer join timeout".into()))
+        }
+    };
+
+    // When client closes, but ME channel stopped as unregistered - it isnt error
+    if client_closed && matches!(writer_result, Err(ProxyError::MiddleConnectionLost)) {
+        writer_result = Ok(());
+    }
+
+    let result = match (main_result, c2me_result, writer_result) {
+        (Ok(()), Ok(()), Ok(())) => Ok(()),
+        (Err(e), _, _) => Err(e),
+        (_, Err(e), _) => Err(e),
+        (_, _, Err(e)) => Err(e),
+    };
+
+    debug!(
+        user = %user,
+        conn_id,
+        trace_id = format_args!("0x{:016x}", trace_id),
+        duration_ms = forensics.started_at.elapsed().as_millis() as u64,
+        bytes_c2me = forensics.bytes_c2me,
+        bytes_me2c = forensics.bytes_me2c.load(Ordering::Relaxed),
+        frames_ok = frame_counter,
+        "ME relay cleanup"
+    );
+
+    let close_reason = classify_conntrack_close_reason(&result);
+    let publish_result = shared.publish_conntrack_close_event(ConntrackCloseEvent {
+        src: peer,
+        dst: local_addr,
+        reason: close_reason,
+    });
+    if !matches!(
+        publish_result,
+        ConntrackClosePublishResult::Sent | ConntrackClosePublishResult::Disabled
+    ) {
+        stats.increment_conntrack_close_event_drop_total();
+    }
+
+    clear_relay_idle_candidate_in(shared.as_ref(), conn_id);
+    me_pool.registry().unregister(conn_id).await;
+    buffer_pool.trim_to(buffer_pool.max_buffers().min(64));
+    let pool_snapshot = buffer_pool.stats();
+    stats.set_buffer_pool_gauges(
+        pool_snapshot.pooled,
+        pool_snapshot.allocated,
+        pool_snapshot.allocated.saturating_sub(pool_snapshot.pooled),
+    );
+    result
+}
+
+fn classify_conntrack_close_reason(result: &Result<()>) -> ConntrackCloseReason {
+    match result {
+        Ok(()) => ConntrackCloseReason::NormalEof,
+        Err(ProxyError::Io(error)) if matches!(error.kind(), std::io::ErrorKind::TimedOut) => {
+            ConntrackCloseReason::Timeout
+        }
+        Err(ProxyError::Io(error))
+            if matches!(
+                error.kind(),
+                std::io::ErrorKind::ConnectionReset
+                    | std::io::ErrorKind::ConnectionAborted
+                    | std::io::ErrorKind::BrokenPipe
+                    | std::io::ErrorKind::NotConnected
+                    | std::io::ErrorKind::UnexpectedEof
+            ) =>
+        {
+            ConntrackCloseReason::Reset
+        }
+        Err(ProxyError::Proxy(message))
+            if message.contains("pressure") || message.contains("evicted") =>
+        {
+            ConntrackCloseReason::Pressure
+        }
+        Err(_) => ConntrackCloseReason::Other,
+    }
+}

src/proxy/relay.rs

@@ -52,18 +52,17 @@
 //! - `SharedCounters` (atomics) let the watchdog read stats without locking
 
 use crate::error::{ProxyError, Result};
-use crate::proxy::traffic_limiter::{RateDirection, TrafficLease, next_refill_delay};
-use crate::stats::{Stats, UserStats};
+use crate::proxy::traffic_limiter::TrafficLease;
+use crate::stats::Stats;
 use crate::stream::BufferPool;
-use std::io;
-use std::pin::Pin;
+use std::future::pending;
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
-use std::task::{Context, Poll};
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::Duration;
-use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt, ReadBuf, copy_bidirectional_with_sizes};
-use tokio::time::{Instant, Sleep};
-use tracing::{debug, trace, warn};
+use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt, copy_bidirectional_with_sizes};
+use tokio::time::Instant;
+use tokio_util::sync::CancellationToken;
+use tracing::{debug, warn};
 
 // ============= Constants =============
 
@@ -85,700 +84,11 @@ fn watchdog_delta(current: u64, previous: u64) -> u64 {
     current.saturating_sub(previous)
 }
 
-// ============= CombinedStream =============
-
-/// Combines separate read and write halves into a single bidirectional stream.
-///
-/// `copy_bidirectional` requires `AsyncRead + AsyncWrite` on each side,
-/// but the handshake layer produces split reader/writer pairs
-/// (e.g. `CryptoReader<FakeTlsReader<OwnedReadHalf>>` + `CryptoWriter<...>`).
-///
-/// This wrapper reunifies them with zero overhead — each trait method
-/// delegates directly to the corresponding half. No buffering, no copies.
-///
-/// Safety: `poll_read` only touches `reader`, `poll_write` only touches `writer`,
-/// so there's no aliasing even though both are called on the same `&mut self`.
-struct CombinedStream<R, W> {
-    reader: R,
-    writer: W,
-}
-
-impl<R, W> CombinedStream<R, W> {
-    fn new(reader: R, writer: W) -> Self {
-        Self { reader, writer }
-    }
-}
-
-impl<R: AsyncRead + Unpin, W: Unpin> AsyncRead for CombinedStream<R, W> {
-    #[inline]
-    fn poll_read(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &mut ReadBuf<'_>,
-    ) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.get_mut().reader).poll_read(cx, buf)
-    }
-}
-
-impl<R: Unpin, W: AsyncWrite + Unpin> AsyncWrite for CombinedStream<R, W> {
-    #[inline]
-    fn poll_write(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &[u8],
-    ) -> Poll<io::Result<usize>> {
-        Pin::new(&mut self.get_mut().writer).poll_write(cx, buf)
-    }
-
-    #[inline]
-    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.get_mut().writer).poll_flush(cx)
-    }
-
-    #[inline]
-    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.get_mut().writer).poll_shutdown(cx)
-    }
-}
-
-// ============= SharedCounters =============
-
-/// Atomic counters shared between the relay (via StatsIo) and the watchdog task.
-///
-/// Using `Relaxed` ordering is sufficient because:
-/// - Counters are monotonically increasing (no ABA problem)
-/// - Slight staleness in watchdog reads is harmless (±10s check interval anyway)
-/// - No ordering dependencies between different counters
-struct SharedCounters {
-    /// Bytes read from client (C→S direction)
-    c2s_bytes: AtomicU64,
-    /// Bytes written to client (S→C direction)
-    s2c_bytes: AtomicU64,
-    /// Number of poll_read completions (≈ C→S chunks)
-    c2s_ops: AtomicU64,
-    /// Number of poll_write completions (≈ S→C chunks)
-    s2c_ops: AtomicU64,
-    /// Milliseconds since relay epoch of last I/O activity
-    last_activity_ms: AtomicU64,
-}
-
-impl SharedCounters {
-    fn new() -> Self {
-        Self {
-            c2s_bytes: AtomicU64::new(0),
-            s2c_bytes: AtomicU64::new(0),
-            c2s_ops: AtomicU64::new(0),
-            s2c_ops: AtomicU64::new(0),
-            last_activity_ms: AtomicU64::new(0),
-        }
-    }
-
-    /// Record activity at this instant.
-    #[inline]
-    fn touch(&self, now: Instant, epoch: Instant) {
-        let ms = now.duration_since(epoch).as_millis() as u64;
-        self.last_activity_ms.store(ms, Ordering::Relaxed);
-    }
-
-    /// How long since last recorded activity.
-    fn idle_duration(&self, now: Instant, epoch: Instant) -> Duration {
-        let last_ms = self.last_activity_ms.load(Ordering::Relaxed);
-        let now_ms = now.duration_since(epoch).as_millis() as u64;
-        Duration::from_millis(now_ms.saturating_sub(last_ms))
-    }
-}
-
-// ============= StatsIo =============
-
-/// Transparent I/O wrapper that tracks per-user statistics and activity.
-///
-/// Wraps the **client** side of the relay. Direction mapping:
-///
-/// | poll method  | direction | stats updated                        |
-/// |-------------|-----------|--------------------------------------|
-/// | `poll_read`  | C→S       | `octets_from`, `msgs_from`, counters |
-/// | `poll_write` | S→C       | `octets_to`, `msgs_to`, counters     |
-///
-/// Both update the shared activity timestamp for the watchdog.
-///
-/// Note on message counts: the original code counted one `read()`/`write_all()`
-/// as one "message". Here we count `poll_read`/`poll_write` completions instead.
-/// Byte counts are identical; op counts may differ slightly due to different
-/// internal buffering in `copy_bidirectional`. This is fine for monitoring.
-struct StatsIo<S> {
-    inner: S,
-    counters: Arc<SharedCounters>,
-    stats: Arc<Stats>,
-    user: String,
-    user_stats: Arc<UserStats>,
-    traffic_lease: Option<Arc<TrafficLease>>,
-    c2s_rate_debt_bytes: u64,
-    c2s_wait: RateWaitState,
-    s2c_wait: RateWaitState,
-    quota_wait: RateWaitState,
-    quota_limit: Option<u64>,
-    quota_exceeded: Arc<AtomicBool>,
-    quota_bytes_since_check: u64,
-    epoch: Instant,
-}
-
-#[derive(Default)]
-struct RateWaitState {
-    sleep: Option<Pin<Box<Sleep>>>,
-    started_at: Option<Instant>,
-    blocked_user: bool,
-    blocked_cidr: bool,
-}
-
-impl<S> StatsIo<S> {
-    #[cfg(test)]
-    fn new(
-        inner: S,
-        counters: Arc<SharedCounters>,
-        stats: Arc<Stats>,
-        user: String,
-        quota_limit: Option<u64>,
-        quota_exceeded: Arc<AtomicBool>,
-        epoch: Instant,
-    ) -> Self {
-        Self::new_with_traffic_lease(
-            inner,
-            counters,
-            stats,
-            user,
-            None,
-            quota_limit,
-            quota_exceeded,
-            epoch,
-        )
-    }
-
-    fn new_with_traffic_lease(
-        inner: S,
-        counters: Arc<SharedCounters>,
-        stats: Arc<Stats>,
-        user: String,
-        traffic_lease: Option<Arc<TrafficLease>>,
-        quota_limit: Option<u64>,
-        quota_exceeded: Arc<AtomicBool>,
-        epoch: Instant,
-    ) -> Self {
-        // Mark initial activity so the watchdog doesn't fire before data flows
-        counters.touch(Instant::now(), epoch);
-        let user_stats = stats.get_or_create_user_stats_handle(&user);
-        Self {
-            inner,
-            counters,
-            stats,
-            user,
-            user_stats,
-            traffic_lease,
-            c2s_rate_debt_bytes: 0,
-            c2s_wait: RateWaitState::default(),
-            s2c_wait: RateWaitState::default(),
-            quota_wait: RateWaitState::default(),
-            quota_limit,
-            quota_exceeded,
-            quota_bytes_since_check: 0,
-            epoch,
-        }
-    }
-
-    fn record_wait(
-        wait: &mut RateWaitState,
-        lease: Option<&Arc<TrafficLease>>,
-        direction: RateDirection,
-    ) {
-        let Some(started_at) = wait.started_at.take() else {
-            return;
-        };
-        let wait_ms = started_at.elapsed().as_millis().min(u128::from(u64::MAX)) as u64;
-        if let Some(lease) = lease {
-            lease.observe_wait_ms(direction, wait.blocked_user, wait.blocked_cidr, wait_ms);
-        }
-        wait.blocked_user = false;
-        wait.blocked_cidr = false;
-    }
-
-    fn arm_wait(wait: &mut RateWaitState, blocked_user: bool, blocked_cidr: bool) {
-        if wait.sleep.is_none() {
-            wait.sleep = Some(Box::pin(tokio::time::sleep(next_refill_delay())));
-            wait.started_at = Some(Instant::now());
-        }
-        wait.blocked_user |= blocked_user;
-        wait.blocked_cidr |= blocked_cidr;
-    }
-
-    fn poll_wait(
-        wait: &mut RateWaitState,
-        cx: &mut Context<'_>,
-        lease: Option<&Arc<TrafficLease>>,
-        direction: RateDirection,
-    ) -> Poll<()> {
-        let Some(sleep) = wait.sleep.as_mut() else {
-            return Poll::Ready(());
-        };
-        if sleep.as_mut().poll(cx).is_pending() {
-            return Poll::Pending;
-        }
-        wait.sleep = None;
-        Self::record_wait(wait, lease, direction);
-        Poll::Ready(())
-    }
-
-    fn settle_c2s_rate_debt(&mut self, cx: &mut Context<'_>) -> Poll<()> {
-        let Some(lease) = self.traffic_lease.as_ref() else {
-            self.c2s_rate_debt_bytes = 0;
-            return Poll::Ready(());
-        };
-
-        while self.c2s_rate_debt_bytes > 0 {
-            let consume = lease.try_consume(RateDirection::Up, self.c2s_rate_debt_bytes);
-            if consume.granted > 0 {
-                self.c2s_rate_debt_bytes = self.c2s_rate_debt_bytes.saturating_sub(consume.granted);
-                continue;
-            }
-            Self::arm_wait(
-                &mut self.c2s_wait,
-                consume.blocked_user,
-                consume.blocked_cidr,
-            );
-            if Self::poll_wait(&mut self.c2s_wait, cx, Some(lease), RateDirection::Up).is_pending()
-            {
-                return Poll::Pending;
-            }
-        }
-
-        if Self::poll_wait(&mut self.c2s_wait, cx, Some(lease), RateDirection::Up).is_pending() {
-            return Poll::Pending;
-        }
-
-        Poll::Ready(())
-    }
-
-    fn arm_quota_wait(&mut self, cx: &mut Context<'_>) -> Poll<()> {
-        Self::arm_wait(&mut self.quota_wait, false, false);
-        Self::poll_wait(&mut self.quota_wait, cx, None, RateDirection::Up)
-    }
-}
-
-#[derive(Debug)]
-struct QuotaIoSentinel;
-
-impl std::fmt::Display for QuotaIoSentinel {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.write_str("user data quota exceeded")
-    }
-}
-
-impl std::error::Error for QuotaIoSentinel {}
-
-fn quota_io_error() -> io::Error {
-    io::Error::new(io::ErrorKind::PermissionDenied, QuotaIoSentinel)
-}
-
-fn is_quota_io_error(err: &io::Error) -> bool {
-    err.kind() == io::ErrorKind::PermissionDenied
-        && err
-            .get_ref()
-            .and_then(|source| source.downcast_ref::<QuotaIoSentinel>())
-            .is_some()
-}
-
-const QUOTA_NEAR_LIMIT_BYTES: u64 = 64 * 1024;
-const QUOTA_LARGE_CHARGE_BYTES: u64 = 16 * 1024;
-const QUOTA_ADAPTIVE_INTERVAL_MIN_BYTES: u64 = 4 * 1024;
-const QUOTA_ADAPTIVE_INTERVAL_MAX_BYTES: u64 = 64 * 1024;
-const QUOTA_RESERVE_SPIN_RETRIES: usize = 64;
-const QUOTA_RESERVE_MAX_ROUNDS: usize = 8;
-
-#[inline]
-fn quota_adaptive_interval_bytes(remaining_before: u64) -> u64 {
-    remaining_before.saturating_div(2).clamp(
-        QUOTA_ADAPTIVE_INTERVAL_MIN_BYTES,
-        QUOTA_ADAPTIVE_INTERVAL_MAX_BYTES,
-    )
-}
-
-#[inline]
-fn should_immediate_quota_check(remaining_before: u64, charge_bytes: u64) -> bool {
-    remaining_before <= QUOTA_NEAR_LIMIT_BYTES || charge_bytes >= QUOTA_LARGE_CHARGE_BYTES
-}
-
-fn refund_reserved_quota_bytes(user_stats: &UserStats, reserved_bytes: u64) {
-    if reserved_bytes == 0 {
-        return;
-    }
-    let mut current = user_stats.quota_used.load(Ordering::Relaxed);
-    loop {
-        let next = current.saturating_sub(reserved_bytes);
-        match user_stats.quota_used.compare_exchange_weak(
-            current,
-            next,
-            Ordering::Relaxed,
-            Ordering::Relaxed,
-        ) {
-            Ok(_) => return,
-            Err(observed) => current = observed,
-        }
-    }
-}
-
-impl<S: AsyncRead + Unpin> AsyncRead for StatsIo<S> {
-    fn poll_read(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &mut ReadBuf<'_>,
-    ) -> Poll<io::Result<()>> {
-        let this = self.get_mut();
-        if this.quota_exceeded.load(Ordering::Acquire) {
-            return Poll::Ready(Err(quota_io_error()));
-        }
-        if this.settle_c2s_rate_debt(cx).is_pending() {
-            return Poll::Pending;
-        }
-        if buf.remaining() == 0 {
-            return Pin::new(&mut this.inner).poll_read(cx, buf);
-        }
-
-        let mut remaining_before = None;
-        let mut reserved_read_bytes = 0u64;
-        let mut read_limit = buf.remaining();
-        if let Some(limit) = this.quota_limit {
-            let used_before = this.user_stats.quota_used();
-            let remaining = limit.saturating_sub(used_before);
-            if remaining == 0 {
-                this.quota_exceeded.store(true, Ordering::Release);
-                return Poll::Ready(Err(quota_io_error()));
-            }
-            remaining_before = Some(remaining);
-            read_limit = read_limit.min(remaining as usize);
-            if read_limit == 0 {
-                this.quota_exceeded.store(true, Ordering::Release);
-                return Poll::Ready(Err(quota_io_error()));
-            }
-
-            let desired = read_limit as u64;
-            let mut reserve_rounds = 0usize;
-            while reserved_read_bytes == 0 {
-                for _ in 0..QUOTA_RESERVE_SPIN_RETRIES {
-                    match this.user_stats.quota_try_reserve(desired, limit) {
-                        Ok(_) => {
-                            reserved_read_bytes = desired;
-                            break;
-                        }
-                        Err(crate::stats::QuotaReserveError::LimitExceeded) => {
-                            this.quota_exceeded.store(true, Ordering::Release);
-                            return Poll::Ready(Err(quota_io_error()));
-                        }
-                        Err(crate::stats::QuotaReserveError::Contended) => {
-                            this.stats.increment_quota_contention_total();
-                        }
-                    }
-                }
-
-                if reserved_read_bytes == 0 {
-                    reserve_rounds = reserve_rounds.saturating_add(1);
-                    if reserve_rounds >= QUOTA_RESERVE_MAX_ROUNDS {
-                        this.stats.increment_quota_contention_timeout_total();
-                        if this.arm_quota_wait(cx).is_pending() {
-                            return Poll::Pending;
-                        }
-                        reserve_rounds = 0;
-                    }
-                }
-            }
-        }
-
-        let limited_read = read_limit < buf.remaining();
-        let read_result = if limited_read {
-            let mut limited_buf = ReadBuf::new(buf.initialize_unfilled_to(read_limit));
-            match Pin::new(&mut this.inner).poll_read(cx, &mut limited_buf) {
-                Poll::Ready(Ok(())) => {
-                    let n = limited_buf.filled().len();
-                    buf.advance(n);
-                    Poll::Ready(Ok(n))
-                }
-                Poll::Ready(Err(err)) => Poll::Ready(Err(err)),
-                Poll::Pending => Poll::Pending,
-            }
-        } else {
-            let before = buf.filled().len();
-            match Pin::new(&mut this.inner).poll_read(cx, buf) {
-                Poll::Ready(Ok(())) => {
-                    let n = buf.filled().len() - before;
-                    Poll::Ready(Ok(n))
-                }
-                Poll::Ready(Err(err)) => Poll::Ready(Err(err)),
-                Poll::Pending => Poll::Pending,
-            }
-        };
-
-        match read_result {
-            Poll::Ready(Ok(n)) => {
-                if reserved_read_bytes > n as u64 {
-                    let refund_bytes = reserved_read_bytes - n as u64;
-                    refund_reserved_quota_bytes(this.user_stats.as_ref(), refund_bytes);
-                    this.stats.add_quota_refund_bytes_total(refund_bytes);
-                }
-                if n > 0 {
-                    let n_to_charge = n as u64;
-
-                    if let Some(remaining) = remaining_before {
-                        if should_immediate_quota_check(remaining, n_to_charge) {
-                            this.quota_bytes_since_check = 0;
-                        } else {
-                            this.quota_bytes_since_check =
-                                this.quota_bytes_since_check.saturating_add(n_to_charge);
-                            let interval = quota_adaptive_interval_bytes(remaining);
-                            if this.quota_bytes_since_check >= interval {
-                                this.quota_bytes_since_check = 0;
-                            }
-                        }
-                    }
-                    if let Some(limit) = this.quota_limit
-                        && this.user_stats.quota_used() >= limit
-                    {
-                        this.quota_exceeded.store(true, Ordering::Release);
-                    }
-
-                    // C→S: client sent data
-                    this.counters
-                        .c2s_bytes
-                        .fetch_add(n_to_charge, Ordering::Relaxed);
-                    this.counters.c2s_ops.fetch_add(1, Ordering::Relaxed);
-                    this.counters.touch(Instant::now(), this.epoch);
-
-                    this.stats
-                        .add_user_traffic_from_handle(this.user_stats.as_ref(), n_to_charge);
-                    if this.traffic_lease.is_some() {
-                        this.c2s_rate_debt_bytes =
-                            this.c2s_rate_debt_bytes.saturating_add(n_to_charge);
-                        let _ = this.settle_c2s_rate_debt(cx);
-                    }
-
-                    trace!(user = %this.user, bytes = n, "C->S");
-                }
-                Poll::Ready(Ok(()))
-            }
-            Poll::Pending => {
-                if reserved_read_bytes > 0 {
-                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_read_bytes);
-                    this.stats.add_quota_refund_bytes_total(reserved_read_bytes);
-                }
-                Poll::Pending
-            }
-            Poll::Ready(Err(err)) => {
-                if reserved_read_bytes > 0 {
-                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_read_bytes);
-                    this.stats.add_quota_refund_bytes_total(reserved_read_bytes);
-                }
-                Poll::Ready(Err(err))
-            }
-        }
-    }
-}
-
-impl<S: AsyncWrite + Unpin> AsyncWrite for StatsIo<S> {
-    fn poll_write(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &[u8],
-    ) -> Poll<io::Result<usize>> {
-        let this = self.get_mut();
-        if this.quota_exceeded.load(Ordering::Acquire) {
-            return Poll::Ready(Err(quota_io_error()));
-        }
-
-        let mut shaper_reserved_bytes = 0u64;
-        let mut write_buf = buf;
-        if let Some(lease) = this.traffic_lease.as_ref() {
-            if !buf.is_empty() {
-                loop {
-                    let consume = lease.try_consume(RateDirection::Down, buf.len() as u64);
-                    if consume.granted > 0 {
-                        shaper_reserved_bytes = consume.granted;
-                        if consume.granted < buf.len() as u64 {
-                            write_buf = &buf[..consume.granted as usize];
-                        }
-                        let _ = Self::poll_wait(
-                            &mut this.s2c_wait,
-                            cx,
-                            Some(lease),
-                            RateDirection::Down,
-                        );
-                        break;
-                    }
-
-                    Self::arm_wait(
-                        &mut this.s2c_wait,
-                        consume.blocked_user,
-                        consume.blocked_cidr,
-                    );
-                    if Self::poll_wait(&mut this.s2c_wait, cx, Some(lease), RateDirection::Down)
-                        .is_pending()
-                    {
-                        return Poll::Pending;
-                    }
-                }
-            } else {
-                let _ = Self::poll_wait(&mut this.s2c_wait, cx, Some(lease), RateDirection::Down);
-            }
-        }
-
-        let mut remaining_before = None;
-        let mut reserved_bytes = 0u64;
-        if let Some(limit) = this.quota_limit {
-            if !write_buf.is_empty() {
-                let mut reserve_rounds = 0usize;
-                while reserved_bytes == 0 {
-                    let used_before = this.user_stats.quota_used();
-                    let remaining = limit.saturating_sub(used_before);
-                    if remaining == 0 {
-                        if let Some(lease) = this.traffic_lease.as_ref() {
-                            lease.refund(RateDirection::Down, shaper_reserved_bytes);
-                        }
-                        this.quota_exceeded.store(true, Ordering::Release);
-                        return Poll::Ready(Err(quota_io_error()));
-                    }
-                    remaining_before = Some(remaining);
-
-                    let desired = remaining.min(write_buf.len() as u64);
-                    let mut saw_contention = false;
-                    for _ in 0..QUOTA_RESERVE_SPIN_RETRIES {
-                        match this.user_stats.quota_try_reserve(desired, limit) {
-                            Ok(_) => {
-                                reserved_bytes = desired;
-                                write_buf = &write_buf[..desired as usize];
-                                break;
-                            }
-                            Err(crate::stats::QuotaReserveError::LimitExceeded) => {
-                                break;
-                            }
-                            Err(crate::stats::QuotaReserveError::Contended) => {
-                                this.stats.increment_quota_contention_total();
-                                saw_contention = true;
-                            }
-                        }
-                    }
-
-                    if reserved_bytes == 0 {
-                        reserve_rounds = reserve_rounds.saturating_add(1);
-                        if reserve_rounds >= QUOTA_RESERVE_MAX_ROUNDS {
-                            this.stats.increment_quota_contention_timeout_total();
-                            if let Some(lease) = this.traffic_lease.as_ref() {
-                                lease.refund(RateDirection::Down, shaper_reserved_bytes);
-                            }
-                            let _ = this.arm_quota_wait(cx);
-                            return Poll::Pending;
-                        } else if saw_contention {
-                            std::hint::spin_loop();
-                        }
-                    }
-                }
-            } else {
-                let used_before = this.user_stats.quota_used();
-                let remaining = limit.saturating_sub(used_before);
-                if remaining == 0 {
-                    if let Some(lease) = this.traffic_lease.as_ref() {
-                        lease.refund(RateDirection::Down, shaper_reserved_bytes);
-                    }
-                    this.quota_exceeded.store(true, Ordering::Release);
-                    return Poll::Ready(Err(quota_io_error()));
-                }
-                remaining_before = Some(remaining);
-            }
-        }
-
-        match Pin::new(&mut this.inner).poll_write(cx, write_buf) {
-            Poll::Ready(Ok(n)) => {
-                if reserved_bytes > n as u64 {
-                    let refund_bytes = reserved_bytes - n as u64;
-                    refund_reserved_quota_bytes(this.user_stats.as_ref(), refund_bytes);
-                    this.stats.add_quota_refund_bytes_total(refund_bytes);
-                }
-                if shaper_reserved_bytes > n as u64
-                    && let Some(lease) = this.traffic_lease.as_ref()
-                {
-                    lease.refund(RateDirection::Down, shaper_reserved_bytes - n as u64);
-                }
-                if n > 0 {
-                    if let Some(lease) = this.traffic_lease.as_ref() {
-                        Self::record_wait(&mut this.s2c_wait, Some(lease), RateDirection::Down);
-                    }
-                    let n_to_charge = n as u64;
-
-                    // S→C: data written to client
-                    this.counters
-                        .s2c_bytes
-                        .fetch_add(n_to_charge, Ordering::Relaxed);
-                    this.counters.s2c_ops.fetch_add(1, Ordering::Relaxed);
-                    this.counters.touch(Instant::now(), this.epoch);
-
-                    this.stats
-                        .add_user_traffic_to_handle(this.user_stats.as_ref(), n_to_charge);
-
-                    if let (Some(limit), Some(remaining)) = (this.quota_limit, remaining_before) {
-                        if should_immediate_quota_check(remaining, n_to_charge) {
-                            this.quota_bytes_since_check = 0;
-                            if this.user_stats.quota_used() >= limit {
-                                this.quota_exceeded.store(true, Ordering::Release);
-                            }
-                        } else {
-                            this.quota_bytes_since_check =
-                                this.quota_bytes_since_check.saturating_add(n_to_charge);
-                            let interval = quota_adaptive_interval_bytes(remaining);
-                            if this.quota_bytes_since_check >= interval {
-                                this.quota_bytes_since_check = 0;
-                                if this.user_stats.quota_used() >= limit {
-                                    this.quota_exceeded.store(true, Ordering::Release);
-                                }
-                            }
-                        }
-                    }
-
-                    trace!(user = %this.user, bytes = n, "S->C");
-                }
-                Poll::Ready(Ok(n))
-            }
-            Poll::Ready(Err(err)) => {
-                if reserved_bytes > 0 {
-                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_bytes);
-                    this.stats.add_quota_refund_bytes_total(reserved_bytes);
-                }
-                if shaper_reserved_bytes > 0
-                    && let Some(lease) = this.traffic_lease.as_ref()
-                {
-                    lease.refund(RateDirection::Down, shaper_reserved_bytes);
-                }
-                Poll::Ready(Err(err))
-            }
-            Poll::Pending => {
-                if reserved_bytes > 0 {
-                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_bytes);
-                    this.stats.add_quota_refund_bytes_total(reserved_bytes);
-                }
-                if shaper_reserved_bytes > 0
-                    && let Some(lease) = this.traffic_lease.as_ref()
-                {
-                    lease.refund(RateDirection::Down, shaper_reserved_bytes);
-                }
-                Poll::Pending
-            }
-        }
-    }
-
-    #[inline]
-    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.get_mut().inner).poll_flush(cx)
-    }
-
-    #[inline]
-    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.get_mut().inner).poll_shutdown(cx)
-    }
-}
+mod io;
 
+use self::io::{CombinedStream, SharedCounters, StatsIo, is_quota_io_error};
+#[cfg(test)]
+use self::io::{quota_adaptive_interval_bytes, should_immediate_quota_check};
 // ============= Relay =============
 
 /// Relay data bidirectionally between client and server.
@@ -883,6 +193,84 @@ pub async fn relay_bidirectional_with_activity_timeout_and_lease<CR, CW, SR, SW>
     traffic_lease: Option<Arc<TrafficLease>>,
     activity_timeout: Duration,
 ) -> Result<()>
+where
+    CR: AsyncRead + Unpin + Send + 'static,
+    CW: AsyncWrite + Unpin + Send + 'static,
+    SR: AsyncRead + Unpin + Send + 'static,
+    SW: AsyncWrite + Unpin + Send + 'static,
+{
+    relay_bidirectional_with_activity_timeout_lease_cancel_inner(
+        client_reader,
+        client_writer,
+        server_reader,
+        server_writer,
+        c2s_buf_size,
+        s2c_buf_size,
+        user,
+        stats,
+        quota_limit,
+        _buffer_pool,
+        traffic_lease,
+        activity_timeout,
+        None,
+    )
+    .await
+}
+
+pub async fn relay_bidirectional_with_activity_timeout_lease_and_cancel<CR, CW, SR, SW>(
+    client_reader: CR,
+    client_writer: CW,
+    server_reader: SR,
+    server_writer: SW,
+    c2s_buf_size: usize,
+    s2c_buf_size: usize,
+    user: &str,
+    stats: Arc<Stats>,
+    quota_limit: Option<u64>,
+    _buffer_pool: Arc<BufferPool>,
+    traffic_lease: Option<Arc<TrafficLease>>,
+    activity_timeout: Duration,
+    session_cancel: CancellationToken,
+) -> Result<()>
+where
+    CR: AsyncRead + Unpin + Send + 'static,
+    CW: AsyncWrite + Unpin + Send + 'static,
+    SR: AsyncRead + Unpin + Send + 'static,
+    SW: AsyncWrite + Unpin + Send + 'static,
+{
+    relay_bidirectional_with_activity_timeout_lease_cancel_inner(
+        client_reader,
+        client_writer,
+        server_reader,
+        server_writer,
+        c2s_buf_size,
+        s2c_buf_size,
+        user,
+        stats,
+        quota_limit,
+        _buffer_pool,
+        traffic_lease,
+        activity_timeout,
+        Some(session_cancel),
+    )
+    .await
+}
+
+async fn relay_bidirectional_with_activity_timeout_lease_cancel_inner<CR, CW, SR, SW>(
+    client_reader: CR,
+    client_writer: CW,
+    server_reader: SR,
+    server_writer: SW,
+    c2s_buf_size: usize,
+    s2c_buf_size: usize,
+    user: &str,
+    stats: Arc<Stats>,
+    quota_limit: Option<u64>,
+    _buffer_pool: Arc<BufferPool>,
+    traffic_lease: Option<Arc<TrafficLease>>,
+    activity_timeout: Duration,
+    session_cancel: Option<CancellationToken>,
+) -> Result<()>
 where
     CR: AsyncRead + Unpin + Send + 'static,
     CW: AsyncWrite + Unpin + Send + 'static,
@@ -979,14 +367,29 @@ where
     //
     // When the watchdog fires, select! drops the copy future,
     // releasing the &mut borrows on client and server.
-    let copy_result = tokio::select! {
+    enum RelayOutcome {
+        Copy(std::io::Result<(u64, u64)>),
+        ActivityTimeout,
+        UserDisabled,
+    }
+
+    let cancel_wait = async move {
+        match session_cancel {
+            Some(token) => token.cancelled().await,
+            None => pending::<()>().await,
+        }
+    };
+    tokio::pin!(cancel_wait);
+
+    let relay_outcome = tokio::select! {
         result = copy_bidirectional_with_sizes(
             &mut client,
             &mut server,
             c2s_buf_size.max(1),
             s2c_buf_size.max(1),
-        ) => Some(result),
-        _ = watchdog => None, // Activity timeout — cancel relay
+        ) => RelayOutcome::Copy(result),
+        _ = watchdog => RelayOutcome::ActivityTimeout,
+        _ = &mut cancel_wait => RelayOutcome::UserDisabled,
     };
 
     // ── Clean shutdown ──────────────────────────────────────────────
@@ -1000,8 +403,8 @@ where
     let s2c_ops = counters.s2c_ops.load(Ordering::Relaxed);
     let duration = epoch.elapsed();
 
-    match copy_result {
-        Some(Ok((c2s, s2c))) => {
+    match relay_outcome {
+        RelayOutcome::Copy(Ok((c2s, s2c))) => {
             // Normal completion — one side closed the connection
             debug!(
                 user = %user_owned,
@@ -1014,7 +417,7 @@ where
             );
             Ok(())
         }
-        Some(Err(e)) if is_quota_io_error(&e) => {
+        RelayOutcome::Copy(Err(e)) if is_quota_io_error(&e) => {
             let c2s = counters.c2s_bytes.load(Ordering::Relaxed);
             let s2c = counters.s2c_bytes.load(Ordering::Relaxed);
             warn!(
@@ -1030,7 +433,7 @@ where
                 user: user_owned.clone(),
             })
         }
-        Some(Err(e)) => {
+        RelayOutcome::Copy(Err(e)) => {
             // I/O error in one of the directions
             let c2s = counters.c2s_bytes.load(Ordering::Relaxed);
             let s2c = counters.s2c_bytes.load(Ordering::Relaxed);
@@ -1046,7 +449,7 @@ where
             );
             Err(e.into())
         }
-        None => {
+        RelayOutcome::ActivityTimeout => {
             // Activity timeout (watchdog fired)
             let c2s = counters.c2s_bytes.load(Ordering::Relaxed);
             let s2c = counters.s2c_bytes.load(Ordering::Relaxed);
@@ -1061,6 +464,22 @@ where
             );
             Ok(())
         }
+        RelayOutcome::UserDisabled => {
+            let c2s = counters.c2s_bytes.load(Ordering::Relaxed);
+            let s2c = counters.s2c_bytes.load(Ordering::Relaxed);
+            debug!(
+                user = %user_owned,
+                c2s_bytes = c2s,
+                s2c_bytes = s2c,
+                c2s_msgs = c2s_ops,
+                s2c_msgs = s2c_ops,
+                duration_secs = duration.as_secs(),
+                "Relay finished (user disabled)"
+            );
+            Err(ProxyError::UserDisabled {
+                user: user_owned.clone(),
+            })
+        }
     }
 }
 

src/proxy/relay/io.rs

@@ -0,0 +1,551 @@
+use crate::proxy::traffic_limiter::{RateDirection, TrafficLease, next_refill_delay};
+use crate::stats::{Stats, UserStats};
+use std::io;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::task::{Context, Poll};
+use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
+use tokio::time::{Instant, Sleep};
+use tracing::trace;
+
+mod combined;
+mod counters;
+mod quota;
+
+pub(super) use self::combined::CombinedStream;
+pub(super) use self::counters::SharedCounters;
+pub(super) use self::quota::is_quota_io_error;
+use self::quota::{
+    QUOTA_RESERVE_MAX_ROUNDS, QUOTA_RESERVE_SPIN_RETRIES, quota_io_error,
+    refund_reserved_quota_bytes,
+};
+pub(super) use self::quota::{quota_adaptive_interval_bytes, should_immediate_quota_check};
+
+/// Transparent I/O wrapper that tracks per-user statistics and activity.
+///
+/// Wraps the **client** side of the relay. Direction mapping:
+///
+/// | poll method  | direction | stats updated                        |
+/// |-------------|-----------|--------------------------------------|
+/// | `poll_read`  | C→S       | `octets_from`, `msgs_from`, counters |
+/// | `poll_write` | S→C       | `octets_to`, `msgs_to`, counters     |
+///
+/// Both update the shared activity timestamp for the watchdog.
+///
+/// Note on message counts: the original code counted one `read()`/`write_all()`
+/// as one "message". Here we count `poll_read`/`poll_write` completions instead.
+/// Byte counts are identical; op counts may differ slightly due to different
+/// internal buffering in `copy_bidirectional`. This is fine for monitoring.
+pub(super) struct StatsIo<S> {
+    inner: S,
+    counters: Arc<SharedCounters>,
+    stats: Arc<Stats>,
+    user: String,
+    user_stats: Arc<UserStats>,
+    traffic_lease: Option<Arc<TrafficLease>>,
+    c2s_rate_debt_bytes: u64,
+    c2s_wait: RateWaitState,
+    s2c_wait: RateWaitState,
+    quota_wait: RateWaitState,
+    quota_limit: Option<u64>,
+    quota_exceeded: Arc<AtomicBool>,
+    pub(super) quota_bytes_since_check: u64,
+    epoch: Instant,
+}
+
+#[derive(Default)]
+struct RateWaitState {
+    sleep: Option<Pin<Box<Sleep>>>,
+    started_at: Option<Instant>,
+    blocked_user: bool,
+    blocked_cidr: bool,
+}
+
+impl<S> StatsIo<S> {
+    /// Creates a StatsIo wrapper without a traffic lease for relay unit tests.
+    #[cfg(test)]
+    pub(super) fn new(
+        inner: S,
+        counters: Arc<SharedCounters>,
+        stats: Arc<Stats>,
+        user: String,
+        quota_limit: Option<u64>,
+        quota_exceeded: Arc<AtomicBool>,
+        epoch: Instant,
+    ) -> Self {
+        Self::new_with_traffic_lease(
+            inner,
+            counters,
+            stats,
+            user,
+            None,
+            quota_limit,
+            quota_exceeded,
+            epoch,
+        )
+    }
+
+    pub(super) fn new_with_traffic_lease(
+        inner: S,
+        counters: Arc<SharedCounters>,
+        stats: Arc<Stats>,
+        user: String,
+        traffic_lease: Option<Arc<TrafficLease>>,
+        quota_limit: Option<u64>,
+        quota_exceeded: Arc<AtomicBool>,
+        epoch: Instant,
+    ) -> Self {
+        // Mark initial activity so the watchdog doesn't fire before data flows
+        counters.touch(Instant::now(), epoch);
+        let user_stats = stats.get_or_create_user_stats_handle(&user);
+        Self {
+            inner,
+            counters,
+            stats,
+            user,
+            user_stats,
+            traffic_lease,
+            c2s_rate_debt_bytes: 0,
+            c2s_wait: RateWaitState::default(),
+            s2c_wait: RateWaitState::default(),
+            quota_wait: RateWaitState::default(),
+            quota_limit,
+            quota_exceeded,
+            quota_bytes_since_check: 0,
+            epoch,
+        }
+    }
+
+    fn record_wait(
+        wait: &mut RateWaitState,
+        lease: Option<&Arc<TrafficLease>>,
+        direction: RateDirection,
+    ) {
+        let Some(started_at) = wait.started_at.take() else {
+            return;
+        };
+        let wait_ms = started_at.elapsed().as_millis().min(u128::from(u64::MAX)) as u64;
+        if let Some(lease) = lease {
+            lease.observe_wait_ms(direction, wait.blocked_user, wait.blocked_cidr, wait_ms);
+        }
+        wait.blocked_user = false;
+        wait.blocked_cidr = false;
+    }
+
+    fn arm_wait(wait: &mut RateWaitState, blocked_user: bool, blocked_cidr: bool) {
+        if wait.sleep.is_none() {
+            wait.sleep = Some(Box::pin(tokio::time::sleep(next_refill_delay())));
+            wait.started_at = Some(Instant::now());
+        }
+        wait.blocked_user |= blocked_user;
+        wait.blocked_cidr |= blocked_cidr;
+    }
+
+    fn poll_wait(
+        wait: &mut RateWaitState,
+        cx: &mut Context<'_>,
+        lease: Option<&Arc<TrafficLease>>,
+        direction: RateDirection,
+    ) -> Poll<()> {
+        let Some(sleep) = wait.sleep.as_mut() else {
+            return Poll::Ready(());
+        };
+        if sleep.as_mut().poll(cx).is_pending() {
+            return Poll::Pending;
+        }
+        wait.sleep = None;
+        Self::record_wait(wait, lease, direction);
+        Poll::Ready(())
+    }
+
+    fn settle_c2s_rate_debt(&mut self, cx: &mut Context<'_>) -> Poll<()> {
+        let Some(lease) = self.traffic_lease.as_ref() else {
+            self.c2s_rate_debt_bytes = 0;
+            return Poll::Ready(());
+        };
+
+        while self.c2s_rate_debt_bytes > 0 {
+            let consume = lease.try_consume(RateDirection::Up, self.c2s_rate_debt_bytes);
+            if consume.granted > 0 {
+                self.c2s_rate_debt_bytes = self.c2s_rate_debt_bytes.saturating_sub(consume.granted);
+                continue;
+            }
+            Self::arm_wait(
+                &mut self.c2s_wait,
+                consume.blocked_user,
+                consume.blocked_cidr,
+            );
+            if Self::poll_wait(&mut self.c2s_wait, cx, Some(lease), RateDirection::Up).is_pending()
+            {
+                return Poll::Pending;
+            }
+        }
+
+        if Self::poll_wait(&mut self.c2s_wait, cx, Some(lease), RateDirection::Up).is_pending() {
+            return Poll::Pending;
+        }
+
+        Poll::Ready(())
+    }
+
+    fn arm_quota_wait(&mut self, cx: &mut Context<'_>) -> Poll<()> {
+        Self::arm_wait(&mut self.quota_wait, false, false);
+        Self::poll_wait(&mut self.quota_wait, cx, None, RateDirection::Up)
+    }
+}
+
+impl<S: AsyncRead + Unpin> AsyncRead for StatsIo<S> {
+    fn poll_read(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &mut ReadBuf<'_>,
+    ) -> Poll<io::Result<()>> {
+        let this = self.get_mut();
+        if this.quota_exceeded.load(Ordering::Acquire) {
+            return Poll::Ready(Err(quota_io_error()));
+        }
+        if this.settle_c2s_rate_debt(cx).is_pending() {
+            return Poll::Pending;
+        }
+        if buf.remaining() == 0 {
+            return Pin::new(&mut this.inner).poll_read(cx, buf);
+        }
+
+        let mut remaining_before = None;
+        let mut reserved_read_bytes = 0u64;
+        let mut read_limit = buf.remaining();
+        if let Some(limit) = this.quota_limit {
+            let used_before = this.user_stats.quota_used();
+            let remaining = limit.saturating_sub(used_before);
+            if remaining == 0 {
+                this.quota_exceeded.store(true, Ordering::Release);
+                return Poll::Ready(Err(quota_io_error()));
+            }
+            remaining_before = Some(remaining);
+            read_limit = read_limit.min(remaining as usize);
+            if read_limit == 0 {
+                this.quota_exceeded.store(true, Ordering::Release);
+                return Poll::Ready(Err(quota_io_error()));
+            }
+
+            let desired = read_limit as u64;
+            let mut reserve_rounds = 0usize;
+            while reserved_read_bytes == 0 {
+                for _ in 0..QUOTA_RESERVE_SPIN_RETRIES {
+                    match this.user_stats.quota_try_reserve(desired, limit) {
+                        Ok(_) => {
+                            reserved_read_bytes = desired;
+                            break;
+                        }
+                        Err(crate::stats::QuotaReserveError::LimitExceeded) => {
+                            this.quota_exceeded.store(true, Ordering::Release);
+                            return Poll::Ready(Err(quota_io_error()));
+                        }
+                        Err(crate::stats::QuotaReserveError::Contended) => {
+                            this.stats.increment_quota_contention_total();
+                        }
+                    }
+                }
+
+                if reserved_read_bytes == 0 {
+                    reserve_rounds = reserve_rounds.saturating_add(1);
+                    if reserve_rounds >= QUOTA_RESERVE_MAX_ROUNDS {
+                        this.stats.increment_quota_contention_timeout_total();
+                        if this.arm_quota_wait(cx).is_pending() {
+                            return Poll::Pending;
+                        }
+                        reserve_rounds = 0;
+                    }
+                }
+            }
+        }
+
+        let limited_read = read_limit < buf.remaining();
+        let read_result = if limited_read {
+            let mut limited_buf = ReadBuf::new(buf.initialize_unfilled_to(read_limit));
+            match Pin::new(&mut this.inner).poll_read(cx, &mut limited_buf) {
+                Poll::Ready(Ok(())) => {
+                    let n = limited_buf.filled().len();
+                    buf.advance(n);
+                    Poll::Ready(Ok(n))
+                }
+                Poll::Ready(Err(err)) => Poll::Ready(Err(err)),
+                Poll::Pending => Poll::Pending,
+            }
+        } else {
+            let before = buf.filled().len();
+            match Pin::new(&mut this.inner).poll_read(cx, buf) {
+                Poll::Ready(Ok(())) => {
+                    let n = buf.filled().len() - before;
+                    Poll::Ready(Ok(n))
+                }
+                Poll::Ready(Err(err)) => Poll::Ready(Err(err)),
+                Poll::Pending => Poll::Pending,
+            }
+        };
+
+        match read_result {
+            Poll::Ready(Ok(n)) => {
+                if reserved_read_bytes > n as u64 {
+                    let refund_bytes = reserved_read_bytes - n as u64;
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), refund_bytes);
+                    this.stats.add_quota_refund_bytes_total(refund_bytes);
+                }
+                if n > 0 {
+                    let n_to_charge = n as u64;
+
+                    if let Some(remaining) = remaining_before {
+                        if should_immediate_quota_check(remaining, n_to_charge) {
+                            this.quota_bytes_since_check = 0;
+                        } else {
+                            this.quota_bytes_since_check =
+                                this.quota_bytes_since_check.saturating_add(n_to_charge);
+                            let interval = quota_adaptive_interval_bytes(remaining);
+                            if this.quota_bytes_since_check >= interval {
+                                this.quota_bytes_since_check = 0;
+                            }
+                        }
+                    }
+                    if let Some(limit) = this.quota_limit
+                        && this.user_stats.quota_used() >= limit
+                    {
+                        this.quota_exceeded.store(true, Ordering::Release);
+                    }
+
+                    // C→S: client sent data
+                    this.counters
+                        .c2s_bytes
+                        .fetch_add(n_to_charge, Ordering::Relaxed);
+                    this.counters.c2s_ops.fetch_add(1, Ordering::Relaxed);
+                    this.counters.touch(Instant::now(), this.epoch);
+
+                    this.stats
+                        .add_user_traffic_from_handle(this.user_stats.as_ref(), n_to_charge);
+                    if this.traffic_lease.is_some() {
+                        this.c2s_rate_debt_bytes =
+                            this.c2s_rate_debt_bytes.saturating_add(n_to_charge);
+                        let _ = this.settle_c2s_rate_debt(cx);
+                    }
+
+                    trace!(user = %this.user, bytes = n, "C->S");
+                }
+                Poll::Ready(Ok(()))
+            }
+            Poll::Pending => {
+                if reserved_read_bytes > 0 {
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_read_bytes);
+                    this.stats.add_quota_refund_bytes_total(reserved_read_bytes);
+                }
+                Poll::Pending
+            }
+            Poll::Ready(Err(err)) => {
+                if reserved_read_bytes > 0 {
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_read_bytes);
+                    this.stats.add_quota_refund_bytes_total(reserved_read_bytes);
+                }
+                Poll::Ready(Err(err))
+            }
+        }
+    }
+}
+
+impl<S: AsyncWrite + Unpin> AsyncWrite for StatsIo<S> {
+    fn poll_write(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &[u8],
+    ) -> Poll<io::Result<usize>> {
+        let this = self.get_mut();
+        if this.quota_exceeded.load(Ordering::Acquire) {
+            return Poll::Ready(Err(quota_io_error()));
+        }
+
+        let mut shaper_reserved_bytes = 0u64;
+        let mut write_buf = buf;
+        if let Some(lease) = this.traffic_lease.as_ref() {
+            if !buf.is_empty() {
+                loop {
+                    let consume = lease.try_consume(RateDirection::Down, buf.len() as u64);
+                    if consume.granted > 0 {
+                        shaper_reserved_bytes = consume.granted;
+                        if consume.granted < buf.len() as u64 {
+                            write_buf = &buf[..consume.granted as usize];
+                        }
+                        let _ = Self::poll_wait(
+                            &mut this.s2c_wait,
+                            cx,
+                            Some(lease),
+                            RateDirection::Down,
+                        );
+                        break;
+                    }
+
+                    Self::arm_wait(
+                        &mut this.s2c_wait,
+                        consume.blocked_user,
+                        consume.blocked_cidr,
+                    );
+                    if Self::poll_wait(&mut this.s2c_wait, cx, Some(lease), RateDirection::Down)
+                        .is_pending()
+                    {
+                        return Poll::Pending;
+                    }
+                }
+            } else {
+                let _ = Self::poll_wait(&mut this.s2c_wait, cx, Some(lease), RateDirection::Down);
+            }
+        }
+
+        let mut remaining_before = None;
+        let mut reserved_bytes = 0u64;
+        if let Some(limit) = this.quota_limit {
+            if !write_buf.is_empty() {
+                let mut reserve_rounds = 0usize;
+                while reserved_bytes == 0 {
+                    let used_before = this.user_stats.quota_used();
+                    let remaining = limit.saturating_sub(used_before);
+                    if remaining == 0 {
+                        if let Some(lease) = this.traffic_lease.as_ref() {
+                            lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                        }
+                        this.quota_exceeded.store(true, Ordering::Release);
+                        return Poll::Ready(Err(quota_io_error()));
+                    }
+                    remaining_before = Some(remaining);
+
+                    let desired = remaining.min(write_buf.len() as u64);
+                    let mut saw_contention = false;
+                    for _ in 0..QUOTA_RESERVE_SPIN_RETRIES {
+                        match this.user_stats.quota_try_reserve(desired, limit) {
+                            Ok(_) => {
+                                reserved_bytes = desired;
+                                write_buf = &write_buf[..desired as usize];
+                                break;
+                            }
+                            Err(crate::stats::QuotaReserveError::LimitExceeded) => {
+                                break;
+                            }
+                            Err(crate::stats::QuotaReserveError::Contended) => {
+                                this.stats.increment_quota_contention_total();
+                                saw_contention = true;
+                            }
+                        }
+                    }
+
+                    if reserved_bytes == 0 {
+                        reserve_rounds = reserve_rounds.saturating_add(1);
+                        if reserve_rounds >= QUOTA_RESERVE_MAX_ROUNDS {
+                            this.stats.increment_quota_contention_timeout_total();
+                            if let Some(lease) = this.traffic_lease.as_ref() {
+                                lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                            }
+                            let _ = this.arm_quota_wait(cx);
+                            return Poll::Pending;
+                        } else if saw_contention {
+                            std::hint::spin_loop();
+                        }
+                    }
+                }
+            } else {
+                let used_before = this.user_stats.quota_used();
+                let remaining = limit.saturating_sub(used_before);
+                if remaining == 0 {
+                    if let Some(lease) = this.traffic_lease.as_ref() {
+                        lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                    }
+                    this.quota_exceeded.store(true, Ordering::Release);
+                    return Poll::Ready(Err(quota_io_error()));
+                }
+                remaining_before = Some(remaining);
+            }
+        }
+
+        match Pin::new(&mut this.inner).poll_write(cx, write_buf) {
+            Poll::Ready(Ok(n)) => {
+                if reserved_bytes > n as u64 {
+                    let refund_bytes = reserved_bytes - n as u64;
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), refund_bytes);
+                    this.stats.add_quota_refund_bytes_total(refund_bytes);
+                }
+                if shaper_reserved_bytes > n as u64
+                    && let Some(lease) = this.traffic_lease.as_ref()
+                {
+                    lease.refund(RateDirection::Down, shaper_reserved_bytes - n as u64);
+                }
+                if n > 0 {
+                    if let Some(lease) = this.traffic_lease.as_ref() {
+                        Self::record_wait(&mut this.s2c_wait, Some(lease), RateDirection::Down);
+                    }
+                    let n_to_charge = n as u64;
+
+                    // S→C: data written to client
+                    this.counters
+                        .s2c_bytes
+                        .fetch_add(n_to_charge, Ordering::Relaxed);
+                    this.counters.s2c_ops.fetch_add(1, Ordering::Relaxed);
+                    this.counters.touch(Instant::now(), this.epoch);
+
+                    this.stats
+                        .add_user_traffic_to_handle(this.user_stats.as_ref(), n_to_charge);
+
+                    if let (Some(limit), Some(remaining)) = (this.quota_limit, remaining_before) {
+                        if should_immediate_quota_check(remaining, n_to_charge) {
+                            this.quota_bytes_since_check = 0;
+                            if this.user_stats.quota_used() >= limit {
+                                this.quota_exceeded.store(true, Ordering::Release);
+                            }
+                        } else {
+                            this.quota_bytes_since_check =
+                                this.quota_bytes_since_check.saturating_add(n_to_charge);
+                            let interval = quota_adaptive_interval_bytes(remaining);
+                            if this.quota_bytes_since_check >= interval {
+                                this.quota_bytes_since_check = 0;
+                                if this.user_stats.quota_used() >= limit {
+                                    this.quota_exceeded.store(true, Ordering::Release);
+                                }
+                            }
+                        }
+                    }
+
+                    trace!(user = %this.user, bytes = n, "S->C");
+                }
+                Poll::Ready(Ok(n))
+            }
+            Poll::Ready(Err(err)) => {
+                if reserved_bytes > 0 {
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_bytes);
+                    this.stats.add_quota_refund_bytes_total(reserved_bytes);
+                }
+                if shaper_reserved_bytes > 0
+                    && let Some(lease) = this.traffic_lease.as_ref()
+                {
+                    lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                }
+                Poll::Ready(Err(err))
+            }
+            Poll::Pending => {
+                if reserved_bytes > 0 {
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_bytes);
+                    this.stats.add_quota_refund_bytes_total(reserved_bytes);
+                }
+                if shaper_reserved_bytes > 0
+                    && let Some(lease) = this.traffic_lease.as_ref()
+                {
+                    lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                }
+                Poll::Pending
+            }
+        }
+    }
+
+    #[inline]
+    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
+        Pin::new(&mut self.get_mut().inner).poll_flush(cx)
+    }
+
+    #[inline]
+    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
+        Pin::new(&mut self.get_mut().inner).poll_shutdown(cx)
+    }
+}

src/proxy/relay/io/combined.rs

@@ -0,0 +1,61 @@
+use std::io;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+
+use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
+
+// ============= CombinedStream =============
+
+/// Combines separate read and write halves into a single bidirectional stream.
+///
+/// `copy_bidirectional` requires `AsyncRead + AsyncWrite` on each side,
+/// but the handshake layer produces split reader/writer pairs
+/// (e.g. `CryptoReader<FakeTlsReader<OwnedReadHalf>>` + `CryptoWriter<...>`).
+///
+/// This wrapper reunifies them with zero overhead — each trait method
+/// delegates directly to the corresponding half. No buffering, no copies.
+///
+/// Safety: `poll_read` only touches `reader`, `poll_write` only touches `writer`,
+/// so there's no aliasing even though both are called on the same `&mut self`.
+pub(in crate::proxy::relay) struct CombinedStream<R, W> {
+    reader: R,
+    writer: W,
+}
+
+impl<R, W> CombinedStream<R, W> {
+    pub(in crate::proxy::relay) fn new(reader: R, writer: W) -> Self {
+        Self { reader, writer }
+    }
+}
+
+impl<R: AsyncRead + Unpin, W: Unpin> AsyncRead for CombinedStream<R, W> {
+    #[inline]
+    fn poll_read(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &mut ReadBuf<'_>,
+    ) -> Poll<io::Result<()>> {
+        Pin::new(&mut self.get_mut().reader).poll_read(cx, buf)
+    }
+}
+
+impl<R: Unpin, W: AsyncWrite + Unpin> AsyncWrite for CombinedStream<R, W> {
+    #[inline]
+    fn poll_write(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &[u8],
+    ) -> Poll<io::Result<usize>> {
+        Pin::new(&mut self.get_mut().writer).poll_write(cx, buf)
+    }
+
+    #[inline]
+    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
+        Pin::new(&mut self.get_mut().writer).poll_flush(cx)
+    }
+
+    #[inline]
+    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
+        Pin::new(&mut self.get_mut().writer).poll_shutdown(cx)
+    }
+}

src/proxy/relay/io/counters.rs

@@ -0,0 +1,51 @@
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::Duration;
+
+use tokio::time::Instant;
+
+// ============= SharedCounters =============
+
+/// Atomic counters shared between the relay (via StatsIo) and the watchdog task.
+///
+/// Using `Relaxed` ordering is sufficient because:
+/// - Counters are monotonically increasing (no ABA problem)
+/// - Slight staleness in watchdog reads is harmless (±10s check interval anyway)
+/// - No ordering dependencies between different counters
+pub(in crate::proxy::relay) struct SharedCounters {
+    /// Bytes read from client (C→S direction)
+    pub(in crate::proxy::relay) c2s_bytes: AtomicU64,
+    /// Bytes written to client (S→C direction)
+    pub(in crate::proxy::relay) s2c_bytes: AtomicU64,
+    /// Number of poll_read completions (≈ C→S chunks)
+    pub(in crate::proxy::relay) c2s_ops: AtomicU64,
+    /// Number of poll_write completions (≈ S→C chunks)
+    pub(in crate::proxy::relay) s2c_ops: AtomicU64,
+    /// Milliseconds since relay epoch of last I/O activity
+    last_activity_ms: AtomicU64,
+}
+
+impl SharedCounters {
+    pub(in crate::proxy::relay) fn new() -> Self {
+        Self {
+            c2s_bytes: AtomicU64::new(0),
+            s2c_bytes: AtomicU64::new(0),
+            c2s_ops: AtomicU64::new(0),
+            s2c_ops: AtomicU64::new(0),
+            last_activity_ms: AtomicU64::new(0),
+        }
+    }
+
+    /// Record activity at this instant.
+    #[inline]
+    pub(in crate::proxy::relay) fn touch(&self, now: Instant, epoch: Instant) {
+        let ms = now.duration_since(epoch).as_millis() as u64;
+        self.last_activity_ms.store(ms, Ordering::Relaxed);
+    }
+
+    /// How long since last recorded activity.
+    pub(in crate::proxy::relay) fn idle_duration(&self, now: Instant, epoch: Instant) -> Duration {
+        let last_ms = self.last_activity_ms.load(Ordering::Relaxed);
+        let now_ms = now.duration_since(epoch).as_millis() as u64;
+        Duration::from_millis(now_ms.saturating_sub(last_ms))
+    }
+}

src/proxy/relay/io/quota.rs

@@ -0,0 +1,68 @@
+use crate::stats::UserStats;
+use std::io;
+use std::sync::atomic::Ordering;
+
+#[derive(Debug)]
+struct QuotaIoSentinel;
+
+impl std::fmt::Display for QuotaIoSentinel {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str("user data quota exceeded")
+    }
+}
+
+impl std::error::Error for QuotaIoSentinel {}
+
+pub(super) fn quota_io_error() -> io::Error {
+    io::Error::new(io::ErrorKind::PermissionDenied, QuotaIoSentinel)
+}
+
+pub(in crate::proxy::relay) fn is_quota_io_error(err: &io::Error) -> bool {
+    err.kind() == io::ErrorKind::PermissionDenied
+        && err
+            .get_ref()
+            .and_then(|source| source.downcast_ref::<QuotaIoSentinel>())
+            .is_some()
+}
+
+const QUOTA_NEAR_LIMIT_BYTES: u64 = 64 * 1024;
+const QUOTA_LARGE_CHARGE_BYTES: u64 = 16 * 1024;
+const QUOTA_ADAPTIVE_INTERVAL_MIN_BYTES: u64 = 4 * 1024;
+const QUOTA_ADAPTIVE_INTERVAL_MAX_BYTES: u64 = 64 * 1024;
+pub(super) const QUOTA_RESERVE_SPIN_RETRIES: usize = 64;
+pub(super) const QUOTA_RESERVE_MAX_ROUNDS: usize = 8;
+
+#[inline]
+pub(in crate::proxy::relay) fn quota_adaptive_interval_bytes(remaining_before: u64) -> u64 {
+    remaining_before.saturating_div(2).clamp(
+        QUOTA_ADAPTIVE_INTERVAL_MIN_BYTES,
+        QUOTA_ADAPTIVE_INTERVAL_MAX_BYTES,
+    )
+}
+
+#[inline]
+pub(in crate::proxy::relay) fn should_immediate_quota_check(
+    remaining_before: u64,
+    charge_bytes: u64,
+) -> bool {
+    remaining_before <= QUOTA_NEAR_LIMIT_BYTES || charge_bytes >= QUOTA_LARGE_CHARGE_BYTES
+}
+
+pub(super) fn refund_reserved_quota_bytes(user_stats: &UserStats, reserved_bytes: u64) {
+    if reserved_bytes == 0 {
+        return;
+    }
+    let mut current = user_stats.quota_used.load(Ordering::Relaxed);
+    loop {
+        let next = current.saturating_sub(reserved_bytes);
+        match user_stats.quota_used.compare_exchange_weak(
+            current,
+            next,
+            Ordering::Relaxed,
+            Ordering::Relaxed,
+        ) {
+            Ok(_) => return,
+            Err(observed) => current = observed,
+        }
+    }
+}

src/proxy/shared_state.rs

@@ -1,5 +1,5 @@
-use std::collections::HashSet;
 use std::collections::hash_map::RandomState;
+use std::collections::{HashMap, HashSet};
 use std::net::{IpAddr, SocketAddr};
 use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, Ordering};
 use std::sync::{Arc, Mutex};
@@ -7,6 +7,7 @@ use std::time::Instant;
 
 use dashmap::DashMap;
 use tokio::sync::mpsc;
+use tokio_util::sync::CancellationToken;
 
 use crate::proxy::handshake::{AuthProbeSaturationState, AuthProbeState};
 use crate::proxy::middle_relay::{DesyncDedupRotationState, RelayIdleCandidateRegistry};
@@ -59,7 +60,7 @@ pub(crate) struct MiddleRelaySharedState {
     pub(crate) desync_hasher: RandomState,
     pub(crate) desync_full_cache_last_emit_at: Mutex<Option<Instant>>,
     pub(crate) desync_dedup_rotation_state: Mutex<DesyncDedupRotationState>,
-    pub(crate) relay_idle_registry: Mutex<RelayIdleCandidateRegistry>,
+    pub(crate) relay_idle_registry: RelayIdleCandidateRegistry,
     pub(crate) relay_idle_mark_seq: AtomicU64,
 }
 
@@ -67,10 +68,35 @@ pub(crate) struct ProxySharedState {
     pub(crate) handshake: HandshakeSharedState,
     pub(crate) middle_relay: MiddleRelaySharedState,
     pub(crate) traffic_limiter: Arc<TrafficLimiter>,
+    disabled_users: DashMap<String, ()>,
+    active_user_sessions: DashMap<(String, u64), CancellationToken>,
     pub(crate) conntrack_pressure_active: AtomicBool,
     pub(crate) conntrack_close_tx: Mutex<Option<mpsc::Sender<ConntrackCloseEvent>>>,
 }
 
+#[must_use = "registered user sessions must be kept alive until relay completion"]
+pub(crate) struct UserSessionRegistration {
+    token: CancellationToken,
+    _guard: UserSessionGuard,
+}
+
+impl UserSessionRegistration {
+    pub(crate) fn token(&self) -> CancellationToken {
+        self.token.clone()
+    }
+}
+
+struct UserSessionGuard {
+    shared: Arc<ProxySharedState>,
+    key: (String, u64),
+}
+
+impl Drop for UserSessionGuard {
+    fn drop(&mut self) {
+        self.shared.active_user_sessions.remove(&self.key);
+    }
+}
+
 impl ProxySharedState {
     pub(crate) fn new() -> Arc<Self> {
         Arc::new(Self {
@@ -97,15 +123,86 @@ impl ProxySharedState {
                 desync_hasher: RandomState::new(),
                 desync_full_cache_last_emit_at: Mutex::new(None),
                 desync_dedup_rotation_state: Mutex::new(DesyncDedupRotationState::default()),
-                relay_idle_registry: Mutex::new(RelayIdleCandidateRegistry::default()),
+                relay_idle_registry: RelayIdleCandidateRegistry::default(),
                 relay_idle_mark_seq: AtomicU64::new(0),
             },
             traffic_limiter: TrafficLimiter::new(),
+            disabled_users: DashMap::new(),
+            active_user_sessions: DashMap::new(),
             conntrack_pressure_active: AtomicBool::new(false),
             conntrack_close_tx: Mutex::new(None),
         })
     }
 
+    pub(crate) fn is_user_enabled(&self, user: &str) -> bool {
+        !self.disabled_users.contains_key(user)
+    }
+
+    pub(crate) fn set_user_enabled(&self, user: &str, enabled: bool) -> bool {
+        if enabled {
+            self.disabled_users.remove(user);
+            false
+        } else {
+            self.disabled_users.insert(user.to_string(), ()).is_none()
+        }
+    }
+
+    pub(crate) fn apply_user_enabled_config(
+        &self,
+        user_enabled: &HashMap<String, bool>,
+    ) -> Vec<String> {
+        let desired_disabled = user_enabled
+            .iter()
+            .filter_map(|(user, enabled)| (!*enabled).then_some(user.clone()))
+            .collect::<HashSet<_>>();
+        let current_disabled = self
+            .disabled_users
+            .iter()
+            .map(|entry| entry.key().clone())
+            .collect::<HashSet<_>>();
+
+        for user in current_disabled.difference(&desired_disabled) {
+            self.disabled_users.remove(user);
+        }
+        let newly_disabled = desired_disabled
+            .difference(&current_disabled)
+            .cloned()
+            .collect::<Vec<_>>();
+        for user in desired_disabled {
+            self.disabled_users.insert(user, ());
+        }
+        newly_disabled
+    }
+
+    pub(crate) fn register_user_session(
+        self: &Arc<Self>,
+        user: &str,
+        session_id: u64,
+    ) -> UserSessionRegistration {
+        let token = CancellationToken::new();
+        let key = (user.to_string(), session_id);
+        self.active_user_sessions.insert(key.clone(), token.clone());
+        UserSessionRegistration {
+            token,
+            _guard: UserSessionGuard {
+                shared: Arc::clone(self),
+                key,
+            },
+        }
+    }
+
+    pub(crate) fn cancel_user_sessions(&self, user: &str) -> usize {
+        let tokens = self
+            .active_user_sessions
+            .iter()
+            .filter_map(|entry| (entry.key().0 == user).then(|| entry.value().clone()))
+            .collect::<Vec<_>>();
+        for token in &tokens {
+            token.cancel();
+        }
+        tokens.len()
+    }
+
     pub(crate) fn set_conntrack_close_sender(&self, tx: mpsc::Sender<ConntrackCloseEvent>) {
         match self.conntrack_close_tx.lock() {
             Ok(mut guard) => {
@@ -166,3 +263,48 @@ impl ProxySharedState {
         self.conntrack_pressure_active.load(Ordering::Relaxed)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn user_enabled_config_sync_tracks_disabled_overrides() {
+        let shared = ProxySharedState::new();
+        assert!(shared.is_user_enabled("alice"));
+
+        let mut user_enabled = HashMap::new();
+        user_enabled.insert("alice".to_string(), false);
+        user_enabled.insert("bob".to_string(), true);
+
+        let mut newly_disabled = shared.apply_user_enabled_config(&user_enabled);
+        newly_disabled.sort();
+        assert_eq!(newly_disabled, vec!["alice".to_string()]);
+        assert!(!shared.is_user_enabled("alice"));
+        assert!(shared.is_user_enabled("bob"));
+
+        assert!(shared.apply_user_enabled_config(&user_enabled).is_empty());
+
+        user_enabled.clear();
+        assert!(shared.apply_user_enabled_config(&user_enabled).is_empty());
+        assert!(shared.is_user_enabled("alice"));
+    }
+
+    #[test]
+    fn cancel_user_sessions_cancels_only_registered_matching_user() {
+        let shared = ProxySharedState::new();
+        let alice_1 = shared.register_user_session("alice", 1);
+        let alice_2 = shared.register_user_session("alice", 2);
+        let bob = shared.register_user_session("bob", 1);
+        let alice_1_token = alice_1.token();
+        let alice_2_token = alice_2.token();
+        let bob_token = bob.token();
+
+        drop(alice_1);
+
+        assert_eq!(shared.cancel_user_sessions("alice"), 1);
+        assert!(!alice_1_token.is_cancelled());
+        assert!(alice_2_token.is_cancelled());
+        assert!(!bob_token.is_cancelled());
+    }
+}

src/proxy/tests/client_masking_blackhat_campaign_tests.rs

@@ -39,6 +39,7 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -85,17 +86,72 @@ fn make_valid_tls_client_hello(secret: &[u8], timestamp: u32, tls_len: usize, fi
         "TLS length must fit into record header"
     );
 
-    let total_len = 5 + tls_len;
-    let mut handshake = vec![fill; total_len];
-
-    handshake[0] = 0x16;
-    handshake[1] = 0x03;
-    handshake[2] = 0x01;
-    handshake[3..5].copy_from_slice(&(tls_len as u16).to_be_bytes());
-
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const TLS_EXTENSION_PADDING: u16 = 0x0015;
+    const X25519_KEY_SHARE_LEN: usize = 32;
     let session_id_len: usize = 32;
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
 
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let base_tls_len = 4
+        + 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    assert!(
+        tls_len == base_tls_len || tls_len >= base_tls_len + 4,
+        "TLS length must leave room for a complete padding extension"
+    );
+    if tls_len > base_tls_len {
+        let padding_len = tls_len - base_tls_len - 4;
+        extensions.extend_from_slice(&TLS_EXTENSION_PADDING.to_be_bytes());
+        extensions.extend_from_slice(&(padding_len as u16).to_be_bytes());
+        extensions.resize(extensions.len() + padding_len, fill);
+    }
+
+    let body_len = tls_len - 4;
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + tls_len);
+    handshake.push(0x16);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&(tls_len as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
     let computed = sha256_hmac(secret, &handshake);
     let mut digest = computed;
@@ -182,10 +238,11 @@ async fn run_tls_success_mtproto_fail_capture(
     assert_eq!(tls_response_head[0], 0x16);
     read_and_discard_tls_record_body(&mut client_side, tls_response_head).await;
 
-    client_side.write_all(&bad_mtproto_record).await.unwrap();
+    let mut client_payload = bad_mtproto_record;
     for record in trailing_records {
-        client_side.write_all(&record).await.unwrap();
+        client_payload.extend_from_slice(&record);
     }
+    client_side.write_all(&client_payload).await.unwrap();
 
     let got = tokio::time::timeout(Duration::from_secs(4), accept_task)
         .await
@@ -434,11 +491,9 @@ async fn blackhat_campaign_06_replayed_tls_hello_is_masked_without_serverhello()
                 client_side.read_exact(&mut head).await.unwrap();
                 assert_eq!(head[0], 0x16);
                 read_and_discard_tls_record_body(&mut client_side, head).await;
-                client_side
-                    .write_all(&invalid_mtproto_record)
-                    .await
-                    .unwrap();
-                client_side.write_all(&first_tail).await.unwrap();
+                let mut client_payload = invalid_mtproto_record;
+                client_payload.extend_from_slice(&first_tail);
+                client_side.write_all(&client_payload).await.unwrap();
             } else {
                 let mut one = [0u8; 1];
                 let no_server_hello = tokio::time::timeout(
@@ -740,8 +795,9 @@ async fn blackhat_campaign_12_parallel_tls_success_mtproto_fail_sessions_keep_is
             let mut head = [0u8; 5];
             client_side.read_exact(&mut head).await.unwrap();
             read_and_discard_tls_record_body(&mut client_side, head).await;
-            client_side.write_all(&bad).await.unwrap();
-            client_side.write_all(&tail).await.unwrap();
+            let mut client_payload = bad;
+            client_payload.extend_from_slice(&tail);
+            client_side.write_all(&client_payload).await.unwrap();
             client_side.shutdown().await.unwrap();
 
             let result = tokio::time::timeout(Duration::from_secs(5), handler)

src/proxy/tests/client_masking_budget_security_tests.rs

@@ -35,6 +35,7 @@ fn build_harness(config: ProxyConfig) -> PipelineHarness {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -64,17 +65,72 @@ fn make_valid_tls_client_hello(secret: &[u8], timestamp: u32, tls_len: usize, fi
         "TLS length must fit into record header"
     );
 
-    let total_len = 5 + tls_len;
-    let mut handshake = vec![fill; total_len];
-
-    handshake[0] = 0x16;
-    handshake[1] = 0x03;
-    handshake[2] = 0x01;
-    handshake[3..5].copy_from_slice(&(tls_len as u16).to_be_bytes());
-
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const TLS_EXTENSION_PADDING: u16 = 0x0015;
+    const X25519_KEY_SHARE_LEN: usize = 32;
     let session_id_len: usize = 32;
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
 
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let base_tls_len = 4
+        + 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    assert!(
+        tls_len == base_tls_len || tls_len >= base_tls_len + 4,
+        "TLS length must leave room for a complete padding extension"
+    );
+    if tls_len > base_tls_len {
+        let padding_len = tls_len - base_tls_len - 4;
+        extensions.extend_from_slice(&TLS_EXTENSION_PADDING.to_be_bytes());
+        extensions.extend_from_slice(&(padding_len as u16).to_be_bytes());
+        extensions.resize(extensions.len() + padding_len, fill);
+    }
+
+    let body_len = tls_len - 4;
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + tls_len);
+    handshake.push(0x16);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&(tls_len as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
     let computed = sha256_hmac(secret, &handshake);
     let mut digest = computed;
@@ -239,11 +295,9 @@ async fn tls_mtproto_bad_client_does_not_reinject_clienthello_into_mask_backend(
     assert_eq!(tls_response_head[0], 0x16);
     read_and_discard_tls_record_body(&mut client_side, tls_response_head).await;
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side.write_all(&trailing_record).await.unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&trailing_record);
+    client_side.write_all(&client_payload).await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(3), accept_task)
         .await

src/proxy/tests/client_masking_diagnostics_security_tests.rs

@@ -19,6 +19,7 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,

src/proxy/tests/client_masking_fragmented_classifier_security_tests.rs

@@ -19,6 +19,7 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,

src/proxy/tests/client_masking_hard_adversarial_tests.rs

@@ -33,6 +33,7 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -79,17 +80,72 @@ fn make_valid_tls_client_hello(secret: &[u8], timestamp: u32, tls_len: usize, fi
         "TLS length must fit into record header"
     );
 
-    let total_len = 5 + tls_len;
-    let mut handshake = vec![fill; total_len];
-
-    handshake[0] = 0x16;
-    handshake[1] = 0x03;
-    handshake[2] = 0x01;
-    handshake[3..5].copy_from_slice(&(tls_len as u16).to_be_bytes());
-
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const TLS_EXTENSION_PADDING: u16 = 0x0015;
+    const X25519_KEY_SHARE_LEN: usize = 32;
     let session_id_len: usize = 32;
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
 
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let base_tls_len = 4
+        + 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    assert!(
+        tls_len == base_tls_len || tls_len >= base_tls_len + 4,
+        "TLS length must leave room for a complete padding extension"
+    );
+    if tls_len > base_tls_len {
+        let padding_len = tls_len - base_tls_len - 4;
+        extensions.extend_from_slice(&TLS_EXTENSION_PADDING.to_be_bytes());
+        extensions.extend_from_slice(&(padding_len as u16).to_be_bytes());
+        extensions.resize(extensions.len() + padding_len, fill);
+    }
+
+    let body_len = tls_len - 4;
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + tls_len);
+    handshake.push(0x16);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&(tls_len as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
     let computed = sha256_hmac(secret, &handshake);
     let mut digest = computed;
@@ -172,13 +228,11 @@ async fn run_tls_success_mtproto_fail_capture(
     assert_eq!(tls_response_head[0], 0x16);
     read_tls_record_body(&mut client_side, tls_response_head).await;
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
+    let mut client_payload = invalid_mtproto_record;
     for record in trailing_records {
-        client_side.write_all(&record).await.unwrap();
+        client_payload.extend_from_slice(&record);
     }
+    client_side.write_all(&client_payload).await.unwrap();
 
     let got = tokio::time::timeout(Duration::from_secs(3), accept_task)
         .await
@@ -343,11 +397,9 @@ async fn replayed_tls_hello_gets_no_serverhello_and_is_masked() {
                 client_side.read_exact(&mut head).await.unwrap();
                 assert_eq!(head[0], 0x16);
                 read_tls_record_body(&mut client_side, head).await;
-                client_side
-                    .write_all(&invalid_mtproto_record)
-                    .await
-                    .unwrap();
-                client_side.write_all(&first_tail).await.unwrap();
+                let mut client_payload = invalid_mtproto_record;
+                client_payload.extend_from_slice(&first_tail);
+                client_side.write_all(&client_payload).await.unwrap();
             } else {
                 let mut one = [0u8; 1];
                 let no_server_hello = tokio::time::timeout(
@@ -418,11 +470,9 @@ async fn connects_bad_increments_once_per_invalid_mtproto() {
     let mut head = [0u8; 5];
     client_side.read_exact(&mut head).await.unwrap();
     read_tls_record_body(&mut client_side, head).await;
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side.write_all(&tail).await.unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&tail);
+    client_side.write_all(&client_payload).await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(3), accept_task)
         .await
@@ -675,8 +725,9 @@ async fn concurrent_tls_mtproto_fail_sessions_are_isolated() {
             let mut head = [0u8; 5];
             client_side.read_exact(&mut head).await.unwrap();
             read_tls_record_body(&mut client_side, head).await;
-            client_side.write_all(&invalid_mtproto).await.unwrap();
-            client_side.write_all(&trailing).await.unwrap();
+            let mut client_payload = invalid_mtproto;
+            client_payload.extend_from_slice(&trailing);
+            client_side.write_all(&client_payload).await.unwrap();
             client_side.shutdown().await.unwrap();
 
             let _ = tokio::time::timeout(Duration::from_secs(3), handler)

src/proxy/tests/client_masking_http2_fragmented_preface_security_tests.rs

@@ -19,6 +19,7 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,

src/proxy/tests/client_masking_prefetch_config_pipeline_integration_security_tests.rs

@@ -19,6 +19,7 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,

src/proxy/tests/client_masking_prefetch_invariant_security_tests.rs

@@ -46,6 +46,7 @@ fn build_harness(secret_hex: &str, mask_port: u16) -> PipelineHarness {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -70,17 +71,77 @@ fn build_harness(secret_hex: &str, mask_port: u16) -> PipelineHarness {
 }
 
 fn make_valid_tls_client_hello(secret: &[u8], timestamp: u32, tls_len: usize, fill: u8) -> Vec<u8> {
-    let total_len = 5 + tls_len;
-    let mut handshake = vec![fill; total_len];
-
-    handshake[0] = 0x16;
-    handshake[1] = 0x03;
-    handshake[2] = 0x01;
-    handshake[3..5].copy_from_slice(&(tls_len as u16).to_be_bytes());
+    assert!(
+        tls_len <= u16::MAX as usize,
+        "TLS length must fit into record header"
+    );
 
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const TLS_EXTENSION_PADDING: u16 = 0x0015;
+    const X25519_KEY_SHARE_LEN: usize = 32;
     let session_id_len: usize = 32;
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
 
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let base_tls_len = 4
+        + 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    assert!(
+        tls_len == base_tls_len || tls_len >= base_tls_len + 4,
+        "TLS length must leave room for a complete padding extension"
+    );
+    if tls_len > base_tls_len {
+        let padding_len = tls_len - base_tls_len - 4;
+        extensions.extend_from_slice(&TLS_EXTENSION_PADDING.to_be_bytes());
+        extensions.extend_from_slice(&(padding_len as u16).to_be_bytes());
+        extensions.resize(extensions.len() + padding_len, fill);
+    }
+
+    let body_len = tls_len - 4;
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + tls_len);
+    handshake.push(0x16);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&(tls_len as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
     let computed = sha256_hmac(secret, &handshake);
     let mut digest = computed;
@@ -249,11 +310,9 @@ async fn blackhat_integration_empty_initial_data_path_is_byte_exact_and_eof_clea
     assert_eq!(head[0], 0x16);
     read_and_discard_tls_record_body(&mut client_side, head).await;
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side.write_all(&trailing_record).await.unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&trailing_record);
+    client_side.write_all(&client_payload).await.unwrap();
     client_side.shutdown().await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(3), accept_task)

src/proxy/tests/client_masking_probe_evasion_blackhat_tests.rs

@@ -24,6 +24,7 @@ fn make_test_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,

src/proxy/tests/client_masking_redteam_expected_fail_tests.rs

@@ -47,6 +47,7 @@ fn build_harness(secret_hex: &str, mask_port: u16) -> RedTeamHarness {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -76,17 +77,73 @@ fn make_valid_tls_client_hello(secret: &[u8], timestamp: u32, tls_len: usize, fi
         "TLS length must fit into record header"
     );
 
-    let total_len = 5 + tls_len;
-    let mut handshake = vec![fill; total_len];
-    handshake[0] = 0x16;
-    handshake[1] = 0x03;
-    handshake[2] = 0x01;
-    handshake[3..5].copy_from_slice(&(tls_len as u16).to_be_bytes());
-
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const TLS_EXTENSION_PADDING: u16 = 0x0015;
+    const X25519_KEY_SHARE_LEN: usize = 32;
     let session_id_len: usize = 32;
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
-    handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
 
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let base_tls_len = 4
+        + 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    assert!(
+        tls_len == base_tls_len || tls_len >= base_tls_len + 4,
+        "TLS length must leave room for a complete padding extension"
+    );
+    if tls_len > base_tls_len {
+        let padding_len = tls_len - base_tls_len - 4;
+        extensions.extend_from_slice(&TLS_EXTENSION_PADDING.to_be_bytes());
+        extensions.extend_from_slice(&(padding_len as u16).to_be_bytes());
+        extensions.resize(extensions.len() + padding_len, fill);
+    }
+
+    let body_len = tls_len - 4;
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + tls_len);
+    handshake.push(0x16);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&(tls_len as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
+    handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
     let computed = sha256_hmac(secret, &handshake);
     let mut digest = computed;
     let ts = timestamp.to_le_bytes();
@@ -155,14 +212,9 @@ async fn run_tls_success_mtproto_fail_session(
     let mut body = vec![0u8; body_len];
     client_side.read_exact(&mut body).await.unwrap();
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side
-        .write_all(&wrap_tls_application_data(&tail))
-        .await
-        .unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&wrap_tls_application_data(&tail));
+    client_side.write_all(&client_payload).await.unwrap();
 
     let forwarded = tokio::time::timeout(Duration::from_secs(3), accept_task)
         .await
@@ -240,6 +292,7 @@ async fn redteam_03_masking_duration_must_be_less_than_1ms_when_backend_down() {
                 selected_scope: String::new(),
                 ipv4: None,
                 ipv6: None,
+                prefer: None,
             }],
             1,
             1,
@@ -484,6 +537,7 @@ async fn measure_invalid_probe_duration_ms(delay_ms: u64, tls_len: u16, body_sen
                 selected_scope: String::new(),
                 ipv4: None,
                 ipv6: None,
+                prefer: None,
             }],
             1,
             1,
@@ -561,6 +615,7 @@ async fn capture_forwarded_probe_len(tls_len: u16, body_sent: usize) -> usize {
                 selected_scope: String::new(),
                 ipv4: None,
                 ipv6: None,
+                prefer: None,
             }],
             1,
             1,

src/proxy/tests/client_masking_replay_timing_security_tests.rs

@@ -21,6 +21,7 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -33,17 +34,77 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
 }
 
 fn make_valid_tls_client_hello(secret: &[u8], timestamp: u32, tls_len: usize, fill: u8) -> Vec<u8> {
-    let total_len = 5 + tls_len;
-    let mut handshake = vec![fill; total_len];
-
-    handshake[0] = 0x16;
-    handshake[1] = 0x03;
-    handshake[2] = 0x01;
-    handshake[3..5].copy_from_slice(&(tls_len as u16).to_be_bytes());
+    assert!(
+        tls_len <= u16::MAX as usize,
+        "TLS length must fit into record header"
+    );
 
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const TLS_EXTENSION_PADDING: u16 = 0x0015;
+    const X25519_KEY_SHARE_LEN: usize = 32;
     let session_id_len: usize = 32;
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
 
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let base_tls_len = 4
+        + 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    assert!(
+        tls_len == base_tls_len || tls_len >= base_tls_len + 4,
+        "TLS length must leave room for a complete padding extension"
+    );
+    if tls_len > base_tls_len {
+        let padding_len = tls_len - base_tls_len - 4;
+        extensions.extend_from_slice(&TLS_EXTENSION_PADDING.to_be_bytes());
+        extensions.extend_from_slice(&(padding_len as u16).to_be_bytes());
+        extensions.resize(extensions.len() + padding_len, fill);
+    }
+
+    let body_len = tls_len - 4;
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + tls_len);
+    handshake.push(0x16);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&(tls_len as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
     let computed = sha256_hmac(secret, &handshake);
     let mut digest = computed;
@@ -118,14 +179,9 @@ async fn run_replay_candidate_session(
         invalid_mtproto_record.extend_from_slice(&TLS_VERSION);
         invalid_mtproto_record.extend_from_slice(&(HANDSHAKE_LEN as u16).to_be_bytes());
         invalid_mtproto_record.extend_from_slice(&vec![0u8; HANDSHAKE_LEN]);
-        client_side
-            .write_all(&invalid_mtproto_record)
-            .await
-            .unwrap();
-        client_side
-            .write_all(b"GET /replay-fallback HTTP/1.1\r\nHost: x\r\n\r\n")
-            .await
-            .unwrap();
+        let mut client_payload = invalid_mtproto_record;
+        client_payload.extend_from_slice(b"GET /replay-fallback HTTP/1.1\r\nHost: x\r\n\r\n");
+        client_side.write_all(&client_payload).await.unwrap();
     }
 
     client_side.shutdown().await.unwrap();

src/proxy/tests/client_masking_shape_classifier_fuzz_redteam_expected_fail_tests.rs

@@ -19,6 +19,7 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,

src/proxy/tests/client_masking_shape_hardening_adversarial_tests.rs

@@ -19,6 +19,7 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,

src/proxy/tests/client_masking_shape_hardening_redteam_expected_fail_tests.rs

@@ -19,6 +19,7 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,

src/proxy/tests/client_masking_shape_hardening_security_tests.rs

@@ -19,6 +19,7 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,

src/proxy/tests/client_masking_stress_adversarial_tests.rs

@@ -33,6 +33,7 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -79,17 +80,72 @@ fn make_valid_tls_client_hello(secret: &[u8], timestamp: u32, tls_len: usize, fi
         "TLS length must fit into record header"
     );
 
-    let total_len = 5 + tls_len;
-    let mut handshake = vec![fill; total_len];
-
-    handshake[0] = 0x16;
-    handshake[1] = 0x03;
-    handshake[2] = 0x01;
-    handshake[3..5].copy_from_slice(&(tls_len as u16).to_be_bytes());
-
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const TLS_EXTENSION_PADDING: u16 = 0x0015;
+    const X25519_KEY_SHARE_LEN: usize = 32;
     let session_id_len: usize = 32;
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
 
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let base_tls_len = 4
+        + 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    assert!(
+        tls_len == base_tls_len || tls_len >= base_tls_len + 4,
+        "TLS length must leave room for a complete padding extension"
+    );
+    if tls_len > base_tls_len {
+        let padding_len = tls_len - base_tls_len - 4;
+        extensions.extend_from_slice(&TLS_EXTENSION_PADDING.to_be_bytes());
+        extensions.extend_from_slice(&(padding_len as u16).to_be_bytes());
+        extensions.resize(extensions.len() + padding_len, fill);
+    }
+
+    let body_len = tls_len - 4;
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + tls_len);
+    handshake.push(0x16);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&(tls_len as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
     let computed = sha256_hmac(secret, &handshake);
     let mut digest = computed;
@@ -204,8 +260,13 @@ async fn run_parallel_tail_fallback_case(
             assert_eq!(server_hello_head[0], 0x16);
             read_tls_record_body(&mut client_side, server_hello_head).await;
 
-            client_side.write_all(&invalid_mtproto).await.unwrap();
-            for chunk in trailing.chunks(write_chunk.max(1)) {
+            let mut chunks = trailing.chunks(write_chunk.max(1));
+            let mut client_payload = invalid_mtproto;
+            if let Some(first_chunk) = chunks.next() {
+                client_payload.extend_from_slice(first_chunk);
+            }
+            client_side.write_all(&client_payload).await.unwrap();
+            for chunk in chunks {
                 client_side.write_all(chunk).await.unwrap();
             }
             client_side.shutdown().await.unwrap();

src/proxy/tests/client_security_tests.rs

@@ -3,7 +3,7 @@ use crate::config::{UpstreamConfig, UpstreamType};
 use crate::crypto::{AesCtr, sha256, sha256_hmac};
 use crate::protocol::constants::{
     DC_IDX_POS, HANDSHAKE_LEN, IV_LEN, PREKEY_LEN, PROTO_TAG_POS, ProtoTag, SKIP_LEN,
-    TLS_RECORD_CHANGE_CIPHER,
+    TLS_RECORD_CHANGE_CIPHER, TLS_VERSION,
 };
 use crate::protocol::tls;
 use crate::proxy::handshake::HandshakeSuccess;
@@ -341,6 +341,7 @@ async fn relay_task_abort_releases_user_gate_and_ip_reservation() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -459,6 +460,7 @@ async fn relay_cutover_releases_user_gate_and_ip_reservation() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -586,6 +588,7 @@ async fn integration_route_cutover_and_quota_overlap_fails_closed_and_releases_s
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -759,6 +762,7 @@ async fn proxy_protocol_header_is_rejected_when_trust_list_is_empty() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -839,6 +843,7 @@ async fn proxy_protocol_header_from_untrusted_peer_range_is_rejected_under_load(
                 selected_scope: String::new(),
                 ipv4: None,
                 ipv6: None,
+                prefer: None,
             }],
             1,
             1,
@@ -1032,6 +1037,7 @@ async fn short_tls_probe_is_masked_through_client_pipeline() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -1123,6 +1129,7 @@ async fn tls12_record_probe_is_masked_through_client_pipeline() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -1212,6 +1219,7 @@ async fn handle_client_stream_increments_connects_all_exactly_once() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -1308,6 +1316,7 @@ async fn running_client_handler_increments_connects_all_exactly_once() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -1401,6 +1410,7 @@ async fn idle_pooled_connection_closes_cleanly_in_generic_stream_path() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -1475,6 +1485,7 @@ async fn idle_pooled_connection_closes_cleanly_in_client_handler_path() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -1564,6 +1575,7 @@ async fn partial_tls_header_stall_triggers_handshake_timeout() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -1618,17 +1630,73 @@ fn make_valid_tls_client_hello_with_len(secret: &[u8], timestamp: u32, tls_len:
         "TLS length must fit into record header"
     );
 
-    let total_len = 5 + tls_len;
-    let mut handshake = vec![0x42u8; total_len];
-
-    handshake[0] = 0x16;
-    handshake[1] = 0x03;
-    handshake[2] = 0x01;
-    handshake[3..5].copy_from_slice(&(tls_len as u16).to_be_bytes());
-
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const TLS_EXTENSION_PADDING: u16 = 0x0015;
+    const X25519_KEY_SHARE_LEN: usize = 32;
+    let fill = 0x42u8;
     let session_id_len: usize = 32;
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
 
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let base_tls_len = 4
+        + 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    assert!(
+        tls_len == base_tls_len || tls_len >= base_tls_len + 4,
+        "TLS length must leave room for a complete padding extension"
+    );
+    if tls_len > base_tls_len {
+        let padding_len = tls_len - base_tls_len - 4;
+        extensions.extend_from_slice(&TLS_EXTENSION_PADDING.to_be_bytes());
+        extensions.extend_from_slice(&(padding_len as u16).to_be_bytes());
+        extensions.resize(extensions.len() + padding_len, fill);
+    }
+
+    let body_len = tls_len - 4;
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + tls_len);
+    handshake.push(0x16);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&(tls_len as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
     let computed = sha256_hmac(secret, &handshake);
     let mut digest = computed;
@@ -1651,6 +1719,9 @@ fn make_valid_tls_client_hello_with_alpn(
     timestamp: u32,
     alpn_protocols: &[&[u8]],
 ) -> Vec<u8> {
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const X25519_KEY_SHARE_LEN: usize = 32;
+
     let mut body = Vec::new();
     body.extend_from_slice(&TLS_VERSION);
     body.extend_from_slice(&[0u8; 32]);
@@ -1662,6 +1733,19 @@ fn make_valid_tls_client_hello_with_alpn(
     body.push(0);
 
     let mut ext_blob = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    ext_blob.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    ext_blob.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    ext_blob.extend_from_slice(&key_share_extension);
+
     if !alpn_protocols.is_empty() {
         let mut alpn_list = Vec::new();
         for proto in alpn_protocols {
@@ -1892,6 +1976,7 @@ async fn valid_tls_path_does_not_fall_back_to_mask_backend() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -2004,6 +2089,7 @@ async fn valid_tls_with_invalid_mtproto_falls_back_to_mask_backend() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -2048,8 +2134,9 @@ async fn valid_tls_with_invalid_mtproto_falls_back_to_mask_backend() {
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side.write_all(&tls_app_record).await.unwrap();
-    client_side.write_all(&trailing_tls_record).await.unwrap();
+    let mut client_payload = tls_app_record;
+    client_payload.extend_from_slice(&trailing_tls_record);
+    client_side.write_all(&client_payload).await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(3), accept_task)
         .await
@@ -2114,6 +2201,7 @@ async fn client_handler_tls_bad_mtproto_is_forwarded_to_mask_backend() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -2173,8 +2261,9 @@ async fn client_handler_tls_bad_mtproto_is_forwarded_to_mask_backend() {
     client.read_exact(&mut tls_response_head).await.unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client.write_all(&tls_app_record).await.unwrap();
-    client.write_all(&trailing_tls_record).await.unwrap();
+    let mut client_payload = tls_app_record;
+    client_payload.extend_from_slice(&trailing_tls_record);
+    client.write_all(&client_payload).await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(3), mask_accept_task)
         .await
@@ -2239,6 +2328,7 @@ async fn alpn_mismatch_tls_probe_is_masked_through_client_pipeline() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -2335,6 +2425,7 @@ async fn invalid_hmac_tls_probe_is_masked_through_client_pipeline() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -2437,6 +2528,7 @@ async fn burst_invalid_tls_probes_are_masked_verbatim() {
                 selected_scope: String::new(),
                 ipv4: None,
                 ipv6: None,
+                prefer: None,
             }],
             1,
             1,
@@ -3395,6 +3487,7 @@ async fn relay_connect_error_releases_user_and_ip_before_return() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -3963,6 +4056,7 @@ async fn untrusted_proxy_header_source_is_rejected() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -4036,6 +4130,7 @@ async fn empty_proxy_trusted_cidrs_rejects_proxy_header_by_default() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -4136,6 +4231,7 @@ async fn oversized_tls_record_is_masked_in_generic_stream_pipeline() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -4242,6 +4338,7 @@ async fn oversized_tls_record_is_masked_in_client_handler_pipeline() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -4362,6 +4459,7 @@ async fn tls_record_len_min_minus_1_is_rejected_in_generic_stream_pipeline() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -4468,6 +4566,7 @@ async fn tls_record_len_min_minus_1_is_rejected_in_client_handler_pipeline() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -4577,6 +4676,7 @@ async fn tls_record_len_16384_is_accepted_in_generic_stream_pipeline() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -4681,6 +4781,7 @@ async fn tls_record_len_16384_is_accepted_in_client_handler_pipeline() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,

src/proxy/tests/client_timing_profile_adversarial_tests.rs

@@ -32,6 +32,7 @@ fn make_test_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -74,12 +75,17 @@ async fn run_generic_once(class: ProbeClass) -> u128 {
     let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
     let backend_addr = listener.local_addr().unwrap();
     let backend_reply = REPLY_404.to_vec();
+    let probe = match class {
+        ProbeClass::MalformedTlsTruncation => malformed_tls_probe(),
+        ProbeClass::PlainWebBaseline => plain_web_probe(),
+    };
 
     let accept_task = tokio::spawn({
         let backend_reply = backend_reply.clone();
+        let expected_probe_len = probe.len();
         async move {
             let (mut stream, _) = listener.accept().await.unwrap();
-            let mut buf = [0u8; 5];
+            let mut buf = vec![0u8; expected_probe_len];
             stream.read_exact(&mut buf).await.unwrap();
             stream.write_all(&backend_reply).await.unwrap();
         }
@@ -93,6 +99,7 @@ async fn run_generic_once(class: ProbeClass) -> u128 {
     cfg.censorship.mask_host = Some("127.0.0.1".to_string());
     cfg.censorship.mask_port = backend_addr.port();
     cfg.censorship.mask_proxy_protocol = 0;
+    cfg.censorship.mask_shape_hardening = false;
 
     if matches!(class, ProbeClass::PlainWebBaseline) {
         cfg.general.modes.classic = false;
@@ -129,11 +136,6 @@ async fn run_generic_once(class: ProbeClass) -> u128 {
         false,
     ));
 
-    let probe = match class {
-        ProbeClass::MalformedTlsTruncation => malformed_tls_probe(),
-        ProbeClass::PlainWebBaseline => plain_web_probe(),
-    };
-
     let started = Instant::now();
     client_side.write_all(&probe).await.unwrap();
     client_side.shutdown().await.unwrap();
@@ -169,11 +171,16 @@ async fn run_client_handler_once(class: ProbeClass) -> u128 {
     let front_addr = front_listener.local_addr().unwrap();
 
     let backend_reply = REPLY_404.to_vec();
+    let probe = match class {
+        ProbeClass::MalformedTlsTruncation => malformed_tls_probe(),
+        ProbeClass::PlainWebBaseline => plain_web_probe(),
+    };
     let mask_accept_task = tokio::spawn({
         let backend_reply = backend_reply.clone();
+        let expected_probe_len = probe.len();
         async move {
             let (mut stream, _) = mask_listener.accept().await.unwrap();
-            let mut buf = [0u8; 5];
+            let mut buf = vec![0u8; expected_probe_len];
             stream.read_exact(&mut buf).await.unwrap();
             stream.write_all(&backend_reply).await.unwrap();
         }
@@ -187,6 +194,7 @@ async fn run_client_handler_once(class: ProbeClass) -> u128 {
     cfg.censorship.mask_host = Some("127.0.0.1".to_string());
     cfg.censorship.mask_port = backend_addr.port();
     cfg.censorship.mask_proxy_protocol = 0;
+    cfg.censorship.mask_shape_hardening = false;
 
     if matches!(class, ProbeClass::PlainWebBaseline) {
         cfg.general.modes.classic = false;
@@ -239,11 +247,6 @@ async fn run_client_handler_once(class: ProbeClass) -> u128 {
         })
     };
 
-    let probe = match class {
-        ProbeClass::MalformedTlsTruncation => malformed_tls_probe(),
-        ProbeClass::PlainWebBaseline => plain_web_probe(),
-    };
-
     let mut client = TcpStream::connect(front_addr).await.unwrap();
     let started = Instant::now();
     client.write_all(&probe).await.unwrap();

src/proxy/tests/client_tls_clienthello_size_security_tests.rs

@@ -34,6 +34,7 @@ fn make_test_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,

src/proxy/tests/client_tls_clienthello_truncation_adversarial_tests.rs

@@ -35,6 +35,7 @@ fn make_test_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,

src/proxy/tests/client_tls_mtproto_fallback_security_tests.rs

@@ -49,6 +49,7 @@ fn build_harness(secret_hex: &str, mask_port: u16) -> PipelineHarness {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -78,17 +79,72 @@ fn make_valid_tls_client_hello(secret: &[u8], timestamp: u32, tls_len: usize, fi
         "TLS length must fit into record header"
     );
 
-    let total_len = 5 + tls_len;
-    let mut handshake = vec![fill; total_len];
-
-    handshake[0] = 0x16;
-    handshake[1] = 0x03;
-    handshake[2] = 0x01;
-    handshake[3..5].copy_from_slice(&(tls_len as u16).to_be_bytes());
-
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const TLS_EXTENSION_PADDING: u16 = 0x0015;
+    const X25519_KEY_SHARE_LEN: usize = 32;
     let session_id_len: usize = 32;
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
 
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let base_tls_len = 4
+        + 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    assert!(
+        tls_len == base_tls_len || tls_len >= base_tls_len + 4,
+        "TLS length must leave room for a complete padding extension"
+    );
+    if tls_len > base_tls_len {
+        let padding_len = tls_len - base_tls_len - 4;
+        extensions.extend_from_slice(&TLS_EXTENSION_PADDING.to_be_bytes());
+        extensions.extend_from_slice(&(padding_len as u16).to_be_bytes());
+        extensions.resize(extensions.len() + padding_len, fill);
+    }
+
+    let body_len = tls_len - 4;
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + tls_len);
+    handshake.push(0x16);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&(tls_len as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
     let computed = sha256_hmac(secret, &handshake);
     let mut digest = computed;
@@ -190,11 +246,9 @@ async fn tls_bad_mtproto_fallback_preserves_wire_and_backend_response() {
     assert_eq!(tls_response_head[0], 0x16);
     read_and_discard_tls_record_body(&mut client_side, tls_response_head).await;
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side.write_all(&trailing_record).await.unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&trailing_record);
+    client_side.write_all(&client_payload).await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(3), accept_task)
         .await
@@ -260,11 +314,9 @@ async fn tls_bad_mtproto_fallback_keeps_connects_bad_accounting() {
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side.write_all(&trailing_record).await.unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&trailing_record);
+    client_side.write_all(&client_payload).await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(3), accept_task)
         .await
@@ -334,11 +386,9 @@ async fn tls_bad_mtproto_fallback_forwards_zero_length_tls_record_verbatim() {
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side.write_all(&trailing_record).await.unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&trailing_record);
+    client_side.write_all(&client_payload).await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(3), accept_task)
         .await
@@ -402,11 +452,9 @@ async fn tls_bad_mtproto_fallback_forwards_max_tls_record_verbatim() {
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side.write_all(&trailing_record).await.unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&trailing_record);
+    client_side.write_all(&client_payload).await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(3), accept_task)
         .await
@@ -480,11 +528,9 @@ async fn tls_bad_mtproto_fallback_light_fuzz_tls_record_lengths_verbatim() {
             .unwrap();
         assert_eq!(tls_response_head[0], 0x16);
 
-        client_side
-            .write_all(&invalid_mtproto_record)
-            .await
-            .unwrap();
-        client_side.write_all(&trailing_record).await.unwrap();
+        let mut client_payload = invalid_mtproto_record;
+        client_payload.extend_from_slice(&trailing_record);
+        client_side.write_all(&client_payload).await.unwrap();
 
         tokio::time::timeout(Duration::from_secs(3), accept_task)
             .await
@@ -585,11 +631,9 @@ async fn tls_bad_mtproto_fallback_concurrent_sessions_are_isolated() {
                 .unwrap();
             assert_eq!(tls_response_head[0], 0x16);
 
-            client_side
-                .write_all(&invalid_mtproto_record)
-                .await
-                .unwrap();
-            client_side.write_all(&trailing_record).await.unwrap();
+            let mut client_payload = invalid_mtproto_record;
+            client_payload.extend_from_slice(&trailing_record);
+            client_side.write_all(&client_payload).await.unwrap();
 
             drop(client_side);
             let _ = tokio::time::timeout(Duration::from_secs(3), handler)
@@ -659,12 +703,14 @@ async fn tls_bad_mtproto_fallback_forwards_fragmented_client_writes_verbatim() {
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
+    let mut chunks = trailing_record.chunks(3);
+    let mut client_payload = invalid_mtproto_record;
+    if let Some(first_chunk) = chunks.next() {
+        client_payload.extend_from_slice(first_chunk);
+    }
+    client_side.write_all(&client_payload).await.unwrap();
 
-    for chunk in trailing_record.chunks(3) {
+    for chunk in chunks {
         client_side.write_all(chunk).await.unwrap();
     }
 
@@ -728,11 +774,13 @@ async fn tls_bad_mtproto_fallback_header_fragmentation_bytewise_is_verbatim() {
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    for b in trailing_record.iter().copied() {
+    let mut bytes = trailing_record.iter().copied();
+    let mut client_payload = invalid_mtproto_record;
+    if let Some(first_byte) = bytes.next() {
+        client_payload.push(first_byte);
+    }
+    client_side.write_all(&client_payload).await.unwrap();
+    for b in bytes {
         client_side.write_all(&[b]).await.unwrap();
     }
 
@@ -801,14 +849,16 @@ async fn tls_bad_mtproto_fallback_record_splitting_chaos_is_verbatim() {
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-
     let chaos = [7usize, 1, 19, 3, 5, 31, 2, 11, 13, 17];
     let mut pos = 0usize;
     let mut idx = 0usize;
+    let mut client_payload = invalid_mtproto_record;
+    let first_step = chaos[idx % chaos.len()];
+    let first_end = first_step.min(trailing_record.len());
+    client_payload.extend_from_slice(&trailing_record[..first_end]);
+    client_side.write_all(&client_payload).await.unwrap();
+    pos = first_end;
+    idx += 1;
     while pos < trailing_record.len() {
         let step = chaos[idx % chaos.len()];
         let end = (pos + step).min(trailing_record.len());
@@ -883,11 +933,9 @@ async fn tls_bad_mtproto_fallback_multiple_tls_records_are_forwarded_in_order()
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side.write_all(&r1).await.unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&r1);
+    client_side.write_all(&client_payload).await.unwrap();
     client_side.write_all(&r2).await.unwrap();
     client_side.write_all(&r3).await.unwrap();
 
@@ -957,11 +1005,9 @@ async fn tls_bad_mtproto_fallback_client_half_close_propagates_eof_to_backend()
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side.write_all(&trailing_record).await.unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&trailing_record);
+    client_side.write_all(&client_payload).await.unwrap();
     client_side.shutdown().await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(3), accept_task)
@@ -1028,11 +1074,9 @@ async fn tls_bad_mtproto_fallback_backend_half_close_after_response_is_tolerated
     assert_eq!(tls_response_head[0], 0x16);
     read_and_discard_tls_record_body(&mut client_side, tls_response_head).await;
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side.write_all(&trailing_record).await.unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&trailing_record);
+    client_side.write_all(&client_payload).await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(3), accept_task)
         .await
@@ -1089,11 +1133,9 @@ async fn tls_bad_mtproto_fallback_backend_reset_after_clienthello_is_handled() {
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    let write_res = client_side.write_all(&trailing_record).await;
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&trailing_record);
+    let write_res = client_side.write_all(&client_payload).await;
     assert!(
         write_res.is_ok() || write_res.is_err(),
         "write completion is environment dependent under backend reset"
@@ -1169,11 +1211,9 @@ async fn tls_bad_mtproto_fallback_backend_slow_reader_preserves_byte_identity()
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side.write_all(&trailing_record).await.unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&trailing_record);
+    client_side.write_all(&client_payload).await.unwrap();
 
     tokio::time::timeout(Duration::from_secs(5), accept_task)
         .await
@@ -1253,11 +1293,9 @@ async fn tls_bad_mtproto_fallback_replay_pressure_masks_replay_without_serverhel
                 let mut head = [0u8; 5];
                 client_side.read_exact(&mut head).await.unwrap();
                 assert_eq!(head[0], 0x16);
-                client_side
-                    .write_all(&invalid_mtproto_record)
-                    .await
-                    .unwrap();
-                client_side.write_all(&trailing_record).await.unwrap();
+                let mut client_payload = invalid_mtproto_record;
+                client_payload.extend_from_slice(&trailing_record);
+                client_side.write_all(&client_payload).await.unwrap();
             } else {
                 let mut one = [0u8; 1];
                 let no_server_hello = tokio::time::timeout(
@@ -1351,13 +1389,29 @@ async fn tls_bad_mtproto_fallback_large_multi_record_chaos_under_backpressure()
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-
     let chaos = [5usize, 23, 11, 47, 3, 19, 29, 13, 7, 31];
-    for record in [&a, &b, &c] {
+    let records = [&a, &b, &c];
+    let mut records_iter = records.iter().copied();
+    let mut client_payload = invalid_mtproto_record;
+    if let Some(first_record) = records_iter.next() {
+        let first_step = chaos[0].min(first_record.len());
+        client_payload.extend_from_slice(&first_record[..first_step]);
+        client_side.write_all(&client_payload).await.unwrap();
+
+        let mut pos = first_step;
+        let mut idx = 1usize;
+        while pos < first_record.len() {
+            let step = chaos[idx % chaos.len()];
+            let end = (pos + step).min(first_record.len());
+            client_side
+                .write_all(&first_record[pos..end])
+                .await
+                .unwrap();
+            pos = end;
+            idx += 1;
+        }
+    }
+    for record in records_iter {
         let mut pos = 0usize;
         let mut idx = 0usize;
         while pos < record.len() {
@@ -1432,11 +1486,9 @@ async fn tls_bad_mtproto_fallback_interleaved_control_and_application_records_ve
         .unwrap();
     assert_eq!(tls_response_head[0], 0x16);
 
-    client_side
-        .write_all(&invalid_mtproto_record)
-        .await
-        .unwrap();
-    client_side.write_all(&ccs).await.unwrap();
+    let mut client_payload = invalid_mtproto_record;
+    client_payload.extend_from_slice(&ccs);
+    client_side.write_all(&client_payload).await.unwrap();
     client_side.write_all(&app).await.unwrap();
     client_side.write_all(&alert).await.unwrap();
 
@@ -1532,11 +1584,13 @@ async fn tls_bad_mtproto_fallback_many_short_sessions_with_chaos_no_cross_leak()
             client_side.read_exact(&mut head).await.unwrap();
             assert_eq!(head[0], 0x16);
 
-            client_side
-                .write_all(&invalid_mtproto_record)
-                .await
-                .unwrap();
-            for chunk in record.chunks((idx % 9) + 1) {
+            let mut chunks = record.chunks((idx % 9) + 1);
+            let mut client_payload = invalid_mtproto_record;
+            if let Some(first_chunk) = chunks.next() {
+                client_payload.extend_from_slice(first_chunk);
+            }
+            client_side.write_all(&client_payload).await.unwrap();
+            for chunk in chunks {
                 client_side.write_all(chunk).await.unwrap();
             }
 

src/proxy/tests/direct_relay_security_tests.rs

@@ -1338,6 +1338,7 @@ async fn direct_relay_abort_midflight_releases_route_gauge() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -1448,6 +1449,7 @@ async fn direct_relay_cutover_midflight_releases_route_gauge() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -1570,6 +1572,7 @@ async fn direct_relay_cutover_storm_multi_session_keeps_generic_errors_and_relea
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,
@@ -1803,6 +1806,7 @@ async fn negative_direct_relay_dc_connection_refused_fails_fast() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         100,
@@ -1897,6 +1901,7 @@ async fn adversarial_direct_relay_cutover_integrity() {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         100,

src/proxy/tests/handshake_advanced_clever_tests.rs

@@ -21,11 +21,59 @@ fn test_config_with_secret_hex(secret_hex: &str) -> ProxyConfig {
 }
 
 fn make_valid_tls_handshake(secret: &[u8], timestamp: u32) -> Vec<u8> {
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const X25519_KEY_SHARE_LEN: usize = 32;
     let session_id_len: usize = 32;
-    let len = tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN + 1 + session_id_len;
-    let mut handshake = vec![0x42u8; len];
+    let fill = 0x42u8;
 
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let body_len = 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + 4 + body_len);
+    handshake.push(TLS_RECORD_HANDSHAKE);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&((4 + body_len) as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
 
     let computed = sha256_hmac(secret, &handshake);
@@ -85,6 +133,9 @@ fn make_valid_tls_client_hello_with_alpn(
     timestamp: u32,
     alpn_protocols: &[&[u8]],
 ) -> Vec<u8> {
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const X25519_KEY_SHARE_LEN: usize = 32;
+
     let mut body = Vec::new();
     body.extend_from_slice(&TLS_VERSION);
     body.extend_from_slice(&[0u8; 32]);
@@ -96,6 +147,19 @@ fn make_valid_tls_client_hello_with_alpn(
     body.push(0);
 
     let mut ext_blob = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    ext_blob.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    ext_blob.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    ext_blob.extend_from_slice(&key_share_extension);
+
     if !alpn_protocols.is_empty() {
         let mut alpn_list = Vec::new();
         for proto in alpn_protocols {
@@ -150,13 +214,7 @@ async fn tls_minimum_viable_length_boundary() {
     let rng = SecureRandom::new();
     let peer: SocketAddr = "192.0.2.1:12345".parse().unwrap();
 
-    let min_len = tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN + 1;
-    let mut exact_min_handshake = vec![0x42u8; min_len];
-    exact_min_handshake[min_len - 1] = 0;
-    exact_min_handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
-    let digest = sha256_hmac(&secret, &exact_min_handshake);
-    exact_min_handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN]
-        .copy_from_slice(&digest);
+    let exact_min_handshake = make_valid_tls_handshake(&secret, 0);
 
     let res = handle_tls_handshake(
         &exact_min_handshake,
@@ -171,12 +229,12 @@ async fn tls_minimum_viable_length_boundary() {
     .await;
     assert!(
         matches!(res, HandshakeResult::Success(_)),
-        "Exact minimum length TLS handshake must succeed"
+        "Minimum valid TLS ClientHello must succeed"
     );
 
-    let short_handshake = vec![0x42u8; min_len - 1];
+    let short_handshake = &exact_min_handshake[..exact_min_handshake.len() - 1];
     let res_short = handle_tls_handshake(
-        &short_handshake,
+        short_handshake,
         tokio::io::empty(),
         tokio::io::sink(),
         peer,
@@ -188,7 +246,7 @@ async fn tls_minimum_viable_length_boundary() {
     .await;
     assert!(
         matches!(res_short, HandshakeResult::BadClient { .. }),
-        "Handshake 1 byte shorter than minimum must fail closed"
+        "Handshake 1 byte shorter than minimum valid ClientHello must fail closed"
     );
 }
 

src/proxy/tests/handshake_baseline_invariant_tests.rs

@@ -1,5 +1,6 @@
 use super::*;
 use crate::crypto::sha256_hmac;
+use crate::protocol::constants::{TLS_RECORD_HANDSHAKE, TLS_VERSION};
 use crate::stats::ReplayChecker;
 use std::net::{IpAddr, Ipv4Addr, SocketAddr};
 use std::time::{Duration, Instant};
@@ -17,11 +18,59 @@ fn test_config_with_secret_hex(secret_hex: &str) -> ProxyConfig {
 }
 
 fn make_valid_tls_handshake(secret: &[u8], timestamp: u32) -> Vec<u8> {
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const X25519_KEY_SHARE_LEN: usize = 32;
     let session_id_len: usize = 32;
-    let len = tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN + 1 + session_id_len;
-    let mut handshake = vec![0x42u8; len];
+    let fill = 0x42u8;
 
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let body_len = 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + 4 + body_len);
+    handshake.push(TLS_RECORD_HANDSHAKE);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&((4 + body_len) as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
 
     let computed = sha256_hmac(secret, &handshake);

src/proxy/tests/handshake_more_clever_tests.rs

@@ -25,11 +25,59 @@ fn test_config_with_secret_hex(secret_hex: &str) -> ProxyConfig {
 }
 
 fn make_valid_tls_handshake(secret: &[u8], timestamp: u32) -> Vec<u8> {
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const X25519_KEY_SHARE_LEN: usize = 32;
     let session_id_len: usize = 32;
-    let len = tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN + 1 + session_id_len;
-    let mut handshake = vec![0x42u8; len];
+    let fill = 0x42u8;
 
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let body_len = 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + 4 + body_len);
+    handshake.push(TLS_RECORD_HANDSHAKE);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&((4 + body_len) as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
 
     let computed = sha256_hmac(secret, &handshake);
@@ -90,6 +138,9 @@ fn make_valid_tls_client_hello_with_sni_and_alpn(
     sni_host: &str,
     alpn_protocols: &[&[u8]],
 ) -> Vec<u8> {
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const X25519_KEY_SHARE_LEN: usize = 32;
+
     let mut body = Vec::new();
     body.extend_from_slice(&TLS_VERSION);
     body.extend_from_slice(&[0u8; 32]);
@@ -112,6 +163,19 @@ fn make_valid_tls_client_hello_with_sni_and_alpn(
     ext_blob.extend_from_slice(&(sni_payload.len() as u16).to_be_bytes());
     ext_blob.extend_from_slice(&sni_payload);
 
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    ext_blob.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    ext_blob.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    ext_blob.extend_from_slice(&key_share_extension);
+
     if !alpn_protocols.is_empty() {
         let mut alpn_list = Vec::new();
         for proto in alpn_protocols {

src/proxy/tests/handshake_real_bug_stress_tests.rs

@@ -24,6 +24,9 @@ fn make_valid_tls_client_hello_with_alpn(
     timestamp: u32,
     alpn_protocols: &[&[u8]],
 ) -> Vec<u8> {
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const X25519_KEY_SHARE_LEN: usize = 32;
+
     let mut body = Vec::new();
     body.extend_from_slice(&TLS_VERSION);
     body.extend_from_slice(&[0u8; 32]);
@@ -35,6 +38,19 @@ fn make_valid_tls_client_hello_with_alpn(
     body.push(0);
 
     let mut ext_blob = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    ext_blob.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    ext_blob.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    ext_blob.extend_from_slice(&key_share_extension);
+
     if !alpn_protocols.is_empty() {
         let mut alpn_list = Vec::new();
         for proto in alpn_protocols {

src/proxy/tests/handshake_security_tests.rs

@@ -10,11 +10,62 @@ use std::time::{Duration, Instant};
 use tokio::sync::Barrier;
 
 fn make_valid_tls_handshake(secret: &[u8], timestamp: u32) -> Vec<u8> {
-    let session_id_len: usize = 32;
-    let len = tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN + 1 + session_id_len;
-    let mut handshake = vec![0x42u8; len];
+    make_valid_tls_handshake_with_fill(secret, timestamp, 0x42)
+}
 
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
+fn make_valid_tls_handshake_with_fill(secret: &[u8], timestamp: u32, fill: u8) -> Vec<u8> {
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const X25519_KEY_SHARE_LEN: usize = 32;
+    let session_id_len: usize = 32;
+
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let body_len = 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + 4 + body_len);
+    handshake.push(TLS_RECORD_HANDSHAKE);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&((4 + body_len) as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
 
     let computed = sha256_hmac(secret, &handshake);
@@ -34,6 +85,9 @@ fn make_valid_tls_client_hello_with_alpn(
     timestamp: u32,
     alpn_protocols: &[&[u8]],
 ) -> Vec<u8> {
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const X25519_KEY_SHARE_LEN: usize = 32;
+
     let mut body = Vec::new();
     body.extend_from_slice(&TLS_VERSION);
     body.extend_from_slice(&[0u8; 32]);
@@ -45,6 +99,19 @@ fn make_valid_tls_client_hello_with_alpn(
     body.push(0);
 
     let mut ext_blob = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    ext_blob.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    ext_blob.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    ext_blob.extend_from_slice(&key_share_extension);
+
     if !alpn_protocols.is_empty() {
         let mut alpn_list = Vec::new();
         for proto in alpn_protocols {
@@ -92,6 +159,9 @@ fn make_valid_tls_client_hello_with_sni_and_alpn(
     sni_host: &str,
     alpn_protocols: &[&[u8]],
 ) -> Vec<u8> {
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const X25519_KEY_SHARE_LEN: usize = 32;
+
     let mut body = Vec::new();
     body.extend_from_slice(&TLS_VERSION);
     body.extend_from_slice(&[0u8; 32]);
@@ -114,6 +184,19 @@ fn make_valid_tls_client_hello_with_sni_and_alpn(
     ext_blob.extend_from_slice(&(sni_payload.len() as u16).to_be_bytes());
     ext_blob.extend_from_slice(&sni_payload);
 
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    ext_blob.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    ext_blob.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    ext_blob.extend_from_slice(&key_share_extension);
+
     if !alpn_protocols.is_empty() {
         let mut alpn_list = Vec::new();
         for proto in alpn_protocols {
@@ -549,25 +632,6 @@ async fn adversarial_tls_replay_churn_allows_only_unique_digests() {
     let replay_checker = Arc::new(ReplayChecker::new(8192, Duration::from_secs(60)));
     let rng = Arc::new(SecureRandom::new());
 
-    let make_tagged_handshake = |timestamp: u32, tag: u8| {
-        let session_id_len: usize = 32;
-        let len = tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN + 1 + session_id_len;
-        let mut handshake = vec![tag; len];
-
-        handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
-        handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
-        let computed = sha256_hmac(&secret, &handshake);
-        let mut digest = computed;
-        let ts = timestamp.to_le_bytes();
-        for i in 0..4 {
-            digest[28 + i] ^= ts[i];
-        }
-
-        handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN]
-            .copy_from_slice(&digest);
-        handshake
-    };
-
     let mut tasks = Vec::new();
 
     // 128 exact duplicates: only one should pass.
@@ -596,12 +660,17 @@ async fn adversarial_tls_replay_churn_allows_only_unique_digests() {
         }));
     }
 
-    // 128 unique timestamps: all should pass because HMAC digest differs.
+    // 128 unique ClientHello bodies: all should pass because replay tracks the
+    // first digest half, while timestamp skew is encoded in the last bytes.
     for i in 0..128u16 {
         let config = Arc::clone(&config);
         let replay_checker = Arc::clone(&replay_checker);
         let rng = Arc::clone(&rng);
-        let handshake = make_tagged_handshake(10_000 + i as u32, (i as u8).wrapping_add(0x80));
+        let handshake = make_valid_tls_handshake_with_fill(
+            &secret,
+            10_000 + i as u32,
+            (i as u8).wrapping_add(0x80),
+        );
         tasks.push(tokio::spawn(async move {
             let peer = SocketAddr::new(
                 IpAddr::V4(Ipv4Addr::new(198, 18, 0, ((i % 250) + 1) as u8)),

src/proxy/tests/handshake_timing_manual_bench_tests.rs

@@ -47,11 +47,59 @@ fn make_valid_mtproto_handshake(
 }
 
 fn make_valid_tls_handshake(secret: &[u8], timestamp: u32) -> Vec<u8> {
+    const TLS_AES_128_GCM_SHA256: [u8; 2] = [0x13, 0x01];
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const X25519_KEY_SHARE_LEN: usize = 32;
     let session_id_len: usize = 32;
-    let len = tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN + 1 + session_id_len;
-    let mut handshake = vec![0x42u8; len];
+    let fill = 0x42u8;
 
-    handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN] = session_id_len as u8;
+    let mut extensions = Vec::new();
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    extensions.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    extensions.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    extensions.extend_from_slice(&key_share_extension);
+
+    let body_len = 2
+        + 32
+        + 1
+        + session_id_len
+        + 2
+        + TLS_AES_128_GCM_SHA256.len()
+        + 1
+        + 1
+        + 2
+        + extensions.len();
+    let mut body = Vec::with_capacity(body_len);
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[fill; 32]);
+    body.push(session_id_len as u8);
+    body.extend_from_slice(&[fill; 32]);
+    body.extend_from_slice(&(TLS_AES_128_GCM_SHA256.len() as u16).to_be_bytes());
+    body.extend_from_slice(&TLS_AES_128_GCM_SHA256);
+    body.push(1);
+    body.push(0);
+    body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+    body.extend_from_slice(&extensions);
+    assert_eq!(body.len(), body_len);
+
+    let mut handshake = Vec::with_capacity(5 + 4 + body_len);
+    handshake.push(TLS_RECORD_HANDSHAKE);
+    handshake.extend_from_slice(&[0x03, 0x01]);
+    handshake.extend_from_slice(&((4 + body_len) as u16).to_be_bytes());
+    handshake.push(0x01);
+    let body_len_bytes = (body_len as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len_bytes[1..4]);
+    handshake.extend_from_slice(&body);
+
+    // The proxy authenticates TLS-fronted clients through the random field.
     handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN].fill(0);
 
     let computed = sha256_hmac(secret, &handshake);
@@ -72,6 +120,9 @@ fn make_valid_tls_client_hello_with_sni_and_alpn(
     sni_host: &str,
     alpn_protocols: &[&[u8]],
 ) -> Vec<u8> {
+    const TLS_EXTENSION_KEY_SHARE: u16 = 0x0033;
+    const X25519_KEY_SHARE_LEN: usize = 32;
+
     let mut body = Vec::new();
     body.extend_from_slice(&TLS_VERSION);
     body.extend_from_slice(&[0u8; 32]);
@@ -93,6 +144,19 @@ fn make_valid_tls_client_hello_with_sni_and_alpn(
     ext_blob.extend_from_slice(&(sni_payload.len() as u16).to_be_bytes());
     ext_blob.extend_from_slice(&sni_payload);
 
+    let mut key_share = Vec::new();
+    key_share.extend_from_slice(&tls::TLS_NAMED_GROUP_X25519.to_be_bytes());
+    key_share.extend_from_slice(&(X25519_KEY_SHARE_LEN as u16).to_be_bytes());
+    key_share.push(9);
+    key_share.resize(key_share.len() + X25519_KEY_SHARE_LEN - 1, 0);
+
+    let mut key_share_extension = Vec::new();
+    key_share_extension.extend_from_slice(&(key_share.len() as u16).to_be_bytes());
+    key_share_extension.extend_from_slice(&key_share);
+    ext_blob.extend_from_slice(&TLS_EXTENSION_KEY_SHARE.to_be_bytes());
+    ext_blob.extend_from_slice(&(key_share_extension.len() as u16).to_be_bytes());
+    ext_blob.extend_from_slice(&key_share_extension);
+
     if !alpn_protocols.is_empty() {
         let mut alpn_list = Vec::new();
         for proto in alpn_protocols {

src/proxy/tests/masking_timing_budget_coupling_security_tests.rs

@@ -22,6 +22,7 @@ async fn adversarial_delayed_interface_lookup_does_not_consume_outcome_floor_bud
 
     let refresh_lock = LOCAL_INTERFACE_REFRESH_LOCK.get_or_init(|| AsyncMutex::new(()));
     let held_refresh_guard = refresh_lock.lock().await;
+    reset_local_interface_enumerations_for_tests();
 
     let (mut client, server) = duplex(1024);
     let started = Instant::now();

src/proxy/tests/middle_relay_idle_registry_poison_security_tests.rs

@@ -1,33 +1,21 @@
 use super::*;
-use std::panic::{AssertUnwindSafe, catch_unwind};
 
 #[test]
-fn blackhat_registry_poison_recovers_with_fail_closed_reset_and_pressure_accounting() {
+fn blackhat_registry_stale_order_entry_is_skipped_and_pressure_accounting_continues() {
     let shared = ProxySharedState::new();
     clear_relay_idle_pressure_state_for_testing_in_shared(shared.as_ref());
 
-    let _ = catch_unwind(AssertUnwindSafe(|| {
-        let mut guard = shared
-            .middle_relay
-            .relay_idle_registry
-            .lock()
-            .expect("registry lock must be acquired before poison");
-        guard.by_conn_id.insert(
-            999,
-            RelayIdleCandidateMeta {
-                mark_order_seq: 1,
-                mark_pressure_seq: 0,
-            },
-        );
-        guard.ordered.insert((1, 999));
-        panic!("intentional poison for idle-registry recovery");
-    }));
+    shared
+        .middle_relay
+        .relay_idle_registry
+        .ordered
+        .lock()
+        .insert((0, 999));
 
-    // Helper lock must recover from poison, reset stale state, and continue.
     assert!(mark_relay_idle_candidate_for_testing(shared.as_ref(), 42));
     assert_eq!(
         oldest_relay_idle_candidate_for_testing(shared.as_ref()),
-        Some(42)
+        Some(999)
     );
 
     let before = relay_pressure_event_seq_for_testing(shared.as_ref());
@@ -35,25 +23,43 @@ fn blackhat_registry_poison_recovers_with_fail_closed_reset_and_pressure_account
     let after = relay_pressure_event_seq_for_testing(shared.as_ref());
     assert!(
         after > before,
-        "pressure accounting must still advance after poison"
+        "pressure accounting must still advance with stale ordered entries"
+    );
+
+    let mut seen_pressure_seq = before;
+    assert!(maybe_evict_idle_candidate_on_pressure_for_testing(
+        shared.as_ref(),
+        42,
+        &mut seen_pressure_seq,
+        &Stats::new()
+    ));
+    assert_eq!(
+        oldest_relay_idle_candidate_for_testing(shared.as_ref()),
+        None
     );
 
     clear_relay_idle_pressure_state_for_testing_in_shared(shared.as_ref());
 }
 
 #[test]
-fn clear_state_helper_must_reset_poisoned_registry_for_deterministic_fifo_tests() {
+fn clear_state_helper_must_reset_split_registry_for_deterministic_fifo_tests() {
     let shared = ProxySharedState::new();
     clear_relay_idle_pressure_state_for_testing_in_shared(shared.as_ref());
 
-    let _ = catch_unwind(AssertUnwindSafe(|| {
-        let _guard = shared
-            .middle_relay
-            .relay_idle_registry
-            .lock()
-            .expect("registry lock must be acquired before poison");
-        panic!("intentional poison while lock held");
-    }));
+    shared.middle_relay.relay_idle_registry.by_conn_id.insert(
+        999,
+        RelayIdleCandidateMeta {
+            mark_order_seq: 1,
+            mark_pressure_seq: 0,
+        },
+    );
+    shared
+        .middle_relay
+        .relay_idle_registry
+        .ordered
+        .lock()
+        .insert((1, 999));
+    set_relay_pressure_state_for_testing(shared.as_ref(), 7, 6);
 
     clear_relay_idle_pressure_state_for_testing_in_shared(shared.as_ref());
 

src/proxy/tests/proxy_shared_state_isolation_tests.rs

@@ -61,6 +61,7 @@ fn new_client_harness() -> ClientHarness {
             selected_scope: String::new(),
             ipv4: None,
             ipv6: None,
+            prefer: None,
         }],
         1,
         1,