Rustfmt

Co-Authored-By: brekotis <93345790+brekotis@users.noreply.github.com>

CONTRIBUTING.md

@@ -1,18 +1,20 @@
 # Issues
-## Warnung
+### Warnung
+
 Before opening Issue, if it is more question than problem or bug - ask about that [in our chat](https://t.me/telemtrs)
 
-## What it is not
-- NOT Question and Answer
-- NOT Helpdesk
-
 ***Each of your Issues triggers attempts to reproduce problems and analyze them, which are done manually by people***
 
+Issues is **NOT** about:
+- Question and Answer
+- Helpdesk
+- Configuration or Intergraion Support
+
 ---
 
 # Pull Requests
 
-## General
+### General
 - ONLY signed and verified commits
 - ONLY from your name
 - DO NOT commit with `codex`, `claude`, or other AI tools as author/committer
@@ -20,7 +22,7 @@ Before opening Issue, if it is more question than problem or bug - ask about tha
 
 ---
 
-## Definition of Ready (MANDATORY)
+### Definition of Ready (MANDATORY)
 
 A Pull Request WILL be ignored or closed if:
 
@@ -32,14 +34,14 @@ A Pull Request WILL be ignored or closed if:
 
 ---
 
-## Blessed Principles
+### Blessed Principles
 - PR must build
 - PR must pass tests
 - PR must be understood by author
 
 ---
 
-## AI Usage Policy
+### AI Usage Policy
 
 AI tools (Claude, ChatGPT, Codex, DeepSeek, etc.) are allowed as **assistants**, NOT as decision-makers.
 
@@ -60,7 +62,7 @@ PRs that look like unverified AI dumps WILL be closed
 
 ---
 
-## Maintainer Policy
+### Maintainer Policy
 
 Maintainers reserve the right to:
 
@@ -72,7 +74,7 @@ Respect the reviewers time
 
 ---
 
-## Enforcement
+### Enforcement
 
 Pull Requests that violate project standards may be closed without review.
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "telemt"
-version = "3.4.14"
+version = "3.4.24"
 edition = "2024"
 
 [features]
@@ -8,88 +8,90 @@ redteam_offline_expected_fail = []
 
 [dependencies]
 # C
-libc = "0.2"
+libc = "0.2.186"
 
 # Async runtime
-tokio = { version = "1.42", features = ["full", "tracing"] }
-tokio-util = { version = "0.7", features = ["full"] }
+tokio = { version = "1.52.3", features = ["full", "tracing"] }
+tokio-util = { version = "0.7.18", features = ["full"] }
 
 # Crypto
-aes = "0.8"
-ctr = "0.9"
-cbc = "0.1"
-sha2 = "0.10"
-sha1 = "0.10"
-md-5 = "0.10"
-hmac = "0.12"
-crc32fast = "1.4"
-crc32c = "0.6"
-zeroize = { version = "1.8", features = ["derive"] }
-subtle = "2.6"
-static_assertions = "1.1"
+aes = { version = "0.8.4", features = ["zeroize"] }
+ctr = { version = "0.9.2", features = ["zeroize"] }
+cbc = "0.1.2"
+sha2 = "0.10.9"
+sha1 = "0.10.6"
+md-5 = "0.10.6"
+hmac = "0.12.1"
+crc32fast = "1.5.0"
+crc32c = "0.6.8"
+zeroize = { version = "1.9.0", features = ["derive"] }
+subtle = "2.6.1"
+static_assertions = "1.1.0"
+ml-kem = { version = "0.3.2", default-features = false, features = ["alloc", "zeroize"] }
 
 # Network
-socket2 = { version = "0.6", features = ["all"] }
-nix = { version = "0.31", default-features = false, features = [
+socket2 = { version = "0.6.4", features = ["all"] }
+nix = { version = "0.31.3", default-features = false, features = [
   "net",
   "user",
   "process",
   "fs",
   "signal",
 ] }
-shadowsocks = { version = "1.24", features = ["aead-cipher-2022"] }
+shadowsocks = { version = "1.24.0", features = ["aead-cipher-2022"] }
 
 # Serialization
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1.0"
-toml = "1.0"
-x509-parser = "0.18"
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.150"
+toml = "1.1"
+x509-parser = "0.18.1"
 
 # Utils
-bytes = "1.9"
-thiserror = "2.0"
-tracing = "0.1"
-tracing-subscriber = { version = "0.3", features = ["env-filter"] }
-tracing-appender = "0.2"
-parking_lot = "0.12"
-dashmap = "6.1"
-arc-swap = "1.7"
-lru = "0.16"
-rand = "0.10"
-chrono = { version = "0.4", features = ["serde"] }
-hex = "0.4"
-base64 = "0.22"
-url = "2.5"
-regex = "1.11"
-crossbeam-queue = "0.3"
-num-bigint = "0.4"
-num-traits = "0.2"
-x25519-dalek = "2"
-anyhow = "1.0"
+bytes = "1.12.0"
+thiserror = "2.0.18"
+tracing = "0.1.44"
+tracing-subscriber = { version = "0.3.23", features = ["env-filter"] }
+tracing-appender = "0.2.5"
+parking_lot = "0.12.5"
+dashmap = "6.2.1"
+arc-swap = "1.9.1"
+lru = "0.16.4"
+rand = "0.10.1"
+chrono = { version = "0.4.45", features = ["serde"] }
+hex = "0.4.3"
+base64 = "0.22.1"
+url = "2.5.8"
+regex = "1.12.4"
+crossbeam-queue = "0.3.12"
+num-bigint = "0.4.6"
+num-traits = "0.2.19"
+x25519-dalek = "2.0.1"
+anyhow = "1.0.102"
 
 # HTTP
-reqwest = { version = "0.13", features = ["rustls"], default-features = false }
-notify = "8.2"
-ipnetwork = { version = "0.21", features = ["serde"] }
-hyper = { version = "1", features = ["server", "http1"] }
-hyper-util = { version = "0.1", features = ["tokio", "server-auto"] }
-http-body-util = "0.1"
-httpdate = "1.0"
-tokio-rustls = { version = "0.26", default-features = false, features = [
+reqwest = { version = "0.13.4", features = ["rustls"], default-features = false }
+notify = "8.2.0"
+ipnetwork = { version = "0.21.1", features = ["serde"] }
+hyper = { version = "1.10.1", features = ["server", "http1"] }
+hyper-util = { version = "0.1.20", features = ["tokio", "server-auto"] }
+http-body-util = "0.1.3"
+httpdate = "1.0.3"
+tokio-rustls = { version = "0.26.4", default-features = false, features = [
   "tls12",
 ] }
-rustls = { version = "0.23", default-features = false, features = [
+rustls = { version = "0.23.41", default-features = false, features = [
   "std",
   "tls12",
   "ring",
 ] }
-webpki-roots = "1.0"
+webpki-roots = "1.0.8"
 
 [dev-dependencies]
-tokio-test = "0.4"
-criterion = "0.8"
-proptest = "1.4"
-futures = "0.3"
+tokio-test = "0.4.5"
+criterion = "0.8.2"
+proptest = "1.11.0"
+futures = "0.3.32"
+tempfile = "3.27.0"
 
 [[bench]]
 name = "crypto_bench"

Dockerfile

@@ -55,6 +55,16 @@ RUN set -eux; \
     strip --strip-unneeded /telemt || true; \
     rm -f "/tmp/${ASSET}" "/tmp/${ASSET}.sha256" /tmp/telemt
 
+RUN --mount=type=bind,target=/tmp \
+    mkdir -p /app && \
+    if [ -f /tmp/config.toml ]; then \
+        cp /tmp/config.toml /app/config.toml; \
+    elif [ -f /tmp/config/config.toml ]; then \
+        cp /tmp/config/config.toml /app/config.toml; \
+    else \
+        echo "Config file not found" && exit 1; \
+    fi
+
 # ==========================
 # Debug Image
 # ==========================
@@ -73,7 +83,7 @@ RUN set -eux; \
 WORKDIR /app
 
 COPY --from=minimal /telemt /app/telemt
-COPY config.toml /app/config.toml
+COPY ./config/config.toml /app/config.toml
 
 EXPOSE 443 9090 9091
 
@@ -99,7 +109,7 @@ RUN set -eux; \
 WORKDIR /app
 
 COPY --from=minimal /telemt /app/telemt
-COPY config.toml /app/config.toml
+COPY --from=minimal /app/config.toml /app/config.toml
 
 EXPOSE 443 9090 9091
 
@@ -116,7 +126,7 @@ FROM gcr.io/distroless/static-debian12 AS prod
 WORKDIR /app
 
 COPY --from=minimal /telemt /app/telemt
-COPY config.toml /app/config.toml
+COPY --from=minimal /app/config.toml /app/config.toml
 
 USER nonroot:nonroot
 

README.md

@@ -8,7 +8,7 @@
 >
 > From June 5th, 2026: we are already analyzing the causes of a new wave of "malfunctions"
 > 
-> Telegram Clients TLS ClientHello has been banned by JA3 Fingerprint: we are already looking for ways to solve this problem
+> Telegram Clients TLS ClientHello has been banned by JA4/JA4+ 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)
 

benches/crypto_bench.rs

@@ -1,12 +1,24 @@
-// Cryptobench
-use criterion::{Criterion, black_box, criterion_group};
+use criterion::{Criterion, criterion_group, criterion_main};
+use std::hint::black_box;
+
+#[allow(unused_imports)]
+#[path = "../src/crypto/aes.rs"]
+mod aes_impl;
+#[allow(unused_imports)]
+#[path = "../src/error.rs"]
+mod error;
+
+use aes_impl::AesCtr;
 
 fn bench_aes_ctr(c: &mut Criterion) {
     c.bench_function("aes_ctr_encrypt_64kb", |b| {
         let data = vec![0u8; 65536];
         b.iter(|| {
             let mut enc = AesCtr::new(&[0u8; 32], 0);
-            black_box(enc.encrypt(&data))
+            black_box(enc.encrypt(black_box(data.as_slice())))
         })
     });
 }
+
+criterion_group!(benches, bench_aes_ctr);
+criterion_main!(benches);

docker-compose.host-netfilter.yml

@@ -4,7 +4,6 @@ services:
       context: .
       target: prod-netfilter
     network_mode: host
-    ports: []
+    ports: !reset []
     cap_add:
-      - NET_BIND_SERVICE
-      - NET_ADMIN
+      - NET_ADMIN

docs/Architecture/API/API.md

@@ -106,6 +106,8 @@ Notes:
 | `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` |
@@ -143,6 +145,8 @@ 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. |
@@ -158,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`. |
@@ -177,6 +183,7 @@ 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`. |
@@ -212,8 +219,8 @@ 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. |
 
@@ -225,8 +232,8 @@ 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. |
 
@@ -245,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 |
 | --- | --- | --- | --- |
@@ -254,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 |
 | --- | --- | --- |
@@ -1217,8 +1263,8 @@ JA3 follows the Salesforce ClientHello field order. JA4 follows the FoxIO TLS-cl
 | `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. |
@@ -1279,10 +1325,101 @@ 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`. |

docs/Config_params/CONFIG_PARAMS.en.md

@@ -14,6 +14,7 @@ This document lists all configuration keys accepted by `config.toml`.
 
 # Table of contents
  - [Top-level keys](#top-level-keys)
+ - [logging](#logging)
  - [general](#general)
  - [general.modes](#generalmodes)
  - [general.links](#generallinks)
@@ -35,6 +36,7 @@ This document lists all configuration keys accepted by `config.toml`.
 | --- | ---- | ------- | ---------- |
 | [`include`](#include) | `String` (special directive) | — | `✔` |
 | [`show_link`](#show_link) | `"*"` or `String[]` | `[]` (`ShowLink::None`) | `✘` |
+| [`logging`](#logging) | Table | default values | `✘` |
 | [`dc_overrides`](#dc_overrides) | `Map<String, String or String[]>` | `{}` | `✘` |
 | [`default_dc`](#default_dc) | `u8` | — (effective fallback: `2` in ME routing) | `✘` |
 | [`beobachten`](#beobachten) | `bool` | `true` | `✘` |
@@ -83,6 +85,84 @@ This document lists all configuration keys accepted by `config.toml`.
     default_dc = 2
     ```
 
+# [logging]
+
+| Key | Type | Default | Hot-Reload |
+| --- | ---- | ------- | ---------- |
+| [`destination`](#loggingdestination) | `"stderr"` / `"syslog"` / `"file"` | `"stderr"` | `✘` |
+| [`path`](#loggingpath) | `String` | — | `✘` |
+| [`rotation`](#loggingrotation) | `"never"` / `"minutely"` / `"hourly"` / `"daily"` / `"weekly"` | `"never"` | `✘` |
+| [`max_size_bytes`](#loggingmax_size_bytes) | `u64` | `0` | `✘` |
+| [`max_files`](#loggingmax_files) | `usize` | `0` | `✘` |
+| [`max_age_secs`](#loggingmax_age_secs) | `u64` | `0` | `✘` |
+
+## logging.destination
+  - **Constraints / validation**: Must be `stderr`, `syslog`, or `file`. `syslog` is supported only on Unix platforms. `file` requires `logging.path`.
+  - **Description**: Selects the runtime log destination. CLI flags override this value.
+  - **Example**:
+
+    ```toml
+    [logging]
+    destination = "file"
+    path = "/var/log/telemt.log"
+    ```
+## logging.path
+  - **Constraints / validation**: Required when `logging.destination = "file"`; must not be empty.
+  - **Description**: File path used for file logging. With time rotation, the file name is used as the rolling prefix.
+  - **Example**:
+
+    ```toml
+    [logging]
+    destination = "file"
+    path = "/var/log/telemt.log"
+    ```
+## logging.rotation
+  - **Constraints / validation**: Must be `never`, `minutely`, `hourly`, `daily`, or `weekly`.
+  - **Description**: Time-based file rotation interval. `weekly` rotates at the Sunday UTC boundary. `never` writes to the exact `logging.path` unless size rotation is enabled.
+  - **Example**:
+
+    ```toml
+    [logging]
+    destination = "file"
+    path = "/var/log/telemt.log"
+    rotation = "daily"
+    ```
+## logging.max_size_bytes
+  - **Constraints / validation**: `0` disables size rotation.
+  - **Description**: Rotates file logs before writing the next record when the active file is non-empty and that record would exceed this byte limit. Records are written whole and are not split.
+  - **Example**:
+
+    ```toml
+    [logging]
+    destination = "file"
+    path = "/var/log/telemt.log"
+    max_size_bytes = 104857600
+    ```
+## logging.max_files
+  - **Constraints / validation**: `0` disables count-based retention.
+  - **Description**: Keeps at most this many matching file logs, counting the active file and rotated archives. The active file is never deleted by retention cleanup.
+  - **Example**:
+
+    ```toml
+    [logging]
+    destination = "file"
+    path = "/var/log/telemt.log"
+    rotation = "daily"
+    max_files = 14
+    ```
+## logging.max_age_secs
+  - **Constraints / validation**: `0` disables age-based retention.
+  - **Description**: Removes rotated file logs older than this many seconds based on file modification time. The active file is never deleted by retention cleanup.
+  - **Example**:
+
+    ```toml
+    [logging]
+    destination = "file"
+    path = "/var/log/telemt.log"
+    rotation = "daily"
+    max_age_secs = 1209600
+    ```
+
 # [general]
 
 
@@ -1805,6 +1885,8 @@ This document lists all configuration keys accepted by `config.toml`.
 | [`listen_unix_sock`](#listen_unix_sock) | `String` | — | `✘` |
 | [`listen_unix_sock_perm`](#listen_unix_sock_perm) | `String` | — | `✘` |
 | [`listen_tcp`](#listen_tcp) | `bool` | — (auto) | `✘` |
+| [`client_mss`](#client_mss) | `String` | `""` | `✘` |
+| [`client_mss_bulk`](#client_mss_bulk) | `String` | `""` | `✘` |
 | [`proxy_protocol`](#proxy_protocol) | `bool` | `false` | `✘` |
 | [`proxy_protocol_header_timeout_ms`](#proxy_protocol_header_timeout_ms) | `u64` | `500` | `✘` |
 | [`proxy_protocol_trusted_cidrs`](#proxy_protocol_trusted_cidrs) | `IpNetwork[]` | `[]` | `✘` |
@@ -1887,6 +1969,27 @@ This document lists all configuration keys accepted by `config.toml`.
     listen_unix_sock = "/run/telemt.sock"
     listen_tcp = true
     ```
+## client_mss
+  - **Constraints / validation**: `String`. Empty or omitted means do not change kernel MSS. Presets: `"extreme-low"` = `88`, `"tspu"` = `92`, `"2in8"` = `256`. Custom decimal strings must be within `88..=4096`.
+  - **Description**: Client-facing TCP MSS applied to TCP listener sockets before `listen(2)`, so Linux can announce it in SYN/ACK. This affects only proxy client TCP listeners, not API, metrics, Unix sockets, Telegram upstreams, ME sockets, or mask backend connections. Changes require listener restart/rebind.
+  - **Operator note**: The two-tier `synlimit` profile does not require Telemt to disable MSS automatically. Operators that follow external host-tuning recipes should decide explicitly whether to leave MSS shaping enabled for handshake fragmentation or disable it for higher media throughput.
+  - **Performance note**: Low MSS increases packet count predictably. Approximate segment multiplier is `ceil(1460 / client_mss)`.
+  - **Example**:
+
+    ```toml
+    [server]
+    client_mss = "tspu"
+    ```
+## client_mss_bulk
+  - **Constraints / validation**: `String`. Same grammar as [`client_mss`](#client_mss) (empty/omitted, presets `"extreme-low"`/`"tspu"`/`"2in8"`, or a decimal in `88..=4096`).
+  - **Description**: Optional bulk-phase MSS. When set, the low `client_mss` is applied only while the TLS handshake (including the DPI-inspected ServerHello) is sent; once the connection transitions to relaying, the client socket MSS is raised to `client_mss_bulk` for the bulk data phase. This keeps the anti-DPI handshake fragmentation but restores normal-size packets for payload, cutting outgoing packets-per-second by roughly the `client_mss` segment multiplier (e.g. ~10x with `"tspu"`). Useful on hosts whose abuse detection counts packets-per-second rather than bandwidth. When empty/omitted, the handshake MSS is kept for the whole connection (previous behavior). Linux only; a no-op elsewhere.
+  - **Example**:
+
+    ```toml
+    [server]
+    client_mss = "tspu"
+    client_mss_bulk = "1400"
+    ```
 ## proxy_protocol
   - **Constraints / validation**: `bool`.
   - **Description**: Enables HAProxy PROXY protocol parsing on incoming connections (PROXY v1/v2). When enabled, client source address is taken from the PROXY header.
@@ -2207,6 +2310,16 @@ Note: This section also accepts the legacy alias `[server.admin_api]` (same sche
 | --- | ---- | ------- | ---------- |
 | [`ip`](#ip) | `IpAddr` | — | `✘` |
 | [`port`](#port-serverlisteners) | `u16` | `server.port` | `✘` |
+| [`client_mss`](#client_mss-serverlisteners) | `String` | `[server].client_mss` | `✘` |
+| [`synlimit`](#synlimit-serverlisteners) | `false`, `"iptables"`, or `"nftables"` | `false` | `✔` |
+| [`synlimit_seconds`](#synlimit_seconds-serverlisteners) | `u32` | `60` | `✔` |
+| [`synlimit_hitcount`](#synlimit_hitcount-serverlisteners) | `u32` | `48` | `✔` |
+| [`synlimit_burst`](#synlimit_burst-serverlisteners) | `u32` | `1` | `✔` |
+| [`synlimit_ios_seconds`](#synlimit_ios_seconds-serverlisteners) | `u32` | `1` | `✔` |
+| [`synlimit_ios_hitcount`](#synlimit_ios_hitcount-serverlisteners) | `u32` | `12` | `✔` |
+| [`synlimit_ios_burst`](#synlimit_ios_burst-serverlisteners) | `u32` | `24` | `✔` |
+| [`synlimit_hashlimit_expire_ms`](#synlimit_hashlimit_expire_ms-serverlisteners) | `u32` | `60000` | `✔` |
+| [`synlimit_hashlimit_size`](#synlimit_hashlimit_size-serverlisteners) | `u32` | `32768` | `✔` |
 | [`announce`](#announce) | `String` | — | `✘` |
 | [`announce_ip`](#announce_ip) | `IpAddr` | — | `✘` |
 | [`proxy_protocol`](#proxy_protocol) | `bool` | — | `✘` |
@@ -2231,6 +2344,130 @@ Note: This section also accepts the legacy alias `[server.admin_api]` (same sche
     ip = "0.0.0.0"
     port = 443
     ```
+## client_mss (server.listeners)
+  - **Constraints / validation**: `String` (optional). Same values as `[server].client_mss`.
+  - **Description**: Per-listener MSS override. When omitted, inherits `[server].client_mss`; when set to an empty string, disables MSS shaping for this listener even if the global value is set. Changes require listener restart/rebind.
+  - **Example**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    client_mss = "256"
+    ```
+## synlimit (server.listeners)
+  - **Constraints / validation**: `false`, `"iptables"`, or `"nftables"`. Omitted or `false` disables SYN limiting for this listener.
+  - **Description**: Installs per-listener Linux netfilter two-tier SYN-fix rules for the listener port. `"iptables"` uses `iptables`/`ip6tables` filter rules with the `hashlimit`, `length`, and TTL/hop-limit matches. `"nftables"` uses Telemt-owned tables with per-source `meter` rules and equivalent IPv4/IPv6 classifiers. Rules are inserted early in `INPUT`, accept under-limit SYN packets, and reject over-limit SYN packets with TCP RST so clients retry promptly instead of waiting for a silent DROP timeout. The generic bucket is controlled by `synlimit_seconds`, `synlimit_hitcount`, and `synlimit_burst`; the iOS-like TTL/length bucket is controlled by `synlimit_ios_*`. Rules are reconciled at runtime and removed during graceful Telemt shutdown; `SIGKILL` cannot be cleaned up by the process. Requires CAP_NET_ADMIN. `synlimit*` changes hot-reload for existing listener endpoints; changing listener `ip` or `port` still requires restart/rebind.
+  - **Operator note**: Telemt does not persist rules with `iptables-persistent`, write `/etc/sysctl.d`, edit systemd limits, or modify `client_mss`. Apply host-level tuning manually if your deployment policy requires it.
+  - **Example**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+
+    [[server.listeners]]
+    ip = "::"
+    port = 443
+    synlimit = "nftables"
+    ```
+## synlimit_seconds (server.listeners)
+  - **Constraints / validation**: `u32`, must be `> 0`. Default is `60`.
+  - **Description**: Generic SYN-fix token-bucket interval. The rate is `synlimit_hitcount / synlimit_seconds` and is rendered to native netfilter rate units (`second`, `minute`, `hour`, or `day`). This bucket handles SYN packets that do not match the iOS-like TTL/length classifier.
+  - **Example**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_seconds = 60
+    ```
+## synlimit_hitcount (server.listeners)
+  - **Constraints / validation**: `u32`, must be `> 0`. Default is `48`.
+  - **Description**: Generic SYN-fix token-bucket rate amount. Together with `synlimit_seconds`, it defines the allowed source-IP SYN rate before excess SYN packets receive TCP RST.
+  - **Example**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_hitcount = 48
+    ```
+## synlimit_burst (server.listeners)
+  - **Constraints / validation**: `u32`, must be `> 0`. Default is `1`.
+  - **Description**: Generic SYN-fix token-bucket burst size. Higher values allow short connection bursts from the same source IP before the steady-state `synlimit_hitcount / synlimit_seconds` rate is enforced.
+  - **Example**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_burst = 1
+    ```
+## synlimit_ios_seconds (server.listeners)
+  - **Constraints / validation**: `u32`, must be `> 0`. Default is `1`.
+  - **Description**: Token-bucket interval for SYN packets matching the iOS-like classifier. IPv4 matches packet length `64` and TTL `< 65`; IPv6 matches packet length `84` and hop limit `< 65`.
+  - **Example**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_ios_seconds = 1
+    ```
+## synlimit_ios_hitcount (server.listeners)
+  - **Constraints / validation**: `u32`, must be `> 0`. Default is `12`.
+  - **Description**: Token-bucket rate amount for the iOS-like SYN classifier.
+  - **Example**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_ios_hitcount = 12
+    ```
+## synlimit_ios_burst (server.listeners)
+  - **Constraints / validation**: `u32`, must be `> 0`. Default is `24`.
+  - **Description**: Token-bucket burst size for the iOS-like SYN classifier.
+  - **Example**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_ios_burst = 24
+    ```
+## synlimit_hashlimit_expire_ms (server.listeners)
+  - **Constraints / validation**: `u32`, must be `> 0`. Default is `60000`.
+  - **Description**: Entry expiration in milliseconds for iptables/ip6tables hashlimit buckets. nftables meters use kernel-managed state and do not expose this exact knob.
+  - **Example**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_hashlimit_expire_ms = 60000
+    ```
+## synlimit_hashlimit_size (server.listeners)
+  - **Constraints / validation**: `u32`, must be `> 0`. Default is `32768`.
+  - **Description**: Hash table size for iptables/ip6tables hashlimit buckets. nftables meters use kernel-managed state and do not expose this exact knob.
+  - **Example**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_hashlimit_size = 32768
+    ```
 ## announce
   - **Constraints / validation**: `String` (optional). Must not be empty when set.
   - **Description**: Public IP/domain announced in proxy links for this listener. Takes precedence over `announce_ip`.
@@ -2949,7 +3186,7 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p
 | [`replay_window_secs`](#replay_window_secs) | `u64` | `120` | `✘` |
 | [`ignore_time_skew`](#ignore_time_skew) | `bool` | `false` | `✘` |
 | [`user_rate_limits`](#user_rate_limits) | `Map<String, RateLimitBps>` | `{}` | `✔` |
-| [`cidr_rate_limits`](#cidr_rate_limits) | `Map<IpNetwork, RateLimitBps>` | `{}` | `✔` |
+| [`cidr_rate_limits`](#cidr_rate_limits) | `Map<CidrRateLimitKey, RateLimitBps>` | `{}` | `✔` |
 
 ## users
   - **Constraints / validation**: Must not be empty (at least one user must exist). Each value must be **exactly 32 hex characters**.
@@ -3104,7 +3341,7 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p
 
 ## user_rate_limits
   - **Constraints / validation**: Table `username -> { up_bps, down_bps }`. At least one direction must be non-zero.
-  - **Description**: Per-user bandwidth caps in bytes/sec for upload (`up_bps`) and download (`down_bps`).
+  - **Description**: Per-user bandwidth caps in bits/sec for upload (`up_bps`) and download (`down_bps`).
   - **Example**:
 
     ```toml
@@ -3112,13 +3349,15 @@ If your backend or network is very bandwidth-constrained, reduce cap first. If p
     alice = { up_bps = 1048576, down_bps = 2097152 }
     ```
 ## cidr_rate_limits
-  - **Constraints / validation**: Table `CIDR -> { up_bps, down_bps }`. CIDR must parse as `IpNetwork`; at least one direction must be non-zero.
-  - **Description**: Source-subnet bandwidth caps applied alongside per-user limits.
+  - **Constraints / validation**: Table `CIDR or auto-template -> { up_bps, down_bps }`. Explicit CIDR keys must parse as `IpNetwork`; auto-template keys must be `*4/N` (`N=0..32`), `*6/N` (`N=0..128`), or `*/N` (`N=0..32`). At least one direction must be non-zero. Duplicate normalized auto-templates are rejected.
+  - **Description**: Source-subnet bandwidth caps applied alongside per-user limits. Explicit CIDR rules use longest-prefix-wins and take priority over auto-templates. Auto-templates create buckets lazily per matched source subnet: `*4/N` for IPv4, `*6/N` for IPv6, and `*/N` as a dual-stack shorthand where IPv4 uses `/N` and IPv6 uses `/(N * 4)`.
   - **Example**:
 
     ```toml
     [access.cidr_rate_limits]
     "203.0.113.0/24" = { up_bps = 0, down_bps = 1048576 }
+    "*4/32" = { up_bps = 262144, down_bps = 1048576 }
+    "*6/64" = { up_bps = 262144, down_bps = 1048576 }
     ```
 # [[upstreams]]
 

docs/Config_params/CONFIG_PARAMS.ru.md

@@ -1807,6 +1807,8 @@
 | [`listen_unix_sock`](#listen_unix_sock) | `String` | — | `✘` |
 | [`listen_unix_sock_perm`](#listen_unix_sock_perm) | `String` | — | `✘` |
 | [`listen_tcp`](#listen_tcp) | `bool` | — (auto) | `✘` |
+| [`client_mss`](#client_mss) | `String` | `""` | `✘` |
+| [`client_mss_bulk`](#client_mss_bulk) | `String` | `""` | `✘` |
 | [`proxy_protocol`](#proxy_protocol) | `bool` | `false` | `✘` |
 | [`proxy_protocol_header_timeout_ms`](#proxy_protocol_header_timeout_ms) | `u64` | `500` | `✘` |
 | [`proxy_protocol_trusted_cidrs`](#proxy_protocol_trusted_cidrs) | `IpNetwork[]` | `[]` | `✘` |
@@ -1889,6 +1891,27 @@
     listen_unix_sock = "/run/telemt.sock"
     listen_tcp = true
     ```
+## client_mss
+  - **Ограничения / валидация**: `String`. Пустое значение или отсутствие параметра означает, что Telemt не изменяет MSS, выбранный ядром. Поддерживаемые presets: `"extreme-low"` = `88`, `"tspu"` = `92`, `"2in8"` = `256`. Пользовательское десятичное значение должно быть строкой в диапазоне `88..=4096`.
+  - **Описание**: MSS для входящих TCP-соединений клиентов. Значение применяется к TCP listener-сокетам до `listen(2)`, чтобы Linux мог объявить его в SYN/ACK. Параметр влияет только на proxy client TCP listeners и не применяется к API, metrics, Unix sockets, Telegram upstreams, ME sockets или mask backend connections. Изменение требует restart/rebind listener’ов.
+  - **Operator note**: Two-tier `synlimit` profile больше не требует автоматического отключения MSS внутри Telemt. Оператор должен сам решить, оставлять MSS shaping для handshake fragmentation или отключать его ради более высокой скорости media.
+  - **Performance note**: Низкий MSS предсказуемо увеличивает количество TCP-сегментов. Приблизительный multiplier: `ceil(1460 / client_mss)`.
+  - **Пример**:
+
+    ```toml
+    [server]
+    client_mss = "tspu"
+    ```
+## client_mss_bulk
+  - **Ограничения / валидация**: `String`. Грамматика та же, что у [`client_mss`](#client_mss) (пусто/не задано, пресеты `"extreme-low"`/`"tspu"`/`"2in8"` либо десятичное число в диапазоне `88..=4096`).
+  - **Описание**: Необязательный MSS для bulk-фазы. Если задан, низкий `client_mss` применяется только на время TLS-handshake (включая инспектируемый DPI ServerHello); как только соединение переходит в фазу relay, MSS клиентского сокета поднимается до `client_mss_bulk` для передачи полезной нагрузки. Так сохраняется anti-DPI фрагментация handshake, но для данных возвращаются пакеты нормального размера — это снижает исходящий packets-per-second примерно во столько раз, каков segment multiplier у `client_mss` (например, ~10x для `"tspu"`). Полезно на хостингах, где abuse-детекция считает packets-per-second, а не полосу. Если пусто/не задано — MSS handshake сохраняется на всё соединение (прежнее поведение). Только Linux; на прочих платформах — no-op.
+  - **Пример**:
+
+    ```toml
+    [server]
+    client_mss = "tspu"
+    client_mss_bulk = "1400"
+    ```
 ## proxy_protocol
   - **Ограничения / валидация**: `bool`.
   - **Описание**: Включает поддержку разбора PROXY protocol от HAProxy (v1/v2) на входящих соединениях. При включении исходный IP клиента берётся из PROXY-заголовка.
@@ -2213,6 +2236,16 @@
 | --- | ---- | ------- | ---------- |
 | [`ip`](#ip) | `IpAddr` | — | `✘` |
 | [`port`](#port-serverlisteners) | `u16` | `server.port` | `✘` |
+| [`client_mss`](#client_mss-serverlisteners) | `String` | `[server].client_mss` | `✘` |
+| [`synlimit`](#synlimit-serverlisteners) | `false`, `"iptables"` или `"nftables"` | `false` | `✔` |
+| [`synlimit_seconds`](#synlimit_seconds-serverlisteners) | `u32` | `60` | `✔` |
+| [`synlimit_hitcount`](#synlimit_hitcount-serverlisteners) | `u32` | `48` | `✔` |
+| [`synlimit_burst`](#synlimit_burst-serverlisteners) | `u32` | `1` | `✔` |
+| [`synlimit_ios_seconds`](#synlimit_ios_seconds-serverlisteners) | `u32` | `1` | `✔` |
+| [`synlimit_ios_hitcount`](#synlimit_ios_hitcount-serverlisteners) | `u32` | `12` | `✔` |
+| [`synlimit_ios_burst`](#synlimit_ios_burst-serverlisteners) | `u32` | `24` | `✔` |
+| [`synlimit_hashlimit_expire_ms`](#synlimit_hashlimit_expire_ms-serverlisteners) | `u32` | `60000` | `✔` |
+| [`synlimit_hashlimit_size`](#synlimit_hashlimit_size-serverlisteners) | `u32` | `32768` | `✔` |
 | [`announce`](#announce) | `String` | — | `✘` |
 | [`announce_ip`](#announce_ip) | `IpAddr` | — | `✘` |
 | [`proxy_protocol`](#proxy_protocol) | `bool` | — | `✘` |
@@ -2237,6 +2270,130 @@
     ip = "0.0.0.0"
     port = 443
     ```
+## client_mss (server.listeners)
+  - **Ограничения / валидация**: `String` (необязательный параметр). Допустимые значения совпадают с `[server].client_mss`.
+  - **Описание**: Per-listener override для MSS. Если параметр не задан, listener наследует `[server].client_mss`; если задана пустая строка, MSS shaping отключается только для этого listener’а, даже когда глобальный параметр задан. Изменение требует restart/rebind listener’а.
+  - **Пример**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    client_mss = "256"
+    ```
+## synlimit (server.listeners)
+  - **Ограничения / валидация**: `false`, `"iptables"` или `"nftables"`. Если параметр не задан или задан как `false`, SYN limiter для этого listener’а выключен.
+  - **Описание**: Устанавливает per-listener Linux netfilter two-tier SYN-fix rules для порта listener’а. `"iptables"` использует `iptables`/`ip6tables` filter rules с `hashlimit`, `length` и TTL/hop-limit matches. `"nftables"` использует Telemt-owned tables с per-source `meter` rules и эквивалентными IPv4/IPv6 classifiers. Rules вставляются рано в `INPUT`, принимают under-limit SYN packets и отвечают TCP RST на over-limit SYN packets, чтобы клиент быстро переподключался вместо ожидания silent DROP timeout. Generic bucket управляется `synlimit_seconds`, `synlimit_hitcount` и `synlimit_burst`; iOS-like TTL/length bucket управляется `synlimit_ios_*`. Rules reconciled at runtime и удаляются при graceful shutdown Telemt; `SIGKILL` процессом не очищается. Требует CAP_NET_ADMIN. Изменения `synlimit*` hot-reload’ятся для существующих listener endpoints; изменение listener `ip` или `port` по-прежнему требует restart/rebind.
+  - **Operator note**: Telemt не сохраняет rules через `iptables-persistent`, не пишет `/etc/sysctl.d`, не меняет systemd limits и не модифицирует `client_mss`. Host-level tuning применяется оператором вручную.
+  - **Пример**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+
+    [[server.listeners]]
+    ip = "::"
+    port = 443
+    synlimit = "nftables"
+    ```
+## synlimit_seconds (server.listeners)
+  - **Ограничения / валидация**: `u32`, должно быть `> 0`. Значение по умолчанию: `60`.
+  - **Описание**: Generic SYN-fix token-bucket interval. Rate равен `synlimit_hitcount / synlimit_seconds` и рендерится в native netfilter rate units (`second`, `minute`, `hour` или `day`). Этот bucket обрабатывает SYN packets, которые не совпали с iOS-like TTL/length classifier.
+  - **Пример**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_seconds = 60
+    ```
+## synlimit_hitcount (server.listeners)
+  - **Ограничения / валидация**: `u32`, должно быть `> 0`. Значение по умолчанию: `48`.
+  - **Описание**: Generic SYN-fix token-bucket rate amount. Вместе с `synlimit_seconds` задает разрешенный source-IP SYN rate до того, как excess SYN packets получат TCP RST.
+  - **Пример**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_hitcount = 48
+    ```
+## synlimit_burst (server.listeners)
+  - **Ограничения / валидация**: `u32`, должно быть `> 0`. Значение по умолчанию: `1`.
+  - **Описание**: Generic SYN-fix token-bucket burst size. Более высокие значения разрешают short connection bursts с одного source IP перед применением steady-state rate `synlimit_hitcount / synlimit_seconds`.
+  - **Пример**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_burst = 1
+    ```
+## synlimit_ios_seconds (server.listeners)
+  - **Ограничения / валидация**: `u32`, должно быть `> 0`. Значение по умолчанию: `1`.
+  - **Описание**: Token-bucket interval для SYN packets, совпавших с iOS-like classifier. IPv4 match: packet length `64` и TTL `< 65`; IPv6 match: packet length `84` и hop limit `< 65`.
+  - **Пример**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_ios_seconds = 1
+    ```
+## synlimit_ios_hitcount (server.listeners)
+  - **Ограничения / валидация**: `u32`, должно быть `> 0`. Значение по умолчанию: `12`.
+  - **Описание**: Token-bucket rate amount для iOS-like SYN classifier.
+  - **Пример**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_ios_hitcount = 12
+    ```
+## synlimit_ios_burst (server.listeners)
+  - **Ограничения / валидация**: `u32`, должно быть `> 0`. Значение по умолчанию: `24`.
+  - **Описание**: Token-bucket burst size для iOS-like SYN classifier.
+  - **Пример**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_ios_burst = 24
+    ```
+## synlimit_hashlimit_expire_ms (server.listeners)
+  - **Ограничения / валидация**: `u32`, должно быть `> 0`. Значение по умолчанию: `60000`.
+  - **Описание**: Entry expiration в миллисекундах для iptables/ip6tables hashlimit buckets. nftables meters используют kernel-managed state и не имеют точного аналога этого knob.
+  - **Пример**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_hashlimit_expire_ms = 60000
+    ```
+## synlimit_hashlimit_size (server.listeners)
+  - **Ограничения / валидация**: `u32`, должно быть `> 0`. Значение по умолчанию: `32768`.
+  - **Описание**: Hash table size для iptables/ip6tables hashlimit buckets. nftables meters используют kernel-managed state и не имеют точного аналога этого knob.
+  - **Пример**:
+
+    ```toml
+    [[server.listeners]]
+    ip = "0.0.0.0"
+    port = 443
+    synlimit = "iptables"
+    synlimit_hashlimit_size = 32768
+    ```
 ## announce
   - **Ограничения / валидация**: `String` (необязательный параметр). Не должен быть пустым, если задан.
   - **Описание**: Публичный IP-адрес или домен, объявляемый в proxy-ссылках для данного listener’а. Имеет приоритет над `announce_ip`.
@@ -2955,7 +3112,7 @@
 | [`replay_window_secs`](#replay_window_secs) | `u64` | `120` | `✘` |
 | [`ignore_time_skew`](#ignore_time_skew) | `bool` | `false` | `✘` |
 | [`user_rate_limits`](#user_rate_limits) | `Map<String, RateLimitBps>` | `{}` | `✔` |
-| [`cidr_rate_limits`](#cidr_rate_limits) | `Map<IpNetwork, RateLimitBps>` | `{}` | `✔` |
+| [`cidr_rate_limits`](#cidr_rate_limits) | `Map<CidrRateLimitKey, RateLimitBps>` | `{}` | `✔` |
 
 ## users
   - **Ограничения / валидация**: Не должно быть пустым (должен существовать хотя бы один пользователь). Каждое значение должно состоять **ровно из 32 шестнадцатеричных символов**.
@@ -3100,7 +3257,7 @@
 
 ## user_rate_limits
   - **Ограничения / валидация**: Таблица `username -> { up_bps, down_bps }`. Должно быть ненулевое значение хотя бы в одном направлении.
-  - **Описание**: Персональные лимиты скорости по пользователям в байтах/сек для отправки (`up_bps`) и получения (`down_bps`).
+  - **Описание**: Персональные лимиты скорости по пользователям в битах/сек для отправки (`up_bps`) и получения (`down_bps`).
   - **Example**:
 
     ```toml
@@ -3108,13 +3265,15 @@
     alice = { up_bps = 1048576, down_bps = 2097152 }
     ```
 ## cidr_rate_limits
-  - **Ограничения / валидация**: Таблица `CIDR -> { up_bps, down_bps }`. CIDR должен корректно разбираться как `IpNetwork`; хотя бы одно направление должно быть ненулевым.
-  - **Описание**: Лимиты скорости для подсетей источников, применяются поверх пользовательских ограничений.
+  - **Ограничения / валидация**: Таблица `CIDR или auto-template -> { up_bps, down_bps }`. Explicit CIDR-ключи должны корректно разбираться как `IpNetwork`; auto-template ключи должны иметь вид `*4/N` (`N=0..32`), `*6/N` (`N=0..128`) или `*/N` (`N=0..32`). Хотя бы одно направление должно быть ненулевым. Дублирующиеся нормализованные auto-template отклоняются.
+  - **Описание**: Лимиты скорости для подсетей источников, применяются поверх пользовательских ограничений. Explicit CIDR-правила используют longest-prefix-wins и имеют приоритет над auto-template. Auto-template создают bucket’ы лениво по matched source subnet: `*4/N` для IPv4, `*6/N` для IPv6, а `*/N` является dual-stack shorthand, где IPv4 использует `/N`, а IPv6 — `/(N * 4)`.
   - **Example**:
 
     ```toml
     [access.cidr_rate_limits]
     "203.0.113.0/24" = { up_bps = 0, down_bps = 1048576 }
+    "*4/32" = { up_bps = 262144, down_bps = 1048576 }
+    "*6/64" = { up_bps = 262144, down_bps = 1048576 }
     ```
 # [[upstreams]]
 

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>"

src/api/config_edit.rs

@@ -0,0 +1,411 @@
+//! 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_rejects_show_link_section() {
+        // show_link is a legacy top-level scalar/array (not a [table]); it cannot
+        // be upserted safely and is superseded by the editable general.links.show.
+        let (path, _d) = temp_config("[censorship]\ntls_domain = \"a\"\n");
+        let patch: Json = serde_json::json!({"show_link": "*"});
+        let err = apply_patch_to_path(&path, &patch, None).await.unwrap_err();
+        assert_eq!(err.code, "section_not_editable");
+    }
+
+    #[tokio::test]
+    async fn patch_general_links_show_is_editable() {
+        // The supported replacement path: edit show via the general.links sub-table.
+        let (path, _d) = temp_config(
+            "[general]\nprefer_ipv6 = false\n[general.links]\nshow = \"*\"\n\
+             [censorship]\ntls_domain = \"a\"\n",
+        );
+        let patch: Json = serde_json::json!({"general": {"links": {"show": ["alice"]}}});
+        let resp = apply_patch_to_path(&path, &patch, None).await.unwrap();
+        assert!(resp.changed.iter().any(|c| c == "general"));
+        let written = tokio::fs::read_to_string(&path).await.unwrap();
+        let parsed: toml::Value = toml::from_str(&written).unwrap();
+        assert_eq!(
+            parsed["general"]["links"]["show"][0].as_str(),
+            Some("alice"),
+            "{written}"
+        );
+        // No leaked top-level [links]/[modes] and no duplicate sub-tables.
+        assert_eq!(written.matches("[general.links]").count(), 1, "{written}");
+    }
+
+    #[tokio::test]
+    async fn patch_links_public_port_written_as_integer_not_float_or_string() {
+        // A JSON integer must land on disk as a bare TOML integer (443), never
+        // 443.0 nor "443". The write re-renders from the typed config, so the
+        // u16 field dictates the output format regardless of JSON quirks.
+        let (path, _d) = temp_config("[general]\nprefer_ipv6 = false\n");
+        let patch: Json = serde_json::json!({"general": {"links": {"public_port": 443}}});
+        apply_patch_to_path(&path, &patch, None).await.unwrap();
+
+        let written = tokio::fs::read_to_string(&path).await.unwrap();
+        assert!(written.contains("public_port = 443"), "{written}");
+        assert!(
+            !written.contains("443.0"),
+            "must not be a float:\n{written}"
+        );
+        assert!(
+            !written.contains("\"443\""),
+            "must not be a string:\n{written}"
+        );
+
+        let parsed: toml::Value = toml::from_str(&written).unwrap();
+        assert_eq!(
+            parsed["general"]["links"]["public_port"].as_integer(),
+            Some(443),
+            "{written}"
+        );
+    }
+
+    #[tokio::test]
+    async fn patch_links_public_port_rejects_float() {
+        // 443.0 cannot deserialize into u16 -> rejected, not silently coerced.
+        let (path, _d) = temp_config("[general]\nprefer_ipv6 = false\n");
+        let patch: Json = serde_json::json!({"general": {"links": {"public_port": 443.0}}});
+        let err = apply_patch_to_path(&path, &patch, None).await.unwrap_err();
+        assert_eq!(err.status, hyper::StatusCode::BAD_REQUEST, "{:?}", err);
+    }
+
+    #[tokio::test]
+    async fn patch_links_public_port_rejects_string() {
+        // "443" is a string, not a u16 -> rejected.
+        let (path, _d) = temp_config("[general]\nprefer_ipv6 = false\n");
+        let patch: Json = serde_json::json!({"general": {"links": {"public_port": "443"}}});
+        let err = apply_patch_to_path(&path, &patch, None).await.unwrap_err();
+        assert_eq!(err.status, hyper::StatusCode::BAD_REQUEST, "{:?}", err);
+    }
+
+    #[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

@@ -97,6 +97,90 @@ 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`).
+///   - `show_link` : legacy top-level scalar/array (not a `[table]`), superseded
+///                   by the editable `general.links.show` sub-table. The
+///                   section-upsert machinery here only handles `[table]` /
+///                   `[[array-of-tables]]` blocks; a bare top-level key cannot be
+///                   located or replaced safely, so it is edited via `general`.
+///
+/// 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",
+    "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);
+    }
+
+    // Serialize the table *inside a wrapper keyed by `section`* so the `toml`
+    // crate emits correctly dotted headers for nested sub-tables, e.g.
+    // `[general]` + `[general.modes]` + `[general.links]`. Serializing the
+    // inner table alone would render bare `[modes]`/`[links]` headers, which
+    // would leak as duplicate top-level tables and break config load.
+    let mut wrapper = toml::value::Table::new();
+    wrapper.insert(section.to_string(), table.clone());
+    let mut out = toml::to_string(&toml::Value::Table(wrapper))
+        .map_err(|e| ApiFailure::internal(format!("failed to serialize {}: {}", section, e)))?;
+    if !out.ends_with('\n') {
+        out.push('\n');
+    }
+    Ok(out)
+}
+
 pub(super) async fn save_access_sections_to_disk(
     config_path: &Path,
     cfg: &ProxyConfig,
@@ -253,11 +337,22 @@ fn serialize_toml_key(key: &str) -> Result<String, ApiFailure> {
 }
 
 fn upsert_toml_table(source: &str, table_name: &str, replacement: &str) -> String {
-    if let Some((start, end)) = find_toml_table_bounds(source, table_name) {
+    let blocks = find_all_table_blocks(source, table_name);
+    if let Some(&(first_start, first_end)) = blocks.first() {
+        // Replace the first block in place and delete any further blocks that
+        // also belong to this table. Telemt writes a section's sub-tables
+        // contiguously, but a hand-edited config may scatter them; dropping the
+        // extras here prevents the duplicate-table corruption that would
+        // otherwise break config load.
         let mut out = String::with_capacity(source.len() + replacement.len());
-        out.push_str(&source[..start]);
+        out.push_str(&source[..first_start]);
         out.push_str(replacement);
-        out.push_str(&source[end..]);
+        let mut cursor = first_end;
+        for &(start, end) in &blocks[1..] {
+            out.push_str(&source[cursor..start]);
+            cursor = end;
+        }
+        out.push_str(&source[cursor..]);
         return out;
     }
 
@@ -272,24 +367,62 @@ fn upsert_toml_table(source: &str, table_name: &str, replacement: &str) -> Strin
     out
 }
 
+/// Whether a (comment-stripped, trimmed) TOML header line belongs to
+/// `table_name`: the table itself (`[X]` / `[[X]]`) or any of its nested
+/// sub-tables (`[X.…]` / `[[X.…]]`). The trailing dot guards against sibling
+/// prefixes — `access.users` must not match `access.user_enabled`.
+fn header_belongs_to(header: &str, table_name: &str) -> bool {
+    let body = match header.strip_prefix("[[").and_then(|h| h.strip_suffix("]]")) {
+        Some(body) => body,
+        None => match header.strip_prefix('[').and_then(|h| h.strip_suffix(']')) {
+            Some(body) => body,
+            None => return false,
+        },
+    };
+    let body = body.trim();
+    body == table_name
+        || body
+            .strip_prefix(table_name)
+            .is_some_and(|rest| rest.starts_with('.'))
+}
+
+/// Locate the first contiguous byte range covering `table_name` and the nested
+/// sub-tables immediately following it. Used for existence checks; see
+/// [`find_all_table_blocks`] for the full set of (possibly scattered) blocks.
 fn find_toml_table_bounds(source: &str, table_name: &str) -> Option<(usize, usize)> {
-    let target = format!("[{}]", table_name);
+    find_all_table_blocks(source, table_name).into_iter().next()
+}
+
+/// Locate every byte range that belongs to `table_name`: the table header and
+/// its nested sub-tables. Returns one range per contiguous run, so a config
+/// where a section's sub-tables are scattered (e.g. hand-edited) yields several
+/// ranges — letting the caller collapse them into a single rendered block.
+fn find_all_table_blocks(source: &str, table_name: &str) -> Vec<(usize, usize)> {
+    let mut blocks = Vec::new();
     let mut offset = 0usize;
-    let mut start = None;
+    let mut start: Option<usize> = 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();
+        let is_header = header.starts_with('[');
         if let Some(start_offset) = start {
-            if trimmed.starts_with('[') {
-                return Some((start_offset, offset));
+            if is_header && !header_belongs_to(header, table_name) {
+                blocks.push((start_offset, offset));
+                start = None;
             }
-        } else if trimmed == target {
+        }
+        if start.is_none() && header_belongs_to(header, table_name) {
             start = Some(offset);
         }
         offset = offset.saturating_add(line.len());
     }
 
-    start.map(|start_offset| (start_offset, source.len()))
+    if let Some(start_offset) = start {
+        blocks.push((start_offset, source.len()));
+    }
+    blocks
 }
 
 async fn write_atomic(path: PathBuf, contents: String) -> Result<(), ApiFailure> {
@@ -336,6 +469,189 @@ 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
+    }
+
+    #[tokio::test]
+    async fn save_general_section_keeps_subtables_dotted_without_duplicates() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        tokio::fs::write(
+            &path,
+            "[general]\nprefer_ipv6 = false\n\n[general.modes]\ntls = true\n\n\
+             [general.links]\npublic_host = \"old.example\"\n\n[server]\nport = 443\n",
+        )
+        .await
+        .unwrap();
+
+        let mut cfg = ProxyConfig::default();
+        cfg.general.prefer_ipv6 = true;
+
+        save_sections_to_disk(&path, &cfg, &["general"])
+            .await
+            .unwrap();
+
+        let written = tokio::fs::read_to_string(&path).await.unwrap();
+
+        // No bare top-level [modes] / [links] headers leaked.
+        for line in written.lines() {
+            let header = line.trim();
+            assert_ne!(header, "[modes]", "leaked top-level [modes]:\n{written}");
+            assert_ne!(header, "[links]", "leaked top-level [links]:\n{written}");
+        }
+
+        // Sub-tables kept their dotted prefix exactly once each.
+        assert_eq!(
+            written.matches("[general.modes]").count(),
+            1,
+            "[general.modes] must appear exactly once:\n{written}"
+        );
+        assert_eq!(
+            written.matches("[general.links]").count(),
+            1,
+            "[general.links] must appear exactly once:\n{written}"
+        );
+
+        // Result parses (duplicate tables would error here).
+        toml::from_str::<toml::Value>(&written)
+            .unwrap_or_else(|e| panic!("written config must parse: {e}\n{written}"));
+
+        assert!(written.contains("[server]\nport = 443")); // untouched table kept
+    }
+
+    #[tokio::test]
+    async fn save_general_section_is_idempotent_across_repeated_saves() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        tokio::fs::write(
+            &path,
+            "[general]\nprefer_ipv6 = false\n\n[general.modes]\ntls = true\n\n\
+             [general.links]\npublic_host = \"old.example\"\n",
+        )
+        .await
+        .unwrap();
+
+        let mut cfg = ProxyConfig::default();
+        cfg.general.prefer_ipv6 = true;
+
+        save_sections_to_disk(&path, &cfg, &["general"])
+            .await
+            .unwrap();
+        save_sections_to_disk(&path, &cfg, &["general"])
+            .await
+            .unwrap();
+
+        let written = tokio::fs::read_to_string(&path).await.unwrap();
+        assert_eq!(written.matches("[general.modes]").count(), 1, "{written}");
+        assert_eq!(written.matches("[general.links]").count(), 1, "{written}");
+        assert_eq!(written.matches("[general]").count(), 1, "{written}");
+        toml::from_str::<toml::Value>(&written)
+            .unwrap_or_else(|e| panic!("written config must parse: {e}\n{written}"));
+    }
+
+    #[test]
+    fn find_bounds_spans_dotted_subtables() {
+        let src = "[general]\nprefer_ipv6 = false\n\n[general.modes]\ntls = true\n\n\
+                   [general.links]\npublic_host = \"a\"\n\n[server]\nport = 1\n";
+        let bounds = find_toml_table_bounds(src, "general");
+        assert!(bounds.is_some(), "should locate [general] block");
+        let (start, end) = bounds.unwrap();
+        let slice = &src[start..end];
+        assert!(slice.starts_with("[general]"));
+        assert!(slice.contains("[general.modes]")); // spans nested sub-tables
+        assert!(slice.contains("[general.links]"));
+        assert!(!slice.contains("[server]")); // terminates at the next unrelated header
+    }
+
+    #[test]
+    fn find_bounds_does_not_overrun_sibling_prefix() {
+        // access.users must not swallow access.user_enabled (dot guards the prefix).
+        let src = "[access.users]\nalice = \"x\"\n\n[access.user_enabled]\nalice = true\n";
+        let bounds = find_toml_table_bounds(src, "access.users").unwrap();
+        let slice = &src[bounds.0..bounds.1];
+        assert!(slice.starts_with("[access.users]"));
+        assert!(!slice.contains("[access.user_enabled]"));
+    }
+
+    #[tokio::test]
+    async fn save_general_handles_non_contiguous_subtables() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        // Hand-edited layout: [general.modes] sits AFTER an unrelated [server].
+        tokio::fs::write(
+            &path,
+            "[general]\nprefer_ipv6 = false\n\n[server]\nport = 443\n\n\
+             [general.modes]\ntls = true\n",
+        )
+        .await
+        .unwrap();
+
+        let mut cfg = ProxyConfig::default();
+        cfg.general.prefer_ipv6 = true;
+
+        save_sections_to_disk(&path, &cfg, &["general"])
+            .await
+            .unwrap();
+
+        let written = tokio::fs::read_to_string(&path).await.unwrap();
+        assert_eq!(
+            written.matches("[general.modes]").count(),
+            1,
+            "non-contiguous [general.modes] must not duplicate:\n{written}"
+        );
+        toml::from_str::<toml::Value>(&written)
+            .unwrap_or_else(|e| panic!("written config must parse: {e}\n{written}"));
+        assert!(written.contains("[server]")); // unrelated section preserved
+    }
+
     #[test]
     fn render_user_rate_limits_section() {
         let mut cfg = ProxyConfig::default();

src/api/mod.rs

@@ -28,6 +28,7 @@ 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;
@@ -84,6 +85,7 @@ 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,
@@ -174,6 +176,7 @@ fn allowed_methods_for_path(path: &str) -> Option<&'static str> {
         | "/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),
@@ -643,6 +646,37 @@ 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

src/config/defaults.rs

@@ -24,6 +24,10 @@ const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_WARM_WRITERS_GLOBAL: u32 = 256;
 const DEFAULT_ME_ROUTE_BACKPRESSURE_ENABLED: bool = false;
 const DEFAULT_ME_ROUTE_FAIRSHARE_ENABLED: bool = false;
 const DEFAULT_ME_WRITER_CMD_CHANNEL_CAPACITY: usize = 4096;
+pub(crate) const ME_WRITER_BYTE_PERMIT_UNIT_BYTES: usize = 16 * 1024;
+pub(crate) const ME_WRITER_FRAME_OVERHEAD_RESERVE_BYTES: usize = 256;
+const DEFAULT_ME_WRITER_BYTE_BUDGET_BYTES: usize =
+    32 * 1024 * 1024 + ME_WRITER_BYTE_PERMIT_UNIT_BYTES;
 const DEFAULT_ME_ROUTE_CHANNEL_CAPACITY: usize = 768;
 const DEFAULT_ME_C2ME_CHANNEL_CAPACITY: usize = 1024;
 const DEFAULT_ME_READER_ROUTE_DATA_WAIT_MS: u64 = 2;
@@ -35,6 +39,8 @@ const DEFAULT_ME_QUOTA_SOFT_OVERSHOOT_BYTES: u64 = 64 * 1024;
 const DEFAULT_ME_D2C_FRAME_BUF_SHRINK_THRESHOLD_BYTES: usize = 256 * 1024;
 const DEFAULT_DIRECT_RELAY_COPY_BUF_C2S_BYTES: usize = 64 * 1024;
 const DEFAULT_DIRECT_RELAY_COPY_BUF_S2C_BYTES: usize = 256 * 1024;
+pub(crate) const DIRECT_RELAY_BUFFER_BUDGET_UNIT_BYTES: usize = 4 * 1024;
+const DEFAULT_DIRECT_RELAY_BUFFER_BUDGET_MAX_BYTES: usize = 0;
 const DEFAULT_ME_WRITER_PICK_SAMPLE_SIZE: u8 = 3;
 const DEFAULT_ME_HEALTH_INTERVAL_MS_UNHEALTHY: u64 = 1000;
 const DEFAULT_ME_HEALTH_INTERVAL_MS_HEALTHY: u64 = 3000;
@@ -54,6 +60,14 @@ 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 = 60;
+const DEFAULT_SYNLIMIT_HITCOUNT: u32 = 48;
+const DEFAULT_SYNLIMIT_BURST: u32 = 1;
+const DEFAULT_SYNLIMIT_IOS_SECONDS: u32 = 1;
+const DEFAULT_SYNLIMIT_IOS_HITCOUNT: u32 = 12;
+const DEFAULT_SYNLIMIT_IOS_BURST: u32 = 24;
+const DEFAULT_SYNLIMIT_HASHLIMIT_EXPIRE_MS: u32 = 60_000;
+const DEFAULT_SYNLIMIT_HASHLIMIT_SIZE: u32 = 32_768;
 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 +257,38 @@ 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_synlimit_ios_seconds() -> u32 {
+    DEFAULT_SYNLIMIT_IOS_SECONDS
+}
+
+pub(crate) fn default_synlimit_ios_hitcount() -> u32 {
+    DEFAULT_SYNLIMIT_IOS_HITCOUNT
+}
+
+pub(crate) fn default_synlimit_ios_burst() -> u32 {
+    DEFAULT_SYNLIMIT_IOS_BURST
+}
+
+pub(crate) fn default_synlimit_hashlimit_expire_ms() -> u32 {
+    DEFAULT_SYNLIMIT_HASHLIMIT_EXPIRE_MS
+}
+
+pub(crate) fn default_synlimit_hashlimit_size() -> u32 {
+    DEFAULT_SYNLIMIT_HASHLIMIT_SIZE
+}
+
 pub(crate) fn default_prefer_4() -> u8 {
     4
 }
@@ -415,6 +461,18 @@ pub(crate) fn default_me_writer_cmd_channel_capacity() -> usize {
     DEFAULT_ME_WRITER_CMD_CHANNEL_CAPACITY
 }
 
+pub(crate) fn default_me_writer_byte_budget_bytes() -> usize {
+    DEFAULT_ME_WRITER_BYTE_BUDGET_BYTES
+}
+
+pub(crate) fn minimum_me_writer_byte_budget_bytes(max_client_frame: usize) -> usize {
+    max_client_frame
+        .saturating_mul(2)
+        .saturating_add(ME_WRITER_FRAME_OVERHEAD_RESERVE_BYTES)
+        .div_ceil(ME_WRITER_BYTE_PERMIT_UNIT_BYTES)
+        .saturating_mul(ME_WRITER_BYTE_PERMIT_UNIT_BYTES)
+}
+
 pub(crate) fn default_me_route_channel_capacity() -> usize {
     DEFAULT_ME_ROUTE_CHANNEL_CAPACITY
 }
@@ -459,6 +517,10 @@ pub(crate) fn default_direct_relay_copy_buf_s2c_bytes() -> usize {
     DEFAULT_DIRECT_RELAY_COPY_BUF_S2C_BYTES
 }
 
+pub(crate) fn default_direct_relay_buffer_budget_max_bytes() -> usize {
+    DEFAULT_DIRECT_RELAY_BUFFER_BUDGET_MAX_BYTES
+}
+
 pub(crate) fn default_me_writer_pick_sample_size() -> u8 {
     DEFAULT_ME_WRITER_PICK_SAMPLE_SIZE
 }

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,
+    CidrRateLimitKey, ListenerConfig, LogLevel, MeBindStaleMode, MeFloorMode, MeSocksKdfPolicy,
+    MeTelemetryLevel, MeWriterPickMode, SynLimitMode,
 };
 
 const HOT_RELOAD_DEBOUNCE: Duration = Duration::from_millis(50);
@@ -125,12 +128,27 @@ pub struct HotFields {
     pub user_expirations: std::collections::HashMap<String, chrono::DateTime<chrono::Utc>>,
     pub user_data_quota: std::collections::HashMap<String, u64>,
     pub user_rate_limits: std::collections::HashMap<String, crate::config::RateLimitBps>,
-    pub cidr_rate_limits:
-        std::collections::HashMap<ipnetwork::IpNetwork, crate::config::RateLimitBps>,
+    pub cidr_rate_limits: std::collections::HashMap<CidrRateLimitKey, crate::config::RateLimitBps>,
     pub user_max_unique_ips: std::collections::HashMap<String, usize>,
     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,
+    pub synlimit_ios_seconds: u32,
+    pub synlimit_ios_hitcount: u32,
+    pub synlimit_ios_burst: u32,
+    pub synlimit_hashlimit_expire_ms: u32,
+    pub synlimit_hashlimit_size: u32,
 }
 
 impl HotFields {
@@ -260,6 +278,30 @@ 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,
+            synlimit_ios_seconds: listener.synlimit_ios_seconds,
+            synlimit_ios_hitcount: listener.synlimit_ios_hitcount,
+            synlimit_ios_burst: listener.synlimit_ios_burst,
+            synlimit_hashlimit_expire_ms: listener.synlimit_hashlimit_expire_ms,
+            synlimit_hashlimit_size: listener.synlimit_hashlimit_size,
         }
     }
 }
@@ -312,6 +354,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
@@ -565,6 +608,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;
@@ -573,6 +617,26 @@ 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;
+        old_listener.synlimit_ios_seconds = new_listener.synlimit_ios_seconds;
+        old_listener.synlimit_ios_hitcount = new_listener.synlimit_ios_hitcount;
+        old_listener.synlimit_ios_burst = new_listener.synlimit_ios_burst;
+        old_listener.synlimit_hashlimit_expire_ms = new_listener.synlimit_hashlimit_expire_ms;
+        old_listener.synlimit_hashlimit_size = new_listener.synlimit_hashlimit_size;
+    }
+}
+
 /// 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;
@@ -608,6 +672,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
     {
@@ -618,6 +683,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
@@ -847,6 +913,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: {} → {}",
@@ -1487,6 +1560,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::*;
@@ -1609,6 +1724,51 @@ mod tests {
         assert!(!config_equal(&applied, &new));
     }
 
+    #[test]
+    fn listener_synlimit_extended_fields_are_hot() {
+        let mut old = sample_config();
+        old.server.listeners.push(ListenerConfig {
+            ip: "0.0.0.0".parse().unwrap(),
+            port: Some(443),
+            client_mss: None,
+            synlimit: SynLimitMode::Iptables,
+            synlimit_seconds: 60,
+            synlimit_hitcount: 48,
+            synlimit_burst: 1,
+            synlimit_ios_seconds: 1,
+            synlimit_ios_hitcount: 12,
+            synlimit_ios_burst: 24,
+            synlimit_hashlimit_expire_ms: 60_000,
+            synlimit_hashlimit_size: 32_768,
+            announce: None,
+            announce_ip: None,
+            proxy_protocol: None,
+            reuse_allow: false,
+        });
+        let mut new = old.clone();
+        new.server.port = 8443;
+        new.server.listeners[0].synlimit_seconds = 120;
+        new.server.listeners[0].synlimit_hitcount = 96;
+        new.server.listeners[0].synlimit_burst = 2;
+        new.server.listeners[0].synlimit_ios_seconds = 2;
+        new.server.listeners[0].synlimit_ios_hitcount = 18;
+        new.server.listeners[0].synlimit_ios_burst = 36;
+        new.server.listeners[0].synlimit_hashlimit_expire_ms = 90_000;
+        new.server.listeners[0].synlimit_hashlimit_size = 65_536;
+
+        let applied = overlay_hot_fields(&old, &new);
+        let listener = &applied.server.listeners[0];
+        assert_eq!(applied.server.port, old.server.port);
+        assert_eq!(listener.synlimit_seconds, 120);
+        assert_eq!(listener.synlimit_hitcount, 96);
+        assert_eq!(listener.synlimit_burst, 2);
+        assert_eq!(listener.synlimit_ios_seconds, 2);
+        assert_eq!(listener.synlimit_ios_hitcount, 18);
+        assert_eq!(listener.synlimit_ios_burst, 36);
+        assert_eq!(listener.synlimit_hashlimit_expire_ms, 90_000);
+        assert_eq!(listener.synlimit_hashlimit_size, 65_536);
+    }
+
     #[test]
     fn reload_applies_hot_change_on_first_observed_snapshot() {
         let initial_tag = "11111111111111111111111111111111";
@@ -1659,6 +1819,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/includes.rs

@@ -0,0 +1,60 @@
+use std::collections::BTreeSet;
+use std::hash::{DefaultHasher, Hash, Hasher};
+use std::path::{Path, PathBuf};
+
+use crate::error::{ProxyError, Result};
+
+pub(super) fn normalize_config_path(path: &Path) -> PathBuf {
+    path.canonicalize().unwrap_or_else(|_| {
+        if path.is_absolute() {
+            path.to_path_buf()
+        } else {
+            std::env::current_dir()
+                .map(|cwd| cwd.join(path))
+                .unwrap_or_else(|_| path.to_path_buf())
+        }
+    })
+}
+
+pub(super) fn hash_rendered_snapshot(rendered: &str) -> u64 {
+    let mut hasher = DefaultHasher::new();
+    rendered.hash(&mut hasher);
+    hasher.finish()
+}
+
+pub(super) fn preprocess_includes(
+    content: &str,
+    base_dir: &Path,
+    depth: u8,
+    source_files: &mut BTreeSet<PathBuf>,
+) -> Result<String> {
+    if depth > 10 {
+        return Err(ProxyError::Config("Include depth > 10".into()));
+    }
+    let mut output = String::with_capacity(content.len());
+    for line in content.lines() {
+        let trimmed = line.trim();
+        if let Some(rest) = trimmed.strip_prefix("include") {
+            let rest = rest.trim();
+            if let Some(rest) = rest.strip_prefix('=') {
+                let path_str = rest.trim().trim_matches('"');
+                let resolved = base_dir.join(path_str);
+                source_files.insert(normalize_config_path(&resolved));
+                let included = std::fs::read_to_string(&resolved)
+                    .map_err(|e| ProxyError::Config(e.to_string()))?;
+                let included_dir = resolved.parent().unwrap_or(base_dir);
+                output.push_str(&preprocess_includes(
+                    &included,
+                    included_dir,
+                    depth + 1,
+                    source_files,
+                )?);
+                output.push('\n');
+                continue;
+            }
+        }
+        output.push_str(line);
+        output.push('\n');
+    }
+    Ok(output)
+}

src/config/load/normalize.rs

@@ -0,0 +1,115 @@
+use crate::error::{ProxyError, Result};
+use tracing::warn;
+
+pub(super) fn is_valid_tls_domain_name(domain: &str) -> bool {
+    !domain.is_empty()
+        && !domain
+            .chars()
+            .any(|ch| ch.is_whitespace() || matches!(ch, '/' | '\\'))
+}
+
+pub(super) fn normalize_domain_to_ascii(domain: &str, field: &str) -> Result<String> {
+    let domain = domain.trim();
+    if !is_valid_tls_domain_name(domain) {
+        return Err(ProxyError::Config(format!(
+            "Invalid {field}: '{}'. Must be a valid domain name",
+            domain
+        )));
+    }
+
+    let parsed = url::Url::parse(&format!("https://{domain}/")).map_err(|error| {
+        ProxyError::Config(format!(
+            "Invalid {field}: '{}'. IDNA conversion failed: {error}",
+            domain
+        ))
+    })?;
+    let host = parsed.host_str().ok_or_else(|| {
+        ProxyError::Config(format!("Invalid {field}: '{}'. Host is empty", domain))
+    })?;
+    Ok(host.to_ascii_lowercase())
+}
+
+pub(super) fn normalize_mask_host_to_ascii(host: &str, field: &str) -> Result<String> {
+    let host = host.trim();
+    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
+            ))
+        })?;
+        return match ip {
+            std::net::IpAddr::V6(v6) => Ok(format!("[{v6}]")),
+            std::net::IpAddr::V4(v4) => Ok(v4.to_string()),
+        };
+    }
+    if let Ok(ip) = host.parse::<std::net::IpAddr>() {
+        return match ip {
+            std::net::IpAddr::V4(v4) => Ok(v4.to_string()),
+            std::net::IpAddr::V6(v6) => Ok(format!("[{v6}]")),
+        };
+    }
+
+    normalize_domain_to_ascii(host, field)
+}
+
+pub(super) fn parse_exclusive_mask_target(target: &str) -> Option<(&str, u16)> {
+    let target = target.trim();
+    if target.is_empty() {
+        return None;
+    }
+
+    if target.starts_with('[') {
+        let end = target.find(']')?;
+        if target.get(end + 1..end + 2)? != ":" {
+            return None;
+        }
+        let host = &target[..=end];
+        let port = target[end + 2..].parse::<u16>().ok()?;
+        return (port > 0).then_some((host, port));
+    }
+
+    let (host, port) = target.rsplit_once(':')?;
+    if host.is_empty() || host.contains(':') {
+        return None;
+    }
+    let port = port.parse::<u16>().ok()?;
+    (port > 0).then_some((host, port))
+}
+
+pub(super) fn normalize_exclusive_mask_target(target: &str, field: &str) -> Result<String> {
+    let (host, port) = parse_exclusive_mask_target(target).ok_or_else(|| {
+        ProxyError::Config(format!(
+            "Invalid {field}: '{}'. Expected host:port with port > 0",
+            target
+        ))
+    })?;
+    let host = normalize_mask_host_to_ascii(host, field)?;
+    Ok(format!("{host}:{port}"))
+}
+
+pub(super) fn push_unique_nonempty(target: &mut Vec<String>, value: String) {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        return;
+    }
+    if !target.iter().any(|existing| existing == trimmed) {
+        target.push(trimmed.to_string());
+    }
+}
+
+pub(super) fn is_valid_ad_tag(tag: &str) -> bool {
+    tag.len() == 32 && tag.chars().all(|ch| ch.is_ascii_hexdigit())
+}
+
+pub(super) fn sanitize_ad_tag(ad_tag: &mut Option<String>) {
+    let Some(tag) = ad_tag.as_ref() else {
+        return;
+    };
+
+    if !is_valid_ad_tag(tag) {
+        warn!("Invalid general.ad_tag value, expected exactly 32 hex chars; ad_tag is disabled");
+        *ad_tag = None;
+    }
+}

src/config/load/runtime_auth.rs

@@ -0,0 +1,112 @@
+use std::collections::HashMap;
+use std::collections::hash_map::DefaultHasher;
+use std::hash::Hasher;
+
+use crate::error::{ProxyError, Result};
+
+const ACCESS_SECRET_BYTES: usize = 16;
+
+/// Precomputed, immutable user authentication data used by handshake hot paths.
+#[derive(Debug, Clone, Default)]
+pub(crate) struct UserAuthSnapshot {
+    entries: Vec<UserAuthEntry>,
+    by_name: HashMap<String, u32>,
+    sni_index: HashMap<u64, Vec<u32>>,
+    sni_initial_index: HashMap<u8, Vec<u32>>,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct UserAuthEntry {
+    pub(crate) user: String,
+    pub(crate) secret: [u8; ACCESS_SECRET_BYTES],
+}
+
+impl UserAuthSnapshot {
+    pub(super) fn from_users(users: &HashMap<String, String>) -> Result<Self> {
+        let mut entries = Vec::with_capacity(users.len());
+        let mut by_name = HashMap::with_capacity(users.len());
+        let mut sni_index = HashMap::with_capacity(users.len());
+        let mut sni_initial_index = HashMap::with_capacity(users.len());
+
+        for (user, secret_hex) in users {
+            let decoded = hex::decode(secret_hex).map_err(|_| ProxyError::InvalidSecret {
+                user: user.clone(),
+                reason: "Must be 32 hex characters".to_string(),
+            })?;
+            if decoded.len() != ACCESS_SECRET_BYTES {
+                return Err(ProxyError::InvalidSecret {
+                    user: user.clone(),
+                    reason: "Must be 32 hex characters".to_string(),
+                });
+            }
+
+            let user_id = u32::try_from(entries.len()).map_err(|_| {
+                ProxyError::Config("Too many users for runtime auth snapshot".to_string())
+            })?;
+
+            let mut secret = [0u8; ACCESS_SECRET_BYTES];
+            secret.copy_from_slice(&decoded);
+            entries.push(UserAuthEntry {
+                user: user.clone(),
+                secret,
+            });
+            by_name.insert(user.clone(), user_id);
+            sni_index
+                .entry(Self::sni_lookup_hash(user))
+                .or_insert_with(Vec::new)
+                .push(user_id);
+            if let Some(initial) = user
+                .as_bytes()
+                .first()
+                .map(|byte| byte.to_ascii_lowercase())
+            {
+                sni_initial_index
+                    .entry(initial)
+                    .or_insert_with(Vec::new)
+                    .push(user_id);
+            }
+        }
+
+        Ok(Self {
+            entries,
+            by_name,
+            sni_index,
+            sni_initial_index,
+        })
+    }
+
+    pub(crate) fn entries(&self) -> &[UserAuthEntry] {
+        &self.entries
+    }
+
+    pub(crate) fn user_id_by_name(&self, user: &str) -> Option<u32> {
+        self.by_name.get(user).copied()
+    }
+
+    pub(crate) fn entry_by_id(&self, user_id: u32) -> Option<&UserAuthEntry> {
+        let idx = usize::try_from(user_id).ok()?;
+        self.entries.get(idx)
+    }
+
+    pub(crate) fn sni_candidates(&self, sni: &str) -> Option<&[u32]> {
+        self.sni_index
+            .get(&Self::sni_lookup_hash(sni))
+            .map(Vec::as_slice)
+    }
+
+    pub(crate) fn sni_initial_candidates(&self, sni: &str) -> Option<&[u32]> {
+        let initial = sni
+            .as_bytes()
+            .first()
+            .map(|byte| byte.to_ascii_lowercase())?;
+        self.sni_initial_index.get(&initial).map(Vec::as_slice)
+    }
+
+    fn sni_lookup_hash(value: &str) -> u64 {
+        let mut hasher = DefaultHasher::new();
+        for byte in value.bytes() {
+            hasher.write_u8(byte.to_ascii_lowercase());
+        }
+        hasher.finish()
+    }
+}

src/config/load/strict_keys.rs

@@ -0,0 +1,695 @@
+use tracing::warn;
+
+use crate::error::{ProxyError, Result};
+
+const TOP_LEVEL_CONFIG_KEYS: &[&str] = &[
+    "general",
+    "logging",
+    "network",
+    "server",
+    "timeouts",
+    "censorship",
+    "access",
+    "upstreams",
+    "show_link",
+    "dc_overrides",
+    "default_dc",
+    "beobachten",
+    "beobachten_minutes",
+    "beobachten_flush_secs",
+    "beobachten_file",
+    "include",
+];
+
+const GENERAL_CONFIG_KEYS: &[&str] = &[
+    "data_path",
+    "quota_state_path",
+    "config_strict",
+    "modes",
+    "prefer_ipv6",
+    "fast_mode",
+    "use_middle_proxy",
+    "proxy_secret_path",
+    "proxy_secret_url",
+    "proxy_config_v4_cache_path",
+    "proxy_config_v4_url",
+    "proxy_config_v6_cache_path",
+    "proxy_config_v6_url",
+    "ad_tag",
+    "middle_proxy_nat_ip",
+    "middle_proxy_nat_probe",
+    "middle_proxy_nat_stun",
+    "middle_proxy_nat_stun_servers",
+    "stun_nat_probe_concurrency",
+    "middle_proxy_pool_size",
+    "middle_proxy_warm_standby",
+    "me_init_retry_attempts",
+    "me2dc_fallback",
+    "me2dc_fast",
+    "me_keepalive_enabled",
+    "me_keepalive_interval_secs",
+    "me_keepalive_jitter_secs",
+    "me_keepalive_payload_random",
+    "rpc_proxy_req_every",
+    "me_writer_cmd_channel_capacity",
+    "me_writer_byte_budget_bytes",
+    "me_route_channel_capacity",
+    "me_c2me_channel_capacity",
+    "me_c2me_send_timeout_ms",
+    "me_reader_route_data_wait_ms",
+    "me_d2c_flush_batch_max_frames",
+    "me_d2c_flush_batch_max_bytes",
+    "me_d2c_flush_batch_max_delay_us",
+    "me_d2c_ack_flush_immediate",
+    "me_quota_soft_overshoot_bytes",
+    "me_d2c_frame_buf_shrink_threshold_bytes",
+    "direct_relay_copy_buf_c2s_bytes",
+    "direct_relay_copy_buf_s2c_bytes",
+    "direct_relay_buffer_budget_max_bytes",
+    "crypto_pending_buffer",
+    "max_client_frame",
+    "desync_all_full",
+    "beobachten",
+    "beobachten_minutes",
+    "beobachten_flush_secs",
+    "beobachten_file",
+    "hardswap",
+    "me_warmup_stagger_enabled",
+    "me_warmup_step_delay_ms",
+    "me_warmup_step_jitter_ms",
+    "me_reconnect_max_concurrent_per_dc",
+    "me_reconnect_backoff_base_ms",
+    "me_reconnect_backoff_cap_ms",
+    "me_reconnect_fast_retry_count",
+    "me_single_endpoint_shadow_writers",
+    "me_single_endpoint_outage_mode_enabled",
+    "me_single_endpoint_outage_disable_quarantine",
+    "me_single_endpoint_outage_backoff_min_ms",
+    "me_single_endpoint_outage_backoff_max_ms",
+    "me_single_endpoint_shadow_rotate_every_secs",
+    "me_floor_mode",
+    "me_adaptive_floor_idle_secs",
+    "me_adaptive_floor_min_writers_single_endpoint",
+    "me_adaptive_floor_min_writers_multi_endpoint",
+    "me_adaptive_floor_recover_grace_secs",
+    "me_adaptive_floor_writers_per_core_total",
+    "me_adaptive_floor_cpu_cores_override",
+    "me_adaptive_floor_max_extra_writers_single_per_core",
+    "me_adaptive_floor_max_extra_writers_multi_per_core",
+    "me_adaptive_floor_max_active_writers_per_core",
+    "me_adaptive_floor_max_warm_writers_per_core",
+    "me_adaptive_floor_max_active_writers_global",
+    "me_adaptive_floor_max_warm_writers_global",
+    "upstream_connect_retry_attempts",
+    "upstream_connect_retry_backoff_ms",
+    "upstream_connect_budget_ms",
+    "tg_connect",
+    "upstream_unhealthy_fail_threshold",
+    "upstream_connect_failfast_hard_errors",
+    "stun_iface_mismatch_ignore",
+    "unknown_dc_log_path",
+    "unknown_dc_file_log_enabled",
+    "log_level",
+    "disable_colors",
+    "telemetry",
+    "me_socks_kdf_policy",
+    "me_route_backpressure_enabled",
+    "me_route_fairshare_enabled",
+    "me_route_backpressure_base_timeout_ms",
+    "me_route_backpressure_high_timeout_ms",
+    "me_route_backpressure_high_watermark_pct",
+    "me_health_interval_ms_unhealthy",
+    "me_health_interval_ms_healthy",
+    "me_admission_poll_ms",
+    "me_warn_rate_limit_ms",
+    "me_route_no_writer_mode",
+    "me_route_no_writer_wait_ms",
+    "me_route_hybrid_max_wait_ms",
+    "me_route_blocking_send_timeout_ms",
+    "me_route_inline_recovery_attempts",
+    "me_route_inline_recovery_wait_ms",
+    "links",
+    "fast_mode_min_tls_record",
+    "update_every",
+    "me_reinit_every_secs",
+    "me_hardswap_warmup_delay_min_ms",
+    "me_hardswap_warmup_delay_max_ms",
+    "me_hardswap_warmup_extra_passes",
+    "me_hardswap_warmup_pass_backoff_base_ms",
+    "me_config_stable_snapshots",
+    "me_config_apply_cooldown_secs",
+    "me_snapshot_require_http_2xx",
+    "me_snapshot_reject_empty_map",
+    "me_snapshot_min_proxy_for_lines",
+    "proxy_secret_stable_snapshots",
+    "proxy_secret_rotate_runtime",
+    "me_secret_atomic_snapshot",
+    "proxy_secret_len_max",
+    "me_pool_drain_ttl_secs",
+    "me_instadrain",
+    "me_pool_drain_threshold",
+    "me_pool_drain_soft_evict_enabled",
+    "me_pool_drain_soft_evict_grace_secs",
+    "me_pool_drain_soft_evict_per_writer",
+    "me_pool_drain_soft_evict_budget_per_core",
+    "me_pool_drain_soft_evict_cooldown_ms",
+    "me_bind_stale_mode",
+    "me_bind_stale_ttl_secs",
+    "me_pool_min_fresh_ratio",
+    "me_reinit_drain_timeout_secs",
+    "proxy_secret_auto_reload_secs",
+    "proxy_config_auto_reload_secs",
+    "me_reinit_singleflight",
+    "me_reinit_trigger_channel",
+    "me_reinit_coalesce_window_ms",
+    "me_deterministic_writer_sort",
+    "me_writer_pick_mode",
+    "me_writer_pick_sample_size",
+    "ntp_check",
+    "ntp_servers",
+    "auto_degradation_enabled",
+    "degradation_min_unavailable_dc_groups",
+    "rst_on_close",
+];
+
+const NETWORK_CONFIG_KEYS: &[&str] = &[
+    "ipv4",
+    "ipv6",
+    "prefer",
+    "multipath",
+    "stun_use",
+    "stun_servers",
+    "stun_tcp_fallback",
+    "http_ip_detect_urls",
+    "cache_public_ip_path",
+    "dns_overrides",
+];
+
+const SERVER_CONFIG_KEYS: &[&str] = &[
+    "port",
+    "listen_addr_ipv4",
+    "listen_addr_ipv6",
+    "listen_unix_sock",
+    "listen_unix_sock_perm",
+    "listen_tcp",
+    "client_mss",
+    "client_mss_bulk",
+    "proxy_protocol",
+    "proxy_protocol_header_timeout_ms",
+    "proxy_protocol_trusted_cidrs",
+    "metrics_port",
+    "metrics_listen",
+    "metrics_whitelist",
+    "api",
+    "admin_api",
+    "listeners",
+    "listen_backlog",
+    "max_connections",
+    "accept_permit_timeout_ms",
+    "conntrack_control",
+];
+
+const API_CONFIG_KEYS: &[&str] = &[
+    "enabled",
+    "listen",
+    "whitelist",
+    "gray_action",
+    "auth_header",
+    "request_body_limit_bytes",
+    "minimal_runtime_enabled",
+    "minimal_runtime_cache_ttl_ms",
+    "runtime_edge_enabled",
+    "runtime_edge_cache_ttl_ms",
+    "runtime_edge_top_n",
+    "runtime_edge_events_capacity",
+    "read_only",
+];
+
+const CONNTRACK_CONTROL_CONFIG_KEYS: &[&str] = &[
+    "inline_conntrack_control",
+    "mode",
+    "backend",
+    "profile",
+    "hybrid_listener_ips",
+    "pressure_high_watermark_pct",
+    "pressure_low_watermark_pct",
+    "delete_budget_per_sec",
+];
+
+const LISTENER_CONFIG_KEYS: &[&str] = &[
+    "ip",
+    "port",
+    "client_mss",
+    "synlimit",
+    "synlimit_seconds",
+    "synlimit_hitcount",
+    "synlimit_burst",
+    "synlimit_ios_seconds",
+    "synlimit_ios_hitcount",
+    "synlimit_ios_burst",
+    "synlimit_hashlimit_expire_ms",
+    "synlimit_hashlimit_size",
+    "announce",
+    "announce_ip",
+    "proxy_protocol",
+    "reuse_allow",
+];
+
+const TIMEOUTS_CONFIG_KEYS: &[&str] = &[
+    "client_first_byte_idle_secs",
+    "client_handshake",
+    "relay_idle_policy_v2_enabled",
+    "relay_client_idle_soft_secs",
+    "relay_client_idle_hard_secs",
+    "relay_idle_grace_after_downstream_activity_secs",
+    "client_keepalive",
+    "client_ack",
+    "me_one_retry",
+    "me_one_timeout_ms",
+];
+
+const CENSORSHIP_CONFIG_KEYS: &[&str] = &[
+    "tls_domain",
+    "tls_domains",
+    "unknown_sni_action",
+    "tls_fetch_scope",
+    "tls_fetch",
+    "mask",
+    "mask_dynamic",
+    "mask_host",
+    "mask_port",
+    "exclusive_mask",
+    "mask_unix_sock",
+    "fake_cert_len",
+    "tls_emulation",
+    "tls_front_dir",
+    "server_hello_delay_min_ms",
+    "server_hello_delay_max_ms",
+    "tls_new_session_tickets",
+    "serverhello_compact",
+    "tls_full_cert_ttl_secs",
+    "alpn_enforce",
+    "mask_proxy_protocol",
+    "mask_shape_hardening",
+    "mask_shape_hardening_aggressive_mode",
+    "mask_shape_bucket_floor_bytes",
+    "mask_shape_bucket_cap_bytes",
+    "mask_shape_above_cap_blur",
+    "mask_shape_above_cap_blur_max_bytes",
+    "mask_relay_max_bytes",
+    "mask_relay_timeout_ms",
+    "mask_relay_idle_timeout_ms",
+    "mask_classifier_prefetch_timeout_ms",
+    "mask_timing_normalization_enabled",
+    "mask_timing_normalization_floor_ms",
+    "mask_timing_normalization_ceiling_ms",
+];
+
+const TLS_FETCH_CONFIG_KEYS: &[&str] = &[
+    "profiles",
+    "strict_route",
+    "attempt_timeout_ms",
+    "total_budget_ms",
+    "grease_enabled",
+    "deterministic",
+    "profile_cache_ttl_secs",
+];
+
+const ACCESS_CONFIG_KEYS: &[&str] = &[
+    "users",
+    "user_enabled",
+    "user_ad_tags",
+    "user_max_tcp_conns",
+    "user_max_tcp_conns_global_each",
+    "user_expirations",
+    "user_data_quota",
+    "user_rate_limits",
+    "cidr_rate_limits",
+    "user_max_unique_ips",
+    "user_max_unique_ips_global_each",
+    "user_max_unique_ips_mode",
+    "user_max_unique_ips_window_secs",
+    "replay_check_len",
+    "replay_window_secs",
+    "ignore_time_skew",
+];
+
+const RATE_LIMIT_BPS_CONFIG_KEYS: &[&str] = &["up_bps", "down_bps"];
+
+const UPSTREAM_CONFIG_KEYS: &[&str] = &[
+    "type",
+    "interface",
+    "bind_addresses",
+    "bindtodevice",
+    "force_bind",
+    "address",
+    "user_id",
+    "username",
+    "password",
+    "url",
+    "weight",
+    "enabled",
+    "scopes",
+    "ipv4",
+    "ipv6",
+];
+
+const PROXY_MODES_CONFIG_KEYS: &[&str] = &["classic", "secure", "tls"];
+const TELEMETRY_CONFIG_KEYS: &[&str] = &["core_enabled", "user_enabled", "me_level"];
+const LINKS_CONFIG_KEYS: &[&str] = &["show", "public_host", "public_port"];
+const LOGGING_CONFIG_KEYS: &[&str] = &[
+    "destination",
+    "path",
+    "rotation",
+    "max_size_bytes",
+    "max_files",
+    "max_age_secs",
+];
+
+#[derive(Debug)]
+struct UnknownConfigKey {
+    path: String,
+    suggestion: Option<String>,
+}
+
+fn table_at<'a>(value: &'a toml::Value, path: &[&str]) -> Option<&'a toml::Table> {
+    let mut current = value;
+    for segment in path {
+        current = current.get(*segment)?;
+    }
+    current.as_table()
+}
+
+fn is_strict_config(parsed_toml: &toml::Value) -> bool {
+    table_at(parsed_toml, &["general"])
+        .and_then(|table| table.get("config_strict"))
+        .and_then(toml::Value::as_bool)
+        .unwrap_or(false)
+}
+
+fn known_config_keys_for_suggestion() -> Vec<&'static str> {
+    let mut keys = Vec::new();
+    for group in [
+        TOP_LEVEL_CONFIG_KEYS,
+        GENERAL_CONFIG_KEYS,
+        NETWORK_CONFIG_KEYS,
+        SERVER_CONFIG_KEYS,
+        API_CONFIG_KEYS,
+        CONNTRACK_CONTROL_CONFIG_KEYS,
+        LISTENER_CONFIG_KEYS,
+        TIMEOUTS_CONFIG_KEYS,
+        CENSORSHIP_CONFIG_KEYS,
+        TLS_FETCH_CONFIG_KEYS,
+        ACCESS_CONFIG_KEYS,
+        RATE_LIMIT_BPS_CONFIG_KEYS,
+        UPSTREAM_CONFIG_KEYS,
+        PROXY_MODES_CONFIG_KEYS,
+        TELEMETRY_CONFIG_KEYS,
+        LINKS_CONFIG_KEYS,
+        LOGGING_CONFIG_KEYS,
+    ] {
+        keys.extend_from_slice(group);
+    }
+    keys
+}
+
+fn levenshtein_distance(a: &str, b: &str) -> usize {
+    let b_chars: Vec<char> = b.chars().collect();
+    let mut prev: Vec<usize> = (0..=b_chars.len()).collect();
+    let mut curr = vec![0usize; b_chars.len() + 1];
+
+    for (i, ca) in a.chars().enumerate() {
+        curr[0] = i + 1;
+        for (j, cb) in b_chars.iter().enumerate() {
+            let replace = if ca == *cb { prev[j] } else { prev[j] + 1 };
+            curr[j + 1] = (prev[j + 1] + 1).min(curr[j] + 1).min(replace);
+        }
+        std::mem::swap(&mut prev, &mut curr);
+    }
+
+    prev[b_chars.len()]
+}
+
+fn unknown_key_suggestion(key: &str, known_keys: &[&'static str]) -> Option<String> {
+    let normalized = key.to_ascii_lowercase();
+    let mut best: Option<(&str, usize)> = None;
+    for known in known_keys {
+        let distance = levenshtein_distance(&normalized, known);
+        let is_better = match best {
+            Some((_, best_distance)) => distance < best_distance,
+            None => true,
+        };
+        if distance <= 4 && is_better {
+            best = Some((known, distance));
+        }
+    }
+    best.map(|(known, _)| known.to_string())
+}
+
+fn push_unknown_keys(
+    unknown: &mut Vec<UnknownConfigKey>,
+    known_for_suggestion: &[&'static str],
+    path: &str,
+    table: &toml::Table,
+    allowed: &[&str],
+) {
+    for key in table.keys() {
+        if !allowed.contains(&key.as_str()) {
+            let full_path = if path.is_empty() {
+                key.clone()
+            } else {
+                format!("{path}.{key}")
+            };
+            unknown.push(UnknownConfigKey {
+                path: full_path,
+                suggestion: unknown_key_suggestion(key, known_for_suggestion),
+            });
+        }
+    }
+}
+
+fn check_known_table(
+    parsed_toml: &toml::Value,
+    unknown: &mut Vec<UnknownConfigKey>,
+    known_for_suggestion: &[&'static str],
+    path: &[&str],
+    allowed: &[&str],
+) {
+    if let Some(table) = table_at(parsed_toml, path) {
+        push_unknown_keys(
+            unknown,
+            known_for_suggestion,
+            &path.join("."),
+            table,
+            allowed,
+        );
+    }
+}
+
+fn check_nested_table_value(
+    unknown: &mut Vec<UnknownConfigKey>,
+    known_for_suggestion: &[&'static str],
+    path: String,
+    value: &toml::Value,
+    allowed: &[&str],
+) {
+    if let Some(table) = value.as_table() {
+        push_unknown_keys(unknown, known_for_suggestion, &path, table, allowed);
+    }
+}
+
+fn collect_unknown_config_keys(parsed_toml: &toml::Value) -> Vec<UnknownConfigKey> {
+    let known_for_suggestion = known_config_keys_for_suggestion();
+    let mut unknown = Vec::new();
+
+    if let Some(root) = parsed_toml.as_table() {
+        push_unknown_keys(
+            &mut unknown,
+            &known_for_suggestion,
+            "",
+            root,
+            TOP_LEVEL_CONFIG_KEYS,
+        );
+    }
+
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["general"],
+        GENERAL_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["general", "modes"],
+        PROXY_MODES_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["general", "telemetry"],
+        TELEMETRY_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["general", "links"],
+        LINKS_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["logging"],
+        LOGGING_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["network"],
+        NETWORK_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["server"],
+        SERVER_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["server", "api"],
+        API_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["server", "admin_api"],
+        API_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["server", "conntrack_control"],
+        CONNTRACK_CONTROL_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["timeouts"],
+        TIMEOUTS_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["censorship"],
+        CENSORSHIP_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["censorship", "tls_fetch"],
+        TLS_FETCH_CONFIG_KEYS,
+    );
+    check_known_table(
+        parsed_toml,
+        &mut unknown,
+        &known_for_suggestion,
+        &["access"],
+        ACCESS_CONFIG_KEYS,
+    );
+
+    if let Some(listeners) = table_at(parsed_toml, &["server"])
+        .and_then(|table| table.get("listeners"))
+        .and_then(toml::Value::as_array)
+    {
+        for (idx, listener) in listeners.iter().enumerate() {
+            check_nested_table_value(
+                &mut unknown,
+                &known_for_suggestion,
+                format!("server.listeners[{idx}]"),
+                listener,
+                LISTENER_CONFIG_KEYS,
+            );
+        }
+    }
+
+    if let Some(upstreams) = parsed_toml.get("upstreams").and_then(toml::Value::as_array) {
+        for (idx, upstream) in upstreams.iter().enumerate() {
+            check_nested_table_value(
+                &mut unknown,
+                &known_for_suggestion,
+                format!("upstreams[{idx}]"),
+                upstream,
+                UPSTREAM_CONFIG_KEYS,
+            );
+        }
+    }
+
+    for access_map in ["user_rate_limits", "cidr_rate_limits"] {
+        if let Some(table) = table_at(parsed_toml, &["access"])
+            .and_then(|access| access.get(access_map))
+            .and_then(toml::Value::as_table)
+        {
+            for (entry_name, value) in table {
+                check_nested_table_value(
+                    &mut unknown,
+                    &known_for_suggestion,
+                    format!("access.{access_map}.{entry_name}"),
+                    value,
+                    RATE_LIMIT_BPS_CONFIG_KEYS,
+                );
+            }
+        }
+    }
+
+    unknown
+}
+
+pub(super) fn handle_unknown_config_keys(parsed_toml: &toml::Value) -> Result<()> {
+    let unknown = collect_unknown_config_keys(parsed_toml);
+    if unknown.is_empty() {
+        return Ok(());
+    }
+
+    for item in &unknown {
+        if let Some(suggestion) = item.suggestion.as_deref() {
+            warn!(
+                key = %item.path,
+                suggestion = %suggestion,
+                "Unknown config key ignored; did you mean the suggested key?"
+            );
+        } else {
+            warn!(key = %item.path, "Unknown config key ignored");
+        }
+    }
+
+    if is_strict_config(parsed_toml) {
+        let mut paths = Vec::with_capacity(unknown.len());
+        for item in unknown {
+            if let Some(suggestion) = item.suggestion {
+                paths.push(format!("{} (did you mean `{}`?)", item.path, suggestion));
+            } else {
+                paths.push(item.path);
+            }
+        }
+        return Err(ProxyError::Config(format!(
+            "unknown config keys are not allowed when general.config_strict=true: {}",
+            paths.join(", ")
+        )));
+    }
+
+    Ok(())
+}

src/config/load/validation.rs

@@ -0,0 +1,111 @@
+use shadowsocks::config::ServerConfig as ShadowsocksServerConfig;
+use tracing::warn;
+
+use crate::error::{ProxyError, Result};
+
+use super::super::types::{LoggingConfig, LoggingDestination, NetworkConfig, UpstreamType};
+use super::ProxyConfig;
+
+pub(super) fn validate_network_cfg(net: &mut NetworkConfig) -> Result<()> {
+    if !net.ipv4 && matches!(net.ipv6, Some(false)) {
+        return Err(ProxyError::Config(
+            "Both ipv4 and ipv6 are disabled in [network]".to_string(),
+        ));
+    }
+
+    if net.prefer != 4 && net.prefer != 6 {
+        return Err(ProxyError::Config(
+            "network.prefer must be 4 or 6".to_string(),
+        ));
+    }
+
+    if !net.ipv4 && net.prefer == 4 {
+        warn!("prefer=4 but ipv4=false; forcing prefer=6");
+        net.prefer = 6;
+    }
+
+    if matches!(net.ipv6, Some(false)) && net.prefer == 6 {
+        warn!("prefer=6 but ipv6=false; forcing prefer=4");
+        net.prefer = 4;
+    }
+
+    Ok(())
+}
+
+pub(super) fn validate_logging_config(logging: &LoggingConfig) -> Result<()> {
+    if let Some(path) = logging.path.as_ref()
+        && path.trim().is_empty()
+    {
+        return Err(ProxyError::Config(
+            "logging.path cannot be empty when provided".to_string(),
+        ));
+    }
+
+    if matches!(logging.destination, LoggingDestination::File) && logging.path.is_none() {
+        return Err(ProxyError::Config(
+            "logging.path must be set when logging.destination=\"file\"".to_string(),
+        ));
+    }
+
+    Ok(())
+}
+
+pub(super) fn validate_upstreams(config: &ProxyConfig) -> Result<()> {
+    let has_enabled_shadowsocks = config.upstreams.iter().any(|upstream| {
+        upstream.enabled && matches!(upstream.upstream_type, UpstreamType::Shadowsocks { .. })
+    });
+
+    if has_enabled_shadowsocks && config.general.use_middle_proxy {
+        return Err(ProxyError::Config(
+            "shadowsocks upstreams require general.use_middle_proxy = false".to_string(),
+        ));
+    }
+
+    for upstream in &config.upstreams {
+        if matches!(upstream.ipv4, Some(false)) && matches!(upstream.ipv6, Some(false)) {
+            return Err(ProxyError::Config(
+                "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)
+                .map_err(|error| ProxyError::Config(format!("invalid shadowsocks url: {error}")))?;
+            if parsed.plugin().is_some() {
+                return Err(ProxyError::Config(
+                    "shadowsocks plugins are not supported".to_string(),
+                ));
+            }
+        }
+    }
+
+    Ok(())
+}
+
+pub(super) 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);
+        }
+    }
+}

src/config/tests/load_memory_envelope_tests.rs

@@ -95,22 +95,162 @@ max_client_frame = 16777217
     remove_temp_config(&path);
 }
 
+#[test]
+fn load_rejects_writer_byte_budget_below_frame_residency_minimum() {
+    let path = write_temp_config(
+        r#"
+[general]
+max_client_frame = 16777216
+me_writer_byte_budget_bytes = 33554432
+"#,
+    );
+
+    let err = ProxyConfig::load(&path)
+        .expect_err("writer byte budget below frame residency minimum must fail");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("general.me_writer_byte_budget_bytes must be within [33570816, 268435456]"),
+        "error must explain writer byte budget minimum, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_unaligned_writer_byte_budget() {
+    let path = write_temp_config(
+        r#"
+[general]
+me_writer_byte_budget_bytes = 33570817
+"#,
+    );
+
+    let err = ProxyConfig::load(&path)
+        .expect_err("writer byte budget outside permit granularity must fail");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("general.me_writer_byte_budget_bytes must be a multiple of 16384"),
+        "error must explain writer byte budget alignment, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_writer_byte_budget_above_hard_cap() {
+    let path = write_temp_config(
+        r#"
+[general]
+me_writer_byte_budget_bytes = 268451840
+"#,
+    );
+
+    let err = ProxyConfig::load(&path).expect_err("writer byte budget above hard cap must fail");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("general.me_writer_byte_budget_bytes must be within [33570816, 268435456]"),
+        "error must explain writer byte budget hard cap, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_unaligned_direct_relay_buffer_budget() {
+    let path = write_temp_config(
+        r#"
+[general]
+direct_relay_buffer_budget_max_bytes = 16777217
+"#,
+    );
+
+    let err = ProxyConfig::load(&path).expect_err("unaligned direct relay buffer budget must fail");
+    assert!(
+        err.to_string().contains(
+            "general.direct_relay_buffer_budget_max_bytes must be 0 or a multiple of 4096"
+        )
+    );
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_direct_relay_buffer_budget_above_hard_cap() {
+    let path = write_temp_config(
+        r#"
+[general]
+direct_relay_buffer_budget_max_bytes = 2147487744
+"#,
+    );
+
+    let err =
+        ProxyConfig::load(&path).expect_err("direct relay buffer budget above hard cap must fail");
+    assert!(err.to_string().contains(
+        "general.direct_relay_buffer_budget_max_bytes must be 0 or within [16777216, 2147483648]"
+    ));
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_listen_backlog_above_i32_upper_bound() {
+    let path = write_temp_config(
+        r#"
+[server]
+listen_backlog = 2147483648
+"#,
+    );
+
+    let err = ProxyConfig::load(&path).expect_err("listen_backlog above socket cap must fail");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("server.listen_backlog must be within [1, 2147483647]"),
+        "error must explain listen_backlog hard cap, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_zero_listen_backlog() {
+    let path = write_temp_config(
+        r#"
+[server]
+listen_backlog = 0
+"#,
+    );
+
+    let err = ProxyConfig::load(&path).expect_err("zero listen_backlog must fail");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("server.listen_backlog must be within [1, 2147483647]"),
+        "error must explain listen_backlog lower bound, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
 #[test]
 fn load_accepts_memory_limits_at_hard_upper_bounds() {
     let path = write_temp_config(
         r#"
 [general]
 me_writer_cmd_channel_capacity = 16384
+me_writer_byte_budget_bytes = 268435456
 me_route_channel_capacity = 8192
 me_c2me_channel_capacity = 8192
+direct_relay_buffer_budget_max_bytes = 2147483648
 max_client_frame = 16777216
 "#,
     );
 
     let cfg = ProxyConfig::load(&path).expect("hard upper bound values must be accepted");
     assert_eq!(cfg.general.me_writer_cmd_channel_capacity, 16384);
+    assert_eq!(cfg.general.me_writer_byte_budget_bytes, 256 * 1024 * 1024);
     assert_eq!(cfg.general.me_route_channel_capacity, 8192);
     assert_eq!(cfg.general.me_c2me_channel_capacity, 8192);
+    assert_eq!(
+        cfg.general.direct_relay_buffer_budget_max_bytes,
+        2 * 1024 * 1024 * 1024
+    );
     assert_eq!(cfg.general.max_client_frame, 16 * 1024 * 1024);
 
     remove_temp_config(&path);

src/config/types.rs

@@ -2,6 +2,7 @@ use chrono::{DateTime, Utc};
 use ipnetwork::IpNetwork;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
+use std::fmt;
 use std::net::IpAddr;
 use std::path::PathBuf;
 
@@ -63,6 +64,86 @@ impl std::fmt::Display for LogLevel {
     }
 }
 
+/// Logging output destination.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum LoggingDestination {
+    /// Write logs to stderr.
+    #[default]
+    Stderr,
+    /// Write logs to syslog on Unix platforms.
+    Syslog,
+    /// Write logs to a file.
+    File,
+}
+
+/// Time-based log rotation interval for file logging.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum LogRotation {
+    /// Do not rotate logs by time.
+    #[default]
+    Never,
+    /// Rotate once per minute.
+    Minutely,
+    /// Rotate once per hour.
+    Hourly,
+    /// Rotate once per day.
+    Daily,
+    /// Rotate once per week.
+    Weekly,
+}
+
+impl LogRotation {
+    /// Parse a CLI rotation value.
+    pub fn from_cli_arg(value: &str) -> Option<Self> {
+        match value.to_ascii_lowercase().as_str() {
+            "never" | "none" | "off" => Some(Self::Never),
+            "minutely" | "minute" => Some(Self::Minutely),
+            "hourly" | "hour" => Some(Self::Hourly),
+            "daily" | "day" => Some(Self::Daily),
+            "weekly" | "week" => Some(Self::Weekly),
+            _ => None,
+        }
+    }
+}
+
+/// File logging and retention settings.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LoggingConfig {
+    /// Effective logging destination.
+    #[serde(default)]
+    pub destination: LoggingDestination,
+    /// File path used when `destination = "file"`.
+    #[serde(default)]
+    pub path: Option<String>,
+    /// Time rotation interval for file logs.
+    #[serde(default)]
+    pub rotation: LogRotation,
+    /// Maximum active log file size before rotating. `0` disables size rotation.
+    #[serde(default)]
+    pub max_size_bytes: u64,
+    /// Maximum number of matching log files to keep. `0` disables count retention.
+    #[serde(default)]
+    pub max_files: usize,
+    /// Maximum age for rotated log files in seconds. `0` disables age retention.
+    #[serde(default)]
+    pub max_age_secs: u64,
+}
+
+impl Default for LoggingConfig {
+    fn default() -> Self {
+        Self {
+            destination: LoggingDestination::Stderr,
+            path: None,
+            rotation: LogRotation::Never,
+            max_size_bytes: 0,
+            max_files: 0,
+            max_age_secs: 0,
+        }
+    }
+}
+
 /// Middle-End telemetry verbosity level.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
 #[serde(rename_all = "lowercase")]
@@ -429,7 +510,7 @@ pub struct GeneralConfig {
     pub ad_tag: Option<String>,
 
     /// Public IP override for middle-proxy NAT environments.
-    /// When set, this IP is used in ME key derivation and RPC_PROXY_REQ "our_addr".
+    /// When set, this IP is used in ME key derivation and local address translation.
     #[serde(default)]
     pub middle_proxy_nat_ip: Option<IpAddr>,
 
@@ -498,6 +579,10 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_writer_cmd_channel_capacity")]
     pub me_writer_cmd_channel_capacity: usize,
 
+    /// Resident-memory budget in bytes for each ME writer data queue.
+    #[serde(default = "default_me_writer_byte_budget_bytes")]
+    pub me_writer_byte_budget_bytes: usize,
+
     /// Capacity of per-connection ME response route channel.
     #[serde(default = "default_me_route_channel_capacity")]
     pub me_route_channel_capacity: usize,
@@ -541,7 +626,7 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_d2c_frame_buf_shrink_threshold_bytes")]
     pub me_d2c_frame_buf_shrink_threshold_bytes: usize,
 
-    /// Copy buffer size for client->DC direction in direct relay.
+    /// Copy buffer ceiling for client->DC direction in direct relay.
     ///
     /// This is also the upper bound for one amortized upload rate-limit burst:
     /// upload debt is settled before the next relay read instead of blocking
@@ -549,13 +634,18 @@ pub struct GeneralConfig {
     #[serde(default = "default_direct_relay_copy_buf_c2s_bytes")]
     pub direct_relay_copy_buf_c2s_bytes: usize,
 
-    /// Copy buffer size for DC->client direction in direct relay.
+    /// Copy buffer ceiling for DC->client direction in direct relay.
     ///
     /// This bounds one direct download rate-limit grant because writes are
     /// clipped to the currently available shaper budget.
     #[serde(default = "default_direct_relay_copy_buf_s2c_bytes")]
     pub direct_relay_copy_buf_s2c_bytes: usize,
 
+    /// Process-wide hard ceiling for Direct relay copy buffers.
+    /// `0` derives the ceiling from host and cgroup memory limits.
+    #[serde(default = "default_direct_relay_buffer_budget_max_bytes")]
+    pub direct_relay_buffer_budget_max_bytes: usize,
+
     /// Max pending ciphertext buffer per client writer (bytes).
     /// Controls FakeTLS backpressure vs throughput.
     #[serde(default = "default_crypto_pending_buffer")]
@@ -1022,6 +1112,7 @@ impl Default for GeneralConfig {
             me_keepalive_payload_random: default_true(),
             rpc_proxy_req_every: default_rpc_proxy_req_every(),
             me_writer_cmd_channel_capacity: default_me_writer_cmd_channel_capacity(),
+            me_writer_byte_budget_bytes: default_me_writer_byte_budget_bytes(),
             me_route_channel_capacity: default_me_route_channel_capacity(),
             me_c2me_channel_capacity: default_me_c2me_channel_capacity(),
             me_c2me_send_timeout_ms: default_me_c2me_send_timeout_ms(),
@@ -1035,6 +1126,7 @@ impl Default for GeneralConfig {
                 default_me_d2c_frame_buf_shrink_threshold_bytes(),
             direct_relay_copy_buf_c2s_bytes: default_direct_relay_copy_buf_c2s_bytes(),
             direct_relay_copy_buf_s2c_bytes: default_direct_relay_copy_buf_s2c_bytes(),
+            direct_relay_buffer_budget_max_bytes: default_direct_relay_buffer_budget_max_bytes(),
             me_warmup_stagger_enabled: default_true(),
             me_warmup_step_delay_ms: default_warmup_step_delay_ms(),
             me_warmup_step_jitter_ms: default_warmup_step_jitter_ms(),
@@ -1369,6 +1461,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 two-tier SYN-fix rules with the hashlimit match.
+    Iptables,
+    /// Use nftables two-tier SYN-fix 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 +1614,20 @@ 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>,
+
+    /// Client-facing TCP MSS to switch to AFTER the TLS handshake (ServerHello)
+    /// is sent. Lets `client_mss` fragment ONLY the handshake (the DPI-inspected
+    /// part) while the bulk transfer uses normal-size packets — avoids the ~10x
+    /// packets-per-second blowup that triggers anti-DDoS abuse blocks on
+    /// pps-policing hosts. Empty/omitted = keep the handshake MSS for the whole
+    /// connection (previous behavior). Same preset/int grammar as `client_mss`.
+    #[serde(default)]
+    pub client_mss_bulk: 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 +1694,8 @@ impl Default for ServerConfig {
             listen_unix_sock: None,
             listen_unix_sock_perm: None,
             listen_tcp: None,
+            client_mss: None,
+            client_mss_bulk: None,
             proxy_protocol: false,
             proxy_protocol_header_timeout_ms: default_proxy_protocol_header_timeout_ms(),
             proxy_protocol_trusted_cidrs: default_proxy_protocol_trusted_cidrs(),
@@ -1720,6 +1899,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>,
 
@@ -1855,6 +2038,7 @@ 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(),
@@ -1926,11 +2110,13 @@ pub struct AccessConfig {
 
     /// Per-CIDR aggregate transport rate limits in bits-per-second.
     ///
-    /// Matching uses longest-prefix-wins semantics. A value of `0` in one
-    /// direction means "unlimited" for that direction. Limits are amortized
-    /// with the same bounded-burst contract as per-user rate limits.
+    /// Explicit CIDR keys use longest-prefix-wins semantics. Auto-template
+    /// keys (`*4/N`, `*6/N`, `*/N`) lazily create per-source-subnet buckets
+    /// after explicit CIDR matching misses. A value of `0` in one direction
+    /// means "unlimited" for that direction. Limits are amortized with the
+    /// same bounded-burst contract as per-user rate limits.
     #[serde(default)]
-    pub cidr_rate_limits: HashMap<IpNetwork, RateLimitBps>,
+    pub cidr_rate_limits: HashMap<CidrRateLimitKey, RateLimitBps>,
 
     /// Per-username client source IP/CIDR deny list. Checked after successful
     /// authentication; matching IPs get the same rejection path as invalid auth
@@ -1999,10 +2185,156 @@ impl AccessConfig {
     }
 }
 
+/// Key used by `access.cidr_rate_limits`.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum CidrRateLimitKey {
+    /// Explicit source CIDR rule.
+    Network(IpNetwork),
+    /// IPv4 auto-template that creates one bucket for each matching `/N`.
+    AutoV4(u8),
+    /// IPv6 auto-template that creates one bucket for each matching `/N`.
+    AutoV6(u8),
+    /// Dual-stack auto-template; IPv4 uses `/N`, IPv6 uses `/(N * 4)`.
+    AutoDual(u8),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub(crate) enum CidrAutoTemplateFamily {
+    V4,
+    V6,
+}
+
+impl CidrAutoTemplateFamily {
+    pub(crate) fn marker(self) -> &'static str {
+        match self {
+            Self::V4 => "*4",
+            Self::V6 => "*6",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub(crate) struct CidrAutoTemplate {
+    pub(crate) family: CidrAutoTemplateFamily,
+    pub(crate) prefix_len: u8,
+}
+
+impl fmt::Display for CidrAutoTemplate {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(formatter, "{}/{}", self.family.marker(), self.prefix_len)
+    }
+}
+
+impl CidrRateLimitKey {
+    pub(crate) fn auto_templates(&self) -> [Option<CidrAutoTemplate>; 2] {
+        match *self {
+            Self::Network(_) => [None, None],
+            Self::AutoV4(prefix_len) => [
+                Some(CidrAutoTemplate {
+                    family: CidrAutoTemplateFamily::V4,
+                    prefix_len,
+                }),
+                None,
+            ],
+            Self::AutoV6(prefix_len) => [
+                Some(CidrAutoTemplate {
+                    family: CidrAutoTemplateFamily::V6,
+                    prefix_len,
+                }),
+                None,
+            ],
+            Self::AutoDual(prefix_len) => [
+                Some(CidrAutoTemplate {
+                    family: CidrAutoTemplateFamily::V4,
+                    prefix_len,
+                }),
+                Some(CidrAutoTemplate {
+                    family: CidrAutoTemplateFamily::V6,
+                    prefix_len: prefix_len.saturating_mul(4),
+                }),
+            ],
+        }
+    }
+}
+
+impl fmt::Display for CidrRateLimitKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Network(cidr) => write!(formatter, "{cidr}"),
+            Self::AutoV4(prefix_len) => write!(formatter, "*4/{prefix_len}"),
+            Self::AutoV6(prefix_len) => write!(formatter, "*6/{prefix_len}"),
+            Self::AutoDual(prefix_len) => write!(formatter, "*/{prefix_len}"),
+        }
+    }
+}
+
+impl Serialize for CidrRateLimitKey {
+    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        serializer.collect_str(self)
+    }
+}
+
+impl<'de> Deserialize<'de> for CidrRateLimitKey {
+    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let value = String::deserialize(deserializer)?;
+        parse_cidr_rate_limit_key(&value).map_err(serde::de::Error::custom)
+    }
+}
+
+fn parse_cidr_rate_limit_key(value: &str) -> std::result::Result<CidrRateLimitKey, String> {
+    if let Some(prefix) = value.strip_prefix("*4/") {
+        return parse_cidr_auto_prefix(value, prefix, 32).map(CidrRateLimitKey::AutoV4);
+    }
+    if let Some(prefix) = value.strip_prefix("*6/") {
+        return parse_cidr_auto_prefix(value, prefix, 128).map(CidrRateLimitKey::AutoV6);
+    }
+    if let Some(prefix) = value.strip_prefix("*/") {
+        return parse_cidr_auto_prefix(value, prefix, 32).map(CidrRateLimitKey::AutoDual);
+    }
+    if value.starts_with('*') {
+        return Err(format!(
+            "invalid CIDR rate limit key {value:?}; expected CIDR, *4/N, *6/N, or */N"
+        ));
+    }
+    value
+        .parse::<IpNetwork>()
+        .map(CidrRateLimitKey::Network)
+        .map_err(|error| {
+            format!(
+                "invalid CIDR rate limit key {value:?}: {error}; expected CIDR, *4/N, *6/N, or */N"
+            )
+        })
+}
+
+fn parse_cidr_auto_prefix(
+    key: &str,
+    prefix: &str,
+    max_prefix: u8,
+) -> std::result::Result<u8, String> {
+    let prefix = prefix.parse::<u8>().map_err(|_| {
+        format!("invalid CIDR auto-template key {key:?}; prefix must be within 0..={max_prefix}")
+    })?;
+    if prefix > max_prefix {
+        return Err(format!(
+            "invalid CIDR auto-template key {key:?}; prefix must be within 0..={max_prefix}"
+        ));
+    }
+    Ok(prefix)
+}
+
+/// Transport rate limit in bits-per-second.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
 pub struct RateLimitBps {
+    /// Upload direction limit in bits-per-second; `0` means unlimited.
     #[serde(default)]
     pub up_bps: u64,
+    /// Download direction limit in bits-per-second; `0` means unlimited.
     #[serde(default)]
     pub down_bps: u64,
 }
@@ -2087,6 +2419,37 @@ 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,
+    /// Generic SYN-fix token-bucket rate interval.
+    #[serde(default = "default_synlimit_seconds")]
+    pub synlimit_seconds: u32,
+    /// Generic SYN-fix token-bucket rate amount.
+    #[serde(default = "default_synlimit_hitcount")]
+    pub synlimit_hitcount: u32,
+    /// Generic SYN-fix token-bucket burst size.
+    #[serde(default = "default_synlimit_burst")]
+    pub synlimit_burst: u32,
+    /// iOS-like SYN-fix token-bucket rate interval.
+    #[serde(default = "default_synlimit_ios_seconds")]
+    pub synlimit_ios_seconds: u32,
+    /// iOS-like SYN-fix token-bucket rate amount.
+    #[serde(default = "default_synlimit_ios_hitcount")]
+    pub synlimit_ios_hitcount: u32,
+    /// iOS-like SYN-fix token-bucket burst size.
+    #[serde(default = "default_synlimit_ios_burst")]
+    pub synlimit_ios_burst: u32,
+    /// Hashlimit entry expiration in milliseconds for iptables/ip6tables rules.
+    #[serde(default = "default_synlimit_hashlimit_expire_ms")]
+    pub synlimit_hashlimit_expire_ms: u32,
+    /// Hashlimit table size for iptables/ip6tables rules.
+    #[serde(default = "default_synlimit_hashlimit_size")]
+    pub synlimit_hashlimit_size: u32,
     /// IP address or hostname to announce in proxy links.
     /// Takes precedence over `announce_ip` if both are set.
     #[serde(default)]
@@ -2104,6 +2467,69 @@ 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())
+    }
+
+    /// Resolves the post-handshake (bulk transfer) client MSS, if configured.
+    pub fn client_mss_bulk_value(&self) -> std::result::Result<Option<u16>, String> {
+        parse_client_mss(self.client_mss_bulk.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/crypto/aes.rs

@@ -4,12 +4,12 @@
 //!
 //! ## Zeroize policy
 //!
-//! - `AesCbc` stores raw key/IV bytes and zeroizes them on drop.
-//! - `AesCtr` wraps an opaque `Aes256Ctr` cipher from the `ctr` crate.
-//!   The expanded key schedule lives inside that type and cannot be
-//!   zeroized from outside. Callers that hold raw key material (e.g.
-//!   `HandshakeSuccess`, `ObfuscationParams`) are responsible for
-//!   zeroizing their own copies.
+//! - `AesCbc` stores raw key/IV bytes and zeroizes them on drop. Temporary
+//!   expanded key schedules are also zeroized by the RustCrypto backend.
+//! - `AesCtr` uses the RustCrypto `zeroize` contract to clear its expanded
+//!   key schedule, counter, and buffered keystream on drop.
+//! - Callers that hold raw key material (e.g. `HandshakeSuccess`,
+//!   `ObfuscationParams`) remain responsible for zeroizing their own copies.
 
 #![allow(dead_code)]
 
@@ -19,24 +19,28 @@ use ctr::{
     Ctr128BE,
     cipher::{KeyIvInit, StreamCipher},
 };
-use zeroize::Zeroize;
+use zeroize::{Zeroize, ZeroizeOnDrop};
 
 type Aes256Ctr = Ctr128BE<Aes256>;
 
+static_assertions::assert_impl_all!(Aes256: ZeroizeOnDrop);
+static_assertions::assert_impl_all!(Aes256Ctr: ZeroizeOnDrop);
+
 // ============= AES-256-CTR =============
 
 /// AES-256-CTR encryptor/decryptor
 ///
 /// CTR mode is symmetric — encryption and decryption are the same operation.
 ///
-/// **Zeroize note:** The inner `Aes256Ctr` cipher state (expanded key schedule
-///     + counter) is opaque and cannot be zeroized. If you need to protect key
-///     material, zeroize the `[u8; 32]` key and `u128` IV at the call site
-///     before dropping them.
+/// **Zeroize note:** The inner `Aes256Ctr` zeroizes its expanded key schedule,
+/// counter, and buffered keystream on drop. Callers remain responsible for
+/// zeroizing their own raw key and IV copies.
 pub struct AesCtr {
     cipher: Aes256Ctr,
 }
 
+impl ZeroizeOnDrop for AesCtr {}
+
 impl AesCtr {
     /// Create new AES-CTR cipher with key and IV
     pub fn new(key: &[u8; 32], iv: u128) -> Self {
@@ -92,7 +96,7 @@ impl AesCtr {
 /// are different operations. This implementation handles CBC chaining
 /// correctly across multiple blocks.
 ///
-/// Key and IV are zeroized on drop.
+/// Key, IV, and temporary expanded key schedules are zeroized on drop.
 pub struct AesCbc {
     key: [u8; 32],
     iv: [u8; 16],
@@ -105,6 +109,8 @@ impl Drop for AesCbc {
     }
 }
 
+impl ZeroizeOnDrop for AesCbc {}
+
 impl AesCbc {
     /// AES block size
     const BLOCK_SIZE: usize = 16;

src/crypto/mod.rs

@@ -5,7 +5,7 @@ pub mod hash;
 pub mod random;
 
 pub use aes::{AesCbc, AesCtr};
-pub use hash::{
-    build_middleproxy_prekey, crc32, crc32c, derive_middleproxy_keys, sha256, sha256_hmac,
-};
+#[allow(unused_imports)]
+pub use hash::build_middleproxy_prekey;
+pub use hash::{crc32, crc32c, derive_middleproxy_keys, sha256, sha256_hmac};
 pub use random::SecureRandom;

src/logging.rs

@@ -5,16 +5,41 @@
 //! - syslog (Unix only, for traditional init systems)
 //! - file (with optional rotation)
 
-#![allow(dead_code)] // Infrastructure module - used via CLI flags
+// Infrastructure module used via CLI flags.
+#![allow(dead_code)]
 
 use std::path::Path;
 
+use crate::config::{LogRotation, LoggingConfig, LoggingDestination};
+
 use tracing_subscriber::layer::SubscriberExt;
 use tracing_subscriber::util::SubscriberInitExt;
 use tracing_subscriber::{EnvFilter, fmt, reload};
 
+// Submodules:
+// - file: bounded file appender for size and retention controls.
+mod file;
+
+#[cfg(test)]
+mod tests;
+
+/// File logging and retention options resolved from config and CLI.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FileLogOptions {
+    /// Log file path or rolling filename prefix path.
+    pub path: String,
+    /// Time rotation interval.
+    pub rotation: LogRotation,
+    /// Maximum active file size before size rotation. `0` disables it.
+    pub max_size_bytes: u64,
+    /// Maximum number of matching log files to keep. `0` disables it.
+    pub max_files: usize,
+    /// Maximum rotated file age in seconds. `0` disables it.
+    pub max_age_secs: u64,
+}
+
 /// Log destination configuration.
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub enum LogDestination {
     /// Log to stderr (default, captured by systemd journald).
     #[default]
@@ -24,12 +49,29 @@ pub enum LogDestination {
     Syslog,
     /// Log to a file with optional rotation.
     File {
-        path: String,
-        /// Rotate daily if true.
-        rotate_daily: bool,
+        /// Resolved file logging options.
+        options: FileLogOptions,
     },
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum LogCliDestination {
+    Stderr,
+    Syslog,
+    File,
+}
+
+/// Logging-related CLI overrides.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct LogCliOptions {
+    destination: Option<LogCliDestination>,
+    path: Option<String>,
+    rotation: Option<LogRotation>,
+    max_size_bytes: Option<u64>,
+    max_files: Option<usize>,
+    max_age_secs: Option<u64>,
+}
+
 /// Logging options parsed from CLI/config.
 #[derive(Debug, Clone, Default)]
 pub struct LoggingOptions {
@@ -101,23 +143,29 @@ pub fn init_logging(
             (filter_handle, LoggingGuard::noop())
         }
 
-        LogDestination::File { path, rotate_daily } => {
-            let (non_blocking, guard) = if *rotate_daily {
-                // Extract directory and filename prefix
-                let path = Path::new(path);
-                let dir = path.parent().unwrap_or(Path::new("/var/log"));
-                let prefix = path
-                    .file_name()
-                    .and_then(|s| s.to_str())
-                    .unwrap_or("telemt");
-
-                let file_appender = tracing_appender::rolling::daily(dir, prefix);
+        LogDestination::File { options } => {
+            let (non_blocking, guard) = if options.max_size_bytes > 0
+                || options.max_files > 0
+                || options.max_age_secs > 0
+            {
+                let file_appender = file::BoundedFileAppender::new(options.clone())
+                    .expect("Failed to open log file");
+                tracing_appender::non_blocking(file_appender)
+            } else if !matches!(options.rotation, LogRotation::Never) {
+                let path = Path::new(&options.path);
+                let dir = log_file_dir(path);
+                let prefix = log_file_name(path);
+                let file_appender = tracing_appender::rolling::RollingFileAppender::builder()
+                    .rotation(to_tracing_rotation(options.rotation))
+                    .filename_prefix(prefix)
+                    .build(dir)
+                    .expect("Failed to open log file");
                 tracing_appender::non_blocking(file_appender)
             } else {
                 let file = std::fs::OpenOptions::new()
                     .create(true)
                     .append(true)
-                    .open(path)
+                    .open(&options.path)
                     .expect("Failed to open log file");
                 tracing_appender::non_blocking(file)
             };
@@ -137,6 +185,28 @@ pub fn init_logging(
     }
 }
 
+fn log_file_dir(path: &Path) -> &Path {
+    path.parent()
+        .filter(|parent| !parent.as_os_str().is_empty())
+        .unwrap_or_else(|| Path::new("."))
+}
+
+fn log_file_name(path: &Path) -> &str {
+    path.file_name()
+        .and_then(|s| s.to_str())
+        .unwrap_or("telemt")
+}
+
+fn to_tracing_rotation(rotation: LogRotation) -> tracing_appender::rolling::Rotation {
+    match rotation {
+        LogRotation::Never => tracing_appender::rolling::Rotation::NEVER,
+        LogRotation::Minutely => tracing_appender::rolling::Rotation::MINUTELY,
+        LogRotation::Hourly => tracing_appender::rolling::Rotation::HOURLY,
+        LogRotation::Daily => tracing_appender::rolling::Rotation::DAILY,
+        LogRotation::Weekly => tracing_appender::rolling::Rotation::WEEKLY,
+    }
+}
+
 /// Syslog writer for tracing.
 #[cfg(unix)]
 #[derive(Clone, Copy)]
@@ -223,121 +293,172 @@ impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for SyslogMakeWriter {
     }
 }
 
-/// Parse log destination from CLI arguments.
-pub fn parse_log_destination(args: &[String]) -> LogDestination {
+/// Parse logging overrides from CLI arguments.
+pub fn parse_log_cli_options(args: &[String]) -> Result<LogCliOptions, String> {
+    let mut options = LogCliOptions::default();
     let mut i = 0;
     while i < args.len() {
         match args[i].as_str() {
             #[cfg(unix)]
             "--syslog" => {
-                return LogDestination::Syslog;
+                options.destination = Some(LogCliDestination::Syslog);
+            }
+            #[cfg(not(unix))]
+            "--syslog" => {
+                options.destination = Some(LogCliDestination::Syslog);
             }
             "--log-file" => {
                 i += 1;
                 if i < args.len() {
-                    return LogDestination::File {
-                        path: args[i].clone(),
-                        rotate_daily: false,
-                    };
+                    options.destination = Some(LogCliDestination::File);
+                    options.path = Some(args[i].clone());
+                } else {
+                    return Err("Missing value for --log-file".to_string());
                 }
             }
             s if s.starts_with("--log-file=") => {
-                return LogDestination::File {
-                    path: s.trim_start_matches("--log-file=").to_string(),
-                    rotate_daily: false,
-                };
+                options.destination = Some(LogCliDestination::File);
+                options.path = Some(s.trim_start_matches("--log-file=").to_string());
             }
             "--log-file-daily" => {
                 i += 1;
                 if i < args.len() {
-                    return LogDestination::File {
-                        path: args[i].clone(),
-                        rotate_daily: true,
-                    };
+                    options.destination = Some(LogCliDestination::File);
+                    options.path = Some(args[i].clone());
+                    options.rotation = Some(LogRotation::Daily);
+                } else {
+                    return Err("Missing value for --log-file-daily".to_string());
                 }
             }
             s if s.starts_with("--log-file-daily=") => {
-                return LogDestination::File {
-                    path: s.trim_start_matches("--log-file-daily=").to_string(),
-                    rotate_daily: true,
-                };
+                options.destination = Some(LogCliDestination::File);
+                options.path = Some(s.trim_start_matches("--log-file-daily=").to_string());
+                options.rotation = Some(LogRotation::Daily);
+            }
+            "--log-rotation" => {
+                i += 1;
+                if i < args.len() {
+                    options.rotation = Some(parse_rotation_cli_value(&args[i])?);
+                } else {
+                    return Err("Missing value for --log-rotation".to_string());
+                }
+            }
+            s if s.starts_with("--log-rotation=") => {
+                options.rotation = Some(parse_rotation_cli_value(
+                    s.trim_start_matches("--log-rotation="),
+                )?);
+            }
+            "--log-max-size-bytes" => {
+                i += 1;
+                if i < args.len() {
+                    options.max_size_bytes =
+                        Some(parse_u64_cli_value("--log-max-size-bytes", &args[i])?);
+                } else {
+                    return Err("Missing value for --log-max-size-bytes".to_string());
+                }
+            }
+            s if s.starts_with("--log-max-size-bytes=") => {
+                options.max_size_bytes = Some(parse_u64_cli_value(
+                    "--log-max-size-bytes",
+                    s.trim_start_matches("--log-max-size-bytes="),
+                )?);
+            }
+            "--log-max-files" => {
+                i += 1;
+                if i < args.len() {
+                    options.max_files = Some(parse_usize_cli_value("--log-max-files", &args[i])?);
+                } else {
+                    return Err("Missing value for --log-max-files".to_string());
+                }
+            }
+            s if s.starts_with("--log-max-files=") => {
+                options.max_files = Some(parse_usize_cli_value(
+                    "--log-max-files",
+                    s.trim_start_matches("--log-max-files="),
+                )?);
+            }
+            "--log-max-age-secs" => {
+                i += 1;
+                if i < args.len() {
+                    options.max_age_secs =
+                        Some(parse_u64_cli_value("--log-max-age-secs", &args[i])?);
+                } else {
+                    return Err("Missing value for --log-max-age-secs".to_string());
+                }
+            }
+            s if s.starts_with("--log-max-age-secs=") => {
+                options.max_age_secs = Some(parse_u64_cli_value(
+                    "--log-max-age-secs",
+                    s.trim_start_matches("--log-max-age-secs="),
+                )?);
             }
             _ => {}
         }
         i += 1;
     }
-    LogDestination::Stderr
+    Ok(options)
 }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
+fn parse_rotation_cli_value(value: &str) -> Result<LogRotation, String> {
+    LogRotation::from_cli_arg(value).ok_or_else(|| {
+        format!(
+            "Invalid --log-rotation value '{value}'. Expected never|minutely|hourly|daily|weekly"
+        )
+    })
+}
 
-    #[test]
-    fn test_parse_log_destination_default() {
-        let args: Vec<String> = vec![];
-        assert!(matches!(
-            parse_log_destination(&args),
-            LogDestination::Stderr
-        ));
-    }
+fn parse_u64_cli_value(flag: &str, value: &str) -> Result<u64, String> {
+    value
+        .parse::<u64>()
+        .map_err(|_| format!("Invalid {flag} value '{value}'. Expected unsigned integer"))
+}
 
-    #[test]
-    fn test_parse_log_destination_file() {
-        let args = vec!["--log-file".to_string(), "/var/log/telemt.log".to_string()];
-        match parse_log_destination(&args) {
-            LogDestination::File { path, rotate_daily } => {
-                assert_eq!(path, "/var/log/telemt.log");
-                assert!(!rotate_daily);
+fn parse_usize_cli_value(flag: &str, value: &str) -> Result<usize, String> {
+    value
+        .parse::<usize>()
+        .map_err(|_| format!("Invalid {flag} value '{value}'. Expected unsigned integer"))
+}
+
+/// Resolve effective logging destination from config and CLI overrides.
+pub fn resolve_log_destination(
+    config: &LoggingConfig,
+    cli: &LogCliOptions,
+) -> Result<LogDestination, String> {
+    let destination = cli.destination.unwrap_or(match config.destination {
+        LoggingDestination::Stderr => LogCliDestination::Stderr,
+        LoggingDestination::Syslog => LogCliDestination::Syslog,
+        LoggingDestination::File => LogCliDestination::File,
+    });
+
+    match destination {
+        LogCliDestination::Stderr => Ok(LogDestination::Stderr),
+        LogCliDestination::Syslog => {
+            #[cfg(unix)]
+            {
+                Ok(LogDestination::Syslog)
             }
-            _ => panic!("Expected File destination"),
-        }
-    }
-
-    #[test]
-    fn test_parse_log_destination_file_daily() {
-        let args = vec!["--log-file-daily=/var/log/telemt".to_string()];
-        match parse_log_destination(&args) {
-            LogDestination::File { path, rotate_daily } => {
-                assert_eq!(path, "/var/log/telemt");
-                assert!(rotate_daily);
+            #[cfg(not(unix))]
+            {
+                Err("Syslog logging is only supported on Unix platforms".to_string())
             }
-            _ => panic!("Expected File destination"),
         }
-    }
+        LogCliDestination::File => {
+            let path = cli.path.as_ref().or(config.path.as_ref()).ok_or_else(|| {
+                "logging.path or --log-file must be set when file logging is enabled".to_string()
+            })?;
+            if path.trim().is_empty() {
+                return Err("Log file path cannot be empty".to_string());
+            }
 
-    #[cfg(unix)]
-    #[test]
-    fn test_parse_log_destination_syslog() {
-        let args = vec!["--syslog".to_string()];
-        assert!(matches!(
-            parse_log_destination(&args),
-            LogDestination::Syslog
-        ));
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn test_syslog_priority_for_level_mapping() {
-        assert_eq!(
-            syslog_priority_for_level(&tracing::Level::ERROR),
-            libc::LOG_ERR
-        );
-        assert_eq!(
-            syslog_priority_for_level(&tracing::Level::WARN),
-            libc::LOG_WARNING
-        );
-        assert_eq!(
-            syslog_priority_for_level(&tracing::Level::INFO),
-            libc::LOG_INFO
-        );
-        assert_eq!(
-            syslog_priority_for_level(&tracing::Level::DEBUG),
-            libc::LOG_DEBUG
-        );
-        assert_eq!(
-            syslog_priority_for_level(&tracing::Level::TRACE),
-            libc::LOG_DEBUG
-        );
+            Ok(LogDestination::File {
+                options: FileLogOptions {
+                    path: path.clone(),
+                    rotation: cli.rotation.unwrap_or(config.rotation),
+                    max_size_bytes: cli.max_size_bytes.unwrap_or(config.max_size_bytes),
+                    max_files: cli.max_files.unwrap_or(config.max_files),
+                    max_age_secs: cli.max_age_secs.unwrap_or(config.max_age_secs),
+                },
+            })
+        }
     }
 }

src/logging/file.rs

@@ -0,0 +1,395 @@
+use std::fs::{self, File, OpenOptions};
+use std::io::{self, Write};
+use std::path::{Path, PathBuf};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use chrono::{DateTime, Datelike, Duration as ChronoDuration, Utc};
+
+use crate::config::LogRotation;
+
+use super::FileLogOptions;
+
+const CLEANUP_INTERVAL_SECS: i64 = 60;
+
+/// File appender with size rotation and local retention cleanup.
+pub(crate) struct BoundedFileAppender {
+    options: FileLogOptions,
+    dir: PathBuf,
+    base_name: String,
+    current_path: PathBuf,
+    current_size: u64,
+    last_cleanup: DateTime<Utc>,
+    file: Option<File>,
+    now: Box<dyn Fn() -> DateTime<Utc> + Send + Sync>,
+}
+
+impl BoundedFileAppender {
+    pub(crate) fn new(options: FileLogOptions) -> io::Result<Self> {
+        Self::with_now(options, Box::new(Utc::now))
+    }
+
+    fn with_now(
+        options: FileLogOptions,
+        now: Box<dyn Fn() -> DateTime<Utc> + Send + Sync>,
+    ) -> io::Result<Self> {
+        let path = Path::new(&options.path);
+        let dir = path
+            .parent()
+            .filter(|parent| !parent.as_os_str().is_empty())
+            .unwrap_or_else(|| Path::new("."))
+            .to_path_buf();
+        let base_name = path
+            .file_name()
+            .and_then(|name| name.to_str())
+            .unwrap_or("telemt")
+            .to_string();
+
+        let start = now();
+        let current_path = active_path_for(&dir, &base_name, options.rotation, &start);
+        let (file, current_size) = open_append_file(&current_path)?;
+        let mut appender = Self {
+            options,
+            dir,
+            base_name,
+            current_path,
+            current_size,
+            last_cleanup: start,
+            file: Some(file),
+            now,
+        };
+        appender.cleanup(&start);
+        Ok(appender)
+    }
+
+    fn now(&self) -> DateTime<Utc> {
+        (self.now)()
+    }
+
+    fn refresh_active_path(&mut self, now: &DateTime<Utc>) -> io::Result<bool> {
+        let next_path = active_path_for(&self.dir, &self.base_name, self.options.rotation, now);
+        if next_path == self.current_path {
+            return Ok(false);
+        }
+
+        self.close_current()?;
+        self.current_path = next_path;
+        self.open_current()?;
+        Ok(true)
+    }
+
+    fn rotate_for_size(&mut self, now: &DateTime<Utc>) -> io::Result<()> {
+        self.close_current()?;
+        if self.current_path.exists() {
+            let archive_path = self.archive_path(now);
+            fs::rename(&self.current_path, archive_path)?;
+        }
+        self.open_current()
+    }
+
+    fn archive_path(&self, now: &DateTime<Utc>) -> PathBuf {
+        let file_name = self
+            .current_path
+            .file_name()
+            .and_then(|name| name.to_str())
+            .unwrap_or(&self.base_name);
+        let stamp = now.format("%Y%m%d%H%M%S");
+        for seq in 0..1000 {
+            let candidate = self.dir.join(format!("{file_name}.{stamp}.{seq}"));
+            if !candidate.exists() {
+                return candidate;
+            }
+        }
+        self.dir.join(format!("{file_name}.{stamp}.overflow"))
+    }
+
+    fn open_current(&mut self) -> io::Result<()> {
+        let (file, current_size) = open_append_file(&self.current_path)?;
+        self.file = Some(file);
+        self.current_size = current_size;
+        Ok(())
+    }
+
+    fn close_current(&mut self) -> io::Result<()> {
+        if let Some(mut file) = self.file.take() {
+            file.flush()?;
+        }
+        Ok(())
+    }
+
+    fn should_rotate_for_size(&self, incoming_len: usize) -> bool {
+        self.options.max_size_bytes > 0
+            && self.current_size > 0
+            && self.current_size.saturating_add(incoming_len as u64) > self.options.max_size_bytes
+    }
+
+    fn cleanup_due(&self, now: &DateTime<Utc>) -> bool {
+        self.options.max_age_secs > 0
+            && now.signed_duration_since(self.last_cleanup)
+                >= ChronoDuration::seconds(CLEANUP_INTERVAL_SECS)
+    }
+
+    fn cleanup(&mut self, now: &DateTime<Utc>) {
+        self.last_cleanup = now.clone();
+        let Ok(entries) = fs::read_dir(&self.dir) else {
+            return;
+        };
+
+        let mut candidates = Vec::new();
+        let prefix = format!("{}.", self.base_name);
+        for entry in entries.flatten() {
+            let path = entry.path();
+            let Ok(file_type) = entry.file_type() else {
+                continue;
+            };
+            if !file_type.is_file() {
+                continue;
+            }
+
+            let is_current = path == self.current_path;
+            let Some(name) = entry.file_name().to_str().map(|name| name.to_string()) else {
+                continue;
+            };
+            if !is_current && !name.starts_with(&prefix) {
+                continue;
+            }
+
+            let Ok(metadata) = entry.metadata() else {
+                continue;
+            };
+            let modified = metadata.modified().unwrap_or(UNIX_EPOCH);
+            candidates.push(LogFileCandidate {
+                path,
+                modified,
+                is_current,
+            });
+        }
+
+        if self.options.max_age_secs > 0 {
+            let cutoff = system_time_from_utc(now)
+                .checked_sub(Duration::from_secs(self.options.max_age_secs))
+                .unwrap_or(UNIX_EPOCH);
+            candidates.retain(|candidate| {
+                if candidate.is_current || candidate.modified >= cutoff {
+                    true
+                } else {
+                    let _ = fs::remove_file(&candidate.path);
+                    false
+                }
+            });
+        }
+
+        if self.options.max_files > 0 && candidates.len() > self.options.max_files {
+            let mut archives: Vec<_> = candidates
+                .into_iter()
+                .filter(|candidate| !candidate.is_current)
+                .collect();
+            archives.sort_by_key(|candidate| candidate.modified);
+            let mut total = archives.len() + 1;
+            for candidate in archives {
+                if total <= self.options.max_files {
+                    break;
+                }
+                let _ = fs::remove_file(candidate.path);
+                total -= 1;
+            }
+        }
+    }
+}
+
+impl Write for BoundedFileAppender {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        let now = self.now();
+        let rotated_by_time = self.refresh_active_path(&now)?;
+        if self.should_rotate_for_size(buf.len()) {
+            self.rotate_for_size(&now)?;
+            self.cleanup(&now);
+        } else if rotated_by_time || self.cleanup_due(&now) {
+            self.cleanup(&now);
+        }
+
+        let Some(file) = self.file.as_mut() else {
+            return Err(io::Error::new(
+                io::ErrorKind::Other,
+                "bounded log file is not open",
+            ));
+        };
+        file.write_all(buf)?;
+        self.current_size = self.current_size.saturating_add(buf.len() as u64);
+        Ok(buf.len())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        if let Some(file) = self.file.as_mut() {
+            file.flush()
+        } else {
+            Ok(())
+        }
+    }
+}
+
+struct LogFileCandidate {
+    path: PathBuf,
+    modified: SystemTime,
+    is_current: bool,
+}
+
+fn open_append_file(path: &Path) -> io::Result<(File, u64)> {
+    let mut options = OpenOptions::new();
+    options.create(true).append(true);
+
+    let file = match options.open(path) {
+        Ok(file) => file,
+        Err(error) => {
+            let Some(parent) = path
+                .parent()
+                .filter(|parent| !parent.as_os_str().is_empty())
+            else {
+                return Err(error);
+            };
+            fs::create_dir_all(parent)?;
+            options.open(path)?
+        }
+    };
+    let current_size = file.metadata()?.len();
+    Ok((file, current_size))
+}
+
+fn active_path_for(
+    dir: &Path,
+    base_name: &str,
+    rotation: LogRotation,
+    now: &DateTime<Utc>,
+) -> PathBuf {
+    match rotation {
+        LogRotation::Never => dir.join(base_name),
+        LogRotation::Minutely | LogRotation::Hourly | LogRotation::Daily | LogRotation::Weekly => {
+            dir.join(format!("{base_name}.{}", period_suffix_for(rotation, now)))
+        }
+    }
+}
+
+fn period_suffix_for(rotation: LogRotation, now: &DateTime<Utc>) -> String {
+    match rotation {
+        LogRotation::Never | LogRotation::Daily => now.format("%Y-%m-%d").to_string(),
+        LogRotation::Hourly => now.format("%Y-%m-%d-%H").to_string(),
+        LogRotation::Minutely => now.format("%Y-%m-%d-%H-%M").to_string(),
+        LogRotation::Weekly => {
+            let days_since_sunday = now.weekday().num_days_from_sunday() as i64;
+            let week_start = now.date_naive() - ChronoDuration::days(days_since_sunday);
+            week_start.format("%Y-%m-%d").to_string()
+        }
+    }
+}
+
+fn system_time_from_utc(now: &DateTime<Utc>) -> SystemTime {
+    let duration = Duration::new(now.timestamp().unsigned_abs(), now.timestamp_subsec_nanos());
+    if now.timestamp() >= 0 {
+        UNIX_EPOCH + duration
+    } else {
+        UNIX_EPOCH - duration
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::io::Write;
+
+    use tempfile::tempdir;
+
+    use super::*;
+
+    fn fixed_now() -> DateTime<Utc> {
+        DateTime::<Utc>::from(UNIX_EPOCH + Duration::from_secs(10))
+    }
+
+    fn options(path: PathBuf) -> FileLogOptions {
+        FileLogOptions {
+            path: path.to_string_lossy().to_string(),
+            rotation: LogRotation::Never,
+            max_size_bytes: 0,
+            max_files: 0,
+            max_age_secs: 0,
+        }
+    }
+
+    fn matching_logs(dir: &Path) -> Vec<PathBuf> {
+        let mut files: Vec<_> = fs::read_dir(dir)
+            .unwrap()
+            .flatten()
+            .map(|entry| entry.path())
+            .filter(|path| {
+                path.file_name()
+                    .and_then(|name| name.to_str())
+                    .map(|name| name.starts_with("telemt.log"))
+                    .unwrap_or(false)
+            })
+            .collect();
+        files.sort();
+        files
+    }
+
+    #[test]
+    fn size_rotation_keeps_latest_write_in_active_file() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("telemt.log");
+        let mut options = options(path.clone());
+        options.max_size_bytes = 6;
+
+        let mut appender = BoundedFileAppender::with_now(options, Box::new(fixed_now)).unwrap();
+        appender.write_all(b"abc\n").unwrap();
+        appender.write_all(b"def\n").unwrap();
+        appender.flush().unwrap();
+
+        assert_eq!(fs::read_to_string(path).unwrap(), "def\n");
+        assert_eq!(matching_logs(dir.path()).len(), 2);
+    }
+
+    #[test]
+    fn max_files_retention_removes_oldest_archives() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("telemt.log");
+        let mut options = options(path);
+        options.max_size_bytes = 4;
+        options.max_files = 2;
+
+        let mut appender = BoundedFileAppender::with_now(options, Box::new(fixed_now)).unwrap();
+        for line in [b"aa\n", b"bb\n", b"cc\n", b"dd\n"] {
+            appender.write_all(line).unwrap();
+        }
+        appender.flush().unwrap();
+
+        assert!(matching_logs(dir.path()).len() <= 2);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn max_age_retention_removes_old_archives() {
+        use std::ffi::CString;
+        use std::os::unix::ffi::OsStrExt;
+
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("telemt.log");
+        let old_archive = dir.path().join("telemt.log.20000101000000.0");
+        fs::write(&old_archive, "old").unwrap();
+
+        let c_path = CString::new(old_archive.as_os_str().as_bytes()).unwrap();
+        let times = [
+            libc::timespec {
+                tv_sec: 0,
+                tv_nsec: 0,
+            },
+            libc::timespec {
+                tv_sec: 0,
+                tv_nsec: 0,
+            },
+        ];
+        let rc = unsafe { libc::utimensat(libc::AT_FDCWD, c_path.as_ptr(), times.as_ptr(), 0) };
+        assert_eq!(rc, 0);
+
+        let mut options = options(path);
+        options.max_age_secs = 1;
+        let _appender = BoundedFileAppender::with_now(options, Box::new(fixed_now)).unwrap();
+
+        assert!(!old_archive.exists());
+    }
+}

src/logging/tests.rs

@@ -0,0 +1,100 @@
+use super::*;
+
+#[test]
+fn test_parse_log_cli_options_default() {
+    let args: Vec<String> = vec![];
+    let options = parse_log_cli_options(&args).unwrap();
+    assert_eq!(
+        resolve_log_destination(&LoggingConfig::default(), &options).unwrap(),
+        LogDestination::Stderr
+    );
+}
+
+#[test]
+fn test_parse_log_cli_options_file() {
+    let args = vec!["--log-file".to_string(), "/var/log/telemt.log".to_string()];
+    let options = parse_log_cli_options(&args).unwrap();
+    match resolve_log_destination(&LoggingConfig::default(), &options).unwrap() {
+        LogDestination::File { options } => {
+            assert_eq!(options.path, "/var/log/telemt.log");
+            assert_eq!(options.rotation, LogRotation::Never);
+        }
+        _ => panic!("Expected File destination"),
+    }
+}
+
+#[test]
+fn test_parse_log_cli_options_file_daily() {
+    let args = vec!["--log-file-daily=/var/log/telemt".to_string()];
+    let options = parse_log_cli_options(&args).unwrap();
+    match resolve_log_destination(&LoggingConfig::default(), &options).unwrap() {
+        LogDestination::File { options } => {
+            assert_eq!(options.path, "/var/log/telemt");
+            assert_eq!(options.rotation, LogRotation::Daily);
+        }
+        _ => panic!("Expected File destination"),
+    }
+}
+
+#[test]
+fn test_parse_log_cli_options_bounds() {
+    let args = vec![
+        "--log-file=/var/log/telemt.log".to_string(),
+        "--log-rotation=hourly".to_string(),
+        "--log-max-size-bytes=1024".to_string(),
+        "--log-max-files=3".to_string(),
+        "--log-max-age-secs=60".to_string(),
+    ];
+    let options = parse_log_cli_options(&args).unwrap();
+    match resolve_log_destination(&LoggingConfig::default(), &options).unwrap() {
+        LogDestination::File { options } => {
+            assert_eq!(options.rotation, LogRotation::Hourly);
+            assert_eq!(options.max_size_bytes, 1024);
+            assert_eq!(options.max_files, 3);
+            assert_eq!(options.max_age_secs, 60);
+        }
+        _ => panic!("Expected File destination"),
+    }
+}
+
+#[test]
+fn test_parse_log_cli_options_rejects_bad_rotation() {
+    let args = vec!["--log-rotation=yearly".to_string()];
+    assert!(parse_log_cli_options(&args).is_err());
+}
+
+#[cfg(unix)]
+#[test]
+fn test_parse_log_cli_options_syslog() {
+    let args = vec!["--syslog".to_string()];
+    let options = parse_log_cli_options(&args).unwrap();
+    assert_eq!(
+        resolve_log_destination(&LoggingConfig::default(), &options).unwrap(),
+        LogDestination::Syslog
+    );
+}
+
+#[cfg(unix)]
+#[test]
+fn test_syslog_priority_for_level_mapping() {
+    assert_eq!(
+        syslog_priority_for_level(&tracing::Level::ERROR),
+        libc::LOG_ERR
+    );
+    assert_eq!(
+        syslog_priority_for_level(&tracing::Level::WARN),
+        libc::LOG_WARNING
+    );
+    assert_eq!(
+        syslog_priority_for_level(&tracing::Level::INFO),
+        libc::LOG_INFO
+    );
+    assert_eq!(
+        syslog_priority_for_level(&tracing::Level::DEBUG),
+        libc::LOG_DEBUG
+    );
+    assert_eq!(
+        syslog_priority_for_level(&tracing::Level::TRACE),
+        libc::LOG_DEBUG
+    );
+}

src/maestro/helpers.rs

@@ -9,7 +9,7 @@ use tracing::{debug, error, info, warn};
 
 use crate::cli;
 use crate::config::ProxyConfig;
-use crate::logging::LogDestination;
+use crate::logging::LogCliOptions;
 use crate::transport::UpstreamManager;
 use crate::transport::middle_proxy::{
     ProxyConfigData, fetch_proxy_config_with_raw_via_upstream, load_proxy_config_cache,
@@ -113,7 +113,7 @@ pub(crate) struct CliArgs {
     pub data_path: Option<PathBuf>,
     pub silent: bool,
     pub log_level: Option<String>,
-    pub log_destination: LogDestination,
+    pub log_cli_options: LogCliOptions,
 }
 
 pub(crate) fn parse_cli() -> CliArgs {
@@ -125,8 +125,13 @@ pub(crate) fn parse_cli() -> CliArgs {
 
     let args: Vec<String> = std::env::args().skip(1).collect();
 
-    // Parse log destination
-    let log_destination = crate::logging::parse_log_destination(&args);
+    let log_cli_options = match crate::logging::parse_log_cli_options(&args) {
+        Ok(options) => options,
+        Err(error) => {
+            eprintln!("[telemt] {error}");
+            std::process::exit(2);
+        }
+    };
 
     // Check for --init first (handled before tokio)
     if let Some(init_opts) = cli::parse_init_args(&args) {
@@ -180,6 +185,21 @@ pub(crate) fn parse_cli() -> CliArgs {
             s if s.starts_with("--log-level=") => {
                 log_level = Some(s.trim_start_matches("--log-level=").to_string());
             }
+            "--log-file" | "--log-file-daily" => {
+                i += 1;
+            }
+            s if s.starts_with("--log-file=") || s.starts_with("--log-file-daily=") => {}
+            "--log-rotation"
+            | "--log-max-size-bytes"
+            | "--log-max-files"
+            | "--log-max-age-secs" => {
+                i += 1;
+            }
+            s if s.starts_with("--log-rotation=")
+                || s.starts_with("--log-max-size-bytes=")
+                || s.starts_with("--log-max-files=")
+                || s.starts_with("--log-max-age-secs=") => {}
+            "--syslog" => {}
             "--help" | "-h" => {
                 print_help();
                 std::process::exit(0);
@@ -192,7 +212,8 @@ pub(crate) fn parse_cli() -> CliArgs {
             "--daemon" | "-d" | "--foreground" | "-f" => {}
             s if s.starts_with("--pid-file") => {
                 if !s.contains('=') {
-                    i += 1; // skip value
+                    // Skip the pid-file value consumed by daemon argument parsing.
+                    i += 1;
                 }
             }
             s if s.starts_with("--run-as-user") => {
@@ -224,7 +245,7 @@ pub(crate) fn parse_cli() -> CliArgs {
         data_path,
         silent,
         log_level,
-        log_destination,
+        log_cli_options,
     }
 }
 
@@ -254,6 +275,10 @@ fn print_help() {
     eprintln!("Logging options:");
     eprintln!("  --log-file <PATH>       Log to file (default: stderr)");
     eprintln!("  --log-file-daily <PATH> Log to file with daily rotation");
+    eprintln!("  --log-rotation <MODE>   never|minutely|hourly|daily|weekly");
+    eprintln!("  --log-max-size-bytes N  Rotate file logs when active file exceeds N bytes");
+    eprintln!("  --log-max-files N       Keep at most N matching file logs (0 disables)");
+    eprintln!("  --log-max-age-secs N    Remove rotated file logs older than N seconds");
     #[cfg(unix)]
     eprintln!("  --syslog                Log to syslog (Unix only)");
     eprintln!();

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/me_startup.rs

@@ -208,6 +208,8 @@ pub(crate) async fn initialize_me_pool(
                     me_nat_probe,
                     None,
                     config.network.stun_servers.clone(),
+                    config.network.stun_tcp_fallback,
+                    config.network.http_ip_detect_urls.clone(),
                     config.general.stun_nat_probe_concurrency,
                     probe.detected_ipv6,
                     config.timeouts.me_one_retry,
@@ -277,6 +279,7 @@ pub(crate) async fn initialize_me_pool(
                     config.general.me_writer_pick_sample_size,
                     config.general.me_socks_kdf_policy,
                     config.general.me_writer_cmd_channel_capacity,
+                    config.general.me_writer_byte_budget_bytes,
                     config.general.me_route_channel_capacity,
                     config.general.me_route_backpressure_enabled,
                     config.general.me_route_fairshare_enabled,

src/maestro/mod.rs

@@ -33,6 +33,9 @@ use crate::conntrack_control;
 use crate::crypto::SecureRandom;
 use crate::ip_tracker::UserIpTracker;
 use crate::network::probe::{decide_network_capabilities, log_probe_result, run_probe};
+use crate::proxy::direct_buffer_budget::{
+    DirectBufferBudget, resolve_direct_buffer_hard_limit, spawn_direct_buffer_budget_controller,
+};
 use crate::proxy::route_mode::{RelayRouteMode, RouteRuntimeController};
 use crate::proxy::shared_state::ProxySharedState;
 use crate::startup::{
@@ -45,6 +48,7 @@ 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::{
@@ -107,7 +111,7 @@ async fn run_telemt_core(
     let data_path = cli_args.data_path;
     let cli_silent = cli_args.silent;
     let cli_log_level = cli_args.log_level;
-    let log_destination = cli_args.log_destination;
+    let log_cli_options = cli_args.log_cli_options;
     let startup_cwd = match std::env::current_dir() {
         Ok(cwd) => cwd,
         Err(e) => {
@@ -330,6 +334,14 @@ async fn run_telemt_core(
     };
 
     let initial_filter_spec = runtime_tasks::log_filter_spec(has_rust_log, &effective_log_level);
+    let log_destination =
+        match crate::logging::resolve_log_destination(&config.logging, &log_cli_options) {
+            Ok(destination) => destination,
+            Err(error) => {
+                eprintln!("[telemt] {error}");
+                std::process::exit(1);
+            }
+        };
     let (filter_layer, filter_handle) =
         reload::Layer::new(EnvFilter::new(initial_filter_spec.clone()));
     startup_tracker
@@ -464,7 +476,16 @@ async fn run_telemt_core(
             config.network.dns_overrides.len()
         );
     }
-    let shared_state = ProxySharedState::new();
+    let direct_buffer_hard_limit =
+        resolve_direct_buffer_hard_limit(config.general.direct_relay_buffer_budget_max_bytes).await;
+    let direct_buffer_budget = DirectBufferBudget::new(direct_buffer_hard_limit);
+    info!(
+        hard_limit_bytes = direct_buffer_hard_limit,
+        configured_override_bytes = config.general.direct_relay_buffer_budget_max_bytes,
+        "Direct relay buffer budget initialized"
+    );
+    let shared_state =
+        ProxySharedState::new_with_direct_buffer_budget(direct_buffer_budget.clone());
     shared_state.apply_user_enabled_config(&config.access.user_enabled);
     shared_state.traffic_limiter.apply_policy(
         config.access.user_rate_limits.clone(),
@@ -873,6 +894,13 @@ async fn run_telemt_core(
         stats.clone(),
         shared_state.clone(),
     );
+    spawn_direct_buffer_budget_controller(
+        direct_buffer_budget,
+        buffer_pool.clone(),
+        stats.clone(),
+        shared_state.clone(),
+        config.server.max_connections,
+    );
 
     let bound = listeners::bind_listeners(
         &config,
@@ -909,6 +937,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/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

@@ -381,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"
@@ -420,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=\"{}\"}} {}",
@@ -559,6 +595,81 @@ async fn render_metrics(
         "telemt_buffer_pool_buffers_total{{kind=\"in_use\"}} {}",
         stats.get_buffer_pool_in_use_gauge()
     );
+    let _ = writeln!(
+        out,
+        "# HELP telemt_buffer_pool_events_total Buffer-pool allocation lifecycle events"
+    );
+    let _ = writeln!(out, "# TYPE telemt_buffer_pool_events_total counter");
+    let _ = writeln!(
+        out,
+        "telemt_buffer_pool_events_total{{event=\"replaced_nonstandard\"}} {}",
+        stats.get_buffer_pool_replaced_nonstandard_total()
+    );
+
+    let direct_budget = shared_state.direct_buffer_budget.snapshot();
+    let _ = writeln!(
+        out,
+        "# HELP telemt_direct_relay_buffer_budget_bytes Direct relay copy-buffer budget and memory inputs"
+    );
+    let _ = writeln!(out, "# TYPE telemt_direct_relay_buffer_budget_bytes gauge");
+    for (kind, value) in [
+        ("hard_limit", direct_budget.hard_limit_bytes),
+        ("target", direct_budget.target_bytes),
+        ("reserved", direct_budget.reserved_bytes),
+        ("memory_total", direct_budget.memory_total_bytes),
+        ("memory_available", direct_budget.memory_available_bytes),
+        ("process_rss", direct_budget.process_rss_bytes),
+    ] {
+        let _ = writeln!(
+            out,
+            "telemt_direct_relay_buffer_budget_bytes{{kind=\"{}\"}} {}",
+            kind, value
+        );
+    }
+    let _ = writeln!(
+        out,
+        "# HELP telemt_direct_relay_buffer_budget_events_total Direct relay buffer-budget lifecycle events"
+    );
+    let _ = writeln!(
+        out,
+        "# TYPE telemt_direct_relay_buffer_budget_events_total counter"
+    );
+    for (result, value) in [
+        ("promotion", direct_budget.promotion_total),
+        ("promotion_denied", direct_budget.promotion_denied_total),
+        ("minimum_fallback", direct_budget.minimum_fallback_total),
+        ("admission_rejected", direct_budget.admission_rejected_total),
+        ("quiet_demotion", direct_budget.quiet_demotion_total),
+        (
+            "write_pressure_demotion",
+            direct_budget.write_pressure_demotion_total,
+        ),
+        (
+            "global_pressure_demotion",
+            direct_budget.global_pressure_demotion_total,
+        ),
+    ] {
+        let _ = writeln!(
+            out,
+            "telemt_direct_relay_buffer_budget_events_total{{result=\"{}\"}} {}",
+            result, value
+        );
+    }
+    let _ = writeln!(
+        out,
+        "# HELP telemt_direct_relay_buffer_sessions Current Direct relay sessions by adaptive tier"
+    );
+    let _ = writeln!(out, "# TYPE telemt_direct_relay_buffer_sessions gauge");
+    for (tier, value) in ["base", "tier1", "tier2", "tier3"]
+        .into_iter()
+        .zip(direct_budget.tier_sessions)
+    {
+        let _ = writeln!(
+            out,
+            "telemt_direct_relay_buffer_sessions{{tier=\"{}\"}} {}",
+            tier, value
+        );
+    }
 
     let _ = writeln!(
         out,
@@ -2399,6 +2510,82 @@ async fn render_metrics(
         }
     );
 
+    let _ = writeln!(
+        out,
+        "# HELP telemt_me_writer_byte_budget_limit_bytes Configured resident-memory budget per ME writer"
+    );
+    let _ = writeln!(out, "# TYPE telemt_me_writer_byte_budget_limit_bytes gauge");
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_byte_budget_limit_bytes {}",
+        if me_allows_normal {
+            stats.get_me_writer_byte_budget_limit_bytes_gauge()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "# HELP telemt_me_writer_byte_budget_reserved_bytes Aggregate ME writer memory reservations by lifecycle state"
+    );
+    let _ = writeln!(
+        out,
+        "# TYPE telemt_me_writer_byte_budget_reserved_bytes gauge"
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_byte_budget_reserved_bytes{{state=\"queued\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_byte_budget_queued_bytes_gauge()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_byte_budget_reserved_bytes{{state=\"inflight\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_byte_budget_inflight_bytes_gauge()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "# HELP telemt_me_writer_byte_budget_events_total ME writer byte-budget outcomes"
+    );
+    let _ = writeln!(
+        out,
+        "# TYPE telemt_me_writer_byte_budget_events_total counter"
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_byte_budget_events_total{{result=\"wait\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_byte_budget_wait_total()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_byte_budget_events_total{{result=\"timeout\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_byte_budget_timeout_total()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_byte_budget_events_total{{result=\"oversize\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_byte_budget_oversize_total()
+        } else {
+            0
+        }
+    );
+
     let _ = writeln!(
         out,
         "# HELP telemt_me_writer_pick_total ME writer-pick outcomes by mode and result"
@@ -3901,7 +4088,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 {
@@ -3915,6 +4115,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(),
@@ -3933,6 +4134,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"
@@ -4045,7 +4258,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/network/probe.rs

@@ -12,7 +12,7 @@ use tracing::{debug, info, warn};
 use crate::config::{NetworkConfig, UpstreamConfig, UpstreamType};
 use crate::error::Result;
 use crate::network::stun::{
-    DualStunResult, IpFamily, StunProbeResult, stun_probe_family_with_bind,
+    DualStunResult, IpFamily, StunProbeResult, stun_probe_family_with_bind_and_tcp_fallback,
 };
 use crate::transport::UpstreamManager;
 
@@ -58,6 +58,7 @@ impl NetworkDecision {
 }
 
 const STUN_BATCH_TIMEOUT: Duration = Duration::from_secs(5);
+const STUN_BATCH_TCP_FALLBACK_TIMEOUT: Duration = Duration::from_secs(12);
 
 pub async fn run_probe(
     config: &NetworkConfig,
@@ -81,8 +82,14 @@ pub async fn run_probe(
             warn!("STUN probe is enabled but network.stun_servers is empty");
             DualStunResult::default()
         } else {
-            probe_stun_servers_parallel(&servers, stun_nat_probe_concurrency.max(1), None, None)
-                .await
+            probe_stun_servers_parallel(
+                &servers,
+                stun_nat_probe_concurrency.max(1),
+                None,
+                None,
+                config.stun_tcp_fallback,
+            )
+            .await
         }
     } else if nat_probe {
         info!("STUN probe is disabled by network.stun_use=false");
@@ -163,6 +170,7 @@ pub async fn run_probe(
             stun_nat_probe_concurrency.max(1),
             bind_v4,
             bind_v6,
+            config.stun_tcp_fallback,
         )
         .await;
         if let Some(reflected) = direct_stun_res.v4.map(|r| r.reflected_addr) {
@@ -234,7 +242,7 @@ pub async fn run_probe(
     Ok(probe)
 }
 
-async fn detect_public_ipv4_http(urls: &[String]) -> Option<Ipv4Addr> {
+pub(crate) async fn detect_public_ipv4_http(urls: &[String]) -> Option<Ipv4Addr> {
     let client = reqwest::Client::builder()
         .timeout(Duration::from_secs(3))
         .build()
@@ -277,6 +285,7 @@ async fn probe_stun_servers_parallel(
     concurrency: usize,
     bind_v4: Option<IpAddr>,
     bind_v6: Option<IpAddr>,
+    tcp_fallback: bool,
 ) -> DualStunResult {
     let mut join_set = JoinSet::new();
     let mut next_idx = 0usize;
@@ -288,9 +297,26 @@ async fn probe_stun_servers_parallel(
             let stun_addr = servers[next_idx].clone();
             next_idx += 1;
             join_set.spawn(async move {
-                let res = timeout(STUN_BATCH_TIMEOUT, async {
-                    let v4 = stun_probe_family_with_bind(&stun_addr, IpFamily::V4, bind_v4).await?;
-                    let v6 = stun_probe_family_with_bind(&stun_addr, IpFamily::V6, bind_v6).await?;
+                let batch_timeout = if tcp_fallback {
+                    STUN_BATCH_TCP_FALLBACK_TIMEOUT
+                } else {
+                    STUN_BATCH_TIMEOUT
+                };
+                let res = timeout(batch_timeout, async {
+                    let v4 = stun_probe_family_with_bind_and_tcp_fallback(
+                        &stun_addr,
+                        IpFamily::V4,
+                        bind_v4,
+                        tcp_fallback,
+                    )
+                    .await?;
+                    let v6 = stun_probe_family_with_bind_and_tcp_fallback(
+                        &stun_addr,
+                        IpFamily::V6,
+                        bind_v6,
+                        tcp_fallback,
+                    )
+                    .await?;
                     Ok::<DualStunResult, crate::error::ProxyError>(DualStunResult { v4, v6 })
                 })
                 .await;

src/network/stun.rs

@@ -4,7 +4,8 @@
 use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
 use std::sync::OnceLock;
 
-use tokio::net::{UdpSocket, lookup_host};
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::{TcpSocket, UdpSocket, lookup_host};
 use tokio::time::{Duration, sleep, timeout};
 
 use crate::crypto::SecureRandom;
@@ -36,9 +37,16 @@ pub struct DualStunResult {
 }
 
 pub async fn stun_probe_dual(stun_addr: &str) -> Result<DualStunResult> {
+    stun_probe_dual_with_tcp_fallback(stun_addr, false).await
+}
+
+pub async fn stun_probe_dual_with_tcp_fallback(
+    stun_addr: &str,
+    tcp_fallback: bool,
+) -> Result<DualStunResult> {
     let (v4, v6) = tokio::join!(
-        stun_probe_family(stun_addr, IpFamily::V4),
-        stun_probe_family(stun_addr, IpFamily::V6),
+        stun_probe_family_with_tcp_fallback(stun_addr, IpFamily::V4, tcp_fallback),
+        stun_probe_family_with_tcp_fallback(stun_addr, IpFamily::V6, tcp_fallback),
     );
 
     Ok(DualStunResult { v4: v4?, v6: v6? })
@@ -48,13 +56,44 @@ pub async fn stun_probe_family(
     stun_addr: &str,
     family: IpFamily,
 ) -> Result<Option<StunProbeResult>> {
-    stun_probe_family_with_bind(stun_addr, family, None).await
+    stun_probe_family_with_tcp_fallback(stun_addr, family, false).await
+}
+
+pub async fn stun_probe_family_with_tcp_fallback(
+    stun_addr: &str,
+    family: IpFamily,
+    tcp_fallback: bool,
+) -> Result<Option<StunProbeResult>> {
+    stun_probe_family_with_bind_and_tcp_fallback(stun_addr, family, None, tcp_fallback).await
 }
 
 pub async fn stun_probe_family_with_bind(
     stun_addr: &str,
     family: IpFamily,
     bind_ip: Option<IpAddr>,
+) -> Result<Option<StunProbeResult>> {
+    stun_probe_family_with_bind_and_tcp_fallback(stun_addr, family, bind_ip, false).await
+}
+
+pub async fn stun_probe_family_with_bind_and_tcp_fallback(
+    stun_addr: &str,
+    family: IpFamily,
+    bind_ip: Option<IpAddr>,
+    tcp_fallback: bool,
+) -> Result<Option<StunProbeResult>> {
+    let udp_attempts = if tcp_fallback { 1 } else { 3 };
+    let udp_result = stun_probe_family_udp(stun_addr, family, bind_ip, udp_attempts).await?;
+    if udp_result.is_some() || !tcp_fallback {
+        return Ok(udp_result);
+    }
+    stun_probe_family_tcp(stun_addr, family, bind_ip).await
+}
+
+async fn stun_probe_family_udp(
+    stun_addr: &str,
+    family: IpFamily,
+    bind_ip: Option<IpAddr>,
+    max_attempts: u8,
 ) -> Result<Option<StunProbeResult>> {
     let bind_addr = match (family, bind_ip) {
         (IpFamily::V4, Some(IpAddr::V4(ip))) => SocketAddr::new(IpAddr::V4(ip), 0),
@@ -94,12 +133,7 @@ pub async fn stun_probe_family_with_bind(
         return Ok(None);
     }
 
-    let mut req = [0u8; 20];
-    req[0..2].copy_from_slice(&0x0001u16.to_be_bytes()); // Binding Request
-    req[2..4].copy_from_slice(&0u16.to_be_bytes()); // length
-    req[4..8].copy_from_slice(&0x2112A442u32.to_be_bytes()); // magic cookie
-    stun_rng().fill(&mut req[8..20]); // transaction ID
-
+    let req = build_binding_request();
     let mut buf = [0u8; 256];
     let mut attempt = 0;
     let mut backoff = Duration::from_secs(1);
@@ -115,7 +149,7 @@ pub async fn stun_probe_family_with_bind(
             Ok(Err(e)) => return Err(ProxyError::Proxy(format!("STUN recv failed: {e}"))),
             Err(_) => {
                 attempt += 1;
-                if attempt >= 3 {
+                if attempt >= max_attempts {
                     return Ok(None);
                 }
                 sleep(backoff).await;
@@ -128,19 +162,139 @@ pub async fn stun_probe_family_with_bind(
             return Ok(None);
         }
 
-        let magic = 0x2112A442u32.to_be_bytes();
         let txid = &req[8..20];
-        let mut idx = 20;
-        while idx + 4 <= n {
-            let atype = u16::from_be_bytes(buf[idx..idx + 2].try_into().unwrap());
-            let alen = u16::from_be_bytes(buf[idx + 2..idx + 4].try_into().unwrap()) as usize;
-            idx += 4;
-            if idx + alen > n {
-                break;
-            }
+        if let Some(reflected_addr) = parse_reflected_addr(&buf[..n], txid) {
+            let local_addr = socket
+                .local_addr()
+                .map_err(|e| ProxyError::Proxy(format!("STUN local_addr failed: {e}")))?;
+            return Ok(Some(StunProbeResult {
+                local_addr,
+                reflected_addr,
+                family,
+            }));
+        }
+    }
 
-            match atype {
-            0x0020 /* XOR-MAPPED-ADDRESS */ | 0x0001 /* MAPPED-ADDRESS */ => {
+    Ok(None)
+}
+
+async fn stun_probe_family_tcp(
+    stun_addr: &str,
+    family: IpFamily,
+    bind_ip: Option<IpAddr>,
+) -> Result<Option<StunProbeResult>> {
+    let target_addr = match resolve_stun_addr(stun_addr, family).await? {
+        Some(addr) => addr,
+        None => return Ok(None),
+    };
+    let socket = match family {
+        IpFamily::V4 => TcpSocket::new_v4(),
+        IpFamily::V6 => TcpSocket::new_v6(),
+    }
+    .map_err(|e| ProxyError::Proxy(format!("STUN TCP socket failed: {e}")))?;
+    match (family, bind_ip) {
+        (IpFamily::V4, Some(IpAddr::V4(ip))) => {
+            if socket.bind(SocketAddr::new(IpAddr::V4(ip), 0)).is_err() {
+                return Ok(None);
+            }
+        }
+        (IpFamily::V6, Some(IpAddr::V6(ip))) => {
+            if socket.bind(SocketAddr::new(IpAddr::V6(ip), 0)).is_err() {
+                return Ok(None);
+            }
+        }
+        (IpFamily::V4, Some(IpAddr::V6(_))) | (IpFamily::V6, Some(IpAddr::V4(_))) => {
+            return Ok(None);
+        }
+        (_, None) => {}
+    }
+
+    let connect_res = timeout(Duration::from_secs(3), socket.connect(target_addr)).await;
+    let mut stream = match connect_res {
+        Ok(Ok(stream)) => stream,
+        Ok(Err(e))
+            if family == IpFamily::V6
+                && matches!(
+                    e.kind(),
+                    std::io::ErrorKind::NetworkUnreachable
+                        | std::io::ErrorKind::HostUnreachable
+                        | std::io::ErrorKind::Unsupported
+                        | std::io::ErrorKind::NetworkDown
+                ) =>
+        {
+            return Ok(None);
+        }
+        Ok(Err(e)) => return Err(ProxyError::Proxy(format!("STUN TCP connect failed: {e}"))),
+        Err(_) => return Ok(None),
+    };
+
+    let req = build_binding_request();
+    timeout(Duration::from_secs(3), stream.write_all(&req))
+        .await
+        .map_err(|_| ProxyError::Proxy("STUN TCP send timeout".to_string()))?
+        .map_err(|e| ProxyError::Proxy(format!("STUN TCP send failed: {e}")))?;
+
+    let mut header = [0u8; 20];
+    timeout(Duration::from_secs(3), stream.read_exact(&mut header))
+        .await
+        .map_err(|_| ProxyError::Proxy("STUN TCP header timeout".to_string()))?
+        .map_err(|e| ProxyError::Proxy(format!("STUN TCP header read failed: {e}")))?;
+    let body_len = u16::from_be_bytes([header[2], header[3]]) as usize;
+    if body_len > 236 {
+        return Ok(None);
+    }
+    let mut buf = [0u8; 256];
+    buf[..20].copy_from_slice(&header);
+    if body_len > 0 {
+        timeout(
+            Duration::from_secs(3),
+            stream.read_exact(&mut buf[20..20 + body_len]),
+        )
+        .await
+        .map_err(|_| ProxyError::Proxy("STUN TCP body timeout".to_string()))?
+        .map_err(|e| ProxyError::Proxy(format!("STUN TCP body read failed: {e}")))?;
+    }
+
+    let txid = &req[8..20];
+    let Some(reflected_addr) = parse_reflected_addr(&buf[..20 + body_len], txid) else {
+        return Ok(None);
+    };
+    let local_addr = stream
+        .local_addr()
+        .map_err(|e| ProxyError::Proxy(format!("STUN TCP local_addr failed: {e}")))?;
+    Ok(Some(StunProbeResult {
+        local_addr,
+        reflected_addr,
+        family,
+    }))
+}
+
+fn build_binding_request() -> [u8; 20] {
+    let mut req = [0u8; 20];
+    req[0..2].copy_from_slice(&0x0001u16.to_be_bytes());
+    req[2..4].copy_from_slice(&0u16.to_be_bytes());
+    req[4..8].copy_from_slice(&0x2112A442u32.to_be_bytes());
+    stun_rng().fill(&mut req[8..20]);
+    req
+}
+
+fn parse_reflected_addr(buf: &[u8], txid: &[u8]) -> Option<SocketAddr> {
+    if buf.len() < 20 {
+        return None;
+    }
+
+    let magic = 0x2112A442u32.to_be_bytes();
+    let mut idx = 20;
+    while idx + 4 <= buf.len() {
+        let atype = u16::from_be_bytes(buf[idx..idx + 2].try_into().ok()?);
+        let alen = u16::from_be_bytes(buf[idx + 2..idx + 4].try_into().ok()?) as usize;
+        idx += 4;
+        if idx + alen > buf.len() {
+            break;
+        }
+
+        match atype {
+            0x0020 | 0x0001 => {
                 if alen < 8 {
                     break;
                 }
@@ -157,7 +311,6 @@ pub async fn stun_probe_family_with_bind(
 
                 let raw_ip = &buf[idx + 4..idx + 4 + len_check];
                 let mut port = u16::from_be_bytes(port_bytes);
-
                 let reflected_ip = if atype == 0x0020 {
                     port ^= ((magic[0] as u16) << 8) | magic[1] as u16;
                     match family_byte {
@@ -172,7 +325,9 @@ pub async fn stun_probe_family_with_bind(
                         }
                         0x02 => {
                             let mut ip = [0u8; 16];
-                            let xor_key = [magic.as_slice(), txid].concat();
+                            let mut xor_key = [0u8; 16];
+                            xor_key[..4].copy_from_slice(&magic);
+                            xor_key[4..].copy_from_slice(txid.get(..12)?);
                             for (i, b) in raw_ip.iter().enumerate().take(16) {
                                 ip[i] = *b ^ xor_key[i];
                             }
@@ -185,34 +340,24 @@ pub async fn stun_probe_family_with_bind(
                     }
                 } else {
                     match family_byte {
-                        0x01 => IpAddr::V4(Ipv4Addr::new(raw_ip[0], raw_ip[1], raw_ip[2], raw_ip[3])),
-                        0x02 => IpAddr::V6(Ipv6Addr::from(<[u8; 16]>::try_from(raw_ip).unwrap())),
+                        0x01 => {
+                            IpAddr::V4(Ipv4Addr::new(raw_ip[0], raw_ip[1], raw_ip[2], raw_ip[3]))
+                        }
+                        0x02 => IpAddr::V6(Ipv6Addr::from(<[u8; 16]>::try_from(raw_ip).ok()?)),
                         _ => {
                             idx += (alen + 3) & !3;
                             continue;
                         }
                     }
                 };
-
-                let reflected_addr = SocketAddr::new(reflected_ip, port);
-                let local_addr = socket
-                    .local_addr()
-                    .map_err(|e| ProxyError::Proxy(format!("STUN local_addr failed: {e}")))?;
-
-                return Ok(Some(StunProbeResult {
-                    local_addr,
-                    reflected_addr,
-                    family,
-                }));
+                return Some(SocketAddr::new(reflected_ip, port));
             }
             _ => {}
         }
 
-            idx += (alen + 3) & !3;
-        }
+        idx += (alen + 3) & !3;
     }
-
-    Ok(None)
+    None
 }
 
 async fn resolve_stun_addr(stun_addr: &str, family: IpFamily) -> Result<Option<SocketAddr>> {
@@ -245,3 +390,58 @@ async fn resolve_stun_addr(stun_addr: &str, family: IpFamily) -> Result<Option<S
     });
     Ok(target)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_reflected_addr_reads_mapped_ipv4() {
+        let txid = [0u8; 12];
+        let mut response = [0u8; 32];
+        response[0..2].copy_from_slice(&0x0101u16.to_be_bytes());
+        response[2..4].copy_from_slice(&12u16.to_be_bytes());
+        response[4..8].copy_from_slice(&0x2112A442u32.to_be_bytes());
+        response[20..22].copy_from_slice(&0x0001u16.to_be_bytes());
+        response[22..24].copy_from_slice(&8u16.to_be_bytes());
+        response[25] = 0x01;
+        response[26..28].copy_from_slice(&443u16.to_be_bytes());
+        response[28..32].copy_from_slice(&[203, 0, 113, 9]);
+
+        let reflected = parse_reflected_addr(&response, &txid).unwrap();
+        assert_eq!(
+            reflected,
+            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 9)), 443)
+        );
+    }
+
+    #[test]
+    fn parse_reflected_addr_reads_xor_mapped_ipv4() {
+        let txid = [0u8; 12];
+        let magic = 0x2112A442u32.to_be_bytes();
+        let port = 443u16;
+        let ip = [203u8, 0, 113, 9];
+        let xport = port ^ (((magic[0] as u16) << 8) | magic[1] as u16);
+        let xip = [
+            ip[0] ^ magic[0],
+            ip[1] ^ magic[1],
+            ip[2] ^ magic[2],
+            ip[3] ^ magic[3],
+        ];
+        let mut response = [0u8; 32];
+        response[0..2].copy_from_slice(&0x0101u16.to_be_bytes());
+        response[2..4].copy_from_slice(&12u16.to_be_bytes());
+        response[4..8].copy_from_slice(&0x2112A442u32.to_be_bytes());
+        response[20..22].copy_from_slice(&0x0020u16.to_be_bytes());
+        response[22..24].copy_from_slice(&8u16.to_be_bytes());
+        response[25] = 0x01;
+        response[26..28].copy_from_slice(&xport.to_be_bytes());
+        response[28..32].copy_from_slice(&xip);
+
+        let reflected = parse_reflected_addr(&response, &txid).unwrap();
+        assert_eq!(
+            reflected,
+            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 9)), 443)
+        );
+    }
+}

src/protocol/constants.rs

@@ -5,6 +5,9 @@
 use std::net::{IpAddr, Ipv4Addr};
 
 use crate::crypto::SecureRandom;
+use crate::protocol::framing::{
+    secure_version_d_body_len_from_wire_len, secure_version_d_padding_len,
+};
 use std::sync::LazyLock;
 
 // ============= Telegram Datacenters =============
@@ -236,22 +239,20 @@ pub fn is_valid_secure_payload_len(data_len: usize) -> bool {
 }
 
 /// Compute Secure Intermediate payload length from wire length.
-/// Secure mode strips up to 3 random tail bytes by truncating to 4-byte boundary.
+/// Secure mode cannot distinguish full-word padding from payload, so only the
+/// non-aligned tail bytes are stripped.
 pub fn secure_payload_len_from_wire_len(wire_len: usize) -> Option<usize> {
-    if wire_len < 4 {
-        return None;
-    }
-    Some(wire_len - (wire_len % 4))
+    secure_version_d_body_len_from_wire_len(wire_len)
 }
 
 /// Generate padding length for Secure Intermediate protocol.
-/// Data must be 4-byte aligned; padding is 1..=3 so total is never divisible by 4.
+/// Outbound padding is 1..=3 so a receiver can strip it by 4-byte alignment.
 pub fn secure_padding_len(data_len: usize, rng: &SecureRandom) -> usize {
     debug_assert!(
         is_valid_secure_payload_len(data_len),
         "Secure payload must be 4-byte aligned, got {data_len}"
     );
-    rng.range(3) + 1
+    secure_version_d_padding_len(rng)
 }
 
 // ============= Timeouts =============
@@ -430,7 +431,7 @@ mod tests {
             for _ in 0..100 {
                 let padding = secure_padding_len(data_len, &rng);
                 assert!(
-                    padding <= 3,
+                    (1..=3).contains(&padding),
                     "padding out of range: data_len={data_len}, padding={padding}"
                 );
                 assert_ne!(
@@ -454,6 +455,16 @@ mod tests {
         }
     }
 
+    #[test]
+    fn secure_wire_len_preserves_full_word_tail() {
+        let payload_len = 64;
+        for padding in [4usize, 8, 12] {
+            let wire_len = payload_len + padding;
+            let recovered = secure_payload_len_from_wire_len(wire_len);
+            assert_eq!(recovered, Some(wire_len));
+        }
+    }
+
     #[test]
     fn secure_wire_len_rejects_too_short_frames() {
         assert_eq!(secure_payload_len_from_wire_len(0), None);

src/protocol/framing.rs

@@ -0,0 +1,92 @@
+//! Shared MTProto transport framing helpers.
+
+use crate::crypto::SecureRandom;
+
+/// QuickACK marker bit used by Intermediate and Secure Intermediate headers.
+pub(crate) const INTERMEDIATE_QUICKACK_FLAG: u32 = 0x8000_0000;
+
+/// Payload length mask used by Intermediate and Secure Intermediate headers.
+pub(crate) const INTERMEDIATE_WIRE_LEN_MASK: u32 = 0x7fff_ffff;
+
+/// Maximum outbound Secure tail length that keeps wire lengths non-aligned.
+pub(crate) const SECURE_VERSION_D_PADDING_MAX: usize = 3;
+
+/// Parsed Intermediate/Secure Intermediate length header.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct IntermediateHeader {
+    /// Payload length on the wire, excluding the four-byte header.
+    pub(crate) wire_len: usize,
+    /// Whether the QuickACK marker bit was set in the length header.
+    pub(crate) quickack: bool,
+}
+
+/// Parse an Intermediate/Secure Intermediate length header.
+pub(crate) fn parse_intermediate_header(header: [u8; 4]) -> IntermediateHeader {
+    let raw = u32::from_le_bytes(header);
+    IntermediateHeader {
+        wire_len: (raw & INTERMEDIATE_WIRE_LEN_MASK) as usize,
+        quickack: (raw & INTERMEDIATE_QUICKACK_FLAG) != 0,
+    }
+}
+
+/// Encode an Intermediate/Secure Intermediate length header.
+pub(crate) fn encode_intermediate_header(wire_len: usize, quickack: bool) -> Option<u32> {
+    if wire_len > INTERMEDIATE_WIRE_LEN_MASK as usize {
+        return None;
+    }
+
+    let mut raw = u32::try_from(wire_len).ok()?;
+    if quickack {
+        raw |= INTERMEDIATE_QUICKACK_FLAG;
+    }
+    Some(raw)
+}
+
+/// Recover the VersionD body length visible to MTProto from the encrypted wire length.
+pub(crate) fn secure_version_d_body_len_from_wire_len(wire_len: usize) -> Option<usize> {
+    if wire_len < 4 {
+        return None;
+    }
+
+    Some(wire_len - (wire_len % 4))
+}
+
+/// Generate outbound Secure tail length without ambiguous full-word padding.
+pub(crate) fn secure_version_d_padding_len(rng: &SecureRandom) -> usize {
+    rng.range(SECURE_VERSION_D_PADDING_MAX) + 1
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn intermediate_header_roundtrip_preserves_quickack_zero_length() {
+        let encoded = encode_intermediate_header(0, true).unwrap();
+        assert_eq!(encoded, INTERMEDIATE_QUICKACK_FLAG);
+
+        let parsed = parse_intermediate_header(encoded.to_le_bytes());
+        assert_eq!(parsed.wire_len, 0);
+        assert!(parsed.quickack);
+    }
+
+    #[test]
+    fn intermediate_header_rejects_lengths_above_31_bits() {
+        assert_eq!(
+            encode_intermediate_header(INTERMEDIATE_WIRE_LEN_MASK as usize, false),
+            Some(INTERMEDIATE_WIRE_LEN_MASK)
+        );
+        assert_eq!(
+            encode_intermediate_header(INTERMEDIATE_WIRE_LEN_MASK as usize + 1, false),
+            None
+        );
+    }
+
+    #[test]
+    fn secure_version_d_body_len_strips_only_non_word_tail() {
+        assert_eq!(secure_version_d_body_len_from_wire_len(3), None);
+        assert_eq!(secure_version_d_body_len_from_wire_len(8), Some(8));
+        assert_eq!(secure_version_d_body_len_from_wire_len(11), Some(8));
+        assert_eq!(secure_version_d_body_len_from_wire_len(12), Some(12));
+    }
+}

src/protocol/mod.rs

@@ -2,6 +2,7 @@
 
 pub mod constants;
 pub mod frame;
+pub(crate) mod framing;
 pub mod obfuscation;
 pub mod tls;
 pub mod 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(),
@@ -1386,6 +1462,10 @@ fn emulated_server_hello_never_places_alpn_in_server_hello_extensions() {
         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,
@@ -1395,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();
@@ -1415,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();
@@ -1452,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]
@@ -1474,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();
@@ -1513,6 +1635,39 @@ 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>)>,
@@ -1674,7 +1829,7 @@ fn select_server_hello_cipher_suite_keeps_profile_cipher_when_offered() {
     );
     assert_eq!(
         select_server_hello_cipher_suite(&ch, [0x13, 0x03]),
-        [0x13, 0x03]
+        Some([0x13, 0x03])
     );
 }
 
@@ -1687,30 +1842,222 @@ fn select_server_hello_cipher_suite_ignores_profile_tls12_cipher() {
     );
     assert_eq!(
         select_server_hello_cipher_suite(&ch, [0xc0, 0x2f]),
-        [0x13, 0x03]
+        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]),
-        [0x13, 0x03]
+        Some([0x13, 0x03])
     );
 }
 
 #[test]
-fn select_server_hello_cipher_suite_keeps_preferred_for_malformed_clienthello() {
+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_cipher_suite(&ch, [0x13, 0x01]),
-        [0x13, 0x01]
+        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();

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};
@@ -109,9 +110,45 @@ mod cipher_suite {
     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 =============
@@ -144,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
     }
@@ -232,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
     }
 
@@ -508,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
@@ -530,6 +697,10 @@ pub fn build_server_hello(
     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,
@@ -537,6 +708,7 @@ pub fn build_server_hello(
         fake_cert_len,
         rng,
         cipher_suite::TLS_AES_128_GCM_SHA256,
+        &server_key_share,
         alpn,
         new_session_tickets,
     )
@@ -554,18 +726,18 @@ pub(crate) fn build_server_hello_with_cipher(
     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_cipher_suite(selected_cipher_suite)
-        .with_x25519_key(&x25519_key)
+        .with_key_share(server_key_share.group(), server_key_share.key_exchange())
         .with_tls13_version()
         .build_record();
 
@@ -1003,6 +1175,148 @@ fn client_hello_cipher_suites_range(handshake: &[u8]) -> Option<(usize, usize)>
     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),
@@ -1027,20 +1341,23 @@ fn is_tls13_cipher_suite(suite: [u8; 2]) -> bool {
 /// 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 keeps malformed or unexpected ClientHello
-/// shapes on the previous fallback behavior.
-pub(crate) fn select_server_hello_cipher_suite(handshake: &[u8], preferred: [u8; 2]) -> [u8; 2] {
+/// 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 preferred;
+        return None;
     };
 
     if client_hello_offers_cipher_suite(handshake, range, preferred) {
-        return preferred;
+        return Some(preferred);
     }
 
     for fallback in [
@@ -1049,11 +1366,43 @@ pub(crate) fn select_server_hello_cipher_suite(handshake: &[u8], preferred: [u8;
         cipher_suite::TLS_AES_256_GCM_SHA384,
     ] {
         if client_hello_offers_cipher_suite(handshake, range, fallback) {
-            return fallback;
+            return Some(fallback);
         }
     }
 
-    preferred
+    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

src/proxy/adaptive_buffers.rs

@@ -1,7 +1,4 @@
-#![allow(dead_code)]
-
-// Adaptive buffer policy is staged and retained for deterministic rollout.
-// Keep definitions compiled for compatibility and security test scaffolding.
+// Adaptive buffer policy shared by active Direct relay sessions.
 
 use dashmap::DashMap;
 use std::cmp::max;
@@ -13,29 +10,42 @@ const PROFILE_TTL: Duration = Duration::from_secs(300);
 const THROUGHPUT_UP_BPS: f64 = 8_000_000.0;
 const THROUGHPUT_DOWN_BPS: f64 = 2_000_000.0;
 const RATIO_CONFIRM_THRESHOLD: f64 = 1.12;
-const TIER1_HOLD_TICKS: u32 = 8;
-const TIER2_HOLD_TICKS: u32 = 4;
-const QUIET_DEMOTE_TICKS: u32 = 480;
-const HARD_COOLDOWN_TICKS: u32 = 20;
+const TIER1_HOLD: Duration = Duration::from_secs(2);
+const TIER2_HOLD: Duration = Duration::from_secs(1);
+const QUIET_DEMOTE: Duration = Duration::from_secs(120);
+const HARD_COOLDOWN: Duration = Duration::from_secs(5);
+const SUSTAINED_PRESSURE_DEMOTE: Duration = Duration::from_secs(30);
+const PRESSURE_DEMOTE_COOLDOWN: Duration = Duration::from_secs(60);
 const HARD_PENDING_THRESHOLD: u32 = 3;
 const HARD_PARTIAL_RATIO_THRESHOLD: f64 = 0.25;
+#[cfg(test)]
 const DIRECT_C2S_CAP_BYTES: usize = 128 * 1024;
+#[cfg(test)]
 const DIRECT_S2C_CAP_BYTES: usize = 512 * 1024;
+#[cfg(test)]
 const ME_FRAMES_CAP: usize = 96;
+#[cfg(test)]
 const ME_BYTES_CAP: usize = 384 * 1024;
+#[cfg(test)]
 const ME_DELAY_MIN_US: u64 = 150;
 const MAX_USER_PROFILES_ENTRIES: usize = 50_000;
 const MAX_USER_KEY_BYTES: usize = 512;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+/// Per-session Direct copy-buffer capacity tier.
 pub enum AdaptiveTier {
+    /// Conservative baseline capacity.
     Base = 0,
+    /// First throughput promotion.
     Tier1 = 1,
+    /// Sustained bidirectional pressure promotion.
     Tier2 = 2,
+    /// Configured per-direction ceilings.
     Tier3 = 3,
 }
 
 impl AdaptiveTier {
+    /// Returns the next larger tier, saturating at `Tier3`.
     pub fn promote(self) -> Self {
         match self {
             Self::Base => Self::Tier1,
@@ -45,6 +55,7 @@ impl AdaptiveTier {
         }
     }
 
+    /// Returns the next smaller tier, saturating at `Base`.
     pub fn demote(self) -> Self {
         match self {
             Self::Base => Self::Base,
@@ -54,6 +65,7 @@ impl AdaptiveTier {
         }
     }
 
+    #[cfg(test)]
     fn ratio(self) -> (usize, usize) {
         match self {
             Self::Base => (1, 1),
@@ -63,49 +75,70 @@ impl AdaptiveTier {
         }
     }
 
+    /// Returns the stable numeric tier used by bounded metrics.
     pub fn as_u8(self) -> u8 {
         self as u8
     }
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+/// Signal that caused an accepted adaptive tier transition.
 pub enum TierTransitionReason {
+    /// Sustained throughput and directional ratio confirmation.
     SoftConfirmed,
+    /// Short pending or partial-write pressure burst.
     HardPressure,
+    /// Sustained low-throughput period.
     QuietDemotion,
+    /// Sustained pending or partial-write pressure.
+    SustainedWritePressure,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+/// Proposed transition emitted by the per-session controller.
 pub struct TierTransition {
+    /// Tier active before the observation.
     pub from: AdaptiveTier,
+    /// Tier requested after the observation.
     pub to: AdaptiveTier,
+    /// Pressure or throughput condition that requested the transition.
     pub reason: TierTransitionReason,
 }
 
 #[derive(Debug, Clone, Copy, Default)]
+/// Directional byte and write-pressure deltas for one observation period.
 pub struct RelaySignalSample {
+    /// Client-to-DC bytes copied during the period.
     pub c2s_bytes: u64,
+    /// Bytes offered to DC-to-client writes during the period.
     pub s2c_requested_bytes: u64,
+    /// Bytes accepted by DC-to-client writes during the period.
     pub s2c_written_bytes: u64,
+    /// Successful DC-to-client write operations during the period.
     pub s2c_write_ops: u64,
+    /// Partial DC-to-client write operations during the period.
     pub s2c_partial_writes: u64,
+    /// Consecutive pending DC-to-client writes at sample time.
     pub s2c_consecutive_pending_writes: u32,
 }
 
 #[derive(Debug, Clone, Copy)]
+/// Stateful hysteresis controller for one active Direct session.
 pub struct SessionAdaptiveController {
     tier: AdaptiveTier,
     max_tier_seen: AdaptiveTier,
     throughput_ema_bps: f64,
     incoming_ema_bps: f64,
     outgoing_ema_bps: f64,
-    tier1_hold_ticks: u32,
-    tier2_hold_ticks: u32,
-    quiet_ticks: u32,
-    hard_cooldown_ticks: u32,
+    tier1_hold: Duration,
+    tier2_hold: Duration,
+    quiet: Duration,
+    hard_cooldown: Duration,
+    sustained_pressure: Duration,
 }
 
 impl SessionAdaptiveController {
+    /// Creates a controller at the tier whose memory reservation was accepted.
     pub fn new(initial_tier: AdaptiveTier) -> Self {
         Self {
             tier: initial_tier,
@@ -113,25 +146,33 @@ impl SessionAdaptiveController {
             throughput_ema_bps: 0.0,
             incoming_ema_bps: 0.0,
             outgoing_ema_bps: 0.0,
-            tier1_hold_ticks: 0,
-            tier2_hold_ticks: 0,
-            quiet_ticks: 0,
-            hard_cooldown_ticks: 0,
+            tier1_hold: Duration::ZERO,
+            tier2_hold: Duration::ZERO,
+            quiet: Duration::ZERO,
+            hard_cooldown: Duration::ZERO,
+            sustained_pressure: Duration::ZERO,
         }
     }
 
+    /// Returns the highest tier proposed by controller observations.
+    #[allow(dead_code)]
     pub fn max_tier_seen(&self) -> AdaptiveTier {
         self.max_tier_seen
     }
 
+    /// Returns the controller's current logical tier.
+    pub fn tier(&self) -> AdaptiveTier {
+        self.tier
+    }
+
+    /// Observes one period and returns at most one hysteresis-controlled transition.
     pub fn observe(&mut self, sample: RelaySignalSample, tick_secs: f64) -> Option<TierTransition> {
         if tick_secs <= f64::EPSILON {
             return None;
         }
 
-        if self.hard_cooldown_ticks > 0 {
-            self.hard_cooldown_ticks -= 1;
-        }
+        let tick = Duration::from_secs_f64(tick_secs);
+        self.hard_cooldown = self.hard_cooldown.saturating_sub(tick);
 
         let c2s_bps = (sample.c2s_bytes as f64 * 8.0) / tick_secs;
         let incoming_bps = (sample.s2c_requested_bytes as f64 * 8.0) / tick_secs;
@@ -144,9 +185,9 @@ impl SessionAdaptiveController {
 
         let tier1_now = self.throughput_ema_bps >= THROUGHPUT_UP_BPS;
         if tier1_now {
-            self.tier1_hold_ticks = self.tier1_hold_ticks.saturating_add(1);
+            self.tier1_hold = self.tier1_hold.saturating_add(tick);
         } else {
-            self.tier1_hold_ticks = 0;
+            self.tier1_hold = Duration::ZERO;
         }
 
         let ratio = if self.outgoing_ema_bps <= f64::EPSILON {
@@ -156,9 +197,9 @@ impl SessionAdaptiveController {
         };
         let tier2_now = ratio >= RATIO_CONFIRM_THRESHOLD;
         if tier2_now {
-            self.tier2_hold_ticks = self.tier2_hold_ticks.saturating_add(1);
+            self.tier2_hold = self.tier2_hold.saturating_add(tick);
         } else {
-            self.tier2_hold_ticks = 0;
+            self.tier2_hold = Duration::ZERO;
         }
 
         let partial_ratio = if sample.s2c_write_ops == 0 {
@@ -169,24 +210,37 @@ impl SessionAdaptiveController {
         let hard_now = sample.s2c_consecutive_pending_writes >= HARD_PENDING_THRESHOLD
             || partial_ratio >= HARD_PARTIAL_RATIO_THRESHOLD;
 
-        if hard_now && self.hard_cooldown_ticks == 0 {
-            return self.promote(TierTransitionReason::HardPressure, HARD_COOLDOWN_TICKS);
+        if hard_now {
+            self.sustained_pressure = self.sustained_pressure.saturating_add(tick);
+            if self.sustained_pressure >= SUSTAINED_PRESSURE_DEMOTE {
+                self.sustained_pressure = Duration::ZERO;
+                return self.demote(
+                    TierTransitionReason::SustainedWritePressure,
+                    PRESSURE_DEMOTE_COOLDOWN,
+                );
+            }
+        } else {
+            self.sustained_pressure = Duration::ZERO;
         }
 
-        if self.tier1_hold_ticks >= TIER1_HOLD_TICKS && self.tier2_hold_ticks >= TIER2_HOLD_TICKS {
-            return self.promote(TierTransitionReason::SoftConfirmed, 0);
+        if hard_now && self.hard_cooldown.is_zero() {
+            return self.promote(TierTransitionReason::HardPressure, HARD_COOLDOWN);
+        }
+
+        if self.tier1_hold >= TIER1_HOLD && self.tier2_hold >= TIER2_HOLD {
+            return self.promote(TierTransitionReason::SoftConfirmed, Duration::ZERO);
         }
 
         let demote_candidate =
             self.throughput_ema_bps < THROUGHPUT_DOWN_BPS && !tier2_now && !hard_now;
         if demote_candidate {
-            self.quiet_ticks = self.quiet_ticks.saturating_add(1);
-            if self.quiet_ticks >= QUIET_DEMOTE_TICKS {
-                self.quiet_ticks = 0;
-                return self.demote(TierTransitionReason::QuietDemotion);
+            self.quiet = self.quiet.saturating_add(tick);
+            if self.quiet >= QUIET_DEMOTE {
+                self.quiet = Duration::ZERO;
+                return self.demote(TierTransitionReason::QuietDemotion, Duration::ZERO);
             }
         } else {
-            self.quiet_ticks = 0;
+            self.quiet = Duration::ZERO;
         }
 
         None
@@ -195,7 +249,7 @@ impl SessionAdaptiveController {
     fn promote(
         &mut self,
         reason: TierTransitionReason,
-        hard_cooldown_ticks: u32,
+        hard_cooldown: Duration,
     ) -> Option<TierTransition> {
         let from = self.tier;
         let to = from.promote();
@@ -204,22 +258,27 @@ impl SessionAdaptiveController {
         }
         self.tier = to;
         self.max_tier_seen = max(self.max_tier_seen, to);
-        self.hard_cooldown_ticks = hard_cooldown_ticks;
-        self.tier1_hold_ticks = 0;
-        self.tier2_hold_ticks = 0;
-        self.quiet_ticks = 0;
+        self.hard_cooldown = hard_cooldown;
+        self.tier1_hold = Duration::ZERO;
+        self.tier2_hold = Duration::ZERO;
+        self.quiet = Duration::ZERO;
         Some(TierTransition { from, to, reason })
     }
 
-    fn demote(&mut self, reason: TierTransitionReason) -> Option<TierTransition> {
+    fn demote(
+        &mut self,
+        reason: TierTransitionReason,
+        hard_cooldown: Duration,
+    ) -> Option<TierTransition> {
         let from = self.tier;
         let to = from.demote();
         if from == to {
             return None;
         }
         self.tier = to;
-        self.tier1_hold_ticks = 0;
-        self.tier2_hold_ticks = 0;
+        self.hard_cooldown = hard_cooldown;
+        self.tier1_hold = Duration::ZERO;
+        self.tier2_hold = Duration::ZERO;
         Some(TierTransition { from, to, reason })
     }
 }
@@ -235,6 +294,8 @@ fn profiles() -> &'static DashMap<String, UserAdaptiveProfile> {
     USER_PROFILES.get_or_init(DashMap::new)
 }
 
+/// Returns a fresh user's recent successful Direct tier, or `Base` when stale.
+#[allow(dead_code)]
 pub fn seed_tier_for_user(user: &str) -> AdaptiveTier {
     if user.len() > MAX_USER_KEY_BYTES {
         return AdaptiveTier::Base;
@@ -253,6 +314,8 @@ pub fn seed_tier_for_user(user: &str) -> AdaptiveTier {
     AdaptiveTier::Base
 }
 
+/// Records the highest successfully allocated tier for bounded session seeding.
+#[allow(dead_code)]
 pub fn record_user_tier(user: &str, tier: AdaptiveTier) {
     if user.len() > MAX_USER_KEY_BYTES {
         return;
@@ -282,6 +345,8 @@ pub fn record_user_tier(user: &str, tier: AdaptiveTier) {
     }
 }
 
+#[cfg(test)]
+/// Returns the legacy staged scaling policy retained by security fixtures.
 pub fn direct_copy_buffers_for_tier(
     tier: AdaptiveTier,
     base_c2s: usize,
@@ -294,6 +359,32 @@ pub fn direct_copy_buffers_for_tier(
     )
 }
 
+/// Maps an adaptive tier to independent capacities within configured ceilings.
+pub(crate) fn direct_copy_buffers_for_tier_with_ceilings(
+    tier: AdaptiveTier,
+    base_c2s: usize,
+    base_s2c: usize,
+    ceiling_c2s: usize,
+    ceiling_s2c: usize,
+) -> (usize, usize) {
+    (
+        direct_direction_size(tier, base_c2s, ceiling_c2s),
+        direct_direction_size(tier, base_s2c, ceiling_s2c),
+    )
+}
+
+fn direct_direction_size(tier: AdaptiveTier, base: usize, ceiling: usize) -> usize {
+    let target = match tier {
+        AdaptiveTier::Base => base,
+        AdaptiveTier::Tier1 => ceiling / 4,
+        AdaptiveTier::Tier2 => ceiling / 2,
+        AdaptiveTier::Tier3 => ceiling,
+    };
+    target.max(base).min(ceiling.max(base)).max(1)
+}
+
+#[cfg(test)]
+/// Returns the staged Middle-End flush policy retained by security fixtures.
 pub fn me_flush_policy_for_tier(
     tier: AdaptiveTier,
     base_frames: usize,
@@ -323,6 +414,7 @@ fn ema(prev: f64, value: f64) -> f64 {
     }
 }
 
+#[cfg(test)]
 fn scale(base: usize, numerator: usize, denominator: usize, cap: usize) -> usize {
     let scaled = base
         .saturating_mul(numerator)
@@ -338,6 +430,10 @@ mod adaptive_buffers_security_tests;
 #[path = "tests/adaptive_buffers_record_race_security_tests.rs"]
 mod adaptive_buffers_record_race_security_tests;
 
+#[cfg(test)]
+#[path = "tests/adaptive_direct_budget_policy_tests.rs"]
+mod adaptive_direct_budget_policy_tests;
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -396,7 +492,7 @@ mod tests {
     fn test_quiet_demotion_is_slow_and_stepwise() {
         let mut ctrl = SessionAdaptiveController::new(AdaptiveTier::Tier2);
         let mut demotion = None;
-        for _ in 0..QUIET_DEMOTE_TICKS {
+        for _ in 0..480 {
             demotion = ctrl.observe(sample(1, 1, 1, 1, 0, 0), 0.25);
         }
 

src/proxy/client.rs

@@ -113,7 +113,7 @@ use crate::proxy::handshake::{
 };
 #[cfg(test)]
 use crate::proxy::handshake::{handle_mtproto_handshake, handle_tls_handshake};
-use crate::proxy::masking::handle_bad_client;
+use crate::proxy::masking::handle_bad_client_with_shared;
 use crate::proxy::middle_relay::handle_via_middle_proxy;
 use crate::proxy::route_mode::{RelayRouteMode, RouteRuntimeController};
 use crate::proxy::shared_state::ProxySharedState;
@@ -310,6 +310,7 @@ fn masking_outcome<R, W>(
     local_addr: SocketAddr,
     config: Arc<ProxyConfig>,
     beobachten: Arc<BeobachtenStore>,
+    shared: Arc<ProxySharedState>,
 ) -> HandshakeOutcome
 where
     R: AsyncRead + Unpin + Send + 'static,
@@ -325,7 +326,7 @@ where
         )
         .await;
 
-        handle_bad_client(
+        handle_bad_client_with_shared(
             reader,
             writer,
             &initial_data,
@@ -333,6 +334,7 @@ where
             local_addr,
             &config,
             &beobachten,
+            shared.as_ref(),
         )
         .await;
         Ok(())
@@ -718,6 +720,7 @@ where
                     local_addr,
                     config.clone(),
                     beobachten.clone(),
+                    shared.clone(),
                 ));
             }
 
@@ -739,6 +742,7 @@ where
                         local_addr,
                         config.clone(),
                         beobachten.clone(),
+                        shared.clone(),
                     ));
                 }
             };
@@ -757,6 +761,7 @@ where
                     local_addr,
                     config.clone(),
                     beobachten.clone(),
+                    shared.clone(),
                 ));
             }
 
@@ -787,6 +792,7 @@ where
                         local_addr,
                         config.clone(),
                         beobachten.clone(),
+                        shared.clone(),
                     ));
                 }
                 HandshakeResult::Error(e) => {
@@ -844,6 +850,7 @@ where
                         local_addr,
                         config.clone(),
                         beobachten.clone(),
+                        shared.clone(),
                     ));
                 }
                 HandshakeResult::Error(e) => return Err(e),
@@ -873,6 +880,7 @@ where
                     local_addr,
                     config.clone(),
                     beobachten.clone(),
+                    shared.clone(),
                 ));
             }
 
@@ -898,6 +906,7 @@ where
                         local_addr,
                         config.clone(),
                         beobachten.clone(),
+                        shared.clone(),
                     ));
                 }
                 HandshakeResult::Error(e) => return Err(e),
@@ -1096,6 +1105,12 @@ impl RunningClientHandler {
         #[cfg(unix)]
         let raw_fd = self.raw_fd;
         let rst_on_close = self.rst_on_close;
+        // MSS for the bulk data phase: once the handshake (incl. ServerHello) is
+        // sent, restore a normal MSS so only the handshake stays fragmented by the
+        // low listener `client_mss`. Cuts pps ~10x (anti-DDoS abuse on pps-policing
+        // hosts like FastVPS). None = keep handshake MSS for the whole connection.
+        #[cfg(unix)]
+        let bulk_mss: Option<u16> = self.config.server.client_mss_bulk_value().ok().flatten();
 
         let outcome = match self.do_handshake().await? {
             Some(outcome) => outcome,
@@ -1109,6 +1124,14 @@ impl RunningClientHandler {
                 if matches!(rst_on_close, crate::config::RstOnCloseMode::Errors) {
                     let _ = crate::transport::socket::clear_linger_fd(raw_fd);
                 }
+                // Handshake (ServerHello) done — raise MSS for bulk transfer.
+                #[cfg(unix)]
+                if let Some(mss) = bulk_mss {
+                    if let Err(e) = crate::transport::socket::set_tcp_mss_fd(raw_fd, u32::from(mss))
+                    {
+                        debug!(error = %e, "Failed to raise bulk MSS; keeping handshake MSS");
+                    }
+                }
                 fut.await
             }
             HandshakeOutcome::NeedsMasking(fut) => fut.await,
@@ -1329,6 +1352,7 @@ impl RunningClientHandler {
                 local_addr,
                 self.config.clone(),
                 self.beobachten.clone(),
+                self.shared.clone(),
             ));
         }
 
@@ -1350,6 +1374,7 @@ impl RunningClientHandler {
                     local_addr,
                     self.config.clone(),
                     self.beobachten.clone(),
+                    self.shared.clone(),
                 ));
             }
         };
@@ -1369,6 +1394,7 @@ impl RunningClientHandler {
                 local_addr,
                 self.config.clone(),
                 self.beobachten.clone(),
+                self.shared.clone(),
             ));
         }
 
@@ -1416,6 +1442,7 @@ impl RunningClientHandler {
                     local_addr,
                     config.clone(),
                     self.beobachten.clone(),
+                    self.shared.clone(),
                 ));
             }
             HandshakeResult::Error(e) => {
@@ -1483,6 +1510,7 @@ impl RunningClientHandler {
                     local_addr,
                     config.clone(),
                     self.beobachten.clone(),
+                    self.shared.clone(),
                 ));
             }
             HandshakeResult::Error(e) => return Err(e),
@@ -1530,6 +1558,7 @@ impl RunningClientHandler {
                 local_addr,
                 self.config.clone(),
                 self.beobachten.clone(),
+                self.shared.clone(),
             ));
         }
 
@@ -1568,6 +1597,7 @@ impl RunningClientHandler {
                     local_addr,
                     config.clone(),
                     self.beobachten.clone(),
+                    self.shared.clone(),
                 ));
             }
             HandshakeResult::Error(e) => return Err(e),

src/proxy/direct_buffer_budget.rs

@@ -0,0 +1,570 @@
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::Duration;
+
+use tokio::sync::watch;
+
+use crate::stats::Stats;
+use crate::stream::BufferPool;
+
+use super::shared_state::ProxySharedState;
+
+/// Accounting granularity for process-wide Direct copy-buffer reservations.
+pub(crate) const DIRECT_BUFFER_UNIT_BYTES: usize = 4 * 1024;
+/// Minimum client-to-DC copy-buffer capacity for one Direct session.
+pub(crate) const DIRECT_BASE_C2S_BYTES: usize = 4 * 1024;
+/// Minimum DC-to-client copy-buffer capacity for one Direct session.
+pub(crate) const DIRECT_BASE_S2C_BYTES: usize = 8 * 1024;
+
+const AUTO_HARD_MIN_BYTES: usize = 64 * 1024 * 1024;
+const AUTO_HARD_MAX_BYTES: usize = 2 * 1024 * 1024 * 1024;
+const AUTO_HARD_FALLBACK_BYTES: usize = 512 * 1024 * 1024;
+const TARGET_FLOOR_MIN_BYTES: usize = 16 * 1024 * 1024;
+const CONTROL_INTERVAL: Duration = Duration::from_secs(1);
+const HEALTHY_RECOVERY_SAMPLES: u8 = 30;
+const BUFFER_POOL_TRIM_LOW_WATERMARK: usize = 64;
+const BUFFER_POOL_TRIM_HIGH_WATERMARK: usize = 128;
+
+#[derive(Debug, Clone, Copy, Default)]
+/// Lock-free observability snapshot of the Direct copy-buffer envelope.
+pub(crate) struct DirectBufferBudgetSnapshot {
+    /// Absolute process-wide copy-buffer ceiling.
+    pub(crate) hard_limit_bytes: u64,
+    /// Current pressure-adjusted promotion target.
+    pub(crate) target_bytes: u64,
+    /// Bytes currently covered by active session leases.
+    pub(crate) reserved_bytes: u64,
+    /// Effective host or cgroup memory limit.
+    pub(crate) memory_total_bytes: u64,
+    /// Effective host or cgroup memory headroom.
+    pub(crate) memory_available_bytes: u64,
+    /// Current process resident set size.
+    pub(crate) process_rss_bytes: u64,
+    /// Successful tier growth reservations.
+    pub(crate) promotion_total: u64,
+    /// Tier growth attempts rejected by the adaptive target.
+    pub(crate) promotion_denied_total: u64,
+    /// Sessions admitted at minimum size above the adaptive target.
+    pub(crate) minimum_fallback_total: u64,
+    /// Sessions rejected by the absolute ceiling.
+    pub(crate) admission_rejected_total: u64,
+    /// Quiet-period tier reductions.
+    pub(crate) quiet_demotion_total: u64,
+    /// Sustained write-pressure tier reductions.
+    pub(crate) write_pressure_demotion_total: u64,
+    /// Process-wide pressure tier reductions.
+    pub(crate) global_pressure_demotion_total: u64,
+    /// Current sessions for Base through Tier3.
+    pub(crate) tier_sessions: [u64; 4],
+}
+
+#[derive(Debug, Clone, Copy, Default)]
+struct SystemMemorySample {
+    total_bytes: u64,
+    available_bytes: u64,
+    process_rss_bytes: u64,
+}
+
+/// Process-wide hard envelope and adaptive target for Direct copy buffers.
+pub(crate) struct DirectBufferBudget {
+    hard_limit_bytes: u64,
+    target_bytes: AtomicU64,
+    reserved_bytes: AtomicU64,
+    pressure_generation: AtomicU64,
+    pressure_tx: watch::Sender<u64>,
+    memory_total_bytes: AtomicU64,
+    memory_available_bytes: AtomicU64,
+    process_rss_bytes: AtomicU64,
+    promotion_total: AtomicU64,
+    promotion_denied_total: AtomicU64,
+    minimum_fallback_total: AtomicU64,
+    admission_rejected_total: AtomicU64,
+    quiet_demotion_total: AtomicU64,
+    write_pressure_demotion_total: AtomicU64,
+    global_pressure_demotion_total: AtomicU64,
+    tier_sessions: [AtomicU64; 4],
+}
+
+impl DirectBufferBudget {
+    /// Creates an envelope with a fixed absolute ceiling.
+    pub(crate) fn new(hard_limit_bytes: usize) -> Arc<Self> {
+        let hard_limit_bytes = align_down(hard_limit_bytes.max(DIRECT_BUFFER_UNIT_BYTES)) as u64;
+        let (pressure_tx, _) = watch::channel(0);
+        Arc::new(Self {
+            hard_limit_bytes,
+            target_bytes: AtomicU64::new(hard_limit_bytes),
+            reserved_bytes: AtomicU64::new(0),
+            pressure_generation: AtomicU64::new(0),
+            pressure_tx,
+            memory_total_bytes: AtomicU64::new(0),
+            memory_available_bytes: AtomicU64::new(0),
+            process_rss_bytes: AtomicU64::new(0),
+            promotion_total: AtomicU64::new(0),
+            promotion_denied_total: AtomicU64::new(0),
+            minimum_fallback_total: AtomicU64::new(0),
+            admission_rejected_total: AtomicU64::new(0),
+            quiet_demotion_total: AtomicU64::new(0),
+            write_pressure_demotion_total: AtomicU64::new(0),
+            global_pressure_demotion_total: AtomicU64::new(0),
+            tier_sessions: std::array::from_fn(|_| AtomicU64::new(0)),
+        })
+    }
+
+    /// Returns the current pressure-adjusted reservation target.
+    pub(crate) fn target_bytes(&self) -> usize {
+        self.target_bytes.load(Ordering::Relaxed) as usize
+    }
+
+    /// Subscribes to target reductions that require prompt session demotion.
+    pub(crate) fn subscribe_pressure(&self) -> watch::Receiver<u64> {
+        self.pressure_tx.subscribe()
+    }
+
+    /// Reserves bytes against either the adaptive target or the absolute ceiling.
+    pub(crate) fn try_reserve(
+        self: &Arc<Self>,
+        bytes: usize,
+        allow_above_target: bool,
+    ) -> Option<DirectBufferLease> {
+        let bytes = align_up(bytes) as u64;
+        let limit = if allow_above_target {
+            self.hard_limit_bytes
+        } else {
+            self.target_bytes
+                .load(Ordering::Relaxed)
+                .min(self.hard_limit_bytes)
+        };
+        if !self.try_add_reserved(bytes, limit) {
+            return None;
+        }
+        self.tier_sessions[0].fetch_add(1, Ordering::Relaxed);
+        Some(DirectBufferLease {
+            budget: Arc::clone(self),
+            reserved_bytes: bytes,
+            tier: 0,
+        })
+    }
+
+    fn try_add_reserved(&self, bytes: u64, limit: u64) -> bool {
+        let mut current = self.reserved_bytes.load(Ordering::Acquire);
+        loop {
+            if bytes > limit.saturating_sub(current) {
+                return false;
+            }
+            match self.reserved_bytes.compare_exchange_weak(
+                current,
+                current + bytes,
+                Ordering::AcqRel,
+                Ordering::Acquire,
+            ) {
+                Ok(_) => return true,
+                Err(observed) => current = observed,
+            }
+        }
+    }
+
+    fn target_floor_bytes(&self) -> u64 {
+        (self.hard_limit_bytes / 8)
+            .max(TARGET_FLOOR_MIN_BYTES as u64)
+            .min(self.hard_limit_bytes)
+    }
+
+    fn set_target_bytes(&self, target: u64) {
+        let target =
+            align_down(target.clamp(self.target_floor_bytes(), self.hard_limit_bytes) as usize)
+                as u64;
+        let previous = self.target_bytes.swap(target, Ordering::AcqRel);
+        if target < previous {
+            let generation = self
+                .pressure_generation
+                .fetch_add(1, Ordering::AcqRel)
+                .wrapping_add(1);
+            self.pressure_tx.send_replace(generation);
+        }
+    }
+
+    fn update_system_sample(&self, sample: SystemMemorySample) {
+        self.memory_total_bytes
+            .store(sample.total_bytes, Ordering::Relaxed);
+        self.memory_available_bytes
+            .store(sample.available_bytes, Ordering::Relaxed);
+        self.process_rss_bytes
+            .store(sample.process_rss_bytes, Ordering::Relaxed);
+    }
+
+    /// Records a session that had to bypass the adaptive target at minimum size.
+    pub(crate) fn increment_minimum_fallback(&self) {
+        self.minimum_fallback_total.fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// Records a session rejected because the absolute ceiling was exhausted.
+    pub(crate) fn increment_admission_rejected(&self) {
+        self.admission_rejected_total
+            .fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// Records a tier reduction after sustained low throughput.
+    pub(crate) fn increment_quiet_demotion(&self) {
+        self.quiet_demotion_total.fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// Records a tier reduction after sustained partial or pending writes.
+    pub(crate) fn increment_write_pressure_demotion(&self) {
+        self.write_pressure_demotion_total
+            .fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// Records a tier reduction requested by the process-wide controller.
+    pub(crate) fn increment_global_pressure_demotion(&self) {
+        self.global_pressure_demotion_total
+            .fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// Captures all bounded metrics without allocating or locking.
+    pub(crate) fn snapshot(&self) -> DirectBufferBudgetSnapshot {
+        DirectBufferBudgetSnapshot {
+            hard_limit_bytes: self.hard_limit_bytes,
+            target_bytes: self.target_bytes.load(Ordering::Relaxed),
+            reserved_bytes: self.reserved_bytes.load(Ordering::Relaxed),
+            memory_total_bytes: self.memory_total_bytes.load(Ordering::Relaxed),
+            memory_available_bytes: self.memory_available_bytes.load(Ordering::Relaxed),
+            process_rss_bytes: self.process_rss_bytes.load(Ordering::Relaxed),
+            promotion_total: self.promotion_total.load(Ordering::Relaxed),
+            promotion_denied_total: self.promotion_denied_total.load(Ordering::Relaxed),
+            minimum_fallback_total: self.minimum_fallback_total.load(Ordering::Relaxed),
+            admission_rejected_total: self.admission_rejected_total.load(Ordering::Relaxed),
+            quiet_demotion_total: self.quiet_demotion_total.load(Ordering::Relaxed),
+            write_pressure_demotion_total: self
+                .write_pressure_demotion_total
+                .load(Ordering::Relaxed),
+            global_pressure_demotion_total: self
+                .global_pressure_demotion_total
+                .load(Ordering::Relaxed),
+            tier_sessions: std::array::from_fn(|index| {
+                self.tier_sessions[index].load(Ordering::Relaxed)
+            }),
+        }
+    }
+}
+
+/// Returns the conservative ceiling used when memory discovery is unavailable.
+pub(crate) fn fallback_direct_buffer_hard_limit() -> usize {
+    AUTO_HARD_FALLBACK_BYTES
+}
+
+/// RAII ownership of all copy-buffer bytes retained by one Direct session.
+pub(crate) struct DirectBufferLease {
+    budget: Arc<DirectBufferBudget>,
+    reserved_bytes: u64,
+    tier: usize,
+}
+
+impl DirectBufferLease {
+    /// Returns the currently covered allocation rounded to accounting units.
+    pub(crate) fn reserved_bytes(&self) -> usize {
+        self.reserved_bytes as usize
+    }
+
+    /// Attempts to cover a larger tier before its buffers are resized.
+    pub(crate) fn try_grow_to(&mut self, bytes: usize) -> bool {
+        let bytes = align_up(bytes) as u64;
+        if bytes <= self.reserved_bytes {
+            return true;
+        }
+        let delta = bytes - self.reserved_bytes;
+        let limit = self
+            .budget
+            .target_bytes
+            .load(Ordering::Relaxed)
+            .min(self.budget.hard_limit_bytes);
+        if !self.budget.try_add_reserved(delta, limit) {
+            self.budget
+                .promotion_denied_total
+                .fetch_add(1, Ordering::Relaxed);
+            return false;
+        }
+        self.reserved_bytes = bytes;
+        self.budget.promotion_total.fetch_add(1, Ordering::Relaxed);
+        true
+    }
+
+    /// Releases bytes only after both directional buffers report smaller coverage.
+    pub(crate) fn shrink_to(&mut self, bytes: usize) {
+        let bytes = align_up(bytes) as u64;
+        if bytes >= self.reserved_bytes {
+            return;
+        }
+        let released = self.reserved_bytes - bytes;
+        self.reserved_bytes = bytes;
+        self.budget
+            .reserved_bytes
+            .fetch_sub(released, Ordering::AcqRel);
+    }
+
+    /// Updates bounded per-tier session gauges for an accepted transition.
+    pub(crate) fn set_tier(&mut self, tier: usize) {
+        let tier = tier.min(self.budget.tier_sessions.len() - 1);
+        if tier == self.tier {
+            return;
+        }
+        decrement_saturating(&self.budget.tier_sessions[self.tier]);
+        self.budget.tier_sessions[tier].fetch_add(1, Ordering::Relaxed);
+        self.tier = tier;
+    }
+}
+
+impl Drop for DirectBufferLease {
+    fn drop(&mut self) {
+        self.budget
+            .reserved_bytes
+            .fetch_sub(self.reserved_bytes, Ordering::AcqRel);
+        decrement_saturating(&self.budget.tier_sessions[self.tier]);
+    }
+}
+
+/// Resolves the startup hard ceiling from config, cgroup, and host memory.
+pub(crate) async fn resolve_direct_buffer_hard_limit(configured: usize) -> usize {
+    if configured != 0 {
+        return align_down(configured);
+    }
+    let sample = read_system_memory_sample().await;
+    if sample.total_bytes == 0 {
+        return AUTO_HARD_FALLBACK_BYTES;
+    }
+    let derived = (sample.total_bytes / 4)
+        .clamp(AUTO_HARD_MIN_BYTES as u64, AUTO_HARD_MAX_BYTES as u64)
+        .min(sample.total_bytes);
+    align_down(derived as usize).max(DIRECT_BUFFER_UNIT_BYTES)
+}
+
+/// Starts the single control-plane task for Direct budget and shared pool pressure.
+pub(crate) fn spawn_direct_buffer_budget_controller(
+    budget: Arc<DirectBufferBudget>,
+    buffer_pool: Arc<BufferPool>,
+    stats: Arc<Stats>,
+    shared: Arc<ProxySharedState>,
+    max_connections: u32,
+) {
+    tokio::spawn(async move {
+        let mut interval = tokio::time::interval(CONTROL_INTERVAL);
+        interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+        let mut healthy_streak = 0u8;
+        let mut previous_denied = 0u64;
+        let mut previous_fallback = 0u64;
+        let mut previous_rejected = 0u64;
+        let pool_trim_low = buffer_pool
+            .max_buffers()
+            .min(BUFFER_POOL_TRIM_LOW_WATERMARK);
+        let pool_trim_high = buffer_pool
+            .max_buffers()
+            .min(BUFFER_POOL_TRIM_HIGH_WATERMARK);
+        let mut pool_trim_armed = true;
+
+        loop {
+            interval.tick().await;
+            let sample = read_system_memory_sample().await;
+            budget.update_system_sample(sample);
+
+            let snapshot = budget.snapshot();
+            let denied_delta = snapshot
+                .promotion_denied_total
+                .saturating_sub(previous_denied);
+            previous_denied = snapshot.promotion_denied_total;
+            let fallback_delta = snapshot
+                .minimum_fallback_total
+                .saturating_sub(previous_fallback);
+            previous_fallback = snapshot.minimum_fallback_total;
+            let rejected_delta = snapshot
+                .admission_rejected_total
+                .saturating_sub(previous_rejected);
+            previous_rejected = snapshot.admission_rejected_total;
+
+            let connection_pct = connection_fill_pct(stats.as_ref(), max_connections);
+            let memory_available_pct = percentage(sample.available_bytes, sample.total_bytes);
+            let target_utilization_pct = percentage(snapshot.reserved_bytes, snapshot.target_bytes);
+            let pressure = shared.conntrack_pressure_active()
+                || connection_pct.is_some_and(|value| value >= 85)
+                || memory_available_pct.is_some_and(|value| value <= 15)
+                || target_utilization_pct.is_some_and(|value| value >= 90)
+                || denied_delta > 0
+                || fallback_delta > 0
+                || rejected_delta > 0;
+
+            if !pressure {
+                pool_trim_armed = true;
+            } else if pool_trim_armed && buffer_pool.pooled() > pool_trim_high {
+                buffer_pool.trim_to(pool_trim_low);
+                pool_trim_armed = false;
+            }
+
+            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),
+            );
+            stats.set_buffer_pool_replaced_nonstandard_total(pool_snapshot.replaced_nonstandard);
+
+            let headroom_target = if sample.total_bytes == 0 {
+                snapshot.hard_limit_bytes
+            } else {
+                snapshot
+                    .reserved_bytes
+                    .saturating_add(sample.available_bytes / 4)
+                    .min(snapshot.hard_limit_bytes)
+            };
+
+            if pressure {
+                healthy_streak = 0;
+                let reduced = snapshot.target_bytes.saturating_mul(3) / 4;
+                budget.set_target_bytes(reduced.min(headroom_target));
+                continue;
+            }
+
+            let healthy = memory_available_pct.is_none_or(|value| value >= 30)
+                && connection_pct.is_none_or(|value| value <= 70);
+            if !healthy {
+                healthy_streak = 0;
+                if headroom_target < snapshot.target_bytes {
+                    budget.set_target_bytes(headroom_target);
+                }
+                continue;
+            }
+
+            healthy_streak = healthy_streak.saturating_add(1);
+            if healthy_streak >= HEALTHY_RECOVERY_SAMPLES {
+                healthy_streak = 0;
+                let increment = (snapshot.target_bytes / 16).max(4 * 1024 * 1024);
+                budget.set_target_bytes(
+                    snapshot
+                        .target_bytes
+                        .saturating_add(increment)
+                        .min(headroom_target),
+                );
+            }
+        }
+    });
+}
+
+fn connection_fill_pct(stats: &Stats, max_connections: u32) -> Option<u8> {
+    if max_connections == 0 {
+        return None;
+    }
+    Some(
+        ((stats.get_current_connections_total().saturating_mul(100)) / u64::from(max_connections))
+            .min(100) as u8,
+    )
+}
+
+fn percentage(value: u64, total: u64) -> Option<u8> {
+    if total == 0 {
+        return None;
+    }
+    Some(((value.saturating_mul(100)) / total).min(100) as u8)
+}
+
+async fn read_system_memory_sample() -> SystemMemorySample {
+    #[cfg(target_os = "linux")]
+    {
+        let meminfo = tokio::fs::read_to_string("/proc/meminfo")
+            .await
+            .unwrap_or_default();
+        let status = tokio::fs::read_to_string("/proc/self/status")
+            .await
+            .unwrap_or_default();
+        let host_total = parse_kib_field(&meminfo, "MemTotal:");
+        let host_available = parse_kib_field(&meminfo, "MemAvailable:");
+        let process_rss = parse_kib_field(&status, "VmRSS:");
+
+        let cgroup_v2_max = read_cgroup_limit("/sys/fs/cgroup/memory.max").await;
+        let cgroup_v2_current = read_u64_file("/sys/fs/cgroup/memory.current").await;
+        let cgroup_v1_max = read_cgroup_limit("/sys/fs/cgroup/memory/memory.limit_in_bytes").await;
+        let cgroup_v1_current = read_u64_file("/sys/fs/cgroup/memory/memory.usage_in_bytes").await;
+        let cgroup_max = cgroup_v2_max.or(cgroup_v1_max);
+        let cgroup_current = cgroup_v2_current.or(cgroup_v1_current);
+
+        let total = match (host_total, cgroup_max) {
+            (0, Some(limit)) => limit,
+            (host, Some(limit)) => host.min(limit),
+            (host, None) => host,
+        };
+        let cgroup_available = cgroup_max
+            .zip(cgroup_current)
+            .map(|(limit, current)| limit.saturating_sub(current));
+        let available = match (host_available, cgroup_available) {
+            (0, Some(value)) => value,
+            (host, Some(value)) => host.min(value),
+            (host, None) => host,
+        };
+        return SystemMemorySample {
+            total_bytes: total,
+            available_bytes: available,
+            process_rss_bytes: process_rss,
+        };
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        SystemMemorySample::default()
+    }
+}
+
+#[cfg(target_os = "linux")]
+async fn read_cgroup_limit(path: &str) -> Option<u64> {
+    let raw = tokio::fs::read_to_string(path).await.ok()?;
+    let raw = raw.trim();
+    if raw == "max" {
+        return None;
+    }
+    let value = raw.parse::<u64>().ok()?;
+    (value < (1u64 << 60)).then_some(value)
+}
+
+#[cfg(target_os = "linux")]
+async fn read_u64_file(path: &str) -> Option<u64> {
+    tokio::fs::read_to_string(path)
+        .await
+        .ok()?
+        .trim()
+        .parse()
+        .ok()
+}
+
+#[cfg(target_os = "linux")]
+fn parse_kib_field(raw: &str, key: &str) -> u64 {
+    raw.lines()
+        .find_map(|line| {
+            let value = line.strip_prefix(key)?.split_whitespace().next()?;
+            value.parse::<u64>().ok()
+        })
+        .unwrap_or(0)
+        .saturating_mul(1024)
+}
+
+fn align_up(bytes: usize) -> usize {
+    bytes
+        .div_ceil(DIRECT_BUFFER_UNIT_BYTES)
+        .saturating_mul(DIRECT_BUFFER_UNIT_BYTES)
+}
+
+fn align_down(bytes: usize) -> usize {
+    bytes / DIRECT_BUFFER_UNIT_BYTES * DIRECT_BUFFER_UNIT_BYTES
+}
+
+fn decrement_saturating(value: &AtomicU64) {
+    let mut current = value.load(Ordering::Relaxed);
+    while current != 0 {
+        match value.compare_exchange_weak(
+            current,
+            current - 1,
+            Ordering::Relaxed,
+            Ordering::Relaxed,
+        ) {
+            Ok(_) => return,
+            Err(observed) => current = observed,
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "tests/direct_buffer_budget_tests.rs"]
+mod tests;

src/proxy/direct_relay.rs

@@ -345,22 +345,22 @@ where
     } else {
         Duration::from_secs(1800)
     };
-    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(),
-        );
+    let relay_result = crate::proxy::relay::relay_direct_adaptive(
+        client_reader,
+        client_writer,
+        tg_reader,
+        tg_writer,
+        config.general.direct_relay_copy_buf_c2s_bytes,
+        config.general.direct_relay_copy_buf_s2c_bytes,
+        config.server.max_connections,
+        user,
+        Arc::clone(&stats),
+        config.access.user_data_quota.get(user).copied(),
+        traffic_lease,
+        relay_activity_timeout,
+        session_cancel.clone(),
+        Arc::clone(&shared.direct_buffer_budget),
+    );
     tokio::pin!(relay_result);
     let relay_result = loop {
         if let Some(cutover) =
@@ -400,7 +400,6 @@ where
         Err(e) => debug!(user = %user, error = %e, "Direct relay ended with error"),
     }
 
-    buffer_pool_trim.trim_to(buffer_pool_trim.max_buffers().min(64));
     let pool_snapshot = buffer_pool_trim.stats();
     stats.set_buffer_pool_gauges(
         pool_snapshot.pooled,

src/proxy/handshake.rs

@@ -4,7 +4,6 @@
 
 use dashmap::DashMap;
 use dashmap::mapref::entry::Entry;
-use hmac::{Hmac, Mac};
 #[cfg(test)]
 use std::collections::HashSet;
 use std::collections::hash_map::DefaultHasher;
@@ -33,8 +32,10 @@ use crate::stream::{CryptoReader, CryptoWriter, FakeTlsReader, FakeTlsWriter};
 use crate::tls_front::{TlsFrontCache, emulator};
 #[cfg(test)]
 use rand::RngExt;
-use sha2::Sha256;
-use subtle::ConstantTimeEq;
+
+mod tls_auth;
+
+use self::tls_auth::{parse_tls_auth_material, validate_tls_secret_candidate};
 
 const ACCESS_SECRET_BYTES: usize = 16;
 const UNKNOWN_SNI_WARN_COOLDOWN_SECS: u64 = 5;
@@ -58,8 +59,6 @@ const OVERLOAD_CANDIDATE_BUDGET_UNHINTED: usize = 8;
 const EXPENSIVE_INVALID_SCAN_SATURATION_THRESHOLD: usize = 64;
 const RECENT_USER_RING_SCAN_LIMIT: usize = 32;
 
-type HmacSha256 = Hmac<Sha256>;
-
 #[cfg(test)]
 const AUTH_PROBE_BACKOFF_BASE_MS: u64 = 1;
 #[cfg(not(test))]
@@ -104,23 +103,6 @@ fn should_emit_unknown_sni_warn_in(shared: &ProxySharedState, now: Instant) -> b
     true
 }
 
-#[derive(Clone, Copy)]
-struct ParsedTlsAuthMaterial {
-    digest: [u8; tls::TLS_DIGEST_LEN],
-    session_id: [u8; 32],
-    session_id_len: usize,
-    now: i64,
-    ignore_time_skew: bool,
-    boot_time_cap_secs: u32,
-}
-
-#[derive(Clone, Copy)]
-struct TlsCandidateValidation {
-    digest: [u8; tls::TLS_DIGEST_LEN],
-    session_id: [u8; 32],
-    session_id_len: usize,
-}
-
 struct MtprotoCandidateValidation {
     proto_tag: ProtoTag,
     dc_idx: i16,
@@ -251,104 +233,6 @@ fn budget_for_validation(total_users: usize, overload: bool, has_hint: bool) ->
     total_users.min(cap.max(1))
 }
 
-fn parse_tls_auth_material(
-    handshake: &[u8],
-    ignore_time_skew: bool,
-    replay_window_secs: u64,
-) -> Option<ParsedTlsAuthMaterial> {
-    if handshake.len() < tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN + 1 {
-        return None;
-    }
-
-    let digest: [u8; tls::TLS_DIGEST_LEN] = handshake
-        [tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN]
-        .try_into()
-        .ok()?;
-
-    let session_id_len_pos = tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN;
-    let session_id_len = usize::from(handshake.get(session_id_len_pos).copied()?);
-    if session_id_len > 32 {
-        return None;
-    }
-    let session_id_start = session_id_len_pos + 1;
-    if handshake.len() < session_id_start + session_id_len {
-        return None;
-    }
-
-    let mut session_id = [0u8; 32];
-    session_id[..session_id_len]
-        .copy_from_slice(&handshake[session_id_start..session_id_start + session_id_len]);
-
-    let now = if !ignore_time_skew {
-        let d = std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .ok()?;
-        i64::try_from(d.as_secs()).ok()?
-    } else {
-        0_i64
-    };
-
-    let replay_window_u32 = u32::try_from(replay_window_secs).unwrap_or(u32::MAX);
-    let boot_time_cap_secs = if ignore_time_skew {
-        0
-    } else {
-        tls::BOOT_TIME_MAX_SECS
-            .min(replay_window_u32)
-            .min(tls::BOOT_TIME_COMPAT_MAX_SECS)
-    };
-
-    Some(ParsedTlsAuthMaterial {
-        digest,
-        session_id,
-        session_id_len,
-        now,
-        ignore_time_skew,
-        boot_time_cap_secs,
-    })
-}
-
-fn compute_tls_hmac_zeroed_digest(secret: &[u8], handshake: &[u8]) -> [u8; 32] {
-    let mut mac = HmacSha256::new_from_slice(secret).expect("HMAC accepts any key length");
-    mac.update(&handshake[..tls::TLS_DIGEST_POS]);
-    mac.update(&[0u8; tls::TLS_DIGEST_LEN]);
-    mac.update(&handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN..]);
-    mac.finalize().into_bytes().into()
-}
-
-fn validate_tls_secret_candidate(
-    parsed: &ParsedTlsAuthMaterial,
-    handshake: &[u8],
-    secret: &[u8],
-) -> Option<TlsCandidateValidation> {
-    let computed = compute_tls_hmac_zeroed_digest(secret, handshake);
-    if !bool::from(parsed.digest[..28].ct_eq(&computed[..28])) {
-        return None;
-    }
-
-    let timestamp = u32::from_le_bytes([
-        parsed.digest[28] ^ computed[28],
-        parsed.digest[29] ^ computed[29],
-        parsed.digest[30] ^ computed[30],
-        parsed.digest[31] ^ computed[31],
-    ]);
-
-    if !parsed.ignore_time_skew {
-        let is_boot_time = parsed.boot_time_cap_secs > 0 && timestamp < parsed.boot_time_cap_secs;
-        if !is_boot_time {
-            let time_diff = parsed.now - i64::from(timestamp);
-            if !(tls::TIME_SKEW_MIN..=tls::TIME_SKEW_MAX).contains(&time_diff) {
-                return None;
-            }
-        }
-    }
-
-    Some(TlsCandidateValidation {
-        digest: parsed.digest,
-        session_id: parsed.session_id,
-        session_id_len: parsed.session_id_len,
-    })
-}
-
 fn validate_mtproto_secret_candidate(
     handshake: &[u8; HANDSHAKE_LEN],
     dec_prekey: &[u8; PREKEY_LEN],
@@ -1473,14 +1357,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 +1419,11 @@ where
                     .await
             } else {
                 true
-            };
-            Some((cached_entry, use_full_cert_payload))
+            }
         } else {
-            None
-        }
+            true
+        };
+        Some((cached_entry, use_full_cert_payload))
     } else {
         None
     };
@@ -1504,13 +1434,6 @@ where
     let validation_session_id_slice = &validation_session_id[..validation_session_id_len];
 
     let response = if let Some((cached_entry, use_full_cert_payload)) = cached {
-        let preferred_cipher_suite = if cached_entry.server_hello_template.cipher_suite == [0, 0] {
-            [0x13, 0x01]
-        } else {
-            cached_entry.server_hello_template.cipher_suite
-        };
-        let selected_cipher_suite =
-            tls::select_server_hello_cipher_suite(handshake, preferred_cipher_suite);
         emulator::build_emulated_server_hello(
             &validated_secret,
             &validation_digest,
@@ -1520,12 +1443,12 @@ where
             config.censorship.serverhello_compact,
             client_tls_version,
             selected_cipher_suite,
+            &server_key_share,
             rng,
             selected_alpn.clone(),
             config.censorship.tls_new_session_tickets,
         )
     } else {
-        let selected_cipher_suite = tls::select_server_hello_cipher_suite(handshake, [0x13, 0x01]);
         tls::build_server_hello_with_cipher(
             &validated_secret,
             &validation_digest,
@@ -1533,6 +1456,7 @@ where
             config.censorship.fake_cert_len,
             rng,
             selected_cipher_suite,
+            &server_key_share,
             selected_alpn.clone(),
             config.censorship.tls_new_session_tickets,
         )
@@ -1817,7 +1741,16 @@ where
             return HandshakeResult::BadClient { reader, writer };
         }
 
-        let validation = matched_validation.expect("validation must exist when matched");
+        let Some(validation) = matched_validation else {
+            auth_probe_record_failure_in(shared, peer.ip(), Instant::now());
+            maybe_apply_server_hello_delay(config).await;
+            warn!(
+                peer = %peer,
+                user = %matched_user,
+                "MTProto handshake matched user without validation material"
+            );
+            return HandshakeResult::BadClient { reader, writer };
+        };
 
         if config
             .access

src/proxy/handshake/tls_auth.rs

@@ -0,0 +1,126 @@
+use hmac::{Hmac, Mac};
+use sha2::Sha256;
+use subtle::ConstantTimeEq;
+
+use crate::protocol::tls;
+
+type HmacSha256 = Hmac<Sha256>;
+
+/// Parsed TLS authentication material extracted from a ClientHello candidate.
+#[derive(Clone, Copy)]
+pub(super) struct ParsedTlsAuthMaterial {
+    digest: [u8; tls::TLS_DIGEST_LEN],
+    session_id: [u8; 32],
+    session_id_len: usize,
+    now: i64,
+    ignore_time_skew: bool,
+    boot_time_cap_secs: u32,
+}
+
+/// Successful TLS secret validation output used by the handshake state machine.
+#[derive(Clone, Copy)]
+pub(super) struct TlsCandidateValidation {
+    pub(super) digest: [u8; tls::TLS_DIGEST_LEN],
+    pub(super) session_id: [u8; 32],
+    pub(super) session_id_len: usize,
+}
+
+/// Parse TLS auth digest and session-id material from a candidate handshake.
+pub(super) fn parse_tls_auth_material(
+    handshake: &[u8],
+    ignore_time_skew: bool,
+    replay_window_secs: u64,
+) -> Option<ParsedTlsAuthMaterial> {
+    if handshake.len() < tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN + 1 {
+        return None;
+    }
+
+    let digest: [u8; tls::TLS_DIGEST_LEN] = handshake
+        [tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN]
+        .try_into()
+        .ok()?;
+
+    let session_id_len_pos = tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN;
+    let session_id_len = usize::from(handshake.get(session_id_len_pos).copied()?);
+    if session_id_len > 32 {
+        return None;
+    }
+    let session_id_start = session_id_len_pos + 1;
+    if handshake.len() < session_id_start + session_id_len {
+        return None;
+    }
+
+    let mut session_id = [0u8; 32];
+    session_id[..session_id_len]
+        .copy_from_slice(&handshake[session_id_start..session_id_start + session_id_len]);
+
+    let now = if !ignore_time_skew {
+        let d = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .ok()?;
+        i64::try_from(d.as_secs()).ok()?
+    } else {
+        0_i64
+    };
+
+    let replay_window_u32 = u32::try_from(replay_window_secs).unwrap_or(u32::MAX);
+    let boot_time_cap_secs = if ignore_time_skew {
+        0
+    } else {
+        tls::BOOT_TIME_MAX_SECS
+            .min(replay_window_u32)
+            .min(tls::BOOT_TIME_COMPAT_MAX_SECS)
+    };
+
+    Some(ParsedTlsAuthMaterial {
+        digest,
+        session_id,
+        session_id_len,
+        now,
+        ignore_time_skew,
+        boot_time_cap_secs,
+    })
+}
+
+fn compute_tls_hmac_zeroed_digest(secret: &[u8], handshake: &[u8]) -> Option<[u8; 32]> {
+    let mut mac = HmacSha256::new_from_slice(secret).ok()?;
+    mac.update(&handshake[..tls::TLS_DIGEST_POS]);
+    mac.update(&[0u8; tls::TLS_DIGEST_LEN]);
+    mac.update(&handshake[tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN..]);
+    Some(mac.finalize().into_bytes().into())
+}
+
+/// Validate a candidate secret against parsed TLS authentication material.
+pub(super) fn validate_tls_secret_candidate(
+    parsed: &ParsedTlsAuthMaterial,
+    handshake: &[u8],
+    secret: &[u8],
+) -> Option<TlsCandidateValidation> {
+    let computed = compute_tls_hmac_zeroed_digest(secret, handshake)?;
+    if !bool::from(parsed.digest[..28].ct_eq(&computed[..28])) {
+        return None;
+    }
+
+    let timestamp = u32::from_le_bytes([
+        parsed.digest[28] ^ computed[28],
+        parsed.digest[29] ^ computed[29],
+        parsed.digest[30] ^ computed[30],
+        parsed.digest[31] ^ computed[31],
+    ]);
+
+    if !parsed.ignore_time_skew {
+        let is_boot_time = parsed.boot_time_cap_secs > 0 && timestamp < parsed.boot_time_cap_secs;
+        if !is_boot_time {
+            let time_diff = parsed.now - i64::from(timestamp);
+            if !(tls::TIME_SKEW_MIN..=tls::TIME_SKEW_MAX).contains(&time_diff) {
+                return None;
+            }
+        }
+    }
+
+    Some(TlsCandidateValidation {
+        digest: parsed.digest,
+        session_id: parsed.session_id,
+        session_id_len: parsed.session_id_len,
+    })
+}

src/proxy/masking.rs

@@ -3,12 +3,15 @@
 use crate::config::ProxyConfig;
 use crate::network::dns_overrides::resolve_socket_addr;
 use crate::protocol::tls;
+use crate::proxy::shared_state::ProxySharedState;
 use crate::stats::beobachten::BeobachtenStore;
 use crate::transport::proxy_protocol::{ProxyProtocolV1Builder, ProxyProtocolV2Builder};
+use crate::transport::socket::configure_tcp_socket;
 #[cfg(unix)]
 use nix::ifaddrs::getifaddrs;
 use rand::rngs::StdRng;
 use rand::{Rng, RngExt, SeedableRng};
+use std::io::{Error as IoError, ErrorKind};
 use std::net::{IpAddr, SocketAddr};
 use std::str;
 #[cfg(test)]
@@ -17,9 +20,9 @@ use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::{Mutex, OnceLock};
 use std::time::{Duration, Instant as StdInstant};
 use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
-use tokio::net::TcpStream;
 #[cfg(unix)]
 use tokio::net::UnixStream;
+use tokio::net::{TcpStream, lookup_host};
 #[cfg(unix)]
 use tokio::sync::Mutex as AsyncMutex;
 use tokio::time::{Instant, timeout};
@@ -36,6 +39,8 @@ const MASK_RELAY_TIMEOUT: Duration = Duration::from_millis(200);
 #[cfg(test)]
 const MASK_RELAY_IDLE_TIMEOUT: Duration = Duration::from_millis(100);
 const MASK_BUFFER_SIZE: usize = 8192;
+const MASK_BUFFER_GROW_AFTER_BYTES: usize = 256 * 1024;
+const MASK_BUFFER_MAX_SIZE: usize = 64 * 1024;
 #[cfg(unix)]
 #[cfg(not(test))]
 const LOCAL_INTERFACE_CACHE_TTL: Duration = Duration::from_secs(300);
@@ -53,6 +58,27 @@ struct MaskTcpTarget<'a> {
     port: u16,
 }
 
+fn mask_copy_read_len(total: usize, byte_cap: usize) -> usize {
+    // Keep short scanner probes on the small baseline buffer and grow only
+    // after the session has proven to be sustained masking relay traffic.
+    let active_buffer_size = if total >= MASK_BUFFER_GROW_AFTER_BYTES {
+        MASK_BUFFER_MAX_SIZE
+    } else {
+        MASK_BUFFER_SIZE
+    };
+
+    if byte_cap == 0 {
+        return active_buffer_size;
+    }
+
+    let remaining_budget = byte_cap.saturating_sub(total);
+    if remaining_budget == 0 {
+        return 0;
+    }
+
+    remaining_budget.min(active_buffer_size)
+}
+
 async fn copy_with_idle_timeout<R, W>(
     reader: &mut R,
     writer: &mut W,
@@ -64,21 +90,18 @@ where
     R: AsyncRead + Unpin,
     W: AsyncWrite + Unpin,
 {
-    let mut buf = Box::new([0u8; MASK_BUFFER_SIZE]);
+    let mut buf = vec![0u8; MASK_BUFFER_SIZE];
     let mut total = 0usize;
     let mut ended_by_eof = false;
-    let unlimited = byte_cap == 0;
 
     loop {
-        let read_len = if unlimited {
-            MASK_BUFFER_SIZE
-        } else {
-            let remaining_budget = byte_cap.saturating_sub(total);
-            if remaining_budget == 0 {
-                break;
-            }
-            remaining_budget.min(MASK_BUFFER_SIZE)
-        };
+        let read_len = mask_copy_read_len(total, byte_cap);
+        if read_len == 0 {
+            break;
+        }
+        if buf.len() < read_len {
+            buf.resize(read_len, 0);
+        }
         let read_res = timeout(idle_timeout, reader.read(&mut buf[..read_len])).await;
         let n = match read_res {
             Ok(Ok(n)) => n,
@@ -250,6 +273,32 @@ async fn consume_client_data_with_timeout_and_cap<R>(
     }
 }
 
+fn mask_failure_drain_cap(config: &ProxyConfig) -> usize {
+    let configured_cap = config.censorship.mask_relay_max_bytes;
+    if configured_cap == 0 {
+        return MASK_BUFFER_SIZE;
+    }
+
+    configured_cap.min(MASK_BUFFER_SIZE)
+}
+
+async fn consume_mask_failure_path<R>(
+    reader: R,
+    config: &ProxyConfig,
+    relay_timeout: Duration,
+    idle_timeout: Duration,
+) where
+    R: AsyncRead + Unpin,
+{
+    consume_client_data_with_timeout_and_cap(
+        reader,
+        mask_failure_drain_cap(config),
+        relay_timeout,
+        idle_timeout,
+    )
+    .await;
+}
+
 async fn wait_mask_connect_budget(started: Instant) {
     let elapsed = started.elapsed();
     if elapsed < MASK_TIMEOUT {
@@ -385,7 +434,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 +468,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();
@@ -471,6 +529,32 @@ fn parse_mask_host_ip_literal(host: &str) -> Option<IpAddr> {
     host.parse::<IpAddr>().ok()
 }
 
+async fn resolve_mask_target_addrs(
+    mask_host: &str,
+    mask_port: u16,
+) -> std::io::Result<Vec<SocketAddr>> {
+    if let Some(addr) = resolve_socket_addr(mask_host, mask_port) {
+        return Ok(vec![addr]);
+    }
+
+    if let Some(ip) = parse_mask_host_ip_literal(mask_host) {
+        return Ok(vec![SocketAddr::new(ip, mask_port)]);
+    }
+
+    let addrs = timeout(MASK_TIMEOUT, lookup_host((mask_host, mask_port)))
+        .await
+        .map_err(|_| IoError::new(ErrorKind::TimedOut, "mask target DNS lookup timed out"))??;
+    let addrs = addrs.collect::<Vec<_>>();
+    if addrs.is_empty() {
+        return Err(IoError::new(
+            ErrorKind::NotFound,
+            "mask target DNS lookup returned no addresses",
+        ));
+    }
+
+    Ok(addrs)
+}
+
 fn matching_tls_domain_for_sni<'a>(config: &'a ProxyConfig, sni: &str) -> Option<&'a str> {
     if config.censorship.tls_domain.eq_ignore_ascii_case(sni) {
         return Some(config.censorship.tls_domain.as_str());
@@ -577,24 +661,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,
     }
 }
@@ -744,7 +836,7 @@ fn is_mask_target_local_listener_with_interfaces(
     mask_host: &str,
     mask_port: u16,
     local_addr: SocketAddr,
-    resolved_override: Option<SocketAddr>,
+    resolved_addrs: &[SocketAddr],
     interface_ips: &[IpAddr],
 ) -> bool {
     if mask_port != local_addr.port() {
@@ -754,7 +846,7 @@ fn is_mask_target_local_listener_with_interfaces(
     let local_ip = canonical_ip(local_addr.ip());
     let literal_mask_ip = parse_mask_host_ip_literal(mask_host).map(canonical_ip);
 
-    if let Some(addr) = resolved_override {
+    for addr in resolved_addrs {
         let resolved_ip = canonical_ip(addr.ip());
         if resolved_ip == local_ip {
             return true;
@@ -791,7 +883,7 @@ fn is_mask_target_local_listener(
     mask_host: &str,
     mask_port: u16,
     local_addr: SocketAddr,
-    resolved_override: Option<SocketAddr>,
+    resolved_addrs: &[SocketAddr],
 ) -> bool {
     if mask_port != local_addr.port() {
         return false;
@@ -802,7 +894,7 @@ fn is_mask_target_local_listener(
         mask_host,
         mask_port,
         local_addr,
-        resolved_override,
+        resolved_addrs,
         &interfaces,
     )
 }
@@ -811,7 +903,7 @@ async fn is_mask_target_local_listener_async(
     mask_host: &str,
     mask_port: u16,
     local_addr: SocketAddr,
-    resolved_override: Option<SocketAddr>,
+    resolved_addrs: &[SocketAddr],
 ) -> bool {
     if mask_port != local_addr.port() {
         return false;
@@ -822,7 +914,7 @@ async fn is_mask_target_local_listener_async(
         mask_host,
         mask_port,
         local_addr,
-        resolved_override,
+        resolved_addrs,
         &interfaces,
     )
 }
@@ -860,7 +952,13 @@ fn build_mask_proxy_header(
     }
 }
 
-/// Handle a bad client by forwarding to mask host
+fn configure_mask_backend_socket(stream: &TcpStream) {
+    if let Err(e) = configure_tcp_socket(stream, false, Duration::from_secs(0)) {
+        debug!(error = %e, "Failed to configure mask backend socket");
+    }
+}
+
+/// Handles a bad client by forwarding it to the configured mask target.
 pub async fn handle_bad_client<R, W>(
     reader: R,
     writer: W,
@@ -872,6 +970,34 @@ pub async fn handle_bad_client<R, W>(
 ) where
     R: AsyncRead + Unpin + Send + 'static,
     W: AsyncWrite + Unpin + Send + 'static,
+{
+    let shared = ProxySharedState::new();
+    handle_bad_client_with_shared(
+        reader,
+        writer,
+        initial_data,
+        peer,
+        local_addr,
+        config,
+        beobachten,
+        shared.as_ref(),
+    )
+    .await;
+}
+
+/// Handles a bad client with shared pre-auth fallback admission state.
+pub(crate) async fn handle_bad_client_with_shared<R, W>(
+    reader: R,
+    writer: W,
+    initial_data: &[u8],
+    peer: SocketAddr,
+    local_addr: SocketAddr,
+    config: &ProxyConfig,
+    beobachten: &BeobachtenStore,
+    shared: &ProxySharedState,
+) where
+    R: AsyncRead + Unpin + Send + 'static,
+    W: AsyncWrite + Unpin + Send + 'static,
 {
     let client_type = detect_client_type(initial_data);
     if config.general.beobachten {
@@ -894,6 +1020,17 @@ pub async fn handle_bad_client<R, W>(
         return;
     }
 
+    let Some(_masking_permit) = shared.try_acquire_masking_fallback_permit() else {
+        let outcome_started = Instant::now();
+        debug!(
+            client_type = client_type,
+            "Masking fallback concurrency limit reached"
+        );
+        consume_mask_failure_path(reader, config, relay_timeout, idle_timeout).await;
+        wait_mask_outcome_budget(outcome_started, config).await;
+        return;
+    };
+
     let client_sni = tls::extract_sni_from_client_hello(initial_data);
     let exclusive_tcp_target = client_sni
         .as_deref()
@@ -956,24 +1093,12 @@ pub async fn handle_bad_client<R, W>(
             Ok(Err(e)) => {
                 wait_mask_connect_budget_if_needed(connect_started, config).await;
                 debug!(error = %e, "Failed to connect to mask unix socket");
-                consume_client_data_with_timeout_and_cap(
-                    reader,
-                    config.censorship.mask_relay_max_bytes,
-                    relay_timeout,
-                    idle_timeout,
-                )
-                .await;
+                consume_mask_failure_path(reader, config, relay_timeout, idle_timeout).await;
                 wait_mask_outcome_budget(outcome_started, config).await;
             }
             Err(_) => {
                 debug!("Timeout connecting to mask unix socket");
-                consume_client_data_with_timeout_and_cap(
-                    reader,
-                    config.censorship.mask_relay_max_bytes,
-                    relay_timeout,
-                    idle_timeout,
-                )
-                .await;
+                consume_mask_failure_path(reader, config, relay_timeout, idle_timeout).await;
                 wait_mask_outcome_budget(outcome_started, config).await;
             }
         }
@@ -986,11 +1111,27 @@ pub async fn handle_bad_client<R, W>(
     let mask_host = mask_target.host;
     let mask_port = mask_target.port;
 
+    let resolved_mask_addrs = match resolve_mask_target_addrs(mask_host, mask_port).await {
+        Ok(addrs) => addrs,
+        Err(e) => {
+            let outcome_started = Instant::now();
+            debug!(
+                client_type = client_type,
+                host = %mask_host,
+                port = mask_port,
+                error = %e,
+                "Failed to resolve mask target"
+            );
+            consume_mask_failure_path(reader, config, relay_timeout, idle_timeout).await;
+            wait_mask_outcome_budget(outcome_started, config).await;
+            return;
+        }
+    };
+
     // Fail closed when fallback points at our own listener endpoint.
     // Self-referential masking can create recursive proxy loops under
     // misconfiguration and leak distinguishable load spikes to adversaries.
-    let resolved_mask_addr = resolve_socket_addr(mask_host, mask_port);
-    if is_mask_target_local_listener_async(mask_host, mask_port, local_addr, resolved_mask_addr)
+    if is_mask_target_local_listener_async(mask_host, mask_port, local_addr, &resolved_mask_addrs)
         .await
     {
         let outcome_started = Instant::now();
@@ -1001,13 +1142,7 @@ pub async fn handle_bad_client<R, W>(
             local = %local_addr,
             "Mask target resolves to local listener; refusing self-referential masking fallback"
         );
-        consume_client_data_with_timeout_and_cap(
-            reader,
-            config.censorship.mask_relay_max_bytes,
-            relay_timeout,
-            idle_timeout,
-        )
-        .await;
+        consume_mask_failure_path(reader, config, relay_timeout, idle_timeout).await;
         wait_mask_outcome_budget(outcome_started, config).await;
         return;
     }
@@ -1022,14 +1157,15 @@ pub async fn handle_bad_client<R, W>(
         "Forwarding bad client to mask host"
     );
 
-    // Apply runtime DNS override for mask target when configured.
-    let mask_addr = resolved_mask_addr
-        .map(|addr| addr.to_string())
-        .unwrap_or_else(|| format!("{}:{}", mask_host, mask_port));
     let connect_started = Instant::now();
-    let connect_result = timeout(MASK_TIMEOUT, TcpStream::connect(&mask_addr)).await;
+    let connect_result = timeout(
+        MASK_TIMEOUT,
+        TcpStream::connect(resolved_mask_addrs.as_slice()),
+    )
+    .await;
     match connect_result {
         Ok(Ok(stream)) => {
+            configure_mask_backend_socket(&stream);
             let proxy_header =
                 build_mask_proxy_header(config.censorship.mask_proxy_protocol, peer, local_addr);
 
@@ -1068,24 +1204,12 @@ pub async fn handle_bad_client<R, W>(
         Ok(Err(e)) => {
             wait_mask_connect_budget_if_needed(connect_started, config).await;
             debug!(error = %e, "Failed to connect to mask host");
-            consume_client_data_with_timeout_and_cap(
-                reader,
-                config.censorship.mask_relay_max_bytes,
-                relay_timeout,
-                idle_timeout,
-            )
-            .await;
+            consume_mask_failure_path(reader, config, relay_timeout, idle_timeout).await;
             wait_mask_outcome_budget(outcome_started, config).await;
         }
         Err(_) => {
             debug!("Timeout connecting to mask host");
-            consume_client_data_with_timeout_and_cap(
-                reader,
-                config.censorship.mask_relay_max_bytes,
-                relay_timeout,
-                idle_timeout,
-            )
-            .await;
+            consume_mask_failure_path(reader, config, relay_timeout, idle_timeout).await;
             wait_mask_outcome_budget(outcome_started, config).await;
         }
     }
@@ -1173,20 +1297,17 @@ async fn consume_client_data<R: AsyncRead + Unpin>(
     idle_timeout: Duration,
 ) {
     // Keep drain path fail-closed under slow-loris stalls.
-    let mut buf = Box::new([0u8; MASK_BUFFER_SIZE]);
+    let mut buf = vec![0u8; MASK_BUFFER_SIZE];
     let mut total = 0usize;
-    let unlimited = byte_cap == 0;
 
     loop {
-        let read_len = if unlimited {
-            MASK_BUFFER_SIZE
-        } else {
-            let remaining_budget = byte_cap.saturating_sub(total);
-            if remaining_budget == 0 {
-                break;
-            }
-            remaining_budget.min(MASK_BUFFER_SIZE)
-        };
+        let read_len = mask_copy_read_len(total, byte_cap);
+        if read_len == 0 {
+            break;
+        }
+        if buf.len() < read_len {
+            buf.resize(read_len, 0);
+        }
         let n = match timeout(idle_timeout, reader.read(&mut buf[..read_len])).await {
             Ok(Ok(n)) => n,
             Ok(Err(_)) | Err(_) => break,
@@ -1197,7 +1318,7 @@ async fn consume_client_data<R: AsyncRead + Unpin>(
         }
 
         total = total.saturating_add(n);
-        if !unlimited && total >= byte_cap {
+        if byte_cap != 0 && total >= byte_cap {
             break;
         }
     }
@@ -1315,6 +1436,10 @@ mod masking_interface_cache_concurrency_security_tests;
 #[path = "tests/masking_production_cap_regression_security_tests.rs"]
 mod masking_production_cap_regression_security_tests;
 
+#[cfg(test)]
+#[path = "tests/masking_relay_manual_perf_tests.rs"]
+mod masking_relay_manual_perf_tests;
+
 #[cfg(test)]
 #[path = "tests/masking_extended_attack_surface_security_tests.rs"]
 mod masking_extended_attack_surface_security_tests;

src/proxy/middle_relay.rs

@@ -52,7 +52,7 @@ use self::c2me::{
 };
 use self::d2c::{
     MeD2cFlushPolicy, MeWriterResponseOutcome, classify_me_d2c_flush_reason,
-    flush_client_or_cancel, observe_me_d2c_flush_event,
+    flush_client_or_cancel, me_d2c_flush_reason_requires_client_flush, observe_me_d2c_flush_event,
     process_me_writer_response_with_traffic_lease,
 };
 use self::desync::{RelayForensicsState, hash_ip_in, report_desync_frame_too_large_in};
@@ -69,7 +69,9 @@ use self::quota::{
 #[cfg(test)]
 use self::c2me::enqueue_c2me_command;
 #[cfg(test)]
-use self::d2c::{compute_intermediate_secure_wire_len, process_me_writer_response};
+use self::d2c::{
+    compute_intermediate_secure_wire_len, process_me_writer_response, write_client_payload,
+};
 #[cfg(test)]
 pub(crate) use self::desync::{
     clear_desync_dedup_for_testing_in_shared, desync_dedup_get_for_testing,
@@ -166,3 +168,7 @@ mod middle_relay_atomic_quota_invariant_tests;
 #[cfg(test)]
 #[path = "tests/middle_relay_baseline_invariant_tests.rs"]
 mod middle_relay_baseline_invariant_tests;
+
+#[cfg(test)]
+#[path = "tests/middle_relay_d2c_flush_padding_security_tests.rs"]
+mod middle_relay_d2c_flush_padding_security_tests;

src/proxy/middle_relay/d2c.rs

@@ -55,6 +55,37 @@ pub(super) fn classify_me_d2c_flush_reason(
     MeD2cFlushReason::QueueDrain
 }
 
+pub(super) fn me_d2c_flush_reason_requires_client_flush(_reason: MeD2cFlushReason) -> bool {
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn all_flush_reasons_trigger_physical_flush() {
+        assert!(me_d2c_flush_reason_requires_client_flush(
+            MeD2cFlushReason::QueueDrain
+        ));
+        assert!(me_d2c_flush_reason_requires_client_flush(
+            MeD2cFlushReason::AckImmediate
+        ));
+        assert!(me_d2c_flush_reason_requires_client_flush(
+            MeD2cFlushReason::BatchFrames
+        ));
+        assert!(me_d2c_flush_reason_requires_client_flush(
+            MeD2cFlushReason::BatchBytes
+        ));
+        assert!(me_d2c_flush_reason_requires_client_flush(
+            MeD2cFlushReason::MaxDelay
+        ));
+        assert!(me_d2c_flush_reason_requires_client_flush(
+            MeD2cFlushReason::Close
+        ));
+    }
+}
+
 pub(super) fn observe_me_d2c_flush_event(
     stats: &Stats,
     reason: MeD2cFlushReason,
@@ -276,20 +307,13 @@ pub(in crate::proxy::middle_relay) fn compute_intermediate_secure_wire_len(
     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 len_val = crate::protocol::framing::encode_intermediate_header(wire_len, quickack)
+        .ok_or_else(|| {
+            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))
 }
 

src/proxy/middle_relay/idle/read.rs

@@ -236,12 +236,8 @@ where
                     }
                     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),
-                )
+                let header = crate::protocol::framing::parse_intermediate_header(len_buf);
+                (header.wire_len, header.quickack, Some(len_buf))
             }
         };
 
@@ -331,7 +327,8 @@ where
         )
         .await?;
 
-        // Secure Intermediate: strip validated trailing padding bytes.
+        // Secure Intermediate strips only non-aligned tail padding; full-word
+        // padding is indistinguishable from payload in VersionD framing.
         if proto_tag == ProtoTag::Secure {
             payload.truncate(secure_payload_len);
         }

src/proxy/middle_relay/session.rs

@@ -149,6 +149,7 @@ where
                             peer,
                             translated_local_addr,
                             payload,
+                            _permit,
                             flags,
                             effective_tag_array,
                         )
@@ -491,12 +492,18 @@ where
                         d2c_flush_policy.max_bytes,
                         max_delay_fired,
                     );
-                    let flush_started_at = if stats_clone.telemetry_policy().me_level.allows_debug() {
+                    let physical_flush =
+                        me_d2c_flush_reason_requires_client_flush(flush_reason);
+                    let flush_started_at = if physical_flush
+                        && stats_clone.telemetry_policy().me_level.allows_debug()
+                    {
                         Some(Instant::now())
                     } else {
                         None
                     };
-                    flush_client_or_cancel(&mut writer, &flow_cancel_me_writer).await?;
+                    if physical_flush {
+                        flush_client_or_cancel(&mut writer, &flow_cancel_me_writer).await?;
+                    }
                     let flush_duration_us = flush_started_at.map(|started| {
                         started
                             .elapsed()
@@ -816,7 +823,6 @@ where
 
     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,

src/proxy/mod.rs

@@ -60,6 +60,8 @@
 
 pub mod adaptive_buffers;
 pub mod client;
+// Process-wide Direct relay copy-buffer ownership and pressure policy.
+pub(crate) mod direct_buffer_budget;
 pub mod direct_relay;
 pub mod handshake;
 pub mod masking;

src/proxy/relay.rs

@@ -84,8 +84,11 @@ fn watchdog_delta(current: u64, previous: u64) -> u64 {
     current.saturating_sub(previous)
 }
 
+mod adaptive_copy;
 mod io;
 
+pub(crate) use self::adaptive_copy::relay_direct_adaptive;
+
 use self::io::{CombinedStream, SharedCounters, StatsIo, is_quota_io_error};
 #[cfg(test)]
 use self::io::{quota_adaptive_interval_bytes, should_immediate_quota_check};
@@ -217,6 +220,7 @@ where
     .await
 }
 
+#[allow(dead_code)]
 pub async fn relay_bidirectional_with_activity_timeout_lease_and_cancel<CR, CW, SR, SW>(
     client_reader: CR,
     client_writer: CW,

src/proxy/relay/adaptive_copy.rs

@@ -0,0 +1,527 @@
+use std::io;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::task::{Context, Poll};
+use std::time::Duration;
+
+use tokio::io::{AsyncBufRead, AsyncRead, AsyncWrite, AsyncWriteExt, ReadBuf, copy_buf};
+use tokio::time::Instant;
+use tokio_util::sync::CancellationToken;
+use tracing::{debug, warn};
+
+use crate::error::{ProxyError, Result};
+use crate::proxy::adaptive_buffers::{
+    AdaptiveTier, RelaySignalSample, SessionAdaptiveController, TierTransitionReason,
+    direct_copy_buffers_for_tier_with_ceilings,
+};
+use crate::proxy::direct_buffer_budget::{
+    DIRECT_BASE_C2S_BYTES, DIRECT_BASE_S2C_BYTES, DirectBufferBudget, DirectBufferLease,
+};
+use crate::proxy::traffic_limiter::TrafficLease;
+use crate::stats::Stats;
+
+use super::WATCHDOG_INTERVAL;
+use super::io::{SharedCounters, StatsIo, is_quota_io_error};
+use super::watchdog_delta;
+
+mod write_pressure;
+
+use self::write_pressure::WritePressureIo;
+
+struct AdaptiveBufferState {
+    desired_bytes: AtomicUsize,
+    actual_bytes: AtomicUsize,
+}
+
+impl AdaptiveBufferState {
+    fn new(bytes: usize) -> Arc<Self> {
+        Arc::new(Self {
+            desired_bytes: AtomicUsize::new(bytes.max(1)),
+            actual_bytes: AtomicUsize::new(bytes.max(1)),
+        })
+    }
+}
+
+struct AdaptiveBufReader<R> {
+    inner: R,
+    buffer: Box<[u8]>,
+    pos: usize,
+    cap: usize,
+    state: Arc<AdaptiveBufferState>,
+}
+
+impl<R> AdaptiveBufReader<R> {
+    fn new(inner: R, state: Arc<AdaptiveBufferState>) -> Self {
+        let bytes = state.actual_bytes.load(Ordering::Relaxed).max(1);
+        Self {
+            inner,
+            buffer: vec![0; bytes].into_boxed_slice(),
+            pos: 0,
+            cap: 0,
+            state,
+        }
+    }
+
+    fn resize_if_drained(&mut self) {
+        if self.pos != self.cap {
+            return;
+        }
+        let desired = self.state.desired_bytes.load(Ordering::Acquire).max(1);
+        if desired == self.buffer.len() {
+            return;
+        }
+        self.buffer = vec![0; desired].into_boxed_slice();
+        self.pos = 0;
+        self.cap = 0;
+        self.state.actual_bytes.store(desired, Ordering::Release);
+    }
+}
+
+impl<R: AsyncRead + Unpin> AsyncRead for AdaptiveBufReader<R> {
+    fn poll_read(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        output: &mut ReadBuf<'_>,
+    ) -> Poll<io::Result<()>> {
+        let this = self.get_mut();
+        if this.pos < this.cap {
+            let available = &this.buffer[this.pos..this.cap];
+            let copied = available.len().min(output.remaining());
+            output.put_slice(&available[..copied]);
+            this.pos += copied;
+            return Poll::Ready(Ok(()));
+        }
+        this.resize_if_drained();
+        Pin::new(&mut this.inner).poll_read(cx, output)
+    }
+}
+
+impl<R: AsyncRead + Unpin> AsyncBufRead for AdaptiveBufReader<R> {
+    fn poll_fill_buf(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<&[u8]>> {
+        let this = self.get_mut();
+        if this.pos < this.cap {
+            return Poll::Ready(Ok(&this.buffer[this.pos..this.cap]));
+        }
+
+        this.resize_if_drained();
+        let mut read_buf = ReadBuf::new(&mut this.buffer);
+        match Pin::new(&mut this.inner).poll_read(cx, &mut read_buf) {
+            Poll::Ready(Ok(())) => {
+                this.pos = 0;
+                this.cap = read_buf.filled().len();
+                Poll::Ready(Ok(&this.buffer[..this.cap]))
+            }
+            Poll::Ready(Err(error)) => Poll::Ready(Err(error)),
+            Poll::Pending => Poll::Pending,
+        }
+    }
+
+    fn consume(self: Pin<&mut Self>, amount: usize) {
+        let this = self.get_mut();
+        this.pos = this.pos.saturating_add(amount).min(this.cap);
+    }
+}
+
+enum AdaptiveRelayOutcome {
+    Copy(io::Result<(u64, u64)>),
+    ActivityTimeout,
+    UserDisabled,
+}
+
+#[allow(clippy::too_many_arguments)]
+/// Relays one Direct session with independently resizable directional buffers.
+pub(crate) async fn relay_direct_adaptive<CR, CW, SR, SW>(
+    client_reader: CR,
+    client_writer: CW,
+    server_reader: SR,
+    server_writer: SW,
+    ceiling_c2s_bytes: usize,
+    ceiling_s2c_bytes: usize,
+    max_connections: u32,
+    user: &str,
+    stats: Arc<Stats>,
+    quota_limit: Option<u64>,
+    traffic_lease: Option<Arc<TrafficLease>>,
+    activity_timeout: Duration,
+    session_cancel: CancellationToken,
+    budget: Arc<DirectBufferBudget>,
+) -> Result<()>
+where
+    CR: AsyncRead + Unpin + Send + 'static,
+    CW: AsyncWrite + Unpin + Send + 'static,
+    SR: AsyncRead + Unpin + Send + 'static,
+    SW: AsyncWrite + Unpin + Send + 'static,
+{
+    let activity_timeout = activity_timeout.max(Duration::from_secs(1));
+    let epoch = Instant::now();
+    let counters = Arc::new(SharedCounters::new());
+    let quota_exceeded = Arc::new(AtomicBool::new(false));
+    let user_owned = user.to_string();
+
+    let (base_c2s, base_s2c) = initial_base_sizes(
+        ceiling_c2s_bytes,
+        ceiling_s2c_bytes,
+        max_connections,
+        budget.target_bytes(),
+    );
+    let base_total = base_c2s.saturating_add(base_s2c);
+    let mut lease = match budget.try_reserve(base_total, false) {
+        Some(lease) => lease,
+        None => {
+            let minimum_total = DIRECT_BASE_C2S_BYTES + DIRECT_BASE_S2C_BYTES;
+            match budget.try_reserve(minimum_total, true) {
+                Some(lease) => {
+                    budget.increment_minimum_fallback();
+                    lease
+                }
+                None => {
+                    budget.increment_admission_rejected();
+                    return Err(ProxyError::Proxy(
+                        "Direct relay buffer pressure: budget exhausted".to_string(),
+                    ));
+                }
+            }
+        }
+    };
+
+    let effective_base = if lease.reserved_bytes() < base_total {
+        (DIRECT_BASE_C2S_BYTES, DIRECT_BASE_S2C_BYTES)
+    } else {
+        (base_c2s, base_s2c)
+    };
+    let c2s_state = AdaptiveBufferState::new(effective_base.0);
+    let s2c_state = AdaptiveBufferState::new(effective_base.1);
+
+    let mut controller = SessionAdaptiveController::new(AdaptiveTier::Base);
+
+    let c2s_client = StatsIo::new_with_traffic_lease(
+        client_reader,
+        Arc::clone(&counters),
+        Arc::clone(&stats),
+        user_owned.clone(),
+        traffic_lease.clone(),
+        quota_limit,
+        Arc::clone(&quota_exceeded),
+        epoch,
+    );
+    let client_writer = StatsIo::new_with_traffic_lease(
+        client_writer,
+        Arc::clone(&counters),
+        Arc::clone(&stats),
+        user_owned.clone(),
+        traffic_lease,
+        quota_limit,
+        Arc::clone(&quota_exceeded),
+        epoch,
+    );
+    let mut client_writer = WritePressureIo::new(client_writer, Arc::clone(&counters));
+    let mut c2s_reader = AdaptiveBufReader::new(c2s_client, Arc::clone(&c2s_state));
+    let mut s2c_reader = AdaptiveBufReader::new(server_reader, Arc::clone(&s2c_state));
+    let mut server_writer = server_writer;
+    let mut pressure_rx = budget.subscribe_pressure();
+
+    let relay_outcome = {
+        let copy = async {
+            let c2s = async {
+                let copied = copy_buf(&mut c2s_reader, &mut server_writer).await?;
+                server_writer.shutdown().await?;
+                Ok::<u64, io::Error>(copied)
+            };
+            let s2c = async {
+                let copied = copy_buf(&mut s2c_reader, &mut client_writer).await?;
+                client_writer.shutdown().await?;
+                Ok::<u64, io::Error>(copied)
+            };
+            tokio::try_join!(c2s, s2c)
+        };
+        tokio::pin!(copy);
+
+        let mut interval = tokio::time::interval(WATCHDOG_INTERVAL);
+        interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+        interval.tick().await;
+        let mut previous = RelaySignalSample::default();
+        let mut previous_log_c2s = 0u64;
+        let mut previous_log_s2c = 0u64;
+        let mut previous_sample_at = epoch;
+
+        loop {
+            tokio::select! {
+                result = &mut copy => break AdaptiveRelayOutcome::Copy(result),
+                _ = session_cancel.cancelled() => break AdaptiveRelayOutcome::UserDisabled,
+                changed = pressure_rx.changed() => {
+                    if changed.is_ok() {
+                        apply_global_pressure_demotion(
+                            &mut controller,
+                            &mut lease,
+                            &c2s_state,
+                            &s2c_state,
+                            effective_base,
+                            (ceiling_c2s_bytes, ceiling_s2c_bytes),
+                            budget.as_ref(),
+                        );
+                        reconcile_reservation(&mut lease, &c2s_state, &s2c_state);
+                    }
+                }
+                _ = interval.tick() => {
+                    let now = Instant::now();
+                    let idle = counters.idle_duration(now, epoch);
+                    if quota_exceeded.load(Ordering::Acquire) {
+                        warn!(user = %user_owned, "User data quota reached, closing relay");
+                        break AdaptiveRelayOutcome::ActivityTimeout;
+                    }
+                    if idle >= activity_timeout {
+                        warn!(
+                            user = %user_owned,
+                            c2s_bytes = counters.c2s_bytes.load(Ordering::Relaxed),
+                            s2c_bytes = counters.s2c_bytes.load(Ordering::Relaxed),
+                            idle_secs = idle.as_secs(),
+                            "Activity timeout"
+                        );
+                        break AdaptiveRelayOutcome::ActivityTimeout;
+                    }
+
+                    let sample = current_sample(counters.as_ref());
+                    let c2s_delta = watchdog_delta(sample.c2s_bytes, previous_log_c2s);
+                    let s2c_delta = watchdog_delta(sample.s2c_written_bytes, previous_log_s2c);
+                    if c2s_delta > 0 || s2c_delta > 0 {
+                        let secs = now.saturating_duration_since(previous_sample_at).as_secs_f64();
+                        debug!(
+                            user = %user_owned,
+                            c2s_kbps = (c2s_delta as f64 / secs / 1024.0) as u64,
+                            s2c_kbps = (s2c_delta as f64 / secs / 1024.0) as u64,
+                            c2s_total = sample.c2s_bytes,
+                            s2c_total = sample.s2c_written_bytes,
+                            "Relay active"
+                        );
+                    }
+
+                    let delta = sample_delta(sample, previous);
+                    let tick_secs = now.saturating_duration_since(previous_sample_at).as_secs_f64();
+                    if let Some(transition) = controller.observe(delta, tick_secs) {
+                        apply_controller_transition(
+                            transition,
+                            &mut controller,
+                            &mut lease,
+                            &c2s_state,
+                            &s2c_state,
+                            effective_base,
+                            (ceiling_c2s_bytes, ceiling_s2c_bytes),
+                            budget.as_ref(),
+                        );
+                    }
+                    reconcile_reservation(&mut lease, &c2s_state, &s2c_state);
+                    previous = sample;
+                    previous_log_c2s = sample.c2s_bytes;
+                    previous_log_s2c = sample.s2c_written_bytes;
+                    previous_sample_at = now;
+                }
+            }
+        }
+    };
+
+    let _ = client_writer.shutdown().await;
+    let _ = server_writer.shutdown().await;
+    let c2s_ops = counters.c2s_ops.load(Ordering::Relaxed);
+    let s2c_ops = counters.s2c_ops.load(Ordering::Relaxed);
+    let duration = epoch.elapsed();
+    match relay_outcome {
+        AdaptiveRelayOutcome::Copy(Ok((c2s, s2c))) => {
+            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"
+            );
+            Ok(())
+        }
+        AdaptiveRelayOutcome::Copy(Err(error)) if is_quota_io_error(&error) => {
+            warn!(
+                user = %user_owned,
+                c2s_bytes = counters.c2s_bytes.load(Ordering::Relaxed),
+                s2c_bytes = counters.s2c_bytes.load(Ordering::Relaxed),
+                c2s_msgs = c2s_ops,
+                s2c_msgs = s2c_ops,
+                duration_secs = duration.as_secs(),
+                "Data quota reached, closing relay"
+            );
+            Err(ProxyError::DataQuotaExceeded { user: user_owned })
+        }
+        AdaptiveRelayOutcome::Copy(Err(error)) => {
+            debug!(
+                user = %user_owned,
+                c2s_bytes = counters.c2s_bytes.load(Ordering::Relaxed),
+                s2c_bytes = counters.s2c_bytes.load(Ordering::Relaxed),
+                c2s_msgs = c2s_ops,
+                s2c_msgs = s2c_ops,
+                duration_secs = duration.as_secs(),
+                error = %error,
+                "Relay error"
+            );
+            Err(error.into())
+        }
+        AdaptiveRelayOutcome::ActivityTimeout => {
+            debug!(
+                user = %user_owned,
+                c2s_bytes = counters.c2s_bytes.load(Ordering::Relaxed),
+                s2c_bytes = counters.s2c_bytes.load(Ordering::Relaxed),
+                c2s_msgs = c2s_ops,
+                s2c_msgs = s2c_ops,
+                duration_secs = duration.as_secs(),
+                "Relay finished (activity timeout)"
+            );
+            Ok(())
+        }
+        AdaptiveRelayOutcome::UserDisabled => {
+            debug!(
+                user = %user_owned,
+                c2s_bytes = counters.c2s_bytes.load(Ordering::Relaxed),
+                s2c_bytes = counters.s2c_bytes.load(Ordering::Relaxed),
+                c2s_msgs = c2s_ops,
+                s2c_msgs = s2c_ops,
+                duration_secs = duration.as_secs(),
+                "Relay finished (user disabled)"
+            );
+            Err(ProxyError::UserDisabled { user: user_owned })
+        }
+    }
+}
+
+fn initial_base_sizes(
+    ceiling_c2s: usize,
+    ceiling_s2c: usize,
+    max_connections: u32,
+    target_bytes: usize,
+) -> (usize, usize) {
+    let configured_total = ceiling_c2s.saturating_add(ceiling_s2c);
+    let configured_worst_case = configured_total.saturating_mul(max_connections as usize);
+    if max_connections != 0 && configured_worst_case <= target_bytes {
+        return (ceiling_c2s, ceiling_s2c);
+    }
+    (
+        DIRECT_BASE_C2S_BYTES.min(ceiling_c2s),
+        DIRECT_BASE_S2C_BYTES.min(ceiling_s2c),
+    )
+}
+
+fn current_sample(counters: &SharedCounters) -> RelaySignalSample {
+    RelaySignalSample {
+        c2s_bytes: counters.c2s_bytes.load(Ordering::Relaxed),
+        s2c_requested_bytes: counters.s2c_requested_bytes.load(Ordering::Relaxed),
+        s2c_written_bytes: counters.s2c_bytes.load(Ordering::Relaxed),
+        s2c_write_ops: counters.s2c_ops.load(Ordering::Relaxed),
+        s2c_partial_writes: counters.s2c_partial_writes.load(Ordering::Relaxed),
+        s2c_consecutive_pending_writes: counters
+            .s2c_consecutive_pending_writes
+            .load(Ordering::Relaxed),
+    }
+}
+
+fn sample_delta(current: RelaySignalSample, previous: RelaySignalSample) -> RelaySignalSample {
+    RelaySignalSample {
+        c2s_bytes: current.c2s_bytes.saturating_sub(previous.c2s_bytes),
+        s2c_requested_bytes: current
+            .s2c_requested_bytes
+            .saturating_sub(previous.s2c_requested_bytes),
+        s2c_written_bytes: current
+            .s2c_written_bytes
+            .saturating_sub(previous.s2c_written_bytes),
+        s2c_write_ops: current.s2c_write_ops.saturating_sub(previous.s2c_write_ops),
+        s2c_partial_writes: current
+            .s2c_partial_writes
+            .saturating_sub(previous.s2c_partial_writes),
+        s2c_consecutive_pending_writes: current.s2c_consecutive_pending_writes,
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn apply_controller_transition(
+    transition: crate::proxy::adaptive_buffers::TierTransition,
+    controller: &mut SessionAdaptiveController,
+    lease: &mut DirectBufferLease,
+    c2s_state: &AdaptiveBufferState,
+    s2c_state: &AdaptiveBufferState,
+    base: (usize, usize),
+    ceilings: (usize, usize),
+    budget: &DirectBufferBudget,
+) {
+    let sizes = direct_copy_buffers_for_tier_with_ceilings(
+        transition.to,
+        base.0,
+        base.1,
+        ceilings.0,
+        ceilings.1,
+    );
+    if transition.to > transition.from {
+        if !lease.try_grow_to(sizes.0.saturating_add(sizes.1)) {
+            *controller = SessionAdaptiveController::new(transition.from);
+            return;
+        }
+    } else {
+        match transition.reason {
+            TierTransitionReason::QuietDemotion => budget.increment_quiet_demotion(),
+            TierTransitionReason::SustainedWritePressure => {
+                budget.increment_write_pressure_demotion();
+            }
+            TierTransitionReason::SoftConfirmed | TierTransitionReason::HardPressure => {}
+        }
+    }
+    set_desired_sizes(c2s_state, s2c_state, sizes);
+    lease.set_tier(transition.to.as_u8() as usize);
+}
+
+fn apply_global_pressure_demotion(
+    controller: &mut SessionAdaptiveController,
+    lease: &mut DirectBufferLease,
+    c2s_state: &AdaptiveBufferState,
+    s2c_state: &AdaptiveBufferState,
+    base: (usize, usize),
+    ceilings: (usize, usize),
+    budget: &DirectBufferBudget,
+) {
+    let current = controller.tier();
+    let target = current.demote();
+    if target == current {
+        return;
+    }
+    *controller = SessionAdaptiveController::new(target);
+    let sizes =
+        direct_copy_buffers_for_tier_with_ceilings(target, base.0, base.1, ceilings.0, ceilings.1);
+    set_desired_sizes(c2s_state, s2c_state, sizes);
+    lease.set_tier(target.as_u8() as usize);
+    budget.increment_global_pressure_demotion();
+}
+
+fn set_desired_sizes(
+    c2s_state: &AdaptiveBufferState,
+    s2c_state: &AdaptiveBufferState,
+    sizes: (usize, usize),
+) {
+    c2s_state
+        .desired_bytes
+        .store(sizes.0.max(1), Ordering::Release);
+    s2c_state
+        .desired_bytes
+        .store(sizes.1.max(1), Ordering::Release);
+}
+
+fn reconcile_reservation(
+    lease: &mut DirectBufferLease,
+    c2s_state: &AdaptiveBufferState,
+    s2c_state: &AdaptiveBufferState,
+) {
+    // Promotion reserves the desired allocation before either reader grows.
+    // Demotion keeps the actual allocation covered until its buffered bytes drain.
+    let covered_c2s = c2s_state
+        .actual_bytes
+        .load(Ordering::Acquire)
+        .max(c2s_state.desired_bytes.load(Ordering::Acquire));
+    let covered_s2c = s2c_state
+        .actual_bytes
+        .load(Ordering::Acquire)
+        .max(s2c_state.desired_bytes.load(Ordering::Acquire));
+    lease.shrink_to(covered_c2s.saturating_add(covered_s2c));
+}

src/proxy/relay/adaptive_copy/write_pressure.rs

@@ -0,0 +1,72 @@
+use std::io;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::sync::atomic::Ordering;
+use std::task::{Context, Poll};
+
+use tokio::io::AsyncWrite;
+
+use super::super::io::SharedCounters;
+
+/// Direct-only writer wrapper that exposes bounded backpressure signals.
+pub(super) struct WritePressureIo<W> {
+    inner: W,
+    counters: Arc<SharedCounters>,
+}
+
+impl<W> WritePressureIo<W> {
+    /// Wraps the client writer without changing its I/O or error contract.
+    pub(super) fn new(inner: W, counters: Arc<SharedCounters>) -> Self {
+        Self { inner, counters }
+    }
+}
+
+impl<W: AsyncWrite + Unpin> AsyncWrite for WritePressureIo<W> {
+    fn poll_write(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buffer: &[u8],
+    ) -> Poll<io::Result<usize>> {
+        let this = self.get_mut();
+        if !buffer.is_empty() {
+            this.counters
+                .s2c_requested_bytes
+                .fetch_add(buffer.len() as u64, Ordering::Relaxed);
+        }
+        match Pin::new(&mut this.inner).poll_write(cx, buffer) {
+            Poll::Ready(Ok(written)) => {
+                this.counters
+                    .s2c_consecutive_pending_writes
+                    .store(0, Ordering::Relaxed);
+                if written < buffer.len() {
+                    this.counters
+                        .s2c_partial_writes
+                        .fetch_add(1, Ordering::Relaxed);
+                }
+                Poll::Ready(Ok(written))
+            }
+            Poll::Ready(Err(error)) => {
+                this.counters
+                    .s2c_consecutive_pending_writes
+                    .store(0, Ordering::Relaxed);
+                Poll::Ready(Err(error))
+            }
+            Poll::Pending => {
+                let _ = this.counters.s2c_consecutive_pending_writes.fetch_update(
+                    Ordering::Relaxed,
+                    Ordering::Relaxed,
+                    |current| Some(current.saturating_add(1)),
+                );
+                Poll::Pending
+            }
+        }
+    }
+
+    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
+        Pin::new(&mut self.get_mut().inner).poll_flush(cx)
+    }
+
+    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/counters.rs

@@ -1,4 +1,4 @@
-use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
 use std::time::Duration;
 
 use tokio::time::Instant;
@@ -20,6 +20,12 @@ pub(in crate::proxy::relay) struct SharedCounters {
     pub(in crate::proxy::relay) c2s_ops: AtomicU64,
     /// Number of poll_write completions (≈ S→C chunks)
     pub(in crate::proxy::relay) s2c_ops: AtomicU64,
+    /// Bytes presented to client writes, including retried pending writes.
+    pub(in crate::proxy::relay) s2c_requested_bytes: AtomicU64,
+    /// Successful client writes that consumed only part of the offered slice.
+    pub(in crate::proxy::relay) s2c_partial_writes: AtomicU64,
+    /// Consecutive pending client writes observed by the active copy loop.
+    pub(in crate::proxy::relay) s2c_consecutive_pending_writes: AtomicU32,
     /// Milliseconds since relay epoch of last I/O activity
     last_activity_ms: AtomicU64,
 }
@@ -31,6 +37,9 @@ impl SharedCounters {
             s2c_bytes: AtomicU64::new(0),
             c2s_ops: AtomicU64::new(0),
             s2c_ops: AtomicU64::new(0),
+            s2c_requested_bytes: AtomicU64::new(0),
+            s2c_partial_writes: AtomicU64::new(0),
+            s2c_consecutive_pending_writes: AtomicU32::new(0),
             last_activity_ms: AtomicU64::new(0),
         }
     }

src/proxy/shared_state.rs

@@ -6,14 +6,16 @@ use std::sync::{Arc, Mutex};
 use std::time::Instant;
 
 use dashmap::DashMap;
-use tokio::sync::mpsc;
+use tokio::sync::{OwnedSemaphorePermit, Semaphore, mpsc};
 use tokio_util::sync::CancellationToken;
 
+use crate::proxy::direct_buffer_budget::{DirectBufferBudget, fallback_direct_buffer_hard_limit};
 use crate::proxy::handshake::{AuthProbeSaturationState, AuthProbeState};
 use crate::proxy::middle_relay::{DesyncDedupRotationState, RelayIdleCandidateRegistry};
 use crate::proxy::traffic_limiter::TrafficLimiter;
 
 const HANDSHAKE_RECENT_USER_RING_LEN: usize = 64;
+const MASKING_FALLBACK_MAX_CONCURRENT: usize = 512;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum ConntrackCloseReason {
@@ -68,10 +70,12 @@ pub(crate) struct ProxySharedState {
     pub(crate) handshake: HandshakeSharedState,
     pub(crate) middle_relay: MiddleRelaySharedState,
     pub(crate) traffic_limiter: Arc<TrafficLimiter>,
+    pub(crate) direct_buffer_budget: Arc<DirectBufferBudget>,
     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>>>,
+    masking_fallback_permits: Arc<Semaphore>,
 }
 
 #[must_use = "registered user sessions must be kept alive until relay completion"]
@@ -99,6 +103,15 @@ impl Drop for UserSessionGuard {
 
 impl ProxySharedState {
     pub(crate) fn new() -> Arc<Self> {
+        Self::new_with_direct_buffer_budget(DirectBufferBudget::new(
+            fallback_direct_buffer_hard_limit(),
+        ))
+    }
+
+    /// Creates process state with the startup-resolved Direct buffer envelope.
+    pub(crate) fn new_with_direct_buffer_budget(
+        direct_buffer_budget: Arc<DirectBufferBudget>,
+    ) -> Arc<Self> {
         Arc::new(Self {
             handshake: HandshakeSharedState {
                 auth_probe: DashMap::new(),
@@ -127,13 +140,23 @@ impl ProxySharedState {
                 relay_idle_mark_seq: AtomicU64::new(0),
             },
             traffic_limiter: TrafficLimiter::new(),
+            direct_buffer_budget,
             disabled_users: DashMap::new(),
             active_user_sessions: DashMap::new(),
             conntrack_pressure_active: AtomicBool::new(false),
             conntrack_close_tx: Mutex::new(None),
+            masking_fallback_permits: Arc::new(Semaphore::new(MASKING_FALLBACK_MAX_CONCURRENT)),
         })
     }
 
+    /// Attempts to reserve one masking fallback slot for a pre-auth connection.
+    pub(crate) fn try_acquire_masking_fallback_permit(&self) -> Option<OwnedSemaphorePermit> {
+        self.masking_fallback_permits
+            .clone()
+            .try_acquire_owned()
+            .ok()
+    }
+
     pub(crate) fn is_user_enabled(&self, user: &str) -> bool {
         !self.disabled_users.contains_key(user)
     }

src/proxy/tests/adaptive_direct_budget_policy_tests.rs

@@ -0,0 +1,58 @@
+use super::*;
+
+#[test]
+fn configured_direct_sizes_are_strict_tier_ceilings() {
+    let base = (4 * 1024, 8 * 1024);
+    let ceilings = (64 * 1024, 256 * 1024);
+    assert_eq!(
+        direct_copy_buffers_for_tier_with_ceilings(
+            AdaptiveTier::Base,
+            base.0,
+            base.1,
+            ceilings.0,
+            ceilings.1,
+        ),
+        base
+    );
+    assert_eq!(
+        direct_copy_buffers_for_tier_with_ceilings(
+            AdaptiveTier::Tier3,
+            base.0,
+            base.1,
+            ceilings.0,
+            ceilings.1,
+        ),
+        ceilings
+    );
+}
+
+#[test]
+fn sustained_pending_pressure_demotes_after_transient_promotion() {
+    let mut controller = SessionAdaptiveController::new(AdaptiveTier::Tier1);
+    let pressure = RelaySignalSample {
+        c2s_bytes: 0,
+        s2c_requested_bytes: 1024,
+        s2c_written_bytes: 0,
+        s2c_write_ops: 0,
+        s2c_partial_writes: 0,
+        s2c_consecutive_pending_writes: 3,
+    };
+
+    let first = controller
+        .observe(pressure, 10.0)
+        .expect("transient pressure must retain the staged promotion");
+    assert_eq!(first.reason, TierTransitionReason::HardPressure);
+
+    let second = controller
+        .observe(pressure, 10.0)
+        .expect("bounded transient pressure may promote one additional tier");
+    assert_eq!(second.reason, TierTransitionReason::HardPressure);
+    let sustained = controller
+        .observe(pressure, 10.0)
+        .expect("sustained pressure must release one tier");
+    assert_eq!(
+        sustained.reason,
+        TierTransitionReason::SustainedWritePressure
+    );
+    assert_eq!(sustained.to, AdaptiveTier::Tier2);
+}

src/proxy/tests/client_masking_blackhat_campaign_tests.rs

@@ -86,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;
@@ -183,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
@@ -435,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(
@@ -741,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

@@ -65,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;
@@ -240,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_hard_adversarial_tests.rs

@@ -80,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;
@@ -173,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
@@ -344,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(
@@ -419,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
@@ -676,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_prefetch_invariant_security_tests.rs

@@ -71,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;
@@ -250,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_redteam_expected_fail_tests.rs

@@ -77,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();
@@ -156,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

src/proxy/tests/client_masking_replay_timing_security_tests.rs

@@ -34,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;
@@ -119,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_stress_adversarial_tests.rs

@@ -80,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;
@@ -205,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;
@@ -1630,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;
@@ -1663,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]);
@@ -1674,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 {
@@ -2062,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
@@ -2188,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

src/proxy/tests/client_tls_mtproto_fallback_security_tests.rs

@@ -79,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;
@@ -191,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
@@ -261,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
@@ -335,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
@@ -403,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
@@ -481,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
@@ -586,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)
@@ -660,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();
     }
 
@@ -729,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();
     }
 
@@ -802,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());
@@ -884,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();
 
@@ -958,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)
@@ -1029,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
@@ -1090,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"
@@ -1170,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
@@ -1254,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(
@@ -1352,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() {
@@ -1433,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();
 
@@ -1533,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_buffer_budget_tests.rs

@@ -0,0 +1,38 @@
+use super::*;
+
+#[test]
+fn lease_drop_releases_the_complete_reservation() {
+    let budget = DirectBufferBudget::new(16 * 1024);
+    {
+        let lease = budget
+            .try_reserve(12 * 1024, false)
+            .expect("minimum reservation must fit");
+        assert_eq!(lease.reserved_bytes(), 12 * 1024);
+        assert_eq!(budget.snapshot().reserved_bytes, 12 * 1024);
+    }
+    assert_eq!(budget.snapshot().reserved_bytes, 0);
+}
+
+#[test]
+fn absolute_ceiling_rejects_excess_minimum_reservations() {
+    let budget = DirectBufferBudget::new(16 * 1024);
+    let _lease = budget
+        .try_reserve(12 * 1024, true)
+        .expect("first minimum reservation must fit");
+    assert!(budget.try_reserve(8 * 1024, true).is_none());
+    assert_eq!(budget.snapshot().reserved_bytes, 12 * 1024);
+}
+
+#[test]
+fn growth_and_shrink_keep_accounting_balanced() {
+    let budget = DirectBufferBudget::new(32 * 1024);
+    let mut lease = budget
+        .try_reserve(12 * 1024, false)
+        .expect("base reservation must fit");
+    assert!(lease.try_grow_to(24 * 1024));
+    assert_eq!(budget.snapshot().reserved_bytes, 24 * 1024);
+    lease.shrink_to(16 * 1024);
+    assert_eq!(budget.snapshot().reserved_bytes, 16 * 1024);
+    drop(lease);
+    assert_eq!(budget.snapshot().reserved_bytes, 0);
+}

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_additional_hardening_security_tests.rs

@@ -34,7 +34,7 @@ fn loop_guard_unspecified_bind_uses_interface_inventory() {
         "mask.example",
         443,
         local,
-        Some(resolved),
+        &[resolved],
         &interfaces,
     ));
 }

src/proxy/tests/masking_interface_cache_concurrency_security_tests.rs

@@ -25,7 +25,7 @@ async fn adversarial_parallel_cold_miss_performs_single_interface_refresh() {
         let barrier = std::sync::Arc::clone(&barrier);
         tasks.push(tokio::spawn(async move {
             barrier.wait().await;
-            is_mask_target_local_listener_async("127.0.0.1", 443, local_addr, None).await
+            is_mask_target_local_listener_async("127.0.0.1", 443, local_addr, &[]).await
         }));
     }
 

src/proxy/tests/masking_interface_cache_security_tests.rs

@@ -17,8 +17,8 @@ async fn tdd_repeated_local_listener_checks_do_not_repeat_interface_enumeration_
 
     let local_addr: SocketAddr = "0.0.0.0:443".parse().expect("valid local addr");
 
-    let _ = is_mask_target_local_listener_async("127.0.0.1", 443, local_addr, None).await;
-    let _ = is_mask_target_local_listener_async("127.0.0.1", 443, local_addr, None).await;
+    let _ = is_mask_target_local_listener_async("127.0.0.1", 443, local_addr, &[]).await;
+    let _ = is_mask_target_local_listener_async("127.0.0.1", 443, local_addr, &[]).await;
 
     assert_eq!(
         local_interface_enumerations_for_tests(),
@@ -35,7 +35,7 @@ async fn tdd_non_local_port_short_circuit_does_not_enumerate_interfaces() {
     reset_local_interface_enumerations_for_tests();
 
     let local_addr: SocketAddr = "0.0.0.0:443".parse().expect("valid local addr");
-    let is_local = is_mask_target_local_listener_async("127.0.0.1", 8443, local_addr, None).await;
+    let is_local = is_mask_target_local_listener_async("127.0.0.1", 8443, local_addr, &[]).await;
 
     assert!(
         !is_local,

src/proxy/tests/masking_relay_manual_perf_tests.rs

@@ -0,0 +1,111 @@
+use super::*;
+use std::pin::Pin;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::task::{Context, Poll};
+use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
+use tokio::time::{Duration, Instant};
+
+const PERF_TOTAL_BYTES: usize = 64 * 1024 * 1024;
+
+struct PatternReader {
+    remaining: usize,
+    chunk: usize,
+    read_calls: AtomicUsize,
+}
+
+impl PatternReader {
+    fn new(total: usize, chunk: usize) -> Self {
+        Self {
+            remaining: total,
+            chunk,
+            read_calls: AtomicUsize::new(0),
+        }
+    }
+
+    fn read_calls(&self) -> usize {
+        self.read_calls.load(Ordering::Relaxed)
+    }
+}
+
+impl AsyncRead for PatternReader {
+    fn poll_read(
+        mut self: Pin<&mut Self>,
+        _cx: &mut Context<'_>,
+        buf: &mut ReadBuf<'_>,
+    ) -> Poll<std::io::Result<()>> {
+        self.read_calls.fetch_add(1, Ordering::Relaxed);
+        if self.remaining == 0 {
+            return Poll::Ready(Ok(()));
+        }
+
+        let take = self.remaining.min(self.chunk).min(buf.remaining());
+        if take == 0 {
+            return Poll::Ready(Ok(()));
+        }
+
+        static PATTERN: [u8; MASK_BUFFER_MAX_SIZE] = [0xA5; MASK_BUFFER_MAX_SIZE];
+        buf.put_slice(&PATTERN[..take]);
+        self.remaining -= take;
+        Poll::Ready(Ok(()))
+    }
+}
+
+#[derive(Default)]
+struct CountingWriter {
+    written: usize,
+}
+
+impl AsyncWrite for CountingWriter {
+    fn poll_write(
+        mut self: Pin<&mut Self>,
+        _cx: &mut Context<'_>,
+        buf: &[u8],
+    ) -> Poll<std::io::Result<usize>> {
+        self.written = self.written.saturating_add(buf.len());
+        Poll::Ready(Ok(buf.len()))
+    }
+
+    fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
+        Poll::Ready(Ok(()))
+    }
+
+    fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
+        Poll::Ready(Ok(()))
+    }
+}
+
+#[tokio::test]
+#[ignore = "manual benchmark: throughput-sensitive and host-dependent"]
+async fn masking_copy_with_idle_timeout_manual_throughput() {
+    let mut reader = PatternReader::new(PERF_TOTAL_BYTES, MASK_BUFFER_MAX_SIZE);
+    let mut writer = CountingWriter::default();
+    let started = Instant::now();
+
+    let outcome = copy_with_idle_timeout(
+        &mut reader,
+        &mut writer,
+        PERF_TOTAL_BYTES,
+        true,
+        Duration::from_secs(30),
+    )
+    .await;
+
+    let elapsed = started.elapsed();
+    let mb = PERF_TOTAL_BYTES as f64 / (1024.0 * 1024.0);
+    let mbps = mb / elapsed.as_secs_f64();
+
+    assert_eq!(outcome.total, PERF_TOTAL_BYTES);
+    assert_eq!(writer.written, PERF_TOTAL_BYTES);
+    assert!(
+        !outcome.ended_by_eof,
+        "manual throughput run should terminate at byte cap"
+    );
+
+    eprintln!(
+        "masking manual throughput: bytes={} elapsed_ms={} mib_per_sec={:.2} read_calls={}",
+        PERF_TOTAL_BYTES,
+        elapsed.as_millis(),
+        mbps,
+        reader.read_calls()
+    );
+}

src/proxy/tests/masking_self_target_loop_security_tests.rs

@@ -15,38 +15,49 @@ fn closed_local_port() -> u16 {
 #[tokio::test]
 async fn self_target_detection_matches_literal_ipv4_listener() {
     let local: SocketAddr = "198.51.100.40:443".parse().unwrap();
-    assert!(is_mask_target_local_listener_async("198.51.100.40", 443, local, None,).await);
+    assert!(is_mask_target_local_listener_async("198.51.100.40", 443, local, &[],).await);
 }
 
 #[tokio::test]
 async fn self_target_detection_matches_bracketed_ipv6_listener() {
     let local: SocketAddr = "[2001:db8::44]:8443".parse().unwrap();
-    assert!(is_mask_target_local_listener_async("[2001:db8::44]", 8443, local, None,).await);
+    assert!(is_mask_target_local_listener_async("[2001:db8::44]", 8443, local, &[],).await);
 }
 
 #[tokio::test]
 async fn self_target_detection_keeps_same_ip_different_port_forwardable() {
     let local: SocketAddr = "203.0.113.44:443".parse().unwrap();
-    assert!(!is_mask_target_local_listener_async("203.0.113.44", 8443, local, None,).await);
+    assert!(!is_mask_target_local_listener_async("203.0.113.44", 8443, local, &[],).await);
 }
 
 #[tokio::test]
 async fn self_target_detection_normalizes_ipv4_mapped_ipv6_literal() {
     let local: SocketAddr = "127.0.0.1:443".parse().unwrap();
-    assert!(is_mask_target_local_listener_async("::ffff:127.0.0.1", 443, local, None,).await);
+    assert!(is_mask_target_local_listener_async("::ffff:127.0.0.1", 443, local, &[],).await);
 }
 
 #[tokio::test]
 async fn self_target_detection_unspecified_bind_blocks_loopback_target() {
     let local: SocketAddr = "0.0.0.0:443".parse().unwrap();
-    assert!(is_mask_target_local_listener_async("127.0.0.1", 443, local, None,).await);
+    assert!(is_mask_target_local_listener_async("127.0.0.1", 443, local, &[],).await);
 }
 
 #[tokio::test]
 async fn self_target_detection_unspecified_bind_keeps_remote_target_forwardable() {
     let local: SocketAddr = "0.0.0.0:443".parse().unwrap();
     let remote: SocketAddr = "198.51.100.44:443".parse().unwrap();
-    assert!(!is_mask_target_local_listener_async("mask.example", 443, local, Some(remote),).await);
+    assert!(!is_mask_target_local_listener_async("mask.example", 443, local, &[remote],).await);
+}
+
+#[tokio::test]
+async fn self_target_detection_checks_all_resolved_addresses() {
+    let local: SocketAddr = "127.0.0.1:443".parse().unwrap();
+    let remote: SocketAddr = "198.51.100.44:443".parse().unwrap();
+    let loopback: SocketAddr = "127.0.0.1:443".parse().unwrap();
+
+    assert!(
+        is_mask_target_local_listener_async("mask.example", 443, local, &[remote, loopback],).await
+    );
 }
 
 #[tokio::test]

src/proxy/tests/middle_relay_d2c_flush_padding_security_tests.rs

@@ -0,0 +1,150 @@
+use std::io;
+use std::pin::Pin;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex};
+use std::task::{Context, Poll};
+
+use tokio::io::AsyncWrite;
+
+use super::*;
+use crate::crypto::AesCtr;
+use crate::protocol::framing::INTERMEDIATE_WIRE_LEN_MASK;
+
+#[derive(Clone, Default)]
+struct RecordingWriter {
+    writes: Arc<Mutex<Vec<u8>>>,
+    flushes: Arc<AtomicUsize>,
+}
+
+impl RecordingWriter {
+    fn captured(&self) -> Vec<u8> {
+        self.writes
+            .lock()
+            .expect("test writer capture lock must not be poisoned")
+            .clone()
+    }
+}
+
+impl AsyncWrite for RecordingWriter {
+    fn poll_write(
+        self: Pin<&mut Self>,
+        _cx: &mut Context<'_>,
+        buf: &[u8],
+    ) -> Poll<io::Result<usize>> {
+        self.writes
+            .lock()
+            .expect("test writer capture lock must not be poisoned")
+            .extend_from_slice(buf);
+        Poll::Ready(Ok(buf.len()))
+    }
+
+    fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<io::Result<()>> {
+        self.flushes.fetch_add(1, Ordering::Relaxed);
+        Poll::Ready(Ok(()))
+    }
+
+    fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<io::Result<()>> {
+        Poll::Ready(Ok(()))
+    }
+}
+
+fn crypto_writer(inner: RecordingWriter) -> CryptoWriter<RecordingWriter> {
+    let key = [0u8; 32];
+    CryptoWriter::new(inner, AesCtr::new(&key, 0), 8 * 1024 * 1024)
+}
+
+fn decrypt_capture(mut encrypted: Vec<u8>) -> Vec<u8> {
+    let key = [0u8; 32];
+    let mut cipher = AesCtr::new(&key, 0);
+    cipher.apply(&mut encrypted);
+    encrypted
+}
+
+fn secure_wire_len(cleartext: &[u8]) -> usize {
+    let header = cleartext
+        .get(..4)
+        .expect("secure frame must include an intermediate header");
+    (u32::from_le_bytes(
+        header
+            .try_into()
+            .expect("secure frame header must be four bytes"),
+    ) & INTERMEDIATE_WIRE_LEN_MASK) as usize
+}
+
+async fn write_secure_payload(payload_len: usize) -> (MeD2cWriteMode, Vec<u8>) {
+    let inner = RecordingWriter::default();
+    let capture = inner.clone();
+    let mut writer = crypto_writer(inner);
+    let payload = vec![0xa5; payload_len];
+    let mut frame_buf = Vec::new();
+    let cancel = CancellationToken::new();
+    let rng = SecureRandom::new();
+
+    let mode = write_client_payload(
+        &mut writer,
+        ProtoTag::Secure,
+        0,
+        &payload,
+        &rng,
+        &mut frame_buf,
+        &cancel,
+    )
+    .await
+    .expect("secure payload write must succeed");
+    flush_client_or_cancel(&mut writer, &cancel)
+        .await
+        .expect("secure payload flush must succeed");
+
+    (mode, decrypt_capture(capture.captured()))
+}
+
+fn assert_secure_payload_with_tail_padding(cleartext: &[u8], payload_len: usize) {
+    let wire_len = secure_wire_len(cleartext);
+    assert_eq!(cleartext.len(), 4 + wire_len);
+    assert!(
+        cleartext[4..4 + payload_len]
+            .iter()
+            .all(|byte| *byte == 0xa5)
+    );
+
+    let padding_len = wire_len
+        .checked_sub(payload_len)
+        .expect("secure wire length must include payload bytes");
+    assert!((1..=3).contains(&padding_len));
+    assert_ne!(wire_len % 4, 0);
+}
+
+#[tokio::test]
+async fn queue_drain_flush_reason_performs_physical_client_flush() {
+    let inner = RecordingWriter::default();
+    let flushes = inner.flushes.clone();
+    let mut writer = crypto_writer(inner);
+    let cancel = CancellationToken::new();
+
+    assert!(me_d2c_flush_reason_requires_client_flush(
+        MeD2cFlushReason::QueueDrain
+    ));
+    flush_client_or_cancel(&mut writer, &cancel)
+        .await
+        .expect("client flush must succeed");
+
+    assert_eq!(flushes.load(Ordering::Relaxed), 1);
+}
+
+#[tokio::test]
+async fn secure_payload_coalesced_path_keeps_tail_padding() {
+    let payload_len = 8;
+    let (mode, cleartext) = write_secure_payload(payload_len).await;
+
+    assert!(matches!(mode, MeD2cWriteMode::Coalesced));
+    assert_secure_payload_with_tail_padding(&cleartext, payload_len);
+}
+
+#[tokio::test]
+async fn secure_payload_split_path_keeps_tail_padding() {
+    let payload_len = ME_D2C_SINGLE_WRITE_COALESCE_MAX_BYTES;
+    let (mode, cleartext) = write_secure_payload(payload_len).await;
+
+    assert!(matches!(mode, MeD2cWriteMode::Split));
+    assert_secure_payload_with_tail_padding(&cleartext, payload_len);
+}

src/proxy/traffic_limiter.rs

@@ -10,7 +10,7 @@ use arc_swap::ArcSwap;
 use dashmap::DashMap;
 use ipnetwork::IpNetwork;
 
-use crate::config::RateLimitBps;
+use crate::config::{CidrRateLimitKey, RateLimitBps};
 
 const REGISTRY_SHARDS: usize = 64;
 const FAIR_EPOCH_MS: u64 = 20;
@@ -413,16 +413,29 @@ struct CidrRule {
     prefix_len: u8,
 }
 
+#[derive(Clone, Copy)]
+struct CidrAutoRule {
+    prefix_len: u8,
+    limits: RateLimitBps,
+}
+
+enum CidrPolicyMatch<'a> {
+    Explicit(&'a CidrRule),
+    Auto { key: String, limits: RateLimitBps },
+}
+
 #[derive(Default)]
 struct PolicySnapshot {
     user_limits: HashMap<String, RateLimitBps>,
     cidr_rules_v4: Vec<CidrRule>,
     cidr_rules_v6: Vec<CidrRule>,
+    cidr_auto_rules_v4: Vec<CidrAutoRule>,
+    cidr_auto_rules_v6: Vec<CidrAutoRule>,
     cidr_rule_keys: HashSet<String>,
 }
 
 impl PolicySnapshot {
-    fn match_cidr(&self, ip: IpAddr) -> Option<&CidrRule> {
+    fn match_cidr(&self, ip: IpAddr) -> Option<CidrPolicyMatch<'_>> {
         match ip {
             IpAddr::V4(_) => self
                 .cidr_rules_v4
@@ -433,6 +446,20 @@ impl PolicySnapshot {
                 .iter()
                 .find(|rule| rule.cidr.contains(ip)),
         }
+        .map(CidrPolicyMatch::Explicit)
+        .or_else(|| self.match_auto_cidr(ip))
+    }
+
+    fn match_auto_cidr(&self, ip: IpAddr) -> Option<CidrPolicyMatch<'_>> {
+        let rule = match ip {
+            IpAddr::V4(_) => self.cidr_auto_rules_v4.first()?,
+            IpAddr::V6(_) => self.cidr_auto_rules_v6.first()?,
+        };
+        let key = auto_cidr_bucket_key(ip, rule.prefix_len)?;
+        Some(CidrPolicyMatch::Auto {
+            key,
+            limits: rule.limits,
+        })
     }
 }
 
@@ -633,7 +660,7 @@ impl TrafficLimiter {
     pub fn apply_policy(
         &self,
         user_limits: HashMap<String, RateLimitBps>,
-        cidr_limits: HashMap<IpNetwork, RateLimitBps>,
+        cidr_limits: HashMap<CidrRateLimitKey, RateLimitBps>,
     ) {
         let filtered_users = user_limits
             .into_iter()
@@ -642,39 +669,64 @@ impl TrafficLimiter {
 
         let mut cidr_rules_v4 = Vec::new();
         let mut cidr_rules_v6 = Vec::new();
+        let mut cidr_auto_rules_v4 = Vec::new();
+        let mut cidr_auto_rules_v6 = Vec::new();
         let mut cidr_rule_keys = HashSet::new();
-        for (cidr, limits) in cidr_limits {
+        for (key, limits) in cidr_limits {
             if limits.up_bps == 0 && limits.down_bps == 0 {
                 continue;
             }
-            let key = cidr.to_string();
-            let rule = CidrRule {
-                key: key.clone(),
-                cidr,
-                limits,
-                prefix_len: cidr.prefix(),
-            };
-            cidr_rule_keys.insert(key);
-            match rule.cidr {
-                IpNetwork::V4(_) => cidr_rules_v4.push(rule),
-                IpNetwork::V6(_) => cidr_rules_v6.push(rule),
+            match key {
+                CidrRateLimitKey::Network(cidr) => {
+                    let key = cidr.to_string();
+                    let rule = CidrRule {
+                        key: key.clone(),
+                        cidr,
+                        limits,
+                        prefix_len: cidr.prefix(),
+                    };
+                    cidr_rule_keys.insert(key);
+                    match rule.cidr {
+                        IpNetwork::V4(_) => cidr_rules_v4.push(rule),
+                        IpNetwork::V6(_) => cidr_rules_v6.push(rule),
+                    }
+                }
+                CidrRateLimitKey::AutoV4(prefix_len) => {
+                    cidr_auto_rules_v4.push(CidrAutoRule { prefix_len, limits });
+                }
+                CidrRateLimitKey::AutoV6(prefix_len) => {
+                    cidr_auto_rules_v6.push(CidrAutoRule { prefix_len, limits });
+                }
+                CidrRateLimitKey::AutoDual(prefix_len) => {
+                    cidr_auto_rules_v4.push(CidrAutoRule { prefix_len, limits });
+                    cidr_auto_rules_v6.push(CidrAutoRule {
+                        prefix_len: prefix_len.saturating_mul(4),
+                        limits,
+                    });
+                }
             }
         }
 
         cidr_rules_v4.sort_by(|a, b| b.prefix_len.cmp(&a.prefix_len));
         cidr_rules_v6.sort_by(|a, b| b.prefix_len.cmp(&a.prefix_len));
+        cidr_auto_rules_v4.sort_by(|a, b| b.prefix_len.cmp(&a.prefix_len));
+        cidr_auto_rules_v6.sort_by(|a, b| b.prefix_len.cmp(&a.prefix_len));
+        let cidr_policy_entries =
+            cidr_rule_keys.len() + cidr_auto_rules_v4.len() + cidr_auto_rules_v6.len();
 
         self.user_scope
             .policy_entries
             .store(filtered_users.len() as u64, Ordering::Relaxed);
         self.cidr_scope
             .policy_entries
-            .store(cidr_rule_keys.len() as u64, Ordering::Relaxed);
+            .store(cidr_policy_entries as u64, Ordering::Relaxed);
 
         self.policy.store(Arc::new(PolicySnapshot {
             user_limits: filtered_users,
             cidr_rules_v4,
             cidr_rules_v6,
+            cidr_auto_rules_v4,
+            cidr_auto_rules_v6,
             cidr_rule_keys,
         }));
 
@@ -703,11 +755,15 @@ impl TrafficLimiter {
         let mut cidr_bucket = None;
         let mut cidr_user_key = None;
         let mut cidr_user_share = None;
-        if let Some(rule) = policy.match_cidr(client_ip) {
+        if let Some(rule_match) = policy.match_cidr(client_ip) {
+            let (key, limits) = match &rule_match {
+                CidrPolicyMatch::Explicit(rule) => (rule.key.as_str(), rule.limits),
+                CidrPolicyMatch::Auto { key, limits } => (key.as_str(), *limits),
+            };
             let bucket = self
                 .cidr_buckets
-                .get_or_insert_with(rule.key.as_str(), || CidrBucket::new(rule.limits));
-            bucket.set_rates(rule.limits);
+                .get_or_insert_with(key, || CidrBucket::new(limits));
+            bucket.set_rates(limits);
             bucket.active_leases.fetch_add(1, Ordering::Relaxed);
             self.cidr_scope
                 .active_leases
@@ -841,6 +897,16 @@ fn bytes_per_epoch(bps: u64) -> u64 {
     bytes.max(1)
 }
 
+fn auto_cidr_bucket_key(ip: IpAddr, prefix_len: u8) -> Option<String> {
+    let cidr = IpNetwork::new(ip, prefix_len).ok()?;
+    let network = IpNetwork::new(cidr.network(), prefix_len).ok()?;
+    let family = match network {
+        IpNetwork::V4(_) => "4",
+        IpNetwork::V6(_) => "6",
+    };
+    Some(format!("auto:{family}:{network}"))
+}
+
 fn current_epoch() -> u64 {
     let start = limiter_epoch_start();
     let elapsed_ms = start.elapsed().as_millis() as u64;
@@ -851,3 +917,82 @@ fn limiter_epoch_start() -> &'static Instant {
     static START: OnceLock<Instant> = OnceLock::new();
     START.get_or_init(Instant::now)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn rate(up_bps: u64, down_bps: u64) -> RateLimitBps {
+        RateLimitBps { up_bps, down_bps }
+    }
+
+    #[test]
+    fn explicit_cidr_rule_wins_over_auto_template() {
+        let limiter = TrafficLimiter::new();
+        let mut cidr_limits = HashMap::new();
+        cidr_limits.insert(CidrRateLimitKey::AutoV4(24), rate(1_000, 0));
+        cidr_limits.insert(
+            CidrRateLimitKey::Network("203.0.113.7/32".parse().unwrap()),
+            rate(2_000, 0),
+        );
+
+        limiter.apply_policy(HashMap::new(), cidr_limits);
+        let policy = limiter.policy.load_full();
+        let matched = policy.match_cidr("203.0.113.7".parse().unwrap()).unwrap();
+
+        match matched {
+            CidrPolicyMatch::Explicit(rule) => assert_eq!(rule.key.as_str(), "203.0.113.7/32"),
+            CidrPolicyMatch::Auto { .. } => panic!("explicit CIDR must have priority"),
+        }
+    }
+
+    #[test]
+    fn auto_template_uses_longest_prefix() {
+        let limiter = TrafficLimiter::new();
+        let mut cidr_limits = HashMap::new();
+        cidr_limits.insert(CidrRateLimitKey::AutoV4(24), rate(1_000, 0));
+        cidr_limits.insert(CidrRateLimitKey::AutoV4(32), rate(2_000, 0));
+
+        limiter.apply_policy(HashMap::new(), cidr_limits);
+        let policy = limiter.policy.load_full();
+        let matched = policy.match_cidr("203.0.113.129".parse().unwrap()).unwrap();
+
+        match matched {
+            CidrPolicyMatch::Auto { key, limits } => {
+                assert_eq!(key, "auto:4:203.0.113.129/32");
+                assert_eq!(limits.up_bps, 2_000);
+            }
+            CidrPolicyMatch::Explicit(_) => panic!("auto-template match expected"),
+        }
+    }
+
+    #[test]
+    fn dual_auto_template_maps_v6_prefix_by_four() {
+        let limiter = TrafficLimiter::new();
+        let mut cidr_limits = HashMap::new();
+        cidr_limits.insert(CidrRateLimitKey::AutoDual(32), rate(1_000, 0));
+
+        limiter.apply_policy(HashMap::new(), cidr_limits);
+        let policy = limiter.policy.load_full();
+        let matched = policy.match_cidr("2001:db8::1".parse().unwrap()).unwrap();
+
+        match matched {
+            CidrPolicyMatch::Auto { key, .. } => {
+                assert_eq!(key, "auto:6:2001:db8::1/128");
+            }
+            CidrPolicyMatch::Explicit(_) => panic!("auto-template match expected"),
+        }
+    }
+
+    #[test]
+    fn auto_cidr_bucket_key_canonicalizes_network_address() {
+        assert_eq!(
+            auto_cidr_bucket_key("203.0.113.129".parse().unwrap(), 24).unwrap(),
+            "auto:4:203.0.113.0/24"
+        );
+        assert_eq!(
+            auto_cidr_bucket_key("2001:db8::abcd".parse().unwrap(), 64).unwrap(),
+            "auto:6:2001:db8::/64"
+        );
+    }
+}

src/stats/me_getters.rs

@@ -204,6 +204,12 @@ impl Stats {
         self.buffer_pool_in_use_gauge.load(Ordering::Relaxed)
     }
 
+    /// Returns the count of non-standard buffers replaced before pooling.
+    pub fn get_buffer_pool_replaced_nonstandard_total(&self) -> u64 {
+        self.buffer_pool_replaced_nonstandard_total
+            .load(Ordering::Relaxed)
+    }
+
     pub fn get_me_c2me_send_full_total(&self) -> u64 {
         self.me_c2me_send_full_total.load(Ordering::Relaxed)
     }
@@ -269,6 +275,36 @@ impl Stats {
         self.me_writer_pick_mode_switch_total
             .load(Ordering::Relaxed)
     }
+    /// Returns the configured resident-memory limit per ME writer.
+    pub fn get_me_writer_byte_budget_limit_bytes_gauge(&self) -> u64 {
+        self.me_writer_byte_budget_limit_bytes_gauge
+            .load(Ordering::Relaxed)
+    }
+    /// Returns aggregate queued or enqueueing writer memory reservations.
+    pub fn get_me_writer_byte_budget_queued_bytes_gauge(&self) -> u64 {
+        self.me_writer_byte_budget_queued_bytes_gauge
+            .load(Ordering::Relaxed)
+    }
+    /// Returns aggregate writer reservations currently owned by socket writes.
+    pub fn get_me_writer_byte_budget_inflight_bytes_gauge(&self) -> u64 {
+        self.me_writer_byte_budget_inflight_bytes_gauge
+            .load(Ordering::Relaxed)
+    }
+    /// Returns the count of blocking writer byte-budget waits.
+    pub fn get_me_writer_byte_budget_wait_total(&self) -> u64 {
+        self.me_writer_byte_budget_wait_total
+            .load(Ordering::Relaxed)
+    }
+    /// Returns the count of writer byte-budget wait timeouts.
+    pub fn get_me_writer_byte_budget_timeout_total(&self) -> u64 {
+        self.me_writer_byte_budget_timeout_total
+            .load(Ordering::Relaxed)
+    }
+    /// Returns the count of payloads that cannot fit the configured writer budget.
+    pub fn get_me_writer_byte_budget_oversize_total(&self) -> u64 {
+        self.me_writer_byte_budget_oversize_total
+            .load(Ordering::Relaxed)
+    }
     pub fn get_me_socks_kdf_strict_reject(&self) -> u64 {
         self.me_socks_kdf_strict_reject.load(Ordering::Relaxed)
     }

src/stats/mod.rs

@@ -274,6 +274,7 @@ pub struct Stats {
     buffer_pool_pooled_gauge: AtomicU64,
     buffer_pool_allocated_gauge: AtomicU64,
     buffer_pool_in_use_gauge: AtomicU64,
+    buffer_pool_replaced_nonstandard_total: AtomicU64,
     // C2ME enqueue observability
     me_c2me_send_full_total: AtomicU64,
     me_c2me_send_high_water_total: AtomicU64,
@@ -292,6 +293,12 @@ pub struct Stats {
     me_writer_pick_p2c_no_candidate_total: AtomicU64,
     me_writer_pick_blocking_fallback_total: AtomicU64,
     me_writer_pick_mode_switch_total: AtomicU64,
+    me_writer_byte_budget_limit_bytes_gauge: AtomicU64,
+    me_writer_byte_budget_queued_bytes_gauge: AtomicU64,
+    me_writer_byte_budget_inflight_bytes_gauge: AtomicU64,
+    me_writer_byte_budget_wait_total: AtomicU64,
+    me_writer_byte_budget_timeout_total: AtomicU64,
+    me_writer_byte_budget_oversize_total: AtomicU64,
     me_socks_kdf_strict_reject: AtomicU64,
     me_socks_kdf_compat_fallback: AtomicU64,
     secure_padding_invalid: AtomicU64,

src/stats/writer_counters.rs

@@ -88,6 +88,56 @@ impl Stats {
                 .fetch_add(1, Ordering::Relaxed);
         }
     }
+    /// Publishes the configured resident-memory limit applied to each ME writer.
+    pub fn set_me_writer_byte_budget_limit_bytes(&self, bytes: usize) {
+        self.me_writer_byte_budget_limit_bytes_gauge
+            .store(bytes as u64, Ordering::Relaxed);
+    }
+    pub(crate) fn add_me_writer_byte_budget_queued_bytes(&self, bytes: u64) {
+        self.me_writer_byte_budget_queued_bytes_gauge
+            .fetch_add(bytes, Ordering::Relaxed);
+    }
+    pub(crate) fn move_me_writer_byte_budget_to_inflight(&self, bytes: u64) {
+        let _ = self.me_writer_byte_budget_queued_bytes_gauge.fetch_update(
+            Ordering::Relaxed,
+            Ordering::Relaxed,
+            |current| Some(current.saturating_sub(bytes)),
+        );
+        self.me_writer_byte_budget_inflight_bytes_gauge
+            .fetch_add(bytes, Ordering::Relaxed);
+    }
+    pub(crate) fn release_me_writer_byte_budget_queued_bytes(&self, bytes: u64) {
+        let _ = self.me_writer_byte_budget_queued_bytes_gauge.fetch_update(
+            Ordering::Relaxed,
+            Ordering::Relaxed,
+            |current| Some(current.saturating_sub(bytes)),
+        );
+    }
+    pub(crate) fn release_me_writer_byte_budget_inflight_bytes(&self, bytes: u64) {
+        let _ = self
+            .me_writer_byte_budget_inflight_bytes_gauge
+            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
+                Some(current.saturating_sub(bytes))
+            });
+    }
+    pub(crate) fn increment_me_writer_byte_budget_wait_total(&self) {
+        if self.telemetry_me_allows_normal() {
+            self.me_writer_byte_budget_wait_total
+                .fetch_add(1, Ordering::Relaxed);
+        }
+    }
+    pub(crate) fn increment_me_writer_byte_budget_timeout_total(&self) {
+        if self.telemetry_me_allows_normal() {
+            self.me_writer_byte_budget_timeout_total
+                .fetch_add(1, Ordering::Relaxed);
+        }
+    }
+    pub(crate) fn increment_me_writer_byte_budget_oversize_total(&self) {
+        if self.telemetry_me_allows_normal() {
+            self.me_writer_byte_budget_oversize_total
+                .fetch_add(1, Ordering::Relaxed);
+        }
+    }
     pub fn increment_me_socks_kdf_strict_reject(&self) {
         if self.telemetry_me_allows_normal() {
             self.me_socks_kdf_strict_reject
@@ -502,6 +552,14 @@ impl Stats {
         }
     }
 
+    /// Publishes the cumulative count of non-standard pool buffer replacements.
+    pub fn set_buffer_pool_replaced_nonstandard_total(&self, value: usize) {
+        if self.telemetry_me_allows_normal() {
+            self.buffer_pool_replaced_nonstandard_total
+                .store(value as u64, Ordering::Relaxed);
+        }
+    }
+
     pub fn increment_me_c2me_send_full_total(&self) {
         if self.telemetry_me_allows_normal() {
             self.me_c2me_send_full_total.fetch_add(1, Ordering::Relaxed);

src/stream/crypto_stream.rs

@@ -68,8 +68,8 @@ use crate::crypto::AesCtr;
 /// Actual limit is supplied at runtime from configuration.
 const DEFAULT_MAX_PENDING_WRITE: usize = 64 * 1024;
 
-/// Default read buffer capacity (reader mostly decrypts in-place into caller buffer).
-const DEFAULT_READ_CAPACITY: usize = 16 * 1024;
+/// Maximum scratch capacity retained after a completed write.
+const MAX_RETAINED_SCRATCH_CAPACITY: usize = 32 * 1024;
 
 // ============= CryptoReader State =============
 
@@ -110,10 +110,6 @@ pub struct CryptoReader<R> {
     upstream: R,
     decryptor: AesCtr,
     state: CryptoReaderState,
-
-    /// Reserved for future coalescing optimizations.
-    #[allow(dead_code)]
-    read_buf: BytesMut,
 }
 
 impl<R> CryptoReader<R> {
@@ -122,7 +118,6 @@ impl<R> CryptoReader<R> {
             upstream,
             decryptor,
             state: CryptoReaderState::Idle,
-            read_buf: BytesMut::with_capacity(DEFAULT_READ_CAPACITY),
         }
     }
 
@@ -321,7 +316,7 @@ struct PendingCiphertext {
 impl PendingCiphertext {
     fn new(max_len: usize) -> Self {
         Self {
-            buf: BytesMut::with_capacity(16 * 1024),
+            buf: BytesMut::new(),
             pos: 0,
             max_len,
         }
@@ -372,15 +367,12 @@ impl PendingCiphertext {
         }
     }
 
-    /// Replace the entire pending ciphertext by moving `src` in (swap, no copy).
-    fn replace_with(&mut self, mut src: BytesMut) {
+    /// Replace the entire pending ciphertext by moving `src` in without copying.
+    fn replace_with(&mut self, src: BytesMut) {
         debug_assert!(src.len() <= self.max_len);
 
-        self.buf.clear();
+        self.buf = src;
         self.pos = 0;
-
-        // Swap: keep allocations hot and avoid copying bytes.
-        std::mem::swap(&mut self.buf, &mut src);
     }
 
     /// Append plaintext and encrypt appended range in-place.
@@ -465,7 +457,7 @@ impl<W> CryptoWriter<W> {
             upstream,
             encryptor,
             state: CryptoWriterState::Idle,
-            scratch: BytesMut::with_capacity(16 * 1024),
+            scratch: BytesMut::new(),
             max_pending_write: max_pending.max(4 * 1024),
         }
     }
@@ -502,6 +494,7 @@ impl<W> CryptoWriter<W> {
     }
 
     fn poison(&mut self, error: io::Error) {
+        self.scratch = BytesMut::new();
         self.state = CryptoWriterState::Poisoned { error: Some(error) };
     }
 
@@ -552,6 +545,15 @@ impl<W> CryptoWriter<W> {
         scratch.extend_from_slice(plaintext);
         encryptor.apply(&mut scratch[..]);
     }
+
+    /// Clear reusable scratch while releasing allocations inflated by large writes.
+    fn recycle_scratch(scratch: &mut BytesMut) {
+        if scratch.capacity() > MAX_RETAINED_SCRATCH_CAPACITY {
+            *scratch = BytesMut::new();
+        } else {
+            scratch.clear();
+        }
+    }
 }
 
 impl<W: AsyncWrite + Unpin> CryptoWriter<W> {
@@ -698,13 +700,13 @@ impl<W: AsyncWrite + Unpin> AsyncWrite for CryptoWriter<W> {
 
             Poll::Ready(Ok(n)) => {
                 if n == this.scratch.len() {
-                    this.scratch.clear();
+                    Self::recycle_scratch(&mut this.scratch);
                     return Poll::Ready(Ok(to_accept));
                 }
 
                 // Partial upstream write of ciphertext
-                let remainder = this.scratch.split_off(n);
-                this.scratch.clear();
+                let mut remainder = std::mem::take(&mut this.scratch);
+                let _ = remainder.split_to(n);
 
                 let pending = Self::ensure_pending(&mut this.state, this.max_pending_write);
                 pending.replace_with(remainder);

src/stream/frame_codec.rs

@@ -15,6 +15,7 @@ use crate::crypto::SecureRandom;
 use crate::protocol::constants::{
     ProtoTag, is_valid_secure_payload_len, secure_padding_len, secure_payload_len_from_wire_len,
 };
+use crate::protocol::framing::{encode_intermediate_header, parse_intermediate_header};
 
 // ============= Unified Codec =============
 
@@ -197,13 +198,9 @@ fn decode_intermediate(src: &mut BytesMut, max_size: usize) -> io::Result<Option
     }
 
     let mut meta = FrameMeta::new();
-    let mut len = u32::from_le_bytes([src[0], src[1], src[2], src[3]]) as usize;
-
-    // Check QuickACK flag
-    if len >= 0x80000000 {
-        meta.quickack = true;
-        len -= 0x80000000;
-    }
+    let header = parse_intermediate_header([src[0], src[1], src[2], src[3]]);
+    let len = header.wire_len;
+    meta.quickack = header.quickack;
 
     // Validate size
     if len > max_size {
@@ -239,10 +236,12 @@ fn encode_intermediate(frame: &Frame, dst: &mut BytesMut) -> io::Result<()> {
 
     dst.reserve(4 + data.len());
 
-    let mut len = data.len() as u32;
-    if frame.meta.quickack {
-        len |= 0x80000000;
-    }
+    let len = encode_intermediate_header(data.len(), frame.meta.quickack).ok_or_else(|| {
+        Error::new(
+            ErrorKind::InvalidInput,
+            format!("frame too large: {} bytes", data.len()),
+        )
+    })?;
 
     dst.extend_from_slice(&len.to_le_bytes());
     dst.extend_from_slice(data);
@@ -258,13 +257,9 @@ fn decode_secure(src: &mut BytesMut, max_size: usize) -> io::Result<Option<Frame
     }
 
     let mut meta = FrameMeta::new();
-    let mut len = u32::from_le_bytes([src[0], src[1], src[2], src[3]]) as usize;
-
-    // Check QuickACK flag
-    if len >= 0x80000000 {
-        meta.quickack = true;
-        len -= 0x80000000;
-    }
+    let header = parse_intermediate_header([src[0], src[1], src[2], src[3]]);
+    let len = header.wire_len;
+    meta.quickack = header.quickack;
 
     // Validate size
     if len > max_size {
@@ -317,16 +312,18 @@ fn encode_secure(frame: &Frame, dst: &mut BytesMut, rng: &SecureRandom) -> io::R
         ));
     }
 
-    // Generate padding that keeps total length non-divisible by 4.
+    // Outbound Secure padding avoids full-word tails that readers cannot strip.
     let padding_len = secure_padding_len(data.len(), rng);
 
     let total_len = data.len() + padding_len;
     dst.reserve(4 + total_len);
 
-    let mut len = total_len as u32;
-    if frame.meta.quickack {
-        len |= 0x80000000;
-    }
+    let len = encode_intermediate_header(total_len, frame.meta.quickack).ok_or_else(|| {
+        Error::new(
+            ErrorKind::InvalidInput,
+            format!("frame too large: {} bytes", total_len),
+        )
+    })?;
 
     dst.extend_from_slice(&len.to_le_bytes());
     dst.extend_from_slice(data);
@@ -523,6 +520,10 @@ mod tests {
     use tokio::io::duplex;
     use tokio_util::codec::{FramedRead, FramedWrite};
 
+    fn assert_secure_decoded_payload(decoded: &[u8], original: &[u8]) {
+        assert_eq!(decoded, original);
+    }
+
     #[tokio::test]
     async fn test_framed_abridged() {
         let (client, server) = duplex(4096);
@@ -565,7 +566,7 @@ mod tests {
         writer.send(frame).await.unwrap();
 
         let received = reader.next().await.unwrap().unwrap();
-        assert_eq!(&received.data[..], &original[..]);
+        assert_secure_decoded_payload(&received.data, &original);
     }
 
     #[tokio::test]
@@ -588,7 +589,11 @@ mod tests {
             writer.send(frame).await.unwrap();
 
             let received = reader.next().await.unwrap().unwrap();
-            assert_eq!(received.data.len(), 8);
+            if proto_tag == ProtoTag::Secure {
+                assert_secure_decoded_payload(&received.data, &original);
+            } else {
+                assert_eq!(received.data.len(), original.len());
+            }
         }
     }
 
@@ -642,7 +647,7 @@ mod tests {
     }
 
     #[test]
-    fn secure_codec_always_adds_padding_and_jitters_wire_length() {
+    fn secure_codec_uses_non_aligned_padding_and_jitters_wire_length() {
         let codec = SecureCodec::new(Arc::new(SecureRandom::new()));
         let payload = Bytes::from_static(&[1, 2, 3, 4, 5, 6, 7, 8]);
         let mut wire_lens = HashSet::new();
@@ -652,13 +657,13 @@ mod tests {
             let mut out = BytesMut::new();
             codec.encode(&frame, &mut out).unwrap();
 
-            assert!(out.len() > 4 + payload.len());
             let wire_len = u32::from_le_bytes([out[0], out[1], out[2], out[3]]) as usize;
+            assert_eq!(out.len(), 4 + wire_len);
             assert!(
                 (payload.len() + 1..=payload.len() + 3).contains(&wire_len),
                 "Secure wire length must be payload+1..3, got {wire_len}"
             );
-            assert_ne!(wire_len % 4, 0, "Secure wire length must be non-4-aligned");
+            assert_ne!(wire_len % 4, 0);
             wire_lens.insert(wire_len);
         }
 

src/stream/frame_stream.rs

@@ -5,21 +5,47 @@
 use super::traits::{FrameMeta, LayeredStream};
 use crate::crypto::{SecureRandom, crc32};
 use crate::protocol::constants::*;
+use crate::protocol::framing::{encode_intermediate_header, parse_intermediate_header};
 use bytes::Bytes;
 use std::io::{Error, ErrorKind, Result};
 use std::sync::Arc;
 use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
 
+const DEFAULT_MAX_FRAME_SIZE: usize = 16 * 1024 * 1024;
+
+fn reject_oversize_frame(len: usize, max_frame_size: usize, protocol: &str) -> Result<()> {
+    if len > max_frame_size {
+        return Err(Error::new(
+            ErrorKind::InvalidData,
+            format!("{protocol} frame too large: {len} bytes (max {max_frame_size})"),
+        ));
+    }
+
+    Ok(())
+}
+
 // ============= Abridged (Compact) Frame =============
 
 /// Reader for abridged MTProto framing
 pub struct AbridgedFrameReader<R> {
     upstream: R,
+    max_frame_size: usize,
 }
 
 impl<R> AbridgedFrameReader<R> {
+    /// Creates a reader with the default maximum frame size.
     pub fn new(upstream: R) -> Self {
-        Self { upstream }
+        Self {
+            upstream,
+            max_frame_size: DEFAULT_MAX_FRAME_SIZE,
+        }
+    }
+
+    fn with_max_frame_size(upstream: R, max_frame_size: usize) -> Self {
+        Self {
+            upstream,
+            max_frame_size,
+        }
     }
 }
 
@@ -47,10 +73,12 @@ impl<R: AsyncRead + Unpin> AbridgedFrameReader<R> {
             len = u32::from_le_bytes([len_bytes[0], len_bytes[1], len_bytes[2], 0]) as usize;
         }
 
-        // Length is in 4-byte words
-        let byte_len = len * 4;
+        // Length is in 4-byte words.
+        let byte_len = len
+            .checked_mul(4)
+            .ok_or_else(|| Error::new(ErrorKind::InvalidData, "abridged frame length overflow"))?;
+        reject_oversize_frame(byte_len, self.max_frame_size, "abridged")?;
 
-        // Read data
         let mut data = vec![0u8; byte_len];
         self.upstream.read_exact(&mut data).await?;
 
@@ -105,10 +133,17 @@ impl<W: AsyncWrite + Unpin> AbridgedFrameWriter<W> {
 
         if len_div_4 < 0x7f {
             // Short length (1 byte)
-            self.upstream.write_all(&[len_div_4 as u8]).await?;
+            let mut first = len_div_4 as u8;
+            if meta.quickack {
+                first |= 0x80;
+            }
+            self.upstream.write_all(&[first]).await?;
         } else if len_div_4 < (1 << 24) {
             // Long length (4 bytes: 0x7f + 3 bytes)
             let mut header = [0x7f, 0, 0, 0];
+            if meta.quickack {
+                header[0] |= 0x80;
+            }
             header[1..4].copy_from_slice(&(len_div_4 as u32).to_le_bytes()[..3]);
             self.upstream.write_all(&header).await?;
         } else {
@@ -144,11 +179,23 @@ impl<W> LayeredStream<W> for AbridgedFrameWriter<W> {
 /// Reader for intermediate MTProto framing
 pub struct IntermediateFrameReader<R> {
     upstream: R,
+    max_frame_size: usize,
 }
 
 impl<R> IntermediateFrameReader<R> {
+    /// Creates a reader with the default maximum frame size.
     pub fn new(upstream: R) -> Self {
-        Self { upstream }
+        Self {
+            upstream,
+            max_frame_size: DEFAULT_MAX_FRAME_SIZE,
+        }
+    }
+
+    fn with_max_frame_size(upstream: R, max_frame_size: usize) -> Self {
+        Self {
+            upstream,
+            max_frame_size,
+        }
     }
 }
 
@@ -160,15 +207,11 @@ impl<R: AsyncRead + Unpin> IntermediateFrameReader<R> {
         let mut len_bytes = [0u8; 4];
         self.upstream.read_exact(&mut len_bytes).await?;
 
-        let mut len = u32::from_le_bytes(len_bytes) as usize;
+        let header = parse_intermediate_header(len_bytes);
+        let len = header.wire_len;
+        meta.quickack = header.quickack;
+        reject_oversize_frame(len, self.max_frame_size, "intermediate")?;
 
-        // Check QuickACK flag (high bit)
-        if len > 0x80000000 {
-            meta.quickack = true;
-            len -= 0x80000000;
-        }
-
-        // Read data
         let mut data = vec![0u8; len];
         self.upstream.read_exact(&mut data).await?;
 
@@ -204,7 +247,13 @@ impl<W: AsyncWrite + Unpin> IntermediateFrameWriter<W> {
         if meta.simple_ack {
             self.upstream.write_all(data).await?;
         } else {
-            let len_bytes = (data.len() as u32).to_le_bytes();
+            let len = encode_intermediate_header(data.len(), meta.quickack).ok_or_else(|| {
+                Error::new(
+                    ErrorKind::InvalidInput,
+                    format!("Frame too large: {} bytes", data.len()),
+                )
+            })?;
+            let len_bytes = len.to_le_bytes();
             self.upstream.write_all(&len_bytes).await?;
             self.upstream.write_all(data).await?;
         }
@@ -233,11 +282,23 @@ impl<W> LayeredStream<W> for IntermediateFrameWriter<W> {
 /// Reader for secure intermediate MTProto framing (with padding)
 pub struct SecureIntermediateFrameReader<R> {
     upstream: R,
+    max_frame_size: usize,
 }
 
 impl<R> SecureIntermediateFrameReader<R> {
+    /// Creates a reader with the default maximum frame size.
     pub fn new(upstream: R) -> Self {
-        Self { upstream }
+        Self {
+            upstream,
+            max_frame_size: DEFAULT_MAX_FRAME_SIZE,
+        }
+    }
+
+    fn with_max_frame_size(upstream: R, max_frame_size: usize) -> Self {
+        Self {
+            upstream,
+            max_frame_size,
+        }
     }
 }
 
@@ -249,24 +310,19 @@ impl<R: AsyncRead + Unpin> SecureIntermediateFrameReader<R> {
         let mut len_bytes = [0u8; 4];
         self.upstream.read_exact(&mut len_bytes).await?;
 
-        let mut len = u32::from_le_bytes(len_bytes) as usize;
-
-        // Check QuickACK flag
-        if len > 0x80000000 {
-            meta.quickack = true;
-            len -= 0x80000000;
-        }
-
-        // Read data (including padding)
-        let mut data = vec![0u8; len];
-        self.upstream.read_exact(&mut data).await?;
-
+        let header = parse_intermediate_header(len_bytes);
+        let len = header.wire_len;
+        meta.quickack = header.quickack;
+        reject_oversize_frame(len, self.max_frame_size, "secure intermediate")?;
         let payload_len = secure_payload_len_from_wire_len(len).ok_or_else(|| {
             Error::new(
                 ErrorKind::InvalidData,
                 format!("Invalid secure frame length: {len}"),
             )
         })?;
+
+        let mut data = vec![0u8; len];
+        self.upstream.read_exact(&mut data).await?;
         data.truncate(payload_len);
 
         Ok((Bytes::from(data), meta))
@@ -311,12 +367,21 @@ impl<W: AsyncWrite + Unpin> SecureIntermediateFrameWriter<W> {
             ));
         }
 
-        // Add padding so total length is never divisible by 4 (MTProto Secure)
+        // Outbound Secure padding avoids full-word tails that readers cannot strip.
         let padding_len = secure_padding_len(data.len(), &self.rng);
         let padding = self.rng.bytes(padding_len);
 
-        let total_len = data.len() + padding_len;
-        let len_bytes = (total_len as u32).to_le_bytes();
+        let total_len = data
+            .len()
+            .checked_add(padding_len)
+            .ok_or_else(|| Error::new(ErrorKind::InvalidInput, "secure frame length overflow"))?;
+        let len = encode_intermediate_header(total_len, meta.quickack).ok_or_else(|| {
+            Error::new(
+                ErrorKind::InvalidInput,
+                format!("Frame too large: {total_len} bytes"),
+            )
+        })?;
+        let len_bytes = len.to_le_bytes();
 
         self.upstream.write_all(&len_bytes).await?;
         self.upstream.write_all(data).await?;
@@ -495,15 +560,22 @@ pub enum FrameReaderKind<R> {
 }
 
 impl<R: AsyncRead + Unpin> FrameReaderKind<R> {
+    /// Creates a frame reader with the default maximum frame size.
     pub fn new(upstream: R, proto_tag: ProtoTag) -> Self {
+        Self::with_max_frame_size(upstream, proto_tag, DEFAULT_MAX_FRAME_SIZE)
+    }
+
+    fn with_max_frame_size(upstream: R, proto_tag: ProtoTag, max_frame_size: usize) -> Self {
         match proto_tag {
-            ProtoTag::Abridged => FrameReaderKind::Abridged(AbridgedFrameReader::new(upstream)),
-            ProtoTag::Intermediate => {
-                FrameReaderKind::Intermediate(IntermediateFrameReader::new(upstream))
-            }
-            ProtoTag::Secure => {
-                FrameReaderKind::SecureIntermediate(SecureIntermediateFrameReader::new(upstream))
-            }
+            ProtoTag::Abridged => FrameReaderKind::Abridged(
+                AbridgedFrameReader::with_max_frame_size(upstream, max_frame_size),
+            ),
+            ProtoTag::Intermediate => FrameReaderKind::Intermediate(
+                IntermediateFrameReader::with_max_frame_size(upstream, max_frame_size),
+            ),
+            ProtoTag::Secure => FrameReaderKind::SecureIntermediate(
+                SecureIntermediateFrameReader::with_max_frame_size(upstream, max_frame_size),
+            ),
         }
     }
 
@@ -557,7 +629,12 @@ mod tests {
     use super::*;
     use crate::crypto::SecureRandom;
     use std::sync::Arc;
-    use tokio::io::duplex;
+    use tokio::io::{AsyncWriteExt, duplex};
+    use tokio::time::{Duration, timeout};
+
+    fn assert_secure_decoded_payload(decoded: &[u8], original: &[u8]) {
+        assert_eq!(decoded, original);
+    }
 
     #[tokio::test]
     async fn test_abridged_roundtrip() {
@@ -613,6 +690,92 @@ mod tests {
         assert_eq!(&received[..], &data[..]);
     }
 
+    #[tokio::test]
+    async fn test_intermediate_quickack_zero_length_roundtrip() {
+        let (client, server) = duplex(1024);
+
+        let mut writer = IntermediateFrameWriter::new(client);
+        let mut reader = IntermediateFrameReader::new(server);
+
+        writer
+            .write_frame(&[], &FrameMeta::new().with_quickack())
+            .await
+            .unwrap();
+        writer.flush().await.unwrap();
+
+        let (received, meta) = reader.read_frame().await.unwrap();
+        assert!(received.is_empty());
+        assert!(meta.quickack);
+    }
+
+    #[tokio::test]
+    async fn test_abridged_quickack_roundtrip() {
+        let (client, server) = duplex(1024);
+
+        let mut writer = AbridgedFrameWriter::new(client);
+        let mut reader = AbridgedFrameReader::new(server);
+
+        let data = vec![1u8, 2, 3, 4];
+        writer
+            .write_frame(&data, &FrameMeta::new().with_quickack())
+            .await
+            .unwrap();
+        writer.flush().await.unwrap();
+
+        let (received, meta) = reader.read_frame().await.unwrap();
+        assert_eq!(&received[..], &data[..]);
+        assert!(meta.quickack);
+    }
+
+    #[tokio::test]
+    async fn abridged_reader_rejects_oversize_frame_before_body_read() {
+        let (mut client, server) = duplex(1024);
+        let mut reader = AbridgedFrameReader::new(server);
+        let len_words = (DEFAULT_MAX_FRAME_SIZE / 4) + 1;
+        let encoded = (len_words as u32).to_le_bytes();
+
+        client
+            .write_all(&[0x7f, encoded[0], encoded[1], encoded[2]])
+            .await
+            .unwrap();
+        let err = timeout(Duration::from_millis(50), reader.read_frame())
+            .await
+            .unwrap()
+            .unwrap_err();
+
+        assert_eq!(err.kind(), ErrorKind::InvalidData);
+    }
+
+    #[tokio::test]
+    async fn intermediate_reader_rejects_oversize_frame_before_body_read() {
+        let (mut client, server) = duplex(1024);
+        let mut reader = IntermediateFrameReader::new(server);
+        let len = encode_intermediate_header(DEFAULT_MAX_FRAME_SIZE + 1, false).unwrap();
+
+        client.write_all(&len.to_le_bytes()).await.unwrap();
+        let err = timeout(Duration::from_millis(50), reader.read_frame())
+            .await
+            .unwrap()
+            .unwrap_err();
+
+        assert_eq!(err.kind(), ErrorKind::InvalidData);
+    }
+
+    #[tokio::test]
+    async fn secure_reader_rejects_oversize_frame_before_body_read() {
+        let (mut client, server) = duplex(1024);
+        let mut reader = SecureIntermediateFrameReader::new(server);
+        let len = encode_intermediate_header(DEFAULT_MAX_FRAME_SIZE + 4, false).unwrap();
+
+        client.write_all(&len.to_le_bytes()).await.unwrap();
+        let err = timeout(Duration::from_millis(50), reader.read_frame())
+            .await
+            .unwrap()
+            .unwrap_err();
+
+        assert_eq!(err.kind(), ErrorKind::InvalidData);
+    }
+
     #[tokio::test]
     async fn test_secure_intermediate_padding() {
         let (client, server) = duplex(1024);
@@ -625,7 +788,7 @@ mod tests {
         writer.flush().await.unwrap();
 
         let (received, _meta) = reader.read_frame().await.unwrap();
-        assert_eq!(received.len(), data.len());
+        assert_secure_decoded_payload(&received, &data);
     }
 
     #[tokio::test]

src/stream/tls_stream.rs

@@ -40,7 +40,7 @@ use std::pin::Pin;
 use std::task::{Context, Poll};
 use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt, ReadBuf};
 
-use super::state::{HeaderBuffer, StreamState, WriteBuffer, YieldBuffer};
+use super::state::{HeaderBuffer, StreamState, YieldBuffer};
 use crate::protocol::constants::{
     MAX_TLS_CIPHERTEXT_SIZE, MAX_TLS_PLAINTEXT_SIZE, TLS_RECORD_ALERT, TLS_RECORD_APPLICATION,
     TLS_RECORD_CHANGE_CIPHER, TLS_RECORD_HANDSHAKE, TLS_VERSION,
@@ -59,6 +59,9 @@ const MAX_TLS_PAYLOAD: usize = MAX_TLS_CIPHERTEXT_SIZE;
 /// Note: we never queue unlimited amount of data here; state holds at most one record.
 const MAX_PENDING_WRITE: usize = 64 * 1024;
 
+/// Maximum record buffer capacity retained between writes.
+const MAX_RETAINED_RECORD_CAPACITY: usize = 2 * (TLS_HEADER_SIZE + MAX_TLS_PAYLOAD);
+
 // ============= TLS Record Types =============
 
 /// Parsed TLS record header (5 bytes)
@@ -639,7 +642,7 @@ enum TlsWriterState {
 
     /// Writing a complete TLS record (header + body), possibly partially
     WritingRecord {
-        record: WriteBuffer,
+        position: usize,
         payload_size: usize,
     },
 
@@ -676,6 +679,7 @@ impl StreamState for TlsWriterState {
 pub struct FakeTlsWriter<W> {
     upstream: W,
     state: TlsWriterState,
+    record_buffer: BytesMut,
 }
 
 impl<W> FakeTlsWriter<W> {
@@ -683,6 +687,7 @@ impl<W> FakeTlsWriter<W> {
         Self {
             upstream,
             state: TlsWriterState::Idle,
+            record_buffer: BytesMut::new(),
         }
     }
 
@@ -704,10 +709,15 @@ impl<W> FakeTlsWriter<W> {
     }
 
     pub fn has_pending(&self) -> bool {
-        matches!(&self.state, TlsWriterState::WritingRecord { record, .. } if !record.is_empty())
+        matches!(
+            &self.state,
+            TlsWriterState::WritingRecord { position, .. }
+                if *position < self.record_buffer.len()
+        )
     }
 
     fn poison(&mut self, error: io::Error) {
+        self.record_buffer = BytesMut::new();
         self.state = TlsWriterState::Poisoned { error: Some(error) };
     }
 
@@ -720,17 +730,26 @@ impl<W> FakeTlsWriter<W> {
         }
     }
 
-    fn build_record(data: &[u8]) -> BytesMut {
+    fn build_record(&mut self, data: &[u8]) {
         let header = TlsRecordHeader {
             record_type: TLS_RECORD_APPLICATION,
             version: TLS_VERSION,
             length: data.len() as u16,
         };
 
-        let mut record = BytesMut::with_capacity(TLS_HEADER_SIZE + data.len());
-        record.extend_from_slice(&header.to_bytes());
-        record.extend_from_slice(data);
-        record
+        self.record_buffer.clear();
+        self.record_buffer.reserve(TLS_HEADER_SIZE + data.len());
+        self.record_buffer.extend_from_slice(&header.to_bytes());
+        self.record_buffer.extend_from_slice(data);
+        debug_assert!(self.record_buffer.len() <= MAX_PENDING_WRITE);
+    }
+
+    fn recycle_record_buffer(&mut self) {
+        if self.record_buffer.capacity() > MAX_RETAINED_RECORD_CAPACITY {
+            self.record_buffer = BytesMut::new();
+        } else {
+            self.record_buffer.clear();
+        }
     }
 }
 
@@ -744,10 +763,11 @@ impl<W: AsyncWrite + Unpin> FakeTlsWriter<W> {
     fn poll_flush_record_inner(
         upstream: &mut W,
         cx: &mut Context<'_>,
-        record: &mut WriteBuffer,
+        record: &[u8],
+        position: &mut usize,
     ) -> FlushResult {
-        while !record.is_empty() {
-            let data = record.pending();
+        while *position < record.len() {
+            let data = &record[*position..];
             match Pin::new(&mut *upstream).poll_write(cx, data) {
                 Poll::Pending => return FlushResult::Pending,
                 Poll::Ready(Err(e)) => return FlushResult::Error(e),
@@ -757,7 +777,7 @@ impl<W: AsyncWrite + Unpin> FakeTlsWriter<W> {
                         "upstream returned 0 bytes written",
                     ));
                 }
-                Poll::Ready(Ok(n)) => record.advance(n),
+                Poll::Ready(Ok(n)) => *position += n,
             }
         }
 
@@ -780,14 +800,19 @@ impl<W: AsyncWrite + Unpin> AsyncWrite for FakeTlsWriter<W> {
             }
 
             TlsWriterState::WritingRecord {
-                mut record,
+                mut position,
                 payload_size,
             } => {
                 // Finish writing previous record before accepting new bytes.
-                match Self::poll_flush_record_inner(&mut this.upstream, cx, &mut record) {
+                match Self::poll_flush_record_inner(
+                    &mut this.upstream,
+                    cx,
+                    &this.record_buffer,
+                    &mut position,
+                ) {
                     FlushResult::Pending => {
                         this.state = TlsWriterState::WritingRecord {
-                            record,
+                            position,
                             payload_size,
                         };
                         return Poll::Pending;
@@ -797,6 +822,7 @@ impl<W: AsyncWrite + Unpin> AsyncWrite for FakeTlsWriter<W> {
                         return Poll::Ready(Err(e));
                     }
                     FlushResult::Complete(_) => {
+                        this.recycle_record_buffer();
                         this.state = TlsWriterState::Idle;
                         // continue to accept new buf below
                     }
@@ -818,19 +844,17 @@ impl<W: AsyncWrite + Unpin> AsyncWrite for FakeTlsWriter<W> {
         let chunk = &buf[..chunk_size];
 
         // Build the complete record (header + payload)
-        let record_data = Self::build_record(chunk);
+        this.build_record(chunk);
 
-        match Pin::new(&mut this.upstream).poll_write(cx, &record_data) {
-            Poll::Ready(Ok(n)) if n == record_data.len() => Poll::Ready(Ok(chunk_size)),
+        match Pin::new(&mut this.upstream).poll_write(cx, &this.record_buffer) {
+            Poll::Ready(Ok(n)) if n == this.record_buffer.len() => {
+                this.recycle_record_buffer();
+                Poll::Ready(Ok(chunk_size))
+            }
 
             Poll::Ready(Ok(n)) => {
-                // Partial write of the record: store remainder.
-                let mut write_buffer = WriteBuffer::with_max_size(MAX_PENDING_WRITE);
-                // record_data length is <= 16389, fits MAX_PENDING_WRITE
-                let _ = write_buffer.extend(&record_data[n..]);
-
                 this.state = TlsWriterState::WritingRecord {
-                    record: write_buffer,
+                    position: n,
                     payload_size: chunk_size,
                 };
 
@@ -844,12 +868,8 @@ impl<W: AsyncWrite + Unpin> AsyncWrite for FakeTlsWriter<W> {
             }
 
             Poll::Pending => {
-                // Buffer entire record and report success for this chunk.
-                let mut write_buffer = WriteBuffer::with_max_size(MAX_PENDING_WRITE);
-                let _ = write_buffer.extend(&record_data);
-
                 this.state = TlsWriterState::WritingRecord {
-                    record: write_buffer,
+                    position: 0,
                     payload_size: chunk_size,
                 };
 
@@ -871,12 +891,17 @@ impl<W: AsyncWrite + Unpin> AsyncWrite for FakeTlsWriter<W> {
             }
 
             TlsWriterState::WritingRecord {
-                mut record,
+                mut position,
                 payload_size,
-            } => match Self::poll_flush_record_inner(&mut this.upstream, cx, &mut record) {
+            } => match Self::poll_flush_record_inner(
+                &mut this.upstream,
+                cx,
+                &this.record_buffer,
+                &mut position,
+            ) {
                 FlushResult::Pending => {
                     this.state = TlsWriterState::WritingRecord {
-                        record,
+                        position,
                         payload_size,
                     };
                     return Poll::Pending;
@@ -886,6 +911,7 @@ impl<W: AsyncWrite + Unpin> AsyncWrite for FakeTlsWriter<W> {
                     return Poll::Ready(Err(e));
                 }
                 FlushResult::Complete(_) => {
+                    this.recycle_record_buffer();
                     this.state = TlsWriterState::Idle;
                 }
             },
@@ -905,11 +931,17 @@ impl<W: AsyncWrite + Unpin> AsyncWrite for FakeTlsWriter<W> {
 
         match state {
             TlsWriterState::WritingRecord {
-                mut record,
+                mut position,
                 payload_size: _,
             } => {
                 // Best-effort flush (do not block shutdown forever).
-                let _ = Self::poll_flush_record_inner(&mut this.upstream, cx, &mut record);
+                let _ = Self::poll_flush_record_inner(
+                    &mut this.upstream,
+                    cx,
+                    &this.record_buffer,
+                    &mut position,
+                );
+                this.recycle_record_buffer();
                 this.state = TlsWriterState::Idle;
             }
             _ => {

src/synlimit_control/command.rs

@@ -0,0 +1,98 @@
+use std::path::PathBuf;
+
+use tokio::io::AsyncWriteExt;
+use tokio::process::Command;
+
+pub(super) async fn run_command(
+    binary: &str,
+    args: &[&str],
+    stdin: Option<String>,
+) -> Result<(), String> {
+    let Some(command_path) = resolve_command(binary) else {
+        return Err(format!("{binary} is not available"));
+    };
+    let mut command = Command::new(command_path);
+    command.args(args);
+    if stdin.is_some() {
+        command.stdin(std::process::Stdio::piped());
+    }
+    command.stdout(std::process::Stdio::null());
+    command.stderr(std::process::Stdio::piped());
+    let mut child = command
+        .spawn()
+        .map_err(|e| format!("spawn {binary} failed: {e}"))?;
+    if let Some(blob) = stdin
+        && let Some(mut writer) = child.stdin.take()
+    {
+        writer
+            .write_all(blob.as_bytes())
+            .await
+            .map_err(|e| format!("stdin write {binary} failed: {e}"))?;
+    }
+    let output = child
+        .wait_with_output()
+        .await
+        .map_err(|e| format!("wait {binary} failed: {e}"))?;
+    if output.status.success() {
+        return Ok(());
+    }
+    let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
+    Err(if stderr.is_empty() {
+        format!("{binary} exited with status {}", output.status)
+    } else {
+        stderr
+    })
+}
+
+pub(super) async fn run_command_stdout(binary: &str, args: &[&str]) -> Result<String, String> {
+    let Some(command_path) = resolve_command(binary) else {
+        return Err(format!("{binary} is not available"));
+    };
+    let output = Command::new(command_path)
+        .args(args)
+        .output()
+        .await
+        .map_err(|e| format!("wait {binary} failed: {e}"))?;
+    if output.status.success() {
+        return Ok(String::from_utf8_lossy(&output.stdout).to_string());
+    }
+    let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
+    Err(if stderr.is_empty() {
+        format!("{binary} exited with status {}", output.status)
+    } else {
+        stderr
+    })
+}
+
+fn resolve_command(binary: &str) -> Option<PathBuf> {
+    let mut dirs = std::env::var_os("PATH")
+        .map(|path| std::env::split_paths(&path).collect::<Vec<_>>())
+        .unwrap_or_default();
+    dirs.extend(["/usr/sbin", "/sbin", "/usr/bin", "/bin"].map(PathBuf::from));
+    dirs.into_iter()
+        .map(|dir| dir.join(binary))
+        .find(|candidate| candidate.exists() && candidate.is_file())
+}
+
+pub(super) fn has_cap_net_admin() -> bool {
+    #[cfg(target_os = "linux")]
+    {
+        let Ok(status) = std::fs::read_to_string("/proc/self/status") else {
+            return false;
+        };
+        for line in status.lines() {
+            if let Some(raw) = line.strip_prefix("CapEff:") {
+                let caps = raw.trim();
+                if let Ok(bits) = u64::from_str_radix(caps, 16) {
+                    const CAP_NET_ADMIN_BIT: u64 = 12;
+                    return (bits & (1u64 << CAP_NET_ADMIN_BIT)) != 0;
+                }
+            }
+        }
+        false
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        false
+    }
+}

src/synlimit_control/iptables.rs

@@ -0,0 +1,389 @@
+use std::net::IpAddr;
+
+use super::command::run_command;
+use super::model::{SynLimitNamespace, SynLimitRule, SynLimitTargets, synlimit_rate_arg};
+
+const IPV4_IOS_PACKET_LENGTH: u16 = 64;
+const IPV6_IOS_PACKET_LENGTH: u16 = 84;
+const IOS_TTL_LIMIT: u8 = 65;
+
+#[derive(Clone, Copy)]
+enum IpTablesFamily {
+    V4,
+    V6,
+}
+
+impl IpTablesFamily {
+    fn ios_packet_length(self) -> u16 {
+        match self {
+            Self::V4 => IPV4_IOS_PACKET_LENGTH,
+            Self::V6 => IPV6_IOS_PACKET_LENGTH,
+        }
+    }
+
+    fn ttl_match(self) -> [&'static str; 3] {
+        match self {
+            Self::V4 => ["-m", "ttl", "--ttl-lt"],
+            Self::V6 => ["-m", "hl", "--hl-lt"],
+        }
+    }
+
+    fn hashlimit_tag(self) -> &'static str {
+        match self {
+            Self::V4 => "4",
+            Self::V6 => "6",
+        }
+    }
+}
+
+pub(super) async fn apply_synlimit_rules(
+    targets: &SynLimitTargets,
+    namespace: &SynLimitNamespace,
+) -> Result<(), String> {
+    apply_rules_for_binary(
+        "iptables",
+        &targets.iptables_v4,
+        IpTablesFamily::V4,
+        namespace,
+    )
+    .await?;
+    apply_rules_for_binary(
+        "ip6tables",
+        &targets.iptables_v6,
+        IpTablesFamily::V6,
+        namespace,
+    )
+    .await
+}
+
+async fn apply_rules_for_binary(
+    binary: &str,
+    targets: &[SynLimitRule],
+    family: IpTablesFamily,
+    namespace: &SynLimitNamespace,
+) -> Result<(), String> {
+    if targets.is_empty() {
+        return Ok(());
+    }
+    let chain = namespace.iptables_chain.as_str();
+    let _ = run_command(binary, &["-t", "filter", "-N", chain], None).await;
+    run_command(binary, &["-t", "filter", "-F", chain], None).await?;
+    if run_command(binary, &["-t", "filter", "-C", "INPUT", "-j", chain], None)
+        .await
+        .is_err()
+    {
+        run_command(
+            binary,
+            &["-t", "filter", "-I", "INPUT", "1", "-j", chain],
+            None,
+        )
+        .await?;
+    }
+
+    for (idx, target) in targets.iter().enumerate() {
+        for rule in iptables_synfix_rule_args(target, idx, family, namespace) {
+            let refs: Vec<&str> = rule.iter().map(String::as_str).collect();
+            run_command(binary, &refs, None).await?;
+        }
+    }
+    run_command(binary, &["-t", "filter", "-A", chain, "-j", "RETURN"], None).await?;
+
+    Ok(())
+}
+
+fn iptables_synfix_rule_args(
+    target: &SynLimitRule,
+    idx: usize,
+    family: IpTablesFamily,
+    namespace: &SynLimitNamespace,
+) -> Vec<Vec<String>> {
+    vec![
+        iptables_ios_accept_rule_args(target, idx, family, namespace),
+        iptables_ios_reject_rule_args(target, family, namespace),
+        iptables_generic_accept_rule_args(target, idx, family, namespace),
+        iptables_generic_reject_rule_args(target, namespace),
+    ]
+}
+
+fn iptables_ios_accept_rule_args(
+    target: &SynLimitRule,
+    idx: usize,
+    family: IpTablesFamily,
+    namespace: &SynLimitNamespace,
+) -> Vec<String> {
+    let hashlimit_name = format!(
+        "{}-I{}-{idx}",
+        namespace.iptables_hashlimit_prefix,
+        family.hashlimit_tag()
+    );
+    let mut args =
+        iptables_base_rule_args(namespace.iptables_chain.as_str(), target.ip, target.port);
+    args.extend(iptables_ios_match_args(family));
+    args.extend(iptables_hashlimit_args(
+        &hashlimit_name,
+        target.ios_seconds,
+        target.ios_hitcount,
+        target.ios_burst,
+        target.hashlimit_expire_ms,
+        target.hashlimit_size,
+    ));
+    args.extend(["-j".to_string(), "ACCEPT".to_string()]);
+    args
+}
+
+fn iptables_ios_reject_rule_args(
+    target: &SynLimitRule,
+    family: IpTablesFamily,
+    namespace: &SynLimitNamespace,
+) -> Vec<String> {
+    let mut args =
+        iptables_base_rule_args(namespace.iptables_chain.as_str(), target.ip, target.port);
+    args.extend(iptables_ios_match_args(family));
+    args.extend(iptables_reject_args());
+    args
+}
+
+fn iptables_generic_accept_rule_args(
+    target: &SynLimitRule,
+    idx: usize,
+    family: IpTablesFamily,
+    namespace: &SynLimitNamespace,
+) -> Vec<String> {
+    let hashlimit_name = format!(
+        "{}-G{}-{idx}",
+        namespace.iptables_hashlimit_prefix,
+        family.hashlimit_tag()
+    );
+    let mut args =
+        iptables_base_rule_args(namespace.iptables_chain.as_str(), target.ip, target.port);
+    args.extend(iptables_hashlimit_args(
+        &hashlimit_name,
+        target.generic_seconds,
+        target.generic_hitcount,
+        target.generic_burst,
+        target.hashlimit_expire_ms,
+        target.hashlimit_size,
+    ));
+    args.extend(["-j".to_string(), "ACCEPT".to_string()]);
+    args
+}
+
+fn iptables_generic_reject_rule_args(
+    target: &SynLimitRule,
+    namespace: &SynLimitNamespace,
+) -> Vec<String> {
+    let mut args =
+        iptables_base_rule_args(namespace.iptables_chain.as_str(), target.ip, target.port);
+    args.extend(iptables_reject_args());
+    args
+}
+
+fn iptables_base_rule_args(chain: &str, ip: Option<IpAddr>, port: u16) -> Vec<String> {
+    let mut args = vec![
+        "-t".to_string(),
+        "filter".to_string(),
+        "-A".to_string(),
+        chain.to_string(),
+        "-p".to_string(),
+        "tcp".to_string(),
+        "--syn".to_string(),
+        "-m".to_string(),
+        "tcp".to_string(),
+        "--tcp-flags".to_string(),
+        "SYN".to_string(),
+        "SYN".to_string(),
+    ];
+    if let Some(ip) = ip {
+        args.push("-d".to_string());
+        args.push(ip.to_string());
+    }
+    args.extend(["--dport".to_string(), port.to_string()]);
+    args
+}
+
+fn iptables_ios_match_args(family: IpTablesFamily) -> Vec<String> {
+    let mut args = vec![
+        "-m".to_string(),
+        "length".to_string(),
+        "--length".to_string(),
+        family.ios_packet_length().to_string(),
+    ];
+    args.extend(family.ttl_match().map(str::to_string));
+    args.push(IOS_TTL_LIMIT.to_string());
+    args
+}
+
+fn iptables_hashlimit_args(
+    name: &str,
+    seconds: u32,
+    hitcount: u32,
+    burst: u32,
+    expire_ms: u32,
+    size: u32,
+) -> Vec<String> {
+    vec![
+        "-m".to_string(),
+        "hashlimit".to_string(),
+        "--hashlimit-name".to_string(),
+        name.to_string(),
+        "--hashlimit-mode".to_string(),
+        "srcip".to_string(),
+        "--hashlimit-upto".to_string(),
+        synlimit_rate_arg(seconds, hitcount),
+        "--hashlimit-burst".to_string(),
+        burst.to_string(),
+        "--hashlimit-htable-expire".to_string(),
+        expire_ms.to_string(),
+        "--hashlimit-htable-size".to_string(),
+        size.to_string(),
+    ]
+}
+
+fn iptables_reject_args() -> Vec<String> {
+    vec![
+        "-j".to_string(),
+        "REJECT".to_string(),
+        "--reject-with".to_string(),
+        "tcp-reset".to_string(),
+    ]
+}
+
+pub(super) async fn clear_rules_for_binary(
+    binary: &str,
+    namespace: &SynLimitNamespace,
+) -> Result<bool, String> {
+    let mut errors = Vec::new();
+    let mut removed = false;
+    let chain = namespace.iptables_chain.as_str();
+    for _ in 0..8 {
+        match run_command(binary, &["-t", "filter", "-D", "INPUT", "-j", chain], None).await {
+            Ok(()) => {
+                removed = true;
+            }
+            Err(error) if is_missing_command_or_iptables_rule(&error) => break,
+            Err(error) => {
+                errors.push(format!("{binary} delete INPUT jump failed: {error}"));
+                break;
+            }
+        }
+    }
+    match run_command(binary, &["-t", "filter", "-F", chain], None).await {
+        Ok(()) => {
+            removed = true;
+        }
+        Err(error) if is_missing_command_or_iptables_rule(&error) => {}
+        Err(error) => {
+            errors.push(format!("{binary} flush chain failed: {error}"));
+        }
+    }
+    match run_command(binary, &["-t", "filter", "-X", chain], None).await {
+        Ok(()) => {
+            removed = true;
+        }
+        Err(error) if is_missing_command_or_iptables_rule(&error) => {}
+        Err(error) => {
+            errors.push(format!("{binary} delete chain failed: {error}"));
+        }
+    }
+
+    if errors.is_empty() {
+        Ok(removed)
+    } else {
+        Err(errors.join(", "))
+    }
+}
+
+fn is_missing_command_or_iptables_rule(error: &str) -> bool {
+    error.contains("is not available")
+        || error.contains("No chain/target/match by that name")
+        || error.contains("does not exist")
+        || error.contains("Couldn't load target")
+}
+
+#[cfg(test)]
+mod tests {
+    use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+
+    use super::*;
+    use crate::synlimit_control::model::test_rule;
+
+    fn has_pair(args: &[String], key: &str, value: &str) -> bool {
+        args.windows(2)
+            .any(|pair| pair[0].as_str() == key && pair[1].as_str() == value)
+    }
+
+    fn has_key(args: &[String], key: &str) -> bool {
+        args.iter().any(|arg| arg == key)
+    }
+
+    fn test_namespace() -> SynLimitNamespace {
+        SynLimitNamespace {
+            nft_table: "telemt_synlimit_test".to_string(),
+            iptables_chain: "TMT_SYN_TEST".to_string(),
+            iptables_hashlimit_prefix: "TMTTEST".to_string(),
+        }
+    }
+
+    #[test]
+    fn iptables_rules_use_synfix_order_and_rejects() {
+        let target = test_rule(Some(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 7))), 443);
+        let namespace = test_namespace();
+        let rules = iptables_synfix_rule_args(&target, 0, IpTablesFamily::V4, &namespace);
+
+        assert_eq!(rules.len(), 4);
+        assert!(has_pair(&rules[0], "-A", "TMT_SYN_TEST"));
+        assert!(has_pair(&rules[0], "--length", "64"));
+        assert!(has_pair(&rules[0], "--ttl-lt", "65"));
+        assert!(has_pair(&rules[0], "--hashlimit-upto", "12/second"));
+        assert!(has_pair(&rules[0], "--hashlimit-burst", "24"));
+        assert!(has_pair(&rules[0], "--hashlimit-htable-expire", "60000"));
+        assert!(has_pair(&rules[0], "--hashlimit-htable-size", "32768"));
+        assert!(has_pair(&rules[0], "-j", "ACCEPT"));
+        assert!(has_pair(&rules[1], "-j", "REJECT"));
+        assert!(has_pair(&rules[1], "--reject-with", "tcp-reset"));
+        assert!(has_pair(&rules[2], "--hashlimit-upto", "48/minute"));
+        assert!(has_pair(&rules[3], "--reject-with", "tcp-reset"));
+    }
+
+    #[test]
+    fn ip6tables_rules_use_ipv6_hoplimit_classifier() {
+        let target = test_rule(Some(IpAddr::V6(Ipv6Addr::LOCALHOST)), 443);
+        let namespace = test_namespace();
+        let rules = iptables_synfix_rule_args(&target, 0, IpTablesFamily::V6, &namespace);
+
+        assert!(has_pair(&rules[0], "--length", "84"));
+        assert!(has_pair(&rules[0], "--hl-lt", "65"));
+        assert!(has_pair(&rules[0], "-d", "::1"));
+    }
+
+    #[test]
+    fn iptables_missing_rule_errors_are_cleanup_benign() {
+        assert!(is_missing_command_or_iptables_rule(
+            "iptables is not available"
+        ));
+        assert!(is_missing_command_or_iptables_rule(
+            "iptables: No chain/target/match by that name."
+        ));
+        assert!(is_missing_command_or_iptables_rule(
+            "iptables: Chain TELEMT_SYNLIMIT does not exist."
+        ));
+        assert!(is_missing_command_or_iptables_rule(
+            "Couldn't load target `TELEMT_SYNLIMIT': No such file or directory"
+        ));
+        assert!(!is_missing_command_or_iptables_rule(
+            "iptables: Permission denied"
+        ));
+    }
+
+    #[test]
+    fn iptables_wildcard_rule_omits_destination_match() {
+        let target = test_rule(None, 443);
+        let namespace = test_namespace();
+        let rules = iptables_synfix_rule_args(&target, 0, IpTablesFamily::V4, &namespace);
+
+        for rule in rules {
+            assert!(!has_key(&rule, "-d"));
+            assert!(has_pair(&rule, "--dport", "443"));
+        }
+    }
+}

src/synlimit_control/mod.rs

@@ -0,0 +1,170 @@
+use std::sync::{Arc, Mutex};
+
+use tokio::sync::watch;
+use tracing::warn;
+
+use crate::config::{ProxyConfig, SynLimitMode};
+
+mod command;
+mod iptables;
+mod model;
+mod nftables;
+
+use self::command::has_cap_net_admin;
+use self::model::{SynLimitNamespace, synlimit_namespace, synlimit_targets};
+
+static ACTIVE_SYNLIMIT_NAMESPACE: Mutex<Option<SynLimitNamespace>> = Mutex::new(None);
+
+pub(crate) fn spawn_synlimit_controller(config_rx: watch::Receiver<Arc<ProxyConfig>>) {
+    if !cfg!(target_os = "linux") {
+        if has_synlimit_config(&config_rx.borrow()) {
+            warn!("SYN limiter is configured but unsupported on this OS; skipping netfilter rules");
+        }
+        return;
+    }
+
+    tokio::spawn(async move {
+        wait_for_config_channel_close_and_reconcile(config_rx).await;
+        if let Err(error) = clear_synlimit_rules_all_backends().await {
+            warn!(error = %error, "Failed to clear SYN limiter rules after config channel close");
+        }
+    });
+}
+
+async fn wait_for_config_channel_close_and_reconcile(
+    mut config_rx: watch::Receiver<Arc<ProxyConfig>>,
+) {
+    while config_rx.changed().await.is_ok() {
+        let cfg = config_rx.borrow_and_update().clone();
+        reconcile_synlimit_rules(&cfg).await;
+    }
+}
+
+pub(crate) async fn reconcile_synlimit_rules(cfg: &ProxyConfig) {
+    let targets = synlimit_targets(cfg);
+    let namespace = synlimit_namespace(&targets);
+    if let Some(previous_namespace) = set_active_synlimit_namespace(namespace.clone()) {
+        match clear_synlimit_rules_for_namespace(&previous_namespace).await {
+            Ok(true) => {
+                warn!("Removed previous SYN limiter namespace before reconcile");
+            }
+            Ok(false) => {}
+            Err(error) => {
+                warn!(error = %error, "Failed to clear previous SYN limiter namespace before reconcile");
+            }
+        }
+    }
+
+    if targets.is_empty() {
+        return;
+    }
+    let Some(namespace) = namespace else {
+        return;
+    };
+    if !has_cap_net_admin() {
+        warn!(
+            "SYN limiter configured but CAP_NET_ADMIN is not available; netfilter rules not applied"
+        );
+        return;
+    }
+
+    match clear_synlimit_rules_for_namespace(&namespace).await {
+        Ok(true) => {
+            warn!("Removed stale SYN limiter rules left by a previous run before reconcile");
+        }
+        Ok(false) => {}
+        Err(error) => {
+            warn!(error = %error, "Failed to clear stale SYN limiter rules before reconcile");
+        }
+    }
+
+    if targets.has_iptables_targets()
+        && let Err(error) = iptables::apply_synlimit_rules(&targets, &namespace).await
+    {
+        warn!(error = %error, "Failed to apply iptables SYN limiter rules");
+    }
+    if targets.has_nft_targets()
+        && let Err(error) = nftables::apply_synlimit_rules(&targets, &namespace).await
+    {
+        warn!(error = %error, "Failed to apply nftables SYN limiter rules");
+    }
+}
+
+pub(crate) async fn clear_synlimit_rules_all_backends() -> Result<bool, String> {
+    let Some(namespace) = take_active_synlimit_namespace() else {
+        return Ok(false);
+    };
+    clear_synlimit_rules_for_namespace(&namespace).await
+}
+
+async fn clear_synlimit_rules_for_namespace(namespace: &SynLimitNamespace) -> Result<bool, String> {
+    if !has_cap_net_admin() {
+        return Ok(false);
+    }
+
+    let mut errors = Vec::new();
+    let mut removed = false;
+    match nftables::clear_rules_all_families(namespace).await {
+        Ok(value) => {
+            removed |= value;
+        }
+        Err(error) => {
+            errors.push(error);
+        }
+    }
+    match iptables::clear_rules_for_binary("iptables", namespace).await {
+        Ok(value) => {
+            removed |= value;
+        }
+        Err(error) => {
+            errors.push(error);
+        }
+    }
+    match iptables::clear_rules_for_binary("ip6tables", namespace).await {
+        Ok(value) => {
+            removed |= value;
+        }
+        Err(error) => {
+            errors.push(error);
+        }
+    }
+
+    if errors.is_empty() {
+        Ok(removed)
+    } else {
+        Err(errors.join("; "))
+    }
+}
+
+fn set_active_synlimit_namespace(next: Option<SynLimitNamespace>) -> Option<SynLimitNamespace> {
+    match ACTIVE_SYNLIMIT_NAMESPACE.lock() {
+        Ok(mut active) => {
+            if *active == next {
+                None
+            } else {
+                std::mem::replace(&mut *active, next)
+            }
+        }
+        Err(error) => {
+            warn!(error = %error, "Failed to update active SYN limiter namespace");
+            None
+        }
+    }
+}
+
+fn take_active_synlimit_namespace() -> Option<SynLimitNamespace> {
+    match ACTIVE_SYNLIMIT_NAMESPACE.lock() {
+        Ok(mut active) => active.take(),
+        Err(error) => {
+            warn!(error = %error, "Failed to read active SYN limiter namespace");
+            None
+        }
+    }
+}
+
+fn has_synlimit_config(cfg: &ProxyConfig) -> bool {
+    cfg.server
+        .listeners
+        .iter()
+        .any(|listener| !matches!(listener.synlimit, SynLimitMode::Off))
+}

src/synlimit_control/model.rs

@@ -0,0 +1,365 @@
+use std::collections::BTreeSet;
+use std::net::IpAddr;
+
+use crate::config::{ProxyConfig, SynLimitMode};
+
+#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
+pub(super) struct SynLimitRule {
+    pub(super) ip: Option<IpAddr>,
+    pub(super) port: u16,
+    pub(super) generic_seconds: u32,
+    pub(super) generic_hitcount: u32,
+    pub(super) generic_burst: u32,
+    pub(super) ios_seconds: u32,
+    pub(super) ios_hitcount: u32,
+    pub(super) ios_burst: u32,
+    pub(super) hashlimit_expire_ms: u32,
+    pub(super) hashlimit_size: u32,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(super) struct SynLimitNamespace {
+    pub(super) nft_table: String,
+    pub(super) iptables_chain: String,
+    pub(super) iptables_hashlimit_prefix: String,
+}
+
+#[derive(Default)]
+pub(super) struct SynLimitTargets {
+    pub(super) iptables_v4: Vec<SynLimitRule>,
+    pub(super) iptables_v6: Vec<SynLimitRule>,
+    pub(super) nft_v4: Vec<SynLimitRule>,
+    pub(super) nft_v6: Vec<SynLimitRule>,
+}
+
+impl SynLimitTargets {
+    pub(super) fn is_empty(&self) -> bool {
+        self.iptables_v4.is_empty()
+            && self.iptables_v6.is_empty()
+            && self.nft_v4.is_empty()
+            && self.nft_v6.is_empty()
+    }
+
+    pub(super) fn has_iptables_targets(&self) -> bool {
+        !self.iptables_v4.is_empty() || !self.iptables_v6.is_empty()
+    }
+
+    pub(super) fn has_nft_targets(&self) -> bool {
+        !self.nft_v4.is_empty() || !self.nft_v6.is_empty()
+    }
+}
+
+struct SynLimitNamespaceHasher {
+    value: u64,
+}
+
+impl SynLimitNamespaceHasher {
+    const OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
+    const PRIME: u64 = 0x0000_0100_0000_01b3;
+
+    fn new() -> Self {
+        Self {
+            value: Self::OFFSET,
+        }
+    }
+
+    fn write(&mut self, bytes: &[u8]) {
+        for byte in bytes {
+            self.value ^= u64::from(*byte);
+            self.value = self.value.wrapping_mul(Self::PRIME);
+        }
+    }
+
+    fn write_u8(&mut self, value: u8) {
+        self.write(&[value]);
+    }
+
+    fn write_u16(&mut self, value: u16) {
+        self.write(&value.to_le_bytes());
+    }
+
+    fn write_u32(&mut self, value: u32) {
+        self.write(&value.to_le_bytes());
+    }
+
+    fn finish(self) -> u64 {
+        self.value
+    }
+}
+
+pub(super) fn synlimit_targets(cfg: &ProxyConfig) -> SynLimitTargets {
+    let mut iptables_v4 = BTreeSet::new();
+    let mut iptables_v6 = BTreeSet::new();
+    let mut nft_v4 = BTreeSet::new();
+    let mut nft_v6 = BTreeSet::new();
+
+    for listener in &cfg.server.listeners {
+        let backend = listener.synlimit;
+        if matches!(backend, SynLimitMode::Off) {
+            continue;
+        }
+        let target = SynLimitRule {
+            ip: (!listener.ip.is_unspecified()).then_some(listener.ip),
+            port: listener.port.unwrap_or(cfg.server.port),
+            generic_seconds: listener.synlimit_seconds,
+            generic_hitcount: listener.synlimit_hitcount,
+            generic_burst: listener.synlimit_burst,
+            ios_seconds: listener.synlimit_ios_seconds,
+            ios_hitcount: listener.synlimit_ios_hitcount,
+            ios_burst: listener.synlimit_ios_burst,
+            hashlimit_expire_ms: listener.synlimit_hashlimit_expire_ms,
+            hashlimit_size: listener.synlimit_hashlimit_size,
+        };
+
+        match (backend, listener.ip.is_ipv4()) {
+            (SynLimitMode::Iptables, true) => {
+                iptables_v4.insert(target);
+            }
+            (SynLimitMode::Iptables, false) => {
+                iptables_v6.insert(target);
+            }
+            (SynLimitMode::Nftables, true) => {
+                nft_v4.insert(target);
+            }
+            (SynLimitMode::Nftables, false) => {
+                nft_v6.insert(target);
+            }
+            (SynLimitMode::Off, _) => {}
+        }
+    }
+
+    SynLimitTargets {
+        iptables_v4: iptables_v4.into_iter().collect(),
+        iptables_v6: iptables_v6.into_iter().collect(),
+        nft_v4: nft_v4.into_iter().collect(),
+        nft_v6: nft_v6.into_iter().collect(),
+    }
+}
+
+pub(super) fn synlimit_namespace(targets: &SynLimitTargets) -> Option<SynLimitNamespace> {
+    if targets.is_empty() {
+        return None;
+    }
+
+    let mut hasher = SynLimitNamespaceHasher::new();
+    write_namespace_rule_group(&mut hasher, b"iptables-v4", &targets.iptables_v4);
+    write_namespace_rule_group(&mut hasher, b"iptables-v6", &targets.iptables_v6);
+    write_namespace_rule_group(&mut hasher, b"nft-v4", &targets.nft_v4);
+    write_namespace_rule_group(&mut hasher, b"nft-v6", &targets.nft_v6);
+
+    let suffix = format!("{:016x}", hasher.finish());
+    let iptables_suffix = &suffix[..12];
+    let hashlimit_suffix = &suffix[..10];
+    Some(SynLimitNamespace {
+        nft_table: format!("telemt_synlimit_{suffix}"),
+        iptables_chain: format!("TMT_SYN_{iptables_suffix}"),
+        iptables_hashlimit_prefix: format!("TMT{hashlimit_suffix}"),
+    })
+}
+
+fn write_namespace_rule_group(
+    hasher: &mut SynLimitNamespaceHasher,
+    group: &[u8],
+    rules: &[SynLimitRule],
+) {
+    hasher.write(group);
+    hasher.write_u32(rules.len() as u32);
+    for rule in rules {
+        write_namespace_rule(hasher, rule);
+    }
+}
+
+fn write_namespace_rule(hasher: &mut SynLimitNamespaceHasher, rule: &SynLimitRule) {
+    match rule.ip {
+        Some(IpAddr::V4(ip)) => {
+            hasher.write_u8(4);
+            hasher.write(&ip.octets());
+        }
+        Some(IpAddr::V6(ip)) => {
+            hasher.write_u8(6);
+            hasher.write(&ip.octets());
+        }
+        None => {
+            hasher.write_u8(0);
+        }
+    }
+    hasher.write_u16(rule.port);
+    hasher.write_u32(rule.generic_seconds);
+    hasher.write_u32(rule.generic_hitcount);
+    hasher.write_u32(rule.generic_burst);
+    hasher.write_u32(rule.ios_seconds);
+    hasher.write_u32(rule.ios_hitcount);
+    hasher.write_u32(rule.ios_burst);
+    hasher.write_u32(rule.hashlimit_expire_ms);
+    hasher.write_u32(rule.hashlimit_size);
+}
+
+pub(super) fn synlimit_rate_arg(seconds: u32, hitcount: u32) -> String {
+    let seconds = u64::from(seconds.max(1));
+    let hitcount = u64::from(hitcount.max(1));
+    for (unit_seconds, unit_name) in [
+        (1_u64, "second"),
+        (60_u64, "minute"),
+        (3_600_u64, "hour"),
+        (86_400_u64, "day"),
+    ] {
+        let amount = hitcount.saturating_mul(unit_seconds);
+        if amount >= seconds && amount % seconds == 0 {
+            return format!("{}/{}", amount / seconds, unit_name);
+        }
+    }
+    let amount = hitcount.saturating_mul(86_400).saturating_add(seconds - 1) / seconds;
+    format!("{}/day", amount.max(1))
+}
+
+#[cfg(test)]
+pub(super) fn test_rule(ip: Option<IpAddr>, port: u16) -> SynLimitRule {
+    SynLimitRule {
+        ip,
+        port,
+        generic_seconds: 60,
+        generic_hitcount: 48,
+        generic_burst: 1,
+        ios_seconds: 1,
+        ios_hitcount: 12,
+        ios_burst: 24,
+        hashlimit_expire_ms: 60_000,
+        hashlimit_size: 32_768,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+
+    use super::*;
+    use crate::config::ListenerConfig;
+
+    fn listener(ip: IpAddr, port: Option<u16>, synlimit: SynLimitMode) -> ListenerConfig {
+        ListenerConfig {
+            ip,
+            port,
+            client_mss: None,
+            synlimit,
+            synlimit_seconds: 60,
+            synlimit_hitcount: 48,
+            synlimit_burst: 1,
+            synlimit_ios_seconds: 1,
+            synlimit_ios_hitcount: 12,
+            synlimit_ios_burst: 24,
+            synlimit_hashlimit_expire_ms: 60_000,
+            synlimit_hashlimit_size: 32_768,
+            announce: None,
+            announce_ip: None,
+            proxy_protocol: None,
+            reuse_allow: false,
+        }
+    }
+
+    #[test]
+    fn synlimit_targets_deduplicate_and_use_legacy_port_fallback() {
+        let mut cfg = ProxyConfig::default();
+        cfg.server.port = 9443;
+        cfg.server.listeners = vec![
+            listener(
+                IpAddr::V4(Ipv4Addr::UNSPECIFIED),
+                None,
+                SynLimitMode::Iptables,
+            ),
+            listener(
+                IpAddr::V4(Ipv4Addr::UNSPECIFIED),
+                None,
+                SynLimitMode::Iptables,
+            ),
+        ];
+
+        let targets = synlimit_targets(&cfg);
+
+        assert_eq!(targets.iptables_v4.len(), 1);
+        assert_eq!(targets.iptables_v4[0].ip, None);
+        assert_eq!(targets.iptables_v4[0].port, 9443);
+        assert!(targets.iptables_v6.is_empty());
+        assert!(targets.nft_v4.is_empty());
+        assert!(targets.nft_v6.is_empty());
+    }
+
+    #[test]
+    fn synlimit_targets_separate_backends_and_ip_families() {
+        let mut cfg = ProxyConfig::default();
+        cfg.server.listeners = vec![
+            listener(
+                IpAddr::V4(Ipv4Addr::new(203, 0, 113, 1)),
+                Some(443),
+                SynLimitMode::Iptables,
+            ),
+            listener(
+                IpAddr::V6(Ipv6Addr::LOCALHOST),
+                Some(443),
+                SynLimitMode::Iptables,
+            ),
+            listener(
+                IpAddr::V4(Ipv4Addr::new(203, 0, 113, 2)),
+                Some(444),
+                SynLimitMode::Nftables,
+            ),
+            listener(
+                IpAddr::V6(Ipv6Addr::UNSPECIFIED),
+                Some(444),
+                SynLimitMode::Nftables,
+            ),
+        ];
+
+        let targets = synlimit_targets(&cfg);
+
+        assert_eq!(targets.iptables_v4.len(), 1);
+        assert_eq!(targets.iptables_v6.len(), 1);
+        assert_eq!(targets.nft_v4.len(), 1);
+        assert_eq!(targets.nft_v6.len(), 1);
+        assert_eq!(
+            targets.iptables_v4[0].ip,
+            Some(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 1)))
+        );
+        assert_eq!(
+            targets.iptables_v6[0].ip,
+            Some(IpAddr::V6(Ipv6Addr::LOCALHOST))
+        );
+        assert_eq!(
+            targets.nft_v4[0].ip,
+            Some(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 2)))
+        );
+        assert_eq!(targets.nft_v6[0].ip, None);
+    }
+
+    #[test]
+    fn synlimit_namespace_is_stable_and_changes_by_targets() {
+        let mut cfg = ProxyConfig::default();
+        cfg.server.listeners = vec![listener(
+            IpAddr::V4(Ipv4Addr::new(203, 0, 113, 1)),
+            Some(443),
+            SynLimitMode::Nftables,
+        )];
+        let first = synlimit_namespace(&synlimit_targets(&cfg))
+            .expect("configured targets must have a namespace");
+        let second = synlimit_namespace(&synlimit_targets(&cfg))
+            .expect("configured targets must have a namespace");
+
+        cfg.server.listeners[0].port = Some(444);
+        let changed = synlimit_namespace(&synlimit_targets(&cfg))
+            .expect("configured targets must have a namespace");
+
+        assert_eq!(first, second);
+        assert_ne!(first, changed);
+        assert!(first.nft_table.starts_with("telemt_synlimit_"));
+        assert!(first.iptables_chain.starts_with("TMT_SYN_"));
+        assert!(first.iptables_chain.len() <= 28);
+        assert!(first.iptables_hashlimit_prefix.starts_with("TMT"));
+    }
+
+    #[test]
+    fn synlimit_rate_arg_uses_native_units_without_fractional_rates() {
+        assert_eq!(synlimit_rate_arg(1, 12), "12/second");
+        assert_eq!(synlimit_rate_arg(60, 48), "48/minute");
+        assert_eq!(synlimit_rate_arg(3600, 121), "121/hour");
+        assert_eq!(synlimit_rate_arg(86400, 241), "241/day");
+    }
+}

src/synlimit_control/nftables.rs

@@ -0,0 +1,316 @@
+use super::command::{run_command, run_command_stdout};
+use super::model::{SynLimitNamespace, SynLimitRule, SynLimitTargets, synlimit_rate_arg};
+
+const NFT_CHAIN: &str = "input";
+const NFT_INPUT_PRIORITY: i16 = -5;
+const IPV4_IOS_PACKET_LENGTH: u16 = 64;
+const IPV6_IOS_PACKET_LENGTH: u16 = 84;
+const IOS_TTL_LIMIT: u8 = 65;
+
+#[derive(Clone, Copy)]
+struct NftTableFamilies {
+    inet: bool,
+    ip: bool,
+    ip6: bool,
+}
+
+#[derive(Clone, Copy)]
+enum NftFamily {
+    Inet,
+    Ip,
+    Ip6,
+}
+
+struct NftApplyPlan<'a> {
+    family: NftFamily,
+    v4_targets: &'a [SynLimitRule],
+    v6_targets: &'a [SynLimitRule],
+}
+
+impl NftFamily {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Inet => "inet",
+            Self::Ip => "ip",
+            Self::Ip6 => "ip6",
+        }
+    }
+}
+
+pub(super) async fn apply_synlimit_rules(
+    targets: &SynLimitTargets,
+    namespace: &SynLimitNamespace,
+) -> Result<(), String> {
+    let families = detect_nft_table_families().await;
+    for plan in nft_apply_plan(families, &targets.nft_v4, &targets.nft_v6) {
+        let script = nft_synlimit_script(plan, namespace);
+        run_command("nft", &["-f", "-"], Some(script)).await?;
+    }
+
+    Ok(())
+}
+
+async fn detect_nft_table_families() -> NftTableFamilies {
+    let Ok(output) = run_command_stdout("nft", &["list", "tables"]).await else {
+        return NftTableFamilies {
+            inet: false,
+            ip: false,
+            ip6: false,
+        };
+    };
+
+    let mut families = NftTableFamilies {
+        inet: false,
+        ip: false,
+        ip6: false,
+    };
+    for line in output.lines() {
+        let mut fields = line.split_whitespace();
+        if fields.next() != Some("table") {
+            continue;
+        }
+        match fields.next() {
+            Some("inet") => families.inet = true,
+            Some("ip") => families.ip = true,
+            Some("ip6") => families.ip6 = true,
+            _ => {}
+        }
+    }
+    families
+}
+
+fn nft_apply_plan<'a>(
+    families: NftTableFamilies,
+    v4_targets: &'a [SynLimitRule],
+    v6_targets: &'a [SynLimitRule],
+) -> Vec<NftApplyPlan<'a>> {
+    if !v4_targets.is_empty() && !v6_targets.is_empty() {
+        return vec![NftApplyPlan {
+            family: NftFamily::Inet,
+            v4_targets,
+            v6_targets,
+        }];
+    }
+    if !v4_targets.is_empty() {
+        return vec![NftApplyPlan {
+            family: if families.inet || !families.ip {
+                NftFamily::Inet
+            } else {
+                NftFamily::Ip
+            },
+            v4_targets,
+            v6_targets: &[],
+        }];
+    }
+    if !v6_targets.is_empty() {
+        return vec![NftApplyPlan {
+            family: if families.inet || !families.ip6 {
+                NftFamily::Inet
+            } else {
+                NftFamily::Ip6
+            },
+            v4_targets: &[],
+            v6_targets,
+        }];
+    }
+    Vec::new()
+}
+
+fn nft_synlimit_script(plan: NftApplyPlan<'_>, namespace: &SynLimitNamespace) -> String {
+    let mut script = String::new();
+    script.push_str(&format!(
+        "table {} {} {{\n",
+        plan.family.as_str(),
+        namespace.nft_table
+    ));
+    script.push_str(&format!("  chain {NFT_CHAIN} {{\n"));
+    script.push_str(&format!(
+        "    type filter hook input priority {NFT_INPUT_PRIORITY}; policy accept;\n"
+    ));
+    for (idx, target) in plan.v4_targets.iter().enumerate() {
+        push_nft_v4_rules(&mut script, target, idx);
+    }
+    for (idx, target) in plan.v6_targets.iter().enumerate() {
+        push_nft_v6_rules(&mut script, target, idx);
+    }
+    script.push_str("  }\n");
+    script.push_str("}\n");
+    script
+}
+
+fn push_nft_v4_rules(script: &mut String, target: &SynLimitRule, idx: usize) {
+    let daddr = target
+        .ip
+        .map(|ip| format!(" ip daddr {ip}"))
+        .unwrap_or_default();
+    let ios_rate = synlimit_rate_arg(target.ios_seconds, target.ios_hitcount);
+    let generic_rate = synlimit_rate_arg(target.generic_seconds, target.generic_hitcount);
+    script.push_str(&format!(
+        "    tcp flags & (fin|syn|rst|ack) == syn{daddr} meta length {IPV4_IOS_PACKET_LENGTH} ip ttl < {IOS_TTL_LIMIT} tcp dport {port} meter telemt_synfix_ios_v4_{idx} {{ ip saddr limit rate over {ios_rate} burst {ios_burst} packets }} reject with tcp reset\n",
+        port = target.port,
+        ios_burst = target.ios_burst,
+    ));
+    script.push_str(&format!(
+        "    tcp flags & (fin|syn|rst|ack) == syn{daddr} meta length {IPV4_IOS_PACKET_LENGTH} ip ttl < {IOS_TTL_LIMIT} tcp dport {port} accept\n",
+        port = target.port,
+    ));
+    script.push_str(&format!(
+        "    tcp flags & (fin|syn|rst|ack) == syn{daddr} tcp dport {port} meter telemt_synfix_v4_{idx} {{ ip saddr limit rate over {generic_rate} burst {generic_burst} packets }} reject with tcp reset\n",
+        port = target.port,
+        generic_burst = target.generic_burst,
+    ));
+    script.push_str(&format!(
+        "    tcp flags & (fin|syn|rst|ack) == syn{daddr} tcp dport {port} accept\n",
+        port = target.port,
+    ));
+}
+
+fn push_nft_v6_rules(script: &mut String, target: &SynLimitRule, idx: usize) {
+    let daddr = target
+        .ip
+        .map(|ip| format!(" ip6 daddr {ip}"))
+        .unwrap_or_default();
+    let ios_rate = synlimit_rate_arg(target.ios_seconds, target.ios_hitcount);
+    let generic_rate = synlimit_rate_arg(target.generic_seconds, target.generic_hitcount);
+    script.push_str(&format!(
+        "    tcp flags & (fin|syn|rst|ack) == syn{daddr} meta length {IPV6_IOS_PACKET_LENGTH} ip6 hoplimit < {IOS_TTL_LIMIT} tcp dport {port} meter telemt_synfix_ios_v6_{idx} {{ ip6 saddr limit rate over {ios_rate} burst {ios_burst} packets }} reject with tcp reset\n",
+        port = target.port,
+        ios_burst = target.ios_burst,
+    ));
+    script.push_str(&format!(
+        "    tcp flags & (fin|syn|rst|ack) == syn{daddr} meta length {IPV6_IOS_PACKET_LENGTH} ip6 hoplimit < {IOS_TTL_LIMIT} tcp dport {port} accept\n",
+        port = target.port,
+    ));
+    script.push_str(&format!(
+        "    tcp flags & (fin|syn|rst|ack) == syn{daddr} tcp dport {port} meter telemt_synfix_v6_{idx} {{ ip6 saddr limit rate over {generic_rate} burst {generic_burst} packets }} reject with tcp reset\n",
+        port = target.port,
+        generic_burst = target.generic_burst,
+    ));
+    script.push_str(&format!(
+        "    tcp flags & (fin|syn|rst|ack) == syn{daddr} tcp dport {port} accept\n",
+        port = target.port,
+    ));
+}
+
+pub(super) async fn clear_rules_all_families(
+    namespace: &SynLimitNamespace,
+) -> Result<bool, String> {
+    let mut errors = Vec::new();
+    let mut removed = false;
+    let table = namespace.nft_table.as_str();
+    for family in [NftFamily::Inet, NftFamily::Ip, NftFamily::Ip6] {
+        match run_command("nft", &["delete", "table", family.as_str(), table], None).await {
+            Ok(()) => {
+                removed = true;
+            }
+            Err(error) if is_missing_command_or_nft_table(&error) => {}
+            Err(error) => {
+                errors.push(format!(
+                    "nft delete table {} {table} failed: {error}",
+                    family.as_str(),
+                ));
+            }
+        }
+    }
+
+    if errors.is_empty() {
+        Ok(removed)
+    } else {
+        Err(errors.join(", "))
+    }
+}
+
+fn is_missing_command_or_nft_table(error: &str) -> bool {
+    error.contains("is not available") || error.contains("No such file or directory")
+}
+
+#[cfg(test)]
+mod tests {
+    use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+
+    use super::*;
+    use crate::synlimit_control::model::test_rule;
+
+    fn test_namespace(table: &str) -> SynLimitNamespace {
+        SynLimitNamespace {
+            nft_table: table.to_string(),
+            iptables_chain: "TMT_SYN_TEST".to_string(),
+            iptables_hashlimit_prefix: "TMTTEST".to_string(),
+        }
+    }
+
+    #[test]
+    fn nft_script_uses_synfix_v4_rules_and_early_priority() {
+        let rule = test_rule(Some(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 7))), 443);
+        let namespace = test_namespace("telemt_synlimit_test_a");
+        let script = nft_synlimit_script(
+            NftApplyPlan {
+                family: NftFamily::Inet,
+                v4_targets: &[rule],
+                v6_targets: &[],
+            },
+            &namespace,
+        );
+
+        assert!(script.contains("table inet telemt_synlimit_test_a"));
+        assert!(script.contains("type filter hook input priority -5; policy accept;"));
+        assert!(script.contains("ip daddr 203.0.113.7"));
+        assert!(script.contains("meta length 64 ip ttl < 65"));
+        assert!(script.contains("limit rate over 12/second burst 24 packets"));
+        assert!(script.contains("limit rate over 48/minute burst 1 packets"));
+        assert!(script.contains("reject with tcp reset"));
+    }
+
+    #[test]
+    fn nft_script_uses_ipv6_hoplimit_classifier() {
+        let rule = test_rule(Some(IpAddr::V6(Ipv6Addr::LOCALHOST)), 443);
+        let namespace = test_namespace("telemt_synlimit_test_b");
+        let script = nft_synlimit_script(
+            NftApplyPlan {
+                family: NftFamily::Inet,
+                v4_targets: &[],
+                v6_targets: &[rule],
+            },
+            &namespace,
+        );
+
+        assert!(script.contains("table inet telemt_synlimit_test_b"));
+        assert!(script.contains("ip6 daddr ::1"));
+        assert!(script.contains("meta length 84 ip6 hoplimit < 65"));
+        assert!(script.contains("ip6 saddr limit rate over 12/second burst 24 packets"));
+        assert!(script.contains("ip6 saddr limit rate over 48/minute burst 1 packets"));
+    }
+
+    #[test]
+    fn nft_missing_table_errors_are_cleanup_benign() {
+        assert!(is_missing_command_or_nft_table("nft is not available"));
+        assert!(is_missing_command_or_nft_table(
+            "Error: No such file or directory"
+        ));
+        assert!(!is_missing_command_or_nft_table(
+            "Error: Operation not permitted"
+        ));
+    }
+
+    #[test]
+    fn nft_apply_plan_keeps_dual_stack_rules_in_inet_table() {
+        let v4_rule = test_rule(Some(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 7))), 443);
+        let v6_rule = test_rule(Some(IpAddr::V6(Ipv6Addr::LOCALHOST)), 443);
+        let v4_rules = [v4_rule];
+        let v6_rules = [v6_rule];
+        let plans = nft_apply_plan(
+            NftTableFamilies {
+                inet: false,
+                ip: false,
+                ip6: false,
+            },
+            &v4_rules,
+            &v6_rules,
+        );
+
+        assert_eq!(plans.len(), 1);
+        assert_eq!(plans[0].family.as_str(), "inet");
+        assert_eq!(plans[0].v4_targets, v4_rules.as_slice());
+        assert_eq!(plans[0].v6_targets, v6_rules.as_slice());
+    }
+}

src/tls_front/cache.rs

@@ -12,7 +12,8 @@ use tokio::time::sleep;
 use tracing::{debug, info, warn};
 
 use crate::tls_front::types::{
-    CachedTlsData, ParsedServerHello, TlsBehaviorProfile, TlsFetchResult, TlsProfileSource,
+    CachedTlsData, ParsedServerHello, TlsBehaviorProfile, TlsFetchResult, TlsProfileQuality,
+    TlsProfileSource,
 };
 
 const FULL_CERT_SENT_SWEEP_INTERVAL_SECS: u64 = 30;
@@ -47,10 +48,14 @@ pub struct TlsFrontCache {
 pub(crate) struct TlsFrontProfileHealth {
     pub(crate) domain: String,
     pub(crate) source: &'static str,
+    pub(crate) quality: &'static str,
+    pub(crate) key_share_group: &'static str,
     pub(crate) age_seconds: u64,
     pub(crate) is_default: bool,
     pub(crate) has_cert_info: bool,
     pub(crate) has_cert_payload: bool,
+    pub(crate) server_hello_record_len: usize,
+    pub(crate) server_hello_extensions: usize,
     pub(crate) app_data_records: usize,
     pub(crate) ticket_records: usize,
     pub(crate) change_cipher_spec_count: u8,
@@ -66,6 +71,23 @@ fn profile_source_label(source: TlsProfileSource) -> &'static str {
     }
 }
 
+fn profile_quality_label(quality: TlsProfileQuality) -> &'static str {
+    match quality {
+        TlsProfileQuality::Fallback => "fallback",
+        TlsProfileQuality::RawPartial => "raw_partial",
+        TlsProfileQuality::RawStrict => "raw_strict",
+    }
+}
+
+fn key_share_group_label(group: Option<u16>) -> &'static str {
+    match group {
+        Some(0x001d) => "x25519",
+        Some(0x11ec) => "x25519mlkem768",
+        Some(_) => "other",
+        None => "none",
+    }
+}
+
 #[allow(dead_code)]
 impl TlsFrontCache {
     pub fn new(domains: &[String], default_len: usize, disk_path: impl AsRef<Path>) -> Self {
@@ -137,7 +159,8 @@ impl TlsFrontCache {
                 .get(domain)
                 .cloned()
                 .unwrap_or_else(|| self.default.clone());
-            let behavior = &cached.behavior_profile;
+            let mut behavior = cached.behavior_profile.clone();
+            behavior.refresh_server_hello_summary(&cached.server_hello_template);
             let age_seconds = now
                 .duration_since(cached.fetched_at)
                 .map(|duration| duration.as_secs())
@@ -146,10 +169,14 @@ impl TlsFrontCache {
             snapshot.push(TlsFrontProfileHealth {
                 domain: domain.clone(),
                 source: profile_source_label(behavior.source),
+                quality: profile_quality_label(behavior.quality),
+                key_share_group: key_share_group_label(behavior.server_hello_key_share_group),
                 age_seconds,
                 is_default: cached.domain == "default",
                 has_cert_info: cached.cert_info.is_some(),
                 has_cert_payload: cached.cert_payload.is_some(),
+                server_hello_record_len: behavior.server_hello_record_len,
+                server_hello_extensions: behavior.server_hello_extension_types.len(),
                 app_data_records: cached
                     .app_data_records_sizes
                     .len()
@@ -337,6 +364,9 @@ impl TlsFrontCache {
                             warn!(domain = %cached.domain, "Skipping stale TLS cache entry (>72h)");
                             continue;
                         }
+                        cached
+                            .behavior_profile
+                            .refresh_server_hello_summary(&cached.server_hello_template);
                         let domain = cached.domain.clone();
                         self.set(&domain, cached).await;
                         loaded += 1;
@@ -378,20 +408,39 @@ impl TlsFrontCache {
 
     /// Replace cached entry from a fetch result.
     pub async fn update_from_fetch(&self, domain: &str, fetched: TlsFetchResult) {
+        let TlsFetchResult {
+            server_hello_parsed,
+            app_data_records_sizes,
+            total_app_data_len,
+            mut behavior_profile,
+            cert_info,
+            cert_payload,
+        } = fetched;
+        behavior_profile.refresh_server_hello_summary(&server_hello_parsed);
+        let quality = behavior_profile.quality;
         let data = CachedTlsData {
-            server_hello_template: fetched.server_hello_parsed,
-            cert_info: fetched.cert_info,
-            cert_payload: fetched.cert_payload,
-            app_data_records_sizes: fetched.app_data_records_sizes.clone(),
-            total_app_data_len: fetched.total_app_data_len,
-            behavior_profile: fetched.behavior_profile,
+            server_hello_template: server_hello_parsed,
+            cert_info,
+            cert_payload,
+            app_data_records_sizes: app_data_records_sizes.clone(),
+            total_app_data_len,
+            behavior_profile,
             fetched_at: SystemTime::now(),
             domain: domain.to_string(),
         };
 
         self.set(domain, data.clone()).await;
         self.persist(domain, &data).await;
-        debug!(domain = %domain, len = fetched.total_app_data_len, "TLS cache updated");
+        if quality == TlsProfileQuality::RawStrict {
+            debug!(domain = %domain, len = total_app_data_len, "TLS cache updated");
+        } else {
+            warn!(
+                domain = %domain,
+                quality = profile_quality_label(quality),
+                len = total_app_data_len,
+                "TLS cache updated with non-strict front profile"
+            );
+        }
     }
 
     pub fn default_entry(&self) -> Arc<CachedTlsData> {