Merge pull request #900 from telemt/flow/3.5.1

Flow/3.5.1

.github/FUNDING.yml

@@ -0,0 +1,16 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom:
+  - https://nowpayments.io/donation?api_key=2bf1afd2-abc2-49f9-a012-f1e715b37223

.github/workflows/build.yml

@@ -36,4 +36,10 @@ jobs:
             ${{ runner.os }}-cargo-
 
       - name: Build Release
-        run: cargo build --release --verbose
+        run: cargo build --release --verbose
+
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: telemt
+          path: target/release/telemt

.github/workflows/coverage.yml

@@ -0,0 +1,49 @@
+name: Coverage
+
+on:
+  pull_request:
+    branches: [ "*" ]
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  coverage:
+    name: LLVM coverage report
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: llvm-tools-preview
+
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-llvm-cov-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-llvm-cov-
+            ${{ runner.os }}-cargo-
+
+      - name: Install cargo-llvm-cov
+        run: cargo install --locked cargo-llvm-cov || true
+
+      - name: Generate LCOV report
+        run: cargo llvm-cov --locked --lcov --output-path lcov.info
+
+      - name: Upload LCOV report
+        uses: actions/upload-artifact@v4
+        with:
+          name: telemt-lcov
+          path: lcov.info

.github/workflows/release.yml

@@ -151,6 +151,14 @@ jobs:
           mkdir -p dist
           cp "target/${{ matrix.target }}/release/${{ env.BINARY_NAME }}" dist/telemt
 
+          if [ "${{ matrix.target }}" = "aarch64-unknown-linux-gnu" ]; then
+            STRIP_BIN=aarch64-linux-gnu-strip
+          else
+            STRIP_BIN=strip
+          fi
+
+          "${STRIP_BIN}" dist/telemt
+
           cd dist
           tar -czf "${{ matrix.asset }}.tar.gz" \
             --owner=0 --group=0 --numeric-owner \
@@ -279,6 +287,14 @@ jobs:
           mkdir -p dist
           cp "target/${{ matrix.target }}/release/${{ env.BINARY_NAME }}" dist/telemt
 
+          if [ "${{ matrix.target }}" = "aarch64-unknown-linux-musl" ]; then
+            STRIP_BIN=aarch64-linux-musl-strip
+          else
+            STRIP_BIN=strip
+          fi
+
+          "${STRIP_BIN}" dist/telemt
+
           cd dist
           tar -czf "${{ matrix.asset }}.tar.gz" \
             --owner=0 --group=0 --numeric-owner \

AGENTS.md

@@ -191,6 +191,11 @@ When facing a non-trivial modification, follow this sequence:
 4. **Implement**: Make the minimal, isolated change.
 5. **Verify**: Explain why the change preserves existing behavior and architectural integrity.
 
+When the repository contains a `PLAN.md` for the current task, maintain it as
+a working checkbox plan while implementing changes. Mark completed and partial
+items in `PLAN.md` as the code changes land, so the remaining work stays
+explicit and future passes do not waste time rediscovering status.
+
 ---
 
 ### 9. Context Awareness
@@ -222,10 +227,9 @@ Your response MUST consist of two sections:
 
 **Section 2: `## Changes`**
 
-- For each modified or created file: the filename on a separate line in backticks, followed by the code block.
-- For files **under 200 lines**: return the full file with all changes applied.
-- For files **over 200 lines**: return only the changed functions/blocks with at least 3 lines of surrounding context above and below. If the user requests the full file, provide it.
-- New files: full file content.
+- For each modified or created file: the filename on a separate line in backticks, followed by a concise description of what changed.
+- Do not include full file contents or long code blocks in `## Changes` unless the user explicitly asks for code text.
+- If code snippets are necessary, include only the minimal relevant excerpt.
 - End with a suggested git commit message in English.
 
 #### Reporting Out-of-Scope Issues
@@ -429,4 +433,3 @@ Every patch must be **atomic and production-safe**.
 * **No transitional states** — no placeholders, incomplete refactors, or temporary inconsistencies.
 
 **Invariant:** After any single patch, the repository remains fully functional and buildable.
-

CODE_OF_CONDUCT.md

@@ -3,50 +3,39 @@
 ## Purpose
 
 **Telemt exists to solve technical problems.**
+- Telemt is open to contributors who want to learn, improve and build meaningful systems together.
+- It is a place for building, testing, reasoning, documenting, and improving systems.
+- Discussions that advance this work are in scope, discussions that divert it are not.
+- Technology has consequences, responsibility is inherent.
 
-Telemt is open to contributors who want to learn, improve and build meaningful systems together.
+> **Absicht bestimmt die Form**
 
-It is a place for building, testing, reasoning, documenting, and improving systems.
-
-Discussions that advance this work are in scope. Discussions that divert it are not.
-
-Technology has consequences. Responsibility is inherent.
-
-> **Zweck bestimmt die Form.**
-
-> Purpose defines form.
+> Design follows intent
 
 ---
 
 ## Principles
 
 * **Technical over emotional**
-
-  Arguments are grounded in data, logs, reproducible cases, or clear reasoning.
+  - Arguments are grounded in data, logs, reproducible cases, or clear reasoning.
 
 * **Clarity over noise**
-
-  Communication is structured, concise, and relevant.
+  - Communication is structured, concise, and relevant.
 
 * **Openness with standards**
-
-  Participation is open. The work remains disciplined.
+  - Participation is open. The work remains disciplined.
 
 * **Independence of judgment**
-
-  Claims are evaluated on technical merit, not affiliation or posture.
+  - Claims are evaluated on technical merit, not affiliation or posture.
 
 * **Responsibility over capability**
-
-  Capability does not justify careless use.
+  - Capability does not justify careless use.
 
 * **Cooperation over friction**
-
-  Progress depends on coordination, mutual support, and honest review.
+  - Progress depends on coordination, mutual support, and honest review.
 
 * **Good intent, rigorous method**
-
-  Assume good intent, but require rigor.
+  - Assume good intent, but require rigor.
 
 > **Aussagen gelten nach ihrer Begründung.**
 
@@ -68,7 +57,9 @@ Participants are expected to:
 
 Precision is learned.
 
-New contributors are welcome. They are expected to grow into these standards. Existing contributors are expected to make that growth possible.
+- New contributors are welcome
+- They are expected to grow into these standards
+- Existing contributors are expected to make that growth possible
 
 > **Wer behauptet, belegt.**
 
@@ -112,7 +103,7 @@ Security is both technical and behavioral.
 
 ---
 
-## 6. Openness
+## Openness
 
 Telemt is open to contributors of different backgrounds, experience levels, and working styles.
 
@@ -148,10 +139,9 @@ Judgment should be exercised with restraint, consistency, and institutional resp
 
 All decisions are expected to serve the durability, clarity, and integrity of Telemt.
 
-> **Ordnung ist Voraussetzung der Funktion.**
-
-> Order is the precondition of function.
+> **Klarheit vor Zustimmung - Bestand vor Beifall**
 
+> Clarity above approval - substantiality before success
 ---
 
 ## Enforcement
@@ -171,42 +161,41 @@ Actions are taken to maintain function, continuity, and signal quality.
 
 ## Final
 
-Telemt is built on discipline, structure, and shared intent.
-- Signal over noise.
-- Facts over opinion.
-- Systems over rhetoric.
+**Telemt is built on discipline, structure, and shared intent**
+- Signal over noise
+- Facts over opinion
+- Systems over rhetoric
+- Work is collective
+- Outcomes are shared
+- Responsibility is distributed
+- Precision is learned
+- Rigor is expected
+- Help is part of the work
 
-- Work is collective.
-- Outcomes are shared.
-- Responsibility is distributed.
+> **Ordnung ist Voraussetzung der Freiheit**
 
-- Precision is learned.
-- Rigor is expected.
-- Help is part of the work.
-
-> **Ordnung ist Voraussetzung der Freiheit.**
-
-- If you contribute — contribute with care.
-- If you speak — speak with substance.
-- If you engage — engage constructively.
+- If you contribute — contribute with care
+- If you speak — speak with substance
+- If you engage — engage constructively
 
 ---
 
 ## After All
 
-Systems outlive intentions.
-- What is built will be used.
-- What is released will propagate.
-- What is maintained will define the future state.
+Systems outlive intentions
+- What is built will be used
+- What is released will propagate
+- What is maintained will define the future state
 
-There is no neutral infrastructure, only infrastructure shaped well or poorly.
+There is no neutral infrastructure, only infrastructure shaped well or poorly
 
-> **Jedes System trägt Verantwortung.**
+> **Ordnung → Umsetzung → Ergebnis**
 
-> Every system carries responsibility.
+> Order → Implementation → Result
 
-- Stability requires discipline.
-- Freedom requires structure.
-- Trust requires honesty.
+- Stability requires discipline
+- Freedom requires structure
+- Trust requires honesty
+
+In the end: the system reflects its contributors
 
-In the end: the system reflects its contributors.

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.
 
@@ -52,11 +54,15 @@ By submitting a PR, you confirm that:
 
 AI-generated code is treated as **draft** and must be validated like any other external contribution.
 
+The problem isn’t AI as a tool, but the dilution of responsibility. If the commit history says "Claude/GPT authored this", then who is accountable for the bug? Claude? GPT? Anthropic? OpenAI? Samuel Altman?
+
+The user who didn’t read the diff? No one? But, in a sensitive system, *"no one"* is an unacceptable maintainer model.
+
 PRs that look like unverified AI dumps WILL be closed
 
 ---
 
-## Maintainer Policy
+### Maintainer Policy
 
 Maintainers reserve the right to:
 
@@ -68,7 +74,7 @@ Respect the reviewers time
 
 ---
 
-## Enforcement
+### Enforcement
 
 Pull Requests that violate project standards may be closed without review.
 
@@ -79,4 +85,4 @@ This includes (but is not limited to):
 - unverified or low-effort changes
 - inability to explain the change
 
-These actions follow the Code of Conduct and are intended to preserve signal, quality, and Telemt's integrity
+These actions follow the Code of Conduct and are intended to preserve signal, quality, and Telemt's integrity

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "telemt"
-version = "3.3.38"
+version = "3.5.1"
 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 = ["client", "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"
@@ -98,4 +100,3 @@ harness = false
 [profile.release]
 lto = "fat"
 codegen-units = 1
-

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,10 +83,38 @@ 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
 
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD ["/app/telemt", "healthcheck", "/app/config.toml", "--mode", "liveness"]
+
+ENTRYPOINT ["/app/telemt"]
+CMD ["config.toml"]
+
+# ==========================
+# Production Netfilter Profile
+# ==========================
+FROM debian:12-slim AS prod-netfilter
+
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+        ca-certificates \
+        conntrack \
+        nftables \
+        iptables; \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY --from=minimal /telemt /app/telemt
+COPY --from=minimal /app/config.toml /app/config.toml
+
+EXPOSE 443 9090 9091
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD ["/app/telemt", "healthcheck", "/app/config.toml", "--mode", "liveness"]
+
 ENTRYPOINT ["/app/telemt"]
 CMD ["config.toml"]
 
@@ -88,11 +126,13 @@ 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
 
 EXPOSE 443 9090 9091
 
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD ["/app/telemt", "healthcheck", "/app/config.toml", "--mode", "liveness"]
+
 ENTRYPOINT ["/app/telemt"]
 CMD ["config.toml"]

LICENSE

@@ -1,4 +1,4 @@
-###### TELEMT Public License 3 ######
+######## TELEMT LICENSE 3.3 #########
 ##### Copyright (c) 2026 Telemt #####
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -14,11 +14,15 @@ are preserved and complied with.
 The canonical version of this License is the English version.
 Official translations are provided for informational purposes only
 and for convenience, and do not have legal force. In case of any
-discrepancy, the English version of this License shall prevail.
-Available versions:
-- English in Markdown: docs/LICENSE/LICENSE.md
-- German: docs/LICENSE/LICENSE.de.md
-- Russian: docs/LICENSE/LICENSE.ru.md
+discrepancy, the English version of this License shall prevail
+
+/----------------------------------------------------------\
+| Language    | Location                                   |
+|-------------|--------------------------------------------|
+| English     | docs/LICENSE/TELEMT-LICENSE.en.md          |
+| German      | docs/LICENSE/TELEMT-LICENSE.de.md          |
+| Russian     | docs/LICENSE/TELEMT-LICENSE.ru.md          |
+\----------------------------------------------------------/
 
 ### License Versioning Policy
 

README.md

@@ -1,189 +1,57 @@
 # Telemt - MTProxy on Rust + Tokio
 
-***Löst Probleme, bevor andere überhaupt wissen, dass sie existieren*** / ***It solves problems before others even realize they exist***
+[![Latest Release](https://img.shields.io/github/v/release/telemt/telemt?color=neon)](https://github.com/telemt/telemt/releases/latest) [![Stars](https://img.shields.io/github/stars/telemt/telemt?style=social)](https://github.com/telemt/telemt/stargazers) [![Forks](https://img.shields.io/github/forks/telemt/telemt?style=social)](https://github.com/telemt/telemt/network/members)
 
-### [**Telemt Chat in Telegram**](https://t.me/telemtrs)
-#### Fixed TLS ClientHello is now available in Telegram Desktop starting from version 6.7.2: to work with EE-MTProxy, please update your client;
-#### Fixed TLS ClientHello for Telegram Android Client is available in [our chat](https://t.me/telemtrs/30234/36441); official releases for Android and iOS are "work in progress";
+[🇷🇺 README на русском](https://github.com/telemt/telemt/blob/main/README.ru.md)
 
+> [!NOTE]
+>
+> From June 5th, 2026: we are already analyzing the causes of a new wave of "malfunctions"
+> 
+> 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)
 
-**Telemt** is a fast, secure, and feature-rich server written in Rust: it fully implements the official Telegram proxy algo and adds many production-ready improvements such as:
-- [ME Pool + Reader/Writer + Registry + Refill + Adaptive Floor + Trio-State + Generation Lifecycle](https://github.com/telemt/telemt/blob/main/docs/model/MODEL.en.md)
-- [Full-covered API w/ management](https://github.com/telemt/telemt/blob/main/docs/API.md)
-- Anti-Replay on Sliding Window
-- Prometheus-format Metrics
-- TLS-Fronting and TCP-Splicing for masking from "prying" eyes
+<p align="center">
+  <a href="https://t.me/telemtrs">
+    <img src="https://github.com/user-attachments/assets/30b7e7b9-974a-4e3d-aab6-b58a85de4507" width="240"/>
+  </a>
+</p>
 
-⚓ Our implementation of **TLS-fronting** is one of the most deeply debugged, focused, advanced and *almost* **"behaviorally consistent to real"**:  we are confident we have it right - [see evidence on our validation and traces](#recognizability-for-dpi-and-crawler)
+**Telemt** is a fast, secure, and feature-rich server written in Rust: it fully implements the official Telegram proxy algo and adds many production-ready improvements
 
-⚓ Our ***Middle-End Pool*** is fastest by design in standard scenarios, compared to other implementations of connecting to the Middle-End Proxy: non dramatically, but usual
+### One-command Install and Update
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
+```
+- [Quick Start Guide](docs/Quick_start/QUICK_START_GUIDE.en.md)
+- [Инструкция по быстрому запуску](docs/Quick_start/QUICK_START_GUIDE.ru.md)
+
+## Features
+Our implementation of **TLS-fronting** is one of the most deeply debugged, focused, advanced and *almost* **"behaviorally consistent to real"**:  we are confident we have it right - [see evidence on our validation and traces](docs/FAQ.en.md#recognizability-for-dpi-and-crawler)
+
+Our ***Middle-End Pool*** is fastest by design in standard scenarios, compared to other implementations of connecting to the Middle-End Proxy: non dramatically, but usual
 
 - Full support for all official MTProto proxy modes:
-  - Classic
-  - Secure - with `dd` prefix
-  - Fake TLS - with `ee` prefix + SNI fronting
-- Replay attack protection
-- Optional traffic masking: forward unrecognized connections to a real web server, e.g. GitHub 🤪
-- Configurable keepalives + timeouts + IPv6 and "Fast Mode"
-- Graceful shutdown on Ctrl+C
-- Extensive logging via `trace` and `debug` with `RUST_LOG` method
-
-# GOTO
-- [Quick Start Guide](#quick-start-guide)
-- [FAQ](#faq)
-  - [Recognizability for DPI and crawler](#recognizability-for-dpi-and-crawler)
-    - [Client WITH secret-key accesses the MTProxy resource:](#client-with-secret-key-accesses-the-mtproxy-resource)
-    - [Client WITHOUT secret-key gets transparent access to the specified resource:](#client-without-secret-key-gets-transparent-access-to-the-specified-resource)
-  - [Telegram Calls via MTProxy](#telegram-calls-via-mtproxy)
-  - [How does DPI see MTProxy TLS?](#how-does-dpi-see-mtproxy-tls)
-  - [Whitelist on IP](#whitelist-on-ip)
-  - [Too many open files](#too-many-open-files)
-- [Build](#build)
-- [Why Rust?](#why-rust)
-- [Issues](#issues)
-- [Roadmap](#roadmap)
-
-
-## Quick Start Guide
-- [Quick Start Guide RU](docs/QUICK_START_GUIDE.ru.md)
-- [Quick Start Guide EN](docs/QUICK_START_GUIDE.en.md)
+  - Classic;
+  - Secure - with `dd` prefix;
+  - Fake TLS - with `ee` prefix + SNI fronting;
+- Replay attack protection;
+- Optional traffic masking: forward unrecognized connections to a real web server, e.g. GitHub 🤪;
+- Configurable keepalives + timeouts + IPv6 and "Fast Mode";
+- Graceful shutdown on Ctrl+C;
+- Extensive logging via `trace` and `debug` with `RUST_LOG` method.
 
 ## FAQ
-
 - [FAQ RU](docs/FAQ.ru.md)
 - [FAQ EN](docs/FAQ.en.md)
 
-### Recognizability for DPI and crawler
-
-On April 1, 2026, we became aware of a method for detecting MTProxy Fake-TLS, 
-based on the ECH extension and the ordering of cipher suites, 
-as well as an overall unique JA3/JA4 fingerprint 
-that does not occur in modern browsers: 
-we have already submitted initial changes to the Telegram Desktop developers and are working on updates for other clients.
-
-- We consider this a breakthrough aspect, which has no stable analogues today
-- Based on this: if `telemt` configured correctly, **TLS mode is completely identical to real-life handshake + communication** with a specified host
-- Here is our evidence:
-    - 212.220.88.77 - "dummy" host, running `telemt`
-    - `petrovich.ru` - `tls` + `masking` host, in HEX: `706574726f766963682e7275`
-    - **No MITM + No Fake Certificates/Crypto** = pure transparent *TCP Splice* to "best" upstream: MTProxy or tls/mask-host:
-      - DPI see legitimate HTTPS to `tls_host`, including *valid chain-of-trust* and entropy
-      - Crawlers completely satisfied receiving responses from `mask_host`
-  #### Client WITH secret-key accesses the MTProxy resource:
-  
-  <img width="360" height="439" alt="telemt" src="https://github.com/user-attachments/assets/39352afb-4a11-4ecc-9d91-9e8cfb20607d" />
-  
-  #### Client WITHOUT secret-key gets transparent access to the specified resource:
-    - with trusted certificate
-    - with original handshake
-    - with full request-response way
-    - with low-latency overhead
-```bash
-root@debian:~/telemt# curl -v -I --resolve petrovich.ru:443:212.220.88.77 https://petrovich.ru/
-* Added petrovich.ru:443:212.220.88.77 to DNS cache
-* Hostname petrovich.ru was found in DNS cache
-*   Trying 212.220.88.77:443...
-* Connected to petrovich.ru (212.220.88.77) port 443 (#0)
-* ALPN: offers h2,http/1.1
-* TLSv1.3 (OUT), TLS handshake, Client hello (1):
-*  CAfile: /etc/ssl/certs/ca-certificates.crt
-*  CApath: /etc/ssl/certs
-* TLSv1.3 (IN), TLS handshake, Server hello (2):
-* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
-* TLSv1.3 (IN), TLS handshake, Certificate (11):
-* TLSv1.3 (IN), TLS handshake, CERT verify (15):
-* TLSv1.3 (IN), TLS handshake, Finished (20):
-* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
-* TLSv1.3 (OUT), TLS handshake, Finished (20):
-* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
-* ALPN: server did not agree on a protocol. Uses default.
-* Server certificate:
-*  subject: C=RU; ST=Saint Petersburg; L=Saint Petersburg; O=STD Petrovich; CN=*.petrovich.ru
-*  start date: Jan 28 11:21:01 2025 GMT
-*  expire date: Mar  1 11:21:00 2026 GMT
-*  subjectAltName: host "petrovich.ru" matched cert's "petrovich.ru"
-*  issuer: C=BE; O=GlobalSign nv-sa; CN=GlobalSign RSA OV SSL CA 2018
-*  SSL certificate verify ok.
-* using HTTP/1.x
-> HEAD / HTTP/1.1
-> Host: petrovich.ru
-> User-Agent: curl/7.88.1
-> Accept: */*
-> 
-* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
-* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
-* old SSL session ID is stale, removing
-< HTTP/1.1 200 OK
-HTTP/1.1 200 OK
-< Server: Variti/0.9.3a
-Server: Variti/0.9.3a
-< Date: Thu, 01 Jan 2026 00:0000 GMT
-Date: Thu, 01 Jan 2026 00:0000 GMT
-< Access-Control-Allow-Origin: *
-Access-Control-Allow-Origin: *
-< Content-Type: text/html
-Content-Type: text/html
-< Cache-Control: no-store
-Cache-Control: no-store
-< Expires: Thu, 01 Jan 2026 00:0000 GMT
-Expires: Thu, 01 Jan 2026 00:0000 GMT
-< Pragma: no-cache
-Pragma: no-cache
-< Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
-Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
-< Content-Type: text/html
-Content-Type: text/html
-< Content-Length: 31253
-Content-Length: 31253
-< Connection: keep-alive
-Connection: keep-alive
-< Keep-Alive: timeout=60
-Keep-Alive: timeout=60
-
-< 
-* Connection #0 to host petrovich.ru left intact
-
-```
-- We challenged ourselves, we kept trying and we didn't only *beat the air*: now, we have something to show you
-  - Do not just take our word for it? - This is great and we respect that: you can build your own `telemt` or download a build and check it right now
-### Telegram Calls via MTProxy
-- Telegram architecture **does NOT allow calls via MTProxy**, but only via SOCKS5, which cannot be obfuscated
-### How does DPI see MTProxy TLS?
-- DPI sees MTProxy in Fake TLS (ee) mode as TLS 1.3
-- the SNI you specify sends both the client and the server;
-- ALPN is similar to HTTP 1.1/2;
-- high entropy, which is normal for AES-encrypted traffic;
-### Whitelist on IP
-- MTProxy cannot work when there is: 
-  - no IP connectivity to the target host: Russian Whitelist on Mobile Networks - "Белый список"
-  - OR all TCP traffic is blocked
-  - OR high entropy/encrypted traffic is blocked: content filters at universities and critical infrastructure
-  - OR all TLS traffic is blocked
-  - OR specified port is blocked: use 443 to make it "like real"
-  - OR provided SNI is blocked: use "officially approved"/innocuous name
-- like most protocols on the Internet; 
-- these situations are observed:
-  - in China behind the Great Firewall
-  - in Russia on mobile networks, less in wired networks
-  - in Iran during "activity"
-### Too many open files
-- On a fresh Linux install the default open file limit is low; under load `telemt` may fail with `Accept error: Too many open files`
-- **Systemd**: add `LimitNOFILE=65536` to the `[Service]` section (already included in the example above)
-- **Docker**: add `--ulimit nofile=65536:65536` to your `docker run` command, or in `docker-compose.yml`:
-```yaml
-ulimits:
-  nofile:
-    soft: 65536
-    hard: 65536
-```
-- **System-wide** (optional): add to `/etc/security/limits.conf`:
-```
-*       soft    nofile  1048576
-*       hard    nofile  1048576
-root    soft    nofile  1048576
-root    hard    nofile  1048576
-```
-
+# Learn more about Telemt
+- [Our Architecture](docs/Architecture)
+- [All Config Options](docs/Config_params)
+- [How to build your own Telemt?](#build)
+- [Running on BSD](docs/Quick_start/OPENBSD_QUICK_START_GUIDE.en.md)
+- [Why Rust?](#why-rust)
 
 ## Build
 ```bash
@@ -194,9 +62,8 @@ cd telemt
 # Starting Release Build
 cargo build --release
 
-# Low-RAM devices (1 GB, e.g. NanoPi Neo3 / Raspberry Pi Zero 2):
-# release profile uses lto = "thin" to reduce peak linker memory.
-# If your custom toolchain overrides profiles, avoid enabling fat LTO.
+# Current release profile uses lto = "fat" for maximum optimization (see Cargo.toml).
+# On low-RAM systems (~1 GB) you can override it to "thin".
 
 # Move to /bin
 mv ./target/release/telemt /bin
@@ -206,12 +73,6 @@ chmod +x /bin/telemt
 telemt config.toml
 ```
 
-### OpenBSD
-- Build and service setup guide: [OpenBSD Guide (EN)](docs/OPENBSD.en.md)
-- Example rc.d script: [contrib/openbsd/telemt.rcd](contrib/openbsd/telemt.rcd)
-- Status: OpenBSD sandbox hardening with `pledge(2)` and `unveil(2)` is not implemented yet.
-
-
 ## Why Rust?
 - Long-running reliability and idempotent behavior
 - Rust's deterministic resource management - RAII 
@@ -219,23 +80,26 @@ telemt config.toml
 - Memory safety and reduced attack surface
 - Tokio's asynchronous architecture
 
-## Issues
-- ✅ [SOCKS5 as Upstream](https://github.com/telemt/telemt/issues/1) -> added Upstream Management
-- ✅ [iOS - Media Upload Hanging-in-Loop](https://github.com/telemt/telemt/issues/2)
+## Support Telemt
 
-## Roadmap
-- Public IP in links
-- Config Reload-on-fly
-- Bind to device or IP for outbound/inbound connections
-- Adtag Support per SNI / Secret
-- Fail-fast on start + Fail-soft on runtime (only WARN/ERROR)
-- Zero-copy, minimal allocs on hotpath
-- DC Healthchecks + global fallback
-- No global mutable state
-- Client isolation + Fair Bandwidth
-- Backpressure-aware IO
-- "Secret Policy" - SNI / Secret Routing :D
-- Multi-upstream Balancer and Failover
-- Strict FSM per handshake
-- Session-based Antireplay with Sliding window, non-broking reconnects
-- Web Control: statistic, state of health, latency, client experience...
+Telemt is free, open-source, and built in personal time.
+If it helps you — consider supporting continued development.
+
+Any cryptocurrency (BTC, ETH, USDT, 350+ coins):
+
+<p align="center">
+  <a href="https://nowpayments.io/donation?api_key=2bf1afd2-abc2-49f9-a012-f1e715b37223" target="_blank" rel="noreferrer noopener">
+    <img src="https://nowpayments.io/images/embeds/donation-button-white.svg" alt="Cryptocurrency & Bitcoin donation button by NOWPayments" height="80">
+  </a>
+</p>
+
+Monero (XMR) directly:
+
+```
+8Bk4tZEYPQWSypeD2hrUXG2rKbAKF16GqEN942ZdAP5cFdSqW6h4DwkP5cJMAdszzuPeHeHZPTyjWWFwzeFdjuci3ktfMoB
+```
+
+All donations go toward infrastructure, development and research
+
+
+![telemt_scheme](docs/assets/telemt.png)

README.ru.md

@@ -0,0 +1,99 @@
+# Telemt — MTProxy на Rust + Tokio
+
+[![Latest Release](https://img.shields.io/github/v/release/telemt/telemt?color=neon)](https://github.com/telemt/telemt/releases/latest) [![Stars](https://img.shields.io/github/stars/telemt/telemt?style=social)](https://github.com/telemt/telemt/stargazers) [![Forks](https://img.shields.io/github/forks/telemt/telemt?style=social)](https://github.com/telemt/telemt/network/members)
+
+> [!NOTE]
+>
+> Клиенты Telegram подвергаются блокировке по JA3-отпечатку; мы ищем варианты решения этой проблемы
+> 
+> Вы можете попробовать собрать свой клиент с нашей Telegram Devlibrary — [tdlib-obf](https://github.com/telemt/tdlib-obf)
+
+<p align="center">
+  <a href="https://t.me/telemtrs">
+    <img src="https://github.com/user-attachments/assets/30b7e7b9-974a-4e3d-aab6-b58a85de4507" width="240"/>
+  </a>
+</p>
+
+**Telemt** — это быстрый, безопасный и функциональный сервер, написанный на Rust: он полностью реализует официальный алгоритм Telegram прокси и добавляет множество различных улучшений
+
+## Установка и обновление одной командой
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
+```
+- [Инструкция по быстрому запуску](docs/Quick_start/QUICK_START_GUIDE.ru.md)
+
+## Функционал
+Наша реализация **TLS-fronting** одна из наиболее глубоко отлаженных, продвинутых и почти поведенчески неотличима от настоящего: мы уверены, что сделали это правильно - [см. доказательства в нашей проверке](docs/FAQ.ru.md#распознаваемость-для-dpi-и-сканеров).
+
+Наша архитектура ***Middle-End Pool*** в стандартных сценариях самая производительная, по сравнению с другими реализациями подключения к Middle-End прокси: не кардинально, но достаточно
+
+- Полная поддержа всех официальных режимов MTProto proxy:
+  - Classic;
+  - Secure — с префиксом `dd`;
+  - Fake TLS — с префиксом `ee` + SNI fronting;
+- Защита от replay-атак;
+- Опциональная маскировка трафика: перенаправление неизвестных подключений на реальные сайты;
+- Настраиваемые keepalive, таймауты, IPv6 и "быстрый режим";
+- Корректное завершение работы (Ctrl+C);
+- Подробное логирование через `trace` и `debug` с помощью `RUST_LOG`.
+
+## ЧаВо
+- [Часто задаваемые вопросы](docs/FAQ.ru.md)
+
+# Узнайте больше о Telemt
+- [Наша архитектура](docs/Architecture)
+- [Все конфигурационные параметры](docs/Config_params)
+- [Как собрать Telemt самостоятельно?](#сборка)
+- [Установка на BSD](docs/Quick_start/OPENBSD_QUICK_START_GUIDE.en.md)
+- [Почему Rust?](#почему-rust)
+
+## Сборка
+```bash
+# Клонируйте репозиторий
+git clone https://github.com/telemt/telemt 
+# Смените каталог на telemt
+cd telemt
+# Начните процесс сборки
+cargo build --release
+
+# В текущем release-профиле используется lto = "fat" для максимальной оптимизации (см. Cargo.toml).
+# На системах с малым объёмом ОЗУ (~1 ГБ) можно переопределить это значение на "thin".
+
+# Перейдите в каталог /bin
+mv ./target/release/telemt /bin
+# Сделайте файл исполняемым
+chmod +x /bin/telemt
+# Запустите!
+telemt config.toml
+```
+
+## Почему Rust?
+- Надёжность при длительной работе и идемпотентное поведение;
+- Детерминированное управление ресурсами — RAII;
+- Отсутствие сборщика мусора;
+- Безопасность памяти и меньше поверхность атаки;
+- Асинхронная архитектура Tokio.
+
+## Поддержать Telemt
+
+Telemt — это бесплатное программное обеспечение с открытым исходным кодом, разрабатываемое в свободное время.
+Если оно оказалось вам полезным, вы можете поддержать дальнейшую разработку.
+
+Любая криптовалюта (BTC, ETH, USDT и 350+ других):
+
+<p align="center">
+  <a href="https://nowpayments.io/donation?api_key=2bf1afd2-abc2-49f9-a012-f1e715b37223" target="_blank" rel="noreferrer noopener">
+    <img src="https://nowpayments.io/images/embeds/donation-button-white.svg" alt="Cryptocurrency & Bitcoin donation button by NOWPayments" height="80">
+  </a>
+</p>
+
+Monero (XMR) напрямую:
+
+```
+8Bk4tZEYPQWSypeD2hrUXG2rKbAKF16GqEN942ZdAP5cFdSqW6h4DwkP5cJMAdszzuPeHeHZPTyjWWFwzeFdjuci3ktfMoB
+```
+
+Все пожертвования пойдут на инфраструктуру, разработку и исследования.
+
+![telemt_scheme](docs/assets/telemt.png)

ROADMAP.md

@@ -1,34 +0,0 @@
-### 3.0.0 Anschluss
-- **Middle Proxy now is stable**, confirmed on canary-deploy over ~20 users
-- Ad-tag now is working
-- DC=203/CDN now is working over ME
-- `getProxyConfig` and `ProxySecret` are automated
-- Version order is now in format `3.0.0` - without Windows-style "microfixes"
-
-### 3.0.1 Kabelsammler
-- Handshake timeouts fixed
-- Connectivity logging refactored
-- Docker: tmpfs for ProxyConfig and ProxySecret
-- Public Host and Port in config
-- ME Relays Head-of-Line Blocking fixed
-- ME Ping
-
-### 3.0.2 Microtrencher
-- New [network] section
-- ME Fixes
-- Small bugs coverage
-
-### 3.0.3 Ausrutscher
-- ME as stateful, no conn-id migration
-- No `flush()` on datapath after RpcWriter
-- Hightech parser for IPv6 without regexp
-- `nat_probe = true` by default
-- Timeout for `recv()` in STUN-client
-- ConnRegistry review
-- Dualstack emergency reconnect
-
-### 3.0.4 Schneeflecken
-- Only WARN and Links in Normal log
-- Consistent IP-family detection
-- Includes for config
-- `nonce_frame_hex` in log only with `DEBUG`

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);

config.toml

@@ -32,13 +32,13 @@ show = "*"
 port = 443
 # proxy_protocol = false           # Enable if behind HAProxy/nginx with PROXY protocol
 # metrics_port = 9090
-# metrics_listen = "0.0.0.0:9090"  # Listen address for metrics (overrides metrics_port)
-# metrics_whitelist = ["127.0.0.1", "::1", "0.0.0.0/0"]
+# metrics_listen = "127.0.0.1:9090" # Listen address for metrics (overrides metrics_port)
+# metrics_whitelist = ["127.0.0.1/32", "::1/128"]
 
 [server.api]
 enabled = true
-listen = "0.0.0.0:9091"
-whitelist = ["127.0.0.0/8"]
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.1/32", "::1/128"]
 minimal_runtime_enabled = false
 minimal_runtime_cache_ttl_ms = 1000
 
@@ -48,9 +48,12 @@ ip = "0.0.0.0"
 
 # === Anti-Censorship & Masking ===
 [censorship]
+# Fake-TLS / SNI masking domain used in generated ee-links.
+# Changing tls_domain invalidates previously generated TLS links.
 tls_domain = "petrovich.ru"
+
 mask = true
-tls_emulation = true        # Fetch real cert lengths and emulate TLS records
+tls_emulation = true         # Fetch real cert lengths and emulate TLS records
 tls_front_dir = "tlsfront"   # Cache directory for TLS emulation
 
 [access.users]

docker-compose.host-netfilter.yml

@@ -0,0 +1,9 @@
+services:
+  telemt:
+    build:
+      context: .
+      target: prod-netfilter
+    network_mode: host
+    ports: !reset []
+    cap_add:
+      - NET_ADMIN

docker-compose.netfilter.yml

@@ -0,0 +1,8 @@
+services:
+  telemt:
+    build:
+      context: .
+      target: prod-netfilter
+    cap_add:
+      - NET_BIND_SERVICE
+      - NET_ADMIN

docker-compose.yml

@@ -1,31 +1,45 @@
 services:
   telemt:
     image: ghcr.io/telemt/telemt:latest
-    build: .
+    build:
+      context: .
+      target: prod
     container_name: telemt
     restart: unless-stopped
     ports:
       - "443:443"
       - "127.0.0.1:9090:9090"
       - "127.0.0.1:9091:9091"
-    # Allow caching 'proxy-secret' in read-only container
+    # Working dir uses tmpfs for caching 'proxy-secret' at runtime.
+    # Config is mounted as a directory (not a single file) so the API can
+    # atomically update config.toml via write-temp → rename within the same FS.
     working_dir: /run/telemt
+    command: ["/etc/telemt/config.toml"]
     volumes:
-      - ./config.toml:/run/telemt/config.toml:ro
+      - ./config:/etc/telemt:rw
     tmpfs:
-      - /run/telemt:rw,mode=1777,size=1m
+      - /run/telemt:rw,mode=1777,size=4m
     environment:
       - RUST_LOG=info
-    # Uncomment this line if you want to use host network for IPv6, but bridge is default and usually better
-    # network_mode: host
+    healthcheck:
+      test: [ "CMD", "/app/telemt", "healthcheck", "/etc/telemt/config.toml", "--mode", "liveness" ]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 20s
     cap_drop:
       - ALL
     cap_add:
-      - NET_BIND_SERVICE   # allow binding to port 443
+      - NET_BIND_SERVICE
     read_only: true
     security_opt:
       - no-new-privileges:true
     ulimits:
       nofile:
         soft: 65536
-        hard: 65536
+        hard: 262144
+    logging:
+      driver: json-file
+      options:
+        max-size: "50m"
+        max-file: "5"

docs/Advanced_settings/HIGH_LOAD.en.md

@@ -0,0 +1,141 @@
+# High-Load Configuration & Tuning Guide
+When deploying Telemt under high-traffic load (tens or hundreds of thousands of concurrent connections), the standard OS network stack limits can lead to packet drops, high CPU context switching, and connection failures. This guide covers Linux kernel tuning, hardware configuration, and architecture optimizations required to prepare the server for high-load scenarios.
+
+---
+## 1. System Limits & File Descriptors
+Every TCP connection requires a file descriptor. At 100k connections, standard Linux limits (often 1024 or 65535) will be exhausted immediately.
+### System-Wide Limits (`sysctl`)
+Increase the global file descriptor limit in `/etc/sysctl.conf`:
+```ini
+fs.file-max = 2097152
+fs.nr_open = 2097152
+```
+### User-Level Limits (`limits.conf`)
+Edit `/etc/security/limits.conf` to allow the telemt (or proxy) user to allocate them:
+```conf
+* soft nofile 1048576
+* hard nofile 1048576
+root soft nofile 1048576
+root hard nofile 1048576
+```
+### Systemd / Docker Overrides
+If using **Systemd**, add to your `telemt.service`:
+```ini
+[Service]
+LimitNOFILE=1048576
+LimitNPROC=65535
+TasksMax=infinity
+```
+If using **Docker**, configure `ulimits` in `docker-compose.yaml`:
+```yaml
+services:
+  telemt:
+    ulimits:
+      nofile:
+        soft: 1048576
+        hard: 1048576
+```
+
+---
+## 2. Kernel Network Stack Tuning (`sysctl`)
+Create a dedicated file `/etc/sysctl.d/99-telemt-highload.conf` and apply it via `sysctl -p /etc/sysctl.d/99-telemt-highload.conf`.
+### 2.1 Connection Queues & SYN Flood Protection
+Increase the size of accept queues to absorb sudden connection spikes (bursts) and mitigate SYN floods:
+```ini
+net.core.somaxconn = 65535
+net.core.netdev_max_backlog = 65535
+net.ipv4.tcp_max_syn_backlog = 65535
+net.ipv4.tcp_syncookies = 1
+```
+### 2.2 Port Exhaustion & TIME-WAIT Sockets
+High churn rates lead to ephemeral port exhaustion. Expand the range and rapidly recycle closed sockets:
+```ini
+net.ipv4.ip_local_port_range = 10000 65535
+net.ipv4.tcp_fin_timeout = 15
+net.ipv4.tcp_tw_reuse = 1
+net.ipv4.tcp_max_tw_buckets = 2000000
+```
+### 2.3 TCP Keepalive (Aggressive Dead Connection Culling)
+By default, Linux keeps silent, dropped connections open for over 2 hours. This consumes memory at scale. Configure the system to detect and drop them in < 5 minutes:
+```ini
+net.ipv4.tcp_keepalive_time = 300
+net.ipv4.tcp_keepalive_intvl = 30
+net.ipv4.tcp_keepalive_probes = 5
+```
+### 2.4 TCP Buffers & Congestion Control
+Optimize memory usage per socket and switch to BBR (Bottleneck Bandwidth and Round-trip propagation time) to improve latency on lossy networks:
+```ini
+# Core buffer sizes
+net.core.rmem_default = 262144
+net.core.wmem_default = 262144
+net.core.rmem_max = 16777216
+net.core.wmem_max = 16777216
+# TCP specific buffers (min, default, max)
+net.ipv4.tcp_rmem = 4096 87380 16777216
+net.ipv4.tcp_wmem = 4096 65536 16777216
+# Enable BBR
+net.core.default_qdisc = fq
+net.ipv4.tcp_congestion_control = bbr
+```
+
+---
+## 3. Conntrack (Netfilter) Tuning
+If your server uses `iptables`, `ufw`, or `firewalld`, the Linux kernel tracks every connection state in a table (`nf_conntrack`). When this table fills up, Linux drops new packets.
+Check your current limit and usage:
+```bash
+sysctl net.netfilter.nf_conntrack_max
+sysctl net.netfilter.nf_conntrack_count
+```
+If it gets close to the limit, tune it up, and reduce the time established connections linger in the tracker:
+```ini
+# In /etc/sysctl.d/99-telemt-highload.conf
+net.netfilter.nf_conntrack_max = 2097152
+# Reduce timeout from default 5 days to 1 hour
+net.netfilter.nf_conntrack_tcp_timeout_established = 3600
+net.netfilter.nf_conntrack_tcp_timeout_time_wait = 12
+```
+*Note: Depending on your OS, you may need to run `modprobe nf_conntrack` before setting these parameters.*
+
+---
+## 4. Multi-Tier Architecture: HAProxy Setup
+For massive traffic loads, buffering Telemt behind a reverse proxy like HAProxy can help absorb connection spikes and handle basic TCP connections before handing them off.
+### HAProxy High-Load `haproxy.cfg`
+```haproxy
+global
+    # Disable detailed logging under load
+    log stdout format raw local0 err
+    # maxconn 250000
+    
+    # Buffer tuning
+    tune.bufsize 16384
+    tune.maxaccept 64
+defaults
+    log     global
+    mode    tcp
+    option  clitcpka
+    option  srvtcpka
+    timeout connect 5s
+    timeout client  1h
+    timeout server  1h
+    # Quick purge for dead peers
+    timeout client-fin 10s
+    timeout server-fin 10s
+frontend proxy_in
+    bind *:443
+    maxconn 250000
+    option tcp-smart-accept
+    default_backend telemt_backend
+backend telemt_backend
+    option tcp-smart-connect
+    # Send-Proxy-V2 to preserve Client IP for Telemt's internal logic
+    server telemt_core 10.10.10.1:443 maxconn 250000 send-proxy-v2 check inter 5s
+```
+**Important**: Telemt must be configured to process the `PROXY` protocol on port `443` for this chain to work and preserve client IPs.
+
+---
+## 5. Diagnostics & Monitoring
+When operating under load, these commands are useful for diagnostics:
+* **Checking dropped connections (Queues full)**: `netstat -s | grep "times the listen queue of a socket overflowed"`
+* **Checking Conntrack drops**: `dmesg | grep conntrack`
+* **Checking File Descriptor usage**: `cat /proc/sys/fs/file-nr`
+* **Real-time connection states**: `ss -s` (Avoid using `netstat` on heavy loads).

docs/Advanced_settings/HIGH_LOAD.ru.md

@@ -0,0 +1,139 @@
+# Руководство по High-Load конфигурации и тюнингу
+При развертывании Telemt под высокой нагрузкой (десятки и сотни тысяч одновременных подключений), стандартные ограничения сетевого стека ОС могут приводить к потерям пакетов, переключениям контекста CPU и отказам в соединениях. В данном руководстве описана настройка ядра Linux, системных лимитов и аппаратной конфигурации для работы в подобных сценариях.
+
+---
+## 1. Системные лимиты и файловые дескрипторы
+Каждое TCP-сосоединение требует файлового дескриптора. При 100 тысячах соединений стандартные лимиты Linux (зачастую 1024 или 65535) будут исчерпаны немедленно.
+### Общесистемные лимиты (`sysctl`)
+Увеличьте глобальный лимит файловых дескрипторов в `/etc/sysctl.conf`:
+```ini
+fs.file-max = 2097152
+fs.nr_open = 2097152
+```
+### На уровне пользователя (`limits.conf`)
+Отредактируйте `/etc/security/limits.conf`, чтобы разрешить пользователю (от которого запущен telemt) резервировать дескрипторы:
+```conf
+* soft nofile 1048576
+* hard nofile 1048576
+root soft nofile 1048576
+root hard nofile 1048576
+```
+### Переопределения для Systemd / Docker
+Если используется **Systemd**, добавьте в ваш `telemt.service`:
+```ini
+[Service]
+LimitNOFILE=1048576
+LimitNPROC=65535
+TasksMax=infinity
+```
+Если используется **Docker**, задайте `ulimits` в `docker-compose.yaml`:
+```yaml
+services:
+  telemt:
+    ulimits:
+      nofile:
+        soft: 1048576
+        hard: 1048576
+```
+
+---
+## 2. Тонкая настройка сетевого стека ядра (`sysctl`)
+Создайте выделенный файл `/etc/sysctl.d/99-telemt-highload.conf` и примените его через `sysctl -p /etc/sysctl.d/99-telemt-highload.conf`.
+### 2.1 Очереди соединений и защита от SYN-флуда
+Увеличьте размеры очередей, чтобы поглощать внезапные всплески соединений и смягчить атаки типа SYN flood:
+```ini
+net.core.somaxconn = 65535
+net.core.netdev_max_backlog = 65535
+net.ipv4.tcp_max_syn_backlog = 65535
+net.ipv4.tcp_syncookies = 1
+```
+### 2.2 Исчерпание портов и TIME-WAIT сокеты
+Высокая текучесть приводит к нехватке временных (ephemeral) портов. Расширьте диапазон портов и позвольте ядру быстро переиспользовать закрытые сокеты:
+```ini
+net.ipv4.ip_local_port_range = 10000 65535
+net.ipv4.tcp_fin_timeout = 15
+net.ipv4.tcp_tw_reuse = 1
+net.ipv4.tcp_max_tw_buckets = 2000000
+```
+### 2.3 TCP Keepalive (Агрессивная очистка мертвых соединений)
+По умолчанию Linux держит "оборванные" TCP-сессии более 2 часов. Задайте параметры для обнаружения и сброса мертвых соединений за менее чем 5 минут:
+```ini
+net.ipv4.tcp_keepalive_time = 300
+net.ipv4.tcp_keepalive_intvl = 30
+net.ipv4.tcp_keepalive_probes = 5
+```
+### 2.4 Буферы TCP и управление перегрузками (Congestion Control)
+Оптимизируйте использование памяти на сокет и переключитесь на алгоритм BBR (Bottleneck Bandwidth and Round-trip propagation time) для улучшения задержки на плохих сетях:
+```ini
+# Размеры буферов ядра (по умолчанию и макс)
+net.core.rmem_default = 262144
+net.core.wmem_default = 262144
+net.core.rmem_max = 16777216
+net.core.wmem_max = 16777216
+# Специфичные TCP буферы (min, default, max)
+net.ipv4.tcp_rmem = 4096 87380 16777216
+net.ipv4.tcp_wmem = 4096 65536 16777216
+# Включение BBR
+net.core.default_qdisc = fq
+net.ipv4.tcp_congestion_control = bbr
+```
+
+---
+## 3. Тюнинг Conntrack (Netfilter)
+Если ваш сервер использует `iptables`, `ufw` или `firewalld`, ядро вынуждено отслеживать каждое соединение в таблице состояний (`nf_conntrack`). Когда эта таблица переполняется, Linux отбрасывает новые пакеты без уведомления приложения.
+Проверьте текущие лимиты и использование:
+```bash
+sysctl net.netfilter.nf_conntrack_max
+sysctl net.netfilter.nf_conntrack_count
+```
+Если вы близки к пределу, увеличьте таблицу и заставьте ядро быстрее удалять установленные соединения. Добавьте в `/etc/sysctl.d/99-telemt-highload.conf`:
+```ini
+net.netfilter.nf_conntrack_max = 2097152
+# Снижаем таймаут с дефолтных 5 дней до 1 часа
+net.netfilter.nf_conntrack_tcp_timeout_established = 3600
+net.netfilter.nf_conntrack_tcp_timeout_time_wait = 12
+```
+*Внимание: в зависимости от ОС, вам может потребоваться выполнить `modprobe nf_conntrack` перед установкой этих параметров.*
+
+---
+## 4. Архитектура: Развертывание за HAProxy
+Для максимальных нагрузок выставление Telemt напрямую в интернет менее эффективно, чем использование оптимизированного L4-балансировщика. HAProxy эффективен в поглощении TCP атак, обработке рукопожатий и сглаживании всплесков подключений.
+### Оптимизация `haproxy.cfg` для High-Load
+```haproxy
+global
+    # Отключить детальные логи соединений под нагрузкой
+    log stdout format raw local0 err
+    maxconn 250000
+    # Тюнинг буферов и приема сокетов
+    tune.bufsize 16384
+    tune.maxaccept 64
+defaults
+    log     global
+    mode    tcp
+    option  clitcpka
+    option  srvtcpka
+    timeout connect 5s
+    timeout client  1h
+    timeout server  1h
+    # Быстрая очистка мертвых пиров
+    timeout client-fin 10s
+    timeout server-fin 10s
+frontend proxy_in
+    bind *:443
+    maxconn 250000
+    option tcp-smart-accept
+    default_backend telemt_backend
+backend telemt_backend
+    option tcp-smart-connect
+    # Send-Proxy-V2 обязателен для сохранения IP клиента внутри внутренней логики Telemt
+    server telemt_core 10.10.10.1:443 maxconn 250000 send-proxy-v2 check inter 5s
+```
+**Важно**: Telemt должен быть настроен на обработку протокола `PROXY` на порту `443`, чтобы получать оригинальные IP-адреса клиентов.
+
+---
+## 5. Диагностика
+Команды для выявления узких мест:
+* **Проверка дропов TCP (переполнение очередей)**: `netstat -s | grep "times the listen queue of a socket overflowed"`
+* **Контроль отбрасывания пакетов Conntrack**: `dmesg | grep conntrack`
+* **Проверка использования файловых дескрипторов**: `cat /proc/sys/fs/file-nr`
+* **Отображение состояния сокетов**: `ss -s` (Избегайте использования `netstat` под высокой нагрузкой).

docs/Advanced_settings/TUNING.de.md

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

docs/Advanced_settings/TUNING.en.md

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

docs/Advanced_settings/TUNING.ru.md

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

docs/Architecture/API/API.md

@@ -9,12 +9,12 @@ API runtime is configured in `[server.api]`.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
-| `enabled` | `bool` | `false` | Enables REST API listener. |
-| `listen` | `string` (`IP:PORT`) | `127.0.0.1:9091` | API bind address. |
-| `whitelist` | `CIDR[]` | `127.0.0.1/32, ::1/128` | Source IP allowlist. Empty list means allow all. |
+| `enabled` | `bool` | `true` | Enables REST API listener. |
+| `listen` | `string` (`IP:PORT`) | `0.0.0.0:9091` | API bind address. |
+| `whitelist` | `CIDR[]` | `127.0.0.0/8` | Source IP allowlist. Empty list means allow all. |
 | `auth_header` | `string` | `""` | Exact value for `Authorization` header. Empty disables header auth. |
-| `request_body_limit_bytes` | `usize` | `65536` | Maximum request body size. Must be `> 0`. |
-| `minimal_runtime_enabled` | `bool` | `false` | Enables runtime snapshot endpoints requiring ME pool read-lock aggregation. |
+| `request_body_limit_bytes` | `usize` | `65536` | Maximum request body size. Must be within `[1, 1048576]`. |
+| `minimal_runtime_enabled` | `bool` | `true` | Enables runtime snapshot endpoints requiring ME pool read-lock aggregation. |
 | `minimal_runtime_cache_ttl_ms` | `u64` | `1000` | Cache TTL for minimal snapshots. `0` disables cache; valid range is `[0, 60000]`. |
 | `runtime_edge_enabled` | `bool` | `false` | Enables runtime edge endpoints with cached aggregation payloads. |
 | `runtime_edge_cache_ttl_ms` | `u64` | `1000` | Cache TTL for runtime edge summary payloads. `0` disables cache. |
@@ -26,7 +26,7 @@ API runtime is configured in `[server.api]`.
 
 Runtime validation for API config:
 - `server.api.listen` must be a valid `IP:PORT`.
-- `server.api.request_body_limit_bytes` must be `> 0`.
+- `server.api.request_body_limit_bytes` must be within `[1, 1048576]`.
 - `server.api.minimal_runtime_cache_ttl_ms` must be within `[0, 60000]`.
 - `server.api.runtime_edge_cache_ttl_ms` must be within `[0, 60000]`.
 - `server.api.runtime_edge_top_n` must be within `[1, 1000]`.
@@ -76,13 +76,14 @@ Requests are processed in this order:
 
 Notes:
 - Whitelist is evaluated against the direct TCP peer IP (`SocketAddr::ip`), without `X-Forwarded-For` support.
-- `Authorization` check is exact string equality against configured `auth_header`.
+- `Authorization` check is exact constant-time byte equality against configured `auth_header`.
 
 ## Endpoint Matrix
 
 | Method | Path | Body | Success | `data` contract |
 | --- | --- | --- | --- | --- |
 | `GET` | `/v1/health` | none | `200` | `HealthData` |
+| `GET` | `/v1/health/ready` | none | `200` or `503` | `HealthReadyData` |
 | `GET` | `/v1/system/info` | none | `200` | `SystemInfoData` |
 | `GET` | `/v1/runtime/gates` | none | `200` | `RuntimeGatesData` |
 | `GET` | `/v1/runtime/initialization` | none | `200` | `RuntimeInitializationData` |
@@ -102,41 +103,100 @@ Notes:
 | `GET` | `/v1/runtime/me-selftest` | none | `200` | `RuntimeMeSelftestData` |
 | `GET` | `/v1/runtime/connections/summary` | none | `200` | `RuntimeEdgeConnectionsSummaryData` |
 | `GET` | `/v1/runtime/events/recent` | none | `200` | `RuntimeEdgeEventsData` |
+| `GET` | `/v1/runtime/tls-fingerprints` | optional `limit=1..1000` | `200` | `RuntimeEdgeTlsFingerprintsData` |
+| `GET` | `/v1/stats/users/active-ips` | none | `200` | `UserActiveIps[]` |
 | `GET` | `/v1/stats/users` | none | `200` | `UserInfo[]` |
+| `GET` | `/v1/config` | none | `200` | `ConfigData` |
+| `PATCH` | `/v1/config` | sparse JSON object; optional reload query | `200` or `202` | `PatchConfigResponse` |
+| `POST` | `/v1/system/reload` | `ReloadRequest` or empty body | `202` | `ReloadAccepted` |
+| `GET` | `/v1/system/reload/{id}` | none | `200` | `ReloadStatus` |
 | `GET` | `/v1/users` | none | `200` | `UserInfo[]` |
-| `POST` | `/v1/users` | `CreateUserRequest` | `201` | `CreateUserResponse` |
+| `POST` | `/v1/users` | `CreateUserRequest` | `201` or `202` | `CreateUserResponse` |
 | `GET` | `/v1/users/{username}` | none | `200` | `UserInfo` |
-| `PATCH` | `/v1/users/{username}` | `PatchUserRequest` | `200` | `UserInfo` |
-| `DELETE` | `/v1/users/{username}` | none | `200` | `string` (deleted username) |
-| `POST` | `/v1/users/{username}/rotate-secret` | `RotateSecretRequest` or empty body | `404` | `ErrorResponse` (`not_found`, current runtime behavior) |
+| `PATCH` | `/v1/users/{username}` | `PatchUserRequest` | `200` or `202` | `UserInfo` |
+| `DELETE` | `/v1/users/{username}` | none | `200` or `202` | `DeleteUserResponse` |
+| `POST` | `/v1/users/{username}/rotate-secret` | `RotateSecretRequest` or empty body | `200` or `202` | `CreateUserResponse` |
+| `POST` | `/v1/users/{username}/enable` | empty body | `200` or `202` | `UserInfo` |
+| `POST` | `/v1/users/{username}/disable` | empty body | `200` or `202` | `UserInfo` |
+| `POST` | `/v1/users/{username}/reset-quota` | empty body | `200` | `ResetUserQuotaResponse` |
+
+## Endpoint Behavior
+
+| Endpoint | Function |
+| --- | --- |
+| `GET /v1/health` | Returns basic API liveness and current `read_only` flag. |
+| `GET /v1/health/ready` | Returns readiness based on admission state and upstream health; returns `503` when not ready. |
+| `GET /v1/system/info` | Returns binary/build metadata, process uptime, config path/hash, and reload counters. |
+| `GET /v1/runtime/gates` | Returns admission, ME readiness, fallback/reroute, and startup gate state. |
+| `GET /v1/runtime/initialization` | Returns startup progress, ME initialization status, and per-component timeline. |
+| `GET /v1/limits/effective` | Returns effective timeout, upstream, ME, unique-IP, and TCP policy values after config defaults/resolution. |
+| `GET /v1/security/posture` | Returns current API/security/telemetry posture flags. |
+| `GET /v1/security/whitelist` | Returns configured API whitelist CIDRs. |
+| `GET /v1/stats/summary` | Returns compact core counters and classed failure counters. |
+| `GET /v1/stats/zero/all` | Returns zero-cost core, upstream, ME, pool, and desync counters. |
+| `GET /v1/stats/upstreams` | Returns upstream zero counters and, when enabled/available, runtime upstream health rows. |
+| `GET /v1/stats/minimal/all` | Returns cached minimal ME writer/DC/runtime/network-path snapshot. |
+| `GET /v1/stats/me-writers` | Returns cached ME writer coverage and per-writer status rows. |
+| `GET /v1/stats/dcs` | Returns cached per-DC endpoint/writer/load status rows. |
+| `GET /v1/runtime/me_pool_state` | Returns active/warm/pending/draining generation state, writer contour/health, and refill state. |
+| `GET /v1/runtime/me_quality` | Returns ME lifecycle counters, route-drop counters, family states, drain gate, and per-DC RTT/coverage. |
+| `GET /v1/runtime/upstream_quality` | Returns upstream policy/counters plus runtime upstream health rows when available. |
+| `GET /v1/runtime/nat_stun` | Returns NAT/STUN runtime flags, configured/live STUN servers, reflection cache, and backoff. |
+| `GET /v1/runtime/me-selftest` | Returns ME self-test state for KDF, time skew, IP family, PID, and SOCKS BND observations. |
+| `GET /v1/runtime/connections/summary` | Returns runtime-edge connection totals and top-N users by connections/throughput. |
+| `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 and optionally submits an in-process runtime reload to Maestro. |
+| `POST /v1/system/reload` | Loads and validates the current on-disk config, then asks Maestro to prepare and activate a new runtime generation. |
+| `GET /v1/system/reload/{id}` | Returns one retained reload status; the coordinator retains the most recent 32 operations. |
+| `GET /v1/users` | Returns disk-first user views sorted by username. |
+| `POST /v1/users` | Creates a user and returns the effective user view plus secret. |
+| `GET /v1/users/{username}` | Returns one disk-first user view or `404` when absent. |
+| `PATCH /v1/users/{username}` | Updates selected per-user fields with JSON Merge Patch semantics. |
+| `DELETE /v1/users/{username}` | Deletes one user and related per-user access-map entries. |
+| `POST /v1/users/{username}/rotate-secret` | Rotates one user's secret and returns the effective secret. |
+| `POST /v1/users/{username}/enable` | Enables one user, removing any disabled override from config. |
+| `POST /v1/users/{username}/disable` | Disables one user and closes active runtime sessions for that user. |
+| `POST /v1/users/{username}/reset-quota` | Resets one user's runtime quota counter and persists quota state. |
 
 ## Common Error Codes
 
 | 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 `network` or an unknown top-level key. |
+| `400` | `field_not_editable` | `PATCH /v1/config` body contains a forbidden nested field under a partially editable section (e.g. `server.api`, `server.port`). |
 | `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`. |
-| `404` | `not_found` | Unknown route, unknown user, or unsupported sub-route (including current `rotate-secret` route). |
+| `404` | `not_found` | Unknown route, unknown user, or unsupported sub-route. |
 | `405` | `method_not_allowed` | Unsupported method for `/v1/users/{username}` route shape. |
 | `409` | `revision_conflict` | `If-Match` revision mismatch. |
+| `409` | `reload_in_progress` | Another reload operation is non-terminal. |
 | `409` | `user_exists` | User already exists on create. |
 | `409` | `last_user_forbidden` | Attempt to delete last configured user. |
 | `413` | `payload_too_large` | Body exceeds `request_body_limit_bytes`. |
 | `500` | `internal_error` | Internal error (I/O, serialization, config load/save). |
 | `503` | `api_disabled` | API disabled in config. |
+| `503` | `maestro_unavailable` | Maestro's reload command channel is unavailable. |
 
 ## Routing and Method Edge Cases
 
 | Case | Behavior |
 | --- | --- |
 | Path matching | Exact match on `req.uri().path()`. Query string does not affect route matching. |
-| Trailing slash | Not normalized. Example: `/v1/users/` is `404`. |
+| 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` | `404 not_found` in current release due route matcher limitation. |
+| `POST /v1/users/{username}/rotate-secret/` | Trailing slash is trimmed and the route matches `rotate-secret`. |
+| `POST /v1/users/{username}/enable/` | Trailing slash is trimmed and the route matches `enable`. |
+| `POST /v1/users/{username}/disable/` | Trailing slash is trimmed and the route matches `disable`. |
+| `POST /v1/users/{username}/reset-quota/` | Trailing slash is trimmed and the route matches `reset-quota`. |
 
 ## Body and JSON Semantics
 
@@ -146,7 +206,7 @@ Notes:
 - Invalid JSON returns `400 bad_request` (`Invalid JSON body`).
 - `Content-Type` is not required for JSON parsing.
 - Unknown JSON fields are ignored by deserialization.
-- `PATCH` updates only provided fields and does not support explicit clearing of optional fields.
+- `PATCH` uses JSON Merge Patch semantics for optional per-user fields: omitted means unchanged, explicit `null` removes the config entry, and a non-null value sets it.
 - `If-Match` supports both quoted and unquoted values; surrounding whitespace is trimmed.
 
 ## Query Parameters
@@ -166,42 +226,163 @@ 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 bits per second. |
+| `rate_limit_down_bps` | `u64` | no | Per-user download rate limit in bits per second. |
 | `max_unique_ips` | `usize` | no | Per-user unique source IP limit. |
+| `enabled` | `bool` | no | User enable flag. Missing means enabled. `false` persists a disabled override. |
 
 ### `PatchUserRequest`
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
 | `secret` | `string` | no | Exactly 32 hex chars. |
-| `user_ad_tag` | `string` | no | Exactly 32 hex chars. |
-| `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. |
-| `max_unique_ips` | `usize` | no | Per-user unique source IP limit. |
+| `user_ad_tag` | `string|null` | no | Exactly 32 hex chars; `null` removes the per-user ad tag. |
+| `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 bits per second; `null` removes the upload direction limit. |
+| `rate_limit_down_bps` | `u64|null` | no | Per-user download rate limit in bits per second; `null` removes the download direction limit. |
+| `max_unique_ips` | `usize|null` | no | Per-user unique source IP limit; `null` removes the per-user override. |
+| `enabled` | `bool|null` | no | `false` disables the user. `true` or `null` removes the disabled override, so the user is enabled. |
+
+### `access.user_source_deny` via API
+- In current API surface, per-user deny-list is **not** exposed as a dedicated field in `CreateUserRequest` / `PatchUserRequest`.
+- Configure it in `config.toml` under `[access.user_source_deny]` and apply via normal config reload path.
+- Runtime behavior after apply:
+  - auth succeeds for username/secret
+  - source IP is checked against `access.user_source_deny[username]`
+  - on match, handshake is rejected with the same fail-closed outcome as invalid auth
+
+Example config:
+```toml
+[access.user_source_deny]
+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`, `dc_overrides`) or the partially editable `server` object (only `listeners` is allowed under `server`; see below). 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`).
+- `network`, `web`, or any unknown top-level key → `400 section_not_editable`.
+- `server` with any key other than `listeners` (e.g. `port`, `api`, `admin_api`) → `400 field_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"}}
+```
+
+Example — replace `[[server.listeners]]` (other `[server]` fields including `[server.api]` are preserved):
+```json
+{"server": {"listeners": [{"ip": "0.0.0.0", "port": 443, "client_mss": "92"}]}}
+```
 
 ### `RotateSecretRequest`
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
 | `secret` | `string` | no | Exactly 32 hex chars. If missing, generated automatically. |
 
-Note: the request contract is defined, but the corresponding route currently returns `404` (see routing edge cases).
+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. |
+| `dc_overrides` | `object?` | `[dc_overrides]` section, if present. |
+| `server` | `object?` | Partial `[server]` view when editable nested fields are present. Currently only `listeners` may appear; `api`/`admin_api`, `port`, unix sockets, and other bind-identity fields are never returned. |
+
+Sections absent from the config file are absent from the response (not `null`). Only the editable sections above are returned; `access` (users/secrets) and `network` (per-node addresses) are always excluded. Under `server`, only the nested field-level allowlist (`listeners`) is exposed.
+
+### `PatchConfigResponse`
+
+Returned by `PATCH /v1/config` on success (`200`, or `202` when a reload was accepted).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `revision` | `string` | SHA-256 hex of the config file after the patch was written. |
+| `restart_required` | `bool` | Legacy classifier result: `true` when the old file watcher alone cannot apply every changed field. Use `runtime_reload_required` and `process_restart_required` for new integrations. |
+| `runtime_reload_required` | `bool` | `true` when full effect requires a Maestro runtime-generation reload rather than the legacy hot-field overlay. |
+| `process_restart_required` | `bool` | `true` when process-owned sockets or paths changed and remain deferred after an in-process reload. |
+| `deferred_process_fields` | `string[]` | Process-owned fields that the active process cannot rebind during generation activation. |
+| `changed` | `string[]` | Top-level section names that differed between the old and new config (e.g. `["censorship"]`). |
+| `reload` | `ReloadAccepted?` | Present only when the patch included a valid reload query and Maestro accepted the operation. |
+
 ### `HealthData`
 | Field | Type | Description |
 | --- | --- | --- |
 | `status` | `string` | Always `"ok"`. |
 | `read_only` | `bool` | Mirrors current API `read_only` mode. |
 
+### `HealthReadyData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `ready` | `bool` | `true` when admission is open and at least one upstream is healthy. |
+| `status` | `string` | `"ready"` or `"not_ready"`. |
+| `reason` | `string?` | `admission_closed` or `no_healthy_upstreams` when not ready. |
+| `admission_open` | `bool` | Current admission-gate state. |
+| `healthy_upstreams` | `usize` | Number of healthy upstream entries. |
+| `total_upstreams` | `usize` | Number of configured upstream entries. |
+
 ### `SummaryData`
 | Field | Type | Description |
 | --- | --- | --- |
 | `uptime_seconds` | `f64` | Process uptime in seconds. |
 | `connections_total` | `u64` | Total accepted client connections. |
 | `connections_bad_total` | `u64` | Failed/invalid client connections. |
+| `connections_bad_by_class` | `ClassCount[]` | Failed/invalid connections grouped by class. |
+| `handshake_failures_by_class` | `ClassCount[]` | Handshake failures grouped by class. |
+| `handshake_failures_by_stage` | `StageCount[]` | Handshake failures grouped by state-machine stage. |
 | `handshake_timeouts_total` | `u64` | Handshake timeout count. |
 | `configured_users` | `usize` | Number of configured users in config. |
 
+#### `ClassCount`
+| Field | Type | Description |
+| --- | --- | --- |
+| `class` | `string` | Failure class label. |
+| `total` | `u64` | Counter value for this class. |
+
+#### `StageCount`
+| Field | Type | Description |
+| --- | --- | --- |
+| `stage` | `string` | State-machine stage label. |
+| `total` | `u64` | Counter value for this stage. |
+
+#### Handshake failure stage diagnostics
+
+`handshake_failures_by_class` and `telemt_handshake_failures_by_class_total` describe the error kind. `handshake_failures_by_stage` and `telemt_handshake_failures_by_stage_total` describe where the same failure happened in the handshake state machine.
+
+This does not add a DPI verdict or any protocol decision. The stage is derived from the existing Telemt handshake control flow and is counted only when the existing handshake failure or timeout accounting path is reached.
+
+Fixed stage labels:
+
+| Stage | Meaning |
+| --- | --- |
+| `first_packet_prelude` | Reading the first 5 bytes before selecting the TLS or direct branch. |
+| `tls_clienthello_body` | Reading the TLS ClientHello body after the TLS record header. |
+| `tls_core` | Running the TLS-F handshake/auth flow. |
+| `tls_post_serverhello_mtproto` | Waiting for the 64-byte MTProto handshake after TLS ServerHello. |
+| `direct_mtproto` | Reading the direct classic/secure 64-byte MTProto handshake. |
+
+Example:
+
+```text
+telemt_handshake_failures_by_class_total{class="expected_64_got_0_unexpected_eof"} 3
+telemt_handshake_failures_by_stage_total{stage="direct_mtproto"} 1
+telemt_handshake_failures_by_stage_total{stage="tls_post_serverhello_mtproto"} 2
+```
+
+This means the same EOF-while-reading-64-bytes failure happened once in the direct MTProto path and twice after TLS ServerHello.
+
 ### `SystemInfoData`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -226,7 +407,12 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `conditional_cast_enabled` | `bool` | Whether conditional ME admission logic is enabled (`general.use_middle_proxy`). |
 | `me_runtime_ready` | `bool` | Current ME runtime readiness status used for conditional gate decisions. |
 | `me2dc_fallback_enabled` | `bool` | Whether ME -> direct fallback is enabled. |
+| `me2dc_fast_enabled` | `bool` | Whether fast ME -> direct fallback is enabled. |
 | `use_middle_proxy` | `bool` | Current transport mode preference. |
+| `route_mode` | `string` | Current route mode label from route runtime controller. |
+| `reroute_active` | `bool` | `true` when ME fallback currently routes new sessions to Direct-DC. |
+| `reroute_to_direct_at_epoch_secs` | `u64?` | Unix timestamp when current direct reroute began. |
+| `reroute_reason` | `string?` | `startup_direct_fallback`, `fast_not_ready_fallback`, or `strict_grace_fallback` while reroute is active. |
 | `startup_status` | `string` | Startup status (`pending`, `initializing`, `ready`, `failed`, `skipped`). |
 | `startup_stage` | `string` | Current startup stage identifier. |
 | `startup_progress_pct` | `f64` | Startup progress percentage (`0..100`). |
@@ -277,11 +463,13 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `upstream` | `EffectiveUpstreamLimits` | Effective upstream connect/retry limits. |
 | `middle_proxy` | `EffectiveMiddleProxyLimits` | Effective ME pool/floor/reconnect limits. |
 | `user_ip_policy` | `EffectiveUserIpPolicyLimits` | Effective unique-IP policy mode/window. |
+| `user_tcp_policy` | `EffectiveUserTcpPolicyLimits` | Effective per-user TCP connection policy. |
 
 #### `EffectiveTimeoutLimits`
 | Field | Type | Description |
 | --- | --- | --- |
 | `client_handshake_secs` | `u64` | Client handshake timeout. |
+| `client_first_byte_idle_secs` | `u64` | First-byte idle timeout before protocol classification. |
 | `tg_connect_secs` | `u64` | Upstream Telegram connect timeout. |
 | `client_keepalive_secs` | `u64` | Client keepalive interval. |
 | `client_ack_secs` | `u64` | ACK timeout. |
@@ -320,13 +508,20 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `writer_pick_mode` | `string` | Writer picker mode (`sorted_rr`, `p2c`). |
 | `writer_pick_sample_size` | `u8` | Candidate sample size for `p2c` picker mode. |
 | `me2dc_fallback` | `bool` | Effective ME -> direct fallback flag. |
+| `me2dc_fast` | `bool` | Effective fast fallback flag. |
 
 #### `EffectiveUserIpPolicyLimits`
 | Field | Type | Description |
 | --- | --- | --- |
+| `global_each` | `usize` | Global per-user unique-IP limit applied when no per-user override exists. |
 | `mode` | `string` | Unique-IP policy mode (`active_window`, `time_window`, `combined`). |
 | `window_secs` | `u64` | Time window length used by unique-IP policy. |
 
+#### `EffectiveUserTcpPolicyLimits`
+| Field | Type | Description |
+| --- | --- | --- |
+| `global_each` | `usize` | Global per-user concurrent TCP limit applied when no per-user override exists. |
+
 ### `SecurityPostureData`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -430,6 +625,8 @@ Note: the request contract is defined, but the corresponding route currently ret
 | --- | --- | --- |
 | `counters` | `RuntimeMeQualityCountersData` | Key ME lifecycle/error counters. |
 | `route_drops` | `RuntimeMeQualityRouteDropData` | Route drop counters by reason. |
+| `family_states` | `RuntimeMeQualityFamilyStateData[]` | Per-family ME route/recovery state rows. |
+| `drain_gate` | `RuntimeMeQualityDrainGateData` | Current ME drain-gate decision state. |
 | `dc_rtt` | `RuntimeMeQualityDcRttData[]` | Per-DC RTT and writer coverage rows. |
 
 #### `RuntimeMeQualityCountersData`
@@ -451,6 +648,24 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `queue_full_base_total` | `u64` | Route drops in base-queue path. |
 | `queue_full_high_total` | `u64` | Route drops in high-priority queue path. |
 
+#### `RuntimeMeQualityFamilyStateData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `family` | `string` | Address family label. |
+| `state` | `string` | Current family state label. |
+| `state_since_epoch_secs` | `u64` | Unix timestamp when current state began. |
+| `suppressed_until_epoch_secs` | `u64?` | Unix timestamp until suppression remains active. |
+| `fail_streak` | `u32` | Consecutive failure count. |
+| `recover_success_streak` | `u32` | Consecutive recovery success count. |
+
+#### `RuntimeMeQualityDrainGateData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `route_quorum_ok` | `bool` | Whether route quorum condition allows drain. |
+| `redundancy_ok` | `bool` | Whether redundancy condition allows drain. |
+| `block_reason` | `string` | Current drain block reason label. |
+| `updated_at_epoch_secs` | `u64` | Unix timestamp of the latest gate update. |
+
 #### `RuntimeMeQualityDcRttData`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -697,6 +912,43 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `event_type` | `string` | Event kind identifier. |
 | `context` | `string` | Context text (truncated to implementation-defined max length). |
 
+### `RuntimeEdgeTlsFingerprintsData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Endpoint availability under `runtime_edge_enabled`. |
+| `reason` | `string?` | `feature_disabled` when endpoint is disabled. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeEdgeTlsFingerprintsPayload?` | Null when unavailable. |
+
+#### `RuntimeEdgeTlsFingerprintsPayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `limit` | `usize` | Effective Top-N row count. |
+| `retention_secs` | `u64` | In-memory retention window, derived from `general.beobachten_minutes`. |
+| `capacity` | `usize` | Maximum retained fingerprint buckets. |
+| `dropped_total` | `u64` | Buckets dropped because the collector was full. |
+| `parse_error_total` | `u64` | Complete ClientHello records that could not be fingerprinted. |
+| `by_fingerprint` | `RuntimeEdgeTlsFingerprintRow[]` | Global JA3/JA4 leaderboard. |
+| `by_ip` | `RuntimeEdgeTlsFingerprintRow[]` | Source-IP scoped leaderboard. |
+| `by_cidr` | `RuntimeEdgeTlsFingerprintRow[]` | Source CIDR scoped leaderboard (`/24` for IPv4, `/56` for IPv6). |
+| `by_user` | `RuntimeEdgeTlsFingerprintRow[]` | Authenticated user scoped leaderboard. |
+
+#### `RuntimeEdgeTlsFingerprintRow`
+| Field | Type | Description |
+| --- | --- | --- |
+| `scope` | `string?` | IP, CIDR, or username; absent in `by_fingerprint`. |
+| `ja3` | `string` | JA3 MD5 hash. |
+| `ja3_raw` | `string` | Raw JA3 field string. |
+| `ja4` | `string` | JA4 TLS client fingerprint. |
+| `ja4_raw` | `string` | Raw JA4 material used for the hashed parts. |
+| `total` | `u64` | Complete ClientHello observations for this bucket. |
+| `auth_success` | `u64` | TLS-authenticated observations for this bucket. |
+| `bad_or_probe` | `u64` | Complete ClientHello observations later classified as bad/probe. |
+| `first_seen_epoch_secs` | `u64` | First observation timestamp. |
+| `last_seen_epoch_secs` | `u64` | Last observation timestamp. |
+
+JA3 follows the Salesforce ClientHello field order. JA4 follows the FoxIO TLS-client `a_b_c` format; GREASE values are excluded and no high-cardinality Prometheus labels are emitted for fingerprints.
+
 ### `ZeroAllData`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -713,11 +965,25 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `uptime_seconds` | `f64` | Process uptime. |
 | `connections_total` | `u64` | Total accepted connections. |
 | `connections_bad_total` | `u64` | Failed/invalid connections. |
+| `connections_bad_by_class` | `ClassCount[]` | Failed/invalid connections grouped by class. |
+| `handshake_failures_by_class` | `ClassCount[]` | Handshake failures grouped by class. |
+| `handshake_failures_by_stage` | `StageCount[]` | Handshake failures grouped by state-machine stage. |
 | `handshake_timeouts_total` | `u64` | Handshake timeouts. |
+| `accept_permit_timeout_total` | `u64` | Listener admission permit acquisition timeouts. |
 | `configured_users` | `usize` | Configured user count. |
 | `telemetry_core_enabled` | `bool` | Core telemetry toggle. |
 | `telemetry_user_enabled` | `bool` | User telemetry toggle. |
 | `telemetry_me_level` | `string` | ME telemetry level (`off|normal|verbose`). |
+| `conntrack_control_enabled` | `bool` | Whether conntrack control is enabled by policy. |
+| `conntrack_control_available` | `bool` | Whether conntrack control backend is currently available. |
+| `conntrack_pressure_active` | `bool` | Current conntrack pressure flag. |
+| `conntrack_event_queue_depth` | `u64` | Current conntrack close-event queue depth. |
+| `conntrack_rule_apply_ok` | `bool` | Last conntrack rule application state. |
+| `conntrack_delete_attempt_total` | `u64` | Conntrack delete attempts. |
+| `conntrack_delete_success_total` | `u64` | Successful conntrack deletes. |
+| `conntrack_delete_not_found_total` | `u64` | Conntrack delete misses. |
+| `conntrack_delete_error_total` | `u64` | Conntrack delete errors. |
+| `conntrack_close_event_drop_total` | `u64` | Dropped conntrack close events. |
 
 #### `ZeroUpstreamData`
 | Field | Type | Description |
@@ -804,6 +1070,24 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `route_drop_queue_full_total` | `u64` | Route drops due to full queue (total). |
 | `route_drop_queue_full_base_total` | `u64` | Route drops in base queue mode. |
 | `route_drop_queue_full_high_total` | `u64` | Route drops in high queue mode. |
+| `d2c_batches_total` | `u64` | ME D->C batch flushes. |
+| `d2c_batch_frames_total` | `u64` | ME D->C frames included in batches. |
+| `d2c_batch_bytes_total` | `u64` | ME D->C payload bytes included in batches. |
+| `d2c_flush_reason_queue_drain_total` | `u64` | Flushes caused by queue drain. |
+| `d2c_flush_reason_batch_frames_total` | `u64` | Flushes caused by frame-count batch limit. |
+| `d2c_flush_reason_batch_bytes_total` | `u64` | Flushes caused by byte-count batch limit. |
+| `d2c_flush_reason_max_delay_total` | `u64` | Flushes caused by max-delay budget. |
+| `d2c_flush_reason_ack_immediate_total` | `u64` | Flushes caused by immediate ACK policy. |
+| `d2c_flush_reason_close_total` | `u64` | Flushes caused by close path. |
+| `d2c_data_frames_total` | `u64` | ME D->C data frames. |
+| `d2c_ack_frames_total` | `u64` | ME D->C ACK frames. |
+| `d2c_payload_bytes_total` | `u64` | ME D->C payload bytes. |
+| `d2c_write_mode_coalesced_total` | `u64` | Coalesced D->C writes. |
+| `d2c_write_mode_split_total` | `u64` | Split D->C writes. |
+| `d2c_quota_reject_pre_write_total` | `u64` | D->C quota rejects before write. |
+| `d2c_quota_reject_post_write_total` | `u64` | D->C quota rejects after write. |
+| `d2c_frame_buf_shrink_total` | `u64` | D->C frame-buffer shrink operations. |
+| `d2c_frame_buf_shrink_bytes_total` | `u64` | Bytes released by D->C frame-buffer shrink operations. |
 | `socks_kdf_strict_reject_total` | `u64` | SOCKS KDF strict rejects. |
 | `socks_kdf_compat_fallback_total` | `u64` | SOCKS KDF compat fallbacks. |
 | `endpoint_quarantine_total` | `u64` | Endpoint quarantine activations. |
@@ -963,6 +1247,8 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `required_writers` | `usize` | Required writers based on current floor policy. |
 | `alive_writers` | `usize` | Writers currently alive. |
 | `coverage_pct` | `f64` | `alive_writers / required_writers * 100`. |
+| `fresh_alive_writers` | `usize` | Alive writers that match freshness requirements. |
+| `fresh_coverage_pct` | `f64` | `fresh_alive_writers / required_writers * 100`. |
 
 #### `MeWriterStatus`
 | Field | Type | Description |
@@ -977,6 +1263,12 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `bound_clients` | `usize` | Number of currently bound clients. |
 | `idle_for_secs` | `u64?` | Idle age in seconds if idle. |
 | `rtt_ema_ms` | `f64?` | RTT exponential moving average. |
+| `matches_active_generation` | `bool` | Whether this writer belongs to the active pool generation. |
+| `in_desired_map` | `bool` | Whether this writer's endpoint remains in desired topology. |
+| `allow_drain_fallback` | `bool` | Whether drain fallback is allowed for this writer. |
+| `drain_started_at_epoch_secs` | `u64?` | Unix timestamp when drain started. |
+| `drain_deadline_epoch_secs` | `u64?` | Unix timestamp of drain deadline. |
+| `drain_over_ttl` | `bool` | Whether drain has exceeded its TTL. |
 
 ### `DcStatusData`
 | Field | Type | Description |
@@ -1001,6 +1293,8 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `floor_capped` | `bool` | `true` when computed floor target was capped by active limits. |
 | `alive_writers` | `usize` | Alive writers in this DC. |
 | `coverage_pct` | `f64` | `alive_writers / required_writers * 100`. |
+| `fresh_alive_writers` | `usize` | Fresh alive writers in this DC. |
+| `fresh_coverage_pct` | `f64` | `fresh_alive_writers / required_writers * 100`. |
 | `rtt_ms` | `f64?` | Aggregated RTT for DC. |
 | `load` | `usize` | Active client sessions bound to this DC. |
 
@@ -1014,10 +1308,14 @@ Note: the request contract is defined, but the corresponding route currently ret
 | Field | Type | Description |
 | --- | --- | --- |
 | `username` | `string` | Username. |
+| `enabled` | `bool` | Effective user enable flag. Missing config entry is reported as `true`. |
+| `in_runtime` | `bool` | Whether current runtime config already contains this user. |
 | `user_ad_tag` | `string?` | Optional ad tag (32 hex chars). |
 | `max_tcp_conns` | `usize?` | Optional max concurrent TCP limit. |
 | `expiration_rfc3339` | `string?` | Optional expiration timestamp. |
 | `data_quota_bytes` | `u64?` | Optional data quota. |
+| `rate_limit_up_bps` | `u64?` | Optional upload rate limit in 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. |
@@ -1027,12 +1325,25 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `total_octets` | `u64` | Total traffic octets for this user. |
 | `links` | `UserLinks` | Active connection links derived from current config. |
 
+### `UserActiveIps`
+| Field | Type | Description |
+| --- | --- | --- |
+| `username` | `string` | Username with at least one active tracked source IP. |
+| `active_ips` | `ip[]` | Active source IPs for this user. |
+
 #### `UserLinks`
 | Field | Type | Description |
 | --- | --- | --- |
 | `classic` | `string[]` | Active `tg://proxy` links for classic mode. |
 | `secure` | `string[]` | Active `tg://proxy` links for secure/DD mode. |
 | `tls` | `string[]` | Active `tg://proxy` links for EE-TLS mode (for each host+TLS domain). |
+| `tls_domains` | `TlsDomainLink[]` | Extra TLS-domain links as explicit domain/link pairs for `censorship.tls_domains`. |
+
+#### `TlsDomainLink`
+| Field | Type | Description |
+| --- | --- | --- |
+| `domain` | `string` | TLS domain represented by the link. |
+| `link` | `string` | `tg://proxy` link for this domain. |
 
 Link generation uses active config and enabled modes:
 - Link port is `general.links.public_port` when configured; otherwise `server.port`.
@@ -1052,13 +1363,199 @@ Link generation uses active config and enabled modes:
 | `user` | `UserInfo` | Created or updated user view. |
 | `secret` | `string` | Effective user secret. |
 
+### `DeleteUserResponse`
+| Field | Type | Description |
+| --- | --- | --- |
+| `username` | `string` | Deleted username. |
+| `in_runtime` | `bool` | `true` when runtime config still contains the user and hot-reload has not applied deletion yet. |
+
+### `ResetUserQuotaResponse`
+| Field | Type | Description |
+| --- | --- | --- |
+| `username` | `string` | User whose runtime quota counter was reset. |
+| `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"}
+}
+```
+
+The response is built from the validated, include-expanded configuration and may therefore contain normalized defaults or synthesized listeners that are absent from the root file. 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`. It covers the complete recursive include graph. If supplied and it does not match the current source manifest, returns `409 revision_conflict`. If omitted, the patch applies unconditionally. |
+
+**Editable sections:** `general`, `timeouts`, `censorship`, `upstreams`, `dc_overrides`, plus partially editable `server` (only nested `listeners`).
+
+**Rejected keys and their error codes:**
+
+| Key | HTTP | `error.code` |
+| --- | --- | --- |
+| `access` | `400` | `access_not_editable` |
+| `network`, `web`, or any unknown top-level key | `400` | `section_not_editable` |
+| `server` with keys other than `listeners` | `400` | `field_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. A mutation is written to the single source file that owns every touched semantic section. File comments, the root file when it is not the owner, and all other include files are preserved. A target split across sources, a patch spanning multiple owners, or an include directive nested inside a TOML table returns `409 config_patch_not_atomic` without writing any file.
+
+**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`.
+
+**Optional in-process reload query:**
+
+| Query | Required | Description |
+| --- | --- | --- |
+| `reload=instant` | no | Activates a new generation and cancels sessions owned by the previous generation. |
+| `reload=drain` | no | Activates a new generation and lets old sessions finish until `timeout_secs`. |
+| `timeout_secs=1..3600` | for `reload=drain` | Bounded old-generation drain interval. Invalid with `reload=instant`. |
+| `failure_policy=keep_new\|rollback` | no | Defaults to `keep_new`. `rollback` applies only through the activation barrier, before old-generation teardown. |
+
+Without a `reload` query parameter, the endpoint writes the patch and the file watcher applies only supported hot fields. With a reload query, coordinator capacity and status are reserved before the source file is replaced. Runtime-owned changes enqueue the validated immutable snapshot after the atomic write. A process-only patch is persisted with `200`, reports its deferred fields, and does not create a reload operation.
+
+**Success `200` or `202` response body** (`data` field of the standard envelope):
+```json
+{
+  "revision": "<new-sha256-hex>",
+  "restart_required": true,
+  "runtime_reload_required": true,
+  "process_restart_required": false,
+  "deferred_process_fields": [],
+  "changed": ["censorship"],
+  "reload": {
+    "reload_id": 7,
+    "target_generation": 2,
+    "config_revision": "<new-sha256-hex>",
+    "state": "accepted",
+    "mode": "instant",
+    "failure_policy": "keep_new"
+  }
+}
+```
+
+- `revision` — SHA-256 hex of the canonical source manifest after the write, including every recursive include path and its raw bytes.
+- `restart_required` — legacy file-watcher classification retained for compatibility.
+- `runtime_reload_required` — reports whether a full Maestro generation reload is needed for runtime effect.
+- `process_restart_required` and `deferred_process_fields` — report socket policies or process-owned paths that remain unchanged by an in-process reload. A pure listener endpoint move is reloadable only when every retained endpoint keeps identical bind policy and neither the active nor desired listener set uses SYN limiting; same-address MSS, PROXY protocol, backlog, reuse, or SYN-limit changes remain deferred.
+- `changed` — list of top-level section names that differed.
+- `reload` — accepted operation metadata; omitted without a reload query and for process-only patches that cannot change the active generation.
+
+**Status codes:**
+
+| HTTP | `error.code` | Condition |
+| --- | --- | --- |
+| `200` | — | Patch applied successfully. |
+| `202` | — | Patch applied and runtime reload accepted. |
+| `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 `network` or an unknown top-level key. |
+| `400` | `field_not_editable` | Patch contains a forbidden nested `server.*` field (anything other than `listeners`). |
+| `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. |
+| `409` | `reload_in_progress` | Another runtime reload is active; the patch is not written. |
+| `409` | `config_patch_not_atomic` | Touched semantic sections have multiple source owners or cannot be mutated as one source-file transaction. |
+| `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?reload=instant'
+```
+
+## Runtime Reload Endpoints
+
+### `POST /v1/system/reload`
+
+Loads the current on-disk config under the API mutation lock and submits an immutable config snapshot to Maestro. `If-Match` is optional and uses the same revision contract as `PATCH /v1/config`. An empty body defaults to `{"mode":"instant","failure_policy":"keep_new"}`.
+
+```json
+{
+  "mode": "drain",
+  "timeout_secs": 30,
+  "failure_policy": "rollback"
+}
+```
+
+The endpoint returns `202` with `ReloadAccepted`. A concurrent non-terminal reload returns `409 reload_in_progress`. Config parsing or validation failure is reported before a command is submitted.
+
+### `GET /v1/system/reload/{id}`
+
+Returns `ReloadStatus` with `state` equal to `accepted`, `preparing`, `activating`, `draining`, `succeeded`, `rolled_back`, or `failed`. Terminal statuses include `finished_at_epoch_secs`; failures include `error`. Successful activation may include `warnings` for old-generation cleanup failures and `deferred_process_fields` for process-owned settings.
+
+Runtime generation activation rebuilds statistics, upstream routing, replay and buffer state, TLS-front cache, IP tracking, admission/route state, and Middle-End orchestration. Per-user quota accounting is process-scoped and remains continuous across generations. A process-owned listener manager can prepare new endpoint sockets without calling `listen(2)`, stop removed acceptors before the runtime swap, and start new acceptors only after the swap. Inbound listener planning depends on normalized config and explicit IPv4/IPv6 policy, never transient outbound connectivity-probe results. Retained endpoints are not rebound, and unsupported same-address policy changes are overlaid with active values and reported as deferred. API, metrics, Unix listeners, PID ownership, and logging remain process-scoped. Maestro does not invoke systemd, containerd, or another process supervisor.
+
+Reload preparation requires every configured TLS-front domain to have a non-default cached profile and requires a ready Middle-End pool when direct fallback is disabled. A candidate that does not satisfy either readiness condition fails without replacing the active generation.
+
+The revision is verified again after preparation. With `failure_policy=rollback`, a changed revision or revision read failure rolls the candidate back; with `failure_policy=keep_new`, the condition is reported in `warnings` and activation continues.
+
+## WEB Proxy Management
+
+The API provides partial operational control for WEB mode; it does not expose a dedicated `/v1/web` resource.
+
+| Operation | Current contract |
+| --- | --- |
+| Read or patch `[web]`, vhosts, profiles, decoys, timeouts, or limits | Not exposed. `GET /v1/config` omits `[web]`; a `web` key in `PATCH /v1/config` returns `400 section_not_editable`. |
+| Persist `server.listeners` | Supported through `PATCH /v1/config`. Arrays replace wholesale. A changed WEB listener is process-owned and remains deferred until process restart. |
+| Apply an externally edited WEB config | Update the owning TOML source, call `POST /v1/system/reload`, then poll `GET /v1/system/reload/{id}`. |
+| Inspect restart requirements | Read `deferred_process_fields` from reload status. `server.listeners` and `web.limits` require process restart. |
+| Manage access users | Use `/v1/users`. Creating a user does not add it to `web.vhosts.profiles`; profile membership remains file-managed. |
+| Disable one user | `POST /v1/users/{username}/disable` updates admission immediately and cancels the user's active sessions. |
+| Rotate a profiled user's secret | Use `/v1/users/{username}/rotate-secret`; the config watcher rebuilds WEB capabilities from the new access snapshot. The API returns the secret, not a `tg://webproxy` link. |
+| Read WEB-specific runtime statistics | No WEB-specific endpoint exists in the current API surface. |
+
+`web.enabled`, `web.carrier`, `web.timeouts`, vhosts, profiles, and decoy snapshots are runtime-generation fields. A changed carrier applies only to newly issued bridge sessions; existing sessions retain their creation-time carrier. WEB listener inventory and trust policy, plus all `[web.limits]`, are process-owned. A successful reload can therefore activate the runtime-owned subset while reporting the process-owned subset as deferred.
+
+Before deleting a user referenced by a WEB profile, remove and apply the profile first. User mutations validate the complete resulting configuration, so a dangling WEB profile is rejected rather than persisted.
+
+The API whitelist is evaluated against the direct TCP peer and does not use the WEB listener's `X-Forwarded-For` policy. Keep the API on a separate loopback or private bind, use a narrow whitelist and a non-empty exact `auth_header`, and do not expose it through the public WEB vhost.
+
+Deployment, TLS-terminator examples, links, and WEB-specific verification are documented in the [WEB proxy guide](../../WEB/WEB_PROXY.en.md).
+
 ## Mutation Semantics
 
 | Endpoint | Notes |
 | --- | --- |
+| `PATCH /v1/config` | Deep-merges and validates the patch, writes touched sections via atomic `tmp + rename`, and optionally submits the exact written revision for an in-process Maestro reload. |
 | `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. Current implementation persists full config document on success. |
-| `POST /v1/users/{username}/rotate-secret` | Currently returns `404` in runtime route matcher; request schema is reserved for intended behavior. |
+| `PATCH /v1/users/{username}` | Partial update of provided fields only. Missing fields remain unchanged; explicit `null` removes optional per-user entries. The write path updates only affected `access.*` TOML tables. |
+| `POST /v1/users/{username}/rotate-secret` | Replaces the user's secret with a provided valid 32-hex value or a generated value, then returns the effective secret in `CreateUserResponse`. |
+| `POST /v1/users/{username}/enable` | Enables the user idempotently by removing the `access.user_enabled[username]` override and updating the runtime admission state immediately. |
+| `POST /v1/users/{username}/disable` | Disables the user idempotently by writing `access.user_enabled[username] = false`, updating runtime admission immediately, and cancelling active sessions for that username. |
+| `POST /v1/users/{username}/reset-quota` | Resets the runtime quota counter for the route username, persists quota state to `general.quota_state_path`, and does not modify user config. |
 | `DELETE /v1/users/{username}` | Deletes only specified user, removes this user from related optional `access.user_*` maps, blocks last-user deletion, and atomically updates only related `access.*` TOML tables. |
 
 All mutating endpoints:
@@ -1067,6 +1564,12 @@ All mutating endpoints:
 - Return new `revision` after successful write.
 - Use process-local mutation lock + atomic write (`tmp + rename`) for config persistence.
 
+Docker deployment note:
+- Mutating endpoints require `config.toml` to live inside a writable mounted directory.
+- Do not mount `config.toml` as a single bind-mounted file when API mutations are enabled; atomic `tmp + rename` writes can fail with `Device or resource busy`.
+- Mount the config directory instead, for example `./config:/etc/telemt:rw`, and start Telemt with `/etc/telemt/config.toml`.
+- A read-only single-file mount remains valid only for read-only deployments or when `[server.api].read_only=true`.
+
 Delete path cleanup guarantees:
 - Config cleanup removes only the requested username keys.
 - Runtime unique-IP cleanup removes only this user's limiter and tracked IP state.
@@ -1095,16 +1598,17 @@ Additional runtime endpoint behavior:
 | `/v1/runtime/me-selftest` | No | ME pool unavailable => `enabled=false`, `reason=source_unavailable` | `enabled=true`, full payload |
 | `/v1/runtime/connections/summary` | `runtime_edge_enabled=false` => `enabled=false`, `reason=feature_disabled` | Recompute lock contention with no cache entry => `enabled=true`, `reason=source_unavailable` | `enabled=true`, full payload |
 | `/v1/runtime/events/recent` | `runtime_edge_enabled=false` => `enabled=false`, `reason=feature_disabled` | Not used in current implementation | `enabled=true`, full payload |
+| `/v1/runtime/tls-fingerprints` | `runtime_edge_enabled=false` => `enabled=false`, `reason=feature_disabled` | Not used in current implementation | `enabled=true`, full payload |
 
 ## ME Fallback Behavior Exposed Via API
 
 When `general.use_middle_proxy=true` and `general.me2dc_fallback=true`:
-- Startup does not block on full ME pool readiness; initialization can continue in background.
+- Startup opens Direct-DC routing first, then initializes ME in background and switches new sessions to Middle mode after ME readiness is observed.
 - Runtime initialization payload can expose ME stage `background_init` until pool becomes ready.
 - Admission/routing decision uses two readiness grace windows for "ME not ready" periods:
-  `80s` before first-ever readiness is observed (startup grace),
+  direct startup fallback before first-ever readiness is observed,
   `6s` after readiness has been observed at least once (runtime failover timeout).
-- While in fallback window breach, new sessions are routed via Direct-DC; when ME becomes ready, routing returns to Middle mode for new sessions.
+- While fallback is active, new sessions are routed via Direct-DC; when ME becomes ready, routing returns to Middle mode. Direct sessions affected by the cutover are closed with the existing staggered delay so clients reconnect through the current route.
 
 ## Serialization Rules
 
@@ -1133,5 +1637,4 @@ When `general.use_middle_proxy=true` and `general.me2dc_fallback=true`:
 
 ## Known Limitations (Current Release)
 
-- `POST /v1/users/{username}/rotate-secret` is currently unreachable in route matcher and returns `404`.
 - API runtime controls under `server.api` are documented as restart-required; hot-reload behavior for these fields is not strictly uniform in all change combinations.

docs/Architecture/Fronting-splitting/TLS_FRONT_PROFILE_FIDELITY.en.md

@@ -0,0 +1,266 @@
+# TLS Front Profile Fidelity
+
+## Overview
+
+This document describes how Telemt reuses captured TLS behavior in the FakeTLS server flight and how to validate the result on a real deployment.
+
+When TLS front emulation is enabled, Telemt can capture useful server-side TLS behavior from the selected origin and reuse that behavior in the emulated success path. The goal is not to reproduce the origin byte-for-byte, but to reduce stable synthetic traits and make the emitted server flight structurally closer to the captured profile.
+
+## Why this change exists
+
+The project already captures useful server-side TLS behavior in the TLS front fetch path:
+
+- `change_cipher_spec_count`
+- `app_data_record_sizes`
+- `ticket_record_sizes`
+
+Before this change, the emulator used only part of that information. This left a gap between captured origin behavior and emitted FakeTLS server flight.
+
+## What is implemented
+
+- The emulator now replays the observed `ChangeCipherSpec` count from the fetched behavior profile.
+- The emulator now replays observed ticket-like tail ApplicationData record sizes when raw or merged TLS profile data is available.
+- The emulator now preserves more of the profiled encrypted-flight structure instead of collapsing it into a smaller synthetic shape.
+- The emulator still falls back to the previous synthetic behavior when the cached profile does not contain raw TLS behavior information.
+- Operator-configured `tls_new_session_tickets` still works as an additive fallback when the profile does not provide enough tail records.
+
+## Practical benefit
+
+- Reduced distinguishability between profiled origin TLS behavior and emulated TLS behavior.
+- Lower chance of stable server-flight fingerprints caused by fixed CCS count or synthetic-only tail record sizes.
+- Better reuse of already captured TLS profile data without changing MTProto logic, KDF routing, or transport architecture.
+
+## Limitations
+
+This mechanism does not aim to make Telemt byte-identical to the origin server.
+
+It also does not change:
+
+- MTProto business logic;
+- KDF routing behavior;
+- the overall transport architecture.
+
+The practical goal is narrower:
+
+- reuse more captured profile data;
+- reduce fixed synthetic behavior in the server flight;
+- preserve a valid FakeTLS success path while changing the emitted shape on the wire.
+
+## Validation targets
+
+- Correct count of emulated `ChangeCipherSpec` records.
+- Correct replay of observed ticket-tail record sizes.
+- No regression in existing ALPN and payload-placement behavior.
+
+## How to validate the result
+
+Recommended validation consists of two layers:
+
+- focused unit and security tests for CCS-count replay and ticket-tail replay;
+- real packet-capture comparison for a selected origin and a successful FakeTLS session.
+
+When testing on the network, the expected result is:
+
+- a valid FakeTLS and MTProto success path is preserved;
+- the early encrypted server flight changes shape when richer profile data is available;
+- the change is visible on the wire without changing MTProto logic or transport architecture.
+
+This validation is intended to show better reuse of captured TLS profile data.
+It is not intended to prove byte-level equivalence with the real origin server.
+
+## How to test on a real deployment
+
+The strongest practical validation is a side-by-side trace comparison between:
+
+- a real TLS origin server used as `mask_host`;
+- a Telemt FakeTLS success-path connection for the same SNI;
+- optional captures from different Telemt builds or configurations.
+
+The purpose of the comparison is to inspect the shape of the server flight:
+
+- record order;
+- count of `ChangeCipherSpec` records;
+- count and grouping of early encrypted `ApplicationData` records;
+- lengths of tail or continuation `ApplicationData` records.
+
+## Recommended environment
+
+Use a Linux host or Docker container for the cleanest reproduction.
+
+Recommended setup:
+
+1. One Telemt instance.
+2. One real HTTPS origin as `mask_host`.
+3. One Telegram client configured with an `ee` proxy link for the Telemt instance.
+4. `tcpdump` or Wireshark available for capture analysis.
+
+## Step-by-step test procedure
+
+### 1. Prepare the origin
+
+1. Choose a real HTTPS origin.
+2. Set both `censorship.tls_domain` and `censorship.mask_host` to that hostname.
+3. Confirm that a direct TLS request works:
+
+```bash
+openssl s_client -connect ORIGIN_IP:443 -servername YOUR_DOMAIN </dev/null
+```
+
+### 2. Configure Telemt
+
+Use a configuration that enables:
+
+- `censorship.mask = true`
+- `censorship.tls_emulation = true`
+- `censorship.mask_host`
+- `censorship.mask_port`
+
+Recommended for cleaner testing:
+
+- keep `censorship.tls_new_session_tickets = 0`, so the result depends primarily on fetched profile data rather than operator-forced synthetic tail records;
+- keep `censorship.tls_fetch.strict_route = true`, if cleaner provenance for captured profile data is important.
+
+### 3. Refresh TLS profile data
+
+1. Start Telemt.
+2. Let it fetch TLS front profile data for the configured domain.
+3. If `tls_front_dir` is persisted, confirm that the TLS front cache is populated.
+
+Persisted cache artifacts are useful, but they are not required if packet captures already demonstrate the runtime result.
+
+### 4. Check TLS-front profile health metrics
+
+If the metrics endpoint is enabled, check the TLS-front profile health before packet-capture validation:
+
+```bash
+curl -s http://127.0.0.1:9999/metrics | grep -E 'telemt_tls_front_profile|telemt_tls_fetch_profile_cache|telemt_tls_front_full_cert'
+```
+
+The profile-health metrics expose the runtime state of configured TLS front domains:
+
+- `telemt_tls_front_profile_domains` shows configured, emitted, and suppressed domain series.
+- `telemt_tls_front_profile_info` shows profile source and feature flags per domain.
+- `telemt_tls_front_profile_age_seconds` shows cached profile age.
+- `telemt_tls_front_profile_app_data_records` shows cached AppData record count.
+- `telemt_tls_front_profile_ticket_records` shows cached ticket-like tail record count.
+- `telemt_tls_front_profile_change_cipher_spec_records` shows cached ChangeCipherSpec count.
+- `telemt_tls_front_profile_app_data_bytes` shows total cached AppData bytes.
+
+Interpretation:
+
+- `source="merged"` or `source="raw"` means real TLS profile data is being used.
+- `source="default"` or `is_default="true"` means the domain currently uses the synthetic default fallback.
+- `has_cert_payload="true"` means certificate payload data is available for TLS emulation.
+- Non-zero AppData/ticket/CCS counters show captured server-flight shape.
+
+Example healthy output:
+
+```text
+telemt_tls_front_profile_domains{status="configured"} 1
+telemt_tls_front_profile_domains{status="emitted"} 1
+telemt_tls_front_profile_domains{status="suppressed"} 0
+telemt_tls_front_profile_info{domain="itunes.apple.com",source="merged",is_default="false",has_cert_info="true",has_cert_payload="true"} 1
+telemt_tls_front_profile_age_seconds{domain="itunes.apple.com"} 20
+telemt_tls_front_profile_app_data_records{domain="itunes.apple.com"} 3
+telemt_tls_front_profile_ticket_records{domain="itunes.apple.com"} 1
+telemt_tls_front_profile_change_cipher_spec_records{domain="itunes.apple.com"} 1
+telemt_tls_front_profile_app_data_bytes{domain="itunes.apple.com"} 5240
+```
+
+These metrics do not prove byte-level origin equivalence. They are an operational health signal that the configured domain is backed by real cached profile data instead of default fallback data.
+
+### 5. Capture a direct-origin trace
+
+From a separate client host, connect directly to the origin:
+
+```bash
+openssl s_client -connect ORIGIN_IP:443 -servername YOUR_DOMAIN </dev/null
+```
+
+Capture with:
+
+```bash
+sudo tcpdump -i any -w origin-direct.pcap host ORIGIN_IP and port 443
+```
+
+### 6. Capture a Telemt FakeTLS success-path trace
+
+Now connect to Telemt with a real Telegram client through an `ee` proxy link that targets the Telemt instance.
+
+`openssl s_client` is useful for direct-origin capture and fallback sanity checks, but it does not exercise the successful FakeTLS and MTProto path.
+
+Capture with:
+
+```bash
+sudo tcpdump -i any -w telemt-emulated.pcap host TELEMT_IP and port 443
+```
+
+### 7. Decode TLS record structure
+
+Use `tshark` to print record-level structure:
+
+```bash
+tshark -r origin-direct.pcap -Y "tls.record" -T fields \
+  -e frame.number \
+  -e ip.src \
+  -e ip.dst \
+  -e tls.record.content_type \
+  -e tls.record.length
+```
+
+```bash
+tshark -r telemt-emulated.pcap -Y "tls.record" -T fields \
+  -e frame.number \
+  -e ip.src \
+  -e ip.dst \
+  -e tls.record.content_type \
+  -e tls.record.length
+```
+
+Focus on the server flight after ClientHello:
+
+- `22` = Handshake
+- `20` = ChangeCipherSpec
+- `23` = ApplicationData
+
+### 8. Build a comparison table
+
+A compact table like the following is usually enough:
+
+| Path | CCS count | AppData count in first encrypted flight | Tail AppData lengths |
+| --- | --- | --- | --- |
+| Origin | `N` | `M` | `[a, b, ...]` |
+| Telemt build A | `...` | `...` | `...` |
+| Telemt build B | `...` | `...` | `...` |
+
+The comparison should make it easy to see that:
+
+- the FakeTLS success path remains valid;
+- the early encrypted server flight changes when richer profile data is reused;
+- the result is backed by packet evidence.
+
+## Example capture set
+
+One practical example of this workflow uses:
+
+- `origin-direct-nginx.pcap`
+- `telemt-ee-before-nginx.pcap`
+- `telemt-ee-after-nginx.pcap`
+
+Practical notes:
+
+- `origin` was captured as a direct TLS 1.2 connection to `nginx.org`;
+- `before` and `after` were captured on the Telemt FakeTLS success path with a real Telegram client;
+- the first server-side FakeTLS response remains valid in both cases;
+- the early encrypted server-flight segmentation differs between `before` and `after`, which is consistent with better reuse of captured profile data;
+- this kind of result shows a wire-visible effect without breaking the success path, but it does not claim full indistinguishability from the origin.
+
+## Stronger validation
+
+For broader confidence, repeat the same comparison on:
+
+1. one CDN-backed origin;
+2. one regular nginx origin;
+3. one origin with a multi-record encrypted flight and visible ticket-like tails.
+
+If the same directional improvement appears across all three, confidence in the result will be much higher than for a single-origin example.

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

@@ -0,0 +1,266 @@
+# Fidelity TLS Front Profile
+
+## Обзор
+
+Этот документ описывает, как Telemt переиспользует захваченное TLS-поведение в FakeTLS server flight и как проверять результат на реальной инсталляции.
+
+Когда включена TLS front emulation, Telemt может собирать полезное серверное TLS-поведение выбранного origin и использовать его в emulated success path. Цель здесь не в побайтном копировании origin, а в уменьшении устойчивых synthetic признаков и в том, чтобы emitted server flight был структурно ближе к захваченному profile.
+
+## Зачем нужно это изменение
+
+Проект уже умеет собирать полезное серверное TLS-поведение в пути TLS front fetch:
+
+- `change_cipher_spec_count`
+- `app_data_record_sizes`
+- `ticket_record_sizes`
+
+До этого изменения эмулятор использовал только часть этой информации. Из-за этого оставался разрыв между захваченным поведением origin и тем FakeTLS server flight, который реально уходил на провод.
+
+## Что реализовано
+
+- Эмулятор теперь воспроизводит наблюдаемое значение `ChangeCipherSpec` из полученного `behavior_profile`.
+- Эмулятор теперь воспроизводит наблюдаемые размеры ticket-like tail ApplicationData records, когда доступны raw или merged TLS profile data.
+- Эмулятор теперь сохраняет больше структуры профилированного encrypted flight, а не схлопывает его в более маленькую synthetic форму.
+- Для профилей без raw TLS behavior по-прежнему сохраняется прежний synthetic fallback.
+- Операторский `tls_new_session_tickets` по-прежнему работает как дополнительный fallback, если профиль не даёт достаточного количества tail records.
+
+## Практическая польза
+
+- Снижается различимость между профилированным origin TLS-поведением и эмулируемым TLS-поведением.
+- Уменьшается шанс устойчивых server-flight fingerprint, вызванных фиксированным CCS count или полностью synthetic tail record sizes.
+- Уже собранные TLS profile data используются лучше, без изменения MTProto logic, KDF routing или transport architecture.
+
+## Ограничения
+
+Этот механизм не ставит целью сделать Telemt побайтно идентичным origin server.
+
+Он также не меняет:
+
+- MTProto business logic;
+- поведение KDF routing;
+- общую transport architecture.
+
+Практическая цель уже:
+
+- использовать больше уже собранных profile data;
+- уменьшить fixed synthetic behavior в server flight;
+- сохранить валидный FakeTLS success path, одновременно меняя форму emitted traffic на проводе.
+
+## Цели валидации
+
+- Корректное количество эмулируемых `ChangeCipherSpec` records.
+- Корректное воспроизведение наблюдаемых ticket-tail record sizes.
+- Отсутствие регрессии в существующем ALPN и payload-placement behavior.
+
+## Как проверять результат
+
+Рекомендуемая валидация состоит из двух слоёв:
+
+- focused unit и security tests для CCS-count replay и ticket-tail replay;
+- сравнение реальных packet capture для выбранного origin и успешной FakeTLS session.
+
+При проверке на сети ожидаемый результат такой:
+
+- валидный FakeTLS и MTProto success path сохраняется;
+- форма раннего encrypted server flight меняется, когда доступно более богатое profile data;
+- изменение видно на проводе без изменения MTProto logic и transport architecture.
+
+Такая проверка нужна для подтверждения того, что уже собранные TLS profile data используются лучше.
+Она не предназначена для доказательства побайтной эквивалентности с реальным origin server.
+
+## Как проверить на реальной инсталляции
+
+Самая сильная практическая проверка — side-by-side trace comparison между:
+
+- реальным TLS origin server, используемым как `mask_host`;
+- Telemt FakeTLS success-path connection для того же SNI;
+- при необходимости capture от разных Telemt builds или configurations.
+
+Смысл сравнения состоит в том, чтобы посмотреть на форму server flight:
+
+- порядок records;
+- количество `ChangeCipherSpec` records;
+- количество и группировку ранних encrypted `ApplicationData` records;
+- размеры tail или continuation `ApplicationData` records.
+
+## Рекомендуемое окружение
+
+Для самой чистой проверки лучше использовать Linux host или Docker container.
+
+Рекомендуемый setup:
+
+1. Один экземпляр Telemt.
+2. Один реальный HTTPS origin как `mask_host`.
+3. Один Telegram client, настроенный на `ee` proxy link для Telemt instance.
+4. `tcpdump` или Wireshark для анализа capture.
+
+## Пошаговая процедура проверки
+
+### 1. Подготовить origin
+
+1. Выберите реальный HTTPS origin.
+2. Установите и `censorship.tls_domain`, и `censorship.mask_host` в hostname этого origin.
+3. Убедитесь, что прямой TLS request работает:
+
+```bash
+openssl s_client -connect ORIGIN_IP:443 -servername YOUR_DOMAIN </dev/null
+```
+
+### 2. Настроить Telemt
+
+Используйте config, где включены:
+
+- `censorship.mask = true`
+- `censorship.tls_emulation = true`
+- `censorship.mask_host`
+- `censorship.mask_port`
+
+Для более чистой проверки рекомендуется:
+
+- держать `censorship.tls_new_session_tickets = 0`, чтобы результат в первую очередь зависел от fetched profile data, а не от операторских synthetic tail records;
+- держать `censorship.tls_fetch.strict_route = true`, если важна более чистая provenance для captured profile data.
+
+### 3. Обновить TLS profile data
+
+1. Запустите Telemt.
+2. Дайте ему получить TLS front profile data для выбранного домена.
+3. Если `tls_front_dir` хранится persistently, убедитесь, что TLS front cache заполнен.
+
+Сохранённые артефакты кэша полезны, но не обязательны, если packet capture уже показывает результат в runtime.
+
+### 4. Проверить метрики состояния TLS-front profile
+
+Если endpoint метрик включён, перед проверкой через packet capture можно быстро проверить состояние TLS-front profile:
+
+```bash
+curl -s http://127.0.0.1:9999/metrics | grep -E 'telemt_tls_front_profile|telemt_tls_fetch_profile_cache|telemt_tls_front_full_cert'
+```
+
+Метрики состояния профиля показывают runtime-состояние настроенных TLS-front доменов:
+
+- `telemt_tls_front_profile_domains` показывает количество настроенных, экспортируемых и скрытых из-за лимита доменов.
+- `telemt_tls_front_profile_info` показывает источник профиля и флаги доступных данных по каждому домену.
+- `telemt_tls_front_profile_age_seconds` показывает возраст закешированного профиля.
+- `telemt_tls_front_profile_app_data_records` показывает количество закешированных AppData records.
+- `telemt_tls_front_profile_ticket_records` показывает количество закешированных ticket-like tail records.
+- `telemt_tls_front_profile_change_cipher_spec_records` показывает закешированное количество ChangeCipherSpec records.
+- `telemt_tls_front_profile_app_data_bytes` показывает общий размер закешированных AppData bytes.
+
+Интерпретация:
+
+- `source="merged"` или `source="raw"` означает, что используются реальные данные TLS-профиля.
+- `source="default"` или `is_default="true"` означает, что домен сейчас работает на synthetic default fallback.
+- `has_cert_payload="true"` означает, что certificate payload доступен для TLS emulation.
+- Ненулевые AppData/ticket/CCS counters показывают захваченную форму server flight.
+
+Пример здорового состояния:
+
+```text
+telemt_tls_front_profile_domains{status="configured"} 1
+telemt_tls_front_profile_domains{status="emitted"} 1
+telemt_tls_front_profile_domains{status="suppressed"} 0
+telemt_tls_front_profile_info{domain="itunes.apple.com",source="merged",is_default="false",has_cert_info="true",has_cert_payload="true"} 1
+telemt_tls_front_profile_age_seconds{domain="itunes.apple.com"} 20
+telemt_tls_front_profile_app_data_records{domain="itunes.apple.com"} 3
+telemt_tls_front_profile_ticket_records{domain="itunes.apple.com"} 1
+telemt_tls_front_profile_change_cipher_spec_records{domain="itunes.apple.com"} 1
+telemt_tls_front_profile_app_data_bytes{domain="itunes.apple.com"} 5240
+```
+
+Эти метрики не доказывают побайтную эквивалентность с origin. Это эксплуатационный сигнал состояния: настроенный домен действительно основан на реальных закешированных данных профиля, а не на default fallback.
+
+### 5. Снять direct-origin trace
+
+С отдельной клиентской машины подключитесь напрямую к origin:
+
+```bash
+openssl s_client -connect ORIGIN_IP:443 -servername YOUR_DOMAIN </dev/null
+```
+
+Capture:
+
+```bash
+sudo tcpdump -i any -w origin-direct.pcap host ORIGIN_IP and port 443
+```
+
+### 6. Снять Telemt FakeTLS success-path trace
+
+Теперь подключитесь к Telemt через реальный Telegram client с `ee` proxy link, который указывает на Telemt instance.
+
+`openssl s_client` полезен для direct-origin capture и для fallback sanity checks, но он не проходит успешный FakeTLS и MTProto path.
+
+Capture:
+
+```bash
+sudo tcpdump -i any -w telemt-emulated.pcap host TELEMT_IP and port 443
+```
+
+### 7. Декодировать структуру TLS records
+
+Используйте `tshark`, чтобы вывести record-level structure:
+
+```bash
+tshark -r origin-direct.pcap -Y "tls.record" -T fields \
+  -e frame.number \
+  -e ip.src \
+  -e ip.dst \
+  -e tls.record.content_type \
+  -e tls.record.length
+```
+
+```bash
+tshark -r telemt-emulated.pcap -Y "tls.record" -T fields \
+  -e frame.number \
+  -e ip.src \
+  -e ip.dst \
+  -e tls.record.content_type \
+  -e tls.record.length
+```
+
+Смотрите на server flight после ClientHello:
+
+- `22` = Handshake
+- `20` = ChangeCipherSpec
+- `23` = ApplicationData
+
+### 8. Собрать сравнительную таблицу
+
+Обычно достаточно короткой таблицы такого вида:
+
+| Path | CCS count | AppData count in first encrypted flight | Tail AppData lengths |
+| --- | --- | --- | --- |
+| Origin | `N` | `M` | `[a, b, ...]` |
+| Telemt build A | `...` | `...` | `...` |
+| Telemt build B | `...` | `...` | `...` |
+
+По такой таблице должно быть легко увидеть, что:
+
+- FakeTLS success path остаётся валидным;
+- ранний encrypted server flight меняется, когда переиспользуется более богатое profile data;
+- результат подтверждён packet evidence.
+
+## Пример набора capture
+
+Один практический пример такой проверки использует:
+
+- `origin-direct-nginx.pcap`
+- `telemt-ee-before-nginx.pcap`
+- `telemt-ee-after-nginx.pcap`
+
+Практические замечания:
+
+- `origin` снимался как прямое TLS 1.2 connection к `nginx.org`;
+- `before` и `after` снимались на Telemt FakeTLS success path с реальным Telegram client;
+- первый server-side FakeTLS response остаётся валидным в обоих случаях;
+- сегментация раннего encrypted server flight отличается между `before` и `after`, что согласуется с лучшим использованием captured profile data;
+- такой результат показывает заметный эффект на проводе без поломки success path, но не заявляет полной неотличимости от origin.
+
+## Более сильная валидация
+
+Для более широкой проверки повторите ту же процедуру ещё на:
+
+1. одном CDN-backed origin;
+2. одном regular nginx origin;
+3. одном origin с multi-record encrypted flight и заметными ticket-like tails.
+
+Если одно и то же направление улучшения повторится на всех трёх, уверенность в результате будет значительно выше, чем для одного origin example.

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

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

docs/FAQ.en.md

@@ -1,5 +1,4 @@
 ## How to set up a "proxy sponsor" channel and statistics via the @MTProxybot
-
 1. Go to the @MTProxybot.
 2. Enter the `/newproxy` command.
 3. Send your server's IP address and port. For example: `1.2.3.4:443`.
@@ -32,23 +31,161 @@ use_middle_proxy = true
 hello = "ad_tag"
 hello2 = "ad_tag2"
 ```
+## Recognizability for DPI and crawler
 
-## Why do you need a middle proxy (ME)
+On April 1, 2026, we became aware of a method for detecting MTProxy Fake-TLS, 
+based on the ECH extension and the ordering of cipher suites, 
+as well as an overall unique JA3/JA4 fingerprint 
+that does not occur in modern browsers.
+
+> [!IMPORTANT]
+> TLS fingerprint has been fixed in latest version of clients for Desktop / Android / iOS.  
+> Please update your client for MTProxy Fake-TLS to work correctly.
+
+- We consider this a breakthrough aspect, which has no stable analogues today
+- Based on this: if `telemt` configured correctly, **TLS mode is completely identical to real-life handshake + communication** with a specified host
+- Here is our evidence:
+    - 212.220.88.77 - "dummy" host, running `telemt`
+    - `petrovich.ru` - `tls` + `masking` host, in HEX: `706574726f766963682e7275`
+    - **No MITM + No Fake Certificates/Crypto** = pure transparent *TCP Splice* to "best" upstream: MTProxy or tls/mask-host:
+      - DPI see legitimate HTTPS to `tls_host`, including *valid chain-of-trust* and entropy
+      - Crawlers completely satisfied receiving responses from `mask_host`
+  ### Client WITH secret-key accesses the MTProxy resource:
+  
+  <img width="360" height="439" alt="telemt" src="https://github.com/user-attachments/assets/39352afb-4a11-4ecc-9d91-9e8cfb20607d" />
+  
+  ### Client WITHOUT secret-key gets transparent access to the specified resource:
+    - with trusted certificate
+    - with original handshake
+    - with full request-response way
+    - with low-latency overhead
+```bash
+root@debian:~/telemt# curl -v -I --resolve petrovich.ru:443:212.220.88.77 https://petrovich.ru/
+* Added petrovich.ru:443:212.220.88.77 to DNS cache
+* Hostname petrovich.ru was found in DNS cache
+*   Trying 212.220.88.77:443...
+* Connected to petrovich.ru (212.220.88.77) port 443 (#0)
+* ALPN: offers h2,http/1.1
+* TLSv1.3 (OUT), TLS handshake, Client hello (1):
+*  CAfile: /etc/ssl/certs/ca-certificates.crt
+*  CApath: /etc/ssl/certs
+* TLSv1.3 (IN), TLS handshake, Server hello (2):
+* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
+* TLSv1.3 (IN), TLS handshake, Certificate (11):
+* TLSv1.3 (IN), TLS handshake, CERT verify (15):
+* TLSv1.3 (IN), TLS handshake, Finished (20):
+* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
+* TLSv1.3 (OUT), TLS handshake, Finished (20):
+* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
+* ALPN: server did not agree on a protocol. Uses default.
+* Server certificate:
+*  subject: C=RU; ST=Saint Petersburg; L=Saint Petersburg; O=STD Petrovich; CN=*.petrovich.ru
+*  start date: Jan 28 11:21:01 2025 GMT
+*  expire date: Mar  1 11:21:00 2026 GMT
+*  subjectAltName: host "petrovich.ru" matched cert's "petrovich.ru"
+*  issuer: C=BE; O=GlobalSign nv-sa; CN=GlobalSign RSA OV SSL CA 2018
+*  SSL certificate verify ok.
+* using HTTP/1.x
+> HEAD / HTTP/1.1
+> Host: petrovich.ru
+> User-Agent: curl/7.88.1
+> Accept: */*
+> 
+* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
+* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
+* old SSL session ID is stale, removing
+< HTTP/1.1 200 OK
+HTTP/1.1 200 OK
+< Server: Variti/0.9.3a
+Server: Variti/0.9.3a
+< Date: Thu, 01 Jan 2026 00:0000 GMT
+Date: Thu, 01 Jan 2026 00:0000 GMT
+< Access-Control-Allow-Origin: *
+Access-Control-Allow-Origin: *
+< Content-Type: text/html
+Content-Type: text/html
+< Cache-Control: no-store
+Cache-Control: no-store
+< Expires: Thu, 01 Jan 2026 00:0000 GMT
+Expires: Thu, 01 Jan 2026 00:0000 GMT
+< Pragma: no-cache
+Pragma: no-cache
+< Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
+Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
+< Content-Type: text/html
+Content-Type: text/html
+< Content-Length: 31253
+Content-Length: 31253
+< Connection: keep-alive
+Connection: keep-alive
+< Keep-Alive: timeout=60
+Keep-Alive: timeout=60
+
+< 
+* Connection #0 to host petrovich.ru left intact
+
+```
+- We challenged ourselves, we kept trying and we didn't only *beat the air*: now, we have something to show you
+  - Do not just take our word for it? - This is great and we respect that: you can build your own `telemt` or download a build and check it right now
+
+
+## F.A.Q.
+
+### Telegram Calls via MTProxy
+- Telegram architecture **does NOT allow calls via MTProxy**, but only via SOCKS5, which cannot be obfuscated
+
+### How does DPI see MTProxy TLS?
+- DPI sees MTProxy in Fake TLS (ee) mode as TLS 1.3
+- the SNI you specify sends both the client and the server;
+- ALPN is similar to HTTP 1.1/2;
+- high entropy, which is normal for AES-encrypted traffic;
+
+### Whitelist on IP
+- MTProxy cannot work when there is: 
+  - no IP connectivity to the target host: Russian Whitelist on Mobile Networks - "Белый список"
+  - OR all TCP traffic is blocked
+  - OR high entropy/encrypted traffic is blocked: content filters at universities and critical infrastructure
+  - OR all TLS traffic is blocked
+  - OR specified port is blocked: use 443 to make it "like real"
+  - OR provided SNI is blocked: use "officially approved"/innocuous name
+- like most protocols on the Internet; 
+- these situations are observed:
+  - in China behind the Great Firewall
+  - in Russia on mobile networks, less in wired networks
+  - in Iran during "activity"
+
+### Why do you need a middle proxy (ME)
 https://github.com/telemt/telemt/discussions/167
 
+## How clients interact with Telegram DCs
+When you register a Telegram account, it gets permanently bound to one of Telegram's data centers (DCs).  
+It is deciced beforehand by Telegram based on the phone number's region.  
+This DC becomes your **home DC**: all content you upload (photos, videos, files, messages) is stored there.  
+Your client authenticates on it with every connection.  
 
-## How many people can use one link
+For example, if your account is registered on **DC2**, your client will always connect to DC2 first.  
+When you open a chat with another user whose home DC is **DC5**, your client opens an additional connection to DC5 to download their media.  
+Those cross-DC requests are normal and happen constantly.  
 
+> [!WARNING]
+> Because every session is anchored to your home DC, an outage there causes other DCs to be unavaliable.  
+> If your home DC is DC2 and DC2 goes down, you **cannot** reach DC5 even though DC5 itself is perfectly healthy.  
+> The client has no valid session to route the request through.  
+
+This is also why it is required for MTProxy to reach Telegram's DC infrastructure as a whole.  
+The proxy itself doesn't care which DC your account lives on. The client negotiates the correct DC through the proxy after connecting.
+
+### How many people can use one link
 By default, an unlimited number of people can use a single link.  
 However, you can limit the number of unique IP addresses for each user:
 ```toml
 [access.user_max_unique_ips]
 hello = 1
 ```
-This parameter sets the maximum number of unique IP addresses from which a single link can be used simultaneously. If the first user disconnects, a second one can connect. At the same time, multiple users can connect from a single IP address simultaneously (for example, devices on the same Wi-Fi network).
-
-## How to create multiple different links
+This parameter sets the maximum number of unique IP addresses from which a single link can be used simultaneously. If the first user disconnects, a second one can connect.
+At the same time, multiple users can connect from a single IP address simultaneously (for example, devices on the same Wi-Fi network).
 
+### How to create multiple different links
 1. Generate the required number of secrets using the command: `openssl rand -hex 16`.
 2. Open the configuration file: `nano /etc/telemt/telemt.toml`.
 3. Add new users to the `[access.users]` section:
@@ -64,7 +201,7 @@ user3 = "00000000000000000000000000000003"
 curl -s http://127.0.0.1:9091/v1/users | jq
 ```
 
-## "Unknown TLS SNI" error
+### "Unknown TLS SNI" error
 Usually, this error occurs if you have changed the `tls_domain` parameter, but users continue to connect using old links with the previous domain.
 
 If you need to allow connections with any domains (ignoring SNI mismatches), add the following parameters:
@@ -73,7 +210,14 @@ If you need to allow connections with any domains (ignoring SNI mismatches), add
 unknown_sni_action = "mask"
 ```
 
-## How to view metrics
+Alternatively, if you want telemt to behave like a vanilla nginx with `ssl_reject_handshake on;` on unknown SNI (emit a TLS `unrecognized_name` alert and close the connection), use:
+```toml
+[censorship]
+unknown_sni_action = "reject_handshake"
+```
+This does not recover stale clients, but it makes port 443 wire-indistinguishable from a stock web server that simply does not host the requested vhost.
+
+### How to view metrics
 
 1. Open the configuration file: `nano /etc/telemt/telemt.toml`.
 2. Add the following parameters:
@@ -87,6 +231,25 @@ metrics_whitelist = ["127.0.0.1/32", "::1/128", "0.0.0.0/0"]
 > [!WARNING]
 > The value `"0.0.0.0/0"` in `metrics_whitelist` opens access to metrics from any IP address. It is recommended to replace it with your personal IP, for example: `"1.2.3.4/32"`.
 
+### Too many open files
+- On a fresh Linux install the default open file limit is low; under load `telemt` may fail with `Accept error: Too many open files`
+- **Systemd**: add `LimitNOFILE=65536` to the `[Service]` section (already included in the example above)
+- **Docker**: add `--ulimit nofile=65536:65536` to your `docker run` command, or in `docker-compose.yml`:
+```yaml
+ulimits:
+  nofile:
+    soft: 65536
+    hard: 65536
+```
+- **System-wide** (optional): add to `/etc/security/limits.conf`:
+```
+*       soft    nofile  1048576
+*       hard    nofile  1048576
+root    soft    nofile  1048576
+root    hard    nofile  1048576
+```
+
+
 ## Additional parameters
 
 ### Domain in the link instead of IP

docs/FAQ.ru.md

@@ -32,10 +32,166 @@ use_middle_proxy = true
 hello = "ad_tag"
 hello2 = "ad_tag2"
 ```
+## Распознаваемость для DPI и сканеров
+1 апреля 2026 года нам стало известно о методе обнаружения MTProxy Fake-TLS, основанном на расширении ECH и порядке набора шифров,
+а также об общем уникальном отпечатке JA3/JA4, который не встречается в современных браузерах.
+
+> [!IMPORTANT]
+> Проблема с TLS отпечатком исправлена в последних версиях клиентов Telegram для Desktop / Android / iOS.  
+> Обновите свой клиент для корректной работы с MTProxy Fake-TLS!
+
+- Для расследования блокировок на базе JA4 ClientHello используйте отдельную инструкцию: [`JA3 и JA4 анализ в Telemt`](Architecture/Fronting-splitting/TLS_JA3_JA4_ANALYSIS.ru.md).
+
+- Мы считаем это прорывом, которому на сегодняшний день нет стабильных аналогов;
+- Исходя из этого: если `telemt` настроен правильно, **режим TLS полностью идентичен реальному «рукопожатию» + обмену данными** с указанным хостом;
+- Вот наши доказательства:
+    - 212.220.88.77 — «фиктивный» хост, на котором запущен `telemt`;
+    - `petrovich.ru` — хост с `tls` + `masking`, в HEX: `706574726f766963682e7275`;
+    - **Без MITM + без поддельных сертификатов/шифрования** = чистое прозрачное *TCP Splice* к «лучшему» исходному серверу: MTProxy или tls/mask-host:
+      - DPI видит легитимный HTTPS к `tls_host`, включая *достоверную цепочку доверия* и энтропию;
+      - Краулеры полностью удовлетворены получением ответов от `mask_host`.
+ 
+  ### Клиент С секретным ключом получает доступ к ресурсу MTProxy:
+  
+  <img width="360" height="439" alt="telemt" src="https://github.com/user-attachments/assets/39352afb-4a11-4ecc-9d91-9e8cfb20607d" />
+  
+  ### Клиент БЕЗ секретного ключа получает прозрачный доступ к указанному ресурсу:
+    - с доверенным сертификатом;
+    - с исходным «рукопожатием»;
+    - с полным циклом запрос-ответ;
+    - с низкой задержкой.
+
+```bash
+root@debian:~/telemt# curl -v -I --resolve petrovich.ru:443:212.220.88.77 https://petrovich.ru/
+* Added petrovich.ru:443:212.220.88.77 to DNS cache
+* Hostname petrovich.ru was found in DNS cache
+*   Trying 212.220.88.77:443...
+* Connected to petrovich.ru (212.220.88.77) port 443 (#0)
+* ALPN: offers h2,http/1.1
+* TLSv1.3 (OUT), TLS handshake, Client hello (1):
+*  CAfile: /etc/ssl/certs/ca-certificates.crt
+*  CApath: /etc/ssl/certs
+* TLSv1.3 (IN), TLS handshake, Server hello (2):
+* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
+* TLSv1.3 (IN), TLS handshake, Certificate (11):
+* TLSv1.3 (IN), TLS handshake, CERT verify (15):
+* TLSv1.3 (IN), TLS handshake, Finished (20):
+* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
+* TLSv1.3 (OUT), TLS handshake, Finished (20):
+* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
+* ALPN: server did not agree on a protocol. Uses default.
+* Server certificate:
+*  subject: C=RU; ST=Saint Petersburg; L=Saint Petersburg; O=STD Petrovich; CN=*.petrovich.ru
+*  start date: Jan 28 11:21:01 2025 GMT
+*  expire date: Mar  1 11:21:00 2026 GMT
+*  subjectAltName: host "petrovich.ru" matched cert's "petrovich.ru"
+*  issuer: C=BE; O=GlobalSign nv-sa; CN=GlobalSign RSA OV SSL CA 2018
+*  SSL certificate verify ok.
+* using HTTP/1.x
+> HEAD / HTTP/1.1
+> Host: petrovich.ru
+> User-Agent: curl/7.88.1
+> Accept: */*
+> 
+* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
+* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
+* old SSL session ID is stale, removing
+< HTTP/1.1 200 OK
+HTTP/1.1 200 OK
+< Server: Variti/0.9.3a
+Server: Variti/0.9.3a
+< Date: Thu, 01 Jan 2026 00:0000 GMT
+Date: Thu, 01 Jan 2026 00:0000 GMT
+< Access-Control-Allow-Origin: *
+Access-Control-Allow-Origin: *
+< Content-Type: text/html
+Content-Type: text/html
+< Cache-Control: no-store
+Cache-Control: no-store
+< Expires: Thu, 01 Jan 2026 00:0000 GMT
+Expires: Thu, 01 Jan 2026 00:0000 GMT
+< Pragma: no-cache
+Pragma: no-cache
+< Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
+Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
+< Content-Type: text/html
+Content-Type: text/html
+< Content-Length: 31253
+Content-Length: 31253
+< Connection: keep-alive
+Connection: keep-alive
+< Keep-Alive: timeout=60
+Keep-Alive: timeout=60
+
+< 
+* Connection #0 to host petrovich.ru left intact
+
+```
+- Мы поставили перед собой задачу, не сдавались и не просто «бились в пустоту»: теперь у нас есть что вам показать.
+- Не верите нам на слово? — Это прекрасно, и мы уважаем ваше решение: вы можете собрать свой собственный `telemt` или скачать готовую сборку и проверить её прямо сейчас.
+
+### Звонки в Telegram через MTProxy
+- Архитектура Telegram **НЕ поддерживает звонки через MTProxy**, а только через SOCKS5, который невозможно замаскировать
+
+### Как DPI распознает TLS-соединение MTProxy?
+- DPI распознает MTProxy в режиме Fake TLS (ee) как TLS 1.3
+- указанный вами SNI отправляется как клиентом, так и сервером;
+- ALPN аналогичен HTTP 1.1/2;
+- высокая энтропия, что нормально для трафика, зашифрованного AES;
+
+### Белый список по IP
+- MTProxy не может работать, если: 
+  - отсутствует IP-связь с целевым хостом: российский белый список в мобильных сетях — «Белый список»;
+  - ИЛИ весь TCP-трафик заблокирован;
+  - ИЛИ трафик с высокой энтропией/зашифрованный трафик заблокирован: контент-фильтры в университетах и критически важной инфраструктуре;
+  - ИЛИ весь TLS-трафик заблокирован;
+  - ИЛИ заблокирован указанный порт: используйте 443, чтобы сделать его «как настоящий»;
+  - ИЛИ заблокирован предоставленный SNI: используйте «официально одобренное»/безобидное имя;
+- как и большинство протоколов в Интернете; 
+- такие ситуации наблюдаются:
+  - в Китае за Великим файрволом;
+  - в России в мобильных сетях, реже в проводных сетях;
+  - в Иране во время «активности».
+
 
 ## Зачем нужен middle proxy (ME)
 https://github.com/telemt/telemt/discussions/167
 
+## Как клиенты взаимодействуют с дата-центрами Telegram
+При регистрации аккаунта Telegram он навсегда привязывается к одному из дата-центров (DC).  
+Telegram заранее определяет к какому DC привязать аккаунт исходя из региона, к которому относится номер телефона.  
+Этот DC становится вашим **домашним**: именно там хранится весь контент, который вы загружаете (фото, видео, файлы, сообщения).  
+И именно на нем клиент авторизуется при каждом подключении.  
+
+Например, если ваш аккаунт зарегистрирован на **DC2**, клиент всегда будет подключаться в первую очередь к DC2.  
+Когда вы открываете переписку с пользователем, чей домашний DC — **DC5**, клиент устанавливает доп. соединение с DC5, чтобы загрузить его контент.  
+Такие кросс-запросы к DC — это нормальная часть работы Telegram.  
+
+> [!WARNING]
+> Поскольку аккаунт всегда привязан к домашнему DC, при его падении контент с других DC будет недоступен.  
+> Если ваш домашний DC — DC2, и DC2 лежит, вы **не сможете** достучаться  и до DC5, даже если сам DC5 полностью исправен.  
+> У клиента просто нет валидной сессии, через которую можно было бы направить запрос.  
+
+По той же причине MTProxy необходимо иметь доступ к инфраструктуре Telegram целиком, а не частично.  
+Cамому MTProxy всё равно, на каком DC живёт ваш аккаунт. Клиент cам договаривается о нужном DC через прокси уже после подключения.  
+
+## Что такое dd и ee в контексте MTProxy?
+
+Это два разных режима работы прокси. Понять, какой режим используется, можно взглянув на начало секрета — там будет dd или ee, вот пример:
+tg://proxy?server=s1.dimasssss.space&port=443&secret=eebe3007e927acd147dde12bee8b1a7c9364726976652e676f6f676c652e636f6d
+
+dd — режим с мусорным трафиком, обфускацией данных, похожий на shadowsocks. У такого трафика есть заметный паттерн, который DPI умеют распознавать и впоследствии блокировать. Использовать этот режим на текущий момент не рекомендуется.
+
+ee — режим маскировки под существующий домен (FakeTLS), словно вы сёрфите в интернете через браузер. На текущий момент не попадает под блокировку.
+
+### Где эти режимы настраиваются?
+
+```toml
+В конфиге telemt.toml в разделе [general.modes]:
+classic = false # классический режим, давно стал бесполезным
+secure = false # переменная dd-режима
+tls = true # переменная ee-режима
+```
 
 ## Сколько человек может пользоваться одной ссылкой
 
@@ -73,6 +229,13 @@ curl -s http://127.0.0.1:9091/v1/users | jq
 unknown_sni_action = "mask"
 ```
 
+Альтернатива: если вы хотите, чтобы telemt на неизвестный SNI вёл себя как обычный nginx с `ssl_reject_handshake on;` (отдавал TLS-alert `unrecognized_name` и закрывал соединение), используйте:
+```toml
+[censorship]
+unknown_sni_action = "reject_handshake"
+```
+Это не пропускает старых клиентов, но делает поведение на 443-м порту неотличимым от стокового веб-сервера, у которого просто нет такого виртуального хоста.
+
 ## Как посмотреть метрики
 
 1. Откройте файл конфигурации: `nano /etc/telemt/telemt.toml`.
@@ -104,7 +267,7 @@ max_connections = 10000    # 0 - без ограничений, 10000 - по у
 ```
 
 ### Upstream Manager
-Для настройки исходящих подключений (апстримов) добавьте соответствующие параметры в секцию `[[upstreams]]` файла конфигурации:
+Для настройки исходящих подключений (Upstreams) добавьте соответствующие параметры в секцию `[[upstreams]]` файла конфигурации:
 
 #### Привязка к исходящему IP-адресу
 ```toml
@@ -119,20 +282,20 @@ interface = "192.168.1.100" # Замените на ваш исходящий IP
 - Без авторизации:
 ```toml
 [[upstreams]]
-type = "socks5"            # Specify SOCKS4 or SOCKS5
-address = "1.2.3.4:1234"   # SOCKS-server Address
-weight = 1                 # Set Weight for Scenarios
+type = "socks5"            # выбор типа SOCKS4 или SOCKS5
+address = "1.2.3.4:1234"   # адрес сервера SOCKS
+weight = 1                 # вес
 enabled = true
 ```
 
 - С авторизацией:
 ```toml
 [[upstreams]]
-type = "socks5"            # Specify SOCKS4 or SOCKS5
-address = "1.2.3.4:1234"   # SOCKS-server Address
-username = "user"          # Username for Auth on SOCKS-server
-password = "pass"          # Password for Auth on SOCKS-server
-weight = 1                 # Set Weight for Scenarios
+type = "socks5"            # выбор типа SOCKS4 или SOCKS5
+address = "1.2.3.4:1234"   # адрес сервера SOCKS
+username = "user"          # имя пользователя
+password = "pass"          # пароль
+weight = 1                 # вес
 enabled = true
 ```
 

docs/LICENSE/LICENSE.de.md

@@ -1,92 +0,0 @@
-# Öffentliche TELEMT-Lizenz 3
-
-***Alle Rechte vorbehalten (c) 2026 Telemt***
-
-Hiermit wird jeder Person, die eine Kopie dieser Software und der dazugehörigen Dokumentation (nachfolgend "Software") erhält, unentgeltlich die Erlaubnis erteilt, die Software ohne Einschränkungen zu nutzen, einschließlich des Rechts, die Software zu verwenden, zu vervielfältigen, zu ändern, abgeleitete Werke zu erstellen, zu verbinden, zu veröffentlichen, zu verbreiten, zu unterlizenzieren und/oder Kopien der Software zu verkaufen sowie diese Rechte auch denjenigen einzuräumen, denen die Software zur Verfügung gestellt wird, vorausgesetzt, dass sämtliche Urheberrechtshinweise sowie die Bedingungen und Bestimmungen dieser Lizenz eingehalten werden.
-
-### Begriffsbestimmungen
-
-Für die Zwecke dieser Lizenz gelten die folgenden Definitionen:
-
-**"Software" (Software)** — die Telemt-Software einschließlich Quellcode, Dokumentation und sämtlicher zugehöriger Dateien, die unter den Bedingungen dieser Lizenz verbreitet werden.
-
-**"Contributor" (Contributor)** — jede natürliche oder juristische Person, die Code, Patches, Dokumentation oder andere Materialien eingereicht hat, die von den Maintainers des Projekts angenommen und in die Software aufgenommen wurden.
-
-**"Beitrag" (Contribution)** — jedes urheberrechtlich geschützte Werk, das bewusst zur Aufnahme in die Software eingereicht wurde.
-
-**"Modifizierte Version" (Modified Version)** — jede Version der Software, die gegenüber der ursprünglichen Software geändert, angepasst, erweitert oder anderweitig modifiziert wurde.
-
-**"Maintainers" (Maintainers)** — natürliche oder juristische Personen, die für das offizielle Telemt-Projekt und dessen offizielle Veröffentlichungen verantwortlich sind.
-
-### 1 Urheberrechtshinweis (Attribution)
-
-Bei der Weitergabe der Software, sowohl in Form des Quellcodes als auch in binärer Form, MÜSSEN folgende Elemente erhalten bleiben:
-
-- der oben genannte Urheberrechtshinweis;
-- der vollständige Text dieser Lizenz;
-- sämtliche bestehenden Hinweise auf Urheberschaft.
-
-### 2 Hinweis auf Modifikationen
-
-Wenn Änderungen an der Software vorgenommen werden, MUSS die Person, die diese Änderungen vorgenommen hat, eindeutig darauf hinweisen, dass die Software modifiziert wurde, und eine kurze Beschreibung der vorgenommenen Änderungen beifügen.
-
-Modifizierte Versionen der Software DÜRFEN NICHT als die originale Version von Telemt dargestellt werden.
-
-### 3 Marken und Bezeichnungen
-
-Diese Lizenz GEWÄHRT KEINE Rechte zur Nutzung der Bezeichnung **"Telemt"**, des Telemt-Logos oder sonstiger Marken, Kennzeichen oder Branding-Elemente von Telemt.
-
-Weiterverbreitete oder modifizierte Versionen der Software DÜRFEN die Bezeichnung Telemt nicht in einer Weise verwenden, die bei Nutzern den Eindruck eines offiziellen Ursprungs oder einer Billigung durch das Telemt-Projekt erwecken könnte, sofern hierfür keine ausdrückliche Genehmigung der Maintainers vorliegt.
-
-Die Verwendung der Bezeichnung **Telemt** zur Beschreibung einer modifizierten Version der Software ist nur zulässig, wenn diese Version eindeutig als modifiziert oder inoffiziell gekennzeichnet ist.
-
-Jegliche Verbreitung, die Nutzer vernünftigerweise darüber täuschen könnte, dass es sich um eine offizielle Veröffentlichung von Telemt handelt, ist untersagt.
-
-### 4 Transparenz bei der Verbreitung von Binärversionen
-
-Im Falle der Verbreitung kompilierter Binärversionen der Software wird der Verbreiter HIERMIT ERMUTIGT (encouraged), soweit dies vernünftigerweise möglich ist, Zugang zum entsprechenden Quellcode sowie zu den Build-Anweisungen bereitzustellen.
-
-Diese Praxis trägt zur Transparenz bei und ermöglicht es Empfängern, die Integrität und Reproduzierbarkeit der verbreiteten Builds zu überprüfen.
-
-## 5 Gewährung einer Patentlizenz und Beendigung von Rechten
-
-Jeder Contributor gewährt den Empfängern der Software eine unbefristete, weltweite, nicht-exklusive, unentgeltliche, lizenzgebührenfreie und unwiderrufliche Patentlizenz für:
-
-- die Herstellung,
-- die Beauftragung der Herstellung,
-- die Nutzung,
-- das Anbieten zum Verkauf,
-- den Verkauf,
-- den Import,
-- sowie jede sonstige Verbreitung der Software.
-
-Diese Patentlizenz erstreckt sich ausschließlich auf solche Patentansprüche, die notwendigerweise durch den jeweiligen Beitrag des Contributors allein oder in Kombination mit der Software verletzt würden.
-
-Leitet eine Person ein Patentverfahren ein oder beteiligt sich daran, einschließlich Gegenklagen oder Kreuzklagen, mit der Behauptung, dass die Software oder ein darin enthaltener Beitrag ein Patent verletzt, **erlöschen sämtliche durch diese Lizenz gewährten Rechte für diese Person unmittelbar mit Einreichung der Klage**.
-
-Darüber hinaus erlöschen alle durch diese Lizenz gewährten Rechte **automatisch**, wenn eine Person ein gerichtliches Verfahren einleitet, in dem behauptet wird, dass die Software selbst ein Patent oder andere Rechte des geistigen Eigentums verletzt.
-
-### 6 Beteiligung und Beiträge zur Entwicklung
-
-Sofern ein Contributor nicht ausdrücklich etwas anderes erklärt, gilt jeder Beitrag, der bewusst zur Aufnahme in die Software eingereicht wird, als unter den Bedingungen dieser Lizenz lizenziert.
-
-Durch die Einreichung eines Beitrags gewährt der Contributor den Maintainers des Telemt-Projekts sowie allen Empfängern der Software die in dieser Lizenz beschriebenen Rechte in Bezug auf diesen Beitrag.
-
-### 7 Urheberhinweis bei Netzwerk- und Servicenutzung
-
-Wird die Software zur Bereitstellung eines öffentlich zugänglichen Netzwerkdienstes verwendet, MUSS der Betreiber dieses Dienstes einen Hinweis auf die Urheberschaft von Telemt an mindestens einer der folgenden Stellen anbringen:
-
-* in der Servicedokumentation;
-* in der Dienstbeschreibung;
-* auf einer Seite "Über" oder einer vergleichbaren Informationsseite;
-* in anderen für Nutzer zugänglichen Materialien, die in angemessenem Zusammenhang mit dem Dienst stehen.
-
-Ein solcher Hinweis DARF NICHT den Eindruck erwecken, dass der Dienst vom Telemt-Projekt oder dessen Maintainers unterstützt oder offiziell gebilligt wird.
-
-### 8 Haftungsausschluss und salvatorische Klausel
-
-DIE SOFTWARE WIRD "WIE BESEHEN" BEREITGESTELLT, OHNE JEGLICHE AUSDRÜCKLICHE ODER STILLSCHWEIGENDE GEWÄHRLEISTUNG, EINSCHLIESSLICH, ABER NICHT BESCHRÄNKT AUF GEWÄHRLEISTUNGEN DER MARKTGÄNGIGKEIT, DER EIGNUNG FÜR EINEN BESTIMMTEN ZWECK UND DER NICHTVERLETZUNG VON RECHTEN.
-
-IN KEINEM FALL HAFTEN DIE AUTOREN ODER RECHTEINHABER FÜR IRGENDWELCHE ANSPRÜCHE, SCHÄDEN ODER SONSTIGE HAFTUNG, DIE AUS VERTRAG, UNERLAUBTER HANDLUNG ODER AUF ANDERE WEISE AUS DER SOFTWARE ODER DER NUTZUNG DER SOFTWARE ENTSTEHEN.
-
-SOLLTE EINE BESTIMMUNG DIESER LIZENZ ALS UNWIRKSAM ODER NICHT DURCHSETZBAR ANGESEHEN WERDEN, IST DIESE BESTIMMUNG SO AUSZULEGEN, DASS SIE DEM URSPRÜNGLICHEN WILLEN DER PARTEIEN MÖGLICHST NAHEKOMMT; DIE ÜBRIGEN BESTIMMUNGEN BLEIBEN DAVON UNBERÜHRT UND IN VOLLER WIRKUNG.

docs/LICENSE/LICENSE.en.md

@@ -1,143 +0,0 @@
-###### TELEMT Public License 3 ######
-##### Copyright (c) 2026 Telemt #####
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this Software and associated documentation files (the "Software"),
-to use, reproduce, modify, prepare derivative works of, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to permit
-persons to whom the Software is furnished to do so, provided that all
-copyright notices, license terms, and conditions set forth in this License
-are preserved and complied with.
-
-### Official Translations
-
-The canonical version of this License is the English version.
-
-Official translations are provided for informational purposes only
-and for convenience, and do not have legal force. In case of any
-discrepancy, the English version of this License shall prevail.
-
-Available versions:
-- English in Markdown: docs/LICENSE/LICENSE.md
-- German: docs/LICENSE/LICENSE.de.md
-- Russian: docs/LICENSE/LICENSE.ru.md
-
-### Definitions
-
-For the purposes of this License:
-
-"Software" means the Telemt software, including source code, documentation,
-and any associated files distributed under this License.
-
-"Contributor" means any person or entity that submits code, patches,
-documentation, or other contributions to the Software that are accepted
-into the Software by the maintainers.
-
-"Contribution" means any work of authorship intentionally submitted
-to the Software for inclusion in the Software.
-
-"Modified Version" means any version of the Software that has been
-changed, adapted, extended, or otherwise modified from the original
-Software.
-
-"Maintainers" means the individuals or entities responsible for
-the official Telemt project and its releases.
-
-#### 1 Attribution
-
-Redistributions of the Software, in source or binary form, MUST RETAIN the
-above copyright notice, this license text, and any existing attribution
-notices.
-
-#### 2 Modification Notice
-
-If you modify the Software, you MUST clearly state that the Software has been
-modified and include a brief description of the changes made.
-
-Modified versions MUST NOT be presented as the original Telemt.
-
-#### 3 Trademark and Branding
-
-This license DOES NOT grant permission to use the name "Telemt", 
-the Telemt logo, or any Telemt trademarks or branding.
-
-Redistributed or modified versions of the Software MAY NOT use the Telemt
-name in a way that suggests endorsement or official origin without explicit
-permission from the Telemt maintainers.
-
-Use of the name "Telemt" to describe a modified version of the Software
-is permitted only if the modified version is clearly identified as a
-modified or unofficial version.
-
-Any distribution that could reasonably confuse users into believing that
-the software is an official Telemt release is prohibited.
-
-#### 4 Binary Distribution Transparency
-
-If you distribute compiled binaries of the Software,
-you are ENCOURAGED to provide access to the corresponding
-source code and build instructions where reasonably possible.
-
-This helps preserve transparency and allows recipients to verify the
-integrity and reproducibility of distributed builds.
-
-#### 5 Patent Grant and Defensive Termination Clause
-
-Each contributor grants you a perpetual, worldwide, non-exclusive,
-no-charge, royalty-free, irrevocable patent license to make, have made,
-use, offer to sell, sell, import, and otherwise transfer the Software.
-
-This patent license applies only to those patent claims necessarily
-infringed by the contributor’s contribution alone or by combination of
-their contribution with the Software.
-
-If you initiate or participate in any patent litigation, including
-cross-claims or counterclaims, alleging that the Software or any
-contribution incorporated within the Software constitutes patent
-infringement, then **all rights granted to you under this license shall
-terminate immediately** as of the date such litigation is filed.
-
-Additionally, if you initiate legal action alleging that the
-Software itself infringes your patent or other intellectual
-property rights, then all rights granted to you under this
-license SHALL TERMINATE automatically.
-
-#### 6 Contributions
-
-Unless you explicitly state otherwise, any Contribution intentionally
-submitted for inclusion in the Software shall be licensed under the terms
-of this License.
-
-By submitting a Contribution, you grant the Telemt maintainers and all
-recipients of the Software the rights described in this License with
-respect to that Contribution.
-
-#### 7 Network Use Attribution
-
-If the Software is used to provide a publicly accessible network service,
-the operator of such service MUST provide attribution to Telemt in at least
-one of the following locations:
-
-- service documentation
-- service description
-- an "About" or similar informational page
-- other user-visible materials reasonably associated with the service
-
-Such attribution MUST NOT imply endorsement by the Telemt project or its
-maintainers.
-
-#### 8 Disclaimer of Warranty and Severability Clause
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
-DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
-OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
-USE OR OTHER DEALINGS IN THE SOFTWARE
-
-IF ANY PROVISION OF THIS LICENSE IS HELD TO BE INVALID OR UNENFORCEABLE,
-SUCH PROVISION SHALL BE INTERPRETED TO REFLECT THE ORIGINAL INTENT
-OF THE PARTIES AS CLOSELY AS POSSIBLE, AND THE REMAINING PROVISIONS
-SHALL REMAIN IN FULL FORCE AND EFFECT

docs/LICENSE/LICENSE.ru.md

@@ -1,90 +0,0 @@
-# Публичная лицензия TELEMT 3
-
-***Все права защищёны (c) 2026 Telemt***
-
-Настоящим любому лицу, получившему копию данного программного обеспечения и сопутствующей документации (далее — "Программное обеспечение"), безвозмездно предоставляется разрешение использовать Программное обеспечение без ограничений, включая право использовать, воспроизводить, изменять, создавать производные произведения, объединять, публиковать, распространять, сублицензировать и (или) продавать копии Программного обеспечения, а также предоставлять такие права лицам, которым предоставляется Программное обеспечение, при условии соблюдения всех уведомлений об авторских правах, условий и положений настоящей Лицензии.
-
-### Определения
-
-Для целей настоящей Лицензии применяются следующие определения:
-
-**"Программное обеспечение" (Software)** — программное обеспечение Telemt, включая исходный код, документацию и любые связанные файлы, распространяемые на условиях настоящей Лицензии.
-
-**"Контрибьютор" (Contributor)** — любое физическое или юридическое лицо, направившее код, исправления (патчи), документацию или иные материалы, которые были приняты мейнтейнерами проекта и включены в состав Программного обеспечения.
-
-**"Вклад" (Contribution)** — любое произведение авторского права, намеренно представленное для включения в состав Программного обеспечения.
-
-**"Модифицированная версия" (Modified Version)** — любая версия Программного обеспечения, которая была изменена, адаптирована, расширена или иным образом модифицирована по сравнению с исходным Программным обеспечением.
-
-**"Мейнтейнеры" (Maintainers)** — физические или юридические лица, ответственные за официальный проект Telemt и его официальные релизы.
-
-### 1 Указание авторства
-
-При распространении Программного обеспечения, как в форме исходного кода, так и в бинарной форме, ДОЛЖНЫ СОХРАНЯТЬСЯ:
-
-- указанное выше уведомление об авторских правах;
-- текст настоящей Лицензии;
-- любые существующие уведомления об авторстве.
-
-### 2 Уведомление о модификации
-
-В случае внесения изменений в Программное обеспечение лицо, осуществившее такие изменения, ОБЯЗАНО явно указать, что Программное обеспечение было модифицировано, а также включить краткое описание внесённых изменений.
-
-Модифицированные версии Программного обеспечения НЕ ДОЛЖНЫ представляться как оригинальная версия Telemt.
-
-### 3 Товарные знаки и обозначения
-
-Настоящая Лицензия НЕ ПРЕДОСТАВЛЯЕТ права использовать наименование **"Telemt"**, логотип Telemt, а также любые товарные знаки, фирменные обозначения или элементы бренда Telemt.
-
-Распространяемые или модифицированные версии Программного обеспечения НЕ ДОЛЖНЫ использовать наименование Telemt таким образом, который может создавать у пользователей впечатление официального происхождения либо одобрения со стороны проекта Telemt без явного разрешения мейнтейнеров проекта.
-
-Использование наименования **Telemt** для описания модифицированной версии Программного обеспечения допускается только при условии, что такая версия ясно обозначена как модифицированная или неофициальная.
-
-Запрещается любое распространение, которое может разумно вводить пользователей в заблуждение относительно того, что программное обеспечение является официальным релизом Telemt.
-
-### 4 Прозрачность распространения бинарных версий
-
-В случае распространения скомпилированных бинарных версий Программного обеспечения распространитель НАСТОЯЩИМ ПОБУЖДАЕТСЯ предоставлять доступ к соответствующему исходному коду и инструкциям по сборке, если это разумно возможно.
-
-Такая практика способствует прозрачности распространения и позволяет получателям проверять целостность и воспроизводимость распространяемых сборок.
-
-### 5 Предоставление патентной лицензии и прекращение прав
-
-Каждый контрибьютор предоставляет получателям Программного обеспечения бессрочную, всемирную, неисключительную, безвозмездную, не требующую выплаты роялти и безотзывную патентную лицензию на:
-
-- изготовление,
-- поручение изготовления,
-- использование,
-- предложение к продаже,
-- продажу,
-- импорт,
-- и иное распространение Программного обеспечения.
-
-Такая патентная лицензия распространяется исключительно на те патентные требования, которые неизбежно нарушаются соответствующим вкладом контрибьютора как таковым либо его сочетанием с Программным обеспечением.
-
-Если лицо инициирует либо участвует в каком-либо судебном разбирательстве по патентному спору, включая встречные или перекрёстные иски, утверждая, что Программное обеспечение либо любой вклад, включённый в него, нарушает патент, **все права, предоставленные такому лицу настоящей Лицензией, немедленно прекращаются** с даты подачи соответствующего иска.
-
-Кроме того, если лицо инициирует судебное разбирательство, утверждая, что само Программное обеспечение нарушает его патентные либо иные права интеллектуальной собственности, все права, предоставленные настоящей Лицензией, **автоматически прекращаются**.
-
-### 6 Участие и вклад в разработку
-
-Если контрибьютор явно не указал иное, любой Вклад, намеренно представленный для включения в Программное обеспечение, считается лицензированным на условиях настоящей Лицензии.
-Путём предоставления Вклада контрибьютор предоставляет мейнтейнером проекта Telemt и всем получателям Программного обеспечения права, предусмотренные настоящей Лицензией, в отношении такого Вклада.
-
-### 7 Указание авторства при сетевом и сервисном использовании
-
-В случае использования Программного обеспечения для предоставления публично доступного сетевого сервиса оператор такого сервиса ОБЯЗАН обеспечить указание авторства Telemt как минимум в одном из следующих мест:
-- документация сервиса;
-- описание сервиса;
-- страница "О программе" или аналогичная информационная страница;
-- иные материалы, доступные пользователям и разумно связанные с данным сервисом.
-
-Такое указание авторства НЕ ДОЛЖНО создавать впечатление одобрения или официальной поддержки со стороны проекта Telemt либо его мейнтейнеров.
-
-### 8 Отказ от гарантий и делимость положений
-
-ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ "КАК ЕСТЬ", БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ГАРАНТИЯМИ КОММЕРЧЕСКОЙ ПРИГОДНОСТИ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ.
-
-НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ТРЕБОВАНИЯМ, УБЫТКАМ ИЛИ ИНОЙ ОТВЕТСТВЕННОСТИ, ВОЗНИКАЮЩЕЙ В РЕЗУЛЬТАТЕ ДОГОВОРА, ДЕЛИКТА ИЛИ ИНЫМ ОБРАЗОМ, СВЯЗАННЫМ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ЕГО ИСПОЛЬЗОВАНИЕМ.
-
-В СЛУЧАЕ ЕСЛИ КАКОЕ-ЛИБО ПОЛОЖЕНИЕ НАСТОЯЩЕЙ ЛИЦЕНЗИИ ПРИЗНАЁТСЯ НЕДЕЙСТВИТЕЛЬНЫМ ИЛИ НЕПРИМЕНИМЫМ, ТАКОЕ ПОЛОЖЕНИЕ ПОДЛЕЖИТ ТОЛКОВАНИЮ МАКСИМАЛЬНО БЛИЗКО К ИСХОДНОМУ НАМЕРЕНИЮ СТОРОН, ПРИ ЭТОМ ОСТАЛЬНЫЕ ПОЛОЖЕНИЯ СОХРАНЯЮТ ПОЛНУЮ ЮРИДИЧЕСКУЮ СИЛУ.

docs/LICENSE/TELEMT-LICENSE.en.md

@@ -0,0 +1,120 @@
+# TELEMT License 3.3
+
+***Copyright (c) 2026 Telemt***
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this Software and associated documentation files (the "Software"), to use, reproduce, modify, prepare derivative works of, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that all copyright notices, license terms, and conditions set forth in this License are preserved and complied with.
+
+### Official Translations
+
+The canonical version of this License is the English version.
+Official translations are provided for informational purposes only and for convenience, and do not have legal force. In case of any discrepancy, the English version of this License shall prevail.
+
+| Language    | Location |
+|-------------|----------|
+| English     | [docs/LICENSE/TELEMT-LICENSE.en.md](https://github.com/telemt/telemt/tree/main/docs/LICENSE/TELEMT-LICENSE.en.md)|
+| German      | [docs/LICENSE/TELEMT-LICENSE.de.md](https://github.com/telemt/telemt/tree/main/docs/LICENSE/TELEMT-LICENSE.de.md)|
+| Russian     | [docs/LICENSE/TELEMT-LICENSE.ru.md](https://github.com/telemt/telemt/tree/main/docs/LICENSE/TELEMT-LICENSE.ru.md)|
+
+### License Versioning Policy
+
+This License is version 3.3 of the TELEMT License.
+Each version of the Software is licensed under the License that accompanies its corresponding source code distribution.
+
+Future versions of the Software may be distributed under a different version of the TELEMT Public License or under a different license, as determined by the Telemt maintainers.
+
+Any such change of license applies only to the versions of the Software distributed with the new license and SHALL NOT retroactively affect any previously released versions of the Software.
+
+Recipients of the Software are granted rights only under the License provided with the version of the Software they received.
+
+Redistributions of the Software, including Modified Versions, MUST preserve the copyright notices, license text, and conditions of this License for all portions of the Software derived from Telemt.
+
+Additional terms or licenses may be applied to modifications or additional code added by a redistributor, provided that such terms do not restrict or alter the rights granted under this License for the original Telemt Software.
+
+Nothing in this section limits the rights granted under this License for versions of the Software already released.
+
+### Definitions
+
+For the purposes of this License:
+
+**"Software"** means the Telemt software, including source code, documentation, and any associated files distributed under this License.
+
+**"Contributor"** means any person or entity that submits code, patches, documentation, or other contributions to the Software that are accepted into the Software by the maintainers.
+
+**"Contribution"** means any work of authorship intentionally submitted to the Software for inclusion in the Software.
+
+**"Modified Version"** means any version of the Software that has been changed, adapted, extended, or otherwise modified from the original Software.
+
+**"Maintainers"** means the individuals or entities responsible for the official Telemt project and its releases.
+
+### 1 Attribution
+
+Redistributions of the Software, in source or binary form, MUST RETAIN:
+
+- the above copyright notice;
+- this license text;
+- any existing attribution notices.
+
+### 2 Modification Notice
+
+If you modify the Software, you MUST clearly state that the Software has been modified and include a brief description of the changes made.
+
+Modified versions MUST NOT be presented as the original Telemt.
+
+### 3 Trademark and Branding
+
+This license DOES NOT grant permission to use the name "Telemt", the Telemt logo, or any Telemt trademarks or branding.
+
+Redistributed or modified versions of the Software MAY NOT use the Telemt name in a way that suggests endorsement or official origin without explicit permission from the Telemt maintainers.
+
+Use of the name "Telemt" to describe a modified version of the Software is permitted only if the modified version is clearly identified as a modified or unofficial version.
+
+Any distribution that could reasonably confuse users into believing that the software is an official Telemt release is prohibited.
+
+### 4 Binary Distribution Transparency
+
+If you distribute compiled binaries of the Software, you are ENCOURAGED to provide access to the corresponding source code and build instructions where reasonably possible.
+
+This helps preserve transparency and allows recipients to verify the integrity and reproducibility of distributed builds.
+
+### 5 Patent Grant and Defensive Termination Clause
+
+Each contributor grants you a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to:
+
+- make,
+- have made,
+- use,
+- offer to sell,
+- sell,
+- import,
+- and otherwise transfer the Software.
+
+This patent license applies only to those patent claims necessarily infringed by the contributor’s contribution alone or by combination of their contribution with the Software.
+
+If you initiate or participate in any patent litigation, including cross-claims or counterclaims, alleging that the Software or any contribution incorporated within the Software constitutes patent infringement, then **all rights granted to you under this license shall terminate immediately** as of the date such litigation is filed.
+
+Additionally, if you initiate legal action alleging that the Software itself infringes your patent or other intellectual property rights, then all rights granted to you under this license SHALL TERMINATE automatically.
+
+### 6 Contributions
+
+Unless you explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Software shall be licensed under the terms of this License.
+
+By submitting a Contribution, you grant the Telemt maintainers and all recipients of the Software the rights described in this License with respect to that Contribution.
+
+### 7 Network Use Attribution
+
+If the Software is used to provide a publicly accessible network service, the operator of such service SHOULD provide attribution to Telemt in at least one of the following locations:
+
+- service documentation;
+- service description;
+- an "About" or similar informational page;
+- other user-visible materials reasonably associated with the service.
+
+Such attribution MUST NOT imply endorsement by the Telemt project or its maintainers.
+
+### 8 Disclaimer of Warranty and Severability Clause
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+IF ANY PROVISION OF THIS LICENSE IS HELD TO BE INVALID OR UNENFORCEABLE, SUCH PROVISION SHALL BE INTERPRETED TO REFLECT THE ORIGINAL INTENT OF THE PARTIES AS CLOSELY AS POSSIBLE, AND THE REMAINING PROVISIONS SHALL REMAIN IN FULL FORCE AND EFFECT.

docs/LICENSE/TELEMT-LICENSE.ru.md

@@ -0,0 +1,120 @@
+# TELEMT Лицензия 3.3
+
+***Copyright (c) 2026 Telemt***
+
+Настоящим безвозмездно предоставляется разрешение любому лицу, получившему копию данного программного обеспечения и сопутствующей документации (далее — "Программное обеспечение"), использовать, воспроизводить, изменять, создавать производные произведения, объединять, публиковать, распространять, сублицензировать и/или продавать копии Программного обеспечения, а также разрешать лицам, которым предоставляется Программное обеспечение, осуществлять указанные действия при условии соблюдения и сохранения всех уведомлений об авторском праве, условий и положений настоящей Лицензии.
+
+### Официальные переводы
+
+Канонической версией настоящей Лицензии является версия на английском языке.  
+Официальные переводы предоставляются исключительно в информационных целях и для удобства и не имеют юридической силы. В случае любых расхождений приоритет имеет английская версия.
+
+| Язык       | Расположение |
+|------------|--------------|
+| Русский    | [docs/LICENSE/TELEMT-LICENSE.ru.md](https://github.com/telemt/telemt/tree/main/docs/LICENSE/TELEMT-LICENSE.ru.md)|
+| Английский | [docs/LICENSE/TELEMT-LICENSE.en.md](https://github.com/telemt/telemt/tree/main/docs/LICENSE/TELEMT-LICENSE.en.md)|
+| Немецкий   | [docs/LICENSE/TELEMT-LICENSE.de.md](https://github.com/telemt/telemt/tree/main/docs/LICENSE/TELEMT-LICENSE.de.md)|
+
+### Политика версионирования лицензии
+
+Настоящая Лицензия является версией 3.3 Лицензии TELEMT.  
+Каждая версия Программного обеспечения лицензируется в соответствии с Лицензией, сопровождающей соответствующее распространение исходного кода.
+
+Будущие версии Программного обеспечения могут распространяться в соответствии с иной версией Лицензии TELEMT Public License либо под иной лицензией, определяемой мейнтейнерами Telemt.
+
+Любое такое изменение лицензии применяется исключительно к версиям Программного обеспечения, распространяемым с новой лицензией, и НЕ распространяется ретроактивно на ранее выпущенные версии Программного обеспечения.
+
+Получатели Программного обеспечения приобретают права исключительно в соответствии с Лицензией, предоставленной вместе с полученной ими версией Программного обеспечения.
+
+При распространении Программного обеспечения, включая Модифицированные версии, ОБЯЗАТЕЛЬНО сохранение уведомлений об авторском праве, текста лицензии и условий настоящей Лицензии в отношении всех частей Программного обеспечения, производных от Telemt.
+
+Дополнительные условия или лицензии могут применяться к модификациям или дополнительному коду, добавленному распространителем, при условии, что такие условия не ограничивают и не изменяют права, предоставленные настоящей Лицензией в отношении оригинального Программного обеспечения Telemt.
+
+Ничто в настоящем разделе не ограничивает права, предоставленные настоящей Лицензией в отношении уже выпущенных версий Программного обеспечения.
+
+### Определения
+
+Для целей настоящей Лицензии:
+
+**"Программное обеспечение"** означает программное обеспечение Telemt, включая исходный код, документацию и любые сопутствующие файлы, распространяемые в соответствии с настоящей Лицензией.
+
+**"Контрибьютор"** означает любое физическое или юридическое лицо, которое предоставляет код, исправления, документацию или иные материалы в качестве вклада в Программное обеспечение, принятые мейнтейнерами для включения в Программное обеспечение.
+
+**"Вклад"** означает любое произведение, сознательно представленное для включения в Программное обеспечение.
+
+**"Модифицированная версия"** означает любую версию Программного обеспечения, которая была изменена, адаптирована, расширена или иным образом модифицирована по сравнению с оригинальным Программным обеспечением.
+
+**"Мейнтейнеры"** означает физических или юридических лиц, ответственных за официальный проект Telemt и его релизы.
+
+### 1. Атрибуция
+
+При распространении Программного обеспечения, как в виде исходного кода, так и в бинарной форме, ОБЯЗАТЕЛЬНО СОХРАНЕНИЕ:
+
+- указанного выше уведомления об авторском праве;
+- текста настоящей Лицензии;
+- всех существующих уведомлений об атрибуции.
+
+### 2. Уведомление о модификациях
+
+В случае внесения изменений в Программное обеспечение вы ОБЯЗАНЫ явно указать факт модификации Программного обеспечения и включить краткое описание внесённых изменений.
+
+Модифицированные версии НЕ ДОЛЖНЫ представляться как оригинальное Программное обеспечение Telemt.
+
+### 3. Товарные знаки и брендинг
+
+Настоящая Лицензия НЕ предоставляет право на использование наименования "Telemt", логотипа Telemt или любых товарных знаков и элементов брендинга Telemt.
+
+Распространяемые или модифицированные версии Программного обеспечения НЕ МОГУТ использовать наименование Telemt таким образом, который может создавать впечатление одобрения или официального происхождения без явного разрешения мейнтейнеров Telemt.
+
+Использование наименования "Telemt" для описания модифицированной версии Программного обеспечения допускается только при условии, что такая версия чётко обозначена как модифицированная или неофициальная.
+
+Запрещается любое распространение, способное разумно ввести пользователей в заблуждение относительно того, что программное обеспечение является официальным релизом Telemt.
+
+### 4. Прозрачность распространения бинарных файлов
+
+В случае распространения скомпилированных бинарных файлов Программного обеспечения рекомендуется (ENCOURAGED) предоставлять доступ к соответствующему исходному коду и инструкциям по сборке, если это разумно возможно.
+
+Это способствует обеспечению прозрачности и позволяет получателям проверять целостность и воспроизводимость распространяемых сборок.
+
+### 5. Патентная лицензия и условие защитного прекращения
+
+Каждый контрибьютор предоставляет вам бессрочную, всемирную, неисключительную, безвозмездную, без лицензионных отчислений, безотзывную патентную лицензию на:
+
+- изготовление,
+- поручение изготовления,
+- использование,
+- предложение к продаже,
+- продажу,
+- импорт,
+- а также иные формы передачи Программного обеспечения.
+
+Данная патентная лицензия распространяется исключительно на те патентные притязания, которые неизбежно нарушаются вкладом контрибьютора отдельно либо в сочетании его вклада с Программным обеспечением.
+
+Если вы инициируете или участвуете в любом патентном судебном разбирательстве, включая встречные иски или требования, утверждая, что Программное обеспечение или любой Вклад, включённый в Программное обеспечение, нарушает патент, то **все предоставленные вам настоящей Лицензией права немедленно прекращаются** с даты подачи такого иска.
+
+Дополнительно, если вы инициируете судебное разбирательство, утверждая, что само Программное обеспечение нарушает ваш патент или иные права интеллектуальной собственности, все права, предоставленные вам настоящей Лицензией, ПРЕКРАЩАЮТСЯ автоматически.
+
+### 6. Вклады
+
+Если вы прямо не указали иное, любой Вклад, сознательно представленный для включения в Программное обеспечение, лицензируется на условиях настоящей Лицензии.
+
+Предоставляя Вклад, вы предоставляете мейнтейнерам Telemt и всем получателям Программного обеспечения права, предусмотренные настоящей Лицензией, в отношении такого Вклада.
+
+### 7. Атрибуция при сетевом использовании
+
+Если Программное обеспечение используется для предоставления общедоступного сетевого сервиса, оператор такого сервиса ДОЛЖЕН (SHOULD) обеспечить указание атрибуции Telemt как минимум в одном из следующих мест:
+
+- документация сервиса;
+- описание сервиса;
+- раздел "О программе" или аналогичная информационная страница;
+- иные материалы, доступные пользователю и разумно связанные с сервисом.
+
+Такая атрибуция НЕ ДОЛЖНА подразумевать одобрение со стороны проекта Telemt или его мейнтейнеров.
+
+### 8. Отказ от гарантий и оговорка о делимости
+
+ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ "КАК ЕСТЬ", БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, В ЧАСТНОСТИ, ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ, СООТВЕТСТВИЯ ОПРЕДЕЛЁННОЙ ЦЕЛИ И ОТСУТСТВИЯ НАРУШЕНИЙ ПРАВ.
+
+НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ТРЕБОВАНИЯМ, УБЫТКАМ ИЛИ ИНОЙ ОТВЕТСТВЕННОСТИ, ВОЗНИКАЮЩИМ В РАМКАХ ДОГОВОРА, ДЕЛИКТА ИЛИ ИНЫМ ОБРАЗОМ, ИЗ, В СВЯЗИ С ИЛИ В РЕЗУЛЬТАТЕ ИСПОЛЬЗОВАНИЯ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ ИЛИ ИНЫХ ДЕЙСТВИЙ С НИМ.
+
+ЕСЛИ ЛЮБОЕ ПОЛОЖЕНИЕ НАСТОЯЩЕЙ ЛИЦЕНЗИИ ПРИЗНАЁТСЯ НЕДЕЙСТВИТЕЛЬНЫМ ИЛИ НЕПРИМЕНИМЫМ, ТАКОЕ ПОЛОЖЕНИЕ ПОДЛЕЖИТ ТОЛКОВАНИЮ МАКСИМАЛЬНО БЛИЗКО К ИСХОДНОМУ НАМЕРЕНИЮ СТОРОН, А ОСТАЛЬНЫЕ ПОЛОЖЕНИЯ СОХРАНЯЮТ ПОЛНУЮ СИЛУ И ДЕЙСТВИЕ.

docs/QUICK_START_GUIDE.en.md

@@ -1,196 +0,0 @@
-# Telemt via Systemd
-
-## Installation
-
-This software is designed for Debian-based OS: in addition to Debian, these are Ubuntu, Mint, Kali, MX and many other Linux
-
-**1. Download**
-```bash
-wget -qO- "https://github.com/telemt/telemt/releases/latest/download/telemt-$(uname -m)-linux-$(ldd --version 2>&1 | grep -iq musl && echo musl || echo gnu).tar.gz" | tar -xz
-```
-**2. Move to the Bin folder**
-```bash
-mv telemt /bin
-```
-**3. Make the file executable**
-```bash
-chmod +x /bin/telemt
-```
-
-## How to use?
-
-**This guide "assumes" that you:**
-- logged in as root or executed `su -` / `sudo su`
-- Already have the "telemt" executable file in the /bin folder. Read the **[Installation](#Installation)** section.
-
----
-
-**0. Check port and generate secrets**
-
-The port you have selected for use should not be in the list:
-```bash
-netstat -lnp
-```
-
-Generate 16 bytes/32 characters in HEX format with OpenSSL or another way:
-```bash
-openssl rand -hex 16
-```
-OR
-```bash
-xxd -l 16 -p /dev/urandom
-```
-OR
-```bash
-python3 -c 'import os; print(os.urandom(16).hex())'
-```
-Save the obtained result somewhere. You will need it later!
-
----
-
-**1. Place your config to /etc/telemt/telemt.toml**
-
-Create the config directory:
-```bash
-mkdir /etc/telemt
-```
-
-Open nano
-```bash
-nano /etc/telemt/telemt.toml
-```
-Insert your configuration:
-
-```toml
-# === General Settings ===
-[general]
-# ad_tag = "00000000000000000000000000000000"
-use_middle_proxy = false
-
-[general.modes]
-classic = false
-secure = false
-tls = true
-
-[server]
-port = 443
-
-[server.api]
-enabled = true
-# listen = "127.0.0.1:9091"
-# whitelist = ["127.0.0.1/32"]
-# read_only = true
-
-# === Anti-Censorship & Masking ===
-[censorship]
-tls_domain = "petrovich.ru"
-
-[access.users]
-# format: "username" = "32_hex_chars_secret"
-hello = "00000000000000000000000000000000"
-```
-
-then Ctrl+S -> Ctrl+X to save
-
-> [!WARNING]
-> Replace the value of the hello parameter with the value you obtained in step 0.  
-> Additionally, change the value of the tls_domain parameter to a different website.
-> Changing the tls_domain parameter will break all links that use the old domain!
-
----
-
-**2. Create telemt user**
-
-```bash
-useradd -d /opt/telemt -m -r -U telemt
-chown -R telemt:telemt /etc/telemt
-```
-
-**3. Create service in /etc/systemd/system/telemt.service**
-
-Open nano
-```bash
-nano /etc/systemd/system/telemt.service
-```
-
-Insert this Systemd module:
-```bash
-[Unit]
-Description=Telemt
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-User=telemt
-Group=telemt
-WorkingDirectory=/opt/telemt
-ExecStart=/bin/telemt /etc/telemt/telemt.toml
-Restart=on-failure
-LimitNOFILE=65536
-AmbientCapabilities=CAP_NET_BIND_SERVICE
-CapabilityBoundingSet=CAP_NET_BIND_SERVICE
-NoNewPrivileges=true
-
-[Install]
-WantedBy=multi-user.target
-```
-then Ctrl+S -> Ctrl+X to save
-
-reload systemd units
-```bash
-systemctl daemon-reload
-```
-
-**4.** To start it, enter the command `systemctl start telemt`
-
-**5.** To get status information, enter `systemctl status telemt`
-
-**6.** For automatic startup at system boot, enter `systemctl enable telemt`
-
-**7.** To get the link(s), enter:
-```bash
-curl -s http://127.0.0.1:9091/v1/users | jq
-```
-
-> Any number of people can use one link.
-
-> [!WARNING]
-> Only the command from step 7 can provide a working link. Do not try to create it yourself or copy it from anywhere if you are not sure what you are doing!
-
----
-
-# Telemt via Docker Compose
-
-**1. Edit `config.toml` in repo root (at least: port, users secrets, tls_domain)**  
-**2. Start container:**
-```bash
-docker compose up -d --build
-```
-**3. Check logs:**
-```bash
-docker compose logs -f telemt
-```
-**4. Stop:**
-```bash
-docker compose down
-```
-> [!NOTE]
-> - `docker-compose.yml` maps `./config.toml` to `/app/config.toml` (read-only)
-> - By default it publishes `443:443` and runs with dropped capabilities (only `NET_BIND_SERVICE` is added)
-> - If you really need host networking (usually only for some IPv6 setups) uncomment `network_mode: host`
-
-**Run without Compose**
-```bash
-docker build -t telemt:local .
-docker run --name telemt --restart unless-stopped \
-  -p 443:443 \
-  -p 9090:9090 \
-  -p 9091:9091 \
-  -e RUST_LOG=info \
-  -v "$PWD/config.toml:/app/config.toml:ro" \
-  --read-only \
-  --cap-drop ALL --cap-add NET_BIND_SERVICE \
-  --ulimit nofile=65536:65536 \
-  telemt:local
-```

docs/QUICK_START_GUIDE.ru.md

@@ -1,195 +0,0 @@
-# Telemt через Systemd
-
-## Установка
-
-Это программное обеспечение разработано для ОС на базе Debian: помимо Debian, это Ubuntu, Mint, Kali, MX и многие другие Linux
-
-**1. Скачать**
-```bash
-wget -qO- "https://github.com/telemt/telemt/releases/latest/download/telemt-$(uname -m)-linux-$(ldd --version 2>&1 | grep -iq musl && echo musl || echo gnu).tar.gz" | tar -xz
-```
-**2. Переместить в папку Bin**
-```bash
-mv telemt /bin
-```
-**3. Сделать файл исполняемым**
-```bash
-chmod +x /bin/telemt
-```
-
-## Как правильно использовать?
-
-**Эта инструкция "предполагает", что вы:**
-- Авторизовались как пользователь root или выполнил `su -` / `sudo su`
-- У вас уже есть исполняемый файл "telemt" в папке /bin. Читайте раздел **[Установка](#установка)**
-
----
-
-**0. Проверьте порт и сгенерируйте секреты**
-
-Порт, который вы выбрали для использования, должен отсутствовать в списке:
-```bash
-netstat -lnp
-```
-
-Сгенерируйте 16 bytes/32 символа в шестнадцатеричном формате с помощью OpenSSL или другим способом:
-```bash
-openssl rand -hex 16
-```
-ИЛИ
-```bash
-xxd -l 16 -p /dev/urandom
-```
-ИЛИ
-```bash
-python3 -c 'import os; print(os.urandom(16).hex())'
-```
-Полученный результат сохраняем где-нибудь. Он понадобиться вам дальше!
-
----
-
-**1. Поместите свою конфигурацию в файл /etc/telemt/telemt.toml**
-
-Создаём директорию для конфига:
-```bash
-mkdir /etc/telemt
-```
-
-Открываем nano
-```bash
-nano /etc/telemt/telemt.toml
-```
-Вставьте свою конфигурацию
-
-```toml
-# === General Settings ===
-[general]
-# ad_tag = "00000000000000000000000000000000"
-use_middle_proxy = false
-
-[general.modes]
-classic = false
-secure = false
-tls = true
-
-[server]
-port = 443
-
-[server.api]
-enabled = true
-# listen = "127.0.0.1:9091"
-# whitelist = ["127.0.0.1/32"]
-# read_only = true
-
-# === Anti-Censorship & Masking ===
-[censorship]
-tls_domain = "petrovich.ru"
-
-[access.users]
-# format: "username" = "32_hex_chars_secret"
-hello = "00000000000000000000000000000000"
-```
-
-Затем нажмите Ctrl+S -> Ctrl+X, чтобы сохранить
-
-> [!WARNING]
-> Замените значение параметра hello на значение, которое вы получили в пункте 0.  
-> Так же замените значение параметра tls_domain на другой сайт.
-> Изменение параметра tls_domain сделает нерабочими все ссылки, использующие старый домен!
-
----
-
-**2. Создайте пользователя для telemt**
-
-```bash
-useradd -d /opt/telemt -m -r -U telemt
-chown -R telemt:telemt /etc/telemt
-```
-
-**3. Создайте службу в /etc/systemd/system/telemt.service**
-
-Открываем nano
-```bash
-nano /etc/systemd/system/telemt.service
-```
-
-Вставьте этот модуль Systemd
-```bash
-[Unit]
-Description=Telemt
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-User=telemt
-Group=telemt
-WorkingDirectory=/opt/telemt
-ExecStart=/bin/telemt /etc/telemt/telemt.toml
-Restart=on-failure
-LimitNOFILE=65536
-AmbientCapabilities=CAP_NET_BIND_SERVICE
-CapabilityBoundingSet=CAP_NET_BIND_SERVICE
-NoNewPrivileges=true
-
-[Install]
-WantedBy=multi-user.target
-```
-Затем нажмите Ctrl+S -> Ctrl+X, чтобы сохранить
-
-перезагрузите конфигурацию systemd
-```bash
-systemctl daemon-reload
-```
-
-**4.** Для запуска введите команду `systemctl start telemt`
-
-**5.** Для получения информации о статусе введите `systemctl status telemt`
-
-**6.** Для автоматического запуска при запуске системы в введите `systemctl enable telemt`
-
-**7.** Для получения ссылки/ссылок введите 
-```bash
-curl -s http://127.0.0.1:9091/v1/users | jq
-```
-> Одной ссылкой может пользоваться сколько угодно человек.
-
-> [!WARNING]
-> Рабочую ссылку может выдать только команда из 7 пункта. Не пытайтесь делать ее самостоятельно или копировать откуда-либо если вы не уверены в том, что делаете!
-
----
-
-# Telemt через Docker Compose
-
-**1. Отредактируйте `config.toml` в корневом каталоге репозитория (как минимум: порт, пользовательские секреты, tls_domain)**  
-**2. Запустите контейнер:**
-```bash
-docker compose up -d --build
-```
-**3. Проверьте логи:**
-```bash
-docker compose logs -f telemt
-```
-**4. Остановите контейнер:**
-```bash
-docker compose down
-```
-> [!NOTE]
-> - В `docker-compose.yml` файл `./config.toml` монтируется в `/app/config.toml` (доступно только для чтения)  
-> - По умолчанию публикуются порты 443:443, а контейнер запускается со сброшенными привилегиями (добавлена только `NET_BIND_SERVICE`)  
-> - Если вам действительно нужна сеть хоста (обычно это требуется только для некоторых конфигураций IPv6), раскомментируйте `network_mode: host`
-
-**Запуск без Docker Compose**
-```bash
-docker build -t telemt:local .
-docker run --name telemt --restart unless-stopped \
-  -p 443:443 \
-  -p 9090:9090 \
-  -p 9091:9091 \
-  -e RUST_LOG=info \
-  -v "$PWD/config.toml:/app/config.toml:ro" \
-  --read-only \
-  --cap-drop ALL --cap-add NET_BIND_SERVICE \
-  --ulimit nofile=65536:65536 \
-  telemt:local
-```

docs/Quick_start/OPENBSD_QUICK_START_GUIDE.en.md

@@ -27,7 +27,8 @@ cargo build --release
 ./target/release/telemt --version
 ```
 
-For low-RAM systems, this repository already uses `lto = "thin"` in release profile.
+For low-RAM systems, note that this repository currently uses `lto = "fat"` in release profile.  
+On constrained builders, a local override to `lto = "thin"` may be more practical.
 
 ## 3. Install binary and config
 

docs/Quick_start/QUICK_START_GUIDE.en.md

@@ -0,0 +1,284 @@
+# Installation Options 
+There are three options for installing Telemt:
+ - [Automated installation using a script](#very-quick-start).
+ - [Manual installation of Telemt as a service](#telemt-via-systemd).
+ - [Installation using Docker Compose](#telemt-via-docker-compose).
+
+# Very quick start
+
+### One-command installation / update on re-run
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
+```
+
+After starting, the script will prompt for:
+ - Your language (1 - English, 2 - Russian);
+ - Your TLS domain (press Enter for petrovich.ru).
+
+The script checks if the port (default **443**) is free. If the port is already in use, installation will fail. You need to free up the port or use the **-p** flag with a different port to retry the installation.
+
+To modify the script’s startup parameters, you can use the following flags:
+ - **-d, --domain** - TLS domain;
+ - **-p, --port** - server port (1–65535);
+ - **-s, --secret** - 32 hex secret;
+ - **-a, --ad-tag** - ad_tag;
+ - **-l, --lan**g - language (1/en or 2/ru);
+
+Providing all options skips interactive prompts.
+
+After completion, the script will provide a link for client connections:
+```bash
+tg://proxy?server=IP&port=PORT&secret=SECRET
+```
+
+### Installing a specific version
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh -s -- 3.3.39
+```
+
+### Uninstall with full cleanup
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh -s -- purge
+```
+
+# Telemt via Systemd
+
+## Installation
+
+This software is designed for Debian-based OS: in addition to Debian, these are Ubuntu, Mint, Kali, MX and many other Linux
+
+**1. Download**
+```bash
+wget -qO- "https://github.com/telemt/telemt/releases/latest/download/telemt-$(uname -m)-linux-$(ldd --version 2>&1 | grep -iq musl && echo musl || echo gnu).tar.gz" | tar -xz
+```
+**2. Move to the Bin folder**
+```bash
+mv telemt /bin
+```
+**3. Make the file executable**
+```bash
+chmod +x /bin/telemt
+```
+
+## How to use?
+
+**This guide "assumes" that you:**
+- logged in as root or executed `su -` / `sudo su`
+- Already have the "telemt" executable file in the /bin folder. Read the **[Installation](#Installation)** section.
+
+---
+
+**0. Check port and generate secrets**
+
+The port you have selected for use should not be in the list:
+```bash
+netstat -lnp
+```
+
+Generate 16 bytes/32 characters in HEX format with OpenSSL or another way:
+```bash
+openssl rand -hex 16
+```
+OR
+```bash
+xxd -l 16 -p /dev/urandom
+```
+OR
+```bash
+python3 -c 'import os; print(os.urandom(16).hex())'
+```
+Save the obtained result somewhere. You will need it later!
+
+---
+
+**1. Place your config to /etc/telemt/telemt.toml**
+
+Create the config directory:
+```bash
+mkdir /etc/telemt
+```
+
+Open nano
+```bash
+nano /etc/telemt/telemt.toml
+```
+Insert your configuration:
+
+```toml
+### Telemt Based Config.toml
+# We believe that these settings are sufficient for most scenarios 
+# where cutting-egde methods and parameters or special solutions are not needed
+
+# === General Settings ===
+[general]
+use_middle_proxy = true
+# Global ad_tag fallback when user has no per-user tag in [access.user_ad_tags]
+# ad_tag = "00000000000000000000000000000000"
+# Per-user ad_tag in [access.user_ad_tags] (32 hex from @MTProxybot)
+
+# === Log Level ===
+# Log level: debug | verbose | normal | silent
+# Can be overridden with --silent or --log-level CLI flags
+# RUST_LOG env var takes absolute priority over all of these
+log_level = "normal"
+
+[general.modes]
+classic = false
+secure = false
+tls = true
+
+[general.links]
+show = "*"
+# show = ["alice", "bob"] # Only show links for alice and bob
+# show = "*"              # Show links for all users
+# public_host = "proxy.example.com"  # Host (IP or domain) for tg:// links
+# public_port = 443                  # Port for tg:// links (default: server.port)
+
+# === Server Binding ===
+[server]
+port = 443
+# proxy_protocol = false            # Enable if behind HAProxy/nginx with PROXY protocol
+# metrics_port = 9090
+# metrics_listen = "127.0.0.1:9090" # Listen address for metrics (overrides metrics_port)
+# metrics_whitelist = ["127.0.0.1/32", "::1/128"]
+
+[server.api]
+enabled = true
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.1/32", "::1/128"]
+minimal_runtime_enabled = false
+minimal_runtime_cache_ttl_ms = 1000
+
+# Listen on multiple interfaces/IPs - IPv4
+[[server.listeners]]
+ip = "0.0.0.0"
+
+# === Anti-Censorship & Masking ===
+[censorship]
+tls_domain = "petrovich.ru"  # Fake-TLS / SNI masking domain used in generated ee-links
+mask = true
+tls_emulation = true         # Fetch real cert lengths and emulate TLS records
+tls_front_dir = "tlsfront"   # Cache directory for TLS emulation
+
+[access.users]
+# format: "username" = "32_hex_chars_secret"
+hello = "00000000000000000000000000000000"
+```
+
+then Ctrl+S -> Ctrl+X to save
+
+> [!WARNING]
+> Replace the value of the `hello` parameter with the value you obtained in step 0.  
+> Additionally, change the value of the `tls_domain` parameter to a different website.
+> Changing the `tls_domain` parameter will break all links that use the old domain!
+
+---
+
+**2. Create telemt user**
+
+```bash
+useradd -d /opt/telemt -m -r -U telemt
+chown -R telemt:telemt /etc/telemt
+```
+
+**3. Create service in /etc/systemd/system/telemt.service**
+
+Open nano
+```bash
+nano /etc/systemd/system/telemt.service
+```
+
+Insert this Systemd module:
+```bash
+[Unit]
+Description=Telemt
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=telemt
+Group=telemt
+WorkingDirectory=/opt/telemt
+ExecStart=/bin/telemt /etc/telemt/telemt.toml
+Restart=on-failure
+LimitNOFILE=65536
+AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target
+```
+then Ctrl+S -> Ctrl+X to save
+
+reload systemd units
+```bash
+systemctl daemon-reload
+```
+
+**4.** To start it, enter the command `systemctl start telemt`
+
+**5.** To get status information, enter `systemctl status telemt`
+
+**6.** For automatic startup at system boot, enter `systemctl enable telemt`
+
+**7.** To get the link(s), enter:
+```bash
+curl -s http://127.0.0.1:9091/v1/users | jq -r '.data[] | "[\(.username)]", (.links.classic[]? | "classic: \(.)"), (.links.secure[]? | "secure: \(.)"), (.links.tls[]? | "tls: \(.)"), ""'
+```
+
+> Any number of people can use one link.
+
+> [!WARNING]
+> Only the command from step 7 can provide a working link. Do not try to create it yourself or copy it from anywhere if you are not sure what you are doing!
+
+---
+
+# Telemt via Docker Compose
+
+**1. Edit `config.toml` in repo root (at least: port, users secrets, tls_domain)**  
+**2. Start container:**
+```bash
+docker compose up -d --build
+```
+**3. Check logs:**
+```bash
+docker compose logs -f telemt
+```
+**4. Stop:**
+```bash
+docker compose down
+```
+> [!NOTE]
+> - `docker-compose.yml` maps `./config.toml` to `/app/config.toml` (read-only)
+> - By default it publishes `443:443` and runs with dropped capabilities (only `NET_BIND_SERVICE` is added)
+> - If you really need host networking (usually only for some IPv6 setups) uncomment `network_mode: host`
+> - If you enable mutating Control API endpoints, mount a writable config directory instead of a single `config.toml` file. Telemt persists config changes with atomic `tmp + rename` writes, and a single bind-mounted file can fail with `Device or resource busy`.
+
+Example writable config mount for Control API mutations:
+```yaml
+services:
+  telemt:
+    working_dir: /run/telemt
+    volumes:
+      - ./config:/etc/telemt:rw
+    tmpfs:
+      - /run/telemt:rw,mode=1777,size=4m
+    command: /usr/local/bin/telemt /etc/telemt/config.toml
+```
+
+**Run without Compose**
+```bash
+docker build -t telemt:local .
+docker run --name telemt --restart unless-stopped \
+  -p 443:443 \
+  -p 9090:9090 \
+  -p 9091:9091 \
+  -e RUST_LOG=info \
+  -v "$PWD/config.toml:/app/config.toml:ro" \
+  --read-only \
+  --cap-drop ALL --cap-add NET_BIND_SERVICE \
+  --ulimit nofile=65536:65536 \
+  telemt:local
+```

docs/Quick_start/QUICK_START_GUIDE.ru.md

@@ -0,0 +1,272 @@
+# Варианты установки
+Имеется три варианта установки Telemt:
+ - [Автоматизированная установка с помощью скрипта](#очень-быстрый-старт).
+ - [Ручная установка Telemt в качестве службы](#telemt-через-systemd-вручную).
+ - [Установка через Docker Compose](#telemt-через-docker-compose).
+
+# Очень быстрый старт
+
+### Установка одной командой / обновление при повторном запуске
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
+```
+После запуска скрипт запросит:
+ - ваш язык (1 - English, 2 - Русский);
+ - ваш TLS-домен (нажмите Enter для petrovich.ru).
+
+Во время установки скрипт проверяет, свободен ли порт (по умолчанию **443**). Если порт занят другим процессом - установка завершится с ошибкой. Для повторной установки необходимо освободить порт или указать другой через флаг **-p**.
+
+Для изменения параметров запуска скрипта можно использовать следующие флаги:
+ - **-d, --domain** - TLS-домен;
+ - **-p, --port** - порт (1–65535);
+ - **-s, --secret** - секрет (32 hex символа);
+ - **-a, --ad-tag** - ad_tag;
+ - **-l, --lang** - язык (1/en или 2/ru).
+
+Если заданы флаги для языка и домена, интерактивных вопросов не будет.
+
+После завершения установки скрипт выдаст ссылку для подключения клиентов:
+```bash
+tg://proxy?server=IP&port=PORT&secret=SECRET
+```
+
+### Установка нужной версии
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh -s -- 3.3.39
+```
+
+### Удаление с полной очисткой
+```bash
+curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh -s -- purge
+```
+
+# Telemt через Systemd вручную
+
+## Установка
+
+Это программное обеспечение разработано для ОС на базе Debian: помимо Debian, это Ubuntu, Mint, Kali, MX и многие другие Linux
+
+**1. Скачать**
+```bash
+wget -qO- "https://github.com/telemt/telemt/releases/latest/download/telemt-$(uname -m)-linux-$(ldd --version 2>&1 | grep -iq musl && echo musl || echo gnu).tar.gz" | tar -xz
+```
+**2. Переместить в папку Bin**
+```bash
+mv telemt /bin
+```
+**3. Сделать файл исполняемым**
+```bash
+chmod +x /bin/telemt
+```
+
+## Как правильно использовать?
+
+**Эта инструкция "предполагает", что вы:**
+- Авторизовались как пользователь root или выполнил `su -` / `sudo su`
+- У вас уже есть исполняемый файл "telemt" в папке /bin. Читайте раздел **[Установка](#установка)**
+
+---
+
+**0. Проверьте порт и сгенерируйте секреты**
+
+Порт, который вы выбрали для использования, должен отсутствовать в списке:
+```bash
+netstat -lnp
+```
+
+Сгенерируйте 16 bytes/32 символа в шестнадцатеричном формате с помощью OpenSSL или другим способом:
+```bash
+openssl rand -hex 16
+```
+ИЛИ
+```bash
+xxd -l 16 -p /dev/urandom
+```
+ИЛИ
+```bash
+python3 -c 'import os; print(os.urandom(16).hex())'
+```
+Полученный результат сохраняем где-нибудь. Он понадобиться вам дальше!
+
+---
+
+**1. Поместите свою конфигурацию в файл /etc/telemt/telemt.toml**
+
+Создаём директорию для конфига:
+```bash
+mkdir /etc/telemt
+```
+
+Открываем nano
+```bash
+nano /etc/telemt/telemt.toml
+```
+Вставьте свою конфигурацию
+
+```toml
+### Конфигурационный файл на основе Telemt
+# Мы полагаем, что этих настроек достаточно для большинства сценариев, 
+# где не требуются передовые методы, параметры или специальные решения
+
+# === Общие настройки ===
+[general]
+use_middle_proxy = true
+# Глобальный ad_tag, если у пользователя нет индивидуального тега в [access.user_ad_tags]
+# ad_tag = "00000000000000000000000000000000"
+# Индивидуальный ad_tag в [access.user_ad_tags] (32 шестнадцатеричных символа от @MTProxybot)
+
+# === Уровень логирования ===
+# Уровень логирования: debug | verbose | normal | silent
+# Можно переопределить с помощью флагов командной строки --silent или --log-level
+# Переменная окружения RUST_LOG имеет абсолютный приоритет над всеми этими настройками
+log_level = "normal"
+
+[general.modes]
+classic = false
+secure = false
+tls = true
+
+[general.links]
+show = "*"
+# show = ["alice", "bob"] # Показывать ссылки только для alice и bob
+# show = "*"              # Показывать ссылки для всех пользователей
+# public_host = "proxy.example.com"  # Хост (IP-адрес или домен) для ссылок tg://
+# public_port = 443                  # Порт для ссылок tg:// (по умолчанию: server.port)
+
+# === Привязка сервера ===
+[server]
+port = 443
+# proxy_protocol = false           # Включите, если сервер находится за HAProxy/nginx с протоколом PROXY
+# metrics_port = 9090
+# metrics_listen = "127.0.0.1:9090"  # Адрес прослушивания для метрик (переопределяет metrics_port)
+# metrics_whitelist = ["127.0.0.1/32", "::1/128"]
+
+[server.api]
+enabled = true
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.1/32", "::1/128"]
+minimal_runtime_enabled = false
+minimal_runtime_cache_ttl_ms = 1000
+
+# Прослушивание на нескольких интерфейсах/IP-адресах - IPv4
+[[server.listeners]]
+ip = "0.0.0.0"
+
+# === Обход блокировок и маскировка ===
+[censorship]
+tls_domain = "petrovich.ru"  # Домен Fake-TLS / SNI, который будет использоваться в сгенерированных ee-ссылках
+mask = true
+tls_emulation = true         # Получить реальную длину сертификата и эмулировать запись TLS
+tls_front_dir = "tlsfront"   # Директория кэша для эмуляции TLS
+
+[access.users]
+# формат: "имя_пользователя" = "секрет_из_32_шестнадцатеричных_символов"
+hello = "00000000000000000000000000000000"
+```
+
+Затем нажмите Ctrl+O -> Ctrl+X, чтобы сохранить
+
+> [!WARNING]
+> Замените значение параметра `hello` на значение, которое вы получили в пункте 0.  
+> Так же замените значение параметра `tls_domain` на другой сайт.
+> Изменение параметра `tls_domain` сделает нерабочими все ссылки, использующие старый домен!
+
+---
+
+**2. Создайте пользователя для telemt**
+
+```bash
+useradd -d /opt/telemt -m -r -U telemt
+chown -R telemt:telemt /etc/telemt
+```
+
+**3. Создайте службу в /etc/systemd/system/telemt.service**
+
+Открываем nano
+```bash
+nano /etc/systemd/system/telemt.service
+```
+
+Вставьте этот модуль Systemd
+```bash
+[Unit]
+Description=Telemt
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=telemt
+Group=telemt
+WorkingDirectory=/opt/telemt
+ExecStart=/bin/telemt /etc/telemt/telemt.toml
+Restart=on-failure
+LimitNOFILE=65536
+AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target
+```
+Затем нажмите Ctrl+S -> Ctrl+X, чтобы сохранить
+
+перезагрузите конфигурацию systemd
+```bash
+systemctl daemon-reload
+```
+
+**4.** Для запуска введите команду `systemctl start telemt`
+
+**5.** Для получения информации о статусе введите `systemctl status telemt`
+
+**6.** Для автоматического запуска при запуске системы в введите `systemctl enable telemt`
+
+**7.** Для получения ссылки/ссылок введите 
+```bash
+curl -s http://127.0.0.1:9091/v1/users | jq -r '.data[] | "[\(.username)]", (.links.classic[]? | "classic: \(.)"), (.links.secure[]? | "secure: \(.)"), (.links.tls[]? | "tls: \(.)"), ""'
+```
+> Одной ссылкой может пользоваться сколько угодно человек.
+
+> [!WARNING]
+> Рабочую ссылку может выдать только команда из 7 пункта. Не пытайтесь делать ее самостоятельно или копировать откуда-либо если вы не уверены в том, что делаете!
+
+---
+
+# Telemt через Docker Compose
+
+**1. Создайте директорию `config/` и поместите в неё отрдеактированный `config.toml` (указав как минимум: порт, пользовательские секреты, tls_domain):**
+```bash
+mkdir config && mv config.toml config/
+```
+**2. Запустите контейнер:**
+```bash
+docker compose up -d --build
+```
+**3. Проверьте логи:**
+```bash
+docker compose logs -f telemt
+```
+**4. Остановите контейнер:**
+```bash
+docker compose down
+```
+> [!NOTE]
+> - Директория `./config/` монтируется в `/etc/telemt/` (read-write), что позволяет API атомарно обновлять config.toml
+> - По умолчанию публикуются порты 443:443, а контейнер запускается со сброшенными привилегиями (добавлена только `NET_BIND_SERVICE`)  
+> - Если вам действительно нужна сеть хоста (обычно это требуется только для некоторых конфигураций IPv6), раскомментируйте `network_mode: host`
+
+**Запуск без Docker Compose**
+```bash
+docker build -t telemt:local .
+docker run --name telemt --restart unless-stopped \
+  -p 443:443 \
+  -p 9090:9090 \
+  -p 9091:9091 \
+  -e RUST_LOG=info \
+  -v "$PWD/config.toml:/app/config.toml:ro" \
+  --read-only \
+  --cap-drop ALL --cap-add NET_BIND_SERVICE \
+  --ulimit nofile=65536:65536 \
+  telemt:local
+```

docs/Setup_examples/VPS_DOUBLE_HOP.en.md

@@ -163,7 +163,7 @@ PING 10.10.10.1 (10.10.10.1) 56(84) bytes of data.
 ---
 
 ## Step 2. Installing telemt on Server B (conditionally Netherlands)
-Installation and configuration are described [here](https://github.com/telemt/telemt/blob/main/docs/QUICK_START_GUIDE.ru.md) or [here](https://gitlab.com/An0nX/telemt-docker#-quick-start-docker-compose).\
+Installation and configuration are described [here](https://github.com/telemt/telemt/blob/main/docs/Quick_start/QUICK_START_GUIDE.en.md) or [here](https://gitlab.com/An0nX/telemt-docker#-quick-start-docker-compose).\
 It is assumed that telemt expects connections on port `443\tcp`.
 
 In the telemt config, you must enable the `Proxy` protocol and restrict connections to it only through the tunnel.

docs/Setup_examples/VPS_DOUBLE_HOP.ru.md

@@ -166,7 +166,7 @@ PING 10.10.10.1 (10.10.10.1) 56(84) bytes of data.
 
 ## Шаг 2. Установка telemt на Сервере B (_условно Нидерланды_)
 
-Установка и настройка описаны [здесь](https://github.com/telemt/telemt/blob/main/docs/QUICK_START_GUIDE.ru.md) или [здесь](https://gitlab.com/An0nX/telemt-docker#-quick-start-docker-compose).\
+Установка и настройка описаны [здесь](https://github.com/telemt/telemt/blob/main/docs/Quick_start/QUICK_START_GUIDE.ru.md) или [здесь](https://gitlab.com/An0nX/telemt-docker#-quick-start-docker-compose).\
 Подразумевается что telemt ожидает подключения на порту `443\tcp`.
 
 В конфиге telemt необходимо включить протокол `Proxy` и ограничить подключения к нему только через туннель.

docs/Setup_examples/XRAY_DOUBLE_HOP.en.md

@@ -0,0 +1,273 @@
+<img src="https://gist.githubusercontent.com/avbor/1f8a128e628f47249aae6e058a57610b/raw/19013276c035e91058e0a9799ab145f8e70e3ff5/scheme.svg">
+
+## Concept
+- **Server A** (_e.g., RU_):\
+  Entry point, accepts Telegram proxy user traffic via **Xray** (port `443\tcp`)\
+  and sends it through the tunnel to Server **B**.\
+  Public port for Telegram clients — `443\tcp`
+- **Server B** (_e.g., NL_):\
+  Exit point, runs the **Xray server** (to terminate the tunnel entry point) and **telemt**.\
+  The server must have unrestricted access to Telegram Data Centers.\
+  Public port for VLESS/REALITY (incoming) — `443\tcp`\
+  Internal telemt port (where decrypted Xray traffic ends up) — `8443\tcp`
+
+The tunnel works over the `VLESS-XTLS-Reality` (or `VLESS/xhttp/reality`) protocol. The original client IP address is preserved thanks to the PROXYv2 protocol, which Xray on Server A dynamically injects via a local loopback before wrapping the traffic into Reality, transparently delivering the real IPs to telemt on Server B.
+
+---
+
+## Step 1. Setup Xray Tunnel (A <-> B)
+
+You must install **Xray-core** (version 1.8.4 or newer recommended) on both servers.
+Official installation script (run on both servers):
+```bash
+bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install
+```
+
+### Key and Parameter Generation (Run Once)
+For configuration, you need a unique UUID and Xray Reality keys. Run on any server with Xray installed:
+1. **Client UUID:**
+```bash
+xray uuid
+# Save the output (e.g.: 12345678-abcd-1234-abcd-1234567890ab) — this is <XRAY_UUID>
+```
+2. **X25519 Keypair (Private & Public) for Reality:**
+```bash
+xray x25519
+# Save the Private key (<SERVER_B_PRIVATE_KEY>) and Public key (<SERVER_B_PUBLIC_KEY>)
+```
+3. **Short ID (Reality identifier):**
+```bash
+openssl rand -hex 8
+# Save the output (e.g.: abc123def456) — this is <SHORT_ID>
+```
+4. **Random Path (for xhttp):**
+```bash
+openssl rand -hex 16
+# Save the output (e.g., 0123456789abcdef0123456789abcdef) to replace <YOUR_RANDOM_PATH> in configs
+```
+
+---
+
+### Configuration for Server B (_EU_):
+
+Create or edit the file `/usr/local/etc/xray/config.json`.
+This Xray instance will listen on the public `443` port and proxy valid Reality traffic, while routing "disguised" traffic (e.g., direct web browser scans) to `yahoo.com`.
+
+```bash
+nano /usr/local/etc/xray/config.json
+```
+
+File content:
+```json
+{
+  "log": {
+    "loglevel": "error",
+    "access": "none"
+  },
+  "inbounds": [
+    {
+      "tag": "vless-in",
+      "port": 443,
+      "protocol": "vless",
+      "settings": {
+        "clients": [
+          {
+            "id": "<XRAY_UUID>"
+          }
+        ],
+        "decryption": "none"
+      },
+      "streamSettings": {
+        "network": "xhttp",
+        "security": "reality",
+        "realitySettings": {
+          "dest": "yahoo.com:443",
+          "serverNames": [
+            "yahoo.com"
+          ],
+          "privateKey": "<SERVER_B_PRIVATE_KEY>",
+          "shortIds": [
+            "<SHORT_ID>"
+          ]
+        },
+        "xhttpSettings": {
+          "path": "/<YOUR_RANDOM_PATH>",
+          "mode": "auto"
+        }
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "tag": "tunnel-to-telemt",
+      "protocol": "freedom",
+      "settings": {
+        "destination": "127.0.0.1:8443"
+      }
+    }
+  ],
+  "routing": {
+    "domainStrategy": "AsIs",
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": [
+          "vless-in"
+        ],
+        "outboundTag": "tunnel-to-telemt"
+      }
+    ]
+  }
+}
+```
+
+Open the firewall port (if enabled):
+```bash
+sudo ufw allow 443/tcp
+```
+Restart and setup Xray to run at boot:
+```bash
+sudo systemctl restart xray
+sudo systemctl enable xray
+```
+
+---
+
+### Configuration for Server A (_RU_):
+
+Similarly, edit `/usr/local/etc/xray/config.json`.
+Here Xray acts as the public entry point: it listens on `443\tcp`, uses a local loopback (via internal port `10444`) to prepend the `PROXYv2` header, and encapsulates the payload via Reality to Server B, instructing Server B to deliver it to its *local* `127.0.0.1:8443` port (where telemt will listen).
+
+```bash
+nano /usr/local/etc/xray/config.json
+```
+
+File content:
+```json
+{
+  "log": {
+    "loglevel": "error",
+    "access": "none"
+  },
+  "inbounds": [
+    {
+      "tag": "public-in",
+      "port": 443,
+      "listen": "0.0.0.0",
+      "protocol": "dokodemo-door",
+      "settings": {
+        "address": "127.0.0.1",
+        "port": 10444,
+        "network": "tcp"
+      }
+    },
+    {
+      "tag": "tunnel-in",
+      "port": 10444,
+      "listen": "127.0.0.1",
+      "protocol": "dokodemo-door",
+      "settings": {
+        "address": "127.0.0.1",
+        "port": 8443,
+        "network": "tcp"
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "tag": "local-injector",
+      "protocol": "freedom",
+      "settings": {
+        "proxyProtocol": 2
+      }
+    },
+    {
+      "tag": "vless-out",
+      "protocol": "vless",
+      "settings": {
+        "vnext": [
+          {
+            "address": "<PUBLIC_IP_SERVER_B>",
+            "port": 443,
+            "users": [
+              {
+                "id": "<XRAY_UUID>",
+                "encryption": "none"
+              }
+            ]
+          }
+        ]
+      },
+      "streamSettings": {
+        "network": "xhttp",
+        "security": "reality",
+        "realitySettings": {
+          "serverName": "yahoo.com",
+          "publicKey": "<SERVER_B_PUBLIC_KEY>",
+          "shortId": "<SHORT_ID>",
+          "spiderX": "/",
+          "fingerprint": "firefox"
+        },
+        "xhttpSettings": {
+          "path": "/<YOUR_RANDOM_PATH>"
+        }
+      }
+    }
+  ],
+  "routing": {
+    "domainStrategy": "AsIs",
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": ["public-in"],
+        "outboundTag": "local-injector"
+      },
+      {
+        "type": "field",
+        "inboundTag": ["tunnel-in"],
+        "outboundTag": "vless-out"
+      }
+    ]
+  }
+}
+```
+*Replace `<PUBLIC_IP_SERVER_B>` with the public IP address of Server B.*
+
+Open the firewall port for clients (if enabled):
+```bash
+sudo ufw allow 443/tcp
+```
+
+Restart and setup Xray to run at boot:
+```bash
+sudo systemctl restart xray
+sudo systemctl enable xray
+```
+
+---
+
+## Step 2. Install telemt on Server B (_EU_)
+
+telemt installation is heavily covered in the [Quick Start Guide](../Quick_start/QUICK_START_GUIDE.en.md).
+By contrast to standard setups, telemt must listen strictly _locally_ (since Xray occupies the public `443` interface) and must expect `PROXYv2` packets.
+
+Edit the configuration file (`config.toml`) on Server B accordingly:
+
+```toml
+[server]
+port = 8443
+listen_addr_ipv4 = "127.0.0.1"
+proxy_protocol = true
+
+[general.links]
+show = "*"
+public_host = "<FQDN_OR_IP_SERVER_A>"
+public_port = 443
+```
+
+- Address `127.0.0.1` and `port = 8443` instructs the core proxy router to process connections unpacked locally via Xray-server.
+- `proxy_protocol = true` commands telemt to parse the injected PROXY header (from Server A's Xray local loopback) and log genuine end-user IPs.
+- Under `public_host`, place Server A's public IP address or FQDN to ensure working links are generated for Telegram users.
+
+Restart `telemt`. Your server is now robust against DPI scanners, passing traffic optimally.
+

docs/Setup_examples/XRAY_DOUBLE_HOP.ru.md

@@ -0,0 +1,272 @@
+<img src="https://gist.githubusercontent.com/avbor/1f8a128e628f47249aae6e058a57610b/raw/19013276c035e91058e0a9799ab145f8e70e3ff5/scheme.svg">
+
+## Концепция
+- **Сервер A** (_РФ_):\
+  Точка входа, принимает трафик пользователей Telegram-прокси напрямую через **Xray** (порт `443\tcp`)\
+  и отправляет его в туннель на Сервер **B**.\
+  Порт для клиентов Telegram — `443\tcp`
+- **Сервер B** (_условно Нидерланды_):\
+  Точка выхода, на нем работает **Xray-сервер** (принимает подключения точки входа) и **telemt**.\
+  На сервере должен быть неограниченный доступ до серверов Telegram.\
+  Порт для VLESS/REALITY (вход) — `443\tcp`\
+  Внутренний порт telemt (куда пробрасывается трафик) — `8443\tcp`
+
+Туннель работает по протоколу VLESS-XTLS-Reality (или VLESS/xhttp/reality). Оригинальный IP-адрес клиента сохраняется благодаря протоколу PROXYv2, который Xray на Сервере А добавляет через локальный loopback перед упаковкой в туннель, благодаря чему прозрачно доходит до telemt.
+
+---
+
+## Шаг 1. Настройка туннеля Xray (A <-> B)
+
+На обоих серверах необходимо установить **Xray-core** (рекомендуется версия 1.8.4 или новее).
+Официальный скрипт установки (выполнить на обоих серверах):
+```bash
+bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install
+```
+
+### Генерация ключей и параметров (выполнить один раз)
+Для конфигурации потребуются уникальные ID и ключи Xray Reality. Выполните на любом сервере с установленным Xray:
+1. **UUID клиента:**
+```bash
+xray uuid
+# Сохраните вывод (например: 12345678-abcd-1234-abcd-1234567890ab) — это <XRAY_UUID>
+```
+2. **Пара ключей X25519 (Private & Public) для Reality:**
+```bash
+xray x25519
+# Сохраните Private key (<SERVER_B_PRIVATE_KEY>) и Public key (<SERVER_B_PUBLIC_KEY>)
+```
+3. **Short ID (идентификатор Reality):**
+```bash
+openssl rand -hex 8
+# Сохраните вывод (например: abc123def456) — это <SHORT_ID>
+```
+4. **Random Path (путь для xhttp):**
+```bash
+openssl rand -hex 16
+# Сохраните вывод (например, 0123456789abcdef0123456789abcdef), чтобы заменить <YOUR_RANDOM_PATH> в конфигах
+```
+
+---
+
+### Конфигурация Сервера B (_Нидерланды_):
+
+Создаем или редактируем файл `/usr/local/etc/xray/config.json`.
+Этот Xray-сервер будет слушать порт `443` и прозрачно пропускать валидный Reality трафик дальше, а "замаскированный" трафик (например, если кто-то стучится в лоб веб-браузером) пойдет на `yahoo.com`.
+
+```bash
+nano /usr/local/etc/xray/config.json
+```
+
+Содержимое файла:
+```json
+{
+  "log": {
+    "loglevel": "error",
+    "access": "none"
+  },
+  "inbounds": [
+    {
+      "tag": "vless-in",
+      "port": 443,
+      "protocol": "vless",
+      "settings": {
+        "clients": [
+          {
+            "id": "<XRAY_UUID>"
+          }
+        ],
+        "decryption": "none"
+      },
+      "streamSettings": {
+        "network": "xhttp",
+        "security": "reality",
+        "realitySettings": {
+          "dest": "yahoo.com:443",
+          "serverNames": [
+            "yahoo.com"
+          ],
+          "privateKey": "<SERVER_B_PRIVATE_KEY>",
+          "shortIds": [
+            "<SHORT_ID>"
+          ]
+        },
+        "xhttpSettings": {
+          "path": "/<YOUR_RANDOM_PATH>",
+          "mode": "auto"
+        }
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "tag": "tunnel-to-telemt",
+      "protocol": "freedom",
+      "settings": {
+        "destination": "127.0.0.1:8443"
+      }
+    }
+  ],
+  "routing": {
+    "domainStrategy": "AsIs",
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": [
+          "vless-in"
+        ],
+        "outboundTag": "tunnel-to-telemt"
+      }
+    ]
+  }
+}
+```
+
+Открываем порт на фаерволе (если включен):
+```bash
+sudo ufw allow 443/tcp
+```
+Перезапускаем Xray:
+```bash
+sudo systemctl restart xray
+sudo systemctl enable xray
+```
+
+---
+
+### Конфигурация Сервера A (_РФ_):
+
+Аналогично, редактируем `/usr/local/etc/xray/config.json`.
+Здесь Xray выступает публичной точкой: он принимает трафик на внешний порт `443\tcp`, пропускает через локальный loopback (порт `10444`) для добавления PROXYv2-заголовка, и упаковывает в Reality до Сервера B, прося тот доставить данные на *свой локальный* порт `127.0.0.1:8443` (именно там будет слушать telemt).
+
+```bash
+nano /usr/local/etc/xray/config.json
+```
+
+Содержимое файла:
+```json
+{
+  "log": {
+    "loglevel": "error",
+    "access": "none"
+  },
+  "inbounds": [
+    {
+      "tag": "public-in",
+      "port": 443,
+      "listen": "0.0.0.0",
+      "protocol": "dokodemo-door",
+      "settings": {
+        "address": "127.0.0.1",
+        "port": 10444,
+        "network": "tcp"
+      }
+    },
+    {
+      "tag": "tunnel-in",
+      "port": 10444,
+      "listen": "127.0.0.1",
+      "protocol": "dokodemo-door",
+      "settings": {
+        "address": "127.0.0.1",
+        "port": 8443,
+        "network": "tcp"
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "tag": "local-injector",
+      "protocol": "freedom",
+      "settings": {
+        "proxyProtocol": 2
+      }
+    },
+    {
+      "tag": "vless-out",
+      "protocol": "vless",
+      "settings": {
+        "vnext": [
+          {
+            "address": "<PUBLIC_IP_SERVER_B>",
+            "port": 443,
+            "users": [
+              {
+                "id": "<XRAY_UUID>",
+                "encryption": "none"
+              }
+            ]
+          }
+        ]
+      },
+      "streamSettings": {
+        "network": "xhttp",
+        "security": "reality",
+        "realitySettings": {
+          "serverName": "yahoo.com",
+          "publicKey": "<SERVER_B_PUBLIC_KEY>",
+          "shortId": "<SHORT_ID>",
+          "spiderX": "/",
+          "fingerprint": "firefox"
+        },
+        "xhttpSettings": {
+          "path": "/<YOUR_RANDOM_PATH>"
+        }
+      }
+    }
+  ],
+  "routing": {
+    "domainStrategy": "AsIs",
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": ["public-in"],
+        "outboundTag": "local-injector"
+      },
+      {
+        "type": "field",
+        "inboundTag": ["tunnel-in"],
+        "outboundTag": "vless-out"
+      }
+    ]
+  }
+}
+```
+*Замените `<PUBLIC_IP_SERVER_B>` на внешний IP-адрес Сервера B.*
+
+Открываем порт на фаерволе для клиентов:
+```bash
+sudo ufw allow 443/tcp
+```
+
+Перезапускаем Xray:
+```bash
+sudo systemctl restart xray
+sudo systemctl enable xray
+```
+
+---
+
+## Шаг 2. Установка и настройка telemt на Сервере B (_Нидерланды_)
+
+Установка telemt описана [в основной инструкции](../Quick_start/QUICK_START_GUIDE.ru.md).
+Отличие в том, что telemt должен слушать *внутренний* порт (так как 443 занят Xray-сервером), а также ожидать `PROXY` протокол из Xray туннеля.
+
+В конфиге `config.toml` прокси (на Сервере B) укажите:
+```toml
+[server]
+port = 8443
+listen_addr_ipv4 = "127.0.0.1"
+proxy_protocol = true
+
+[general.links]
+show = "*"
+public_host = "<FQDN_OR_IP_SERVER_A>"
+public_port = 443
+```
+
+- `port = 8443` и `listen_addr_ipv4 = "127.0.0.1"` означают, что telemt принимает подключения только изнутри (приходящие от локального Xray-процесса).
+- `proxy_protocol = true` заставляет telemt парсить PROXYv2-заголовок (который добавил Xray на Сервере A через loopback), восстанавливая IP-адрес конечного пользователя (РФ).
+- В `public_host` укажите публичный IP-адрес или домен Сервера A, чтобы ссылки на подключение генерировались корректно.
+
+Перезапустите `telemt`, и клиенты смогут подключаться по выданным ссылкам.
+

docs/WEB/WEB_PROXY.de.md

@@ -0,0 +1,279 @@
+# WEB-Proxy-Modus
+
+[English](WEB_PROXY.en.md) | [Русский](WEB_PROXY.ru.md) | [Deutsch](WEB_PROXY.de.md)
+
+Der WEB-Modus transportiert gewöhnliche MTProxy-Streams über begrenzte HTTPS-Carrier, die mit dem Proxy-Typ `WEB` von Telegram Desktop kompatibel sind. Telemt terminiert TLS nicht selbst: NGINX oder HAProxy verwaltet das öffentliche Zertifikat und leitet unverschlüsseltes HTTP/1.1 an einen privaten Telemt-Listener weiter.
+
+> [!IMPORTANT]
+>
+> Der WEB-Modus ist im aktuellen Quellcode implementiert und konfigurierbar. Für die erste Bereitstellung sind ein Binary aus einer Revision mit dieser Implementierung und ein Neustart des Telemt-Prozesses erforderlich. Veröffentlichte Pakete dürfen erst verwendet werden, nachdem geprüft wurde, dass sie dieselbe Revision enthalten. Die Ende-zu-Ende-Prüfung mit dem vorgesehenen Telegram-Desktop-Build und dem realen öffentlichen TLS-Endpunkt bleibt ein Abnahmeschritt des Betreibers.
+
+## Datenpfad
+
+```text
+Telegram Desktop
+    | HTTPS :443
+    v
+NGINX oder HAProxy (TLS-Terminierung, kanonischer Host und eine X-Forwarded-For-Adresse)
+    | unverschlüsseltes HTTP/1.1 in einem privaten Netz
+    v
+Telemt-WEB-Listener
+    |-- authentifizierter Carrier --> begrenzte logische MTProxy-Relays --> Telegram
+    `-- gewöhnlicher oder ungültiger Request --> konfigurierte Decoy-Site
+```
+
+Leiten Sie den vollständigen öffentlichen vhost an Telemt weiter. Wenn der TLS-Terminator nur bekannte Carrier-Pfade trennt, unterscheiden sich gewöhnliches und authentifiziertes Verhalten beobachtbar und Telemt kann seine Decoy-Richtlinie nicht durchsetzen.
+
+## Unterstützter Client-Vertrag
+
+- Der öffentliche Endpunkt ist immer `https://HOST:443`.
+- Unterstützt werden 16-Byte-MTProxy-Secrets in den Modi `plain` und `dd`. FakeTLS-Secrets mit `ee` werden im WEB-Modus nicht unterstützt.
+- `web.carrier = "https"` wählt serialisierte HTTPS-Uplinks und Long Polling. `web.carrier = "https-lanes"` wählt unabhängige HTTPS-Sequenzen und Polls pro logischem Stream. WebSocket-Carrier werden nicht angeboten.
+- Capability-, Bootstrap- und Session-Zugangsdaten sind getrennte Werte mit begrenzter Lebensdauer. Carrier-Zugangsdaten sind geheim und dürfen nicht in Access-Logs erscheinen.
+- Ein Bootstrap ist ein Bearer-Token und nicht an eine Quelladresse gebunden. Client-Adresse und IP-Familie dürfen sich zwischen dem Laden der Bridge und der Sitzungserstellung ändern. Die Ausstellungsadresse bleibt dem Limit ungenutzter Bootstraps zugeordnet; die Adresse des ersten gültigen Erstellungs-Requests wird der Sitzung zugeordnet.
+- Die innere MTProxy-Authentifizierung ist auf den Benutzer und Secret-Modus des vhost-Profils beschränkt. Ein ungültiger innerer Handshake schließt nur seinen logischen Stream und gelangt niemals in den TCP-Masking-Pfad.
+
+Telegram-Desktop-WEB-Links enthalten keinen Port, da der Client Port 443 voraussetzt:
+
+```text
+tg://webproxy?server=proxy.example.com&secret=0123456789abcdef0123456789abcdef
+tg://webproxy?server=proxy.example.com&secret=dd0123456789abcdef0123456789abcdef
+```
+
+Telemt gibt Links für die durch `[general.links].show` ausgewählten WEB-Profile über das vorhandene Log-Target `telemt::links` aus.
+
+## Voraussetzungen
+
+- Ein eigener öffentlicher FQDN und ein gültiges TLS-Zertifikat auf NGINX oder HAProxy.
+- Eine stabile öffentliche IP für diesen Hostnamen. `public_addr` muss genau diese konkrete IP auf Port 443 enthalten, da die Adresse Teil des Ziel-Tupels des inneren Relays ist.
+- Ein privater oder lokaler HTTP-Pfad vom TLS-Terminator zu Telemt.
+- Eine gewöhnliche Decoy-Site als privater HTTP-Origin oder unveränderlicher Snapshot eines lokalen Verzeichnisses.
+- Ein kompatibler Telegram-Desktop-Build mit dem Proxy-Typ `WEB`.
+
+Die weitergeleitete Client-Adresse darf eine andere IP-Familie als `public_addr` verwenden und sich während der Bootstrap-Lebensdauer ändern. `public_addr` muss weiterhin den exakten öffentlichen Endpoint der inneren MTProxy-Route bezeichnen.
+
+## Minimale Telemt-Konfiguration
+
+Das Beispiel bindet den WEB-Listener an Loopback und verwendet einen privaten HTTP-Decoy-Origin:
+
+```toml
+[general.links]
+show = ["web-user"]
+
+[access.users]
+web-user = "0123456789abcdef0123456789abcdef"
+
+[[server.listeners]]
+ip = "127.0.0.1"
+port = 18080
+transport = "web"
+proxy_protocol = false
+web_client_ip_source = "x_forwarded_for"
+web_trusted_proxy_cidrs = ["127.0.0.1/32"]
+
+[web]
+enabled = true
+carrier = "https-lanes"
+
+[[web.vhosts]]
+host = "proxy.example.com"
+public_addr = "203.0.113.10:443"
+
+[web.vhosts.decoy]
+mode = "http_upstream"
+upstream = "http://127.0.0.1:18081"
+
+[[web.vhosts.profiles]]
+user = "web-user"
+secret_mode = "dd"
+max_sessions = 8
+max_streams = 512
+max_streams_per_session = 64
+```
+
+`https` bleibt der Default und behält das ursprüngliche serialisierte Verhalten bei. Bei `https-lanes` ist Lane null für Session-Steuerung reserviert, und jeder logische Stream ungleich null erhält eine eigene Lane. Jede Lane besitzt eigene Uplink-Sequenzen, Retry-Digests, Downlink-Cursor, nicht bestätigte Replay-Batches, Queues und einen Newest-Poll-Wins-Lebenszyklus. Ein langsamer Stream blockiert daher keinen anderen Stream auf der WEB-Protokollebene.
+
+Damit entfällt die Serialisierung zwischen WEB-Streams auf Anwendungsebene. Öffentliches HTTP/2 läuft weiterhin über eine oder mehrere TCP-Verbindungen, sodass Paketverlust Head-of-Line-Blocking auf Transportebene verursachen kann; `https-lanes` ist kein HTTP/3- oder QUIC-Carrier.
+
+Alle Lane-Queues bleiben innerhalb der vorhandenen Byte-/Item-Budgets pro Sitzung und Prozess. Die Bridge begrenzt jede Lane zusätzlich auf 8 MiB und 1024 eingereihte Elemente. Lane-Long-Polls dürfen höchstens die Hälfte von `web.limits.max_http_handlers` belegen, sodass Handler-Kapazität für Sitzungserstellung, Uplink, DELETE und andere Steuerarbeit verbleibt. `https-lanes` erfordert `max_http_handlers >= 2`.
+
+Die Pfade `/api/v1/up` und `/api/v1/down` ändern sich nicht. Bei `https-lanes` enthält jeder Request an diese Pfade genau einen kanonischen dezimalen `X-Lane-ID`-Header. Die Uplink-Sequenz beginnt pro Lane unabhängig bei `1`, der Downlink-Cursor bei `0`. Lane null akzeptiert nur Session-`PONG`; jeder Frame einer Lane ungleich null muss dieselbe Stream-ID tragen, und eine neue Lane muss mit `OPEN` beginnen. Nachdem eingereihte und nicht bestätigte Downlink-Daten einer geschlossenen Lane vollständig abgearbeitet sind, antwortet Telemt leer mit `X-Lane-Closed: 1`, und die Bridge beendet deren Polling. Wiederholungen bleiben byte-identisch und spielen die ursprüngliche Bestätigung oder den Downlink-Batch erneut aus.
+
+Der WEB-Listener muss `proxy_protocol = false` und `reuse_allow = false` verwenden. `client_mss`, `synlimit`, `announce` und `announce_ip` sind nicht zulässig. `web_trusted_proxy_cidrs` muss nicht leer sein und darf nur die unmittelbar vorgeschalteten NGINX- oder HAProxy-Peers enthalten; `/0`-Netze werden abgelehnt.
+
+Der HTTP-Decoy-Origin muss eine Loopback-, Link-Local- oder private IP-Adresse als Literal verwenden. Telemt bewahrt bei gewöhnlichen Requests Methode, Pfad, Query, Header, gestreamten Body, Response-Status, Header und Body und entfernt Hop-by-Hop-Header. Vor dem Fallback auf den Decoy entfernt Telemt Carrier-Zugangsdaten und Bodys aus fehlerhaften Carrier-Requests.
+
+Alternativ kann ein unveränderlicher Snapshot einer statischen Site verwendet werden:
+
+```toml
+[web.vhosts.decoy]
+mode = "static_directory"
+directory = "/var/lib/telemt/public"
+index = "index.html"
+```
+
+Statische Dateien werden beim Start und bei einem erfolgreichen Konfigurations-Reload gelesen. Eintragszahl, Dateigröße und Gesamtgröße des Snapshots werden durch `[web.limits]` begrenzt. Symlinks und Pfade außerhalb des konfigurierten Verzeichnisses werden abgelehnt. Ändern Sie das Verzeichnis nicht gleichzeitig, während Telemt einen Snapshot erstellt.
+
+Alle WEB-Schlüssel und Defaults sind in der [Konfigurationsreferenz](../Config_params/CONFIG_PARAMS.de.md#web) aufgeführt.
+
+## TLS-Terminierung mit NGINX
+
+```nginx
+upstream telemt_web {
+    server 127.0.0.1:18080;
+    keepalive 64;
+}
+
+server {
+    listen 443 ssl;
+    http2 on;
+    server_name proxy.example.com;
+    access_log off;
+
+    ssl_certificate     /etc/letsencrypt/live/proxy.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/proxy.example.com/privkey.pem;
+
+    client_max_body_size 2m;
+
+    location / {
+        proxy_pass http://telemt_web;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header Connection "";
+
+        proxy_connect_timeout 5s;
+        proxy_send_timeout 35s;
+        proxy_read_timeout 35s;
+        proxy_request_buffering off;
+        proxy_buffering off;
+        proxy_next_upstream off;
+    }
+}
+```
+
+`client_max_body_size` muss mindestens `web.limits.max_body_bytes` entsprechen. `proxy_read_timeout` und `proxy_send_timeout` müssen größer als `web.timeouts.long_poll_secs` sein, dessen Default 25 Sekunden beträgt. Überschreiben Sie `X-Forwarded-For`, statt einen Wert anzuhängen. Telemt akzeptiert eine syntaktisch gültige IP-Adresse; fehlt der Header bei einem vertrauenswürdigen TLS-Terminator, verwendet Telemt die Adresse des direkten Peers, doch clientbezogene Limits und Quellrichtlinien sehen dann den Terminator statt des echten Clients. Aktivieren Sie keine Upstream-Wiederholungen: Der Bridge-Transport führt byte-identische Wiederholungen über sein eigenes Sequenzprotokoll aus.
+
+Öffentliches HTTP/2 ist für `https-lanes` obligatorisch; verwenden Sie die entsprechende HTTP/2-Direktive der installierten NGINX-Version. Der private Hop von NGINX zu Telemt bleibt absichtlich HTTP/1.1. Die Upstream-Verbindungskapazität muss die erwarteten gleichzeitigen Lane-Polls tragen; `keepalive` steuert den Idle-Pool und ist keine Nebenläufigkeitsgrenze.
+
+## TLS-Terminierung mit HAProxy
+
+```haproxy
+frontend public_https
+    mode http
+    no log
+    bind :443 ssl crt /etc/haproxy/certs/proxy.example.com.pem alpn h2,http/1.1
+    acl telemt_web_host hdr(host) -i proxy.example.com proxy.example.com:443
+    use_backend telemt_web if telemt_web_host
+
+backend telemt_web
+    mode http
+    option http-keep-alive
+    retries 0
+    timeout connect 5s
+    timeout server 35s
+    http-request set-header Host proxy.example.com
+    http-request del-header X-Forwarded-For
+    http-request set-header X-Forwarded-For %[src]
+    server telemt_web_1 127.0.0.1:18080 check
+```
+
+Im Frontend oder im Abschnitt `defaults` muss auch `timeout client` oberhalb der Long-Poll-Deadline liegen. Für `https-lanes` muss das öffentliche HAProxy-ALPN `h2` enthalten. Pfad, Raw Query, Body sowie die Carrier-Header `Authorization`, `Content-Type`, `X-Up-Seq`, `X-Down-Cursor` und `X-Lane-ID` dürfen nicht umgeschrieben werden.
+
+## Lebenszyklus und Reload-Verhalten
+
+| Konfiguration | Runtime-Verhalten |
+| --- | --- |
+| Bestand der WEB-Listener, Bind-Adresse und Vertrauensrichtlinie | Prozesseigen; Telemt neu starten. |
+| Jeder Wert in `[web.limits]` | Prozesseigener Speicher- und Ressourcenvertrag; Telemt neu starten. |
+| `web.enabled`, `web.carrier`, Timeouts, vhosts, Profile und Decoys | Werden vom Config-Watcher oder durch einen Runtime-Generations-Reload angewendet. |
+| Bestehende HTTP-Verbindungen und WEB-Sitzungen | Behalten Carrier, Grenzen und Deadlines ihres Erstellungszeitpunkts; neu ausgegebene Bridge-Sitzungen verwenden den aktiven Carrier. Neue logische Streams verwenden die aktive Relay-Generation. |
+| Beenden des Prozesses | Verwendet den zuletzt geladenen Wert von `web.timeouts.shutdown_secs`. |
+
+Jeder logische Stream behält die Client-IP seiner Sitzung und besitzt während der gesamten Relay-Lebensdauer einen prozessweit eindeutigen, von null verschiedenen synthetischen Quellport. Damit bleibt für Direct- und Middle-End-KDF-Routing ein stabiles, kollisionsfreies Quell-/Ziel-Tupel erhalten.
+
+## Verwaltung über die API
+
+API-Verwaltung ist verfügbar, aber absichtlich eingeschränkt. Es gibt weder einen eigenen Endpunkt `/v1/web` noch einen WEB-spezifischen Runtime-Statistik-Endpunkt.
+
+| Operation | API-Unterstützung |
+| --- | --- |
+| `[web]`, vhosts, Profile, Decoys, Timeouts oder Limits lesen oder ändern | Nein. `GET /v1/config` lässt `[web]` aus; `PATCH /v1/config` antwortet für `web` mit `400 section_not_editable`. |
+| `server.listeners` speichern | Ja, über `PATCH /v1/config`; ein geänderter WEB-Listener bleibt jedoch bis zum Prozessneustart zurückgestellt. |
+| Außerhalb der API geänderte WEB-Konfiguration anwenden | Ja, über `POST /v1/system/reload` und anschließende Abfrage des Vorgangsstatus. |
+| `[access.users]` verwalten | Ja, über `/v1/users`. Das Erstellen eines Benutzers erzeugt kein WEB-Profil. |
+| Einen Benutzer widerrufen | Ja. `/v1/users/{username}/disable` aktualisiert die Admission sofort und beendet die aktiven Sitzungen dieses Benutzers. |
+
+Binden Sie die API an Loopback, halten Sie die Whitelist direkter Peers eng, konfigurieren Sie einen exakten Authorization-Header und verwenden Sie `read_only = false` nur dort, wo Mutationen erforderlich sind:
+
+```toml
+[server.api]
+enabled = true
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.0/8"]
+auth_header = "Bearer replace-with-a-random-control-token"
+read_only = false
+```
+
+Die API-Whitelist prüft den direkten TCP-Peer und vertraut `X-Forwarded-For` nicht. Änderungen an `[server.api]` selbst erfordern einen Prozessneustart.
+
+Nachdem ein Administrator oder Konfigurationssystem die TOML-Datei atomar aktualisiert hat, setzen Sie `TELEMT_API_AUTH` auf den exakten Wert von `auth_header` und starten Sie einen beobachtbaren Generations-Reload:
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/v1/system/reload \
+  -H "Authorization: ${TELEMT_API_AUTH}" \
+  -H 'Content-Type: application/json' \
+  -d '{"mode":"drain","timeout_secs":30,"failure_policy":"rollback"}'
+
+# Use data.reload_id from the response.
+curl -sS http://127.0.0.1:9091/v1/system/reload/RELOAD_ID \
+  -H "Authorization: ${TELEMT_API_AUTH}"
+```
+
+Der terminale Status `succeeded` bestätigt die Runtime-Aktivierung. Ein geänderter `web.carrier` wird von neu ausgegebenen Bridge-Sitzungen verwendet; bestehende Sitzungen werden nicht migriert. Enthält `deferred_process_fields` den Wert `server.listeners` oder `web.limits`, ist die Datei gültig und gespeichert, diese Einstellungen erfordern aber weiterhin einen Telemt-Neustart.
+
+Operationen für Access-Benutzer verwenden die vorhandenen Endpunkte, zum Beispiel:
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/v1/users/web-user/disable \
+  -H "Authorization: ${TELEMT_API_AUTH}"
+
+curl -sS -X POST http://127.0.0.1:9091/v1/users/web-user/rotate-secret \
+  -H "Authorization: ${TELEMT_API_AUTH}" \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+Nach einer Secret-Rotation erstellt der Config-Watcher die WEB-Capabilities neu. Die Users-API liefert das Secret, aber keine `tg://webproxy`-URL. Erstellen Sie den Link mit dem konfigurierten Hostnamen und der `plain`- oder `dd`-Darstellung des Profils. Entfernen und aktivieren Sie vor dem Löschen eines Benutzers zuerst das WEB-Profil, das auf ihn verweist, damit die resultierende Konfiguration gültig bleibt.
+
+Der vollständige Vertrag für Requests, Revisionen, Fehler und alle Benutzer-Endpunkte steht in der [Dokumentation der Control API](../Architecture/API/API.md).
+
+## Bereitstellungsinvarianten
+
+- Veröffentlichen Sie den unverschlüsselten HTTP-WEB-Listener niemals in einem nicht vertrauenswürdigen Netz. Erzwingen Sie diese Einschränkung auch bei einer Loopback-Bindung mit Host-Firewall-Regeln.
+- Deaktivieren Sie am TLS-Terminator die Protokollierung von Request-Target und Authorization oder verwenden Sie ein geprüftes, redigiertes Format. Raw Queries enthalten Bridge-Capabilities und `Authorization` enthält Bootstrap- oder Session-Bearer-Zugangsdaten.
+- Verwenden Sie pro vhost eine stabile öffentliche Adresse. Wenn DNS mehrere Ingress-Adressen liefert, muss jede Bereitstellung die Adresse ihres externen Pfads verwenden.
+- Bootstrap- und Session-Register sind prozesslokal. Ein Multi-Prozess- oder Multi-Host-Upstream-Pool benötigt Affinität für den vollständigen vhost: Bridge-GET, Sitzungserstellung, Uplink, Downlink und DELETE. Ein einzelner Telemt-Prozess benötigt keine zusätzliche Affinität.
+- Ein ungenutzter Bootstrap übersteht einen Konfigurations-Reload nur, wenn die exakte Profilidentität aktiv bleibt: Host, `public_addr`, Benutzer, Secret-Modus, Carrier und Capability. Bereits erstellte Sitzungen behalten ihren unveränderlichen Carrier und ihre Profilidentität und bleiben lifecycle-bounded.
+- Der Decoy gehört zum Anti-Probing-Vertrag. Prüfen Sie sein gewöhnliches 404-Verhalten und die Antwortzeiten über den öffentlichen TLS-Endpunkt, bevor Sie Links verteilen.
+
+## Erstprüfung
+
+1. Starten Sie das neu erstellte Telemt-Binary mit der WEB-Konfiguration und prüfen Sie, dass der private Listener gebunden ist.
+2. Prüfen Sie über den öffentlichen TLS-Endpunkt, dass `GET /`, ein unbekannter Pfad und eine ungültige `bridge`-Query die konfigurierte Decoy-Site zurückgeben.
+3. Prüfen Sie, dass Telemt genau eine syntaktisch gültige `X-Forwarded-For`-Adresse und `Host: proxy.example.com` oder `Host: proxy.example.com:443` erhält.
+4. Importieren Sie den ausgegebenen `tg://webproxy`-Link in den vorgesehenen Telegram-Desktop-Build und stellen Sie eine Proxy-Verbindung her.
+5. Bestätigen Sie für `https-lanes`, dass die öffentliche Verbindung HTTP/2 ausgehandelt hat, und testen Sie mindestens zwei gleichzeitige logische Streams; der private Hop zu Telemt bleibt HTTP/1.1.
+6. Testen Sie einen Reconnect und mindestens einen Long Poll über 25 Sekunden, um sicherzustellen, dass Frontend-Timeouts den Carrier nicht abbrechen.
+7. Prüfen Sie Benutzer- und logische MTProxy-Verbindungslimits anhand der Logical-Stream-Zähler und nicht anhand der Zahl der HTTP-Verbindungen.
+
+## Fehlerbehebung
+
+| Symptom | Prüfung |
+| --- | --- |
+| WEB-Konfiguration ist auf dem Datenträger gültig, aber das Listener-Verhalten hat sich nicht geändert | Prüfen Sie `deferred_process_fields`; Listener- und `[web.limits]`-Änderungen erfordern einen Neustart. |
+| Carrier-Requests erreichen den Decoy | Prüfen Sie den exakten vhost, den Secret-Modus des Links, das CIDR des direkten Proxys und genau einen syntaktisch gültigen `X-Forwarded-For`-Wert. |
+| Long Polls werden nach einem festen Intervall getrennt | Setzen Sie Client-, Server-, Sende- und Lese-Timeouts von NGINX/HAProxy über `web.timeouts.long_poll_secs`. |
+| `https-lanes` funktioniert, Streams blockieren sich aber weiterhin | Prüfen Sie die öffentliche HTTP/2-Aushandlung, die unveränderte Weitergabe von `X-Lane-ID` und genügend TLS-Terminator-Upstream-Verbindungen für parallele private HTTP/1.1-Polls. |
+| Telegram Desktop lehnt den Link ab | Lassen Sie den Port weg und verwenden Sie einen gültigen FQDN, extern Port 443 sowie ausschließlich `plain` oder `dd`. |
+| Ein Knoten funktioniert, ein Load-Balancing-Pool aber nur sporadisch | Konfigurieren Sie Affinität für den gesamten vhost; WEB-Zugangsdatenregister sind prozesslokal. |

docs/WEB/WEB_PROXY.en.md

@@ -0,0 +1,279 @@
+# WEB proxy mode
+
+[English](WEB_PROXY.en.md) | [Русский](WEB_PROXY.ru.md) | [Deutsch](WEB_PROXY.de.md)
+
+WEB mode carries ordinary MTProxy streams through bounded HTTPS carriers compatible with Telegram Desktop's `WEB` proxy type. Telemt does not terminate TLS: NGINX or HAProxy owns the public certificate and forwards plain HTTP/1.1 to a private Telemt listener.
+
+> [!IMPORTANT]
+>
+> WEB mode is implemented and configurable in the current source tree. The first deployment requires a binary built from a revision containing this implementation and a Telemt process restart. Published packages can be used only after verifying that they contain the same revision. End-to-end validation with the intended Telegram Desktop build and the real public TLS endpoint remains an operator acceptance step.
+
+## Traffic path
+
+```text
+Telegram Desktop
+    | HTTPS :443
+    v
+NGINX or HAProxy (TLS termination, canonical Host and one X-Forwarded-For address)
+    | plain HTTP/1.1 on a private network
+    v
+Telemt WEB listener
+    |-- authenticated carrier --> bounded logical MTProxy relays --> Telegram
+    `-- ordinary or invalid request --> configured decoy site
+```
+
+Route the complete public vhost to Telemt. Splitting only recognized carrier paths at the TLS terminator would make ordinary and authenticated behavior observably different and would bypass Telemt's decoy policy.
+
+## Supported client contract
+
+- The public endpoint is always `https://HOST:443`.
+- `plain` and `dd` 16-byte MTProxy secrets are supported. `ee` FakeTLS secrets are not supported by WEB mode.
+- `web.carrier = "https"` selects serialized HTTPS uplink and long polling. `web.carrier = "https-lanes"` selects independent HTTPS sequencing and polling per logical stream. WebSocket carriers are not advertised.
+- Capability, bootstrap, and session credentials are separate bounded-lifetime values. Carrier credentials must be treated as secrets and must not appear in access logs.
+- A bootstrap is a bearer credential, not a source-address-bound token. The client address and IP family may change between bridge loading and session creation. The issuing address retains unused-bootstrap accounting, while the address on the first valid creation request owns the session.
+- Inner MTProxy authentication is restricted to the user and secret mode selected by the vhost profile. Invalid inner handshakes close only their logical stream and never enter the TCP masking path.
+
+Telegram Desktop WEB links omit a port because the client requires port 443:
+
+```text
+tg://webproxy?server=proxy.example.com&secret=0123456789abcdef0123456789abcdef
+tg://webproxy?server=proxy.example.com&secret=dd0123456789abcdef0123456789abcdef
+```
+
+Telemt prints links for WEB profiles selected by `[general.links].show` through the existing `telemt::links` log target.
+
+## Prerequisites
+
+- A dedicated public FQDN and valid TLS certificate on NGINX or HAProxy.
+- A stable public IP for that hostname. `public_addr` must be that concrete IP on port 443 because it participates in the inner relay destination tuple.
+- A private or loopback HTTP path from the TLS terminator to Telemt.
+- A normal decoy site, either a private HTTP origin or an immutable local directory snapshot.
+- A compatible Telegram Desktop build with the `WEB` proxy type.
+
+The forwarded client address may differ in family from `public_addr` and may change while a bootstrap is live. `public_addr` must still identify the exact public endpoint used by the inner MTProxy route.
+
+## Minimal Telemt configuration
+
+The example keeps the WEB listener on loopback and uses a private HTTP decoy origin:
+
+```toml
+[general.links]
+show = ["web-user"]
+
+[access.users]
+web-user = "0123456789abcdef0123456789abcdef"
+
+[[server.listeners]]
+ip = "127.0.0.1"
+port = 18080
+transport = "web"
+proxy_protocol = false
+web_client_ip_source = "x_forwarded_for"
+web_trusted_proxy_cidrs = ["127.0.0.1/32"]
+
+[web]
+enabled = true
+carrier = "https-lanes"
+
+[[web.vhosts]]
+host = "proxy.example.com"
+public_addr = "203.0.113.10:443"
+
+[web.vhosts.decoy]
+mode = "http_upstream"
+upstream = "http://127.0.0.1:18081"
+
+[[web.vhosts.profiles]]
+user = "web-user"
+secret_mode = "dd"
+max_sessions = 8
+max_streams = 512
+max_streams_per_session = 64
+```
+
+`https` remains the default and preserves the original serialized behavior. `https-lanes` assigns lane zero to session control and one lane to every non-zero logical stream. Each lane has its own uplink sequence, retry digest, downlink cursor, unacknowledged replay batch, queue, and newest-poll-wins lifecycle. A slow stream therefore does not block another stream at the WEB protocol layer.
+
+This removes application-level serialization between WEB streams. Public HTTP/2 still runs over one or more TCP connections, so packet loss can cause transport-level head-of-line blocking; `https-lanes` is not an HTTP/3 or QUIC carrier.
+
+All lane queues remain inside the existing per-session and process-wide byte/item budgets. The bridge also limits each lane to 8 MiB and 1024 queued items. Telemt permits lane long polls to occupy at most half of `web.limits.max_http_handlers`, preserving handler capacity for session creation, uplink, DELETE, and other control work. `https-lanes` requires `max_http_handlers >= 2`.
+
+The `/api/v1/up` and `/api/v1/down` paths do not change. In `https-lanes`, every request on those paths carries one canonical decimal `X-Lane-ID`. Uplink sequence starts at `1` and downlink cursor at `0` independently for each lane. Lane zero accepts only session `PONG`; every frame in a non-zero lane must have the same stream ID, and a new lane must begin with `OPEN`. After a closed lane's queued and unacknowledged downlink data is drained, Telemt returns an empty response with `X-Lane-Closed: 1`, and the bridge stops polling it. Retries remain byte-identical and replay the original acknowledgement or downlink batch.
+
+The WEB listener must use `proxy_protocol = false` and `reuse_allow = false`. It cannot use `client_mss`, `synlimit`, `announce`, or `announce_ip`. `web_trusted_proxy_cidrs` must be non-empty and must contain only the immediate NGINX or HAProxy peers; `/0` networks are rejected.
+
+The HTTP decoy origin must be a loopback, link-local, or private IP literal. Telemt preserves ordinary request method, path, query, headers, streamed body, response status, headers, and body while removing hop-by-hop headers. Malformed carrier requests have carrier credentials and bodies removed before falling back to the decoy.
+
+An immutable static-site snapshot can be used instead:
+
+```toml
+[web.vhosts.decoy]
+mode = "static_directory"
+directory = "/var/lib/telemt/public"
+index = "index.html"
+```
+
+Static files are read at startup and successful configuration reload. Entry count, per-file size, and total snapshot size are bounded by `[web.limits]`. Symlinks and paths escaping the configured directory are rejected. Do not mutate the directory concurrently while Telemt builds a snapshot.
+
+All WEB keys and defaults are listed in the [configuration reference](../Config_params/CONFIG_PARAMS.en.md#web).
+
+## NGINX TLS termination
+
+```nginx
+upstream telemt_web {
+    server 127.0.0.1:18080;
+    keepalive 64;
+}
+
+server {
+    listen 443 ssl;
+    http2 on;
+    server_name proxy.example.com;
+    access_log off;
+
+    ssl_certificate     /etc/letsencrypt/live/proxy.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/proxy.example.com/privkey.pem;
+
+    client_max_body_size 2m;
+
+    location / {
+        proxy_pass http://telemt_web;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header Connection "";
+
+        proxy_connect_timeout 5s;
+        proxy_send_timeout 35s;
+        proxy_read_timeout 35s;
+        proxy_request_buffering off;
+        proxy_buffering off;
+        proxy_next_upstream off;
+    }
+}
+```
+
+`client_max_body_size` must be at least `web.limits.max_body_bytes`. `proxy_read_timeout` and `proxy_send_timeout` must exceed `web.timeouts.long_poll_secs`, which defaults to 25 seconds. Overwrite, rather than append to, `X-Forwarded-For`. Telemt accepts one parseable IP address; if a trusted terminator omits the header, Telemt falls back to the direct peer address, but per-client limits and source policy then see the terminator rather than the real client. Do not enable upstream retries: the bridge performs byte-identical retries through its own sequence protocol.
+
+Public HTTP/2 is mandatory for `https-lanes`; use the equivalent HTTP/2 directive supported by the installed NGINX release. The private NGINX-to-Telemt hop intentionally remains HTTP/1.1. Ensure the upstream connection capacity can sustain the expected simultaneous lane polls; `keepalive` controls the idle pool and is not a concurrency limit.
+
+## HAProxy TLS termination
+
+```haproxy
+frontend public_https
+    mode http
+    no log
+    bind :443 ssl crt /etc/haproxy/certs/proxy.example.com.pem alpn h2,http/1.1
+    acl telemt_web_host hdr(host) -i proxy.example.com proxy.example.com:443
+    use_backend telemt_web if telemt_web_host
+
+backend telemt_web
+    mode http
+    option http-keep-alive
+    retries 0
+    timeout connect 5s
+    timeout server 35s
+    http-request set-header Host proxy.example.com
+    http-request del-header X-Forwarded-For
+    http-request set-header X-Forwarded-For %[src]
+    server telemt_web_1 127.0.0.1:18080 check
+```
+
+The frontend or `defaults` section must also set `timeout client` above the long-poll deadline. HAProxy's public ALPN must include `h2` for `https-lanes`. Do not rewrite the path, raw query, body, or the `Authorization`, `Content-Type`, `X-Up-Seq`, `X-Down-Cursor`, and `X-Lane-ID` carrier headers.
+
+## Lifecycle and reload behavior
+
+| Configuration | Runtime behavior |
+| --- | --- |
+| WEB listener inventory, bind address, and trust policy | Process-owned; restart Telemt. |
+| Any `[web.limits]` value | Process-owned memory/resource contract; restart Telemt. |
+| `web.enabled`, `web.carrier`, timeouts, vhosts, profiles, and decoys | Applied by the config watcher or a runtime generation reload. |
+| Existing HTTP connections and WEB sessions | Keep their acquisition-time carrier, limits, and deadlines; newly issued bridge sessions use the active carrier. New logical streams use the active relay generation. |
+| Process shutdown | Uses the latest reloaded `web.timeouts.shutdown_secs`. |
+
+Each logical stream keeps its session's creation-time client IP and owns a process-unique, non-zero synthetic source port for the complete relay lifetime. This preserves one stable, non-colliding source/destination tuple for Direct and Middle-End KDF routing.
+
+## API management
+
+API management is available, but it is intentionally partial. There is no dedicated `/v1/web` endpoint and no WEB-specific runtime statistics endpoint.
+
+| Operation | API support |
+| --- | --- |
+| Read or patch `[web]`, vhosts, profiles, decoys, timeouts, or limits | No. `GET /v1/config` omits `[web]`; `PATCH /v1/config` returns `400 section_not_editable` for `web`. |
+| Persist `server.listeners` | Yes, through `PATCH /v1/config`, but a changed WEB listener remains deferred until process restart. |
+| Apply an externally edited WEB configuration | Yes, through `POST /v1/system/reload`, then inspect the operation status. |
+| Manage `[access.users]` | Yes, through `/v1/users`. User creation does not create a WEB profile. |
+| Revoke one user | Yes. `/v1/users/{username}/disable` updates admission immediately and cancels that user's active sessions. |
+
+Bind the API to loopback, keep its direct-peer whitelist narrow, configure an exact authorization header, and leave `read_only = false` only when mutation is required:
+
+```toml
+[server.api]
+enabled = true
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.0/8"]
+auth_header = "Bearer replace-with-a-random-control-token"
+read_only = false
+```
+
+The API whitelist checks the direct TCP peer and does not trust `X-Forwarded-For`. Changes to `[server.api]` itself require a process restart.
+
+After an administrator or configuration system atomically updates the TOML file, set `TELEMT_API_AUTH` to the exact value configured in `auth_header` and submit an observable generation reload:
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/v1/system/reload \
+  -H "Authorization: ${TELEMT_API_AUTH}" \
+  -H 'Content-Type: application/json' \
+  -d '{"mode":"drain","timeout_secs":30,"failure_policy":"rollback"}'
+
+# Use data.reload_id from the response.
+curl -sS http://127.0.0.1:9091/v1/system/reload/RELOAD_ID \
+  -H "Authorization: ${TELEMT_API_AUTH}"
+```
+
+A terminal `succeeded` status confirms runtime activation. A changed `web.carrier` is used by newly issued bridge sessions; existing sessions are not migrated. If `deferred_process_fields` contains `server.listeners` or `web.limits`, the file is valid and persisted but those settings still require a Telemt restart.
+
+Access-user operations use the existing endpoints, for example:
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/v1/users/web-user/disable \
+  -H "Authorization: ${TELEMT_API_AUTH}"
+
+curl -sS -X POST http://127.0.0.1:9091/v1/users/web-user/rotate-secret \
+  -H "Authorization: ${TELEMT_API_AUTH}" \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+The config watcher rebuilds WEB capabilities after a secret rotation. The users API returns the secret, not a `tg://webproxy` URL; construct the link with the configured hostname and the profile's `plain` or `dd` representation. Before deleting a user referenced by a WEB profile, remove and apply that profile first so the resulting configuration remains valid.
+
+See the complete [Control API contract](../Architecture/API/API.md) for request envelopes, revisions, failure modes, and all user endpoints.
+
+## Deployment invariants
+
+- Never expose the plain HTTP WEB listener to an untrusted network. Enforce the restriction with host firewall rules even when it binds to loopback.
+- Disable request-target and authorization logging at the TLS terminator, or use a verified redacted format. Raw queries contain bridge capabilities and `Authorization` contains bootstrap or session bearer credentials.
+- Keep one stable public address per vhost. If DNS returns several ingress addresses, each deployment must use the address matching its external path.
+- Bootstrap and session registries are process-local. A multi-process or multi-host upstream pool requires affinity for the complete vhost: bridge GET, session creation, uplink, downlink, and DELETE. A single Telemt process needs no extra affinity.
+- An unused bootstrap survives a configuration reload only when the exact profile identity remains active: host, `public_addr`, user, secret mode, carrier, and capability. Existing created sessions retain their immutable carrier and profile identity and remain lifecycle-bounded.
+- The decoy is part of the anti-probing contract. Verify its ordinary 404 behavior and response timing through the public TLS endpoint before distributing links.
+
+## Initial verification
+
+1. Start the rebuilt Telemt binary with the WEB configuration and confirm that the private listener is bound.
+2. Confirm through the public TLS endpoint that `GET /`, an unknown path, and an invalid `bridge` query return the configured decoy site.
+3. Confirm that Telemt receives one parseable `X-Forwarded-For` address and `Host: proxy.example.com` or `Host: proxy.example.com:443`.
+4. Import the printed `tg://webproxy` link in the intended Telegram Desktop build and establish a proxy connection.
+5. For `https-lanes`, confirm that the public connection negotiated HTTP/2 and exercise at least two simultaneous logical streams; the private Telemt hop remains HTTP/1.1.
+6. Exercise reconnect and at least one long poll beyond 25 seconds to prove the frontend timeouts do not truncate the carrier.
+7. Verify user and logical MTProxy connection limits using logical-stream counters, not the number of HTTP connections.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| WEB configuration is valid on disk but listener behavior did not change | Inspect reload `deferred_process_fields`; listener and `[web.limits]` changes require restart. |
+| Carrier requests reach the decoy | Verify exact vhost, link secret mode, direct proxy CIDR, and one parseable `X-Forwarded-For` value. |
+| Long polls disconnect near a fixed interval | Raise NGINX/HAProxy client, server, send, and read timeouts above `web.timeouts.long_poll_secs`. |
+| `https-lanes` works but streams still block each other | Confirm public HTTP/2 negotiation, preserve `X-Lane-ID`, and provide enough TLS-terminator upstream connections for concurrent private HTTP/1.1 polls. |
+| Telegram Desktop rejects the link | Omit the port, use a valid FQDN, port 443 externally, and only `plain` or `dd` secret mode. |
+| One node works but a load-balanced pool is intermittent | Add complete-vhost affinity; WEB credential registries are process-local. |

docs/WEB/WEB_PROXY.ru.md

@@ -0,0 +1,279 @@
+# WEB-режим прокси
+
+[English](WEB_PROXY.en.md) | [Русский](WEB_PROXY.ru.md) | [Deutsch](WEB_PROXY.de.md)
+
+WEB-режим переносит обычные MTProxy-потоки через bounded HTTPS carriers, совместимые с типом прокси `WEB` в Telegram Desktop. Telemt не терминирует TLS: публичный сертификат обслуживает NGINX или HAProxy, который передаёт обычный HTTP/1.1 на приватный listener Telemt.
+
+> [!IMPORTANT]
+>
+> WEB-режим реализован и настраивается в текущем дереве исходного кода. Для первого развёртывания нужен бинарный файл, собранный из ревизии с этой реализацией, и перезапуск процесса Telemt. Готовый пакет можно использовать только после проверки, что он содержит эту ревизию. Сквозная проверка с целевой сборкой Telegram Desktop и реальным публичным TLS endpoint остаётся обязательным приёмочным шагом оператора.
+
+## Путь трафика
+
+```text
+Telegram Desktop
+    | HTTPS :443
+    v
+NGINX или HAProxy (TLS termination, канонический Host и один адрес X-Forwarded-For)
+    | обычный HTTP/1.1 в приватной сети
+    v
+WEB-listener Telemt
+    |-- аутентифицированный carrier --> bounded logical MTProxy relays --> Telegram
+    `-- обычный или некорректный запрос --> настроенный decoy site
+```
+
+Направляйте в Telemt весь публичный vhost. Если TLS-терминатор будет выделять только известные carrier paths, поведение обычных и аутентифицированных запросов станет наблюдаемо различным, а decoy policy Telemt будет обойдена.
+
+## Поддерживаемый контракт клиента
+
+- Публичный endpoint всегда имеет вид `https://HOST:443`.
+- Поддерживаются 16-байтовые MTProxy-секреты `plain` и `dd`. FakeTLS-секреты `ee` в WEB-режиме не поддерживаются.
+- `web.carrier = "https"` выбирает сериализованные HTTPS uplink и long polling. `web.carrier = "https-lanes"` выбирает независимые HTTPS sequencing и polling для каждого logical stream. WebSocket carriers не анонсируются.
+- Capability, bootstrap и session credentials — отдельные значения с ограниченным сроком жизни. Carrier credentials считаются секретами и не должны попадать в access logs.
+- Bootstrap является bearer credential, а не token с привязкой к source address. Адрес клиента и его IP-семейство могут измениться между загрузкой bridge и созданием session. Адрес выдачи продолжает учитываться в лимите неиспользованных bootstrap, а владельцем session становится адрес первого корректного запроса создания.
+- Внутренняя MTProxy-аутентификация ограничена пользователем и режимом секрета, выбранными профилем vhost. Некорректный внутренний handshake закрывает только свой logical stream и никогда не попадает в TCP masking path.
+
+В WEB-ссылках Telegram Desktop нет порта, потому что клиент требует порт 443:
+
+```text
+tg://webproxy?server=proxy.example.com&secret=0123456789abcdef0123456789abcdef
+tg://webproxy?server=proxy.example.com&secret=dd0123456789abcdef0123456789abcdef
+```
+
+Telemt печатает ссылки для WEB-профилей, выбранных в `[general.links].show`, через существующий log target `telemt::links`.
+
+## Предварительные требования
+
+- Отдельный публичный FQDN и действующий TLS-сертификат на NGINX или HAProxy.
+- Стабильный публичный IP этого hostname. В `public_addr` должен быть указан именно этот конкретный IP с портом 443, поскольку адрес участвует во внутреннем destination tuple relay.
+- Приватный или loopback HTTP-путь от TLS-терминатора до Telemt.
+- Обычный decoy site: приватный HTTP origin либо immutable snapshot локального каталога.
+- Совместимая сборка Telegram Desktop с типом прокси `WEB`.
+
+Forwarded client address может принадлежать другому IP-семейству, чем `public_addr`, и изменяться в течение срока жизни bootstrap. При этом `public_addr` должен по-прежнему указывать точный публичный endpoint внутреннего MTProxy route.
+
+## Минимальная конфигурация Telemt
+
+В примере WEB-listener остаётся на loopback, а decoy использует приватный HTTP origin:
+
+```toml
+[general.links]
+show = ["web-user"]
+
+[access.users]
+web-user = "0123456789abcdef0123456789abcdef"
+
+[[server.listeners]]
+ip = "127.0.0.1"
+port = 18080
+transport = "web"
+proxy_protocol = false
+web_client_ip_source = "x_forwarded_for"
+web_trusted_proxy_cidrs = ["127.0.0.1/32"]
+
+[web]
+enabled = true
+carrier = "https-lanes"
+
+[[web.vhosts]]
+host = "proxy.example.com"
+public_addr = "203.0.113.10:443"
+
+[web.vhosts.decoy]
+mode = "http_upstream"
+upstream = "http://127.0.0.1:18081"
+
+[[web.vhosts.profiles]]
+user = "web-user"
+secret_mode = "dd"
+max_sessions = 8
+max_streams = 512
+max_streams_per_session = 64
+```
+
+`https` остаётся default и сохраняет исходное сериализованное поведение. В `https-lanes` lane zero отведена под session control, а каждому ненулевому logical stream соответствует своя lane. У каждой lane собственные uplink sequence, retry digest, downlink cursor, unacknowledged replay batch, очередь и lifecycle newest-poll-wins. Поэтому медленный stream не блокирует другой stream на уровне WEB-протокола.
+
+Это устраняет сериализацию между WEB-streams на уровне приложения. Публичный HTTP/2 всё ещё работает поверх одного или нескольких TCP-connections, поэтому потеря пакетов может вызвать transport-level head-of-line blocking; `https-lanes` не является HTTP/3- или QUIC-carrier.
+
+Все lane queues входят в существующие per-session и process-wide byte/item budgets. Bridge дополнительно ограничивает одну lane 8 MiB и 1024 элементами. Lane long polls могут занимать не более половины `web.limits.max_http_handlers`, оставляя handler capacity для session creation, uplink, DELETE и другой control work. Для `https-lanes` требуется `max_http_handlers >= 2`.
+
+Paths `/api/v1/up` и `/api/v1/down` не меняются. В `https-lanes` каждый запрос к ним содержит один канонический десятичный `X-Lane-ID`. Uplink sequence начинается с `1`, а downlink cursor — с `0` независимо для каждой lane. Lane zero принимает только session `PONG`; все frames ненулевой lane должны иметь тот же stream ID, а новая lane должна начинаться с `OPEN`. После отправки всей queued и unacknowledged downlink data закрытой lane Telemt возвращает пустой ответ с `X-Lane-Closed: 1`, и bridge прекращает её polling. Retry остаются byte-identical и повторяют исходный acknowledgement или downlink batch.
+
+Для WEB-listener обязательны `proxy_protocol = false` и `reuse_allow = false`. В нём нельзя использовать `client_mss`, `synlimit`, `announce` и `announce_ip`. Массив `web_trusted_proxy_cidrs` должен быть непустым и содержать только непосредственные адреса NGINX или HAProxy; сети `/0` запрещены.
+
+HTTP decoy origin должен быть loopback, link-local или private IP literal. Для обычных запросов Telemt сохраняет method, path, query, headers, streamed body, response status, headers и body, удаляя hop-by-hop headers. Перед отправкой некорректного carrier-запроса в decoy Telemt удаляет из него carrier credentials и body.
+
+Вместо origin можно использовать immutable snapshot статического сайта:
+
+```toml
+[web.vhosts.decoy]
+mode = "static_directory"
+directory = "/var/lib/telemt/public"
+index = "index.html"
+```
+
+Статические файлы читаются при запуске и успешном reload конфигурации. Число элементов, размер одного файла и общий размер snapshot ограничены `[web.limits]`. Symlinks и пути с выходом из настроенного каталога запрещены. Не изменяйте каталог одновременно с построением snapshot в Telemt.
+
+Все WEB-ключи и defaults перечислены в [справочнике конфигурации](../Config_params/CONFIG_PARAMS.ru.md#web).
+
+## Терминация TLS на NGINX
+
+```nginx
+upstream telemt_web {
+    server 127.0.0.1:18080;
+    keepalive 64;
+}
+
+server {
+    listen 443 ssl;
+    http2 on;
+    server_name proxy.example.com;
+    access_log off;
+
+    ssl_certificate     /etc/letsencrypt/live/proxy.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/proxy.example.com/privkey.pem;
+
+    client_max_body_size 2m;
+
+    location / {
+        proxy_pass http://telemt_web;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header Connection "";
+
+        proxy_connect_timeout 5s;
+        proxy_send_timeout 35s;
+        proxy_read_timeout 35s;
+        proxy_request_buffering off;
+        proxy_buffering off;
+        proxy_next_upstream off;
+    }
+}
+```
+
+`client_max_body_size` должен быть не меньше `web.limits.max_body_bytes`. Значения `proxy_read_timeout` и `proxy_send_timeout` должны превышать `web.timeouts.long_poll_secs`, по умолчанию равный 25 секундам. Перезаписывайте `X-Forwarded-For`, а не дополняйте его. Telemt принимает один корректно разбираемый IP-адрес; если доверенный TLS-терминатор не передал header, Telemt использует адрес непосредственного peer, но per-client limits и source policy тогда видят терминатор вместо реального клиента. Не включайте upstream retries: byte-identical retry выполняет сам bridge по своему sequence protocol.
+
+Для `https-lanes` обязателен публичный HTTP/2; используйте эквивалентную HTTP/2-директиву, поддерживаемую установленной версией NGINX. Приватный hop NGINX-to-Telemt намеренно остаётся HTTP/1.1. Upstream connection capacity должна выдерживать ожидаемое число одновременных lane polls; `keepalive` управляет idle pool и не является лимитом concurrency.
+
+## Терминация TLS на HAProxy
+
+```haproxy
+frontend public_https
+    mode http
+    no log
+    bind :443 ssl crt /etc/haproxy/certs/proxy.example.com.pem alpn h2,http/1.1
+    acl telemt_web_host hdr(host) -i proxy.example.com proxy.example.com:443
+    use_backend telemt_web if telemt_web_host
+
+backend telemt_web
+    mode http
+    option http-keep-alive
+    retries 0
+    timeout connect 5s
+    timeout server 35s
+    http-request set-header Host proxy.example.com
+    http-request del-header X-Forwarded-For
+    http-request set-header X-Forwarded-For %[src]
+    server telemt_web_1 127.0.0.1:18080 check
+```
+
+Во frontend или секции `defaults` также задайте `timeout client` выше long-poll deadline. Для `https-lanes` публичный ALPN HAProxy должен содержать `h2`. Не переписывайте path, raw query, body и carrier headers `Authorization`, `Content-Type`, `X-Up-Seq`, `X-Down-Cursor`, `X-Lane-ID`.
+
+## Lifecycle и reload
+
+| Конфигурация | Поведение runtime |
+| --- | --- |
+| Состав WEB-listeners, bind address и trust policy | Принадлежат процессу; перезапустите Telemt. |
+| Любое значение `[web.limits]` | Process-owned контракт памяти и ресурсов; перезапустите Telemt. |
+| `web.enabled`, `web.carrier`, timeouts, vhosts, profiles и decoys | Применяются config watcher или runtime generation reload. |
+| Существующие HTTP connections и WEB sessions | Сохраняют carrier, лимиты и deadlines своего момента создания; новые bridge sessions получают активный carrier. Новые logical streams используют активное relay generation. |
+| Завершение процесса | Использует последнее применённое значение `web.timeouts.shutdown_secs`. |
+
+Каждый logical stream сохраняет client IP своей сессии и владеет уникальным в пределах процесса ненулевым synthetic source port до завершения relay. Это сохраняет один стабильный непересекающийся source/destination tuple для Direct и Middle-End KDF routing.
+
+## Управление через API
+
+Управление через API доступно, но намеренно ограничено. Отдельных endpoint `/v1/web` и WEB-specific runtime statistics endpoint сейчас нет.
+
+| Операция | Поддержка API |
+| --- | --- |
+| Чтение или изменение `[web]`, vhosts, profiles, decoys, timeouts или limits | Нет. `GET /v1/config` не возвращает `[web]`; `PATCH /v1/config` отвечает `400 section_not_editable` на ключ `web`. |
+| Сохранение `server.listeners` | Да, через `PATCH /v1/config`, но изменённый WEB-listener остаётся deferred до перезапуска процесса. |
+| Применение WEB-конфигурации, изменённой вне API | Да, через `POST /v1/system/reload` с последующей проверкой статуса операции. |
+| Управление `[access.users]` | Да, через `/v1/users`. Создание пользователя не создаёт WEB-профиль. |
+| Отзыв отдельного пользователя | Да. `/v1/users/{username}/disable` немедленно обновляет admission и завершает активные сессии пользователя. |
+
+Привяжите API к loopback, оставьте узким whitelist непосредственных peers, настройте точное значение authorization header и используйте `read_only = false` только там, где нужны мутации:
+
+```toml
+[server.api]
+enabled = true
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.0/8"]
+auth_header = "Bearer replace-with-a-random-control-token"
+read_only = false
+```
+
+API whitelist проверяет непосредственный TCP peer и не доверяет `X-Forwarded-For`. Изменения самой секции `[server.api]` требуют перезапуска процесса.
+
+После атомарного изменения TOML-файла администратором или системой управления конфигурацией задайте в `TELEMT_API_AUTH` точное значение `auth_header` и отправьте наблюдаемый generation reload:
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/v1/system/reload \
+  -H "Authorization: ${TELEMT_API_AUTH}" \
+  -H 'Content-Type: application/json' \
+  -d '{"mode":"drain","timeout_secs":30,"failure_policy":"rollback"}'
+
+# Use data.reload_id from the response.
+curl -sS http://127.0.0.1:9091/v1/system/reload/RELOAD_ID \
+  -H "Authorization: ${TELEMT_API_AUTH}"
+```
+
+Терминальный статус `succeeded` подтверждает активацию runtime. Изменённый `web.carrier` используют новые bridge sessions; существующие сессии не мигрируют. Если `deferred_process_fields` содержит `server.listeners` или `web.limits`, файл валиден и сохранён, но эти настройки всё ещё требуют перезапуска Telemt.
+
+Операции с access users используют существующие endpoints, например:
+
+```bash
+curl -sS -X POST http://127.0.0.1:9091/v1/users/web-user/disable \
+  -H "Authorization: ${TELEMT_API_AUTH}"
+
+curl -sS -X POST http://127.0.0.1:9091/v1/users/web-user/rotate-secret \
+  -H "Authorization: ${TELEMT_API_AUTH}" \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+После ротации секрета config watcher перестраивает WEB capabilities. Users API возвращает секрет, но не URL `tg://webproxy`; соберите ссылку из настроенного hostname и представления `plain` или `dd` соответствующего профиля. Перед удалением пользователя, на которого ссылается WEB-профиль, сначала удалите и примените этот профиль, чтобы итоговая конфигурация оставалась валидной.
+
+Полный контракт запросов, revisions, ошибок и всех user endpoints приведён в [документации Control API](../Architecture/API/API.md).
+
+## Инварианты развёртывания
+
+- Никогда не публикуйте plain HTTP WEB-listener в недоверенной сети. Закрепите это host firewall rules, даже если listener использует loopback.
+- Отключите логирование request target и authorization на TLS-терминаторе либо используйте проверенный формат с редактированием. Raw queries содержат bridge capabilities, а `Authorization` — bootstrap или session bearer credentials.
+- Сохраняйте один стабильный публичный адрес на vhost. Если DNS возвращает несколько ingress addresses, каждый deployment должен использовать адрес своего внешнего пути.
+- Bootstrap- и session-registries локальны для процесса. Для multi-process или multi-host upstream pool нужна affinity всего vhost: bridge GET, создание сессии, uplink, downlink и DELETE. Одному процессу Telemt дополнительная affinity не нужна.
+- Неиспользованный bootstrap переживает reload конфигурации, только если остаётся активной точная identity профиля: host, `public_addr`, user, secret mode, carrier и capability. Уже созданные sessions сохраняют неизменные carrier и identity профиля и остаются lifecycle-bounded.
+- Decoy входит в anti-probing contract. До распространения ссылок проверьте через публичный TLS endpoint его обычный ответ 404 и response timing.
+
+## Первичная проверка
+
+1. Запустите пересобранный Telemt с WEB-конфигурацией и убедитесь, что приватный listener привязан.
+2. Через публичный TLS endpoint проверьте, что `GET /`, неизвестный path и некорректный query `bridge` возвращают настроенный decoy site.
+3. Убедитесь, что Telemt получает один корректно разбираемый адрес `X-Forwarded-For` и `Host: proxy.example.com` либо `Host: proxy.example.com:443`.
+4. Импортируйте напечатанную ссылку `tg://webproxy` в целевую сборку Telegram Desktop и установите соединение через прокси.
+5. Для `https-lanes` подтвердите согласование HTTP/2 на публичном connection и проверьте как минимум два одновременных logical streams; приватный hop к Telemt остаётся HTTP/1.1.
+6. Проверьте reconnect и как минимум один long poll длительнее 25 секунд, чтобы frontend timeouts не обрывали carrier.
+7. Проверяйте лимиты пользователя и logical MTProxy connections по logical-stream counters, а не по числу HTTP connections.
+
+## Диагностика
+
+| Симптом | Что проверить |
+| --- | --- |
+| WEB-конфигурация валидна на диске, но поведение listener’а не изменилось | Проверьте `deferred_process_fields`; listener и `[web.limits]` требуют перезапуска. |
+| Carrier-запросы попадают в decoy | Проверьте точный vhost, secret mode ссылки, CIDR непосредственного proxy и единственное корректно разбираемое значение `X-Forwarded-For`. |
+| Long polls разрываются через фиксированный интервал | Поднимите client, server, send и read timeouts NGINX/HAProxy выше `web.timeouts.long_poll_secs`. |
+| `https-lanes` работает, но streams всё ещё блокируют друг друга | Проверьте согласование публичного HTTP/2, сохранение `X-Lane-ID` и достаточное число upstream connections TLS-терминатора для параллельных приватных HTTP/1.1 polls. |
+| Telegram Desktop отклоняет ссылку | Не указывайте порт, используйте валидный FQDN, внешний порт 443 и только `plain` или `dd`. |
+| Один узел работает, но load-balanced pool нестабилен | Настройте affinity всего vhost: WEB credential registries локальны для процесса. |

docs/assets/telegram_button.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg width="100%" height="100%" viewBox="0 0 150 30" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;"><path d="M150,15c0,8.279 -6.721,15 -15,15l-120,0c-8.279,0 -15,-6.721 -15,-15c0,-8.279 6.721,-15 15,-15l120,0c8.279,0 15,6.721 15,15Z" style="fill:#24a1ed;"/><g transform="matrix(20.833333,0,0,20.833333,111.464184,22.329305)"></g><text x="39.666px" y="22.329px" style="font-family:'ArialMT', 'Arial', sans-serif;font-size:20.833px;fill:#fff;">Join us!</text></svg>

install.sh

@@ -8,43 +8,273 @@ CONFIG_DIR="${CONFIG_DIR:-/etc/telemt}"
 CONFIG_FILE="${CONFIG_FILE:-${CONFIG_DIR}/telemt.toml}"
 WORK_DIR="${WORK_DIR:-/opt/telemt}"
 TLS_DOMAIN="${TLS_DOMAIN:-petrovich.ru}"
+SERVER_PORT="${SERVER_PORT:-443}"
+USER_SECRET=""
+AD_TAG=""
 SERVICE_NAME="telemt"
 TEMP_DIR=""
 SUDO=""
 CONFIG_PARENT_DIR=""
 SERVICE_START_FAILED=0
 
+PORT_PROVIDED=0
+SECRET_PROVIDED=0
+AD_TAG_PROVIDED=0
+DOMAIN_PROVIDED=0
+LANG_PROVIDED=0
+
 ACTION="install"
 TARGET_VERSION="${VERSION:-latest}"
+LANG_CHOICE="en"
+
+PATH="${PATH}:/usr/sbin:/sbin"
+
+set_language() {
+    case "$1" in
+        ru)
+            L_ERR_DOMAIN_REQ="требует аргумент (домен)."
+            L_ERR_PORT_REQ="требует аргумент (порт)."
+            L_ERR_PORT_NUM="Порт должен быть числом."
+            L_ERR_PORT_RANGE="Порт должен быть от 1 до 65535."
+            L_ERR_SECRET_REQ="требует аргумент (секрет)."
+            L_ERR_SECRET_HEX="Секрет должен содержать только HEX символы."
+            L_ERR_SECRET_LEN="Секрет должен состоять ровно из 32 символов."
+            L_ERR_ADTAG_REQ="требует аргумент (ad_tag)."
+            L_ERR_UNKNOWN_OPT="Неизвестная опция:"
+            L_WARN_EXTRA_ARG="Игнорируется лишний аргумент:"
+            L_ERR_REQ_ARG="требует аргумент (1, 2, en или ru)."
+            L_ERR_EMPTY_VAR="не может быть пустым."
+            L_ERR_INV_VER="Недопустимые символы в версии."
+            L_ERR_INV_BIN="Недопустимые символы в BIN_NAME."
+            L_ERR_ROOT="Для работы скрипта требуются права root или sudo."
+            L_ERR_SUDO_TTY="sudo требует пароль, но терминал (TTY) не обнаружен."
+            L_ERR_DIR_CHECK="Ошибка: конфиг является директорией."
+            L_ERR_CMD_NOT_FOUND="Необходимая команда не найдена:"
+            L_ERR_NO_DL_TOOL="Не установлен curl или wget."
+            L_ERR_NO_CP_TOOL="Необходима утилита cp или install."
+            L_WARN_NO_NET_TOOL="Утилиты сети не найдены. Проверка порта пропущена."
+            L_INFO_PORT_IGNORE="Порт занят текущим процессом телеметрии. Игнорируем."
+            L_ERR_PORT_IN_USE="Порт уже занят другим процессом:"
+            L_ERR_PORT_FREE="Освободите порт или укажите другой и попробуйте снова."
+            L_ERR_UNSUP_ARCH="Неподдерживаемая архитектура:"
+            L_ERR_CREATE_GRP="Не удалось создать группу"
+            L_ERR_CREATE_USR="Не удалось создать пользователя"
+            L_ERR_MKDIR="Не удалось создать директории"
+            L_ERR_INSTALL_DIR="не является директорией."
+            L_ERR_BIN_INSTALL="Не удалось установить бинарный файл"
+            L_ERR_BIN_COPY="Не удалось скопировать бинарный файл"
+            L_ERR_BIN_EXEC="Бинарный файл не исполняемый."
+            L_ERR_GEN_SEC="Не удалось сгенерировать секрет."
+            L_INFO_CONF_EXISTS="Конфиг уже существует. Обновление параметров..."
+            L_INFO_UPD_PORT="Обновлен порт:"
+            L_INFO_UPD_SEC="Обновлен секрет для пользователя 'hello'"
+            L_INFO_UPD_DOM="Обновлен tls_domain:"
+            L_INFO_UPD_TAG="Обновлен ad_tag"
+            L_ERR_CONF_INST="Не удалось установить конфиг"
+            L_INFO_CONF_OK="Конфиг успешно создан."
+            L_INFO_CONF_SEC="Настроен секрет для пользователя 'hello':"
+            L_WARN_SVC_FAIL="Не удалось запустить службу"
+            L_INFO_MANUAL_START="Менеджер служб не найден. Запустите вручную:"
+            L_INFO_UNINST_START="Начинается удаление"
+            L_U_STAGE_1=">>> Этап 1: Остановка служб"
+            L_U_STAGE_2=">>> Этап 2: Удаление конфигурации службы"
+            L_U_STAGE_3=">>> Этап 3: Завершение процессов пользователя"
+            L_U_STAGE_4=">>> Этап 4: Удаление бинарного файла"
+            L_U_STAGE_5=">>> Этап 5: Полная очистка (конфиг, данные, пользователь)"
+            L_INFO_KEEP_CONF="Примечание: Конфигурация сохранена. Используйте 'purge' для очистки."
+            L_INFO_I_START="Начинается установка"
+            L_I_STAGE_1=">>> Этап 1: Проверка окружения и зависимостей"
+            L_I_STAGE_2=">>> Этап 2: Интерактивная настройка"
+            L_I_PROMPT_DOM="\nПожалуйста, укажите домен TLS\nНажмите Enter, чтобы оставить по умолчанию [%s]: "
+            L_I_PROMPT_PORT="\nПожалуйста, укажите порт сервера\nНажмите Enter, чтобы оставить по умолчанию [%s]: "
+            L_WARN_NO_TTY="Интерактивный режим недоступен (нет TTY). Используется:"
+            L_I_STAGE_3=">>> Этап 3: Загрузка архива"
+            L_ERR_TMP_DIR="Не удалось создать временную директорию"
+            L_ERR_TMP_INV="Временная директория недействительна"
+            L_INFO_FALLBACK="Сборка x86_64-v3 не найдена, откат к стандартной x86_64..."
+            L_ERR_DL_FAIL="Ошибка загрузки архива"
+            L_I_STAGE_4=">>> Этап 4: Распаковка архива"
+            L_ERR_EXTRACT="Ошибка распаковки архива."
+            L_ERR_BIN_NOT_FOUND="Бинарный файл не найден в архиве"
+            L_I_STAGE_5=">>> Этап 5: Настройка окружения (Юзер, Группа, Папки)"
+            L_I_STAGE_6=">>> Этап 6: Установка бинарного файла"
+            L_I_STAGE_7=">>> Этап 7: Генерация/Обновление конфигурации"
+            L_I_STAGE_8=">>> Этап 8: Установка и запуск службы"
+            L_OUT_WARN_H="УСТАНОВКА ЗАВЕРШЕНА С ПРЕДУПРЕЖДЕНИЯМИ"
+            L_OUT_WARN_D="Служба установлена, но не запустилась.\nПожалуйста, проверьте логи.\n"
+            L_OUT_SUCC_H="УСТАНОВКА УСПЕШНО ЗАВЕРШЕНА"
+            L_OUT_UNINST_H="УДАЛЕНИЕ ЗАВЕРШЕНО"
+            L_OUT_LINK="Ваша ссылка для подключения к Telegram Proxy:\n"
+            L_ERR_INCORR_ROOT_LOGIN="Используйте 'su -' или 'sudo -i' для входа под пользователем root"
+            L_OUT_LOGS="Чтобы посмотреть логи (в случае проблем), используйте команду:"
+            ;;
+        *)
+            L_ERR_DOMAIN_REQ="requires a domain argument."
+            L_ERR_PORT_REQ="requires a port argument."
+            L_ERR_PORT_NUM="Port must be a valid number."
+            L_ERR_PORT_RANGE="Port must be between 1 and 65535."
+            L_ERR_SECRET_REQ="requires a secret argument."
+            L_ERR_SECRET_HEX="Secret must contain only hex characters."
+            L_ERR_SECRET_LEN="Secret must be exactly 32 chars."
+            L_ERR_ADTAG_REQ="requires an ad_tag argument."
+            L_ERR_UNKNOWN_OPT="Unknown option:"
+            L_WARN_EXTRA_ARG="Ignoring extra argument:"
+            L_ERR_REQ_ARG="requires an argument (1, 2, en, ru)."
+            L_ERR_EMPTY_VAR="cannot be empty."
+            L_ERR_INV_VER="Invalid characters in version."
+            L_ERR_INV_BIN="Invalid characters in BIN_NAME."
+            L_ERR_ROOT="This script requires root or sudo."
+            L_ERR_SUDO_TTY="sudo requires a password, but no TTY detected."
+            L_ERR_DIR_CHECK="Safety check failed: Config is a directory."
+            L_ERR_CMD_NOT_FOUND="Required command not found:"
+            L_ERR_NO_DL_TOOL="Neither curl nor wget is installed."
+            L_ERR_NO_CP_TOOL="Need cp or install."
+            L_WARN_NO_NET_TOOL="Network tools not found. Skipping port check."
+            L_INFO_PORT_IGNORE="Port is in use by telemt. Ignoring as it will be restarted."
+            L_ERR_PORT_IN_USE="Port is already in use by another process:"
+            L_ERR_PORT_FREE="Please free the port or change it and try again."
+            L_ERR_UNSUP_ARCH="Unsupported architecture:"
+            L_ERR_CREATE_GRP="Cannot create group"
+            L_ERR_CREATE_USR="Cannot create user"
+            L_ERR_MKDIR="Failed to create directories"
+            L_ERR_INSTALL_DIR="is not a directory."
+            L_ERR_BIN_INSTALL="Failed to install binary"
+            L_ERR_BIN_COPY="Failed to copy binary"
+            L_ERR_BIN_EXEC="Binary not executable."
+            L_ERR_GEN_SEC="Failed to generate secret."
+            L_INFO_CONF_EXISTS="Config already exists. Updating parameters..."
+            L_INFO_UPD_PORT="Updated port:"
+            L_INFO_UPD_SEC="Updated secret for user 'hello'"
+            L_INFO_UPD_DOM="Updated tls_domain:"
+            L_INFO_UPD_TAG="Updated ad_tag"
+            L_ERR_CONF_INST="Failed to install config"
+            L_INFO_CONF_OK="Config created successfully."
+            L_INFO_CONF_SEC="Configured secret for user 'hello':"
+            L_WARN_SVC_FAIL="Failed to start service"
+            L_INFO_MANUAL_START="Service manager not found. Start manually:"
+            L_INFO_UNINST_START="Starting uninstallation of"
+            L_U_STAGE_1=">>> Stage 1: Stopping services"
+            L_U_STAGE_2=">>> Stage 2: Removing service configuration"
+            L_U_STAGE_3=">>> Stage 3: Terminating user processes"
+            L_U_STAGE_4=">>> Stage 4: Removing binary"
+            L_U_STAGE_5=">>> Stage 5: Purging configuration, data, and user"
+            L_INFO_KEEP_CONF="Note: Configuration kept. Run with 'purge' to remove completely."
+            L_INFO_I_START="Starting installation of"
+            L_I_STAGE_1=">>> Stage 1: Verifying environment and dependencies"
+            L_I_STAGE_2=">>> Stage 2: Interactive Setup"
+            L_I_PROMPT_DOM="\nPlease specify the TLS Domain\nPress Enter to keep default [%s]: "
+            L_I_PROMPT_PORT="\nPlease specify the Server Port\nPress Enter to keep default [%s]: "
+            L_WARN_NO_TTY="Interactive mode unavailable (no TTY). Using:"
+            L_I_STAGE_3=">>> Stage 3: Downloading archive"
+            L_ERR_TMP_DIR="Temp directory creation failed"
+            L_ERR_TMP_INV="Temp directory is invalid or was not created"
+            L_INFO_FALLBACK="x86_64-v3 build not found, falling back to standard x86_64..."
+            L_ERR_DL_FAIL="Download failed"
+            L_I_STAGE_4=">>> Stage 4: Extracting archive"
+            L_ERR_EXTRACT="Extraction failed."
+            L_ERR_BIN_NOT_FOUND="Binary not found in archive"
+            L_I_STAGE_5=">>> Stage 5: Setting up environment (User, Group, Directories)"
+            L_I_STAGE_6=">>> Stage 6: Installing binary"
+            L_I_STAGE_7=">>> Stage 7: Generating/Updating configuration"
+            L_I_STAGE_8=">>> Stage 8: Installing and starting service"
+            L_OUT_WARN_H="INSTALLATION COMPLETED WITH WARNINGS"
+            L_OUT_WARN_D="The service was installed but failed to start.\nPlease check the logs to determine the issue.\n"
+            L_OUT_SUCC_H="INSTALLATION SUCCESS"
+            L_OUT_UNINST_H="UNINSTALLATION COMPLETE"
+            L_OUT_LINK="Your Telegram Proxy connection link:\n"
+            L_ERR_INCORR_ROOT_LOGIN="Use 'su -' or 'sudo -i' to login under root"
+            L_OUT_LOGS="To view logs (in case of issues), use the following command:"
+            ;;
+    esac
+}
+
+set_language "$LANG_CHOICE"
 
 while [ $# -gt 0 ]; do
     case "$1" in
         -h|--help) ACTION="help"; shift ;;
+        -l|--lang)
+            if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                printf '[ERROR] %s %s\n' "$1" "$L_ERR_REQ_ARG" >&2; exit 1
+            fi
+            case "$2" in
+                ru|2) LANG_CHOICE="ru"; set_language "$LANG_CHOICE"; LANG_PROVIDED=1 ;;
+                en|1) LANG_CHOICE="en"; set_language "$LANG_CHOICE"; LANG_PROVIDED=1 ;;
+                *) printf '[ERROR] %s %s\n' "$1" "$L_ERR_REQ_ARG" >&2; exit 1 ;;
+            esac
+            shift 2 ;;
         -d|--domain)
             if [ "$#" -lt 2 ] || [ -z "$2" ]; then
-                printf '[ERROR] %s requires a domain argument.\n' "$1" >&2
-                exit 1
+                printf '[ERROR] %s %s\n' "$1" "$L_ERR_DOMAIN_REQ" >&2; exit 1
             fi
-            TLS_DOMAIN="$2"
-            shift 2 ;;
+            TLS_DOMAIN="$2"; DOMAIN_PROVIDED=1; shift 2 ;;
+        -p|--port)
+            if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                printf '[ERROR] %s %s\n' "$1" "$L_ERR_PORT_REQ" >&2; exit 1
+            fi
+            case "$2" in
+                *[!0-9]*) printf '[ERROR] %s\n' "$L_ERR_PORT_NUM" >&2; exit 1 ;;
+            esac
+            port_num="$(printf '%s\n' "$2" | sed 's/^0*//')"
+            [ -z "$port_num" ] && port_num="0"
+            if [ "${#port_num}" -gt 5 ] || [ "$port_num" -lt 1 ] || [ "$port_num" -gt 65535 ]; then
+                printf '[ERROR] %s\n' "$L_ERR_PORT_RANGE" >&2; exit 1
+            fi
+            SERVER_PORT="$port_num"; PORT_PROVIDED=1; shift 2 ;;
+        -s|--secret)
+            if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                printf '[ERROR] %s %s\n' "$1" "$L_ERR_SECRET_REQ" >&2; exit 1
+            fi
+            case "$2" in
+                *[!0-9a-fA-F]*) printf '[ERROR] %s\n' "$L_ERR_SECRET_HEX" >&2; exit 1 ;;
+            esac
+            if [ "${#2}" -ne 32 ]; then
+                printf '[ERROR] %s\n' "$L_ERR_SECRET_LEN" >&2; exit 1
+            fi
+            USER_SECRET="$2"; SECRET_PROVIDED=1; shift 2 ;;
+        -a|--ad-tag|--ad_tag)
+            if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                printf '[ERROR] %s %s\n' "$1" "$L_ERR_ADTAG_REQ" >&2; exit 1
+            fi
+            AD_TAG="$2"; AD_TAG_PROVIDED=1; shift 2 ;;
         uninstall|--uninstall)
             if [ "$ACTION" != "purge" ]; then ACTION="uninstall"; fi
             shift ;;
         purge|--purge) ACTION="purge"; shift ;;
         install|--install) ACTION="install"; shift ;;
-        -*) printf '[ERROR] Unknown option: %s\n' "$1" >&2; exit 1 ;;
+        -*) printf '[ERROR] %s %s\n' "$L_ERR_UNKNOWN_OPT" "$1" >&2; exit 1 ;;
         *)
             if [ "$ACTION" = "install" ]; then TARGET_VERSION="$1"
-            else printf '[WARNING] Ignoring extra argument: %s\n' "$1" >&2; fi
+            else printf '[WARNING] %s %s\n' "$L_WARN_EXTRA_ARG" "$1" >&2; fi
             shift ;;
     esac
 done
 
+if [ "$ACTION" != "help" ] && [ "$LANG_PROVIDED" -eq 0 ]; then
+    if [ -t 0 ] || [ -c /dev/tty ]; then
+        printf "\nSelect language / Выберите язык:\n"
+        printf "  1) English (default)\n"
+        printf "  2) Русский\n"
+        printf "Your choice / Ваш выбор [1/2]: "
+        read -r input_lang </dev/tty || input_lang=""
+        case "$input_lang" in
+            2) LANG_CHOICE="ru" ;;
+            *) LANG_CHOICE="en" ;;
+        esac
+    else
+        LANG_CHOICE="en"
+    fi
+    set_language "$LANG_CHOICE"
+fi
+
 say() {
     if [ "$#" -eq 0 ] || [ -z "${1:-}" ]; then
         printf '\n'
     else
-        printf '[INFO] %s\n' "$*"
+        case "$*" in
+            \[*\]*) printf '%s\n' "$*" ;;
+            *) printf '[INFO] %s\n' "$*" ;;
+        esac
     fi
 }
 die() { printf '[ERROR] %s\n' "$*" >&2; exit 1; }
@@ -59,12 +289,33 @@ cleanup() {
 trap cleanup EXIT INT TERM
 
 show_help() {
-    say "Usage: $0 [ <version> | install | uninstall | purge ] [ -d <domain> ] [ --help ]"
-    say "  <version>    Install specific version (e.g. 3.3.15, default: latest)"
-    say "  install      Install the latest version"
-    say "  uninstall    Remove the binary and service (keeps config and user)"
-    say "  purge        Remove everything including configuration, data, and user"
-    say "  -d, --domain Set TLS domain (default: petrovich.ru)"
+    if [ "$LANG_CHOICE" = "ru" ]; then
+        say "Использование: $0 [ <версия> | install | uninstall | purge ] [ опции ]"
+        say "  <версия>     Установить конкретную версию (например, 3.3.15, по умолчанию: latest)"
+        say "  install      Установить последнюю версию"
+        say "  uninstall    Удалить бинарный файл и службу"
+        say "  purge        Полностью удалить вместе с конфигурацией, данными и пользователем"
+        say ""
+        say "Опции:"
+        say "  -d, --domain Указать домен TLS (по умолчанию: petrovich.ru)"
+        say "  -p, --port   Указать порт сервера (по умолчанию: 443)"
+        say "  -s, --secret Указать секрет пользователя (32 hex символа)"
+        say "  -a, --ad-tag Указать ad_tag"
+        say "  -l, --lang   Выбрать язык вывода (1/en или 2/ru)"
+    else
+        say "Usage: $0 [ <version> | install | uninstall | purge ] [ options ]"
+        say "  <version>    Install specific version (e.g. 3.3.15, default: latest)"
+        say "  install      Install the latest version"
+        say "  uninstall    Remove the binary and service"
+        say "  purge        Remove everything including configuration, data, and user"
+        say ""
+        say "Options:"
+        say "  -d, --domain Set TLS domain (default: petrovich.ru)"
+        say "  -p, --port   Set server port (default: 443)"
+        say "  -s, --secret Set specific user secret (32 hex characters)"
+        say "  -a, --ad-tag Set ad_tag"
+        say "  -l, --lang   Set output language (1/en or 2/ru)"
+    fi
     exit 0
 }
 
@@ -81,13 +332,13 @@ get_realpath() {
     path_in="$1"
     case "$path_in" in /*) ;; *) path_in="$(pwd)/$path_in" ;; esac
 
-    if command -v realpath >/dev/null 2>&1; then 
+    if command -v realpath >/dev/null 2>&1; then
         if realpath_out="$(realpath -m "$path_in" 2>/dev/null)"; then
             printf '%s\n' "$realpath_out"
             return
         fi
     fi
-    
+
     if command -v readlink >/dev/null 2>&1; then
         resolved_path="$(readlink -f "$path_in" 2>/dev/null || true)"
         if [ -n "$resolved_path" ]; then
@@ -120,18 +371,22 @@ get_svc_mgr() {
     else echo "none"; fi
 }
 
+is_config_exists() {
+    if [ -n "$SUDO" ]; then
+        $SUDO sh -c '[ -f "$1" ]' _ "$CONFIG_FILE"
+    else
+        [ -f "$CONFIG_FILE" ]
+    fi
+}
+
 verify_common() {
-    [ -n "$BIN_NAME" ] || die "BIN_NAME cannot be empty."
-    [ -n "$INSTALL_DIR" ] || die "INSTALL_DIR cannot be empty."
-    [ -n "$CONFIG_DIR" ] || die "CONFIG_DIR cannot be empty."
-    [ -n "$CONFIG_FILE" ] || die "CONFIG_FILE cannot be empty."
+    [ -n "$BIN_NAME" ] || die "BIN_NAME $L_ERR_EMPTY_VAR"
+    [ -n "$INSTALL_DIR" ] || die "INSTALL_DIR $L_ERR_EMPTY_VAR"
+    [ -n "$CONFIG_DIR" ] || die "CONFIG_DIR $L_ERR_EMPTY_VAR"
+    [ -n "$CONFIG_FILE" ] || die "CONFIG_FILE $L_ERR_EMPTY_VAR"
 
-    case "${INSTALL_DIR}${CONFIG_DIR}${WORK_DIR}${CONFIG_FILE}" in
-        *[!a-zA-Z0-9_./-]*) die "Invalid characters in paths. Only alphanumeric, _, ., -, and / allowed." ;;
-    esac
-
-    case "$TARGET_VERSION" in *[!a-zA-Z0-9_.-]*) die "Invalid characters in version." ;; esac
-    case "$BIN_NAME" in *[!a-zA-Z0-9_-]*) die "Invalid characters in BIN_NAME." ;; esac
+    case "$TARGET_VERSION" in *[!a-zA-Z0-9_.-]*) die "$L_ERR_INV_VER" ;; esac
+    case "$BIN_NAME" in *[!a-zA-Z0-9_-]*) die "$L_ERR_INV_BIN" ;; esac
 
     INSTALL_DIR="$(get_realpath "$INSTALL_DIR")"
     CONFIG_DIR="$(get_realpath "$CONFIG_DIR")"
@@ -144,59 +399,75 @@ verify_common() {
 
     if [ "$(id -u)" -eq 0 ]; then
         SUDO=""
+        if [ "${USER:-}" != "root" ] && [ "${LOGNAME:-}" != "root" ]; then
+            die "$L_ERR_INCORR_ROOT_LOGIN"
+        fi
     else
-        command -v sudo >/dev/null 2>&1 || die "This script requires root or sudo. Neither found."
+        command -v sudo >/dev/null 2>&1 || die "$L_ERR_ROOT"
         SUDO="sudo"
         if ! sudo -n true 2>/dev/null; then
             if ! [ -t 0 ]; then
-                die "sudo requires a password, but no TTY detected. Aborting to prevent hang."
+                die "$L_ERR_SUDO_TTY"
             fi
         fi
     fi
 
     if [ -n "$SUDO" ]; then
         if $SUDO sh -c '[ -d "$1" ]' _ "$CONFIG_FILE"; then
-            die "Safety check failed: CONFIG_FILE '$CONFIG_FILE' is a directory."
+            die "$L_ERR_DIR_CHECK"
         fi
     elif [ -d "$CONFIG_FILE" ]; then
-        die "Safety check failed: CONFIG_FILE '$CONFIG_FILE' is a directory."
+        die "$L_ERR_DIR_CHECK"
     fi
 
-    for path in "$CONFIG_DIR" "$CONFIG_PARENT_DIR" "$WORK_DIR"; do
-        check_path="$(get_realpath "$path")"
-        case "$check_path" in
-            /|/bin|/sbin|/usr|/usr/bin|/usr/sbin|/usr/local|/usr/local/bin|/usr/local/sbin|/usr/local/etc|/usr/local/share|/etc|/var|/var/lib|/var/log|/var/run|/home|/root|/tmp|/lib|/lib64|/opt|/run|/boot|/dev|/sys|/proc)
-                die "Safety check failed: '$path' (resolved to '$check_path') is a critical system directory." ;;
-        esac
-    done
-
-    check_install_dir="$(get_realpath "$INSTALL_DIR")"
-    case "$check_install_dir" in
-        /|/etc|/var|/home|/root|/tmp|/usr|/usr/local|/opt|/boot|/dev|/sys|/proc|/run)
-            die "Safety check failed: INSTALL_DIR '$INSTALL_DIR' is a critical system directory." ;;
-    esac
-
-    for cmd in id uname grep find rm chown chmod mv mktemp mkdir tr dd sed ps head sleep cat tar gzip rmdir; do
-        command -v "$cmd" >/dev/null 2>&1 || die "Required command not found: $cmd"
+    for cmd in id uname awk grep find rm chown chmod mv mktemp mkdir tr dd sed ps head sleep cat tar gzip; do
+        command -v "$cmd" >/dev/null 2>&1 || die "$L_ERR_CMD_NOT_FOUND $cmd"
     done
 }
 
 verify_install_deps() {
-    command -v curl >/dev/null 2>&1 || command -v wget >/dev/null 2>&1 || die "Neither curl nor wget is installed."
-    command -v cp >/dev/null 2>&1 || command -v install >/dev/null 2>&1 || die "Need cp or install"
+    command -v curl >/dev/null 2>&1 || command -v wget >/dev/null 2>&1 || die "$L_ERR_NO_DL_TOOL"
+    command -v cp >/dev/null 2>&1 || command -v install >/dev/null 2>&1 || die "$L_ERR_NO_CP_TOOL"
 
     if ! command -v setcap >/dev/null 2>&1; then
         if command -v apk >/dev/null 2>&1; then
-            $SUDO apk add --no-cache libcap-utils >/dev/null 2>&1 || $SUDO apk add --no-cache libcap >/dev/null 2>&1 || true
+            $SUDO apk add --no-cache libcap-utils libcap >/dev/null 2>&1 || true
         elif command -v apt-get >/dev/null 2>&1; then
-            $SUDO apt-get update -q >/dev/null 2>&1 || true
-            $SUDO apt-get install -y -q libcap2-bin >/dev/null 2>&1 || true
+            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y -q libcap2-bin >/dev/null 2>&1 || {
+                $SUDO env DEBIAN_FRONTEND=noninteractive apt-get update -q >/dev/null 2>&1 || true
+                $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y -q libcap2-bin >/dev/null 2>&1 || true
+            }
         elif command -v dnf >/dev/null 2>&1; then $SUDO dnf install -y -q libcap >/dev/null 2>&1 || true
         elif command -v yum >/dev/null 2>&1; then $SUDO yum install -y -q libcap >/dev/null 2>&1 || true
         fi
     fi
 }
 
+check_port_availability() {
+    port_info=""
+
+    if command -v ss >/dev/null 2>&1; then
+        port_info=$($SUDO ss -tulnp 2>/dev/null | grep -E ":${SERVER_PORT}([[:space:]]|$)" || true)
+    elif command -v netstat >/dev/null 2>&1; then
+        port_info=$($SUDO netstat -tulnp 2>/dev/null | grep -E ":${SERVER_PORT}([[:space:]]|$)" || true)
+    elif command -v lsof >/dev/null 2>&1; then
+        port_info=$($SUDO lsof -i :${SERVER_PORT} 2>/dev/null | grep LISTEN || true)
+    else
+        say "[WARNING] $L_WARN_NO_NET_TOOL"
+        return 0
+    fi
+
+    if [ -n "$port_info" ]; then
+        if printf '%s\n' "$port_info" | grep -q "${BIN_NAME}"; then
+            say "  -> $L_INFO_PORT_IGNORE"
+        else
+            say "[ERROR] $L_ERR_PORT_IN_USE $SERVER_PORT:"
+            printf '  %s\n' "$port_info"
+            die "$L_ERR_PORT_FREE"
+        fi
+    fi
+}
+
 detect_arch() {
     sys_arch="$(uname -m)"
     case "$sys_arch" in
@@ -208,7 +479,7 @@ detect_arch() {
             fi
             ;;
         aarch64|arm64) echo "aarch64" ;;
-        *) die "Unsupported architecture: $sys_arch" ;;
+        *) die "$L_ERR_UNSUP_ARCH $sys_arch" ;;
     esac
 }
 
@@ -232,7 +503,7 @@ ensure_user_group() {
     if ! check_os_entity group telemt; then
         if command -v groupadd >/dev/null 2>&1; then $SUDO groupadd -r telemt
         elif command -v addgroup >/dev/null 2>&1; then $SUDO addgroup -S telemt
-        else die "Cannot create group"; fi
+        else die "$L_ERR_CREATE_GRP" ; fi
     fi
 
     if ! check_os_entity passwd telemt; then
@@ -244,16 +515,16 @@ ensure_user_group() {
             else
                 $SUDO adduser --system --home "$WORK_DIR" --shell "$nologin_bin" --no-create-home --ingroup telemt --disabled-password telemt
             fi
-        else die "Cannot create user"; fi
+        else die "$L_ERR_CREATE_USR"; fi
     fi
 }
 
 setup_dirs() {
-    $SUDO mkdir -p "$WORK_DIR" "$CONFIG_DIR" "$CONFIG_PARENT_DIR" || die "Failed to create directories"
-    
+    $SUDO mkdir -p "$WORK_DIR" "$CONFIG_DIR" "$CONFIG_PARENT_DIR" || die "$L_ERR_MKDIR"
+
     $SUDO chown telemt:telemt "$WORK_DIR" && $SUDO chmod 750 "$WORK_DIR"
-    $SUDO chown root:telemt "$CONFIG_DIR" && $SUDO chmod 750 "$CONFIG_DIR"
-    
+    $SUDO chown telemt:telemt "$CONFIG_DIR" && $SUDO chmod 750 "$CONFIG_DIR"
+
     if [ "$CONFIG_PARENT_DIR" != "$CONFIG_DIR" ] && [ "$CONFIG_PARENT_DIR" != "." ] && [ "$CONFIG_PARENT_DIR" != "/" ]; then
         $SUDO chown root:telemt "$CONFIG_PARENT_DIR" && $SUDO chmod 750 "$CONFIG_PARENT_DIR"
     fi
@@ -261,9 +532,9 @@ setup_dirs() {
 
 stop_service() {
     svc="$(get_svc_mgr)"
-    if [ "$svc" = "systemd" ] && systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then
+    if [ "$svc" = "systemd" ] && $SUDO systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then
         $SUDO systemctl stop "$SERVICE_NAME" 2>/dev/null || true
-    elif [ "$svc" = "openrc" ] && rc-service "$SERVICE_NAME" status >/dev/null 2>&1; then
+    elif [ "$svc" = "openrc" ] && $SUDO rc-service "$SERVICE_NAME" status >/dev/null 2>&1; then
         $SUDO rc-service "$SERVICE_NAME" stop 2>/dev/null || true
     fi
 }
@@ -271,21 +542,23 @@ stop_service() {
 install_binary() {
     bin_src="$1"; bin_dst="$2"
     if [ -e "$INSTALL_DIR" ] && [ ! -d "$INSTALL_DIR" ]; then
-        die "'$INSTALL_DIR' is not a directory."
+        die "'$INSTALL_DIR' $L_ERR_INSTALL_DIR"
     fi
 
-    $SUDO mkdir -p "$INSTALL_DIR" || die "Failed to create install directory"
+    $SUDO mkdir -p "$INSTALL_DIR" || die "$L_ERR_MKDIR"
+
+    $SUDO rm -f "$bin_dst" 2>/dev/null || true
+
     if command -v install >/dev/null 2>&1; then
-        $SUDO install -m 0755 "$bin_src" "$bin_dst" || die "Failed to install binary"
+        $SUDO install -m 0755 "$bin_src" "$bin_dst" || die "$L_ERR_BIN_INSTALL"
     else
-        $SUDO rm -f "$bin_dst" 2>/dev/null || true
-        $SUDO cp "$bin_src" "$bin_dst" && $SUDO chmod 0755 "$bin_dst" || die "Failed to copy binary"
+        $SUDO cp "$bin_src" "$bin_dst" && $SUDO chmod 0755 "$bin_dst" || die "$L_ERR_BIN_COPY"
     fi
 
-    $SUDO sh -c '[ -x "$1" ]' _ "$bin_dst" || die "Binary not executable: $bin_dst"
+    $SUDO sh -c '[ -x "$1" ]' _ "$bin_dst" || die "$L_ERR_BIN_EXEC $bin_dst"
 
     if command -v setcap >/dev/null 2>&1; then
-        $SUDO setcap cap_net_bind_service=+ep "$bin_dst" 2>/dev/null || true
+        $SUDO setcap cap_net_bind_service,cap_net_admin=+ep "$bin_dst" 2>/dev/null || true
     fi
 }
 
@@ -301,11 +574,20 @@ generate_secret() {
 }
 
 generate_config_content() {
+    conf_secret="$1"
+    conf_tag="$2"
     escaped_tls_domain="$(printf '%s\n' "$TLS_DOMAIN" | tr -d '[:cntrl:]' | sed 's/\\/\\\\/g; s/"/\\"/g')"
 
     cat <<EOF
 [general]
-use_middle_proxy = false
+use_middle_proxy = true
+EOF
+
+    if [ -n "$conf_tag" ]; then
+        echo "ad_tag = \"${conf_tag}\""
+    fi
+
+    cat <<EOF
 
 [general.modes]
 classic = false
@@ -313,7 +595,7 @@ secure = false
 tls = true
 
 [server]
-port = 443
+port = ${SERVER_PORT}
 
 [server.api]
 enabled = true
@@ -324,28 +606,65 @@ whitelist = ["127.0.0.1/32"]
 tls_domain = "${escaped_tls_domain}"
 
 [access.users]
-hello = "$1"
+hello = "${conf_secret}"
 EOF
 }
 
 install_config() {
-    if [ -n "$SUDO" ]; then
-        if $SUDO sh -c '[ -f "$1" ]' _ "$CONFIG_FILE"; then
-            say "  -> Config already exists at $CONFIG_FILE. Skipping creation."
-            return 0
-        fi
-    elif [ -f "$CONFIG_FILE" ]; then
-        say "  -> Config already exists at $CONFIG_FILE. Skipping creation."
+    if is_config_exists; then
+        say "  -> $L_INFO_CONF_EXISTS"
+
+        tmp_conf="${TEMP_DIR}/config.tmp"
+        $SUDO cat "$CONFIG_FILE" > "$tmp_conf"
+
+        escaped_domain="$(printf '%s\n' "$TLS_DOMAIN" | tr -d '[:cntrl:]' | sed 's/\\/\\\\/g; s/"/\\"/g')"
+
+        awk -v port="$SERVER_PORT" -v secret="$USER_SECRET" -v domain="$escaped_domain" -v ad_tag="$AD_TAG" \
+            -v flag_p="$PORT_PROVIDED" -v flag_s="$SECRET_PROVIDED" -v flag_d="$DOMAIN_PROVIDED" -v flag_a="$AD_TAG_PROVIDED" '
+        BEGIN { ad_tag_handled = 0 }
+
+        flag_p == "1" && /^[ \t]*port[ \t]*=/ { print "port = " port; next }
+        flag_s == "1" && /^[ \t]*hello[ \t]*=/ { print "hello = \"" secret "\""; next }
+        flag_d == "1" && /^[ \t]*tls_domain[ \t]*=/ { print "tls_domain = \"" domain "\""; next }
+
+        flag_a == "1" && /^[ \t]*ad_tag[ \t]*=/ {
+            if (!ad_tag_handled) {
+                print "ad_tag = \"" ad_tag "\"";
+                ad_tag_handled = 1;
+            }
+            next
+        }
+        flag_a == "1" && /^\[general\]/ {
+            print;
+            if (!ad_tag_handled) {
+                print "ad_tag = \"" ad_tag "\"";
+                ad_tag_handled = 1;
+            }
+            next
+        }
+
+        { print }
+        ' "$tmp_conf" > "${tmp_conf}.new" && mv "${tmp_conf}.new" "$tmp_conf"
+
+        [ "$PORT_PROVIDED" -eq 1 ] && say "  -> $L_INFO_UPD_PORT $SERVER_PORT"
+        [ "$SECRET_PROVIDED" -eq 1 ] && say "  -> $L_INFO_UPD_SEC"
+        [ "$DOMAIN_PROVIDED" -eq 1 ] && say "  -> $L_INFO_UPD_DOM $TLS_DOMAIN"
+        [ "$AD_TAG_PROVIDED" -eq 1 ] && say "  -> $L_INFO_UPD_TAG"
+
+        write_root "$CONFIG_FILE" < "$tmp_conf"
+        rm -f "$tmp_conf"
         return 0
     fi
 
-    toml_secret="$(generate_secret)" || die "Failed to generate secret."
+    if [ -z "$USER_SECRET" ]; then
+        USER_SECRET="$(generate_secret)" || die "$L_ERR_GEN_SEC"
+    fi
 
-    generate_config_content "$toml_secret" | write_root "$CONFIG_FILE" || die "Failed to install config"
+    generate_config_content "$USER_SECRET" "$AD_TAG" | write_root "$CONFIG_FILE" || die "$L_ERR_CONF_INST"
     $SUDO chown root:telemt "$CONFIG_FILE" && $SUDO chmod 640 "$CONFIG_FILE"
 
-    say "  -> Config created successfully."
-    say "  -> Generated secret for default user 'hello': $toml_secret"
+    say "  -> $L_INFO_CONF_OK"
+    say "  -> $L_INFO_CONF_SEC $USER_SECRET"
 }
 
 generate_systemd_content() {
@@ -362,9 +681,10 @@ Group=telemt
 WorkingDirectory=$WORK_DIR
 ExecStart="${INSTALL_DIR}/${BIN_NAME}" "${CONFIG_FILE}"
 Restart=on-failure
+RestartSec=5
 LimitNOFILE=65536
-AmbientCapabilities=CAP_NET_BIND_SERVICE
-CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_NET_ADMIN
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE CAP_NET_ADMIN
 
 [Install]
 WantedBy=multi-user.target
@@ -395,9 +715,9 @@ install_service() {
 
         $SUDO systemctl daemon-reload || true
         $SUDO systemctl enable "$SERVICE_NAME" || true
-        
+
         if ! $SUDO systemctl start "$SERVICE_NAME"; then
-            say "[WARNING] Failed to start service"
+            say "[WARNING] $L_WARN_SVC_FAIL"
             SERVICE_START_FAILED=1
         fi
     elif [ "$svc" = "openrc" ]; then
@@ -405,17 +725,17 @@ install_service() {
         $SUDO chown root:root "/etc/init.d/${SERVICE_NAME}" && $SUDO chmod 0755 "/etc/init.d/${SERVICE_NAME}"
 
         $SUDO rc-update add "$SERVICE_NAME" default 2>/dev/null || true
-        
+
         if ! $SUDO rc-service "$SERVICE_NAME" start 2>/dev/null; then
-            say "[WARNING] Failed to start service"
+            say "[WARNING] $L_WARN_SVC_FAIL"
             SERVICE_START_FAILED=1
         fi
     else
         cmd="\"${INSTALL_DIR}/${BIN_NAME}\" \"${CONFIG_FILE}\""
-        if [ -n "$SUDO" ]; then 
-            say "  -> Service manager not found. Start manually: sudo -u telemt $cmd"
-        else 
-            say "  -> Service manager not found. Start manually: su -s /bin/sh telemt -c '$cmd'"
+        if [ -n "$SUDO" ]; then
+            say "  -> $L_INFO_MANUAL_START sudo -u telemt $cmd"
+        else
+            say "  -> $L_INFO_MANUAL_START su -s /bin/sh telemt -c '$cmd'"
         fi
     fi
 }
@@ -429,9 +749,10 @@ kill_user_procs() {
         if command -v pgrep >/dev/null 2>&1; then
             pids="$(pgrep -u telemt 2>/dev/null || true)"
         else
-            pids="$(ps -u telemt -o pid= 2>/dev/null || true)"
+            pids="$(ps -ef 2>/dev/null | awk '$1=="telemt"{print $2}' || true)"
+            [ -z "$pids" ] && pids="$(ps 2>/dev/null | awk '$2=="telemt"{print $1}' || true)"
         fi
-        
+
         if [ -n "$pids" ]; then
             for pid in $pids; do
                 case "$pid" in ''|*[!0-9]*) continue ;; *) $SUDO kill "$pid" 2>/dev/null || true ;; esac
@@ -445,12 +766,12 @@ kill_user_procs() {
 }
 
 uninstall() {
-    say "Starting uninstallation of $BIN_NAME..."
+    say "$L_INFO_UNINST_START $BIN_NAME..."
 
-    say ">>> Stage 1: Stopping services"
+    say "$L_U_STAGE_1"
     stop_service
 
-    say ">>> Stage 2: Removing service configuration"
+    say "$L_U_STAGE_2"
     svc="$(get_svc_mgr)"
     if [ "$svc" = "systemd" ]; then
         $SUDO systemctl disable "$SERVICE_NAME" 2>/dev/null || true
@@ -461,27 +782,30 @@ uninstall() {
         $SUDO rm -f "/etc/init.d/${SERVICE_NAME}"
     fi
 
-    say ">>> Stage 3: Terminating user processes"
+    say "$L_U_STAGE_3"
     kill_user_procs
 
-    say ">>> Stage 4: Removing binary"
+    say "$L_U_STAGE_4"
     $SUDO rm -f "${INSTALL_DIR}/${BIN_NAME}"
 
     if [ "$ACTION" = "purge" ]; then
-        say ">>> Stage 5: Purging configuration, data, and user"
+        say "$L_U_STAGE_5"
         $SUDO rm -rf "$CONFIG_DIR" "$WORK_DIR"
         $SUDO rm -f "$CONFIG_FILE"
-        if [ "$CONFIG_PARENT_DIR" != "$CONFIG_DIR" ] && [ "$CONFIG_PARENT_DIR" != "." ] && [ "$CONFIG_PARENT_DIR" != "/" ]; then
-            $SUDO rmdir "$CONFIG_PARENT_DIR" 2>/dev/null || true
+
+        if check_os_entity passwd telemt; then
+            $SUDO userdel telemt 2>/dev/null || $SUDO deluser telemt 2>/dev/null || true
+        fi
+
+        if check_os_entity group telemt; then
+            $SUDO groupdel telemt 2>/dev/null || $SUDO delgroup telemt 2>/dev/null || true
         fi
-        $SUDO userdel telemt 2>/dev/null || $SUDO deluser telemt 2>/dev/null || true
-        $SUDO groupdel telemt 2>/dev/null || $SUDO delgroup telemt 2>/dev/null || true
     else
-        say "Note: Configuration and user kept. Run with 'purge' to remove completely."
+        say "$L_INFO_KEEP_CONF"
     fi
-    
+
     printf '\n====================================================================\n'
-    printf '                    UNINSTALLATION COMPLETE\n'
+    printf '                    %s\n' "$L_OUT_UNINST_H"
     printf '====================================================================\n\n'
     exit 0
 }
@@ -490,95 +814,163 @@ case "$ACTION" in
     help) show_help ;;
     uninstall|purge) verify_common; uninstall ;;
     install)
-        say "Starting installation of $BIN_NAME (Version: $TARGET_VERSION)"
+        say "$L_INFO_I_START $BIN_NAME (Version: $TARGET_VERSION)"
 
-        say ">>> Stage 1: Verifying environment and dependencies"
-        verify_common; verify_install_deps
+        say "$L_I_STAGE_1"
+        verify_common
+        verify_install_deps
 
-        if [ "$TARGET_VERSION" != "latest" ]; then 
+        if is_config_exists; then
+            ext_port="$($SUDO awk -F'=' '/^[ \t]*port[ \t]*=/ {gsub(/[^0-9]/, "", $2); print $2; exit}' "$CONFIG_FILE" 2>/dev/null || true)"
+            if [ -n "$ext_port" ] && [ "$PORT_PROVIDED" -eq 0 ]; then
+                SERVER_PORT="$ext_port"
+            fi
+
+            ext_secret="$($SUDO awk -F'"' '/^[ \t]*hello[ \t]*=/ {print $2; exit}' "$CONFIG_FILE" 2>/dev/null || true)"
+            if [ -n "$ext_secret" ] && [ "$SECRET_PROVIDED" -eq 0 ]; then
+                USER_SECRET="$ext_secret"
+            fi
+
+            ext_domain="$($SUDO awk -F'"' '/^[ \t]*tls_domain[ \t]*=/ {print $2; exit}' "$CONFIG_FILE" 2>/dev/null || true)"
+            if [ -n "$ext_domain" ] && [ "$DOMAIN_PROVIDED" -eq 0 ]; then
+                TLS_DOMAIN="$ext_domain"
+            fi
+        fi
+
+        if [ "$PORT_PROVIDED" -eq 0 ] || [ "$DOMAIN_PROVIDED" -eq 0 ]; then
+            say "$L_I_STAGE_2"
+        fi
+
+        if [ "$PORT_PROVIDED" -eq 0 ]; then
+            if [ -t 0 ] || [ -c /dev/tty ]; then
+                while true; do
+                    printf "$L_I_PROMPT_PORT" "$SERVER_PORT"
+                    read -r input_port </dev/tty || input_port=""
+                    if [ -z "$input_port" ]; then
+                        break
+                    fi
+                    case "$input_port" in
+                        *[!0-9]*) printf '[ERROR] %s\n' "$L_ERR_PORT_NUM" >&2; continue ;;
+                    esac
+                    port_num="$(printf '%s\n' "$input_port" | sed 's/^0*//')"
+                    [ -z "$port_num" ] && port_num="0"
+                    if [ "${#port_num}" -gt 5 ] || [ "$port_num" -lt 1 ] || [ "$port_num" -gt 65535 ]; then
+                        printf '[ERROR] %s\n' "$L_ERR_PORT_RANGE" >&2; continue
+                    fi
+                    SERVER_PORT="$port_num"
+                    break
+                done
+            else
+                say "[WARNING] $L_WARN_NO_TTY $SERVER_PORT"
+            fi
+            PORT_PROVIDED=1
+        fi
+
+        if [ "$DOMAIN_PROVIDED" -eq 0 ]; then
+            if [ -t 0 ] || [ -c /dev/tty ]; then
+                printf "$L_I_PROMPT_DOM" "$TLS_DOMAIN"
+                read -r input_domain </dev/tty || input_domain=""
+                if [ -n "$input_domain" ]; then
+                    TLS_DOMAIN="$input_domain"
+                fi
+            else
+                say "[WARNING] $L_WARN_NO_TTY $TLS_DOMAIN"
+            fi
+            DOMAIN_PROVIDED=1
+        fi
+
+        check_port_availability
+
+        if [ "$TARGET_VERSION" != "latest" ]; then
             TARGET_VERSION="${TARGET_VERSION#v}"
         fi
-        
+
         ARCH="$(detect_arch)"; LIBC="$(detect_libc)"
         FILE_NAME="${BIN_NAME}-${ARCH}-linux-${LIBC}.tar.gz"
-        
+
         if [ "$TARGET_VERSION" = "latest" ]; then
             DL_URL="https://github.com/${REPO}/releases/latest/download/${FILE_NAME}"
-        else 
+        else
             DL_URL="https://github.com/${REPO}/releases/download/${TARGET_VERSION}/${FILE_NAME}"
         fi
 
-        say ">>> Stage 2: Downloading archive"
-        TEMP_DIR="$(mktemp -d)" || die "Temp directory creation failed"
+        say "$L_I_STAGE_3"
+        TEMP_DIR="$(mktemp -d)" || die "$L_ERR_TMP_DIR"
         if [ -z "$TEMP_DIR" ] || [ ! -d "$TEMP_DIR" ]; then
-            die "Temp directory is invalid or was not created"
+            die "$L_ERR_TMP_INV"
         fi
 
         if ! fetch_file "$DL_URL" "${TEMP_DIR}/${FILE_NAME}"; then
             if [ "$ARCH" = "x86_64-v3" ]; then
-                say "  -> x86_64-v3 build not found, falling back to standard x86_64..."
+                say "  -> $L_INFO_FALLBACK"
                 ARCH="x86_64"
                 FILE_NAME="${BIN_NAME}-${ARCH}-linux-${LIBC}.tar.gz"
                 if [ "$TARGET_VERSION" = "latest" ]; then
                     DL_URL="https://github.com/${REPO}/releases/latest/download/${FILE_NAME}"
-                else 
+                else
                     DL_URL="https://github.com/${REPO}/releases/download/${TARGET_VERSION}/${FILE_NAME}"
                 fi
-                fetch_file "$DL_URL" "${TEMP_DIR}/${FILE_NAME}" || die "Download failed"
+                fetch_file "$DL_URL" "${TEMP_DIR}/${FILE_NAME}" || die "$L_ERR_DL_FAIL"
             else
-                die "Download failed"
+                die "$L_ERR_DL_FAIL"
             fi
         fi
 
-        say ">>> Stage 3: Extracting archive"
+        say "$L_I_STAGE_4"
         if ! gzip -dc "${TEMP_DIR}/${FILE_NAME}" | tar -xf - -C "$TEMP_DIR" 2>/dev/null; then
-            die "Extraction failed (downloaded archive might be invalid or 404)."
+            die "$L_ERR_EXTRACT"
         fi
 
         EXTRACTED_BIN="$(find "$TEMP_DIR" -type f -name "$BIN_NAME" -print 2>/dev/null | head -n 1 || true)"
-        [ -n "$EXTRACTED_BIN" ] || die "Binary '$BIN_NAME' not found in archive"
+        [ -n "$EXTRACTED_BIN" ] || die "$L_ERR_BIN_NOT_FOUND"
 
-        say ">>> Stage 4: Setting up environment (User, Group, Directories)"
+        say "$L_I_STAGE_5"
         ensure_user_group; setup_dirs; stop_service
-        
-        say ">>> Stage 5: Installing binary"
+
+        say "$L_I_STAGE_6"
         install_binary "$EXTRACTED_BIN" "${INSTALL_DIR}/${BIN_NAME}"
-        
-        say ">>> Stage 6: Generating configuration"
+
+        say "$L_I_STAGE_7"
         install_config
-        
-        say ">>> Stage 7: Installing and starting service"
+
+        say "$L_I_STAGE_8"
         install_service
 
         if [ "${SERVICE_START_FAILED:-0}" -eq 1 ]; then
             printf '\n====================================================================\n'
-            printf '               INSTALLATION COMPLETED WITH WARNINGS\n'
+            printf '               %s\n' "$L_OUT_WARN_H"
             printf '====================================================================\n\n'
-            printf 'The service was installed but failed to start automatically.\n'
-            printf 'Please check the logs to determine the issue.\n\n'
+            printf '%b' "$L_OUT_WARN_D"
         else
             printf '\n====================================================================\n'
-            printf '                      INSTALLATION SUCCESS\n'
+            printf '                      %s\n' "$L_OUT_SUCC_H"
             printf '====================================================================\n\n'
         fi
-        
+
+        SERVER_IP=""
+        if command -v curl >/dev/null 2>&1; then SERVER_IP="$(curl -s4 -m 3 ifconfig.me 2>/dev/null || curl -s4 -m 3 api.ipify.org 2>/dev/null || true)"
+        elif command -v wget >/dev/null 2>&1; then SERVER_IP="$(wget -qO- -T 3 ifconfig.me 2>/dev/null || wget -qO- -T 3 api.ipify.org 2>/dev/null || true)"; fi
+        [ -z "$SERVER_IP" ] && SERVER_IP="<YOUR_SERVER_IP>"
+
+        if command -v xxd >/dev/null 2>&1; then HEX_DOMAIN="$(printf '%s' "$TLS_DOMAIN" | xxd -p | tr -d '\n')"
+        elif command -v hexdump >/dev/null 2>&1; then HEX_DOMAIN="$(printf '%s' "$TLS_DOMAIN" | hexdump -v -e '/1 "%02x"')"
+        elif command -v od >/dev/null 2>&1; then HEX_DOMAIN="$(printf '%s' "$TLS_DOMAIN" | od -A n -t x1 | tr -d ' \n')"
+        else HEX_DOMAIN=""; fi
+
+        CLIENT_SECRET="ee${USER_SECRET}${HEX_DOMAIN}"
+
+        printf '%b\n' "$L_OUT_LINK"
+        printf '  tg://proxy?server=%s&port=%s&secret=%s\n\n' "$SERVER_IP" "$SERVER_PORT" "$CLIENT_SECRET"
+
         svc="$(get_svc_mgr)"
         if [ "$svc" = "systemd" ]; then
-            printf 'To check the status of your proxy service, run:\n'
-            printf '  systemctl status %s\n\n' "$SERVICE_NAME"
+            printf '%s\n' "$L_OUT_LOGS"
+            printf '  sudo journalctl -u %s -f\n\n' "$SERVICE_NAME"
         elif [ "$svc" = "openrc" ]; then
-            printf 'To check the status of your proxy service, run:\n'
-            printf '  rc-service %s status\n\n' "$SERVICE_NAME"
+            printf '%s\n' "$L_OUT_LOGS"
+            printf '  sudo tail -f /var/log/messages /var/log/syslog 2>/dev/null | grep -i %s\n\n' "$SERVICE_NAME"
         fi
-        
-        printf 'To get your user connection links (for Telegram), run:\n'
-        if command -v jq >/dev/null 2>&1; then
-            printf '  curl -s http://127.0.0.1:9091/v1/users | jq -r '\''.data[] | "User: \\(.username)\\n\\(.links.tls[0] // empty)\\n"'\''\n'
-        else
-            printf '  curl -s http://127.0.0.1:9091/v1/users\n'
-            printf '  (Tip: Install '\''jq'\'' for a much cleaner output)\n'
-        fi
-        
-        printf '\n====================================================================\n'
+
+        printf '====================================================================\n'
         ;;
 esac

src/api/config_edit.rs

@@ -0,0 +1,387 @@
+//! Config-editing API: read managed sections and apply sparse field patches.
+//! `access.*` is intentionally not editable here (owned by the users API).
+//! `[server]` is only partially editable — see [`EDITABLE_SERVER_FIELDS`].
+
+use serde_json::Value as Json;
+use toml::Value as Toml;
+
+use super::ApiShared;
+use super::config_store::{
+    EDITABLE_SECTIONS, EDITABLE_SERVER_FIELDS, compute_snapshot_revision, is_editable_section,
+    load_candidate_snapshot, load_config_snapshot, render_server_listeners,
+    render_top_level_section, resolve_single_source_owner, upsert_toml_table, write_atomic,
+};
+use super::model::ApiFailure;
+use crate::config::ProxyConfig;
+use crate::config::hot_reload::classify_config_changes;
+use crate::maestro::reload::{ReloadAccepted, ReloadRequest, ReloadSubmitError};
+use crate::maestro::runtime_build::{deferred_process_fields, resolve_reload_config};
+use serde::Serialize;
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+#[derive(Debug, Serialize)]
+pub(super) struct PatchConfigResponse {
+    pub revision: String,
+    pub restart_required: bool,
+    pub runtime_reload_required: bool,
+    pub process_restart_required: bool,
+    pub deferred_process_fields: Vec<String>,
+    pub changed: Vec<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub reload: Option<ReloadAccepted>,
+}
+
+struct PreparedConfigPatch {
+    owner_path: PathBuf,
+    owner_contents: String,
+    desired_config: Arc<ProxyConfig>,
+    response: PatchConfigResponse,
+}
+
+/// Serializes config mutations behind `mutation_lock`, commits them, and records
+/// a runtime event. The route handler calls this shared-state wrapper.
+pub(super) async fn patch_config(
+    patch_json: Json,
+    expected_revision: Option<String>,
+    reload_request: Option<ReloadRequest>,
+    shared: &ApiShared,
+) -> Result<PatchConfigResponse, ApiFailure> {
+    let _guard = shared.mutation_lock.lock().await;
+    let active_config = shared.active_runtime.load_full().config();
+    let mut prepared =
+        prepare_patch_to_path(&shared.config_path, &patch_json, expected_revision).await?;
+    let resolved = resolve_reload_config(&active_config, &prepared.desired_config);
+    prepared.response.runtime_reload_required = resolved.runtime_changed;
+    prepared.response.process_restart_required = !resolved.deferred_process_fields.is_empty();
+    prepared.response.deferred_process_fields = resolved.deferred_process_fields;
+    let reservation = if let Some(request) = reload_request.filter(|_| resolved.runtime_changed) {
+        Some(
+            shared
+                .reload_control
+                .reserve(prepared.response.revision.clone(), request)
+                .await
+                .map_err(reload_submit_failure)?,
+        )
+    } else {
+        None
+    };
+    write_atomic(prepared.owner_path, prepared.owner_contents).await?;
+    if let Some(reservation) = reservation {
+        prepared.response.reload = Some(reservation.enqueue(prepared.desired_config));
+    }
+    let resp = prepared.response;
+    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.
+#[cfg(test)]
+pub(super) async fn apply_patch_to_path(
+    config_path: &Path,
+    patch_json: &Json,
+    expected_revision: Option<String>,
+) -> Result<PatchConfigResponse, ApiFailure> {
+    let prepared = prepare_patch_to_path(config_path, patch_json, expected_revision).await?;
+    write_atomic(prepared.owner_path, prepared.owner_contents).await?;
+    Ok(prepared.response)
+}
+
+async fn prepare_patch_to_path(
+    config_path: &Path,
+    patch_json: &Json,
+    expected_revision: Option<String>,
+) -> Result<PreparedConfigPatch, ApiFailure> {
+    // 1. optimistic concurrency
+    let loaded = load_config_snapshot(config_path, false).await?;
+    let current = compute_snapshot_revision(&loaded);
+    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 / forbidden server fields
+    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, value) in patch_table {
+        if !is_editable_section(key.as_str()) {
+            return Err(ApiFailure::new(
+                hyper::StatusCode::BAD_REQUEST,
+                "section_not_editable",
+                format!("section not editable: {}", key),
+            ));
+        }
+        if key == "server" {
+            validate_server_patch(value)?;
+        }
+    }
+    let touched: Vec<&str> = patch_table
+        .keys()
+        .map(|k| k.as_str())
+        .filter(|k| is_editable_section(k))
+        .collect();
+    if touched.is_empty() {
+        return Err(ApiFailure::bad_request("empty patch: no editable sections"));
+    }
+
+    // 3. Merge against the fully expanded and normalized desired config. The
+    // source owner is resolved separately so included sections stay in their
+    // original file and unrelated source files remain byte-identical.
+    let old_cfg = loaded.config.clone();
+    let mut merged = Toml::try_from(&old_cfg)
+        .map_err(|e| ApiFailure::internal(format!("failed to serialize config: {}", e)))?;
+    deep_merge(&mut merged, &patch_toml);
+
+    let requested_cfg: ProxyConfig = merged
+        .clone()
+        .try_into()
+        .map_err(|e| ApiFailure::bad_request(format!("config does not deserialize: {}", e)))?;
+    requested_cfg
+        .validate()
+        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
+
+    let ownership_targets: Vec<&str> = touched
+        .iter()
+        .map(|section| {
+            if *section == "server" {
+                "server.listeners"
+            } else {
+                *section
+            }
+        })
+        .collect();
+    let owner_path = resolve_single_source_owner(&loaded, config_path, &ownership_targets)?;
+    let mut owner_contents = loaded
+        .source_contents
+        .get(&owner_path)
+        .cloned()
+        .ok_or_else(|| ApiFailure::internal("config source owner is missing from snapshot"))?;
+    for section in &touched {
+        if *section == "server" {
+            let rendered = render_server_listeners(&requested_cfg)?;
+            owner_contents = upsert_toml_table(&owner_contents, "server.listeners", &rendered);
+        } else {
+            let rendered = render_top_level_section(&requested_cfg, section)?;
+            owner_contents = upsert_toml_table(&owner_contents, section, &rendered);
+        }
+    }
+
+    let candidate = load_candidate_snapshot(
+        config_path,
+        &loaded.source_contents,
+        owner_path.clone(),
+        owner_contents.clone(),
+    )
+    .await?;
+    if touched.contains(&"server")
+        && serde_json::to_value(&candidate.config.server.listeners).ok()
+            != serde_json::to_value(&requested_cfg.server.listeners).ok()
+    {
+        return Err(ApiFailure::new(
+            hyper::StatusCode::BAD_REQUEST,
+            "ambiguous_listeners",
+            "server.listeners normalizes to a different effective listener set",
+        ));
+    }
+
+    // 4. classify the validated, normalized candidate.
+    let revision = compute_snapshot_revision(&candidate);
+    let new_cfg = candidate.config;
+    let class = classify_config_changes(&old_cfg, &new_cfg);
+    let deferred_process_fields = deferred_process_fields(&old_cfg, &new_cfg);
+
+    Ok(PreparedConfigPatch {
+        owner_path,
+        owner_contents,
+        desired_config: Arc::new(new_cfg),
+        response: PatchConfigResponse {
+            revision,
+            restart_required: class.restart_required,
+            runtime_reload_required: class.restart_required,
+            process_restart_required: !deferred_process_fields.is_empty(),
+            deferred_process_fields,
+            changed: class.changed,
+            reload: None,
+        },
+    })
+}
+
+fn reload_submit_failure(error: ReloadSubmitError) -> ApiFailure {
+    match error {
+        ReloadSubmitError::InProgress(reload_id) => ApiFailure::new(
+            hyper::StatusCode::CONFLICT,
+            "reload_in_progress",
+            format!("Reload {} is already in progress", reload_id),
+        ),
+        ReloadSubmitError::MaestroUnavailable => ApiFailure::new(
+            hyper::StatusCode::SERVICE_UNAVAILABLE,
+            "maestro_unavailable",
+            "Maestro reload coordinator is unavailable",
+        ),
+    }
+}
+
+/// Return only the editable config sections + current revision.
+pub(super) async fn read_managed_config(config_path: &Path) -> Result<(Toml, String), ApiFailure> {
+    let loaded = load_config_snapshot(config_path, false).await?;
+    let revision = compute_snapshot_revision(&loaded);
+    let parsed = Toml::try_from(&loaded.config)
+        .map_err(|error| ApiFailure::internal(format!("failed to serialize config: {error}")))?;
+
+    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.api` (auth_header) and `network` (per-node
+    // addresses). Mirror the PATCH contract, including the nested server
+    // field-level allowlist.
+    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());
+        }
+    }
+    if let Some(server) = parsed_table.get("server") {
+        if let Some(filtered) = filter_server_for_read(server) {
+            table.insert("server".to_string(), filtered);
+        }
+    }
+
+    Ok((Toml::Table(table), revision))
+}
+
+/// Keep only [`EDITABLE_SERVER_FIELDS`] from a `[server]` table for GET.
+fn filter_server_for_read(server: &Toml) -> Option<Toml> {
+    let Some(src) = server.as_table() else {
+        return None;
+    };
+    let mut out = toml::value::Table::new();
+    for field in EDITABLE_SERVER_FIELDS {
+        if let Some(value) = src.get(*field) {
+            // Skip empty listeners arrays so absent-vs-empty stays consistent
+            // with other optional sections.
+            if *field == "listeners" {
+                if let Some(arr) = value.as_array() {
+                    if arr.is_empty() {
+                        continue;
+                    }
+                }
+            }
+            out.insert((*field).to_string(), value.clone());
+        }
+    }
+    if out.is_empty() {
+        None
+    } else {
+        Some(Toml::Table(out))
+    }
+}
+
+/// Reject any `[server]` patch keys outside [`EDITABLE_SERVER_FIELDS`].
+fn validate_server_patch(server: &Toml) -> Result<(), ApiFailure> {
+    let Some(table) = server.as_table() else {
+        return Err(ApiFailure::new(
+            hyper::StatusCode::BAD_REQUEST,
+            "section_not_editable",
+            "server patch must be a JSON object",
+        ));
+    };
+    if table.is_empty() {
+        return Err(ApiFailure::bad_request(
+            "empty server patch: provide at least one editable field \
+             (currently: listeners)",
+        ));
+    }
+    for key in table.keys() {
+        if !EDITABLE_SERVER_FIELDS.contains(&key.as_str()) {
+            return Err(ApiFailure::new(
+                hyper::StatusCode::BAD_REQUEST,
+                "field_not_editable",
+                format!(
+                    "server.{} is not editable via the config API; allowed server fields: {}",
+                    key,
+                    EDITABLE_SERVER_FIELDS.join(", ")
+                ),
+            ));
+        }
+    }
+    Ok(())
+}
+
+/// 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() {
+                    // TOML has no null value, so sparse object nulls are omitted.
+                    continue;
+                }
+                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)]
+#[path = "config_edit/tests.rs"]
+mod tests;

src/api/config_edit/tests.rs

@@ -0,0 +1,368 @@
+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"));
+    assert_eq!(cens["fake_cert_len"].as_integer(), Some(100));
+}
+
+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.runtime_reload_required);
+    assert!(!resp.process_restart_required);
+    assert!(resp.deferred_process_fields.is_empty());
+    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::current_revision(&path)
+            .await
+            .unwrap()
+    );
+}
+
+#[tokio::test]
+async fn read_managed_config_strips_access() {
+    let (path, _d) = temp_config(
+        "[censorship]\ntls_domain = \"a.com\"\n[access.users]\nbob = \"00000000000000000000000000000000\"\n",
+    );
+    let (value, revision) = read_managed_config(&path).await.unwrap();
+    let table = value.as_table().unwrap();
+    assert!(table.contains_key("censorship"));
+    // Secrets never leave the box through this endpoint.
+    assert!(!table.contains_key("access"));
+    assert_eq!(
+        revision,
+        crate::api::config_store::current_revision(&path)
+            .await
+            .unwrap()
+    );
+}
+
+#[tokio::test]
+async fn read_managed_config_returns_only_editable_sections() {
+    // Full server (api/port) and network must not leak. Listeners-only server
+    // is returned via the nested allowlist (covered in a dedicated test).
+    let (path, _d) = temp_config(concat!(
+        "[censorship]\ntls_domain = \"a\"\n",
+        "[server]\nport = 443\n[server.api]\nauth_header = \"SECRET\"\n",
+        "[network]\nipv4 = true\n",
+        "[access.users]\nbob = \"00000000000000000000000000000000\"\n",
+    ));
+    let (value, _rev) = read_managed_config(&path).await.unwrap();
+    let table = value.as_table().unwrap();
+    assert!(table.contains_key("censorship"));
+    let server = table["server"].as_table().unwrap();
+    assert!(server.contains_key("listeners"));
+    assert!(!server.contains_key("api"));
+    assert!(!server.contains_key("port"));
+    assert!(!table.contains_key("network"));
+    assert!(!table.contains_key("access"));
+}
+
+#[tokio::test]
+async fn read_managed_config_returns_server_listeners_only() {
+    let (path, _d) = temp_config(concat!(
+        "[censorship]\ntls_domain = \"a\"\n",
+        "[server]\nport = 443\n",
+        "[server.api]\nauth_header = \"SECRET\"\n",
+        "[[server.listeners]]\nip = \"0.0.0.0\"\nport = 443\n",
+    ));
+    let (value, _rev) = read_managed_config(&path).await.unwrap();
+    let table = value.as_table().unwrap();
+    let server = table
+        .get("server")
+        .expect("server.listeners present")
+        .as_table()
+        .unwrap();
+    assert!(server.contains_key("listeners"));
+    assert!(!server.contains_key("api"));
+    assert!(!server.contains_key("port"));
+    let listeners = server["listeners"].as_array().unwrap();
+    assert_eq!(listeners.len(), 1);
+    assert_eq!(listeners[0]["port"].as_integer(), Some(443));
+}
+
+#[tokio::test]
+async fn patch_rejects_forbidden_server_fields() {
+    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, "field_not_editable");
+}
+
+#[tokio::test]
+async fn patch_rejects_server_api_field() {
+    let (path, _d) = temp_config("[censorship]\ntls_domain = \"a\"\n");
+    let patch: Json = serde_json::json!({"server": {"api": {"enabled": false}}});
+    let err = apply_patch_to_path(&path, &patch, None).await.unwrap_err();
+    assert_eq!(err.code, "field_not_editable");
+}
+
+#[tokio::test]
+async fn patch_server_listeners_preserves_api() {
+    let (path, _d) = temp_config(concat!(
+        "[censorship]\ntls_domain = \"a\"\n",
+        "[server]\nport = 443\n",
+        "[server.api]\nenabled = true\nauth_header = \"SECRET\"\n",
+        "[[server.listeners]]\nip = \"0.0.0.0\"\nport = 443\n",
+    ));
+    let patch: Json = serde_json::json!({
+        "server": {
+            "listeners": [
+                {"ip": "0.0.0.0", "port": 8443, "client_mss": "92"}
+            ]
+        }
+    });
+    let resp = apply_patch_to_path(&path, &patch, None).await.unwrap();
+    assert!(resp.changed.iter().any(|c| c == "server"));
+    let written = tokio::fs::read_to_string(&path).await.unwrap();
+    let parsed: toml::Value = toml::from_str(&written).unwrap();
+    assert_eq!(
+        parsed["server"]["api"]["auth_header"].as_str(),
+        Some("SECRET"),
+        "{written}"
+    );
+    let listeners = parsed["server"]["listeners"].as_array().unwrap();
+    assert_eq!(listeners.len(), 1, "{written}");
+    assert_eq!(listeners[0]["port"].as_integer(), Some(8443), "{written}");
+    assert_eq!(listeners[0]["client_mss"].as_str(), Some("92"), "{written}");
+}
+
+#[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_writes_the_included_section_owner_only() {
+    let dir = tempfile::tempdir().unwrap();
+    let root = dir.path().join("config.toml");
+    let included = dir.path().join("censorship.toml");
+    let root_body = "include = \"censorship.toml\"\n[server]\nport = 443\n";
+    let included_body = "[censorship]\ntls_domain = \"old.example\"\n";
+    tokio::fs::write(&root, root_body).await.unwrap();
+    tokio::fs::write(&included, included_body).await.unwrap();
+    let patch: Json = serde_json::json!({
+        "censorship": {"tls_domain": "new.example"}
+    });
+
+    let response = apply_patch_to_path(&root, &patch, None).await.unwrap();
+
+    assert_eq!(tokio::fs::read_to_string(&root).await.unwrap(), root_body);
+    let written = tokio::fs::read_to_string(&included).await.unwrap();
+    assert!(written.contains("tls_domain = \"new.example\""));
+    assert_eq!(
+        response.revision,
+        crate::api::config_store::current_revision(&root)
+            .await
+            .unwrap()
+    );
+}
+
+#[tokio::test]
+async fn patch_rejects_multiple_source_owners_without_writing() {
+    let dir = tempfile::tempdir().unwrap();
+    let root = dir.path().join("config.toml");
+    let included = dir.path().join("censorship.toml");
+    let root_body = concat!(
+        "include = \"censorship.toml\"\n",
+        "[general]\nprefer_ipv6 = false\n"
+    );
+    let included_body = "[censorship]\ntls_domain = \"old.example\"\n";
+    tokio::fs::write(&root, root_body).await.unwrap();
+    tokio::fs::write(&included, included_body).await.unwrap();
+    let patch: Json = serde_json::json!({
+        "general": {"prefer_ipv6": true},
+        "censorship": {"tls_domain": "new.example"}
+    });
+
+    let error = apply_patch_to_path(&root, &patch, None).await.unwrap_err();
+
+    assert_eq!(error.code, "config_patch_not_atomic");
+    assert_eq!(tokio::fs::read_to_string(&root).await.unwrap(), root_body);
+    assert_eq!(
+        tokio::fs::read_to_string(&included).await.unwrap(),
+        included_body
+    );
+}
+
+#[tokio::test]
+async fn unavailable_reload_coordinator_is_detected_before_config_write() {
+    let (path, _dir) = temp_config("[censorship]\ntls_domain = \"old.example\"\n");
+    let original = tokio::fs::read_to_string(&path).await.unwrap();
+    let patch: Json = serde_json::json!({
+        "censorship": {"tls_domain": "new.example"}
+    });
+    let prepared = prepare_patch_to_path(&path, &patch, None).await.unwrap();
+    let (control, receiver) = crate::maestro::reload::ReloadControl::channel(1);
+    drop(receiver);
+
+    let error = match control
+        .reserve(prepared.response.revision.clone(), ReloadRequest::default())
+        .await
+    {
+        Ok(_) => panic!("closed reload coordinator must reject the reservation"),
+        Err(error) => error,
+    };
+
+    assert_eq!(error, ReloadSubmitError::MaestroUnavailable);
+    assert_eq!(tokio::fs::read_to_string(&path).await.unwrap(), original);
+}
+
+#[tokio::test]
+async fn failed_config_write_releases_reload_reservation() {
+    let dir = tempfile::tempdir().unwrap();
+    let (control, _receiver) = crate::maestro::reload::ReloadControl::channel(1);
+    let reservation = control
+        .reserve("candidate-revision".to_string(), ReloadRequest::default())
+        .await
+        .unwrap();
+
+    let result = write_atomic(dir.path().to_path_buf(), "invalid target".to_string()).await;
+    drop(reservation);
+
+    assert!(result.is_err());
+    assert_eq!(control.in_progress().await, None);
+}
+
+#[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.runtime_reload_required);
+    assert!(!resp.process_restart_required);
+    assert!(resp.changed.iter().any(|c| c == "general"));
+}

src/api/config_store.rs

@@ -1,23 +1,32 @@
-use std::collections::BTreeMap;
-use std::io::Write;
+use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 
-use chrono::{DateTime, Utc};
 use hyper::header::IF_MATCH;
-use serde::Serialize;
 use sha2::{Digest, Sha256};
 
-use crate::config::ProxyConfig;
+use crate::config::{ConfigSourceGraph, LoadedConfig, ProxyConfig};
 
 use super::model::ApiFailure;
 
+// Source-preserving TOML rendering and atomic persistence helpers.
+mod persistence;
+
+#[cfg(test)]
+use persistence::{find_toml_table_bounds, render_access_section, save_sections_to_disk};
+pub(in crate::api) use persistence::{
+    render_server_listeners, render_top_level_section, save_access_sections_to_disk,
+    upsert_toml_table, write_atomic,
+};
+
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(super) enum AccessSection {
     Users,
+    UserEnabled,
     UserAdTags,
     UserMaxTcpConns,
     UserExpirations,
     UserDataQuota,
+    UserRateLimits,
     UserMaxUniqueIps,
 }
 
@@ -25,10 +34,12 @@ impl AccessSection {
     fn table_name(self) -> &'static str {
         match self {
             Self::Users => "access.users",
+            Self::UserEnabled => "access.user_enabled",
             Self::UserAdTags => "access.user_ad_tags",
             Self::UserMaxTcpConns => "access.user_max_tcp_conns",
             Self::UserExpirations => "access.user_expirations",
             Self::UserDataQuota => "access.user_data_quota",
+            Self::UserRateLimits => "access.user_rate_limits",
             Self::UserMaxUniqueIps => "access.user_max_unique_ips",
         }
     }
@@ -62,10 +73,21 @@ pub(super) async fn ensure_expected_revision(
 }
 
 pub(super) async fn current_revision(config_path: &Path) -> Result<String, ApiFailure> {
-    let content = tokio::fs::read_to_string(config_path)
+    let config_path = config_path.to_path_buf();
+    let graph = tokio::task::spawn_blocking(move || ProxyConfig::read_source_graph(config_path))
         .await
-        .map_err(|e| ApiFailure::internal(format!("failed to read config: {}", e)))?;
-    Ok(compute_revision(&content))
+        .map_err(|error| ApiFailure::internal(format!("failed to join config reader: {error}")))?
+        .map_err(|error| ApiFailure::internal(format!("failed to read config graph: {error}")))?;
+    Ok(compute_source_revision(&graph))
+}
+
+pub(crate) async fn current_revision_for_maestro(config_path: &Path) -> Result<String, String> {
+    let config_path = config_path.to_path_buf();
+    tokio::task::spawn_blocking(move || ProxyConfig::read_source_graph(config_path))
+        .await
+        .map_err(|error| format!("failed to join config reader: {error}"))?
+        .map(|graph| compute_source_revision(&graph))
+        .map_err(|error| error.to_string())
 }
 
 pub(super) fn compute_revision(content: &str) -> String {
@@ -74,6 +96,164 @@ pub(super) fn compute_revision(content: &str) -> String {
     hex::encode(hasher.finalize())
 }
 
+pub(super) fn compute_snapshot_revision(loaded: &LoadedConfig) -> String {
+    compute_source_revision(&ConfigSourceGraph {
+        source_contents: loaded.source_contents.clone(),
+        rendered: String::new(),
+    })
+}
+
+pub(super) fn compute_source_revision(graph: &ConfigSourceGraph) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(b"telemt-config-manifest-v1\0");
+    for (path, content) in &graph.source_contents {
+        let path = path.as_os_str().as_encoded_bytes();
+        hasher.update((path.len() as u64).to_le_bytes());
+        hasher.update(path);
+        hasher.update((content.len() as u64).to_le_bytes());
+        hasher.update(content.as_bytes());
+    }
+    hex::encode(hasher.finalize())
+}
+
+pub(super) async fn load_config_snapshot(
+    config_path: &Path,
+    invalid_is_bad_request: bool,
+) -> Result<LoadedConfig, ApiFailure> {
+    let config_path = config_path.to_path_buf();
+    tokio::task::spawn_blocking(move || ProxyConfig::load_with_metadata(config_path))
+        .await
+        .map_err(|error| ApiFailure::internal(format!("failed to join config loader: {error}")))?
+        .map_err(|error| {
+            if invalid_is_bad_request {
+                ApiFailure::bad_request(format!("invalid runtime config: {error}"))
+            } else {
+                ApiFailure::internal(format!("failed to load config: {error}"))
+            }
+        })
+}
+
+pub(super) fn resolve_single_source_owner(
+    loaded: &LoadedConfig,
+    config_path: &Path,
+    targets: &[&str],
+) -> Result<PathBuf, ApiFailure> {
+    let root = normalize_source_path(config_path);
+    let mut mutation_owners = BTreeSet::new();
+
+    if loaded
+        .source_contents
+        .values()
+        .any(|content| has_include_inside_table(content))
+    {
+        return Err(ApiFailure::new(
+            hyper::StatusCode::CONFLICT,
+            "config_patch_not_atomic",
+            "config includes nested inside a TOML table cannot be mutated atomically",
+        ));
+    }
+
+    for target in targets {
+        let mut owners = BTreeSet::new();
+        for (path, content) in &loaded.source_contents {
+            let parsed: toml::Value = toml::from_str(content).map_err(|error| {
+                ApiFailure::new(
+                    hyper::StatusCode::CONFLICT,
+                    "config_patch_not_atomic",
+                    format!(
+                        "config source {} is not independently writable: {error}",
+                        path.display()
+                    ),
+                )
+            })?;
+            if toml_path_exists(&parsed, target) {
+                owners.insert(path.clone());
+            }
+        }
+        match owners.len() {
+            0 => {
+                mutation_owners.insert(root.clone());
+            }
+            1 => {
+                mutation_owners.extend(owners);
+            }
+            _ => {
+                return Err(ApiFailure::new(
+                    hyper::StatusCode::CONFLICT,
+                    "config_patch_not_atomic",
+                    format!("config section {target} is owned by multiple source files"),
+                ));
+            }
+        }
+    }
+
+    if mutation_owners.len() != 1 {
+        return Err(ApiFailure::new(
+            hyper::StatusCode::CONFLICT,
+            "config_patch_not_atomic",
+            "one mutation may update only one config source file",
+        ));
+    }
+    mutation_owners
+        .into_iter()
+        .next()
+        .ok_or_else(|| ApiFailure::bad_request("empty mutation: no owned config sections"))
+}
+
+fn toml_path_exists(value: &toml::Value, target: &str) -> bool {
+    target
+        .split('.')
+        .try_fold(value, |current, part| current.get(part))
+        .is_some()
+}
+
+fn has_include_inside_table(content: &str) -> bool {
+    let mut inside_table = false;
+    for line in content.lines() {
+        let trimmed = line.trim();
+        if trimmed.starts_with('[') {
+            inside_table = true;
+        }
+        if inside_table
+            && trimmed
+                .strip_prefix("include")
+                .is_some_and(|rest| rest.trim_start().starts_with('='))
+        {
+            return true;
+        }
+    }
+    false
+}
+
+pub(super) async fn load_candidate_snapshot(
+    config_path: &Path,
+    base_sources: &BTreeMap<PathBuf, String>,
+    owner_path: PathBuf,
+    owner_contents: String,
+) -> Result<LoadedConfig, ApiFailure> {
+    let config_path = config_path.to_path_buf();
+    let mut overrides = base_sources.clone();
+    overrides.insert(owner_path, owner_contents);
+    tokio::task::spawn_blocking(move || {
+        ProxyConfig::load_with_source_overrides(config_path, &overrides)
+    })
+    .await
+    .map_err(|error| ApiFailure::internal(format!("failed to join config loader: {error}")))?
+    .map_err(|error| ApiFailure::bad_request(format!("invalid patched config: {error}")))
+}
+
+fn normalize_source_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) async fn load_config_from_disk(config_path: &Path) -> Result<ProxyConfig, ApiFailure> {
     let config_path = config_path.to_path_buf();
     tokio::task::spawn_blocking(move || ProxyConfig::load(config_path))
@@ -82,6 +262,15 @@ pub(super) async fn load_config_from_disk(config_path: &Path) -> Result<ProxyCon
         .map_err(|e| ApiFailure::internal(format!("failed to load config: {}", e)))
 }
 
+pub(super) async fn load_config_for_reload(config_path: &Path) -> Result<ProxyConfig, ApiFailure> {
+    let config_path = config_path.to_path_buf();
+    tokio::task::spawn_blocking(move || ProxyConfig::load(config_path))
+        .await
+        .map_err(|error| ApiFailure::internal(format!("failed to join config loader: {}", error)))?
+        .map_err(|error| ApiFailure::bad_request(format!("invalid runtime config: {}", error)))
+}
+
+#[allow(dead_code)]
 pub(super) async fn save_config_to_disk(
     config_path: &Path,
     cfg: &ProxyConfig,
@@ -92,178 +281,48 @@ pub(super) async fn save_config_to_disk(
     Ok(compute_revision(&serialized))
 }
 
-pub(super) async fn save_access_sections_to_disk(
-    config_path: &Path,
-    cfg: &ProxyConfig,
-    sections: &[AccessSection],
-) -> 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)))?;
+/// 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.
+///   - `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`.
+///
+/// `server` is partially editable: only the nested fields listed in
+/// [`EDITABLE_SERVER_FIELDS`] (currently `listeners`) may appear in GET/PATCH.
+/// Secrets and bind identity (`api`/`admin_api`, `port`, unix sockets, …) stay
+/// blocked. See also the field-level allowlist note below for `network.*`.
+///
+/// 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",
+];
 
-    let mut applied = Vec::new();
-    for section in sections {
-        if applied.contains(section) {
-            continue;
-        }
-        let rendered = render_access_section(cfg, *section)?;
-        content = upsert_toml_table(&content, section.table_name(), &rendered);
-        applied.push(*section);
-    }
+/// Nested fields under `[server]` that may be read/patched via the config API.
+///
+/// Arrays (e.g. `listeners`) replace wholesale on PATCH, matching the existing
+/// merge semantics for non-table values.
+pub(super) const EDITABLE_SERVER_FIELDS: &[&str] = &["listeners"];
 
-    write_atomic(config_path.to_path_buf(), content.clone()).await?;
-    Ok(compute_revision(&content))
+/// Whether `key` is an allowed top-level PATCH/GET section name.
+///
+/// Fully editable sections from [`EDITABLE_SECTIONS`], plus `server` which is
+/// further restricted by [`EDITABLE_SERVER_FIELDS`].
+pub(super) fn is_editable_section(key: &str) -> bool {
+    EDITABLE_SECTIONS.contains(&key) || key == "server"
 }
 
-fn render_access_section(cfg: &ProxyConfig, section: AccessSection) -> Result<String, ApiFailure> {
-    let body = match section {
-        AccessSection::Users => {
-            let rows: BTreeMap<String, String> = cfg
-                .access
-                .users
-                .iter()
-                .map(|(key, value)| (key.clone(), value.clone()))
-                .collect();
-            serialize_table_body(&rows)?
-        }
-        AccessSection::UserAdTags => {
-            let rows: BTreeMap<String, String> = cfg
-                .access
-                .user_ad_tags
-                .iter()
-                .map(|(key, value)| (key.clone(), value.clone()))
-                .collect();
-            serialize_table_body(&rows)?
-        }
-        AccessSection::UserMaxTcpConns => {
-            let rows: BTreeMap<String, usize> = cfg
-                .access
-                .user_max_tcp_conns
-                .iter()
-                .map(|(key, value)| (key.clone(), *value))
-                .collect();
-            serialize_table_body(&rows)?
-        }
-        AccessSection::UserExpirations => {
-            let rows: BTreeMap<String, DateTime<Utc>> = cfg
-                .access
-                .user_expirations
-                .iter()
-                .map(|(key, value)| (key.clone(), *value))
-                .collect();
-            serialize_table_body(&rows)?
-        }
-        AccessSection::UserDataQuota => {
-            let rows: BTreeMap<String, u64> = cfg
-                .access
-                .user_data_quota
-                .iter()
-                .map(|(key, value)| (key.clone(), *value))
-                .collect();
-            serialize_table_body(&rows)?
-        }
-        AccessSection::UserMaxUniqueIps => {
-            let rows: BTreeMap<String, usize> = cfg
-                .access
-                .user_max_unique_ips
-                .iter()
-                .map(|(key, value)| (key.clone(), *value))
-                .collect();
-            serialize_table_body(&rows)?
-        }
-    };
-
-    let mut out = format!("[{}]\n", section.table_name());
-    if !body.is_empty() {
-        out.push_str(&body);
-    }
-    if !out.ends_with('\n') {
-        out.push('\n');
-    }
-    Ok(out)
-}
-
-fn serialize_table_body<T: Serialize>(value: &T) -> Result<String, ApiFailure> {
-    toml::to_string(value)
-        .map_err(|e| ApiFailure::internal(format!("failed to serialize access section: {}", e)))
-}
-
-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 mut out = String::with_capacity(source.len() + replacement.len());
-        out.push_str(&source[..start]);
-        out.push_str(replacement);
-        out.push_str(&source[end..]);
-        return out;
-    }
-
-    let mut out = source.to_string();
-    if !out.is_empty() && !out.ends_with('\n') {
-        out.push('\n');
-    }
-    if !out.is_empty() {
-        out.push('\n');
-    }
-    out.push_str(replacement);
-    out
-}
-
-fn find_toml_table_bounds(source: &str, table_name: &str) -> Option<(usize, usize)> {
-    let target = format!("[{}]", table_name);
-    let mut offset = 0usize;
-    let mut start = None;
-
-    for line in source.split_inclusive('\n') {
-        let trimmed = line.trim();
-        if let Some(start_offset) = start {
-            if trimmed.starts_with('[') {
-                return Some((start_offset, offset));
-            }
-        } else if trimmed == target {
-            start = Some(offset);
-        }
-        offset = offset.saturating_add(line.len());
-    }
-
-    start.map(|start_offset| (start_offset, source.len()))
-}
-
-async fn write_atomic(path: PathBuf, contents: String) -> Result<(), ApiFailure> {
-    tokio::task::spawn_blocking(move || write_atomic_sync(&path, &contents))
-        .await
-        .map_err(|e| ApiFailure::internal(format!("failed to join writer: {}", e)))?
-        .map_err(|e| ApiFailure::internal(format!("failed to write config: {}", e)))
-}
-
-fn write_atomic_sync(path: &Path, contents: &str) -> std::io::Result<()> {
-    let parent = path.parent().unwrap_or_else(|| Path::new("."));
-    std::fs::create_dir_all(parent)?;
-
-    let tmp_name = format!(
-        ".{}.tmp-{}",
-        path.file_name()
-            .and_then(|s| s.to_str())
-            .unwrap_or("config.toml"),
-        rand::random::<u64>()
-    );
-    let tmp_path = parent.join(tmp_name);
-
-    let write_result = (|| {
-        let mut file = std::fs::OpenOptions::new()
-            .create_new(true)
-            .write(true)
-            .open(&tmp_path)?;
-        file.write_all(contents.as_bytes())?;
-        file.sync_all()?;
-        std::fs::rename(&tmp_path, path)?;
-        if let Ok(dir) = std::fs::File::open(parent) {
-            let _ = dir.sync_all();
-        }
-        Ok(())
-    })();
-
-    if write_result.is_err() {
-        let _ = std::fs::remove_file(&tmp_path);
-    }
-    write_result
-}
+#[cfg(test)]
+#[path = "config_store/tests.rs"]
+mod tests;

src/api/config_store/persistence.rs

@@ -0,0 +1,418 @@
+use std::collections::BTreeMap;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use chrono::{DateTime, Utc};
+use serde::Serialize;
+
+use crate::config::{ProxyConfig, RateLimitBps};
+
+#[cfg(test)]
+use super::compute_revision;
+use super::{
+    AccessSection, compute_snapshot_revision, load_candidate_snapshot, load_config_snapshot,
+    resolve_single_source_owner, toml_path_exists,
+};
+use crate::api::model::ApiFailure;
+
+/// Re-render the given top-level tables from `cfg` and upsert each into the
+/// on-disk file, preserving every untouched section (and its comments).
+#[cfg(test)]
+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.
+pub(in crate::api) 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)
+}
+
+/// Renders normalized listener entries as nested array-of-table blocks.
+pub(in crate::api) fn render_server_listeners(cfg: &ProxyConfig) -> Result<String, ApiFailure> {
+    let mut out = String::new();
+    for listener in &cfg.server.listeners {
+        out.push_str("[[server.listeners]]\n");
+        out.push_str(&toml::to_string(listener).map_err(|error| {
+            ApiFailure::internal(format!("failed to serialize server.listeners: {error}"))
+        })?);
+        if !out.ends_with('\n') {
+            out.push('\n');
+        }
+    }
+    Ok(out)
+}
+
+/// Validates and atomically writes access tables to their single source owner.
+pub(in crate::api) async fn save_access_sections_to_disk(
+    config_path: &Path,
+    cfg: &ProxyConfig,
+    sections: &[AccessSection],
+) -> Result<String, ApiFailure> {
+    let loaded = load_config_snapshot(config_path, false).await?;
+    let mut applied = Vec::new();
+    for section in sections {
+        if applied.contains(section) {
+            continue;
+        }
+        applied.push(*section);
+    }
+    applied.retain(|section| {
+        !access_section_is_empty(cfg, *section)
+            || loaded.source_contents.values().any(|contents| {
+                toml::from_str::<toml::Value>(contents)
+                    .ok()
+                    .is_some_and(|value| toml_path_exists(&value, section.table_name()))
+            })
+    });
+    if applied.is_empty() {
+        return Ok(compute_snapshot_revision(&loaded));
+    }
+
+    let targets = applied
+        .iter()
+        .map(|section| section.table_name())
+        .collect::<Vec<_>>();
+    let owner_path = resolve_single_source_owner(&loaded, config_path, &targets)?;
+    let mut owner_contents = loaded
+        .source_contents
+        .get(&owner_path)
+        .cloned()
+        .ok_or_else(|| ApiFailure::internal("config source owner is missing from snapshot"))?;
+    for section in applied {
+        let rendered = render_access_section(cfg, section)?;
+        owner_contents = upsert_toml_table(&owner_contents, section.table_name(), &rendered);
+    }
+
+    let candidate = load_candidate_snapshot(
+        config_path,
+        &loaded.source_contents,
+        owner_path.clone(),
+        owner_contents.clone(),
+    )
+    .await?;
+    let revision = compute_snapshot_revision(&candidate);
+    write_atomic(owner_path, owner_contents).await?;
+    Ok(revision)
+}
+
+/// Renders one access-control table for persistence tests and user mutations.
+pub(super) fn render_access_section(
+    cfg: &ProxyConfig,
+    section: AccessSection,
+) -> Result<String, ApiFailure> {
+    let body = match section {
+        AccessSection::Users => {
+            let rows: BTreeMap<String, String> = cfg
+                .access
+                .users
+                .iter()
+                .map(|(key, value)| (key.clone(), value.clone()))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserEnabled => {
+            let rows: BTreeMap<String, bool> = cfg
+                .access
+                .user_enabled
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserAdTags => {
+            let rows: BTreeMap<String, String> = cfg
+                .access
+                .user_ad_tags
+                .iter()
+                .map(|(key, value)| (key.clone(), value.clone()))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserMaxTcpConns => {
+            let rows: BTreeMap<String, usize> = cfg
+                .access
+                .user_max_tcp_conns
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserExpirations => {
+            let rows: BTreeMap<String, DateTime<Utc>> = cfg
+                .access
+                .user_expirations
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserDataQuota => {
+            let rows: BTreeMap<String, u64> = cfg
+                .access
+                .user_data_quota
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserRateLimits => {
+            let rows: BTreeMap<String, RateLimitBps> = cfg
+                .access
+                .user_rate_limits
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_rate_limit_body(&rows)?
+        }
+        AccessSection::UserMaxUniqueIps => {
+            let rows: BTreeMap<String, usize> = cfg
+                .access
+                .user_max_unique_ips
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+    };
+
+    let mut out = format!("[{}]\n", section.table_name());
+    if !body.is_empty() {
+        out.push_str(&body);
+    }
+    if !out.ends_with('\n') {
+        out.push('\n');
+    }
+    Ok(out)
+}
+
+fn access_section_is_empty(cfg: &ProxyConfig, section: AccessSection) -> bool {
+    match section {
+        AccessSection::Users => cfg.access.users.is_empty(),
+        AccessSection::UserEnabled => cfg.access.user_enabled.is_empty(),
+        AccessSection::UserAdTags => cfg.access.user_ad_tags.is_empty(),
+        AccessSection::UserMaxTcpConns => cfg.access.user_max_tcp_conns.is_empty(),
+        AccessSection::UserExpirations => cfg.access.user_expirations.is_empty(),
+        AccessSection::UserDataQuota => cfg.access.user_data_quota.is_empty(),
+        AccessSection::UserRateLimits => cfg.access.user_rate_limits.is_empty(),
+        AccessSection::UserMaxUniqueIps => cfg.access.user_max_unique_ips.is_empty(),
+    }
+}
+
+fn serialize_table_body<T: Serialize>(value: &T) -> Result<String, ApiFailure> {
+    toml::to_string(value)
+        .map_err(|e| ApiFailure::internal(format!("failed to serialize access section: {}", e)))
+}
+
+fn serialize_rate_limit_body(rows: &BTreeMap<String, RateLimitBps>) -> Result<String, ApiFailure> {
+    let mut out = String::new();
+    for (key, value) in rows {
+        let key = serialize_toml_key(key)?;
+        out.push_str(&format!(
+            "{key} = {{ up_bps = {}, down_bps = {} }}\n",
+            value.up_bps, value.down_bps
+        ));
+    }
+    Ok(out)
+}
+
+fn serialize_toml_key(key: &str) -> Result<String, ApiFailure> {
+    let mut row = BTreeMap::new();
+    row.insert(key.to_string(), 0_u8);
+    let rendered = serialize_table_body(&row)?;
+    rendered
+        .split_once(" = ")
+        .map(|(key, _)| key.to_string())
+        .ok_or_else(|| ApiFailure::internal("failed to serialize TOML key"))
+}
+
+/// Replaces all blocks owned by one semantic TOML table with one rendering.
+pub(in crate::api) fn upsert_toml_table(
+    source: &str,
+    table_name: &str,
+    replacement: &str,
+) -> String {
+    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[..first_start]);
+        out.push_str(replacement);
+        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;
+    }
+
+    let mut out = source.to_string();
+    if !out.is_empty() && !out.ends_with('\n') {
+        out.push('\n');
+    }
+    if !out.is_empty() {
+        out.push('\n');
+    }
+    out.push_str(replacement);
+    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.
+/// Locates one complete TOML table block in source text.
+#[cfg(test)]
+pub(super) fn find_toml_table_bounds(source: &str, table_name: &str) -> Option<(usize, usize)> {
+    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: Option<usize> = None;
+
+    for line in source.split_inclusive('\n') {
+        // 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 is_header && !header_belongs_to(header, table_name) {
+                blocks.push((start_offset, offset));
+                start = None;
+            }
+        }
+        if start.is_none() && header_belongs_to(header, table_name) {
+            start = Some(offset);
+        }
+        offset = offset.saturating_add(line.len());
+    }
+
+    if let Some(start_offset) = start {
+        blocks.push((start_offset, source.len()));
+    }
+    blocks
+}
+
+/// Replaces one config source through a durable same-directory rename.
+pub(in crate::api) async fn write_atomic(
+    path: PathBuf,
+    contents: String,
+) -> Result<(), ApiFailure> {
+    tokio::task::spawn_blocking(move || write_atomic_sync(&path, &contents))
+        .await
+        .map_err(|e| ApiFailure::internal(format!("failed to join writer: {}", e)))?
+        .map_err(|e| ApiFailure::internal(format!("failed to write config: {}", e)))
+}
+
+fn write_atomic_sync(path: &Path, contents: &str) -> std::io::Result<()> {
+    let parent = path.parent().unwrap_or_else(|| Path::new("."));
+    std::fs::create_dir_all(parent)?;
+
+    let tmp_name = format!(
+        ".{}.tmp-{}",
+        path.file_name()
+            .and_then(|s| s.to_str())
+            .unwrap_or("config.toml"),
+        rand::random::<u64>()
+    );
+    let tmp_path = parent.join(tmp_name);
+
+    let write_result = (|| {
+        let mut file = std::fs::OpenOptions::new()
+            .create_new(true)
+            .write(true)
+            .open(&tmp_path)?;
+        file.write_all(contents.as_bytes())?;
+        file.sync_all()?;
+        std::fs::rename(&tmp_path, path)?;
+        if let Ok(dir) = std::fs::File::open(parent) {
+            let _ = dir.sync_all();
+        }
+        Ok(())
+    })();
+
+    if write_result.is_err() {
+        let _ = std::fs::remove_file(&tmp_path);
+    }
+    write_result
+}

src/api/config_store/tests.rs

@@ -0,0 +1,309 @@
+use super::*;
+use crate::config::RateLimitBps;
+
+#[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\""));
+    // Untouched comments and tables remain byte content.
+    assert!(written.contains("# top comment"));
+    assert!(written.contains("[server]\nport = 443"));
+    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]]"));
+    // The bound spans through the last upstream block.
+    assert!(slice.contains("kind = \"b\""));
+}
+
+#[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"));
+    // The bound terminates at the next header.
+    assert!(!slice.contains("[server]"));
+}
+
+#[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}"));
+
+    // The unrelated table remains untouched.
+    assert!(written.contains("[server]\nport = 443"));
+}
+
+#[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]"));
+    // Nested sub-tables belong to the parent table bound.
+    assert!(slice.contains("[general.modes]"));
+    assert!(slice.contains("[general.links]"));
+    // The bound terminates before an unrelated header.
+    assert!(!slice.contains("[server]"));
+}
+
+#[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]"));
+}
+
+#[test]
+fn nested_include_detection_does_not_reject_similar_access_keys() {
+    assert!(has_include_inside_table(
+        "[access.users]\ninclude = \"users.toml\"\n"
+    ));
+    assert!(!has_include_inside_table(
+        "[access.users]\ninclude_user = \"00000000000000000000000000000000\"\n"
+    ));
+}
+
+#[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}"));
+    // The unrelated section remains present.
+    assert!(written.contains("[server]"));
+}
+
+#[tokio::test]
+async fn manifest_revision_changes_when_an_included_source_changes() {
+    let dir = tempfile::tempdir().unwrap();
+    let root = dir.path().join("config.toml");
+    let included = dir.path().join("included.toml");
+    tokio::fs::write(&root, "include = \"included.toml\"\n")
+        .await
+        .unwrap();
+    tokio::fs::write(&included, "[censorship]\ntls_domain = \"one.example\"\n")
+        .await
+        .unwrap();
+    let first = current_revision(&root).await.unwrap();
+
+    tokio::fs::write(&included, "[censorship]\ntls_domain = \"two.example\"\n")
+        .await
+        .unwrap();
+    let second = current_revision(&root).await.unwrap();
+
+    assert_ne!(first, second);
+}
+
+#[tokio::test]
+async fn manifest_revision_does_not_require_typed_config_validation() {
+    let dir = tempfile::tempdir().unwrap();
+    let root = dir.path().join("config.toml");
+    tokio::fs::write(&root, "[server]\nport = \"invalid\"\n")
+        .await
+        .unwrap();
+
+    let revision = current_revision(&root).await.unwrap();
+
+    assert_eq!(revision.len(), 64);
+    assert!(load_config_snapshot(&root, false).await.is_err());
+}
+
+#[tokio::test]
+async fn access_mutation_writes_only_the_single_included_owner() {
+    let dir = tempfile::tempdir().unwrap();
+    let root = dir.path().join("config.toml");
+    let included = dir.path().join("users.toml");
+    let root_body = "include = \"users.toml\"\n[censorship]\ntls_domain = \"example.com\"\n";
+    let included_body = "[access.users]\nalice = \"00000000000000000000000000000000\"\n";
+    tokio::fs::write(&root, root_body).await.unwrap();
+    tokio::fs::write(&included, included_body).await.unwrap();
+    let mut cfg = load_config_from_disk(&root).await.unwrap();
+    cfg.access.users.insert(
+        "bob".to_string(),
+        "11111111111111111111111111111111".to_string(),
+    );
+
+    let revision = save_access_sections_to_disk(&root, &cfg, &[AccessSection::Users])
+        .await
+        .unwrap();
+
+    assert_eq!(tokio::fs::read_to_string(&root).await.unwrap(), root_body);
+    let written = tokio::fs::read_to_string(&included).await.unwrap();
+    assert!(written.contains("bob = \"11111111111111111111111111111111\""));
+    assert_eq!(revision, current_revision(&root).await.unwrap());
+}
+
+#[tokio::test]
+async fn access_mutation_rejects_sections_with_different_source_owners() {
+    let dir = tempfile::tempdir().unwrap();
+    let root = dir.path().join("config.toml");
+    let included = dir.path().join("enabled.toml");
+    let root_body = concat!(
+        "include = \"enabled.toml\"\n",
+        "[access.users]\nalice = \"00000000000000000000000000000000\"\n"
+    );
+    let included_body = "[access.user_enabled]\nalice = false\n";
+    tokio::fs::write(&root, root_body).await.unwrap();
+    tokio::fs::write(&included, included_body).await.unwrap();
+    let cfg = load_config_from_disk(&root).await.unwrap();
+
+    let error = save_access_sections_to_disk(
+        &root,
+        &cfg,
+        &[AccessSection::Users, AccessSection::UserEnabled],
+    )
+    .await
+    .unwrap_err();
+
+    assert_eq!(error.code, "config_patch_not_atomic");
+    assert_eq!(tokio::fs::read_to_string(&root).await.unwrap(), root_body);
+    assert_eq!(
+        tokio::fs::read_to_string(&included).await.unwrap(),
+        included_body
+    );
+}
+
+#[test]
+fn render_user_rate_limits_section() {
+    let mut cfg = ProxyConfig::default();
+    cfg.access.user_rate_limits.insert(
+        "alice".to_string(),
+        RateLimitBps {
+            up_bps: 1024,
+            down_bps: 2048,
+        },
+    );
+
+    let rendered =
+        render_access_section(&cfg, AccessSection::UserRateLimits).expect("section must render");
+
+    assert!(rendered.starts_with("[access.user_rate_limits]\n"));
+    assert!(rendered.contains("alice = { up_bps = 1024, down_bps = 2048 }"));
+}

src/api/http_utils.rs

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

src/api/model.rs

@@ -5,6 +5,7 @@ use chrono::{DateTime, Utc};
 use hyper::StatusCode;
 use serde::{Deserialize, Serialize};
 
+use super::patch::{Patch, patch_field};
 use crate::crypto::SecureRandom;
 
 const MAX_USERNAME_LEN: usize = 64;
@@ -14,6 +15,7 @@ pub(super) struct ApiFailure {
     pub(super) status: StatusCode,
     pub(super) code: &'static str,
     pub(super) message: String,
+    pub(super) allow: Option<&'static str>,
 }
 
 impl ApiFailure {
@@ -22,6 +24,7 @@ impl ApiFailure {
             status,
             code,
             message: message.into(),
+            allow: None,
         }
     }
 
@@ -32,6 +35,15 @@ impl ApiFailure {
     pub(super) fn bad_request(message: impl Into<String>) -> Self {
         Self::new(StatusCode::BAD_REQUEST, "bad_request", message)
     }
+
+    pub(super) fn method_not_allowed(allow: &'static str) -> Self {
+        Self {
+            status: StatusCode::METHOD_NOT_ALLOWED,
+            code: "method_not_allowed",
+            message: "Unsupported HTTP method for this route".to_string(),
+            allow: Some(allow),
+        }
+    }
 }
 
 #[derive(Serialize)]
@@ -60,11 +72,30 @@ pub(super) struct HealthData {
     pub(super) read_only: bool,
 }
 
+#[derive(Serialize)]
+pub(super) struct HealthReadyData {
+    pub(super) ready: bool,
+    pub(super) status: &'static str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) admission_open: bool,
+    pub(super) healthy_upstreams: usize,
+    pub(super) total_upstreams: usize,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct ClassCount {
+    pub(super) class: String,
+    pub(super) total: u64,
+}
+
 #[derive(Serialize)]
 pub(super) struct SummaryData {
     pub(super) uptime_seconds: f64,
     pub(super) connections_total: u64,
     pub(super) connections_bad_total: u64,
+    pub(super) connections_bad_by_class: Vec<ClassCount>,
+    pub(super) handshake_failures_by_class: Vec<ClassCount>,
     pub(super) handshake_timeouts_total: u64,
     pub(super) configured_users: usize,
 }
@@ -80,6 +111,8 @@ pub(super) struct ZeroCoreData {
     pub(super) uptime_seconds: f64,
     pub(super) connections_total: u64,
     pub(super) connections_bad_total: u64,
+    pub(super) connections_bad_by_class: Vec<ClassCount>,
+    pub(super) handshake_failures_by_class: Vec<ClassCount>,
     pub(super) handshake_timeouts_total: u64,
     pub(super) accept_permit_timeout_total: u64,
     pub(super) configured_users: usize,
@@ -434,16 +467,26 @@ pub(super) struct UserLinks {
     pub(super) classic: Vec<String>,
     pub(super) secure: Vec<String>,
     pub(super) tls: Vec<String>,
+    pub(super) tls_domains: Vec<TlsDomainLink>,
+}
+
+#[derive(Serialize)]
+pub(super) struct TlsDomainLink {
+    pub(super) domain: String,
+    pub(super) link: String,
 }
 
 #[derive(Serialize)]
 pub(super) struct UserInfo {
     pub(super) username: String,
+    pub(super) enabled: bool,
     pub(super) in_runtime: bool,
     pub(super) user_ad_tag: Option<String>,
     pub(super) max_tcp_conns: Option<usize>,
     pub(super) expiration_rfc3339: Option<String>,
     pub(super) data_quota_bytes: Option<u64>,
+    pub(super) rate_limit_up_bps: Option<u64>,
+    pub(super) rate_limit_down_bps: Option<u64>,
     pub(super) max_unique_ips: Option<usize>,
     pub(super) current_connections: u64,
     pub(super) active_unique_ips: usize,
@@ -472,6 +515,26 @@ pub(super) struct DeleteUserResponse {
     pub(super) in_runtime: bool,
 }
 
+#[derive(Serialize)]
+pub(super) struct ResetUserQuotaResponse {
+    pub(super) username: String,
+    pub(super) used_bytes: u64,
+    pub(super) last_reset_epoch_secs: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct UserQuotaListData {
+    pub(super) users: Vec<UserQuotaEntry>,
+}
+
+#[derive(Serialize)]
+pub(super) struct UserQuotaEntry {
+    pub(super) username: String,
+    pub(super) data_quota_bytes: u64,
+    pub(super) used_bytes: u64,
+    pub(super) last_reset_epoch_secs: u64,
+}
+
 #[derive(Deserialize)]
 pub(super) struct CreateUserRequest {
     pub(super) username: String,
@@ -480,17 +543,31 @@ pub(super) struct CreateUserRequest {
     pub(super) max_tcp_conns: Option<usize>,
     pub(super) expiration_rfc3339: Option<String>,
     pub(super) data_quota_bytes: Option<u64>,
+    pub(super) rate_limit_up_bps: Option<u64>,
+    pub(super) rate_limit_down_bps: Option<u64>,
     pub(super) max_unique_ips: Option<usize>,
+    pub(super) enabled: Option<bool>,
 }
 
 #[derive(Deserialize)]
 pub(super) struct PatchUserRequest {
     pub(super) secret: Option<String>,
-    pub(super) user_ad_tag: Option<String>,
-    pub(super) max_tcp_conns: Option<usize>,
-    pub(super) expiration_rfc3339: Option<String>,
-    pub(super) data_quota_bytes: Option<u64>,
-    pub(super) max_unique_ips: Option<usize>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) user_ad_tag: Patch<String>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) max_tcp_conns: Patch<usize>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) expiration_rfc3339: Patch<String>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) data_quota_bytes: Patch<u64>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) rate_limit_up_bps: Patch<u64>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) rate_limit_down_bps: Patch<u64>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) max_unique_ips: Patch<usize>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) enabled: Patch<bool>,
 }
 
 #[derive(Default, Deserialize)]
@@ -509,6 +586,20 @@ pub(super) fn parse_optional_expiration(
     Ok(Some(parsed.with_timezone(&Utc)))
 }
 
+pub(super) fn parse_patch_expiration(
+    value: &Patch<String>,
+) -> Result<Patch<DateTime<Utc>>, ApiFailure> {
+    match value {
+        Patch::Unchanged => Ok(Patch::Unchanged),
+        Patch::Remove => Ok(Patch::Remove),
+        Patch::Set(raw) => {
+            let parsed = DateTime::parse_from_rfc3339(raw)
+                .map_err(|_| ApiFailure::bad_request("expiration_rfc3339 must be valid RFC3339"))?;
+            Ok(Patch::Set(parsed.with_timezone(&Utc)))
+        }
+    }
+}
+
 pub(super) fn is_valid_user_secret(secret: &str) -> bool {
     secret.len() == 32 && secret.chars().all(|c| c.is_ascii_hexdigit())
 }

src/api/patch.rs

@@ -0,0 +1,134 @@
+use serde::Deserialize;
+
+/// Three-state field for JSON Merge Patch semantics on the `PATCH /v1/users/{user}`
+/// endpoint.
+///
+/// `Unchanged` is produced when the JSON body omits the field entirely and tells the
+/// handler to leave the corresponding configuration entry untouched. `Remove` is
+/// produced when the JSON body sets the field to `null` and instructs the handler to
+/// drop the entry from the corresponding access HashMap. `Set` carries an explicit
+/// new value, including zero, which is preserved verbatim in the configuration.
+#[derive(Debug)]
+pub(super) enum Patch<T> {
+    Unchanged,
+    Remove,
+    Set(T),
+}
+
+impl<T> Default for Patch<T> {
+    fn default() -> Self {
+        Self::Unchanged
+    }
+}
+
+/// Serde deserializer adapter for fields that follow JSON Merge Patch semantics.
+///
+/// Pair this with `#[serde(default, deserialize_with = "patch_field")]` on a
+/// `Patch<T>` field. An omitted field falls back to `Patch::Unchanged` via
+/// `Default`; an explicit JSON `null` becomes `Patch::Remove`; any other value
+/// becomes `Patch::Set(v)`.
+pub(super) fn patch_field<'de, D, T>(deserializer: D) -> Result<Patch<T>, D::Error>
+where
+    D: serde::Deserializer<'de>,
+    T: serde::Deserialize<'de>,
+{
+    Option::<T>::deserialize(deserializer).map(|opt| match opt {
+        Some(value) => Patch::Set(value),
+        None => Patch::Remove,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::api::model::{PatchUserRequest, parse_patch_expiration};
+    use chrono::{TimeZone, Utc};
+    use serde::Deserialize;
+
+    #[derive(Deserialize)]
+    struct Holder {
+        #[serde(default, deserialize_with = "patch_field")]
+        value: Patch<u64>,
+    }
+
+    fn parse(json: &str) -> Holder {
+        serde_json::from_str(json).expect("valid json")
+    }
+
+    #[test]
+    fn omitted_field_yields_unchanged() {
+        let h = parse("{}");
+        assert!(matches!(h.value, Patch::Unchanged));
+    }
+
+    #[test]
+    fn explicit_null_yields_remove() {
+        let h = parse(r#"{"value": null}"#);
+        assert!(matches!(h.value, Patch::Remove));
+    }
+
+    #[test]
+    fn explicit_value_yields_set() {
+        let h = parse(r#"{"value": 42}"#);
+        assert!(matches!(h.value, Patch::Set(42)));
+    }
+
+    #[test]
+    fn explicit_zero_yields_set_zero() {
+        let h = parse(r#"{"value": 0}"#);
+        assert!(matches!(h.value, Patch::Set(0)));
+    }
+
+    #[test]
+    fn parse_patch_expiration_passes_unchanged_and_remove_through() {
+        assert!(matches!(
+            parse_patch_expiration(&Patch::Unchanged),
+            Ok(Patch::Unchanged)
+        ));
+        assert!(matches!(
+            parse_patch_expiration(&Patch::Remove),
+            Ok(Patch::Remove)
+        ));
+    }
+
+    #[test]
+    fn parse_patch_expiration_parses_set_value() {
+        let parsed =
+            parse_patch_expiration(&Patch::Set("2030-01-02T03:04:05Z".into())).expect("valid");
+        match parsed {
+            Patch::Set(dt) => {
+                assert_eq!(dt, Utc.with_ymd_and_hms(2030, 1, 2, 3, 4, 5).unwrap());
+            }
+            other => panic!("expected Patch::Set, got {:?}", other),
+        }
+    }
+
+    #[test]
+    fn parse_patch_expiration_rejects_invalid_set_value() {
+        assert!(parse_patch_expiration(&Patch::Set("not-a-date".into())).is_err());
+    }
+
+    #[test]
+    fn patch_user_request_deserializes_mixed_states() {
+        let raw = r#"{
+            "secret": "00112233445566778899aabbccddeeff",
+            "max_tcp_conns": 0,
+            "max_unique_ips": null,
+            "data_quota_bytes": 1024,
+            "rate_limit_up_bps": 4096,
+            "rate_limit_down_bps": null
+        }"#;
+        let req: PatchUserRequest = serde_json::from_str(raw).expect("valid json");
+        assert_eq!(
+            req.secret.as_deref(),
+            Some("00112233445566778899aabbccddeeff")
+        );
+        assert!(matches!(req.max_tcp_conns, Patch::Set(0)));
+        assert!(matches!(req.max_unique_ips, Patch::Remove));
+        assert!(matches!(req.data_quota_bytes, Patch::Set(1024)));
+        assert!(matches!(req.rate_limit_up_bps, Patch::Set(4096)));
+        assert!(matches!(req.rate_limit_down_bps, Patch::Remove));
+        assert!(matches!(req.expiration_rfc3339, Patch::Unchanged));
+        assert!(matches!(req.user_ad_tag, Patch::Unchanged));
+    }
+}

src/api/reload_tests.rs

@@ -0,0 +1,119 @@
+use super::*;
+use crate::config::ProxyConfig;
+
+async fn config_file() -> (tempfile::TempDir, PathBuf, String) {
+    let directory = tempfile::tempdir().unwrap();
+    let path = directory.path().join("config.toml");
+    let mut config = ProxyConfig::default();
+    config.server.max_connections = 4_242;
+    let body = toml::to_string_pretty(&config).unwrap();
+    tokio::fs::write(&path, &body).await.unwrap();
+    let revision = config_store::current_revision(&path).await.unwrap();
+    (directory, path, revision)
+}
+
+#[tokio::test]
+async fn reload_submission_uses_matching_disk_revision_and_snapshot() {
+    let (_directory, path, revision) = config_file().await;
+    let mutation_lock = Mutex::new(());
+    let (control, mut commands) = ReloadControl::channel(1);
+    let request = ReloadRequest::default();
+
+    let (accepted, response_revision) = submit_reload_from_disk(
+        &path,
+        &mutation_lock,
+        &control,
+        Some(&revision),
+        request.clone(),
+    )
+    .await
+    .unwrap();
+    let command = commands.recv().await.unwrap();
+
+    assert_eq!(response_revision, revision);
+    assert_eq!(accepted.config_revision, revision);
+    assert_eq!(command.config_revision, revision);
+    assert_eq!(command.request, request);
+    assert_eq!(command.config.server.max_connections, 4_242);
+}
+
+#[tokio::test]
+async fn revision_conflict_rejects_without_enqueuing_reload() {
+    let (_directory, path, _revision) = config_file().await;
+    let mutation_lock = Mutex::new(());
+    let (control, _commands) = ReloadControl::channel(1);
+
+    let error = submit_reload_from_disk(
+        &path,
+        &mutation_lock,
+        &control,
+        Some("stale-revision"),
+        ReloadRequest::default(),
+    )
+    .await
+    .unwrap_err();
+
+    assert_eq!(error.status, StatusCode::CONFLICT);
+    assert_eq!(error.code, "revision_conflict");
+    assert_eq!(control.in_progress().await, None);
+}
+
+#[tokio::test]
+async fn reload_conflict_and_closed_coordinator_map_to_http_contract() {
+    let (_directory, path, _revision) = config_file().await;
+    let mutation_lock = Mutex::new(());
+    let (control, mut commands) = ReloadControl::channel(1);
+    let _accepted = submit_reload_from_disk(
+        &path,
+        &mutation_lock,
+        &control,
+        None,
+        ReloadRequest::default(),
+    )
+    .await
+    .unwrap();
+    let _command = commands.recv().await.unwrap();
+
+    let conflict = submit_reload_from_disk(
+        &path,
+        &mutation_lock,
+        &control,
+        None,
+        ReloadRequest::default(),
+    )
+    .await
+    .unwrap_err();
+    assert_eq!(conflict.status, StatusCode::CONFLICT);
+    assert_eq!(conflict.code, "reload_in_progress");
+
+    control.fail(1, "test cleanup").await;
+    drop(commands);
+    let unavailable = submit_reload_from_disk(
+        &path,
+        &mutation_lock,
+        &control,
+        None,
+        ReloadRequest::default(),
+    )
+    .await
+    .unwrap_err();
+    assert_eq!(unavailable.status, StatusCode::SERVICE_UNAVAILABLE);
+    assert_eq!(unavailable.code, "maestro_unavailable");
+}
+
+#[test]
+fn reload_routes_expose_only_documented_methods_and_ids() {
+    assert_eq!(
+        allowed_methods_for_path("/v1/system/reload"),
+        Some(ALLOW_POST)
+    );
+    assert_eq!(
+        allowed_methods_for_path("/v1/system/reload/42"),
+        Some(ALLOW_GET)
+    );
+    assert_eq!(reload_status_route_id("/v1/system/reload/42"), Some(42));
+    assert_eq!(
+        reload_status_route_id("/v1/system/reload/not-a-number"),
+        None
+    );
+}

src/api/runtime_edge.rs

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

src/api/runtime_stats.rs

@@ -7,8 +7,8 @@ use crate::transport::upstream::IpPreference;
 
 use super::ApiShared;
 use super::model::{
-    DcEndpointWriters, DcStatus, DcStatusData, MeWriterStatus, MeWritersData, MeWritersSummary,
-    MinimalAllData, MinimalAllPayload, MinimalDcPathData, MinimalMeRuntimeData,
+    ClassCount, DcEndpointWriters, DcStatus, DcStatusData, MeWriterStatus, MeWritersData,
+    MeWritersSummary, MinimalAllData, MinimalAllPayload, MinimalDcPathData, MinimalMeRuntimeData,
     MinimalQuarantineData, UpstreamDcStatus, UpstreamStatus, UpstreamSummaryData, UpstreamsData,
     ZeroAllData, ZeroCodeCount, ZeroCoreData, ZeroDesyncData, ZeroMiddleProxyData, ZeroPoolData,
     ZeroUpstreamData,
@@ -26,6 +26,16 @@ pub(crate) struct MinimalCacheEntry {
 
 pub(super) fn build_zero_all_data(stats: &Stats, configured_users: usize) -> ZeroAllData {
     let telemetry = stats.telemetry_policy();
+    let bad_connection_classes = stats
+        .get_connects_bad_class_counts()
+        .into_iter()
+        .map(|(class, total)| ClassCount { class, total })
+        .collect();
+    let handshake_failure_classes = stats
+        .get_handshake_failure_class_counts()
+        .into_iter()
+        .map(|(class, total)| ClassCount { class, total })
+        .collect();
     let handshake_error_codes = stats
         .get_me_handshake_error_code_counts()
         .into_iter()
@@ -38,6 +48,8 @@ pub(super) fn build_zero_all_data(stats: &Stats, configured_users: usize) -> Zer
             uptime_seconds: stats.uptime_secs(),
             connections_total: stats.get_connects_all(),
             connections_bad_total: stats.get_connects_bad(),
+            connections_bad_by_class: bad_connection_classes,
+            handshake_failures_by_class: handshake_failure_classes,
             handshake_timeouts_total: stats.get_handshake_timeouts(),
             accept_permit_timeout_total: stats.get_accept_permit_timeout_total(),
             configured_users,

src/api/runtime_watch.rs

@@ -4,58 +4,184 @@ use std::time::{SystemTime, UNIX_EPOCH};
 
 use tokio::sync::watch;
 
-use crate::config::ProxyConfig;
+use crate::maestro::generation::RuntimeWatchState;
 
 use super::ApiRuntimeState;
 use super::events::ApiEventStore;
 
 pub(super) fn spawn_runtime_watchers(
-    config_rx: watch::Receiver<Arc<ProxyConfig>>,
-    admission_rx: watch::Receiver<bool>,
+    runtime_watch_rx: watch::Receiver<Option<RuntimeWatchState>>,
     runtime_state: Arc<ApiRuntimeState>,
     runtime_events: Arc<ApiEventStore>,
 ) {
-    let mut config_rx_reload = config_rx;
-    let runtime_state_reload = runtime_state.clone();
-    let runtime_events_reload = runtime_events.clone();
-    tokio::spawn(async move {
-        loop {
-            if config_rx_reload.changed().await.is_err() {
-                break;
-            }
-            runtime_state_reload
-                .config_reload_count
-                .fetch_add(1, Ordering::Relaxed);
-            runtime_state_reload
-                .last_config_reload_epoch_secs
-                .store(now_epoch_secs(), Ordering::Relaxed);
-            runtime_events_reload.record("config.reload.applied", "config receiver updated");
-        }
-    });
+    let _config_watcher = spawn_config_watcher(
+        runtime_watch_rx.clone(),
+        runtime_state.clone(),
+        runtime_events.clone(),
+    );
+    let _admission_watcher =
+        spawn_admission_watcher(runtime_watch_rx, runtime_state, runtime_events);
+}
 
-    let mut admission_rx_watch = admission_rx;
+fn spawn_config_watcher(
+    mut runtime_watch_rx: watch::Receiver<Option<RuntimeWatchState>>,
+    runtime_state: Arc<ApiRuntimeState>,
+    runtime_events: Arc<ApiEventStore>,
+) -> tokio::task::JoinHandle<()> {
     tokio::spawn(async move {
-        runtime_state
-            .admission_open
-            .store(*admission_rx_watch.borrow(), Ordering::Relaxed);
-        runtime_events.record(
-            "admission.state",
-            format!("accepting_new_connections={}", *admission_rx_watch.borrow()),
-        );
+        let Some(mut current) = runtime_watch_rx.borrow().clone() else {
+            return;
+        };
         loop {
-            if admission_rx_watch.changed().await.is_err() {
-                break;
+            tokio::select! {
+                biased;
+                changed = runtime_watch_rx.changed() => {
+                    if changed.is_err() {
+                        break;
+                    }
+                    let Some(next) = runtime_watch_rx.borrow().clone() else {
+                        continue;
+                    };
+                    if next.generation_id != current.generation_id {
+                        current = next;
+                        record_config_reload(
+                            &runtime_state,
+                            &runtime_events,
+                            format!("runtime generation {} activated", current.generation_id),
+                        );
+                    }
+                }
+                changed = current.config_rx.changed() => {
+                    if changed.is_err() {
+                        let Some(next) = wait_for_new_generation(
+                            &mut runtime_watch_rx,
+                            current.generation_id,
+                        ).await else {
+                            break;
+                        };
+                        current = next;
+                        record_config_reload(
+                            &runtime_state,
+                            &runtime_events,
+                            format!("runtime generation {} activated", current.generation_id),
+                        );
+                        continue;
+                    }
+                    if active_generation_id(&runtime_watch_rx) != Some(current.generation_id) {
+                        continue;
+                    }
+                    record_config_reload(
+                        &runtime_state,
+                        &runtime_events,
+                        format!("generation {} config receiver updated", current.generation_id),
+                    );
+                }
             }
-            let admission_open = *admission_rx_watch.borrow();
-            runtime_state
-                .admission_open
-                .store(admission_open, Ordering::Relaxed);
-            runtime_events.record(
-                "admission.state",
-                format!("accepting_new_connections={}", admission_open),
-            );
         }
-    });
+    })
+}
+
+fn spawn_admission_watcher(
+    mut runtime_watch_rx: watch::Receiver<Option<RuntimeWatchState>>,
+    runtime_state: Arc<ApiRuntimeState>,
+    runtime_events: Arc<ApiEventStore>,
+) -> tokio::task::JoinHandle<()> {
+    tokio::spawn(async move {
+        let Some(mut current) = runtime_watch_rx.borrow().clone() else {
+            return;
+        };
+        record_admission_state(&runtime_state, &runtime_events, &current);
+        loop {
+            tokio::select! {
+                biased;
+                changed = runtime_watch_rx.changed() => {
+                    if changed.is_err() {
+                        break;
+                    }
+                    let Some(next) = runtime_watch_rx.borrow().clone() else {
+                        continue;
+                    };
+                    if next.generation_id != current.generation_id {
+                        current = next;
+                        record_admission_state(&runtime_state, &runtime_events, &current);
+                    }
+                }
+                changed = current.admission_rx.changed() => {
+                    if changed.is_err() {
+                        let Some(next) = wait_for_new_generation(
+                            &mut runtime_watch_rx,
+                            current.generation_id,
+                        ).await else {
+                            break;
+                        };
+                        current = next;
+                        record_admission_state(&runtime_state, &runtime_events, &current);
+                        continue;
+                    }
+                    if active_generation_id(&runtime_watch_rx) == Some(current.generation_id) {
+                        record_admission_state(&runtime_state, &runtime_events, &current);
+                    }
+                }
+            }
+        }
+    })
+}
+
+fn active_generation_id(
+    runtime_watch_rx: &watch::Receiver<Option<RuntimeWatchState>>,
+) -> Option<u64> {
+    runtime_watch_rx
+        .borrow()
+        .as_ref()
+        .map(|state| state.generation_id)
+}
+
+async fn wait_for_new_generation(
+    runtime_watch_rx: &mut watch::Receiver<Option<RuntimeWatchState>>,
+    previous_generation_id: u64,
+) -> Option<RuntimeWatchState> {
+    loop {
+        if let Some(state) = runtime_watch_rx.borrow().clone()
+            && state.generation_id != previous_generation_id
+        {
+            return Some(state);
+        }
+        if runtime_watch_rx.changed().await.is_err() {
+            return None;
+        }
+    }
+}
+
+fn record_config_reload(
+    runtime_state: &ApiRuntimeState,
+    runtime_events: &ApiEventStore,
+    context: String,
+) {
+    runtime_state
+        .config_reload_count
+        .fetch_add(1, Ordering::Relaxed);
+    runtime_state
+        .last_config_reload_epoch_secs
+        .store(now_epoch_secs(), Ordering::Relaxed);
+    runtime_events.record("config.reload.applied", context);
+}
+
+fn record_admission_state(
+    runtime_state: &ApiRuntimeState,
+    runtime_events: &ApiEventStore,
+    current: &RuntimeWatchState,
+) {
+    let admission_open = *current.admission_rx.borrow();
+    runtime_state
+        .admission_open
+        .store(admission_open, Ordering::Relaxed);
+    runtime_events.record(
+        "admission.state",
+        format!(
+            "generation={} accepting_new_connections={}",
+            current.generation_id, admission_open
+        ),
+    );
 }
 
 fn now_epoch_secs() -> u64 {
@@ -64,3 +190,130 @@ fn now_epoch_secs() -> u64 {
         .unwrap_or_default()
         .as_secs()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::ProxyConfig;
+    use std::sync::atomic::{AtomicBool, AtomicU64};
+    use std::time::Duration;
+
+    fn state(
+        generation_id: u64,
+    ) -> (
+        RuntimeWatchState,
+        watch::Sender<Arc<ProxyConfig>>,
+        watch::Sender<bool>,
+    ) {
+        let (config_tx, config_rx) = watch::channel(Arc::new(ProxyConfig::default()));
+        let (admission_tx, admission_rx) = watch::channel(true);
+        (
+            RuntimeWatchState {
+                generation_id,
+                config_rx,
+                admission_rx,
+            },
+            config_tx,
+            admission_tx,
+        )
+    }
+
+    fn runtime_state() -> Arc<ApiRuntimeState> {
+        Arc::new(ApiRuntimeState {
+            process_started_at_epoch_secs: 1,
+            config_reload_count: AtomicU64::new(0),
+            last_config_reload_epoch_secs: AtomicU64::new(0),
+            admission_open: AtomicBool::new(false),
+        })
+    }
+
+    async fn wait_for_count(runtime_state: &ApiRuntimeState, expected: u64) {
+        tokio::time::timeout(Duration::from_secs(1), async {
+            loop {
+                if runtime_state.config_reload_count.load(Ordering::Relaxed) == expected {
+                    break;
+                }
+                tokio::task::yield_now().await;
+            }
+        })
+        .await
+        .unwrap();
+    }
+
+    #[tokio::test]
+    async fn watchers_follow_only_the_active_generation() {
+        let (initial, initial_config_tx, initial_admission_tx) = state(1);
+        let (runtime_watch_tx, runtime_watch_rx) = watch::channel(Some(initial));
+        let runtime_state = runtime_state();
+        let events = Arc::new(ApiEventStore::new(16));
+        spawn_runtime_watchers(runtime_watch_rx, runtime_state.clone(), events.clone());
+        tokio::task::yield_now().await;
+
+        assert_eq!(runtime_state.config_reload_count.load(Ordering::Relaxed), 0);
+        initial_config_tx.send_replace(Arc::new(ProxyConfig::default()));
+        wait_for_count(&runtime_state, 1).await;
+
+        let (next, next_config_tx, next_admission_tx) = state(2);
+        runtime_watch_tx.send_replace(Some(next));
+        wait_for_count(&runtime_state, 2).await;
+
+        initial_config_tx.send_replace(Arc::new(ProxyConfig::default()));
+        initial_admission_tx.send_replace(false);
+        tokio::task::yield_now().await;
+        assert_eq!(runtime_state.config_reload_count.load(Ordering::Relaxed), 2);
+        assert!(runtime_state.admission_open.load(Ordering::Relaxed));
+
+        next_config_tx.send_replace(Arc::new(ProxyConfig::default()));
+        next_admission_tx.send_replace(false);
+        wait_for_count(&runtime_state, 3).await;
+        tokio::time::timeout(Duration::from_secs(1), async {
+            while runtime_state.admission_open.load(Ordering::Relaxed) {
+                tokio::task::yield_now().await;
+            }
+        })
+        .await
+        .unwrap();
+
+        let snapshot = events.snapshot(16);
+        assert_eq!(
+            snapshot
+                .events
+                .iter()
+                .filter(|event| event.event_type == "config.reload.applied")
+                .count(),
+            3
+        );
+    }
+
+    #[tokio::test]
+    async fn watcher_recovers_from_closed_generation_and_exits_with_process_channel() {
+        let (initial, initial_config_tx, _initial_admission_tx) = state(1);
+        let (runtime_watch_tx, runtime_watch_rx) = watch::channel(Some(initial));
+        let runtime_state = runtime_state();
+        let events = Arc::new(ApiEventStore::new(16));
+        let watcher = spawn_config_watcher(runtime_watch_rx, runtime_state.clone(), events.clone());
+        drop(initial_config_tx);
+        tokio::task::yield_now().await;
+
+        let (next, next_config_tx, _next_admission_tx) = state(2);
+        runtime_watch_tx.send_replace(Some(next));
+        wait_for_count(&runtime_state, 1).await;
+        next_config_tx.send_replace(Arc::new(ProxyConfig::default()));
+        wait_for_count(&runtime_state, 2).await;
+
+        drop(runtime_watch_tx);
+        tokio::time::timeout(Duration::from_secs(1), watcher)
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(
+            events
+                .snapshot(16)
+                .events
+                .iter()
+                .filter(|event| event.event_type == "config.reload.applied")
+                .count(),
+            2
+        );
+    }
+}

src/api/runtime_zero.rs

@@ -1,4 +1,5 @@
 use std::sync::atomic::Ordering;
+use std::time::{SystemTime, UNIX_EPOCH};
 
 use serde::Serialize;
 
@@ -162,7 +163,7 @@ pub(super) fn build_system_info_data(
         build_time_utc,
         rustc_version,
         process_started_at_epoch_secs: shared.runtime_state.process_started_at_epoch_secs,
-        uptime_seconds: shared.stats.uptime_secs(),
+        uptime_seconds: process_uptime_seconds(shared.runtime_state.process_started_at_epoch_secs),
         config_path: shared.config_path.display().to_string(),
         config_hash: revision.to_string(),
         config_reload_count: shared
@@ -173,11 +174,24 @@ pub(super) fn build_system_info_data(
     }
 }
 
+fn process_uptime_seconds(process_started_at_epoch_secs: u64) -> f64 {
+    let now_epoch_secs = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs();
+    process_uptime_seconds_at(process_started_at_epoch_secs, now_epoch_secs)
+}
+
+fn process_uptime_seconds_at(process_started_at_epoch_secs: u64, now_epoch_secs: u64) -> f64 {
+    now_epoch_secs.saturating_sub(process_started_at_epoch_secs) as f64
+}
+
 pub(super) async fn build_runtime_gates_data(
     shared: &ApiShared,
     cfg: &ProxyConfig,
 ) -> RuntimeGatesData {
     let startup_summary = build_runtime_startup_summary(shared).await;
+    let startup_snapshot = shared.startup_tracker.snapshot().await;
     let route_state = shared.route_runtime.snapshot();
     let route_mode = route_state.mode.as_str();
     let fast_fallback_enabled =
@@ -191,7 +205,9 @@ pub(super) async fn build_runtime_gates_data(
         None
     };
     let reroute_reason = if reroute_active {
-        if fast_fallback_enabled {
+        if startup_snapshot.me.status.as_str() != "ready" {
+            Some("startup_direct_fallback")
+        } else if fast_fallback_enabled {
             Some("fast_not_ready_fallback")
         } else {
             Some("strict_grace_fallback")
@@ -336,3 +352,14 @@ fn me_writer_pick_mode_label(mode: MeWriterPickMode) -> &'static str {
         MeWriterPickMode::P2c => "p2c",
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::process_uptime_seconds_at;
+
+    #[test]
+    fn process_uptime_is_monotonic_and_saturating() {
+        assert_eq!(process_uptime_seconds_at(100, 135), 35.0);
+        assert_eq!(process_uptime_seconds_at(135, 100), 0.0);
+    }
+}

src/api/users.rs

@@ -3,685 +3,34 @@ use std::net::IpAddr;
 use hyper::StatusCode;
 
 use crate::config::ProxyConfig;
+use crate::config::RateLimitBps;
 use crate::ip_tracker::UserIpTracker;
 use crate::stats::Stats;
 
 use super::ApiShared;
 use super::config_store::{
-    AccessSection, ensure_expected_revision, load_config_from_disk, save_access_sections_to_disk,
-    save_config_to_disk,
+    AccessSection, current_revision, ensure_expected_revision, load_config_from_disk,
+    save_access_sections_to_disk,
 };
 use super::model::{
     ApiFailure, CreateUserRequest, CreateUserResponse, PatchUserRequest, RotateSecretRequest,
-    UserInfo, UserLinks, is_valid_ad_tag, is_valid_user_secret, is_valid_username,
-    parse_optional_expiration, random_user_secret,
+    TlsDomainLink, UserInfo, UserLinks, UserQuotaEntry, UserQuotaListData, is_valid_ad_tag,
+    is_valid_user_secret, is_valid_username, parse_optional_expiration, parse_patch_expiration,
+    random_user_secret,
 };
+use super::patch::Patch;
 
-pub(super) async fn create_user(
-    body: CreateUserRequest,
-    expected_revision: Option<String>,
-    shared: &ApiShared,
-) -> Result<(CreateUserResponse, String), ApiFailure> {
-    let touches_user_ad_tags = body.user_ad_tag.is_some();
-    let touches_user_max_tcp_conns = body.max_tcp_conns.is_some();
-    let touches_user_expirations = body.expiration_rfc3339.is_some();
-    let touches_user_data_quota = body.data_quota_bytes.is_some();
-    let touches_user_max_unique_ips = body.max_unique_ips.is_some();
+mod create;
+mod lifecycle;
+mod links;
+mod update;
+mod view;
 
-    if !is_valid_username(&body.username) {
-        return Err(ApiFailure::bad_request(
-            "username must match [A-Za-z0-9_.-] and be 1..64 chars",
-        ));
-    }
-
-    let secret = match body.secret {
-        Some(secret) => {
-            if !is_valid_user_secret(&secret) {
-                return Err(ApiFailure::bad_request(
-                    "secret must be exactly 32 hex characters",
-                ));
-            }
-            secret
-        }
-        None => random_user_secret(),
-    };
-
-    if let Some(ad_tag) = body.user_ad_tag.as_ref()
-        && !is_valid_ad_tag(ad_tag)
-    {
-        return Err(ApiFailure::bad_request(
-            "user_ad_tag must be exactly 32 hex characters",
-        ));
-    }
-
-    let expiration = parse_optional_expiration(body.expiration_rfc3339.as_deref())?;
-    let _guard = shared.mutation_lock.lock().await;
-    let mut cfg = load_config_from_disk(&shared.config_path).await?;
-    ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
-
-    if cfg.access.users.contains_key(&body.username) {
-        return Err(ApiFailure::new(
-            StatusCode::CONFLICT,
-            "user_exists",
-            "User already exists",
-        ));
-    }
-
-    cfg.access
-        .users
-        .insert(body.username.clone(), secret.clone());
-    if let Some(ad_tag) = body.user_ad_tag {
-        cfg.access
-            .user_ad_tags
-            .insert(body.username.clone(), ad_tag);
-    }
-    if let Some(limit) = body.max_tcp_conns {
-        cfg.access
-            .user_max_tcp_conns
-            .insert(body.username.clone(), limit);
-    }
-    if let Some(expiration) = expiration {
-        cfg.access
-            .user_expirations
-            .insert(body.username.clone(), expiration);
-    }
-    if let Some(quota) = body.data_quota_bytes {
-        cfg.access
-            .user_data_quota
-            .insert(body.username.clone(), quota);
-    }
-
-    let updated_limit = body.max_unique_ips;
-    if let Some(limit) = updated_limit {
-        cfg.access
-            .user_max_unique_ips
-            .insert(body.username.clone(), limit);
-    }
-
-    cfg.validate()
-        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
-
-    let mut touched_sections = vec![AccessSection::Users];
-    if touches_user_ad_tags {
-        touched_sections.push(AccessSection::UserAdTags);
-    }
-    if touches_user_max_tcp_conns {
-        touched_sections.push(AccessSection::UserMaxTcpConns);
-    }
-    if touches_user_expirations {
-        touched_sections.push(AccessSection::UserExpirations);
-    }
-    if touches_user_data_quota {
-        touched_sections.push(AccessSection::UserDataQuota);
-    }
-    if touches_user_max_unique_ips {
-        touched_sections.push(AccessSection::UserMaxUniqueIps);
-    }
-
-    let revision =
-        save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
-    drop(_guard);
-
-    if let Some(limit) = updated_limit {
-        shared
-            .ip_tracker
-            .set_user_limit(&body.username, limit)
-            .await;
-    }
-    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
-
-    let users = users_from_config(
-        &cfg,
-        &shared.stats,
-        &shared.ip_tracker,
-        detected_ip_v4,
-        detected_ip_v6,
-        None,
-    )
-    .await;
-    let user = users
-        .into_iter()
-        .find(|entry| entry.username == body.username)
-        .unwrap_or(UserInfo {
-            username: body.username.clone(),
-            in_runtime: false,
-            user_ad_tag: None,
-            max_tcp_conns: cfg
-                .access
-                .user_max_tcp_conns
-                .get(&body.username)
-                .copied()
-                .filter(|limit| *limit > 0)
-                .or((cfg.access.user_max_tcp_conns_global_each > 0)
-                    .then_some(cfg.access.user_max_tcp_conns_global_each)),
-            expiration_rfc3339: None,
-            data_quota_bytes: None,
-            max_unique_ips: updated_limit,
-            current_connections: 0,
-            active_unique_ips: 0,
-            active_unique_ips_list: Vec::new(),
-            recent_unique_ips: 0,
-            recent_unique_ips_list: Vec::new(),
-            total_octets: 0,
-            links: build_user_links(&cfg, &secret, detected_ip_v4, detected_ip_v6),
-        });
-
-    Ok((CreateUserResponse { user, secret }, revision))
-}
-
-pub(super) async fn patch_user(
-    user: &str,
-    body: PatchUserRequest,
-    expected_revision: Option<String>,
-    shared: &ApiShared,
-) -> Result<(UserInfo, String), ApiFailure> {
-    if let Some(secret) = body.secret.as_ref()
-        && !is_valid_user_secret(secret)
-    {
-        return Err(ApiFailure::bad_request(
-            "secret must be exactly 32 hex characters",
-        ));
-    }
-    if let Some(ad_tag) = body.user_ad_tag.as_ref()
-        && !is_valid_ad_tag(ad_tag)
-    {
-        return Err(ApiFailure::bad_request(
-            "user_ad_tag must be exactly 32 hex characters",
-        ));
-    }
-    let expiration = parse_optional_expiration(body.expiration_rfc3339.as_deref())?;
-    let _guard = shared.mutation_lock.lock().await;
-    let mut cfg = load_config_from_disk(&shared.config_path).await?;
-    ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
-
-    if !cfg.access.users.contains_key(user) {
-        return Err(ApiFailure::new(
-            StatusCode::NOT_FOUND,
-            "not_found",
-            "User not found",
-        ));
-    }
-
-    if let Some(secret) = body.secret {
-        cfg.access.users.insert(user.to_string(), secret);
-    }
-    if let Some(ad_tag) = body.user_ad_tag {
-        cfg.access.user_ad_tags.insert(user.to_string(), ad_tag);
-    }
-    if let Some(limit) = body.max_tcp_conns {
-        cfg.access
-            .user_max_tcp_conns
-            .insert(user.to_string(), limit);
-    }
-    if let Some(expiration) = expiration {
-        cfg.access
-            .user_expirations
-            .insert(user.to_string(), expiration);
-    }
-    if let Some(quota) = body.data_quota_bytes {
-        cfg.access.user_data_quota.insert(user.to_string(), quota);
-    }
-
-    let mut updated_limit = None;
-    if let Some(limit) = body.max_unique_ips {
-        cfg.access
-            .user_max_unique_ips
-            .insert(user.to_string(), limit);
-        updated_limit = Some(limit);
-    }
-
-    cfg.validate()
-        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
-
-    let revision = save_config_to_disk(&shared.config_path, &cfg).await?;
-    drop(_guard);
-    if let Some(limit) = updated_limit {
-        shared.ip_tracker.set_user_limit(user, limit).await;
-    }
-    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
-    let users = users_from_config(
-        &cfg,
-        &shared.stats,
-        &shared.ip_tracker,
-        detected_ip_v4,
-        detected_ip_v6,
-        None,
-    )
-    .await;
-    let user_info = users
-        .into_iter()
-        .find(|entry| entry.username == user)
-        .ok_or_else(|| ApiFailure::internal("failed to build updated user view"))?;
-
-    Ok((user_info, revision))
-}
-
-pub(super) async fn rotate_secret(
-    user: &str,
-    body: RotateSecretRequest,
-    expected_revision: Option<String>,
-    shared: &ApiShared,
-) -> Result<(CreateUserResponse, String), ApiFailure> {
-    let secret = body.secret.unwrap_or_else(random_user_secret);
-    if !is_valid_user_secret(&secret) {
-        return Err(ApiFailure::bad_request(
-            "secret must be exactly 32 hex characters",
-        ));
-    }
-
-    let _guard = shared.mutation_lock.lock().await;
-    let mut cfg = load_config_from_disk(&shared.config_path).await?;
-    ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
-
-    if !cfg.access.users.contains_key(user) {
-        return Err(ApiFailure::new(
-            StatusCode::NOT_FOUND,
-            "not_found",
-            "User not found",
-        ));
-    }
-
-    cfg.access.users.insert(user.to_string(), secret.clone());
-    cfg.validate()
-        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
-    let touched_sections = [
-        AccessSection::Users,
-        AccessSection::UserAdTags,
-        AccessSection::UserMaxTcpConns,
-        AccessSection::UserExpirations,
-        AccessSection::UserDataQuota,
-        AccessSection::UserMaxUniqueIps,
-    ];
-    let revision =
-        save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
-    drop(_guard);
-
-    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
-    let users = users_from_config(
-        &cfg,
-        &shared.stats,
-        &shared.ip_tracker,
-        detected_ip_v4,
-        detected_ip_v6,
-        None,
-    )
-    .await;
-    let user_info = users
-        .into_iter()
-        .find(|entry| entry.username == user)
-        .ok_or_else(|| ApiFailure::internal("failed to build updated user view"))?;
-
-    Ok((
-        CreateUserResponse {
-            user: user_info,
-            secret,
-        },
-        revision,
-    ))
-}
-
-pub(super) async fn delete_user(
-    user: &str,
-    expected_revision: Option<String>,
-    shared: &ApiShared,
-) -> Result<(String, String), ApiFailure> {
-    let _guard = shared.mutation_lock.lock().await;
-    let mut cfg = load_config_from_disk(&shared.config_path).await?;
-    ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
-
-    if !cfg.access.users.contains_key(user) {
-        return Err(ApiFailure::new(
-            StatusCode::NOT_FOUND,
-            "not_found",
-            "User not found",
-        ));
-    }
-    if cfg.access.users.len() <= 1 {
-        return Err(ApiFailure::new(
-            StatusCode::CONFLICT,
-            "last_user_forbidden",
-            "Cannot delete the last configured user",
-        ));
-    }
-
-    cfg.access.users.remove(user);
-    cfg.access.user_ad_tags.remove(user);
-    cfg.access.user_max_tcp_conns.remove(user);
-    cfg.access.user_expirations.remove(user);
-    cfg.access.user_data_quota.remove(user);
-    cfg.access.user_max_unique_ips.remove(user);
-
-    cfg.validate()
-        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
-    let touched_sections = [
-        AccessSection::Users,
-        AccessSection::UserAdTags,
-        AccessSection::UserMaxTcpConns,
-        AccessSection::UserExpirations,
-        AccessSection::UserDataQuota,
-        AccessSection::UserMaxUniqueIps,
-    ];
-    let revision =
-        save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
-    drop(_guard);
-    shared.ip_tracker.remove_user_limit(user).await;
-    shared.ip_tracker.clear_user_ips(user).await;
-
-    Ok((user.to_string(), revision))
-}
-
-pub(super) async fn users_from_config(
-    cfg: &ProxyConfig,
-    stats: &Stats,
-    ip_tracker: &UserIpTracker,
-    startup_detected_ip_v4: Option<IpAddr>,
-    startup_detected_ip_v6: Option<IpAddr>,
-    runtime_cfg: Option<&ProxyConfig>,
-) -> Vec<UserInfo> {
-    let mut names = cfg.access.users.keys().cloned().collect::<Vec<_>>();
-    names.sort();
-    let active_ip_lists = ip_tracker.get_active_ips_for_users(&names).await;
-    let recent_ip_lists = ip_tracker.get_recent_ips_for_users(&names).await;
-
-    let mut users = Vec::with_capacity(names.len());
-    for username in names {
-        let active_ip_list = active_ip_lists
-            .get(&username)
-            .cloned()
-            .unwrap_or_else(Vec::new);
-        let recent_ip_list = recent_ip_lists
-            .get(&username)
-            .cloned()
-            .unwrap_or_else(Vec::new);
-        let links = cfg
-            .access
-            .users
-            .get(&username)
-            .map(|secret| {
-                build_user_links(cfg, secret, startup_detected_ip_v4, startup_detected_ip_v6)
-            })
-            .unwrap_or(UserLinks {
-                classic: Vec::new(),
-                secure: Vec::new(),
-                tls: Vec::new(),
-            });
-        users.push(UserInfo {
-            in_runtime: runtime_cfg
-                .map(|runtime| runtime.access.users.contains_key(&username))
-                .unwrap_or(false),
-            user_ad_tag: cfg.access.user_ad_tags.get(&username).cloned(),
-            max_tcp_conns: cfg
-                .access
-                .user_max_tcp_conns
-                .get(&username)
-                .copied()
-                .filter(|limit| *limit > 0)
-                .or((cfg.access.user_max_tcp_conns_global_each > 0)
-                    .then_some(cfg.access.user_max_tcp_conns_global_each)),
-            expiration_rfc3339: cfg
-                .access
-                .user_expirations
-                .get(&username)
-                .map(chrono::DateTime::<chrono::Utc>::to_rfc3339),
-            data_quota_bytes: cfg.access.user_data_quota.get(&username).copied(),
-            max_unique_ips: cfg
-                .access
-                .user_max_unique_ips
-                .get(&username)
-                .copied()
-                .filter(|limit| *limit > 0)
-                .or((cfg.access.user_max_unique_ips_global_each > 0)
-                    .then_some(cfg.access.user_max_unique_ips_global_each)),
-            current_connections: stats.get_user_curr_connects(&username),
-            active_unique_ips: active_ip_list.len(),
-            active_unique_ips_list: active_ip_list,
-            recent_unique_ips: recent_ip_list.len(),
-            recent_unique_ips_list: recent_ip_list,
-            total_octets: stats.get_user_total_octets(&username),
-            links,
-            username,
-        });
-    }
-    users
-}
-
-fn build_user_links(
-    cfg: &ProxyConfig,
-    secret: &str,
-    startup_detected_ip_v4: Option<IpAddr>,
-    startup_detected_ip_v6: Option<IpAddr>,
-) -> UserLinks {
-    let hosts = resolve_link_hosts(cfg, startup_detected_ip_v4, startup_detected_ip_v6);
-    let port = cfg.general.links.public_port.unwrap_or(cfg.server.port);
-    let tls_domains = resolve_tls_domains(cfg);
-
-    let mut classic = Vec::new();
-    let mut secure = Vec::new();
-    let mut tls = Vec::new();
-
-    for host in &hosts {
-        if cfg.general.modes.classic {
-            classic.push(format!(
-                "tg://proxy?server={}&port={}&secret={}",
-                host, port, secret
-            ));
-        }
-        if cfg.general.modes.secure {
-            secure.push(format!(
-                "tg://proxy?server={}&port={}&secret=dd{}",
-                host, port, secret
-            ));
-        }
-        if cfg.general.modes.tls {
-            for domain in &tls_domains {
-                let domain_hex = hex::encode(domain);
-                tls.push(format!(
-                    "tg://proxy?server={}&port={}&secret=ee{}{}",
-                    host, port, secret, domain_hex
-                ));
-            }
-        }
-    }
-
-    UserLinks {
-        classic,
-        secure,
-        tls,
-    }
-}
-
-fn resolve_link_hosts(
-    cfg: &ProxyConfig,
-    startup_detected_ip_v4: Option<IpAddr>,
-    startup_detected_ip_v6: Option<IpAddr>,
-) -> Vec<String> {
-    if let Some(host) = cfg
-        .general
-        .links
-        .public_host
-        .as_deref()
-        .map(str::trim)
-        .filter(|value| !value.is_empty())
-    {
-        return vec![host.to_string()];
-    }
-
-    let mut hosts = Vec::new();
-    for listener in &cfg.server.listeners {
-        if let Some(host) = listener
-            .announce
-            .as_deref()
-            .map(str::trim)
-            .filter(|value| !value.is_empty())
-        {
-            push_unique_host(&mut hosts, host);
-            continue;
-        }
-        if let Some(ip) = listener.announce_ip
-            && !ip.is_unspecified()
-        {
-            push_unique_host(&mut hosts, &ip.to_string());
-            continue;
-        }
-        if listener.ip.is_unspecified() {
-            let detected_ip = if listener.ip.is_ipv4() {
-                startup_detected_ip_v4
-            } else {
-                startup_detected_ip_v6
-            };
-            if let Some(ip) = detected_ip {
-                push_unique_host(&mut hosts, &ip.to_string());
-            } else {
-                push_unique_host(&mut hosts, &listener.ip.to_string());
-            }
-            continue;
-        }
-        push_unique_host(&mut hosts, &listener.ip.to_string());
-    }
-
-    if !hosts.is_empty() {
-        return hosts;
-    }
-
-    if let Some(ip) = startup_detected_ip_v4.or(startup_detected_ip_v6) {
-        return vec![ip.to_string()];
-    }
-
-    if let Some(host) = cfg.server.listen_addr_ipv4.as_deref() {
-        push_host_from_legacy_listen(&mut hosts, host);
-    }
-    if let Some(host) = cfg.server.listen_addr_ipv6.as_deref() {
-        push_host_from_legacy_listen(&mut hosts, host);
-    }
-    if !hosts.is_empty() {
-        return hosts;
-    }
-
-    vec!["UNKNOWN".to_string()]
-}
-
-fn push_host_from_legacy_listen(hosts: &mut Vec<String>, raw: &str) {
-    let candidate = raw.trim();
-    if candidate.is_empty() {
-        return;
-    }
-
-    match candidate.parse::<IpAddr>() {
-        Ok(ip) if ip.is_unspecified() => {}
-        Ok(ip) => push_unique_host(hosts, &ip.to_string()),
-        Err(_) => push_unique_host(hosts, candidate),
-    }
-}
-
-fn push_unique_host(hosts: &mut Vec<String>, candidate: &str) {
-    if !hosts.iter().any(|existing| existing == candidate) {
-        hosts.push(candidate.to_string());
-    }
-}
-
-fn resolve_tls_domains(cfg: &ProxyConfig) -> Vec<&str> {
-    let mut domains = Vec::with_capacity(1 + cfg.censorship.tls_domains.len());
-    let primary = cfg.censorship.tls_domain.as_str();
-    if !primary.is_empty() {
-        domains.push(primary);
-    }
-    for domain in &cfg.censorship.tls_domains {
-        let value = domain.as_str();
-        if value.is_empty() || domains.contains(&value) {
-            continue;
-        }
-        domains.push(value);
-    }
-    domains
-}
+pub(super) use create::create_user;
+pub(super) use lifecycle::{delete_user, rotate_secret};
+use links::{build_user_links, empty_user_links};
+pub(super) use update::{patch_user, set_user_enabled};
+pub(super) use view::{build_user_quota_list, users_from_config};
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::ip_tracker::UserIpTracker;
-    use crate::stats::Stats;
-
-    #[tokio::test]
-    async fn users_from_config_reports_effective_tcp_limit_with_global_fallback() {
-        let mut cfg = ProxyConfig::default();
-        cfg.access.users.insert(
-            "alice".to_string(),
-            "0123456789abcdef0123456789abcdef".to_string(),
-        );
-        cfg.access.user_max_tcp_conns_global_each = 7;
-
-        let stats = Stats::new();
-        let tracker = UserIpTracker::new();
-
-        let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
-        let alice = users
-            .iter()
-            .find(|entry| entry.username == "alice")
-            .expect("alice must be present");
-        assert!(!alice.in_runtime);
-        assert_eq!(alice.max_tcp_conns, Some(7));
-
-        cfg.access.user_max_tcp_conns.insert("alice".to_string(), 5);
-        let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
-        let alice = users
-            .iter()
-            .find(|entry| entry.username == "alice")
-            .expect("alice must be present");
-        assert!(!alice.in_runtime);
-        assert_eq!(alice.max_tcp_conns, Some(5));
-
-        cfg.access.user_max_tcp_conns.insert("alice".to_string(), 0);
-        let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
-        let alice = users
-            .iter()
-            .find(|entry| entry.username == "alice")
-            .expect("alice must be present");
-        assert!(!alice.in_runtime);
-        assert_eq!(alice.max_tcp_conns, Some(7));
-
-        cfg.access.user_max_tcp_conns_global_each = 0;
-        let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
-        let alice = users
-            .iter()
-            .find(|entry| entry.username == "alice")
-            .expect("alice must be present");
-        assert!(!alice.in_runtime);
-        assert_eq!(alice.max_tcp_conns, None);
-    }
-
-    #[tokio::test]
-    async fn users_from_config_marks_runtime_membership_when_snapshot_is_provided() {
-        let mut disk_cfg = ProxyConfig::default();
-        disk_cfg.access.users.insert(
-            "alice".to_string(),
-            "0123456789abcdef0123456789abcdef".to_string(),
-        );
-        disk_cfg.access.users.insert(
-            "bob".to_string(),
-            "fedcba9876543210fedcba9876543210".to_string(),
-        );
-
-        let mut runtime_cfg = ProxyConfig::default();
-        runtime_cfg.access.users.insert(
-            "alice".to_string(),
-            "0123456789abcdef0123456789abcdef".to_string(),
-        );
-
-        let stats = Stats::new();
-        let tracker = UserIpTracker::new();
-        let users =
-            users_from_config(&disk_cfg, &stats, &tracker, None, None, Some(&runtime_cfg)).await;
-
-        let alice = users
-            .iter()
-            .find(|entry| entry.username == "alice")
-            .expect("alice must be present");
-        let bob = users
-            .iter()
-            .find(|entry| entry.username == "bob")
-            .expect("bob must be present");
-
-        assert!(alice.in_runtime);
-        assert!(!bob.in_runtime);
-    }
-}
+mod tests;

src/api/users/create.rs

@@ -0,0 +1,177 @@
+use super::*;
+
+pub(in crate::api) async fn create_user(
+    body: CreateUserRequest,
+    expected_revision: Option<String>,
+    shared: &ApiShared,
+) -> Result<(CreateUserResponse, String), ApiFailure> {
+    let touches_user_ad_tags = body.user_ad_tag.is_some();
+    let touches_user_max_tcp_conns = body.max_tcp_conns.is_some();
+    let touches_user_expirations = body.expiration_rfc3339.is_some();
+    let touches_user_data_quota = body.data_quota_bytes.is_some();
+    let touches_user_rate_limits =
+        body.rate_limit_up_bps.is_some() || body.rate_limit_down_bps.is_some();
+    let touches_user_max_unique_ips = body.max_unique_ips.is_some();
+    let touches_user_enabled = matches!(body.enabled, Some(false));
+
+    if !is_valid_username(&body.username) {
+        return Err(ApiFailure::bad_request(
+            "username must match [A-Za-z0-9_.-] and be 1..64 chars",
+        ));
+    }
+
+    let secret = match body.secret {
+        Some(secret) => {
+            if !is_valid_user_secret(&secret) {
+                return Err(ApiFailure::bad_request(
+                    "secret must be exactly 32 hex characters",
+                ));
+            }
+            secret
+        }
+        None => random_user_secret(),
+    };
+
+    if let Some(ad_tag) = body.user_ad_tag.as_ref()
+        && !is_valid_ad_tag(ad_tag)
+    {
+        return Err(ApiFailure::bad_request(
+            "user_ad_tag must be exactly 32 hex characters",
+        ));
+    }
+
+    let expiration = parse_optional_expiration(body.expiration_rfc3339.as_deref())?;
+    let _guard = shared.mutation_lock.lock().await;
+    let mut cfg = load_config_from_disk(&shared.config_path).await?;
+    ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
+
+    if cfg.access.users.contains_key(&body.username) {
+        return Err(ApiFailure::new(
+            StatusCode::CONFLICT,
+            "user_exists",
+            "User already exists",
+        ));
+    }
+
+    cfg.access
+        .users
+        .insert(body.username.clone(), secret.clone());
+    if let Some(ad_tag) = body.user_ad_tag {
+        cfg.access
+            .user_ad_tags
+            .insert(body.username.clone(), ad_tag);
+    }
+    if let Some(limit) = body.max_tcp_conns {
+        cfg.access
+            .user_max_tcp_conns
+            .insert(body.username.clone(), limit);
+    }
+    if let Some(expiration) = expiration {
+        cfg.access
+            .user_expirations
+            .insert(body.username.clone(), expiration);
+    }
+    if let Some(quota) = body.data_quota_bytes {
+        cfg.access
+            .user_data_quota
+            .insert(body.username.clone(), quota);
+    }
+    if touches_user_rate_limits {
+        cfg.access.user_rate_limits.insert(
+            body.username.clone(),
+            RateLimitBps {
+                up_bps: body.rate_limit_up_bps.unwrap_or(0),
+                down_bps: body.rate_limit_down_bps.unwrap_or(0),
+            },
+        );
+    }
+
+    let updated_limit = body.max_unique_ips;
+    if let Some(limit) = updated_limit {
+        cfg.access
+            .user_max_unique_ips
+            .insert(body.username.clone(), limit);
+    }
+    if matches!(body.enabled, Some(false)) {
+        cfg.access.user_enabled.insert(body.username.clone(), false);
+    }
+
+    cfg.validate()
+        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
+
+    let mut touched_sections = vec![AccessSection::Users];
+    if touches_user_ad_tags {
+        touched_sections.push(AccessSection::UserAdTags);
+    }
+    if touches_user_max_tcp_conns {
+        touched_sections.push(AccessSection::UserMaxTcpConns);
+    }
+    if touches_user_expirations {
+        touched_sections.push(AccessSection::UserExpirations);
+    }
+    if touches_user_data_quota {
+        touched_sections.push(AccessSection::UserDataQuota);
+    }
+    if touches_user_rate_limits {
+        touched_sections.push(AccessSection::UserRateLimits);
+    }
+    if touches_user_max_unique_ips {
+        touched_sections.push(AccessSection::UserMaxUniqueIps);
+    }
+    if touches_user_enabled {
+        touched_sections.push(AccessSection::UserEnabled);
+    }
+
+    let revision =
+        save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
+    drop(_guard);
+
+    if let Some(limit) = updated_limit {
+        shared
+            .ip_tracker
+            .set_user_limit(&body.username, limit)
+            .await;
+    }
+    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
+
+    let users = users_from_config(
+        &cfg,
+        &shared.stats,
+        &shared.ip_tracker,
+        detected_ip_v4,
+        detected_ip_v6,
+        None,
+    )
+    .await;
+    let user = users
+        .into_iter()
+        .find(|entry| entry.username == body.username)
+        .unwrap_or(UserInfo {
+            username: body.username.clone(),
+            enabled: cfg.access.is_user_enabled(&body.username),
+            in_runtime: false,
+            user_ad_tag: None,
+            max_tcp_conns: cfg
+                .access
+                .user_max_tcp_conns
+                .get(&body.username)
+                .copied()
+                .filter(|limit| *limit > 0)
+                .or((cfg.access.user_max_tcp_conns_global_each > 0)
+                    .then_some(cfg.access.user_max_tcp_conns_global_each)),
+            expiration_rfc3339: None,
+            data_quota_bytes: None,
+            rate_limit_up_bps: body.rate_limit_up_bps.filter(|limit| *limit > 0),
+            rate_limit_down_bps: body.rate_limit_down_bps.filter(|limit| *limit > 0),
+            max_unique_ips: updated_limit,
+            current_connections: 0,
+            active_unique_ips: 0,
+            active_unique_ips_list: Vec::new(),
+            recent_unique_ips: 0,
+            recent_unique_ips_list: Vec::new(),
+            total_octets: 0,
+            links: build_user_links(&cfg, &secret, detected_ip_v4, detected_ip_v6),
+        });
+
+    Ok((CreateUserResponse { user, secret }, revision))
+}

src/api/users/lifecycle.rs

@@ -0,0 +1,116 @@
+use super::*;
+
+pub(in crate::api) async fn rotate_secret(
+    user: &str,
+    body: RotateSecretRequest,
+    expected_revision: Option<String>,
+    shared: &ApiShared,
+) -> Result<(CreateUserResponse, String), ApiFailure> {
+    let secret = body.secret.unwrap_or_else(random_user_secret);
+    if !is_valid_user_secret(&secret) {
+        return Err(ApiFailure::bad_request(
+            "secret must be exactly 32 hex characters",
+        ));
+    }
+
+    let _guard = shared.mutation_lock.lock().await;
+    let mut cfg = load_config_from_disk(&shared.config_path).await?;
+    ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
+
+    if !cfg.access.users.contains_key(user) {
+        return Err(ApiFailure::new(
+            StatusCode::NOT_FOUND,
+            "not_found",
+            "User not found",
+        ));
+    }
+
+    cfg.access.users.insert(user.to_string(), secret.clone());
+    cfg.validate()
+        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
+    let revision =
+        save_access_sections_to_disk(&shared.config_path, &cfg, &[AccessSection::Users]).await?;
+    drop(_guard);
+
+    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
+    let users = users_from_config(
+        &cfg,
+        &shared.stats,
+        &shared.ip_tracker,
+        detected_ip_v4,
+        detected_ip_v6,
+        None,
+    )
+    .await;
+    let user_info = users
+        .into_iter()
+        .find(|entry| entry.username == user)
+        .ok_or_else(|| ApiFailure::internal("failed to build updated user view"))?;
+
+    Ok((
+        CreateUserResponse {
+            user: user_info,
+            secret,
+        },
+        revision,
+    ))
+}
+
+pub(in crate::api) async fn delete_user(
+    user: &str,
+    expected_revision: Option<String>,
+    shared: &ApiShared,
+) -> Result<(String, String), ApiFailure> {
+    let _guard = shared.mutation_lock.lock().await;
+    let mut cfg = load_config_from_disk(&shared.config_path).await?;
+    ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
+
+    if !cfg.access.users.contains_key(user) {
+        return Err(ApiFailure::new(
+            StatusCode::NOT_FOUND,
+            "not_found",
+            "User not found",
+        ));
+    }
+    if cfg.access.users.len() <= 1 {
+        return Err(ApiFailure::new(
+            StatusCode::CONFLICT,
+            "last_user_forbidden",
+            "Cannot delete the last configured user",
+        ));
+    }
+
+    let mut touched_sections = vec![AccessSection::Users];
+    cfg.access.users.remove(user);
+    if cfg.access.user_enabled.remove(user).is_some() {
+        touched_sections.push(AccessSection::UserEnabled);
+    }
+    if cfg.access.user_ad_tags.remove(user).is_some() {
+        touched_sections.push(AccessSection::UserAdTags);
+    }
+    if cfg.access.user_max_tcp_conns.remove(user).is_some() {
+        touched_sections.push(AccessSection::UserMaxTcpConns);
+    }
+    if cfg.access.user_expirations.remove(user).is_some() {
+        touched_sections.push(AccessSection::UserExpirations);
+    }
+    if cfg.access.user_data_quota.remove(user).is_some() {
+        touched_sections.push(AccessSection::UserDataQuota);
+    }
+    if cfg.access.user_rate_limits.remove(user).is_some() {
+        touched_sections.push(AccessSection::UserRateLimits);
+    }
+    if cfg.access.user_max_unique_ips.remove(user).is_some() {
+        touched_sections.push(AccessSection::UserMaxUniqueIps);
+    }
+
+    cfg.validate()
+        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
+    let revision =
+        save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
+    drop(_guard);
+    shared.ip_tracker.remove_user_limit(user).await;
+    shared.ip_tracker.clear_user_ips(user).await;
+
+    Ok((user.to_string(), revision))
+}

src/api/users/links.rs

@@ -0,0 +1,199 @@
+use super::*;
+
+pub(in crate::api::users) fn empty_user_links() -> UserLinks {
+    UserLinks {
+        classic: Vec::new(),
+        secure: Vec::new(),
+        tls: Vec::new(),
+        tls_domains: Vec::new(),
+    }
+}
+
+pub(in crate::api::users) fn build_user_links(
+    cfg: &ProxyConfig,
+    secret: &str,
+    startup_detected_ip_v4: Option<IpAddr>,
+    startup_detected_ip_v6: Option<IpAddr>,
+) -> UserLinks {
+    let hosts = resolve_link_hosts(cfg, startup_detected_ip_v4, startup_detected_ip_v6);
+    let port = cfg
+        .general
+        .links
+        .public_port
+        .unwrap_or(resolve_default_link_port(cfg));
+    let tls_domains = resolve_tls_domains(cfg);
+    let extra_tls_domains = resolve_extra_tls_domains(cfg);
+
+    let mut classic = Vec::new();
+    let mut secure = Vec::new();
+    let mut tls = Vec::new();
+    let mut tls_domain_links = Vec::new();
+
+    for host in &hosts {
+        if cfg.general.modes.classic {
+            classic.push(format!(
+                "tg://proxy?server={}&port={}&secret={}",
+                host, port, secret
+            ));
+        }
+        if cfg.general.modes.secure {
+            secure.push(format!(
+                "tg://proxy?server={}&port={}&secret=dd{}",
+                host, port, secret
+            ));
+        }
+        if cfg.general.modes.tls {
+            for domain in &tls_domains {
+                let domain_hex = hex::encode(domain);
+                tls.push(format!(
+                    "tg://proxy?server={}&port={}&secret=ee{}{}",
+                    host, port, secret, domain_hex
+                ));
+            }
+            for domain in &extra_tls_domains {
+                let domain_hex = hex::encode(domain);
+                let link = format!(
+                    "tg://proxy?server={}&port={}&secret=ee{}{}",
+                    host, port, secret, domain_hex
+                );
+                tls_domain_links.push(TlsDomainLink {
+                    domain: (*domain).to_string(),
+                    link,
+                });
+            }
+        }
+    }
+
+    UserLinks {
+        classic,
+        secure,
+        tls,
+        tls_domains: tls_domain_links,
+    }
+}
+
+fn resolve_default_link_port(cfg: &ProxyConfig) -> u16 {
+    cfg.server
+        .listeners
+        .first()
+        .and_then(|listener| listener.port)
+        .unwrap_or(cfg.server.port)
+}
+
+fn resolve_link_hosts(
+    cfg: &ProxyConfig,
+    startup_detected_ip_v4: Option<IpAddr>,
+    startup_detected_ip_v6: Option<IpAddr>,
+) -> Vec<String> {
+    if let Some(host) = cfg
+        .general
+        .links
+        .public_host
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+    {
+        return vec![host.to_string()];
+    }
+
+    let mut hosts = Vec::new();
+    for listener in &cfg.server.listeners {
+        if let Some(host) = listener
+            .announce
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+        {
+            push_unique_host(&mut hosts, host);
+            continue;
+        }
+        if let Some(ip) = listener.announce_ip
+            && !ip.is_unspecified()
+        {
+            push_unique_host(&mut hosts, &ip.to_string());
+            continue;
+        }
+        if listener.ip.is_unspecified() {
+            let detected_ip = if listener.ip.is_ipv4() {
+                startup_detected_ip_v4
+            } else {
+                startup_detected_ip_v6
+            };
+            if let Some(ip) = detected_ip {
+                push_unique_host(&mut hosts, &ip.to_string());
+            } else {
+                push_unique_host(&mut hosts, &listener.ip.to_string());
+            }
+            continue;
+        }
+        push_unique_host(&mut hosts, &listener.ip.to_string());
+    }
+
+    if !hosts.is_empty() {
+        return hosts;
+    }
+
+    if let Some(ip) = startup_detected_ip_v4.or(startup_detected_ip_v6) {
+        return vec![ip.to_string()];
+    }
+
+    if let Some(host) = cfg.server.listen_addr_ipv4.as_deref() {
+        push_host_from_legacy_listen(&mut hosts, host);
+    }
+    if let Some(host) = cfg.server.listen_addr_ipv6.as_deref() {
+        push_host_from_legacy_listen(&mut hosts, host);
+    }
+    if !hosts.is_empty() {
+        return hosts;
+    }
+
+    vec!["UNKNOWN".to_string()]
+}
+
+fn push_host_from_legacy_listen(hosts: &mut Vec<String>, raw: &str) {
+    let candidate = raw.trim();
+    if candidate.is_empty() {
+        return;
+    }
+
+    match candidate.parse::<IpAddr>() {
+        Ok(ip) if ip.is_unspecified() => {}
+        Ok(ip) => push_unique_host(hosts, &ip.to_string()),
+        Err(_) => push_unique_host(hosts, candidate),
+    }
+}
+
+fn push_unique_host(hosts: &mut Vec<String>, candidate: &str) {
+    if !hosts.iter().any(|existing| existing == candidate) {
+        hosts.push(candidate.to_string());
+    }
+}
+
+fn resolve_tls_domains(cfg: &ProxyConfig) -> Vec<&str> {
+    let mut domains = Vec::with_capacity(1 + cfg.censorship.tls_domains.len());
+    let primary = cfg.censorship.tls_domain.as_str();
+    if !primary.is_empty() {
+        domains.push(primary);
+    }
+    for domain in &cfg.censorship.tls_domains {
+        let value = domain.as_str();
+        if value.is_empty() || domains.contains(&value) {
+            continue;
+        }
+        domains.push(value);
+    }
+    domains
+}
+
+fn resolve_extra_tls_domains(cfg: &ProxyConfig) -> Vec<&str> {
+    let mut domains = Vec::with_capacity(cfg.censorship.tls_domains.len());
+    let primary = cfg.censorship.tls_domain.as_str();
+    for domain in &cfg.censorship.tls_domains {
+        let value = domain.as_str();
+        if value.is_empty() || value == primary || domains.contains(&value) {
+            continue;
+        }
+        domains.push(value);
+    }
+    domains
+}

src/api/users/tests.rs

@@ -0,0 +1,292 @@
+use super::*;
+use crate::ip_tracker::UserIpTracker;
+use crate::stats::Stats;
+
+#[tokio::test]
+async fn users_from_config_reports_effective_tcp_limit_with_global_fallback() {
+    let mut cfg = ProxyConfig::default();
+    cfg.access.users.insert(
+        "alice".to_string(),
+        "0123456789abcdef0123456789abcdef".to_string(),
+    );
+    cfg.access.user_max_tcp_conns_global_each = 7;
+
+    let stats = Stats::new();
+    let tracker = UserIpTracker::new();
+
+    let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+    let alice = users
+        .iter()
+        .find(|entry| entry.username == "alice")
+        .expect("alice must be present");
+    assert!(!alice.in_runtime);
+    assert_eq!(alice.max_tcp_conns, Some(7));
+
+    cfg.access.user_max_tcp_conns.insert("alice".to_string(), 5);
+    let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+    let alice = users
+        .iter()
+        .find(|entry| entry.username == "alice")
+        .expect("alice must be present");
+    assert!(!alice.in_runtime);
+    assert_eq!(alice.max_tcp_conns, Some(5));
+
+    cfg.access.user_max_tcp_conns.insert("alice".to_string(), 0);
+    let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+    let alice = users
+        .iter()
+        .find(|entry| entry.username == "alice")
+        .expect("alice must be present");
+    assert!(!alice.in_runtime);
+    assert_eq!(alice.max_tcp_conns, Some(7));
+
+    cfg.access.user_max_tcp_conns_global_each = 0;
+    let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+    let alice = users
+        .iter()
+        .find(|entry| entry.username == "alice")
+        .expect("alice must be present");
+    assert!(!alice.in_runtime);
+    assert_eq!(alice.max_tcp_conns, None);
+}
+
+#[tokio::test]
+async fn users_from_config_reports_user_rate_limits() {
+    let mut cfg = ProxyConfig::default();
+    cfg.access.users.insert(
+        "alice".to_string(),
+        "0123456789abcdef0123456789abcdef".to_string(),
+    );
+    cfg.access.user_rate_limits.insert(
+        "alice".to_string(),
+        RateLimitBps {
+            up_bps: 1024,
+            down_bps: 0,
+        },
+    );
+
+    let stats = Stats::new();
+    let tracker = UserIpTracker::new();
+
+    let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+    let alice = users
+        .iter()
+        .find(|entry| entry.username == "alice")
+        .expect("alice must be present");
+
+    assert_eq!(alice.rate_limit_up_bps, Some(1024));
+    assert_eq!(alice.rate_limit_down_bps, None);
+}
+
+#[tokio::test]
+async fn users_from_config_reports_user_enabled_default_and_override() {
+    let mut cfg = ProxyConfig::default();
+    cfg.access.users.insert(
+        "alice".to_string(),
+        "0123456789abcdef0123456789abcdef".to_string(),
+    );
+    cfg.access.users.insert(
+        "bob".to_string(),
+        "fedcba9876543210fedcba9876543210".to_string(),
+    );
+    cfg.access.user_enabled.insert("bob".to_string(), false);
+
+    let stats = Stats::new();
+    let tracker = UserIpTracker::new();
+    let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+    let alice = users
+        .iter()
+        .find(|entry| entry.username == "alice")
+        .expect("alice must be present");
+    let bob = users
+        .iter()
+        .find(|entry| entry.username == "bob")
+        .expect("bob must be present");
+
+    assert!(alice.enabled);
+    assert!(!bob.enabled);
+
+    cfg.access.user_enabled.insert("bob".to_string(), true);
+    let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+    let bob = users
+        .iter()
+        .find(|entry| entry.username == "bob")
+        .expect("bob must be present");
+    assert!(bob.enabled);
+}
+
+#[tokio::test]
+async fn users_from_config_marks_runtime_membership_when_snapshot_is_provided() {
+    let mut disk_cfg = ProxyConfig::default();
+    disk_cfg.access.users.insert(
+        "alice".to_string(),
+        "0123456789abcdef0123456789abcdef".to_string(),
+    );
+    disk_cfg.access.users.insert(
+        "bob".to_string(),
+        "fedcba9876543210fedcba9876543210".to_string(),
+    );
+
+    let mut runtime_cfg = ProxyConfig::default();
+    runtime_cfg.access.users.insert(
+        "alice".to_string(),
+        "0123456789abcdef0123456789abcdef".to_string(),
+    );
+
+    let stats = Stats::new();
+    let tracker = UserIpTracker::new();
+    let users =
+        users_from_config(&disk_cfg, &stats, &tracker, None, None, Some(&runtime_cfg)).await;
+
+    let alice = users
+        .iter()
+        .find(|entry| entry.username == "alice")
+        .expect("alice must be present");
+    let bob = users
+        .iter()
+        .find(|entry| entry.username == "bob")
+        .expect("bob must be present");
+
+    assert!(alice.in_runtime);
+    assert!(!bob.in_runtime);
+}
+
+#[tokio::test]
+async fn users_from_config_returns_tls_link_for_each_tls_domain() {
+    let mut cfg = ProxyConfig::default();
+    cfg.access.users.insert(
+        "alice".to_string(),
+        "0123456789abcdef0123456789abcdef".to_string(),
+    );
+    cfg.general.modes.classic = false;
+    cfg.general.modes.secure = false;
+    cfg.general.modes.tls = true;
+    cfg.general.links.public_host = Some("proxy.example.net".to_string());
+    cfg.general.links.public_port = Some(443);
+    cfg.censorship.tls_domain = "front-a.example.com".to_string();
+    cfg.censorship.tls_domains = vec![
+        "front-b.example.com".to_string(),
+        "front-c.example.com".to_string(),
+        "front-b.example.com".to_string(),
+        "front-a.example.com".to_string(),
+    ];
+
+    let stats = Stats::new();
+    let tracker = UserIpTracker::new();
+    let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+    let alice = users
+        .iter()
+        .find(|entry| entry.username == "alice")
+        .expect("alice must be present");
+
+    assert_eq!(alice.links.tls.len(), 3);
+    assert!(
+        alice
+            .links
+            .tls
+            .iter()
+            .any(|link| link.ends_with(&hex::encode("front-a.example.com")))
+    );
+    assert!(
+        alice
+            .links
+            .tls
+            .iter()
+            .any(|link| link.ends_with(&hex::encode("front-b.example.com")))
+    );
+    assert!(
+        alice
+            .links
+            .tls
+            .iter()
+            .any(|link| link.ends_with(&hex::encode("front-c.example.com")))
+    );
+    assert_eq!(alice.links.tls_domains.len(), 2);
+    assert!(
+        alice
+            .links
+            .tls_domains
+            .iter()
+            .any(|entry| entry.domain == "front-b.example.com"
+                && entry.link.ends_with(&hex::encode("front-b.example.com")))
+    );
+    assert!(
+        alice
+            .links
+            .tls_domains
+            .iter()
+            .any(|entry| entry.domain == "front-c.example.com"
+                && entry.link.ends_with(&hex::encode("front-c.example.com")))
+    );
+    assert!(
+        !alice
+            .links
+            .tls_domains
+            .iter()
+            .any(|entry| entry.domain == "front-a.example.com")
+    );
+}
+
+#[test]
+fn build_user_quota_list_skips_users_without_positive_quota_and_sorts_by_username() {
+    let mut cfg = ProxyConfig::default();
+    cfg.access.users.insert(
+        "alice".to_string(),
+        "0123456789abcdef0123456789abcdef".to_string(),
+    );
+    cfg.access.users.insert(
+        "bob".to_string(),
+        "fedcba9876543210fedcba9876543210".to_string(),
+    );
+    cfg.access.users.insert(
+        "carol".to_string(),
+        "aaaabbbbccccddddeeeeffff00001111".to_string(),
+    );
+    // alice has a positive quota and should be listed.
+    cfg.access
+        .user_data_quota
+        .insert("alice".to_string(), 1 << 20);
+    // bob has no quota entry at all (None) — should be skipped.
+    // carol has an explicit zero quota — should be skipped.
+    cfg.access.user_data_quota.insert("carol".to_string(), 0);
+
+    let stats = Stats::new();
+    // Charge some traffic against alice; carol gets traffic too but should
+    // still be filtered out by the quota check.
+    let alice_stats = stats.get_or_create_user_stats_handle("alice");
+    stats.quota_charge_post_write(&alice_stats, 4096);
+    let carol_stats = stats.get_or_create_user_stats_handle("carol");
+    stats.quota_charge_post_write(&carol_stats, 99);
+
+    let data = build_user_quota_list(&cfg, &stats);
+
+    assert_eq!(data.users.len(), 1);
+    let entry = &data.users[0];
+    assert_eq!(entry.username, "alice");
+    assert_eq!(entry.data_quota_bytes, 1 << 20);
+    assert_eq!(entry.used_bytes, 4096);
+    assert_eq!(entry.last_reset_epoch_secs, 0);
+}
+
+#[test]
+fn build_user_quota_list_orders_multiple_users_by_username_ascending() {
+    let mut cfg = ProxyConfig::default();
+    for name in ["charlie", "alice", "bob"] {
+        cfg.access.users.insert(
+            name.to_string(),
+            "0123456789abcdef0123456789abcdef".to_string(),
+        );
+        cfg.access.user_data_quota.insert(name.to_string(), 1 << 30);
+    }
+
+    let stats = Stats::new();
+    let data = build_user_quota_list(&cfg, &stats);
+
+    let names: Vec<&str> = data.users.iter().map(|e| e.username.as_str()).collect();
+    assert_eq!(names, vec!["alice", "bob", "charlie"]);
+    for entry in &data.users {
+        assert_eq!(entry.used_bytes, 0);
+        assert_eq!(entry.last_reset_epoch_secs, 0);
+        assert_eq!(entry.data_quota_bytes, 1 << 30);
+    }
+}

src/api/users/update.rs

@@ -0,0 +1,244 @@
+use super::*;
+
+pub(in crate::api) async fn patch_user(
+    user: &str,
+    body: PatchUserRequest,
+    expected_revision: Option<String>,
+    shared: &ApiShared,
+) -> Result<(UserInfo, String), ApiFailure> {
+    let touches_users = body.secret.is_some();
+    let touches_user_ad_tags = !matches!(&body.user_ad_tag, Patch::Unchanged);
+    let touches_user_max_tcp_conns = !matches!(&body.max_tcp_conns, Patch::Unchanged);
+    let touches_user_expirations = !matches!(&body.expiration_rfc3339, Patch::Unchanged);
+    let touches_user_data_quota = !matches!(&body.data_quota_bytes, Patch::Unchanged);
+    let touches_user_rate_limits = !matches!(&body.rate_limit_up_bps, Patch::Unchanged)
+        || !matches!(&body.rate_limit_down_bps, Patch::Unchanged);
+    let touches_user_max_unique_ips = !matches!(&body.max_unique_ips, Patch::Unchanged);
+    let touches_user_enabled = !matches!(&body.enabled, Patch::Unchanged);
+
+    if let Some(secret) = body.secret.as_ref()
+        && !is_valid_user_secret(secret)
+    {
+        return Err(ApiFailure::bad_request(
+            "secret must be exactly 32 hex characters",
+        ));
+    }
+    if let Patch::Set(ad_tag) = &body.user_ad_tag
+        && !is_valid_ad_tag(ad_tag)
+    {
+        return Err(ApiFailure::bad_request(
+            "user_ad_tag must be exactly 32 hex characters",
+        ));
+    }
+    let expiration = parse_patch_expiration(&body.expiration_rfc3339)?;
+    let _guard = shared.mutation_lock.lock().await;
+    let mut cfg = load_config_from_disk(&shared.config_path).await?;
+    ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
+
+    if !cfg.access.users.contains_key(user) {
+        return Err(ApiFailure::new(
+            StatusCode::NOT_FOUND,
+            "not_found",
+            "User not found",
+        ));
+    }
+
+    if let Some(secret) = body.secret {
+        cfg.access.users.insert(user.to_string(), secret);
+    }
+    match body.user_ad_tag {
+        Patch::Unchanged => {}
+        Patch::Remove => {
+            cfg.access.user_ad_tags.remove(user);
+        }
+        Patch::Set(ad_tag) => {
+            cfg.access.user_ad_tags.insert(user.to_string(), ad_tag);
+        }
+    }
+    match body.max_tcp_conns {
+        Patch::Unchanged => {}
+        Patch::Remove => {
+            cfg.access.user_max_tcp_conns.remove(user);
+        }
+        Patch::Set(limit) => {
+            cfg.access
+                .user_max_tcp_conns
+                .insert(user.to_string(), limit);
+        }
+    }
+    match expiration {
+        Patch::Unchanged => {}
+        Patch::Remove => {
+            cfg.access.user_expirations.remove(user);
+        }
+        Patch::Set(expiration) => {
+            cfg.access
+                .user_expirations
+                .insert(user.to_string(), expiration);
+        }
+    }
+    match body.data_quota_bytes {
+        Patch::Unchanged => {}
+        Patch::Remove => {
+            cfg.access.user_data_quota.remove(user);
+        }
+        Patch::Set(quota) => {
+            cfg.access.user_data_quota.insert(user.to_string(), quota);
+        }
+    }
+    if touches_user_rate_limits {
+        let mut rate_limit = cfg
+            .access
+            .user_rate_limits
+            .get(user)
+            .copied()
+            .unwrap_or_default();
+        match body.rate_limit_up_bps {
+            Patch::Unchanged => {}
+            Patch::Remove => rate_limit.up_bps = 0,
+            Patch::Set(limit) => rate_limit.up_bps = limit,
+        }
+        match body.rate_limit_down_bps {
+            Patch::Unchanged => {}
+            Patch::Remove => rate_limit.down_bps = 0,
+            Patch::Set(limit) => rate_limit.down_bps = limit,
+        }
+        if rate_limit.up_bps == 0 && rate_limit.down_bps == 0 {
+            cfg.access.user_rate_limits.remove(user);
+        } else {
+            cfg.access
+                .user_rate_limits
+                .insert(user.to_string(), rate_limit);
+        }
+    }
+    // Capture how the per-user IP limit changed, so the in-memory ip_tracker
+    // can be synced (set or removed) after the config is persisted.
+    let max_unique_ips_change = match body.max_unique_ips {
+        Patch::Unchanged => None,
+        Patch::Remove => {
+            cfg.access.user_max_unique_ips.remove(user);
+            Some(None)
+        }
+        Patch::Set(limit) => {
+            cfg.access
+                .user_max_unique_ips
+                .insert(user.to_string(), limit);
+            Some(Some(limit))
+        }
+    };
+    match body.enabled {
+        Patch::Unchanged => {}
+        Patch::Remove | Patch::Set(true) => {
+            cfg.access.user_enabled.remove(user);
+        }
+        Patch::Set(false) => {
+            cfg.access.user_enabled.insert(user.to_string(), false);
+        }
+    }
+
+    cfg.validate()
+        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
+
+    let mut touched_sections = Vec::new();
+    if touches_users {
+        touched_sections.push(AccessSection::Users);
+    }
+    if touches_user_ad_tags {
+        touched_sections.push(AccessSection::UserAdTags);
+    }
+    if touches_user_max_tcp_conns {
+        touched_sections.push(AccessSection::UserMaxTcpConns);
+    }
+    if touches_user_expirations {
+        touched_sections.push(AccessSection::UserExpirations);
+    }
+    if touches_user_data_quota {
+        touched_sections.push(AccessSection::UserDataQuota);
+    }
+    if touches_user_rate_limits {
+        touched_sections.push(AccessSection::UserRateLimits);
+    }
+    if touches_user_max_unique_ips {
+        touched_sections.push(AccessSection::UserMaxUniqueIps);
+    }
+    if touches_user_enabled {
+        touched_sections.push(AccessSection::UserEnabled);
+    }
+
+    let revision = if touched_sections.is_empty() {
+        current_revision(&shared.config_path).await?
+    } else {
+        save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?
+    };
+    drop(_guard);
+    match max_unique_ips_change {
+        Some(Some(limit)) => shared.ip_tracker.set_user_limit(user, limit).await,
+        Some(None) => shared.ip_tracker.remove_user_limit(user).await,
+        None => {}
+    }
+    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
+    let users = users_from_config(
+        &cfg,
+        &shared.stats,
+        &shared.ip_tracker,
+        detected_ip_v4,
+        detected_ip_v6,
+        None,
+    )
+    .await;
+    let user_info = users
+        .into_iter()
+        .find(|entry| entry.username == user)
+        .ok_or_else(|| ApiFailure::internal("failed to build updated user view"))?;
+
+    Ok((user_info, revision))
+}
+
+pub(in crate::api) async fn set_user_enabled(
+    user: &str,
+    enabled: bool,
+    expected_revision: Option<String>,
+    shared: &ApiShared,
+) -> Result<(UserInfo, String), ApiFailure> {
+    let _guard = shared.mutation_lock.lock().await;
+    let mut cfg = load_config_from_disk(&shared.config_path).await?;
+    ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
+
+    if !cfg.access.users.contains_key(user) {
+        return Err(ApiFailure::new(
+            StatusCode::NOT_FOUND,
+            "not_found",
+            "User not found",
+        ));
+    }
+
+    if enabled {
+        cfg.access.user_enabled.remove(user);
+    } else {
+        cfg.access.user_enabled.insert(user.to_string(), false);
+    }
+
+    cfg.validate()
+        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
+    let revision =
+        save_access_sections_to_disk(&shared.config_path, &cfg, &[AccessSection::UserEnabled])
+            .await?;
+    drop(_guard);
+
+    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
+    let users = users_from_config(
+        &cfg,
+        &shared.stats,
+        &shared.ip_tracker,
+        detected_ip_v4,
+        detected_ip_v6,
+        None,
+    )
+    .await;
+    let user_info = users
+        .into_iter()
+        .find(|entry| entry.username == user)
+        .ok_or_else(|| ApiFailure::internal("failed to build updated user view"))?;
+
+    Ok((user_info, revision))
+}

src/api/users/view.rs

@@ -0,0 +1,112 @@
+use super::*;
+
+pub(in crate::api) async fn users_from_config(
+    cfg: &ProxyConfig,
+    stats: &Stats,
+    ip_tracker: &UserIpTracker,
+    startup_detected_ip_v4: Option<IpAddr>,
+    startup_detected_ip_v6: Option<IpAddr>,
+    runtime_cfg: Option<&ProxyConfig>,
+) -> Vec<UserInfo> {
+    let mut names = cfg.access.users.keys().cloned().collect::<Vec<_>>();
+    names.sort();
+    let active_ip_lists = ip_tracker.get_active_ips_for_users(&names).await;
+    let recent_ip_lists = ip_tracker.get_recent_ips_for_users(&names).await;
+
+    let mut users = Vec::with_capacity(names.len());
+    for username in names {
+        let active_ip_list = active_ip_lists
+            .get(&username)
+            .cloned()
+            .unwrap_or_else(Vec::new);
+        let recent_ip_list = recent_ip_lists
+            .get(&username)
+            .cloned()
+            .unwrap_or_else(Vec::new);
+        let links = cfg
+            .access
+            .users
+            .get(&username)
+            .map(|secret| {
+                build_user_links(cfg, secret, startup_detected_ip_v4, startup_detected_ip_v6)
+            })
+            .unwrap_or_else(empty_user_links);
+        users.push(UserInfo {
+            enabled: cfg.access.is_user_enabled(&username),
+            in_runtime: runtime_cfg
+                .map(|runtime| runtime.access.users.contains_key(&username))
+                .unwrap_or(false),
+            user_ad_tag: cfg.access.user_ad_tags.get(&username).cloned(),
+            max_tcp_conns: cfg
+                .access
+                .user_max_tcp_conns
+                .get(&username)
+                .copied()
+                .filter(|limit| *limit > 0)
+                .or((cfg.access.user_max_tcp_conns_global_each > 0)
+                    .then_some(cfg.access.user_max_tcp_conns_global_each)),
+            expiration_rfc3339: cfg
+                .access
+                .user_expirations
+                .get(&username)
+                .map(chrono::DateTime::<chrono::Utc>::to_rfc3339),
+            data_quota_bytes: cfg.access.user_data_quota.get(&username).copied(),
+            rate_limit_up_bps: cfg
+                .access
+                .user_rate_limits
+                .get(&username)
+                .map(|limit| limit.up_bps)
+                .filter(|limit| *limit > 0),
+            rate_limit_down_bps: cfg
+                .access
+                .user_rate_limits
+                .get(&username)
+                .map(|limit| limit.down_bps)
+                .filter(|limit| *limit > 0),
+            max_unique_ips: cfg
+                .access
+                .user_max_unique_ips
+                .get(&username)
+                .copied()
+                .filter(|limit| *limit > 0)
+                .or((cfg.access.user_max_unique_ips_global_each > 0)
+                    .then_some(cfg.access.user_max_unique_ips_global_each)),
+            current_connections: stats.get_user_curr_connects(&username),
+            active_unique_ips: active_ip_list.len(),
+            active_unique_ips_list: active_ip_list,
+            recent_unique_ips: recent_ip_list.len(),
+            recent_unique_ips_list: recent_ip_list,
+            total_octets: stats.get_user_total_octets(&username),
+            links,
+            username,
+        });
+    }
+    users
+}
+
+pub(in crate::api) fn build_user_quota_list(cfg: &ProxyConfig, stats: &Stats) -> UserQuotaListData {
+    let mut names = cfg.access.users.keys().cloned().collect::<Vec<_>>();
+    names.sort();
+
+    let snapshot = stats.user_quota_snapshot();
+    let mut users = Vec::with_capacity(names.len());
+    for username in names {
+        let Some(&data_quota_bytes) = cfg.access.user_data_quota.get(&username) else {
+            continue;
+        };
+        if data_quota_bytes == 0 {
+            continue;
+        }
+        let (used_bytes, last_reset_epoch_secs) = snapshot
+            .get(&username)
+            .map(|entry| (entry.used_bytes, entry.last_reset_epoch_secs))
+            .unwrap_or((0, 0));
+        users.push(UserQuotaEntry {
+            username,
+            data_quota_bytes,
+            used_bytes,
+            last_reset_epoch_secs,
+        });
+    }
+    UserQuotaListData { users }
+}

src/cli.rs

@@ -6,12 +6,15 @@
 //! - `reload [--pid-file PATH]` - Reload configuration (SIGHUP)
 //! - `status [--pid-file PATH]` - Check daemon status
 //! - `run [OPTIONS] [config.toml]` - Run in foreground (default behavior)
+//! - `healthcheck [OPTIONS] [config.toml]` - Run control-plane health probe
 
 use rand::RngExt;
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::process::Command;
 
+use crate::healthcheck::{self, HealthcheckMode};
+
 #[cfg(unix)]
 use crate::daemon::{self, DEFAULT_PID_FILE, DaemonOptions};
 
@@ -28,6 +31,8 @@ pub enum Subcommand {
     Reload,
     /// Check daemon status (`status` subcommand).
     Status,
+    /// Run health probe and exit with status code.
+    Healthcheck,
     /// Fire-and-forget setup (`--init`).
     Init,
 }
@@ -38,6 +43,8 @@ pub struct ParsedCommand {
     pub subcommand: Subcommand,
     pub pid_file: PathBuf,
     pub config_path: String,
+    pub healthcheck_mode: HealthcheckMode,
+    pub healthcheck_mode_invalid: Option<String>,
     #[cfg(unix)]
     pub daemon_opts: DaemonOptions,
     pub init_opts: Option<InitOptions>,
@@ -52,6 +59,8 @@ impl Default for ParsedCommand {
             #[cfg(not(unix))]
             pid_file: PathBuf::from("/var/run/telemt.pid"),
             config_path: "config.toml".to_string(),
+            healthcheck_mode: HealthcheckMode::Liveness,
+            healthcheck_mode_invalid: None,
             #[cfg(unix)]
             daemon_opts: DaemonOptions::default(),
             init_opts: None,
@@ -91,6 +100,9 @@ pub fn parse_command(args: &[String]) -> ParsedCommand {
             "status" => {
                 cmd.subcommand = Subcommand::Status;
             }
+            "healthcheck" => {
+                cmd.subcommand = Subcommand::Healthcheck;
+            }
             "run" => {
                 cmd.subcommand = Subcommand::Run;
                 #[cfg(unix)]
@@ -113,7 +125,35 @@ pub fn parse_command(args: &[String]) -> ParsedCommand {
     while i < args.len() {
         match args[i].as_str() {
             // Skip subcommand names
-            "start" | "stop" | "reload" | "status" | "run" => {}
+            "start" | "stop" | "reload" | "status" | "run" | "healthcheck" => {}
+            "--mode" => {
+                i += 1;
+                if i < args.len() {
+                    match HealthcheckMode::from_cli_arg(&args[i]) {
+                        Some(mode) => {
+                            cmd.healthcheck_mode = mode;
+                            cmd.healthcheck_mode_invalid = None;
+                        }
+                        None => {
+                            cmd.healthcheck_mode_invalid = Some(args[i].clone());
+                        }
+                    }
+                } else {
+                    cmd.healthcheck_mode_invalid = Some(String::new());
+                }
+            }
+            s if s.starts_with("--mode=") => {
+                let raw = s.trim_start_matches("--mode=");
+                match HealthcheckMode::from_cli_arg(raw) {
+                    Some(mode) => {
+                        cmd.healthcheck_mode = mode;
+                        cmd.healthcheck_mode_invalid = None;
+                    }
+                    None => {
+                        cmd.healthcheck_mode_invalid = Some(raw.to_string());
+                    }
+                }
+            }
             // PID file option (for stop/reload/status)
             "--pid-file" => {
                 i += 1;
@@ -152,6 +192,20 @@ pub fn execute_subcommand(cmd: &ParsedCommand) -> Option<i32> {
         Subcommand::Stop => Some(cmd_stop(&cmd.pid_file)),
         Subcommand::Reload => Some(cmd_reload(&cmd.pid_file)),
         Subcommand::Status => Some(cmd_status(&cmd.pid_file)),
+        Subcommand::Healthcheck => {
+            if let Some(invalid_mode) = cmd.healthcheck_mode_invalid.as_ref() {
+                if invalid_mode.is_empty() {
+                    eprintln!("[telemt] Missing value for --mode (supported: liveness, ready)");
+                } else {
+                    eprintln!(
+                        "[telemt] Invalid --mode value '{invalid_mode}' (supported: liveness, ready)"
+                    );
+                }
+                Some(2)
+            } else {
+                Some(healthcheck::run(&cmd.config_path, cmd.healthcheck_mode))
+            }
+        }
         Subcommand::Init => {
             if let Some(opts) = cmd.init_opts.clone() {
                 match run_init(opts) {
@@ -177,6 +231,20 @@ pub fn execute_subcommand(cmd: &ParsedCommand) -> Option<i32> {
             eprintln!("[telemt] Subcommand not supported on this platform");
             Some(1)
         }
+        Subcommand::Healthcheck => {
+            if let Some(invalid_mode) = cmd.healthcheck_mode_invalid.as_ref() {
+                if invalid_mode.is_empty() {
+                    eprintln!("[telemt] Missing value for --mode (supported: liveness, ready)");
+                } else {
+                    eprintln!(
+                        "[telemt] Invalid --mode value '{invalid_mode}' (supported: liveness, ready)"
+                    );
+                }
+                Some(2)
+            } else {
+                Some(healthcheck::run(&cmd.config_path, cmd.healthcheck_mode))
+            }
+        }
         Subcommand::Init => {
             if let Some(opts) = cmd.init_opts.clone() {
                 match run_init(opts) {
@@ -598,16 +666,17 @@ secure = false
 tls = true
 
 [server]
-port = {port}
 listen_addr_ipv4 = "0.0.0.0"
 listen_addr_ipv6 = "::"
 
 [[server.listeners]]
 ip = "0.0.0.0"
+port = {port}
 # reuse_allow = false # Set true only when intentionally running multiple telemt instances on same port
 
 [[server.listeners]]
 ip = "::"
+port = {port}
 
 [timeouts]
 client_first_byte_idle_secs = 300
@@ -620,6 +689,7 @@ tls_domain = "{domain}"
 mask = true
 mask_port = 443
 fake_cert_len = 2048
+serverhello_compact = false
 tls_full_cert_ttl_secs = 90
 
 [access]
@@ -635,6 +705,9 @@ ignore_time_skew = false
 type = "direct"
 enabled = true
 weight = 10
+# Optional per-upstream DC family policy:
+# ipv6 = true
+# prefer = 6
 "#,
         username = username,
         secret = secret,

src/config/defaults.rs

@@ -21,7 +21,13 @@ const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_ACTIVE_WRITERS_PER_CORE: u16 = 64;
 const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_WARM_WRITERS_PER_CORE: u16 = 64;
 const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_ACTIVE_WRITERS_GLOBAL: u32 = 256;
 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;
@@ -33,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;
@@ -52,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 = 24;
+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;
@@ -100,7 +116,7 @@ pub(crate) fn default_fake_cert_len() -> usize {
 }
 
 pub(crate) fn default_tls_front_dir() -> String {
-    "/etc/telemt/tlsfront".to_string()
+    "tlsfront".to_string()
 }
 
 pub(crate) fn default_replay_check_len() -> usize {
@@ -241,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
 }
@@ -413,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
 }
@@ -457,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
 }
@@ -529,6 +593,14 @@ pub(crate) fn default_me_route_backpressure_base_timeout_ms() -> u64 {
     25
 }
 
+pub(crate) fn default_me_route_backpressure_enabled() -> bool {
+    DEFAULT_ME_ROUTE_BACKPRESSURE_ENABLED
+}
+
+pub(crate) fn default_me_route_fairshare_enabled() -> bool {
+    DEFAULT_ME_ROUTE_FAIRSHARE_ENABLED
+}
+
 pub(crate) fn default_me_route_backpressure_high_timeout_ms() -> u64 {
     120
 }
@@ -558,13 +630,17 @@ pub(crate) fn default_beobachten_flush_secs() -> u64 {
 }
 
 pub(crate) fn default_beobachten_file() -> String {
-    "/etc/telemt/beobachten.txt".to_string()
+    "beobachten.txt".to_string()
 }
 
 pub(crate) fn default_tls_new_session_tickets() -> u8 {
     0
 }
 
+pub(crate) fn default_serverhello_compact() -> bool {
+    false
+}
+
 pub(crate) fn default_tls_full_cert_ttl_secs() -> u64 {
     90
 }
@@ -615,6 +691,26 @@ pub(crate) fn default_mask_relay_max_bytes() -> usize {
     32 * 1024
 }
 
+#[cfg(not(test))]
+pub(crate) fn default_mask_relay_timeout_ms() -> u64 {
+    60_000
+}
+
+#[cfg(test)]
+pub(crate) fn default_mask_relay_timeout_ms() -> u64 {
+    200
+}
+
+#[cfg(not(test))]
+pub(crate) fn default_mask_relay_idle_timeout_ms() -> u64 {
+    5_000
+}
+
+#[cfg(test)]
+pub(crate) fn default_mask_relay_idle_timeout_ms() -> u64 {
+    100
+}
+
 pub(crate) fn default_mask_classifier_prefetch_timeout_ms() -> u64 {
     5
 }

src/config/hot_reload/diff.rs

@@ -0,0 +1,270 @@
+use super::*;
+
+fn canonicalize_json(value: &mut serde_json::Value) {
+    match value {
+        serde_json::Value::Object(map) => {
+            let mut pairs: Vec<(String, serde_json::Value)> =
+                std::mem::take(map).into_iter().collect();
+            pairs.sort_by(|a, b| a.0.cmp(&b.0));
+            for (_, item) in pairs.iter_mut() {
+                canonicalize_json(item);
+            }
+            for (key, item) in pairs {
+                map.insert(key, item);
+            }
+        }
+        serde_json::Value::Array(items) => {
+            for item in items {
+                canonicalize_json(item);
+            }
+        }
+        _ => {}
+    }
+}
+
+pub(super) fn config_equal(lhs: &ProxyConfig, rhs: &ProxyConfig) -> bool {
+    let mut left = match serde_json::to_value(lhs) {
+        Ok(value) => value,
+        Err(_) => return false,
+    };
+    let mut right = match serde_json::to_value(rhs) {
+        Ok(value) => value,
+        Err(_) => return false,
+    };
+    canonicalize_json(&mut left);
+    canonicalize_json(&mut right);
+    left == right
+}
+
+fn listeners_equal(
+    lhs: &[crate::config::ListenerConfig],
+    rhs: &[crate::config::ListenerConfig],
+) -> bool {
+    serde_json::to_value(lhs).ok() == serde_json::to_value(rhs).ok()
+}
+
+/// Warns when the requested snapshot contains fields that require restart.
+pub(super) fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: bool) {
+    let mut warned = false;
+    if old.server.port != new.server.port {
+        warned = true;
+        warn!(
+            "config reload: server.port changed ({} → {}); restart required",
+            old.server.port, new.server.port
+        );
+    }
+    if old.server.api.enabled != new.server.api.enabled
+        || old.server.api.listen != new.server.api.listen
+        || old.server.api.whitelist != new.server.api.whitelist
+        || old.server.api.gray_action != new.server.api.gray_action
+        || old.server.api.auth_header != new.server.api.auth_header
+        || old.server.api.request_body_limit_bytes != new.server.api.request_body_limit_bytes
+        || old.server.api.minimal_runtime_enabled != new.server.api.minimal_runtime_enabled
+        || old.server.api.minimal_runtime_cache_ttl_ms
+            != new.server.api.minimal_runtime_cache_ttl_ms
+        || old.server.api.runtime_edge_enabled != new.server.api.runtime_edge_enabled
+        || old.server.api.runtime_edge_cache_ttl_ms != new.server.api.runtime_edge_cache_ttl_ms
+        || old.server.api.runtime_edge_top_n != new.server.api.runtime_edge_top_n
+        || old.server.api.runtime_edge_events_capacity
+            != new.server.api.runtime_edge_events_capacity
+        || old.server.api.read_only != new.server.api.read_only
+    {
+        warned = true;
+        warn!("config reload: server.api changed; restart required");
+    }
+    if old.server.proxy_protocol != new.server.proxy_protocol
+        || !listeners_equal(&old.server.listeners, &new.server.listeners)
+        || old.server.listen_backlog != new.server.listen_backlog
+        || 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
+    {
+        warned = true;
+        warn!("config reload: server listener settings changed; restart required");
+    }
+    if old.censorship.tls_domain != new.censorship.tls_domain
+        || 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
+        || old.censorship.mask_unix_sock != new.censorship.mask_unix_sock
+        || old.censorship.fake_cert_len != new.censorship.fake_cert_len
+        || old.censorship.tls_emulation != new.censorship.tls_emulation
+        || old.censorship.tls_front_dir != new.censorship.tls_front_dir
+        || old.censorship.server_hello_delay_min_ms != new.censorship.server_hello_delay_min_ms
+        || old.censorship.server_hello_delay_max_ms != new.censorship.server_hello_delay_max_ms
+        || old.censorship.tls_new_session_tickets != new.censorship.tls_new_session_tickets
+        || old.censorship.serverhello_compact != new.censorship.serverhello_compact
+        || old.censorship.tls_full_cert_ttl_secs != new.censorship.tls_full_cert_ttl_secs
+        || old.censorship.alpn_enforce != new.censorship.alpn_enforce
+        || old.censorship.mask_proxy_protocol != new.censorship.mask_proxy_protocol
+        || old.censorship.mask_shape_hardening != new.censorship.mask_shape_hardening
+        || old.censorship.mask_shape_bucket_floor_bytes
+            != new.censorship.mask_shape_bucket_floor_bytes
+        || old.censorship.mask_shape_bucket_cap_bytes != new.censorship.mask_shape_bucket_cap_bytes
+        || old.censorship.mask_shape_above_cap_blur != new.censorship.mask_shape_above_cap_blur
+        || old.censorship.mask_shape_above_cap_blur_max_bytes
+            != new.censorship.mask_shape_above_cap_blur_max_bytes
+        || old.censorship.mask_relay_max_bytes != new.censorship.mask_relay_max_bytes
+        || old.censorship.mask_relay_timeout_ms != new.censorship.mask_relay_timeout_ms
+        || old.censorship.mask_relay_idle_timeout_ms != new.censorship.mask_relay_idle_timeout_ms
+        || old.censorship.mask_classifier_prefetch_timeout_ms
+            != new.censorship.mask_classifier_prefetch_timeout_ms
+        || old.censorship.mask_timing_normalization_enabled
+            != new.censorship.mask_timing_normalization_enabled
+        || old.censorship.mask_timing_normalization_floor_ms
+            != new.censorship.mask_timing_normalization_floor_ms
+        || old.censorship.mask_timing_normalization_ceiling_ms
+            != new.censorship.mask_timing_normalization_ceiling_ms
+    {
+        warned = true;
+        warn!("config reload: censorship settings changed; restart required");
+    }
+    if old.censorship.tls_domain != new.censorship.tls_domain {
+        warned = true;
+        warn!(
+            "config reload: censorship.tls_domain changed ('{}' → '{}'); restart required",
+            old.censorship.tls_domain, new.censorship.tls_domain
+        );
+    }
+    if old.network.ipv4 != new.network.ipv4 || old.network.ipv6 != new.network.ipv6 {
+        warned = true;
+        warn!("config reload: network.ipv4/ipv6 changed; restart required");
+    }
+    if old.network.prefer != new.network.prefer
+        || old.network.multipath != new.network.multipath
+        || old.network.stun_use != new.network.stun_use
+        || old.network.stun_servers != new.network.stun_servers
+        || old.network.stun_tcp_fallback != new.network.stun_tcp_fallback
+        || old.network.http_ip_detect_urls != new.network.http_ip_detect_urls
+        || old.network.cache_public_ip_path != new.network.cache_public_ip_path
+    {
+        warned = true;
+        warn!("config reload: non-hot network settings changed; restart required");
+    }
+    if old.general.use_middle_proxy != new.general.use_middle_proxy {
+        warned = true;
+        warn!("config reload: use_middle_proxy changed; restart required");
+    }
+    if old.general.stun_nat_probe_concurrency != new.general.stun_nat_probe_concurrency {
+        warned = true;
+        warn!("config reload: general.stun_nat_probe_concurrency changed; restart required");
+    }
+    if old.general.middle_proxy_pool_size != new.general.middle_proxy_pool_size {
+        warned = true;
+        warn!("config reload: general.middle_proxy_pool_size changed; restart required");
+    }
+    if old.general.me_route_no_writer_mode != new.general.me_route_no_writer_mode
+        || old.general.me_route_no_writer_wait_ms != new.general.me_route_no_writer_wait_ms
+        || old.general.me_route_hybrid_max_wait_ms != new.general.me_route_hybrid_max_wait_ms
+        || old.general.me_route_blocking_send_timeout_ms
+            != new.general.me_route_blocking_send_timeout_ms
+        || old.general.me_route_inline_recovery_attempts
+            != new.general.me_route_inline_recovery_attempts
+        || old.general.me_route_inline_recovery_wait_ms
+            != new.general.me_route_inline_recovery_wait_ms
+    {
+        warned = true;
+        warn!("config reload: general.me_route_no_writer_* changed; restart required");
+    }
+    if old.general.unknown_dc_log_path != new.general.unknown_dc_log_path
+        || old.general.unknown_dc_file_log_enabled != new.general.unknown_dc_file_log_enabled
+    {
+        warned = true;
+        warn!("config reload: general.unknown_dc_* changed; restart required");
+    }
+    if old.general.me_init_retry_attempts != new.general.me_init_retry_attempts {
+        warned = true;
+        warn!("config reload: general.me_init_retry_attempts changed; restart required");
+    }
+    if old.general.me2dc_fallback != new.general.me2dc_fallback
+        || old.general.me2dc_fast != new.general.me2dc_fast
+    {
+        warned = true;
+        warn!("config reload: general.me2dc_fallback/me2dc_fast changed; restart required");
+    }
+    if old.general.proxy_config_v4_cache_path != new.general.proxy_config_v4_cache_path
+        || old.general.proxy_config_v6_cache_path != new.general.proxy_config_v6_cache_path
+    {
+        warned = true;
+        warn!("config reload: general.proxy_config_*_cache_path changed; restart required");
+    }
+    if old.general.me_keepalive_enabled != new.general.me_keepalive_enabled
+        || old.general.me_keepalive_interval_secs != new.general.me_keepalive_interval_secs
+        || old.general.me_keepalive_jitter_secs != new.general.me_keepalive_jitter_secs
+        || old.general.me_keepalive_payload_random != new.general.me_keepalive_payload_random
+    {
+        warned = true;
+        warn!("config reload: general.me_keepalive_* changed; restart required");
+    }
+    if old.general.upstream_connect_retry_attempts != new.general.upstream_connect_retry_attempts
+        || old.general.upstream_connect_retry_backoff_ms
+            != new.general.upstream_connect_retry_backoff_ms
+        || old.general.tg_connect != new.general.tg_connect
+        || old.general.upstream_unhealthy_fail_threshold
+            != new.general.upstream_unhealthy_fail_threshold
+        || old.general.upstream_connect_failfast_hard_errors
+            != new.general.upstream_connect_failfast_hard_errors
+        || old.general.rpc_proxy_req_every != new.general.rpc_proxy_req_every
+    {
+        warned = true;
+        warn!("config reload: general.upstream_* changed; restart required");
+    }
+    if non_hot_changed && !warned {
+        warn!("config reload: one or more non-hot fields changed; restart required");
+    }
+}
+
+/// Resolve the public host for link generation — mirrors the logic in main.rs.
+///
+/// Priority:
+/// 1. `[general.links] public_host` — explicit override in config
+/// 2. `detected_ip_v4` — from STUN/interface probe at startup
+/// 3. `detected_ip_v6` — fallback
+/// 4. `"UNKNOWN"` — warn the user to set `public_host`
+
+/// 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
+}

src/config/hot_reload/fields.rs

@@ -0,0 +1,351 @@
+use super::*;
+
+/// Fields that are safe to swap without restarting listeners.
+#[derive(Debug, Clone, PartialEq)]
+pub struct HotFields {
+    pub log_level: LogLevel,
+    pub ad_tag: Option<String>,
+    pub dns_overrides: Vec<String>,
+    pub desync_all_full: bool,
+    pub update_every_secs: u64,
+    pub me_reinit_every_secs: u64,
+    pub me_reinit_singleflight: bool,
+    pub me_reinit_coalesce_window_ms: u64,
+    pub hardswap: bool,
+    pub me_pool_drain_ttl_secs: u64,
+    pub me_instadrain: bool,
+    pub me_pool_drain_threshold: u64,
+    pub me_pool_min_fresh_ratio: f32,
+    pub me_reinit_drain_timeout_secs: u64,
+    pub me_hardswap_warmup_delay_min_ms: u64,
+    pub me_hardswap_warmup_delay_max_ms: u64,
+    pub me_hardswap_warmup_extra_passes: u8,
+    pub me_hardswap_warmup_pass_backoff_base_ms: u64,
+    pub me_bind_stale_mode: MeBindStaleMode,
+    pub me_bind_stale_ttl_secs: u64,
+    pub me_secret_atomic_snapshot: bool,
+    pub me_deterministic_writer_sort: bool,
+    pub me_writer_pick_mode: MeWriterPickMode,
+    pub me_writer_pick_sample_size: u8,
+    pub me_single_endpoint_shadow_writers: u8,
+    pub me_single_endpoint_outage_mode_enabled: bool,
+    pub me_single_endpoint_outage_disable_quarantine: bool,
+    pub me_single_endpoint_outage_backoff_min_ms: u64,
+    pub me_single_endpoint_outage_backoff_max_ms: u64,
+    pub me_single_endpoint_shadow_rotate_every_secs: u64,
+    pub me_config_stable_snapshots: u8,
+    pub me_config_apply_cooldown_secs: u64,
+    pub me_snapshot_require_http_2xx: bool,
+    pub me_snapshot_reject_empty_map: bool,
+    pub me_snapshot_min_proxy_for_lines: u32,
+    pub proxy_secret_stable_snapshots: u8,
+    pub proxy_secret_rotate_runtime: bool,
+    pub proxy_secret_len_max: usize,
+    pub telemetry_core_enabled: bool,
+    pub telemetry_user_enabled: bool,
+    pub telemetry_me_level: MeTelemetryLevel,
+    pub me_socks_kdf_policy: MeSocksKdfPolicy,
+    pub me_route_backpressure_enabled: bool,
+    pub me_route_fairshare_enabled: bool,
+    pub me_floor_mode: MeFloorMode,
+    pub me_adaptive_floor_idle_secs: u64,
+    pub me_adaptive_floor_min_writers_single_endpoint: u8,
+    pub me_adaptive_floor_min_writers_multi_endpoint: u8,
+    pub me_adaptive_floor_recover_grace_secs: u64,
+    pub me_adaptive_floor_writers_per_core_total: u16,
+    pub me_adaptive_floor_cpu_cores_override: u16,
+    pub me_adaptive_floor_max_extra_writers_single_per_core: u16,
+    pub me_adaptive_floor_max_extra_writers_multi_per_core: u16,
+    pub me_adaptive_floor_max_active_writers_per_core: u16,
+    pub me_adaptive_floor_max_warm_writers_per_core: u16,
+    pub me_adaptive_floor_max_active_writers_global: u32,
+    pub me_adaptive_floor_max_warm_writers_global: u32,
+    pub me_route_backpressure_base_timeout_ms: u64,
+    pub me_route_backpressure_high_timeout_ms: u64,
+    pub me_route_backpressure_high_watermark_pct: u8,
+    pub me_reader_route_data_wait_ms: u64,
+    pub me_d2c_flush_batch_max_frames: usize,
+    pub me_d2c_flush_batch_max_bytes: usize,
+    pub me_d2c_flush_batch_max_delay_us: u64,
+    pub me_d2c_ack_flush_immediate: bool,
+    pub me_quota_soft_overshoot_bytes: u64,
+    pub me_d2c_frame_buf_shrink_threshold_bytes: usize,
+    pub direct_relay_copy_buf_c2s_bytes: usize,
+    pub direct_relay_copy_buf_s2c_bytes: usize,
+    pub me_health_interval_ms_unhealthy: u64,
+    pub me_health_interval_ms_healthy: u64,
+    pub me_admission_poll_ms: u64,
+    pub me_warn_rate_limit_ms: u64,
+    pub users: std::collections::HashMap<String, String>,
+    pub user_enabled: std::collections::HashMap<String, bool>,
+    pub user_ad_tags: std::collections::HashMap<String, String>,
+    pub user_max_tcp_conns: std::collections::HashMap<String, usize>,
+    pub user_max_tcp_conns_global_each: usize,
+    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<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,
+}
+
+impl HotFields {
+    pub fn from_config(cfg: &ProxyConfig) -> Self {
+        Self {
+            log_level: cfg.general.log_level.clone(),
+            ad_tag: cfg.general.ad_tag.clone(),
+            dns_overrides: cfg.network.dns_overrides.clone(),
+            desync_all_full: cfg.general.desync_all_full,
+            update_every_secs: cfg.general.effective_update_every_secs(),
+            me_reinit_every_secs: cfg.general.me_reinit_every_secs,
+            me_reinit_singleflight: cfg.general.me_reinit_singleflight,
+            me_reinit_coalesce_window_ms: cfg.general.me_reinit_coalesce_window_ms,
+            hardswap: cfg.general.hardswap,
+            me_pool_drain_ttl_secs: cfg.general.me_pool_drain_ttl_secs,
+            me_instadrain: cfg.general.me_instadrain,
+            me_pool_drain_threshold: cfg.general.me_pool_drain_threshold,
+            me_pool_min_fresh_ratio: cfg.general.me_pool_min_fresh_ratio,
+            me_reinit_drain_timeout_secs: cfg.general.me_reinit_drain_timeout_secs,
+            me_hardswap_warmup_delay_min_ms: cfg.general.me_hardswap_warmup_delay_min_ms,
+            me_hardswap_warmup_delay_max_ms: cfg.general.me_hardswap_warmup_delay_max_ms,
+            me_hardswap_warmup_extra_passes: cfg.general.me_hardswap_warmup_extra_passes,
+            me_hardswap_warmup_pass_backoff_base_ms: cfg
+                .general
+                .me_hardswap_warmup_pass_backoff_base_ms,
+            me_bind_stale_mode: cfg.general.me_bind_stale_mode,
+            me_bind_stale_ttl_secs: cfg.general.me_bind_stale_ttl_secs,
+            me_secret_atomic_snapshot: cfg.general.me_secret_atomic_snapshot,
+            me_deterministic_writer_sort: cfg.general.me_deterministic_writer_sort,
+            me_writer_pick_mode: cfg.general.me_writer_pick_mode,
+            me_writer_pick_sample_size: cfg.general.me_writer_pick_sample_size,
+            me_single_endpoint_shadow_writers: cfg.general.me_single_endpoint_shadow_writers,
+            me_single_endpoint_outage_mode_enabled: cfg
+                .general
+                .me_single_endpoint_outage_mode_enabled,
+            me_single_endpoint_outage_disable_quarantine: cfg
+                .general
+                .me_single_endpoint_outage_disable_quarantine,
+            me_single_endpoint_outage_backoff_min_ms: cfg
+                .general
+                .me_single_endpoint_outage_backoff_min_ms,
+            me_single_endpoint_outage_backoff_max_ms: cfg
+                .general
+                .me_single_endpoint_outage_backoff_max_ms,
+            me_single_endpoint_shadow_rotate_every_secs: cfg
+                .general
+                .me_single_endpoint_shadow_rotate_every_secs,
+            me_config_stable_snapshots: cfg.general.me_config_stable_snapshots,
+            me_config_apply_cooldown_secs: cfg.general.me_config_apply_cooldown_secs,
+            me_snapshot_require_http_2xx: cfg.general.me_snapshot_require_http_2xx,
+            me_snapshot_reject_empty_map: cfg.general.me_snapshot_reject_empty_map,
+            me_snapshot_min_proxy_for_lines: cfg.general.me_snapshot_min_proxy_for_lines,
+            proxy_secret_stable_snapshots: cfg.general.proxy_secret_stable_snapshots,
+            proxy_secret_rotate_runtime: cfg.general.proxy_secret_rotate_runtime,
+            proxy_secret_len_max: cfg.general.proxy_secret_len_max,
+            telemetry_core_enabled: cfg.general.telemetry.core_enabled,
+            telemetry_user_enabled: cfg.general.telemetry.user_enabled,
+            telemetry_me_level: cfg.general.telemetry.me_level,
+            me_socks_kdf_policy: cfg.general.me_socks_kdf_policy,
+            me_route_backpressure_enabled: cfg.general.me_route_backpressure_enabled,
+            me_route_fairshare_enabled: cfg.general.me_route_fairshare_enabled,
+            me_floor_mode: cfg.general.me_floor_mode,
+            me_adaptive_floor_idle_secs: cfg.general.me_adaptive_floor_idle_secs,
+            me_adaptive_floor_min_writers_single_endpoint: cfg
+                .general
+                .me_adaptive_floor_min_writers_single_endpoint,
+            me_adaptive_floor_min_writers_multi_endpoint: cfg
+                .general
+                .me_adaptive_floor_min_writers_multi_endpoint,
+            me_adaptive_floor_recover_grace_secs: cfg.general.me_adaptive_floor_recover_grace_secs,
+            me_adaptive_floor_writers_per_core_total: cfg
+                .general
+                .me_adaptive_floor_writers_per_core_total,
+            me_adaptive_floor_cpu_cores_override: cfg.general.me_adaptive_floor_cpu_cores_override,
+            me_adaptive_floor_max_extra_writers_single_per_core: cfg
+                .general
+                .me_adaptive_floor_max_extra_writers_single_per_core,
+            me_adaptive_floor_max_extra_writers_multi_per_core: cfg
+                .general
+                .me_adaptive_floor_max_extra_writers_multi_per_core,
+            me_adaptive_floor_max_active_writers_per_core: cfg
+                .general
+                .me_adaptive_floor_max_active_writers_per_core,
+            me_adaptive_floor_max_warm_writers_per_core: cfg
+                .general
+                .me_adaptive_floor_max_warm_writers_per_core,
+            me_adaptive_floor_max_active_writers_global: cfg
+                .general
+                .me_adaptive_floor_max_active_writers_global,
+            me_adaptive_floor_max_warm_writers_global: cfg
+                .general
+                .me_adaptive_floor_max_warm_writers_global,
+            me_route_backpressure_base_timeout_ms: cfg
+                .general
+                .me_route_backpressure_base_timeout_ms,
+            me_route_backpressure_high_timeout_ms: cfg
+                .general
+                .me_route_backpressure_high_timeout_ms,
+            me_route_backpressure_high_watermark_pct: cfg
+                .general
+                .me_route_backpressure_high_watermark_pct,
+            me_reader_route_data_wait_ms: cfg.general.me_reader_route_data_wait_ms,
+            me_d2c_flush_batch_max_frames: cfg.general.me_d2c_flush_batch_max_frames,
+            me_d2c_flush_batch_max_bytes: cfg.general.me_d2c_flush_batch_max_bytes,
+            me_d2c_flush_batch_max_delay_us: cfg.general.me_d2c_flush_batch_max_delay_us,
+            me_d2c_ack_flush_immediate: cfg.general.me_d2c_ack_flush_immediate,
+            me_quota_soft_overshoot_bytes: cfg.general.me_quota_soft_overshoot_bytes,
+            me_d2c_frame_buf_shrink_threshold_bytes: cfg
+                .general
+                .me_d2c_frame_buf_shrink_threshold_bytes,
+            direct_relay_copy_buf_c2s_bytes: cfg.general.direct_relay_copy_buf_c2s_bytes,
+            direct_relay_copy_buf_s2c_bytes: cfg.general.direct_relay_copy_buf_s2c_bytes,
+            me_health_interval_ms_unhealthy: cfg.general.me_health_interval_ms_unhealthy,
+            me_health_interval_ms_healthy: cfg.general.me_health_interval_ms_healthy,
+            me_admission_poll_ms: cfg.general.me_admission_poll_ms,
+            me_warn_rate_limit_ms: cfg.general.me_warn_rate_limit_ms,
+            users: cfg.access.users.clone(),
+            user_enabled: cfg.access.user_enabled.clone(),
+            user_ad_tags: cfg.access.user_ad_tags.clone(),
+            user_max_tcp_conns: cfg.access.user_max_tcp_conns.clone(),
+            user_max_tcp_conns_global_each: cfg.access.user_max_tcp_conns_global_each,
+            user_expirations: cfg.access.user_expirations.clone(),
+            user_data_quota: cfg.access.user_data_quota.clone(),
+            user_rate_limits: cfg.access.user_rate_limits.clone(),
+            cidr_rate_limits: cfg.access.cidr_rate_limits.clone(),
+            user_max_unique_ips: cfg.access.user_max_unique_ips.clone(),
+            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,
+        }
+    }
+}
+
+pub(super) fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
+    let mut cfg = old.clone();
+
+    cfg.general.log_level = new.general.log_level.clone();
+    cfg.general.ad_tag = new.general.ad_tag.clone();
+    cfg.network.dns_overrides = new.network.dns_overrides.clone();
+    cfg.general.desync_all_full = new.general.desync_all_full;
+    cfg.general.update_every = new.general.update_every;
+    cfg.general.proxy_secret_auto_reload_secs = new.general.proxy_secret_auto_reload_secs;
+    cfg.general.proxy_config_auto_reload_secs = new.general.proxy_config_auto_reload_secs;
+    cfg.general.me_reinit_every_secs = new.general.me_reinit_every_secs;
+    cfg.general.me_reinit_singleflight = new.general.me_reinit_singleflight;
+    cfg.general.me_reinit_coalesce_window_ms = new.general.me_reinit_coalesce_window_ms;
+    cfg.general.hardswap = new.general.hardswap;
+    cfg.general.me_pool_drain_ttl_secs = new.general.me_pool_drain_ttl_secs;
+    cfg.general.me_instadrain = new.general.me_instadrain;
+    cfg.general.me_pool_drain_threshold = new.general.me_pool_drain_threshold;
+    cfg.general.me_pool_min_fresh_ratio = new.general.me_pool_min_fresh_ratio;
+    cfg.general.me_reinit_drain_timeout_secs = new.general.me_reinit_drain_timeout_secs;
+    cfg.general.me_hardswap_warmup_delay_min_ms = new.general.me_hardswap_warmup_delay_min_ms;
+    cfg.general.me_hardswap_warmup_delay_max_ms = new.general.me_hardswap_warmup_delay_max_ms;
+    cfg.general.me_hardswap_warmup_extra_passes = new.general.me_hardswap_warmup_extra_passes;
+    cfg.general.me_hardswap_warmup_pass_backoff_base_ms =
+        new.general.me_hardswap_warmup_pass_backoff_base_ms;
+    cfg.general.me_bind_stale_mode = new.general.me_bind_stale_mode;
+    cfg.general.me_bind_stale_ttl_secs = new.general.me_bind_stale_ttl_secs;
+    cfg.general.me_secret_atomic_snapshot = new.general.me_secret_atomic_snapshot;
+    cfg.general.me_deterministic_writer_sort = new.general.me_deterministic_writer_sort;
+    cfg.general.me_writer_pick_mode = new.general.me_writer_pick_mode;
+    cfg.general.me_writer_pick_sample_size = new.general.me_writer_pick_sample_size;
+    cfg.general.me_single_endpoint_shadow_writers = new.general.me_single_endpoint_shadow_writers;
+    cfg.general.me_single_endpoint_outage_mode_enabled =
+        new.general.me_single_endpoint_outage_mode_enabled;
+    cfg.general.me_single_endpoint_outage_disable_quarantine =
+        new.general.me_single_endpoint_outage_disable_quarantine;
+    cfg.general.me_single_endpoint_outage_backoff_min_ms =
+        new.general.me_single_endpoint_outage_backoff_min_ms;
+    cfg.general.me_single_endpoint_outage_backoff_max_ms =
+        new.general.me_single_endpoint_outage_backoff_max_ms;
+    cfg.general.me_single_endpoint_shadow_rotate_every_secs =
+        new.general.me_single_endpoint_shadow_rotate_every_secs;
+    cfg.general.me_config_stable_snapshots = new.general.me_config_stable_snapshots;
+    cfg.general.me_config_apply_cooldown_secs = new.general.me_config_apply_cooldown_secs;
+    cfg.general.me_snapshot_require_http_2xx = new.general.me_snapshot_require_http_2xx;
+    cfg.general.me_snapshot_reject_empty_map = new.general.me_snapshot_reject_empty_map;
+    cfg.general.me_snapshot_min_proxy_for_lines = new.general.me_snapshot_min_proxy_for_lines;
+    cfg.general.proxy_secret_stable_snapshots = new.general.proxy_secret_stable_snapshots;
+    cfg.general.proxy_secret_rotate_runtime = new.general.proxy_secret_rotate_runtime;
+    cfg.general.proxy_secret_len_max = new.general.proxy_secret_len_max;
+    cfg.general.telemetry = new.general.telemetry.clone();
+    cfg.general.me_socks_kdf_policy = new.general.me_socks_kdf_policy;
+    cfg.general.me_floor_mode = new.general.me_floor_mode;
+    cfg.general.me_adaptive_floor_idle_secs = new.general.me_adaptive_floor_idle_secs;
+    cfg.general.me_adaptive_floor_min_writers_single_endpoint =
+        new.general.me_adaptive_floor_min_writers_single_endpoint;
+    cfg.general.me_adaptive_floor_min_writers_multi_endpoint =
+        new.general.me_adaptive_floor_min_writers_multi_endpoint;
+    cfg.general.me_adaptive_floor_recover_grace_secs =
+        new.general.me_adaptive_floor_recover_grace_secs;
+    cfg.general.me_adaptive_floor_writers_per_core_total =
+        new.general.me_adaptive_floor_writers_per_core_total;
+    cfg.general.me_adaptive_floor_cpu_cores_override =
+        new.general.me_adaptive_floor_cpu_cores_override;
+    cfg.general
+        .me_adaptive_floor_max_extra_writers_single_per_core = new
+        .general
+        .me_adaptive_floor_max_extra_writers_single_per_core;
+    cfg.general
+        .me_adaptive_floor_max_extra_writers_multi_per_core = new
+        .general
+        .me_adaptive_floor_max_extra_writers_multi_per_core;
+    cfg.general.me_adaptive_floor_max_active_writers_per_core =
+        new.general.me_adaptive_floor_max_active_writers_per_core;
+    cfg.general.me_adaptive_floor_max_warm_writers_per_core =
+        new.general.me_adaptive_floor_max_warm_writers_per_core;
+    cfg.general.me_adaptive_floor_max_active_writers_global =
+        new.general.me_adaptive_floor_max_active_writers_global;
+    cfg.general.me_adaptive_floor_max_warm_writers_global =
+        new.general.me_adaptive_floor_max_warm_writers_global;
+    cfg.general.me_route_backpressure_base_timeout_ms =
+        new.general.me_route_backpressure_base_timeout_ms;
+    cfg.general.me_route_backpressure_high_timeout_ms =
+        new.general.me_route_backpressure_high_timeout_ms;
+    cfg.general.me_route_backpressure_high_watermark_pct =
+        new.general.me_route_backpressure_high_watermark_pct;
+    cfg.general.me_route_backpressure_enabled = new.general.me_route_backpressure_enabled;
+    cfg.general.me_route_fairshare_enabled = new.general.me_route_fairshare_enabled;
+    cfg.general.me_reader_route_data_wait_ms = new.general.me_reader_route_data_wait_ms;
+    cfg.general.me_d2c_flush_batch_max_frames = new.general.me_d2c_flush_batch_max_frames;
+    cfg.general.me_d2c_flush_batch_max_bytes = new.general.me_d2c_flush_batch_max_bytes;
+    cfg.general.me_d2c_flush_batch_max_delay_us = new.general.me_d2c_flush_batch_max_delay_us;
+    cfg.general.me_d2c_ack_flush_immediate = new.general.me_d2c_ack_flush_immediate;
+    cfg.general.me_quota_soft_overshoot_bytes = new.general.me_quota_soft_overshoot_bytes;
+    cfg.general.me_d2c_frame_buf_shrink_threshold_bytes =
+        new.general.me_d2c_frame_buf_shrink_threshold_bytes;
+    cfg.general.direct_relay_copy_buf_c2s_bytes = new.general.direct_relay_copy_buf_c2s_bytes;
+    cfg.general.direct_relay_copy_buf_s2c_bytes = new.general.direct_relay_copy_buf_s2c_bytes;
+    cfg.general.me_health_interval_ms_unhealthy = new.general.me_health_interval_ms_unhealthy;
+    cfg.general.me_health_interval_ms_healthy = new.general.me_health_interval_ms_healthy;
+    cfg.general.me_admission_poll_ms = new.general.me_admission_poll_ms;
+    cfg.general.me_warn_rate_limit_ms = new.general.me_warn_rate_limit_ms;
+
+    cfg.access.users = new.access.users.clone();
+    cfg.access.user_enabled = new.access.user_enabled.clone();
+    cfg.access.user_ad_tags = new.access.user_ad_tags.clone();
+    cfg.access.user_max_tcp_conns = new.access.user_max_tcp_conns.clone();
+    cfg.access.user_max_tcp_conns_global_each = new.access.user_max_tcp_conns_global_each;
+    cfg.access.user_expirations = new.access.user_expirations.clone();
+    cfg.access.user_data_quota = new.access.user_data_quota.clone();
+    cfg.access.user_rate_limits = new.access.user_rate_limits.clone();
+    cfg.access.cidr_rate_limits = new.access.cidr_rate_limits.clone();
+    cfg.access.user_max_unique_ips = new.access.user_max_unique_ips.clone();
+    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;
+    let process_limits = cfg.web.limits.clone();
+    cfg.web = new.web.clone();
+    cfg.web.limits = process_limits;
+    if cfg.rebuild_runtime_user_auth().is_err() {
+        cfg.runtime_user_auth = None;
+    }
+    if cfg.rebuild_runtime_web().is_err() {
+        cfg.web = old.web.clone();
+    }
+
+    cfg
+}

src/config/hot_reload/reporting.rs

@@ -0,0 +1,499 @@
+use super::*;
+
+fn resolve_default_link_port(cfg: &ProxyConfig) -> u16 {
+    cfg.server
+        .listeners
+        .first()
+        .and_then(|listener| listener.port)
+        .unwrap_or(cfg.server.port)
+}
+
+fn resolve_link_host(
+    cfg: &ProxyConfig,
+    detected_ip_v4: Option<IpAddr>,
+    detected_ip_v6: Option<IpAddr>,
+) -> String {
+    if let Some(ref h) = cfg.general.links.public_host {
+        return h.clone();
+    }
+    detected_ip_v4
+        .or(detected_ip_v6)
+        .map(|ip| ip.to_string())
+        .unwrap_or_else(|| {
+            warn!(
+                "config reload: could not determine public IP for proxy links. \
+                 Set [general.links] public_host in config."
+            );
+            "UNKNOWN".to_string()
+        })
+}
+
+/// Print TG proxy links for a single user — mirrors print_proxy_links() in main.rs.
+fn print_user_links(user: &str, secret: &str, host: &str, port: u16, cfg: &ProxyConfig) {
+    info!(target: "telemt::links", "--- New user: {} ---", user);
+    if cfg.general.modes.classic {
+        info!(
+            target: "telemt::links",
+            "  Classic: tg://proxy?server={}&port={}&secret={}",
+            host, port, secret
+        );
+    }
+    if cfg.general.modes.secure {
+        info!(
+            target: "telemt::links",
+            "  DD:      tg://proxy?server={}&port={}&secret=dd{}",
+            host, port, secret
+        );
+    }
+    if cfg.general.modes.tls {
+        let mut domains = vec![cfg.censorship.tls_domain.clone()];
+        for d in &cfg.censorship.tls_domains {
+            if !domains.contains(d) {
+                domains.push(d.clone());
+            }
+        }
+        for domain in &domains {
+            let domain_hex = hex::encode(domain.as_bytes());
+            info!(
+                target: "telemt::links",
+                "  EE-TLS:  tg://proxy?server={}&port={}&secret=ee{}{}",
+                host, port, secret, domain_hex
+            );
+        }
+    }
+    info!(target: "telemt::links", "--------------------");
+}
+
+/// Log all detected changes and emit TG links for new users.
+pub(super) fn log_changes(
+    old_hot: &HotFields,
+    new_hot: &HotFields,
+    new_cfg: &ProxyConfig,
+    log_tx: &watch::Sender<LogLevel>,
+    detected_ip_v4: Option<IpAddr>,
+    detected_ip_v6: Option<IpAddr>,
+) {
+    if old_hot.log_level != new_hot.log_level {
+        info!(
+            "config reload: log_level: '{}' → '{}'",
+            old_hot.log_level, new_hot.log_level
+        );
+        log_tx.send(new_hot.log_level.clone()).ok();
+    }
+
+    if old_hot.user_ad_tags != new_hot.user_ad_tags {
+        info!(
+            "config reload: user_ad_tags updated ({} entries)",
+            new_hot.user_ad_tags.len(),
+        );
+    }
+
+    if old_hot.ad_tag != new_hot.ad_tag {
+        info!("config reload: general.ad_tag updated (applied on next connection)");
+    }
+
+    if old_hot.dns_overrides != new_hot.dns_overrides {
+        info!(
+            "config reload: network.dns_overrides updated ({} entries)",
+            new_hot.dns_overrides.len()
+        );
+    }
+
+    if old_hot.desync_all_full != new_hot.desync_all_full {
+        info!(
+            "config reload: desync_all_full: {} → {}",
+            old_hot.desync_all_full, new_hot.desync_all_full,
+        );
+    }
+
+    if old_hot.update_every_secs != new_hot.update_every_secs {
+        info!(
+            "config reload: update_every(effective): {}s → {}s",
+            old_hot.update_every_secs, new_hot.update_every_secs,
+        );
+    }
+    if old_hot.me_reinit_every_secs != new_hot.me_reinit_every_secs
+        || old_hot.me_reinit_singleflight != new_hot.me_reinit_singleflight
+        || old_hot.me_reinit_coalesce_window_ms != new_hot.me_reinit_coalesce_window_ms
+    {
+        info!(
+            "config reload: me_reinit: interval={}s singleflight={} coalesce={}ms",
+            new_hot.me_reinit_every_secs,
+            new_hot.me_reinit_singleflight,
+            new_hot.me_reinit_coalesce_window_ms
+        );
+    }
+
+    if old_hot.hardswap != new_hot.hardswap {
+        info!(
+            "config reload: hardswap: {} → {}",
+            old_hot.hardswap, new_hot.hardswap,
+        );
+    }
+
+    if old_hot.me_pool_drain_ttl_secs != new_hot.me_pool_drain_ttl_secs {
+        info!(
+            "config reload: me_pool_drain_ttl_secs: {}s → {}s",
+            old_hot.me_pool_drain_ttl_secs, new_hot.me_pool_drain_ttl_secs,
+        );
+    }
+    if old_hot.me_instadrain != new_hot.me_instadrain {
+        info!(
+            "config reload: me_instadrain: {} → {}",
+            old_hot.me_instadrain, new_hot.me_instadrain,
+        );
+    }
+
+    if old_hot.me_pool_drain_threshold != new_hot.me_pool_drain_threshold {
+        info!(
+            "config reload: me_pool_drain_threshold: {} → {}",
+            old_hot.me_pool_drain_threshold, new_hot.me_pool_drain_threshold,
+        );
+    }
+
+    if (old_hot.me_pool_min_fresh_ratio - new_hot.me_pool_min_fresh_ratio).abs() > f32::EPSILON {
+        info!(
+            "config reload: me_pool_min_fresh_ratio: {:.3} → {:.3}",
+            old_hot.me_pool_min_fresh_ratio, new_hot.me_pool_min_fresh_ratio,
+        );
+    }
+
+    if old_hot.me_reinit_drain_timeout_secs != new_hot.me_reinit_drain_timeout_secs {
+        info!(
+            "config reload: me_reinit_drain_timeout_secs: {}s → {}s",
+            old_hot.me_reinit_drain_timeout_secs, new_hot.me_reinit_drain_timeout_secs,
+        );
+    }
+    if old_hot.me_hardswap_warmup_delay_min_ms != new_hot.me_hardswap_warmup_delay_min_ms
+        || old_hot.me_hardswap_warmup_delay_max_ms != new_hot.me_hardswap_warmup_delay_max_ms
+        || old_hot.me_hardswap_warmup_extra_passes != new_hot.me_hardswap_warmup_extra_passes
+        || old_hot.me_hardswap_warmup_pass_backoff_base_ms
+            != new_hot.me_hardswap_warmup_pass_backoff_base_ms
+    {
+        info!(
+            "config reload: me_hardswap_warmup: min={}ms max={}ms extra_passes={} pass_backoff={}ms",
+            new_hot.me_hardswap_warmup_delay_min_ms,
+            new_hot.me_hardswap_warmup_delay_max_ms,
+            new_hot.me_hardswap_warmup_extra_passes,
+            new_hot.me_hardswap_warmup_pass_backoff_base_ms
+        );
+    }
+    if old_hot.me_bind_stale_mode != new_hot.me_bind_stale_mode
+        || old_hot.me_bind_stale_ttl_secs != new_hot.me_bind_stale_ttl_secs
+    {
+        info!(
+            "config reload: me_bind_stale: mode={:?} ttl={}s",
+            new_hot.me_bind_stale_mode, new_hot.me_bind_stale_ttl_secs
+        );
+    }
+    if old_hot.me_secret_atomic_snapshot != new_hot.me_secret_atomic_snapshot
+        || old_hot.me_deterministic_writer_sort != new_hot.me_deterministic_writer_sort
+        || old_hot.me_writer_pick_mode != new_hot.me_writer_pick_mode
+        || old_hot.me_writer_pick_sample_size != new_hot.me_writer_pick_sample_size
+    {
+        info!(
+            "config reload: me_runtime_flags: secret_atomic_snapshot={} deterministic_sort={} writer_pick_mode={:?} writer_pick_sample_size={}",
+            new_hot.me_secret_atomic_snapshot,
+            new_hot.me_deterministic_writer_sort,
+            new_hot.me_writer_pick_mode,
+            new_hot.me_writer_pick_sample_size,
+        );
+    }
+    if old_hot.me_single_endpoint_shadow_writers != new_hot.me_single_endpoint_shadow_writers
+        || old_hot.me_single_endpoint_outage_mode_enabled
+            != new_hot.me_single_endpoint_outage_mode_enabled
+        || old_hot.me_single_endpoint_outage_disable_quarantine
+            != new_hot.me_single_endpoint_outage_disable_quarantine
+        || old_hot.me_single_endpoint_outage_backoff_min_ms
+            != new_hot.me_single_endpoint_outage_backoff_min_ms
+        || old_hot.me_single_endpoint_outage_backoff_max_ms
+            != new_hot.me_single_endpoint_outage_backoff_max_ms
+        || old_hot.me_single_endpoint_shadow_rotate_every_secs
+            != new_hot.me_single_endpoint_shadow_rotate_every_secs
+    {
+        info!(
+            "config reload: me_single_endpoint: shadow={} outage_enabled={} disable_quarantine={} backoff=[{}..{}]ms rotate={}s",
+            new_hot.me_single_endpoint_shadow_writers,
+            new_hot.me_single_endpoint_outage_mode_enabled,
+            new_hot.me_single_endpoint_outage_disable_quarantine,
+            new_hot.me_single_endpoint_outage_backoff_min_ms,
+            new_hot.me_single_endpoint_outage_backoff_max_ms,
+            new_hot.me_single_endpoint_shadow_rotate_every_secs
+        );
+    }
+    if old_hot.me_config_stable_snapshots != new_hot.me_config_stable_snapshots
+        || old_hot.me_config_apply_cooldown_secs != new_hot.me_config_apply_cooldown_secs
+        || old_hot.me_snapshot_require_http_2xx != new_hot.me_snapshot_require_http_2xx
+        || old_hot.me_snapshot_reject_empty_map != new_hot.me_snapshot_reject_empty_map
+        || old_hot.me_snapshot_min_proxy_for_lines != new_hot.me_snapshot_min_proxy_for_lines
+    {
+        info!(
+            "config reload: me_snapshot_guard: stable={} cooldown={}s require_2xx={} reject_empty={} min_proxy_for={}",
+            new_hot.me_config_stable_snapshots,
+            new_hot.me_config_apply_cooldown_secs,
+            new_hot.me_snapshot_require_http_2xx,
+            new_hot.me_snapshot_reject_empty_map,
+            new_hot.me_snapshot_min_proxy_for_lines
+        );
+    }
+    if old_hot.proxy_secret_stable_snapshots != new_hot.proxy_secret_stable_snapshots
+        || old_hot.proxy_secret_rotate_runtime != new_hot.proxy_secret_rotate_runtime
+        || old_hot.proxy_secret_len_max != new_hot.proxy_secret_len_max
+    {
+        info!(
+            "config reload: proxy_secret_runtime: stable={} rotate={} len_max={}",
+            new_hot.proxy_secret_stable_snapshots,
+            new_hot.proxy_secret_rotate_runtime,
+            new_hot.proxy_secret_len_max
+        );
+    }
+
+    if old_hot.telemetry_core_enabled != new_hot.telemetry_core_enabled
+        || old_hot.telemetry_user_enabled != new_hot.telemetry_user_enabled
+        || old_hot.telemetry_me_level != new_hot.telemetry_me_level
+    {
+        info!(
+            "config reload: telemetry: core_enabled={} user_enabled={} me_level={}",
+            new_hot.telemetry_core_enabled,
+            new_hot.telemetry_user_enabled,
+            new_hot.telemetry_me_level,
+        );
+    }
+
+    if old_hot.me_socks_kdf_policy != new_hot.me_socks_kdf_policy {
+        info!(
+            "config reload: me_socks_kdf_policy: {:?} → {:?}",
+            old_hot.me_socks_kdf_policy, new_hot.me_socks_kdf_policy,
+        );
+    }
+
+    if old_hot.me_floor_mode != new_hot.me_floor_mode
+        || old_hot.me_adaptive_floor_idle_secs != new_hot.me_adaptive_floor_idle_secs
+        || old_hot.me_adaptive_floor_min_writers_single_endpoint
+            != new_hot.me_adaptive_floor_min_writers_single_endpoint
+        || old_hot.me_adaptive_floor_min_writers_multi_endpoint
+            != new_hot.me_adaptive_floor_min_writers_multi_endpoint
+        || old_hot.me_adaptive_floor_recover_grace_secs
+            != new_hot.me_adaptive_floor_recover_grace_secs
+        || old_hot.me_adaptive_floor_writers_per_core_total
+            != new_hot.me_adaptive_floor_writers_per_core_total
+        || old_hot.me_adaptive_floor_cpu_cores_override
+            != new_hot.me_adaptive_floor_cpu_cores_override
+        || old_hot.me_adaptive_floor_max_extra_writers_single_per_core
+            != new_hot.me_adaptive_floor_max_extra_writers_single_per_core
+        || old_hot.me_adaptive_floor_max_extra_writers_multi_per_core
+            != new_hot.me_adaptive_floor_max_extra_writers_multi_per_core
+        || old_hot.me_adaptive_floor_max_active_writers_per_core
+            != new_hot.me_adaptive_floor_max_active_writers_per_core
+        || old_hot.me_adaptive_floor_max_warm_writers_per_core
+            != new_hot.me_adaptive_floor_max_warm_writers_per_core
+        || old_hot.me_adaptive_floor_max_active_writers_global
+            != new_hot.me_adaptive_floor_max_active_writers_global
+        || old_hot.me_adaptive_floor_max_warm_writers_global
+            != new_hot.me_adaptive_floor_max_warm_writers_global
+    {
+        info!(
+            "config reload: me_floor: mode={:?} idle={}s min_single={} min_multi={} recover_grace={}s per_core_total={} cores_override={} extra_single_per_core={} extra_multi_per_core={} max_active_per_core={} max_warm_per_core={} max_active_global={} max_warm_global={}",
+            new_hot.me_floor_mode,
+            new_hot.me_adaptive_floor_idle_secs,
+            new_hot.me_adaptive_floor_min_writers_single_endpoint,
+            new_hot.me_adaptive_floor_min_writers_multi_endpoint,
+            new_hot.me_adaptive_floor_recover_grace_secs,
+            new_hot.me_adaptive_floor_writers_per_core_total,
+            new_hot.me_adaptive_floor_cpu_cores_override,
+            new_hot.me_adaptive_floor_max_extra_writers_single_per_core,
+            new_hot.me_adaptive_floor_max_extra_writers_multi_per_core,
+            new_hot.me_adaptive_floor_max_active_writers_per_core,
+            new_hot.me_adaptive_floor_max_warm_writers_per_core,
+            new_hot.me_adaptive_floor_max_active_writers_global,
+            new_hot.me_adaptive_floor_max_warm_writers_global,
+        );
+    }
+
+    if old_hot.me_route_backpressure_base_timeout_ms
+        != new_hot.me_route_backpressure_base_timeout_ms
+        || old_hot.me_route_backpressure_high_timeout_ms
+            != new_hot.me_route_backpressure_high_timeout_ms
+        || old_hot.me_route_backpressure_high_watermark_pct
+            != new_hot.me_route_backpressure_high_watermark_pct
+        || old_hot.me_route_backpressure_enabled != new_hot.me_route_backpressure_enabled
+        || old_hot.me_route_fairshare_enabled != new_hot.me_route_fairshare_enabled
+        || old_hot.me_reader_route_data_wait_ms != new_hot.me_reader_route_data_wait_ms
+        || old_hot.me_health_interval_ms_unhealthy != new_hot.me_health_interval_ms_unhealthy
+        || old_hot.me_health_interval_ms_healthy != new_hot.me_health_interval_ms_healthy
+        || old_hot.me_admission_poll_ms != new_hot.me_admission_poll_ms
+        || old_hot.me_warn_rate_limit_ms != new_hot.me_warn_rate_limit_ms
+    {
+        info!(
+            "config reload: me_route_backpressure: enabled={} base={}ms high={}ms watermark={}%; me_route_fairshare_enabled={}; me_reader_route_data_wait_ms={}; me_health_interval: unhealthy={}ms healthy={}ms; me_admission_poll={}ms; me_warn_rate_limit={}ms",
+            new_hot.me_route_backpressure_enabled,
+            new_hot.me_route_backpressure_base_timeout_ms,
+            new_hot.me_route_backpressure_high_timeout_ms,
+            new_hot.me_route_backpressure_high_watermark_pct,
+            new_hot.me_route_fairshare_enabled,
+            new_hot.me_reader_route_data_wait_ms,
+            new_hot.me_health_interval_ms_unhealthy,
+            new_hot.me_health_interval_ms_healthy,
+            new_hot.me_admission_poll_ms,
+            new_hot.me_warn_rate_limit_ms,
+        );
+    }
+
+    if old_hot.me_d2c_flush_batch_max_frames != new_hot.me_d2c_flush_batch_max_frames
+        || old_hot.me_d2c_flush_batch_max_bytes != new_hot.me_d2c_flush_batch_max_bytes
+        || old_hot.me_d2c_flush_batch_max_delay_us != new_hot.me_d2c_flush_batch_max_delay_us
+        || old_hot.me_d2c_ack_flush_immediate != new_hot.me_d2c_ack_flush_immediate
+        || old_hot.me_quota_soft_overshoot_bytes != new_hot.me_quota_soft_overshoot_bytes
+        || old_hot.me_d2c_frame_buf_shrink_threshold_bytes
+            != new_hot.me_d2c_frame_buf_shrink_threshold_bytes
+        || old_hot.direct_relay_copy_buf_c2s_bytes != new_hot.direct_relay_copy_buf_c2s_bytes
+        || old_hot.direct_relay_copy_buf_s2c_bytes != new_hot.direct_relay_copy_buf_s2c_bytes
+    {
+        info!(
+            "config reload: relay_tuning: me_d2c_frames={} me_d2c_bytes={} me_d2c_delay_us={} me_ack_flush_immediate={} me_quota_soft_overshoot_bytes={} me_d2c_frame_buf_shrink_threshold_bytes={} direct_buf_c2s={} direct_buf_s2c={}",
+            new_hot.me_d2c_flush_batch_max_frames,
+            new_hot.me_d2c_flush_batch_max_bytes,
+            new_hot.me_d2c_flush_batch_max_delay_us,
+            new_hot.me_d2c_ack_flush_immediate,
+            new_hot.me_quota_soft_overshoot_bytes,
+            new_hot.me_d2c_frame_buf_shrink_threshold_bytes,
+            new_hot.direct_relay_copy_buf_c2s_bytes,
+            new_hot.direct_relay_copy_buf_s2c_bytes,
+        );
+    }
+
+    if old_hot.users != new_hot.users {
+        let mut added: Vec<&String> = new_hot
+            .users
+            .keys()
+            .filter(|u| !old_hot.users.contains_key(*u))
+            .collect();
+        added.sort();
+
+        let mut removed: Vec<&String> = old_hot
+            .users
+            .keys()
+            .filter(|u| !new_hot.users.contains_key(*u))
+            .collect();
+        removed.sort();
+
+        let mut changed: Vec<&String> = new_hot
+            .users
+            .keys()
+            .filter(|u| {
+                old_hot
+                    .users
+                    .get(*u)
+                    .map(|s| s != &new_hot.users[*u])
+                    .unwrap_or(false)
+            })
+            .collect();
+        changed.sort();
+
+        if !added.is_empty() {
+            info!(
+                "config reload: users added: [{}]",
+                added
+                    .iter()
+                    .map(|s| s.as_str())
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            );
+            let host = resolve_link_host(new_cfg, detected_ip_v4, detected_ip_v6);
+            let port = new_cfg
+                .general
+                .links
+                .public_port
+                .unwrap_or(resolve_default_link_port(new_cfg));
+            for user in &added {
+                if let Some(secret) = new_hot.users.get(*user) {
+                    print_user_links(user, secret, &host, port, new_cfg);
+                }
+            }
+        }
+        if !removed.is_empty() {
+            info!(
+                "config reload: users removed: [{}]",
+                removed
+                    .iter()
+                    .map(|s| s.as_str())
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            );
+        }
+        if !changed.is_empty() {
+            info!(
+                "config reload: users secret changed: [{}]",
+                changed
+                    .iter()
+                    .map(|s| s.as_str())
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            );
+        }
+    }
+
+    if old_hot.user_enabled != new_hot.user_enabled {
+        info!(
+            "config reload: user_enabled updated ({} disabled overrides)",
+            new_hot
+                .user_enabled
+                .values()
+                .filter(|enabled| !**enabled)
+                .count()
+        );
+    }
+    if old_hot.user_max_tcp_conns != new_hot.user_max_tcp_conns {
+        info!(
+            "config reload: user_max_tcp_conns updated ({} entries)",
+            new_hot.user_max_tcp_conns.len()
+        );
+    }
+    if old_hot.user_max_tcp_conns_global_each != new_hot.user_max_tcp_conns_global_each {
+        info!(
+            "config reload: user_max_tcp_conns policy global_each={}",
+            new_hot.user_max_tcp_conns_global_each
+        );
+    }
+    if old_hot.user_expirations != new_hot.user_expirations {
+        info!(
+            "config reload: user_expirations updated ({} entries)",
+            new_hot.user_expirations.len()
+        );
+    }
+    if old_hot.user_data_quota != new_hot.user_data_quota {
+        info!(
+            "config reload: user_data_quota updated ({} entries)",
+            new_hot.user_data_quota.len()
+        );
+    }
+    if old_hot.user_rate_limits != new_hot.user_rate_limits {
+        info!(
+            "config reload: user_rate_limits updated ({} entries)",
+            new_hot.user_rate_limits.len()
+        );
+    }
+    if old_hot.cidr_rate_limits != new_hot.cidr_rate_limits {
+        info!(
+            "config reload: cidr_rate_limits updated ({} entries)",
+            new_hot.cidr_rate_limits.len()
+        );
+    }
+    if old_hot.user_max_unique_ips != new_hot.user_max_unique_ips {
+        info!(
+            "config reload: user_max_unique_ips updated ({} entries)",
+            new_hot.user_max_unique_ips.len()
+        );
+    }
+    if old_hot.user_max_unique_ips_global_each != new_hot.user_max_unique_ips_global_each
+        || old_hot.user_max_unique_ips_mode != new_hot.user_max_unique_ips_mode
+        || old_hot.user_max_unique_ips_window_secs != new_hot.user_max_unique_ips_window_secs
+    {
+        info!(
+            "config reload: user_max_unique_ips policy global_each={} mode={:?} window={}s",
+            new_hot.user_max_unique_ips_global_each,
+            new_hot.user_max_unique_ips_mode,
+            new_hot.user_max_unique_ips_window_secs
+        );
+    }
+}

src/config/hot_reload/tests.rs

@@ -0,0 +1,293 @@
+use super::*;
+
+fn sample_config() -> ProxyConfig {
+    ProxyConfig::default()
+}
+
+fn write_reload_config(path: &Path, ad_tag: Option<&str>, server_port: Option<u16>) {
+    let mut config = String::from(
+        r#"
+                [censorship]
+                tls_domain = "example.com"
+
+                [access.users]
+                user = "00000000000000000000000000000000"
+            "#,
+    );
+
+    if ad_tag.is_some() {
+        config.push_str("\n[general]\n");
+        if let Some(tag) = ad_tag {
+            config.push_str(&format!("ad_tag = \"{tag}\"\n"));
+        }
+    }
+
+    if let Some(port) = server_port {
+        config.push_str("\n[server]\n");
+        config.push_str(&format!("port = {port}\n"));
+    }
+
+    std::fs::write(path, config).unwrap();
+}
+
+fn temp_config_path(prefix: &str) -> PathBuf {
+    let nonce = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap()
+        .as_nanos();
+    std::env::temp_dir().join(format!("{prefix}_{nonce}.toml"))
+}
+
+#[test]
+fn overlay_applies_hot_and_preserves_non_hot() {
+    let old = sample_config();
+    let mut new = old.clone();
+    new.general.hardswap = !old.general.hardswap;
+    new.server.port = old.server.port.saturating_add(1);
+
+    let applied = overlay_hot_fields(&old, &new);
+    assert_eq!(applied.general.hardswap, new.general.hardswap);
+    assert_eq!(applied.server.port, old.server.port);
+}
+
+#[test]
+fn non_hot_only_change_does_not_change_hot_snapshot() {
+    let old = sample_config();
+    let mut new = old.clone();
+    new.server.port = old.server.port.saturating_add(1);
+
+    let applied = overlay_hot_fields(&old, &new);
+    assert_eq!(
+        HotFields::from_config(&old),
+        HotFields::from_config(&applied)
+    );
+    assert_eq!(applied.server.port, old.server.port);
+}
+
+#[test]
+fn bind_stale_mode_is_hot() {
+    let old = sample_config();
+    let mut new = old.clone();
+    new.general.me_bind_stale_mode = match old.general.me_bind_stale_mode {
+        MeBindStaleMode::Never => MeBindStaleMode::Ttl,
+        MeBindStaleMode::Ttl => MeBindStaleMode::Always,
+        MeBindStaleMode::Always => MeBindStaleMode::Never,
+    };
+
+    let applied = overlay_hot_fields(&old, &new);
+    assert_eq!(
+        applied.general.me_bind_stale_mode,
+        new.general.me_bind_stale_mode
+    );
+    assert_ne!(
+        HotFields::from_config(&old),
+        HotFields::from_config(&applied)
+    );
+}
+
+#[test]
+fn keepalive_is_not_hot() {
+    let old = sample_config();
+    let mut new = old.clone();
+    new.general.me_keepalive_interval_secs = old.general.me_keepalive_interval_secs + 5;
+
+    let applied = overlay_hot_fields(&old, &new);
+    assert_eq!(
+        applied.general.me_keepalive_interval_secs,
+        old.general.me_keepalive_interval_secs
+    );
+    assert_eq!(
+        HotFields::from_config(&old),
+        HotFields::from_config(&applied)
+    );
+}
+
+#[test]
+fn mixed_hot_and_non_hot_change_applies_only_hot_subset() {
+    let old = sample_config();
+    let mut new = old.clone();
+    new.general.hardswap = !old.general.hardswap;
+    new.general.use_middle_proxy = !old.general.use_middle_proxy;
+
+    let applied = overlay_hot_fields(&old, &new);
+    assert_eq!(applied.general.hardswap, new.general.hardswap);
+    assert_eq!(
+        applied.general.use_middle_proxy,
+        old.general.use_middle_proxy
+    );
+    assert!(!config_equal(&applied, &new));
+}
+
+#[test]
+fn listener_synlimit_fields_are_process_owned() {
+    let mut old = sample_config();
+    old.server.listeners.push(ListenerConfig {
+        ip: "0.0.0.0".parse().unwrap(),
+        transport: crate::config::ListenerTransport::Mtproxy,
+        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,
+        web_client_ip_source: crate::config::WebClientIpSource::XForwardedFor,
+        web_trusted_proxy_cidrs: Vec::new(),
+    });
+    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,
+        old.server.listeners[0].synlimit_seconds
+    );
+    assert_eq!(
+        listener.synlimit_hitcount,
+        old.server.listeners[0].synlimit_hitcount
+    );
+    assert_eq!(
+        listener.synlimit_burst,
+        old.server.listeners[0].synlimit_burst
+    );
+    assert_eq!(
+        listener.synlimit_hashlimit_size,
+        old.server.listeners[0].synlimit_hashlimit_size
+    );
+    assert!(classify_config_changes(&old, &new).restart_required);
+}
+
+#[test]
+fn reload_applies_hot_change_on_first_observed_snapshot() {
+    let initial_tag = "11111111111111111111111111111111";
+    let final_tag = "22222222222222222222222222222222";
+    let path = temp_config_path("telemt_hot_reload_stable");
+
+    write_reload_config(&path, Some(initial_tag), None);
+    let initial_cfg = Arc::new(ProxyConfig::load(&path).unwrap());
+    let initial_hash = ProxyConfig::load_with_metadata(&path)
+        .unwrap()
+        .rendered_hash;
+    let (config_tx, _config_rx) = watch::channel(initial_cfg.clone());
+    let (log_tx, _log_rx) = watch::channel(initial_cfg.general.log_level.clone());
+    let mut reload_state = ReloadState::new(Some(initial_hash));
+
+    write_reload_config(&path, Some(final_tag), None);
+    reload_config(&path, &config_tx, &log_tx, None, None, &mut reload_state).unwrap();
+    assert_eq!(
+        config_tx.borrow().general.ad_tag.as_deref(),
+        Some(final_tag)
+    );
+
+    let _ = std::fs::remove_file(path);
+}
+
+#[test]
+fn reload_keeps_hot_apply_when_non_hot_fields_change() {
+    let initial_tag = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+    let final_tag = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+    let path = temp_config_path("telemt_hot_reload_mixed");
+
+    write_reload_config(&path, Some(initial_tag), None);
+    let initial_cfg = Arc::new(ProxyConfig::load(&path).unwrap());
+    let initial_hash = ProxyConfig::load_with_metadata(&path)
+        .unwrap()
+        .rendered_hash;
+    let (config_tx, _config_rx) = watch::channel(initial_cfg.clone());
+    let (log_tx, _log_rx) = watch::channel(initial_cfg.general.log_level.clone());
+    let mut reload_state = ReloadState::new(Some(initial_hash));
+
+    write_reload_config(&path, Some(final_tag), Some(initial_cfg.server.port + 1));
+    reload_config(&path, &config_tx, &log_tx, None, None, &mut reload_state).unwrap();
+
+    let applied = config_tx.borrow().clone();
+    assert_eq!(applied.general.ad_tag.as_deref(), Some(final_tag));
+    assert_eq!(applied.server.port, initial_cfg.server.port);
+
+    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";
+    let final_tag = "dddddddddddddddddddddddddddddddd";
+    let path = temp_config_path("telemt_hot_reload_parse_recovery");
+
+    write_reload_config(&path, Some(initial_tag), None);
+    let initial_cfg = Arc::new(ProxyConfig::load(&path).unwrap());
+    let initial_hash = ProxyConfig::load_with_metadata(&path)
+        .unwrap()
+        .rendered_hash;
+    let (config_tx, _config_rx) = watch::channel(initial_cfg.clone());
+    let (log_tx, _log_rx) = watch::channel(initial_cfg.general.log_level.clone());
+    let mut reload_state = ReloadState::new(Some(initial_hash));
+
+    std::fs::write(&path, "[access.users\nuser = \"broken\"\n").unwrap();
+    assert!(reload_config(&path, &config_tx, &log_tx, None, None, &mut reload_state).is_none());
+    assert_eq!(
+        config_tx.borrow().general.ad_tag.as_deref(),
+        Some(initial_tag)
+    );
+
+    write_reload_config(&path, Some(final_tag), None);
+    reload_config(&path, &config_tx, &log_tx, None, None, &mut reload_state).unwrap();
+    assert_eq!(
+        config_tx.borrow().general.ad_tag.as_deref(),
+        Some(final_tag)
+    );
+
+    let _ = std::fs::remove_file(path);
+}

src/config/hot_reload/watcher.rs

@@ -0,0 +1,370 @@
+use super::*;
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub(super) struct WatchManifest {
+    files: BTreeSet<PathBuf>,
+    dirs: BTreeSet<PathBuf>,
+}
+
+impl WatchManifest {
+    fn from_source_files(source_files: &[PathBuf]) -> Self {
+        let mut files = BTreeSet::new();
+        let mut dirs = BTreeSet::new();
+
+        for path in source_files {
+            let normalized = normalize_watch_path(path);
+            files.insert(normalized.clone());
+            if let Some(parent) = normalized.parent() {
+                dirs.insert(parent.to_path_buf());
+            }
+        }
+
+        Self { files, dirs }
+    }
+
+    fn matches_event_paths(&self, event_paths: &[PathBuf]) -> bool {
+        event_paths
+            .iter()
+            .map(|path| normalize_watch_path(path))
+            .any(|path| self.files.contains(&path))
+    }
+}
+
+#[derive(Debug, Default)]
+pub(super) struct ReloadState {
+    applied_snapshot_hash: Option<u64>,
+}
+
+impl ReloadState {
+    pub(super) fn new(applied_snapshot_hash: Option<u64>) -> Self {
+        Self {
+            applied_snapshot_hash,
+        }
+    }
+
+    fn is_applied(&self, hash: u64) -> bool {
+        self.applied_snapshot_hash == Some(hash)
+    }
+
+    fn mark_applied(&mut self, hash: u64) {
+        self.applied_snapshot_hash = Some(hash);
+    }
+}
+
+fn normalize_watch_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())
+        }
+    })
+}
+
+fn sync_watch_paths<W: Watcher>(
+    watcher: &mut W,
+    current: &BTreeSet<PathBuf>,
+    next: &BTreeSet<PathBuf>,
+    recursive_mode: RecursiveMode,
+    kind: &str,
+) {
+    for path in current.difference(next) {
+        if let Err(e) = watcher.unwatch(path) {
+            warn!(path = %path.display(), error = %e, "config watcher: failed to unwatch {kind}");
+        }
+    }
+
+    for path in next.difference(current) {
+        if let Err(e) = watcher.watch(path, recursive_mode) {
+            warn!(path = %path.display(), error = %e, "config watcher: failed to watch {kind}");
+        }
+    }
+}
+
+fn apply_watch_manifest<W1: Watcher, W2: Watcher>(
+    notify_watcher: Option<&mut W1>,
+    poll_watcher: Option<&mut W2>,
+    manifest_state: &Arc<StdRwLock<WatchManifest>>,
+    next_manifest: WatchManifest,
+) {
+    let current_manifest = manifest_state
+        .read()
+        .map(|manifest| manifest.clone())
+        .unwrap_or_default();
+
+    if current_manifest == next_manifest {
+        return;
+    }
+
+    if let Some(watcher) = notify_watcher {
+        sync_watch_paths(
+            watcher,
+            &current_manifest.dirs,
+            &next_manifest.dirs,
+            RecursiveMode::NonRecursive,
+            "config directory",
+        );
+    }
+
+    if let Some(watcher) = poll_watcher {
+        sync_watch_paths(
+            watcher,
+            &current_manifest.files,
+            &next_manifest.files,
+            RecursiveMode::NonRecursive,
+            "config file",
+        );
+    }
+
+    if let Ok(mut manifest) = manifest_state.write() {
+        *manifest = next_manifest;
+    }
+}
+
+/// Load config, validate, diff against current, and broadcast if changed.
+pub(super) fn reload_config(
+    config_path: &PathBuf,
+    config_tx: &watch::Sender<Arc<ProxyConfig>>,
+    log_tx: &watch::Sender<LogLevel>,
+    detected_ip_v4: Option<IpAddr>,
+    detected_ip_v6: Option<IpAddr>,
+    reload_state: &mut ReloadState,
+) -> Option<WatchManifest> {
+    let loaded = match ProxyConfig::load_with_metadata(config_path) {
+        Ok(loaded) => loaded,
+        Err(e) => {
+            error!("config reload: failed to parse {:?}: {}", config_path, e);
+            return None;
+        }
+    };
+    let LoadedConfig {
+        config: new_cfg,
+        source_files,
+        source_contents: _,
+        rendered_hash,
+    } = loaded;
+    let next_manifest = WatchManifest::from_source_files(&source_files);
+
+    if let Err(e) = new_cfg.validate() {
+        error!(
+            "config reload: validation failed: {}; keeping old config",
+            e
+        );
+        return Some(next_manifest);
+    }
+
+    if reload_state.is_applied(rendered_hash) {
+        return Some(next_manifest);
+    }
+
+    let old_cfg = config_tx.borrow().clone();
+    let applied_cfg = overlay_hot_fields(&old_cfg, &new_cfg);
+    let old_hot = HotFields::from_config(&old_cfg);
+    let applied_hot = HotFields::from_config(&applied_cfg);
+    let non_hot_changed = !config_equal(&applied_cfg, &new_cfg);
+    let hot_changed = old_hot != applied_hot;
+
+    if non_hot_changed {
+        warn_non_hot_changes(&old_cfg, &new_cfg, non_hot_changed);
+    }
+
+    if !hot_changed {
+        reload_state.mark_applied(rendered_hash);
+        return Some(next_manifest);
+    }
+
+    if old_hot.dns_overrides != applied_hot.dns_overrides
+        && let Err(e) = crate::network::dns_overrides::install_entries(&applied_hot.dns_overrides)
+    {
+        error!(
+            "config reload: invalid network.dns_overrides: {}; keeping old config",
+            e
+        );
+        return Some(next_manifest);
+    }
+
+    log_changes(
+        &old_hot,
+        &applied_hot,
+        &applied_cfg,
+        log_tx,
+        detected_ip_v4,
+        detected_ip_v6,
+    );
+    config_tx.send(Arc::new(applied_cfg)).ok();
+    reload_state.mark_applied(rendered_hash);
+    Some(next_manifest)
+}
+
+/// Spawn the hot-reload watcher task.
+///
+/// Uses `notify` (inotify on Linux) to detect file changes instantly.
+/// SIGHUP is also handled on Unix as an additional manual trigger.
+///
+/// `detected_ip_v4` / `detected_ip_v6` are the IPs discovered during the
+/// startup probe — used when generating proxy links for newly added users,
+/// matching the same logic as the startup output.
+/// The watcher releases its notify and signal resources when `cancellation` fires.
+pub fn spawn_config_watcher(
+    config_path: PathBuf,
+    initial: Arc<ProxyConfig>,
+    detected_ip_v4: Option<IpAddr>,
+    detected_ip_v6: Option<IpAddr>,
+    cancellation: tokio_util::sync::CancellationToken,
+) -> (watch::Receiver<Arc<ProxyConfig>>, watch::Receiver<LogLevel>) {
+    let initial_level = initial.general.log_level.clone();
+    let (config_tx, config_rx) = watch::channel(initial);
+    let (log_tx, log_rx) = watch::channel(initial_level);
+
+    let config_path = normalize_watch_path(&config_path);
+    let initial_loaded = ProxyConfig::load_with_metadata(&config_path).ok();
+    let initial_manifest = initial_loaded
+        .as_ref()
+        .map(|loaded| WatchManifest::from_source_files(&loaded.source_files))
+        .unwrap_or_else(|| WatchManifest::from_source_files(std::slice::from_ref(&config_path)));
+    let initial_snapshot_hash = initial_loaded.as_ref().map(|loaded| loaded.rendered_hash);
+
+    tokio::spawn(async move {
+        let (notify_tx, mut notify_rx) = mpsc::channel::<()>(4);
+        let manifest_state = Arc::new(StdRwLock::new(WatchManifest::default()));
+        let mut reload_state = ReloadState::new(initial_snapshot_hash);
+
+        let tx_inotify = notify_tx.clone();
+        let manifest_for_inotify = manifest_state.clone();
+        let mut inotify_watcher =
+            match recommended_watcher(move |res: notify::Result<notify::Event>| {
+                let Ok(event) = res else { return };
+                if !matches!(
+                    event.kind,
+                    EventKind::Modify(_) | EventKind::Create(_) | EventKind::Remove(_)
+                ) {
+                    return;
+                }
+                let is_our_file = manifest_for_inotify
+                    .read()
+                    .map(|manifest| manifest.matches_event_paths(&event.paths))
+                    .unwrap_or(false);
+                if is_our_file {
+                    let _ = tx_inotify.try_send(());
+                }
+            }) {
+                Ok(watcher) => Some(watcher),
+                Err(e) => {
+                    warn!("config watcher: inotify unavailable: {}", e);
+                    None
+                }
+            };
+        apply_watch_manifest(
+            inotify_watcher.as_mut(),
+            Option::<&mut notify::poll::PollWatcher>::None,
+            &manifest_state,
+            initial_manifest.clone(),
+        );
+        if inotify_watcher.is_some() {
+            info!("config watcher: inotify active on {:?}", config_path);
+        }
+
+        let tx_poll = notify_tx.clone();
+        let manifest_for_poll = manifest_state.clone();
+        let mut poll_watcher = match notify::poll::PollWatcher::new(
+            move |res: notify::Result<notify::Event>| {
+                let Ok(event) = res else { return };
+                if !matches!(
+                    event.kind,
+                    EventKind::Modify(_) | EventKind::Create(_) | EventKind::Remove(_)
+                ) {
+                    return;
+                }
+                let is_our_file = manifest_for_poll
+                    .read()
+                    .map(|manifest| manifest.matches_event_paths(&event.paths))
+                    .unwrap_or(false);
+                if is_our_file {
+                    let _ = tx_poll.try_send(());
+                }
+            },
+            notify::Config::default()
+                .with_poll_interval(Duration::from_secs(3))
+                .with_compare_contents(true),
+        ) {
+            Ok(watcher) => Some(watcher),
+            Err(e) => {
+                warn!("config watcher: poll watcher unavailable: {}", e);
+                None
+            }
+        };
+        apply_watch_manifest(
+            Option::<&mut notify::RecommendedWatcher>::None,
+            poll_watcher.as_mut(),
+            &manifest_state,
+            initial_manifest.clone(),
+        );
+        if poll_watcher.is_some() {
+            info!("config watcher: poll watcher active (Docker/NFS safe)");
+        }
+
+        #[cfg(unix)]
+        let mut sighup = {
+            use tokio::signal::unix::{SignalKind, signal};
+            signal(SignalKind::hangup()).expect("Failed to register SIGHUP handler")
+        };
+
+        loop {
+            #[cfg(unix)]
+            tokio::select! {
+                msg = notify_rx.recv() => {
+                    if msg.is_none() { break; }
+                }
+                _ = sighup.recv() => {
+                    info!("SIGHUP received — reloading {:?}", config_path);
+                }
+                _ = cancellation.cancelled() => break,
+            }
+            #[cfg(not(unix))]
+            tokio::select! {
+                msg = notify_rx.recv() => {
+                    if msg.is_none() { break; }
+                }
+                _ = cancellation.cancelled() => break,
+            }
+
+            // Debounce: drain extra events that arrive within a short quiet window.
+            tokio::time::sleep(HOT_RELOAD_DEBOUNCE).await;
+            while notify_rx.try_recv().is_ok() {}
+
+            let mut next_manifest = reload_config(
+                &config_path,
+                &config_tx,
+                &log_tx,
+                detected_ip_v4,
+                detected_ip_v6,
+                &mut reload_state,
+            );
+            if next_manifest.is_none() {
+                tokio::time::sleep(HOT_RELOAD_DEBOUNCE).await;
+                while notify_rx.try_recv().is_ok() {}
+                next_manifest = reload_config(
+                    &config_path,
+                    &config_tx,
+                    &log_tx,
+                    detected_ip_v4,
+                    detected_ip_v6,
+                    &mut reload_state,
+                );
+            }
+
+            if let Some(next_manifest) = next_manifest {
+                apply_watch_manifest(
+                    inotify_watcher.as_mut(),
+                    poll_watcher.as_mut(),
+                    &manifest_state,
+                    next_manifest,
+                );
+            }
+        }
+    });
+
+    (config_rx, log_rx)
+}

src/config/load/decode.rs

@@ -0,0 +1,159 @@
+use super::*;
+
+pub(super) type DecodedSourceGraph = (
+    ProxyConfig,
+    BTreeSet<PathBuf>,
+    BTreeMap<PathBuf, String>,
+    String,
+);
+
+pub(super) fn decode_source_graph(graph: ConfigSourceGraph) -> Result<DecodedSourceGraph> {
+    let ConfigSourceGraph {
+        source_contents,
+        rendered: processed,
+    } = graph;
+    let source_files: BTreeSet<PathBuf> = source_contents.keys().cloned().collect();
+
+    let parsed_toml: toml::Value =
+        toml::from_str(&processed).map_err(|e| ProxyError::Config(e.to_string()))?;
+    handle_unknown_config_keys(&parsed_toml)?;
+    let general_table = parsed_toml
+        .get("general")
+        .and_then(|value| value.as_table());
+    let network_table = parsed_toml
+        .get("network")
+        .and_then(|value| value.as_table());
+    let server_table = parsed_toml.get("server").and_then(|value| value.as_table());
+    let conntrack_control_table = server_table
+        .and_then(|table| table.get("conntrack_control"))
+        .and_then(|value| value.as_table());
+    let update_every_is_explicit = general_table
+        .map(|table| table.contains_key("update_every"))
+        .unwrap_or(false);
+    let beobachten_is_explicit = general_table
+        .map(|table| table.contains_key("beobachten"))
+        .unwrap_or(false);
+    let beobachten_minutes_is_explicit = general_table
+        .map(|table| table.contains_key("beobachten_minutes"))
+        .unwrap_or(false);
+    let beobachten_flush_secs_is_explicit = general_table
+        .map(|table| table.contains_key("beobachten_flush_secs"))
+        .unwrap_or(false);
+    let beobachten_file_is_explicit = general_table
+        .map(|table| table.contains_key("beobachten_file"))
+        .unwrap_or(false);
+    let legacy_secret_is_explicit = general_table
+        .map(|table| table.contains_key("proxy_secret_auto_reload_secs"))
+        .unwrap_or(false);
+    let legacy_config_is_explicit = general_table
+        .map(|table| table.contains_key("proxy_config_auto_reload_secs"))
+        .unwrap_or(false);
+    let legacy_top_level_beobachten = parsed_toml.get("beobachten").cloned();
+    let legacy_top_level_beobachten_minutes = parsed_toml.get("beobachten_minutes").cloned();
+    let legacy_top_level_beobachten_flush_secs = parsed_toml.get("beobachten_flush_secs").cloned();
+    let legacy_top_level_beobachten_file = parsed_toml.get("beobachten_file").cloned();
+    let stun_servers_is_explicit = network_table
+        .map(|table| table.contains_key("stun_servers"))
+        .unwrap_or(false);
+    let inline_conntrack_control_is_explicit = conntrack_control_table
+        .map(|table| table.contains_key("inline_conntrack_control"))
+        .unwrap_or(false);
+
+    let mut config: ProxyConfig = parsed_toml
+        .try_into()
+        .map_err(|e| ProxyError::Config(e.to_string()))?;
+    config
+        .server
+        .conntrack_control
+        .inline_conntrack_control_explicit = inline_conntrack_control_is_explicit;
+
+    if !update_every_is_explicit && (legacy_secret_is_explicit || legacy_config_is_explicit) {
+        config.general.update_every = None;
+    }
+
+    // Backward compatibility: legacy top-level beobachten* keys.
+    // Prefer `[general].*` when both are present.
+    let mut legacy_beobachten_applied = false;
+    if !beobachten_is_explicit && let Some(value) = legacy_top_level_beobachten.as_ref() {
+        let parsed = value.as_bool().ok_or_else(|| {
+            ProxyError::Config("beobachten (top-level) must be a boolean".to_string())
+        })?;
+        config.general.beobachten = parsed;
+        legacy_beobachten_applied = true;
+    }
+    if !beobachten_minutes_is_explicit
+        && let Some(value) = legacy_top_level_beobachten_minutes.as_ref()
+    {
+        let raw = value.as_integer().ok_or_else(|| {
+            ProxyError::Config("beobachten_minutes (top-level) must be an integer".to_string())
+        })?;
+        let parsed = u64::try_from(raw).map_err(|_| {
+            ProxyError::Config(
+                "beobachten_minutes (top-level) must be within u64 range".to_string(),
+            )
+        })?;
+        config.general.beobachten_minutes = parsed;
+        legacy_beobachten_applied = true;
+    }
+    if !beobachten_flush_secs_is_explicit
+        && let Some(value) = legacy_top_level_beobachten_flush_secs.as_ref()
+    {
+        let raw = value.as_integer().ok_or_else(|| {
+            ProxyError::Config("beobachten_flush_secs (top-level) must be an integer".to_string())
+        })?;
+        let parsed = u64::try_from(raw).map_err(|_| {
+            ProxyError::Config(
+                "beobachten_flush_secs (top-level) must be within u64 range".to_string(),
+            )
+        })?;
+        config.general.beobachten_flush_secs = parsed;
+        legacy_beobachten_applied = true;
+    }
+    if !beobachten_file_is_explicit && let Some(value) = legacy_top_level_beobachten_file.as_ref() {
+        let parsed = value.as_str().ok_or_else(|| {
+            ProxyError::Config("beobachten_file (top-level) must be a string".to_string())
+        })?;
+        config.general.beobachten_file = parsed.to_string();
+        legacy_beobachten_applied = true;
+    }
+    if legacy_beobachten_applied {
+        warn!("top-level beobachten* keys are deprecated; use general.beobachten* instead");
+    }
+
+    let legacy_nat_stun = config.general.middle_proxy_nat_stun.take();
+    let legacy_nat_stun_servers = std::mem::take(&mut config.general.middle_proxy_nat_stun_servers);
+    let legacy_nat_stun_used = legacy_nat_stun.is_some() || !legacy_nat_stun_servers.is_empty();
+    if stun_servers_is_explicit {
+        let mut explicit_stun_servers = Vec::new();
+        for stun in std::mem::take(&mut config.network.stun_servers) {
+            push_unique_nonempty(&mut explicit_stun_servers, stun);
+        }
+        config.network.stun_servers = explicit_stun_servers;
+
+        if legacy_nat_stun_used {
+            warn!(
+                "general.middle_proxy_nat_stun and general.middle_proxy_nat_stun_servers are ignored because network.stun_servers is explicitly set"
+            );
+        }
+    } else {
+        // Keep the default STUN pool unless network.stun_servers is explicitly overridden.
+        let mut unified_stun_servers = default_stun_servers();
+        if let Some(stun) = legacy_nat_stun {
+            push_unique_nonempty(&mut unified_stun_servers, stun);
+        }
+        for stun in legacy_nat_stun_servers {
+            push_unique_nonempty(&mut unified_stun_servers, stun);
+        }
+
+        config.network.stun_servers = unified_stun_servers;
+
+        if legacy_nat_stun_used {
+            warn!(
+                "general.middle_proxy_nat_stun and general.middle_proxy_nat_stun_servers are deprecated; use network.stun_servers"
+            );
+        }
+    }
+
+    sanitize_ad_tag(&mut config.general.ad_tag);
+    Ok((config, source_files, source_contents, processed))
+}

src/config/load/effective.rs

@@ -0,0 +1,222 @@
+use super::*;
+
+pub(super) fn apply(config: &mut ProxyConfig) -> Result<()> {
+    // Normalize optional TLS fetch scope: whitespace-only values disable scoped routing.
+    config.censorship.tls_fetch_scope = config.censorship.tls_fetch_scope.trim().to_string();
+
+    if config.censorship.tls_fetch.profiles.is_empty() {
+        config.censorship.tls_fetch.profiles = TlsFetchConfig::default().profiles;
+    } else {
+        let mut seen = HashSet::new();
+        config
+            .censorship
+            .tls_fetch
+            .profiles
+            .retain(|profile| seen.insert(*profile));
+    }
+
+    if config.censorship.tls_fetch.attempt_timeout_ms == 0 {
+        return Err(ProxyError::Config(
+            "censorship.tls_fetch.attempt_timeout_ms must be > 0".to_string(),
+        ));
+    }
+    if config.censorship.tls_fetch.total_budget_ms == 0 {
+        return Err(ProxyError::Config(
+            "censorship.tls_fetch.total_budget_ms must be > 0".to_string(),
+        ));
+    }
+
+    // Merge primary + extra TLS domains, deduplicate (primary always first).
+    if !config.censorship.tls_domains.is_empty() {
+        let mut all = Vec::with_capacity(1 + config.censorship.tls_domains.len());
+        all.push(config.censorship.tls_domain.clone());
+        for d in std::mem::take(&mut config.censorship.tls_domains) {
+            if !d.is_empty() {
+                let domain = normalize_domain_to_ascii(&d, "censorship.tls_domains entry")?;
+                if !all.contains(&domain) {
+                    all.push(domain);
+                }
+            }
+        }
+        // keep primary as tls_domain; store remaining back to tls_domains
+        if all.len() > 1 {
+            config.censorship.tls_domains = all[1..].to_vec();
+        }
+    }
+
+    let mut exclusive_mask = HashMap::with_capacity(config.censorship.exclusive_mask.len());
+    let mut exclusive_mask_targets = HashMap::with_capacity(config.censorship.exclusive_mask.len());
+    for (domain, target) in std::mem::take(&mut config.censorship.exclusive_mask) {
+        let domain = normalize_domain_to_ascii(&domain, "censorship.exclusive_mask domain")?;
+        let target = normalize_exclusive_mask_target(&target, "censorship.exclusive_mask target")?;
+        let Some((host, port)) = parse_exclusive_mask_target(&target) else {
+            return Err(ProxyError::Config(format!(
+                "Invalid censorship.exclusive_mask target for '{}': '{}'. Expected host:port with port > 0",
+                domain, target
+            )));
+        };
+        exclusive_mask_targets.insert(
+            domain.clone(),
+            ExclusiveMaskTarget {
+                host: host.to_string(),
+                port,
+            },
+        );
+        exclusive_mask.insert(domain, target);
+    }
+    config.censorship.exclusive_mask = exclusive_mask;
+    config.censorship.exclusive_mask_targets = exclusive_mask_targets;
+
+    // Migration: prefer_ipv6 -> network.prefer.
+    if config.general.prefer_ipv6 {
+        if config.network.prefer == 4 {
+            config.network.prefer = 6;
+        }
+        warn!("prefer_ipv6 is deprecated, use [network].prefer = 6");
+    }
+
+    if config.general.use_middle_proxy && !config.general.me_secret_atomic_snapshot {
+        config.general.me_secret_atomic_snapshot = true;
+        warn!(
+            "Auto-enabled me_secret_atomic_snapshot for middle proxy mode to keep KDF key_selector/secret coherent"
+        );
+    }
+
+    validate_network_cfg(&mut config.network)?;
+    crate::network::dns_overrides::validate_entries(&config.network.dns_overrides)?;
+
+    if config.general.use_middle_proxy && config.network.ipv6 == Some(true) {
+        warn!(
+            "IPv6 with Middle Proxy is experimental and may cause KDF address mismatch; consider disabling IPv6 or ME"
+        );
+    }
+
+    // Random fake_cert_len only when default is in use.
+    if !config.censorship.tls_emulation
+        && config.censorship.fake_cert_len == default_fake_cert_len()
+    {
+        config.censorship.fake_cert_len = rand::rng().random_range(1024..4096);
+    }
+
+    // Resolve listen_tcp: explicit value wins, otherwise auto-detect.
+    // If unix socket is set → TCP only when listen_addr_ipv4 or listeners are explicitly provided.
+    // If no unix socket → TCP always (backward compat).
+    let listen_tcp = config.server.listen_tcp.unwrap_or_else(|| {
+        if config.server.listen_unix_sock.is_some() {
+            // Unix socket present: TCP only if user explicitly set addresses or listeners.
+            config.server.listen_addr_ipv4.is_some() || !config.server.listeners.is_empty()
+        } else {
+            true
+        }
+    });
+
+    // Migration: Populate listeners if empty (skip when listen_tcp = false).
+    if config.server.listeners.is_empty() && listen_tcp {
+        let ipv4_str = config
+            .server
+            .listen_addr_ipv4
+            .as_deref()
+            .unwrap_or("0.0.0.0");
+        if let Ok(ipv4) = ipv4_str.parse::<IpAddr>() {
+            config.server.listeners.push(ListenerConfig {
+                ip: ipv4,
+                transport: ListenerTransport::Mtproxy,
+                port: Some(config.server.port),
+                client_mss: None,
+                synlimit: SynLimitMode::default(),
+                synlimit_seconds: default_synlimit_seconds(),
+                synlimit_hitcount: default_synlimit_hitcount(),
+                synlimit_burst: default_synlimit_burst(),
+                synlimit_ios_seconds: default_synlimit_ios_seconds(),
+                synlimit_ios_hitcount: default_synlimit_ios_hitcount(),
+                synlimit_ios_burst: default_synlimit_ios_burst(),
+                synlimit_hashlimit_expire_ms: default_synlimit_hashlimit_expire_ms(),
+                synlimit_hashlimit_size: default_synlimit_hashlimit_size(),
+                announce: None,
+                announce_ip: None,
+                proxy_protocol: None,
+                reuse_allow: false,
+                web_client_ip_source: WebClientIpSource::XForwardedFor,
+                web_trusted_proxy_cidrs: Vec::new(),
+            });
+        }
+        if let Some(ipv6_str) = &config.server.listen_addr_ipv6
+            && let Ok(ipv6) = ipv6_str.parse::<IpAddr>()
+        {
+            config.server.listeners.push(ListenerConfig {
+                ip: ipv6,
+                transport: ListenerTransport::Mtproxy,
+                port: Some(config.server.port),
+                client_mss: None,
+                synlimit: SynLimitMode::default(),
+                synlimit_seconds: default_synlimit_seconds(),
+                synlimit_hitcount: default_synlimit_hitcount(),
+                synlimit_burst: default_synlimit_burst(),
+                synlimit_ios_seconds: default_synlimit_ios_seconds(),
+                synlimit_ios_hitcount: default_synlimit_ios_hitcount(),
+                synlimit_ios_burst: default_synlimit_ios_burst(),
+                synlimit_hashlimit_expire_ms: default_synlimit_hashlimit_expire_ms(),
+                synlimit_hashlimit_size: default_synlimit_hashlimit_size(),
+                announce: None,
+                announce_ip: None,
+                proxy_protocol: None,
+                reuse_allow: false,
+                web_client_ip_source: WebClientIpSource::XForwardedFor,
+                web_trusted_proxy_cidrs: Vec::new(),
+            });
+        }
+    }
+
+    // Migration: listeners[].port fallback to legacy server.port.
+    for listener in &mut config.server.listeners {
+        if listener.port.is_none() {
+            listener.port = Some(config.server.port);
+        }
+    }
+
+    // Migration: announce_ip → announce for each listener.
+    for listener in &mut config.server.listeners {
+        if listener.announce.is_none()
+            && let Some(ip) = listener.announce_ip.take()
+        {
+            listener.announce = Some(ip.to_string());
+        }
+    }
+    validate_listener_runtime_profiles(config)?;
+
+    // Migration: show_link (top-level) → general.links.show.
+    if !config.show_link.is_empty() && config.general.links.show.is_empty() {
+        config.general.links.show = config.show_link.clone();
+    }
+
+    // Migration: Populate upstreams if empty (Default Direct).
+    if config.upstreams.is_empty() {
+        config.upstreams.push(UpstreamConfig {
+            upstream_type: UpstreamType::Direct {
+                interface: None,
+                bind_addresses: None,
+                bindtodevice: None,
+            },
+            weight: 1,
+            enabled: true,
+            scopes: String::new(),
+            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
+            prefer: None,
+        });
+    }
+    normalize_upstream_family_policy(config);
+
+    // Ensure default DC203 override is present.
+    config
+        .dc_overrides
+        .entry("203".to_string())
+        .or_insert_with(|| vec!["91.105.192.100:443".to_string()]);
+
+    validate_logging_config(&config.logging)?;
+    validate_upstreams(config)?;
+    config.rebuild_runtime_user_auth()?;
+    config.rebuild_runtime_web()?;
+    Ok(())
+}

src/config/load/includes.rs

@@ -0,0 +1,70 @@
+use std::collections::{BTreeMap, 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>,
+    source_contents: &mut BTreeMap<PathBuf, String>,
+    source_overrides: &BTreeMap<PathBuf, String>,
+) -> 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);
+                let normalized = normalize_config_path(&resolved);
+                source_files.insert(normalized.clone());
+                let included = source_overrides
+                    .get(&normalized)
+                    .cloned()
+                    .map(Ok)
+                    .unwrap_or_else(|| std::fs::read_to_string(&resolved))
+                    .map_err(|e| ProxyError::Config(e.to_string()))?;
+                source_contents.insert(normalized, included.clone());
+                let included_dir = resolved.parent().unwrap_or(base_dir);
+                output.push_str(&preprocess_includes(
+                    &included,
+                    included_dir,
+                    depth + 1,
+                    source_files,
+                    source_contents,
+                    source_overrides,
+                )?);
+                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/pipeline.rs

@@ -0,0 +1,18 @@
+use super::*;
+
+pub(super) fn load_source_graph(graph: ConfigSourceGraph) -> Result<LoadedConfig> {
+    let (mut config, source_files, source_contents, processed) =
+        decode::decode_source_graph(graph)?;
+    validate_core::validate(&mut config)?;
+    validate_runtime::validate(&mut config)?;
+    validate_me::validate(&mut config)?;
+    validate_server::validate(&mut config)?;
+    validate_web::validate(&mut config)?;
+    effective::apply(&mut config)?;
+    Ok(LoadedConfig {
+        config,
+        source_files: source_files.into_iter().collect(),
+        source_contents,
+        rendered_hash: hash_rendered_snapshot(&processed),
+    })
+}