Update Cargo.toml

Co-Authored-By: Aleksandr Kalashnikov <33665156+sleep3r@users.noreply.github.com>

.dockerignore

@@ -0,0 +1,8 @@
+.git
+.github
+target
+.kilocode
+cache
+tlsfront
+*.tar
+*.tar.gz

.github/codeql/codeql-config.yml

@@ -7,7 +7,16 @@ queries:
   - uses: security-and-quality
   - uses: ./.github/codeql/queries
 
+paths-ignore:
+  - "**/tests/**"
+  - "**/test/**"
+  - "**/*_test.rs"
+  - "**/*/tests.rs"
 query-filters:
+  - exclude:
+      tags:
+        - test
+
   - exclude:
       id:
         - rust/unwrap-on-option

.github/workflows/build.yml

@@ -0,0 +1,39 @@
+name: Build
+
+on:
+  push:
+    branches: [ "*" ]
+  pull_request:
+    branches: [ "*" ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install latest stable Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo registry & build artifacts
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Build Release
+        run: cargo build --release --verbose

.github/workflows/release.yml

@@ -5,37 +5,87 @@ on:
     tags:
       - '[0-9]+.[0-9]+.[0-9]+'
   workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag (example: 3.3.15)'
+        required: true
+        type: string
+
+concurrency:
+  group: release-${{ github.ref_name }}-${{ github.event.inputs.tag || 'auto' }}
+  cancel-in-progress: true
 
 permissions:
   contents: read
-  packages: write
 
 env:
   CARGO_TERM_COLOR: always
+  BINARY_NAME: telemt
 
 jobs:
-  build:
-    name: Build ${{ matrix.target }}
+  prepare:
+    name: Prepare
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
+
+    outputs:
+      version: ${{ steps.vars.outputs.version }}
+      prerelease: ${{ steps.vars.outputs.prerelease }}
+
+    steps:
+      - name: Resolve version
+        id: vars
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
+            VERSION="${{ github.event.inputs.tag }}"
+          else
+            VERSION="${GITHUB_REF#refs/tags/}"
+          fi
+
+          VERSION="${VERSION#refs/tags/}"
+
+          if [ -z "${VERSION}" ]; then
+            echo "Release version is empty" >&2
+            exit 1
+          fi
+
+          if [[ "${VERSION}" == *-* ]]; then
+            PRERELEASE=true
+          else
+            PRERELEASE=false
+          fi
+
+          echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
+          echo "prerelease=${PRERELEASE}" >> "${GITHUB_OUTPUT}"
+
+  # ==========================
+  # GNU / glibc
+  # ==========================
+  build-gnu:
+    name: GNU ${{ matrix.asset }}
+    runs-on: ubuntu-latest
+    needs: prepare
+
+    container:
+      image: rust:slim-bookworm
 
     strategy:
       fail-fast: false
       matrix:
         include:
           - target: x86_64-unknown-linux-gnu
-            artifact_name: telemt
-            asset_name: telemt-x86_64-linux-gnu
+            asset: telemt-x86_64-linux-gnu
+            cpu: baseline
+
+          - target: x86_64-unknown-linux-gnu
+            asset: telemt-x86_64-v3-linux-gnu
+            cpu: v3
+
           - target: aarch64-unknown-linux-gnu
-            artifact_name: telemt
-            asset_name: telemt-aarch64-linux-gnu
-          - target: x86_64-unknown-linux-musl
-            artifact_name: telemt
-            asset_name: telemt-x86_64-linux-musl
-          - target: aarch64-unknown-linux-musl
-            artifact_name: telemt
-            asset_name: telemt-aarch64-linux-musl
+            asset: telemt-aarch64-linux-gnu
+            cpu: generic
 
     steps:
       - uses: actions/checkout@v4
@@ -43,47 +93,245 @@ jobs:
       - uses: dtolnay/rust-toolchain@v1
         with:
           toolchain: stable
-          targets: ${{ matrix.target }}
+          targets: |
+            x86_64-unknown-linux-gnu
+            aarch64-unknown-linux-gnu
 
-      - name: Install cross-compilation tools
+      - name: Install deps
         run: |
-          sudo apt-get update
-          sudo apt-get install -y gcc-aarch64-linux-gnu
+          apt-get update
+          apt-get install -y \
+            build-essential \
+            clang \
+            lld \
+            pkg-config \
+            gcc-aarch64-linux-gnu \
+            g++-aarch64-linux-gnu
 
       - uses: actions/cache@v4
         with:
           path: |
-            ~/.cargo/registry
-            ~/.cargo/git
+            /usr/local/cargo/registry
+            /usr/local/cargo/git
             target
-          key: ${{ runner.os }}-${{ matrix.target }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          key: gnu-${{ matrix.asset }}-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: |
-            ${{ runner.os }}-${{ matrix.target }}-cargo-
+            gnu-${{ matrix.asset }}-
+            gnu-
 
-      - name: Install cross
-        run: cargo install cross --git https://github.com/cross-rs/cross
-
-      - name: Build Release
-        env:
-          RUSTFLAGS: ${{ contains(matrix.target, 'musl') && '-C target-feature=+crt-static' || '' }}
-        run: cross build --release --target ${{ matrix.target }}
-
-      - name: Package binary
+      - name: Build
+        shell: bash
         run: |
-          cd target/${{ matrix.target }}/release
-          tar -czvf ${{ matrix.asset_name }}.tar.gz ${{ matrix.artifact_name }}
-          sha256sum ${{ matrix.asset_name }}.tar.gz > ${{ matrix.asset_name }}.sha256
+          set -euo pipefail
+
+          if [ "${{ matrix.target }}" = "aarch64-unknown-linux-gnu" ]; then
+            export CC=aarch64-linux-gnu-gcc
+            export CXX=aarch64-linux-gnu-g++
+            export RUSTFLAGS="-C linker=aarch64-linux-gnu-gcc -C lto=fat -C panic=abort"
+          else
+            export CC=clang
+            export CXX=clang++
+
+            if [ "${{ matrix.cpu }}" = "v3" ]; then
+              CPU_FLAGS="-C target-cpu=x86-64-v3"
+            else
+              CPU_FLAGS="-C target-cpu=x86-64"
+            fi
+
+            export RUSTFLAGS="-C linker=clang -C link-arg=-fuse-ld=lld -C lto=fat -C panic=abort ${CPU_FLAGS}"
+          fi
+
+          cargo build --release --target ${{ matrix.target }} -j "$(nproc)"
+
+      - name: Package
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          mkdir -p dist
+          cp "target/${{ matrix.target }}/release/${{ env.BINARY_NAME }}" dist/telemt
+
+          cd dist
+          tar -czf "${{ matrix.asset }}.tar.gz" \
+            --owner=0 --group=0 --numeric-owner \
+            telemt
+
+          sha256sum "${{ matrix.asset }}.tar.gz" > "${{ matrix.asset }}.tar.gz.sha256"
 
       - uses: actions/upload-artifact@v4
         with:
-          name: ${{ matrix.asset_name }}
-          path: |
-            target/${{ matrix.target }}/release/${{ matrix.asset_name }}.tar.gz
-            target/${{ matrix.target }}/release/${{ matrix.asset_name }}.sha256
+          name: ${{ matrix.asset }}
+          path: dist/*
 
-  build-docker-image:
-    needs: build
+  # ==========================
+  # MUSL
+  # ==========================
+  build-musl:
+    name: MUSL ${{ matrix.asset }}
     runs-on: ubuntu-latest
+    needs: prepare
+
+    container:
+      image: rust:slim-bookworm
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-musl
+            asset: telemt-x86_64-linux-musl
+            cpu: baseline
+
+          - target: x86_64-unknown-linux-musl
+            asset: telemt-x86_64-v3-linux-musl
+            cpu: v3
+
+          - target: aarch64-unknown-linux-musl
+            asset: telemt-aarch64-linux-musl
+            cpu: generic
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install deps
+        run: |
+          apt-get update
+          apt-get install -y \
+            musl-tools \
+            pkg-config \
+            curl
+
+      - uses: actions/cache@v4
+        if: matrix.target == 'aarch64-unknown-linux-musl'
+        with:
+          path: ~/.musl-aarch64
+          key: musl-toolchain-aarch64-v1
+
+      - name: Install aarch64 musl toolchain
+        if: matrix.target == 'aarch64-unknown-linux-musl'
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          TOOLCHAIN_DIR="$HOME/.musl-aarch64"
+          ARCHIVE="aarch64-linux-musl-cross.tgz"
+          URL="https://github.com/telemt/telemt/releases/download/toolchains/${ARCHIVE}"
+
+          if [ -x "${TOOLCHAIN_DIR}/bin/aarch64-linux-musl-gcc" ]; then
+            echo "MUSL toolchain cached"
+          else
+            curl -fL \
+              --retry 5 \
+              --retry-delay 3 \
+              --connect-timeout 10 \
+              --max-time 120 \
+              -o "${ARCHIVE}" "${URL}"
+
+            mkdir -p "${TOOLCHAIN_DIR}"
+            tar -xzf "${ARCHIVE}" --strip-components=1 -C "${TOOLCHAIN_DIR}"
+          fi
+
+          echo "${TOOLCHAIN_DIR}/bin" >> "${GITHUB_PATH}"
+
+      - name: Add rust target
+        run: rustup target add ${{ matrix.target }}
+
+      - uses: actions/cache@v4
+        with:
+          path: |
+            /usr/local/cargo/registry
+            /usr/local/cargo/git
+            target
+          key: musl-${{ matrix.asset }}-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            musl-${{ matrix.asset }}-
+            musl-
+
+      - name: Build
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [ "${{ matrix.target }}" = "aarch64-unknown-linux-musl" ]; then
+            export CC=aarch64-linux-musl-gcc
+            export CC_aarch64_unknown_linux_musl=aarch64-linux-musl-gcc
+            export RUSTFLAGS="-C target-feature=+crt-static -C linker=aarch64-linux-musl-gcc -C lto=fat -C panic=abort"
+          else
+            export CC=musl-gcc
+            export CC_x86_64_unknown_linux_musl=musl-gcc
+
+            if [ "${{ matrix.cpu }}" = "v3" ]; then
+              CPU_FLAGS="-C target-cpu=x86-64-v3"
+            else
+              CPU_FLAGS="-C target-cpu=x86-64"
+            fi
+
+            export RUSTFLAGS="-C target-feature=+crt-static -C lto=fat -C panic=abort ${CPU_FLAGS}"
+          fi
+
+          cargo build --release --target ${{ matrix.target }} -j "$(nproc)"
+
+      - name: Package
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          mkdir -p dist
+          cp "target/${{ matrix.target }}/release/${{ env.BINARY_NAME }}" dist/telemt
+
+          cd dist
+          tar -czf "${{ matrix.asset }}.tar.gz" \
+            --owner=0 --group=0 --numeric-owner \
+            telemt
+
+          sha256sum "${{ matrix.asset }}.tar.gz" > "${{ matrix.asset }}.tar.gz.sha256"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.asset }}
+          path: dist/*
+
+  # ==========================
+  # Release
+  # ==========================
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: [prepare, build-gnu, build-musl]
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: Flatten artifacts
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p dist
+          find artifacts -type f -exec cp {} dist/ \;
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.prepare.outputs.version }}
+          target_commitish: ${{ github.sha }}
+          files: dist/*
+          generate_release_notes: true
+          prerelease: ${{ needs.prepare.outputs.prerelease == 'true' }}
+          overwrite_files: true
+
+  # ==========================
+  # Docker
+  # ==========================
+  docker:
+    name: Docker
+    runs-on: ubuntu-latest
+    needs: [prepare, release]
+
     permissions:
       contents: read
       packages: write
@@ -92,48 +340,66 @@ jobs:
       - uses: actions/checkout@v4
 
       - uses: docker/setup-qemu-action@v3
+
       - uses: docker/setup-buildx-action@v3
 
-      - name: Login to GHCR
-        uses: docker/login-action@v3
+      - uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Extract version
-        id: vars
-        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+      - name: Probe release assets
+        shell: bash
+        env:
+          VERSION: ${{ needs.prepare.outputs.version }}
+        run: |
+          set -euo pipefail
 
-      - name: Build and push
+          for asset in \
+            telemt-x86_64-linux-musl.tar.gz \
+            telemt-x86_64-linux-musl.tar.gz.sha256 \
+            telemt-aarch64-linux-musl.tar.gz \
+            telemt-aarch64-linux-musl.tar.gz.sha256
+          do
+            curl -fsIL \
+              --retry 10 \
+              --retry-delay 3 \
+              "https://github.com/${GITHUB_REPOSITORY}/releases/download/${VERSION}/${asset}" \
+              > /dev/null
+          done
+
+      - name: Compute image tags
+        id: meta
+        shell: bash
+        env:
+          VERSION: ${{ needs.prepare.outputs.version }}
+        run: |
+          set -euo pipefail
+
+          IMAGE="$(echo "ghcr.io/${GITHUB_REPOSITORY}" | tr '[:upper:]' '[:lower:]')"
+          TAGS="${IMAGE}:${VERSION}"
+
+          if [[ "${VERSION}" != *-* ]]; then
+            TAGS="${TAGS}"$'\n'"${IMAGE}:latest"
+          fi
+
+          {
+            echo "tags<<EOF"
+            printf '%s\n' "${TAGS}"
+            echo "EOF"
+          } >> "${GITHUB_OUTPUT}"
+
+      - name: Build & Push
         uses: docker/build-push-action@v6
         with:
           context: .
           push: true
-          tags: |
-            ghcr.io/${{ github.repository }}:${{ steps.vars.outputs.VERSION }}
-            ghcr.io/${{ github.repository }}:latest
-
-  release:
-    name: Create Release
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/download-artifact@v4
-        with:
-          path: artifacts
-
-      - name: Create Release
-        uses: softprops/action-gh-release@v2
-        with:
-          files: artifacts/**/*
-          generate_release_notes: true
-          draft: false
-          prerelease: ${{ contains(github.ref, '-rc') || contains(github.ref, '-beta') || contains(github.ref, '-alpha') }}
+          pull: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          build-args: |
+            TELEMT_REPOSITORY=${{ github.repository }}
+            TELEMT_VERSION=${{ needs.prepare.outputs.version }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/rust.yml

@@ -1,54 +0,0 @@
-name: Rust
-
-on:
-  push:
-    branches: [ "*" ]
-  pull_request:
-    branches: [ "*" ]
-
-env:
-  CARGO_TERM_COLOR: always
-
-jobs:
-  build:
-    name: Build
-    runs-on: ubuntu-latest
-
-    permissions:
-      contents: read
-      actions: write
-      checks: write
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-
-    - name: Install latest stable Rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-      with:
-        components: rustfmt, clippy
-
-    - name: Cache cargo registry & build artifacts
-      uses: actions/cache@v4
-      with:
-        path: |
-          ~/.cargo/registry
-          ~/.cargo/git
-          target
-        key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
-        restore-keys: |
-          ${{ runner.os }}-cargo-
-
-    - name: Build Release
-      run: cargo build --release --verbose
-
-    - name: Run tests
-      run: cargo test --verbose
-
-# clippy dont fail on warnings because of active development of telemt 
-# and many warnings
-    - name: Run clippy
-      run: cargo clippy -- --cap-lints warn
-
-    - name: Check for unused dependencies
-      run: cargo udeps || true

.github/workflows/test.yml

@@ -0,0 +1,139 @@
+name: Check
+
+on:
+  push:
+    branches: [ "*" ]
+  pull_request:
+    branches: [ "*" ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+# ==========================
+# Formatting
+# ==========================
+  fmt:
+    name: Fmt
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+
+      - run: cargo fmt -- --check
+
+# ==========================
+# Tests
+# ==========================
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      actions: write
+      checks: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-nextest-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-nextest-
+            ${{ runner.os }}-cargo-
+
+      - name: Install cargo-nextest
+        run: cargo install --locked cargo-nextest || true
+
+      - name: Run tests with nextest
+        run: cargo nextest run -j "$(nproc)"
+
+# ==========================
+# Clippy
+# ==========================
+  clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      checks: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-clippy-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-clippy-
+            ${{ runner.os }}-cargo-
+
+      - name: Run clippy
+        run: cargo clippy -j "$(nproc)" -- --cap-lints warn
+
+# ==========================
+# Udeps
+# ==========================
+  udeps:
+    name: Udeps
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rust-src
+
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-udeps-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-udeps-
+            ${{ runner.os }}-cargo-
+
+      - name: Install cargo-udeps
+        run: cargo install --locked cargo-udeps || true
+
+      - name: Run udeps
+        run: cargo udeps -j "$(nproc)" || true

.gitignore

@@ -21,3 +21,4 @@ target
 #.idea/
 
 proxy-secret
+coverage-html/

AGENTS.md

@@ -390,6 +390,12 @@ you MUST explain why existing invariants remain valid.
 - Do not modify existing tests unless the task explicitly requires it.
 - Do not weaken assertions.
 - Preserve determinism in testable components.
+- Bug-first forces the discipline of proving you understand a bug before you fix it. Tests written after a fix almost always pass trivially and catch nothing new.
+- Invariants over scenarios is the core shift. The route_mode table alone would have caught both BUG-1 and BUG-2 before they were written — "snapshot equals watch state after any transition burst" is a two-line property test that fails immediately on the current diverged-atomics code.
+- Differential/model catches logic drift over time.
+- Scheduler pressure is specifically aimed at the concurrent state bugs that keep reappearing. A single-threaded happy-path test of set_mode will never find subtle bugs; 10,000 concurrent calls will find it on the first run.
+- Mutation gate answers your original complaint directly. It measures test power. If you can remove a bounds check and nothing breaks, the suite isn't covering that branch yet — it just says so explicitly.
+- Dead parameter is a code smell rule. 
 
 ### 15. Security Constraints
 

CODE_OF_CONDUCT.md

@@ -0,0 +1,212 @@
+# Code of Conduct
+
+## 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.
+
+> **Zweck bestimmt die Form.**
+
+> Purpose defines form.
+
+---
+
+## Principles
+
+* **Technical over emotional**
+
+  Arguments are grounded in data, logs, reproducible cases, or clear reasoning.
+
+* **Clarity over noise**
+
+  Communication is structured, concise, and relevant.
+
+* **Openness with standards**
+
+  Participation is open. The work remains disciplined.
+
+* **Independence of judgment**
+
+  Claims are evaluated on technical merit, not affiliation or posture.
+
+* **Responsibility over capability**
+
+  Capability does not justify careless use.
+
+* **Cooperation over friction**
+
+  Progress depends on coordination, mutual support, and honest review.
+
+* **Good intent, rigorous method**
+
+  Assume good intent, but require rigor.
+
+> **Aussagen gelten nach ihrer Begründung.**
+
+> Claims are weighed by evidence.
+
+---
+
+## Expected Behavior
+
+Participants are expected to:
+
+* Communicate directly and respectfully
+* Support claims with evidence
+* Stay within technical scope
+* Accept critique and provide it constructively
+* Reduce noise, duplication, and ambiguity
+* Help others reach correct and reproducible outcomes
+* Act in a way that improves the system as a whole
+
+Precision is learned.
+
+New contributors are welcome. They are expected to grow into these standards. Existing contributors are expected to make that growth possible.
+
+> **Wer behauptet, belegt.**
+
+> Whoever claims, proves.
+
+---
+
+## Unacceptable Behavior
+
+The following is not allowed:
+
+* Personal attacks, insults, harassment, or intimidation
+* Repeatedly derailing discussion away from Telemt’s purpose
+* Spam, flooding, or repeated low-quality input
+* Misinformation presented as fact
+* Attempts to degrade, destabilize, or exhaust Telemt or its participants
+* Use of Telemt or its spaces to enable harm
+
+Telemt is not a venue for disputes that displace technical work.
+Such discussions may be closed, removed, or redirected.
+
+> **Störung ist kein Beitrag.**
+
+> Disruption is not contribution.
+
+---
+
+## Security and Misuse
+
+Telemt is intended for responsible use.
+
+* Do not use it to plan, coordinate, or execute harm
+* Do not publish vulnerabilities without responsible disclosure
+* Report security issues privately where possible
+
+Security is both technical and behavioral.
+
+> **Verantwortung endet nicht am Code.**
+
+> Responsibility does not end at the code.
+
+---
+
+## 6. Openness
+
+Telemt is open to contributors of different backgrounds, experience levels, and working styles.
+
+- Standards are public, legible, and applied to the work itself.
+- Questions are welcome. Careful disagreement is welcome. Honest correction is welcome.
+- Gatekeeping by obscurity, status signaling, or hostility is not.
+
+---
+
+## Scope
+
+This Code of Conduct applies to all official spaces:
+
+* Source repositories (issues, pull requests, discussions)
+* Documentation
+* Communication channels associated with Telemt
+
+---
+
+## Maintainer Stewardship
+
+Maintainers are responsible for final decisions in matters of conduct, scope, and direction.
+
+This responsibility is stewardship: 
+- preserving continuity, 
+- protecting signal, 
+- maintaining standards, 
+- keeping Telemt workable for others.
+
+Judgment should be exercised with restraint, consistency, and institutional responsibility.
+- Not every decision requires extended debate.
+- Not every intervention requires public explanation.
+
+All decisions are expected to serve the durability, clarity, and integrity of Telemt.
+
+> **Ordnung ist Voraussetzung der Funktion.**
+
+> Order is the precondition of function.
+
+---
+
+## Enforcement
+
+Maintainers may act to preserve the integrity of Telemt, including by:
+
+* Removing content
+* Locking discussions
+* Rejecting contributions
+* Restricting or banning participants
+
+Actions are taken to maintain function, continuity, and signal quality.
+- Where possible, correction is preferred to exclusion.
+- Where necessary, exclusion is preferred to decay.
+
+---
+
+## Final
+
+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.
+
+> **Ordnung ist Voraussetzung der Freiheit.**
+
+- 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.
+
+There is no neutral infrastructure, only infrastructure shaped well or poorly.
+
+> **Jedes System trägt Verantwortung.**
+
+> Every system carries responsibility.
+
+- Stability requires discipline.
+- Freedom requires structure.
+- Trust requires honesty.
+
+In the end: the system reflects its contributors.

Cargo.toml

@@ -1,8 +1,11 @@
 [package]
 name = "telemt"
-version = "3.3.20"
+version = "3.3.33"
 edition = "2024"
 
+[features]
+redteam_offline_expected_fail = []
+
 [dependencies]
 # C
 libc = "0.2"
@@ -26,24 +29,33 @@ subtle = "2.6"
 static_assertions = "1.1"
 
 # Network
-socket2 = { version = "0.5", features = ["all"] }
-nix = { version = "0.28", default-features = false, features = ["net"] }
+socket2 = { version = "0.6", features = ["all"] }
+nix = { version = "0.31", default-features = false, features = [
+  "net",
+  "user",
+  "process",
+  "fs",
+  "signal",
+] }
+shadowsocks = { version = "1.24", features = ["aead-cipher-2022"] }
 
 # Serialization
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
-toml = "0.8"
-x509-parser = "0.15"
+toml = "1.0"
+x509-parser = "0.18"
 
 # 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 = "5.5"
+dashmap = "6.1"
+arc-swap = "1.7"
 lru = "0.16"
-rand = "0.9"
+rand = "0.10"
 chrono = { version = "0.4", features = ["serde"] }
 hex = "0.4"
 base64 = "0.22"
@@ -52,23 +64,30 @@ regex = "1.11"
 crossbeam-queue = "0.3"
 num-bigint = "0.4"
 num-traits = "0.2"
+x25519-dalek = "2"
 anyhow = "1.0"
 
 # HTTP
-reqwest = { version = "0.12", features = ["rustls-tls"], default-features = false }
-notify = { version = "6", features = ["macos_fsevent"] }
-ipnetwork = "0.20"
+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 = ["tls12"] }
-rustls = { version = "0.23", default-features = false, features = ["std", "tls12", "ring"] }
-webpki-roots = "0.26"
+tokio-rustls = { version = "0.26", default-features = false, features = [
+  "tls12",
+] }
+rustls = { version = "0.23", default-features = false, features = [
+  "std",
+  "tls12",
+  "ring",
+] }
+webpki-roots = "1.0"
 
 [dev-dependencies]
 tokio-test = "0.4"
-criterion = "0.5"
+criterion = "0.8"
 proptest = "1.4"
 futures = "0.3"
 
@@ -77,4 +96,6 @@ name = "crypto_bench"
 harness = false
 
 [profile.release]
-lto = "thin"
+lto = "fat"
+codegen-units = 1
+

Dockerfile

@@ -1,43 +1,98 @@
-# ==========================
-# Stage 1: Build
-# ==========================
-FROM rust:1.88-slim-bookworm AS builder
+# syntax=docker/dockerfile:1
 
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    pkg-config \
-    && rm -rf /var/lib/apt/lists/*
-
-WORKDIR /build
-
-COPY Cargo.toml Cargo.lock* ./
-RUN mkdir src && echo 'fn main() {}' > src/main.rs && \
-    cargo build --release 2>/dev/null || true && \
-    rm -rf src
-
-COPY . .
-RUN cargo build --release && strip target/release/telemt
+ARG TELEMT_REPOSITORY=telemt/telemt
+ARG TELEMT_VERSION=latest
 
 # ==========================
-# Stage 2: Runtime
+# Minimal Image
 # ==========================
-FROM debian:bookworm-slim
+FROM debian:12-slim AS minimal
 
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    ca-certificates \
-    && rm -rf /var/lib/apt/lists/*
+ARG TARGETARCH
+ARG TELEMT_REPOSITORY
+ARG TELEMT_VERSION
 
-RUN useradd -r -s /usr/sbin/nologin telemt
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+        binutils \
+        ca-certificates \
+        curl \
+        tar; \
+    rm -rf /var/lib/apt/lists/*
+
+RUN set -eux; \
+    case "${TARGETARCH}" in \
+        amd64) ASSET="telemt-x86_64-linux-musl.tar.gz" ;; \
+        arm64) ASSET="telemt-aarch64-linux-musl.tar.gz" ;; \
+        *) echo "Unsupported TARGETARCH: ${TARGETARCH}" >&2; exit 1 ;; \
+    esac; \
+    VERSION="${TELEMT_VERSION#refs/tags/}"; \
+    if [ -z "${VERSION}" ] || [ "${VERSION}" = "latest" ]; then \
+        BASE_URL="https://github.com/${TELEMT_REPOSITORY}/releases/latest/download"; \
+    else \
+        BASE_URL="https://github.com/${TELEMT_REPOSITORY}/releases/download/${VERSION}"; \
+    fi; \
+    curl -fL \
+        --retry 5 \
+        --retry-delay 3 \
+        --connect-timeout 10 \
+        --max-time 120 \
+        -o "/tmp/${ASSET}" \
+        "${BASE_URL}/${ASSET}"; \
+    curl -fL \
+        --retry 5 \
+        --retry-delay 3 \
+        --connect-timeout 10 \
+        --max-time 120 \
+        -o "/tmp/${ASSET}.sha256" \
+        "${BASE_URL}/${ASSET}.sha256"; \
+    cd /tmp; \
+    sha256sum -c "${ASSET}.sha256"; \
+    tar -xzf "${ASSET}" -C /tmp; \
+    test -f /tmp/telemt; \
+    install -m 0755 /tmp/telemt /telemt; \
+    strip --strip-unneeded /telemt || true; \
+    rm -f "/tmp/${ASSET}" "/tmp/${ASSET}.sha256" /tmp/telemt
+
+# ==========================
+# Debug Image
+# ==========================
+FROM debian:12-slim AS debug
+
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+        ca-certificates \
+        tzdata \
+        curl \
+        iproute2 \
+        busybox; \
+    rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
 
-COPY --from=builder /build/target/release/telemt /app/telemt
+COPY --from=minimal /telemt /app/telemt
 COPY config.toml /app/config.toml
 
-RUN chown -R telemt:telemt /app
-USER telemt
-
-EXPOSE 443
-EXPOSE 9090
+EXPOSE 443 9090 9091
+
+ENTRYPOINT ["/app/telemt"]
+CMD ["config.toml"]
+
+# ==========================
+# Production Distroless on MUSL
+# ==========================
+FROM gcr.io/distroless/static-debian12 AS prod
+
+WORKDIR /app
+
+COPY --from=minimal /telemt /app/telemt
+COPY config.toml /app/config.toml
+
+USER nonroot:nonroot
+
+EXPOSE 443 9090 9091
 
 ENTRYPOINT ["/app/telemt"]
 CMD ["config.toml"]

README.md

@@ -19,9 +19,9 @@
 
 ### 🇷🇺 RU
 
-#### Релиз 3.3.15 Semistable
+#### О релизах
 
-[3.3.15](https://github.com/telemt/telemt/releases/tag/3.3.15) по итогам работы в продакшн признан одним из самых стабильных и рекомендуется к использованию, когда cutting-edge фичи некритичны!
+[3.3.27](https://github.com/telemt/telemt/releases/tag/3.3.27) даёт баланс стабильности и передового функционала, а так же последние исправления по безопасности и багам
 
 Будем рады вашему фидбеку и предложениям по улучшению — особенно в части **API**, **статистики**, **UX**
 
@@ -40,9 +40,9 @@
 
 ### 🇬🇧 EN
 
-#### Release 3.3.15 Semistable
+#### About releases
 
-[3.3.15](https://github.com/telemt/telemt/releases/tag/3.3.15) is, based on the results of his work in production, recognized as one of the most stable and recommended for use when cutting-edge features are not so necessary!
+[3.3.27](https://github.com/telemt/telemt/releases/tag/3.3.27) provides a balance of stability and advanced functionality, as well as the latest security and bug fixes
 
 We are looking forward to your feedback and improvement proposals — especially regarding **API**, **statistics**, **UX**
 

benches/crypto_bench.rs

@@ -1,5 +1,5 @@
 // Cryptobench
-use criterion::{black_box, criterion_group, Criterion};
+use criterion::{Criterion, black_box, criterion_group};
 
 fn bench_aes_ctr(c: &mut Criterion) {
     c.bench_function("aes_ctr_encrypt_64kb", |b| {
@@ -9,4 +9,4 @@ fn bench_aes_ctr(c: &mut Criterion) {
             black_box(enc.encrypt(&data))
         })
     });
-}
+}

config.toml

@@ -32,6 +32,7 @@ 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"]
 
 [server.api]

docker-compose.yml

@@ -7,6 +7,7 @@ services:
     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: /run/telemt
     volumes:

docs/API.md

@@ -497,13 +497,14 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `direct_total` | `usize` | Direct-route upstream entries. |
 | `socks4_total` | `usize` | SOCKS4 upstream entries. |
 | `socks5_total` | `usize` | SOCKS5 upstream entries. |
+| `shadowsocks_total` | `usize` | Shadowsocks upstream entries. |
 
 #### `RuntimeUpstreamQualityUpstreamData`
 | Field | Type | Description |
 | --- | --- | --- |
 | `upstream_id` | `usize` | Runtime upstream index. |
-| `route_kind` | `string` | `direct`, `socks4`, `socks5`. |
-| `address` | `string` | Upstream address (`direct` literal for direct route kind). |
+| `route_kind` | `string` | `direct`, `socks4`, `socks5`, `shadowsocks`. |
+| `address` | `string` | Upstream address (`direct` literal for direct route kind, `host:port` only for proxied upstreams). |
 | `weight` | `u16` | Selection weight. |
 | `scopes` | `string` | Configured scope selector. |
 | `healthy` | `bool` | Current health flag. |
@@ -757,13 +758,14 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `direct_total` | `usize` | Number of direct upstream entries. |
 | `socks4_total` | `usize` | Number of SOCKS4 upstream entries. |
 | `socks5_total` | `usize` | Number of SOCKS5 upstream entries. |
+| `shadowsocks_total` | `usize` | Number of Shadowsocks upstream entries. |
 
 #### `UpstreamStatus`
 | Field | Type | Description |
 | --- | --- | --- |
 | `upstream_id` | `usize` | Runtime upstream index. |
-| `route_kind` | `string` | Upstream route kind: `direct`, `socks4`, `socks5`. |
-| `address` | `string` | Upstream address (`direct` for direct route kind). Authentication fields are intentionally omitted. |
+| `route_kind` | `string` | Upstream route kind: `direct`, `socks4`, `socks5`, `shadowsocks`. |
+| `address` | `string` | Upstream address (`direct` for direct route kind, `host:port` for Shadowsocks). Authentication fields are intentionally omitted. |
 | `weight` | `u16` | Selection weight. |
 | `scopes` | `string` | Configured scope selector string. |
 | `healthy` | `bool` | Current health flag. |

docs/CONFIG_PARAMS.en.md

@@ -0,0 +1,448 @@
+# Telemt Config Parameters Reference
+
+This document lists all configuration keys accepted by `config.toml`.
+
+> [!WARNING]
+> 
+> The configuration parameters detailed in this document are intended for advanced users and fine-tuning purposes. Modifying these settings without a clear understanding of their function may lead to application instability or other unexpected behavior. Please proceed with caution and at your own risk.
+
+## Top-level keys
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| include | `String` (special directive) | `null` | — | Includes another TOML file with `include = "relative/or/absolute/path.toml"`; includes are processed recursively before parsing. |
+| show_link | `"*" \| String[]` | `[]` (`ShowLink::None`) | — | Legacy top-level link visibility selector (`"*"` for all users or explicit usernames list). |
+| dc_overrides | `Map<String, String[]>` | `{}` | — | Overrides DC endpoints for non-standard DCs; key is DC id string, value is `ip:port` list. |
+| default_dc | `u8 \| null` | `null` (effective fallback: `2` in ME routing) | — | Default DC index used for unmapped non-standard DCs. |
+
+## [general]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| data_path | `String \| null` | `null` | — | Optional runtime data directory path. |
+| prefer_ipv6 | `bool` | `false` | Deprecated. Use `network.prefer`. | Deprecated legacy IPv6 preference flag migrated to `network.prefer`. |
+| fast_mode | `bool` | `true` | — | Enables fast-path optimizations for traffic processing. |
+| use_middle_proxy | `bool` | `true` | none | Enables ME transport mode; if `false`, runtime falls back to direct DC routing. |
+| proxy_secret_path | `String \| null` | `"proxy-secret"` | Path may be `null`. | Path to Telegram infrastructure proxy-secret file used by ME handshake logic. |
+| proxy_config_v4_cache_path | `String \| null` | `"cache/proxy-config-v4.txt"` | — | Optional cache path for raw `getProxyConfig` (IPv4) snapshot. |
+| proxy_config_v6_cache_path | `String \| null` | `"cache/proxy-config-v6.txt"` | — | Optional cache path for raw `getProxyConfigV6` (IPv6) snapshot. |
+| ad_tag | `String \| null` | `null` | — | Global fallback ad tag (32 hex characters). |
+| middle_proxy_nat_ip | `IpAddr \| null` | `null` | Must be a valid IP when set. | Manual public NAT IP override used as ME address material when set. |
+| middle_proxy_nat_probe | `bool` | `true` | Auto-forced to `true` when `use_middle_proxy = true`. | Enables ME NAT probing; runtime may force it on when ME mode is active. |
+| middle_proxy_nat_stun | `String \| null` | `null` | Deprecated. Use `network.stun_servers`. | Deprecated legacy single STUN server for NAT probing. |
+| middle_proxy_nat_stun_servers | `String[]` | `[]` | Deprecated. Use `network.stun_servers`. | Deprecated legacy STUN list for NAT probing fallback. |
+| stun_nat_probe_concurrency | `usize` | `8` | Must be `> 0`. | Maximum number of parallel STUN probes during NAT/public endpoint discovery. |
+| middle_proxy_pool_size | `usize` | `8` | none | Target size of active ME writer pool. |
+| middle_proxy_warm_standby | `usize` | `16` | none | Reserved compatibility field in current runtime revision. |
+| me_init_retry_attempts | `u32` | `0` | `0..=1_000_000`. | Startup retries for ME pool initialization (`0` means unlimited). |
+| me2dc_fallback | `bool` | `true` | — | Allows fallback from ME mode to direct DC when ME startup fails. |
+| me_keepalive_enabled | `bool` | `true` | none | Enables periodic ME keepalive/ping traffic. |
+| me_keepalive_interval_secs | `u64` | `8` | none | Base ME keepalive interval in seconds. |
+| me_keepalive_jitter_secs | `u64` | `2` | none | Keepalive jitter in seconds to reduce synchronized bursts. |
+| me_keepalive_payload_random | `bool` | `true` | none | Randomizes keepalive payload bytes instead of fixed zero payload. |
+| rpc_proxy_req_every | `u64` | `0` | `0` or `10..=300`. | Interval for service `RPC_PROXY_REQ` activity signals (`0` disables). |
+| me_writer_cmd_channel_capacity | `usize` | `4096` | Must be `> 0`. | Capacity of per-writer command channel. |
+| me_route_channel_capacity | `usize` | `768` | Must be `> 0`. | Capacity of per-connection ME response route channel. |
+| me_c2me_channel_capacity | `usize` | `1024` | Must be `> 0`. | Capacity of per-client command queue (client reader -> ME sender). |
+| me_c2me_send_timeout_ms | `u64` | `4000` | `0..=60000`. | Maximum wait for enqueueing client->ME commands when the per-client queue is full (`0` keeps legacy unbounded wait). |
+| me_reader_route_data_wait_ms | `u64` | `2` | `0..=20`. | Bounded wait for routing ME DATA to per-connection queue (`0` = no wait). |
+| me_d2c_flush_batch_max_frames | `usize` | `32` | `1..=512`. | Max ME->client frames coalesced before flush. |
+| me_d2c_flush_batch_max_bytes | `usize` | `131072` | `4096..=2_097_152`. | Max ME->client payload bytes coalesced before flush. |
+| me_d2c_flush_batch_max_delay_us | `u64` | `500` | `0..=5000`. | Max microsecond wait for coalescing more ME->client frames (`0` disables timed coalescing). |
+| me_d2c_ack_flush_immediate | `bool` | `true` | — | Flushes client writer immediately after quick-ack write. |
+| me_quota_soft_overshoot_bytes | `u64` | `65536` | `0..=16_777_216`. | Extra per-route quota allowance (bytes) tolerated before writer-side quota enforcement drops route data. |
+| me_d2c_frame_buf_shrink_threshold_bytes | `usize` | `262144` | `4096..=16_777_216`. | Threshold for shrinking oversized ME->client frame-aggregation buffers after flush. |
+| direct_relay_copy_buf_c2s_bytes | `usize` | `65536` | `4096..=1_048_576`. | Copy buffer size for client->DC direction in direct relay. |
+| direct_relay_copy_buf_s2c_bytes | `usize` | `262144` | `8192..=2_097_152`. | Copy buffer size for DC->client direction in direct relay. |
+| crypto_pending_buffer | `usize` | `262144` | — | Max pending ciphertext buffer per client writer (bytes). |
+| max_client_frame | `usize` | `16777216` | — | Maximum allowed client MTProto frame size (bytes). |
+| desync_all_full | `bool` | `false` | — | Emits full crypto-desync forensic logs for every event. |
+| beobachten | `bool` | `true` | — | Enables per-IP forensic observation buckets. |
+| beobachten_minutes | `u64` | `10` | Must be `> 0`. | Retention window (minutes) for per-IP observation buckets. |
+| beobachten_flush_secs | `u64` | `15` | Must be `> 0`. | Snapshot flush interval (seconds) for observation output file. |
+| beobachten_file | `String` | `"cache/beobachten.txt"` | — | Observation snapshot output file path. |
+| hardswap | `bool` | `true` | none | Enables generation-based ME hardswap strategy. |
+| me_warmup_stagger_enabled | `bool` | `true` | none | Staggers extra ME warmup dials to avoid connection spikes. |
+| me_warmup_step_delay_ms | `u64` | `500` | none | Base delay in milliseconds between warmup dial steps. |
+| me_warmup_step_jitter_ms | `u64` | `300` | none | Additional random delay in milliseconds for warmup steps. |
+| me_reconnect_max_concurrent_per_dc | `u32` | `8` | none | Limits concurrent reconnect workers per DC during health recovery. |
+| me_reconnect_backoff_base_ms | `u64` | `500` | none | Initial reconnect backoff in milliseconds. |
+| me_reconnect_backoff_cap_ms | `u64` | `30000` | none | Maximum reconnect backoff cap in milliseconds. |
+| me_reconnect_fast_retry_count | `u32` | `16` | none | Immediate retry budget before long backoff behavior applies. |
+| me_single_endpoint_shadow_writers | `u8` | `2` | `0..=32`. | Additional reserve writers for one-endpoint DC groups. |
+| me_single_endpoint_outage_mode_enabled | `bool` | `true` | — | Enables aggressive outage recovery for one-endpoint DC groups. |
+| me_single_endpoint_outage_disable_quarantine | `bool` | `true` | — | Ignores endpoint quarantine in one-endpoint outage mode. |
+| me_single_endpoint_outage_backoff_min_ms | `u64` | `250` | Must be `> 0`; also `<= me_single_endpoint_outage_backoff_max_ms`. | Minimum reconnect backoff in outage mode (ms). |
+| me_single_endpoint_outage_backoff_max_ms | `u64` | `3000` | Must be `> 0`; also `>= me_single_endpoint_outage_backoff_min_ms`. | Maximum reconnect backoff in outage mode (ms). |
+| me_single_endpoint_shadow_rotate_every_secs | `u64` | `900` | — | Periodic shadow writer rotation interval (`0` disables). |
+| me_floor_mode | `"static" \| "adaptive"` | `"adaptive"` | — | Writer floor policy mode. |
+| me_adaptive_floor_idle_secs | `u64` | `90` | — | Idle time before adaptive floor may reduce one-endpoint target. |
+| me_adaptive_floor_min_writers_single_endpoint | `u8` | `1` | `1..=32`. | Minimum adaptive writer target for one-endpoint DC groups. |
+| me_adaptive_floor_min_writers_multi_endpoint | `u8` | `1` | `1..=32`. | Minimum adaptive writer target for multi-endpoint DC groups. |
+| me_adaptive_floor_recover_grace_secs | `u64` | `180` | — | Grace period to hold static floor after activity. |
+| me_adaptive_floor_writers_per_core_total | `u16` | `48` | Must be `> 0`. | Global writer budget per logical CPU core in adaptive mode. |
+| me_adaptive_floor_cpu_cores_override | `u16` | `0` | — | Manual CPU core count override (`0` uses auto-detection). |
+| me_adaptive_floor_max_extra_writers_single_per_core | `u16` | `1` | — | Per-core max extra writers above base floor for one-endpoint DCs. |
+| me_adaptive_floor_max_extra_writers_multi_per_core | `u16` | `2` | — | Per-core max extra writers above base floor for multi-endpoint DCs. |
+| me_adaptive_floor_max_active_writers_per_core | `u16` | `64` | Must be `> 0`. | Hard cap for active ME writers per logical CPU core. |
+| me_adaptive_floor_max_warm_writers_per_core | `u16` | `64` | Must be `> 0`. | Hard cap for warm ME writers per logical CPU core. |
+| me_adaptive_floor_max_active_writers_global | `u32` | `256` | Must be `> 0`. | Hard global cap for active ME writers. |
+| me_adaptive_floor_max_warm_writers_global | `u32` | `256` | Must be `> 0`. | Hard global cap for warm ME writers. |
+| upstream_connect_retry_attempts | `u32` | `2` | Must be `> 0`. | Connect attempts for selected upstream before error/fallback. |
+| upstream_connect_retry_backoff_ms | `u64` | `100` | — | Delay between upstream connect attempts (ms). |
+| upstream_connect_budget_ms | `u64` | `3000` | Must be `> 0`. | Total wall-clock budget for one upstream connect request (ms). |
+| tg_connect | `u64` | `10` | Must be `> 0`. | Per-attempt upstream TCP connect timeout to Telegram DC (seconds). |
+| upstream_unhealthy_fail_threshold | `u32` | `5` | Must be `> 0`. | Consecutive failed requests before upstream is marked unhealthy. |
+| upstream_connect_failfast_hard_errors | `bool` | `false` | — | Skips additional retries for hard non-transient connect errors. |
+| stun_iface_mismatch_ignore | `bool` | `false` | none | Reserved compatibility flag in current runtime revision. |
+| unknown_dc_log_path | `String \| null` | `"unknown-dc.txt"` | — | File path for unknown-DC request logging (`null` disables file path). |
+| unknown_dc_file_log_enabled | `bool` | `false` | — | Enables unknown-DC file logging. |
+| log_level | `"debug" \| "verbose" \| "normal" \| "silent"` | `"normal"` | — | Runtime logging verbosity. |
+| disable_colors | `bool` | `false` | — | Disables ANSI colors in logs. |
+| me_socks_kdf_policy | `"strict" \| "compat"` | `"strict"` | — | SOCKS-bound KDF fallback policy for ME handshake. |
+| me_route_backpressure_base_timeout_ms | `u64` | `25` | Must be `> 0`. | Base backpressure timeout for route-channel send (ms). |
+| me_route_backpressure_high_timeout_ms | `u64` | `120` | Must be `>= me_route_backpressure_base_timeout_ms`. | High backpressure timeout when queue occupancy exceeds watermark (ms). |
+| me_route_backpressure_high_watermark_pct | `u8` | `80` | `1..=100`. | Queue occupancy threshold (%) for high timeout mode. |
+| me_health_interval_ms_unhealthy | `u64` | `1000` | Must be `> 0`. | Health monitor interval while writer coverage is degraded (ms). |
+| me_health_interval_ms_healthy | `u64` | `3000` | Must be `> 0`. | Health monitor interval while writer coverage is healthy (ms). |
+| me_admission_poll_ms | `u64` | `1000` | Must be `> 0`. | Poll interval for conditional-admission checks (ms). |
+| me_warn_rate_limit_ms | `u64` | `5000` | Must be `> 0`. | Cooldown for repetitive ME warning logs (ms). |
+| me_route_no_writer_mode | `"async_recovery_failfast" \| "inline_recovery_legacy" \| "hybrid_async_persistent"` | `"hybrid_async_persistent"` | — | Route behavior when no writer is immediately available. |
+| me_route_no_writer_wait_ms | `u64` | `250` | `10..=5000`. | Max wait in async-recovery failfast mode (ms). |
+| me_route_hybrid_max_wait_ms | `u64` | `3000` | `50..=60000`. | Maximum cumulative wait in hybrid no-writer mode before failfast fallback (ms). |
+| me_route_blocking_send_timeout_ms | `u64` | `250` | `0..=5000`. | Maximum wait for blocking route-channel send fallback (`0` keeps legacy unbounded wait). |
+| me_route_inline_recovery_attempts | `u32` | `3` | Must be `> 0`. | Inline recovery attempts in legacy mode. |
+| me_route_inline_recovery_wait_ms | `u64` | `3000` | `10..=30000`. | Max inline recovery wait in legacy mode (ms). |
+| fast_mode_min_tls_record | `usize` | `0` | — | Minimum TLS record size when fast-mode coalescing is enabled (`0` disables). |
+| update_every | `u64 \| null` | `300` | If set: must be `> 0`; if `null`: legacy fallback path is used. | Unified refresh interval for ME config and proxy-secret updater tasks. |
+| me_reinit_every_secs | `u64` | `900` | Must be `> 0`. | Periodic interval for zero-downtime ME reinit cycle. |
+| me_hardswap_warmup_delay_min_ms | `u64` | `1000` | Must be `<= me_hardswap_warmup_delay_max_ms`. | Lower bound for hardswap warmup dial spacing. |
+| me_hardswap_warmup_delay_max_ms | `u64` | `2000` | Must be `> 0`. | Upper bound for hardswap warmup dial spacing. |
+| me_hardswap_warmup_extra_passes | `u8` | `3` | Must be within `[0, 10]`. | Additional warmup passes after the base pass in one hardswap cycle. |
+| me_hardswap_warmup_pass_backoff_base_ms | `u64` | `500` | Must be `> 0`. | Base backoff between extra hardswap warmup passes. |
+| me_config_stable_snapshots | `u8` | `2` | Must be `> 0`. | Number of identical ME config snapshots required before apply. |
+| me_config_apply_cooldown_secs | `u64` | `300` | none | Cooldown between applied ME endpoint-map updates. |
+| me_snapshot_require_http_2xx | `bool` | `true` | — | Requires 2xx HTTP responses for applying config snapshots. |
+| me_snapshot_reject_empty_map | `bool` | `true` | — | Rejects empty config snapshots. |
+| me_snapshot_min_proxy_for_lines | `u32` | `1` | Must be `> 0`. | Minimum parsed `proxy_for` rows required to accept snapshot. |
+| proxy_secret_stable_snapshots | `u8` | `2` | Must be `> 0`. | Number of identical proxy-secret snapshots required before rotation. |
+| proxy_secret_rotate_runtime | `bool` | `true` | none | Enables runtime proxy-secret rotation from updater snapshots. |
+| me_secret_atomic_snapshot | `bool` | `true` | — | Keeps selector and secret bytes from the same snapshot atomically. |
+| proxy_secret_len_max | `usize` | `256` | Must be within `[32, 4096]`. | Upper length limit for accepted proxy-secret bytes. |
+| me_pool_drain_ttl_secs | `u64` | `90` | none | Time window where stale writers remain fallback-eligible after map change. |
+| me_instadrain | `bool` | `false` | — | Forces draining stale writers to be removed on the next cleanup tick, bypassing TTL/deadline waiting. |
+| me_pool_drain_threshold | `u64` | `128` | — | Max draining stale writers before batch force-close (`0` disables threshold cleanup). |
+| me_pool_drain_soft_evict_enabled | `bool` | `true` | — | Enables gradual soft-eviction of stale writers during drain/reinit instead of immediate hard close. |
+| me_pool_drain_soft_evict_grace_secs | `u64` | `30` | `0..=3600`. | Grace period before stale writers become soft-evict candidates. |
+| me_pool_drain_soft_evict_per_writer | `u8` | `1` | `1..=16`. | Maximum stale routes soft-evicted per writer in one eviction pass. |
+| me_pool_drain_soft_evict_budget_per_core | `u16` | `8` | `1..=64`. | Per-core budget limiting aggregate soft-eviction work per pass. |
+| me_pool_drain_soft_evict_cooldown_ms | `u64` | `5000` | Must be `> 0`. | Cooldown between consecutive soft-eviction passes (ms). |
+| me_bind_stale_mode | `"never" \| "ttl" \| "always"` | `"ttl"` | — | Policy for new binds on stale draining writers. |
+| me_bind_stale_ttl_secs | `u64` | `90` | — | TTL for stale bind allowance when stale mode is `ttl`. |
+| me_pool_min_fresh_ratio | `f32` | `0.8` | Must be within `[0.0, 1.0]`. | Minimum fresh desired-DC coverage ratio before stale writers are drained. |
+| me_reinit_drain_timeout_secs | `u64` | `120` | `0` disables force-close; if `> 0` and `< me_pool_drain_ttl_secs`, runtime bumps it to TTL. | Force-close timeout for draining stale writers (`0` keeps indefinite draining). |
+| proxy_secret_auto_reload_secs | `u64` | `3600` | Deprecated. Use `general.update_every`. | Deprecated legacy secret reload interval (fallback when `update_every` is not set). |
+| proxy_config_auto_reload_secs | `u64` | `3600` | Deprecated. Use `general.update_every`. | Deprecated legacy config reload interval (fallback when `update_every` is not set). |
+| me_reinit_singleflight | `bool` | `true` | — | Serializes ME reinit cycles across trigger sources. |
+| me_reinit_trigger_channel | `usize` | `64` | Must be `> 0`. | Trigger queue capacity for reinit scheduler. |
+| me_reinit_coalesce_window_ms | `u64` | `200` | — | Trigger coalescing window before starting reinit (ms). |
+| me_deterministic_writer_sort | `bool` | `true` | — | Enables deterministic candidate sort for writer binding path. |
+| me_writer_pick_mode | `"sorted_rr" \| "p2c"` | `"p2c"` | — | Writer selection mode for route bind path. |
+| me_writer_pick_sample_size | `u8` | `3` | `2..=4`. | Number of candidates sampled by picker in `p2c` mode. |
+| ntp_check | `bool` | `true` | — | Enables NTP drift check at startup. |
+| ntp_servers | `String[]` | `["pool.ntp.org"]` | — | NTP servers used for drift check. |
+| auto_degradation_enabled | `bool` | `true` | none | Reserved compatibility flag in current runtime revision. |
+| degradation_min_unavailable_dc_groups | `u8` | `2` | none | Reserved compatibility threshold in current runtime revision. |
+
+## [general.modes]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| classic | `bool` | `false` | — | Enables classic MTProxy mode. |
+| secure | `bool` | `false` | — | Enables secure mode. |
+| tls | `bool` | `true` | — | Enables TLS mode. |
+
+## [general.links]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| show | `"*" \| String[]` | `"*"` | — | Selects users whose tg:// links are shown at startup. |
+| public_host | `String \| null` | `null` | — | Public hostname/IP override for generated tg:// links. |
+| public_port | `u16 \| null` | `null` | — | Public port override for generated tg:// links. |
+
+## [general.telemetry]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| core_enabled | `bool` | `true` | — | Enables core hot-path telemetry counters. |
+| user_enabled | `bool` | `true` | — | Enables per-user telemetry counters. |
+| me_level | `"silent" \| "normal" \| "debug"` | `"normal"` | — | Middle-End telemetry verbosity level. |
+
+## [network]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| ipv4 | `bool` | `true` | — | Enables IPv4 networking. |
+| ipv6 | `bool` | `false` | — | Enables/disables IPv6 when set |
+| prefer | `u8` | `4` | Must be `4` or `6`. | Preferred IP family for selection (`4` or `6`). |
+| multipath | `bool` | `false` | — | Enables multipath behavior where supported. |
+| stun_use | `bool` | `true` | none | Global STUN switch; when `false`, STUN probing path is disabled. |
+| stun_servers | `String[]` | Built-in STUN list (13 hosts) | Deduplicated; empty values are removed. | Primary STUN server list for NAT/public endpoint discovery. |
+| stun_tcp_fallback | `bool` | `true` | none | Enables TCP fallback for STUN when UDP path is blocked. |
+| http_ip_detect_urls | `String[]` | `["https://ifconfig.me/ip", "https://api.ipify.org"]` | none | HTTP fallback endpoints for public IP detection when STUN is unavailable. |
+| cache_public_ip_path | `String` | `"cache/public_ip.txt"` | — | File path for caching detected public IP. |
+| dns_overrides | `String[]` | `[]` | Must match `host:port:ip`; IPv6 must be bracketed. | Runtime DNS overrides in `host:port:ip` format. |
+
+## [server]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| port | `u16` | `443` | — | Main proxy listen port. |
+| listen_addr_ipv4 | `String \| null` | `"0.0.0.0"` | — | IPv4 bind address for TCP listener. |
+| listen_addr_ipv6 | `String \| null` | `"::"` | — | IPv6 bind address for TCP listener. |
+| listen_unix_sock | `String \| null` | `null` | — | Unix socket path for listener. |
+| listen_unix_sock_perm | `String \| null` | `null` | — | Unix socket permissions in octal string (e.g., `"0666"`). |
+| listen_tcp | `bool \| null` | `null` (auto) | — | Explicit TCP listener enable/disable override. |
+| proxy_protocol | `bool` | `false` | — | Enables HAProxy PROXY protocol parsing on incoming client connections. |
+| proxy_protocol_header_timeout_ms | `u64` | `500` | Must be `> 0`. | Timeout for PROXY protocol header read/parse (ms). |
+| proxy_protocol_trusted_cidrs | `IpNetwork[]` | `[]` | — | When non-empty, only connections from these proxy source CIDRs are allowed to provide PROXY protocol headers. If empty, PROXY headers are rejected by default (security hardening). |
+| metrics_port | `u16 \| null` | `null` | — | Metrics endpoint port (enables metrics listener). |
+| metrics_listen | `String \| null` | `null` | — | Full metrics bind address (`IP:PORT`), overrides `metrics_port`. |
+| metrics_whitelist | `IpNetwork[]` | `["127.0.0.1/32", "::1/128"]` | — | CIDR whitelist for metrics endpoint access. |
+| max_connections | `u32` | `10000` | — | Max concurrent client connections (`0` = unlimited). |
+| accept_permit_timeout_ms | `u64` | `250` | `0..=60000`. | Maximum wait for acquiring a connection-slot permit before the accepted connection is dropped (`0` keeps legacy unbounded wait). |
+
+Note: When `server.proxy_protocol` is enabled, incoming PROXY protocol headers are parsed from the first bytes of the connection and the client source address is replaced with `src_addr` from the header. For security, the peer source IP (the direct connection address) is verified against `server.proxy_protocol_trusted_cidrs`; if this list is empty, PROXY headers are rejected and the connection is considered untrusted. 
+
+## [server.api]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| enabled | `bool` | `true` | — | Enables control-plane REST API. |
+| listen | `String` | `"0.0.0.0:9091"` | Must be valid `IP:PORT`. | API bind address in `IP:PORT` format. |
+| whitelist | `IpNetwork[]` | `["127.0.0.0/8"]` | — | CIDR whitelist allowed to access API. |
+| auth_header | `String` | `""` | — | Exact expected `Authorization` header value (empty = disabled). |
+| request_body_limit_bytes | `usize` | `65536` | Must be `> 0`. | Maximum accepted HTTP request body size. |
+| minimal_runtime_enabled | `bool` | `true` | — | Enables minimal runtime snapshots endpoint logic. |
+| minimal_runtime_cache_ttl_ms | `u64` | `1000` | `0..=60000`. | Cache TTL for minimal runtime snapshots (ms; `0` disables cache). |
+| runtime_edge_enabled | `bool` | `false` | — | Enables runtime edge endpoints. |
+| runtime_edge_cache_ttl_ms | `u64` | `1000` | `0..=60000`. | Cache TTL for runtime edge aggregation payloads (ms). |
+| runtime_edge_top_n | `usize` | `10` | `1..=1000`. | Top-N size for edge connection leaderboard. |
+| runtime_edge_events_capacity | `usize` | `256` | `16..=4096`. | Ring-buffer capacity for runtime edge events. |
+| read_only | `bool` | `false` | — | Rejects mutating API endpoints when enabled. |
+
+## [[server.listeners]]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| ip | `IpAddr` | — | — | Listener bind IP. |
+| announce | `String \| null` | — | — | Public IP/domain announced in proxy links (priority over `announce_ip`). |
+| announce_ip | `IpAddr \| null` | — | Deprecated. Use `announce`. | Deprecated legacy announce IP (migrated to `announce` if needed). |
+| proxy_protocol | `bool \| null` | `null` | — | Per-listener override for PROXY protocol enable flag. |
+| reuse_allow | `bool` | `false` | — | Enables `SO_REUSEPORT` for multi-instance bind sharing. |
+
+## [timeouts]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| client_handshake | `u64` | `30` | — | Client handshake timeout. |
+| relay_idle_policy_v2_enabled | `bool` | `true` | — | Enables soft/hard middle-relay client idle policy. |
+| relay_client_idle_soft_secs | `u64` | `120` | Must be `> 0`; must be `<= relay_client_idle_hard_secs`. | Soft idle threshold for middle-relay client uplink inactivity (seconds). |
+| relay_client_idle_hard_secs | `u64` | `360` | Must be `> 0`; must be `>= relay_client_idle_soft_secs`. | Hard idle threshold for middle-relay client uplink inactivity (seconds). |
+| relay_idle_grace_after_downstream_activity_secs | `u64` | `30` | Must be `<= relay_client_idle_hard_secs`. | Extra hard-idle grace after recent downstream activity (seconds). |
+| client_keepalive | `u64` | `15` | — | Client keepalive timeout. |
+| client_ack | `u64` | `90` | — | Client ACK timeout. |
+| me_one_retry | `u8` | `12` | none | Fast reconnect attempts budget for single-endpoint DC scenarios. |
+| me_one_timeout_ms | `u64` | `1200` | none | Timeout in milliseconds for each quick single-endpoint reconnect attempt. |
+
+## [censorship]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| tls_domain | `String` | `"petrovich.ru"` | — | Primary TLS domain used in fake TLS handshake profile. |
+| tls_domains | `String[]` | `[]` | — | Additional TLS domains for generating multiple links. |
+| unknown_sni_action | `"drop" \| "mask"` | `"drop"` | — | Action for TLS ClientHello with unknown/non-configured SNI. |
+| tls_fetch_scope | `String` | `""` | Value is trimmed during load; empty keeps default upstream routing behavior. | Upstream scope tag used for TLS-front metadata fetches. |
+| tls_fetch | `Table` | built-in defaults | See `[censorship.tls_fetch]` section below. | TLS-front metadata fetch strategy settings. |
+| mask | `bool` | `true` | — | Enables masking/fronting relay mode. |
+| mask_host | `String \| null` | `null` | — | Upstream mask host for TLS fronting relay. |
+| mask_port | `u16` | `443` | — | Upstream mask port for TLS fronting relay. |
+| mask_unix_sock | `String \| null` | `null` | — | Unix socket path for mask backend instead of TCP host/port. |
+| fake_cert_len | `usize` | `2048` | — | Length of synthetic certificate payload when emulation data is unavailable. |
+| tls_emulation | `bool` | `true` | — | Enables certificate/TLS behavior emulation from cached real fronts. |
+| tls_front_dir | `String` | `"tlsfront"` | — | Directory path for TLS front cache storage. |
+| server_hello_delay_min_ms | `u64` | `0` | — | Minimum server_hello delay for anti-fingerprint behavior (ms). |
+| server_hello_delay_max_ms | `u64` | `0` | — | Maximum server_hello delay for anti-fingerprint behavior (ms). |
+| tls_new_session_tickets | `u8` | `0` | — | Number of `NewSessionTicket` messages to emit after handshake. |
+| tls_full_cert_ttl_secs | `u64` | `90` | — | TTL for sending full cert payload per (domain, client IP) tuple. |
+| alpn_enforce | `bool` | `true` | — | Enforces ALPN echo behavior based on client preference. |
+| mask_proxy_protocol | `u8` | `0` | — | PROXY protocol mode for mask backend (`0` disabled, `1` v1, `2` v2). |
+| mask_shape_hardening | `bool` | `true` | — | Enables client->mask shape-channel hardening by applying controlled tail padding to bucket boundaries on mask relay shutdown. |
+| mask_shape_hardening_aggressive_mode | `bool` | `false` | Requires `mask_shape_hardening = true`. | Opt-in aggressive shaping profile: allows shaping on backend-silent non-EOF paths and switches above-cap blur to strictly positive random tail. |
+| mask_shape_bucket_floor_bytes | `usize` | `512` | Must be `> 0`; should be `<= mask_shape_bucket_cap_bytes`. | Minimum bucket size used by shape-channel hardening. |
+| mask_shape_bucket_cap_bytes | `usize` | `4096` | Must be `>= mask_shape_bucket_floor_bytes`. | Maximum bucket size used by shape-channel hardening; traffic above cap is not padded further. |
+| mask_shape_above_cap_blur | `bool` | `false` | Requires `mask_shape_hardening = true`; requires `mask_shape_above_cap_blur_max_bytes > 0`. | Adds bounded randomized tail bytes even when forwarded size already exceeds cap. |
+| mask_shape_above_cap_blur_max_bytes | `usize` | `512` | Must be `<= 1048576`; must be `> 0` when `mask_shape_above_cap_blur = true`. | Maximum randomized extra bytes appended above cap. |
+| mask_relay_max_bytes | `usize` | `5242880` | Must be `> 0`; must be `<= 67108864`. | Maximum relayed bytes per direction on unauthenticated masking fallback path. |
+| mask_classifier_prefetch_timeout_ms | `u64` | `5` | Must be within `[5, 50]`. | Timeout budget (ms) for extending fragmented initial classifier window on masking fallback. |
+| mask_timing_normalization_enabled | `bool` | `false` | Requires `mask_timing_normalization_floor_ms > 0`; requires `ceiling >= floor`. | Enables timing envelope normalization on masking outcomes. |
+| mask_timing_normalization_floor_ms | `u64` | `0` | Must be `> 0` when timing normalization is enabled; must be `<= ceiling`. | Lower bound (ms) for masking outcome normalization target. |
+| mask_timing_normalization_ceiling_ms | `u64` | `0` | Must be `>= floor`; must be `<= 60000`. | Upper bound (ms) for masking outcome normalization target. |
+
+## [censorship.tls_fetch]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| profiles | `("modern_chrome_like" \| "modern_firefox_like" \| "compat_tls12" \| "legacy_minimal")[]` | `["modern_chrome_like", "modern_firefox_like", "compat_tls12", "legacy_minimal"]` | Empty list falls back to defaults; values are deduplicated preserving order. | Ordered ClientHello profile fallback chain for TLS-front metadata fetch. |
+| strict_route | `bool` | `true` | — | Fails closed on upstream-route connect errors instead of falling back to direct TCP when route is configured. |
+| attempt_timeout_ms | `u64` | `5000` | Must be `> 0`. | Timeout budget per one TLS-fetch profile attempt (ms). |
+| total_budget_ms | `u64` | `15000` | Must be `> 0`. | Total wall-clock budget across all TLS-fetch attempts (ms). |
+| grease_enabled | `bool` | `false` | — | Enables GREASE-style random values in selected ClientHello extensions for fetch traffic. |
+| deterministic | `bool` | `false` | — | Enables deterministic ClientHello randomness for debugging/tests. |
+| profile_cache_ttl_secs | `u64` | `600` | `0` disables cache. | TTL for winner-profile cache entries used by TLS fetch path. |
+
+### Shape-channel hardening notes (`[censorship]`)
+
+These parameters are designed to reduce one specific fingerprint source during masking: the exact number of bytes sent from proxy to `mask_host` for invalid or probing traffic.
+
+Without hardening, a censor can often correlate probe input length with backend-observed length very precisely (for example: `5 + body_sent` on early TLS reject paths). That creates a length-based classifier signal.
+
+When `mask_shape_hardening = true`, Telemt pads the **client->mask** stream tail to a bucket boundary at relay shutdown:
+
+- Total bytes sent to mask are first measured.
+- A bucket is selected using powers of two starting from `mask_shape_bucket_floor_bytes`.
+- Padding is added only if total bytes are below `mask_shape_bucket_cap_bytes`.
+- If bytes already exceed cap, no extra padding is added.
+
+This means multiple nearby probe sizes collapse into the same backend-observed size class, making active classification harder.
+
+What each parameter changes in practice:
+
+- `mask_shape_hardening`
+	Enables or disables this entire length-shaping stage on the fallback path.
+	When `false`, backend-observed length stays close to the real forwarded probe length.
+	When `true`, clean relay shutdown can append random padding bytes to move the total into a bucket.
+
+- `mask_shape_bucket_floor_bytes`
+	Sets the first bucket boundary used for small probes.
+	Example: with floor `512`, a malformed probe that would otherwise forward `37` bytes can be expanded to `512` bytes on clean EOF.
+	Larger floor values hide very small probes better, but increase egress cost.
+
+- `mask_shape_bucket_cap_bytes`
+	Sets the largest bucket Telemt will pad up to with bucket logic.
+	Example: with cap `4096`, a forwarded total of `1800` bytes may be padded to `2048` or `4096` depending on the bucket ladder, but a total already above `4096` will not be bucket-padded further.
+	Larger cap values increase the range over which size classes are collapsed, but also increase worst-case overhead.
+
+- Clean EOF matters in conservative mode
+	In the default profile, shape padding is intentionally conservative: it is applied on clean relay shutdown, not on every timeout/drip path.
+	This avoids introducing new timeout-tail artifacts that some backends or tests interpret as a separate fingerprint.
+
+Practical trade-offs:
+
+- Better anti-fingerprinting on size/shape channel.
+- Slightly higher egress overhead for small probes due to padding.
+- Behavior is intentionally conservative and enabled by default.
+
+Recommended starting profile:
+
+- `mask_shape_hardening = true` (default)
+- `mask_shape_bucket_floor_bytes = 512`
+- `mask_shape_bucket_cap_bytes = 4096`
+
+### Aggressive mode notes (`[censorship]`)
+
+`mask_shape_hardening_aggressive_mode` is an opt-in profile for higher anti-classifier pressure.
+
+- Default is `false` to preserve conservative timeout/no-tail behavior.
+- Requires `mask_shape_hardening = true`.
+- When enabled, backend-silent non-EOF masking paths may be shaped.
+- When enabled together with above-cap blur, the random extra tail uses `[1, max]` instead of `[0, max]`.
+
+What changes when aggressive mode is enabled:
+
+- Backend-silent timeout paths can be shaped
+	In default mode, a client that keeps the socket half-open and times out will usually not receive shape padding on that path.
+	In aggressive mode, Telemt may still shape that backend-silent session if no backend bytes were returned.
+	This is specifically aimed at active probes that try to avoid EOF in order to preserve an exact backend-observed length.
+
+- Above-cap blur always adds at least one byte
+	In default mode, above-cap blur may choose `0`, so some oversized probes still land on their exact base forwarded length.
+	In aggressive mode, that exact-base sample is removed by construction.
+
+- Tradeoff
+	Aggressive mode improves resistance to active length classifiers, but it is more opinionated and less conservative.
+	If your deployment prioritizes strict compatibility with timeout/no-tail semantics, leave it disabled.
+	If your threat model includes repeated active probing by a censor, this mode is the stronger profile.
+
+Use this mode only when your threat model prioritizes classifier resistance over strict compatibility with conservative masking semantics.
+
+### Above-cap blur notes (`[censorship]`)
+
+`mask_shape_above_cap_blur` adds a second-stage blur for very large probes that are already above `mask_shape_bucket_cap_bytes`.
+
+- A random tail in `[0, mask_shape_above_cap_blur_max_bytes]` is appended in default mode.
+- In aggressive mode, the random tail becomes strictly positive: `[1, mask_shape_above_cap_blur_max_bytes]`.
+- This reduces exact-size leakage above cap at bounded overhead.
+- Keep `mask_shape_above_cap_blur_max_bytes` conservative to avoid unnecessary egress growth.
+
+Operational meaning:
+
+- Without above-cap blur
+	A probe that forwards `5005` bytes will still look like `5005` bytes to the backend if it is already above cap.
+
+- With above-cap blur enabled
+	That same probe may look like any value in a bounded window above its base length.
+	Example with `mask_shape_above_cap_blur_max_bytes = 64`:
+	backend-observed size becomes `5005..5069` in default mode, or `5006..5069` in aggressive mode.
+
+- Choosing `mask_shape_above_cap_blur_max_bytes`
+	Small values reduce cost but preserve more separability between far-apart oversized classes.
+	Larger values blur oversized classes more aggressively, but add more egress overhead and more output variance.
+
+### Timing normalization envelope notes (`[censorship]`)
+
+`mask_timing_normalization_enabled` smooths timing differences between masking outcomes by applying a target duration envelope.
+
+- A random target is selected in `[mask_timing_normalization_floor_ms, mask_timing_normalization_ceiling_ms]`.
+- Fast paths are delayed up to the selected target.
+- Slow paths are not forced to finish by the ceiling (the envelope is best-effort shaping, not truncation).
+
+Recommended starting profile for timing shaping:
+
+- `mask_timing_normalization_enabled = true`
+- `mask_timing_normalization_floor_ms = 180`
+- `mask_timing_normalization_ceiling_ms = 320`
+
+If your backend or network is very bandwidth-constrained, reduce cap first. If probes are still too distinguishable in your environment, increase floor gradually.
+
+## [access]
+
+| Parameter | Type | Default | Constraints / validation | TOML shape example | Description |
+|---|---|---|---|---|---|
+| users | `Map<String, String>` | `{"default": "000…000"}` | Secret must be 32 hex characters. | `[access.users]`<br>`user = "32-hex secret"`<br>`user2 = "32-hex secret"` | User credentials map used for client authentication. |
+| user_ad_tags | `Map<String, String>` | `{}` | Every value must be exactly 32 hex characters. | `[access.user_ad_tags]`<br>`user = "32-hex ad_tag"` | Per-user ad tags used as override over `general.ad_tag`. |
+| user_max_tcp_conns | `Map<String, usize>` | `{}` | — | `[access.user_max_tcp_conns]`<br>`user = 500` | Per-user maximum concurrent TCP connections. |
+| user_expirations | `Map<String, DateTime<Utc>>` | `{}` | Timestamp must be valid RFC3339/ISO-8601 datetime. | `[access.user_expirations]`<br>`user = "2026-12-31T23:59:59Z"` | Per-user account expiration timestamps. |
+| user_data_quota | `Map<String, u64>` | `{}` | — | `[access.user_data_quota]`<br>`user = 1073741824` | Per-user traffic quota in bytes. |
+| user_max_unique_ips | `Map<String, usize>` | `{}` | — | `[access.user_max_unique_ips]`<br>`user = 16` | Per-user unique source IP limits. |
+| user_max_unique_ips_global_each | `usize` | `0` | — | `user_max_unique_ips_global_each = 0` | Global fallback used when `[access.user_max_unique_ips]` has no per-user override. |
+| user_max_unique_ips_mode | `"active_window" \| "time_window" \| "combined"` | `"active_window"` | — | `user_max_unique_ips_mode = "active_window"` | Unique source IP limit accounting mode. |
+| user_max_unique_ips_window_secs | `u64` | `30` | Must be `> 0`. | `user_max_unique_ips_window_secs = 30` | Window size (seconds) used by unique-IP accounting modes that use time windows. |
+| replay_check_len | `usize` | `65536` | — | `replay_check_len = 65536` | Replay-protection storage length. |
+| replay_window_secs | `u64` | `1800` | — | `replay_window_secs = 1800` | Replay-protection window in seconds. |
+| ignore_time_skew | `bool` | `false` | — | `ignore_time_skew = false` | Disables client/server timestamp skew checks in replay validation when enabled. |
+
+## [[upstreams]]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| type | `"direct" \| "socks4" \| "socks5"` | — | Required field. | Upstream transport type selector. |
+| weight | `u16` | `1` | none | Base weight used by weighted-random upstream selection. |
+| enabled | `bool` | `true` | none | Disabled entries are excluded from upstream selection at runtime. |
+| scopes | `String` | `""` | none | Comma-separated scope tags used for request-level upstream filtering. |
+| interface | `String \| null` | `null` | Optional; type-specific runtime rules apply. | Optional outbound interface/local bind hint (supported with type-specific rules). |
+| bind_addresses | `String[] \| null` | `null` | Applies to `type = "direct"`. | Optional explicit local source bind addresses for `type = "direct"`. |
+| address | `String` | — | Required for `type = "socks4"` and `type = "socks5"`. | SOCKS server endpoint (`host:port` or `ip:port`) for SOCKS upstream types. |
+| user_id | `String \| null` | `null` | Only for `type = "socks4"`. | SOCKS4 CONNECT user ID (`type = "socks4"` only). |
+| username | `String \| null` | `null` | Only for `type = "socks5"`. | SOCKS5 username (`type = "socks5"` only). |
+| password | `String \| null` | `null` | Only for `type = "socks5"`. | SOCKS5 password (`type = "socks5"` only). |

docs/FAQ.en.md

@@ -3,7 +3,7 @@
 1. Go to @MTProxybot bot.
 2. Enter the command `/newproxy`
 3. Send the server IP and port. For example: 1.2.3.4:443
-4. Open the config `nano /etc/telemt.toml`.
+4. Open the config `nano /etc/telemt/telemt.toml`.
 5. Copy and send the user secret from the [access.users] section to the bot.
 6. Copy the tag received from the bot. For example 1234567890abcdef1234567890abcdef.
 > [!WARNING]
@@ -33,6 +33,9 @@ hello = "ad_tag"
 hello2 = "ad_tag2"
 ```
 
+## Why is middle proxy (ME) needed
+https://github.com/telemt/telemt/discussions/167
+
 ## How many people can use 1 link
 
 By default, 1 link can be used by any number of people.  
@@ -60,9 +63,12 @@ user3 = "00000000000000000000000000000003"
 curl -s http://127.0.0.1:9091/v1/users | jq
 ```
 
+## "Unknown TLS SNI" Error
+You probably updated tls_domain, but users are still connecting via old links with the previous domain.
+
 ## How to view metrics
 
-1. Open the config `nano /etc/telemt.toml`
+1. Open the config `nano /etc/telemt/telemt.toml`
 2. Add the following parameters
 ```toml
 [server]
@@ -120,3 +126,17 @@ password = "pass"          # Password for Auth on SOCKS-server
 weight = 1                 # Set Weight for Scenarios
 enabled = true
 ```
+
+#### Shadowsocks as Upstream
+Requires `use_middle_proxy = false`.
+
+```toml
+[general]
+use_middle_proxy = false
+
+[[upstreams]]
+type = "shadowsocks"
+url = "ss://2022-blake3-aes-256-gcm:BASE64_KEY@1.2.3.4:8388"
+weight = 1
+enabled = true
+```

docs/FAQ.ru.md

@@ -3,7 +3,7 @@
 1. Зайти в бота @MTProxybot.
 2. Ввести команду `/newproxy`
 3. Отправить IP и порт сервера. Например: 1.2.3.4:443
-4. Открыть конфиг `nano /etc/telemt.toml`.
+4. Открыть конфиг `nano /etc/telemt/telemt.toml`.
 5. Скопировать и отправить боту секрет пользователя из раздела [access.users].
 6. Скопировать полученный tag у бота. Например 1234567890abcdef1234567890abcdef.
 > [!WARNING]
@@ -33,6 +33,10 @@ hello = "ad_tag"
 hello2 = "ad_tag2"
 ```
 
+## Зачем нужен middle proxy (ME)
+https://github.com/telemt/telemt/discussions/167
+
+
 ## Сколько человек может пользоваться 1 ссылкой
 
 По умолчанию 1 ссылкой может пользоваться сколько угодно человек.  
@@ -60,9 +64,12 @@ user3 = "00000000000000000000000000000003"
 curl -s http://127.0.0.1:9091/v1/users | jq
 ```
 
+## Ошибка "Unknown TLS SNI"
+Возможно, вы обновили tls_domain, но пользователи всё ещё пытаются подключаться по старым ссылкам с прежним доменом.
+
 ## Как посмотреть метрики
 
-1. Открыть конфиг `nano /etc/telemt.toml`
+1. Открыть конфиг `nano /etc/telemt/telemt.toml`
 2. Добавить следующие параметры
 ```toml
 [server]
@@ -121,3 +128,16 @@ weight = 1                 # Set Weight for Scenarios
 enabled = true
 ```
 
+#### Shadowsocks как Upstream
+Требует `use_middle_proxy = false`.
+
+```toml
+[general]
+use_middle_proxy = false
+
+[[upstreams]]
+type = "shadowsocks"
+url = "ss://2022-blake3-aes-256-gcm:BASE64_KEY@1.2.3.4:8388"
+weight = 1
+enabled = true
+```

docs/QUICK_START_GUIDE.en.md

@@ -27,12 +27,12 @@ chmod +x /bin/telemt
 
 **0. Check port and generate secrets**
 
-The port you have selected for use should be MISSING from the list, when:
+The port you have selected for use should not be in the list:
 ```bash
 netstat -lnp
 ```
 
-Generate 16 bytes/32 characters HEX with OpenSSL or another way:
+Generate 16 bytes/32 characters in HEX format with OpenSSL or another way:
 ```bash
 openssl rand -hex 16
 ```
@@ -50,7 +50,7 @@ Save the obtained result somewhere. You will need it later!
 
 **1. Place your config to /etc/telemt/telemt.toml**
 
-Create config directory:
+Create the config directory:
 ```bash
 mkdir /etc/telemt
 ```
@@ -59,7 +59,7 @@ Open nano
 ```bash
 nano /etc/telemt/telemt.toml
 ```
-paste your config
+Insert your configuration:
 
 ```toml
 # === General Settings ===
@@ -93,8 +93,9 @@ 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. 
-> Replace the value of the tls_domain parameter with another website.
+> 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!
 
 ---
 
@@ -105,14 +106,14 @@ useradd -d /opt/telemt -m -r -U telemt
 chown -R telemt:telemt /etc/telemt
 ```
 
-**3. Create service on /etc/systemd/system/telemt.service**
+**3. Create service in /etc/systemd/system/telemt.service**
 
 Open nano
 ```bash
 nano /etc/systemd/system/telemt.service
 ```
 
-paste this Systemd Module
+Insert this Systemd module:
 ```bash
 [Unit]
 Description=Telemt
@@ -147,13 +148,16 @@ systemctl daemon-reload
 
 **6.** For automatic startup at system boot, enter `systemctl enable telemt`
 
-**7.** To get the link(s), enter
+**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
@@ -181,6 +185,8 @@ docker compose down
 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 \

docs/QUICK_START_GUIDE.ru.md

@@ -95,6 +95,7 @@ hello = "00000000000000000000000000000000"
 > [!WARNING]
 > Замените значение параметра hello на значение, которое вы получили в пункте 0.  
 > Так же замените значение параметра tls_domain на другой сайт.
+> Изменение параметра tls_domain сделает нерабочими все ссылки, использующие старый домен!
 
 ---
 
@@ -178,11 +179,13 @@ docker compose down
 > - По умолчанию публикуются порты 443:443, а контейнер запускается со сброшенными привилегиями (добавлена только `NET_BIND_SERVICE`)  
 > - Если вам действительно нужна сеть хоста (обычно это требуется только для некоторых конфигураций IPv6), раскомментируйте `network_mode: host`
 
-**Запуск в Docker Compose**
+**Запуск без 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 \

docs/TUNING.de.md

@@ -82,7 +82,7 @@ Die unten angegebenen `Default`-Werte sind Code-Defaults (bei fehlendem Schlüss
 
 | Feld | Gilt für | Typ | Pflicht | Default | Bedeutung |
 |---|---|---|---|---|---|
-| `[[upstreams]].type` | alle Upstreams | `"direct" \| "socks4" \| "socks5"` | ja | n/a | Upstream-Transporttyp. |
+| `[[upstreams]].type` | alle Upstreams | `"direct" \| "socks4" \| "socks5" \| "shadowsocks"` | ja | n/a | Upstream-Transporttyp. |
 | `[[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. |
@@ -95,6 +95,8 @@ Die unten angegebenen `Default`-Werte sind Code-Defaults (bei fehlendem Schlüss
 | `interface` | `socks5` | `Option<String>` | nein | `null` | Wird nur genutzt, wenn `address` als `ip:port` angegeben ist. |
 | `username` | `socks5` | `Option<String>` | nein | `null` | SOCKS5 Benutzername. |
 | `password` | `socks5` | `Option<String>` | nein | `null` | SOCKS5 Passwort. |
+| `url` | `shadowsocks` | `String` | ja | n/a | Shadowsocks-SIP002-URL (`ss://...`). In Runtime-APIs wird nur `host:port` offengelegt. |
+| `interface` | `shadowsocks` | `Option<String>` | nein | `null` | Optionales ausgehendes Bind-Interface oder lokale Literal-IP. |
 
 ### Runtime-Regeln (wichtig)
 
@@ -115,6 +117,7 @@ Die unten angegebenen `Default`-Werte sind Code-Defaults (bei fehlendem Schlüss
 8. Im ME-Modus wird der gewählte Upstream auch für den ME-TCP-Dial-Pfad verwendet.
 9. Im ME-Modus ist bei `direct` mit bind/interface die STUN-Reflection bind-aware für KDF-Adressmaterial.
 10. Im ME-Modus werden bei SOCKS-Upstream `BND.ADDR/BND.PORT` für KDF verwendet, wenn gültig/öffentlich und gleiche IP-Familie.
+11. `shadowsocks`-Upstreams erfordern `general.use_middle_proxy = false`. Mit aktiviertem ME-Modus schlägt das Laden der Config sofort fehl.
 
 ## Upstream-Konfigurationsbeispiele
 
@@ -150,7 +153,20 @@ weight = 2
 enabled = true
 ```
 
-### Beispiel 4: Gemischte Upstreams mit Scopes
+### Beispiel 4: Shadowsocks-Upstream
+
+```toml
+[general]
+use_middle_proxy = false
+
+[[upstreams]]
+type = "shadowsocks"
+url = "ss://2022-blake3-aes-256-gcm:BASE64_KEY@198.51.100.50:8388"
+weight = 2
+enabled = true
+```
+
+### Beispiel 5: Gemischte Upstreams mit Scopes
 
 ```toml
 [[upstreams]]

docs/TUNING.en.md

@@ -82,7 +82,7 @@ Defaults below are code defaults (used when a key is omitted), not necessarily v
 
 | Field | Applies to | Type | Required | Default | Meaning |
 |---|---|---|---|---|---|
-| `[[upstreams]].type` | all upstreams | `"direct" \| "socks4" \| "socks5"` | yes | n/a | Upstream transport type. |
+| `[[upstreams]].type` | all upstreams | `"direct" \| "socks4" \| "socks5" \| "shadowsocks"` | yes | n/a | Upstream transport type. |
 | `[[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. |
@@ -95,6 +95,8 @@ Defaults below are code defaults (used when a key is omitted), not necessarily v
 | `interface` | `socks5` | `Option<String>` | no | `null` | Used only for SOCKS server `ip:port` dial path. |
 | `username` | `socks5` | `Option<String>` | no | `null` | SOCKS5 username auth. |
 | `password` | `socks5` | `Option<String>` | no | `null` | SOCKS5 password auth. |
+| `url` | `shadowsocks` | `String` | yes | n/a | Shadowsocks SIP002 URL (`ss://...`). Only `host:port` is exposed in runtime APIs. |
+| `interface` | `shadowsocks` | `Option<String>` | no | `null` | Optional outgoing bind interface or literal local IP. |
 
 ### Runtime rules (important)
 
@@ -115,6 +117,7 @@ Defaults below are code defaults (used when a key is omitted), not necessarily v
 8. In ME mode, the selected upstream is also used for ME TCP dial path.
 9. In ME mode for `direct` upstream with bind/interface, STUN reflection logic is bind-aware for KDF source material.
 10. In ME mode for SOCKS upstream, SOCKS `BND.ADDR/BND.PORT` is used for KDF when it is valid/public for the same family.
+11. `shadowsocks` upstreams require `general.use_middle_proxy = false`. Config load fails fast if ME mode is enabled.
 
 ## Upstream Configuration Examples
 
@@ -150,7 +153,20 @@ weight = 2
 enabled = true
 ```
 
-### Example 4: Mixed upstreams with scopes
+### Example 4: Shadowsocks upstream
+
+```toml
+[general]
+use_middle_proxy = false
+
+[[upstreams]]
+type = "shadowsocks"
+url = "ss://2022-blake3-aes-256-gcm:BASE64_KEY@198.51.100.50:8388"
+weight = 2
+enabled = true
+```
+
+### Example 5: Mixed upstreams with scopes
 
 ```toml
 [[upstreams]]

docs/TUNING.ru.md

@@ -82,7 +82,7 @@
 
 | Поле | Применимость | Тип | Обязательно | Default | Назначение |
 |---|---|---|---|---|---|
-| `[[upstreams]].type` | все upstream | `"direct" \| "socks4" \| "socks5"` | да | n/a | Тип upstream транспорта. |
+| `[[upstreams]].type` | все upstream | `"direct" \| "socks4" \| "socks5" \| "shadowsocks"` | да | n/a | Тип upstream транспорта. |
 | `[[upstreams]].weight` | все upstream | `u16` | нет | `1` | Базовый вес в weighted-random выборе. |
 | `[[upstreams]].enabled` | все upstream | `bool` | нет | `true` | Выключенные записи игнорируются на старте. |
 | `[[upstreams]].scopes` | все upstream | `String` | нет | `""` | Список scope-токенов через запятую для маршрутизации. |
@@ -95,6 +95,8 @@
 | `interface` | `socks5` | `Option<String>` | нет | `null` | Используется только если `address` задан как `ip:port`. |
 | `username` | `socks5` | `Option<String>` | нет | `null` | Логин SOCKS5 auth. |
 | `password` | `socks5` | `Option<String>` | нет | `null` | Пароль SOCKS5 auth. |
+| `url` | `shadowsocks` | `String` | да | n/a | Shadowsocks SIP002 URL (`ss://...`). В runtime API раскрывается только `host:port`. |
+| `interface` | `shadowsocks` | `Option<String>` | нет | `null` | Необязательный исходящий bind-интерфейс или literal локальный IP. |
 
 ### Runtime-правила
 
@@ -115,6 +117,7 @@
 8. В ME-режиме выбранный upstream также используется для ME TCP dial path.
 9. В ME-режиме для `direct` upstream с bind/interface STUN-рефлексия выполняется bind-aware для KDF материала.
 10. В ME-режиме для SOCKS upstream используются `BND.ADDR/BND.PORT` для KDF, если адрес валиден/публичен и соответствует IP family.
+11. `shadowsocks` upstream требует `general.use_middle_proxy = false`. При включенном ME-режиме конфиг отклоняется при загрузке.
 
 ## Примеры конфигурации Upstreams
 
@@ -150,7 +153,20 @@ weight = 2
 enabled = true
 ```
 
-### Пример 4: смешанные upstream с scopes
+### Пример 4: Shadowsocks upstream
+
+```toml
+[general]
+use_middle_proxy = false
+
+[[upstreams]]
+type = "shadowsocks"
+url = "ss://2022-blake3-aes-256-gcm:BASE64_KEY@198.51.100.50:8388"
+weight = 2
+enabled = true
+```
+
+### Пример 5: смешанные upstream с scopes
 
 ```toml
 [[upstreams]]

docs/VPS_DOUBLE_HOP.en.md

@@ -0,0 +1,287 @@
+<img src="https://gist.githubusercontent.com/avbor/1f8a128e628f47249aae6e058a57610b/raw/19013276c035e91058e0a9799ab145f8e70e3ff5/scheme.svg">
+
+## Concept
+- **Server A** (__conditionally Russian Federation_):\
+  Entry point, receives Telegram proxy user traffic via **HAProxy** (port `443`)\
+  and sends it to the tunnel to Server **B**.\
+  Internal IP in the tunnel — `10.10.10.2`\
+  Port for HAProxy clients — `443\tcp`
+- **Server B** (_conditionally Netherlands_):\
+  Exit point, runs **telemt** and accepts client connections through Server **A**.\
+  The server must have unrestricted access to Telegram servers.\
+  Internal IP in the tunnel — `10.10.10.1`\
+  AmneziaWG port — `8443\udp`\
+  Port for telemt clients — `443\tcp`
+
+---
+
+## Step 1. Setting up the AmneziaWG tunnel (A <-> B)
+[AmneziaWG](https://github.com/amnezia-vpn/amneziawg-linux-kernel-module) must be installed on all servers.\
+All following commands are given for **Ubuntu 24.04**.\
+For RHEL-based distributions, installation instructions are available at the link above.
+
+### Installing AmneziaWG (Servers A and B)
+The following steps must be performed on each server:
+
+#### 1. Adding the AmneziaWG repository and installing required packages:
+```bash
+sudo apt install -y software-properties-common python3-launchpadlib gnupg2 linux-headers-$(uname -r) && \
+sudo add-apt-repository ppa:amnezia/ppa && \
+sudo apt-get install -y amneziawg
+```
+
+#### 2. Generating a unique key pair:
+```bash
+cd /etc/amnezia/amneziawg && \
+awg genkey | tee private.key | awg pubkey > public.key
+```
+
+As a result, you will get two files in the `/etc/amnezia/amneziawg` folder:\
+`private.key` - private, and\
+`public.key` - public server keys
+
+#### 3. Configuring network interfaces:
+Obfuscation parameters `S1`, `S2`, `H1`, `H2`, `H3`, `H4` must be strictly identical on both servers.\
+Parameters `Jc`, `Jmin` and `Jmax` can differ.\
+Parameters `I1-I5` ([Custom Protocol Signature](https://docs.amnezia.org/documentation/amnezia-wg/)) must be specified on the client side (Server **A**).
+
+Recommendations for choosing values:
+
+```text
+Jc — 1 ≤ Jc ≤ 128; from 4 to 12 inclusive
+Jmin — Jmax > Jmin < 1280*; recommended 8
+Jmax — Jmin < Jmax ≤ 1280*; recommended 80
+S1 — S1 ≤ 1132* (1280* - 148 = 1132); S1 + 56 ≠ S2;
+recommended range from 15 to 150 inclusive
+S2 — S2 ≤ 1188* (1280* - 92 = 1188);
+recommended range from 15 to 150 inclusive
+H1/H2/H3/H4 — must be unique and differ from each other;
+recommended range from 5 to 2147483647 inclusive
+
+* It is assumed that the Internet connection has an MTU of 1280.
+```
+
+> [!IMPORTANT]
+> It is recommended to use your own, unique values.\
+> You can use the [generator](https://htmlpreview.github.io/?https://gist.githubusercontent.com/avbor/955782b5c37b06240b243aa375baeac5/raw/13f5517ca473b47c412b9a99407066de973732bd/awg-gen.html) to select parameters.
+
+#### Server B Configuration (Netherlands):
+
+Create the interface configuration file (`awg0`)
+```bash
+nano /etc/amnezia/amneziawg/awg0.conf
+```
+
+File content
+```ini
+[Interface]
+Address = 10.10.10.1/24
+ListenPort = 8443
+PrivateKey = <PRIVATE_KEY_SERVER_B>
+SaveConfig = true
+Jc = 4
+Jmin = 8
+Jmax = 80
+S1 = 29
+S2 = 15
+S3 = 18
+S4 = 0
+H1 = 2087563914
+H2 = 188817757
+H3 = 101784570
+H4 = 432174303
+
+[Peer]
+PublicKey = <PUBLIC_KEY_SERVER_A>
+AllowedIPs = 10.10.10.2/32
+```
+`ListenPort` - the port on which the server will wait for connections, you can choose any free one.\
+`<PRIVATE_KEY_SERVER_B>` - the content of the `private.key` file from Server **B**.\
+`<PUBLIC_KEY_SERVER_A>` - the content of the `public.key` file from Server **A**.
+
+Open the port on the firewall (if enabled):
+```bash
+sudo ufw allow from <PUBLIC_IP_SERVER_A> to any port 8443 proto udp
+```
+
+`<PUBLIC_IP_SERVER_A>` - the external IP address of Server **A**.
+
+#### Server A Configuration (Russian Federation):
+Create the interface configuration file (awg0)
+
+```bash
+nano /etc/amnezia/amneziawg/awg0.conf
+```
+
+File content
+```ini
+[Interface]
+Address = 10.10.10.2/24
+PrivateKey = <PRIVATE_KEY_SERVER_A>
+Jc = 4
+Jmin = 8
+Jmax = 80
+S1 = 29
+S2 = 15
+S3 = 18
+S4 = 0
+H1 = 2087563914
+H2 = 188817757
+H3 = 101784570
+H4 = 432174303
+I1 = <b 0xc10000000108981eba846e21f74e00>
+I2 = <b 0xc20000000108981eba846e21f74e00>
+I3 = <b 0xc30000000108981eba846e21f74e00>
+I4 = <b 0x43981eba846e21f74e>
+I5 = <b 0x43981eba846e21f74e>
+
+[Peer]
+PublicKey = <PUBLIC_KEY_SERVER_B>
+Endpoint = <PUBLIC_IP_SERVER_B>:8443
+AllowedIPs = 10.10.10.1/32
+PersistentKeepalive = 25
+```
+
+`<PRIVATE_KEY_SERVER_A>` - the content of the `private.key` file from Server **A**.\
+`<PUBLIC_KEY_SERVER_B>` - the content of the `public.key` file from Server **B**.\
+`<PUBLIC_IP_SERVER_B>` - the public IP address of Server **B**.
+
+Enable the tunnel on both servers:
+```bash
+sudo systemctl enable --now awg-quick@awg0
+```
+
+Make sure Server B is accessible from Server A through the tunnel.
+```bash
+ping 10.10.10.1
+PING 10.10.10.1 (10.10.10.1) 56(84) bytes of data.
+64 bytes from 10.10.10.1: icmp_seq=1 ttl=64 time=35.1 ms
+64 bytes from 10.10.10.1: icmp_seq=2 ttl=64 time=35.0 ms
+64 bytes from 10.10.10.1: icmp_seq=3 ttl=64 time=35.1 ms
+^C
+```
+---
+
+## 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).\
+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.
+```toml
+[server]
+port = 443
+listen_addr_ipv4 = "10.10.10.1"
+proxy_protocol = true
+```
+
+Also, for correct link generation, specify the FQDN or IP address and port of Server `A`
+```toml
+[general.links]
+show = "*"
+public_host = "<FQDN_OR_IP_SERVER_A>"
+public_port = 443
+```
+
+Open the port on the firewall (if enabled):
+```bash
+sudo ufw allow from 10.10.10.2 to any port 443 proto tcp
+```
+
+---
+
+## Step 3. Configuring HAProxy on Server A (Russian Federation)
+Since the version in the standard Ubuntu repository is relatively old, it makes sense to use the official Docker image.\
+[Instructions](https://docs.docker.com/engine/install/ubuntu/) for installing Docker on Ubuntu.
+
+> [!WARNING]
+> By default, regular users do not have rights to use ports < 1024.
+> Attempts to run HAProxy on port 443 can lead to errors:
+> ```
+> [ALERT] (8) : Binding [/usr/local/etc/haproxy/haproxy.cfg:17] for frontend tcp_in_443: 
+> protocol tcpv4: cannot bind socket (Permission denied) for [0.0.0.0:443].
+> ```
+> There are two simple ways to bypass this restriction, choose one:
+> 1. At the OS level, change the net.ipv4.ip_unprivileged_port_start setting to allow users to use all ports:
+> ```
+> echo "net.ipv4.ip_unprivileged_port_start = 0" | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
+> ```
+> or
+> 
+> 2. Run HAProxy as root:
+> Uncomment the `user: "root"` parameter in docker-compose.yaml.
+
+#### Create a folder for HAProxy:
+```bash
+mkdir -p /opt/docker-compose/haproxy && cd $_
+```
+
+#### Create the docker-compose.yaml file
+`nano docker-compose.yaml`
+
+File content
+```yaml
+services:
+  haproxy:
+    image: haproxy:latest
+    container_name: haproxy
+    restart: unless-stopped
+    # user: "root"
+    network_mode: "host"
+    volumes:
+      - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "1m"
+        max-file: "1"
+```
+
+#### Create the haproxy.cfg config file
+Accept connections on port 443\tcp and send them through the tunnel to Server `B` 10.10.10.1:443
+
+`nano haproxy.cfg`
+
+File content
+
+```haproxy
+global
+    log stdout format raw local0
+    maxconn 10000
+
+defaults
+    log     global
+    mode    tcp
+    option  tcplog
+    option  clitcpka
+    option  srvtcpka
+    timeout connect 5s
+    timeout client  2h
+    timeout server  2h
+    timeout check   5s
+
+frontend tcp_in_443
+    bind *:443
+    maxconn 8000
+    option tcp-smart-accept
+    default_backend telemt_nodes
+
+backend telemt_nodes
+    option tcp-smart-connect
+    server server_a 10.10.10.1:443 check inter 5s rise 2 fall 3 send-proxy-v2
+
+
+```
+> [!WARNING]
+> **The file must end with an empty line, otherwise HAProxy will not start!**
+
+#### Allow port 443\tcp in the firewall (if enabled)
+```bash
+sudo ufw allow 443/tcp
+```
+
+#### Start the HAProxy container
+```bash
+docker compose up -d
+```
+
+If everything is configured correctly, you can now try connecting Telegram clients using links from the telemt log\api.

docs/VPS_DOUBLE_HOP.ru.md

@@ -0,0 +1,291 @@
+<img src="https://gist.githubusercontent.com/avbor/1f8a128e628f47249aae6e058a57610b/raw/19013276c035e91058e0a9799ab145f8e70e3ff5/scheme.svg">
+
+## Концепция
+- **Сервер A** (_РФ_):\
+  Точка входа, принимает трафик пользователей Telegram-прокси через **HAProxy** (порт `443`)\
+  и отправляет в туннель на Сервер **B**.\
+  Внутренний IP в туннеле — `10.10.10.2`\
+  Порт для клиентов HAProxy — `443\tcp`
+- **Сервер B** (_условно Нидерланды_):\
+  Точка выхода, на нем работает **telemt** и принимает подключения клиентов через Сервер **A**.\
+  На сервере должен быть неограниченный доступ до серверов Telegram.\
+  Внутренний IP в туннеле — `10.10.10.1`\
+  Порт AmneziaWG — `8443\udp`\
+  Порт для клиентов telemt — `443\tcp`
+
+---
+
+## Шаг 1. Настройка туннеля AmneziaWG (A <-> B)
+
+На всех серверах необходимо установить [amneziawg](https://github.com/amnezia-vpn/amneziawg-linux-kernel-module).\
+Далее все команды даны для **Ununtu 24.04**.\
+Для RHEL-based дистрибутивов инструкция по установке есть по ссылке выше.
+
+### Установка AmneziaWG (Сервера A и B)
+На каждом из серверов необходимо выполнить следующие шаги:
+
+#### 1. Добавление репозитория AmneziaWG и установка необходимых пакетов:
+```bash
+sudo apt install -y software-properties-common python3-launchpadlib gnupg2 linux-headers-$(uname -r) && \
+sudo add-apt-repository ppa:amnezia/ppa && \
+sudo apt-get install -y amneziawg
+```
+ 
+#### 2. Генерация уникальной пары ключей:
+```bash
+cd /etc/amnezia/amneziawg && \
+awg genkey | tee private.key | awg pubkey > public.key
+```
+В результате вы получите в папке `/etc/amnezia/amneziawg` два файла:\
+`private.key` - приватный и\
+`public.key` - публичный ключи сервера
+
+#### 3. Настройка сетевых интерфейсов:
+
+Параметры обфускации `S1`, `S2`, `H1`, `H2`, `H3`, `H4` должны быть строго идентичными на обоих серверах.\
+Параметры `Jc`, `Jmin` и `Jmax` могут отличатся.\
+Параметры `I1-I5` ([Custom Protocol Signature](https://docs.amnezia.org/documentation/amnezia-wg/)) нужно указывать на стороне _клиента_ (Сервер **А**).
+
+Рекомендации по выбору значений:
+```text
+Jc — 1 ≤ Jc ≤ 128; от 4 до 12 включительно
+Jmin — Jmax > Jmin < 1280*; рекомендовано 8
+Jmax — Jmin < Jmax ≤ 1280*; рекомендовано 80
+S1 — S1 ≤ 1132* (1280* - 148 = 1132); S1 + 56 ≠ S2;
+рекомендованный диапазон от 15 до 150 включительно
+S2 — S2 ≤ 1188* (1280* - 92 = 1188);
+рекомендованный диапазон от 15 до 150 включительно
+H1/H2/H3/H4 — должны быть уникальны и отличаться друг от друга;
+рекомендованный диапазон от 5 до 2147483647 включительно
+
+* Предполагается, что подключение к Интернету имеет MTU 1280.
+```
+> [!IMPORTANT]
+> Рекомендуется использовать собственные, уникальные значения.\
+> Для выбора параметров можете воспользоваться [генератором](https://htmlpreview.github.io/?https://gist.githubusercontent.com/avbor/955782b5c37b06240b243aa375baeac5/raw/13f5517ca473b47c412b9a99407066de973732bd/awg-gen.html).
+
+#### Конфигурация Сервера B (_Нидерланды_):
+
+Создаем файл конфигурации интерфейса (`awg0`)
+```bash
+nano /etc/amnezia/amneziawg/awg0.conf
+```
+
+Содержимое файла
+```ini
+[Interface]
+Address = 10.10.10.1/24
+ListenPort = 8443
+PrivateKey = <PRIVATE_KEY_SERVER_B>
+SaveConfig = true
+Jc = 4
+Jmin = 8
+Jmax = 80
+S1 = 29
+S2 = 15
+S3 = 18
+S4 = 0
+H1 = 2087563914
+H2 = 188817757
+H3 = 101784570
+H4 = 432174303
+
+[Peer]
+PublicKey = <PUBLIC_KEY_SERVER_A>
+AllowedIPs = 10.10.10.2/32
+```
+
+`ListenPort` - порт, на котором сервер будет ждать подключения, можете выбрать любой свободный.\
+`<PRIVATE_KEY_SERVER_B>` - содержимое файла `private.key` с сервера **B**.\
+`<PUBLIC_KEY_SERVER_A>` - содержимое файла `public.key` с сервера **A**.
+
+Открываем порт на фаерволе (если включен):
+```bash
+sudo ufw allow from <PUBLIC_IP_SERVER_A> to any port 8443 proto udp
+```
+
+`<PUBLIC_IP_SERVER_A>` - внешний IP адрес Сервера **A**.
+
+#### Конфигурация Сервера A (_РФ_):
+
+Создаем файл конфигурации интерфейса (`awg0`)
+```bash
+nano /etc/amnezia/amneziawg/awg0.conf
+```
+
+Содержимое файла
+```ini
+[Interface]
+Address = 10.10.10.2/24
+PrivateKey = <PRIVATE_KEY_SERVER_A>
+Jc = 4
+Jmin = 8
+Jmax = 80
+S1 = 29
+S2 = 15
+S3 = 18
+S4 = 0
+H1 = 2087563914
+H2 = 188817757
+H3 = 101784570
+H4 = 432174303
+I1 = <b 0xc10000000108981eba846e21f74e00>
+I2 = <b 0xc20000000108981eba846e21f74e00>
+I3 = <b 0xc30000000108981eba846e21f74e00>
+I4 = <b 0x43981eba846e21f74e>
+I5 = <b 0x43981eba846e21f74e>
+
+[Peer]
+PublicKey = <PUBLIC_KEY_SERVER_B>
+Endpoint = <PUBLIC_IP_SERVER_B>:8443
+AllowedIPs = 10.10.10.1/32
+PersistentKeepalive = 25
+```
+
+`<PRIVATE_KEY_SERVER_A>` - содержимое файла `private.key` с сервера **A**.\
+`<PUBLIC_KEY_SERVER_B>` - содержимое файла `public.key` с сервера **B**.\
+`<PUBLIC_IP_SERVER_B>` - публичный IP адресс сервера **B**.
+
+#### Включаем туннель на обоих серверах:
+```bash
+sudo systemctl enable --now awg-quick@awg0 
+```
+
+Убедитесь, что с Сервера `A` доступен Сервер `B` через туннель.
+```bash
+ping 10.10.10.1
+PING 10.10.10.1 (10.10.10.1) 56(84) bytes of data.
+64 bytes from 10.10.10.1: icmp_seq=1 ttl=64 time=35.1 ms
+64 bytes from 10.10.10.1: icmp_seq=2 ttl=64 time=35.0 ms
+64 bytes from 10.10.10.1: icmp_seq=3 ttl=64 time=35.1 ms
+^C
+
+```
+
+---
+
+## Шаг 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).\
+Подразумевается что telemt ожидает подключения на порту `443\tcp`.
+
+В конфиге telemt необходимо включить протокол `Proxy` и ограничить подключения к нему только через туннель.
+
+```toml
+[server]
+port = 443
+listen_addr_ipv4 = "10.10.10.1"
+proxy_protocol = true
+```
+
+А также, для правильной генерации ссылок, указать FQDN или IP адрес и порт Сервера `A` 
+
+```toml
+[general.links]
+show = "*"
+public_host = "<FQDN_OR_IP_SERVER_A>"
+public_port = 443
+```
+
+Открываем порт на фаерволе (если включен):
+```bash
+sudo ufw allow from 10.10.10.2 to any port 443 proto tcp
+```
+
+---
+
+### Шаг 3. Настройка HAProxy на Сервере A (_РФ_)
+
+Т.к. в стандартном репозитории Ubuntu версия относительно старая, имеет смысл воспользоваться официальным образом Docker.\
+[Инструкция](https://docs.docker.com/engine/install/ubuntu/) по установке Docker на Ubuntu.
+
+> [!WARNING]
+> По умолчанию у обычных пользователей нет прав на использование портов < 1024.\
+> Попытки запустить HAProxy на 443 порту могут приводить к ошибкам:
+> ```
+> [ALERT] (8) : Binding [/usr/local/etc/haproxy/haproxy.cfg:17] for frontend tcp_in_443: 
+> protocol tcpv4: cannot bind socket (Permission denied) for [0.0.0.0:443].
+> ```
+> Есть два простых способа обойти это ограничение, выберите что-то одно:
+> 1. На уровне ОС изменить настройку net.ipv4.ip_unprivileged_port_start, разрешив пользователям использовать все порты:
+> ```
+> echo "net.ipv4.ip_unprivileged_port_start = 0" | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
+> ```
+> или
+> 
+> 2. Запустить HAProxy под root:\
+> Раскомментируйте в docker-compose.yaml параметр `user: "root"`.
+
+#### Создаем папку для HAProxy:
+```bash
+mkdir -p /opt/docker-compose/haproxy && cd $_
+```
+#### Создаем файл docker-compose.yaml
+
+`nano docker-compose.yaml`
+
+Содержимое файла
+```yaml
+services:
+  haproxy:
+    image: haproxy:latest
+    container_name: haproxy
+    restart: unless-stopped
+    # user: "root"
+    network_mode: "host"
+    volumes:
+      - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "1m"
+        max-file: "1"
+```
+#### Создаем файл конфига haproxy.cfg
+Принимаем подключения на порту 443\tcp и отправляем их через туннель на Сервер `B` 10.10.10.1:443
+
+`nano haproxy.cfg`
+
+Содержимое файла
+```haproxy
+global
+    log stdout format raw local0
+    maxconn 10000
+
+defaults
+    log     global
+    mode    tcp
+    option  tcplog
+    option  clitcpka
+    option  srvtcpka
+    timeout connect 5s
+    timeout client  2h
+    timeout server  2h
+    timeout check   5s
+
+frontend tcp_in_443
+    bind *:443
+    maxconn 8000
+    option tcp-smart-accept
+    default_backend telemt_nodes
+
+backend telemt_nodes
+    option tcp-smart-connect
+    server server_a 10.10.10.1:443 check inter 5s rise 2 fall 3 send-proxy-v2
+
+
+```
+>[!WARNING]
+>**Файл должен заканчиваться пустой строкой, иначе HAProxy не запустится!**
+
+#### Разрешаем порт 443\tcp в фаерволе (если включен)
+```bash
+sudo ufw allow 443/tcp
+```
+
+#### Запускаем контейнер HAProxy
+```bash
+docker compose up -d
+```
+
+Если все настроено верно, то теперь можно пробовать подключить клиентов Telegram с использованием ссылок из лога\api telemt.

docs/fronting-splitting/TLS-F-TCP-S.ru.md

@@ -38,8 +38,9 @@ umweltschutz.de -> A-запись 198.18.88.88
 
 В конфигурации Telemt:
 
-```
-tls_domain = umweltschutz.de
+```toml
+[censorship]
+tls_domain = "umweltschutz.de"
 ```
 
 Этот домен используется клиентом как SNI в ClientHello
@@ -56,8 +57,9 @@ tls_domain = umweltschutz.de
 
 В конфигурации Telemt:
 
-```
-mask_host = 127.0.0.1
+```toml
+[censorship]
+mask_host = "127.0.0.1"
 mask_port = 8443
 ```
 
@@ -151,16 +153,18 @@ mask_host:mask_port
 
 Например:
 
-```
-tls_domain = github.com
-mask_host = github.com
+```toml
+[censorship]
+tls_domain = "github.com"
+mask_host = "github.com"
 mask_port = 443
 ```
 
 или
 
-```
-mask_host = 140.82.121.4
+```toml
+[censorship]
+mask_host = "140.82.121.4"
 ```
 
 В этом случае:

install.sh

@@ -3,113 +3,554 @@ set -eu
 
 REPO="${REPO:-telemt/telemt}"
 BIN_NAME="${BIN_NAME:-telemt}"
-VERSION="${1:-${VERSION:-latest}}"
-INSTALL_DIR="${INSTALL_DIR:-/usr/local/bin}"
+INSTALL_DIR="${INSTALL_DIR:-/bin}"
+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}"
+SERVICE_NAME="telemt"
+TEMP_DIR=""
+SUDO=""
+CONFIG_PARENT_DIR=""
+SERVICE_START_FAILED=0
+
+ACTION="install"
+TARGET_VERSION="${VERSION:-latest}"
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        -h|--help) ACTION="help"; shift ;;
+        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 ;;
+        *)
+            if [ "$ACTION" = "install" ]; then TARGET_VERSION="$1"
+            else printf '[WARNING] Ignoring extra argument: %s\n' "$1" >&2; fi
+            shift ;;
+    esac
+done
 
 say() {
-    printf '%s\n' "$*"
+    if [ "$#" -eq 0 ] || [ -z "${1:-}" ]; then
+        printf '\n'
+    else
+        printf '[INFO] %s\n' "$*"
+    fi
+}
+die() { printf '[ERROR] %s\n' "$*" >&2; exit 1; }
+
+write_root() { $SUDO sh -c 'cat > "$1"' _ "$1"; }
+
+cleanup() {
+    if [ -n "${TEMP_DIR:-}" ] && [ -d "$TEMP_DIR" ]; then
+        rm -rf -- "$TEMP_DIR"
+    fi
+}
+trap cleanup EXIT INT TERM
+
+show_help() {
+    say "Usage: $0 [ <version> | install | uninstall | purge | --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"
+    exit 0
 }
 
-die() {
-    printf 'Error: %s\n' "$*" >&2
-    exit 1
+check_os_entity() {
+    if command -v getent >/dev/null 2>&1; then getent "$1" "$2" >/dev/null 2>&1
+    else grep -q "^${2}:" "/etc/$1" 2>/dev/null; fi
 }
 
-need_cmd() {
-    command -v "$1" >/dev/null 2>&1 || die "required command not found: $1"
+normalize_path() {
+    printf '%s\n' "$1" | tr -s '/' | sed 's|/$||; s|^$|/|'
 }
 
-detect_os() {
-    os="$(uname -s)"
-    case "$os" in
-        Linux) printf 'linux\n' ;;
-        OpenBSD) printf 'openbsd\n' ;;
-        *) printf '%s\n' "$os" ;;
+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 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
+            printf '%s\n' "$resolved_path"
+            return
+        fi
+    fi
+
+    d="${path_in%/*}"; b="${path_in##*/}"
+    if [ -z "$d" ]; then d="/"; fi
+    if [ "$d" = "$path_in" ]; then d="/"; b="$path_in"; fi
+
+    if [ -d "$d" ]; then
+        abs_d="$(cd "$d" >/dev/null 2>&1 && pwd || true)"
+        if [ -n "$abs_d" ]; then
+            if [ "$b" = "." ] || [ -z "$b" ]; then printf '%s\n' "$abs_d"
+            elif [ "$abs_d" = "/" ]; then printf '/%s\n' "$b"
+            else printf '%s/%s\n' "$abs_d" "$b"; fi
+        else
+            normalize_path "$path_in"
+        fi
+    else
+        normalize_path "$path_in"
+    fi
+}
+
+get_svc_mgr() {
+    if command -v systemctl >/dev/null 2>&1 && [ -d /run/systemd/system ]; then echo "systemd"
+    elif command -v rc-service >/dev/null 2>&1; then echo "openrc"
+    else echo "none"; 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."
+
+    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
+
+    INSTALL_DIR="$(get_realpath "$INSTALL_DIR")"
+    CONFIG_DIR="$(get_realpath "$CONFIG_DIR")"
+    WORK_DIR="$(get_realpath "$WORK_DIR")"
+    CONFIG_FILE="$(get_realpath "$CONFIG_FILE")"
+
+    CONFIG_PARENT_DIR="${CONFIG_FILE%/*}"
+    if [ -z "$CONFIG_PARENT_DIR" ]; then CONFIG_PARENT_DIR="/"; fi
+    if [ "$CONFIG_PARENT_DIR" = "$CONFIG_FILE" ]; then CONFIG_PARENT_DIR="."; fi
+
+    if [ "$(id -u)" -eq 0 ]; then
+        SUDO=""
+    else
+        command -v sudo >/dev/null 2>&1 || die "This script requires root or sudo. Neither found."
+        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."
+            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."
+        fi
+    elif [ -d "$CONFIG_FILE" ]; then
+        die "Safety check failed: CONFIG_FILE '$CONFIG_FILE' is a directory."
+    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"
+    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"
+
+    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
+        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
+        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
 }
 
 detect_arch() {
-    arch="$(uname -m)"
-    case "$arch" in
-        x86_64|amd64) printf 'x86_64\n' ;;
-        aarch64|arm64) printf 'aarch64\n' ;;
-        *) die "unsupported architecture: $arch" ;;
+    sys_arch="$(uname -m)"
+    case "$sys_arch" in
+        x86_64|amd64) echo "x86_64" ;;
+        aarch64|arm64) echo "aarch64" ;;
+        *) die "Unsupported architecture: $sys_arch" ;;
     esac
 }
 
 detect_libc() {
-    case "$(ldd --version 2>&1 || true)" in
-        *musl*) printf 'musl\n' ;;
-        *) printf 'gnu\n' ;;
-    esac
+    for f in /lib/ld-musl-*.so.* /lib64/ld-musl-*.so.*; do
+        if [ -e "$f" ]; then echo "musl"; return 0; fi
+    done
+    if grep -qE '^ID="?alpine"?' /etc/os-release 2>/dev/null; then echo "musl"; return 0; fi
+    if command -v ldd >/dev/null 2>&1 && (ldd --version 2>&1 || true) | grep -qi musl; then echo "musl"; return 0; fi
+    echo "gnu"
 }
 
-fetch_to_stdout() {
-    url="$1"
-    if command -v curl >/dev/null 2>&1; then
-        curl -fsSL "$url"
-    elif command -v wget >/dev/null 2>&1; then
-        wget -qO- "$url"
-    else
-        die "neither curl nor wget is installed"
+fetch_file() {
+    if command -v curl >/dev/null 2>&1; then curl -fsSL "$1" -o "$2"
+    else wget -q -O "$2" "$1"; fi
+}
+
+ensure_user_group() {
+    nologin_bin="$(command -v nologin 2>/dev/null || command -v false 2>/dev/null || echo /bin/false)"
+
+    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
+    fi
+
+    if ! check_os_entity passwd telemt; then
+        if command -v useradd >/dev/null 2>&1; then
+            $SUDO useradd -r -g telemt -d "$WORK_DIR" -s "$nologin_bin" -c "Telemt Proxy" telemt
+        elif command -v adduser >/dev/null 2>&1; then
+            if adduser --help 2>&1 | grep -q -- '-S'; then
+                $SUDO adduser -S -D -H -h "$WORK_DIR" -s "$nologin_bin" -G telemt telemt
+            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
+    fi
+}
+
+setup_dirs() {
+    $SUDO mkdir -p "$WORK_DIR" "$CONFIG_DIR" "$CONFIG_PARENT_DIR" || die "Failed to create directories"
+    
+    $SUDO chown telemt:telemt "$WORK_DIR" && $SUDO chmod 750 "$WORK_DIR"
+    $SUDO chown root: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
+}
+
+stop_service() {
+    svc="$(get_svc_mgr)"
+    if [ "$svc" = "systemd" ] && 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
+        $SUDO rc-service "$SERVICE_NAME" stop 2>/dev/null || true
     fi
 }
 
 install_binary() {
-    src="$1"
-    dst="$2"
+    bin_src="$1"; bin_dst="$2"
+    if [ -e "$INSTALL_DIR" ] && [ ! -d "$INSTALL_DIR" ]; then
+        die "'$INSTALL_DIR' is not a directory."
+    fi
 
-    if [ -w "$INSTALL_DIR" ] || { [ ! -e "$INSTALL_DIR" ] && [ -w "$(dirname "$INSTALL_DIR")" ]; }; then
-        mkdir -p "$INSTALL_DIR"
-        install -m 0755 "$src" "$dst"
-    elif command -v sudo >/dev/null 2>&1; then
-        sudo mkdir -p "$INSTALL_DIR"
-        sudo install -m 0755 "$src" "$dst"
+    $SUDO mkdir -p "$INSTALL_DIR" || die "Failed to create install directory"
+    if command -v install >/dev/null 2>&1; then
+        $SUDO install -m 0755 "$bin_src" "$bin_dst" || die "Failed to install binary"
     else
-        die "cannot write to $INSTALL_DIR and sudo is not available"
+        $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"
+    fi
+
+    $SUDO sh -c '[ -x "$1" ]' _ "$bin_dst" || die "Binary not executable: $bin_dst"
+
+    if command -v setcap >/dev/null 2>&1; then
+        $SUDO setcap cap_net_bind_service=+ep "$bin_dst" 2>/dev/null || true
     fi
 }
 
-need_cmd uname
-need_cmd tar
-need_cmd mktemp
-need_cmd grep
-need_cmd install
+generate_secret() {
+    secret="$(command -v openssl >/dev/null 2>&1 && openssl rand -hex 16 2>/dev/null || true)"
+    if [ -z "$secret" ] || [ "${#secret}" -ne 32 ]; then
+        if command -v od >/dev/null 2>&1; then secret="$(dd if=/dev/urandom bs=16 count=1 2>/dev/null | od -An -tx1 | tr -d ' \n')"
+        elif command -v hexdump >/dev/null 2>&1; then secret="$(dd if=/dev/urandom bs=16 count=1 2>/dev/null | hexdump -e '1/1 "%02x"')"
+        elif command -v xxd >/dev/null 2>&1; then secret="$(dd if=/dev/urandom bs=16 count=1 2>/dev/null | xxd -p | tr -d '\n')"
+        fi
+    fi
+    if [ "${#secret}" -eq 32 ]; then echo "$secret"; else return 1; fi
+}
 
-ARCH="$(detect_arch)"
-OS="$(detect_os)"
+generate_config_content() {
+    escaped_tls_domain="$(printf '%s\n' "$TLS_DOMAIN" | tr -d '[:cntrl:]' | sed 's/\\/\\\\/g; s/"/\\"/g')"
 
-if [ "$OS" != "linux" ]; then
-    case "$OS" in
-        openbsd)
-            die "install.sh installs only Linux release artifacts. On OpenBSD, build from source (see docs/OPENBSD.en.md)."
-            ;;
-        *)
-            die "unsupported operating system for install.sh: $OS"
-            ;;
-    esac
-fi
+    cat <<EOF
+[general]
+use_middle_proxy = false
 
-LIBC="$(detect_libc)"
+[general.modes]
+classic = false
+secure = false
+tls = true
 
-case "$VERSION" in
-    latest)
-        URL="https://github.com/$REPO/releases/latest/download/${BIN_NAME}-${ARCH}-linux-${LIBC}.tar.gz"
-        ;;
-    *)
-        URL="https://github.com/$REPO/releases/download/${VERSION}/${BIN_NAME}-${ARCH}-linux-${LIBC}.tar.gz"
+[server]
+port = 443
+
+[server.api]
+enabled = true
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.1/32"]
+
+[censorship]
+tls_domain = "${escaped_tls_domain}"
+
+[access.users]
+hello = "$1"
+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."
+        return 0
+    fi
+
+    toml_secret="$(generate_secret)" || die "Failed to generate secret."
+
+    generate_config_content "$toml_secret" | write_root "$CONFIG_FILE" || die "Failed to install config"
+    $SUDO chown root:telemt "$CONFIG_FILE" && $SUDO chmod 640 "$CONFIG_FILE"
+
+    say "  -> Config created successfully."
+    say "  -> Generated secret for default user 'hello': $toml_secret"
+}
+
+generate_systemd_content() {
+    cat <<EOF
+[Unit]
+Description=Telemt
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=telemt
+Group=telemt
+WorkingDirectory=$WORK_DIR
+ExecStart="${INSTALL_DIR}/${BIN_NAME}" "${CONFIG_FILE}"
+Restart=on-failure
+LimitNOFILE=65536
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+
+[Install]
+WantedBy=multi-user.target
+EOF
+}
+
+generate_openrc_content() {
+    cat <<EOF
+#!/sbin/openrc-run
+name="$SERVICE_NAME"
+description="Telemt Proxy Service"
+command="${INSTALL_DIR}/${BIN_NAME}"
+command_args="${CONFIG_FILE}"
+command_background=true
+command_user="telemt:telemt"
+pidfile="/run/\${RC_SVCNAME}.pid"
+directory="${WORK_DIR}"
+rc_ulimit="-n 65536"
+depend() { need net; use logger; }
+EOF
+}
+
+install_service() {
+    svc="$(get_svc_mgr)"
+    if [ "$svc" = "systemd" ]; then
+        generate_systemd_content | write_root "/etc/systemd/system/${SERVICE_NAME}.service"
+        $SUDO chown root:root "/etc/systemd/system/${SERVICE_NAME}.service" && $SUDO chmod 644 "/etc/systemd/system/${SERVICE_NAME}.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"
+            SERVICE_START_FAILED=1
+        fi
+    elif [ "$svc" = "openrc" ]; then
+        generate_openrc_content | write_root "/etc/init.d/${SERVICE_NAME}"
+        $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"
+            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'"
+        fi
+    fi
+}
+
+kill_user_procs() {
+    if command -v pkill >/dev/null 2>&1; then
+        $SUDO pkill -u telemt "$BIN_NAME" 2>/dev/null || true
+        sleep 1
+        $SUDO pkill -9 -u telemt "$BIN_NAME" 2>/dev/null || true
+    else
+        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)"
+        fi
+        
+        if [ -n "$pids" ]; then
+            for pid in $pids; do
+                case "$pid" in ''|*[!0-9]*) continue ;; *) $SUDO kill "$pid" 2>/dev/null || true ;; esac
+            done
+            sleep 1
+            for pid in $pids; do
+                case "$pid" in ''|*[!0-9]*) continue ;; *) $SUDO kill -9 "$pid" 2>/dev/null || true ;; esac
+            done
+        fi
+    fi
+}
+
+uninstall() {
+    say "Starting uninstallation of $BIN_NAME..."
+
+    say ">>> Stage 1: Stopping services"
+    stop_service
+
+    say ">>> Stage 2: Removing service configuration"
+    svc="$(get_svc_mgr)"
+    if [ "$svc" = "systemd" ]; then
+        $SUDO systemctl disable "$SERVICE_NAME" 2>/dev/null || true
+        $SUDO rm -f "/etc/systemd/system/${SERVICE_NAME}.service"
+        $SUDO systemctl daemon-reload 2>/dev/null || true
+    elif [ "$svc" = "openrc" ]; then
+        $SUDO rc-update del "$SERVICE_NAME" 2>/dev/null || true
+        $SUDO rm -f "/etc/init.d/${SERVICE_NAME}"
+    fi
+
+    say ">>> Stage 3: Terminating user processes"
+    kill_user_procs
+
+    say ">>> Stage 4: Removing binary"
+    $SUDO rm -f "${INSTALL_DIR}/${BIN_NAME}"
+
+    if [ "$ACTION" = "purge" ]; then
+        say ">>> Stage 5: Purging configuration, data, and user"
+        $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
+        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."
+    fi
+    
+    printf '\n====================================================================\n'
+    printf '                    UNINSTALLATION COMPLETE\n'
+    printf '====================================================================\n\n'
+    exit 0
+}
+
+case "$ACTION" in
+    help) show_help ;;
+    uninstall|purge) verify_common; uninstall ;;
+    install)
+        say "Starting installation of $BIN_NAME (Version: $TARGET_VERSION)"
+
+        say ">>> Stage 1: Verifying environment and dependencies"
+        verify_common; verify_install_deps
+
+        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 
+            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"
+        if [ -z "$TEMP_DIR" ] || [ ! -d "$TEMP_DIR" ]; then
+            die "Temp directory is invalid or was not created"
+        fi
+
+        fetch_file "$DL_URL" "${TEMP_DIR}/${FILE_NAME}" || die "Download failed"
+
+        say ">>> Stage 3: Extracting archive"
+        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)."
+        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"
+
+        say ">>> Stage 4: Setting up environment (User, Group, Directories)"
+        ensure_user_group; setup_dirs; stop_service
+        
+        say ">>> Stage 5: Installing binary"
+        install_binary "$EXTRACTED_BIN" "${INSTALL_DIR}/${BIN_NAME}"
+        
+        say ">>> Stage 6: Generating configuration"
+        install_config
+        
+        say ">>> Stage 7: Installing and starting service"
+        install_service
+
+        if [ "${SERVICE_START_FAILED:-0}" -eq 1 ]; then
+            printf '\n====================================================================\n'
+            printf '               INSTALLATION COMPLETED WITH WARNINGS\n'
+            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'
+        else
+            printf '\n====================================================================\n'
+            printf '                      INSTALLATION SUCCESS\n'
+            printf '====================================================================\n\n'
+        fi
+        
+        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"
+        elif [ "$svc" = "openrc" ]; then
+            printf 'To check the status of your proxy service, run:\n'
+            printf '  rc-service %s status\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'
         ;;
 esac
-
-TMPDIR="$(mktemp -d)"
-trap 'rm -rf "$TMPDIR"' EXIT INT TERM
-
-say "Installing $BIN_NAME ($VERSION) for $ARCH-linux-$LIBC..."
-fetch_to_stdout "$URL" | tar -xzf - -C "$TMPDIR"
-
-[ -f "$TMPDIR/$BIN_NAME" ] || die "archive did not contain $BIN_NAME"
-
-install_binary "$TMPDIR/$BIN_NAME" "$INSTALL_DIR/$BIN_NAME"
-
-say "Installed: $INSTALL_DIR/$BIN_NAME"
-"$INSTALL_DIR/$BIN_NAME" --version 2>/dev/null || true

src/api/http_utils.rs

@@ -24,10 +24,7 @@ pub(super) fn success_response<T: Serialize>(
         .unwrap()
 }
 
-pub(super) fn error_response(
-    request_id: u64,
-    failure: ApiFailure,
-) -> hyper::Response<Full<Bytes>> {
+pub(super) fn error_response(request_id: u64, failure: ApiFailure) -> hyper::Response<Full<Bytes>> {
     let payload = ErrorResponse {
         ok: false,
         error: ErrorBody {

src/api/mod.rs

@@ -1,3 +1,5 @@
+#![allow(clippy::too_many_arguments)]
+
 use std::convert::Infallible;
 use std::net::{IpAddr, SocketAddr};
 use std::path::PathBuf;
@@ -19,8 +21,8 @@ use crate::ip_tracker::UserIpTracker;
 use crate::proxy::route_mode::RouteRuntimeController;
 use crate::startup::StartupTracker;
 use crate::stats::Stats;
-use crate::transport::middle_proxy::MePool;
 use crate::transport::UpstreamManager;
+use crate::transport::middle_proxy::MePool;
 
 mod config_store;
 mod events;
@@ -36,10 +38,11 @@ mod runtime_zero;
 mod users;
 
 use config_store::{current_revision, parse_if_match};
-use http_utils::{error_response, read_json, read_optional_json, success_response};
 use events::ApiEventStore;
+use http_utils::{error_response, read_json, read_optional_json, success_response};
 use model::{
     ApiFailure, CreateUserRequest, HealthData, PatchUserRequest, RotateSecretRequest, SummaryData,
+    UserActiveIps,
 };
 use runtime_edge::{
     EdgeConnectionsCacheEntry, build_runtime_connections_summary_data,
@@ -55,11 +58,11 @@ use runtime_stats::{
     MinimalCacheEntry, build_dcs_data, build_me_writers_data, build_minimal_all_data,
     build_upstreams_data, build_zero_all_data,
 };
+use runtime_watch::spawn_runtime_watchers;
 use runtime_zero::{
     build_limits_effective_data, build_runtime_gates_data, build_security_posture_data,
     build_system_info_data,
 };
-use runtime_watch::spawn_runtime_watchers;
 use users::{create_user, delete_user, patch_user, rotate_secret, users_from_config};
 
 pub(super) struct ApiRuntimeState {
@@ -208,15 +211,15 @@ async fn handle(
         ));
     }
 
-    if !api_cfg.whitelist.is_empty()
-        && !api_cfg
-            .whitelist
-            .iter()
-            .any(|net| net.contains(peer.ip()))
+    if !api_cfg.whitelist.is_empty() && !api_cfg.whitelist.iter().any(|net| net.contains(peer.ip()))
     {
         return Ok(error_response(
             request_id,
-            ApiFailure::new(StatusCode::FORBIDDEN, "forbidden", "Source IP is not allowed"),
+            ApiFailure::new(
+                StatusCode::FORBIDDEN,
+                "forbidden",
+                "Source IP is not allowed",
+            ),
         ));
     }
 
@@ -347,7 +350,8 @@ async fn handle(
             }
             ("GET", "/v1/runtime/connections/summary") => {
                 let revision = current_revision(&shared.config_path).await?;
-                let data = build_runtime_connections_summary_data(shared.as_ref(), cfg.as_ref()).await;
+                let data =
+                    build_runtime_connections_summary_data(shared.as_ref(), cfg.as_ref()).await;
                 Ok(success_response(StatusCode::OK, data, revision))
             }
             ("GET", "/v1/runtime/events/recent") => {
@@ -359,6 +363,18 @@ async fn handle(
                 );
                 Ok(success_response(StatusCode::OK, data, revision))
             }
+            ("GET", "/v1/stats/users/active-ips") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let usernames: Vec<_> = cfg.access.users.keys().cloned().collect();
+                let active_ips_map = shared.ip_tracker.get_active_ips_for_users(&usernames).await;
+                let mut data: Vec<UserActiveIps> = active_ips_map
+                    .into_iter()
+                    .filter(|(_, ips)| !ips.is_empty())
+                    .map(|(username, active_ips)| UserActiveIps { username, active_ips })
+                    .collect();
+                data.sort_by(|a, b| a.username.cmp(&b.username));
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
             ("GET", "/v1/stats/users") | ("GET", "/v1/users") => {
                 let revision = current_revision(&shared.config_path).await?;
                 let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
@@ -389,13 +405,16 @@ async fn handle(
                 let (data, revision) = match result {
                     Ok(ok) => ok,
                     Err(error) => {
-                        shared.runtime_events.record("api.user.create.failed", error.code);
+                        shared
+                            .runtime_events
+                            .record("api.user.create.failed", error.code);
                         return Err(error);
                     }
                 };
-                shared
-                    .runtime_events
-                    .record("api.user.create.ok", format!("username={}", data.user.username));
+                shared.runtime_events.record(
+                    "api.user.create.ok",
+                    format!("username={}", data.user.username),
+                );
                 Ok(success_response(StatusCode::CREATED, data, revision))
             }
             _ => {
@@ -414,7 +433,8 @@ async fn handle(
                             detected_ip_v6,
                         )
                         .await;
-                        if let Some(user_info) = users.into_iter().find(|entry| entry.username == user)
+                        if let Some(user_info) =
+                            users.into_iter().find(|entry| entry.username == user)
                         {
                             return Ok(success_response(StatusCode::OK, user_info, revision));
                         }
@@ -435,7 +455,8 @@ async fn handle(
                             ));
                         }
                         let expected_revision = parse_if_match(req.headers());
-                        let body = read_json::<PatchUserRequest>(req.into_body(), body_limit).await?;
+                        let body =
+                            read_json::<PatchUserRequest>(req.into_body(), body_limit).await?;
                         let result = patch_user(user, body, expected_revision, &shared).await;
                         let (data, revision) = match result {
                             Ok(ok) => ok,
@@ -475,10 +496,9 @@ async fn handle(
                                 return Err(error);
                             }
                         };
-                        shared.runtime_events.record(
-                            "api.user.delete.ok",
-                            format!("username={}", deleted_user),
-                        );
+                        shared
+                            .runtime_events
+                            .record("api.user.delete.ok", format!("username={}", deleted_user));
                         return Ok(success_response(StatusCode::OK, deleted_user, revision));
                     }
                     if method == Method::POST

src/api/model.rs

@@ -1,10 +1,12 @@
 use std::net::IpAddr;
+use std::sync::OnceLock;
 
 use chrono::{DateTime, Utc};
 use hyper::StatusCode;
-use rand::Rng;
 use serde::{Deserialize, Serialize};
 
+use crate::crypto::SecureRandom;
+
 const MAX_USERNAME_LEN: usize = 64;
 
 #[derive(Debug)]
@@ -134,6 +136,7 @@ pub(super) struct UpstreamSummaryData {
     pub(super) direct_total: usize,
     pub(super) socks4_total: usize,
     pub(super) socks5_total: usize,
+    pub(super) shadowsocks_total: usize,
 }
 
 #[derive(Serialize, Clone)]
@@ -171,6 +174,24 @@ pub(super) struct ZeroMiddleProxyData {
     pub(super) route_drop_queue_full_total: u64,
     pub(super) route_drop_queue_full_base_total: u64,
     pub(super) route_drop_queue_full_high_total: u64,
+    pub(super) d2c_batches_total: u64,
+    pub(super) d2c_batch_frames_total: u64,
+    pub(super) d2c_batch_bytes_total: u64,
+    pub(super) d2c_flush_reason_queue_drain_total: u64,
+    pub(super) d2c_flush_reason_batch_frames_total: u64,
+    pub(super) d2c_flush_reason_batch_bytes_total: u64,
+    pub(super) d2c_flush_reason_max_delay_total: u64,
+    pub(super) d2c_flush_reason_ack_immediate_total: u64,
+    pub(super) d2c_flush_reason_close_total: u64,
+    pub(super) d2c_data_frames_total: u64,
+    pub(super) d2c_ack_frames_total: u64,
+    pub(super) d2c_payload_bytes_total: u64,
+    pub(super) d2c_write_mode_coalesced_total: u64,
+    pub(super) d2c_write_mode_split_total: u64,
+    pub(super) d2c_quota_reject_pre_write_total: u64,
+    pub(super) d2c_quota_reject_post_write_total: u64,
+    pub(super) d2c_frame_buf_shrink_total: u64,
+    pub(super) d2c_frame_buf_shrink_bytes_total: u64,
     pub(super) socks_kdf_strict_reject_total: u64,
     pub(super) socks_kdf_compat_fallback_total: u64,
     pub(super) endpoint_quarantine_total: u64,
@@ -421,6 +442,12 @@ pub(super) struct UserInfo {
     pub(super) links: UserLinks,
 }
 
+#[derive(Serialize)]
+pub(super) struct UserActiveIps {
+    pub(super) username: String,
+    pub(super) active_ips: Vec<IpAddr>,
+}
+
 #[derive(Serialize)]
 pub(super) struct CreateUserResponse {
     pub(super) user: UserInfo,
@@ -481,7 +508,9 @@ pub(super) fn is_valid_username(user: &str) -> bool {
 }
 
 pub(super) fn random_user_secret() -> String {
+    static API_SECRET_RNG: OnceLock<SecureRandom> = OnceLock::new();
+    let rng = API_SECRET_RNG.get_or_init(SecureRandom::new);
     let mut bytes = [0u8; 16];
-    rand::rng().fill(&mut bytes);
+    rng.fill(&mut bytes);
     hex::encode(bytes)
 }

src/api/runtime_init.rs

@@ -167,11 +167,7 @@ async fn current_me_pool_stage_progress(shared: &ApiShared) -> Option<f64> {
     let pool = shared.me_pool.read().await.clone()?;
     let status = pool.api_status_snapshot().await;
     let configured_dc_groups = status.configured_dc_groups;
-    let covered_dc_groups = status
-        .dcs
-        .iter()
-        .filter(|dc| dc.alive_writers > 0)
-        .count();
+    let covered_dc_groups = status.dcs.iter().filter(|dc| dc.alive_writers > 0).count();
 
     let dc_coverage = ratio_01(covered_dc_groups, configured_dc_groups);
     let writer_coverage = ratio_01(status.alive_writers, status.required_writers);

src/api/runtime_min.rs

@@ -107,6 +107,25 @@ pub(super) struct RuntimeMeQualityRouteDropData {
     pub(super) queue_full_high_total: u64,
 }
 
+#[derive(Serialize)]
+pub(super) struct RuntimeMeQualityFamilyStateData {
+    pub(super) family: &'static str,
+    pub(super) state: &'static str,
+    pub(super) state_since_epoch_secs: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) suppressed_until_epoch_secs: Option<u64>,
+    pub(super) fail_streak: u32,
+    pub(super) recover_success_streak: u32,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeQualityDrainGateData {
+    pub(super) route_quorum_ok: bool,
+    pub(super) redundancy_ok: bool,
+    pub(super) block_reason: &'static str,
+    pub(super) updated_at_epoch_secs: u64,
+}
+
 #[derive(Serialize)]
 pub(super) struct RuntimeMeQualityDcRttData {
     pub(super) dc: i16,
@@ -120,6 +139,8 @@ pub(super) struct RuntimeMeQualityDcRttData {
 pub(super) struct RuntimeMeQualityPayload {
     pub(super) counters: RuntimeMeQualityCountersData,
     pub(super) route_drops: RuntimeMeQualityRouteDropData,
+    pub(super) family_states: Vec<RuntimeMeQualityFamilyStateData>,
+    pub(super) drain_gate: RuntimeMeQualityDrainGateData,
     pub(super) dc_rtt: Vec<RuntimeMeQualityDcRttData>,
 }
 
@@ -158,6 +179,7 @@ pub(super) struct RuntimeUpstreamQualitySummaryData {
     pub(super) direct_total: usize,
     pub(super) socks4_total: usize,
     pub(super) socks5_total: usize,
+    pub(super) shadowsocks_total: usize,
 }
 
 #[derive(Serialize)]
@@ -360,6 +382,19 @@ pub(super) async fn build_runtime_me_quality_data(shared: &ApiShared) -> Runtime
     };
 
     let status = pool.api_status_snapshot().await;
+    let family_states = pool
+        .api_family_state_snapshot()
+        .into_iter()
+        .map(|entry| RuntimeMeQualityFamilyStateData {
+            family: entry.family,
+            state: entry.state,
+            state_since_epoch_secs: entry.state_since_epoch_secs,
+            suppressed_until_epoch_secs: entry.suppressed_until_epoch_secs,
+            fail_streak: entry.fail_streak,
+            recover_success_streak: entry.recover_success_streak,
+        })
+        .collect();
+    let drain_gate_snapshot = pool.api_drain_gate_snapshot();
     RuntimeMeQualityData {
         enabled: true,
         reason: None,
@@ -380,6 +415,13 @@ pub(super) async fn build_runtime_me_quality_data(shared: &ApiShared) -> Runtime
                 queue_full_base_total: shared.stats.get_me_route_drop_queue_full_base(),
                 queue_full_high_total: shared.stats.get_me_route_drop_queue_full_high(),
             },
+            family_states,
+            drain_gate: RuntimeMeQualityDrainGateData {
+                route_quorum_ok: drain_gate_snapshot.route_quorum_ok,
+                redundancy_ok: drain_gate_snapshot.redundancy_ok,
+                block_reason: drain_gate_snapshot.block_reason,
+                updated_at_epoch_secs: drain_gate_snapshot.updated_at_epoch_secs,
+            },
             dc_rtt: status
                 .dcs
                 .into_iter()
@@ -404,7 +446,9 @@ pub(super) async fn build_runtime_upstream_quality_data(
         connect_attempt_total: shared.stats.get_upstream_connect_attempt_total(),
         connect_success_total: shared.stats.get_upstream_connect_success_total(),
         connect_fail_total: shared.stats.get_upstream_connect_fail_total(),
-        connect_failfast_hard_error_total: shared.stats.get_upstream_connect_failfast_hard_error_total(),
+        connect_failfast_hard_error_total: shared
+            .stats
+            .get_upstream_connect_failfast_hard_error_total(),
     };
 
     let Some(snapshot) = shared.upstream_manager.try_api_snapshot() else {
@@ -444,6 +488,7 @@ pub(super) async fn build_runtime_upstream_quality_data(
             direct_total: snapshot.summary.direct_total,
             socks4_total: snapshot.summary.socks4_total,
             socks5_total: snapshot.summary.socks5_total,
+            shadowsocks_total: snapshot.summary.shadowsocks_total,
         }),
         upstreams: Some(
             snapshot
@@ -455,6 +500,7 @@ pub(super) async fn build_runtime_upstream_quality_data(
                         crate::transport::UpstreamRouteKind::Direct => "direct",
                         crate::transport::UpstreamRouteKind::Socks4 => "socks4",
                         crate::transport::UpstreamRouteKind::Socks5 => "socks5",
+                        crate::transport::UpstreamRouteKind::Shadowsocks => "shadowsocks",
                     },
                     address: upstream.address,
                     weight: upstream.weight,
@@ -474,7 +520,9 @@ pub(super) async fn build_runtime_upstream_quality_data(
                                 crate::transport::upstream::IpPreference::PreferV6 => "prefer_v6",
                                 crate::transport::upstream::IpPreference::PreferV4 => "prefer_v4",
                                 crate::transport::upstream::IpPreference::BothWork => "both_work",
-                                crate::transport::upstream::IpPreference::Unavailable => "unavailable",
+                                crate::transport::upstream::IpPreference::Unavailable => {
+                                    "unavailable"
+                                }
                             },
                         })
                         .collect(),
@@ -512,14 +560,18 @@ pub(super) async fn build_runtime_nat_stun_data(shared: &ApiShared) -> RuntimeNa
                 live_total: snapshot.live_servers.len(),
             },
             reflection: RuntimeNatStunReflectionBlockData {
-                v4: snapshot.reflection_v4.map(|entry| RuntimeNatStunReflectionData {
-                    addr: entry.addr.to_string(),
-                    age_secs: entry.age_secs,
-                }),
-                v6: snapshot.reflection_v6.map(|entry| RuntimeNatStunReflectionData {
-                    addr: entry.addr.to_string(),
-                    age_secs: entry.age_secs,
-                }),
+                v4: snapshot
+                    .reflection_v4
+                    .map(|entry| RuntimeNatStunReflectionData {
+                        addr: entry.addr.to_string(),
+                        age_secs: entry.age_secs,
+                    }),
+                v6: snapshot
+                    .reflection_v6
+                    .map(|entry| RuntimeNatStunReflectionData {
+                        addr: entry.addr.to_string(),
+                        age_secs: entry.age_secs,
+                    }),
             },
             stun_backoff_remaining_ms: snapshot.stun_backoff_remaining_ms,
         }),

src/api/runtime_selftest.rs

@@ -1,5 +1,5 @@
-use std::net::IpAddr;
 use std::collections::HashMap;
+use std::net::IpAddr;
 use std::sync::{Mutex, OnceLock};
 use std::time::{SystemTime, UNIX_EPOCH};
 
@@ -7,8 +7,8 @@ use serde::Serialize;
 
 use crate::config::{ProxyConfig, UpstreamType};
 use crate::network::probe::{detect_interface_ipv4, detect_interface_ipv6, is_bogon};
-use crate::transport::middle_proxy::{bnd_snapshot, timeskew_snapshot, upstream_bnd_snapshots};
 use crate::transport::UpstreamRouteKind;
+use crate::transport::middle_proxy::{bnd_snapshot, timeskew_snapshot, upstream_bnd_snapshots};
 
 use super::ApiShared;
 
@@ -262,8 +262,8 @@ fn update_kdf_ewma(now_epoch_secs: u64, total_errors: u64) -> f64 {
     let delta_errors = total_errors.saturating_sub(guard.last_total_errors);
     let instant_rate_per_min = (delta_errors as f64) * 60.0 / (dt_secs as f64);
     let alpha = 1.0 - f64::exp(-(dt_secs as f64) / KDF_EWMA_TAU_SECS);
-    guard.ewma_errors_per_min = guard.ewma_errors_per_min
-        + alpha * (instant_rate_per_min - guard.ewma_errors_per_min);
+    guard.ewma_errors_per_min =
+        guard.ewma_errors_per_min + alpha * (instant_rate_per_min - guard.ewma_errors_per_min);
     guard.last_epoch_secs = now_epoch_secs;
     guard.last_total_errors = total_errors;
     guard.ewma_errors_per_min
@@ -284,6 +284,7 @@ fn map_route_kind(value: UpstreamRouteKind) -> &'static str {
         UpstreamRouteKind::Direct => "direct",
         UpstreamRouteKind::Socks4 => "socks4",
         UpstreamRouteKind::Socks5 => "socks5",
+        UpstreamRouteKind::Shadowsocks => "shadowsocks",
     }
 }
 

src/api/runtime_stats.rs

@@ -2,8 +2,8 @@ use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
 use crate::config::ApiConfig;
 use crate::stats::Stats;
-use crate::transport::upstream::IpPreference;
 use crate::transport::UpstreamRouteKind;
+use crate::transport::upstream::IpPreference;
 
 use super::ApiShared;
 use super::model::{
@@ -68,6 +68,25 @@ pub(super) fn build_zero_all_data(stats: &Stats, configured_users: usize) -> Zer
             route_drop_queue_full_total: stats.get_me_route_drop_queue_full(),
             route_drop_queue_full_base_total: stats.get_me_route_drop_queue_full_base(),
             route_drop_queue_full_high_total: stats.get_me_route_drop_queue_full_high(),
+            d2c_batches_total: stats.get_me_d2c_batches_total(),
+            d2c_batch_frames_total: stats.get_me_d2c_batch_frames_total(),
+            d2c_batch_bytes_total: stats.get_me_d2c_batch_bytes_total(),
+            d2c_flush_reason_queue_drain_total: stats.get_me_d2c_flush_reason_queue_drain_total(),
+            d2c_flush_reason_batch_frames_total: stats.get_me_d2c_flush_reason_batch_frames_total(),
+            d2c_flush_reason_batch_bytes_total: stats.get_me_d2c_flush_reason_batch_bytes_total(),
+            d2c_flush_reason_max_delay_total: stats.get_me_d2c_flush_reason_max_delay_total(),
+            d2c_flush_reason_ack_immediate_total: stats
+                .get_me_d2c_flush_reason_ack_immediate_total(),
+            d2c_flush_reason_close_total: stats.get_me_d2c_flush_reason_close_total(),
+            d2c_data_frames_total: stats.get_me_d2c_data_frames_total(),
+            d2c_ack_frames_total: stats.get_me_d2c_ack_frames_total(),
+            d2c_payload_bytes_total: stats.get_me_d2c_payload_bytes_total(),
+            d2c_write_mode_coalesced_total: stats.get_me_d2c_write_mode_coalesced_total(),
+            d2c_write_mode_split_total: stats.get_me_d2c_write_mode_split_total(),
+            d2c_quota_reject_pre_write_total: stats.get_me_d2c_quota_reject_pre_write_total(),
+            d2c_quota_reject_post_write_total: stats.get_me_d2c_quota_reject_post_write_total(),
+            d2c_frame_buf_shrink_total: stats.get_me_d2c_frame_buf_shrink_total(),
+            d2c_frame_buf_shrink_bytes_total: stats.get_me_d2c_frame_buf_shrink_bytes_total(),
             socks_kdf_strict_reject_total: stats.get_me_socks_kdf_strict_reject(),
             socks_kdf_compat_fallback_total: stats.get_me_socks_kdf_compat_fallback(),
             endpoint_quarantine_total: stats.get_me_endpoint_quarantine_total(),
@@ -136,7 +155,8 @@ fn build_zero_upstream_data(stats: &Stats) -> ZeroUpstreamData {
             .get_upstream_connect_duration_success_bucket_501_1000ms(),
         connect_duration_success_bucket_gt_1000ms: stats
             .get_upstream_connect_duration_success_bucket_gt_1000ms(),
-        connect_duration_fail_bucket_le_100ms: stats.get_upstream_connect_duration_fail_bucket_le_100ms(),
+        connect_duration_fail_bucket_le_100ms: stats
+            .get_upstream_connect_duration_fail_bucket_le_100ms(),
         connect_duration_fail_bucket_101_500ms: stats
             .get_upstream_connect_duration_fail_bucket_101_500ms(),
         connect_duration_fail_bucket_501_1000ms: stats
@@ -178,6 +198,7 @@ pub(super) fn build_upstreams_data(shared: &ApiShared, api_cfg: &ApiConfig) -> U
         direct_total: snapshot.summary.direct_total,
         socks4_total: snapshot.summary.socks4_total,
         socks5_total: snapshot.summary.socks5_total,
+        shadowsocks_total: snapshot.summary.shadowsocks_total,
     };
     let upstreams = snapshot
         .upstreams
@@ -391,8 +412,7 @@ async fn get_minimal_payload_cached(
         adaptive_floor_min_writers_multi_endpoint: runtime
             .adaptive_floor_min_writers_multi_endpoint,
         adaptive_floor_recover_grace_secs: runtime.adaptive_floor_recover_grace_secs,
-        adaptive_floor_writers_per_core_total: runtime
-            .adaptive_floor_writers_per_core_total,
+        adaptive_floor_writers_per_core_total: runtime.adaptive_floor_writers_per_core_total,
         adaptive_floor_cpu_cores_override: runtime.adaptive_floor_cpu_cores_override,
         adaptive_floor_max_extra_writers_single_per_core: runtime
             .adaptive_floor_max_extra_writers_single_per_core,
@@ -400,12 +420,9 @@ async fn get_minimal_payload_cached(
             .adaptive_floor_max_extra_writers_multi_per_core,
         adaptive_floor_max_active_writers_per_core: runtime
             .adaptive_floor_max_active_writers_per_core,
-        adaptive_floor_max_warm_writers_per_core: runtime
-            .adaptive_floor_max_warm_writers_per_core,
-        adaptive_floor_max_active_writers_global: runtime
-            .adaptive_floor_max_active_writers_global,
-        adaptive_floor_max_warm_writers_global: runtime
-            .adaptive_floor_max_warm_writers_global,
+        adaptive_floor_max_warm_writers_per_core: runtime.adaptive_floor_max_warm_writers_per_core,
+        adaptive_floor_max_active_writers_global: runtime.adaptive_floor_max_active_writers_global,
+        adaptive_floor_max_warm_writers_global: runtime.adaptive_floor_max_warm_writers_global,
         adaptive_floor_cpu_cores_detected: runtime.adaptive_floor_cpu_cores_detected,
         adaptive_floor_cpu_cores_effective: runtime.adaptive_floor_cpu_cores_effective,
         adaptive_floor_global_cap_raw: runtime.adaptive_floor_global_cap_raw,
@@ -517,6 +534,7 @@ fn map_route_kind(value: UpstreamRouteKind) -> &'static str {
         UpstreamRouteKind::Direct => "direct",
         UpstreamRouteKind::Socks4 => "socks4",
         UpstreamRouteKind::Socks5 => "socks5",
+        UpstreamRouteKind::Shadowsocks => "shadowsocks",
     }
 }
 

src/api/runtime_zero.rs

@@ -35,11 +35,14 @@ pub(super) struct RuntimeGatesData {
     pub(super) conditional_cast_enabled: bool,
     pub(super) me_runtime_ready: bool,
     pub(super) me2dc_fallback_enabled: bool,
+    pub(super) me2dc_fast_enabled: bool,
     pub(super) use_middle_proxy: bool,
     pub(super) route_mode: &'static str,
     pub(super) reroute_active: bool,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub(super) reroute_to_direct_at_epoch_secs: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reroute_reason: Option<&'static str>,
     pub(super) startup_status: &'static str,
     pub(super) startup_stage: String,
     pub(super) startup_progress_pct: f64,
@@ -47,6 +50,7 @@ pub(super) struct RuntimeGatesData {
 
 #[derive(Serialize)]
 pub(super) struct EffectiveTimeoutLimits {
+    pub(super) client_first_byte_idle_secs: u64,
     pub(super) client_handshake_secs: u64,
     pub(super) tg_connect_secs: u64,
     pub(super) client_keepalive_secs: u64,
@@ -86,6 +90,7 @@ pub(super) struct EffectiveMiddleProxyLimits {
     pub(super) writer_pick_mode: &'static str,
     pub(super) writer_pick_sample_size: u8,
     pub(super) me2dc_fallback: bool,
+    pub(super) me2dc_fast: bool,
 }
 
 #[derive(Serialize)]
@@ -128,7 +133,8 @@ pub(super) fn build_system_info_data(
         .runtime_state
         .last_config_reload_epoch_secs
         .load(Ordering::Relaxed);
-    let last_config_reload_epoch_secs = (last_reload_epoch_secs > 0).then_some(last_reload_epoch_secs);
+    let last_config_reload_epoch_secs =
+        (last_reload_epoch_secs > 0).then_some(last_reload_epoch_secs);
 
     let git_commit = option_env!("TELEMT_GIT_COMMIT")
         .or(option_env!("VERGEN_GIT_SHA"))
@@ -153,7 +159,10 @@ pub(super) fn build_system_info_data(
         uptime_seconds: shared.stats.uptime_secs(),
         config_path: shared.config_path.display().to_string(),
         config_hash: revision.to_string(),
-        config_reload_count: shared.runtime_state.config_reload_count.load(Ordering::Relaxed),
+        config_reload_count: shared
+            .runtime_state
+            .config_reload_count
+            .load(Ordering::Relaxed),
         last_config_reload_epoch_secs,
     }
 }
@@ -165,6 +174,8 @@ pub(super) async fn build_runtime_gates_data(
     let startup_summary = build_runtime_startup_summary(shared).await;
     let route_state = shared.route_runtime.snapshot();
     let route_mode = route_state.mode.as_str();
+    let fast_fallback_enabled =
+        cfg.general.use_middle_proxy && cfg.general.me2dc_fallback && cfg.general.me2dc_fast;
     let reroute_active = cfg.general.use_middle_proxy
         && cfg.general.me2dc_fallback
         && matches!(route_state.mode, RelayRouteMode::Direct);
@@ -173,6 +184,15 @@ pub(super) async fn build_runtime_gates_data(
     } else {
         None
     };
+    let reroute_reason = if reroute_active {
+        if fast_fallback_enabled {
+            Some("fast_not_ready_fallback")
+        } else {
+            Some("strict_grace_fallback")
+        }
+    } else {
+        None
+    };
     let me_runtime_ready = if !cfg.general.use_middle_proxy {
         true
     } else {
@@ -190,10 +210,12 @@ pub(super) async fn build_runtime_gates_data(
         conditional_cast_enabled: cfg.general.use_middle_proxy,
         me_runtime_ready,
         me2dc_fallback_enabled: cfg.general.me2dc_fallback,
+        me2dc_fast_enabled: fast_fallback_enabled,
         use_middle_proxy: cfg.general.use_middle_proxy,
         route_mode,
         reroute_active,
         reroute_to_direct_at_epoch_secs,
+        reroute_reason,
         startup_status: startup_summary.status,
         startup_stage: startup_summary.stage,
         startup_progress_pct: startup_summary.progress_pct,
@@ -206,8 +228,9 @@ pub(super) fn build_limits_effective_data(cfg: &ProxyConfig) -> EffectiveLimitsD
         me_reinit_every_secs: cfg.general.effective_me_reinit_every_secs(),
         me_pool_force_close_secs: cfg.general.effective_me_pool_force_close_secs(),
         timeouts: EffectiveTimeoutLimits {
+            client_first_byte_idle_secs: cfg.timeouts.client_first_byte_idle_secs,
             client_handshake_secs: cfg.timeouts.client_handshake,
-            tg_connect_secs: cfg.timeouts.tg_connect,
+            tg_connect_secs: cfg.general.tg_connect,
             client_keepalive_secs: cfg.timeouts.client_keepalive,
             client_ack_secs: cfg.timeouts.client_ack,
             me_one_retry: cfg.timeouts.me_one_retry,
@@ -233,9 +256,7 @@ pub(super) fn build_limits_effective_data(cfg: &ProxyConfig) -> EffectiveLimitsD
             adaptive_floor_writers_per_core_total: cfg
                 .general
                 .me_adaptive_floor_writers_per_core_total,
-            adaptive_floor_cpu_cores_override: cfg
-                .general
-                .me_adaptive_floor_cpu_cores_override,
+            adaptive_floor_cpu_cores_override: cfg.general.me_adaptive_floor_cpu_cores_override,
             adaptive_floor_max_extra_writers_single_per_core: cfg
                 .general
                 .me_adaptive_floor_max_extra_writers_single_per_core,
@@ -261,6 +282,7 @@ pub(super) fn build_limits_effective_data(cfg: &ProxyConfig) -> EffectiveLimitsD
             writer_pick_mode: me_writer_pick_mode_label(cfg.general.me_writer_pick_mode),
             writer_pick_sample_size: cfg.general.me_writer_pick_sample_size,
             me2dc_fallback: cfg.general.me2dc_fallback,
+            me2dc_fast: cfg.general.me2dc_fast,
         },
         user_ip_policy: EffectiveUserIpPolicyLimits {
             global_each: cfg.access.user_max_unique_ips_global_each,

src/api/users.rs

@@ -46,7 +46,9 @@ pub(super) async fn create_user(
         None => random_user_secret(),
     };
 
-    if let Some(ad_tag) = body.user_ad_tag.as_ref() && !is_valid_ad_tag(ad_tag) {
+    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",
         ));
@@ -65,12 +67,18 @@ pub(super) async fn create_user(
         ));
     }
 
-    cfg.access.users.insert(body.username.clone(), secret.clone());
+    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);
+        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);
+        cfg.access
+            .user_max_tcp_conns
+            .insert(body.username.clone(), limit);
     }
     if let Some(expiration) = expiration {
         cfg.access
@@ -78,7 +86,9 @@ pub(super) async fn create_user(
             .insert(body.username.clone(), expiration);
     }
     if let Some(quota) = body.data_quota_bytes {
-        cfg.access.user_data_quota.insert(body.username.clone(), quota);
+        cfg.access
+            .user_data_quota
+            .insert(body.username.clone(), quota);
     }
 
     let updated_limit = body.max_unique_ips;
@@ -108,11 +118,15 @@ pub(super) async fn create_user(
         touched_sections.push(AccessSection::UserMaxUniqueIps);
     }
 
-    let revision = save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
+    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;
+        shared
+            .ip_tracker
+            .set_user_limit(&body.username, limit)
+            .await;
     }
     let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
 
@@ -140,12 +154,7 @@ pub(super) async fn create_user(
             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,
-            ),
+            links: build_user_links(&cfg, &secret, detected_ip_v4, detected_ip_v6),
         });
 
     Ok((CreateUserResponse { user, secret }, revision))
@@ -157,12 +166,16 @@ pub(super) async fn patch_user(
     expected_revision: Option<String>,
     shared: &ApiShared,
 ) -> Result<(UserInfo, String), ApiFailure> {
-    if let Some(secret) = body.secret.as_ref() && !is_valid_user_secret(secret) {
+    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) {
+    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",
         ));
@@ -187,10 +200,14 @@ pub(super) async fn patch_user(
         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);
+        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);
+        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);
@@ -198,7 +215,9 @@ pub(super) async fn patch_user(
 
     let mut updated_limit = None;
     if let Some(limit) = body.max_unique_ips {
-        cfg.access.user_max_unique_ips.insert(user.to_string(), limit);
+        cfg.access
+            .user_max_unique_ips
+            .insert(user.to_string(), limit);
         updated_limit = Some(limit);
     }
 
@@ -263,7 +282,8 @@ pub(super) async fn rotate_secret(
         AccessSection::UserDataQuota,
         AccessSection::UserMaxUniqueIps,
     ];
-    let revision = save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
+    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();
@@ -330,7 +350,8 @@ pub(super) async fn delete_user(
         AccessSection::UserDataQuota,
         AccessSection::UserMaxUniqueIps,
     ];
-    let revision = save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
+    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;
@@ -365,12 +386,7 @@ pub(super) async fn users_from_config(
             .users
             .get(&username)
             .map(|secret| {
-                build_user_links(
-                    cfg,
-                    secret,
-                    startup_detected_ip_v4,
-                    startup_detected_ip_v6,
-                )
+                build_user_links(cfg, secret, startup_detected_ip_v4, startup_detected_ip_v6)
             })
             .unwrap_or(UserLinks {
                 classic: Vec::new(),
@@ -392,10 +408,8 @@ pub(super) async fn users_from_config(
                 .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),
-                ),
+                .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,
@@ -481,11 +495,11 @@ fn resolve_link_hosts(
             push_unique_host(&mut hosts, host);
             continue;
         }
-        if let Some(ip) = listener.announce_ip {
-            if !ip.is_unspecified() {
-                push_unique_host(&mut hosts, &ip.to_string());
-                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() {

src/cli.rs

@@ -1,11 +1,270 @@
-//! CLI commands: --init (fire-and-forget setup)
+//! CLI commands: --init (fire-and-forget setup), daemon options, subcommands
+//!
+//! Subcommands:
+//! - `start [OPTIONS] [config.toml]` - Start the daemon
+//! - `stop [--pid-file PATH]` - Stop a running daemon
+//! - `reload [--pid-file PATH]` - Reload configuration (SIGHUP)
+//! - `status [--pid-file PATH]` - Check daemon status
+//! - `run [OPTIONS] [config.toml]` - Run in foreground (default behavior)
 
+use rand::RngExt;
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::process::Command;
-use rand::Rng;
+
+#[cfg(unix)]
+use crate::daemon::{self, DaemonOptions, DEFAULT_PID_FILE};
+
+/// CLI subcommand to execute.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Subcommand {
+    /// Run the proxy (default, or explicit `run` subcommand).
+    Run,
+    /// Start as daemon (`start` subcommand).
+    Start,
+    /// Stop a running daemon (`stop` subcommand).
+    Stop,
+    /// Reload configuration (`reload` subcommand).
+    Reload,
+    /// Check daemon status (`status` subcommand).
+    Status,
+    /// Fire-and-forget setup (`--init`).
+    Init,
+}
+
+/// Parsed subcommand with its options.
+#[derive(Debug)]
+pub struct ParsedCommand {
+    pub subcommand: Subcommand,
+    pub pid_file: PathBuf,
+    pub config_path: String,
+    #[cfg(unix)]
+    pub daemon_opts: DaemonOptions,
+    pub init_opts: Option<InitOptions>,
+}
+
+impl Default for ParsedCommand {
+    fn default() -> Self {
+        Self {
+            subcommand: Subcommand::Run,
+            #[cfg(unix)]
+            pid_file: PathBuf::from(DEFAULT_PID_FILE),
+            #[cfg(not(unix))]
+            pid_file: PathBuf::from("/var/run/telemt.pid"),
+            config_path: "config.toml".to_string(),
+            #[cfg(unix)]
+            daemon_opts: DaemonOptions::default(),
+            init_opts: None,
+        }
+    }
+}
+
+/// Parse CLI arguments into a command structure.
+pub fn parse_command(args: &[String]) -> ParsedCommand {
+    let mut cmd = ParsedCommand::default();
+
+    // Check for --init first (legacy form)
+    if args.iter().any(|a| a == "--init") {
+        cmd.subcommand = Subcommand::Init;
+        cmd.init_opts = parse_init_args(args);
+        return cmd;
+    }
+
+    // Check for subcommand as first argument
+    if let Some(first) = args.first() {
+        match first.as_str() {
+            "start" => {
+                cmd.subcommand = Subcommand::Start;
+                #[cfg(unix)]
+                {
+                    cmd.daemon_opts = parse_daemon_args(args);
+                    // Force daemonize for start command
+                    cmd.daemon_opts.daemonize = true;
+                }
+            }
+            "stop" => {
+                cmd.subcommand = Subcommand::Stop;
+            }
+            "reload" => {
+                cmd.subcommand = Subcommand::Reload;
+            }
+            "status" => {
+                cmd.subcommand = Subcommand::Status;
+            }
+            "run" => {
+                cmd.subcommand = Subcommand::Run;
+                #[cfg(unix)]
+                {
+                    cmd.daemon_opts = parse_daemon_args(args);
+                }
+            }
+            _ => {
+                // No subcommand, default to Run
+                #[cfg(unix)]
+                {
+                    cmd.daemon_opts = parse_daemon_args(args);
+                }
+            }
+        }
+    }
+
+    // Parse remaining options
+    let mut i = 0;
+    while i < args.len() {
+        match args[i].as_str() {
+            // Skip subcommand names
+            "start" | "stop" | "reload" | "status" | "run" => {}
+            // PID file option (for stop/reload/status)
+            "--pid-file" => {
+                i += 1;
+                if i < args.len() {
+                    cmd.pid_file = PathBuf::from(&args[i]);
+                    #[cfg(unix)]
+                    {
+                        cmd.daemon_opts.pid_file = Some(cmd.pid_file.clone());
+                    }
+                }
+            }
+            s if s.starts_with("--pid-file=") => {
+                cmd.pid_file = PathBuf::from(s.trim_start_matches("--pid-file="));
+                #[cfg(unix)]
+                {
+                    cmd.daemon_opts.pid_file = Some(cmd.pid_file.clone());
+                }
+            }
+            // Config path (positional, non-flag argument)
+            s if !s.starts_with('-') => {
+                cmd.config_path = s.to_string();
+            }
+            _ => {}
+        }
+        i += 1;
+    }
+
+    cmd
+}
+
+/// Execute a subcommand that doesn't require starting the server.
+/// Returns `Some(exit_code)` if the command was handled, `None` if server should start.
+#[cfg(unix)]
+pub fn execute_subcommand(cmd: &ParsedCommand) -> Option<i32> {
+    match cmd.subcommand {
+        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::Init => {
+            if let Some(opts) = cmd.init_opts.clone() {
+                match run_init(opts) {
+                    Ok(()) => Some(0),
+                    Err(e) => {
+                        eprintln!("[telemt] Init failed: {}", e);
+                        Some(1)
+                    }
+                }
+            } else {
+                Some(1)
+            }
+        }
+        // Run and Start need the server
+        Subcommand::Run | Subcommand::Start => None,
+    }
+}
+
+#[cfg(not(unix))]
+pub fn execute_subcommand(cmd: &ParsedCommand) -> Option<i32> {
+    match cmd.subcommand {
+        Subcommand::Stop | Subcommand::Reload | Subcommand::Status => {
+            eprintln!("[telemt] Subcommand not supported on this platform");
+            Some(1)
+        }
+        Subcommand::Init => {
+            if let Some(opts) = cmd.init_opts.clone() {
+                match run_init(opts) {
+                    Ok(()) => Some(0),
+                    Err(e) => {
+                        eprintln!("[telemt] Init failed: {}", e);
+                        Some(1)
+                    }
+                }
+            } else {
+                Some(1)
+            }
+        }
+        Subcommand::Run | Subcommand::Start => None,
+    }
+}
+
+/// Stop command: send SIGTERM to the running daemon.
+#[cfg(unix)]
+fn cmd_stop(pid_file: &Path) -> i32 {
+    use nix::sys::signal::Signal;
+
+    println!("Stopping telemt daemon...");
+
+    match daemon::signal_pid_file(pid_file, Signal::SIGTERM) {
+        Ok(()) => {
+            println!("Stop signal sent successfully");
+
+            // Wait for process to exit (up to 10 seconds)
+            for _ in 0..20 {
+                std::thread::sleep(std::time::Duration::from_millis(500));
+                if let daemon::DaemonStatus::NotRunning = daemon::check_status(pid_file) {
+                    println!("Daemon stopped");
+                    return 0;
+                }
+            }
+            println!("Daemon may still be shutting down");
+            0
+        }
+        Err(e) => {
+            eprintln!("Failed to stop daemon: {}", e);
+            1
+        }
+    }
+}
+
+/// Reload command: send SIGHUP to trigger config reload.
+#[cfg(unix)]
+fn cmd_reload(pid_file: &Path) -> i32 {
+    use nix::sys::signal::Signal;
+
+    println!("Reloading telemt configuration...");
+
+    match daemon::signal_pid_file(pid_file, Signal::SIGHUP) {
+        Ok(()) => {
+            println!("Reload signal sent successfully");
+            0
+        }
+        Err(e) => {
+            eprintln!("Failed to reload daemon: {}", e);
+            1
+        }
+    }
+}
+
+/// Status command: check if daemon is running.
+#[cfg(unix)]
+fn cmd_status(pid_file: &Path) -> i32 {
+    match daemon::check_status(pid_file) {
+        daemon::DaemonStatus::Running(pid) => {
+            println!("telemt is running (pid {})", pid);
+            0
+        }
+        daemon::DaemonStatus::Stale(pid) => {
+            println!("telemt is not running (stale pid file, was pid {})", pid);
+            // Clean up stale PID file
+            let _ = std::fs::remove_file(pid_file);
+            1
+        }
+        daemon::DaemonStatus::NotRunning => {
+            println!("telemt is not running");
+            1
+        }
+    }
+}
 
 /// Options for the init command
+#[derive(Debug, Clone)]
 pub struct InitOptions {
     pub port: u16,
     pub domain: String,
@@ -15,6 +274,64 @@ pub struct InitOptions {
     pub no_start: bool,
 }
 
+/// Parse daemon-related options from CLI args.
+#[cfg(unix)]
+pub fn parse_daemon_args(args: &[String]) -> DaemonOptions {
+    let mut opts = DaemonOptions::default();
+    let mut i = 0;
+
+    while i < args.len() {
+        match args[i].as_str() {
+            "--daemon" | "-d" => {
+                opts.daemonize = true;
+            }
+            "--foreground" | "-f" => {
+                opts.foreground = true;
+            }
+            "--pid-file" => {
+                i += 1;
+                if i < args.len() {
+                    opts.pid_file = Some(PathBuf::from(&args[i]));
+                }
+            }
+            s if s.starts_with("--pid-file=") => {
+                opts.pid_file = Some(PathBuf::from(s.trim_start_matches("--pid-file=")));
+            }
+            "--run-as-user" => {
+                i += 1;
+                if i < args.len() {
+                    opts.user = Some(args[i].clone());
+                }
+            }
+            s if s.starts_with("--run-as-user=") => {
+                opts.user = Some(s.trim_start_matches("--run-as-user=").to_string());
+            }
+            "--run-as-group" => {
+                i += 1;
+                if i < args.len() {
+                    opts.group = Some(args[i].clone());
+                }
+            }
+            s if s.starts_with("--run-as-group=") => {
+                opts.group = Some(s.trim_start_matches("--run-as-group=").to_string());
+            }
+            "--working-dir" => {
+                i += 1;
+                if i < args.len() {
+                    opts.working_dir = Some(PathBuf::from(&args[i]));
+                }
+            }
+            s if s.starts_with("--working-dir=") => {
+                opts.working_dir = Some(PathBuf::from(s.trim_start_matches("--working-dir=")));
+            }
+            _ => {}
+        }
+        i += 1;
+    }
+
+    opts
+}
+
 impl Default for InitOptions {
     fn default() -> Self {
         Self {
@@ -35,10 +352,10 @@ pub fn parse_init_args(args: &[String]) -> Option<InitOptions> {
     if !args.iter().any(|a| a == "--init") {
         return None;
     }
-    
+
     let mut opts = InitOptions::default();
     let mut i = 0;
-    
+
     while i < args.len() {
         match args[i].as_str() {
             "--port" => {
@@ -78,16 +395,22 @@ pub fn parse_init_args(args: &[String]) -> Option<InitOptions> {
         }
         i += 1;
     }
-    
+
     Some(opts)
 }
 
 /// Run the fire-and-forget setup.
 pub fn run_init(opts: InitOptions) -> Result<(), Box<dyn std::error::Error>> {
+    use crate::service::{self, InitSystem, ServiceOptions};
+
     eprintln!("[telemt] Fire-and-forget setup");
     eprintln!();
-    
-    // 1. Generate or validate secret
+
+    // 1. Detect init system
+    let init_system = service::detect_init_system();
+    eprintln!("[+] Detected init system: {}", init_system);
+
+    // 2. Generate or validate secret
     let secret = match opts.secret {
         Some(s) => {
             if s.len() != 32 || !s.chars().all(|c| c.is_ascii_hexdigit()) {
@@ -98,80 +421,134 @@ pub fn run_init(opts: InitOptions) -> Result<(), Box<dyn std::error::Error>> {
         }
         None => generate_secret(),
     };
-    
+
     eprintln!("[+] Secret: {}", secret);
     eprintln!("[+] User:   {}", opts.username);
     eprintln!("[+] Port:   {}", opts.port);
     eprintln!("[+] Domain: {}", opts.domain);
-    
-    // 2. Create config directory
+
+    // 3. Create config directory
     fs::create_dir_all(&opts.config_dir)?;
     let config_path = opts.config_dir.join("config.toml");
-    
-    // 3. Write config
+
+    // 4. Write config
     let config_content = generate_config(&opts.username, &secret, opts.port, &opts.domain);
     fs::write(&config_path, &config_content)?;
     eprintln!("[+] Config written to {}", config_path.display());
-    
-    // 4. Write systemd unit
+
+    // 5. Generate and write service file
     let exe_path = std::env::current_exe()
         .unwrap_or_else(|_| PathBuf::from("/usr/local/bin/telemt"));
-    
-    let unit_path = Path::new("/etc/systemd/system/telemt.service");
-    let unit_content = generate_systemd_unit(&exe_path, &config_path);
-    
-    match fs::write(unit_path, &unit_content) {
+
+    let service_opts = ServiceOptions {
+        exe_path: &exe_path,
+        config_path: &config_path,
+        user: None,  // Let systemd/init handle user
+        group: None,
+        pid_file: "/var/run/telemt.pid",
+        working_dir: Some("/var/lib/telemt"),
+        description: "Telemt MTProxy - Telegram MTProto Proxy",
+    };
+
+    let service_path = service::service_file_path(init_system);
+    let service_content = service::generate_service_file(init_system, &service_opts);
+
+    // Ensure parent directory exists
+    if let Some(parent) = Path::new(service_path).parent() {
+        let _ = fs::create_dir_all(parent);
+    }
+
+    match fs::write(service_path, &service_content) {
         Ok(()) => {
-            eprintln!("[+] Systemd unit written to {}", unit_path.display());
+            eprintln!("[+] Service file written to {}", service_path);
+
+            // Make script executable for OpenRC/FreeBSD
+            #[cfg(unix)]
+            if init_system == InitSystem::OpenRC || init_system == InitSystem::FreeBSDRc {
+                use std::os::unix::fs::PermissionsExt;
+                let mut perms = fs::metadata(service_path)?.permissions();
+                perms.set_mode(0o755);
+                fs::set_permissions(service_path, perms)?;
+            }
         }
         Err(e) => {
-            eprintln!("[!] Cannot write systemd unit (run as root?): {}", e);
-            eprintln!("[!] Manual unit file content:");
-            eprintln!("{}", unit_content);
-            
-            // Still print links and config
+            eprintln!("[!] Cannot write service file (run as root?): {}", e);
+            eprintln!("[!] Manual service file content:");
+            eprintln!("{}", service_content);
+
+            // Still print links and installation instructions
+            eprintln!();
+            eprintln!("{}", service::installation_instructions(init_system));
             print_links(&opts.username, &secret, opts.port, &opts.domain);
             return Ok(());
         }
     }
-    
-    // 5. Reload systemd
-    run_cmd("systemctl", &["daemon-reload"]);
-    
-    // 6. Enable service
-    run_cmd("systemctl", &["enable", "telemt.service"]);
-    eprintln!("[+] Service enabled");
-    
-    // 7. Start service (unless --no-start)
-    if !opts.no_start {
-        run_cmd("systemctl", &["start", "telemt.service"]);
-        eprintln!("[+] Service started");
-        
-        // Brief delay then check status
-        std::thread::sleep(std::time::Duration::from_secs(1));
-        let status = Command::new("systemctl")
-            .args(["is-active", "telemt.service"])
-            .output();
-        
-        match status {
-            Ok(out) if out.status.success() => {
-                eprintln!("[+] Service is running");
-            }
-            _ => {
-                eprintln!("[!] Service may not have started correctly");
-                eprintln!("[!] Check: journalctl -u telemt.service -n 20");
+
+    // 6. Install and enable service based on init system
+    match init_system {
+        InitSystem::Systemd => {
+            run_cmd("systemctl", &["daemon-reload"]);
+            run_cmd("systemctl", &["enable", "telemt.service"]);
+            eprintln!("[+] Service enabled");
+
+            if !opts.no_start {
+                run_cmd("systemctl", &["start", "telemt.service"]);
+                eprintln!("[+] Service started");
+
+                std::thread::sleep(std::time::Duration::from_secs(1));
+                let status = Command::new("systemctl")
+                    .args(["is-active", "telemt.service"])
+                    .output();
+
+                match status {
+                    Ok(out) if out.status.success() => {
+                        eprintln!("[+] Service is running");
+                    }
+                    _ => {
+                        eprintln!("[!] Service may not have started correctly");
+                        eprintln!("[!] Check: journalctl -u telemt.service -n 20");
+                    }
+                }
+            } else {
+                eprintln!("[+] Service not started (--no-start)");
+                eprintln!("[+] Start manually: systemctl start telemt.service");
             }
         }
-    } else {
-        eprintln!("[+] Service not started (--no-start)");
-        eprintln!("[+] Start manually: systemctl start telemt.service");
+        InitSystem::OpenRC => {
+            run_cmd("rc-update", &["add", "telemt", "default"]);
+            eprintln!("[+] Service enabled");
+
+            if !opts.no_start {
+                run_cmd("rc-service", &["telemt", "start"]);
+                eprintln!("[+] Service started");
+            } else {
+                eprintln!("[+] Service not started (--no-start)");
+                eprintln!("[+] Start manually: rc-service telemt start");
+            }
+        }
+        InitSystem::FreeBSDRc => {
+            run_cmd("sysrc", &["telemt_enable=YES"]);
+            eprintln!("[+] Service enabled");
+
+            if !opts.no_start {
+                run_cmd("service", &["telemt", "start"]);
+                eprintln!("[+] Service started");
+            } else {
+                eprintln!("[+] Service not started (--no-start)");
+                eprintln!("[+] Start manually: service telemt start");
+            }
+        }
+        InitSystem::Unknown => {
+            eprintln!("[!] Unknown init system - service file written but not installed");
+            eprintln!("[!] You may need to install it manually");
+        }
     }
-    
+
     eprintln!();
-    
-    // 8. Print links
+
+    // 7. Print links
     print_links(&opts.username, &secret, opts.port, &opts.domain);
-    
+
     Ok(())
 }
 
@@ -183,7 +560,7 @@ fn generate_secret() -> String {
 
 fn generate_config(username: &str, secret: &str, port: u16, domain: &str) -> String {
     format!(
-r#"# Telemt MTProxy — auto-generated config
+        r#"# Telemt MTProxy — auto-generated config
 # Re-run `telemt --init` to regenerate
 
 show_link = ["{username}"]
@@ -198,8 +575,16 @@ desync_all_full = false
 update_every = 43200
 hardswap = false
 me_pool_drain_ttl_secs = 90
+me_instadrain = false
+me_pool_drain_threshold = 32
+me_pool_drain_soft_evict_grace_secs = 10
+me_pool_drain_soft_evict_per_writer = 2
+me_pool_drain_soft_evict_budget_per_core = 16
+me_pool_drain_soft_evict_cooldown_ms = 1000
+me_bind_stale_mode = "never"
 me_pool_min_fresh_ratio = 0.8
-me_reinit_drain_timeout_secs = 120
+me_reinit_drain_timeout_secs = 90
+tg_connect = 10
 
 [network]
 ipv4 = true
@@ -225,8 +610,8 @@ ip = "0.0.0.0"
 ip = "::"
 
 [timeouts]
-client_handshake = 15
-tg_connect = 10
+client_first_byte_idle_secs = 300
+client_handshake = 60
 client_keepalive = 60
 client_ack = 300
 
@@ -239,7 +624,7 @@ tls_full_cert_ttl_secs = 90
 
 [access]
 replay_check_len = 65536
-replay_window_secs = 1800
+replay_window_secs = 120
 ignore_time_skew = false
 
 [access.users]
@@ -257,35 +642,6 @@ weight = 10
     )
 }
 
-fn generate_systemd_unit(exe_path: &Path, config_path: &Path) -> String {
-    format!(
-r#"[Unit]
-Description=Telemt MTProxy
-Documentation=https://github.com/nicepkg/telemt
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-ExecStart={exe} {config}
-Restart=always
-RestartSec=5
-LimitNOFILE=65535
-# Security hardening
-NoNewPrivileges=true
-ProtectSystem=strict
-ProtectHome=true
-ReadWritePaths=/etc/telemt
-PrivateTmp=true
-
-[Install]
-WantedBy=multi-user.target
-"#,
-        exe = exe_path.display(),
-        config = config_path.display(),
-    )
-}
-
 fn run_cmd(cmd: &str, args: &[&str]) {
     match Command::new(cmd).args(args).output() {
         Ok(output) => {
@@ -302,11 +658,13 @@ fn run_cmd(cmd: &str, args: &[&str]) {
 
 fn print_links(username: &str, secret: &str, port: u16, domain: &str) {
     let domain_hex = hex::encode(domain);
-    
+
     println!("=== Proxy Links ===");
     println!("[{}]", username);
-    println!("  EE-TLS:  tg://proxy?server=YOUR_SERVER_IP&port={}&secret=ee{}{}", 
-        port, secret, domain_hex);
+    println!(
+        "  EE-TLS:  tg://proxy?server=YOUR_SERVER_IP&port={}&secret=ee{}{}",
+        port, secret, domain_hex
+    );
     println!();
     println!("Replace YOUR_SERVER_IP with your server's public IP.");
     println!("The proxy will auto-detect and display the correct link on startup.");

src/config/defaults.rs

@@ -1,6 +1,6 @@
-use std::collections::HashMap;
 use ipnetwork::IpNetwork;
 use serde::Deserialize;
+use std::collections::HashMap;
 
 // Helper defaults kept private to the config module.
 const DEFAULT_NETWORK_IPV6: Option<bool> = Some(false);
@@ -27,8 +27,10 @@ const DEFAULT_ME_C2ME_CHANNEL_CAPACITY: usize = 1024;
 const DEFAULT_ME_READER_ROUTE_DATA_WAIT_MS: u64 = 2;
 const DEFAULT_ME_D2C_FLUSH_BATCH_MAX_FRAMES: usize = 32;
 const DEFAULT_ME_D2C_FLUSH_BATCH_MAX_BYTES: usize = 128 * 1024;
-const DEFAULT_ME_D2C_FLUSH_BATCH_MAX_DELAY_US: u64 = 1500;
-const DEFAULT_ME_D2C_ACK_FLUSH_IMMEDIATE: bool = false;
+const DEFAULT_ME_D2C_FLUSH_BATCH_MAX_DELAY_US: u64 = 500;
+const DEFAULT_ME_D2C_ACK_FLUSH_IMMEDIATE: bool = true;
+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;
 const DEFAULT_ME_WRITER_PICK_SAMPLE_SIZE: u8 = 3;
@@ -36,7 +38,16 @@ const DEFAULT_ME_HEALTH_INTERVAL_MS_UNHEALTHY: u64 = 1000;
 const DEFAULT_ME_HEALTH_INTERVAL_MS_HEALTHY: u64 = 3000;
 const DEFAULT_ME_ADMISSION_POLL_MS: u64 = 1000;
 const DEFAULT_ME_WARN_RATE_LIMIT_MS: u64 = 5000;
+const DEFAULT_ME_ROUTE_HYBRID_MAX_WAIT_MS: u64 = 3000;
+const DEFAULT_ME_ROUTE_BLOCKING_SEND_TIMEOUT_MS: u64 = 250;
+const DEFAULT_ME_C2ME_SEND_TIMEOUT_MS: u64 = 4000;
+const DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_ENABLED: bool = true;
+const DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_GRACE_SECS: u64 = 10;
+const DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_PER_WRITER: u8 = 2;
+const DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_BUDGET_PER_CORE: u16 = 16;
+const DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_COOLDOWN_MS: u64 = 1000;
 const DEFAULT_USER_MAX_UNIQUE_IPS_WINDOW_SECS: u64 = 30;
+const DEFAULT_ACCEPT_PERMIT_TIMEOUT_MS: u64 = 250;
 const DEFAULT_UPSTREAM_CONNECT_RETRY_ATTEMPTS: u32 = 2;
 const DEFAULT_UPSTREAM_UNHEALTHY_FAIL_THRESHOLD: u32 = 5;
 const DEFAULT_UPSTREAM_CONNECT_BUDGET_MS: u64 = 3000;
@@ -56,6 +67,26 @@ pub(crate) fn default_tls_domain() -> String {
     "petrovich.ru".to_string()
 }
 
+pub(crate) fn default_tls_fetch_scope() -> String {
+    String::new()
+}
+
+pub(crate) fn default_tls_fetch_attempt_timeout_ms() -> u64 {
+    5_000
+}
+
+pub(crate) fn default_tls_fetch_total_budget_ms() -> u64 {
+    15_000
+}
+
+pub(crate) fn default_tls_fetch_strict_route() -> bool {
+    true
+}
+
+pub(crate) fn default_tls_fetch_profile_cache_ttl_secs() -> u64 {
+    600
+}
+
 pub(crate) fn default_mask_port() -> u16 {
     443
 }
@@ -73,10 +104,32 @@ pub(crate) fn default_replay_check_len() -> usize {
 }
 
 pub(crate) fn default_replay_window_secs() -> u64 {
-    1800
+    // Keep replay cache TTL tight by default to reduce replay surface.
+    // Deployments with higher RTT or longer reconnect jitter can override this in config.
+    120
 }
 
 pub(crate) fn default_handshake_timeout() -> u64 {
+    60
+}
+
+pub(crate) fn default_client_first_byte_idle_secs() -> u64 {
+    300
+}
+
+pub(crate) fn default_relay_idle_policy_v2_enabled() -> bool {
+    true
+}
+
+pub(crate) fn default_relay_client_idle_soft_secs() -> u64 {
+    120
+}
+
+pub(crate) fn default_relay_client_idle_hard_secs() -> u64 {
+    360
+}
+
+pub(crate) fn default_relay_idle_grace_after_downstream_activity_secs() -> u64 {
     30
 }
 
@@ -85,11 +138,11 @@ pub(crate) fn default_connect_timeout() -> u64 {
 }
 
 pub(crate) fn default_keepalive() -> u64 {
-    60
+    15
 }
 
 pub(crate) fn default_ack_timeout() -> u64 {
-    300
+    90
 }
 pub(crate) fn default_me_one_retry() -> u8 {
     12
@@ -112,10 +165,7 @@ pub(crate) fn default_weight() -> u16 {
 }
 
 pub(crate) fn default_metrics_whitelist() -> Vec<IpNetwork> {
-    vec![
-        "127.0.0.1/32".parse().unwrap(),
-        "::1/128".parse().unwrap(),
-    ]
+    vec!["127.0.0.1/32".parse().unwrap(), "::1/128".parse().unwrap()]
 }
 
 pub(crate) fn default_api_listen() -> String {
@@ -138,19 +188,39 @@ pub(crate) fn default_api_minimal_runtime_cache_ttl_ms() -> u64 {
     1000
 }
 
-pub(crate) fn default_api_runtime_edge_enabled() -> bool { false }
-pub(crate) fn default_api_runtime_edge_cache_ttl_ms() -> u64 { 1000 }
-pub(crate) fn default_api_runtime_edge_top_n() -> usize { 10 }
-pub(crate) fn default_api_runtime_edge_events_capacity() -> usize { 256 }
+pub(crate) fn default_api_runtime_edge_enabled() -> bool {
+    false
+}
+pub(crate) fn default_api_runtime_edge_cache_ttl_ms() -> u64 {
+    1000
+}
+pub(crate) fn default_api_runtime_edge_top_n() -> usize {
+    10
+}
+pub(crate) fn default_api_runtime_edge_events_capacity() -> usize {
+    256
+}
 
 pub(crate) fn default_proxy_protocol_header_timeout_ms() -> u64 {
     500
 }
 
+pub(crate) fn default_proxy_protocol_trusted_cidrs() -> Vec<IpNetwork> {
+    vec!["0.0.0.0/0".parse().unwrap(), "::/0".parse().unwrap()]
+}
+
 pub(crate) fn default_server_max_connections() -> u32 {
     10_000
 }
 
+pub(crate) fn default_listen_backlog() -> u32 {
+    1024
+}
+
+pub(crate) fn default_accept_permit_timeout_ms() -> u64 {
+    DEFAULT_ACCEPT_PERMIT_TIMEOUT_MS
+}
+
 pub(crate) fn default_prefer_4() -> u8 {
     4
 }
@@ -211,6 +281,10 @@ pub(crate) fn default_me2dc_fallback() -> bool {
     true
 }
 
+pub(crate) fn default_me2dc_fast() -> bool {
+    false
+}
+
 pub(crate) fn default_keepalive_interval() -> u64 {
     8
 }
@@ -347,6 +421,14 @@ pub(crate) fn default_me_d2c_ack_flush_immediate() -> bool {
     DEFAULT_ME_D2C_ACK_FLUSH_IMMEDIATE
 }
 
+pub(crate) fn default_me_quota_soft_overshoot_bytes() -> u64 {
+    DEFAULT_ME_QUOTA_SOFT_OVERSHOOT_BYTES
+}
+
+pub(crate) fn default_me_d2c_frame_buf_shrink_threshold_bytes() -> usize {
+    DEFAULT_ME_D2C_FRAME_BUF_SHRINK_THRESHOLD_BYTES
+}
+
 pub(crate) fn default_direct_relay_copy_buf_c2s_bytes() -> usize {
     DEFAULT_DIRECT_RELAY_COPY_BUF_C2S_BYTES
 }
@@ -375,6 +457,18 @@ pub(crate) fn default_me_warn_rate_limit_ms() -> u64 {
     DEFAULT_ME_WARN_RATE_LIMIT_MS
 }
 
+pub(crate) fn default_me_route_hybrid_max_wait_ms() -> u64 {
+    DEFAULT_ME_ROUTE_HYBRID_MAX_WAIT_MS
+}
+
+pub(crate) fn default_me_route_blocking_send_timeout_ms() -> u64 {
+    DEFAULT_ME_ROUTE_BLOCKING_SEND_TIMEOUT_MS
+}
+
+pub(crate) fn default_me_c2me_send_timeout_ms() -> u64 {
+    DEFAULT_ME_C2ME_SEND_TIMEOUT_MS
+}
+
 pub(crate) fn default_upstream_connect_retry_attempts() -> u32 {
     DEFAULT_UPSTREAM_CONNECT_RETRY_ATTEMPTS
 }
@@ -456,17 +550,67 @@ pub(crate) fn default_tls_full_cert_ttl_secs() -> u64 {
 }
 
 pub(crate) fn default_server_hello_delay_min_ms() -> u64 {
-    0
+    8
 }
 
 pub(crate) fn default_server_hello_delay_max_ms() -> u64 {
-    0
+    24
 }
 
 pub(crate) fn default_alpn_enforce() -> bool {
     true
 }
 
+pub(crate) fn default_mask_shape_hardening() -> bool {
+    true
+}
+
+pub(crate) fn default_mask_shape_hardening_aggressive_mode() -> bool {
+    false
+}
+
+pub(crate) fn default_mask_shape_bucket_floor_bytes() -> usize {
+    512
+}
+
+pub(crate) fn default_mask_shape_bucket_cap_bytes() -> usize {
+    4096
+}
+
+pub(crate) fn default_mask_shape_above_cap_blur() -> bool {
+    false
+}
+
+pub(crate) fn default_mask_shape_above_cap_blur_max_bytes() -> usize {
+    512
+}
+
+#[cfg(not(test))]
+pub(crate) fn default_mask_relay_max_bytes() -> usize {
+    5 * 1024 * 1024
+}
+
+#[cfg(test)]
+pub(crate) fn default_mask_relay_max_bytes() -> usize {
+    32 * 1024
+}
+
+pub(crate) fn default_mask_classifier_prefetch_timeout_ms() -> u64 {
+    5
+}
+
+pub(crate) fn default_mask_timing_normalization_enabled() -> bool {
+    false
+}
+
+pub(crate) fn default_mask_timing_normalization_floor_ms() -> u64 {
+    0
+}
+
+pub(crate) fn default_mask_timing_normalization_ceiling_ms() -> u64 {
+    0
+}
+
 pub(crate) fn default_stun_servers() -> Vec<String> {
     vec![
         "stun.l.google.com:5349".to_string(),
@@ -581,15 +725,39 @@ pub(crate) fn default_proxy_secret_len_max() -> usize {
 }
 
 pub(crate) fn default_me_reinit_drain_timeout_secs() -> u64 {
-    120
+    90
 }
 
 pub(crate) fn default_me_pool_drain_ttl_secs() -> u64 {
     90
 }
 
+pub(crate) fn default_me_instadrain() -> bool {
+    false
+}
+
 pub(crate) fn default_me_pool_drain_threshold() -> u64 {
-    128
+    32
+}
+
+pub(crate) fn default_me_pool_drain_soft_evict_enabled() -> bool {
+    DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_ENABLED
+}
+
+pub(crate) fn default_me_pool_drain_soft_evict_grace_secs() -> u64 {
+    DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_GRACE_SECS
+}
+
+pub(crate) fn default_me_pool_drain_soft_evict_per_writer() -> u8 {
+    DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_PER_WRITER
+}
+
+pub(crate) fn default_me_pool_drain_soft_evict_budget_per_core() -> u16 {
+    DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_BUDGET_PER_CORE
+}
+
+pub(crate) fn default_me_pool_drain_soft_evict_cooldown_ms() -> u64 {
+    DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_COOLDOWN_MS
 }
 
 pub(crate) fn default_me_bind_stale_ttl_secs() -> u64 {

src/config/hot_reload.rs

@@ -31,11 +31,10 @@ use notify::{EventKind, RecursiveMode, Watcher, recommended_watcher};
 use tokio::sync::{mpsc, watch};
 use tracing::{error, info, warn};
 
-use crate::config::{
-    LogLevel, MeBindStaleMode, MeFloorMode, MeSocksKdfPolicy, MeTelemetryLevel,
-    MeWriterPickMode,
-};
 use super::load::{LoadedConfig, ProxyConfig};
+use crate::config::{
+    LogLevel, MeBindStaleMode, MeFloorMode, MeSocksKdfPolicy, MeTelemetryLevel, MeWriterPickMode,
+};
 
 const HOT_RELOAD_DEBOUNCE: Duration = Duration::from_millis(50);
 
@@ -44,16 +43,17 @@ const HOT_RELOAD_DEBOUNCE: Duration = Duration::from_millis(50);
 /// 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 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 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,
@@ -106,18 +106,20 @@ pub struct HotFields {
     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_ad_tags:            std::collections::HashMap<String, String>,
-    pub user_max_tcp_conns:      std::collections::HashMap<String, usize>,
-    pub user_expirations:        std::collections::HashMap<String, chrono::DateTime<chrono::Utc>>,
-    pub user_data_quota:         std::collections::HashMap<String, u64>,
-    pub user_max_unique_ips:     std::collections::HashMap<String, usize>,
+    pub users: std::collections::HashMap<String, String>,
+    pub user_ad_tags: std::collections::HashMap<String, String>,
+    pub user_max_tcp_conns: std::collections::HashMap<String, usize>,
+    pub user_expirations: std::collections::HashMap<String, chrono::DateTime<chrono::Utc>>,
+    pub user_data_quota: std::collections::HashMap<String, u64>,
+    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,
@@ -126,16 +128,17 @@ pub struct HotFields {
 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,
+            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,
+            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,
@@ -187,15 +190,11 @@ impl HotFields {
             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_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_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,
@@ -214,26 +213,36 @@ impl HotFields {
             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_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_ad_tags:            cfg.access.user_ad_tags.clone(),
-            user_max_tcp_conns:      cfg.access.user_max_tcp_conns.clone(),
-            user_expirations:        cfg.access.user_expirations.clone(),
-            user_data_quota:         cfg.access.user_data_quota.clone(),
-            user_max_unique_ips:     cfg.access.user_max_unique_ips.clone(),
+            users: cfg.access.users.clone(),
+            user_ad_tags: cfg.access.user_ad_tags.clone(),
+            user_max_tcp_conns: cfg.access.user_max_tcp_conns.clone(),
+            user_expirations: cfg.access.user_expirations.clone(),
+            user_data_quota: cfg.access.user_data_quota.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,
@@ -332,7 +341,9 @@ struct ReloadState {
 
 impl ReloadState {
     fn new(applied_snapshot_hash: Option<u64>) -> Self {
-        Self { applied_snapshot_hash }
+        Self {
+            applied_snapshot_hash,
+        }
     }
 
     fn is_applied(&self, hash: u64) -> bool {
@@ -431,6 +442,7 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
     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;
@@ -478,10 +490,14 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
         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_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 =
@@ -501,6 +517,9 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
     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;
@@ -540,8 +559,7 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
         || 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_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
@@ -552,6 +570,7 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
     }
     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
@@ -563,6 +582,7 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
     }
     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_host != new.censorship.mask_host
         || old.censorship.mask_port != new.censorship.mask_port
@@ -576,6 +596,22 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
         || 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_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");
@@ -616,6 +652,9 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
     }
     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
@@ -634,9 +673,11 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
         warned = true;
         warn!("config reload: general.me_init_retry_attempts changed; restart required");
     }
-    if old.general.me2dc_fallback != new.general.me2dc_fallback {
+    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 changed; restart required");
+        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
@@ -655,6 +696,7 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
     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
@@ -805,6 +847,12 @@ fn log_changes(
             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!(
@@ -845,8 +893,7 @@ fn log_changes(
     {
         info!(
             "config reload: me_bind_stale: mode={:?} ttl={}s",
-            new_hot.me_bind_stale_mode,
-            new_hot.me_bind_stale_ttl_secs
+            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
@@ -926,8 +973,7 @@ fn log_changes(
     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,
+            old_hot.me_socks_kdf_policy, new_hot.me_socks_kdf_policy,
         );
     }
 
@@ -981,8 +1027,7 @@ fn log_changes(
         || old_hot.me_route_backpressure_high_watermark_pct
             != new_hot.me_route_backpressure_high_watermark_pct
         || 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_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
@@ -1004,34 +1049,47 @@ fn log_changes(
         || 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={} direct_buf_c2s={} direct_buf_s2c={}",
+            "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()
+        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()
+        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()
+        let mut changed: Vec<&String> = new_hot
+            .users
+            .keys()
             .filter(|u| {
-                old_hot.users.get(*u)
+                old_hot
+                    .users
+                    .get(*u)
                     .map(|s| s != &new_hot.users[*u])
                     .unwrap_or(false)
             })
@@ -1041,10 +1099,18 @@ fn log_changes(
         if !added.is_empty() {
             info!(
                 "config reload: users added: [{}]",
-                added.iter().map(|s| s.as_str()).collect::<Vec<_>>().join(", ")
+                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(new_cfg.server.port);
+            let port = new_cfg
+                .general
+                .links
+                .public_port
+                .unwrap_or(new_cfg.server.port);
             for user in &added {
                 if let Some(secret) = new_hot.users.get(*user) {
                     print_user_links(user, secret, &host, port, new_cfg);
@@ -1054,13 +1120,21 @@ fn log_changes(
         if !removed.is_empty() {
             info!(
                 "config reload: users removed: [{}]",
-                removed.iter().map(|s| s.as_str()).collect::<Vec<_>>().join(", ")
+                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(", ")
+                changed
+                    .iter()
+                    .map(|s| s.as_str())
+                    .collect::<Vec<_>>()
+                    .join(", ")
             );
         }
     }
@@ -1091,8 +1165,7 @@ fn log_changes(
     }
     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
+        || 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",
@@ -1127,7 +1200,10 @@ fn reload_config(
     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);
+        error!(
+            "config reload: validation failed: {}; keeping old config",
+            e
+        );
         return Some(next_manifest);
     }
 
@@ -1192,7 +1268,7 @@ pub fn spawn_config_watcher(
 ) -> (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 (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();
@@ -1209,25 +1285,29 @@ pub fn spawn_config_watcher(
 
         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
-            }
-        };
+        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,
@@ -1243,7 +1323,10 @@ pub fn spawn_config_watcher(
         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(_)) {
+                if !matches!(
+                    event.kind,
+                    EventKind::Modify(_) | EventKind::Create(_) | EventKind::Remove(_)
+                ) {
                     return;
                 }
                 let is_our_file = manifest_for_poll
@@ -1291,7 +1374,9 @@ pub fn spawn_config_watcher(
                 }
             }
             #[cfg(not(unix))]
-            if notify_rx.recv().await.is_none() { break; }
+            if notify_rx.recv().await.is_none() {
+                break;
+            }
 
             // Debounce: drain extra events that arrive within a short quiet window.
             tokio::time::sleep(HOT_RELOAD_DEBOUNCE).await;
@@ -1393,7 +1478,10 @@ mod tests {
         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!(
+            HotFields::from_config(&old),
+            HotFields::from_config(&applied)
+        );
         assert_eq!(applied.server.port, old.server.port);
     }
 
@@ -1412,7 +1500,10 @@ mod tests {
             applied.general.me_bind_stale_mode,
             new.general.me_bind_stale_mode
         );
-        assert_ne!(HotFields::from_config(&old), HotFields::from_config(&applied));
+        assert_ne!(
+            HotFields::from_config(&old),
+            HotFields::from_config(&applied)
+        );
     }
 
     #[test]
@@ -1426,7 +1517,10 @@ mod tests {
             applied.general.me_keepalive_interval_secs,
             old.general.me_keepalive_interval_secs
         );
-        assert_eq!(HotFields::from_config(&old), HotFields::from_config(&applied));
+        assert_eq!(
+            HotFields::from_config(&old),
+            HotFields::from_config(&applied)
+        );
     }
 
     #[test]
@@ -1438,7 +1532,10 @@ mod tests {
 
         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_eq!(
+            applied.general.use_middle_proxy,
+            old.general.use_middle_proxy
+        );
         assert!(!config_equal(&applied, &new));
     }
 
@@ -1450,14 +1547,19 @@ mod tests {
 
         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 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));
+        assert_eq!(
+            config_tx.borrow().general.ad_tag.as_deref(),
+            Some(final_tag)
+        );
 
         let _ = std::fs::remove_file(path);
     }
@@ -1470,7 +1572,9 @@ mod tests {
 
         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 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));
@@ -1493,7 +1597,9 @@ mod tests {
 
         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 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));
@@ -1507,7 +1613,10 @@ mod tests {
 
         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));
+        assert_eq!(
+            config_tx.borrow().general.ad_tag.as_deref(),
+            Some(final_tag)
+        );
 
         let _ = std::fs::remove_file(path);
     }

src/config/mod.rs

@@ -1,9 +1,9 @@
 //! Configuration.
 
 pub(crate) mod defaults;
-mod types;
-mod load;
 pub mod hot_reload;
+mod load;
+mod types;
 
 pub use load::ProxyConfig;
 pub use types::*;

src/config/tests/load_idle_policy_tests.rs

@@ -0,0 +1,102 @@
+use super::*;
+use std::fs;
+use std::path::PathBuf;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+fn write_temp_config(contents: &str) -> PathBuf {
+    let nonce = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .expect("system time must be after unix epoch")
+        .as_nanos();
+    let path = std::env::temp_dir().join(format!("telemt-idle-policy-{nonce}.toml"));
+    fs::write(&path, contents).expect("temp config write must succeed");
+    path
+}
+
+fn remove_temp_config(path: &PathBuf) {
+    let _ = fs::remove_file(path);
+}
+
+#[test]
+fn default_timeouts_enable_apple_compatible_handshake_profile() {
+    let cfg = ProxyConfig::default();
+    assert_eq!(cfg.timeouts.client_first_byte_idle_secs, 300);
+    assert_eq!(cfg.timeouts.client_handshake, 60);
+}
+
+#[test]
+fn load_accepts_zero_first_byte_idle_timeout_as_legacy_opt_out() {
+    let path = write_temp_config(
+        r#"
+[timeouts]
+client_first_byte_idle_secs = 0
+"#,
+    );
+
+    let cfg = ProxyConfig::load(&path).expect("config with zero first-byte idle timeout must load");
+    assert_eq!(cfg.timeouts.client_first_byte_idle_secs, 0);
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_relay_hard_idle_smaller_than_soft_idle_with_clear_error() {
+    let path = write_temp_config(
+        r#"
+[timeouts]
+relay_client_idle_soft_secs = 120
+relay_client_idle_hard_secs = 60
+"#,
+    );
+
+    let err = ProxyConfig::load(&path).expect_err("config with hard<soft must fail");
+    let msg = err.to_string();
+    assert!(
+        msg.contains(
+            "timeouts.relay_client_idle_hard_secs must be >= timeouts.relay_client_idle_soft_secs"
+        ),
+        "error must explain the violated hard>=soft invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_relay_grace_larger_than_hard_idle_with_clear_error() {
+    let path = write_temp_config(
+        r#"
+[timeouts]
+relay_client_idle_soft_secs = 60
+relay_client_idle_hard_secs = 120
+relay_idle_grace_after_downstream_activity_secs = 121
+"#,
+    );
+
+    let err = ProxyConfig::load(&path).expect_err("config with grace>hard must fail");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("timeouts.relay_idle_grace_after_downstream_activity_secs must be <= timeouts.relay_client_idle_hard_secs"),
+        "error must explain the violated grace<=hard invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_zero_handshake_timeout_with_clear_error() {
+    let path = write_temp_config(
+        r#"
+[timeouts]
+client_handshake = 0
+"#,
+    );
+
+    let err = ProxyConfig::load(&path).expect_err("config with zero handshake timeout must fail");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("timeouts.client_handshake must be > 0"),
+        "error must explain that handshake timeout must be positive, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}

src/config/tests/load_mask_classifier_prefetch_timeout_security_tests.rs

@@ -0,0 +1,76 @@
+use super::*;
+use std::fs;
+use std::path::PathBuf;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+fn write_temp_config(contents: &str) -> PathBuf {
+    let nonce = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .expect("system time must be after unix epoch")
+        .as_nanos();
+    let path = std::env::temp_dir().join(format!(
+        "telemt-load-mask-prefetch-timeout-security-{nonce}.toml"
+    ));
+    fs::write(&path, contents).expect("temp config write must succeed");
+    path
+}
+
+fn remove_temp_config(path: &PathBuf) {
+    let _ = fs::remove_file(path);
+}
+
+#[test]
+fn load_rejects_mask_classifier_prefetch_timeout_below_min_bound() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_classifier_prefetch_timeout_ms = 4
+"#,
+    );
+
+    let err = ProxyConfig::load(&path)
+        .expect_err("prefetch timeout below minimum security bound must be rejected");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("censorship.mask_classifier_prefetch_timeout_ms must be within [5, 50]"),
+        "error must explain timeout bound invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_mask_classifier_prefetch_timeout_above_max_bound() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_classifier_prefetch_timeout_ms = 51
+"#,
+    );
+
+    let err = ProxyConfig::load(&path)
+        .expect_err("prefetch timeout above max security bound must be rejected");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("censorship.mask_classifier_prefetch_timeout_ms must be within [5, 50]"),
+        "error must explain timeout bound invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_accepts_mask_classifier_prefetch_timeout_within_bounds() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_classifier_prefetch_timeout_ms = 20
+"#,
+    );
+
+    let cfg =
+        ProxyConfig::load(&path).expect("prefetch timeout within security bounds must be accepted");
+    assert_eq!(cfg.censorship.mask_classifier_prefetch_timeout_ms, 20);
+
+    remove_temp_config(&path);
+}

src/config/tests/load_mask_shape_security_tests.rs

@@ -0,0 +1,292 @@
+use super::*;
+use std::fs;
+use std::path::PathBuf;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+fn write_temp_config(contents: &str) -> PathBuf {
+    let nonce = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .expect("system time must be after unix epoch")
+        .as_nanos();
+    let path = std::env::temp_dir().join(format!("telemt-load-mask-shape-security-{nonce}.toml"));
+    fs::write(&path, contents).expect("temp config write must succeed");
+    path
+}
+
+fn remove_temp_config(path: &PathBuf) {
+    let _ = fs::remove_file(path);
+}
+
+#[test]
+fn load_rejects_zero_mask_shape_bucket_floor_bytes() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_shape_bucket_floor_bytes = 0
+mask_shape_bucket_cap_bytes = 4096
+"#,
+    );
+
+    let err =
+        ProxyConfig::load(&path).expect_err("zero mask_shape_bucket_floor_bytes must be rejected");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("censorship.mask_shape_bucket_floor_bytes must be > 0"),
+        "error must explain floor>0 invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_mask_shape_bucket_cap_less_than_floor() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_shape_bucket_floor_bytes = 1024
+mask_shape_bucket_cap_bytes = 512
+"#,
+    );
+
+    let err =
+        ProxyConfig::load(&path).expect_err("mask_shape_bucket_cap_bytes < floor must be rejected");
+    let msg = err.to_string();
+    assert!(
+        msg.contains(
+            "censorship.mask_shape_bucket_cap_bytes must be >= censorship.mask_shape_bucket_floor_bytes"
+        ),
+        "error must explain cap>=floor invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_accepts_mask_shape_bucket_cap_equal_to_floor() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_shape_hardening = true
+mask_shape_bucket_floor_bytes = 1024
+mask_shape_bucket_cap_bytes = 1024
+"#,
+    );
+
+    let cfg = ProxyConfig::load(&path).expect("equal cap and floor must be accepted");
+    assert!(cfg.censorship.mask_shape_hardening);
+    assert_eq!(cfg.censorship.mask_shape_bucket_floor_bytes, 1024);
+    assert_eq!(cfg.censorship.mask_shape_bucket_cap_bytes, 1024);
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_above_cap_blur_when_shape_hardening_disabled() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_shape_hardening = false
+mask_shape_above_cap_blur = true
+mask_shape_above_cap_blur_max_bytes = 64
+"#,
+    );
+
+    let err =
+        ProxyConfig::load(&path).expect_err("above-cap blur must require shape hardening enabled");
+    let msg = err.to_string();
+    assert!(
+        msg.contains(
+            "censorship.mask_shape_above_cap_blur requires censorship.mask_shape_hardening = true"
+        ),
+        "error must explain blur prerequisite, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_above_cap_blur_with_zero_max_bytes() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_shape_hardening = true
+mask_shape_above_cap_blur = true
+mask_shape_above_cap_blur_max_bytes = 0
+"#,
+    );
+
+    let err =
+        ProxyConfig::load(&path).expect_err("above-cap blur max bytes must be > 0 when enabled");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("censorship.mask_shape_above_cap_blur_max_bytes must be > 0 when censorship.mask_shape_above_cap_blur is enabled"),
+        "error must explain blur max bytes invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_timing_normalization_floor_zero_when_enabled() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_timing_normalization_enabled = true
+mask_timing_normalization_floor_ms = 0
+mask_timing_normalization_ceiling_ms = 200
+"#,
+    );
+
+    let err =
+        ProxyConfig::load(&path).expect_err("timing normalization floor must be > 0 when enabled");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("censorship.mask_timing_normalization_floor_ms must be > 0 when censorship.mask_timing_normalization_enabled is true"),
+        "error must explain timing floor invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_timing_normalization_ceiling_below_floor() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_timing_normalization_enabled = true
+mask_timing_normalization_floor_ms = 220
+mask_timing_normalization_ceiling_ms = 200
+"#,
+    );
+
+    let err = ProxyConfig::load(&path).expect_err("timing normalization ceiling must be >= floor");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("censorship.mask_timing_normalization_ceiling_ms must be >= censorship.mask_timing_normalization_floor_ms"),
+        "error must explain timing ceiling/floor invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_accepts_valid_timing_normalization_and_above_cap_blur_config() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_shape_hardening = true
+mask_shape_above_cap_blur = true
+mask_shape_above_cap_blur_max_bytes = 128
+mask_timing_normalization_enabled = true
+mask_timing_normalization_floor_ms = 150
+mask_timing_normalization_ceiling_ms = 240
+"#,
+    );
+
+    let cfg = ProxyConfig::load(&path)
+        .expect("valid blur and timing normalization settings must be accepted");
+    assert!(cfg.censorship.mask_shape_hardening);
+    assert!(cfg.censorship.mask_shape_above_cap_blur);
+    assert_eq!(cfg.censorship.mask_shape_above_cap_blur_max_bytes, 128);
+    assert!(cfg.censorship.mask_timing_normalization_enabled);
+    assert_eq!(cfg.censorship.mask_timing_normalization_floor_ms, 150);
+    assert_eq!(cfg.censorship.mask_timing_normalization_ceiling_ms, 240);
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_aggressive_shape_mode_when_shape_hardening_disabled() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_shape_hardening = false
+mask_shape_hardening_aggressive_mode = true
+"#,
+    );
+
+    let err = ProxyConfig::load(&path)
+        .expect_err("aggressive shape hardening mode must require shape hardening enabled");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("censorship.mask_shape_hardening_aggressive_mode requires censorship.mask_shape_hardening = true"),
+        "error must explain aggressive-mode prerequisite, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_accepts_aggressive_shape_mode_when_shape_hardening_enabled() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_shape_hardening = true
+mask_shape_hardening_aggressive_mode = true
+mask_shape_above_cap_blur = true
+mask_shape_above_cap_blur_max_bytes = 8
+"#,
+    );
+
+    let cfg = ProxyConfig::load(&path)
+        .expect("aggressive shape hardening mode should be accepted when prerequisites are met");
+    assert!(cfg.censorship.mask_shape_hardening);
+    assert!(cfg.censorship.mask_shape_hardening_aggressive_mode);
+    assert!(cfg.censorship.mask_shape_above_cap_blur);
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_zero_mask_relay_max_bytes() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_relay_max_bytes = 0
+"#,
+    );
+
+    let err = ProxyConfig::load(&path).expect_err("mask_relay_max_bytes must be > 0");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("censorship.mask_relay_max_bytes must be > 0"),
+        "error must explain non-zero relay cap invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_mask_relay_max_bytes_above_upper_bound() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_relay_max_bytes = 67108865
+"#,
+    );
+
+    let err =
+        ProxyConfig::load(&path).expect_err("mask_relay_max_bytes above hard cap must be rejected");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("censorship.mask_relay_max_bytes must be <= 67108864"),
+        "error must explain relay cap upper bound invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_accepts_valid_mask_relay_max_bytes() {
+    let path = write_temp_config(
+        r#"
+[censorship]
+mask_relay_max_bytes = 8388608
+"#,
+    );
+
+    let cfg = ProxyConfig::load(&path).expect("valid mask_relay_max_bytes must be accepted");
+    assert_eq!(cfg.censorship.mask_relay_max_bytes, 8_388_608);
+
+    remove_temp_config(&path);
+}

src/config/tests/load_security_tests.rs

@@ -0,0 +1,88 @@
+use super::*;
+use std::fs;
+use std::path::PathBuf;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+fn write_temp_config(contents: &str) -> PathBuf {
+    let nonce = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .expect("system time must be after unix epoch")
+        .as_nanos();
+    let path = std::env::temp_dir().join(format!("telemt-load-security-{nonce}.toml"));
+    fs::write(&path, contents).expect("temp config write must succeed");
+    path
+}
+
+fn remove_temp_config(path: &PathBuf) {
+    let _ = fs::remove_file(path);
+}
+
+#[test]
+fn load_rejects_server_hello_delay_equal_to_handshake_timeout_budget() {
+    let path = write_temp_config(
+        r#"
+[timeouts]
+client_handshake = 1
+
+[censorship]
+server_hello_delay_max_ms = 1000
+"#,
+    );
+
+    let err =
+        ProxyConfig::load(&path).expect_err("delay equal to handshake timeout must be rejected");
+    let msg = err.to_string();
+    assert!(
+        msg.contains(
+            "censorship.server_hello_delay_max_ms must be < timeouts.client_handshake * 1000"
+        ),
+        "error must explain delay<timeout invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_rejects_server_hello_delay_larger_than_handshake_timeout_budget() {
+    let path = write_temp_config(
+        r#"
+[timeouts]
+client_handshake = 1
+
+[censorship]
+server_hello_delay_max_ms = 1500
+"#,
+    );
+
+    let err =
+        ProxyConfig::load(&path).expect_err("delay larger than handshake timeout must be rejected");
+    let msg = err.to_string();
+    assert!(
+        msg.contains(
+            "censorship.server_hello_delay_max_ms must be < timeouts.client_handshake * 1000"
+        ),
+        "error must explain delay<timeout invariant, got: {msg}"
+    );
+
+    remove_temp_config(&path);
+}
+
+#[test]
+fn load_accepts_server_hello_delay_strictly_below_handshake_timeout_budget() {
+    let path = write_temp_config(
+        r#"
+[timeouts]
+client_handshake = 1
+
+[censorship]
+server_hello_delay_max_ms = 999
+"#,
+    );
+
+    let cfg =
+        ProxyConfig::load(&path).expect("delay below handshake timeout budget must be accepted");
+    assert_eq!(cfg.timeouts.client_handshake, 1);
+    assert_eq!(cfg.censorship.server_hello_delay_max_ms, 999);
+
+    remove_temp_config(&path);
+}

src/config/types.rs

@@ -135,8 +135,8 @@ impl MeSocksKdfPolicy {
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
 #[serde(rename_all = "lowercase")]
 pub enum MeBindStaleMode {
-    Never,
     #[default]
+    Never,
     Ttl,
     Always,
 }
@@ -429,6 +429,11 @@ pub struct GeneralConfig {
     #[serde(default = "default_me2dc_fallback")]
     pub me2dc_fallback: bool,
 
+    /// Fast ME->Direct fallback mode for new sessions.
+    /// Active only when both `use_middle_proxy=true` and `me2dc_fallback=true`.
+    #[serde(default = "default_me2dc_fast")]
+    pub me2dc_fast: bool,
+
     /// Enable ME keepalive padding frames.
     #[serde(default = "default_true")]
     pub me_keepalive_enabled: bool,
@@ -462,8 +467,13 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_c2me_channel_capacity")]
     pub me_c2me_channel_capacity: usize,
 
+    /// Maximum wait in milliseconds for enqueueing C2ME commands when the queue is full.
+    /// `0` keeps legacy unbounded wait behavior.
+    #[serde(default = "default_me_c2me_send_timeout_ms")]
+    pub me_c2me_send_timeout_ms: u64,
+
     /// Bounded wait in milliseconds for routing ME DATA to per-connection queue.
-    /// `0` keeps legacy no-wait behavior.
+    /// `0` keeps non-blocking routing; values >0 enable bounded wait for compatibility.
     #[serde(default = "default_me_reader_route_data_wait_ms")]
     pub me_reader_route_data_wait_ms: u64,
 
@@ -484,6 +494,14 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_d2c_ack_flush_immediate")]
     pub me_d2c_ack_flush_immediate: bool,
 
+    /// Additional bytes above strict per-user quota allowed in hot-path soft mode.
+    #[serde(default = "default_me_quota_soft_overshoot_bytes")]
+    pub me_quota_soft_overshoot_bytes: u64,
+
+    /// Shrink threshold for reusable ME->Client frame assembly buffer.
+    #[serde(default = "default_me_d2c_frame_buf_shrink_threshold_bytes")]
+    pub me_d2c_frame_buf_shrink_threshold_bytes: usize,
+
     /// Copy buffer size for client->DC direction in direct relay.
     #[serde(default = "default_direct_relay_copy_buf_c2s_bytes")]
     pub direct_relay_copy_buf_c2s_bytes: usize,
@@ -645,6 +663,10 @@ pub struct GeneralConfig {
     #[serde(default = "default_upstream_connect_budget_ms")]
     pub upstream_connect_budget_ms: u64,
 
+    /// Per-attempt TCP connect timeout to Telegram DC (seconds).
+    #[serde(default = "default_connect_timeout")]
+    pub tg_connect: u64,
+
     /// Consecutive failed requests before upstream is marked unhealthy.
     #[serde(default = "default_upstream_unhealthy_fail_threshold")]
     pub upstream_unhealthy_fail_threshold: u32,
@@ -716,6 +738,15 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_route_no_writer_wait_ms")]
     pub me_route_no_writer_wait_ms: u64,
 
+    /// Maximum cumulative wait in milliseconds for hybrid no-writer mode before failfast.
+    #[serde(default = "default_me_route_hybrid_max_wait_ms")]
+    pub me_route_hybrid_max_wait_ms: u64,
+
+    /// Maximum wait in milliseconds for blocking ME writer channel send fallback.
+    /// `0` keeps legacy unbounded wait behavior.
+    #[serde(default = "default_me_route_blocking_send_timeout_ms")]
+    pub me_route_blocking_send_timeout_ms: u64,
+
     /// Number of inline recovery attempts in legacy mode.
     #[serde(default = "default_me_route_inline_recovery_attempts")]
     pub me_route_inline_recovery_attempts: u32,
@@ -798,11 +829,35 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_pool_drain_ttl_secs")]
     pub me_pool_drain_ttl_secs: u64,
 
+    /// Force-remove any draining writer on the next cleanup tick, regardless of age/deadline.
+    #[serde(default = "default_me_instadrain")]
+    pub me_instadrain: bool,
+
     /// Maximum allowed number of draining ME writers before oldest ones are force-closed in batches.
     /// Set to 0 to disable threshold-based draining cleanup and keep timeout-only behavior.
     #[serde(default = "default_me_pool_drain_threshold")]
     pub me_pool_drain_threshold: u64,
 
+    /// Enable staged client eviction for draining ME writers that remain non-empty past TTL.
+    #[serde(default = "default_me_pool_drain_soft_evict_enabled")]
+    pub me_pool_drain_soft_evict_enabled: bool,
+
+    /// Extra grace in seconds after drain TTL before soft-eviction stage starts.
+    #[serde(default = "default_me_pool_drain_soft_evict_grace_secs")]
+    pub me_pool_drain_soft_evict_grace_secs: u64,
+
+    /// Maximum number of client sessions to evict from one draining writer per health tick.
+    #[serde(default = "default_me_pool_drain_soft_evict_per_writer")]
+    pub me_pool_drain_soft_evict_per_writer: u8,
+
+    /// Soft-eviction budget per CPU core for one health tick.
+    #[serde(default = "default_me_pool_drain_soft_evict_budget_per_core")]
+    pub me_pool_drain_soft_evict_budget_per_core: u16,
+
+    /// Cooldown for repetitive soft-eviction on the same writer in milliseconds.
+    #[serde(default = "default_me_pool_drain_soft_evict_cooldown_ms")]
+    pub me_pool_drain_soft_evict_cooldown_ms: u64,
+
     /// Policy for new binds on stale draining writers.
     #[serde(default)]
     pub me_bind_stale_mode: MeBindStaleMode,
@@ -817,7 +872,7 @@ pub struct GeneralConfig {
     pub me_pool_min_fresh_ratio: f32,
 
     /// Drain timeout in seconds for stale ME writers after endpoint map changes.
-    /// Set to 0 to keep stale writers draining indefinitely (no force-close).
+    /// Set to 0 to use the runtime safety fallback timeout.
     #[serde(default = "default_me_reinit_drain_timeout_secs")]
     pub me_reinit_drain_timeout_secs: u64,
 
@@ -893,6 +948,7 @@ impl Default for GeneralConfig {
             middle_proxy_warm_standby: default_middle_proxy_warm_standby(),
             me_init_retry_attempts: default_me_init_retry_attempts(),
             me2dc_fallback: default_me2dc_fallback(),
+            me2dc_fast: default_me2dc_fast(),
             me_keepalive_enabled: default_true(),
             me_keepalive_interval_secs: default_keepalive_interval(),
             me_keepalive_jitter_secs: default_keepalive_jitter(),
@@ -901,11 +957,15 @@ impl Default for GeneralConfig {
             me_writer_cmd_channel_capacity: default_me_writer_cmd_channel_capacity(),
             me_route_channel_capacity: default_me_route_channel_capacity(),
             me_c2me_channel_capacity: default_me_c2me_channel_capacity(),
+            me_c2me_send_timeout_ms: default_me_c2me_send_timeout_ms(),
             me_reader_route_data_wait_ms: default_me_reader_route_data_wait_ms(),
             me_d2c_flush_batch_max_frames: default_me_d2c_flush_batch_max_frames(),
             me_d2c_flush_batch_max_bytes: default_me_d2c_flush_batch_max_bytes(),
             me_d2c_flush_batch_max_delay_us: default_me_d2c_flush_batch_max_delay_us(),
             me_d2c_ack_flush_immediate: default_me_d2c_ack_flush_immediate(),
+            me_quota_soft_overshoot_bytes: default_me_quota_soft_overshoot_bytes(),
+            me_d2c_frame_buf_shrink_threshold_bytes:
+                default_me_d2c_frame_buf_shrink_threshold_bytes(),
             direct_relay_copy_buf_c2s_bytes: default_direct_relay_copy_buf_c2s_bytes(),
             direct_relay_copy_buf_s2c_bytes: default_direct_relay_copy_buf_s2c_bytes(),
             me_warmup_stagger_enabled: default_true(),
@@ -916,27 +976,42 @@ impl Default for GeneralConfig {
             me_reconnect_backoff_cap_ms: default_reconnect_backoff_cap_ms(),
             me_reconnect_fast_retry_count: default_me_reconnect_fast_retry_count(),
             me_single_endpoint_shadow_writers: default_me_single_endpoint_shadow_writers(),
-            me_single_endpoint_outage_mode_enabled: default_me_single_endpoint_outage_mode_enabled(),
-            me_single_endpoint_outage_disable_quarantine: default_me_single_endpoint_outage_disable_quarantine(),
-            me_single_endpoint_outage_backoff_min_ms: default_me_single_endpoint_outage_backoff_min_ms(),
-            me_single_endpoint_outage_backoff_max_ms: default_me_single_endpoint_outage_backoff_max_ms(),
-            me_single_endpoint_shadow_rotate_every_secs: default_me_single_endpoint_shadow_rotate_every_secs(),
+            me_single_endpoint_outage_mode_enabled: default_me_single_endpoint_outage_mode_enabled(
+            ),
+            me_single_endpoint_outage_disable_quarantine:
+                default_me_single_endpoint_outage_disable_quarantine(),
+            me_single_endpoint_outage_backoff_min_ms:
+                default_me_single_endpoint_outage_backoff_min_ms(),
+            me_single_endpoint_outage_backoff_max_ms:
+                default_me_single_endpoint_outage_backoff_max_ms(),
+            me_single_endpoint_shadow_rotate_every_secs:
+                default_me_single_endpoint_shadow_rotate_every_secs(),
             me_floor_mode: MeFloorMode::default(),
             me_adaptive_floor_idle_secs: default_me_adaptive_floor_idle_secs(),
-            me_adaptive_floor_min_writers_single_endpoint: default_me_adaptive_floor_min_writers_single_endpoint(),
-            me_adaptive_floor_min_writers_multi_endpoint: default_me_adaptive_floor_min_writers_multi_endpoint(),
+            me_adaptive_floor_min_writers_single_endpoint:
+                default_me_adaptive_floor_min_writers_single_endpoint(),
+            me_adaptive_floor_min_writers_multi_endpoint:
+                default_me_adaptive_floor_min_writers_multi_endpoint(),
             me_adaptive_floor_recover_grace_secs: default_me_adaptive_floor_recover_grace_secs(),
-            me_adaptive_floor_writers_per_core_total: default_me_adaptive_floor_writers_per_core_total(),
+            me_adaptive_floor_writers_per_core_total:
+                default_me_adaptive_floor_writers_per_core_total(),
             me_adaptive_floor_cpu_cores_override: default_me_adaptive_floor_cpu_cores_override(),
-            me_adaptive_floor_max_extra_writers_single_per_core: default_me_adaptive_floor_max_extra_writers_single_per_core(),
-            me_adaptive_floor_max_extra_writers_multi_per_core: default_me_adaptive_floor_max_extra_writers_multi_per_core(),
-            me_adaptive_floor_max_active_writers_per_core: default_me_adaptive_floor_max_active_writers_per_core(),
-            me_adaptive_floor_max_warm_writers_per_core: default_me_adaptive_floor_max_warm_writers_per_core(),
-            me_adaptive_floor_max_active_writers_global: default_me_adaptive_floor_max_active_writers_global(),
-            me_adaptive_floor_max_warm_writers_global: default_me_adaptive_floor_max_warm_writers_global(),
+            me_adaptive_floor_max_extra_writers_single_per_core:
+                default_me_adaptive_floor_max_extra_writers_single_per_core(),
+            me_adaptive_floor_max_extra_writers_multi_per_core:
+                default_me_adaptive_floor_max_extra_writers_multi_per_core(),
+            me_adaptive_floor_max_active_writers_per_core:
+                default_me_adaptive_floor_max_active_writers_per_core(),
+            me_adaptive_floor_max_warm_writers_per_core:
+                default_me_adaptive_floor_max_warm_writers_per_core(),
+            me_adaptive_floor_max_active_writers_global:
+                default_me_adaptive_floor_max_active_writers_global(),
+            me_adaptive_floor_max_warm_writers_global:
+                default_me_adaptive_floor_max_warm_writers_global(),
             upstream_connect_retry_attempts: default_upstream_connect_retry_attempts(),
             upstream_connect_retry_backoff_ms: default_upstream_connect_retry_backoff_ms(),
             upstream_connect_budget_ms: default_upstream_connect_budget_ms(),
+            tg_connect: default_connect_timeout(),
             upstream_unhealthy_fail_threshold: default_upstream_unhealthy_fail_threshold(),
             upstream_connect_failfast_hard_errors: default_upstream_connect_failfast_hard_errors(),
             stun_iface_mismatch_ignore: false,
@@ -948,13 +1023,16 @@ impl Default for GeneralConfig {
             me_socks_kdf_policy: MeSocksKdfPolicy::Strict,
             me_route_backpressure_base_timeout_ms: default_me_route_backpressure_base_timeout_ms(),
             me_route_backpressure_high_timeout_ms: default_me_route_backpressure_high_timeout_ms(),
-            me_route_backpressure_high_watermark_pct: default_me_route_backpressure_high_watermark_pct(),
+            me_route_backpressure_high_watermark_pct:
+                default_me_route_backpressure_high_watermark_pct(),
             me_health_interval_ms_unhealthy: default_me_health_interval_ms_unhealthy(),
             me_health_interval_ms_healthy: default_me_health_interval_ms_healthy(),
             me_admission_poll_ms: default_me_admission_poll_ms(),
             me_warn_rate_limit_ms: default_me_warn_rate_limit_ms(),
             me_route_no_writer_mode: MeRouteNoWriterMode::default(),
             me_route_no_writer_wait_ms: default_me_route_no_writer_wait_ms(),
+            me_route_hybrid_max_wait_ms: default_me_route_hybrid_max_wait_ms(),
+            me_route_blocking_send_timeout_ms: default_me_route_blocking_send_timeout_ms(),
             me_route_inline_recovery_attempts: default_me_route_inline_recovery_attempts(),
             me_route_inline_recovery_wait_ms: default_me_route_inline_recovery_wait_ms(),
             links: LinksConfig::default(),
@@ -972,7 +1050,8 @@ impl Default for GeneralConfig {
             me_hardswap_warmup_delay_min_ms: default_me_hardswap_warmup_delay_min_ms(),
             me_hardswap_warmup_delay_max_ms: default_me_hardswap_warmup_delay_max_ms(),
             me_hardswap_warmup_extra_passes: default_me_hardswap_warmup_extra_passes(),
-            me_hardswap_warmup_pass_backoff_base_ms: default_me_hardswap_warmup_pass_backoff_base_ms(),
+            me_hardswap_warmup_pass_backoff_base_ms:
+                default_me_hardswap_warmup_pass_backoff_base_ms(),
             me_config_stable_snapshots: default_me_config_stable_snapshots(),
             me_config_apply_cooldown_secs: default_me_config_apply_cooldown_secs(),
             me_snapshot_require_http_2xx: default_me_snapshot_require_http_2xx(),
@@ -983,7 +1062,14 @@ impl Default for GeneralConfig {
             me_secret_atomic_snapshot: default_me_secret_atomic_snapshot(),
             proxy_secret_len_max: default_proxy_secret_len_max(),
             me_pool_drain_ttl_secs: default_me_pool_drain_ttl_secs(),
+            me_instadrain: default_me_instadrain(),
             me_pool_drain_threshold: default_me_pool_drain_threshold(),
+            me_pool_drain_soft_evict_enabled: default_me_pool_drain_soft_evict_enabled(),
+            me_pool_drain_soft_evict_grace_secs: default_me_pool_drain_soft_evict_grace_secs(),
+            me_pool_drain_soft_evict_per_writer: default_me_pool_drain_soft_evict_per_writer(),
+            me_pool_drain_soft_evict_budget_per_core:
+                default_me_pool_drain_soft_evict_budget_per_core(),
+            me_pool_drain_soft_evict_cooldown_ms: default_me_pool_drain_soft_evict_cooldown_ms(),
             me_bind_stale_mode: MeBindStaleMode::default(),
             me_bind_stale_ttl_secs: default_me_bind_stale_ttl_secs(),
             me_pool_min_fresh_ratio: default_me_pool_min_fresh_ratio(),
@@ -1008,8 +1094,10 @@ impl GeneralConfig {
     /// Resolve the active updater interval for ME infrastructure refresh tasks.
     /// `update_every` has priority, otherwise legacy proxy_*_auto_reload_secs are used.
     pub fn effective_update_every_secs(&self) -> u64 {
-        self.update_every
-            .unwrap_or_else(|| self.proxy_secret_auto_reload_secs.min(self.proxy_config_auto_reload_secs))
+        self.update_every.unwrap_or_else(|| {
+            self.proxy_secret_auto_reload_secs
+                .min(self.proxy_config_auto_reload_secs)
+        })
     }
 
     /// Resolve periodic zero-downtime reinit interval for ME writers.
@@ -1019,8 +1107,13 @@ impl GeneralConfig {
 
     /// Resolve force-close timeout for stale writers.
     /// `me_reinit_drain_timeout_secs` remains backward-compatible alias.
+    /// A configured `0` uses the runtime safety fallback (300s).
     pub fn effective_me_pool_force_close_secs(&self) -> u64 {
-        self.me_reinit_drain_timeout_secs
+        if self.me_reinit_drain_timeout_secs == 0 {
+            300
+        } else {
+            self.me_reinit_drain_timeout_secs
+        }
     }
 }
 
@@ -1158,14 +1251,23 @@ pub struct ServerConfig {
 
     /// Trusted source CIDRs allowed to send incoming PROXY protocol headers.
     ///
-    /// When non-empty, connections from addresses outside this allowlist are
-    /// rejected before `src_addr` is applied.
-    #[serde(default)]
+    /// If this field is omitted in config, it defaults to trust-all CIDRs
+    /// (`0.0.0.0/0` and `::/0`). If it is explicitly set to an empty list,
+    /// all PROXY protocol headers are rejected.
+    #[serde(default = "default_proxy_protocol_trusted_cidrs")]
     pub proxy_protocol_trusted_cidrs: Vec<IpNetwork>,
 
+    /// Port for the Prometheus-compatible metrics endpoint.
+    /// Enables metrics when set; binds on all interfaces (dual-stack) by default.
     #[serde(default)]
     pub metrics_port: Option<u16>,
 
+    /// Listen address for metrics in `IP:PORT` format (e.g. `"127.0.0.1:9090"`).
+    /// When set, takes precedence over `metrics_port` and binds on the specified address only.
+    #[serde(default)]
+    pub metrics_listen: Option<String>,
+
+    /// CIDR whitelist for the metrics endpoint.
     #[serde(default = "default_metrics_whitelist")]
     pub metrics_whitelist: Vec<IpNetwork>,
 
@@ -1175,10 +1277,20 @@ pub struct ServerConfig {
     #[serde(default)]
     pub listeners: Vec<ListenerConfig>,
 
+    /// TCP `listen(2)` backlog for client-facing sockets (also used for the metrics HTTP listener).
+    /// The effective queue is capped by the kernel (for example `somaxconn` on Linux).
+    #[serde(default = "default_listen_backlog")]
+    pub listen_backlog: u32,
+
     /// Maximum number of concurrent client connections.
     /// 0 means unlimited.
     #[serde(default = "default_server_max_connections")]
     pub max_connections: u32,
+
+    /// Maximum wait in milliseconds while acquiring a connection slot permit.
+    /// `0` keeps legacy unbounded wait behavior.
+    #[serde(default = "default_accept_permit_timeout_ms")]
+    pub accept_permit_timeout_ms: u64,
 }
 
 impl Default for ServerConfig {
@@ -1192,23 +1304,47 @@ impl Default for ServerConfig {
             listen_tcp: None,
             proxy_protocol: false,
             proxy_protocol_header_timeout_ms: default_proxy_protocol_header_timeout_ms(),
-            proxy_protocol_trusted_cidrs: Vec::new(),
+            proxy_protocol_trusted_cidrs: default_proxy_protocol_trusted_cidrs(),
             metrics_port: None,
+            metrics_listen: None,
             metrics_whitelist: default_metrics_whitelist(),
             api: ApiConfig::default(),
             listeners: Vec::new(),
+            listen_backlog: default_listen_backlog(),
             max_connections: default_server_max_connections(),
+            accept_permit_timeout_ms: default_accept_permit_timeout_ms(),
         }
     }
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TimeoutsConfig {
+    /// Maximum idle wait in seconds for the first client byte before handshake parsing starts.
+    /// `0` disables the separate idle phase and keeps legacy timeout behavior.
+    #[serde(default = "default_client_first_byte_idle_secs")]
+    pub client_first_byte_idle_secs: u64,
+
+    /// Maximum active handshake duration in seconds after the first client byte is received.
     #[serde(default = "default_handshake_timeout")]
     pub client_handshake: u64,
 
-    #[serde(default = "default_connect_timeout")]
-    pub tg_connect: u64,
+    /// Enables soft/hard relay client idle policy for middle-relay sessions.
+    #[serde(default = "default_relay_idle_policy_v2_enabled")]
+    pub relay_idle_policy_v2_enabled: bool,
+
+    /// Soft idle threshold for middle-relay client uplink activity in seconds.
+    /// Hitting this threshold marks the session as idle-candidate, but does not close it.
+    #[serde(default = "default_relay_client_idle_soft_secs")]
+    pub relay_client_idle_soft_secs: u64,
+
+    /// Hard idle threshold for middle-relay client uplink activity in seconds.
+    /// Hitting this threshold closes the session.
+    #[serde(default = "default_relay_client_idle_hard_secs")]
+    pub relay_client_idle_hard_secs: u64,
+
+    /// Additional grace in seconds added to hard idle window after recent downstream activity.
+    #[serde(default = "default_relay_idle_grace_after_downstream_activity_secs")]
+    pub relay_idle_grace_after_downstream_activity_secs: u64,
 
     #[serde(default = "default_keepalive")]
     pub client_keepalive: u64,
@@ -1228,8 +1364,13 @@ pub struct TimeoutsConfig {
 impl Default for TimeoutsConfig {
     fn default() -> Self {
         Self {
+            client_first_byte_idle_secs: default_client_first_byte_idle_secs(),
             client_handshake: default_handshake_timeout(),
-            tg_connect: default_connect_timeout(),
+            relay_idle_policy_v2_enabled: default_relay_idle_policy_v2_enabled(),
+            relay_client_idle_soft_secs: default_relay_client_idle_soft_secs(),
+            relay_client_idle_hard_secs: default_relay_client_idle_hard_secs(),
+            relay_idle_grace_after_downstream_activity_secs:
+                default_relay_idle_grace_after_downstream_activity_secs(),
             client_keepalive: default_keepalive(),
             client_ack: default_ack_timeout(),
             me_one_retry: default_me_one_retry(),
@@ -1238,6 +1379,90 @@ impl Default for TimeoutsConfig {
     }
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum UnknownSniAction {
+    #[default]
+    Drop,
+    Mask,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TlsFetchProfile {
+    ModernChromeLike,
+    ModernFirefoxLike,
+    CompatTls12,
+    LegacyMinimal,
+}
+
+impl TlsFetchProfile {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            TlsFetchProfile::ModernChromeLike => "modern_chrome_like",
+            TlsFetchProfile::ModernFirefoxLike => "modern_firefox_like",
+            TlsFetchProfile::CompatTls12 => "compat_tls12",
+            TlsFetchProfile::LegacyMinimal => "legacy_minimal",
+        }
+    }
+}
+
+fn default_tls_fetch_profiles() -> Vec<TlsFetchProfile> {
+    vec![
+        TlsFetchProfile::ModernChromeLike,
+        TlsFetchProfile::ModernFirefoxLike,
+        TlsFetchProfile::CompatTls12,
+        TlsFetchProfile::LegacyMinimal,
+    ]
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TlsFetchConfig {
+    /// Ordered list of ClientHello profiles used for adaptive fallback.
+    #[serde(default = "default_tls_fetch_profiles")]
+    pub profiles: Vec<TlsFetchProfile>,
+
+    /// When true and upstream route is configured, TLS fetch fails closed on
+    /// upstream connect errors and does not fallback to direct TCP.
+    #[serde(default = "default_tls_fetch_strict_route")]
+    pub strict_route: bool,
+
+    /// Timeout per one profile attempt in milliseconds.
+    #[serde(default = "default_tls_fetch_attempt_timeout_ms")]
+    pub attempt_timeout_ms: u64,
+
+    /// Total wall-clock budget in milliseconds across all profile attempts.
+    #[serde(default = "default_tls_fetch_total_budget_ms")]
+    pub total_budget_ms: u64,
+
+    /// Adds GREASE-style values into selected ClientHello extensions.
+    #[serde(default)]
+    pub grease_enabled: bool,
+
+    /// Produces deterministic ClientHello randomness for debugging/tests.
+    #[serde(default)]
+    pub deterministic: bool,
+
+    /// TTL for winner-profile cache entries in seconds.
+    /// Set to 0 to disable profile cache.
+    #[serde(default = "default_tls_fetch_profile_cache_ttl_secs")]
+    pub profile_cache_ttl_secs: u64,
+}
+
+impl Default for TlsFetchConfig {
+    fn default() -> Self {
+        Self {
+            profiles: default_tls_fetch_profiles(),
+            strict_route: default_tls_fetch_strict_route(),
+            attempt_timeout_ms: default_tls_fetch_attempt_timeout_ms(),
+            total_budget_ms: default_tls_fetch_total_budget_ms(),
+            grease_enabled: false,
+            deterministic: false,
+            profile_cache_ttl_secs: default_tls_fetch_profile_cache_ttl_secs(),
+        }
+    }
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AntiCensorshipConfig {
     #[serde(default = "default_tls_domain")]
@@ -1247,6 +1472,19 @@ pub struct AntiCensorshipConfig {
     #[serde(default)]
     pub tls_domains: Vec<String>,
 
+    /// Policy for TLS ClientHello with unknown (non-configured) SNI.
+    #[serde(default)]
+    pub unknown_sni_action: UnknownSniAction,
+
+    /// Upstream scope used for TLS front metadata fetches.
+    /// Empty value keeps default upstream routing behavior.
+    #[serde(default = "default_tls_fetch_scope")]
+    pub tls_fetch_scope: String,
+
+    /// Fetch strategy for TLS front metadata bootstrap and periodic refresh.
+    #[serde(default)]
+    pub tls_fetch: TlsFetchConfig,
+
     #[serde(default = "default_true")]
     pub mask: bool,
 
@@ -1297,6 +1535,54 @@ pub struct AntiCensorshipConfig {
     /// Allows the backend to see the real client IP.
     #[serde(default)]
     pub mask_proxy_protocol: u8,
+
+    /// Enable shape-channel hardening on mask backend path by padding
+    /// client->mask stream tail to configured buckets on stream end.
+    #[serde(default = "default_mask_shape_hardening")]
+    pub mask_shape_hardening: bool,
+
+    /// Opt-in aggressive shape hardening mode.
+    /// When enabled, masking may shape some backend-silent timeout paths and
+    /// enforces strictly positive above-cap blur when blur is enabled.
+    #[serde(default = "default_mask_shape_hardening_aggressive_mode")]
+    pub mask_shape_hardening_aggressive_mode: bool,
+
+    /// Minimum bucket size for mask shape hardening padding.
+    #[serde(default = "default_mask_shape_bucket_floor_bytes")]
+    pub mask_shape_bucket_floor_bytes: usize,
+
+    /// Maximum bucket size for mask shape hardening padding.
+    #[serde(default = "default_mask_shape_bucket_cap_bytes")]
+    pub mask_shape_bucket_cap_bytes: usize,
+
+    /// Add bounded random tail bytes even when total bytes already exceed
+    /// mask_shape_bucket_cap_bytes.
+    #[serde(default = "default_mask_shape_above_cap_blur")]
+    pub mask_shape_above_cap_blur: bool,
+
+    /// Maximum random bytes appended above cap when above-cap blur is enabled.
+    #[serde(default = "default_mask_shape_above_cap_blur_max_bytes")]
+    pub mask_shape_above_cap_blur_max_bytes: usize,
+
+    /// Maximum bytes relayed per direction on unauthenticated masking fallback paths.
+    #[serde(default = "default_mask_relay_max_bytes")]
+    pub mask_relay_max_bytes: usize,
+
+    /// Prefetch timeout (ms) for extending fragmented masking classifier window.
+    #[serde(default = "default_mask_classifier_prefetch_timeout_ms")]
+    pub mask_classifier_prefetch_timeout_ms: u64,
+
+    /// Enable outcome-time normalization envelope for masking fallback.
+    #[serde(default = "default_mask_timing_normalization_enabled")]
+    pub mask_timing_normalization_enabled: bool,
+
+    /// Lower bound (ms) for masking outcome timing envelope.
+    #[serde(default = "default_mask_timing_normalization_floor_ms")]
+    pub mask_timing_normalization_floor_ms: u64,
+
+    /// Upper bound (ms) for masking outcome timing envelope.
+    #[serde(default = "default_mask_timing_normalization_ceiling_ms")]
+    pub mask_timing_normalization_ceiling_ms: u64,
 }
 
 impl Default for AntiCensorshipConfig {
@@ -1304,6 +1590,9 @@ impl Default for AntiCensorshipConfig {
         Self {
             tls_domain: default_tls_domain(),
             tls_domains: Vec::new(),
+            unknown_sni_action: UnknownSniAction::Drop,
+            tls_fetch_scope: default_tls_fetch_scope(),
+            tls_fetch: TlsFetchConfig::default(),
             mask: default_true(),
             mask_host: None,
             mask_port: default_mask_port(),
@@ -1317,6 +1606,17 @@ impl Default for AntiCensorshipConfig {
             tls_full_cert_ttl_secs: default_tls_full_cert_ttl_secs(),
             alpn_enforce: default_alpn_enforce(),
             mask_proxy_protocol: 0,
+            mask_shape_hardening: default_mask_shape_hardening(),
+            mask_shape_hardening_aggressive_mode: default_mask_shape_hardening_aggressive_mode(),
+            mask_shape_bucket_floor_bytes: default_mask_shape_bucket_floor_bytes(),
+            mask_shape_bucket_cap_bytes: default_mask_shape_bucket_cap_bytes(),
+            mask_shape_above_cap_blur: default_mask_shape_above_cap_blur(),
+            mask_shape_above_cap_blur_max_bytes: default_mask_shape_above_cap_blur_max_bytes(),
+            mask_relay_max_bytes: default_mask_relay_max_bytes(),
+            mask_classifier_prefetch_timeout_ms: default_mask_classifier_prefetch_timeout_ms(),
+            mask_timing_normalization_enabled: default_mask_timing_normalization_enabled(),
+            mask_timing_normalization_floor_ms: default_mask_timing_normalization_floor_ms(),
+            mask_timing_normalization_ceiling_ms: default_mask_timing_normalization_ceiling_ms(),
         }
     }
 }
@@ -1409,6 +1709,11 @@ pub enum UpstreamType {
         #[serde(default)]
         password: Option<String>,
     },
+    Shadowsocks {
+        url: String,
+        #[serde(default)]
+        interface: Option<String>,
+    },
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -1489,7 +1794,10 @@ impl ShowLink {
 }
 
 impl Serialize for ShowLink {
-    fn serialize<S: serde::Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
+    fn serialize<S: serde::Serializer>(
+        &self,
+        serializer: S,
+    ) -> std::result::Result<S::Ok, S::Error> {
         match self {
             ShowLink::None => Vec::<String>::new().serialize(serializer),
             ShowLink::All => serializer.serialize_str("*"),
@@ -1499,7 +1807,9 @@ impl Serialize for ShowLink {
 }
 
 impl<'de> Deserialize<'de> for ShowLink {
-    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
+    fn deserialize<D: serde::Deserializer<'de>>(
+        deserializer: D,
+    ) -> std::result::Result<Self, D::Error> {
         use serde::de;
 
         struct ShowLinkVisitor;
@@ -1515,14 +1825,14 @@ impl<'de> Deserialize<'de> for ShowLink {
                 if v == "*" {
                     Ok(ShowLink::All)
                 } else {
-                    Err(de::Error::invalid_value(
-                        de::Unexpected::Str(v),
-                        &r#""*""#,
-                    ))
+                    Err(de::Error::invalid_value(de::Unexpected::Str(v), &r#""*""#))
                 }
             }
 
-            fn visit_seq<A: de::SeqAccess<'de>>(self, mut seq: A) -> std::result::Result<ShowLink, A::Error> {
+            fn visit_seq<A: de::SeqAccess<'de>>(
+                self,
+                mut seq: A,
+            ) -> std::result::Result<ShowLink, A::Error> {
                 let mut names = Vec::new();
                 while let Some(name) = seq.next_element::<String>()? {
                     names.push(name);

src/crypto/aes.rs

@@ -13,10 +13,13 @@
 
 #![allow(dead_code)]
 
-use aes::Aes256;
-use ctr::{Ctr128BE, cipher::{KeyIvInit, StreamCipher}};
-use zeroize::Zeroize;
 use crate::error::{ProxyError, Result};
+use aes::Aes256;
+use ctr::{
+    Ctr128BE,
+    cipher::{KeyIvInit, StreamCipher},
+};
+use zeroize::Zeroize;
 
 type Aes256Ctr = Ctr128BE<Aes256>;
 
@@ -42,33 +45,39 @@ impl AesCtr {
             cipher: Aes256Ctr::new(key.into(), (&iv_bytes).into()),
         }
     }
-    
+
     /// Create from key and IV slices
     pub fn from_key_iv(key: &[u8], iv: &[u8]) -> Result<Self> {
         if key.len() != 32 {
-            return Err(ProxyError::InvalidKeyLength { expected: 32, got: key.len() });
+            return Err(ProxyError::InvalidKeyLength {
+                expected: 32,
+                got: key.len(),
+            });
         }
         if iv.len() != 16 {
-            return Err(ProxyError::InvalidKeyLength { expected: 16, got: iv.len() });
+            return Err(ProxyError::InvalidKeyLength {
+                expected: 16,
+                got: iv.len(),
+            });
         }
-        
+
         let key: [u8; 32] = key.try_into().unwrap();
         let iv = u128::from_be_bytes(iv.try_into().unwrap());
         Ok(Self::new(&key, iv))
     }
-    
+
     /// Encrypt/decrypt data in-place (CTR mode is symmetric)
     pub fn apply(&mut self, data: &mut [u8]) {
         self.cipher.apply_keystream(data);
     }
-    
+
     /// Encrypt data, returning new buffer
     pub fn encrypt(&mut self, data: &[u8]) -> Vec<u8> {
         let mut output = data.to_vec();
         self.apply(&mut output);
         output
     }
-    
+
     /// Decrypt data (for CTR, identical to encrypt)
     pub fn decrypt(&mut self, data: &[u8]) -> Vec<u8> {
         self.encrypt(data)
@@ -99,27 +108,33 @@ impl Drop for AesCbc {
 impl AesCbc {
     /// AES block size
     const BLOCK_SIZE: usize = 16;
-    
+
     /// Create new AES-CBC cipher with key and IV
     pub fn new(key: [u8; 32], iv: [u8; 16]) -> Self {
         Self { key, iv }
     }
-    
+
     /// Create from slices
     pub fn from_slices(key: &[u8], iv: &[u8]) -> Result<Self> {
         if key.len() != 32 {
-            return Err(ProxyError::InvalidKeyLength { expected: 32, got: key.len() });
+            return Err(ProxyError::InvalidKeyLength {
+                expected: 32,
+                got: key.len(),
+            });
         }
         if iv.len() != 16 {
-            return Err(ProxyError::InvalidKeyLength { expected: 16, got: iv.len() });
+            return Err(ProxyError::InvalidKeyLength {
+                expected: 16,
+                got: iv.len(),
+            });
         }
-        
+
         Ok(Self {
             key: key.try_into().unwrap(),
             iv: iv.try_into().unwrap(),
         })
     }
-    
+
     /// Encrypt a single block using raw AES (no chaining)
     fn encrypt_block(&self, block: &[u8; 16], key_schedule: &aes::Aes256) -> [u8; 16] {
         use aes::cipher::BlockEncrypt;
@@ -127,7 +142,7 @@ impl AesCbc {
         key_schedule.encrypt_block((&mut output).into());
         output
     }
-    
+
     /// Decrypt a single block using raw AES (no chaining)
     fn decrypt_block(&self, block: &[u8; 16], key_schedule: &aes::Aes256) -> [u8; 16] {
         use aes::cipher::BlockDecrypt;
@@ -135,7 +150,7 @@ impl AesCbc {
         key_schedule.decrypt_block((&mut output).into());
         output
     }
-    
+
     /// XOR two 16-byte blocks
     fn xor_blocks(a: &[u8; 16], b: &[u8; 16]) -> [u8; 16] {
         let mut result = [0u8; 16];
@@ -144,27 +159,28 @@ impl AesCbc {
         }
         result
     }
-    
+
     /// Encrypt data using CBC mode with proper chaining
     ///
     /// CBC Encryption: C[i] = AES_Encrypt(P[i] XOR C[i-1]), where C[-1] = IV
     pub fn encrypt(&self, data: &[u8]) -> Result<Vec<u8>> {
         if !data.len().is_multiple_of(Self::BLOCK_SIZE) {
-            return Err(ProxyError::Crypto(
-                format!("CBC data must be aligned to 16 bytes, got {}", data.len())
-            ));
+            return Err(ProxyError::Crypto(format!(
+                "CBC data must be aligned to 16 bytes, got {}",
+                data.len()
+            )));
         }
-        
+
         if data.is_empty() {
             return Ok(Vec::new());
         }
-        
+
         use aes::cipher::KeyInit;
         let key_schedule = aes::Aes256::new((&self.key).into());
-        
+
         let mut result = Vec::with_capacity(data.len());
         let mut prev_ciphertext = self.iv;
-        
+
         for chunk in data.chunks(Self::BLOCK_SIZE) {
             let plaintext: [u8; 16] = chunk.try_into().unwrap();
             let xored = Self::xor_blocks(&plaintext, &prev_ciphertext);
@@ -172,30 +188,31 @@ impl AesCbc {
             prev_ciphertext = ciphertext;
             result.extend_from_slice(&ciphertext);
         }
-        
+
         Ok(result)
     }
-    
+
     /// Decrypt data using CBC mode with proper chaining
     ///
     /// CBC Decryption: P[i] = AES_Decrypt(C[i]) XOR C[i-1], where C[-1] = IV
     pub fn decrypt(&self, data: &[u8]) -> Result<Vec<u8>> {
         if !data.len().is_multiple_of(Self::BLOCK_SIZE) {
-            return Err(ProxyError::Crypto(
-                format!("CBC data must be aligned to 16 bytes, got {}", data.len())
-            ));
+            return Err(ProxyError::Crypto(format!(
+                "CBC data must be aligned to 16 bytes, got {}",
+                data.len()
+            )));
         }
-        
+
         if data.is_empty() {
             return Ok(Vec::new());
         }
-        
+
         use aes::cipher::KeyInit;
         let key_schedule = aes::Aes256::new((&self.key).into());
-        
+
         let mut result = Vec::with_capacity(data.len());
         let mut prev_ciphertext = self.iv;
-        
+
         for chunk in data.chunks(Self::BLOCK_SIZE) {
             let ciphertext: [u8; 16] = chunk.try_into().unwrap();
             let decrypted = self.decrypt_block(&ciphertext, &key_schedule);
@@ -203,75 +220,77 @@ impl AesCbc {
             prev_ciphertext = ciphertext;
             result.extend_from_slice(&plaintext);
         }
-        
+
         Ok(result)
     }
-    
+
     /// Encrypt data in-place
     pub fn encrypt_in_place(&self, data: &mut [u8]) -> Result<()> {
         if !data.len().is_multiple_of(Self::BLOCK_SIZE) {
-            return Err(ProxyError::Crypto(
-                format!("CBC data must be aligned to 16 bytes, got {}", data.len())
-            ));
+            return Err(ProxyError::Crypto(format!(
+                "CBC data must be aligned to 16 bytes, got {}",
+                data.len()
+            )));
         }
-        
+
         if data.is_empty() {
             return Ok(());
         }
-        
+
         use aes::cipher::KeyInit;
         let key_schedule = aes::Aes256::new((&self.key).into());
-        
+
         let mut prev_ciphertext = self.iv;
-        
+
         for i in (0..data.len()).step_by(Self::BLOCK_SIZE) {
             let block = &mut data[i..i + Self::BLOCK_SIZE];
-            
+
             for j in 0..Self::BLOCK_SIZE {
                 block[j] ^= prev_ciphertext[j];
             }
-            
+
             let block_array: &mut [u8; 16] = block.try_into().unwrap();
             *block_array = self.encrypt_block(block_array, &key_schedule);
-            
+
             prev_ciphertext = *block_array;
         }
-        
+
         Ok(())
     }
-    
+
     /// Decrypt data in-place
     pub fn decrypt_in_place(&self, data: &mut [u8]) -> Result<()> {
         if !data.len().is_multiple_of(Self::BLOCK_SIZE) {
-            return Err(ProxyError::Crypto(
-                format!("CBC data must be aligned to 16 bytes, got {}", data.len())
-            ));
+            return Err(ProxyError::Crypto(format!(
+                "CBC data must be aligned to 16 bytes, got {}",
+                data.len()
+            )));
         }
-        
+
         if data.is_empty() {
             return Ok(());
         }
-        
+
         use aes::cipher::KeyInit;
         let key_schedule = aes::Aes256::new((&self.key).into());
-        
+
         let mut prev_ciphertext = self.iv;
-        
+
         for i in (0..data.len()).step_by(Self::BLOCK_SIZE) {
             let block = &mut data[i..i + Self::BLOCK_SIZE];
-            
+
             let current_ciphertext: [u8; 16] = block.try_into().unwrap();
-            
+
             let block_array: &mut [u8; 16] = block.try_into().unwrap();
             *block_array = self.decrypt_block(block_array, &key_schedule);
-            
+
             for j in 0..Self::BLOCK_SIZE {
                 block[j] ^= prev_ciphertext[j];
             }
-            
+
             prev_ciphertext = current_ciphertext;
         }
-        
+
         Ok(())
     }
 }
@@ -318,227 +337,227 @@ impl Decryptor for PassthroughEncryptor {
 #[cfg(test)]
 mod tests {
     use super::*;
-    
+
     // ============= AES-CTR Tests =============
-    
+
     #[test]
     fn test_aes_ctr_roundtrip() {
         let key = [0u8; 32];
         let iv = 12345u128;
-        
+
         let original = b"Hello, MTProto!";
-        
+
         let mut enc = AesCtr::new(&key, iv);
         let encrypted = enc.encrypt(original);
-        
+
         let mut dec = AesCtr::new(&key, iv);
         let decrypted = dec.decrypt(&encrypted);
-        
+
         assert_eq!(original.as_slice(), decrypted.as_slice());
     }
-    
+
     #[test]
     fn test_aes_ctr_in_place() {
         let key = [0x42u8; 32];
         let iv = 999u128;
-        
+
         let original = b"Test data for in-place encryption";
         let mut data = original.to_vec();
-        
+
         let mut cipher = AesCtr::new(&key, iv);
         cipher.apply(&mut data);
-        
+
         assert_ne!(&data[..], original);
-        
+
         let mut cipher = AesCtr::new(&key, iv);
         cipher.apply(&mut data);
-        
+
         assert_eq!(&data[..], original);
     }
-    
+
     // ============= AES-CBC Tests =============
-    
+
     #[test]
     fn test_aes_cbc_roundtrip() {
         let key = [0u8; 32];
         let iv = [0u8; 16];
-        
+
         let original = [0u8; 32];
-        
+
         let cipher = AesCbc::new(key, iv);
         let encrypted = cipher.encrypt(&original).unwrap();
         let decrypted = cipher.decrypt(&encrypted).unwrap();
-        
+
         assert_eq!(original.as_slice(), decrypted.as_slice());
     }
-    
+
     #[test]
     fn test_aes_cbc_chaining_works() {
         let key = [0x42u8; 32];
         let iv = [0x00u8; 16];
-        
+
         let plaintext = [0xAAu8; 32];
-        
+
         let cipher = AesCbc::new(key, iv);
         let ciphertext = cipher.encrypt(&plaintext).unwrap();
-        
+
         let block1 = &ciphertext[0..16];
         let block2 = &ciphertext[16..32];
-        
+
         assert_ne!(
             block1, block2,
             "CBC chaining broken: identical plaintext blocks produced identical ciphertext"
         );
     }
-    
+
     #[test]
     fn test_aes_cbc_known_vector() {
         let key = [0u8; 32];
         let iv = [0u8; 16];
         let plaintext = [0u8; 16];
-        
+
         let cipher = AesCbc::new(key, iv);
         let ciphertext = cipher.encrypt(&plaintext).unwrap();
-        
+
         let decrypted = cipher.decrypt(&ciphertext).unwrap();
         assert_eq!(plaintext.as_slice(), decrypted.as_slice());
-        
+
         assert_ne!(ciphertext.as_slice(), plaintext.as_slice());
     }
-    
+
     #[test]
     fn test_aes_cbc_multi_block() {
         let key = [0x12u8; 32];
         let iv = [0x34u8; 16];
-        
+
         let plaintext: Vec<u8> = (0..80).collect();
-        
+
         let cipher = AesCbc::new(key, iv);
         let ciphertext = cipher.encrypt(&plaintext).unwrap();
         let decrypted = cipher.decrypt(&ciphertext).unwrap();
-        
+
         assert_eq!(plaintext, decrypted);
     }
-    
+
     #[test]
     fn test_aes_cbc_in_place() {
         let key = [0x12u8; 32];
         let iv = [0x34u8; 16];
-        
+
         let original = [0x56u8; 48];
         let mut buffer = original;
-        
+
         let cipher = AesCbc::new(key, iv);
-        
+
         cipher.encrypt_in_place(&mut buffer).unwrap();
         assert_ne!(&buffer[..], &original[..]);
-        
+
         cipher.decrypt_in_place(&mut buffer).unwrap();
         assert_eq!(&buffer[..], &original[..]);
     }
-    
+
     #[test]
     fn test_aes_cbc_empty_data() {
         let cipher = AesCbc::new([0u8; 32], [0u8; 16]);
-        
+
         let encrypted = cipher.encrypt(&[]).unwrap();
         assert!(encrypted.is_empty());
-        
+
         let decrypted = cipher.decrypt(&[]).unwrap();
         assert!(decrypted.is_empty());
     }
-    
+
     #[test]
     fn test_aes_cbc_unaligned_error() {
         let cipher = AesCbc::new([0u8; 32], [0u8; 16]);
-        
+
         let result = cipher.encrypt(&[0u8; 15]);
         assert!(result.is_err());
-        
+
         let result = cipher.encrypt(&[0u8; 17]);
         assert!(result.is_err());
     }
-    
+
     #[test]
     fn test_aes_cbc_avalanche_effect() {
         let key = [0xAB; 32];
         let iv = [0xCD; 16];
-        
+
         let plaintext1 = [0u8; 32];
         let mut plaintext2 = [0u8; 32];
         plaintext2[0] = 0x01;
-        
+
         let cipher = AesCbc::new(key, iv);
-        
+
         let ciphertext1 = cipher.encrypt(&plaintext1).unwrap();
         let ciphertext2 = cipher.encrypt(&plaintext2).unwrap();
-        
+
         assert_ne!(&ciphertext1[0..16], &ciphertext2[0..16]);
         assert_ne!(&ciphertext1[16..32], &ciphertext2[16..32]);
     }
-    
+
     #[test]
     fn test_aes_cbc_iv_matters() {
         let key = [0x55; 32];
         let plaintext = [0x77u8; 16];
-        
+
         let cipher1 = AesCbc::new(key, [0u8; 16]);
         let cipher2 = AesCbc::new(key, [1u8; 16]);
-        
+
         let ciphertext1 = cipher1.encrypt(&plaintext).unwrap();
         let ciphertext2 = cipher2.encrypt(&plaintext).unwrap();
-        
+
         assert_ne!(ciphertext1, ciphertext2);
     }
-    
+
     #[test]
     fn test_aes_cbc_deterministic() {
         let key = [0x99; 32];
         let iv = [0x88; 16];
         let plaintext = [0x77u8; 32];
-        
+
         let cipher = AesCbc::new(key, iv);
-        
+
         let ciphertext1 = cipher.encrypt(&plaintext).unwrap();
         let ciphertext2 = cipher.encrypt(&plaintext).unwrap();
-        
+
         assert_eq!(ciphertext1, ciphertext2);
     }
-    
+
     // ============= Zeroize Tests =============
-    
+
     #[test]
     fn test_aes_cbc_zeroize_on_drop() {
         let key = [0xAA; 32];
         let iv = [0xBB; 16];
-        
+
         let cipher = AesCbc::new(key, iv);
         // Verify key/iv are set
         assert_eq!(cipher.key, [0xAA; 32]);
         assert_eq!(cipher.iv, [0xBB; 16]);
-        
+
         drop(cipher);
         // After drop, key/iv are zeroized (can't observe directly,
         // but the Drop impl runs without panic)
     }
-    
+
     // ============= Error Handling Tests =============
-    
+
     #[test]
     fn test_invalid_key_length() {
         let result = AesCtr::from_key_iv(&[0u8; 16], &[0u8; 16]);
         assert!(result.is_err());
-        
+
         let result = AesCbc::from_slices(&[0u8; 16], &[0u8; 16]);
         assert!(result.is_err());
     }
-    
+
     #[test]
     fn test_invalid_iv_length() {
         let result = AesCtr::from_key_iv(&[0u8; 32], &[0u8; 8]);
         assert!(result.is_err());
-        
+
         let result = AesCbc::from_slices(&[0u8; 32], &[0u8; 8]);
         assert!(result.is_err());
     }
-}
+}

src/crypto/hash.rs

@@ -12,10 +12,10 @@
 //! usages are intentional and protocol-mandated.
 
 use hmac::{Hmac, Mac};
-use sha2::Sha256;
 use md5::Md5;
 use sha1::Sha1;
 use sha2::Digest;
+use sha2::Sha256;
 
 type HmacSha256 = Hmac<Sha256>;
 
@@ -28,8 +28,7 @@ pub fn sha256(data: &[u8]) -> [u8; 32] {
 
 /// SHA-256 HMAC
 pub fn sha256_hmac(key: &[u8], data: &[u8]) -> [u8; 32] {
-    let mut mac = HmacSha256::new_from_slice(key)
-        .expect("HMAC accepts any key length");
+    let mut mac = HmacSha256::new_from_slice(key).expect("HMAC accepts any key length");
     mac.update(data);
     mac.finalize().into_bytes().into()
 }
@@ -124,27 +123,18 @@ pub fn derive_middleproxy_keys(
     srv_ipv6: Option<&[u8; 16]>,
 ) -> ([u8; 32], [u8; 16]) {
     let s = build_middleproxy_prekey(
-        nonce_srv,
-        nonce_clt,
-        clt_ts,
-        srv_ip,
-        clt_port,
-        purpose,
-        clt_ip,
-        srv_port,
-        secret,
-        clt_ipv6,
-        srv_ipv6,
+        nonce_srv, nonce_clt, clt_ts, srv_ip, clt_port, purpose, clt_ip, srv_port, secret,
+        clt_ipv6, srv_ipv6,
     );
 
     let md5_1 = md5(&s[1..]);
     let sha1_sum = sha1(&s);
     let md5_2 = md5(&s[2..]);
-    
+
     let mut key = [0u8; 32];
     key[..12].copy_from_slice(&md5_1[..12]);
     key[12..].copy_from_slice(&sha1_sum);
-    
+
     (key, md5_2)
 }
 
@@ -164,17 +154,8 @@ mod tests {
         let secret = vec![0x55u8; 128];
 
         let prekey = build_middleproxy_prekey(
-            &nonce_srv,
-            &nonce_clt,
-            &clt_ts,
-            srv_ip,
-            &clt_port,
-            b"CLIENT",
-            clt_ip,
-            &srv_port,
-            &secret,
-            None,
-            None,
+            &nonce_srv, &nonce_clt, &clt_ts, srv_ip, &clt_port, b"CLIENT", clt_ip, &srv_port,
+            &secret, None, None,
         );
         let digest = sha256(&prekey);
         assert_eq!(

src/crypto/mod.rs

@@ -4,7 +4,7 @@ pub mod aes;
 pub mod hash;
 pub mod random;
 
-pub use aes::{AesCtr, AesCbc};
+pub use aes::{AesCbc, AesCtr};
 pub use hash::{
     build_middleproxy_prekey, crc32, crc32c, derive_middleproxy_keys, sha256, sha256_hmac,
 };

src/crypto/random.rs

@@ -3,11 +3,11 @@
 #![allow(deprecated)]
 #![allow(dead_code)]
 
-use rand::{Rng, RngCore, SeedableRng};
-use rand::rngs::StdRng;
-use parking_lot::Mutex;
-use zeroize::Zeroize;
 use crate::crypto::AesCtr;
+use parking_lot::Mutex;
+use rand::rngs::StdRng;
+use rand::{Rng, RngExt, SeedableRng};
+use zeroize::Zeroize;
 
 /// Cryptographically secure PRNG with AES-CTR
 pub struct SecureRandom {
@@ -34,16 +34,16 @@ impl SecureRandom {
     pub fn new() -> Self {
         let mut seed_source = rand::rng();
         let mut rng = StdRng::from_rng(&mut seed_source);
-        
+
         let mut key = [0u8; 32];
         rng.fill_bytes(&mut key);
         let iv: u128 = rng.random();
-        
+
         let cipher = AesCtr::new(&key, iv);
-        
+
         // Zeroize local key copy — cipher already consumed it
         key.zeroize();
-        
+
         Self {
             inner: Mutex::new(SecureRandomInner {
                 rng,
@@ -53,7 +53,7 @@ impl SecureRandom {
             }),
         }
     }
-    
+
     /// Fill a caller-provided buffer with random bytes.
     pub fn fill(&self, out: &mut [u8]) {
         let mut inner = self.inner.lock();
@@ -94,25 +94,25 @@ impl SecureRandom {
         self.fill(&mut out);
         out
     }
-    
+
     /// Generate random number in range [0, max)
     pub fn range(&self, max: usize) -> usize {
         if max == 0 {
             return 0;
         }
         let mut inner = self.inner.lock();
-        inner.rng.gen_range(0..max)
+        inner.rng.random_range(0..max)
     }
-    
+
     /// Generate random bits
     pub fn bits(&self, k: usize) -> u64 {
         if k == 0 {
             return 0;
         }
-        
+
         let bytes_needed = k.div_ceil(8);
         let bytes = self.bytes(bytes_needed.min(8));
-        
+
         let mut result = 0u64;
         for (i, &b) in bytes.iter().enumerate() {
             if i >= 8 {
@@ -120,14 +120,14 @@ impl SecureRandom {
             }
             result |= (b as u64) << (i * 8);
         }
-        
+
         if k < 64 {
             result &= (1u64 << k) - 1;
         }
-        
+
         result
     }
-    
+
     /// Choose random element from slice
     pub fn choose<'a, T>(&self, slice: &'a [T]) -> Option<&'a T> {
         if slice.is_empty() {
@@ -136,22 +136,22 @@ impl SecureRandom {
             Some(&slice[self.range(slice.len())])
         }
     }
-    
+
     /// Shuffle slice in place
     pub fn shuffle<T>(&self, slice: &mut [T]) {
         let mut inner = self.inner.lock();
         for i in (1..slice.len()).rev() {
-            let j = inner.rng.gen_range(0..=i);
+            let j = inner.rng.random_range(0..=i);
             slice.swap(i, j);
         }
     }
-    
+
     /// Generate random u32
     pub fn u32(&self) -> u32 {
         let mut inner = self.inner.lock();
         inner.rng.random()
     }
-    
+
     /// Generate random u64
     pub fn u64(&self) -> u64 {
         let mut inner = self.inner.lock();
@@ -169,7 +169,7 @@ impl Default for SecureRandom {
 mod tests {
     use super::*;
     use std::collections::HashSet;
-    
+
     #[test]
     fn test_bytes_uniqueness() {
         let rng = SecureRandom::new();
@@ -177,7 +177,7 @@ mod tests {
         let b = rng.bytes(32);
         assert_ne!(a, b);
     }
-    
+
     #[test]
     fn test_bytes_length() {
         let rng = SecureRandom::new();
@@ -186,63 +186,63 @@ mod tests {
         assert_eq!(rng.bytes(100).len(), 100);
         assert_eq!(rng.bytes(1000).len(), 1000);
     }
-    
+
     #[test]
     fn test_range() {
         let rng = SecureRandom::new();
-        
+
         for _ in 0..1000 {
             let n = rng.range(10);
             assert!(n < 10);
         }
-        
+
         assert_eq!(rng.range(1), 0);
         assert_eq!(rng.range(0), 0);
     }
-    
+
     #[test]
     fn test_bits() {
         let rng = SecureRandom::new();
-        
+
         for _ in 0..100 {
             assert!(rng.bits(1) <= 1);
         }
-        
+
         for _ in 0..100 {
             assert!(rng.bits(8) <= 255);
         }
     }
-    
+
     #[test]
     fn test_choose() {
         let rng = SecureRandom::new();
         let items = vec![1, 2, 3, 4, 5];
-        
+
         let mut seen = HashSet::new();
         for _ in 0..1000 {
             if let Some(&item) = rng.choose(&items) {
                 seen.insert(item);
             }
         }
-        
+
         assert_eq!(seen.len(), 5);
-        
+
         let empty: Vec<i32> = vec![];
         assert!(rng.choose(&empty).is_none());
     }
-    
+
     #[test]
     fn test_shuffle() {
         let rng = SecureRandom::new();
         let original = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
-        
+
         let mut shuffled = original.clone();
         rng.shuffle(&mut shuffled);
-        
+
         let mut sorted = shuffled.clone();
         sorted.sort();
         assert_eq!(sorted, original);
-        
+
         assert_ne!(shuffled, original);
     }
 }

src/daemon/mod.rs

@@ -0,0 +1,533 @@
+//! Unix daemon support for telemt.
+//!
+//! Provides classic Unix daemonization (double-fork), PID file management,
+//! and privilege dropping for running telemt as a background service.
+
+use std::fs::{self, File, OpenOptions};
+use std::io::{self, Read, Write};
+use std::os::unix::fs::OpenOptionsExt;
+use std::path::{Path, PathBuf};
+
+use nix::fcntl::{Flock, FlockArg};
+use nix::unistd::{self, ForkResult, Gid, Pid, Uid, chdir, close, fork, getpid, setsid};
+use tracing::{debug, info, warn};
+
+/// Default PID file location.
+pub const DEFAULT_PID_FILE: &str = "/var/run/telemt.pid";
+
+/// Daemon configuration options parsed from CLI.
+#[derive(Debug, Clone, Default)]
+pub struct DaemonOptions {
+    /// Run as daemon (fork to background).
+    pub daemonize: bool,
+    /// Path to PID file.
+    pub pid_file: Option<PathBuf>,
+    /// User to run as after binding sockets.
+    pub user: Option<String>,
+    /// Group to run as after binding sockets.
+    pub group: Option<String>,
+    /// Working directory for the daemon.
+    pub working_dir: Option<PathBuf>,
+    /// Explicit foreground mode (for systemd Type=simple).
+    pub foreground: bool,
+}
+
+impl DaemonOptions {
+    /// Returns the effective PID file path.
+    pub fn pid_file_path(&self) -> &Path {
+        self.pid_file
+            .as_deref()
+            .unwrap_or(Path::new(DEFAULT_PID_FILE))
+    }
+
+    /// Returns true if we should actually daemonize.
+    /// Foreground flag takes precedence.
+    pub fn should_daemonize(&self) -> bool {
+        self.daemonize && !self.foreground
+    }
+}
+
+/// Error types for daemon operations.
+#[derive(Debug, thiserror::Error)]
+pub enum DaemonError {
+    #[error("fork failed: {0}")]
+    ForkFailed(#[source] nix::Error),
+
+    #[error("setsid failed: {0}")]
+    SetsidFailed(#[source] nix::Error),
+
+    #[error("chdir failed: {0}")]
+    ChdirFailed(#[source] nix::Error),
+
+    #[error("failed to open /dev/null: {0}")]
+    DevNullFailed(#[source] io::Error),
+
+    #[error("failed to redirect stdio: {0}")]
+    RedirectFailed(#[source] nix::Error),
+
+    #[error("PID file error: {0}")]
+    PidFile(String),
+
+    #[error("another instance is already running (pid {0})")]
+    AlreadyRunning(i32),
+
+    #[error("user '{0}' not found")]
+    UserNotFound(String),
+
+    #[error("group '{0}' not found")]
+    GroupNotFound(String),
+
+    #[error("failed to set uid/gid: {0}")]
+    PrivilegeDrop(#[source] nix::Error),
+
+    #[error("io error: {0}")]
+    Io(#[from] io::Error),
+}
+
+/// Result of a successful daemonize() call.
+#[derive(Debug)]
+pub enum DaemonizeResult {
+    /// We are the parent process and should exit.
+    Parent,
+    /// We are the daemon child process and should continue.
+    Child,
+}
+
+/// Performs classic Unix double-fork daemonization.
+///
+/// This detaches the process from the controlling terminal:
+/// 1. First fork - parent exits, child continues
+/// 2. setsid() - become session leader
+/// 3. Second fork - ensure we can never acquire a controlling terminal
+/// 4. chdir("/") - don't hold any directory open
+/// 5. Redirect stdin/stdout/stderr to /dev/null
+///
+/// Returns `DaemonizeResult::Parent` in the original parent (which should exit),
+/// or `DaemonizeResult::Child` in the final daemon child.
+pub fn daemonize(working_dir: Option<&Path>) -> Result<DaemonizeResult, DaemonError> {
+    // First fork
+    match unsafe { fork() } {
+        Ok(ForkResult::Parent { .. }) => {
+            // Parent exits
+            return Ok(DaemonizeResult::Parent);
+        }
+        Ok(ForkResult::Child) => {
+            // Child continues
+        }
+        Err(e) => return Err(DaemonError::ForkFailed(e)),
+    }
+
+    // Create new session, become session leader
+    setsid().map_err(DaemonError::SetsidFailed)?;
+
+    // Second fork to ensure we can never acquire a controlling terminal
+    match unsafe { fork() } {
+        Ok(ForkResult::Parent { .. }) => {
+            // Intermediate parent exits
+            std::process::exit(0);
+        }
+        Ok(ForkResult::Child) => {
+            // Final daemon child continues
+        }
+        Err(e) => return Err(DaemonError::ForkFailed(e)),
+    }
+
+    // Change working directory
+    let target_dir = working_dir.unwrap_or(Path::new("/"));
+    chdir(target_dir).map_err(DaemonError::ChdirFailed)?;
+
+    // Redirect stdin, stdout, stderr to /dev/null
+    redirect_stdio_to_devnull()?;
+
+    Ok(DaemonizeResult::Child)
+}
+
+/// Redirects stdin, stdout, and stderr to /dev/null.
+fn redirect_stdio_to_devnull() -> Result<(), DaemonError> {
+    let devnull = File::options()
+        .read(true)
+        .write(true)
+        .open("/dev/null")
+        .map_err(DaemonError::DevNullFailed)?;
+
+    let devnull_fd = std::os::unix::io::AsRawFd::as_raw_fd(&devnull);
+
+    // Use libc::dup2 directly for redirecting standard file descriptors
+    // nix 0.31's dup2 requires OwnedFd which doesn't work well with stdio fds
+    unsafe {
+        // Redirect stdin (fd 0)
+        if libc::dup2(devnull_fd, 0) < 0 {
+            return Err(DaemonError::RedirectFailed(nix::errno::Errno::last()));
+        }
+        // Redirect stdout (fd 1)
+        if libc::dup2(devnull_fd, 1) < 0 {
+            return Err(DaemonError::RedirectFailed(nix::errno::Errno::last()));
+        }
+        // Redirect stderr (fd 2)
+        if libc::dup2(devnull_fd, 2) < 0 {
+            return Err(DaemonError::RedirectFailed(nix::errno::Errno::last()));
+        }
+    }
+
+    // Close original devnull fd if it's not one of the standard fds
+    if devnull_fd > 2 {
+        let _ = close(devnull_fd);
+    }
+
+    Ok(())
+}
+
+/// PID file manager with flock-based locking.
+pub struct PidFile {
+    path: PathBuf,
+    file: Option<File>,
+    locked: bool,
+}
+
+impl PidFile {
+    /// Creates a new PID file manager for the given path.
+    pub fn new<P: AsRef<Path>>(path: P) -> Self {
+        Self {
+            path: path.as_ref().to_path_buf(),
+            file: None,
+            locked: false,
+        }
+    }
+
+    /// Checks if another instance is already running.
+    ///
+    /// Returns the PID of the running instance if one exists.
+    pub fn check_running(&self) -> Result<Option<i32>, DaemonError> {
+        if !self.path.exists() {
+            return Ok(None);
+        }
+
+        // Try to read existing PID
+        let mut contents = String::new();
+        File::open(&self.path)
+            .and_then(|mut f| f.read_to_string(&mut contents))
+            .map_err(|e| DaemonError::PidFile(format!("cannot read {}: {}", self.path.display(), e)))?;
+
+        let pid: i32 = contents
+            .trim()
+            .parse()
+            .map_err(|_| DaemonError::PidFile(format!("invalid PID in {}", self.path.display())))?;
+
+        // Check if process is still running
+        if is_process_running(pid) {
+            Ok(Some(pid))
+        } else {
+            // Stale PID file
+            debug!(pid, path = %self.path.display(), "Removing stale PID file");
+            let _ = fs::remove_file(&self.path);
+            Ok(None)
+        }
+    }
+
+    /// Acquires the PID file lock and writes the current PID.
+    ///
+    /// Fails if another instance is already running.
+    pub fn acquire(&mut self) -> Result<(), DaemonError> {
+        // Check for running instance first
+        if let Some(pid) = self.check_running()? {
+            return Err(DaemonError::AlreadyRunning(pid));
+        }
+
+        // Ensure parent directory exists
+        if let Some(parent) = self.path.parent() {
+            if !parent.exists() {
+                fs::create_dir_all(parent).map_err(|e| {
+                    DaemonError::PidFile(format!(
+                        "cannot create directory {}: {}",
+                        parent.display(),
+                        e
+                    ))
+                })?;
+            }
+        }
+
+        // Open/create PID file with exclusive lock
+        let file = OpenOptions::new()
+            .write(true)
+            .create(true)
+            .truncate(true)
+            .mode(0o644)
+            .open(&self.path)
+            .map_err(|e| {
+                DaemonError::PidFile(format!("cannot open {}: {}", self.path.display(), e))
+            })?;
+
+        // Try to acquire exclusive lock (non-blocking)
+        let flock = Flock::lock(file, FlockArg::LockExclusiveNonblock).map_err(|(_, errno)| {
+            // Check if another instance grabbed the lock
+            if let Some(pid) = self.check_running().ok().flatten() {
+                DaemonError::AlreadyRunning(pid)
+            } else {
+                DaemonError::PidFile(format!("cannot lock {}: {}", self.path.display(), errno))
+            }
+        })?;
+
+        // Write our PID
+        let pid = getpid();
+        let mut file = flock.unlock().map_err(|(_, errno)| {
+            DaemonError::PidFile(format!("unlock failed: {}", errno))
+        })?;
+
+        writeln!(file, "{}", pid).map_err(|e| {
+            DaemonError::PidFile(format!("cannot write PID to {}: {}", self.path.display(), e))
+        })?;
+
+        // Re-acquire lock and keep it
+        let flock = Flock::lock(file, FlockArg::LockExclusiveNonblock).map_err(|(_, errno)| {
+            DaemonError::PidFile(format!("cannot re-lock {}: {}", self.path.display(), errno))
+        })?;
+
+        self.file = Some(flock.unlock().map_err(|(_, errno)| {
+            DaemonError::PidFile(format!("unlock for storage failed: {}", errno))
+        })?);
+        self.locked = true;
+
+        info!(pid = pid.as_raw(), path = %self.path.display(), "PID file created");
+        Ok(())
+    }
+
+    /// Releases the PID file lock and removes the file.
+    pub fn release(&mut self) -> Result<(), DaemonError> {
+        if let Some(file) = self.file.take() {
+            drop(file);
+        }
+        self.locked = false;
+
+        if self.path.exists() {
+            fs::remove_file(&self.path).map_err(|e| {
+                DaemonError::PidFile(format!("cannot remove {}: {}", self.path.display(), e))
+            })?;
+            debug!(path = %self.path.display(), "PID file removed");
+        }
+
+        Ok(())
+    }
+
+    /// Returns the path to this PID file.
+    #[allow(dead_code)]
+    pub fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+impl Drop for PidFile {
+    fn drop(&mut self) {
+        if self.locked {
+            if let Err(e) = self.release() {
+                warn!(error = %e, "Failed to clean up PID file on drop");
+            }
+        }
+    }
+}
+
+/// Checks if a process with the given PID is running.
+fn is_process_running(pid: i32) -> bool {
+    // kill(pid, 0) checks if process exists without sending a signal
+    nix::sys::signal::kill(Pid::from_raw(pid), None).is_ok()
+}
+
+/// Drops privileges to the specified user and group.
+///
+/// This should be called after binding privileged ports but before
+/// entering the main event loop.
+pub fn drop_privileges(user: Option<&str>, group: Option<&str>) -> Result<(), DaemonError> {
+    // Look up group first (need to do this while still root)
+    let target_gid = if let Some(group_name) = group {
+        Some(lookup_group(group_name)?)
+    } else if let Some(user_name) = user {
+        // If no group specified but user is, use user's primary group
+        Some(lookup_user_primary_gid(user_name)?)
+    } else {
+        None
+    };
+
+    // Look up user
+    let target_uid = if let Some(user_name) = user {
+        Some(lookup_user(user_name)?)
+    } else {
+        None
+    };
+
+    // Drop privileges: set GID first, then UID
+    // (Setting UID first would prevent us from setting GID)
+    if let Some(gid) = target_gid {
+        unistd::setgid(gid).map_err(DaemonError::PrivilegeDrop)?;
+        // Also set supplementary groups to just this one
+        unistd::setgroups(&[gid]).map_err(DaemonError::PrivilegeDrop)?;
+        info!(gid = gid.as_raw(), "Dropped group privileges");
+    }
+
+    if let Some(uid) = target_uid {
+        unistd::setuid(uid).map_err(DaemonError::PrivilegeDrop)?;
+        info!(uid = uid.as_raw(), "Dropped user privileges");
+    }
+
+    Ok(())
+}
+
+/// Looks up a user by name and returns their UID.
+fn lookup_user(name: &str) -> Result<Uid, DaemonError> {
+    // Use libc getpwnam
+    let c_name = std::ffi::CString::new(name).map_err(|_| DaemonError::UserNotFound(name.to_string()))?;
+
+    unsafe {
+        let pwd = libc::getpwnam(c_name.as_ptr());
+        if pwd.is_null() {
+            Err(DaemonError::UserNotFound(name.to_string()))
+        } else {
+            Ok(Uid::from_raw((*pwd).pw_uid))
+        }
+    }
+}
+
+/// Looks up a user's primary GID by username.
+fn lookup_user_primary_gid(name: &str) -> Result<Gid, DaemonError> {
+    let c_name = std::ffi::CString::new(name).map_err(|_| DaemonError::UserNotFound(name.to_string()))?;
+
+    unsafe {
+        let pwd = libc::getpwnam(c_name.as_ptr());
+        if pwd.is_null() {
+            Err(DaemonError::UserNotFound(name.to_string()))
+        } else {
+            Ok(Gid::from_raw((*pwd).pw_gid))
+        }
+    }
+}
+
+/// Looks up a group by name and returns its GID.
+fn lookup_group(name: &str) -> Result<Gid, DaemonError> {
+    let c_name = std::ffi::CString::new(name).map_err(|_| DaemonError::GroupNotFound(name.to_string()))?;
+
+    unsafe {
+        let grp = libc::getgrnam(c_name.as_ptr());
+        if grp.is_null() {
+            Err(DaemonError::GroupNotFound(name.to_string()))
+        } else {
+            Ok(Gid::from_raw((*grp).gr_gid))
+        }
+    }
+}
+
+/// Reads PID from a PID file.
+#[allow(dead_code)]
+pub fn read_pid_file<P: AsRef<Path>>(path: P) -> Result<i32, DaemonError> {
+    let path = path.as_ref();
+    let mut contents = String::new();
+    File::open(path)
+        .and_then(|mut f| f.read_to_string(&mut contents))
+        .map_err(|e| DaemonError::PidFile(format!("cannot read {}: {}", path.display(), e)))?;
+
+    contents
+        .trim()
+        .parse()
+        .map_err(|_| DaemonError::PidFile(format!("invalid PID in {}", path.display())))
+}
+
+/// Sends a signal to the process specified in a PID file.
+#[allow(dead_code)]
+pub fn signal_pid_file<P: AsRef<Path>>(
+    path: P,
+    signal: nix::sys::signal::Signal,
+) -> Result<(), DaemonError> {
+    let pid = read_pid_file(&path)?;
+
+    if !is_process_running(pid) {
+        return Err(DaemonError::PidFile(format!(
+            "process {} from {} is not running",
+            pid,
+            path.as_ref().display()
+        )));
+    }
+
+    nix::sys::signal::kill(Pid::from_raw(pid), signal).map_err(|e| {
+        DaemonError::PidFile(format!("cannot signal process {}: {}", pid, e))
+    })?;
+
+    Ok(())
+}
+
+/// Returns the status of the daemon based on PID file.
+#[allow(dead_code)]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DaemonStatus {
+    /// Daemon is running with the given PID.
+    Running(i32),
+    /// PID file exists but process is not running.
+    Stale(i32),
+    /// No PID file exists.
+    NotRunning,
+}
+
+/// Checks the daemon status from a PID file.
+#[allow(dead_code)]
+pub fn check_status<P: AsRef<Path>>(path: P) -> DaemonStatus {
+    let path = path.as_ref();
+
+    if !path.exists() {
+        return DaemonStatus::NotRunning;
+    }
+
+    match read_pid_file(path) {
+        Ok(pid) => {
+            if is_process_running(pid) {
+                DaemonStatus::Running(pid)
+            } else {
+                DaemonStatus::Stale(pid)
+            }
+        }
+        Err(_) => DaemonStatus::NotRunning,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_daemon_options_default() {
+        let opts = DaemonOptions::default();
+        assert!(!opts.daemonize);
+        assert!(!opts.should_daemonize());
+        assert_eq!(opts.pid_file_path(), Path::new(DEFAULT_PID_FILE));
+    }
+
+    #[test]
+    fn test_daemon_options_foreground_overrides() {
+        let opts = DaemonOptions {
+            daemonize: true,
+            foreground: true,
+            ..Default::default()
+        };
+        assert!(!opts.should_daemonize());
+    }
+
+    #[test]
+    fn test_check_status_not_running() {
+        let path = "/tmp/telemt_test_nonexistent.pid";
+        assert_eq!(check_status(path), DaemonStatus::NotRunning);
+    }
+
+    #[test]
+    fn test_pid_file_basic() {
+        let path = "/tmp/telemt_test_pidfile.pid";
+        let _ = fs::remove_file(path);
+
+        let mut pf = PidFile::new(path);
+        assert!(pf.check_running().unwrap().is_none());
+
+        pf.acquire().unwrap();
+        assert!(Path::new(path).exists());
+
+        // Read it back
+        let pid = read_pid_file(path).unwrap();
+        assert_eq!(pid, std::process::id() as i32);
+
+        pf.release().unwrap();
+        assert!(!Path::new(path).exists());
+    }
+}

src/error.rs

@@ -12,28 +12,15 @@ use thiserror::Error;
 #[derive(Debug)]
 pub enum StreamError {
     /// Partial read: got fewer bytes than expected
-    PartialRead {
-        expected: usize,
-        got: usize,
-    },
+    PartialRead { expected: usize, got: usize },
     /// Partial write: wrote fewer bytes than expected
-    PartialWrite {
-        expected: usize,
-        written: usize,
-    },
+    PartialWrite { expected: usize, written: usize },
     /// Stream is in poisoned state and cannot be used
-    Poisoned {
-        reason: String,
-    },
+    Poisoned { reason: String },
     /// Buffer overflow: attempted to buffer more than allowed
-    BufferOverflow {
-        limit: usize,
-        attempted: usize,
-    },
+    BufferOverflow { limit: usize, attempted: usize },
     /// Invalid frame format
-    InvalidFrame {
-        details: String,
-    },
+    InvalidFrame { details: String },
     /// Unexpected end of stream
     UnexpectedEof,
     /// Underlying I/O error
@@ -47,13 +34,21 @@ impl fmt::Display for StreamError {
                 write!(f, "partial read: expected {} bytes, got {}", expected, got)
             }
             Self::PartialWrite { expected, written } => {
-                write!(f, "partial write: expected {} bytes, wrote {}", expected, written)
+                write!(
+                    f,
+                    "partial write: expected {} bytes, wrote {}",
+                    expected, written
+                )
             }
             Self::Poisoned { reason } => {
                 write!(f, "stream poisoned: {}", reason)
             }
             Self::BufferOverflow { limit, attempted } => {
-                write!(f, "buffer overflow: limit {}, attempted {}", limit, attempted)
+                write!(
+                    f,
+                    "buffer overflow: limit {}, attempted {}",
+                    limit, attempted
+                )
             }
             Self::InvalidFrame { details } => {
                 write!(f, "invalid frame: {}", details)
@@ -90,9 +85,7 @@ impl From<StreamError> for std::io::Error {
             StreamError::UnexpectedEof => {
                 std::io::Error::new(std::io::ErrorKind::UnexpectedEof, err)
             }
-            StreamError::Poisoned { .. } => {
-                std::io::Error::other(err)
-            }
+            StreamError::Poisoned { .. } => std::io::Error::other(err),
             StreamError::BufferOverflow { .. } => {
                 std::io::Error::new(std::io::ErrorKind::OutOfMemory, err)
             }
@@ -112,7 +105,7 @@ impl From<StreamError> for std::io::Error {
 pub trait Recoverable {
     /// Check if error is recoverable (can retry operation)
     fn is_recoverable(&self) -> bool;
-    
+
     /// Check if connection can continue after this error
     fn can_continue(&self) -> bool;
 }
@@ -123,19 +116,22 @@ impl Recoverable for StreamError {
             Self::PartialRead { .. } | Self::PartialWrite { .. } => true,
             Self::Io(e) => matches!(
                 e.kind(),
-                std::io::ErrorKind::WouldBlock 
-                | std::io::ErrorKind::Interrupted
-                | std::io::ErrorKind::TimedOut
+                std::io::ErrorKind::WouldBlock
+                    | std::io::ErrorKind::Interrupted
+                    | std::io::ErrorKind::TimedOut
             ),
-            Self::Poisoned { .. } 
+            Self::Poisoned { .. }
             | Self::BufferOverflow { .. }
             | Self::InvalidFrame { .. }
             | Self::UnexpectedEof => false,
         }
     }
-    
+
     fn can_continue(&self) -> bool {
-        !matches!(self, Self::Poisoned { .. } | Self::UnexpectedEof | Self::BufferOverflow { .. })
+        !matches!(
+            self,
+            Self::Poisoned { .. } | Self::UnexpectedEof | Self::BufferOverflow { .. }
+        )
     }
 }
 
@@ -143,19 +139,19 @@ impl Recoverable for std::io::Error {
     fn is_recoverable(&self) -> bool {
         matches!(
             self.kind(),
-            std::io::ErrorKind::WouldBlock 
-            | std::io::ErrorKind::Interrupted
-            | std::io::ErrorKind::TimedOut
+            std::io::ErrorKind::WouldBlock
+                | std::io::ErrorKind::Interrupted
+                | std::io::ErrorKind::TimedOut
         )
     }
-    
+
     fn can_continue(&self) -> bool {
         !matches!(
             self.kind(),
             std::io::ErrorKind::BrokenPipe
-            | std::io::ErrorKind::ConnectionReset
-            | std::io::ErrorKind::ConnectionAborted
-            | std::io::ErrorKind::NotConnected
+                | std::io::ErrorKind::ConnectionReset
+                | std::io::ErrorKind::ConnectionAborted
+                | std::io::ErrorKind::NotConnected
         )
     }
 }
@@ -165,96 +161,91 @@ impl Recoverable for std::io::Error {
 #[derive(Error, Debug)]
 pub enum ProxyError {
     // ============= Crypto Errors =============
-    
     #[error("Crypto error: {0}")]
     Crypto(String),
-    
+
     #[error("Invalid key length: expected {expected}, got {got}")]
     InvalidKeyLength { expected: usize, got: usize },
-    
+
     // ============= Stream Errors =============
-    
     #[error("Stream error: {0}")]
     Stream(#[from] StreamError),
-    
+
     // ============= Protocol Errors =============
-    
     #[error("Invalid handshake: {0}")]
     InvalidHandshake(String),
-    
+
     #[error("Invalid protocol tag: {0:02x?}")]
     InvalidProtoTag([u8; 4]),
-    
+
     #[error("Invalid TLS record: type={record_type}, version={version:02x?}")]
     InvalidTlsRecord { record_type: u8, version: [u8; 2] },
-    
+
     #[error("Replay attack detected from {addr}")]
     ReplayAttack { addr: SocketAddr },
-    
+
     #[error("Time skew detected: client={client_time}, server={server_time}")]
     TimeSkew { client_time: u32, server_time: u32 },
-    
+
     #[error("Invalid message length: {len} (min={min}, max={max})")]
     InvalidMessageLength { len: usize, min: usize, max: usize },
-    
+
     #[error("Checksum mismatch: expected={expected:08x}, got={got:08x}")]
     ChecksumMismatch { expected: u32, got: u32 },
-    
+
     #[error("Sequence number mismatch: expected={expected}, got={got}")]
     SeqNoMismatch { expected: i32, got: i32 },
-    
+
     #[error("TLS handshake failed: {reason}")]
     TlsHandshakeFailed { reason: String },
-    
+
     #[error("Telegram handshake timeout")]
     TgHandshakeTimeout,
-    
+
     // ============= Network Errors =============
-    
     #[error("Connection timeout to {addr}")]
     ConnectionTimeout { addr: String },
-    
+
     #[error("Connection refused by {addr}")]
     ConnectionRefused { addr: String },
-    
+
     #[error("IO error: {0}")]
     Io(#[from] std::io::Error),
-    
+
     // ============= Proxy Protocol Errors =============
-    
     #[error("Invalid proxy protocol header")]
     InvalidProxyProtocol,
-    
+
+    #[error("Unknown TLS SNI")]
+    UnknownTlsSni,
+
     #[error("Proxy error: {0}")]
     Proxy(String),
-    
+
     // ============= Config Errors =============
-    
     #[error("Config error: {0}")]
     Config(String),
-    
+
     #[error("Invalid secret for user {user}: {reason}")]
     InvalidSecret { user: String, reason: String },
-    
+
     // ============= User Errors =============
-    
     #[error("User {user} expired")]
     UserExpired { user: String },
-    
+
     #[error("User {user} exceeded connection limit")]
     ConnectionLimitExceeded { user: String },
-    
+
     #[error("User {user} exceeded data quota")]
     DataQuotaExceeded { user: String },
-    
+
     #[error("Unknown user")]
     UnknownUser,
-    
+
     #[error("Rate limited")]
     RateLimited,
-    
+
     // ============= General Errors =============
-    
     #[error("Internal error: {0}")]
     Internal(String),
 }
@@ -269,7 +260,7 @@ impl Recoverable for ProxyError {
             _ => false,
         }
     }
-    
+
     fn can_continue(&self) -> bool {
         match self {
             Self::Stream(e) => e.can_continue(),
@@ -301,17 +292,19 @@ impl<T, R, W> HandshakeResult<T, R, W> {
     pub fn is_success(&self) -> bool {
         matches!(self, HandshakeResult::Success(_))
     }
-    
+
     /// Check if bad client
     pub fn is_bad_client(&self) -> bool {
         matches!(self, HandshakeResult::BadClient { .. })
     }
-    
+
     /// Map the success value
     pub fn map<U, F: FnOnce(T) -> U>(self, f: F) -> HandshakeResult<U, R, W> {
         match self {
             HandshakeResult::Success(v) => HandshakeResult::Success(f(v)),
-            HandshakeResult::BadClient { reader, writer } => HandshakeResult::BadClient { reader, writer },
+            HandshakeResult::BadClient { reader, writer } => {
+                HandshakeResult::BadClient { reader, writer }
+            }
             HandshakeResult::Error(e) => HandshakeResult::Error(e),
         }
     }
@@ -338,76 +331,104 @@ impl<T, R, W> From<StreamError> for HandshakeResult<T, R, W> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    
+
     #[test]
     fn test_stream_error_display() {
-        let err = StreamError::PartialRead { expected: 100, got: 50 };
+        let err = StreamError::PartialRead {
+            expected: 100,
+            got: 50,
+        };
         assert!(err.to_string().contains("100"));
         assert!(err.to_string().contains("50"));
-        
-        let err = StreamError::Poisoned { reason: "test".into() };
+
+        let err = StreamError::Poisoned {
+            reason: "test".into(),
+        };
         assert!(err.to_string().contains("test"));
     }
-    
+
     #[test]
     fn test_stream_error_recoverable() {
-        assert!(StreamError::PartialRead { expected: 10, got: 5 }.is_recoverable());
-        assert!(StreamError::PartialWrite { expected: 10, written: 5 }.is_recoverable());
+        assert!(
+            StreamError::PartialRead {
+                expected: 10,
+                got: 5
+            }
+            .is_recoverable()
+        );
+        assert!(
+            StreamError::PartialWrite {
+                expected: 10,
+                written: 5
+            }
+            .is_recoverable()
+        );
         assert!(!StreamError::Poisoned { reason: "x".into() }.is_recoverable());
         assert!(!StreamError::UnexpectedEof.is_recoverable());
     }
-    
+
     #[test]
     fn test_stream_error_can_continue() {
         assert!(!StreamError::Poisoned { reason: "x".into() }.can_continue());
         assert!(!StreamError::UnexpectedEof.can_continue());
-        assert!(StreamError::PartialRead { expected: 10, got: 5 }.can_continue());
+        assert!(
+            StreamError::PartialRead {
+                expected: 10,
+                got: 5
+            }
+            .can_continue()
+        );
     }
-    
+
     #[test]
     fn test_stream_error_to_io_error() {
         let stream_err = StreamError::UnexpectedEof;
         let io_err: std::io::Error = stream_err.into();
         assert_eq!(io_err.kind(), std::io::ErrorKind::UnexpectedEof);
     }
-    
+
     #[test]
     fn test_handshake_result() {
         let success: HandshakeResult<i32, (), ()> = HandshakeResult::Success(42);
         assert!(success.is_success());
         assert!(!success.is_bad_client());
-        
-        let bad: HandshakeResult<i32, (), ()> = HandshakeResult::BadClient { reader: (), writer: () };
+
+        let bad: HandshakeResult<i32, (), ()> = HandshakeResult::BadClient {
+            reader: (),
+            writer: (),
+        };
         assert!(!bad.is_success());
         assert!(bad.is_bad_client());
     }
-    
+
     #[test]
     fn test_handshake_result_map() {
         let success: HandshakeResult<i32, (), ()> = HandshakeResult::Success(42);
         let mapped = success.map(|x| x * 2);
-        
+
         match mapped {
             HandshakeResult::Success(v) => assert_eq!(v, 84),
             _ => panic!("Expected success"),
         }
     }
-    
+
     #[test]
     fn test_proxy_error_recoverable() {
         let err = ProxyError::RateLimited;
         assert!(err.is_recoverable());
-        
+
         let err = ProxyError::InvalidHandshake("bad".into());
         assert!(!err.is_recoverable());
     }
-    
+
     #[test]
     fn test_error_display() {
-        let err = ProxyError::ConnectionTimeout { addr: "1.2.3.4:443".into() };
+        let err = ProxyError::ConnectionTimeout {
+            addr: "1.2.3.4:443".into(),
+        };
         assert!(err.to_string().contains("1.2.3.4:443"));
-        
+
         let err = ProxyError::InvalidProxyProtocol;
         assert!(err.to_string().contains("proxy protocol"));
     }
-}
+}

src/ip_tracker.rs

@@ -5,10 +5,11 @@
 use std::collections::HashMap;
 use std::net::IpAddr;
 use std::sync::Arc;
+use std::sync::Mutex;
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::time::{Duration, Instant};
 
-use tokio::sync::RwLock;
+use tokio::sync::{Mutex as AsyncMutex, RwLock};
 
 use crate::config::UserMaxUniqueIpsMode;
 
@@ -21,6 +22,8 @@ pub struct UserIpTracker {
     limit_mode: Arc<RwLock<UserMaxUniqueIpsMode>>,
     limit_window: Arc<RwLock<Duration>>,
     last_compact_epoch_secs: Arc<AtomicU64>,
+    cleanup_queue: Arc<Mutex<Vec<(String, IpAddr)>>>,
+    cleanup_drain_lock: Arc<AsyncMutex<()>>,
 }
 
 impl UserIpTracker {
@@ -33,6 +36,79 @@ impl UserIpTracker {
             limit_mode: Arc::new(RwLock::new(UserMaxUniqueIpsMode::ActiveWindow)),
             limit_window: Arc::new(RwLock::new(Duration::from_secs(30))),
             last_compact_epoch_secs: Arc::new(AtomicU64::new(0)),
+            cleanup_queue: Arc::new(Mutex::new(Vec::new())),
+            cleanup_drain_lock: Arc::new(AsyncMutex::new(())),
+        }
+    }
+
+    pub fn enqueue_cleanup(&self, user: String, ip: IpAddr) {
+        match self.cleanup_queue.lock() {
+            Ok(mut queue) => queue.push((user, ip)),
+            Err(poisoned) => {
+                let mut queue = poisoned.into_inner();
+                queue.push((user.clone(), ip));
+                self.cleanup_queue.clear_poison();
+                tracing::warn!(
+                    "UserIpTracker cleanup_queue lock poisoned; recovered and enqueued IP cleanup for {} ({})",
+                    user,
+                    ip
+                );
+            }
+        }
+    }
+
+    #[cfg(test)]
+    pub(crate) fn cleanup_queue_len_for_tests(&self) -> usize {
+        self.cleanup_queue
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+            .len()
+    }
+
+    #[cfg(test)]
+    pub(crate) fn cleanup_queue_mutex_for_tests(&self) -> Arc<Mutex<Vec<(String, IpAddr)>>> {
+        Arc::clone(&self.cleanup_queue)
+    }
+
+    pub(crate) async fn drain_cleanup_queue(&self) {
+        // Serialize queue draining and active-IP mutation so check-and-add cannot
+        // observe stale active entries that are already queued for removal.
+        let _drain_guard = self.cleanup_drain_lock.lock().await;
+        let to_remove = {
+            match self.cleanup_queue.lock() {
+                Ok(mut queue) => {
+                    if queue.is_empty() {
+                        return;
+                    }
+                    std::mem::take(&mut *queue)
+                }
+                Err(poisoned) => {
+                    let mut queue = poisoned.into_inner();
+                    if queue.is_empty() {
+                        self.cleanup_queue.clear_poison();
+                        return;
+                    }
+                    let drained = std::mem::take(&mut *queue);
+                    self.cleanup_queue.clear_poison();
+                    drained
+                }
+            }
+        };
+
+        let mut active_ips = self.active_ips.write().await;
+        for (user, ip) in to_remove {
+            if let Some(user_ips) = active_ips.get_mut(&user) {
+                if let Some(count) = user_ips.get_mut(&ip) {
+                    if *count > 1 {
+                        *count -= 1;
+                    } else {
+                        user_ips.remove(&ip);
+                    }
+                }
+                if user_ips.is_empty() {
+                    active_ips.remove(&user);
+                }
+            }
         }
     }
 
@@ -65,7 +141,8 @@ impl UserIpTracker {
 
         let mut active_ips = self.active_ips.write().await;
         let mut recent_ips = self.recent_ips.write().await;
-        let mut users = Vec::<String>::with_capacity(active_ips.len().saturating_add(recent_ips.len()));
+        let mut users =
+            Vec::<String>::with_capacity(active_ips.len().saturating_add(recent_ips.len()));
         users.extend(active_ips.keys().cloned());
         for user in recent_ips.keys() {
             if !active_ips.contains_key(user) {
@@ -74,8 +151,14 @@ impl UserIpTracker {
         }
 
         for user in users {
-            let active_empty = active_ips.get(&user).map(|ips| ips.is_empty()).unwrap_or(true);
-            let recent_empty = recent_ips.get(&user).map(|ips| ips.is_empty()).unwrap_or(true);
+            let active_empty = active_ips
+                .get(&user)
+                .map(|ips| ips.is_empty())
+                .unwrap_or(true);
+            let recent_empty = recent_ips
+                .get(&user)
+                .map(|ips| ips.is_empty())
+                .unwrap_or(true);
             if active_empty && recent_empty {
                 active_ips.remove(&user);
                 recent_ips.remove(&user);
@@ -118,6 +201,7 @@ impl UserIpTracker {
     }
 
     pub async fn check_and_add(&self, username: &str, ip: IpAddr) -> Result<(), String> {
+        self.drain_cleanup_queue().await;
         self.maybe_compact_empty_users().await;
         let default_max_ips = *self.default_max_ips.read().await;
         let limit = {
@@ -194,6 +278,7 @@ impl UserIpTracker {
     }
 
     pub async fn get_recent_counts_for_users(&self, users: &[String]) -> HashMap<String, usize> {
+        self.drain_cleanup_queue().await;
         let window = *self.limit_window.read().await;
         let now = Instant::now();
         let recent_ips = self.recent_ips.read().await;
@@ -214,6 +299,7 @@ impl UserIpTracker {
     }
 
     pub async fn get_active_ips_for_users(&self, users: &[String]) -> HashMap<String, Vec<IpAddr>> {
+        self.drain_cleanup_queue().await;
         let active_ips = self.active_ips.read().await;
         let mut out = HashMap::with_capacity(users.len());
         for user in users {
@@ -228,6 +314,7 @@ impl UserIpTracker {
     }
 
     pub async fn get_recent_ips_for_users(&self, users: &[String]) -> HashMap<String, Vec<IpAddr>> {
+        self.drain_cleanup_queue().await;
         let window = *self.limit_window.read().await;
         let now = Instant::now();
         let recent_ips = self.recent_ips.read().await;
@@ -250,11 +337,13 @@ impl UserIpTracker {
     }
 
     pub async fn get_active_ip_count(&self, username: &str) -> usize {
+        self.drain_cleanup_queue().await;
         let active_ips = self.active_ips.read().await;
         active_ips.get(username).map(|ips| ips.len()).unwrap_or(0)
     }
 
     pub async fn get_active_ips(&self, username: &str) -> Vec<IpAddr> {
+        self.drain_cleanup_queue().await;
         let active_ips = self.active_ips.read().await;
         active_ips
             .get(username)
@@ -263,6 +352,7 @@ impl UserIpTracker {
     }
 
     pub async fn get_stats(&self) -> Vec<(String, usize, usize)> {
+        self.drain_cleanup_queue().await;
         let active_ips = self.active_ips.read().await;
         let max_ips = self.max_ips.read().await;
         let default_max_ips = *self.default_max_ips.read().await;
@@ -301,6 +391,7 @@ impl UserIpTracker {
     }
 
     pub async fn is_ip_active(&self, username: &str, ip: IpAddr) -> bool {
+        self.drain_cleanup_queue().await;
         let active_ips = self.active_ips.read().await;
         active_ips
             .get(username)

src/logging.rs

@@ -0,0 +1,291 @@
+//! Logging configuration for telemt.
+//!
+//! Supports multiple log destinations:
+//! - stderr (default, works with systemd journald)
+//! - syslog (Unix only, for traditional init systems)
+//! - file (with optional rotation)
+
+#![allow(dead_code)] // Infrastructure module - used via CLI flags
+
+use std::path::Path;
+
+use tracing_subscriber::layer::SubscriberExt;
+use tracing_subscriber::util::SubscriberInitExt;
+use tracing_subscriber::{EnvFilter, fmt, reload};
+
+/// Log destination configuration.
+#[derive(Debug, Clone, Default)]
+pub enum LogDestination {
+    /// Log to stderr (default, captured by systemd journald).
+    #[default]
+    Stderr,
+    /// Log to syslog (Unix only).
+    #[cfg(unix)]
+    Syslog,
+    /// Log to a file with optional rotation.
+    File {
+        path: String,
+        /// Rotate daily if true.
+        rotate_daily: bool,
+    },
+}
+
+/// Logging options parsed from CLI/config.
+#[derive(Debug, Clone, Default)]
+pub struct LoggingOptions {
+    /// Where to send logs.
+    pub destination: LogDestination,
+    /// Disable ANSI colors.
+    pub disable_colors: bool,
+}
+
+/// Guard that must be held to keep file logging active.
+/// When dropped, flushes and closes log files.
+pub struct LoggingGuard {
+    _guard: Option<tracing_appender::non_blocking::WorkerGuard>,
+}
+
+impl LoggingGuard {
+    fn new(guard: Option<tracing_appender::non_blocking::WorkerGuard>) -> Self {
+        Self { _guard: guard }
+    }
+
+    /// Creates a no-op guard for stderr/syslog logging.
+    pub fn noop() -> Self {
+        Self { _guard: None }
+    }
+}
+
+/// Initialize the tracing subscriber with the specified options.
+///
+/// Returns a reload handle for dynamic log level changes and a guard
+/// that must be kept alive for file logging.
+pub fn init_logging(
+    opts: &LoggingOptions,
+    initial_filter: &str,
+) -> (reload::Handle<EnvFilter, impl tracing::Subscriber + Send + Sync>, LoggingGuard) {
+    let (filter_layer, filter_handle) = reload::Layer::new(EnvFilter::new(initial_filter));
+
+    match &opts.destination {
+        LogDestination::Stderr => {
+            let fmt_layer = fmt::Layer::default()
+                .with_ansi(!opts.disable_colors)
+                .with_target(true);
+
+            tracing_subscriber::registry()
+                .with(filter_layer)
+                .with(fmt_layer)
+                .init();
+
+            (filter_handle, LoggingGuard::noop())
+        }
+
+        #[cfg(unix)]
+        LogDestination::Syslog => {
+            // Use a custom fmt layer that writes to syslog
+            let fmt_layer = fmt::Layer::default()
+                .with_ansi(false)
+                .with_target(true)
+                .with_writer(SyslogWriter::new);
+
+            tracing_subscriber::registry()
+                .with(filter_layer)
+                .with(fmt_layer)
+                .init();
+
+            (filter_handle, LoggingGuard::noop())
+        }
+
+        LogDestination::File { path, rotate_daily } => {
+            let (non_blocking, guard) = if *rotate_daily {
+                // Extract directory and filename prefix
+                let path = Path::new(path);
+                let dir = path.parent().unwrap_or(Path::new("/var/log"));
+                let prefix = path.file_name()
+                    .and_then(|s| s.to_str())
+                    .unwrap_or("telemt");
+
+                let file_appender = tracing_appender::rolling::daily(dir, prefix);
+                tracing_appender::non_blocking(file_appender)
+            } else {
+                let file = std::fs::OpenOptions::new()
+                    .create(true)
+                    .append(true)
+                    .open(path)
+                    .expect("Failed to open log file");
+                tracing_appender::non_blocking(file)
+            };
+
+            let fmt_layer = fmt::Layer::default()
+                .with_ansi(false)
+                .with_target(true)
+                .with_writer(non_blocking);
+
+            tracing_subscriber::registry()
+                .with(filter_layer)
+                .with(fmt_layer)
+                .init();
+
+            (filter_handle, LoggingGuard::new(Some(guard)))
+        }
+    }
+}
+
+/// Syslog writer for tracing.
+#[cfg(unix)]
+struct SyslogWriter {
+    _private: (),
+}
+
+#[cfg(unix)]
+impl SyslogWriter {
+    fn new() -> Self {
+        // Open syslog connection on first use
+        static INIT: std::sync::Once = std::sync::Once::new();
+        INIT.call_once(|| {
+            unsafe {
+                // Open syslog with ident "telemt", LOG_PID, LOG_DAEMON facility
+                let ident = b"telemt\0".as_ptr() as *const libc::c_char;
+                libc::openlog(ident, libc::LOG_PID | libc::LOG_NDELAY, libc::LOG_DAEMON);
+            }
+        });
+        Self { _private: () }
+    }
+}
+
+#[cfg(unix)]
+impl std::io::Write for SyslogWriter {
+    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+        // Convert to C string, stripping newlines
+        let msg = String::from_utf8_lossy(buf);
+        let msg = msg.trim_end();
+
+        if msg.is_empty() {
+            return Ok(buf.len());
+        }
+
+        // Determine priority based on log level in the message
+        let priority = if msg.contains(" ERROR ") || msg.contains(" error ") {
+            libc::LOG_ERR
+        } else if msg.contains(" WARN ") || msg.contains(" warn ") {
+            libc::LOG_WARNING
+        } else if msg.contains(" INFO ") || msg.contains(" info ") {
+            libc::LOG_INFO
+        } else if msg.contains(" DEBUG ") || msg.contains(" debug ") {
+            libc::LOG_DEBUG
+        } else {
+            libc::LOG_INFO
+        };
+
+        // Write to syslog
+        let c_msg = std::ffi::CString::new(msg.as_bytes())
+            .unwrap_or_else(|_| std::ffi::CString::new("(invalid utf8)").unwrap());
+
+        unsafe {
+            libc::syslog(priority, b"%s\0".as_ptr() as *const libc::c_char, c_msg.as_ptr());
+        }
+
+        Ok(buf.len())
+    }
+
+    fn flush(&mut self) -> std::io::Result<()> {
+        Ok(())
+    }
+}
+
+#[cfg(unix)]
+impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for SyslogWriter {
+    type Writer = SyslogWriter;
+
+    fn make_writer(&'a self) -> Self::Writer {
+        SyslogWriter::new()
+    }
+}
+
+/// Parse log destination from CLI arguments.
+pub fn parse_log_destination(args: &[String]) -> LogDestination {
+    let mut i = 0;
+    while i < args.len() {
+        match args[i].as_str() {
+            #[cfg(unix)]
+            "--syslog" => {
+                return LogDestination::Syslog;
+            }
+            "--log-file" => {
+                i += 1;
+                if i < args.len() {
+                    return LogDestination::File {
+                        path: args[i].clone(),
+                        rotate_daily: false,
+                    };
+                }
+            }
+            s if s.starts_with("--log-file=") => {
+                return LogDestination::File {
+                    path: s.trim_start_matches("--log-file=").to_string(),
+                    rotate_daily: false,
+                };
+            }
+            "--log-file-daily" => {
+                i += 1;
+                if i < args.len() {
+                    return LogDestination::File {
+                        path: args[i].clone(),
+                        rotate_daily: true,
+                    };
+                }
+            }
+            s if s.starts_with("--log-file-daily=") => {
+                return LogDestination::File {
+                    path: s.trim_start_matches("--log-file-daily=").to_string(),
+                    rotate_daily: true,
+                };
+            }
+            _ => {}
+        }
+        i += 1;
+    }
+    LogDestination::Stderr
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_parse_log_destination_default() {
+        let args: Vec<String> = vec![];
+        assert!(matches!(parse_log_destination(&args), LogDestination::Stderr));
+    }
+
+    #[test]
+    fn test_parse_log_destination_file() {
+        let args = vec!["--log-file".to_string(), "/var/log/telemt.log".to_string()];
+        match parse_log_destination(&args) {
+            LogDestination::File { path, rotate_daily } => {
+                assert_eq!(path, "/var/log/telemt.log");
+                assert!(!rotate_daily);
+            }
+            _ => panic!("Expected File destination"),
+        }
+    }
+
+    #[test]
+    fn test_parse_log_destination_file_daily() {
+        let args = vec!["--log-file-daily=/var/log/telemt".to_string()];
+        match parse_log_destination(&args) {
+            LogDestination::File { path, rotate_daily } => {
+                assert_eq!(path, "/var/log/telemt");
+                assert!(rotate_daily);
+            }
+            _ => panic!("Expected File destination"),
+        }
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn test_parse_log_destination_syslog() {
+        let args = vec!["--syslog".to_string()];
+        assert!(matches!(parse_log_destination(&args), LogDestination::Syslog));
+    }
+}

src/maestro/admission.rs

@@ -21,10 +21,29 @@ pub(crate) async fn configure_admission_gate(
     if config.general.use_middle_proxy {
         if let Some(pool) = me_pool.as_ref() {
             let initial_ready = pool.admission_ready_conditional_cast().await;
-            admission_tx.send_replace(initial_ready);
-            let _ = route_runtime.set_mode(RelayRouteMode::Middle);
+            let mut fallback_enabled = config.general.me2dc_fallback;
+            let mut fast_fallback_enabled = fallback_enabled && config.general.me2dc_fast;
+            let (initial_gate_open, initial_route_mode, initial_fallback_reason) = if initial_ready
+            {
+                (true, RelayRouteMode::Middle, None)
+            } else if fast_fallback_enabled {
+                (
+                    true,
+                    RelayRouteMode::Direct,
+                    Some("fast_not_ready_fallback"),
+                )
+            } else {
+                (false, RelayRouteMode::Middle, None)
+            };
+            admission_tx.send_replace(initial_gate_open);
+            let _ = route_runtime.set_mode(initial_route_mode);
             if initial_ready {
                 info!("Conditional-admission gate: open / ME pool READY");
+            } else if let Some(reason) = initial_fallback_reason {
+                warn!(
+                    fallback_reason = reason,
+                    "Conditional-admission gate opened in ME fast fallback mode"
+                );
             } else {
                 warn!("Conditional-admission gate: closed / ME pool is NOT ready)");
             }
@@ -34,10 +53,9 @@ pub(crate) async fn configure_admission_gate(
             let route_runtime_gate = route_runtime.clone();
             let mut config_rx_gate = config_rx.clone();
             let mut admission_poll_ms = config.general.me_admission_poll_ms.max(1);
-            let mut fallback_enabled = config.general.me2dc_fallback;
             tokio::spawn(async move {
-                let mut gate_open = initial_ready;
-                let mut route_mode = RelayRouteMode::Middle;
+                let mut gate_open = initial_gate_open;
+                let mut route_mode = initial_route_mode;
                 let mut ready_observed = initial_ready;
                 let mut not_ready_since = if initial_ready {
                     None
@@ -53,16 +71,23 @@ pub(crate) async fn configure_admission_gate(
                             let cfg = config_rx_gate.borrow_and_update().clone();
                             admission_poll_ms = cfg.general.me_admission_poll_ms.max(1);
                             fallback_enabled = cfg.general.me2dc_fallback;
+                            fast_fallback_enabled = cfg.general.me2dc_fallback && cfg.general.me2dc_fast;
                             continue;
                         }
                         _ = tokio::time::sleep(Duration::from_millis(admission_poll_ms)) => {}
                     }
                     let ready = pool_for_gate.admission_ready_conditional_cast().await;
                     let now = Instant::now();
-                    let (next_gate_open, next_route_mode, next_fallback_active) = if ready {
+                    let (next_gate_open, next_route_mode, next_fallback_reason) = if ready {
                         ready_observed = true;
                         not_ready_since = None;
-                        (true, RelayRouteMode::Middle, false)
+                        (true, RelayRouteMode::Middle, None)
+                    } else if fast_fallback_enabled {
+                        (
+                            true,
+                            RelayRouteMode::Direct,
+                            Some("fast_not_ready_fallback"),
+                        )
                     } else {
                         let not_ready_started_at = *not_ready_since.get_or_insert(now);
                         let not_ready_for = now.saturating_duration_since(not_ready_started_at);
@@ -72,11 +97,12 @@ pub(crate) async fn configure_admission_gate(
                             STARTUP_FALLBACK_AFTER
                         };
                         if fallback_enabled && not_ready_for > fallback_after {
-                            (true, RelayRouteMode::Direct, true)
+                            (true, RelayRouteMode::Direct, Some("strict_grace_fallback"))
                         } else {
-                            (false, RelayRouteMode::Middle, false)
+                            (false, RelayRouteMode::Middle, None)
                         }
                     };
+                    let next_fallback_active = next_fallback_reason.is_some();
 
                     if next_route_mode != route_mode {
                         route_mode = next_route_mode;
@@ -88,17 +114,28 @@ pub(crate) async fn configure_admission_gate(
                                     "Middle-End routing restored for new sessions"
                                 );
                             } else {
-                                let fallback_after = if ready_observed {
-                                    RUNTIME_FALLBACK_AFTER
+                                let fallback_reason = next_fallback_reason.unwrap_or("unknown");
+                                if fallback_reason == "strict_grace_fallback" {
+                                    let fallback_after = if ready_observed {
+                                        RUNTIME_FALLBACK_AFTER
+                                    } else {
+                                        STARTUP_FALLBACK_AFTER
+                                    };
+                                    warn!(
+                                        target_mode = route_mode.as_str(),
+                                        cutover_generation = snapshot.generation,
+                                        grace_secs = fallback_after.as_secs(),
+                                        fallback_reason,
+                                        "ME pool stayed not-ready beyond grace; routing new sessions via Direct-DC"
+                                    );
                                 } else {
-                                    STARTUP_FALLBACK_AFTER
-                                };
-                                warn!(
-                                    target_mode = route_mode.as_str(),
-                                    cutover_generation = snapshot.generation,
-                                    grace_secs = fallback_after.as_secs(),
-                                    "ME pool stayed not-ready beyond grace; routing new sessions via Direct-DC"
-                                );
+                                    warn!(
+                                        target_mode = route_mode.as_str(),
+                                        cutover_generation = snapshot.generation,
+                                        fallback_reason,
+                                        "ME pool not-ready; routing new sessions via Direct-DC (fast mode)"
+                                    );
+                                }
                             }
                         }
                     }
@@ -108,7 +145,10 @@ pub(crate) async fn configure_admission_gate(
                         admission_tx_gate.send_replace(gate_open);
                         if gate_open {
                             if next_fallback_active {
-                                warn!("Conditional-admission gate opened in ME fallback mode");
+                                warn!(
+                                    fallback_reason = next_fallback_reason.unwrap_or("unknown"),
+                                    "Conditional-admission gate opened in ME fallback mode"
+                                );
                             } else {
                                 info!("Conditional-admission gate opened / ME pool READY");
                             }

src/maestro/connectivity.rs

@@ -1,3 +1,5 @@
+#![allow(clippy::too_many_arguments)]
+
 use std::sync::Arc;
 use std::time::Instant;
 
@@ -11,10 +13,10 @@ use crate::startup::{
     COMPONENT_DC_CONNECTIVITY_PING, COMPONENT_ME_CONNECTIVITY_PING, COMPONENT_RUNTIME_READY,
     StartupTracker,
 };
+use crate::transport::UpstreamManager;
 use crate::transport::middle_proxy::{
     MePingFamily, MePingSample, MePool, format_me_route, format_sample_line, run_me_ping,
 };
-use crate::transport::UpstreamManager;
 
 pub(crate) async fn run_startup_connectivity(
     config: &Arc<ProxyConfig>,
@@ -47,11 +49,15 @@ pub(crate) async fn run_startup_connectivity(
 
         let v4_ok = me_results.iter().any(|r| {
             matches!(r.family, MePingFamily::V4)
-                && r.samples.iter().any(|s| s.error.is_none() && s.handshake_ms.is_some())
+                && r.samples
+                    .iter()
+                    .any(|s| s.error.is_none() && s.handshake_ms.is_some())
         });
         let v6_ok = me_results.iter().any(|r| {
             matches!(r.family, MePingFamily::V6)
-                && r.samples.iter().any(|s| s.error.is_none() && s.handshake_ms.is_some())
+                && r.samples
+                    .iter()
+                    .any(|s| s.error.is_none() && s.handshake_ms.is_some())
         });
 
         info!("================= Telegram ME Connectivity =================");
@@ -131,8 +137,14 @@ pub(crate) async fn run_startup_connectivity(
         .await;
 
     for upstream_result in &ping_results {
-        let v6_works = upstream_result.v6_results.iter().any(|r| r.rtt_ms.is_some());
-        let v4_works = upstream_result.v4_results.iter().any(|r| r.rtt_ms.is_some());
+        let v6_works = upstream_result
+            .v6_results
+            .iter()
+            .any(|r| r.rtt_ms.is_some());
+        let v4_works = upstream_result
+            .v4_results
+            .iter()
+            .any(|r| r.rtt_ms.is_some());
 
         if upstream_result.both_available {
             if prefer_ipv6 {

src/maestro/helpers.rs

@@ -1,16 +1,24 @@
-use std::time::Duration;
+#![allow(clippy::items_after_test_module)]
+
 use std::path::PathBuf;
+use std::time::Duration;
 
 use tokio::sync::watch;
 use tracing::{debug, error, info, warn};
 
 use crate::cli;
 use crate::config::ProxyConfig;
+use crate::logging::LogDestination;
+use crate::transport::UpstreamManager;
 use crate::transport::middle_proxy::{
-    ProxyConfigData, fetch_proxy_config_with_raw, load_proxy_config_cache, save_proxy_config_cache,
+    ProxyConfigData, fetch_proxy_config_with_raw_via_upstream, load_proxy_config_cache,
+    save_proxy_config_cache,
 };
 
-pub(crate) fn resolve_runtime_config_path(config_path_cli: &str, startup_cwd: &std::path::Path) -> PathBuf {
+pub(crate) fn resolve_runtime_config_path(
+    config_path_cli: &str,
+    startup_cwd: &std::path::Path,
+) -> PathBuf {
     let raw = PathBuf::from(config_path_cli);
     let absolute = if raw.is_absolute() {
         raw
@@ -20,7 +28,16 @@ pub(crate) fn resolve_runtime_config_path(config_path_cli: &str, startup_cwd: &s
     absolute.canonicalize().unwrap_or(absolute)
 }
 
-pub(crate) fn parse_cli() -> (String, Option<PathBuf>, bool, Option<String>) {
+/// Parsed CLI arguments.
+pub(crate) struct CliArgs {
+    pub config_path: String,
+    pub data_path: Option<PathBuf>,
+    pub silent: bool,
+    pub log_level: Option<String>,
+    pub log_destination: LogDestination,
+}
+
+pub(crate) fn parse_cli() -> CliArgs {
     let mut config_path = "config.toml".to_string();
     let mut data_path: Option<PathBuf> = None;
     let mut silent = false;
@@ -28,6 +45,9 @@ pub(crate) fn parse_cli() -> (String, Option<PathBuf>, bool, Option<String>) {
 
     let args: Vec<String> = std::env::args().skip(1).collect();
 
+    // Parse log destination
+    let log_destination = crate::logging::parse_log_destination(&args);
+
     // Check for --init first (handled before tokio)
     if let Some(init_opts) = cli::parse_init_args(&args) {
         if let Err(e) = cli::run_init(init_opts) {
@@ -50,7 +70,9 @@ pub(crate) fn parse_cli() -> (String, Option<PathBuf>, bool, Option<String>) {
                 }
             }
             s if s.starts_with("--data-path=") => {
-                data_path = Some(PathBuf::from(s.trim_start_matches("--data-path=").to_string()));
+                data_path = Some(PathBuf::from(
+                    s.trim_start_matches("--data-path=").to_string(),
+                ));
             }
             "--silent" | "-s" => {
                 silent = true;
@@ -65,34 +87,35 @@ pub(crate) fn parse_cli() -> (String, Option<PathBuf>, bool, Option<String>) {
                 log_level = Some(s.trim_start_matches("--log-level=").to_string());
             }
             "--help" | "-h" => {
-                eprintln!("Usage: telemt [config.toml] [OPTIONS]");
-                eprintln!();
-                eprintln!("Options:");
-                eprintln!("  --data-path <DIR>       Set data directory (absolute path; overrides config value)");
-                eprintln!("  --silent, -s            Suppress info logs");
-                eprintln!("  --log-level <LEVEL>     debug|verbose|normal|silent");
-                eprintln!("  --help, -h              Show this help");
-                eprintln!();
-                eprintln!("Setup (fire-and-forget):");
-                eprintln!(
-                    "  --init                  Generate config, install systemd service, start"
-                );
-                eprintln!("    --port <PORT>          Listen port (default: 443)");
-                eprintln!(
-                    "    --domain <DOMAIN>      TLS domain for masking (default: www.google.com)"
-                );
-                eprintln!(
-                    "    --secret <HEX>         32-char hex secret (auto-generated if omitted)"
-                );
-                eprintln!("    --user <NAME>          Username (default: user)");
-                eprintln!("    --config-dir <DIR>     Config directory (default: /etc/telemt)");
-                eprintln!("    --no-start             Don't start the service after install");
+                print_help();
                 std::process::exit(0);
             }
             "--version" | "-V" => {
                 println!("telemt {}", env!("CARGO_PKG_VERSION"));
                 std::process::exit(0);
             }
+            // Skip daemon-related flags (already parsed)
+            "--daemon" | "-d" | "--foreground" | "-f" => {}
+            s if s.starts_with("--pid-file") => {
+                if !s.contains('=') {
+                    i += 1; // skip value
+                }
+            }
+            s if s.starts_with("--run-as-user") => {
+                if !s.contains('=') {
+                    i += 1;
+                }
+            }
+            s if s.starts_with("--run-as-group") => {
+                if !s.contains('=') {
+                    i += 1;
+                }
+            }
+            s if s.starts_with("--working-dir") => {
+                if !s.contains('=') {
+                    i += 1;
+                }
+            }
             s if !s.starts_with('-') => {
                 config_path = s.to_string();
             }
@@ -103,7 +126,77 @@ pub(crate) fn parse_cli() -> (String, Option<PathBuf>, bool, Option<String>) {
         i += 1;
     }
 
-    (config_path, data_path, silent, log_level)
+    CliArgs {
+        config_path,
+        data_path,
+        silent,
+        log_level,
+        log_destination,
+    }
+}
+
+fn print_help() {
+    eprintln!("Usage: telemt [COMMAND] [OPTIONS] [config.toml]");
+    eprintln!();
+    eprintln!("Commands:");
+    eprintln!("  run                     Run in foreground (default if no command given)");
+    #[cfg(unix)]
+    {
+        eprintln!("  start                   Start as background daemon");
+        eprintln!("  stop                    Stop a running daemon");
+        eprintln!("  reload                  Reload configuration (send SIGHUP)");
+        eprintln!("  status                  Check if daemon is running");
+    }
+    eprintln!();
+    eprintln!("Options:");
+    eprintln!("  --data-path <DIR>       Set data directory (absolute path; overrides config value)");
+    eprintln!("  --silent, -s            Suppress info logs");
+    eprintln!("  --log-level <LEVEL>     debug|verbose|normal|silent");
+    eprintln!("  --help, -h              Show this help");
+    eprintln!("  --version, -V           Show version");
+    eprintln!();
+    eprintln!("Logging options:");
+    eprintln!("  --log-file <PATH>       Log to file (default: stderr)");
+    eprintln!("  --log-file-daily <PATH> Log to file with daily rotation");
+    #[cfg(unix)]
+    eprintln!("  --syslog                Log to syslog (Unix only)");
+    eprintln!();
+    #[cfg(unix)]
+    {
+        eprintln!("Daemon options (Unix only):");
+        eprintln!("  --daemon, -d            Fork to background (daemonize)");
+        eprintln!("  --foreground, -f        Explicit foreground mode (for systemd)");
+        eprintln!("  --pid-file <PATH>       PID file path (default: /var/run/telemt.pid)");
+        eprintln!("  --run-as-user <USER>    Drop privileges to this user after binding");
+        eprintln!("  --run-as-group <GROUP>  Drop privileges to this group after binding");
+        eprintln!("  --working-dir <DIR>     Working directory for daemon mode");
+        eprintln!();
+    }
+    eprintln!("Setup (fire-and-forget):");
+    eprintln!(
+        "  --init                  Generate config, install systemd service, start"
+    );
+    eprintln!("    --port <PORT>          Listen port (default: 443)");
+    eprintln!(
+        "    --domain <DOMAIN>      TLS domain for masking (default: www.google.com)"
+    );
+    eprintln!(
+        "    --secret <HEX>         32-char hex secret (auto-generated if omitted)"
+    );
+    eprintln!("    --user <NAME>          Username (default: user)");
+    eprintln!("    --config-dir <DIR>     Config directory (default: /etc/telemt)");
+    eprintln!("    --no-start             Don't start the service after install");
+    #[cfg(unix)]
+    {
+        eprintln!();
+        eprintln!("Examples:");
+        eprintln!("  telemt config.toml                    Run in foreground");
+        eprintln!("  telemt start config.toml              Start as daemon");
+        eprintln!("  telemt start --pid-file /tmp/t.pid    Start with custom PID file");
+        eprintln!("  telemt stop                           Stop daemon");
+        eprintln!("  telemt reload                         Reload configuration");
+        eprintln!("  telemt status                         Check daemon status");
+    }
 }
 
 #[cfg(test)]
@@ -146,7 +239,12 @@ mod tests {
 
 pub(crate) fn print_proxy_links(host: &str, port: u16, config: &ProxyConfig) {
     info!(target: "telemt::links", "--- Proxy Links ({}) ---", host);
-    for user_name in config.general.links.show.resolve_users(&config.access.users) {
+    for user_name in config
+        .general
+        .links
+        .show
+        .resolve_users(&config.access.users)
+    {
         if let Some(secret) = config.access.users.get(user_name) {
             info!(target: "telemt::links", "User: {}", user_name);
             if config.general.modes.classic {
@@ -253,6 +351,7 @@ pub(crate) fn format_uptime(total_secs: u64) -> String {
     format!("{} / {} seconds", parts.join(", "), total_secs)
 }
 
+#[allow(dead_code)]
 pub(crate) async fn wait_until_admission_open(admission_rx: &mut watch::Receiver<bool>) -> bool {
     loop {
         if *admission_rx.borrow() {
@@ -273,9 +372,10 @@ pub(crate) async fn load_startup_proxy_config_snapshot(
     cache_path: Option<&str>,
     me2dc_fallback: bool,
     label: &'static str,
+    upstream: Option<std::sync::Arc<UpstreamManager>>,
 ) -> Option<ProxyConfigData> {
     loop {
-        match fetch_proxy_config_with_raw(url).await {
+        match fetch_proxy_config_with_raw_via_upstream(url, upstream.clone()).await {
             Ok((cfg, raw)) => {
                 if !cfg.map.is_empty() {
                     if let Some(path) = cache_path
@@ -286,7 +386,10 @@ pub(crate) async fn load_startup_proxy_config_snapshot(
                     return Some(cfg);
                 }
 
-                warn!(snapshot = label, url, "Startup proxy-config is empty; trying disk cache");
+                warn!(
+                    snapshot = label,
+                    url, "Startup proxy-config is empty; trying disk cache"
+                );
                 if let Some(path) = cache_path {
                     match load_proxy_config_cache(path).await {
                         Ok(cached) if !cached.map.is_empty() => {
@@ -301,8 +404,7 @@ pub(crate) async fn load_startup_proxy_config_snapshot(
                         Ok(_) => {
                             warn!(
                                 snapshot = label,
-                                path,
-                                "Startup proxy-config cache is empty; ignoring cache file"
+                                path, "Startup proxy-config cache is empty; ignoring cache file"
                             );
                         }
                         Err(cache_err) => {
@@ -346,8 +448,7 @@ pub(crate) async fn load_startup_proxy_config_snapshot(
                         Ok(_) => {
                             warn!(
                                 snapshot = label,
-                                path,
-                                "Startup proxy-config cache is empty; ignoring cache file"
+                                path, "Startup proxy-config cache is empty; ignoring cache file"
                             );
                         }
                         Err(cache_err) => {

src/maestro/listeners.rs

@@ -12,19 +12,17 @@ use tracing::{debug, error, info, warn};
 use crate::config::ProxyConfig;
 use crate::crypto::SecureRandom;
 use crate::ip_tracker::UserIpTracker;
-use crate::proxy::route_mode::{ROUTE_SWITCH_ERROR_MSG, RouteRuntimeController};
 use crate::proxy::ClientHandler;
+use crate::proxy::route_mode::{ROUTE_SWITCH_ERROR_MSG, RouteRuntimeController};
 use crate::startup::{COMPONENT_LISTENERS_BIND, StartupTracker};
 use crate::stats::beobachten::BeobachtenStore;
 use crate::stats::{ReplayChecker, Stats};
 use crate::stream::BufferPool;
 use crate::tls_front::TlsFrontCache;
 use crate::transport::middle_proxy::MePool;
-use crate::transport::{
-    ListenOptions, UpstreamManager, create_listener, find_listener_processes,
-};
+use crate::transport::{ListenOptions, UpstreamManager, create_listener, find_listener_processes};
 
-use super::helpers::{is_expected_handshake_eof, print_proxy_links, wait_until_admission_open};
+use super::helpers::{is_expected_handshake_eof, print_proxy_links};
 
 pub(crate) struct BoundListeners {
     pub(crate) listeners: Vec<(TcpListener, bool)>,
@@ -74,6 +72,7 @@ pub(crate) async fn bind_listeners(
         let options = ListenOptions {
             reuse_port: listener_conf.reuse_allow,
             ipv6_only: listener_conf.ip.is_ipv6(),
+            backlog: config.server.listen_backlog,
             ..Default::default()
         };
 
@@ -81,8 +80,9 @@ pub(crate) async fn bind_listeners(
             Ok(socket) => {
                 let listener = TcpListener::from_std(socket.into())?;
                 info!("Listening on {}", addr);
-                let listener_proxy_protocol =
-                    listener_conf.proxy_protocol.unwrap_or(config.server.proxy_protocol);
+                let listener_proxy_protocol = listener_conf
+                    .proxy_protocol
+                    .unwrap_or(config.server.proxy_protocol);
 
                 let public_host = if let Some(ref announce) = listener_conf.announce {
                     announce.clone()
@@ -100,8 +100,14 @@ pub(crate) async fn bind_listeners(
                     listener_conf.ip.to_string()
                 };
 
-                if config.general.links.public_host.is_none() && !config.general.links.show.is_empty() {
-                    let link_port = config.general.links.public_port.unwrap_or(config.server.port);
+                if config.general.links.public_host.is_none()
+                    && !config.general.links.show.is_empty()
+                {
+                    let link_port = config
+                        .general
+                        .links
+                        .public_port
+                        .unwrap_or(config.server.port);
                     print_proxy_links(&public_host, link_port, config);
                 }
 
@@ -145,12 +151,14 @@ pub(crate) async fn bind_listeners(
         let (host, port) = if let Some(ref h) = config.general.links.public_host {
             (
                 h.clone(),
-                config.general.links.public_port.unwrap_or(config.server.port),
+                config
+                    .general
+                    .links
+                    .public_port
+                    .unwrap_or(config.server.port),
             )
         } else {
-            let ip = detected_ip_v4
-                .or(detected_ip_v6)
-                .map(|ip| ip.to_string());
+            let ip = detected_ip_v4.or(detected_ip_v6).map(|ip| ip.to_string());
             if ip.is_none() {
                 warn!(
                     "show_link is configured but public IP could not be detected. Set public_host in config."
@@ -158,7 +166,11 @@ pub(crate) async fn bind_listeners(
             }
             (
                 ip.unwrap_or_else(|| "UNKNOWN".to_string()),
-                config.general.links.public_port.unwrap_or(config.server.port),
+                config
+                    .general
+                    .links
+                    .public_port
+                    .unwrap_or(config.server.port),
             )
         };
 
@@ -178,13 +190,19 @@ pub(crate) async fn bind_listeners(
                     use std::os::unix::fs::PermissionsExt;
                     let perms = std::fs::Permissions::from_mode(mode);
                     if let Err(e) = std::fs::set_permissions(unix_path, perms) {
-                        error!("Failed to set unix socket permissions to {}: {}", perm_str, e);
+                        error!(
+                            "Failed to set unix socket permissions to {}: {}",
+                            perm_str, e
+                        );
                     } else {
                         info!("Listening on unix:{} (mode {})", unix_path, perm_str);
                     }
                 }
                 Err(e) => {
-                    warn!("Invalid listen_unix_sock_perm '{}': {}. Ignoring.", perm_str, e);
+                    warn!(
+                        "Invalid listen_unix_sock_perm '{}': {}. Ignoring.",
+                        perm_str, e
+                    );
                     info!("Listening on unix:{}", unix_path);
                 }
             }
@@ -195,7 +213,7 @@ pub(crate) async fn bind_listeners(
         has_unix_listener = true;
 
         let mut config_rx_unix: watch::Receiver<Arc<ProxyConfig>> = config_rx.clone();
-        let mut admission_rx_unix = admission_rx.clone();
+        let admission_rx_unix = admission_rx.clone();
         let stats = stats.clone();
         let upstream_manager = upstream_manager.clone();
         let replay_checker = replay_checker.clone();
@@ -212,17 +230,42 @@ pub(crate) async fn bind_listeners(
             let unix_conn_counter = Arc::new(std::sync::atomic::AtomicU64::new(1));
 
             loop {
-                if !wait_until_admission_open(&mut admission_rx_unix).await {
-                    warn!("Conditional-admission gate channel closed for unix listener");
-                    break;
-                }
                 match unix_listener.accept().await {
                     Ok((stream, _)) => {
-                        let permit = match max_connections_unix.clone().acquire_owned().await {
-                            Ok(permit) => permit,
-                            Err(_) => {
-                                error!("Connection limiter is closed");
-                                break;
+                        if !*admission_rx_unix.borrow() {
+                            drop(stream);
+                            continue;
+                        }
+                        let accept_permit_timeout_ms =
+                            config_rx_unix.borrow().server.accept_permit_timeout_ms;
+                        let permit = if accept_permit_timeout_ms == 0 {
+                            match max_connections_unix.clone().acquire_owned().await {
+                                Ok(permit) => permit,
+                                Err(_) => {
+                                    error!("Connection limiter is closed");
+                                    break;
+                                }
+                            }
+                        } else {
+                            match tokio::time::timeout(
+                                Duration::from_millis(accept_permit_timeout_ms),
+                                max_connections_unix.clone().acquire_owned(),
+                            )
+                            .await
+                            {
+                                Ok(Ok(permit)) => permit,
+                                Ok(Err(_)) => {
+                                    error!("Connection limiter is closed");
+                                    break;
+                                }
+                                Err(_) => {
+                                    debug!(
+                                        timeout_ms = accept_permit_timeout_ms,
+                                        "Dropping accepted unix connection: permit wait timeout"
+                                    );
+                                    drop(stream);
+                                    continue;
+                                }
                             }
                         };
                         let conn_id =
@@ -312,7 +355,7 @@ pub(crate) fn spawn_tcp_accept_loops(
 ) {
     for (listener, listener_proxy_protocol) in listeners {
         let mut config_rx: watch::Receiver<Arc<ProxyConfig>> = config_rx.clone();
-        let mut admission_rx_tcp = admission_rx.clone();
+        let admission_rx_tcp = admission_rx.clone();
         let stats = stats.clone();
         let upstream_manager = upstream_manager.clone();
         let replay_checker = replay_checker.clone();
@@ -327,17 +370,44 @@ pub(crate) fn spawn_tcp_accept_loops(
 
         tokio::spawn(async move {
             loop {
-                if !wait_until_admission_open(&mut admission_rx_tcp).await {
-                    warn!("Conditional-admission gate channel closed for tcp listener");
-                    break;
-                }
                 match listener.accept().await {
                     Ok((stream, peer_addr)) => {
-                        let permit = match max_connections_tcp.clone().acquire_owned().await {
-                            Ok(permit) => permit,
-                            Err(_) => {
-                                error!("Connection limiter is closed");
-                                break;
+                        if !*admission_rx_tcp.borrow() {
+                            debug!(peer = %peer_addr, "Admission gate closed, dropping connection");
+                            drop(stream);
+                            continue;
+                        }
+                        let accept_permit_timeout_ms =
+                            config_rx.borrow().server.accept_permit_timeout_ms;
+                        let permit = if accept_permit_timeout_ms == 0 {
+                            match max_connections_tcp.clone().acquire_owned().await {
+                                Ok(permit) => permit,
+                                Err(_) => {
+                                    error!("Connection limiter is closed");
+                                    break;
+                                }
+                            }
+                        } else {
+                            match tokio::time::timeout(
+                                Duration::from_millis(accept_permit_timeout_ms),
+                                max_connections_tcp.clone().acquire_owned(),
+                            )
+                            .await
+                            {
+                                Ok(Ok(permit)) => permit,
+                                Ok(Err(_)) => {
+                                    error!("Connection limiter is closed");
+                                    break;
+                                }
+                                Err(_) => {
+                                    debug!(
+                                        peer = %peer_addr,
+                                        timeout_ms = accept_permit_timeout_ms,
+                                        "Dropping accepted connection: permit wait timeout"
+                                    );
+                                    drop(stream);
+                                    continue;
+                                }
                             }
                         };
                         let config = config_rx.borrow_and_update().clone();

src/maestro/me_startup.rs

@@ -1,3 +1,5 @@
+#![allow(clippy::too_many_arguments)]
+
 use std::sync::Arc;
 use std::time::Duration;
 
@@ -12,8 +14,8 @@ use crate::startup::{
     COMPONENT_ME_PROXY_CONFIG_V6, COMPONENT_ME_SECRET_FETCH, StartupMeStatus, StartupTracker,
 };
 use crate::stats::Stats;
-use crate::transport::middle_proxy::MePool;
 use crate::transport::UpstreamManager;
+use crate::transport::middle_proxy::MePool;
 
 use super::helpers::load_startup_proxy_config_snapshot;
 
@@ -61,9 +63,10 @@ pub(crate) async fn initialize_me_pool(
     let proxy_secret_path = config.general.proxy_secret_path.as_deref();
     let pool_size = config.general.middle_proxy_pool_size.max(1);
     let proxy_secret = loop {
-        match crate::transport::middle_proxy::fetch_proxy_secret(
+        match crate::transport::middle_proxy::fetch_proxy_secret_with_upstream(
             proxy_secret_path,
             config.general.proxy_secret_len_max,
+            Some(upstream_manager.clone()),
         )
         .await
         {
@@ -127,6 +130,7 @@ pub(crate) async fn initialize_me_pool(
                 config.general.proxy_config_v4_cache_path.as_deref(),
                 me2dc_fallback,
                 "getProxyConfig",
+                Some(upstream_manager.clone()),
             )
             .await;
             if cfg_v4.is_some() {
@@ -158,6 +162,7 @@ pub(crate) async fn initialize_me_pool(
                 config.general.proxy_config_v6_cache_path.as_deref(),
                 me2dc_fallback,
                 "getProxyConfigV6",
+                Some(upstream_manager.clone()),
             )
             .await;
             if cfg_v6.is_some() {
@@ -229,15 +234,25 @@ pub(crate) async fn initialize_me_pool(
                     config.general.me_adaptive_floor_recover_grace_secs,
                     config.general.me_adaptive_floor_writers_per_core_total,
                     config.general.me_adaptive_floor_cpu_cores_override,
-                    config.general.me_adaptive_floor_max_extra_writers_single_per_core,
-                    config.general.me_adaptive_floor_max_extra_writers_multi_per_core,
+                    config
+                        .general
+                        .me_adaptive_floor_max_extra_writers_single_per_core,
+                    config
+                        .general
+                        .me_adaptive_floor_max_extra_writers_multi_per_core,
                     config.general.me_adaptive_floor_max_active_writers_per_core,
                     config.general.me_adaptive_floor_max_warm_writers_per_core,
                     config.general.me_adaptive_floor_max_active_writers_global,
                     config.general.me_adaptive_floor_max_warm_writers_global,
                     config.general.hardswap,
                     config.general.me_pool_drain_ttl_secs,
+                    config.general.me_instadrain,
                     config.general.me_pool_drain_threshold,
+                    config.general.me_pool_drain_soft_evict_enabled,
+                    config.general.me_pool_drain_soft_evict_grace_secs,
+                    config.general.me_pool_drain_soft_evict_per_writer,
+                    config.general.me_pool_drain_soft_evict_budget_per_core,
+                    config.general.me_pool_drain_soft_evict_cooldown_ms,
                     config.general.effective_me_pool_force_close_secs(),
                     config.general.me_pool_min_fresh_ratio,
                     config.general.me_hardswap_warmup_delay_min_ms,
@@ -262,6 +277,8 @@ pub(crate) async fn initialize_me_pool(
                     config.general.me_warn_rate_limit_ms,
                     config.general.me_route_no_writer_mode,
                     config.general.me_route_no_writer_wait_ms,
+                    config.general.me_route_hybrid_max_wait_ms,
+                    config.general.me_route_blocking_send_timeout_ms,
                     config.general.me_route_inline_recovery_attempts,
                     config.general.me_route_inline_recovery_wait_ms,
                 );
@@ -324,18 +341,76 @@ pub(crate) async fn initialize_me_pool(
                                             "Middle-End pool initialized successfully"
                                         );
 
-                                        let pool_health = pool_bg.clone();
-                                        let rng_health = rng_bg.clone();
-                                        let min_conns = pool_size;
-                                        tokio::spawn(async move {
-                                            crate::transport::middle_proxy::me_health_monitor(
-                                                pool_health,
-                                                rng_health,
-                                                min_conns,
-                                            )
-                                            .await;
-                                        });
-                                        break;
+                                            // ── Supervised background tasks ──────────────────
+                                            // Each task runs inside a nested tokio::spawn so
+                                            // that a panic is caught via JoinHandle and the
+                                            // outer loop restarts the task automatically.
+                                            let pool_health = pool_bg.clone();
+                                            let rng_health = rng_bg.clone();
+                                            let min_conns = pool_size;
+                                            tokio::spawn(async move {
+                                                loop {
+                                                    let p = pool_health.clone();
+                                                    let r = rng_health.clone();
+                                                    let res = tokio::spawn(async move {
+                                                        crate::transport::middle_proxy::me_health_monitor(
+                                                            p, r, min_conns,
+                                                        )
+                                                        .await;
+                                                    })
+                                                    .await;
+                                                    match res {
+                                                        Ok(()) => warn!("me_health_monitor exited unexpectedly, restarting"),
+                                                        Err(e) => {
+                                                            error!(error = %e, "me_health_monitor panicked, restarting in 1s");
+                                                            tokio::time::sleep(Duration::from_secs(1)).await;
+                                                        }
+                                                    }
+                                                }
+                                            });
+                                            let pool_drain_enforcer = pool_bg.clone();
+                                            tokio::spawn(async move {
+                                                loop {
+                                                    let p = pool_drain_enforcer.clone();
+                                                    let res = tokio::spawn(async move {
+                                                        crate::transport::middle_proxy::me_drain_timeout_enforcer(p).await;
+                                                    })
+                                                    .await;
+                                                    match res {
+                                                        Ok(()) => warn!("me_drain_timeout_enforcer exited unexpectedly, restarting"),
+                                                        Err(e) => {
+                                                            error!(error = %e, "me_drain_timeout_enforcer panicked, restarting in 1s");
+                                                            tokio::time::sleep(Duration::from_secs(1)).await;
+                                                        }
+                                                    }
+                                                }
+                                            });
+                                            let pool_watchdog = pool_bg.clone();
+                                            tokio::spawn(async move {
+                                                loop {
+                                                    let p = pool_watchdog.clone();
+                                                    let res = tokio::spawn(async move {
+                                                        crate::transport::middle_proxy::me_zombie_writer_watchdog(p).await;
+                                                    })
+                                                    .await;
+                                                    match res {
+                                                        Ok(()) => warn!("me_zombie_writer_watchdog exited unexpectedly, restarting"),
+                                                        Err(e) => {
+                                                            error!(error = %e, "me_zombie_writer_watchdog panicked, restarting in 1s");
+                                                            tokio::time::sleep(Duration::from_secs(1)).await;
+                                                        }
+                                                    }
+                                                }
+                                            });
+                                            // CRITICAL: keep the current-thread runtime
+                                            // alive. Without this, block_on() returns,
+                                            // the Runtime is dropped, and ALL spawned
+                                            // background tasks (health monitor, drain
+                                            // enforcer, zombie watchdog) are silently
+                                            // cancelled — causing the draining-writer
+                                            // leak that brought us here.
+                                            std::future::pending::<()>().await;
+                                            unreachable!();
                                     }
                                     Err(e) => {
                                         startup_tracker_bg.set_me_last_error(Some(e.to_string())).await;
@@ -393,14 +468,69 @@ pub(crate) async fn initialize_me_pool(
                                     "Middle-End pool initialized successfully"
                                 );
 
+                                // ── Supervised background tasks ──────────────────
                                 let pool_clone = pool.clone();
                                 let rng_clone = rng.clone();
                                 let min_conns = pool_size;
                                 tokio::spawn(async move {
-                                    crate::transport::middle_proxy::me_health_monitor(
-                                        pool_clone, rng_clone, min_conns,
-                                    )
-                                    .await;
+                                    loop {
+                                        let p = pool_clone.clone();
+                                        let r = rng_clone.clone();
+                                        let res = tokio::spawn(async move {
+                                            crate::transport::middle_proxy::me_health_monitor(
+                                                p, r, min_conns,
+                                            )
+                                            .await;
+                                        })
+                                        .await;
+                                        match res {
+                                            Ok(()) => warn!(
+                                                "me_health_monitor exited unexpectedly, restarting"
+                                            ),
+                                            Err(e) => {
+                                                error!(error = %e, "me_health_monitor panicked, restarting in 1s");
+                                                tokio::time::sleep(Duration::from_secs(1)).await;
+                                            }
+                                        }
+                                    }
+                                });
+                                let pool_drain_enforcer = pool.clone();
+                                tokio::spawn(async move {
+                                    loop {
+                                        let p = pool_drain_enforcer.clone();
+                                        let res = tokio::spawn(async move {
+                                                crate::transport::middle_proxy::me_drain_timeout_enforcer(p).await;
+                                            })
+                                            .await;
+                                        match res {
+                                            Ok(()) => warn!(
+                                                "me_drain_timeout_enforcer exited unexpectedly, restarting"
+                                            ),
+                                            Err(e) => {
+                                                error!(error = %e, "me_drain_timeout_enforcer panicked, restarting in 1s");
+                                                tokio::time::sleep(Duration::from_secs(1)).await;
+                                            }
+                                        }
+                                    }
+                                });
+                                let pool_watchdog = pool.clone();
+                                tokio::spawn(async move {
+                                    loop {
+                                        let p = pool_watchdog.clone();
+                                        let res = tokio::spawn(async move {
+                                                crate::transport::middle_proxy::me_zombie_writer_watchdog(p).await;
+                                            })
+                                            .await;
+                                        match res {
+                                            Ok(()) => warn!(
+                                                "me_zombie_writer_watchdog exited unexpectedly, restarting"
+                                            ),
+                                            Err(e) => {
+                                                error!(error = %e, "me_zombie_writer_watchdog panicked, restarting in 1s");
+                                                tokio::time::sleep(Duration::from_secs(1)).await;
+                                            }
+                                        }
+                                    }
                                 });
 
                                 break Some(pool);

src/maestro/mod.rs

@@ -11,9 +11,9 @@
 // - admission: conditional-cast gate and route mode switching.
 // - listeners: TCP/Unix listener bind and accept-loop orchestration.
 // - shutdown: graceful shutdown sequence and uptime logging.
-mod helpers;
 mod admission;
 mod connectivity;
+mod helpers;
 mod listeners;
 mod me_startup;
 mod runtime_tasks;
@@ -33,22 +33,70 @@ use crate::crypto::SecureRandom;
 use crate::ip_tracker::UserIpTracker;
 use crate::network::probe::{decide_network_capabilities, log_probe_result, run_probe};
 use crate::proxy::route_mode::{RelayRouteMode, RouteRuntimeController};
+use crate::startup::{
+    COMPONENT_API_BOOTSTRAP, COMPONENT_CONFIG_LOAD, COMPONENT_ME_POOL_CONSTRUCT,
+    COMPONENT_ME_POOL_INIT_STAGE1, COMPONENT_ME_PROXY_CONFIG_V4, COMPONENT_ME_PROXY_CONFIG_V6,
+    COMPONENT_ME_SECRET_FETCH, COMPONENT_NETWORK_PROBE, COMPONENT_TRACING_INIT, StartupMeStatus,
+    StartupTracker,
+};
 use crate::stats::beobachten::BeobachtenStore;
 use crate::stats::telemetry::TelemetryPolicy;
 use crate::stats::{ReplayChecker, Stats};
-use crate::startup::{
-    COMPONENT_API_BOOTSTRAP, COMPONENT_CONFIG_LOAD,
-    COMPONENT_ME_POOL_CONSTRUCT, COMPONENT_ME_POOL_INIT_STAGE1,
-    COMPONENT_ME_PROXY_CONFIG_V4, COMPONENT_ME_PROXY_CONFIG_V6, COMPONENT_ME_SECRET_FETCH,
-    COMPONENT_NETWORK_PROBE, COMPONENT_TRACING_INIT, StartupMeStatus, StartupTracker,
-};
 use crate::stream::BufferPool;
-use crate::transport::middle_proxy::MePool;
 use crate::transport::UpstreamManager;
+use crate::transport::middle_proxy::MePool;
 use helpers::{parse_cli, resolve_runtime_config_path};
 
+#[cfg(unix)]
+use crate::daemon::{DaemonOptions, PidFile, drop_privileges};
+
 /// Runs the full telemt runtime startup pipeline and blocks until shutdown.
+///
+/// On Unix, daemon options should be handled before calling this function
+/// (daemonization must happen before tokio runtime starts).
+#[cfg(unix)]
+pub async fn run_with_daemon(
+    daemon_opts: DaemonOptions,
+) -> std::result::Result<(), Box<dyn std::error::Error>> {
+    run_inner(daemon_opts).await
+}
+
+/// Runs the full telemt runtime startup pipeline and blocks until shutdown.
+///
+/// This is the main entry point for non-daemon mode or when called as a library.
+#[allow(dead_code)]
 pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
+    #[cfg(unix)]
+    {
+        // Parse CLI to get daemon options even in simple run() path
+        let args: Vec<String> = std::env::args().skip(1).collect();
+        let daemon_opts = crate::cli::parse_daemon_args(&args);
+        run_inner(daemon_opts).await
+    }
+    #[cfg(not(unix))]
+    {
+        run_inner().await
+    }
+}
+
+#[cfg(unix)]
+async fn run_inner(
+    daemon_opts: DaemonOptions,
+) -> std::result::Result<(), Box<dyn std::error::Error>> {
+
+    // Acquire PID file if daemonizing or if explicitly requested
+    // Keep it alive until shutdown (underscore prefix = intentionally kept for RAII cleanup)
+    let _pid_file = if daemon_opts.daemonize || daemon_opts.pid_file.is_some() {
+        let mut pf = PidFile::new(daemon_opts.pid_file_path());
+        if let Err(e) = pf.acquire() {
+            eprintln!("[telemt] {}", e);
+            std::process::exit(1);
+        }
+        Some(pf)
+    } else {
+        None
+    };
+
     let process_started_at = Instant::now();
     let process_started_at_epoch_secs = SystemTime::now()
         .duration_since(UNIX_EPOCH)
@@ -56,9 +104,17 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
         .as_secs();
     let startup_tracker = Arc::new(StartupTracker::new(process_started_at_epoch_secs));
     startup_tracker
-        .start_component(COMPONENT_CONFIG_LOAD, Some("load and validate config".to_string()))
+        .start_component(
+            COMPONENT_CONFIG_LOAD,
+            Some("load and validate config".to_string()),
+        )
         .await;
-    let (config_path_cli, data_path, cli_silent, cli_log_level) = parse_cli();
+    let cli_args = parse_cli();
+    let config_path_cli = cli_args.config_path;
+    let data_path = cli_args.data_path;
+    let cli_silent = cli_args.silent;
+    let cli_log_level = cli_args.log_level;
+    let log_destination = cli_args.log_destination;
     let startup_cwd = match std::env::current_dir() {
         Ok(cwd) => cwd,
         Err(e) => {
@@ -77,7 +133,10 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
             } else {
                 let default = ProxyConfig::default();
                 std::fs::write(&config_path, toml::to_string_pretty(&default).unwrap()).unwrap();
-                eprintln!("[telemt] Created default config at {}", config_path.display());
+                eprintln!(
+                    "[telemt] Created default config at {}",
+                    config_path.display()
+                );
                 default
             }
         }
@@ -94,24 +153,36 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
 
     if let Some(ref data_path) = config.general.data_path {
         if !data_path.is_absolute() {
-            eprintln!("[telemt] data_path must be absolute: {}", data_path.display());
+            eprintln!(
+                "[telemt] data_path must be absolute: {}",
+                data_path.display()
+            );
             std::process::exit(1);
         }
 
         if data_path.exists() {
             if !data_path.is_dir() {
-                eprintln!("[telemt] data_path exists but is not a directory: {}", data_path.display());
-                std::process::exit(1);
-            }
-        } else {
-            if let Err(e) = std::fs::create_dir_all(data_path) {
-                eprintln!("[telemt] Can't create data_path {}: {}", data_path.display(), e);
+                eprintln!(
+                    "[telemt] data_path exists but is not a directory: {}",
+                    data_path.display()
+                );
                 std::process::exit(1);
             }
+        } else if let Err(e) = std::fs::create_dir_all(data_path) {
+            eprintln!(
+                "[telemt] Can't create data_path {}: {}",
+                data_path.display(),
+                e
+            );
+            std::process::exit(1);
         }
 
         if let Err(e) = std::env::set_current_dir(data_path) {
-            eprintln!("[telemt] Can't use data_path {}: {}", data_path.display(), e);
+            eprintln!(
+                "[telemt] Can't use data_path {}: {}",
+                data_path.display(),
+                e
+            );
             std::process::exit(1);
         }
     }
@@ -135,22 +206,54 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
 
     let (filter_layer, filter_handle) = reload::Layer::new(EnvFilter::new("info"));
     startup_tracker
-        .start_component(COMPONENT_TRACING_INIT, Some("initialize tracing subscriber".to_string()))
+        .start_component(
+            COMPONENT_TRACING_INIT,
+            Some("initialize tracing subscriber".to_string()),
+        )
         .await;
 
-    // Configure color output based on config
-    let fmt_layer = if config.general.disable_colors {
-        fmt::Layer::default().with_ansi(false)
-    } else {
-        fmt::Layer::default().with_ansi(true)
-    };
+    // Initialize logging based on destination
+    let _logging_guard: Option<crate::logging::LoggingGuard>;
+    match log_destination {
+        crate::logging::LogDestination::Stderr => {
+            // Default: log to stderr (works with systemd journald)
+            let fmt_layer = if config.general.disable_colors {
+                fmt::Layer::default().with_ansi(false)
+            } else {
+                fmt::Layer::default().with_ansi(true)
+            };
+            tracing_subscriber::registry()
+                .with(filter_layer)
+                .with(fmt_layer)
+                .init();
+            _logging_guard = None;
+        }
+        #[cfg(unix)]
+        crate::logging::LogDestination::Syslog => {
+            // Syslog: for OpenRC/FreeBSD
+            let logging_opts = crate::logging::LoggingOptions {
+                destination: log_destination,
+                disable_colors: true,
+            };
+            let (_, guard) = crate::logging::init_logging(&logging_opts, "info");
+            _logging_guard = Some(guard);
+        }
+        crate::logging::LogDestination::File { .. } => {
+            // File logging with optional rotation
+            let logging_opts = crate::logging::LoggingOptions {
+                destination: log_destination,
+                disable_colors: true,
+            };
+            let (_, guard) = crate::logging::init_logging(&logging_opts, "info");
+            _logging_guard = Some(guard);
+        }
+    }
 
-    tracing_subscriber::registry()
-        .with(filter_layer)
-        .with(fmt_layer)
-        .init();
     startup_tracker
-        .complete_component(COMPONENT_TRACING_INIT, Some("tracing initialized".to_string()))
+        .complete_component(
+            COMPONENT_TRACING_INIT,
+            Some("tracing initialized".to_string()),
+        )
         .await;
 
     info!("Telemt MTProxy v{}", env!("CARGO_PKG_VERSION"));
@@ -199,6 +302,7 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
         config.general.upstream_connect_retry_attempts,
         config.general.upstream_connect_retry_backoff_ms,
         config.general.upstream_connect_budget_ms,
+        config.general.tg_connect,
         config.general.upstream_unhealthy_fail_threshold,
         config.general.upstream_connect_failfast_hard_errors,
         stats.clone(),
@@ -216,7 +320,8 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
             config.access.user_max_unique_ips_window_secs,
         )
         .await;
-    if config.access.user_max_unique_ips_global_each > 0 || !config.access.user_max_unique_ips.is_empty()
+    if config.access.user_max_unique_ips_global_each > 0
+        || !config.access.user_max_unique_ips.is_empty()
     {
         info!(
             global_each_limit = config.access.user_max_unique_ips_global_each,
@@ -243,7 +348,10 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
     let route_runtime = Arc::new(RouteRuntimeController::new(initial_route_mode));
     let api_me_pool = Arc::new(RwLock::new(None::<Arc<MePool>>));
     startup_tracker
-        .start_component(COMPONENT_API_BOOTSTRAP, Some("spawn API listener task".to_string()))
+        .start_component(
+            COMPONENT_API_BOOTSTRAP,
+            Some("spawn API listener task".to_string()),
+        )
         .await;
 
     if config.server.api.enabled {
@@ -326,7 +434,10 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
     .await;
 
     startup_tracker
-        .start_component(COMPONENT_NETWORK_PROBE, Some("probe network capabilities".to_string()))
+        .start_component(
+            COMPONENT_NETWORK_PROBE,
+            Some("probe network capabilities".to_string()),
+        )
         .await;
     let probe = run_probe(
         &config.network,
@@ -339,11 +450,8 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
         probe.detected_ipv4.map(IpAddr::V4),
         probe.detected_ipv6.map(IpAddr::V6),
     ));
-    let decision = decide_network_capabilities(
-        &config.network,
-        &probe,
-        config.general.middle_proxy_nat_ip,
-    );
+    let decision =
+        decide_network_capabilities(&config.network, &probe, config.general.middle_proxy_nat_ip);
     log_probe_result(&probe, &decision);
     startup_tracker
         .complete_component(
@@ -446,24 +554,16 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
 
     // If ME failed to initialize, force direct-only mode.
     if me_pool.is_some() {
-        startup_tracker
-            .set_transport_mode("middle_proxy")
-            .await;
-        startup_tracker
-            .set_degraded(false)
-            .await;
+        startup_tracker.set_transport_mode("middle_proxy").await;
+        startup_tracker.set_degraded(false).await;
         info!("Transport: Middle-End Proxy - all DC-over-RPC");
     } else {
         let _ = use_middle_proxy;
         use_middle_proxy = false;
         // Make runtime config reflect direct-only mode for handlers.
         config.general.use_middle_proxy = false;
-        startup_tracker
-            .set_transport_mode("direct")
-            .await;
-        startup_tracker
-            .set_degraded(true)
-            .await;
+        startup_tracker.set_transport_mode("direct").await;
+        startup_tracker.set_degraded(true).await;
         if me2dc_fallback {
             startup_tracker
                 .set_me_status(StartupMeStatus::Failed, "fallback_to_direct")
@@ -484,7 +584,7 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
         Duration::from_secs(config.access.replay_window_secs),
     ));
 
-    let buffer_pool = Arc::new(BufferPool::with_config(16 * 1024, 4096));
+    let buffer_pool = Arc::new(BufferPool::with_config(64 * 1024, 4096));
 
     connectivity::run_startup_connectivity(
         &config,
@@ -563,6 +663,17 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
         std::process::exit(1);
     }
 
+    // Drop privileges after binding sockets (which may require root for port < 1024)
+    if daemon_opts.user.is_some() || daemon_opts.group.is_some() {
+        if let Err(e) = drop_privileges(
+            daemon_opts.user.as_deref(),
+            daemon_opts.group.as_deref(),
+        ) {
+            error!(error = %e, "Failed to drop privileges");
+            std::process::exit(1);
+        }
+    }
+
     runtime_tasks::apply_runtime_log_filter(
         has_rust_log,
         &effective_log_level,
@@ -583,6 +694,9 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
 
     runtime_tasks::mark_runtime_ready(&startup_tracker).await;
 
+    // Spawn signal handlers for SIGUSR1/SIGUSR2 (non-shutdown signals)
+    shutdown::spawn_signal_handlers(stats.clone(), process_started_at);
+
     listeners::spawn_tcp_accept_loops(
         listeners,
         config_rx.clone(),
@@ -600,7 +714,7 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
         max_connections.clone(),
     );
 
-    shutdown::wait_for_shutdown(process_started_at, me_pool).await;
+    shutdown::wait_for_shutdown(process_started_at, me_pool, stats).await;
 
     Ok(())
 }

src/maestro/runtime_tasks.rs

@@ -4,21 +4,24 @@ use std::sync::Arc;
 
 use tokio::sync::{mpsc, watch};
 use tracing::{debug, warn};
-use tracing_subscriber::reload;
 use tracing_subscriber::EnvFilter;
+use tracing_subscriber::reload;
 
-use crate::config::{LogLevel, ProxyConfig};
 use crate::config::hot_reload::spawn_config_watcher;
+use crate::config::{LogLevel, ProxyConfig};
 use crate::crypto::SecureRandom;
 use crate::ip_tracker::UserIpTracker;
 use crate::metrics;
 use crate::network::probe::NetworkProbe;
-use crate::startup::{COMPONENT_CONFIG_WATCHER_START, COMPONENT_METRICS_START, COMPONENT_RUNTIME_READY, StartupTracker};
+use crate::startup::{
+    COMPONENT_CONFIG_WATCHER_START, COMPONENT_METRICS_START, COMPONENT_RUNTIME_READY,
+    StartupTracker,
+};
 use crate::stats::beobachten::BeobachtenStore;
 use crate::stats::telemetry::TelemetryPolicy;
 use crate::stats::{ReplayChecker, Stats};
-use crate::transport::middle_proxy::{MePool, MeReinitTrigger};
 use crate::transport::UpstreamManager;
+use crate::transport::middle_proxy::{MePool, MeReinitTrigger};
 
 use super::helpers::write_beobachten_snapshot;
 
@@ -79,15 +82,13 @@ pub(crate) async fn spawn_runtime_tasks(
             Some("spawn config hot-reload watcher".to_string()),
         )
         .await;
-    let (config_rx, log_level_rx): (
-        watch::Receiver<Arc<ProxyConfig>>,
-        watch::Receiver<LogLevel>,
-    ) = spawn_config_watcher(
-        config_path.to_path_buf(),
-        config.clone(),
-        detected_ip_v4,
-        detected_ip_v6,
-    );
+    let (config_rx, log_level_rx): (watch::Receiver<Arc<ProxyConfig>>, watch::Receiver<LogLevel>) =
+        spawn_config_watcher(
+            config_path.to_path_buf(),
+            config.clone(),
+            detected_ip_v4,
+            detected_ip_v6,
+        );
     startup_tracker
         .complete_component(
             COMPONENT_CONFIG_WATCHER_START,
@@ -114,7 +115,8 @@ pub(crate) async fn spawn_runtime_tasks(
                 break;
             }
             let cfg = config_rx_policy.borrow_and_update().clone();
-            stats_policy.apply_telemetry_policy(TelemetryPolicy::from_config(&cfg.general.telemetry));
+            stats_policy
+                .apply_telemetry_policy(TelemetryPolicy::from_config(&cfg.general.telemetry));
             if let Some(pool) = &me_pool_for_policy {
                 pool.update_runtime_transport_policy(
                     cfg.general.me_socks_kdf_policy,
@@ -130,7 +132,11 @@ pub(crate) async fn spawn_runtime_tasks(
     let ip_tracker_policy = ip_tracker.clone();
     let mut config_rx_ip_limits = config_rx.clone();
     tokio::spawn(async move {
-        let mut prev_limits = config_rx_ip_limits.borrow().access.user_max_unique_ips.clone();
+        let mut prev_limits = config_rx_ip_limits
+            .borrow()
+            .access
+            .user_max_unique_ips
+            .clone();
         let mut prev_global_each = config_rx_ip_limits
             .borrow()
             .access
@@ -183,7 +189,9 @@ pub(crate) async fn spawn_runtime_tasks(
             let sleep_secs = cfg.general.beobachten_flush_secs.max(1);
 
             if cfg.general.beobachten {
-                let ttl = std::time::Duration::from_secs(cfg.general.beobachten_minutes.saturating_mul(60));
+                let ttl = std::time::Duration::from_secs(
+                    cfg.general.beobachten_minutes.saturating_mul(60),
+                );
                 let path = cfg.general.beobachten_file.clone();
                 let snapshot = beobachten_writer.snapshot_text(ttl);
                 if let Err(e) = write_beobachten_snapshot(&path, &snapshot).await {
@@ -227,8 +235,11 @@ pub(crate) async fn spawn_runtime_tasks(
         let config_rx_clone_rot = config_rx.clone();
         let reinit_tx_rotation = reinit_tx.clone();
         tokio::spawn(async move {
-            crate::transport::middle_proxy::me_rotation_task(config_rx_clone_rot, reinit_tx_rotation)
-                .await;
+            crate::transport::middle_proxy::me_rotation_task(
+                config_rx_clone_rot,
+                reinit_tx_rotation,
+            )
+            .await;
         });
     }
 
@@ -279,11 +290,32 @@ pub(crate) async fn spawn_metrics_if_configured(
     ip_tracker: Arc<UserIpTracker>,
     config_rx: watch::Receiver<Arc<ProxyConfig>>,
 ) {
-    if let Some(port) = config.server.metrics_port {
+    // metrics_listen takes precedence; fall back to metrics_port for backward compat.
+    let metrics_target: Option<(u16, Option<String>)> =
+        if let Some(ref listen) = config.server.metrics_listen {
+            match listen.parse::<std::net::SocketAddr>() {
+                Ok(addr) => Some((addr.port(), Some(listen.clone()))),
+                Err(e) => {
+                    startup_tracker
+                        .skip_component(
+                            COMPONENT_METRICS_START,
+                            Some(format!("invalid metrics_listen \"{}\": {}", listen, e)),
+                        )
+                        .await;
+                    None
+                }
+            }
+        } else {
+            config.server.metrics_port.map(|p| (p, None))
+        };
+
+    if let Some((port, listen)) = metrics_target {
+        let fallback_label = format!("port {}", port);
+        let label = listen.as_deref().unwrap_or(&fallback_label);
         startup_tracker
             .start_component(
                 COMPONENT_METRICS_START,
-                Some(format!("spawn metrics endpoint on {}", port)),
+                Some(format!("spawn metrics endpoint on {}", label)),
             )
             .await;
         let stats = stats.clone();
@@ -291,9 +323,12 @@ pub(crate) async fn spawn_metrics_if_configured(
         let config_rx_metrics = config_rx.clone();
         let ip_tracker_metrics = ip_tracker.clone();
         let whitelist = config.server.metrics_whitelist.clone();
+        let listen_backlog = config.server.listen_backlog;
         tokio::spawn(async move {
             metrics::serve(
                 port,
+                listen,
+                listen_backlog,
                 stats,
                 beobachten,
                 ip_tracker_metrics,
@@ -308,7 +343,7 @@ pub(crate) async fn spawn_metrics_if_configured(
                 Some("metrics task spawned".to_string()),
             )
             .await;
-    } else {
+    } else if config.server.metrics_listen.is_none() {
         startup_tracker
             .skip_component(
                 COMPONENT_METRICS_START,

src/maestro/shutdown.rs

@@ -1,42 +1,211 @@
+//! Shutdown and signal handling for telemt.
+//!
+//! Handles graceful shutdown on various signals:
+//! - SIGINT (Ctrl+C) / SIGTERM: Graceful shutdown
+//! - SIGQUIT: Graceful shutdown with stats dump
+//! - SIGUSR1: Reserved for log rotation (logs acknowledgment)
+//! - SIGUSR2: Dump runtime status to log
+//!
+//! SIGHUP is handled separately in config/hot_reload.rs for config reload.
+
 use std::sync::Arc;
 use std::time::{Duration, Instant};
 
+#[cfg(unix)]
+use tokio::signal::unix::{SignalKind, signal};
+#[cfg(not(unix))]
 use tokio::signal;
-use tracing::{error, info, warn};
+use tracing::{info, warn};
 
+use crate::stats::Stats;
 use crate::transport::middle_proxy::MePool;
 
 use super::helpers::{format_uptime, unit_label};
 
-pub(crate) async fn wait_for_shutdown(process_started_at: Instant, me_pool: Option<Arc<MePool>>) {
-    match signal::ctrl_c().await {
-        Ok(()) => {
-            let shutdown_started_at = Instant::now();
-            info!("Shutting down...");
-            let uptime_secs = process_started_at.elapsed().as_secs();
-            info!("Uptime: {}", format_uptime(uptime_secs));
-            if let Some(pool) = &me_pool {
-                match tokio::time::timeout(Duration::from_secs(2), pool.shutdown_send_close_conn_all())
-                    .await
-                {
-                    Ok(total) => {
-                        info!(
-                            close_conn_sent = total,
-                            "ME shutdown: RPC_CLOSE_CONN broadcast completed"
-                        );
-                    }
-                    Err(_) => {
-                        warn!("ME shutdown: RPC_CLOSE_CONN broadcast timed out");
-                    }
-                }
-            }
-            let shutdown_secs = shutdown_started_at.elapsed().as_secs();
-            info!(
-                "Shutdown completed successfully in {} {}.",
-                shutdown_secs,
-                unit_label(shutdown_secs, "second", "seconds")
-            );
+/// Signal that triggered shutdown.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ShutdownSignal {
+    /// SIGINT (Ctrl+C)
+    Interrupt,
+    /// SIGTERM
+    Terminate,
+    /// SIGQUIT (with stats dump)
+    Quit,
+}
+
+impl std::fmt::Display for ShutdownSignal {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ShutdownSignal::Interrupt => write!(f, "SIGINT"),
+            ShutdownSignal::Terminate => write!(f, "SIGTERM"),
+            ShutdownSignal::Quit => write!(f, "SIGQUIT"),
         }
-        Err(e) => error!("Signal error: {}", e),
     }
 }
+
+/// Waits for a shutdown signal and performs graceful shutdown.
+pub(crate) async fn wait_for_shutdown(
+    process_started_at: Instant,
+    me_pool: Option<Arc<MePool>>,
+    stats: Arc<Stats>,
+) {
+    let signal = wait_for_shutdown_signal().await;
+    perform_shutdown(signal, process_started_at, me_pool, &stats).await;
+}
+
+/// Waits for any shutdown signal (SIGINT, SIGTERM, SIGQUIT).
+#[cfg(unix)]
+async fn wait_for_shutdown_signal() -> ShutdownSignal {
+    let mut sigint = signal(SignalKind::interrupt()).expect("Failed to register SIGINT handler");
+    let mut sigterm = signal(SignalKind::terminate()).expect("Failed to register SIGTERM handler");
+    let mut sigquit = signal(SignalKind::quit()).expect("Failed to register SIGQUIT handler");
+
+    tokio::select! {
+        _ = sigint.recv() => ShutdownSignal::Interrupt,
+        _ = sigterm.recv() => ShutdownSignal::Terminate,
+        _ = sigquit.recv() => ShutdownSignal::Quit,
+    }
+}
+
+#[cfg(not(unix))]
+async fn wait_for_shutdown_signal() -> ShutdownSignal {
+    signal::ctrl_c().await.expect("Failed to listen for Ctrl+C");
+    ShutdownSignal::Interrupt
+}
+
+/// Performs graceful shutdown sequence.
+async fn perform_shutdown(
+    signal: ShutdownSignal,
+    process_started_at: Instant,
+    me_pool: Option<Arc<MePool>>,
+    stats: &Stats,
+) {
+    let shutdown_started_at = Instant::now();
+    info!(signal = %signal, "Received shutdown signal");
+
+    // Dump stats if SIGQUIT
+    if signal == ShutdownSignal::Quit {
+        dump_stats(stats, process_started_at);
+    }
+
+    info!("Shutting down...");
+    let uptime_secs = process_started_at.elapsed().as_secs();
+    info!("Uptime: {}", format_uptime(uptime_secs));
+
+    // Graceful ME pool shutdown
+    if let Some(pool) = &me_pool {
+        match tokio::time::timeout(Duration::from_secs(2), pool.shutdown_send_close_conn_all()).await
+        {
+            Ok(total) => {
+                info!(
+                    close_conn_sent = total,
+                    "ME shutdown: RPC_CLOSE_CONN broadcast completed"
+                );
+            }
+            Err(_) => {
+                warn!("ME shutdown: RPC_CLOSE_CONN broadcast timed out");
+            }
+        }
+    }
+
+    let shutdown_secs = shutdown_started_at.elapsed().as_secs();
+    info!(
+        "Shutdown completed successfully in {} {}.",
+        shutdown_secs,
+        unit_label(shutdown_secs, "second", "seconds")
+    );
+}
+
+/// Dumps runtime statistics to the log.
+fn dump_stats(stats: &Stats, process_started_at: Instant) {
+    let uptime_secs = process_started_at.elapsed().as_secs();
+
+    info!("=== Runtime Statistics Dump ===");
+    info!("Uptime: {}", format_uptime(uptime_secs));
+
+    // Connection stats
+    info!(
+        "Connections: total={}, current={} (direct={}, me={}), bad={}",
+        stats.get_connects_all(),
+        stats.get_current_connections_total(),
+        stats.get_current_connections_direct(),
+        stats.get_current_connections_me(),
+        stats.get_connects_bad(),
+    );
+
+    // ME pool stats
+    info!(
+        "ME keepalive: sent={}, pong={}, failed={}, timeout={}",
+        stats.get_me_keepalive_sent(),
+        stats.get_me_keepalive_pong(),
+        stats.get_me_keepalive_failed(),
+        stats.get_me_keepalive_timeout(),
+    );
+
+    // Relay stats
+    info!(
+        "Relay idle: soft_mark={}, hard_close={}, pressure_evict={}",
+        stats.get_relay_idle_soft_mark_total(),
+        stats.get_relay_idle_hard_close_total(),
+        stats.get_relay_pressure_evict_total(),
+    );
+
+    info!("=== End Statistics Dump ===");
+}
+
+/// Spawns a background task to handle operational signals (SIGUSR1, SIGUSR2).
+///
+/// These signals don't trigger shutdown but perform specific actions:
+/// - SIGUSR1: Log rotation acknowledgment (for external log rotation tools)
+/// - SIGUSR2: Dump runtime status to log
+#[cfg(unix)]
+pub(crate) fn spawn_signal_handlers(
+    stats: Arc<Stats>,
+    process_started_at: Instant,
+) {
+    tokio::spawn(async move {
+        let mut sigusr1 = signal(SignalKind::user_defined1())
+            .expect("Failed to register SIGUSR1 handler");
+        let mut sigusr2 = signal(SignalKind::user_defined2())
+            .expect("Failed to register SIGUSR2 handler");
+
+        loop {
+            tokio::select! {
+                _ = sigusr1.recv() => {
+                    handle_sigusr1();
+                }
+                _ = sigusr2.recv() => {
+                    handle_sigusr2(&stats, process_started_at);
+                }
+            }
+        }
+    });
+}
+
+/// No-op on non-Unix platforms.
+#[cfg(not(unix))]
+pub(crate) fn spawn_signal_handlers(
+    _stats: Arc<Stats>,
+    _process_started_at: Instant,
+) {
+    // No SIGUSR1/SIGUSR2 on non-Unix
+}
+
+/// Handles SIGUSR1 - log rotation signal.
+///
+/// This signal is typically sent by logrotate or similar tools after
+/// rotating log files. Since tracing-subscriber doesn't natively support
+/// reopening files, we just acknowledge the signal. If file logging is
+/// added in the future, this would reopen log file handles.
+#[cfg(unix)]
+fn handle_sigusr1() {
+    info!("SIGUSR1 received - log rotation acknowledged");
+    // Future: If using file-based logging, reopen file handles here
+}
+
+/// Handles SIGUSR2 - dump runtime status.
+#[cfg(unix)]
+fn handle_sigusr2(stats: &Stats, process_started_at: Instant) {
+    info!("SIGUSR2 received - dumping runtime status");
+    dump_stats(stats, process_started_at);
+}

src/maestro/tls_bootstrap.rs

@@ -1,12 +1,13 @@
 use std::sync::Arc;
 use std::time::Duration;
 
-use rand::Rng;
+use rand::RngExt;
 use tracing::warn;
 
 use crate::config::ProxyConfig;
 use crate::startup::{COMPONENT_TLS_FRONT_BOOTSTRAP, StartupTracker};
 use crate::tls_front::TlsFrontCache;
+use crate::tls_front::fetcher::TlsFetchStrategy;
 use crate::transport::UpstreamManager;
 
 pub(crate) async fn bootstrap_tls_front(
@@ -38,27 +39,44 @@ pub(crate) async fn bootstrap_tls_front(
             .clone()
             .unwrap_or_else(|| config.censorship.tls_domain.clone());
         let mask_unix_sock = config.censorship.mask_unix_sock.clone();
-        let fetch_timeout = Duration::from_secs(5);
+        let tls_fetch_scope = (!config.censorship.tls_fetch_scope.is_empty())
+            .then(|| config.censorship.tls_fetch_scope.clone());
+        let tls_fetch = config.censorship.tls_fetch.clone();
+        let fetch_strategy = TlsFetchStrategy {
+            profiles: tls_fetch.profiles,
+            strict_route: tls_fetch.strict_route,
+            attempt_timeout: Duration::from_millis(tls_fetch.attempt_timeout_ms.max(1)),
+            total_budget: Duration::from_millis(tls_fetch.total_budget_ms.max(1)),
+            grease_enabled: tls_fetch.grease_enabled,
+            deterministic: tls_fetch.deterministic,
+            profile_cache_ttl: Duration::from_secs(tls_fetch.profile_cache_ttl_secs),
+        };
+        let fetch_timeout = fetch_strategy.total_budget;
 
         let cache_initial = cache.clone();
         let domains_initial = tls_domains.to_vec();
         let host_initial = mask_host.clone();
         let unix_sock_initial = mask_unix_sock.clone();
+        let scope_initial = tls_fetch_scope.clone();
         let upstream_initial = upstream_manager.clone();
+        let strategy_initial = fetch_strategy.clone();
         tokio::spawn(async move {
             let mut join = tokio::task::JoinSet::new();
             for domain in domains_initial {
                 let cache_domain = cache_initial.clone();
                 let host_domain = host_initial.clone();
                 let unix_sock_domain = unix_sock_initial.clone();
+                let scope_domain = scope_initial.clone();
                 let upstream_domain = upstream_initial.clone();
+                let strategy_domain = strategy_initial.clone();
                 join.spawn(async move {
-                    match crate::tls_front::fetcher::fetch_real_tls(
+                    match crate::tls_front::fetcher::fetch_real_tls_with_strategy(
                         &host_domain,
                         port,
                         &domain,
-                        fetch_timeout,
+                        &strategy_domain,
                         Some(upstream_domain),
+                        scope_domain.as_deref(),
                         proxy_protocol,
                         unix_sock_domain.as_deref(),
                     )
@@ -100,7 +118,9 @@ pub(crate) async fn bootstrap_tls_front(
         let domains_refresh = tls_domains.to_vec();
         let host_refresh = mask_host.clone();
         let unix_sock_refresh = mask_unix_sock.clone();
+        let scope_refresh = tls_fetch_scope.clone();
         let upstream_refresh = upstream_manager.clone();
+        let strategy_refresh = fetch_strategy.clone();
         tokio::spawn(async move {
             loop {
                 let base_secs = rand::rng().random_range(4 * 3600..=6 * 3600);
@@ -112,14 +132,17 @@ pub(crate) async fn bootstrap_tls_front(
                     let cache_domain = cache_refresh.clone();
                     let host_domain = host_refresh.clone();
                     let unix_sock_domain = unix_sock_refresh.clone();
+                    let scope_domain = scope_refresh.clone();
                     let upstream_domain = upstream_refresh.clone();
+                    let strategy_domain = strategy_refresh.clone();
                     join.spawn(async move {
-                        match crate::tls_front::fetcher::fetch_real_tls(
+                        match crate::tls_front::fetcher::fetch_real_tls_with_strategy(
                             &host_domain,
                             port,
                             &domain,
-                            fetch_timeout,
+                            &strategy_domain,
                             Some(upstream_domain),
+                            scope_domain.as_deref(),
                             proxy_protocol,
                             unix_sock_domain.as_deref(),
                         )

src/main.rs

@@ -4,8 +4,21 @@ mod api;
 mod cli;
 mod config;
 mod crypto;
+#[cfg(unix)]
+mod daemon;
 mod error;
 mod ip_tracker;
+mod logging;
+mod service;
+#[cfg(test)]
+#[path = "tests/ip_tracker_encapsulation_adversarial_tests.rs"]
+mod ip_tracker_encapsulation_adversarial_tests;
+#[cfg(test)]
+#[path = "tests/ip_tracker_hotpath_adversarial_tests.rs"]
+mod ip_tracker_hotpath_adversarial_tests;
+#[cfg(test)]
+#[path = "tests/ip_tracker_regression_tests.rs"]
+mod ip_tracker_regression_tests;
 mod maestro;
 mod metrics;
 mod network;
@@ -18,7 +31,49 @@ mod tls_front;
 mod transport;
 mod util;
 
-#[tokio::main]
-async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
-    maestro::run().await
+fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
+    // Install rustls crypto provider early
+    let _ = rustls::crypto::ring::default_provider().install_default();
+
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    let cmd = cli::parse_command(&args);
+
+    // Handle subcommands that don't need the server (stop, reload, status, init)
+    if let Some(exit_code) = cli::execute_subcommand(&cmd) {
+        std::process::exit(exit_code);
+    }
+
+    #[cfg(unix)]
+    {
+        let daemon_opts = cmd.daemon_opts;
+
+        // Daemonize BEFORE runtime
+        if daemon_opts.should_daemonize() {
+            match daemon::daemonize(daemon_opts.working_dir.as_deref()) {
+                Ok(daemon::DaemonizeResult::Parent) => {
+                    std::process::exit(0);
+                }
+                Ok(daemon::DaemonizeResult::Child) => {
+                    // continue
+                }
+                Err(e) => {
+                    eprintln!("[telemt] Daemonization failed: {}", e);
+                    std::process::exit(1);
+                }
+            }
+        }
+
+        tokio::runtime::Builder::new_multi_thread()
+            .enable_all()
+            .build()?
+            .block_on(maestro::run_with_daemon(daemon_opts))
+    }
+
+    #[cfg(not(unix))]
+    {
+        tokio::runtime::Builder::new_multi_thread()
+            .enable_all()
+            .build()?
+            .block_on(maestro::run())
+    }
 }

src/network/dns_overrides.rs

@@ -26,9 +26,7 @@ fn parse_ip_spec(ip_spec: &str) -> Result<IpAddr> {
     }
 
     let ip = ip_spec.parse::<IpAddr>().map_err(|_| {
-        ProxyError::Config(format!(
-            "network.dns_overrides IP is invalid: '{ip_spec}'"
-        ))
+        ProxyError::Config(format!("network.dns_overrides IP is invalid: '{ip_spec}'"))
     })?;
     if matches!(ip, IpAddr::V6(_)) {
         return Err(ProxyError::Config(format!(
@@ -103,9 +101,9 @@ pub fn validate_entries(entries: &[String]) -> Result<()> {
 /// Replace runtime DNS overrides with a new validated snapshot.
 pub fn install_entries(entries: &[String]) -> Result<()> {
     let parsed = parse_entries(entries)?;
-    let mut guard = overrides_store()
-        .write()
-        .map_err(|_| ProxyError::Config("network.dns_overrides runtime lock is poisoned".to_string()))?;
+    let mut guard = overrides_store().write().map_err(|_| {
+        ProxyError::Config("network.dns_overrides runtime lock is poisoned".to_string())
+    })?;
     *guard = parsed;
     Ok(())
 }

src/network/probe.rs

@@ -1,4 +1,5 @@
 #![allow(dead_code)]
+#![allow(clippy::items_after_test_module)]
 
 use std::collections::HashMap;
 use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, UdpSocket};
@@ -10,7 +11,9 @@ use tracing::{debug, info, warn};
 
 use crate::config::{NetworkConfig, UpstreamConfig, UpstreamType};
 use crate::error::Result;
-use crate::network::stun::{stun_probe_family_with_bind, DualStunResult, IpFamily, StunProbeResult};
+use crate::network::stun::{
+    DualStunResult, IpFamily, StunProbeResult, stun_probe_family_with_bind,
+};
 use crate::transport::UpstreamManager;
 
 #[derive(Debug, Clone, Default)]
@@ -78,13 +81,8 @@ pub async fn run_probe(
             warn!("STUN probe is enabled but network.stun_servers is empty");
             DualStunResult::default()
         } else {
-            probe_stun_servers_parallel(
-                &servers,
-                stun_nat_probe_concurrency.max(1),
-                None,
-                None,
-            )
-            .await
+            probe_stun_servers_parallel(&servers, stun_nat_probe_concurrency.max(1), None, None)
+                .await
         }
     } else if nat_probe {
         info!("STUN probe is disabled by network.stun_use=false");
@@ -99,7 +97,8 @@ pub async fn run_probe(
         let UpstreamType::Direct {
             interface,
             bind_addresses,
-        } = &upstream.upstream_type else {
+        } = &upstream.upstream_type
+        else {
             continue;
         };
         if let Some(addrs) = bind_addresses.as_ref().filter(|v| !v.is_empty()) {
@@ -199,11 +198,10 @@ pub async fn run_probe(
     if nat_probe
         && probe.reflected_ipv4.is_none()
         && probe.detected_ipv4.map(is_bogon_v4).unwrap_or(false)
+        && let Some(public_ip) = detect_public_ipv4_http(&config.http_ip_detect_urls).await
     {
-        if let Some(public_ip) = detect_public_ipv4_http(&config.http_ip_detect_urls).await {
-            probe.reflected_ipv4 = Some(SocketAddr::new(IpAddr::V4(public_ip), 0));
-            info!(public_ip = %public_ip, "STUN unavailable, using HTTP public IPv4 fallback");
-        }
+        probe.reflected_ipv4 = Some(SocketAddr::new(IpAddr::V4(public_ip), 0));
+        info!(public_ip = %public_ip, "STUN unavailable, using HTTP public IPv4 fallback");
     }
 
     probe.ipv4_nat_detected = match (probe.detected_ipv4, probe.reflected_ipv4) {
@@ -217,12 +215,20 @@ pub async fn run_probe(
 
     probe.ipv4_usable = config.ipv4
         && probe.detected_ipv4.is_some()
-        && (!probe.ipv4_is_bogon || probe.reflected_ipv4.map(|r| !is_bogon(r.ip())).unwrap_or(false));
+        && (!probe.ipv4_is_bogon
+            || probe
+                .reflected_ipv4
+                .map(|r| !is_bogon(r.ip()))
+                .unwrap_or(false));
 
     let ipv6_enabled = config.ipv6.unwrap_or(probe.detected_ipv6.is_some());
     probe.ipv6_usable = ipv6_enabled
         && probe.detected_ipv6.is_some()
-        && (!probe.ipv6_is_bogon || probe.reflected_ipv6.map(|r| !is_bogon(r.ip())).unwrap_or(false));
+        && (!probe.ipv6_is_bogon
+            || probe
+                .reflected_ipv6
+                .map(|r| !is_bogon(r.ip()))
+                .unwrap_or(false));
 
     Ok(probe)
 }
@@ -280,8 +286,6 @@ async fn probe_stun_servers_parallel(
         while next_idx < servers.len() && join_set.len() < concurrency {
             let stun_addr = servers[next_idx].clone();
             next_idx += 1;
-            let bind_v4 = bind_v4;
-            let bind_v6 = bind_v6;
             join_set.spawn(async move {
                 let res = timeout(STUN_BATCH_TIMEOUT, async {
                     let v4 = stun_probe_family_with_bind(&stun_addr, IpFamily::V4, bind_v4).await?;
@@ -300,11 +304,15 @@ async fn probe_stun_servers_parallel(
         match task {
             Ok((stun_addr, Ok(Ok(result)))) => {
                 if let Some(v4) = result.v4 {
-                    let entry = best_v4_by_ip.entry(v4.reflected_addr.ip()).or_insert((0, v4));
+                    let entry = best_v4_by_ip
+                        .entry(v4.reflected_addr.ip())
+                        .or_insert((0, v4));
                     entry.0 += 1;
                 }
                 if let Some(v6) = result.v6 {
-                    let entry = best_v6_by_ip.entry(v6.reflected_addr.ip()).or_insert((0, v6));
+                    let entry = best_v6_by_ip
+                        .entry(v6.reflected_addr.ip())
+                        .or_insert((0, v6));
                     entry.0 += 1;
                 }
                 if result.v4.is_some() || result.v6.is_some() {
@@ -324,17 +332,11 @@ async fn probe_stun_servers_parallel(
     }
 
     let mut out = DualStunResult::default();
-    if let Some((_, best)) = best_v4_by_ip
-        .into_values()
-        .max_by_key(|(count, _)| *count)
-    {
+    if let Some((_, best)) = best_v4_by_ip.into_values().max_by_key(|(count, _)| *count) {
         info!("STUN-Quorum reached, IP: {}", best.reflected_addr.ip());
         out.v4 = Some(best);
     }
-    if let Some((_, best)) = best_v6_by_ip
-        .into_values()
-        .max_by_key(|(count, _)| *count)
-    {
+    if let Some((_, best)) = best_v6_by_ip.into_values().max_by_key(|(count, _)| *count) {
         info!("STUN-Quorum reached, IP: {}", best.reflected_addr.ip());
         out.v6 = Some(best);
     }
@@ -347,7 +349,8 @@ pub fn decide_network_capabilities(
     middle_proxy_nat_ip: Option<IpAddr>,
 ) -> NetworkDecision {
     let ipv4_dc = config.ipv4 && probe.detected_ipv4.is_some();
-    let ipv6_dc = config.ipv6.unwrap_or(probe.detected_ipv6.is_some()) && probe.detected_ipv6.is_some();
+    let ipv6_dc =
+        config.ipv6.unwrap_or(probe.detected_ipv6.is_some()) && probe.detected_ipv6.is_some();
     let nat_ip_v4 = matches!(middle_proxy_nat_ip, Some(IpAddr::V4(_)));
     let nat_ip_v6 = matches!(middle_proxy_nat_ip, Some(IpAddr::V6(_)));
 
@@ -534,10 +537,26 @@ pub fn is_bogon_v6(ip: Ipv6Addr) -> bool {
 
 pub fn log_probe_result(probe: &NetworkProbe, decision: &NetworkDecision) {
     info!(
-        ipv4 = probe.detected_ipv4.as_ref().map(|v| v.to_string()).unwrap_or_else(|| "-".into()),
-        ipv6 = probe.detected_ipv6.as_ref().map(|v| v.to_string()).unwrap_or_else(|| "-".into()),
-        reflected_v4 = probe.reflected_ipv4.as_ref().map(|v| v.ip().to_string()).unwrap_or_else(|| "-".into()),
-        reflected_v6 = probe.reflected_ipv6.as_ref().map(|v| v.ip().to_string()).unwrap_or_else(|| "-".into()),
+        ipv4 = probe
+            .detected_ipv4
+            .as_ref()
+            .map(|v| v.to_string())
+            .unwrap_or_else(|| "-".into()),
+        ipv6 = probe
+            .detected_ipv6
+            .as_ref()
+            .map(|v| v.to_string())
+            .unwrap_or_else(|| "-".into()),
+        reflected_v4 = probe
+            .reflected_ipv4
+            .as_ref()
+            .map(|v| v.ip().to_string())
+            .unwrap_or_else(|| "-".into()),
+        reflected_v6 = probe
+            .reflected_ipv6
+            .as_ref()
+            .map(|v| v.ip().to_string())
+            .unwrap_or_else(|| "-".into()),
         ipv4_bogon = probe.ipv4_is_bogon,
         ipv6_bogon = probe.ipv6_is_bogon,
         ipv4_me = decision.ipv4_me,

src/network/stun.rs

@@ -2,13 +2,20 @@
 #![allow(dead_code)]
 
 use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
+use std::sync::OnceLock;
 
-use tokio::net::{lookup_host, UdpSocket};
-use tokio::time::{timeout, Duration, sleep};
+use tokio::net::{UdpSocket, lookup_host};
+use tokio::time::{Duration, sleep, timeout};
 
+use crate::crypto::SecureRandom;
 use crate::error::{ProxyError, Result};
 use crate::network::dns_overrides::{resolve, split_host_port};
 
+fn stun_rng() -> &'static SecureRandom {
+    static STUN_RNG: OnceLock<SecureRandom> = OnceLock::new();
+    STUN_RNG.get_or_init(SecureRandom::new)
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum IpFamily {
     V4,
@@ -34,13 +41,13 @@ pub async fn stun_probe_dual(stun_addr: &str) -> Result<DualStunResult> {
         stun_probe_family(stun_addr, IpFamily::V6),
     );
 
-    Ok(DualStunResult {
-        v4: v4?,
-        v6: v6?,
-    })
+    Ok(DualStunResult { v4: v4?, v6: v6? })
 }
 
-pub async fn stun_probe_family(stun_addr: &str, family: IpFamily) -> Result<Option<StunProbeResult>> {
+pub async fn stun_probe_family(
+    stun_addr: &str,
+    family: IpFamily,
+) -> Result<Option<StunProbeResult>> {
     stun_probe_family_with_bind(stun_addr, family, None).await
 }
 
@@ -49,8 +56,6 @@ pub async fn stun_probe_family_with_bind(
     family: IpFamily,
     bind_ip: Option<IpAddr>,
 ) -> Result<Option<StunProbeResult>> {
-    use rand::RngCore;
-
     let bind_addr = match (family, bind_ip) {
         (IpFamily::V4, Some(IpAddr::V4(ip))) => SocketAddr::new(IpAddr::V4(ip), 0),
         (IpFamily::V6, Some(IpAddr::V6(ip))) => SocketAddr::new(IpAddr::V6(ip), 0),
@@ -71,13 +76,18 @@ pub async fn stun_probe_family_with_bind(
     if let Some(addr) = target_addr {
         match socket.connect(addr).await {
             Ok(()) => {}
-            Err(e) if family == IpFamily::V6 && matches!(
-                e.kind(),
-                std::io::ErrorKind::NetworkUnreachable
-                | std::io::ErrorKind::HostUnreachable
-                | std::io::ErrorKind::Unsupported
-                | std::io::ErrorKind::NetworkDown
-            ) => return Ok(None),
+            Err(e)
+                if family == IpFamily::V6
+                    && matches!(
+                        e.kind(),
+                        std::io::ErrorKind::NetworkUnreachable
+                            | std::io::ErrorKind::HostUnreachable
+                            | std::io::ErrorKind::Unsupported
+                            | std::io::ErrorKind::NetworkDown
+                    ) =>
+            {
+                return Ok(None);
+            }
             Err(e) => return Err(ProxyError::Proxy(format!("STUN connect failed: {e}"))),
         }
     } else {
@@ -88,7 +98,7 @@ pub async fn stun_probe_family_with_bind(
     req[0..2].copy_from_slice(&0x0001u16.to_be_bytes()); // Binding Request
     req[2..4].copy_from_slice(&0u16.to_be_bytes()); // length
     req[4..8].copy_from_slice(&0x2112A442u32.to_be_bytes()); // magic cookie
-    rand::rng().fill_bytes(&mut req[8..20]); // transaction ID
+    stun_rng().fill(&mut req[8..20]); // transaction ID
 
     let mut buf = [0u8; 256];
     let mut attempt = 0;
@@ -120,16 +130,16 @@ pub async fn stun_probe_family_with_bind(
 
         let magic = 0x2112A442u32.to_be_bytes();
         let txid = &req[8..20];
-    let mut idx = 20;
-    while idx + 4 <= n {
-        let atype = u16::from_be_bytes(buf[idx..idx + 2].try_into().unwrap());
-        let alen = u16::from_be_bytes(buf[idx + 2..idx + 4].try_into().unwrap()) as usize;
-        idx += 4;
-        if idx + alen > n {
-            break;
-        }
+        let mut idx = 20;
+        while idx + 4 <= n {
+            let atype = u16::from_be_bytes(buf[idx..idx + 2].try_into().unwrap());
+            let alen = u16::from_be_bytes(buf[idx + 2..idx + 4].try_into().unwrap()) as usize;
+            idx += 4;
+            if idx + alen > n {
+                break;
+            }
 
-        match atype {
+            match atype {
             0x0020 /* XOR-MAPPED-ADDRESS */ | 0x0001 /* MAPPED-ADDRESS */ => {
                 if alen < 8 {
                     break;
@@ -198,9 +208,8 @@ pub async fn stun_probe_family_with_bind(
             _ => {}
         }
 
-        idx += (alen + 3) & !3;
-    }
-
+            idx += (alen + 3) & !3;
+        }
     }
 
     Ok(None)
@@ -228,7 +237,11 @@ async fn resolve_stun_addr(stun_addr: &str, family: IpFamily) -> Result<Option<S
         .await
         .map_err(|e| ProxyError::Proxy(format!("STUN resolve failed: {e}")))?;
 
-    let target = addrs
-        .find(|a| matches!((a.is_ipv4(), family), (true, IpFamily::V4) | (false, IpFamily::V6)));
+    let target = addrs.find(|a| {
+        matches!(
+            (a.is_ipv4(), family),
+            (true, IpFamily::V4) | (false, IpFamily::V6)
+        )
+    });
     Ok(target)
 }

src/protocol/constants.rs

@@ -33,35 +33,89 @@ pub static TG_DATACENTERS_V6: LazyLock<Vec<IpAddr>> = LazyLock::new(|| {
 
 // ============= Middle Proxies (for advertising) =============
 
-pub static TG_MIDDLE_PROXIES_V4: LazyLock<std::collections::HashMap<i32, Vec<(IpAddr, u16)>>> = 
+pub static TG_MIDDLE_PROXIES_V4: LazyLock<std::collections::HashMap<i32, Vec<(IpAddr, u16)>>> =
     LazyLock::new(|| {
         let mut m = std::collections::HashMap::new();
-        m.insert(1, vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 175, 50)), 8888)]);
-        m.insert(-1, vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 175, 50)), 8888)]);
-        m.insert(2, vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 161, 144)), 8888)]);
-        m.insert(-2, vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 161, 144)), 8888)]);
-        m.insert(3, vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 175, 100)), 8888)]);
-        m.insert(-3, vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 175, 100)), 8888)]);
+        m.insert(
+            1,
+            vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 175, 50)), 8888)],
+        );
+        m.insert(
+            -1,
+            vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 175, 50)), 8888)],
+        );
+        m.insert(
+            2,
+            vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 161, 144)), 8888)],
+        );
+        m.insert(
+            -2,
+            vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 161, 144)), 8888)],
+        );
+        m.insert(
+            3,
+            vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 175, 100)), 8888)],
+        );
+        m.insert(
+            -3,
+            vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 175, 100)), 8888)],
+        );
         m.insert(4, vec![(IpAddr::V4(Ipv4Addr::new(91, 108, 4, 136)), 8888)]);
-        m.insert(-4, vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 165, 109)), 8888)]);
+        m.insert(
+            -4,
+            vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 165, 109)), 8888)],
+        );
         m.insert(5, vec![(IpAddr::V4(Ipv4Addr::new(91, 108, 56, 183)), 8888)]);
-        m.insert(-5, vec![(IpAddr::V4(Ipv4Addr::new(91, 108, 56, 183)), 8888)]);
+        m.insert(
+            -5,
+            vec![(IpAddr::V4(Ipv4Addr::new(91, 108, 56, 183)), 8888)],
+        );
         m
     });
 
-pub static TG_MIDDLE_PROXIES_V6: LazyLock<std::collections::HashMap<i32, Vec<(IpAddr, u16)>>> = 
+pub static TG_MIDDLE_PROXIES_V6: LazyLock<std::collections::HashMap<i32, Vec<(IpAddr, u16)>>> =
     LazyLock::new(|| {
         let mut m = std::collections::HashMap::new();
-        m.insert(1, vec![(IpAddr::V6("2001:b28:f23d:f001::d".parse().unwrap()), 8888)]);
-        m.insert(-1, vec![(IpAddr::V6("2001:b28:f23d:f001::d".parse().unwrap()), 8888)]);
-        m.insert(2, vec![(IpAddr::V6("2001:67c:04e8:f002::d".parse().unwrap()), 80)]);
-        m.insert(-2, vec![(IpAddr::V6("2001:67c:04e8:f002::d".parse().unwrap()), 80)]);
-        m.insert(3, vec![(IpAddr::V6("2001:b28:f23d:f003::d".parse().unwrap()), 8888)]);
-        m.insert(-3, vec![(IpAddr::V6("2001:b28:f23d:f003::d".parse().unwrap()), 8888)]);
-        m.insert(4, vec![(IpAddr::V6("2001:67c:04e8:f004::d".parse().unwrap()), 8888)]);
-        m.insert(-4, vec![(IpAddr::V6("2001:67c:04e8:f004::d".parse().unwrap()), 8888)]);
-        m.insert(5, vec![(IpAddr::V6("2001:b28:f23f:f005::d".parse().unwrap()), 8888)]);
-        m.insert(-5, vec![(IpAddr::V6("2001:b28:f23f:f005::d".parse().unwrap()), 8888)]);
+        m.insert(
+            1,
+            vec![(IpAddr::V6("2001:b28:f23d:f001::d".parse().unwrap()), 8888)],
+        );
+        m.insert(
+            -1,
+            vec![(IpAddr::V6("2001:b28:f23d:f001::d".parse().unwrap()), 8888)],
+        );
+        m.insert(
+            2,
+            vec![(IpAddr::V6("2001:67c:04e8:f002::d".parse().unwrap()), 80)],
+        );
+        m.insert(
+            -2,
+            vec![(IpAddr::V6("2001:67c:04e8:f002::d".parse().unwrap()), 80)],
+        );
+        m.insert(
+            3,
+            vec![(IpAddr::V6("2001:b28:f23d:f003::d".parse().unwrap()), 8888)],
+        );
+        m.insert(
+            -3,
+            vec![(IpAddr::V6("2001:b28:f23d:f003::d".parse().unwrap()), 8888)],
+        );
+        m.insert(
+            4,
+            vec![(IpAddr::V6("2001:67c:04e8:f004::d".parse().unwrap()), 8888)],
+        );
+        m.insert(
+            -4,
+            vec![(IpAddr::V6("2001:67c:04e8:f004::d".parse().unwrap()), 8888)],
+        );
+        m.insert(
+            5,
+            vec![(IpAddr::V6("2001:b28:f23f:f005::d".parse().unwrap()), 8888)],
+        );
+        m.insert(
+            -5,
+            vec![(IpAddr::V6("2001:b28:f23f:f005::d".parse().unwrap()), 8888)],
+        );
         m
     });
 
@@ -89,12 +143,12 @@ impl ProtoTag {
             _ => None,
         }
     }
-    
+
     /// Convert to 4 bytes (little-endian)
     pub fn to_bytes(self) -> [u8; 4] {
         (self as u32).to_le_bytes()
     }
-    
+
     /// Get protocol tag as bytes slice
     pub fn as_bytes(&self) -> &'static [u8; 4] {
         match self {
@@ -152,11 +206,29 @@ pub const TLS_RECORD_CHANGE_CIPHER: u8 = 0x14;
 pub const TLS_RECORD_APPLICATION: u8 = 0x17;
 /// TLS record type: Alert
 pub const TLS_RECORD_ALERT: u8 = 0x15;
-/// Maximum TLS record size
-pub const MAX_TLS_RECORD_SIZE: usize = 16384;
-/// Maximum TLS chunk size (with overhead)
-/// RFC 8446 §5.2 allows up to 16384 + 256 bytes of ciphertext
-pub const MAX_TLS_CHUNK_SIZE: usize = 16384 + 256;
+/// Maximum TLS plaintext record payload size.
+/// RFC 8446 §5.1: "The length MUST NOT exceed 2^14 bytes."
+/// Use this for validating incoming unencrypted records
+/// (ClientHello, ChangeCipherSpec, unprotected Handshake messages).
+pub const MAX_TLS_PLAINTEXT_SIZE: usize = 16_384;
+
+/// Structural minimum for a valid TLS 1.3 ClientHello with SNI.
+/// Derived from RFC 8446 §4.1.2 field layout + Appendix D.4 compat mode.
+/// Deliberately conservative (below any real client) to avoid false
+/// positives on legitimate connections with compact extension sets.
+pub const MIN_TLS_CLIENT_HELLO_SIZE: usize = 100;
+
+/// Maximum TLS ciphertext record payload size.
+/// RFC 8446 §5.2: "The length MUST NOT exceed 2^14 + 256 bytes."
+/// The +256 accounts for maximum AEAD expansion overhead.
+/// Use this for validating or sizing buffers for encrypted records.
+pub const MAX_TLS_CIPHERTEXT_SIZE: usize = 16_384 + 256;
+
+#[deprecated(note = "use MAX_TLS_PLAINTEXT_SIZE")]
+pub const MAX_TLS_RECORD_SIZE: usize = MAX_TLS_PLAINTEXT_SIZE;
+
+#[deprecated(note = "use MAX_TLS_CIPHERTEXT_SIZE")]
+pub const MAX_TLS_CHUNK_SIZE: usize = MAX_TLS_CIPHERTEXT_SIZE;
 
 /// Secure Intermediate payload is expected to be 4-byte aligned.
 pub fn is_valid_secure_payload_len(data_len: usize) -> bool {
@@ -204,9 +276,7 @@ pub const SMALL_BUFFER_SIZE: usize = 8192;
 // ============= Statistics =============
 
 /// Duration buckets for histogram metrics
-pub static DURATION_BUCKETS: &[f64] = &[
-    0.1, 0.5, 1.0, 2.0, 5.0, 15.0, 60.0, 300.0, 600.0, 1800.0,
-];
+pub static DURATION_BUCKETS: &[f64] = &[0.1, 0.5, 1.0, 2.0, 5.0, 15.0, 60.0, 300.0, 600.0, 1800.0];
 
 // ============= Reserved Nonce Patterns =============
 
@@ -217,29 +287,27 @@ pub static RESERVED_NONCE_FIRST_BYTES: &[u8] = &[0xef];
 pub static RESERVED_NONCE_BEGINNINGS: &[[u8; 4]] = &[
     [0x48, 0x45, 0x41, 0x44], // HEAD
     [0x50, 0x4F, 0x53, 0x54], // POST
-    [0x47, 0x45, 0x54, 0x20], // GET 
+    [0x47, 0x45, 0x54, 0x20], // GET
     [0xee, 0xee, 0xee, 0xee], // Intermediate
     [0xdd, 0xdd, 0xdd, 0xdd], // Secure
     [0x16, 0x03, 0x01, 0x02], // TLS
 ];
 
 /// Reserved continuation bytes (bytes 4-7)
-pub static RESERVED_NONCE_CONTINUES: &[[u8; 4]] = &[
-    [0x00, 0x00, 0x00, 0x00],
-];
+pub static RESERVED_NONCE_CONTINUES: &[[u8; 4]] = &[[0x00, 0x00, 0x00, 0x00]];
 
 // ============= RPC Constants (for Middle Proxy) =============
 
 /// RPC Proxy Request
 /// RPC Flags (from Erlang mtp_rpc.erl)
 pub const RPC_FLAG_NOT_ENCRYPTED: u32 = 0x2;
-pub const RPC_FLAG_HAS_AD_TAG: u32    = 0x8;
-pub const RPC_FLAG_MAGIC: u32          = 0x1000;
-pub const RPC_FLAG_EXTMODE2: u32       = 0x20000;
-pub const RPC_FLAG_PAD: u32            = 0x8000000;
-pub const RPC_FLAG_INTERMEDIATE: u32   = 0x20000000;
-pub const RPC_FLAG_ABRIDGED: u32       = 0x40000000;
-pub const RPC_FLAG_QUICKACK: u32       = 0x80000000;
+pub const RPC_FLAG_HAS_AD_TAG: u32 = 0x8;
+pub const RPC_FLAG_MAGIC: u32 = 0x1000;
+pub const RPC_FLAG_EXTMODE2: u32 = 0x20000;
+pub const RPC_FLAG_PAD: u32 = 0x8000000;
+pub const RPC_FLAG_INTERMEDIATE: u32 = 0x20000000;
+pub const RPC_FLAG_ABRIDGED: u32 = 0x40000000;
+pub const RPC_FLAG_QUICKACK: u32 = 0x80000000;
 
 pub const RPC_PROXY_REQ: [u8; 4] = [0xee, 0xf1, 0xce, 0x36];
 /// RPC Proxy Answer
@@ -267,63 +335,66 @@ pub mod rpc_flags {
     pub const FLAG_QUICKACK: u32 = 0x80000000;
 }
 
+// ============= Middle-End Proxy Servers =============
+pub const ME_PROXY_PORT: u16 = 8888;
 
-    // ============= Middle-End Proxy Servers =============
-    pub const ME_PROXY_PORT: u16 = 8888;
-    
-    pub static TG_MIDDLE_PROXIES_FLAT_V4: LazyLock<Vec<(IpAddr, u16)>> = LazyLock::new(|| {
-        vec![
-            (IpAddr::V4(Ipv4Addr::new(149, 154, 175, 50)), 8888),
-            (IpAddr::V4(Ipv4Addr::new(149, 154, 161, 144)), 8888),
-            (IpAddr::V4(Ipv4Addr::new(149, 154, 175, 100)), 8888),
-            (IpAddr::V4(Ipv4Addr::new(91, 108, 4, 136)), 8888),
-            (IpAddr::V4(Ipv4Addr::new(91, 108, 56, 183)), 8888),
-        ]
-    });
-    
-    // ============= RPC Constants (u32 native endian) =============
-    // From mtproto-common.h + net-tcp-rpc-common.h + mtproto-proxy.c
-    
-    pub const RPC_NONCE_U32: u32           = 0x7acb87aa;
-    pub const RPC_HANDSHAKE_U32: u32       = 0x7682eef5;
-    pub const RPC_HANDSHAKE_ERROR_U32: u32 = 0x6a27beda;
-    pub const TL_PROXY_TAG_U32: u32        = 0xdb1e26ae;  // mtproto-proxy.c:121
-    
-    // mtproto-common.h
-    pub const RPC_PROXY_REQ_U32: u32       = 0x36cef1ee;
-    pub const RPC_PROXY_ANS_U32: u32       = 0x4403da0d;
-    pub const RPC_CLOSE_CONN_U32: u32      = 0x1fcf425d;
-    pub const RPC_CLOSE_EXT_U32: u32       = 0x5eb634a2;
-    pub const RPC_SIMPLE_ACK_U32: u32      = 0x3bac409b;
-    pub const RPC_PING_U32: u32            = 0x5730a2df;
-    pub const RPC_PONG_U32: u32            = 0x8430eaa7;
-    
-    pub const RPC_CRYPTO_NONE_U32: u32 = 0;
-    pub const RPC_CRYPTO_AES_U32: u32  = 1;
-    
-    pub mod proxy_flags {
-        pub const FLAG_HAS_AD_TAG: u32    = 1;
-        pub const FLAG_NOT_ENCRYPTED: u32 = 0x2;
-        pub const FLAG_HAS_AD_TAG2: u32   = 0x8;
-        pub const FLAG_MAGIC: u32         = 0x1000;
-        pub const FLAG_EXTMODE2: u32      = 0x20000;
-        pub const FLAG_PAD: u32           = 0x8000000;
-        pub const FLAG_INTERMEDIATE: u32  = 0x20000000;
-        pub const FLAG_ABRIDGED: u32      = 0x40000000;
-        pub const FLAG_QUICKACK: u32      = 0x80000000;
-    }
+pub static TG_MIDDLE_PROXIES_FLAT_V4: LazyLock<Vec<(IpAddr, u16)>> = LazyLock::new(|| {
+    vec![
+        (IpAddr::V4(Ipv4Addr::new(149, 154, 175, 50)), 8888),
+        (IpAddr::V4(Ipv4Addr::new(149, 154, 161, 144)), 8888),
+        (IpAddr::V4(Ipv4Addr::new(149, 154, 175, 100)), 8888),
+        (IpAddr::V4(Ipv4Addr::new(91, 108, 4, 136)), 8888),
+        (IpAddr::V4(Ipv4Addr::new(91, 108, 56, 183)), 8888),
+    ]
+});
 
-    pub mod rpc_crypto_flags {
-        pub const USE_CRC32C: u32 = 0x800;
-    }
-    
-    pub const ME_CONNECT_TIMEOUT_SECS: u64 = 5;
-    pub const ME_HANDSHAKE_TIMEOUT_SECS: u64 = 10;
-    
-    #[cfg(test)]
+// ============= RPC Constants (u32 native endian) =============
+// From mtproto-common.h + net-tcp-rpc-common.h + mtproto-proxy.c
+
+pub const RPC_NONCE_U32: u32 = 0x7acb87aa;
+pub const RPC_HANDSHAKE_U32: u32 = 0x7682eef5;
+pub const RPC_HANDSHAKE_ERROR_U32: u32 = 0x6a27beda;
+pub const TL_PROXY_TAG_U32: u32 = 0xdb1e26ae; // mtproto-proxy.c:121
+
+// mtproto-common.h
+pub const RPC_PROXY_REQ_U32: u32 = 0x36cef1ee;
+pub const RPC_PROXY_ANS_U32: u32 = 0x4403da0d;
+pub const RPC_CLOSE_CONN_U32: u32 = 0x1fcf425d;
+pub const RPC_CLOSE_EXT_U32: u32 = 0x5eb634a2;
+pub const RPC_SIMPLE_ACK_U32: u32 = 0x3bac409b;
+pub const RPC_PING_U32: u32 = 0x5730a2df;
+pub const RPC_PONG_U32: u32 = 0x8430eaa7;
+
+pub const RPC_CRYPTO_NONE_U32: u32 = 0;
+pub const RPC_CRYPTO_AES_U32: u32 = 1;
+
+pub mod proxy_flags {
+    pub const FLAG_HAS_AD_TAG: u32 = 1;
+    pub const FLAG_NOT_ENCRYPTED: u32 = 0x2;
+    pub const FLAG_HAS_AD_TAG2: u32 = 0x8;
+    pub const FLAG_MAGIC: u32 = 0x1000;
+    pub const FLAG_EXTMODE2: u32 = 0x20000;
+    pub const FLAG_PAD: u32 = 0x8000000;
+    pub const FLAG_INTERMEDIATE: u32 = 0x20000000;
+    pub const FLAG_ABRIDGED: u32 = 0x40000000;
+    pub const FLAG_QUICKACK: u32 = 0x80000000;
+}
+
+pub mod rpc_crypto_flags {
+    pub const USE_CRC32C: u32 = 0x800;
+}
+
+pub const ME_CONNECT_TIMEOUT_SECS: u64 = 5;
+pub const ME_HANDSHAKE_TIMEOUT_SECS: u64 = 10;
+
+#[cfg(test)]
+#[path = "tests/tls_size_constants_security_tests.rs"]
+mod tls_size_constants_security_tests;
+
+#[cfg(test)]
 mod tests {
     use super::*;
-    
+
     #[test]
     fn test_proto_tag_roundtrip() {
         for tag in [ProtoTag::Abridged, ProtoTag::Intermediate, ProtoTag::Secure] {
@@ -332,20 +403,20 @@ mod tests {
             assert_eq!(tag, parsed);
         }
     }
-    
+
     #[test]
     fn test_proto_tag_values() {
         assert_eq!(ProtoTag::Abridged.to_bytes(), PROTO_TAG_ABRIDGED);
         assert_eq!(ProtoTag::Intermediate.to_bytes(), PROTO_TAG_INTERMEDIATE);
         assert_eq!(ProtoTag::Secure.to_bytes(), PROTO_TAG_SECURE);
     }
-    
+
     #[test]
     fn test_invalid_proto_tag() {
         assert!(ProtoTag::from_bytes([0, 0, 0, 0]).is_none());
         assert!(ProtoTag::from_bytes([0xff, 0xff, 0xff, 0xff]).is_none());
     }
-    
+
     #[test]
     fn test_datacenters_count() {
         assert_eq!(TG_DATACENTERS_V4.len(), 5);

src/protocol/frame.rs

@@ -22,7 +22,7 @@ impl FrameExtra {
     pub fn new() -> Self {
         Self::default()
     }
-    
+
     /// Create with quickack flag set
     pub fn with_quickack() -> Self {
         Self {
@@ -30,7 +30,7 @@ impl FrameExtra {
             ..Default::default()
         }
     }
-    
+
     /// Create with simple_ack flag set
     pub fn with_simple_ack() -> Self {
         Self {
@@ -38,7 +38,7 @@ impl FrameExtra {
             ..Default::default()
         }
     }
-    
+
     /// Check if any flags are set
     pub fn has_flags(&self) -> bool {
         self.quickack || self.simple_ack || self.skip_send
@@ -76,22 +76,22 @@ impl FrameMode {
             FrameMode::Abridged => 4,
             FrameMode::Intermediate => 4,
             FrameMode::SecureIntermediate => 4 + 3, // length + padding
-            FrameMode::Full => 12 + 16, // header + max CBC padding
+            FrameMode::Full => 12 + 16,             // header + max CBC padding
         }
     }
 }
 
 /// Validate message length for MTProto
 pub fn validate_message_length(len: usize) -> bool {
-    use super::constants::{MIN_MSG_LEN, MAX_MSG_LEN, PADDING_FILLER};
-    
+    use super::constants::{MAX_MSG_LEN, MIN_MSG_LEN, PADDING_FILLER};
+
     (MIN_MSG_LEN..=MAX_MSG_LEN).contains(&len) && len.is_multiple_of(PADDING_FILLER.len())
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
-    
+
     #[test]
     fn test_frame_extra_default() {
         let extra = FrameExtra::default();
@@ -100,18 +100,18 @@ mod tests {
         assert!(!extra.skip_send);
         assert!(!extra.has_flags());
     }
-    
+
     #[test]
     fn test_frame_extra_flags() {
         let extra = FrameExtra::with_quickack();
         assert!(extra.quickack);
         assert!(extra.has_flags());
-        
+
         let extra = FrameExtra::with_simple_ack();
         assert!(extra.simple_ack);
         assert!(extra.has_flags());
     }
-    
+
     #[test]
     fn test_validate_message_length() {
         assert!(validate_message_length(12)); // MIN_MSG_LEN
@@ -119,4 +119,4 @@ mod tests {
         assert!(!validate_message_length(8)); // Too small
         assert!(!validate_message_length(13)); // Not aligned to 4
     }
-}
+}

src/protocol/mod.rs

@@ -12,4 +12,4 @@ pub use frame::*;
 #[allow(unused_imports)]
 pub use obfuscation::*;
 #[allow(unused_imports)]
-pub use tls::*;
+pub use tls::*;

src/protocol/obfuscation.rs

@@ -2,9 +2,9 @@
 
 #![allow(dead_code)]
 
-use zeroize::Zeroize;
-use crate::crypto::{sha256, AesCtr};
 use super::constants::*;
+use crate::crypto::{AesCtr, sha256};
+use zeroize::Zeroize;
 
 /// Obfuscation parameters from handshake
 ///
@@ -44,41 +44,40 @@ impl ObfuscationParams {
         let dec_prekey_iv = &handshake[SKIP_LEN..SKIP_LEN + PREKEY_LEN + IV_LEN];
         let dec_prekey = &dec_prekey_iv[..PREKEY_LEN];
         let dec_iv_bytes = &dec_prekey_iv[PREKEY_LEN..];
-        
+
         let enc_prekey_iv: Vec<u8> = dec_prekey_iv.iter().rev().copied().collect();
         let enc_prekey = &enc_prekey_iv[..PREKEY_LEN];
         let enc_iv_bytes = &enc_prekey_iv[PREKEY_LEN..];
-        
+
         for (username, secret) in secrets {
             let mut dec_key_input = Vec::with_capacity(PREKEY_LEN + secret.len());
             dec_key_input.extend_from_slice(dec_prekey);
             dec_key_input.extend_from_slice(secret);
             let decrypt_key = sha256(&dec_key_input);
-            
+
             let decrypt_iv = u128::from_be_bytes(dec_iv_bytes.try_into().unwrap());
-            
+
             let mut decryptor = AesCtr::new(&decrypt_key, decrypt_iv);
             let decrypted = decryptor.decrypt(handshake);
-            
+
             let tag_bytes: [u8; 4] = decrypted[PROTO_TAG_POS..PROTO_TAG_POS + 4]
                 .try_into()
                 .unwrap();
-            
+
             let proto_tag = match ProtoTag::from_bytes(tag_bytes) {
                 Some(tag) => tag,
                 None => continue,
             };
-            
-            let dc_idx = i16::from_le_bytes(
-                decrypted[DC_IDX_POS..DC_IDX_POS + 2].try_into().unwrap()
-            );
-            
+
+            let dc_idx =
+                i16::from_le_bytes(decrypted[DC_IDX_POS..DC_IDX_POS + 2].try_into().unwrap());
+
             let mut enc_key_input = Vec::with_capacity(PREKEY_LEN + secret.len());
             enc_key_input.extend_from_slice(enc_prekey);
             enc_key_input.extend_from_slice(secret);
             let encrypt_key = sha256(&enc_key_input);
             let encrypt_iv = u128::from_be_bytes(enc_iv_bytes.try_into().unwrap());
-            
+
             return Some((
                 ObfuscationParams {
                     decrypt_key,
@@ -91,20 +90,20 @@ impl ObfuscationParams {
                 username.clone(),
             ));
         }
-        
+
         None
     }
-    
+
     /// Create AES-CTR decryptor for client -> proxy direction
     pub fn create_decryptor(&self) -> AesCtr {
         AesCtr::new(&self.decrypt_key, self.decrypt_iv)
     }
-    
+
     /// Create AES-CTR encryptor for proxy -> client direction
     pub fn create_encryptor(&self) -> AesCtr {
         AesCtr::new(&self.encrypt_key, self.encrypt_iv)
     }
-    
+
     /// Get the combined encrypt key and IV for fast mode
     pub fn enc_key_iv(&self) -> Vec<u8> {
         let mut result = Vec::with_capacity(KEY_LEN + IV_LEN);
@@ -120,7 +119,7 @@ pub fn generate_nonce<R: FnMut(usize) -> Vec<u8>>(mut random_bytes: R) -> [u8; H
         let nonce_vec = random_bytes(HANDSHAKE_LEN);
         let mut nonce = [0u8; HANDSHAKE_LEN];
         nonce.copy_from_slice(&nonce_vec);
-        
+
         if is_valid_nonce(&nonce) {
             return nonce;
         }
@@ -132,17 +131,17 @@ pub fn is_valid_nonce(nonce: &[u8; HANDSHAKE_LEN]) -> bool {
     if RESERVED_NONCE_FIRST_BYTES.contains(&nonce[0]) {
         return false;
     }
-    
+
     let first_four: [u8; 4] = nonce[..4].try_into().unwrap();
     if RESERVED_NONCE_BEGINNINGS.contains(&first_four) {
         return false;
     }
-    
+
     let continue_four: [u8; 4] = nonce[4..8].try_into().unwrap();
     if RESERVED_NONCE_CONTINUES.contains(&continue_four) {
         return false;
     }
-    
+
     true
 }
 
@@ -153,7 +152,7 @@ pub fn prepare_tg_nonce(
     enc_key_iv: Option<&[u8]>,
 ) {
     nonce[PROTO_TAG_POS..PROTO_TAG_POS + 4].copy_from_slice(&proto_tag.to_bytes());
-    
+
     if let Some(key_iv) = enc_key_iv {
         let reversed: Vec<u8> = key_iv.iter().rev().copied().collect();
         nonce[SKIP_LEN..SKIP_LEN + KEY_LEN + IV_LEN].copy_from_slice(&reversed);
@@ -171,39 +170,39 @@ pub fn encrypt_nonce(nonce: &[u8; HANDSHAKE_LEN]) -> Vec<u8> {
     let key_iv = &nonce[SKIP_LEN..SKIP_LEN + KEY_LEN + IV_LEN];
     let enc_key = sha256(key_iv);
     let enc_iv = u128::from_be_bytes(key_iv[..IV_LEN].try_into().unwrap());
-    
+
     let mut encryptor = AesCtr::new(&enc_key, enc_iv);
-    
+
     let mut result = nonce.to_vec();
     let encrypted_part = encryptor.encrypt(&nonce[PROTO_TAG_POS..]);
     result[PROTO_TAG_POS..].copy_from_slice(&encrypted_part);
-    
+
     result
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
-    
+
     #[test]
     fn test_is_valid_nonce() {
         let mut valid = [0x42u8; HANDSHAKE_LEN];
         valid[4..8].copy_from_slice(&[1, 2, 3, 4]);
         assert!(is_valid_nonce(&valid));
-        
+
         let mut invalid = [0x00u8; HANDSHAKE_LEN];
         invalid[0] = 0xef;
         assert!(!is_valid_nonce(&invalid));
-        
+
         let mut invalid = [0x00u8; HANDSHAKE_LEN];
         invalid[..4].copy_from_slice(b"HEAD");
         assert!(!is_valid_nonce(&invalid));
-        
+
         let mut invalid = [0x42u8; HANDSHAKE_LEN];
         invalid[4..8].copy_from_slice(&[0, 0, 0, 0]);
         assert!(!is_valid_nonce(&invalid));
     }
-    
+
     #[test]
     fn test_generate_nonce() {
         let mut counter = 0u8;
@@ -211,7 +210,7 @@ mod tests {
             counter = counter.wrapping_add(1);
             vec![counter; n]
         });
-        
+
         assert!(is_valid_nonce(&nonce));
         assert_eq!(nonce.len(), HANDSHAKE_LEN);
     }

src/protocol/tests/tls_adversarial_tests.rs

@@ -0,0 +1,358 @@
+use super::*;
+use crate::crypto::sha256_hmac;
+use std::time::Instant;
+
+/// Helper to create a byte vector of specific length.
+fn make_garbage(len: usize) -> Vec<u8> {
+    vec![0x42u8; len]
+}
+
+/// Helper to create a valid-looking HMAC digest for test.
+fn make_digest(secret: &[u8], msg: &[u8], ts: u32) -> [u8; 32] {
+    let mut hmac = sha256_hmac(secret, msg);
+    let ts_bytes = ts.to_le_bytes();
+    for i in 0..4 {
+        hmac[28 + i] ^= ts_bytes[i];
+    }
+    hmac
+}
+
+fn make_valid_tls_handshake_with_session_id(
+    secret: &[u8],
+    timestamp: u32,
+    session_id: &[u8],
+) -> Vec<u8> {
+    let session_id_len = session_id.len();
+    let len = TLS_DIGEST_POS + TLS_DIGEST_LEN + 1 + session_id_len;
+    let mut handshake = vec![0x42u8; len];
+
+    handshake[TLS_DIGEST_POS + TLS_DIGEST_LEN] = session_id_len as u8;
+    let sid_start = TLS_DIGEST_POS + TLS_DIGEST_LEN + 1;
+    handshake[sid_start..sid_start + session_id_len].copy_from_slice(session_id);
+    handshake[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN].fill(0);
+
+    let digest = make_digest(secret, &handshake, timestamp);
+
+    handshake[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN].copy_from_slice(&digest);
+    handshake
+}
+
+fn make_valid_tls_handshake(secret: &[u8], timestamp: u32) -> Vec<u8> {
+    make_valid_tls_handshake_with_session_id(secret, timestamp, &[0x42; 32])
+}
+
+// ------------------------------------------------------------------
+// Truncated Packet Tests (OWASP ASVS 5.1.4, 5.1.5)
+// ------------------------------------------------------------------
+
+#[test]
+fn validate_tls_handshake_truncated_10_bytes_rejected() {
+    let secrets = vec![("user".to_string(), b"secret".to_vec())];
+    let truncated = make_garbage(10);
+    assert!(validate_tls_handshake(&truncated, &secrets, true).is_none());
+}
+
+#[test]
+fn validate_tls_handshake_truncated_at_digest_start_rejected() {
+    let secrets = vec![("user".to_string(), b"secret".to_vec())];
+    // TLS_DIGEST_POS = 11. 11 bytes should be rejected.
+    let truncated = make_garbage(TLS_DIGEST_POS);
+    assert!(validate_tls_handshake(&truncated, &secrets, true).is_none());
+}
+
+#[test]
+fn validate_tls_handshake_truncated_inside_digest_rejected() {
+    let secrets = vec![("user".to_string(), b"secret".to_vec())];
+    // TLS_DIGEST_POS + 16 (half digest)
+    let truncated = make_garbage(TLS_DIGEST_POS + 16);
+    assert!(validate_tls_handshake(&truncated, &secrets, true).is_none());
+}
+
+#[test]
+fn extract_sni_truncated_at_record_header_rejected() {
+    let truncated = make_garbage(3);
+    assert!(extract_sni_from_client_hello(&truncated).is_none());
+}
+
+#[test]
+fn extract_sni_truncated_at_handshake_header_rejected() {
+    let mut truncated = vec![TLS_RECORD_HANDSHAKE, 0x03, 0x03, 0x00, 0x05];
+    truncated.extend_from_slice(&[0x01, 0x00]); // ClientHello type but truncated length
+    assert!(extract_sni_from_client_hello(&truncated).is_none());
+}
+
+// ------------------------------------------------------------------
+// Malformed Extension Parsing Tests
+// ------------------------------------------------------------------
+
+#[test]
+fn extract_sni_with_overlapping_extension_lengths_rejected() {
+    let mut h = vec![0x16, 0x03, 0x03, 0x00, 0x60]; // Record header
+    h.push(0x01); // Handshake type: ClientHello
+    h.extend_from_slice(&[0x00, 0x00, 0x5C]); // Length: 92
+    h.extend_from_slice(&[0x03, 0x03]); // Version
+    h.extend_from_slice(&[0u8; 32]); // Random
+    h.push(0); // Session ID length: 0
+    h.extend_from_slice(&[0x00, 0x02, 0x13, 0x01]); // Cipher suites
+    h.extend_from_slice(&[0x01, 0x00]); // Compression
+
+    // Extensions start
+    h.extend_from_slice(&[0x00, 0x20]); // Total Extensions length: 32
+
+    // Extension 1: SNI (type 0)
+    h.extend_from_slice(&[0x00, 0x00]);
+    h.extend_from_slice(&[0x00, 0x40]); // Claimed len: 64 (OVERFLOWS total extensions len 32)
+    h.extend_from_slice(&[0u8; 64]);
+
+    assert!(extract_sni_from_client_hello(&h).is_none());
+}
+
+#[test]
+fn extract_sni_with_infinite_loop_potential_extension_rejected() {
+    let mut h = vec![0x16, 0x03, 0x03, 0x00, 0x60]; // Record header
+    h.push(0x01); // Handshake type: ClientHello
+    h.extend_from_slice(&[0x00, 0x00, 0x5C]); // Length: 92
+    h.extend_from_slice(&[0x03, 0x03]); // Version
+    h.extend_from_slice(&[0u8; 32]); // Random
+    h.push(0); // Session ID length: 0
+    h.extend_from_slice(&[0x00, 0x02, 0x13, 0x01]); // Cipher suites
+    h.extend_from_slice(&[0x01, 0x00]); // Compression
+
+    // Extensions start
+    h.extend_from_slice(&[0x00, 0x10]); // Total Extensions length: 16
+
+    // Extension: zero length but claims more?
+    // If our parser didn't advance, it might loop.
+    // Telemt uses `pos += 4 + elen;` so it always advances.
+    h.extend_from_slice(&[0x12, 0x34]); // Unknown type
+    h.extend_from_slice(&[0x00, 0x00]); // Length 0
+
+    // Fill the rest with garbage
+    h.extend_from_slice(&[0x42; 12]);
+
+    // We expect it to finish without SNI found
+    assert!(extract_sni_from_client_hello(&h).is_none());
+}
+
+#[test]
+fn extract_sni_with_invalid_hostname_rejected() {
+    let host = b"invalid_host!%^";
+    let mut sni = Vec::new();
+    sni.extend_from_slice(&((host.len() + 3) as u16).to_be_bytes());
+    sni.push(0);
+    sni.extend_from_slice(&(host.len() as u16).to_be_bytes());
+    sni.extend_from_slice(host);
+
+    let mut h = vec![0x16, 0x03, 0x03, 0x00, 0x60]; // Record header
+    h.push(0x01); // ClientHello
+    h.extend_from_slice(&[0x00, 0x00, 0x5C]);
+    h.extend_from_slice(&[0x03, 0x03]);
+    h.extend_from_slice(&[0u8; 32]);
+    h.push(0);
+    h.extend_from_slice(&[0x00, 0x02, 0x13, 0x01]);
+    h.extend_from_slice(&[0x01, 0x00]);
+
+    let mut ext = Vec::new();
+    ext.extend_from_slice(&0x0000u16.to_be_bytes());
+    ext.extend_from_slice(&(sni.len() as u16).to_be_bytes());
+    ext.extend_from_slice(&sni);
+
+    h.extend_from_slice(&(ext.len() as u16).to_be_bytes());
+    h.extend_from_slice(&ext);
+
+    assert!(
+        extract_sni_from_client_hello(&h).is_none(),
+        "Invalid SNI hostname must be rejected"
+    );
+}
+
+// ------------------------------------------------------------------
+// Timing Neutrality Tests (OWASP ASVS 5.1.7)
+// ------------------------------------------------------------------
+
+#[test]
+fn validate_tls_handshake_timing_neutrality() {
+    let secret = b"timing_test_secret_32_bytes_long_";
+    let secrets = vec![("u".to_string(), secret.to_vec())];
+
+    let mut base = vec![0x42u8; 100];
+    base[TLS_DIGEST_POS + TLS_DIGEST_LEN] = 32;
+
+    const ITER: usize = 600;
+    const ROUNDS: usize = 7;
+
+    let mut per_round_avg_diff_ns = Vec::with_capacity(ROUNDS);
+
+    for round in 0..ROUNDS {
+        let mut success_h = base.clone();
+        let mut fail_h = base.clone();
+
+        let start_success = Instant::now();
+        for _ in 0..ITER {
+            let digest = make_digest(secret, &success_h, 0);
+            success_h[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN].copy_from_slice(&digest);
+            let _ = validate_tls_handshake_at_time(&success_h, &secrets, true, 0);
+        }
+        let success_elapsed = start_success.elapsed();
+
+        let start_fail = Instant::now();
+        for i in 0..ITER {
+            let mut digest = make_digest(secret, &fail_h, 0);
+            let flip_idx = (i + round) % (TLS_DIGEST_LEN - 4);
+            digest[flip_idx] ^= 0xFF;
+            fail_h[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN].copy_from_slice(&digest);
+            let _ = validate_tls_handshake_at_time(&fail_h, &secrets, true, 0);
+        }
+        let fail_elapsed = start_fail.elapsed();
+
+        let diff = if success_elapsed > fail_elapsed {
+            success_elapsed - fail_elapsed
+        } else {
+            fail_elapsed - success_elapsed
+        };
+        per_round_avg_diff_ns.push(diff.as_nanos() as f64 / ITER as f64);
+    }
+
+    per_round_avg_diff_ns.sort_by(|a, b| a.partial_cmp(b).unwrap());
+    let median_avg_diff_ns = per_round_avg_diff_ns[ROUNDS / 2];
+
+    // Keep this as a coarse side-channel guard only; noisy shared CI hosts can
+    // introduce microsecond-level jitter that should not fail deterministic suites.
+    assert!(
+        median_avg_diff_ns < 50_000.0,
+        "Median timing delta too large: {} ns/iter",
+        median_avg_diff_ns
+    );
+}
+
+// ------------------------------------------------------------------
+// Adversarial Fingerprinting / Active Probing Tests
+// ------------------------------------------------------------------
+
+#[test]
+fn is_tls_handshake_robustness_against_probing() {
+    // Valid TLS 1.0 ClientHello
+    assert!(is_tls_handshake(&[0x16, 0x03, 0x01]));
+    // Valid TLS 1.2/1.3 ClientHello (Legacy Record Layer)
+    assert!(is_tls_handshake(&[0x16, 0x03, 0x03]));
+
+    // Invalid record type but matching version
+    assert!(!is_tls_handshake(&[0x17, 0x03, 0x03]));
+    // Plaintext HTTP request
+    assert!(!is_tls_handshake(b"GET / HTTP/1.1"));
+    // Short garbage
+    assert!(!is_tls_handshake(&[0x16, 0x03]));
+}
+
+#[test]
+fn validate_tls_handshake_at_time_strict_boundary() {
+    let secret = b"strict_boundary_secret_32_bytes_";
+    let secrets = vec![("u".to_string(), secret.to_vec())];
+    let now: i64 = 1_000_000_000;
+
+    // Boundary: exactly TIME_SKEW_MAX (120s past)
+    let ts_past = (now - TIME_SKEW_MAX) as u32;
+    let h = make_valid_tls_handshake_with_session_id(secret, ts_past, &[0x42; 32]);
+    assert!(validate_tls_handshake_at_time(&h, &secrets, false, now).is_some());
+
+    // Boundary + 1s: should be rejected
+    let ts_too_past = (now - TIME_SKEW_MAX - 1) as u32;
+    let h2 = make_valid_tls_handshake_with_session_id(secret, ts_too_past, &[0x42; 32]);
+    assert!(validate_tls_handshake_at_time(&h2, &secrets, false, now).is_none());
+}
+
+#[test]
+fn extract_sni_with_duplicate_extensions_rejected() {
+    // Construct a ClientHello with TWO SNI extensions
+    let host1 = b"first.com";
+    let mut sni1 = Vec::new();
+    sni1.extend_from_slice(&((host1.len() + 3) as u16).to_be_bytes());
+    sni1.push(0);
+    sni1.extend_from_slice(&(host1.len() as u16).to_be_bytes());
+    sni1.extend_from_slice(host1);
+
+    let host2 = b"second.com";
+    let mut sni2 = Vec::new();
+    sni2.extend_from_slice(&((host2.len() + 3) as u16).to_be_bytes());
+    sni2.push(0);
+    sni2.extend_from_slice(&(host2.len() as u16).to_be_bytes());
+    sni2.extend_from_slice(host2);
+
+    let mut ext = Vec::new();
+    // Ext 1: SNI
+    ext.extend_from_slice(&0x0000u16.to_be_bytes());
+    ext.extend_from_slice(&(sni1.len() as u16).to_be_bytes());
+    ext.extend_from_slice(&sni1);
+    // Ext 2: SNI again
+    ext.extend_from_slice(&0x0000u16.to_be_bytes());
+    ext.extend_from_slice(&(sni2.len() as u16).to_be_bytes());
+    ext.extend_from_slice(&sni2);
+
+    let mut body = Vec::new();
+    body.extend_from_slice(&[0x03, 0x03]);
+    body.extend_from_slice(&[0u8; 32]);
+    body.push(0);
+    body.extend_from_slice(&[0x00, 0x02, 0x13, 0x01]);
+    body.extend_from_slice(&[0x01, 0x00]);
+    body.extend_from_slice(&(ext.len() as u16).to_be_bytes());
+    body.extend_from_slice(&ext);
+
+    let mut handshake = Vec::new();
+    handshake.push(0x01);
+    let body_len = (body.len() as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len[1..4]);
+    handshake.extend_from_slice(&body);
+
+    let mut h = Vec::new();
+    h.push(0x16);
+    h.extend_from_slice(&[0x03, 0x03]);
+    h.extend_from_slice(&(handshake.len() as u16).to_be_bytes());
+    h.extend_from_slice(&handshake);
+
+    // Duplicate SNI extensions are ambiguous and must fail closed.
+    assert!(extract_sni_from_client_hello(&h).is_none());
+}
+
+#[test]
+fn extract_alpn_with_malformed_list_rejected() {
+    let mut alpn_payload = Vec::new();
+    alpn_payload.extend_from_slice(&0x0005u16.to_be_bytes()); // Total len 5
+    alpn_payload.push(10); // Labeled len 10 (OVERFLOWS total 5)
+    alpn_payload.extend_from_slice(b"h2");
+
+    let mut ext = Vec::new();
+    ext.extend_from_slice(&0x0010u16.to_be_bytes()); // Type: ALPN (16)
+    ext.extend_from_slice(&(alpn_payload.len() as u16).to_be_bytes());
+    ext.extend_from_slice(&alpn_payload);
+
+    let mut h = vec![
+        0x16, 0x03, 0x03, 0x00, 0x40, 0x01, 0x00, 0x00, 0x3C, 0x03, 0x03,
+    ];
+    h.extend_from_slice(&[0u8; 32]);
+    h.push(0);
+    h.extend_from_slice(&[0x00, 0x02, 0x13, 0x01, 0x01, 0x00]);
+    h.extend_from_slice(&(ext.len() as u16).to_be_bytes());
+    h.extend_from_slice(&ext);
+
+    let res = extract_alpn_from_client_hello(&h);
+    assert!(
+        res.is_empty(),
+        "Malformed ALPN list must return empty or fail"
+    );
+}
+
+#[test]
+fn extract_sni_with_huge_extension_header_rejected() {
+    let mut h = vec![0x16, 0x03, 0x03, 0x00, 0x00]; // Record header
+    h.push(0x01); // ClientHello
+    h.extend_from_slice(&[0x00, 0xFF, 0xFF]); // Huge length (65535) - overflows record
+    h.extend_from_slice(&[0x03, 0x03]);
+    h.extend_from_slice(&[0u8; 32]);
+    h.push(0);
+    h.extend_from_slice(&[0x00, 0x02, 0x13, 0x01, 0x01, 0x00]);
+
+    // Extensions start
+    h.extend_from_slice(&[0xFF, 0xFF]); // Total extensions: 65535 (OVERFLOWS everything)
+
+    assert!(extract_sni_from_client_hello(&h).is_none());
+}

src/protocol/tests/tls_fuzz_security_tests.rs

@@ -0,0 +1,210 @@
+use super::*;
+use crate::crypto::sha256_hmac;
+use std::panic::catch_unwind;
+
+fn make_valid_tls_handshake_with_session_id(
+    secret: &[u8],
+    timestamp: u32,
+    session_id: &[u8],
+) -> Vec<u8> {
+    let session_id_len = session_id.len();
+    assert!(session_id_len <= u8::MAX as usize);
+
+    let len = TLS_DIGEST_POS + TLS_DIGEST_LEN + 1 + session_id_len;
+    let mut handshake = vec![0x42u8; len];
+    handshake[TLS_DIGEST_POS + TLS_DIGEST_LEN] = session_id_len as u8;
+    let sid_start = TLS_DIGEST_POS + TLS_DIGEST_LEN + 1;
+    handshake[sid_start..sid_start + session_id_len].copy_from_slice(session_id);
+    handshake[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN].fill(0);
+
+    let mut digest = sha256_hmac(secret, &handshake);
+    let ts = timestamp.to_le_bytes();
+    for idx in 0..4 {
+        digest[28 + idx] ^= ts[idx];
+    }
+
+    handshake[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN].copy_from_slice(&digest);
+    handshake
+}
+
+fn make_valid_client_hello_record(host: &str, alpn_protocols: &[&[u8]]) -> Vec<u8> {
+    let mut body = Vec::new();
+    body.extend_from_slice(&TLS_VERSION);
+    body.extend_from_slice(&[0u8; 32]);
+    body.push(0);
+    body.extend_from_slice(&2u16.to_be_bytes());
+    body.extend_from_slice(&[0x13, 0x01]);
+    body.push(1);
+    body.push(0);
+
+    let mut ext_blob = Vec::new();
+
+    let host_bytes = host.as_bytes();
+    let mut sni_payload = Vec::new();
+    sni_payload.extend_from_slice(&((host_bytes.len() + 3) as u16).to_be_bytes());
+    sni_payload.push(0);
+    sni_payload.extend_from_slice(&(host_bytes.len() as u16).to_be_bytes());
+    sni_payload.extend_from_slice(host_bytes);
+    ext_blob.extend_from_slice(&0x0000u16.to_be_bytes());
+    ext_blob.extend_from_slice(&(sni_payload.len() as u16).to_be_bytes());
+    ext_blob.extend_from_slice(&sni_payload);
+
+    if !alpn_protocols.is_empty() {
+        let mut alpn_list = Vec::new();
+        for proto in alpn_protocols {
+            alpn_list.push(proto.len() as u8);
+            alpn_list.extend_from_slice(proto);
+        }
+        let mut alpn_data = Vec::new();
+        alpn_data.extend_from_slice(&(alpn_list.len() as u16).to_be_bytes());
+        alpn_data.extend_from_slice(&alpn_list);
+
+        ext_blob.extend_from_slice(&0x0010u16.to_be_bytes());
+        ext_blob.extend_from_slice(&(alpn_data.len() as u16).to_be_bytes());
+        ext_blob.extend_from_slice(&alpn_data);
+    }
+
+    body.extend_from_slice(&(ext_blob.len() as u16).to_be_bytes());
+    body.extend_from_slice(&ext_blob);
+
+    let mut handshake = Vec::new();
+    handshake.push(0x01);
+    let body_len = (body.len() as u32).to_be_bytes();
+    handshake.extend_from_slice(&body_len[1..4]);
+    handshake.extend_from_slice(&body);
+
+    let mut record = Vec::new();
+    record.push(TLS_RECORD_HANDSHAKE);
+    record.extend_from_slice(&[0x03, 0x01]);
+    record.extend_from_slice(&(handshake.len() as u16).to_be_bytes());
+    record.extend_from_slice(&handshake);
+    record
+}
+
+#[test]
+fn client_hello_fuzz_corpus_never_panics_or_accepts_corruption() {
+    let valid = make_valid_client_hello_record("example.com", &[b"h2", b"http/1.1"]);
+    assert_eq!(
+        extract_sni_from_client_hello(&valid).as_deref(),
+        Some("example.com")
+    );
+    assert_eq!(
+        extract_alpn_from_client_hello(&valid),
+        vec![b"h2".to_vec(), b"http/1.1".to_vec()]
+    );
+    assert!(
+        extract_sni_from_client_hello(&make_valid_client_hello_record("127.0.0.1", &[])).is_none(),
+        "literal IP hostnames must be rejected"
+    );
+
+    let mut corpus = vec![
+        Vec::new(),
+        vec![0x16, 0x03, 0x03],
+        valid[..9].to_vec(),
+        valid[..valid.len() - 1].to_vec(),
+    ];
+
+    let mut wrong_type = valid.clone();
+    wrong_type[0] = 0x15;
+    corpus.push(wrong_type);
+
+    let mut wrong_handshake = valid.clone();
+    wrong_handshake[5] = 0x02;
+    corpus.push(wrong_handshake);
+
+    let mut wrong_length = valid.clone();
+    wrong_length[3] ^= 0x7f;
+    corpus.push(wrong_length);
+
+    for (idx, input) in corpus.iter().enumerate() {
+        assert!(catch_unwind(|| extract_sni_from_client_hello(input)).is_ok());
+        assert!(catch_unwind(|| extract_alpn_from_client_hello(input)).is_ok());
+
+        if idx == 0 {
+            continue;
+        }
+
+        assert!(
+            extract_sni_from_client_hello(input).is_none(),
+            "corpus item {idx} must fail closed for SNI"
+        );
+        assert!(
+            extract_alpn_from_client_hello(input).is_empty(),
+            "corpus item {idx} must fail closed for ALPN"
+        );
+    }
+}
+
+#[test]
+fn tls_handshake_fuzz_corpus_never_panics_and_rejects_digest_mutations() {
+    let secret = b"tls_fuzz_security_secret";
+    let now: i64 = 1_700_000_000;
+    let base = make_valid_tls_handshake_with_session_id(secret, now as u32, &[0x42; 32]);
+    let secrets = vec![("fuzz-user".to_string(), secret.to_vec())];
+
+    assert!(validate_tls_handshake_at_time(&base, &secrets, false, now).is_some());
+
+    let mut corpus = Vec::new();
+
+    let mut truncated = base.clone();
+    truncated.truncate(TLS_DIGEST_POS + 16);
+    corpus.push(truncated);
+
+    let mut digest_flip = base.clone();
+    digest_flip[TLS_DIGEST_POS + 7] ^= 0x80;
+    corpus.push(digest_flip);
+
+    let mut session_id_len_overflow = base.clone();
+    session_id_len_overflow[TLS_DIGEST_POS + TLS_DIGEST_LEN] = 33;
+    corpus.push(session_id_len_overflow);
+
+    let mut timestamp_far_past = base.clone();
+    timestamp_far_past[TLS_DIGEST_POS + 28..TLS_DIGEST_POS + 32]
+        .copy_from_slice(&((now - i64::from(TIME_SKEW_MAX) - 1) as u32).to_le_bytes());
+    corpus.push(timestamp_far_past);
+
+    let mut timestamp_far_future = base.clone();
+    timestamp_far_future[TLS_DIGEST_POS + 28..TLS_DIGEST_POS + 32]
+        .copy_from_slice(&((now - TIME_SKEW_MIN + 1) as u32).to_le_bytes());
+    corpus.push(timestamp_far_future);
+
+    let mut seed = 0xA5A5_5A5A_F00D_BAAD_u64;
+    for _ in 0..32 {
+        let mut mutated = base.clone();
+        for _ in 0..2 {
+            seed = seed
+                .wrapping_mul(2862933555777941757)
+                .wrapping_add(3037000493);
+            let idx = TLS_DIGEST_POS + (seed as usize % TLS_DIGEST_LEN);
+            mutated[idx] ^= ((seed >> 17) as u8).wrapping_add(1);
+        }
+        corpus.push(mutated);
+    }
+
+    for (idx, handshake) in corpus.iter().enumerate() {
+        let result =
+            catch_unwind(|| validate_tls_handshake_at_time(handshake, &secrets, false, now));
+        assert!(result.is_ok(), "corpus item {idx} must not panic");
+        assert!(
+            result.unwrap().is_none(),
+            "corpus item {idx} must fail closed"
+        );
+    }
+}
+
+#[test]
+fn tls_boot_time_acceptance_is_capped_by_replay_window() {
+    let secret = b"tls_boot_time_cap_secret";
+    let secrets = vec![("boot-user".to_string(), secret.to_vec())];
+    let boot_ts = 1u32;
+    let handshake = make_valid_tls_handshake_with_session_id(secret, boot_ts, &[0x42; 32]);
+
+    assert!(
+        validate_tls_handshake_with_replay_window(&handshake, &secrets, false, 300).is_some(),
+        "boot-time timestamp should be accepted while replay window permits it"
+    );
+    assert!(
+        validate_tls_handshake_with_replay_window(&handshake, &secrets, false, 0).is_none(),
+        "boot-time timestamp must be rejected when replay window disables the bypass"
+    );
+}

src/protocol/tests/tls_length_cast_hardening_security_tests.rs

@@ -0,0 +1,37 @@
+use super::*;
+
+#[test]
+fn extension_builder_fails_closed_on_u16_length_overflow() {
+    let builder = TlsExtensionBuilder {
+        extensions: vec![0u8; (u16::MAX as usize) + 1],
+    };
+
+    let built = builder.build();
+    assert!(
+        built.is_empty(),
+        "oversized extension blob must fail closed instead of truncating length field"
+    );
+}
+
+#[test]
+fn server_hello_builder_fails_closed_on_session_id_len_overflow() {
+    let builder = ServerHelloBuilder {
+        random: [0u8; 32],
+        session_id: vec![0xAB; (u8::MAX as usize) + 1],
+        cipher_suite: cipher_suite::TLS_AES_128_GCM_SHA256,
+        compression: 0,
+        extensions: TlsExtensionBuilder::new(),
+    };
+
+    let message = builder.build_message();
+    let record = builder.build_record();
+
+    assert!(
+        message.is_empty(),
+        "session_id length overflow must fail closed in message builder"
+    );
+    assert!(
+        record.is_empty(),
+        "session_id length overflow must fail closed in record builder"
+    );
+}

src/protocol/tests/tls_size_constants_security_tests.rs

@@ -0,0 +1,11 @@
+use super::{MAX_TLS_CIPHERTEXT_SIZE, MAX_TLS_PLAINTEXT_SIZE, MIN_TLS_CLIENT_HELLO_SIZE};
+
+#[test]
+fn tls_size_constants_match_rfc_8446() {
+    assert_eq!(MAX_TLS_PLAINTEXT_SIZE, 16_384);
+    assert_eq!(MAX_TLS_CIPHERTEXT_SIZE, 16_640);
+
+    assert!(MIN_TLS_CLIENT_HELLO_SIZE < 512);
+    assert!(MIN_TLS_CLIENT_HELLO_SIZE > 64);
+    assert!(MAX_TLS_CIPHERTEXT_SIZE > MAX_TLS_PLAINTEXT_SIZE);
+}

src/protocol/tls.rs

@@ -5,15 +5,69 @@
 //! actually carries MTProto authentication data.
 
 #![allow(dead_code)]
+#![cfg_attr(not(test), forbid(clippy::undocumented_unsafe_blocks))]
+#![cfg_attr(
+    not(test),
+    deny(
+        clippy::unwrap_used,
+        clippy::expect_used,
+        clippy::panic,
+        clippy::todo,
+        clippy::unimplemented,
+        clippy::correctness,
+        clippy::option_if_let_else,
+        clippy::or_fun_call,
+        clippy::branches_sharing_code,
+        clippy::single_option_map,
+        clippy::useless_let_if_seq,
+        clippy::redundant_locals,
+        clippy::cloned_ref_to_slice_refs,
+        unsafe_code,
+        clippy::await_holding_lock,
+        clippy::await_holding_refcell_ref,
+        clippy::debug_assert_with_mut_call,
+        clippy::macro_use_imports,
+        clippy::cast_ptr_alignment,
+        clippy::cast_lossless,
+        clippy::ptr_as_ptr,
+        clippy::large_stack_arrays,
+        clippy::same_functions_in_if_condition,
+        trivial_casts,
+        trivial_numeric_casts,
+        unused_extern_crates,
+        unused_import_braces,
+        rust_2018_idioms
+    )
+)]
+#![cfg_attr(
+    not(test),
+    allow(
+        clippy::use_self,
+        clippy::redundant_closure,
+        clippy::too_many_arguments,
+        clippy::doc_markdown,
+        clippy::missing_const_for_fn,
+        clippy::unnecessary_operation,
+        clippy::redundant_pub_crate,
+        clippy::derive_partial_eq_without_eq,
+        clippy::type_complexity,
+        clippy::new_ret_no_self,
+        clippy::cast_possible_truncation,
+        clippy::cast_possible_wrap,
+        clippy::significant_drop_tightening,
+        clippy::significant_drop_in_scrutinee,
+        clippy::float_cmp,
+        clippy::nursery
+    )
+)]
 
-use crate::crypto::{sha256_hmac, SecureRandom};
+use super::constants::*;
+use crate::crypto::{SecureRandom, sha256_hmac};
 #[cfg(test)]
 use crate::error::ProxyError;
-use super::constants::*;
 use std::time::{SystemTime, UNIX_EPOCH};
-use num_bigint::BigUint;
-use num_traits::One;
 use subtle::ConstantTimeEq;
+use x25519_dalek::{X25519_BASEPOINT_BYTES, x25519};
 
 // ============= Public Constants =============
 
@@ -27,10 +81,17 @@ pub const TLS_DIGEST_POS: usize = 11;
 pub const TLS_DIGEST_HALF_LEN: usize = 16;
 
 /// Time skew limits for anti-replay (in seconds)
-pub const TIME_SKEW_MIN: i64 = -20 * 60; // 20 minutes before
-pub const TIME_SKEW_MAX: i64 = 10 * 60;  // 10 minutes after
+///
+/// The default window is intentionally narrow to reduce replay acceptance.
+/// Operators with known clock-drifted clients should tune deployment config
+/// (for example replay-window policy) to match their environment.
+pub const TIME_SKEW_MIN: i64 = -2 * 60; // 2 minutes before
+pub const TIME_SKEW_MAX: i64 = 2 * 60; // 2 minutes after
 /// Maximum accepted boot-time timestamp (seconds) before skew checks are enforced.
 pub const BOOT_TIME_MAX_SECS: u32 = 7 * 24 * 60 * 60;
+/// Hard cap for boot-time compatibility bypass to avoid oversized acceptance
+/// windows when replay TTL is configured very large.
+pub const BOOT_TIME_COMPAT_MAX_SECS: u32 = 2 * 60;
 
 // ============= Private Constants =============
 
@@ -80,80 +141,63 @@ impl TlsExtensionBuilder {
             extensions: Vec::with_capacity(128),
         }
     }
-    
+
     /// Add Key Share extension with X25519 key
     fn add_key_share(&mut self, public_key: &[u8; 32]) -> &mut Self {
         // Extension type: key_share (0x0033)
-        self.extensions.extend_from_slice(&extension_type::KEY_SHARE.to_be_bytes());
-        
+        self.extensions
+            .extend_from_slice(&extension_type::KEY_SHARE.to_be_bytes());
+
         // Key share entry: curve (2) + key_len (2) + key (32) = 36 bytes
         // Extension data length
         let entry_len: u16 = 2 + 2 + 32; // curve + length + key
         self.extensions.extend_from_slice(&entry_len.to_be_bytes());
-        
+
         // Named curve: x25519
-        self.extensions.extend_from_slice(&named_curve::X25519.to_be_bytes());
-        
+        self.extensions
+            .extend_from_slice(&named_curve::X25519.to_be_bytes());
+
         // Key length
         self.extensions.extend_from_slice(&(32u16).to_be_bytes());
-        
+
         // Key data
         self.extensions.extend_from_slice(public_key);
-        
+
         self
     }
-    
+
     /// Add Supported Versions extension
     fn add_supported_versions(&mut self, version: u16) -> &mut Self {
         // Extension type: supported_versions (0x002b)
-        self.extensions.extend_from_slice(&extension_type::SUPPORTED_VERSIONS.to_be_bytes());
-        
+        self.extensions
+            .extend_from_slice(&extension_type::SUPPORTED_VERSIONS.to_be_bytes());
+
         // Extension data: length (2) + version (2)
         self.extensions.extend_from_slice(&(2u16).to_be_bytes());
-        
+
         // Selected version
         self.extensions.extend_from_slice(&version.to_be_bytes());
-        
+
         self
     }
 
-    /// Add ALPN extension with a single selected protocol.
-    fn add_alpn(&mut self, proto: &[u8]) -> &mut Self {
-        // Extension type: ALPN (0x0010)
-        self.extensions.extend_from_slice(&extension_type::ALPN.to_be_bytes());
-
-        // ALPN extension format:
-        // extension_data length (2 bytes)
-        //   protocols length (2 bytes)
-        //     protocol name length (1 byte)
-        //     protocol name bytes
-        let proto_len = proto.len() as u8;
-        let list_len: u16 = 1 + u16::from(proto_len);
-        let ext_len: u16 = 2 + list_len;
-
-        self.extensions.extend_from_slice(&ext_len.to_be_bytes());
-        self.extensions.extend_from_slice(&list_len.to_be_bytes());
-        self.extensions.push(proto_len);
-        self.extensions.extend_from_slice(proto);
-        self
-    }
-    
     /// Build final extensions with length prefix
     fn build(self) -> Vec<u8> {
+        let Ok(len) = u16::try_from(self.extensions.len()) else {
+            return Vec::new();
+        };
         let mut result = Vec::with_capacity(2 + self.extensions.len());
-        
+
         // Extensions length (2 bytes)
-        let len = self.extensions.len() as u16;
         result.extend_from_slice(&len.to_be_bytes());
-        
+
         // Extensions data
         result.extend_from_slice(&self.extensions);
-        
+
         result
     }
-    
+
     /// Get current extensions without length prefix (for calculation)
-    #[allow(dead_code)]
     fn as_bytes(&self) -> &[u8] {
         &self.extensions
     }
@@ -173,8 +217,6 @@ struct ServerHelloBuilder {
     compression: u8,
     /// Extensions
     extensions: TlsExtensionBuilder,
-    /// Selected ALPN protocol (if any)
-    alpn: Option<Vec<u8>>,
 }
 
 impl ServerHelloBuilder {
@@ -185,35 +227,30 @@ impl ServerHelloBuilder {
             cipher_suite: cipher_suite::TLS_AES_128_GCM_SHA256,
             compression: 0x00,
             extensions: TlsExtensionBuilder::new(),
-            alpn: None,
         }
     }
-    
+
     fn with_x25519_key(mut self, key: &[u8; 32]) -> Self {
         self.extensions.add_key_share(key);
         self
     }
-    
+
     fn with_tls13_version(mut self) -> Self {
         // TLS 1.3 = 0x0304
         self.extensions.add_supported_versions(0x0304);
         self
     }
 
-    fn with_alpn(mut self, proto: Option<Vec<u8>>) -> Self {
-        self.alpn = proto;
-        self
-    }
-    
     /// Build ServerHello message (without record header)
     fn build_message(&self) -> Vec<u8> {
-        let mut ext_builder = self.extensions.clone();
-        if let Some(ref alpn) = self.alpn {
-            ext_builder.add_alpn(alpn);
-        }
-        let extensions = ext_builder.extensions.clone();
-        let extensions_len = extensions.len() as u16;
-        
+        let Ok(session_id_len) = u8::try_from(self.session_id.len()) else {
+            return Vec::new();
+        };
+        let extensions = self.extensions.extensions.clone();
+        let Ok(extensions_len) = u16::try_from(extensions.len()) else {
+            return Vec::new();
+        };
+
         // Calculate total length
         let body_len = 2 + // version
                        32 + // random
@@ -221,55 +258,67 @@ impl ServerHelloBuilder {
                        2 + // cipher suite
                        1 + // compression
                        2 + extensions.len(); // extensions length + data
-        
+        if body_len > 0x00ff_ffff {
+            return Vec::new();
+        }
+
         let mut message = Vec::with_capacity(4 + body_len);
-        
+
         // Handshake header
         message.push(0x02); // ServerHello message type
-        
+
         // 3-byte length
-        let len_bytes = (body_len as u32).to_be_bytes();
+        let Ok(body_len_u32) = u32::try_from(body_len) else {
+            return Vec::new();
+        };
+        let len_bytes = body_len_u32.to_be_bytes();
         message.extend_from_slice(&len_bytes[1..4]);
-        
+
         // Server version (TLS 1.2 in header, actual version in extension)
         message.extend_from_slice(&TLS_VERSION);
-        
+
         // Random (32 bytes) - placeholder, will be replaced with digest
         message.extend_from_slice(&self.random);
-        
+
         // Session ID
-        message.push(self.session_id.len() as u8);
+        message.push(session_id_len);
         message.extend_from_slice(&self.session_id);
-        
+
         // Cipher suite
         message.extend_from_slice(&self.cipher_suite);
-        
+
         // Compression method
         message.push(self.compression);
-        
+
         // Extensions length
         message.extend_from_slice(&extensions_len.to_be_bytes());
-        
+
         // Extensions data
         message.extend_from_slice(&extensions);
-        
+
         message
     }
-    
+
     /// Build complete ServerHello TLS record
     fn build_record(&self) -> Vec<u8> {
         let message = self.build_message();
-        
+        if message.is_empty() {
+            return Vec::new();
+        }
+        let Ok(message_len) = u16::try_from(message.len()) else {
+            return Vec::new();
+        };
+
         let mut record = Vec::with_capacity(5 + message.len());
-        
+
         // TLS record header
         record.push(TLS_RECORD_HANDSHAKE);
         record.extend_from_slice(&TLS_VERSION);
-        record.extend_from_slice(&(message.len() as u16).to_be_bytes());
-        
+        record.extend_from_slice(&message_len.to_be_bytes());
+
         // Message
         record.extend_from_slice(&message);
-        
+
         record
     }
 }
@@ -296,9 +345,9 @@ pub fn validate_tls_handshake(
 
 /// Validate TLS ClientHello and cap the boot-time bypass by replay-cache TTL.
 ///
-/// A boot-time timestamp is only accepted when it falls below both
-/// `BOOT_TIME_MAX_SECS` and the configured replay window, preventing timestamp
-/// reuse outside replay cache coverage.
+/// A boot-time timestamp is only accepted when it falls below all three
+/// bounds: `BOOT_TIME_MAX_SECS`, configured replay window, and
+/// `BOOT_TIME_COMPAT_MAX_SECS`, preventing oversized compatibility windows.
 #[must_use]
 pub fn validate_tls_handshake_with_replay_window(
     handshake: &[u8],
@@ -316,7 +365,16 @@ pub fn validate_tls_handshake_with_replay_window(
     };
 
     let replay_window_u32 = u32::try_from(replay_window_secs).unwrap_or(u32::MAX);
-    let boot_time_cap_secs = BOOT_TIME_MAX_SECS.min(replay_window_u32);
+    // Boot-time bypass and ignore_time_skew serve different compatibility paths.
+    // When skew checks are disabled, force boot-time cap to zero to prevent
+    // accidental future coupling of boot-time logic into the ignore-skew path.
+    let boot_time_cap_secs = if ignore_time_skew {
+        0
+    } else {
+        BOOT_TIME_MAX_SECS
+            .min(replay_window_u32)
+            .min(BOOT_TIME_COMPAT_MAX_SECS)
+    };
 
     validate_tls_handshake_at_time_with_boot_cap(
         handshake,
@@ -360,27 +418,30 @@ fn validate_tls_handshake_at_time_with_boot_cap(
     if handshake.len() < TLS_DIGEST_POS + TLS_DIGEST_LEN + 1 {
         return None;
     }
-    
+
     // Extract digest
     let digest: [u8; TLS_DIGEST_LEN] = handshake[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN]
         .try_into()
         .ok()?;
-    
+
     // Extract session ID
     let session_id_len_pos = TLS_DIGEST_POS + TLS_DIGEST_LEN;
     let session_id_len = handshake.get(session_id_len_pos).copied()? as usize;
+    if session_id_len > 32 {
+        return None;
+    }
     let session_id_start = session_id_len_pos + 1;
-    
+
     if handshake.len() < session_id_start + session_id_len {
         return None;
     }
-    
+
     let session_id = handshake[session_id_start..session_id_start + session_id_len].to_vec();
-    
+
     // Build message for HMAC (with zeroed digest)
     let mut msg = handshake.to_vec();
     msg[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN].fill(0);
-    
+
     let mut first_match: Option<(&String, u32)> = None;
 
     for (user, secret) in secrets {
@@ -411,7 +472,7 @@ fn validate_tls_handshake_at_time_with_boot_cap(
         if !ignore_time_skew {
             // Allow very small timestamps (boot time instead of unix time)
             // This is a quirk in some clients that use uptime instead of real time
-            let is_boot_time = timestamp < boot_time_cap_secs;
+            let is_boot_time = boot_time_cap_secs > 0 && timestamp < boot_time_cap_secs;
             if !is_boot_time {
                 let time_diff = now - i64::from(timestamp);
                 if !(TIME_SKEW_MIN..=TIME_SKEW_MAX).contains(&time_diff) {
@@ -419,7 +480,7 @@ fn validate_tls_handshake_at_time_with_boot_cap(
                 }
             }
         }
-        
+
         if first_match.is_none() {
             first_match = Some((user, timestamp));
         }
@@ -433,27 +494,14 @@ fn validate_tls_handshake_at_time_with_boot_cap(
     })
 }
 
-fn curve25519_prime() -> BigUint {
-    (BigUint::one() << 255) - BigUint::from(19u32)
-}
-
 /// Generate a fake X25519 public key for TLS
 ///
-/// Produces a quadratic residue mod p = 2^255 - 19 by computing n² mod p,
-/// which matches Python/C behavior and avoids DPI fingerprinting.
+/// Uses RFC 7748 X25519 scalar multiplication over the canonical basepoint,
+/// yielding distribution-consistent public keys for anti-fingerprinting.
 pub fn gen_fake_x25519_key(rng: &SecureRandom) -> [u8; 32] {
-    let mut n_bytes = [0u8; 32];
-    n_bytes.copy_from_slice(&rng.bytes(32));
-
-    let n = BigUint::from_bytes_le(&n_bytes);
-    let p = curve25519_prime();
-    let pk = (&n * &n) % &p;
-
-    let mut out = pk.to_bytes_le();
-    out.resize(32, 0);
-    let mut result = [0u8; 32];
-    result.copy_from_slice(&out[..32]);
-    result
+    let mut scalar = [0u8; 32];
+    scalar.copy_from_slice(&rng.bytes(32));
+    x25519(scalar, X25519_BASEPOINT_BYTES)
 }
 
 /// Build TLS ServerHello response
@@ -474,27 +522,50 @@ pub fn build_server_hello(
     new_session_tickets: u8,
 ) -> Vec<u8> {
     const MIN_APP_DATA: usize = 64;
-    const MAX_APP_DATA: usize = 16640; // RFC 8446 §5.2 upper bound
+    const MAX_APP_DATA: usize = MAX_TLS_CIPHERTEXT_SIZE;
     let fake_cert_len = fake_cert_len.clamp(MIN_APP_DATA, MAX_APP_DATA);
     let x25519_key = gen_fake_x25519_key(rng);
-    
+
     // Build ServerHello
     let server_hello = ServerHelloBuilder::new(session_id.to_vec())
         .with_x25519_key(&x25519_key)
         .with_tls13_version()
-        .with_alpn(alpn)
         .build_record();
-    
+
     // Build Change Cipher Spec record
     let change_cipher_spec = [
         TLS_RECORD_CHANGE_CIPHER,
-        TLS_VERSION[0], TLS_VERSION[1],
-        0x00, 0x01, // length = 1
-        0x01,       // CCS byte
+        TLS_VERSION[0],
+        TLS_VERSION[1],
+        0x00,
+        0x01, // length = 1
+        0x01, // CCS byte
     ];
-    
-    // Build fake certificate (Application Data record)
-    let fake_cert = rng.bytes(fake_cert_len);
+
+    // Build first encrypted flight mimic as opaque ApplicationData bytes.
+    // Embed a compact EncryptedExtensions-like ALPN block when selected.
+    let mut fake_cert = Vec::with_capacity(fake_cert_len);
+    if let Some(proto) = alpn
+        .as_ref()
+        .filter(|p| !p.is_empty() && p.len() <= u8::MAX as usize)
+    {
+        let proto_list_len = 1usize + proto.len();
+        let ext_data_len = 2usize + proto_list_len;
+        let marker_len = 4usize + ext_data_len;
+        if marker_len <= fake_cert_len {
+            fake_cert.extend_from_slice(&0x0010u16.to_be_bytes());
+            fake_cert.extend_from_slice(&(ext_data_len as u16).to_be_bytes());
+            fake_cert.extend_from_slice(&(proto_list_len as u16).to_be_bytes());
+            fake_cert.push(proto.len() as u8);
+            fake_cert.extend_from_slice(proto);
+        }
+    }
+    if fake_cert.len() < fake_cert_len {
+        fake_cert.extend_from_slice(&rng.bytes(fake_cert_len - fake_cert.len()));
+    } else if fake_cert.len() > fake_cert_len {
+        fake_cert.truncate(fake_cert_len);
+    }
+
     let mut app_data_record = Vec::with_capacity(5 + fake_cert_len);
     app_data_record.push(TLS_RECORD_APPLICATION);
     app_data_record.extend_from_slice(&TLS_VERSION);
@@ -502,12 +573,13 @@ pub fn build_server_hello(
     // Fill ApplicationData with fully random bytes of desired length to avoid
     // deterministic DPI fingerprints (fixed inner content type markers).
     app_data_record.extend_from_slice(&fake_cert);
-    
+
     // Build optional NewSessionTicket records (TLS 1.3 handshake messages are encrypted;
     // here we mimic with opaque ApplicationData records of plausible size).
     let mut tickets = Vec::new();
-    if new_session_tickets > 0 {
-        for _ in 0..new_session_tickets {
+    let ticket_count = new_session_tickets.min(4);
+    if ticket_count > 0 {
+        for _ in 0..ticket_count {
             let ticket_len: usize = rng.range(48) + 48; // 48-95 bytes
             let mut record = Vec::with_capacity(5 + ticket_len);
             record.push(TLS_RECORD_APPLICATION);
@@ -520,7 +592,10 @@ pub fn build_server_hello(
 
     // Combine all records
     let mut response = Vec::with_capacity(
-        server_hello.len() + change_cipher_spec.len() + app_data_record.len() + tickets.iter().map(|r| r.len()).sum::<usize>()
+        server_hello.len()
+            + change_cipher_spec.len()
+            + app_data_record.len()
+            + tickets.iter().map(|r| r.len()).sum::<usize>(),
     );
     response.extend_from_slice(&server_hello);
     response.extend_from_slice(&change_cipher_spec);
@@ -528,18 +603,17 @@ pub fn build_server_hello(
     for t in &tickets {
         response.extend_from_slice(t);
     }
-    
+
     // Compute HMAC for the response
     let mut hmac_input = Vec::with_capacity(TLS_DIGEST_LEN + response.len());
     hmac_input.extend_from_slice(client_digest);
     hmac_input.extend_from_slice(&response);
     let response_digest = sha256_hmac(secret, &hmac_input);
-    
+
     // Insert computed digest into ServerHello
     // Position: record header (5) + message type (1) + length (3) + version (2) = 11
-    response[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN]
-        .copy_from_slice(&response_digest);
-    
+    response[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN].copy_from_slice(&response_digest);
+
     response
 }
 
@@ -549,6 +623,11 @@ pub fn extract_sni_from_client_hello(handshake: &[u8]) -> Option<String> {
         return None;
     }
 
+    let record_len = u16::from_be_bytes([handshake[3], handshake[4]]) as usize;
+    if handshake.len() < 5 + record_len {
+        return None;
+    }
+
     let mut pos = 5; // after record header
     if handshake.get(pos).copied()? != 0x01 {
         return None; // not ClientHello
@@ -588,6 +667,9 @@ pub fn extract_sni_from_client_hello(handshake: &[u8]) -> Option<String> {
         return None;
     }
 
+    let mut saw_sni_extension = false;
+    let mut extracted_sni = None;
+
     while pos + 4 <= ext_end {
         let etype = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]);
         let elen = u16::from_be_bytes([handshake[pos + 2], handshake[pos + 3]]) as usize;
@@ -595,6 +677,12 @@ pub fn extract_sni_from_client_hello(handshake: &[u8]) -> Option<String> {
         if pos + elen > ext_end {
             break;
         }
+        if etype == 0x0000 {
+            if saw_sni_extension {
+                return None;
+            }
+            saw_sni_extension = true;
+        }
         if etype == 0x0000 && elen >= 5 {
             // server_name extension
             let list_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
@@ -602,17 +690,19 @@ pub fn extract_sni_from_client_hello(handshake: &[u8]) -> Option<String> {
             let sn_end = std::cmp::min(sn_pos + list_len, pos + elen);
             while sn_pos + 3 <= sn_end {
                 let name_type = handshake[sn_pos];
-                let name_len = u16::from_be_bytes([handshake[sn_pos + 1], handshake[sn_pos + 2]]) as usize;
+                let name_len =
+                    u16::from_be_bytes([handshake[sn_pos + 1], handshake[sn_pos + 2]]) as usize;
                 sn_pos += 3;
                 if sn_pos + name_len > sn_end {
                     break;
                 }
-                if name_type == 0 && name_len > 0
+                if name_type == 0
+                    && name_len > 0
                     && let Ok(host) = std::str::from_utf8(&handshake[sn_pos..sn_pos + name_len])
+                    && is_valid_sni_hostname(host)
                 {
-                    if is_valid_sni_hostname(host) {
-                        return Some(host.to_string());
-                    }
+                    extracted_sni = Some(host.to_string());
+                    break;
                 }
                 sn_pos += name_len;
             }
@@ -620,7 +710,7 @@ pub fn extract_sni_from_client_hello(handshake: &[u8]) -> Option<String> {
         pos += elen;
     }
 
-    None
+    extracted_sni
 }
 
 fn is_valid_sni_hostname(host: &str) -> bool {
@@ -654,41 +744,64 @@ fn is_valid_sni_hostname(host: &str) -> bool {
 
 /// Extract ALPN protocol list from ClientHello, return in offered order.
 pub fn extract_alpn_from_client_hello(handshake: &[u8]) -> Vec<Vec<u8>> {
+    if handshake.len() < 5 || handshake[0] != TLS_RECORD_HANDSHAKE {
+        return Vec::new();
+    }
+
+    let record_len = u16::from_be_bytes([handshake[3], handshake[4]]) as usize;
+    if handshake.len() < 5 + record_len {
+        return Vec::new();
+    }
+
     let mut pos = 5; // after record header
     if handshake.get(pos) != Some(&0x01) {
         return Vec::new();
     }
     pos += 4; // type + len
     pos += 2 + 32; // version + random
-    if pos >= handshake.len() { return Vec::new(); }
+    if pos >= handshake.len() {
+        return Vec::new();
+    }
     let session_id_len = *handshake.get(pos).unwrap_or(&0) as usize;
     pos += 1 + session_id_len;
-    if pos + 2 > handshake.len() { return Vec::new(); }
-    let cipher_len = u16::from_be_bytes([handshake[pos], handshake[pos+1]]) as usize;
+    if pos + 2 > handshake.len() {
+        return Vec::new();
+    }
+    let cipher_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
     pos += 2 + cipher_len;
-    if pos >= handshake.len() { return Vec::new(); }
+    if pos >= handshake.len() {
+        return Vec::new();
+    }
     let comp_len = *handshake.get(pos).unwrap_or(&0) as usize;
     pos += 1 + comp_len;
-    if pos + 2 > handshake.len() { return Vec::new(); }
-    let ext_len = u16::from_be_bytes([handshake[pos], handshake[pos+1]]) as usize;
+    if pos + 2 > handshake.len() {
+        return Vec::new();
+    }
+    let ext_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
     pos += 2;
     let ext_end = pos + ext_len;
-    if ext_end > handshake.len() { return Vec::new(); }
+    if ext_end > handshake.len() {
+        return Vec::new();
+    }
     let mut out = Vec::new();
     while pos + 4 <= ext_end {
-        let etype = u16::from_be_bytes([handshake[pos], handshake[pos+1]]);
-        let elen = u16::from_be_bytes([handshake[pos+2], handshake[pos+3]]) as usize;
+        let etype = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]);
+        let elen = u16::from_be_bytes([handshake[pos + 2], handshake[pos + 3]]) as usize;
         pos += 4;
-        if pos + elen > ext_end { break; }
+        if pos + elen > ext_end {
+            break;
+        }
         if etype == extension_type::ALPN && elen >= 3 {
-            let list_len = u16::from_be_bytes([handshake[pos], handshake[pos+1]]) as usize;
+            let list_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
             let mut lp = pos + 2;
             let list_end = (pos + 2).saturating_add(list_len).min(pos + elen);
             while lp < list_end {
                 let plen = handshake[lp] as usize;
                 lp += 1;
-                if lp + plen > list_end { break; }
-                out.push(handshake[lp..lp+plen].to_vec());
+                if lp + plen > list_end {
+                    break;
+                }
+                out.push(handshake[lp..lp + plen].to_vec());
                 lp += plen;
             }
             break;
@@ -698,29 +811,28 @@ pub fn extract_alpn_from_client_hello(handshake: &[u8]) -> Vec<Vec<u8>> {
     out
 }
 
-
 /// Check if bytes look like a TLS ClientHello
 pub fn is_tls_handshake(first_bytes: &[u8]) -> bool {
     if first_bytes.len() < 3 {
         return false;
     }
-    
-    // TLS record header: 0x16 (handshake) 0x03 0x01 (TLS 1.0)
-    first_bytes[0] == TLS_RECORD_HANDSHAKE 
-        && first_bytes[1] == 0x03 
-        && first_bytes[2] == 0x01
+
+    // TLS ClientHello commonly uses legacy record versions 0x0301 or 0x0303.
+    first_bytes[0] == TLS_RECORD_HANDSHAKE
+        && first_bytes[1] == 0x03
+        && (first_bytes[2] == 0x01 || first_bytes[2] == 0x03)
 }
 
 /// Parse TLS record header, returns (record_type, length)
 pub fn parse_tls_record_header(header: &[u8; 5]) -> Option<(u8, u16)> {
     let record_type = header[0];
     let version = [header[1], header[2]];
-    
+
     // We accept both TLS 1.0 header (for ClientHello) and TLS 1.2/1.3
     if version != [0x03, 0x01] && version != TLS_VERSION {
         return None;
     }
-    
+
     let length = u16::from_be_bytes([header[3], header[4]]);
     Some((record_type, length))
 }
@@ -736,7 +848,7 @@ fn validate_server_hello_structure(data: &[u8]) -> Result<(), ProxyError> {
             version: [0, 0],
         });
     }
-    
+
     // Check record header
     if data[0] != TLS_RECORD_HANDSHAKE {
         return Err(ProxyError::InvalidTlsRecord {
@@ -744,7 +856,7 @@ fn validate_server_hello_structure(data: &[u8]) -> Result<(), ProxyError> {
             version: [data[1], data[2]],
         });
     }
-    
+
     // Check version
     if data[1..3] != TLS_VERSION {
         return Err(ProxyError::InvalidTlsRecord {
@@ -752,31 +864,34 @@ fn validate_server_hello_structure(data: &[u8]) -> Result<(), ProxyError> {
             version: [data[1], data[2]],
         });
     }
-    
+
     // Check record length
     let record_len = u16::from_be_bytes([data[3], data[4]]) as usize;
     if data.len() < 5 + record_len {
-        return Err(ProxyError::InvalidHandshake(
-            format!("ServerHello record truncated: expected {}, got {}", 
-                5 + record_len, data.len())
-        ));
+        return Err(ProxyError::InvalidHandshake(format!(
+            "ServerHello record truncated: expected {}, got {}",
+            5 + record_len,
+            data.len()
+        )));
     }
-    
+
     // Check message type
     if data[5] != 0x02 {
-        return Err(ProxyError::InvalidHandshake(
-            format!("Expected ServerHello (0x02), got 0x{:02x}", data[5])
-        ));
+        return Err(ProxyError::InvalidHandshake(format!(
+            "Expected ServerHello (0x02), got 0x{:02x}",
+            data[5]
+        )));
     }
-    
+
     // Parse message length
     let msg_len = u32::from_be_bytes([0, data[6], data[7], data[8]]) as usize;
     if msg_len + 4 != record_len {
-        return Err(ProxyError::InvalidHandshake(
-            format!("Message length mismatch: {} + 4 != {}", msg_len, record_len)
-        ));
+        return Err(ProxyError::InvalidHandshake(format!(
+            "Message length mismatch: {} + 4 != {}",
+            msg_len, record_len
+        )));
     }
-    
+
     Ok(())
 }
 
@@ -786,7 +901,7 @@ fn validate_server_hello_structure(data: &[u8]) -> Result<(), ProxyError> {
 /// Using `static_assertions` ensures these can never silently break across
 /// refactors without a compile error.
 mod compile_time_security_checks {
-    use super::{TLS_DIGEST_LEN, TLS_DIGEST_HALF_LEN};
+    use super::{TLS_DIGEST_HALF_LEN, TLS_DIGEST_LEN};
     use static_assertions::const_assert;
 
     // The digest must be exactly one SHA-256 output.
@@ -804,5 +919,17 @@ mod compile_time_security_checks {
 // ============= Security-focused regression tests =============
 
 #[cfg(test)]
-#[path = "tls_security_tests.rs"]
+#[path = "tests/tls_security_tests.rs"]
 mod security_tests;
+
+#[cfg(test)]
+#[path = "tests/tls_adversarial_tests.rs"]
+mod adversarial_tests;
+
+#[cfg(test)]
+#[path = "tests/tls_fuzz_security_tests.rs"]
+mod fuzz_security_tests;
+
+#[cfg(test)]
+#[path = "tests/tls_length_cast_hardening_security_tests.rs"]
+mod length_cast_hardening_security_tests;

src/proxy/adaptive_buffers.rs

@@ -0,0 +1,380 @@
+#![allow(dead_code)]
+
+// Adaptive buffer policy is staged and retained for deterministic rollout.
+// Keep definitions compiled for compatibility and security test scaffolding.
+
+use dashmap::DashMap;
+use std::cmp::max;
+use std::sync::OnceLock;
+use std::time::{Duration, Instant};
+
+const EMA_ALPHA: f64 = 0.2;
+const PROFILE_TTL: Duration = Duration::from_secs(300);
+const THROUGHPUT_UP_BPS: f64 = 8_000_000.0;
+const THROUGHPUT_DOWN_BPS: f64 = 2_000_000.0;
+const RATIO_CONFIRM_THRESHOLD: f64 = 1.12;
+const TIER1_HOLD_TICKS: u32 = 8;
+const TIER2_HOLD_TICKS: u32 = 4;
+const QUIET_DEMOTE_TICKS: u32 = 480;
+const HARD_COOLDOWN_TICKS: u32 = 20;
+const HARD_PENDING_THRESHOLD: u32 = 3;
+const HARD_PARTIAL_RATIO_THRESHOLD: f64 = 0.25;
+const DIRECT_C2S_CAP_BYTES: usize = 128 * 1024;
+const DIRECT_S2C_CAP_BYTES: usize = 512 * 1024;
+const ME_FRAMES_CAP: usize = 96;
+const ME_BYTES_CAP: usize = 384 * 1024;
+const ME_DELAY_MIN_US: u64 = 150;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum AdaptiveTier {
+    Base = 0,
+    Tier1 = 1,
+    Tier2 = 2,
+    Tier3 = 3,
+}
+
+impl AdaptiveTier {
+    pub fn promote(self) -> Self {
+        match self {
+            Self::Base => Self::Tier1,
+            Self::Tier1 => Self::Tier2,
+            Self::Tier2 => Self::Tier3,
+            Self::Tier3 => Self::Tier3,
+        }
+    }
+
+    pub fn demote(self) -> Self {
+        match self {
+            Self::Base => Self::Base,
+            Self::Tier1 => Self::Base,
+            Self::Tier2 => Self::Tier1,
+            Self::Tier3 => Self::Tier2,
+        }
+    }
+
+    fn ratio(self) -> (usize, usize) {
+        match self {
+            Self::Base => (1, 1),
+            Self::Tier1 => (5, 4),
+            Self::Tier2 => (3, 2),
+            Self::Tier3 => (2, 1),
+        }
+    }
+
+    pub fn as_u8(self) -> u8 {
+        self as u8
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TierTransitionReason {
+    SoftConfirmed,
+    HardPressure,
+    QuietDemotion,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TierTransition {
+    pub from: AdaptiveTier,
+    pub to: AdaptiveTier,
+    pub reason: TierTransitionReason,
+}
+
+#[derive(Debug, Clone, Copy, Default)]
+pub struct RelaySignalSample {
+    pub c2s_bytes: u64,
+    pub s2c_requested_bytes: u64,
+    pub s2c_written_bytes: u64,
+    pub s2c_write_ops: u64,
+    pub s2c_partial_writes: u64,
+    pub s2c_consecutive_pending_writes: u32,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct SessionAdaptiveController {
+    tier: AdaptiveTier,
+    max_tier_seen: AdaptiveTier,
+    throughput_ema_bps: f64,
+    incoming_ema_bps: f64,
+    outgoing_ema_bps: f64,
+    tier1_hold_ticks: u32,
+    tier2_hold_ticks: u32,
+    quiet_ticks: u32,
+    hard_cooldown_ticks: u32,
+}
+
+impl SessionAdaptiveController {
+    pub fn new(initial_tier: AdaptiveTier) -> Self {
+        Self {
+            tier: initial_tier,
+            max_tier_seen: initial_tier,
+            throughput_ema_bps: 0.0,
+            incoming_ema_bps: 0.0,
+            outgoing_ema_bps: 0.0,
+            tier1_hold_ticks: 0,
+            tier2_hold_ticks: 0,
+            quiet_ticks: 0,
+            hard_cooldown_ticks: 0,
+        }
+    }
+
+    pub fn max_tier_seen(&self) -> AdaptiveTier {
+        self.max_tier_seen
+    }
+
+    pub fn observe(&mut self, sample: RelaySignalSample, tick_secs: f64) -> Option<TierTransition> {
+        if tick_secs <= f64::EPSILON {
+            return None;
+        }
+
+        if self.hard_cooldown_ticks > 0 {
+            self.hard_cooldown_ticks -= 1;
+        }
+
+        let c2s_bps = (sample.c2s_bytes as f64 * 8.0) / tick_secs;
+        let incoming_bps = (sample.s2c_requested_bytes as f64 * 8.0) / tick_secs;
+        let outgoing_bps = (sample.s2c_written_bytes as f64 * 8.0) / tick_secs;
+        let throughput = c2s_bps.max(outgoing_bps);
+
+        self.throughput_ema_bps = ema(self.throughput_ema_bps, throughput);
+        self.incoming_ema_bps = ema(self.incoming_ema_bps, incoming_bps);
+        self.outgoing_ema_bps = ema(self.outgoing_ema_bps, outgoing_bps);
+
+        let tier1_now = self.throughput_ema_bps >= THROUGHPUT_UP_BPS;
+        if tier1_now {
+            self.tier1_hold_ticks = self.tier1_hold_ticks.saturating_add(1);
+        } else {
+            self.tier1_hold_ticks = 0;
+        }
+
+        let ratio = if self.outgoing_ema_bps <= f64::EPSILON {
+            0.0
+        } else {
+            self.incoming_ema_bps / self.outgoing_ema_bps
+        };
+        let tier2_now = ratio >= RATIO_CONFIRM_THRESHOLD;
+        if tier2_now {
+            self.tier2_hold_ticks = self.tier2_hold_ticks.saturating_add(1);
+        } else {
+            self.tier2_hold_ticks = 0;
+        }
+
+        let partial_ratio = if sample.s2c_write_ops == 0 {
+            0.0
+        } else {
+            sample.s2c_partial_writes as f64 / sample.s2c_write_ops as f64
+        };
+        let hard_now = sample.s2c_consecutive_pending_writes >= HARD_PENDING_THRESHOLD
+            || partial_ratio >= HARD_PARTIAL_RATIO_THRESHOLD;
+
+        if hard_now && self.hard_cooldown_ticks == 0 {
+            return self.promote(TierTransitionReason::HardPressure, HARD_COOLDOWN_TICKS);
+        }
+
+        if self.tier1_hold_ticks >= TIER1_HOLD_TICKS && self.tier2_hold_ticks >= TIER2_HOLD_TICKS {
+            return self.promote(TierTransitionReason::SoftConfirmed, 0);
+        }
+
+        let demote_candidate =
+            self.throughput_ema_bps < THROUGHPUT_DOWN_BPS && !tier2_now && !hard_now;
+        if demote_candidate {
+            self.quiet_ticks = self.quiet_ticks.saturating_add(1);
+            if self.quiet_ticks >= QUIET_DEMOTE_TICKS {
+                self.quiet_ticks = 0;
+                return self.demote(TierTransitionReason::QuietDemotion);
+            }
+        } else {
+            self.quiet_ticks = 0;
+        }
+
+        None
+    }
+
+    fn promote(
+        &mut self,
+        reason: TierTransitionReason,
+        hard_cooldown_ticks: u32,
+    ) -> Option<TierTransition> {
+        let from = self.tier;
+        let to = from.promote();
+        if from == to {
+            return None;
+        }
+        self.tier = to;
+        self.max_tier_seen = max(self.max_tier_seen, to);
+        self.hard_cooldown_ticks = hard_cooldown_ticks;
+        self.tier1_hold_ticks = 0;
+        self.tier2_hold_ticks = 0;
+        self.quiet_ticks = 0;
+        Some(TierTransition { from, to, reason })
+    }
+
+    fn demote(&mut self, reason: TierTransitionReason) -> Option<TierTransition> {
+        let from = self.tier;
+        let to = from.demote();
+        if from == to {
+            return None;
+        }
+        self.tier = to;
+        self.tier1_hold_ticks = 0;
+        self.tier2_hold_ticks = 0;
+        Some(TierTransition { from, to, reason })
+    }
+}
+
+#[derive(Debug, Clone, Copy)]
+struct UserAdaptiveProfile {
+    tier: AdaptiveTier,
+    seen_at: Instant,
+}
+
+fn profiles() -> &'static DashMap<String, UserAdaptiveProfile> {
+    static USER_PROFILES: OnceLock<DashMap<String, UserAdaptiveProfile>> = OnceLock::new();
+    USER_PROFILES.get_or_init(DashMap::new)
+}
+
+pub fn seed_tier_for_user(user: &str) -> AdaptiveTier {
+    let now = Instant::now();
+    if let Some(entry) = profiles().get(user) {
+        let value = entry.value();
+        if now.duration_since(value.seen_at) <= PROFILE_TTL {
+            return value.tier;
+        }
+    }
+    AdaptiveTier::Base
+}
+
+pub fn record_user_tier(user: &str, tier: AdaptiveTier) {
+    let now = Instant::now();
+    if let Some(mut entry) = profiles().get_mut(user) {
+        let existing = *entry;
+        let effective = if now.duration_since(existing.seen_at) > PROFILE_TTL {
+            tier
+        } else {
+            max(existing.tier, tier)
+        };
+        *entry = UserAdaptiveProfile {
+            tier: effective,
+            seen_at: now,
+        };
+        return;
+    }
+    profiles().insert(user.to_string(), UserAdaptiveProfile { tier, seen_at: now });
+}
+
+pub fn direct_copy_buffers_for_tier(
+    tier: AdaptiveTier,
+    base_c2s: usize,
+    base_s2c: usize,
+) -> (usize, usize) {
+    let (num, den) = tier.ratio();
+    (
+        scale(base_c2s, num, den, DIRECT_C2S_CAP_BYTES),
+        scale(base_s2c, num, den, DIRECT_S2C_CAP_BYTES),
+    )
+}
+
+pub fn me_flush_policy_for_tier(
+    tier: AdaptiveTier,
+    base_frames: usize,
+    base_bytes: usize,
+    base_delay: Duration,
+) -> (usize, usize, Duration) {
+    let (num, den) = tier.ratio();
+    let frames = scale(base_frames, num, den, ME_FRAMES_CAP).max(1);
+    let bytes = scale(base_bytes, num, den, ME_BYTES_CAP).max(4096);
+    let delay_us = base_delay.as_micros() as u64;
+    let adjusted_delay_us = match tier {
+        AdaptiveTier::Base => delay_us,
+        AdaptiveTier::Tier1 => (delay_us.saturating_mul(7)).saturating_div(10),
+        AdaptiveTier::Tier2 => delay_us.saturating_div(2),
+        AdaptiveTier::Tier3 => (delay_us.saturating_mul(3)).saturating_div(10),
+    }
+    .max(ME_DELAY_MIN_US)
+    .min(delay_us.max(ME_DELAY_MIN_US));
+    (frames, bytes, Duration::from_micros(adjusted_delay_us))
+}
+
+fn ema(prev: f64, value: f64) -> f64 {
+    if prev <= f64::EPSILON {
+        value
+    } else {
+        (prev * (1.0 - EMA_ALPHA)) + (value * EMA_ALPHA)
+    }
+}
+
+fn scale(base: usize, numerator: usize, denominator: usize, cap: usize) -> usize {
+    let scaled = base
+        .saturating_mul(numerator)
+        .saturating_div(denominator.max(1));
+    scaled.min(cap).max(1)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample(
+        c2s_bytes: u64,
+        s2c_requested_bytes: u64,
+        s2c_written_bytes: u64,
+        s2c_write_ops: u64,
+        s2c_partial_writes: u64,
+        s2c_consecutive_pending_writes: u32,
+    ) -> RelaySignalSample {
+        RelaySignalSample {
+            c2s_bytes,
+            s2c_requested_bytes,
+            s2c_written_bytes,
+            s2c_write_ops,
+            s2c_partial_writes,
+            s2c_consecutive_pending_writes,
+        }
+    }
+
+    #[test]
+    fn test_soft_promotion_requires_tier1_and_tier2() {
+        let mut ctrl = SessionAdaptiveController::new(AdaptiveTier::Base);
+        let tick_secs = 0.25;
+        let mut promoted = None;
+        for _ in 0..8 {
+            promoted = ctrl.observe(
+                sample(
+                    300_000, // ~9.6 Mbps
+                    320_000, // incoming > outgoing to confirm tier2
+                    250_000, 10, 0, 0,
+                ),
+                tick_secs,
+            );
+        }
+
+        let transition = promoted.expect("expected soft promotion");
+        assert_eq!(transition.from, AdaptiveTier::Base);
+        assert_eq!(transition.to, AdaptiveTier::Tier1);
+        assert_eq!(transition.reason, TierTransitionReason::SoftConfirmed);
+    }
+
+    #[test]
+    fn test_hard_promotion_on_pending_pressure() {
+        let mut ctrl = SessionAdaptiveController::new(AdaptiveTier::Base);
+        let transition = ctrl
+            .observe(sample(10_000, 20_000, 10_000, 4, 1, 3), 0.25)
+            .expect("expected hard promotion");
+        assert_eq!(transition.reason, TierTransitionReason::HardPressure);
+        assert_eq!(transition.to, AdaptiveTier::Tier1);
+    }
+
+    #[test]
+    fn test_quiet_demotion_is_slow_and_stepwise() {
+        let mut ctrl = SessionAdaptiveController::new(AdaptiveTier::Tier2);
+        let mut demotion = None;
+        for _ in 0..QUIET_DEMOTE_TICKS {
+            demotion = ctrl.observe(sample(1, 1, 1, 1, 0, 0), 0.25);
+        }
+
+        let transition = demotion.expect("expected quiet demotion");
+        assert_eq!(transition.from, AdaptiveTier::Tier2);
+        assert_eq!(transition.to, AdaptiveTier::Tier1);
+        assert_eq!(transition.reason, TierTransitionReason::QuietDemotion);
+    }
+}

src/proxy/direct_relay.rs

@@ -1,12 +1,13 @@
+use std::collections::HashSet;
+use std::ffi::OsString;
 use std::fs::OpenOptions;
 use std::io::Write;
 use std::net::SocketAddr;
+use std::path::{Component, Path, PathBuf};
 use std::sync::Arc;
-use std::collections::HashSet;
 use std::sync::{Mutex, OnceLock};
 
-use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt};
-use tokio::net::TcpStream;
+use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt, ReadHalf, WriteHalf, split};
 use tokio::sync::watch;
 use tracing::{debug, info, warn};
 
@@ -17,21 +18,55 @@ use crate::protocol::constants::*;
 use crate::proxy::handshake::{HandshakeSuccess, encrypt_tg_nonce_with_ciphers, generate_tg_nonce};
 use crate::proxy::relay::relay_bidirectional;
 use crate::proxy::route_mode::{
-    RelayRouteMode, RouteCutoverState, ROUTE_SWITCH_ERROR_MSG, affected_cutover_state,
+    ROUTE_SWITCH_ERROR_MSG, RelayRouteMode, RouteCutoverState, affected_cutover_state,
     cutover_stagger_delay,
 };
 use crate::stats::Stats;
 use crate::stream::{BufferPool, CryptoReader, CryptoWriter};
 use crate::transport::UpstreamManager;
+#[cfg(unix)]
+use nix::fcntl::{Flock, FlockArg, OFlag, openat};
+#[cfg(unix)]
+use nix::sys::stat::Mode;
+
+#[cfg(unix)]
+use std::os::unix::fs::OpenOptionsExt;
 
 const UNKNOWN_DC_LOG_DISTINCT_LIMIT: usize = 1024;
 static LOGGED_UNKNOWN_DCS: OnceLock<Mutex<HashSet<i16>>> = OnceLock::new();
+const MAX_SCOPE_HINT_LEN: usize = 64;
+
+fn validated_scope_hint(user: &str) -> Option<&str> {
+    let scope = user.strip_prefix("scope_")?;
+    if scope.is_empty() || scope.len() > MAX_SCOPE_HINT_LEN {
+        return None;
+    }
+    if scope
+        .bytes()
+        .all(|b| b.is_ascii_alphanumeric() || b == b'-')
+    {
+        Some(scope)
+    } else {
+        None
+    }
+}
+
+#[derive(Clone)]
+struct SanitizedUnknownDcLogPath {
+    resolved_path: PathBuf,
+    allowed_parent: PathBuf,
+    file_name: OsString,
+}
 
 // In tests, this function shares global mutable state. Callers that also use
 // cache-reset helpers must hold `unknown_dc_test_lock()` to keep assertions
 // deterministic under parallel execution.
 fn should_log_unknown_dc(dc_idx: i16) -> bool {
     let set = LOGGED_UNKNOWN_DCS.get_or_init(|| Mutex::new(HashSet::new()));
+    should_log_unknown_dc_with_set(set, dc_idx)
+}
+
+fn should_log_unknown_dc_with_set(set: &Mutex<HashSet<i16>>, dc_idx: i16) -> bool {
     match set.lock() {
         Ok(mut guard) => {
             if guard.contains(&dc_idx) {
@@ -42,9 +77,136 @@ fn should_log_unknown_dc(dc_idx: i16) -> bool {
             }
             guard.insert(dc_idx)
         }
-        // If the lock is poisoned, keep logging rather than silently dropping
-        // operator-visible diagnostics.
-        Err(_) => true,
+        // Fail closed on poisoned state to avoid unbounded blocking log writes.
+        Err(_) => false,
+    }
+}
+
+fn sanitize_unknown_dc_log_path(path: &str) -> Option<SanitizedUnknownDcLogPath> {
+    let candidate = Path::new(path);
+    if candidate.as_os_str().is_empty() {
+        return None;
+    }
+    if candidate
+        .components()
+        .any(|component| matches!(component, Component::ParentDir))
+    {
+        return None;
+    }
+
+    let cwd = std::env::current_dir().ok()?;
+    let file_name = candidate.file_name()?;
+    let parent = candidate.parent().unwrap_or_else(|| Path::new("."));
+    let parent_path = if parent.is_absolute() {
+        parent.to_path_buf()
+    } else {
+        cwd.join(parent)
+    };
+    let canonical_parent = parent_path.canonicalize().ok()?;
+    if !canonical_parent.is_dir() {
+        return None;
+    }
+
+    Some(SanitizedUnknownDcLogPath {
+        resolved_path: canonical_parent.join(file_name),
+        allowed_parent: canonical_parent,
+        file_name: file_name.to_os_string(),
+    })
+}
+
+fn unknown_dc_log_path_is_still_safe(path: &SanitizedUnknownDcLogPath) -> bool {
+    let Some(parent) = path.resolved_path.parent() else {
+        return false;
+    };
+    let Ok(current_parent) = parent.canonicalize() else {
+        return false;
+    };
+    if current_parent != path.allowed_parent {
+        return false;
+    }
+
+    if let Ok(canonical_target) = path.resolved_path.canonicalize() {
+        let Some(target_parent) = canonical_target.parent() else {
+            return false;
+        };
+        let Some(target_name) = canonical_target.file_name() else {
+            return false;
+        };
+        if target_parent != path.allowed_parent || target_name != path.file_name {
+            return false;
+        }
+    }
+
+    true
+}
+
+#[cfg(test)]
+fn open_unknown_dc_log_append(path: &Path) -> std::io::Result<std::fs::File> {
+    #[cfg(unix)]
+    {
+        OpenOptions::new()
+            .create(true)
+            .append(true)
+            .custom_flags(libc::O_NOFOLLOW)
+            .open(path)
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = path;
+        Err(std::io::Error::new(
+            std::io::ErrorKind::PermissionDenied,
+            "unknown_dc_file_log_enabled requires unix O_NOFOLLOW support",
+        ))
+    }
+}
+
+fn open_unknown_dc_log_append_anchored(
+    path: &SanitizedUnknownDcLogPath,
+) -> std::io::Result<std::fs::File> {
+    #[cfg(unix)]
+    {
+        let parent = OpenOptions::new()
+            .read(true)
+            .custom_flags(libc::O_DIRECTORY | libc::O_NOFOLLOW | libc::O_CLOEXEC)
+            .open(&path.allowed_parent)?;
+
+        let oflags = OFlag::O_CREAT
+            | OFlag::O_APPEND
+            | OFlag::O_WRONLY
+            | OFlag::O_NOFOLLOW
+            | OFlag::O_CLOEXEC;
+        let mode = Mode::from_bits_truncate(0o600);
+        let path_component = Path::new(path.file_name.as_os_str());
+        let fd = openat(&parent, path_component, oflags, mode)
+            .map_err(|err| std::io::Error::from_raw_os_error(err as i32))?;
+        let file = std::fs::File::from(fd);
+        Ok(file)
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = path;
+        Err(std::io::Error::new(
+            std::io::ErrorKind::PermissionDenied,
+            "unknown_dc_file_log_enabled requires unix O_NOFOLLOW support",
+        ))
+    }
+}
+
+fn append_unknown_dc_line(file: &mut std::fs::File, dc_idx: i16) -> std::io::Result<()> {
+    #[cfg(unix)]
+    {
+        let cloned = file.try_clone()?;
+        let mut locked = Flock::lock(cloned, FlockArg::LockExclusive)
+            .map_err(|(_, err)| std::io::Error::from_raw_os_error(err as i32))?;
+        let write_result = writeln!(&mut *locked, "dc_idx={dc_idx}");
+        let _ = locked
+            .unlock()
+            .map_err(|(_, err)| std::io::Error::from_raw_os_error(err as i32))?;
+        write_result
+    }
+    #[cfg(not(unix))]
+    {
+        writeln!(file, "dc_idx={dc_idx}")
     }
 }
 
@@ -93,8 +255,15 @@ where
         "Connecting to Telegram DC"
     );
 
+    let scope_hint = validated_scope_hint(user);
+    if user.starts_with("scope_") && scope_hint.is_none() {
+        warn!(
+            user = %user,
+            "Ignoring invalid scope hint and falling back to default upstream selection"
+        );
+    }
     let tg_stream = upstream_manager
-        .connect(dc_addr, Some(success.dc_idx), user.strip_prefix("scope_").filter(|s| !s.is_empty()))
+        .connect(dc_addr, Some(success.dc_idx), scope_hint)
         .await?;
 
     debug!(peer = %success.peer, dc_addr = %dc_addr, "Connected, performing TG handshake");
@@ -105,7 +274,7 @@ where
     debug!(peer = %success.peer, "TG handshake complete, starting relay");
 
     stats.increment_user_connects(user);
-    stats.increment_current_connections_direct();
+    let _direct_connection_lease = stats.acquire_direct_connection_lease();
 
     let relay_result = relay_bidirectional(
         client_reader,
@@ -116,15 +285,14 @@ where
         config.general.direct_relay_copy_buf_s2c_bytes,
         user,
         Arc::clone(&stats),
+        config.access.user_data_quota.get(user).copied(),
         buffer_pool,
     );
     tokio::pin!(relay_result);
     let relay_result = loop {
-        if let Some(cutover) = affected_cutover_state(
-            &route_rx,
-            RelayRouteMode::Direct,
-            route_snapshot.generation,
-        ) {
+        if let Some(cutover) =
+            affected_cutover_state(&route_rx, RelayRouteMode::Direct, route_snapshot.generation)
+        {
             let delay = cutover_stagger_delay(session_id, cutover.generation);
             warn!(
                 user = %user,
@@ -148,8 +316,6 @@ where
         }
     };
 
-    stats.decrement_current_connections_direct();
-
     match &relay_result {
         Ok(()) => debug!(user = %user, "Direct relay completed"),
         Err(e) => debug!(user = %user, error = %e, "Direct relay ended with error"),
@@ -174,7 +340,9 @@ fn get_dc_addr_static(dc_idx: i16, config: &ProxyConfig) -> Result<SocketAddr> {
         for addr_str in addrs {
             match addr_str.parse::<SocketAddr>() {
                 Ok(addr) => parsed.push(addr),
-                Err(_) => warn!(dc_idx = dc_idx, addr_str = %addr_str, "Invalid DC override address in config, ignoring"),
+                Err(_) => {
+                    warn!(dc_idx = dc_idx, addr_str = %addr_str, "Invalid DC override address in config, ignoring")
+                }
             }
         }
 
@@ -196,18 +364,27 @@ fn get_dc_addr_static(dc_idx: i16, config: &ProxyConfig) -> Result<SocketAddr> {
 
     // Unknown DC requested by client without override: log and fall back.
     if !config.dc_overrides.contains_key(&dc_key) {
-        warn!(dc_idx = dc_idx, "Requested non-standard DC with no override; falling back to default cluster");
+        warn!(
+            dc_idx = dc_idx,
+            "Requested non-standard DC with no override; falling back to default cluster"
+        );
         if config.general.unknown_dc_file_log_enabled
             && let Some(path) = &config.general.unknown_dc_log_path
-            && should_log_unknown_dc(dc_idx)
             && let Ok(handle) = tokio::runtime::Handle::try_current()
         {
-            let path = path.clone();
-            handle.spawn_blocking(move || {
-                if let Ok(mut file) = OpenOptions::new().create(true).append(true).open(path) {
-                    let _ = writeln!(file, "dc_idx={dc_idx}");
+            if let Some(path) = sanitize_unknown_dc_log_path(path) {
+                if should_log_unknown_dc(dc_idx) {
+                    handle.spawn_blocking(move || {
+                        if unknown_dc_log_path_is_still_safe(&path)
+                            && let Ok(mut file) = open_unknown_dc_log_append_anchored(&path)
+                        {
+                            let _ = append_unknown_dc_line(&mut file, dc_idx);
+                        }
+                    });
                 }
-            });
+            } else {
+                warn!(dc_idx = dc_idx, raw_path = %path, "Rejected unsafe unknown DC log path");
+            }
         }
     }
 
@@ -231,15 +408,15 @@ fn get_dc_addr_static(dc_idx: i16, config: &ProxyConfig) -> Result<SocketAddr> {
     ))
 }
 
-async fn do_tg_handshake_static(
-    mut stream: TcpStream,
+async fn do_tg_handshake_static<S>(
+    mut stream: S,
     success: &HandshakeSuccess,
     config: &ProxyConfig,
     rng: &SecureRandom,
-) -> Result<(
-    CryptoReader<tokio::net::tcp::OwnedReadHalf>,
-    CryptoWriter<tokio::net::tcp::OwnedWriteHalf>,
-)> {
+) -> Result<(CryptoReader<ReadHalf<S>>, CryptoWriter<WriteHalf<S>>)>
+where
+    S: AsyncRead + AsyncWrite + Unpin,
+{
     let (nonce, _tg_enc_key, _tg_enc_iv, _tg_dec_key, _tg_dec_iv) = generate_tg_nonce(
         success.proto_tag,
         success.dc_idx,
@@ -260,7 +437,7 @@ async fn do_tg_handshake_static(
     stream.write_all(&encrypted_nonce).await?;
     stream.flush().await?;
 
-    let (read_half, write_half) = stream.into_split();
+    let (read_half, write_half) = split(stream);
 
     let max_pending = config.general.crypto_pending_buffer;
     Ok((
@@ -270,5 +447,17 @@ async fn do_tg_handshake_static(
 }
 
 #[cfg(test)]
-#[path = "direct_relay_security_tests.rs"]
+#[path = "tests/direct_relay_security_tests.rs"]
 mod security_tests;
+
+#[cfg(test)]
+#[path = "tests/direct_relay_business_logic_tests.rs"]
+mod business_logic_tests;
+
+#[cfg(test)]
+#[path = "tests/direct_relay_common_mistakes_tests.rs"]
+mod common_mistakes_tests;
+
+#[cfg(test)]
+#[path = "tests/direct_relay_subtle_adversarial_tests.rs"]
+mod subtle_adversarial_tests;

src/proxy/direct_relay_security_tests.rs

@@ -1,51 +0,0 @@
-use super::*;
-
-#[test]
-fn unknown_dc_log_is_deduplicated_per_dc_idx() {
-    let _guard = unknown_dc_test_lock()
-        .lock()
-        .expect("unknown dc test lock must be available");
-    clear_unknown_dc_log_cache_for_testing();
-
-    assert!(should_log_unknown_dc(777));
-    assert!(
-        !should_log_unknown_dc(777),
-        "same unknown dc_idx must not be logged repeatedly"
-    );
-    assert!(
-        should_log_unknown_dc(778),
-        "different unknown dc_idx must still be loggable"
-    );
-}
-
-#[test]
-fn unknown_dc_log_respects_distinct_limit() {
-    let _guard = unknown_dc_test_lock()
-        .lock()
-        .expect("unknown dc test lock must be available");
-    clear_unknown_dc_log_cache_for_testing();
-
-    for dc in 1..=UNKNOWN_DC_LOG_DISTINCT_LIMIT {
-        assert!(
-            should_log_unknown_dc(dc as i16),
-            "expected first-time unknown dc_idx to be loggable"
-        );
-    }
-
-    assert!(
-        !should_log_unknown_dc(i16::MAX),
-        "distinct unknown dc_idx entries above limit must not be logged"
-    );
-}
-
-#[test]
-fn fallback_dc_never_panics_with_single_dc_list() {
-    let mut cfg = ProxyConfig::default();
-    cfg.network.prefer = 6;
-    cfg.network.ipv6 = Some(true);
-    cfg.default_dc = Some(42);
-
-    let addr = get_dc_addr_static(999, &cfg).expect("fallback dc must resolve safely");
-    let expected = SocketAddr::new(TG_DATACENTERS_V6[0], TG_DATACENTER_PORT);
-    assert_eq!(addr, expected);
-}

src/proxy/handshake.rs

@@ -2,32 +2,38 @@
 
 #![allow(dead_code)]
 
-use std::net::SocketAddr;
+use dashmap::DashMap;
+use dashmap::mapref::entry::Entry;
 use std::collections::HashSet;
+use std::collections::hash_map::RandomState;
+use std::hash::{BuildHasher, Hash, Hasher};
+use std::net::SocketAddr;
 use std::net::{IpAddr, Ipv6Addr};
 use std::sync::Arc;
 use std::sync::{Mutex, OnceLock};
-use std::collections::hash_map::DefaultHasher;
-use std::hash::{Hash, Hasher};
 use std::time::{Duration, Instant};
-use dashmap::DashMap;
-use dashmap::mapref::entry::Entry;
 use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt};
-use tracing::{debug, warn, trace};
-use zeroize::Zeroize;
+use tracing::{debug, info, trace, warn};
+use zeroize::{Zeroize, Zeroizing};
 
-use crate::crypto::{sha256, AesCtr, SecureRandom};
-use rand::Rng;
+use crate::config::{ProxyConfig, UnknownSniAction};
+use crate::crypto::{AesCtr, SecureRandom, sha256};
+use crate::error::{HandshakeResult, ProxyError};
 use crate::protocol::constants::*;
 use crate::protocol::tls;
-use crate::stream::{FakeTlsReader, FakeTlsWriter, CryptoReader, CryptoWriter};
-use crate::error::{ProxyError, HandshakeResult};
 use crate::stats::ReplayChecker;
-use crate::config::ProxyConfig;
+use crate::stream::{CryptoReader, CryptoWriter, FakeTlsReader, FakeTlsWriter};
 use crate::tls_front::{TlsFrontCache, emulator};
+use rand::RngExt;
 
 const ACCESS_SECRET_BYTES: usize = 16;
 static INVALID_SECRET_WARNED: OnceLock<Mutex<HashSet<(String, String)>>> = OnceLock::new();
+const UNKNOWN_SNI_WARN_COOLDOWN_SECS: u64 = 5;
+static UNKNOWN_SNI_WARN_NEXT_ALLOWED: OnceLock<Mutex<Option<Instant>>> = OnceLock::new();
+#[cfg(test)]
+const WARNED_SECRET_MAX_ENTRIES: usize = 64;
+#[cfg(not(test))]
+const WARNED_SECRET_MAX_ENTRIES: usize = 1_024;
 
 const AUTH_PROBE_TRACK_RETENTION_SECS: u64 = 10 * 60;
 #[cfg(test)]
@@ -36,6 +42,7 @@ const AUTH_PROBE_TRACK_MAX_ENTRIES: usize = 256;
 const AUTH_PROBE_TRACK_MAX_ENTRIES: usize = 65_536;
 const AUTH_PROBE_PRUNE_SCAN_LIMIT: usize = 1_024;
 const AUTH_PROBE_BACKOFF_START_FAILS: u32 = 4;
+const AUTH_PROBE_SATURATION_GRACE_FAILS: u32 = 2;
 
 #[cfg(test)]
 const AUTH_PROBE_BACKOFF_BASE_MS: u64 = 1;
@@ -54,12 +61,51 @@ struct AuthProbeState {
     last_seen: Instant,
 }
 
+#[derive(Clone, Copy)]
+struct AuthProbeSaturationState {
+    fail_streak: u32,
+    blocked_until: Instant,
+    last_seen: Instant,
+}
+
 static AUTH_PROBE_STATE: OnceLock<DashMap<IpAddr, AuthProbeState>> = OnceLock::new();
+static AUTH_PROBE_SATURATION_STATE: OnceLock<Mutex<Option<AuthProbeSaturationState>>> =
+    OnceLock::new();
+static AUTH_PROBE_EVICTION_HASHER: OnceLock<RandomState> = OnceLock::new();
 
 fn auth_probe_state_map() -> &'static DashMap<IpAddr, AuthProbeState> {
     AUTH_PROBE_STATE.get_or_init(DashMap::new)
 }
 
+fn auth_probe_saturation_state() -> &'static Mutex<Option<AuthProbeSaturationState>> {
+    AUTH_PROBE_SATURATION_STATE.get_or_init(|| Mutex::new(None))
+}
+
+fn auth_probe_saturation_state_lock()
+-> std::sync::MutexGuard<'static, Option<AuthProbeSaturationState>> {
+    auth_probe_saturation_state()
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+fn unknown_sni_warn_state_lock() -> std::sync::MutexGuard<'static, Option<Instant>> {
+    UNKNOWN_SNI_WARN_NEXT_ALLOWED
+        .get_or_init(|| Mutex::new(None))
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+fn should_emit_unknown_sni_warn(now: Instant) -> bool {
+    let mut guard = unknown_sni_warn_state_lock();
+    if let Some(next_allowed) = *guard
+        && now < next_allowed
+    {
+        return false;
+    }
+    *guard = Some(now + Duration::from_secs(UNKNOWN_SNI_WARN_COOLDOWN_SECS));
+    true
+}
+
 fn normalize_auth_probe_ip(peer_ip: IpAddr) -> IpAddr {
     match peer_ip {
         IpAddr::V4(ip) => IpAddr::V4(ip),
@@ -88,12 +134,26 @@ fn auth_probe_state_expired(state: &AuthProbeState, now: Instant) -> bool {
 }
 
 fn auth_probe_eviction_offset(peer_ip: IpAddr, now: Instant) -> usize {
-    let mut hasher = DefaultHasher::new();
+    let hasher_state = AUTH_PROBE_EVICTION_HASHER.get_or_init(RandomState::new);
+    let mut hasher = hasher_state.build_hasher();
     peer_ip.hash(&mut hasher);
     now.hash(&mut hasher);
     hasher.finish() as usize
 }
 
+fn auth_probe_scan_start_offset(
+    peer_ip: IpAddr,
+    now: Instant,
+    state_len: usize,
+    scan_limit: usize,
+) -> usize {
+    if state_len == 0 || scan_limit == 0 {
+        return 0;
+    }
+
+    auth_probe_eviction_offset(peer_ip, now) % state_len
+}
+
 fn auth_probe_is_throttled(peer_ip: IpAddr, now: Instant) -> bool {
     let peer_ip = normalize_auth_probe_ip(peer_ip);
     let state = auth_probe_state_map();
@@ -108,6 +168,75 @@ fn auth_probe_is_throttled(peer_ip: IpAddr, now: Instant) -> bool {
     now < entry.blocked_until
 }
 
+fn auth_probe_saturation_grace_exhausted(peer_ip: IpAddr, now: Instant) -> bool {
+    let peer_ip = normalize_auth_probe_ip(peer_ip);
+    let state = auth_probe_state_map();
+    let Some(entry) = state.get(&peer_ip) else {
+        return false;
+    };
+    if auth_probe_state_expired(&entry, now) {
+        drop(entry);
+        state.remove(&peer_ip);
+        return false;
+    }
+
+    entry.fail_streak >= AUTH_PROBE_BACKOFF_START_FAILS + AUTH_PROBE_SATURATION_GRACE_FAILS
+}
+
+fn auth_probe_should_apply_preauth_throttle(peer_ip: IpAddr, now: Instant) -> bool {
+    if !auth_probe_is_throttled(peer_ip, now) {
+        return false;
+    }
+
+    if !auth_probe_saturation_is_throttled(now) {
+        return true;
+    }
+
+    auth_probe_saturation_grace_exhausted(peer_ip, now)
+}
+
+fn auth_probe_saturation_is_throttled(now: Instant) -> bool {
+    let mut guard = auth_probe_saturation_state_lock();
+
+    let Some(state) = guard.as_mut() else {
+        return false;
+    };
+
+    if now.duration_since(state.last_seen) > Duration::from_secs(AUTH_PROBE_TRACK_RETENTION_SECS) {
+        *guard = None;
+        return false;
+    }
+
+    if now < state.blocked_until {
+        return true;
+    }
+
+    false
+}
+
+fn auth_probe_note_saturation(now: Instant) {
+    let mut guard = auth_probe_saturation_state_lock();
+
+    match guard.as_mut() {
+        Some(state)
+            if now.duration_since(state.last_seen)
+                <= Duration::from_secs(AUTH_PROBE_TRACK_RETENTION_SECS) =>
+        {
+            state.fail_streak = state.fail_streak.saturating_add(1);
+            state.last_seen = now;
+            state.blocked_until = now + auth_probe_backoff(state.fail_streak);
+        }
+        _ => {
+            let fail_streak = AUTH_PROBE_BACKOFF_START_FAILS;
+            *guard = Some(AuthProbeSaturationState {
+                fail_streak,
+                blocked_until: now + auth_probe_backoff(fail_streak),
+                last_seen: now,
+            });
+        }
+    }
+}
+
 fn auth_probe_record_failure(peer_ip: IpAddr, now: Instant) {
     let peer_ip = normalize_auth_probe_ip(peer_ip);
     let state = auth_probe_state_map();
@@ -144,24 +273,107 @@ fn auth_probe_record_failure_with_state(
     }
 
     if state.len() >= AUTH_PROBE_TRACK_MAX_ENTRIES {
-        let mut stale_keys = Vec::new();
-        let mut eviction_candidates = Vec::new();
-        for entry in state.iter().take(AUTH_PROBE_PRUNE_SCAN_LIMIT) {
-            eviction_candidates.push(*entry.key());
-            if auth_probe_state_expired(entry.value(), now) {
-                stale_keys.push(*entry.key());
+        let mut rounds = 0usize;
+        while state.len() >= AUTH_PROBE_TRACK_MAX_ENTRIES {
+            rounds += 1;
+            if rounds > 8 {
+                auth_probe_note_saturation(now);
+                let mut eviction_candidate: Option<(IpAddr, u32, Instant)> = None;
+                for entry in state.iter().take(AUTH_PROBE_PRUNE_SCAN_LIMIT) {
+                    let key = *entry.key();
+                    let fail_streak = entry.value().fail_streak;
+                    let last_seen = entry.value().last_seen;
+                    match eviction_candidate {
+                        Some((_, current_fail, current_seen))
+                            if fail_streak > current_fail
+                                || (fail_streak == current_fail && last_seen >= current_seen) => {}
+                        _ => eviction_candidate = Some((key, fail_streak, last_seen)),
+                    }
+                }
+
+                let Some((evict_key, _, _)) = eviction_candidate else {
+                    return;
+                };
+                state.remove(&evict_key);
+                break;
             }
-        }
-        for stale_key in stale_keys {
-            state.remove(&stale_key);
-        }
-        if state.len() >= AUTH_PROBE_TRACK_MAX_ENTRIES {
-            if eviction_candidates.is_empty() {
+
+            let mut stale_keys = Vec::new();
+            let mut eviction_candidate: Option<(IpAddr, u32, Instant)> = None;
+            let state_len = state.len();
+            let scan_limit = state_len.min(AUTH_PROBE_PRUNE_SCAN_LIMIT);
+
+            if state_len <= AUTH_PROBE_PRUNE_SCAN_LIMIT {
+                for entry in state.iter() {
+                    let key = *entry.key();
+                    let fail_streak = entry.value().fail_streak;
+                    let last_seen = entry.value().last_seen;
+                    match eviction_candidate {
+                        Some((_, current_fail, current_seen))
+                            if fail_streak > current_fail
+                                || (fail_streak == current_fail && last_seen >= current_seen) => {}
+                        _ => eviction_candidate = Some((key, fail_streak, last_seen)),
+                    }
+                    if auth_probe_state_expired(entry.value(), now) {
+                        stale_keys.push(key);
+                    }
+                }
+            } else {
+                let start_offset =
+                    auth_probe_scan_start_offset(peer_ip, now, state_len, scan_limit);
+                let mut scanned = 0usize;
+                for entry in state.iter().skip(start_offset) {
+                    let key = *entry.key();
+                    let fail_streak = entry.value().fail_streak;
+                    let last_seen = entry.value().last_seen;
+                    match eviction_candidate {
+                        Some((_, current_fail, current_seen))
+                            if fail_streak > current_fail
+                                || (fail_streak == current_fail && last_seen >= current_seen) => {}
+                        _ => eviction_candidate = Some((key, fail_streak, last_seen)),
+                    }
+                    if auth_probe_state_expired(entry.value(), now) {
+                        stale_keys.push(key);
+                    }
+                    scanned += 1;
+                    if scanned >= scan_limit {
+                        break;
+                    }
+                }
+
+                if scanned < scan_limit {
+                    for entry in state.iter().take(scan_limit - scanned) {
+                        let key = *entry.key();
+                        let fail_streak = entry.value().fail_streak;
+                        let last_seen = entry.value().last_seen;
+                        match eviction_candidate {
+                            Some((_, current_fail, current_seen))
+                                if fail_streak > current_fail
+                                    || (fail_streak == current_fail
+                                        && last_seen >= current_seen) => {}
+                            _ => eviction_candidate = Some((key, fail_streak, last_seen)),
+                        }
+                        if auth_probe_state_expired(entry.value(), now) {
+                            stale_keys.push(key);
+                        }
+                    }
+                }
+            }
+
+            for stale_key in stale_keys {
+                state.remove(&stale_key);
+            }
+
+            if state.len() < AUTH_PROBE_TRACK_MAX_ENTRIES {
+                break;
+            }
+
+            let Some((evict_key, _, _)) = eviction_candidate else {
+                auth_probe_note_saturation(now);
                 return;
-            }
-            let idx = auth_probe_eviction_offset(peer_ip, now) % eviction_candidates.len();
-            let evict_key = eviction_candidates[idx];
+            };
             state.remove(&evict_key);
+            auth_probe_note_saturation(now);
         }
     }
 
@@ -186,6 +398,10 @@ fn clear_auth_probe_state_for_testing() {
     if let Some(state) = AUTH_PROBE_STATE.get() {
         state.clear();
     }
+    if AUTH_PROBE_SATURATION_STATE.get().is_some() {
+        let mut guard = auth_probe_saturation_state_lock();
+        *guard = None;
+    }
 }
 
 #[cfg(test)]
@@ -200,12 +416,41 @@ fn auth_probe_is_throttled_for_testing(peer_ip: IpAddr) -> bool {
     auth_probe_is_throttled(peer_ip, Instant::now())
 }
 
+#[cfg(test)]
+fn auth_probe_saturation_is_throttled_for_testing() -> bool {
+    auth_probe_saturation_is_throttled(Instant::now())
+}
+
+#[cfg(test)]
+fn auth_probe_saturation_is_throttled_at_for_testing(now: Instant) -> bool {
+    auth_probe_saturation_is_throttled(now)
+}
+
 #[cfg(test)]
 fn auth_probe_test_lock() -> &'static Mutex<()> {
     static TEST_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
     TEST_LOCK.get_or_init(|| Mutex::new(()))
 }
 
+#[cfg(test)]
+fn unknown_sni_warn_test_lock() -> &'static Mutex<()> {
+    static TEST_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    TEST_LOCK.get_or_init(|| Mutex::new(()))
+}
+
+#[cfg(test)]
+fn clear_unknown_sni_warn_state_for_testing() {
+    if UNKNOWN_SNI_WARN_NEXT_ALLOWED.get().is_some() {
+        let mut guard = unknown_sni_warn_state_lock();
+        *guard = None;
+    }
+}
+
+#[cfg(test)]
+fn should_emit_unknown_sni_warn_for_testing(now: Instant) -> bool {
+    should_emit_unknown_sni_warn(now)
+}
+
 #[cfg(test)]
 fn clear_warned_secrets_for_testing() {
     if let Some(warned) = INVALID_SECRET_WARNED.get()
@@ -225,7 +470,13 @@ fn warn_invalid_secret_once(name: &str, reason: &str, expected: usize, got: Opti
     let key = (name.to_string(), reason.to_string());
     let warned = INVALID_SECRET_WARNED.get_or_init(|| Mutex::new(HashSet::new()));
     let should_warn = match warned.lock() {
-        Ok(mut guard) => guard.insert(key),
+        Ok(mut guard) => {
+            if !guard.contains(&key) && guard.len() >= WARNED_SECRET_MAX_ENTRIES {
+                false
+            } else {
+                guard.insert(key)
+            }
+        }
         Err(_) => true,
     };
 
@@ -317,6 +568,39 @@ fn decode_user_secrets(
     secrets
 }
 
+#[inline]
+fn find_matching_tls_domain<'a>(config: &'a ProxyConfig, sni: &str) -> Option<&'a str> {
+    if config.censorship.tls_domain.eq_ignore_ascii_case(sni) {
+        return Some(config.censorship.tls_domain.as_str());
+    }
+
+    for domain in &config.censorship.tls_domains {
+        if domain.eq_ignore_ascii_case(sni) {
+            return Some(domain.as_str());
+        }
+    }
+
+    None
+}
+
+async fn maybe_apply_server_hello_delay(config: &ProxyConfig) {
+    if config.censorship.server_hello_delay_max_ms == 0 {
+        return;
+    }
+
+    let min = config.censorship.server_hello_delay_min_ms;
+    let max = config.censorship.server_hello_delay_max_ms.max(min);
+    let delay_ms = if max == min {
+        max
+    } else {
+        rand::rng().random_range(min..=max)
+    };
+
+    if delay_ms > 0 {
+        tokio::time::sleep(Duration::from_millis(delay_ms)).await;
+    }
+}
+
 /// Result of successful handshake
 ///
 /// Key material (`dec_key`, `dec_iv`, `enc_key`, `enc_iv`) is
@@ -332,7 +616,7 @@ pub struct HandshakeSuccess {
     /// Decryption key and IV (for reading from client)
     pub dec_key: [u8; 32],
     pub dec_iv: u128,
-    /// Encryption key and IV (for writing to client) 
+    /// Encryption key and IV (for writing to client)
     pub enc_key: [u8; 32],
     pub enc_iv: u128,
     /// Client address
@@ -367,17 +651,78 @@ where
 {
     debug!(peer = %peer, handshake_len = handshake.len(), "Processing TLS handshake");
 
-    if auth_probe_is_throttled(peer.ip(), Instant::now()) {
+    let throttle_now = Instant::now();
+    if auth_probe_should_apply_preauth_throttle(peer.ip(), throttle_now) {
+        maybe_apply_server_hello_delay(config).await;
         debug!(peer = %peer, "TLS handshake rejected by pre-auth probe throttle");
         return HandshakeResult::BadClient { reader, writer };
     }
 
     if handshake.len() < tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN + 1 {
+        auth_probe_record_failure(peer.ip(), Instant::now());
+        maybe_apply_server_hello_delay(config).await;
         debug!(peer = %peer, "TLS handshake too short");
         return HandshakeResult::BadClient { reader, writer };
     }
 
-    let secrets = decode_user_secrets(config, None);
+    let client_sni = tls::extract_sni_from_client_hello(handshake);
+    let preferred_user_hint = client_sni
+        .as_deref()
+        .filter(|sni| config.access.users.contains_key(*sni));
+    let matched_tls_domain = client_sni
+        .as_deref()
+        .and_then(|sni| find_matching_tls_domain(config, sni));
+
+    let alpn_list = if config.censorship.alpn_enforce {
+        tls::extract_alpn_from_client_hello(handshake)
+    } else {
+        Vec::new()
+    };
+    let selected_alpn = if config.censorship.alpn_enforce {
+        if alpn_list.iter().any(|p| p == b"h2") {
+            Some(b"h2".to_vec())
+        } else if alpn_list.iter().any(|p| p == b"http/1.1") {
+            Some(b"http/1.1".to_vec())
+        } else if !alpn_list.is_empty() {
+            maybe_apply_server_hello_delay(config).await;
+            debug!(peer = %peer, "Client ALPN list has no supported protocol; using masking fallback");
+            return HandshakeResult::BadClient { reader, writer };
+        } else {
+            None
+        }
+    } else {
+        None
+    };
+
+    if client_sni.is_some() && matched_tls_domain.is_none() && preferred_user_hint.is_none() {
+        auth_probe_record_failure(peer.ip(), Instant::now());
+        maybe_apply_server_hello_delay(config).await;
+        let sni = client_sni.as_deref().unwrap_or_default();
+        let log_now = Instant::now();
+        if should_emit_unknown_sni_warn(log_now) {
+            warn!(
+                peer = %peer,
+                sni = %sni,
+                unknown_sni = true,
+                unknown_sni_action = ?config.censorship.unknown_sni_action,
+                "TLS handshake rejected by unknown SNI policy"
+            );
+        } else {
+            info!(
+                peer = %peer,
+                sni = %sni,
+                unknown_sni = true,
+                unknown_sni_action = ?config.censorship.unknown_sni_action,
+                "TLS handshake rejected by unknown SNI policy"
+            );
+        }
+        return match config.censorship.unknown_sni_action {
+            UnknownSniAction::Drop => HandshakeResult::Error(ProxyError::UnknownTlsSni),
+            UnknownSniAction::Mask => HandshakeResult::BadClient { reader, writer },
+        };
+    }
+
+    let secrets = decode_user_secrets(config, preferred_user_hint);
 
     let validation = match tls::validate_tls_handshake_with_replay_window(
         handshake,
@@ -388,8 +733,9 @@ where
         Some(v) => v,
         None => {
             auth_probe_record_failure(peer.ip(), Instant::now());
+            maybe_apply_server_hello_delay(config).await;
             debug!(
-                peer = %peer, 
+                peer = %peer,
                 ignore_time_skew = config.access.ignore_time_skew,
                 "TLS handshake validation failed - no matching user or time skew"
             );
@@ -397,32 +743,28 @@ where
         }
     };
 
-    // Replay tracking is applied only after successful authentication to avoid
-    // letting unauthenticated probes evict valid entries from the replay cache.
+    // Reject known replay digests before expensive cache/domain/ALPN policy work.
     let digest_half = &validation.digest[..tls::TLS_DIGEST_HALF_LEN];
-    if replay_checker.check_and_add_tls_digest(digest_half) {
+    if replay_checker.check_tls_digest(digest_half) {
         auth_probe_record_failure(peer.ip(), Instant::now());
+        maybe_apply_server_hello_delay(config).await;
         warn!(peer = %peer, "TLS replay attack detected (duplicate digest)");
         return HandshakeResult::BadClient { reader, writer };
     }
 
     let secret = match secrets.iter().find(|(name, _)| *name == validation.user) {
         Some((_, s)) => s,
-        None => return HandshakeResult::BadClient { reader, writer },
+        None => {
+            maybe_apply_server_hello_delay(config).await;
+            return HandshakeResult::BadClient { reader, writer };
+        }
     };
 
     let cached = if config.censorship.tls_emulation {
         if let Some(cache) = tls_cache.as_ref() {
-            let selected_domain = if let Some(sni) = tls::extract_sni_from_client_hello(handshake) {
-                if cache.contains_domain(&sni).await {
-                    sni
-                } else {
-                    config.censorship.tls_domain.clone()
-                }
-            } else {
-                config.censorship.tls_domain.clone()
-            };
-            let cached_entry = cache.get(&selected_domain).await;
+            let selected_domain =
+                matched_tls_domain.unwrap_or(config.censorship.tls_domain.as_str());
+            let cached_entry = cache.get(selected_domain).await;
             let use_full_cert_payload = cache
                 .take_full_cert_budget_for_ip(
                     peer.ip(),
@@ -437,25 +779,8 @@ where
         None
     };
 
-    let alpn_list = if config.censorship.alpn_enforce {
-        tls::extract_alpn_from_client_hello(handshake)
-    } else {
-        Vec::new()
-    };
-    let selected_alpn = if config.censorship.alpn_enforce {
-        if alpn_list.iter().any(|p| p == b"h2") {
-            Some(b"h2".to_vec())
-        } else if alpn_list.iter().any(|p| p == b"http/1.1") {
-            Some(b"http/1.1".to_vec())
-        } else if !alpn_list.is_empty() {
-            debug!(peer = %peer, "Client ALPN list has no supported protocol; using masking fallback");
-            return HandshakeResult::BadClient { reader, writer };
-        } else {
-            None
-        }
-    } else {
-        None
-    };
+    // Add replay digest only for policy-valid handshakes.
+    replay_checker.add_tls_digest(digest_half);
 
     let response = if let Some((cached_entry, use_full_cert_payload)) = cached {
         emulator::build_emulated_server_hello(
@@ -480,19 +805,9 @@ where
         )
     };
 
-    // Optional anti-fingerprint delay before sending ServerHello.
-    if config.censorship.server_hello_delay_max_ms > 0 {
-        let min = config.censorship.server_hello_delay_min_ms;
-        let max = config.censorship.server_hello_delay_max_ms.max(min);
-        let delay_ms = if max == min {
-            max
-        } else {
-            rand::rng().random_range(min..=max)
-        };
-        if delay_ms > 0 {
-            tokio::time::sleep(std::time::Duration::from_millis(delay_ms)).await;
-        }
-    }
+    // Apply the same optional delay budget used by reject paths to reduce
+    // distinguishability between success and fail-closed handshakes.
+    maybe_apply_server_hello_delay(config).await;
 
     debug!(peer = %peer, response_len = response.len(), "Sending TLS ServerHello");
 
@@ -536,9 +851,19 @@ where
     R: AsyncRead + Unpin + Send,
     W: AsyncWrite + Unpin + Send,
 {
-    trace!(peer = %peer, handshake = ?hex::encode(handshake), "MTProto handshake bytes");
+    let handshake_fingerprint = {
+        let digest = sha256(&handshake[..8]);
+        hex::encode(&digest[..4])
+    };
+    trace!(
+        peer = %peer,
+        handshake_fingerprint = %handshake_fingerprint,
+        "MTProto handshake prefix"
+    );
 
-    if auth_probe_is_throttled(peer.ip(), Instant::now()) {
+    let throttle_now = Instant::now();
+    if auth_probe_should_apply_preauth_throttle(peer.ip(), throttle_now) {
+        maybe_apply_server_hello_delay(config).await;
         debug!(peer = %peer, "MTProto handshake rejected by pre-auth probe throttle");
         return HandshakeResult::BadClient { reader, writer };
     }
@@ -550,14 +875,13 @@ where
     let decoded_users = decode_user_secrets(config, preferred_user);
 
     for (user, secret) in decoded_users {
-
         let dec_prekey = &dec_prekey_iv[..PREKEY_LEN];
         let dec_iv_bytes = &dec_prekey_iv[PREKEY_LEN..];
 
-        let mut dec_key_input = Vec::with_capacity(PREKEY_LEN + secret.len());
+        let mut dec_key_input = Zeroizing::new(Vec::with_capacity(PREKEY_LEN + secret.len()));
         dec_key_input.extend_from_slice(dec_prekey);
         dec_key_input.extend_from_slice(&secret);
-        let dec_key = sha256(&dec_key_input);
+        let dec_key = Zeroizing::new(sha256(&dec_key_input));
 
         let mut dec_iv_arr = [0u8; IV_LEN];
         dec_iv_arr.copy_from_slice(dec_iv_bytes);
@@ -590,10 +914,10 @@ where
         let enc_prekey = &enc_prekey_iv[..PREKEY_LEN];
         let enc_iv_bytes = &enc_prekey_iv[PREKEY_LEN..];
 
-        let mut enc_key_input = Vec::with_capacity(PREKEY_LEN + secret.len());
+        let mut enc_key_input = Zeroizing::new(Vec::with_capacity(PREKEY_LEN + secret.len()));
         enc_key_input.extend_from_slice(enc_prekey);
         enc_key_input.extend_from_slice(&secret);
-        let enc_key = sha256(&enc_key_input);
+        let enc_key = Zeroizing::new(sha256(&enc_key_input));
 
         let mut enc_iv_arr = [0u8; IV_LEN];
         enc_iv_arr.copy_from_slice(enc_iv_bytes);
@@ -601,14 +925,15 @@ where
 
         let encryptor = AesCtr::new(&enc_key, enc_iv);
 
-// Apply replay tracking only after successful authentication.
-    //
-    // This ordering prevents an attacker from producing invalid handshakes that
-    // still collide with a valid handshake's replay slot and thus evict a valid
-    // entry from the cache. We accept the cost of performing the full
-    // authentication check first to avoid poisoning the replay cache.
+        // Apply replay tracking only after successful authentication.
+        //
+        // This ordering prevents an attacker from producing invalid handshakes that
+        // still collide with a valid handshake's replay slot and thus evict a valid
+        // entry from the cache. We accept the cost of performing the full
+        // authentication check first to avoid poisoning the replay cache.
         if replay_checker.check_and_add_handshake(dec_prekey_iv) {
             auth_probe_record_failure(peer.ip(), Instant::now());
+            maybe_apply_server_hello_delay(config).await;
             warn!(peer = %peer, user = %user, "MTProto replay attack detected");
             return HandshakeResult::BadClient { reader, writer };
         }
@@ -617,9 +942,9 @@ where
             user: user.clone(),
             dc_idx,
             proto_tag,
-            dec_key,
+            dec_key: *dec_key,
             dec_iv,
-            enc_key,
+            enc_key: *enc_key,
             enc_iv,
             peer,
             is_tls,
@@ -645,13 +970,14 @@ where
     }
 
     auth_probe_record_failure(peer.ip(), Instant::now());
+    maybe_apply_server_hello_delay(config).await;
     debug!(peer = %peer, "MTProto handshake: no matching user found");
     HandshakeResult::BadClient { reader, writer }
 }
 
 /// Generate nonce for Telegram connection
 pub fn generate_tg_nonce(
-    proto_tag: ProtoTag, 
+    proto_tag: ProtoTag,
     dc_idx: i16,
     client_enc_key: &[u8; 32],
     client_enc_iv: u128,
@@ -664,20 +990,26 @@ pub fn generate_tg_nonce(
             continue;
         };
 
-        if RESERVED_NONCE_FIRST_BYTES.contains(&nonce[0]) { continue; }
+        if RESERVED_NONCE_FIRST_BYTES.contains(&nonce[0]) {
+            continue;
+        }
 
         let first_four: [u8; 4] = [nonce[0], nonce[1], nonce[2], nonce[3]];
-        if RESERVED_NONCE_BEGINNINGS.contains(&first_four) { continue; }
+        if RESERVED_NONCE_BEGINNINGS.contains(&first_four) {
+            continue;
+        }
 
         let continue_four: [u8; 4] = [nonce[4], nonce[5], nonce[6], nonce[7]];
-        if RESERVED_NONCE_CONTINUES.contains(&continue_four) { continue; }
+        if RESERVED_NONCE_CONTINUES.contains(&continue_four) {
+            continue;
+        }
 
         nonce[PROTO_TAG_POS..PROTO_TAG_POS + 4].copy_from_slice(&proto_tag.to_bytes());
         // CRITICAL: write dc_idx so upstream DC knows where to route
         nonce[DC_IDX_POS..DC_IDX_POS + 2].copy_from_slice(&dc_idx.to_le_bytes());
 
         if fast_mode {
-            let mut key_iv = Vec::with_capacity(KEY_LEN + IV_LEN);
+            let mut key_iv = Zeroizing::new(Vec::with_capacity(KEY_LEN + IV_LEN));
             key_iv.extend_from_slice(client_enc_key);
             key_iv.extend_from_slice(&client_enc_iv.to_be_bytes());
             key_iv.reverse(); // Python/C behavior: reversed enc_key+enc_iv in nonce
@@ -685,7 +1017,7 @@ pub fn generate_tg_nonce(
         }
 
         let enc_key_iv = &nonce[SKIP_LEN..SKIP_LEN + KEY_LEN + IV_LEN];
-        let dec_key_iv: Vec<u8> = enc_key_iv.iter().rev().copied().collect();
+        let dec_key_iv = Zeroizing::new(enc_key_iv.iter().rev().copied().collect::<Vec<u8>>());
 
         let mut tg_enc_key = [0u8; 32];
         tg_enc_key.copy_from_slice(&enc_key_iv[..KEY_LEN]);
@@ -706,7 +1038,7 @@ pub fn generate_tg_nonce(
 /// Encrypt nonce for sending to Telegram and return cipher objects with correct counter state
 pub fn encrypt_tg_nonce_with_ciphers(nonce: &[u8; HANDSHAKE_LEN]) -> (Vec<u8>, AesCtr, AesCtr) {
     let enc_key_iv = &nonce[SKIP_LEN..SKIP_LEN + KEY_LEN + IV_LEN];
-    let dec_key_iv: Vec<u8> = enc_key_iv.iter().rev().copied().collect();
+    let dec_key_iv = Zeroizing::new(enc_key_iv.iter().rev().copied().collect::<Vec<u8>>());
 
     let mut enc_key = [0u8; 32];
     enc_key.copy_from_slice(&enc_key_iv[..KEY_LEN]);
@@ -721,12 +1053,14 @@ pub fn encrypt_tg_nonce_with_ciphers(nonce: &[u8; HANDSHAKE_LEN]) -> (Vec<u8>, A
     let dec_iv = u128::from_be_bytes(dec_iv_arr);
 
     let mut encryptor = AesCtr::new(&enc_key, enc_iv);
-    let encrypted_full = encryptor.encrypt(nonce);  // counter: 0 → 4
+    let encrypted_full = encryptor.encrypt(nonce); // counter: 0 → 4
 
     let mut result = nonce[..PROTO_TAG_POS].to_vec();
     result.extend_from_slice(&encrypted_full[PROTO_TAG_POS..]);
 
     let decryptor = AesCtr::new(&dec_key, dec_iv);
+    enc_key.zeroize();
+    dec_key.zeroize();
 
     (result, encryptor, decryptor)
 }
@@ -738,9 +1072,57 @@ pub fn encrypt_tg_nonce(nonce: &[u8; HANDSHAKE_LEN]) -> Vec<u8> {
 }
 
 #[cfg(test)]
-#[path = "handshake_security_tests.rs"]
+#[path = "tests/handshake_security_tests.rs"]
 mod security_tests;
 
+#[cfg(test)]
+#[path = "tests/handshake_adversarial_tests.rs"]
+mod adversarial_tests;
+
+#[cfg(test)]
+#[path = "tests/handshake_fuzz_security_tests.rs"]
+mod fuzz_security_tests;
+
+#[cfg(test)]
+#[path = "tests/handshake_saturation_poison_security_tests.rs"]
+mod saturation_poison_security_tests;
+
+#[cfg(test)]
+#[path = "tests/handshake_auth_probe_hardening_adversarial_tests.rs"]
+mod auth_probe_hardening_adversarial_tests;
+
+#[cfg(test)]
+#[path = "tests/handshake_auth_probe_scan_budget_security_tests.rs"]
+mod auth_probe_scan_budget_security_tests;
+
+#[cfg(test)]
+#[path = "tests/handshake_auth_probe_scan_offset_stress_tests.rs"]
+mod auth_probe_scan_offset_stress_tests;
+
+#[cfg(test)]
+#[path = "tests/handshake_auth_probe_eviction_bias_security_tests.rs"]
+mod auth_probe_eviction_bias_security_tests;
+
+#[cfg(test)]
+#[path = "tests/handshake_advanced_clever_tests.rs"]
+mod advanced_clever_tests;
+
+#[cfg(test)]
+#[path = "tests/handshake_more_clever_tests.rs"]
+mod more_clever_tests;
+
+#[cfg(test)]
+#[path = "tests/handshake_real_bug_stress_tests.rs"]
+mod real_bug_stress_tests;
+
+#[cfg(test)]
+#[path = "tests/handshake_timing_manual_bench_tests.rs"]
+mod timing_manual_bench_tests;
+
+#[cfg(test)]
+#[path = "tests/handshake_key_material_zeroization_security_tests.rs"]
+mod handshake_key_material_zeroization_security_tests;
+
 /// Compile-time guard: HandshakeSuccess holds cryptographic key material and
 /// must never be Copy.  A Copy impl would allow silent key duplication,
 /// undermining the zeroize-on-drop guarantee.

src/proxy/masking_security_tests.rs

@@ -1,731 +0,0 @@
-use super::*;
-use crate::config::ProxyConfig;
-use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, Ordering};
-use std::pin::Pin;
-use std::task::{Context, Poll};
-use tokio::io::{duplex, AsyncBufReadExt, BufReader};
-use tokio::net::TcpListener;
-#[cfg(unix)]
-use tokio::net::UnixListener;
-use tokio::time::{sleep, timeout, Duration};
-
-#[tokio::test]
-async fn bad_client_probe_is_forwarded_verbatim_to_mask_backend() {
-    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
-    let backend_addr = listener.local_addr().unwrap();
-    let probe = b"GET / HTTP/1.1\r\nHost: front.example\r\n\r\n".to_vec();
-    let backend_reply = b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nOK".to_vec();
-
-    let accept_task = tokio::spawn({
-        let probe = probe.clone();
-        let backend_reply = backend_reply.clone();
-        async move {
-            let (mut stream, _) = listener.accept().await.unwrap();
-            let mut received = vec![0u8; probe.len()];
-            stream.read_exact(&mut received).await.unwrap();
-            assert_eq!(received, probe);
-            stream.write_all(&backend_reply).await.unwrap();
-        }
-    });
-
-    let mut config = ProxyConfig::default();
-    config.general.beobachten = false;
-    config.censorship.mask = true;
-    config.censorship.mask_host = Some("127.0.0.1".to_string());
-    config.censorship.mask_port = backend_addr.port();
-    config.censorship.mask_unix_sock = None;
-    config.censorship.mask_proxy_protocol = 0;
-
-    let peer: SocketAddr = "203.0.113.10:42424".parse().unwrap();
-    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
-
-    let (client_reader, _client_writer) = duplex(256);
-    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
-
-    let beobachten = BeobachtenStore::new();
-    handle_bad_client(
-        client_reader,
-        client_visible_writer,
-        &probe,
-        peer,
-        local_addr,
-        &config,
-        &beobachten,
-    )
-    .await;
-
-    let mut observed = vec![0u8; backend_reply.len()];
-    client_visible_reader.read_exact(&mut observed).await.unwrap();
-    assert_eq!(observed, backend_reply);
-    accept_task.await.unwrap();
-}
-
-#[tokio::test]
-async fn tls_scanner_probe_keeps_http_like_fallback_surface() {
-    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
-    let backend_addr = listener.local_addr().unwrap();
-    let probe = vec![0x16, 0x03, 0x01, 0x00, 0x10, 0x01, 0x02, 0x03, 0x04];
-    let backend_reply = b"HTTP/1.1 400 Bad Request\r\nContent-Length: 0\r\n\r\n".to_vec();
-
-    let accept_task = tokio::spawn({
-        let probe = probe.clone();
-        let backend_reply = backend_reply.clone();
-        async move {
-            let (mut stream, _) = listener.accept().await.unwrap();
-            let mut received = vec![0u8; probe.len()];
-            stream.read_exact(&mut received).await.unwrap();
-            assert_eq!(received, probe);
-            stream.write_all(&backend_reply).await.unwrap();
-        }
-    });
-
-    let mut config = ProxyConfig::default();
-    config.general.beobachten = true;
-    config.general.beobachten_minutes = 1;
-    config.censorship.mask = true;
-    config.censorship.mask_host = Some("127.0.0.1".to_string());
-    config.censorship.mask_port = backend_addr.port();
-    config.censorship.mask_unix_sock = None;
-    config.censorship.mask_proxy_protocol = 0;
-
-    let peer: SocketAddr = "198.51.100.44:55221".parse().unwrap();
-    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
-
-    let (client_reader, _client_writer) = duplex(256);
-    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
-
-    let beobachten = BeobachtenStore::new();
-    handle_bad_client(
-        client_reader,
-        client_visible_writer,
-        &probe,
-        peer,
-        local_addr,
-        &config,
-        &beobachten,
-    )
-    .await;
-
-    let mut observed = vec![0u8; backend_reply.len()];
-    client_visible_reader.read_exact(&mut observed).await.unwrap();
-    assert_eq!(observed, backend_reply);
-
-    let snapshot = beobachten.snapshot_text(Duration::from_secs(60));
-    assert!(snapshot.contains("[TLS-scanner]"));
-    assert!(snapshot.contains("198.51.100.44-1"));
-    accept_task.await.unwrap();
-}
-
-#[test]
-fn detect_client_type_covers_ssh_port_scanner_and_unknown() {
-    assert_eq!(detect_client_type(b"SSH-2.0-OpenSSH_9.7"), "SSH");
-    assert_eq!(detect_client_type(b"\x01\x02\x03"), "port-scanner");
-    assert_eq!(detect_client_type(b"random-binary-payload"), "unknown");
-}
-
-#[test]
-fn detect_client_type_len_boundary_9_vs_10_bytes() {
-    assert_eq!(detect_client_type(b"123456789"), "port-scanner");
-    assert_eq!(detect_client_type(b"1234567890"), "unknown");
-}
-
-#[tokio::test]
-async fn beobachten_records_scanner_class_when_mask_is_disabled() {
-    let mut config = ProxyConfig::default();
-    config.general.beobachten = true;
-    config.general.beobachten_minutes = 1;
-    config.censorship.mask = false;
-
-    let peer: SocketAddr = "203.0.113.99:41234".parse().unwrap();
-    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
-    let initial = b"SSH-2.0-probe";
-
-    let (mut client_reader_side, client_reader) = duplex(256);
-    let (_client_visible_reader, client_visible_writer) = duplex(256);
-    let beobachten = BeobachtenStore::new();
-
-    let task = tokio::spawn(async move {
-        handle_bad_client(
-            client_reader,
-            client_visible_writer,
-            initial,
-            peer,
-            local_addr,
-            &config,
-            &beobachten,
-        )
-        .await;
-        beobachten
-    });
-
-    client_reader_side.write_all(b"noise").await.unwrap();
-    drop(client_reader_side);
-
-    let beobachten = timeout(Duration::from_secs(3), task).await.unwrap().unwrap();
-    let snapshot = beobachten.snapshot_text(Duration::from_secs(60));
-    assert!(snapshot.contains("[SSH]"));
-    assert!(snapshot.contains("203.0.113.99-1"));
-}
-
-#[tokio::test]
-async fn backend_unavailable_falls_back_to_silent_consume() {
-    let temp_listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
-    let unused_port = temp_listener.local_addr().unwrap().port();
-    drop(temp_listener);
-
-    let mut config = ProxyConfig::default();
-    config.general.beobachten = false;
-    config.censorship.mask = true;
-    config.censorship.mask_host = Some("127.0.0.1".to_string());
-    config.censorship.mask_port = unused_port;
-    config.censorship.mask_unix_sock = None;
-    config.censorship.mask_proxy_protocol = 0;
-
-    let peer: SocketAddr = "203.0.113.11:42425".parse().unwrap();
-    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
-    let probe = b"GET /probe HTTP/1.1\r\nHost: x\r\n\r\n";
-
-    let (mut client_reader_side, client_reader) = duplex(256);
-    let (mut client_visible_reader, client_visible_writer) = duplex(256);
-    let beobachten = BeobachtenStore::new();
-
-    let task = tokio::spawn(async move {
-        handle_bad_client(
-            client_reader,
-            client_visible_writer,
-            probe,
-            peer,
-            local_addr,
-            &config,
-            &beobachten,
-        )
-        .await;
-    });
-
-    client_reader_side.write_all(b"noise").await.unwrap();
-    drop(client_reader_side);
-
-    timeout(Duration::from_secs(3), task).await.unwrap().unwrap();
-
-    let mut buf = [0u8; 1];
-    let n = timeout(Duration::from_secs(1), client_visible_reader.read(&mut buf))
-        .await
-        .unwrap()
-        .unwrap();
-    assert_eq!(n, 0);
-}
-
-#[tokio::test]
-async fn mask_disabled_consumes_client_data_without_response() {
-    let mut config = ProxyConfig::default();
-    config.general.beobachten = false;
-    config.censorship.mask = false;
-
-    let peer: SocketAddr = "198.51.100.12:45454".parse().unwrap();
-    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
-    let initial = b"scanner";
-
-    let (mut client_reader_side, client_reader) = duplex(256);
-    let (mut client_visible_reader, client_visible_writer) = duplex(256);
-    let beobachten = BeobachtenStore::new();
-
-    let task = tokio::spawn(async move {
-        handle_bad_client(
-            client_reader,
-            client_visible_writer,
-            initial,
-            peer,
-            local_addr,
-            &config,
-            &beobachten,
-        )
-        .await;
-    });
-
-    client_reader_side.write_all(b"untrusted payload").await.unwrap();
-    drop(client_reader_side);
-
-    timeout(Duration::from_secs(3), task).await.unwrap().unwrap();
-
-    let mut buf = [0u8; 1];
-    let n = timeout(Duration::from_secs(1), client_visible_reader.read(&mut buf))
-        .await
-        .unwrap()
-        .unwrap();
-    assert_eq!(n, 0);
-}
-
-#[tokio::test]
-async fn proxy_protocol_v1_header_is_sent_before_probe() {
-    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
-    let backend_addr = listener.local_addr().unwrap();
-    let probe = b"GET / HTTP/1.1\r\nHost: front.example\r\n\r\n".to_vec();
-    let backend_reply = b"HTTP/1.1 204 No Content\r\nContent-Length: 0\r\n\r\n".to_vec();
-
-    let accept_task = tokio::spawn({
-        let probe = probe.clone();
-        let backend_reply = backend_reply.clone();
-        async move {
-            let (stream, _) = listener.accept().await.unwrap();
-            let mut reader = BufReader::new(stream);
-
-            let mut header_line = Vec::new();
-            reader.read_until(b'\n', &mut header_line).await.unwrap();
-            let header_text = String::from_utf8(header_line.clone()).unwrap();
-            assert!(header_text.starts_with("PROXY TCP4 "));
-            assert!(header_text.ends_with("\r\n"));
-
-            let mut received_probe = vec![0u8; probe.len()];
-            reader.read_exact(&mut received_probe).await.unwrap();
-            assert_eq!(received_probe, probe);
-
-            let mut stream = reader.into_inner();
-            stream.write_all(&backend_reply).await.unwrap();
-        }
-    });
-
-    let mut config = ProxyConfig::default();
-    config.general.beobachten = false;
-    config.censorship.mask = true;
-    config.censorship.mask_host = Some("127.0.0.1".to_string());
-    config.censorship.mask_port = backend_addr.port();
-    config.censorship.mask_unix_sock = None;
-    config.censorship.mask_proxy_protocol = 1;
-
-    let peer: SocketAddr = "203.0.113.15:50001".parse().unwrap();
-    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
-
-    let (client_reader, _client_writer) = duplex(256);
-    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
-
-    let beobachten = BeobachtenStore::new();
-    handle_bad_client(
-        client_reader,
-        client_visible_writer,
-        &probe,
-        peer,
-        local_addr,
-        &config,
-        &beobachten,
-    )
-    .await;
-
-    let mut observed = vec![0u8; backend_reply.len()];
-    client_visible_reader.read_exact(&mut observed).await.unwrap();
-    assert_eq!(observed, backend_reply);
-    accept_task.await.unwrap();
-}
-
-#[tokio::test]
-async fn proxy_protocol_v2_header_is_sent_before_probe() {
-    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
-    let backend_addr = listener.local_addr().unwrap();
-    let probe = b"GET / HTTP/1.1\r\nHost: front.example\r\n\r\n".to_vec();
-    let backend_reply = b"HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n".to_vec();
-
-    let accept_task = tokio::spawn({
-        let probe = probe.clone();
-        let backend_reply = backend_reply.clone();
-        async move {
-            let (mut stream, _) = listener.accept().await.unwrap();
-
-            let mut sig = [0u8; 12];
-            stream.read_exact(&mut sig).await.unwrap();
-            assert_eq!(&sig, b"\r\n\r\n\0\r\nQUIT\n");
-
-            let mut fixed = [0u8; 4];
-            stream.read_exact(&mut fixed).await.unwrap();
-            let addr_len = u16::from_be_bytes([fixed[2], fixed[3]]) as usize;
-
-            let mut addr_block = vec![0u8; addr_len];
-            stream.read_exact(&mut addr_block).await.unwrap();
-
-            let mut received_probe = vec![0u8; probe.len()];
-            stream.read_exact(&mut received_probe).await.unwrap();
-            assert_eq!(received_probe, probe);
-
-            stream.write_all(&backend_reply).await.unwrap();
-        }
-    });
-
-    let mut config = ProxyConfig::default();
-    config.general.beobachten = false;
-    config.censorship.mask = true;
-    config.censorship.mask_host = Some("127.0.0.1".to_string());
-    config.censorship.mask_port = backend_addr.port();
-    config.censorship.mask_unix_sock = None;
-    config.censorship.mask_proxy_protocol = 2;
-
-    let peer: SocketAddr = "203.0.113.18:50004".parse().unwrap();
-    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
-
-    let (client_reader, _client_writer) = duplex(256);
-    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
-
-    let beobachten = BeobachtenStore::new();
-    handle_bad_client(
-        client_reader,
-        client_visible_writer,
-        &probe,
-        peer,
-        local_addr,
-        &config,
-        &beobachten,
-    )
-    .await;
-
-    let mut observed = vec![0u8; backend_reply.len()];
-    client_visible_reader.read_exact(&mut observed).await.unwrap();
-    assert_eq!(observed, backend_reply);
-    accept_task.await.unwrap();
-}
-
-#[tokio::test]
-async fn proxy_protocol_v1_mixed_family_falls_back_to_unknown_header() {
-    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
-    let backend_addr = listener.local_addr().unwrap();
-    let probe = b"GET /mix HTTP/1.1\r\nHost: front.example\r\n\r\n".to_vec();
-    let backend_reply = b"HTTP/1.1 204 No Content\r\nContent-Length: 0\r\n\r\n".to_vec();
-
-    let accept_task = tokio::spawn({
-        let probe = probe.clone();
-        let backend_reply = backend_reply.clone();
-        async move {
-            let (stream, _) = listener.accept().await.unwrap();
-            let mut reader = BufReader::new(stream);
-
-            let mut header_line = Vec::new();
-            reader.read_until(b'\n', &mut header_line).await.unwrap();
-            let header_text = String::from_utf8(header_line).unwrap();
-            assert_eq!(header_text, "PROXY UNKNOWN\r\n");
-
-            let mut received_probe = vec![0u8; probe.len()];
-            reader.read_exact(&mut received_probe).await.unwrap();
-            assert_eq!(received_probe, probe);
-
-            let mut stream = reader.into_inner();
-            stream.write_all(&backend_reply).await.unwrap();
-        }
-    });
-
-    let mut config = ProxyConfig::default();
-    config.general.beobachten = false;
-    config.censorship.mask = true;
-    config.censorship.mask_host = Some("127.0.0.1".to_string());
-    config.censorship.mask_port = backend_addr.port();
-    config.censorship.mask_unix_sock = None;
-    config.censorship.mask_proxy_protocol = 1;
-
-    let peer: SocketAddr = "203.0.113.20:50006".parse().unwrap();
-    let local_addr: SocketAddr = "[::1]:443".parse().unwrap();
-
-    let (client_reader, _client_writer) = duplex(256);
-    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
-
-    let beobachten = BeobachtenStore::new();
-    handle_bad_client(
-        client_reader,
-        client_visible_writer,
-        &probe,
-        peer,
-        local_addr,
-        &config,
-        &beobachten,
-    )
-    .await;
-
-    let mut observed = vec![0u8; backend_reply.len()];
-    client_visible_reader.read_exact(&mut observed).await.unwrap();
-    assert_eq!(observed, backend_reply);
-    accept_task.await.unwrap();
-}
-
-#[cfg(unix)]
-#[tokio::test]
-async fn unix_socket_mask_path_forwards_probe_and_response() {
-    let sock_path = format!("/tmp/telemt-mask-test-{}-{}.sock", std::process::id(), rand::random::<u64>());
-    let _ = std::fs::remove_file(&sock_path);
-
-    let listener = UnixListener::bind(&sock_path).unwrap();
-    let probe = b"GET /unix HTTP/1.1\r\nHost: front.example\r\n\r\n".to_vec();
-    let backend_reply = b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nOK".to_vec();
-
-    let accept_task = tokio::spawn({
-        let probe = probe.clone();
-        let backend_reply = backend_reply.clone();
-        async move {
-            let (mut stream, _) = listener.accept().await.unwrap();
-            let mut received = vec![0u8; probe.len()];
-            stream.read_exact(&mut received).await.unwrap();
-            assert_eq!(received, probe);
-            stream.write_all(&backend_reply).await.unwrap();
-        }
-    });
-
-    let mut config = ProxyConfig::default();
-    config.general.beobachten = false;
-    config.censorship.mask = true;
-    config.censorship.mask_unix_sock = Some(sock_path.clone());
-    config.censorship.mask_proxy_protocol = 0;
-
-    let peer: SocketAddr = "203.0.113.30:50010".parse().unwrap();
-    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
-
-    let (client_reader, _client_writer) = duplex(256);
-    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
-
-    let beobachten = BeobachtenStore::new();
-    handle_bad_client(
-        client_reader,
-        client_visible_writer,
-        &probe,
-        peer,
-        local_addr,
-        &config,
-        &beobachten,
-    )
-    .await;
-
-    let mut observed = vec![0u8; backend_reply.len()];
-    client_visible_reader.read_exact(&mut observed).await.unwrap();
-    assert_eq!(observed, backend_reply);
-
-    accept_task.await.unwrap();
-    let _ = std::fs::remove_file(sock_path);
-}
-
-#[tokio::test]
-async fn mask_disabled_slowloris_connection_is_closed_by_consume_timeout() {
-    let mut config = ProxyConfig::default();
-    config.general.beobachten = false;
-    config.censorship.mask = false;
-
-    let peer: SocketAddr = "198.51.100.33:45455".parse().unwrap();
-    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
-
-    let (_client_reader_side, client_reader) = duplex(256);
-    let (_client_visible_reader, client_visible_writer) = duplex(256);
-    let beobachten = BeobachtenStore::new();
-
-    let task = tokio::spawn(async move {
-        handle_bad_client(
-            client_reader,
-            client_visible_writer,
-            b"slowloris",
-            peer,
-            local_addr,
-            &config,
-            &beobachten,
-        )
-        .await;
-    });
-
-    timeout(Duration::from_secs(1), task).await.unwrap().unwrap();
-}
-
-struct PendingWriter;
-
-impl tokio::io::AsyncWrite for PendingWriter {
-    fn poll_write(
-        self: Pin<&mut Self>,
-        _cx: &mut Context<'_>,
-        _buf: &[u8],
-    ) -> Poll<std::io::Result<usize>> {
-        Poll::Pending
-    }
-
-    fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
-        Poll::Ready(Ok(()))
-    }
-
-    fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
-        Poll::Ready(Ok(()))
-    }
-}
-
-struct DropTrackedPendingReader {
-    dropped: Arc<AtomicBool>,
-}
-
-impl tokio::io::AsyncRead for DropTrackedPendingReader {
-    fn poll_read(
-        self: Pin<&mut Self>,
-        _cx: &mut Context<'_>,
-        _buf: &mut tokio::io::ReadBuf<'_>,
-    ) -> Poll<std::io::Result<()>> {
-        Poll::Pending
-    }
-}
-
-impl Drop for DropTrackedPendingReader {
-    fn drop(&mut self) {
-        self.dropped.store(true, Ordering::SeqCst);
-    }
-}
-
-struct DropTrackedPendingWriter {
-    dropped: Arc<AtomicBool>,
-}
-
-impl tokio::io::AsyncWrite for DropTrackedPendingWriter {
-    fn poll_write(
-        self: Pin<&mut Self>,
-        _cx: &mut Context<'_>,
-        _buf: &[u8],
-    ) -> Poll<std::io::Result<usize>> {
-        Poll::Pending
-    }
-
-    fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
-        Poll::Ready(Ok(()))
-    }
-
-    fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
-        Poll::Ready(Ok(()))
-    }
-}
-
-impl Drop for DropTrackedPendingWriter {
-    fn drop(&mut self) {
-        self.dropped.store(true, Ordering::SeqCst);
-    }
-}
-
-#[tokio::test]
-async fn proxy_header_write_timeout_returns_false() {
-    let mut writer = PendingWriter;
-    let ok = write_proxy_header_with_timeout(&mut writer, b"PROXY UNKNOWN\r\n").await;
-    assert!(!ok, "Proxy header writes that never complete must time out");
-}
-
-#[tokio::test]
-async fn relay_to_mask_keeps_backend_to_client_flow_when_client_to_backend_stalls() {
-    let (mut client_feed_writer, client_feed_reader) = duplex(64);
-    let (mut client_visible_reader, client_visible_writer) = duplex(64);
-    let (mut backend_feed_writer, backend_feed_reader) = duplex(64);
-
-    // Make client->mask direction immediately active so the c2m path blocks on PendingWriter.
-    client_feed_writer.write_all(b"X").await.unwrap();
-
-    let relay = tokio::spawn(async move {
-        relay_to_mask(
-            client_feed_reader,
-            client_visible_writer,
-            backend_feed_reader,
-            PendingWriter,
-            b"",
-        )
-        .await;
-    });
-
-    // Allow relay tasks to start, then emulate mask backend response.
-    sleep(Duration::from_millis(20)).await;
-    backend_feed_writer.write_all(b"HTTP/1.1 200 OK\r\n\r\n").await.unwrap();
-    backend_feed_writer.shutdown().await.unwrap();
-
-    let mut observed = vec![0u8; 19];
-    timeout(Duration::from_secs(1), client_visible_reader.read_exact(&mut observed))
-        .await
-        .unwrap()
-        .unwrap();
-    assert_eq!(observed, b"HTTP/1.1 200 OK\r\n\r\n");
-
-    relay.abort();
-    let _ = relay.await;
-}
-
-#[tokio::test]
-async fn relay_to_mask_preserves_backend_response_after_client_half_close() {
-    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
-    let backend_addr = listener.local_addr().unwrap();
-    let request = b"GET / HTTP/1.1\r\nHost: front.example\r\n\r\n".to_vec();
-    let response = b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nOK".to_vec();
-
-    let backend_task = tokio::spawn({
-        let request = request.clone();
-        let response = response.clone();
-        async move {
-            let (mut stream, _) = listener.accept().await.unwrap();
-            let mut observed_req = vec![0u8; request.len()];
-            stream.read_exact(&mut observed_req).await.unwrap();
-            assert_eq!(observed_req, request);
-            stream.write_all(&response).await.unwrap();
-            stream.shutdown().await.unwrap();
-        }
-    });
-
-    let mut config = ProxyConfig::default();
-    config.general.beobachten = false;
-    config.censorship.mask = true;
-    config.censorship.mask_host = Some("127.0.0.1".to_string());
-    config.censorship.mask_port = backend_addr.port();
-    config.censorship.mask_unix_sock = None;
-    config.censorship.mask_proxy_protocol = 0;
-
-    let peer: SocketAddr = "203.0.113.77:55001".parse().unwrap();
-    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
-
-    let (mut client_write, client_read) = duplex(1024);
-    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
-    let beobachten = BeobachtenStore::new();
-
-    let fallback_task = tokio::spawn(async move {
-        handle_bad_client(
-            client_read,
-            client_visible_writer,
-            &request,
-            peer,
-            local_addr,
-            &config,
-            &beobachten,
-        )
-        .await;
-    });
-
-    client_write.shutdown().await.unwrap();
-
-    let mut observed_resp = vec![0u8; response.len()];
-    timeout(Duration::from_secs(1), client_visible_reader.read_exact(&mut observed_resp))
-        .await
-        .unwrap()
-        .unwrap();
-    assert_eq!(observed_resp, response);
-
-    timeout(Duration::from_secs(1), fallback_task).await.unwrap().unwrap();
-    timeout(Duration::from_secs(1), backend_task).await.unwrap().unwrap();
-}
-
-#[tokio::test]
-async fn relay_to_mask_timeout_cancels_and_drops_all_io_endpoints() {
-    let reader_dropped = Arc::new(AtomicBool::new(false));
-    let writer_dropped = Arc::new(AtomicBool::new(false));
-    let mask_reader_dropped = Arc::new(AtomicBool::new(false));
-    let mask_writer_dropped = Arc::new(AtomicBool::new(false));
-
-    let reader = DropTrackedPendingReader {
-        dropped: reader_dropped.clone(),
-    };
-    let writer = DropTrackedPendingWriter {
-        dropped: writer_dropped.clone(),
-    };
-    let mask_read = DropTrackedPendingReader {
-        dropped: mask_reader_dropped.clone(),
-    };
-    let mask_write = DropTrackedPendingWriter {
-        dropped: mask_writer_dropped.clone(),
-    };
-
-    let timed = timeout(
-        Duration::from_millis(40),
-        relay_to_mask(reader, writer, mask_read, mask_write, b""),
-    )
-    .await;
-
-    assert!(timed.is_err(), "stalled relay must be bounded by timeout");
-
-    assert!(reader_dropped.load(Ordering::SeqCst));
-    assert!(writer_dropped.load(Ordering::SeqCst));
-    assert!(mask_reader_dropped.load(Ordering::SeqCst));
-    assert!(mask_writer_dropped.load(Ordering::SeqCst));
-}

src/proxy/middle_relay_security_tests.rs

@@ -1,781 +0,0 @@
-use super::*;
-use bytes::Bytes;
-use crate::crypto::AesCtr;
-use crate::crypto::SecureRandom;
-use crate::stats::Stats;
-use crate::stream::{BufferPool, CryptoReader, CryptoWriter, PooledBuffer};
-use std::net::SocketAddr;
-use std::sync::Arc;
-use std::sync::atomic::AtomicU64;
-use tokio::io::AsyncWriteExt;
-use tokio::io::duplex;
-use tokio::time::{Duration as TokioDuration, timeout};
-
-fn make_pooled_payload(data: &[u8]) -> PooledBuffer {
-    let pool = Arc::new(BufferPool::with_config(data.len().max(1), 4));
-    let mut payload = pool.get();
-    payload.resize(data.len(), 0);
-    payload[..data.len()].copy_from_slice(data);
-    payload
-}
-
-fn make_pooled_payload_from(pool: &Arc<BufferPool>, data: &[u8]) -> PooledBuffer {
-    let mut payload = pool.get();
-    payload.resize(data.len(), 0);
-    payload[..data.len()].copy_from_slice(data);
-    payload
-}
-
-#[test]
-fn should_yield_sender_only_on_budget_with_backlog() {
-    assert!(!should_yield_c2me_sender(0, true));
-    assert!(!should_yield_c2me_sender(C2ME_SENDER_FAIRNESS_BUDGET - 1, true));
-    assert!(!should_yield_c2me_sender(C2ME_SENDER_FAIRNESS_BUDGET, false));
-    assert!(should_yield_c2me_sender(C2ME_SENDER_FAIRNESS_BUDGET, true));
-}
-
-#[tokio::test]
-async fn enqueue_c2me_command_uses_try_send_fast_path() {
-    let (tx, mut rx) = mpsc::channel::<C2MeCommand>(2);
-    enqueue_c2me_command(
-        &tx,
-        C2MeCommand::Data {
-            payload: make_pooled_payload(&[1, 2, 3]),
-            flags: 0,
-        },
-    )
-    .await
-    .unwrap();
-
-    let recv = timeout(TokioDuration::from_millis(50), rx.recv())
-        .await
-        .unwrap()
-        .unwrap();
-    match recv {
-        C2MeCommand::Data { payload, flags } => {
-            assert_eq!(payload.as_ref(), &[1, 2, 3]);
-            assert_eq!(flags, 0);
-        }
-        C2MeCommand::Close => panic!("unexpected close command"),
-    }
-}
-
-#[tokio::test]
-async fn enqueue_c2me_command_falls_back_to_send_when_queue_is_full() {
-    let (tx, mut rx) = mpsc::channel::<C2MeCommand>(1);
-    tx.send(C2MeCommand::Data {
-        payload: make_pooled_payload(&[9]),
-        flags: 9,
-    })
-    .await
-    .unwrap();
-
-    let tx2 = tx.clone();
-    let producer = tokio::spawn(async move {
-        enqueue_c2me_command(
-            &tx2,
-            C2MeCommand::Data {
-                payload: make_pooled_payload(&[7, 7]),
-                flags: 7,
-            },
-        )
-        .await
-        .unwrap();
-    });
-
-    let _ = timeout(TokioDuration::from_millis(100), rx.recv())
-        .await
-        .unwrap();
-    producer.await.unwrap();
-
-    let recv = timeout(TokioDuration::from_millis(100), rx.recv())
-        .await
-        .unwrap()
-        .unwrap();
-    match recv {
-        C2MeCommand::Data { payload, flags } => {
-            assert_eq!(payload.as_ref(), &[7, 7]);
-            assert_eq!(flags, 7);
-        }
-        C2MeCommand::Close => panic!("unexpected close command"),
-    }
-}
-
-#[tokio::test]
-async fn enqueue_c2me_command_closed_channel_recycles_payload() {
-    let pool = Arc::new(BufferPool::with_config(64, 4));
-    let payload = make_pooled_payload_from(&pool, &[1, 2, 3, 4]);
-    let (tx, rx) = mpsc::channel::<C2MeCommand>(1);
-    drop(rx);
-
-    let result = enqueue_c2me_command(
-        &tx,
-        C2MeCommand::Data {
-            payload,
-            flags: 0,
-        },
-    )
-    .await;
-
-    assert!(result.is_err(), "closed queue must fail enqueue");
-    drop(result);
-    assert!(
-        pool.stats().pooled >= 1,
-        "payload must return to pool when enqueue fails on closed channel"
-    );
-}
-
-#[tokio::test]
-async fn enqueue_c2me_command_full_then_closed_recycles_waiting_payload() {
-    let pool = Arc::new(BufferPool::with_config(64, 4));
-    let (tx, rx) = mpsc::channel::<C2MeCommand>(1);
-
-    tx.send(C2MeCommand::Data {
-        payload: make_pooled_payload_from(&pool, &[9]),
-        flags: 1,
-    })
-    .await
-    .unwrap();
-
-    let tx2 = tx.clone();
-    let pool2 = pool.clone();
-    let blocked_send = tokio::spawn(async move {
-        enqueue_c2me_command(
-            &tx2,
-            C2MeCommand::Data {
-                payload: make_pooled_payload_from(&pool2, &[7, 7, 7]),
-                flags: 2,
-            },
-        )
-        .await
-    });
-
-    tokio::time::sleep(TokioDuration::from_millis(10)).await;
-    drop(rx);
-
-    let result = timeout(TokioDuration::from_secs(1), blocked_send)
-        .await
-        .expect("blocked send task must finish")
-        .expect("blocked send task must not panic");
-
-    assert!(
-        result.is_err(),
-        "closing receiver while sender is blocked must fail enqueue"
-    );
-    drop(result);
-    assert!(
-        pool.stats().pooled >= 2,
-        "both queued and blocked payloads must return to pool after channel close"
-    );
-}
-
-#[test]
-fn desync_dedup_cache_is_bounded() {
-    let _guard = desync_dedup_test_lock()
-        .lock()
-        .expect("desync dedup test lock must be available");
-    clear_desync_dedup_for_testing();
-
-    let now = Instant::now();
-    for key in 0..DESYNC_DEDUP_MAX_ENTRIES as u64 {
-        assert!(
-            should_emit_full_desync(key, false, now),
-            "unique keys up to cap must be tracked"
-        );
-    }
-
-    assert!(
-        !should_emit_full_desync(u64::MAX, false, now),
-        "new key above cap must remain suppressed to avoid log amplification"
-    );
-
-    assert!(
-        !should_emit_full_desync(7, false, now),
-        "already tracked key inside dedup window must stay suppressed"
-    );
-}
-
-#[test]
-fn desync_dedup_full_cache_churn_stays_suppressed() {
-    let _guard = desync_dedup_test_lock()
-        .lock()
-        .expect("desync dedup test lock must be available");
-    clear_desync_dedup_for_testing();
-
-    let now = Instant::now();
-    for key in 0..DESYNC_DEDUP_MAX_ENTRIES as u64 {
-        assert!(should_emit_full_desync(key, false, now));
-    }
-
-    for offset in 0..2048u64 {
-        assert!(
-            !should_emit_full_desync(u64::MAX - offset, false, now),
-            "fresh full-cache churn must remain suppressed under pressure"
-        );
-    }
-}
-
-fn make_forensics_state() -> RelayForensicsState {
-    RelayForensicsState {
-        trace_id: 1,
-        conn_id: 2,
-        user: "test-user".to_string(),
-        peer: "127.0.0.1:50000".parse::<SocketAddr>().unwrap(),
-        peer_hash: 3,
-        started_at: Instant::now(),
-        bytes_c2me: 0,
-        bytes_me2c: Arc::new(AtomicU64::new(0)),
-        desync_all_full: false,
-    }
-}
-
-fn make_crypto_reader(reader: tokio::io::DuplexStream) -> CryptoReader<tokio::io::DuplexStream> {
-    let key = [0u8; 32];
-    let iv = 0u128;
-    CryptoReader::new(reader, AesCtr::new(&key, iv))
-}
-
-fn make_crypto_writer(writer: tokio::io::DuplexStream) -> CryptoWriter<tokio::io::DuplexStream> {
-    let key = [0u8; 32];
-    let iv = 0u128;
-    CryptoWriter::new(writer, AesCtr::new(&key, iv), 8 * 1024)
-}
-
-fn encrypt_for_reader(plaintext: &[u8]) -> Vec<u8> {
-    let key = [0u8; 32];
-    let iv = 0u128;
-    let mut cipher = AesCtr::new(&key, iv);
-    cipher.encrypt(plaintext)
-}
-
-#[tokio::test]
-async fn read_client_payload_times_out_on_header_stall() {
-    let _guard = desync_dedup_test_lock()
-        .lock()
-        .expect("middle relay test lock must be available");
-    let (reader, _writer) = duplex(1024);
-    let mut crypto_reader = make_crypto_reader(reader);
-    let buffer_pool = Arc::new(BufferPool::new());
-    let stats = Stats::new();
-    let forensics = make_forensics_state();
-    let mut frame_counter = 0;
-
-    let result = read_client_payload(
-        &mut crypto_reader,
-        ProtoTag::Intermediate,
-        1024,
-        TokioDuration::from_millis(25),
-        &buffer_pool,
-        &forensics,
-        &mut frame_counter,
-        &stats,
-    )
-    .await;
-
-    assert!(
-        matches!(result, Err(ProxyError::Io(ref e)) if e.kind() == std::io::ErrorKind::TimedOut),
-        "stalled header read must time out"
-    );
-}
-
-#[tokio::test]
-async fn read_client_payload_times_out_on_payload_stall() {
-    let _guard = desync_dedup_test_lock()
-        .lock()
-        .expect("middle relay test lock must be available");
-    let (reader, mut writer) = duplex(1024);
-    let encrypted_len = encrypt_for_reader(&[8, 0, 0, 0]);
-    writer.write_all(&encrypted_len).await.unwrap();
-
-    let mut crypto_reader = make_crypto_reader(reader);
-    let buffer_pool = Arc::new(BufferPool::new());
-    let stats = Stats::new();
-    let forensics = make_forensics_state();
-    let mut frame_counter = 0;
-
-    let result = read_client_payload(
-        &mut crypto_reader,
-        ProtoTag::Intermediate,
-        1024,
-        TokioDuration::from_millis(25),
-        &buffer_pool,
-        &forensics,
-        &mut frame_counter,
-        &stats,
-    )
-    .await;
-
-    assert!(
-        matches!(result, Err(ProxyError::Io(ref e)) if e.kind() == std::io::ErrorKind::TimedOut),
-        "stalled payload body read must time out"
-    );
-}
-
-#[tokio::test]
-async fn read_client_payload_large_intermediate_frame_is_exact() {
-    let _guard = desync_dedup_test_lock()
-        .lock()
-        .expect("middle relay test lock must be available");
-
-    let (reader, mut writer) = duplex(262_144);
-    let mut crypto_reader = make_crypto_reader(reader);
-    let buffer_pool = Arc::new(BufferPool::new());
-    let stats = Stats::new();
-    let forensics = make_forensics_state();
-    let mut frame_counter = 0;
-
-    let payload_len = buffer_pool.buffer_size().saturating_mul(3).max(65_537);
-    let mut plaintext = Vec::with_capacity(4 + payload_len);
-    plaintext.extend_from_slice(&(payload_len as u32).to_le_bytes());
-    plaintext.extend((0..payload_len).map(|idx| (idx as u8).wrapping_mul(31)));
-
-    let encrypted = encrypt_for_reader(&plaintext);
-    writer.write_all(&encrypted).await.unwrap();
-
-    let read = read_client_payload(
-        &mut crypto_reader,
-        ProtoTag::Intermediate,
-        payload_len + 16,
-        TokioDuration::from_secs(1),
-        &buffer_pool,
-        &forensics,
-        &mut frame_counter,
-        &stats,
-    )
-    .await
-    .expect("payload read must succeed")
-    .expect("frame must be present");
-
-    let (frame, quickack) = read;
-    assert!(!quickack, "quickack flag must be unset");
-    assert_eq!(frame.len(), payload_len, "payload size must match wire length");
-    for (idx, byte) in frame.iter().enumerate() {
-        assert_eq!(*byte, (idx as u8).wrapping_mul(31));
-    }
-    assert_eq!(frame_counter, 1, "exactly one frame must be counted");
-}
-
-#[tokio::test]
-async fn read_client_payload_secure_strips_tail_padding_bytes() {
-    let _guard = desync_dedup_test_lock()
-        .lock()
-        .expect("middle relay test lock must be available");
-
-    let (reader, mut writer) = duplex(1024);
-    let mut crypto_reader = make_crypto_reader(reader);
-    let buffer_pool = Arc::new(BufferPool::new());
-    let stats = Stats::new();
-    let forensics = make_forensics_state();
-    let mut frame_counter = 0;
-
-    let payload = [0x11u8, 0x22, 0x33, 0x44, 0xaa, 0xbb, 0xcc, 0xdd];
-    let tail = [0xeeu8, 0xff, 0x99];
-    let wire_len = payload.len() + tail.len();
-
-    let mut plaintext = Vec::with_capacity(4 + wire_len);
-    plaintext.extend_from_slice(&(wire_len as u32).to_le_bytes());
-    plaintext.extend_from_slice(&payload);
-    plaintext.extend_from_slice(&tail);
-    let encrypted = encrypt_for_reader(&plaintext);
-    writer.write_all(&encrypted).await.unwrap();
-
-    let read = read_client_payload(
-        &mut crypto_reader,
-        ProtoTag::Secure,
-        1024,
-        TokioDuration::from_secs(1),
-        &buffer_pool,
-        &forensics,
-        &mut frame_counter,
-        &stats,
-    )
-    .await
-    .expect("secure payload read must succeed")
-    .expect("secure frame must be present");
-
-    let (frame, quickack) = read;
-    assert!(!quickack, "quickack flag must be unset");
-    assert_eq!(frame.as_ref(), &payload);
-    assert_eq!(frame_counter, 1, "one secure frame must be counted");
-}
-
-#[tokio::test]
-async fn read_client_payload_secure_rejects_wire_len_below_4() {
-    let _guard = desync_dedup_test_lock()
-        .lock()
-        .expect("middle relay test lock must be available");
-
-    let (reader, mut writer) = duplex(1024);
-    let mut crypto_reader = make_crypto_reader(reader);
-    let buffer_pool = Arc::new(BufferPool::new());
-    let stats = Stats::new();
-    let forensics = make_forensics_state();
-    let mut frame_counter = 0;
-
-    let mut plaintext = Vec::with_capacity(7);
-    plaintext.extend_from_slice(&3u32.to_le_bytes());
-    plaintext.extend_from_slice(&[1u8, 2, 3]);
-    let encrypted = encrypt_for_reader(&plaintext);
-    writer.write_all(&encrypted).await.unwrap();
-
-    let result = read_client_payload(
-        &mut crypto_reader,
-        ProtoTag::Secure,
-        1024,
-        TokioDuration::from_secs(1),
-        &buffer_pool,
-        &forensics,
-        &mut frame_counter,
-        &stats,
-    )
-    .await;
-
-    assert!(
-        matches!(result, Err(ProxyError::Proxy(ref msg)) if msg.contains("Frame too small: 3")),
-        "secure wire length below 4 must be fail-closed by the frame-too-small guard"
-    );
-}
-
-#[tokio::test]
-async fn read_client_payload_intermediate_skips_zero_len_frame() {
-    let _guard = desync_dedup_test_lock()
-        .lock()
-        .expect("middle relay test lock must be available");
-
-    let (reader, mut writer) = duplex(1024);
-    let mut crypto_reader = make_crypto_reader(reader);
-    let buffer_pool = Arc::new(BufferPool::new());
-    let stats = Stats::new();
-    let forensics = make_forensics_state();
-    let mut frame_counter = 0;
-
-    let payload = [7u8, 6, 5, 4, 3, 2, 1, 0];
-    let mut plaintext = Vec::with_capacity(4 + 4 + payload.len());
-    plaintext.extend_from_slice(&0u32.to_le_bytes());
-    plaintext.extend_from_slice(&(payload.len() as u32).to_le_bytes());
-    plaintext.extend_from_slice(&payload);
-    let encrypted = encrypt_for_reader(&plaintext);
-    writer.write_all(&encrypted).await.unwrap();
-
-    let read = read_client_payload(
-        &mut crypto_reader,
-        ProtoTag::Intermediate,
-        1024,
-        TokioDuration::from_secs(1),
-        &buffer_pool,
-        &forensics,
-        &mut frame_counter,
-        &stats,
-    )
-    .await
-    .expect("intermediate payload read must succeed")
-    .expect("frame must be present");
-
-    let (frame, quickack) = read;
-    assert!(!quickack, "quickack flag must be unset");
-    assert_eq!(frame.as_ref(), &payload);
-    assert_eq!(frame_counter, 1, "zero-length frame must be skipped");
-}
-
-#[tokio::test]
-async fn read_client_payload_abridged_extended_len_sets_quickack() {
-    let _guard = desync_dedup_test_lock()
-        .lock()
-        .expect("middle relay test lock must be available");
-
-    let (reader, mut writer) = duplex(4096);
-    let mut crypto_reader = make_crypto_reader(reader);
-    let buffer_pool = Arc::new(BufferPool::new());
-    let stats = Stats::new();
-    let forensics = make_forensics_state();
-    let mut frame_counter = 0;
-
-    let payload_len = 4 * 130;
-    let len_words = (payload_len / 4) as u32;
-    let mut plaintext = Vec::with_capacity(1 + 3 + payload_len);
-    plaintext.push(0xff | 0x80);
-    let lw = len_words.to_le_bytes();
-    plaintext.extend_from_slice(&lw[..3]);
-    plaintext.extend((0..payload_len).map(|idx| (idx as u8).wrapping_add(17)));
-
-    let encrypted = encrypt_for_reader(&plaintext);
-    writer.write_all(&encrypted).await.unwrap();
-
-    let read = read_client_payload(
-        &mut crypto_reader,
-        ProtoTag::Abridged,
-        payload_len + 16,
-        TokioDuration::from_secs(1),
-        &buffer_pool,
-        &forensics,
-        &mut frame_counter,
-        &stats,
-    )
-    .await
-    .expect("abridged payload read must succeed")
-    .expect("frame must be present");
-
-    let (frame, quickack) = read;
-    assert!(quickack, "quickack bit must be propagated from abridged header");
-    assert_eq!(frame.len(), payload_len);
-    assert_eq!(frame_counter, 1, "one abridged frame must be counted");
-}
-
-#[tokio::test]
-async fn read_client_payload_returns_buffer_to_pool_after_emit() {
-    let _guard = desync_dedup_test_lock()
-        .lock()
-        .expect("middle relay test lock must be available");
-
-    let pool = Arc::new(BufferPool::with_config(64, 8));
-    pool.preallocate(1);
-    assert_eq!(pool.stats().pooled, 1, "precondition: one pooled buffer");
-
-    let (reader, mut writer) = duplex(4096);
-    let mut crypto_reader = make_crypto_reader(reader);
-    let stats = Stats::new();
-    let forensics = make_forensics_state();
-    let mut frame_counter = 0;
-
-    // Force growth beyond default pool buffer size to catch ownership-take regressions.
-    let payload_len = 257usize;
-    let mut plaintext = Vec::with_capacity(4 + payload_len);
-    plaintext.extend_from_slice(&(payload_len as u32).to_le_bytes());
-    plaintext.extend((0..payload_len).map(|idx| (idx as u8).wrapping_mul(13)));
-
-    let encrypted = encrypt_for_reader(&plaintext);
-    writer.write_all(&encrypted).await.unwrap();
-
-    let _ = read_client_payload(
-        &mut crypto_reader,
-        ProtoTag::Intermediate,
-        payload_len + 8,
-        TokioDuration::from_secs(1),
-        &pool,
-        &forensics,
-        &mut frame_counter,
-        &stats,
-    )
-    .await
-    .expect("payload read must succeed")
-    .expect("frame must be present");
-
-    assert_eq!(frame_counter, 1);
-    let pool_stats = pool.stats();
-    assert!(
-        pool_stats.pooled >= 1,
-        "emitted payload buffer must be returned to pool to avoid pool drain"
-    );
-}
-
-#[tokio::test]
-async fn read_client_payload_keeps_pool_buffer_checked_out_until_frame_drop() {
-    let _guard = desync_dedup_test_lock()
-        .lock()
-        .expect("middle relay test lock must be available");
-
-    let pool = Arc::new(BufferPool::with_config(64, 2));
-    pool.preallocate(1);
-    assert_eq!(pool.stats().pooled, 1, "one pooled buffer must be available");
-
-    let (reader, mut writer) = duplex(1024);
-    let mut crypto_reader = make_crypto_reader(reader);
-    let stats = Stats::new();
-    let forensics = make_forensics_state();
-    let mut frame_counter = 0;
-
-    let payload = [0x41u8, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48];
-    let mut plaintext = Vec::with_capacity(4 + payload.len());
-    plaintext.extend_from_slice(&(payload.len() as u32).to_le_bytes());
-    plaintext.extend_from_slice(&payload);
-    let encrypted = encrypt_for_reader(&plaintext);
-    writer.write_all(&encrypted).await.unwrap();
-
-    let (frame, quickack) = read_client_payload(
-        &mut crypto_reader,
-        ProtoTag::Intermediate,
-        1024,
-        TokioDuration::from_secs(1),
-        &pool,
-        &forensics,
-        &mut frame_counter,
-        &stats,
-    )
-    .await
-    .expect("payload read must succeed")
-    .expect("frame must be present");
-
-    assert!(!quickack);
-    assert_eq!(frame.as_ref(), &payload);
-    assert_eq!(
-        pool.stats().pooled,
-        0,
-        "buffer must stay checked out while frame payload is alive"
-    );
-
-    drop(frame);
-    assert!(
-        pool.stats().pooled >= 1,
-        "buffer must return to pool only after frame drop"
-    );
-}
-
-#[tokio::test]
-async fn enqueue_c2me_close_unblocks_after_queue_drain() {
-    let (tx, mut rx) = mpsc::channel::<C2MeCommand>(1);
-    tx.send(C2MeCommand::Data {
-        payload: make_pooled_payload(&[0x41]),
-        flags: 0,
-    })
-    .await
-    .unwrap();
-
-    let tx2 = tx.clone();
-    let close_task = tokio::spawn(async move { enqueue_c2me_command(&tx2, C2MeCommand::Close).await });
-
-    tokio::time::sleep(TokioDuration::from_millis(10)).await;
-
-    let first = timeout(TokioDuration::from_millis(100), rx.recv())
-        .await
-        .unwrap()
-        .expect("first queued item must be present");
-    assert!(matches!(first, C2MeCommand::Data { .. }));
-
-    close_task.await.unwrap().expect("close enqueue must succeed after drain");
-
-    let second = timeout(TokioDuration::from_millis(100), rx.recv())
-        .await
-        .unwrap()
-        .expect("close command must follow after queue drain");
-    assert!(matches!(second, C2MeCommand::Close));
-}
-
-#[tokio::test]
-async fn enqueue_c2me_close_full_then_receiver_drop_fails_cleanly() {
-    let (tx, rx) = mpsc::channel::<C2MeCommand>(1);
-    tx.send(C2MeCommand::Data {
-        payload: make_pooled_payload(&[0x42]),
-        flags: 0,
-    })
-    .await
-    .unwrap();
-
-    let tx2 = tx.clone();
-    let close_task = tokio::spawn(async move { enqueue_c2me_command(&tx2, C2MeCommand::Close).await });
-
-    tokio::time::sleep(TokioDuration::from_millis(10)).await;
-    drop(rx);
-
-    let result = timeout(TokioDuration::from_secs(1), close_task)
-        .await
-        .expect("close task must finish")
-        .expect("close task must not panic");
-    assert!(
-        result.is_err(),
-        "close enqueue must fail cleanly when receiver is dropped under pressure"
-    );
-}
-
-#[tokio::test]
-async fn process_me_writer_response_ack_obeys_flush_policy() {
-    let (writer_side, _reader_side) = duplex(1024);
-    let mut writer = make_crypto_writer(writer_side);
-    let rng = SecureRandom::new();
-    let mut frame_buf = Vec::new();
-    let stats = Stats::new();
-    let bytes_me2c = AtomicU64::new(0);
-
-    let immediate = process_me_writer_response(
-        MeResponse::Ack(0x11223344),
-        &mut writer,
-        ProtoTag::Intermediate,
-        &rng,
-        &mut frame_buf,
-        &stats,
-        "user",
-        &bytes_me2c,
-        77,
-        true,
-        false,
-    )
-    .await
-    .expect("ack response must be processed");
-
-    assert!(matches!(
-        immediate,
-        MeWriterResponseOutcome::Continue {
-            frames: 1,
-            bytes: 4,
-            flush_immediately: true,
-        }
-    ));
-
-    let delayed = process_me_writer_response(
-        MeResponse::Ack(0x55667788),
-        &mut writer,
-        ProtoTag::Intermediate,
-        &rng,
-        &mut frame_buf,
-        &stats,
-        "user",
-        &bytes_me2c,
-        77,
-        false,
-        false,
-    )
-    .await
-    .expect("ack response must be processed");
-
-    assert!(matches!(
-        delayed,
-        MeWriterResponseOutcome::Continue {
-            frames: 1,
-            bytes: 4,
-            flush_immediately: false,
-        }
-    ));
-}
-
-#[tokio::test]
-async fn process_me_writer_response_data_updates_byte_accounting() {
-    let (writer_side, _reader_side) = duplex(1024);
-    let mut writer = make_crypto_writer(writer_side);
-    let rng = SecureRandom::new();
-    let mut frame_buf = Vec::new();
-    let stats = Stats::new();
-    let bytes_me2c = AtomicU64::new(0);
-
-    let payload = vec![1u8, 2, 3, 4, 5, 6, 7, 8, 9];
-    let outcome = process_me_writer_response(
-        MeResponse::Data {
-            flags: 0,
-            data: Bytes::from(payload.clone()),
-        },
-        &mut writer,
-        ProtoTag::Intermediate,
-        &rng,
-        &mut frame_buf,
-        &stats,
-        "user",
-        &bytes_me2c,
-        88,
-        false,
-        false,
-    )
-    .await
-    .expect("data response must be processed");
-
-    assert!(matches!(
-        outcome,
-        MeWriterResponseOutcome::Continue {
-            frames: 1,
-            bytes,
-            flush_immediately: false,
-        } if bytes == payload.len()
-    ));
-    assert_eq!(
-        bytes_me2c.load(std::sync::atomic::Ordering::Relaxed),
-        payload.len() as u64,
-        "ME->C byte accounting must increase by emitted payload size"
-    );
-}

src/proxy/mod.rs

@@ -1,12 +1,72 @@
 //! Proxy Defs
 
+// Apply strict linting to proxy production code while keeping test builds noise-tolerant.
+#![cfg_attr(test, allow(warnings))]
+#![cfg_attr(not(test), forbid(clippy::undocumented_unsafe_blocks))]
+#![cfg_attr(
+    not(test),
+    deny(
+        clippy::unwrap_used,
+        clippy::expect_used,
+        clippy::panic,
+        clippy::todo,
+        clippy::unimplemented,
+        clippy::correctness,
+        clippy::option_if_let_else,
+        clippy::or_fun_call,
+        clippy::branches_sharing_code,
+        clippy::single_option_map,
+        clippy::useless_let_if_seq,
+        clippy::redundant_locals,
+        clippy::cloned_ref_to_slice_refs,
+        unsafe_code,
+        clippy::await_holding_lock,
+        clippy::await_holding_refcell_ref,
+        clippy::debug_assert_with_mut_call,
+        clippy::macro_use_imports,
+        clippy::cast_ptr_alignment,
+        clippy::cast_lossless,
+        clippy::ptr_as_ptr,
+        clippy::large_stack_arrays,
+        clippy::same_functions_in_if_condition,
+        trivial_casts,
+        trivial_numeric_casts,
+        unused_extern_crates,
+        unused_import_braces,
+        rust_2018_idioms
+    )
+)]
+#![cfg_attr(
+    not(test),
+    allow(
+        clippy::use_self,
+        clippy::redundant_closure,
+        clippy::too_many_arguments,
+        clippy::doc_markdown,
+        clippy::missing_const_for_fn,
+        clippy::unnecessary_operation,
+        clippy::redundant_pub_crate,
+        clippy::derive_partial_eq_without_eq,
+        clippy::type_complexity,
+        clippy::new_ret_no_self,
+        clippy::cast_possible_truncation,
+        clippy::cast_possible_wrap,
+        clippy::significant_drop_tightening,
+        clippy::significant_drop_in_scrutinee,
+        clippy::float_cmp,
+        clippy::nursery
+    )
+)]
+
+pub mod adaptive_buffers;
 pub mod client;
 pub mod direct_relay;
 pub mod handshake;
 pub mod masking;
 pub mod middle_relay;
-pub mod route_mode;
 pub mod relay;
+pub mod route_mode;
+pub mod session_eviction;
 
 pub use client::ClientHandler;
 #[allow(unused_imports)]

src/proxy/relay.rs

@@ -51,20 +51,18 @@
 //! - `poll_write` on client = S→C (to client)     → `octets_to`, `msgs_to`
 //! - `SharedCounters` (atomics) let the watchdog read stats without locking
 
+use crate::error::{ProxyError, Result};
+use crate::stats::{Stats, UserStats};
+use crate::stream::BufferPool;
 use std::io;
 use std::pin::Pin;
 use std::sync::Arc;
-use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 use std::task::{Context, Poll};
 use std::time::Duration;
-use tokio::io::{
-    AsyncRead, AsyncWrite, AsyncWriteExt, ReadBuf, copy_bidirectional_with_sizes,
-};
+use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt, ReadBuf, copy_bidirectional_with_sizes};
 use tokio::time::Instant;
 use tracing::{debug, trace, warn};
-use crate::error::Result;
-use crate::stats::Stats;
-use crate::stream::BufferPool;
 
 // ============= Constants =============
 
@@ -80,6 +78,11 @@ const ACTIVITY_TIMEOUT: Duration = Duration::from_secs(1800);
 /// without measurable overhead from atomic reads.
 const WATCHDOG_INTERVAL: Duration = Duration::from_secs(10);
 
+#[inline]
+fn watchdog_delta(current: u64, previous: u64) -> u64 {
+    current.saturating_sub(previous)
+}
+
 // ============= CombinedStream =============
 
 /// Combines separate read and write halves into a single bidirectional stream.
@@ -205,6 +208,10 @@ struct StatsIo<S> {
     counters: Arc<SharedCounters>,
     stats: Arc<Stats>,
     user: String,
+    user_stats: Arc<UserStats>,
+    quota_limit: Option<u64>,
+    quota_exceeded: Arc<AtomicBool>,
+    quota_bytes_since_check: u64,
     epoch: Instant,
 }
 
@@ -214,14 +221,68 @@ impl<S> StatsIo<S> {
         counters: Arc<SharedCounters>,
         stats: Arc<Stats>,
         user: String,
+        quota_limit: Option<u64>,
+        quota_exceeded: Arc<AtomicBool>,
         epoch: Instant,
     ) -> Self {
         // Mark initial activity so the watchdog doesn't fire before data flows
         counters.touch(Instant::now(), epoch);
-        Self { inner, counters, stats, user, epoch }
+        let user_stats = stats.get_or_create_user_stats_handle(&user);
+        Self {
+            inner,
+            counters,
+            stats,
+            user,
+            user_stats,
+            quota_limit,
+            quota_exceeded,
+            quota_bytes_since_check: 0,
+            epoch,
+        }
     }
 }
 
+#[derive(Debug)]
+struct QuotaIoSentinel;
+
+impl std::fmt::Display for QuotaIoSentinel {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str("user data quota exceeded")
+    }
+}
+
+impl std::error::Error for QuotaIoSentinel {}
+
+fn quota_io_error() -> io::Error {
+    io::Error::new(io::ErrorKind::PermissionDenied, QuotaIoSentinel)
+}
+
+fn is_quota_io_error(err: &io::Error) -> bool {
+    err.kind() == io::ErrorKind::PermissionDenied
+        && err
+            .get_ref()
+            .and_then(|source| source.downcast_ref::<QuotaIoSentinel>())
+            .is_some()
+}
+
+const QUOTA_NEAR_LIMIT_BYTES: u64 = 64 * 1024;
+const QUOTA_LARGE_CHARGE_BYTES: u64 = 16 * 1024;
+const QUOTA_ADAPTIVE_INTERVAL_MIN_BYTES: u64 = 4 * 1024;
+const QUOTA_ADAPTIVE_INTERVAL_MAX_BYTES: u64 = 64 * 1024;
+
+#[inline]
+fn quota_adaptive_interval_bytes(remaining_before: u64) -> u64 {
+    remaining_before.saturating_div(2).clamp(
+        QUOTA_ADAPTIVE_INTERVAL_MIN_BYTES,
+        QUOTA_ADAPTIVE_INTERVAL_MAX_BYTES,
+    )
+}
+
+#[inline]
+fn should_immediate_quota_check(remaining_before: u64, charge_bytes: u64) -> bool {
+    remaining_before <= QUOTA_NEAR_LIMIT_BYTES || charge_bytes >= QUOTA_LARGE_CHARGE_BYTES
+}
+
 impl<S: AsyncRead + Unpin> AsyncRead for StatsIo<S> {
     fn poll_read(
         self: Pin<&mut Self>,
@@ -229,19 +290,61 @@ impl<S: AsyncRead + Unpin> AsyncRead for StatsIo<S> {
         buf: &mut ReadBuf<'_>,
     ) -> Poll<io::Result<()>> {
         let this = self.get_mut();
+        if this.quota_exceeded.load(Ordering::Acquire) {
+            return Poll::Ready(Err(quota_io_error()));
+        }
+
+        let mut remaining_before = None;
+        if let Some(limit) = this.quota_limit {
+            let used_before = this.user_stats.quota_used();
+            let remaining = limit.saturating_sub(used_before);
+            if remaining == 0 {
+                this.quota_exceeded.store(true, Ordering::Release);
+                return Poll::Ready(Err(quota_io_error()));
+            }
+            remaining_before = Some(remaining);
+        }
+
         let before = buf.filled().len();
 
         match Pin::new(&mut this.inner).poll_read(cx, buf) {
             Poll::Ready(Ok(())) => {
                 let n = buf.filled().len() - before;
                 if n > 0 {
+                    let n_to_charge = n as u64;
+
                     // C→S: client sent data
-                    this.counters.c2s_bytes.fetch_add(n as u64, Ordering::Relaxed);
+                    this.counters
+                        .c2s_bytes
+                        .fetch_add(n_to_charge, Ordering::Relaxed);
                     this.counters.c2s_ops.fetch_add(1, Ordering::Relaxed);
                     this.counters.touch(Instant::now(), this.epoch);
 
-                    this.stats.add_user_octets_from(&this.user, n as u64);
-                    this.stats.increment_user_msgs_from(&this.user);
+                    this.stats
+                        .add_user_octets_from_handle(this.user_stats.as_ref(), n_to_charge);
+                    this.stats
+                        .increment_user_msgs_from_handle(this.user_stats.as_ref());
+
+                    if let (Some(limit), Some(remaining)) = (this.quota_limit, remaining_before) {
+                        this.stats
+                            .quota_charge_post_write(this.user_stats.as_ref(), n_to_charge);
+                        if should_immediate_quota_check(remaining, n_to_charge) {
+                            this.quota_bytes_since_check = 0;
+                            if this.user_stats.quota_used() >= limit {
+                                this.quota_exceeded.store(true, Ordering::Release);
+                            }
+                        } else {
+                            this.quota_bytes_since_check =
+                                this.quota_bytes_since_check.saturating_add(n_to_charge);
+                            let interval = quota_adaptive_interval_bytes(remaining);
+                            if this.quota_bytes_since_check >= interval {
+                                this.quota_bytes_since_check = 0;
+                                if this.user_stats.quota_used() >= limit {
+                                    this.quota_exceeded.store(true, Ordering::Release);
+                                }
+                            }
+                        }
+                    }
 
                     trace!(user = %this.user, bytes = n, "C->S");
                 }
@@ -259,17 +362,58 @@ impl<S: AsyncWrite + Unpin> AsyncWrite for StatsIo<S> {
         buf: &[u8],
     ) -> Poll<io::Result<usize>> {
         let this = self.get_mut();
+        if this.quota_exceeded.load(Ordering::Acquire) {
+            return Poll::Ready(Err(quota_io_error()));
+        }
+
+        let mut remaining_before = None;
+        if let Some(limit) = this.quota_limit {
+            let used_before = this.user_stats.quota_used();
+            let remaining = limit.saturating_sub(used_before);
+            if remaining == 0 {
+                this.quota_exceeded.store(true, Ordering::Release);
+                return Poll::Ready(Err(quota_io_error()));
+            }
+            remaining_before = Some(remaining);
+        }
 
         match Pin::new(&mut this.inner).poll_write(cx, buf) {
             Poll::Ready(Ok(n)) => {
                 if n > 0 {
+                    let n_to_charge = n as u64;
+
                     // S→C: data written to client
-                    this.counters.s2c_bytes.fetch_add(n as u64, Ordering::Relaxed);
+                    this.counters
+                        .s2c_bytes
+                        .fetch_add(n_to_charge, Ordering::Relaxed);
                     this.counters.s2c_ops.fetch_add(1, Ordering::Relaxed);
                     this.counters.touch(Instant::now(), this.epoch);
 
-                    this.stats.add_user_octets_to(&this.user, n as u64);
-                    this.stats.increment_user_msgs_to(&this.user);
+                    this.stats
+                        .add_user_octets_to_handle(this.user_stats.as_ref(), n_to_charge);
+                    this.stats
+                        .increment_user_msgs_to_handle(this.user_stats.as_ref());
+
+                    if let (Some(limit), Some(remaining)) = (this.quota_limit, remaining_before) {
+                        this.stats
+                            .quota_charge_post_write(this.user_stats.as_ref(), n_to_charge);
+                        if should_immediate_quota_check(remaining, n_to_charge) {
+                            this.quota_bytes_since_check = 0;
+                            if this.user_stats.quota_used() >= limit {
+                                this.quota_exceeded.store(true, Ordering::Release);
+                            }
+                        } else {
+                            this.quota_bytes_since_check =
+                                this.quota_bytes_since_check.saturating_add(n_to_charge);
+                            let interval = quota_adaptive_interval_bytes(remaining);
+                            if this.quota_bytes_since_check >= interval {
+                                this.quota_bytes_since_check = 0;
+                                if this.user_stats.quota_used() >= limit {
+                                    this.quota_exceeded.store(true, Ordering::Release);
+                                }
+                            }
+                        }
+                    }
 
                     trace!(user = %this.user, bytes = n, "S->C");
                 }
@@ -307,7 +451,8 @@ impl<S: AsyncWrite + Unpin> AsyncWrite for StatsIo<S> {
 /// - Per-user stats: bytes and ops counted per direction
 /// - Periodic rate logging: every 10 seconds when active
 /// - Clean shutdown: both write sides are shut down on exit
-/// - Error propagation: I/O errors are returned as `ProxyError::Io`
+/// - Error propagation: quota exits return `ProxyError::DataQuotaExceeded`,
+///   other I/O failures are returned as `ProxyError::Io`
 pub async fn relay_bidirectional<CR, CW, SR, SW>(
     client_reader: CR,
     client_writer: CW,
@@ -317,6 +462,7 @@ pub async fn relay_bidirectional<CR, CW, SR, SW>(
     s2c_buf_size: usize,
     user: &str,
     stats: Arc<Stats>,
+    quota_limit: Option<u64>,
     _buffer_pool: Arc<BufferPool>,
 ) -> Result<()>
 where
@@ -327,6 +473,7 @@ where
 {
     let epoch = Instant::now();
     let counters = Arc::new(SharedCounters::new());
+    let quota_exceeded = Arc::new(AtomicBool::new(false));
     let user_owned = user.to_string();
 
     // ── Combine split halves into bidirectional streams ──────────────
@@ -339,12 +486,15 @@ where
         Arc::clone(&counters),
         Arc::clone(&stats),
         user_owned.clone(),
+        quota_limit,
+        Arc::clone(&quota_exceeded),
         epoch,
     );
 
     // ── Watchdog: activity timeout + periodic rate logging ──────────
     let wd_counters = Arc::clone(&counters);
     let wd_user = user_owned.clone();
+    let wd_quota_exceeded = Arc::clone(&quota_exceeded);
 
     let watchdog = async {
         let mut prev_c2s: u64 = 0;
@@ -356,6 +506,11 @@ where
             let now = Instant::now();
             let idle = wd_counters.idle_duration(now, epoch);
 
+            if wd_quota_exceeded.load(Ordering::Acquire) {
+                warn!(user = %wd_user, "User data quota reached, closing relay");
+                return;
+            }
+
             // ── Activity timeout ────────────────────────────────────
             if idle >= ACTIVITY_TIMEOUT {
                 let c2s = wd_counters.c2s_bytes.load(Ordering::Relaxed);
@@ -373,8 +528,8 @@ where
             // ── Periodic rate logging ───────────────────────────────
             let c2s = wd_counters.c2s_bytes.load(Ordering::Relaxed);
             let s2c = wd_counters.s2c_bytes.load(Ordering::Relaxed);
-            let c2s_delta = c2s - prev_c2s;
-            let s2c_delta = s2c - prev_s2c;
+            let c2s_delta = watchdog_delta(c2s, prev_c2s);
+            let s2c_delta = watchdog_delta(s2c, prev_s2c);
 
             if c2s_delta > 0 || s2c_delta > 0 {
                 let secs = WATCHDOG_INTERVAL.as_secs_f64();
@@ -439,6 +594,22 @@ where
             );
             Ok(())
         }
+        Some(Err(e)) if is_quota_io_error(&e) => {
+            let c2s = counters.c2s_bytes.load(Ordering::Relaxed);
+            let s2c = counters.s2c_bytes.load(Ordering::Relaxed);
+            warn!(
+                user = %user_owned,
+                c2s_bytes = c2s,
+                s2c_bytes = s2c,
+                c2s_msgs = c2s_ops,
+                s2c_msgs = s2c_ops,
+                duration_secs = duration.as_secs(),
+                "Data quota reached, closing relay"
+            );
+            Err(ProxyError::DataQuotaExceeded {
+                user: user_owned.clone(),
+            })
+        }
         Some(Err(e)) => {
             // I/O error in one of the directions
             let c2s = counters.c2s_bytes.load(Ordering::Relaxed);
@@ -472,3 +643,31 @@ where
         }
     }
 }
+
+#[cfg(test)]
+#[path = "tests/relay_adversarial_tests.rs"]
+mod adversarial_tests;
+
+#[cfg(test)]
+#[path = "tests/relay_quota_boundary_blackhat_tests.rs"]
+mod relay_quota_boundary_blackhat_tests;
+
+#[cfg(test)]
+#[path = "tests/relay_quota_model_adversarial_tests.rs"]
+mod relay_quota_model_adversarial_tests;
+
+#[cfg(test)]
+#[path = "tests/relay_quota_overflow_regression_tests.rs"]
+mod relay_quota_overflow_regression_tests;
+
+#[cfg(test)]
+#[path = "tests/relay_quota_extended_attack_surface_security_tests.rs"]
+mod relay_quota_extended_attack_surface_security_tests;
+
+#[cfg(test)]
+#[path = "tests/relay_watchdog_delta_security_tests.rs"]
+mod relay_watchdog_delta_security_tests;
+
+#[cfg(test)]
+#[path = "tests/relay_atomic_quota_invariant_tests.rs"]
+mod relay_atomic_quota_invariant_tests;

src/proxy/route_mode.rs

@@ -1,10 +1,10 @@
 use std::sync::Arc;
-use std::sync::atomic::{AtomicU8, AtomicU64, Ordering};
+use std::sync::atomic::{AtomicU64, Ordering};
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use tokio::sync::watch;
 
-pub(crate) const ROUTE_SWITCH_ERROR_MSG: &str = "Route mode switched by cutover";
+pub(crate) const ROUTE_SWITCH_ERROR_MSG: &str = "Session terminated";
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 #[repr(u8)]
@@ -14,17 +14,6 @@ pub(crate) enum RelayRouteMode {
 }
 
 impl RelayRouteMode {
-    pub(crate) fn as_u8(self) -> u8 {
-        self as u8
-    }
-
-    pub(crate) fn from_u8(value: u8) -> Self {
-        match value {
-            1 => Self::Middle,
-            _ => Self::Direct,
-        }
-    }
-
     pub(crate) fn as_str(self) -> &'static str {
         match self {
             Self::Direct => "direct",
@@ -41,8 +30,6 @@ pub(crate) struct RouteCutoverState {
 
 #[derive(Clone)]
 pub(crate) struct RouteRuntimeController {
-    mode: Arc<AtomicU8>,
-    generation: Arc<AtomicU64>,
     direct_since_epoch_secs: Arc<AtomicU64>,
     tx: watch::Sender<RouteCutoverState>,
 }
@@ -60,18 +47,13 @@ impl RouteRuntimeController {
             0
         };
         Self {
-            mode: Arc::new(AtomicU8::new(initial_mode.as_u8())),
-            generation: Arc::new(AtomicU64::new(0)),
             direct_since_epoch_secs: Arc::new(AtomicU64::new(direct_since_epoch_secs)),
             tx,
         }
     }
 
     pub(crate) fn snapshot(&self) -> RouteCutoverState {
-        RouteCutoverState {
-            mode: RelayRouteMode::from_u8(self.mode.load(Ordering::Relaxed)),
-            generation: self.generation.load(Ordering::Relaxed),
-        }
+        *self.tx.borrow()
     }
 
     pub(crate) fn subscribe(&self) -> watch::Receiver<RouteCutoverState> {
@@ -84,20 +66,28 @@ impl RouteRuntimeController {
     }
 
     pub(crate) fn set_mode(&self, mode: RelayRouteMode) -> Option<RouteCutoverState> {
-        let previous = self.mode.swap(mode.as_u8(), Ordering::Relaxed);
-        if previous == mode.as_u8() {
+        let mut next = None;
+        let changed = self.tx.send_if_modified(|state| {
+            if state.mode == mode {
+                return false;
+            }
+            if matches!(mode, RelayRouteMode::Direct) {
+                self.direct_since_epoch_secs
+                    .store(now_epoch_secs(), Ordering::Relaxed);
+            } else {
+                self.direct_since_epoch_secs.store(0, Ordering::Relaxed);
+            }
+            state.mode = mode;
+            state.generation = state.generation.saturating_add(1);
+            next = Some(*state);
+            true
+        });
+
+        if !changed {
             return None;
         }
-        if matches!(mode, RelayRouteMode::Direct) {
-            self.direct_since_epoch_secs
-                .store(now_epoch_secs(), Ordering::Relaxed);
-        } else {
-            self.direct_since_epoch_secs.store(0, Ordering::Relaxed);
-        }
-        let generation = self.generation.fetch_add(1, Ordering::Relaxed) + 1;
-        let next = RouteCutoverState { mode, generation };
-        self.tx.send_replace(next);
-        Some(next)
+
+        next
     }
 }
 
@@ -110,10 +100,10 @@ fn now_epoch_secs() -> u64 {
 
 pub(crate) fn is_session_affected_by_cutover(
     current: RouteCutoverState,
-    _session_mode: RelayRouteMode,
+    session_mode: RelayRouteMode,
     session_generation: u64,
 ) -> bool {
-    current.generation > session_generation
+    current.generation > session_generation && current.mode != session_mode
 }
 
 pub(crate) fn affected_cutover_state(
@@ -129,9 +119,7 @@ pub(crate) fn affected_cutover_state(
 }
 
 pub(crate) fn cutover_stagger_delay(session_id: u64, generation: u64) -> Duration {
-    let mut value = session_id
-        ^ generation.rotate_left(17)
-        ^ 0x9e37_79b9_7f4a_7c15;
+    let mut value = session_id ^ generation.rotate_left(17) ^ 0x9e37_79b9_7f4a_7c15;
     value ^= value >> 30;
     value = value.wrapping_mul(0xbf58_476d_1ce4_e5b9);
     value ^= value >> 27;
@@ -140,3 +128,11 @@ pub(crate) fn cutover_stagger_delay(session_id: u64, generation: u64) -> Duratio
     let ms = 1000 + (value % 1000);
     Duration::from_millis(ms)
 }
+
+#[cfg(test)]
+#[path = "tests/route_mode_security_tests.rs"]
+mod security_tests;
+
+#[cfg(test)]
+#[path = "tests/route_mode_coherence_adversarial_tests.rs"]
+mod coherence_adversarial_tests;

src/proxy/session_eviction.rs

@@ -0,0 +1,48 @@
+#![allow(dead_code)]
+
+/// Session eviction is intentionally disabled in runtime.
+///
+/// The initial `user+dc` single-lease model caused valid parallel client
+/// connections to evict each other. Keep the API shape for compatibility,
+/// but make it a no-op until a safer policy is introduced.
+
+#[derive(Debug, Clone, Default)]
+pub struct SessionLease;
+
+impl SessionLease {
+    pub fn is_stale(&self) -> bool {
+        false
+    }
+
+    #[allow(dead_code)]
+    pub fn release(&self) {}
+}
+
+pub struct RegistrationResult {
+    pub lease: SessionLease,
+    pub replaced_existing: bool,
+}
+
+pub fn register_session(_user: &str, _dc_idx: i16) -> RegistrationResult {
+    RegistrationResult {
+        lease: SessionLease,
+        replaced_existing: false,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_session_eviction_disabled_behavior() {
+        let first = register_session("alice", 2);
+        let second = register_session("alice", 2);
+        assert!(!first.replaced_existing);
+        assert!(!second.replaced_existing);
+        assert!(!first.lease.is_stale());
+        assert!(!second.lease.is_stale());
+        first.lease.release();
+        second.lease.release();
+    }
+}

src/proxy/tests/client_adversarial_tests.rs

@@ -0,0 +1,714 @@
+use super::*;
+use crate::config::ProxyConfig;
+use crate::error::ProxyError;
+use crate::ip_tracker::UserIpTracker;
+use crate::stats::Stats;
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+// ------------------------------------------------------------------
+// Priority 3: Massive Concurrency Stress (OWASP ASVS 5.1.6)
+// ------------------------------------------------------------------
+
+#[tokio::test]
+async fn client_stress_10k_connections_limit_strict() {
+    let user = "stress-user";
+    let limit = 512;
+
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+
+    let mut config = ProxyConfig::default();
+    config
+        .access
+        .user_max_tcp_conns
+        .insert(user.to_string(), limit);
+
+    let iterations = 1000;
+    let mut tasks = Vec::new();
+
+    for i in 0..iterations {
+        let stats = Arc::clone(&stats);
+        let ip_tracker = Arc::clone(&ip_tracker);
+        let config = config.clone();
+        let user_str = user.to_string();
+
+        tasks.push(tokio::spawn(async move {
+            let peer = SocketAddr::new(
+                IpAddr::V4(Ipv4Addr::new(127, 0, 0, (i % 254 + 1) as u8)),
+                10000 + (i % 1000) as u16,
+            );
+
+            match RunningClientHandler::acquire_user_connection_reservation_static(
+                &user_str, &config, stats, peer, ip_tracker,
+            )
+            .await
+            {
+                Ok(res) => Ok(res),
+                Err(ProxyError::ConnectionLimitExceeded { .. }) => Err(()),
+                Err(e) => panic!("Unexpected error: {:?}", e),
+            }
+        }));
+    }
+
+    let results = futures::future::join_all(tasks).await;
+    let mut successes = 0;
+    let mut failures = 0;
+    let mut reservations = Vec::new();
+
+    for res in results {
+        match res.unwrap() {
+            Ok(r) => {
+                successes += 1;
+                reservations.push(r);
+            }
+            Err(_) => failures += 1,
+        }
+    }
+
+    assert_eq!(successes, limit, "Should allow exactly 'limit' connections");
+    assert_eq!(
+        failures,
+        iterations - limit,
+        "Should fail the rest with LimitExceeded"
+    );
+    assert_eq!(stats.get_user_curr_connects(user), limit as u64);
+
+    drop(reservations);
+
+    ip_tracker.drain_cleanup_queue().await;
+
+    assert_eq!(
+        stats.get_user_curr_connects(user),
+        0,
+        "Stats must converge to 0 after all drops"
+    );
+    assert_eq!(
+        ip_tracker.get_active_ip_count(user).await,
+        0,
+        "IP tracker must converge to 0"
+    );
+}
+
+// ------------------------------------------------------------------
+// Priority 3: IP Tracker Race Stress
+// ------------------------------------------------------------------
+
+#[tokio::test]
+async fn client_ip_tracker_race_condition_stress() {
+    let user = "race-user";
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 100).await;
+
+    let iterations = 1000;
+    let mut tasks = Vec::new();
+
+    for i in 0..iterations {
+        let ip_tracker = Arc::clone(&ip_tracker);
+        let ip = IpAddr::V4(Ipv4Addr::new(10, 0, 0, (i % 254 + 1) as u8));
+
+        tasks.push(tokio::spawn(async move {
+            for _ in 0..10 {
+                if let Ok(()) = ip_tracker.check_and_add("race-user", ip).await {
+                    ip_tracker.remove_ip("race-user", ip).await;
+                }
+            }
+        }));
+    }
+
+    futures::future::join_all(tasks).await;
+
+    assert_eq!(
+        ip_tracker.get_active_ip_count(user).await,
+        0,
+        "IP count must be zero after balanced add/remove burst"
+    );
+}
+
+#[tokio::test]
+async fn client_limit_burst_peak_never_exceeds_cap() {
+    let user = "peak-cap-user";
+    let limit = 32;
+    let attempts = 256;
+
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+
+    let mut config = ProxyConfig::default();
+    config
+        .access
+        .user_max_tcp_conns
+        .insert(user.to_string(), limit);
+
+    let peak = Arc::new(AtomicU64::new(0));
+    let mut tasks = Vec::with_capacity(attempts);
+
+    for i in 0..attempts {
+        let stats = Arc::clone(&stats);
+        let ip_tracker = Arc::clone(&ip_tracker);
+        let config = config.clone();
+        let peak = Arc::clone(&peak);
+
+        tasks.push(tokio::spawn(async move {
+            let peer = SocketAddr::new(
+                IpAddr::V4(Ipv4Addr::new(203, 0, 113, (i % 250 + 1) as u8)),
+                20000 + i as u16,
+            );
+
+            let acquired = RunningClientHandler::acquire_user_connection_reservation_static(
+                user,
+                &config,
+                stats.clone(),
+                peer,
+                ip_tracker,
+            )
+            .await;
+
+            if let Ok(reservation) = acquired {
+                let now = stats.get_user_curr_connects(user);
+                loop {
+                    let prev = peak.load(Ordering::Relaxed);
+                    if now <= prev {
+                        break;
+                    }
+                    if peak
+                        .compare_exchange(prev, now, Ordering::Relaxed, Ordering::Relaxed)
+                        .is_ok()
+                    {
+                        break;
+                    }
+                }
+                tokio::time::sleep(Duration::from_millis(2)).await;
+                drop(reservation);
+            }
+        }));
+    }
+
+    futures::future::join_all(tasks).await;
+    ip_tracker.drain_cleanup_queue().await;
+
+    assert!(
+        peak.load(Ordering::Relaxed) <= limit as u64,
+        "peak concurrent reservations must not exceed configured cap"
+    );
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}
+
+#[tokio::test]
+async fn client_quota_rejection_never_mutates_live_counters() {
+    let user = "quota-reject-user";
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+
+    let mut config = ProxyConfig::default();
+    config.access.user_data_quota.insert(user.to_string(), 0);
+
+    let peer: SocketAddr = "198.51.100.201:31111".parse().unwrap();
+    let res = RunningClientHandler::acquire_user_connection_reservation_static(
+        user,
+        &config,
+        stats.clone(),
+        peer,
+        ip_tracker.clone(),
+    )
+    .await;
+
+    assert!(matches!(res, Err(ProxyError::DataQuotaExceeded { .. })));
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}
+
+#[tokio::test]
+async fn client_expiration_rejection_never_mutates_live_counters() {
+    let user = "expired-user";
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+
+    let mut config = ProxyConfig::default();
+    config.access.user_expirations.insert(
+        user.to_string(),
+        chrono::Utc::now() - chrono::Duration::seconds(1),
+    );
+
+    let peer: SocketAddr = "198.51.100.202:31112".parse().unwrap();
+    let res = RunningClientHandler::acquire_user_connection_reservation_static(
+        user,
+        &config,
+        stats.clone(),
+        peer,
+        ip_tracker.clone(),
+    )
+    .await;
+
+    assert!(matches!(res, Err(ProxyError::UserExpired { .. })));
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}
+
+#[tokio::test]
+async fn client_ip_limit_failure_rolls_back_counter_exactly() {
+    let user = "ip-limit-rollback-user";
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 1).await;
+
+    let mut config = ProxyConfig::default();
+    config
+        .access
+        .user_max_tcp_conns
+        .insert(user.to_string(), 16);
+
+    let first_peer: SocketAddr = "198.51.100.203:31113".parse().unwrap();
+    let first = RunningClientHandler::acquire_user_connection_reservation_static(
+        user,
+        &config,
+        stats.clone(),
+        first_peer,
+        ip_tracker.clone(),
+    )
+    .await
+    .unwrap();
+
+    let second_peer: SocketAddr = "198.51.100.204:31114".parse().unwrap();
+    let second = RunningClientHandler::acquire_user_connection_reservation_static(
+        user,
+        &config,
+        stats.clone(),
+        second_peer,
+        ip_tracker.clone(),
+    )
+    .await;
+
+    assert!(matches!(
+        second,
+        Err(ProxyError::ConnectionLimitExceeded { .. })
+    ));
+    assert_eq!(stats.get_user_curr_connects(user), 1);
+
+    drop(first);
+    ip_tracker.drain_cleanup_queue().await;
+
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}
+
+#[tokio::test]
+async fn client_parallel_limit_checks_success_path_leaves_no_residue() {
+    let user = "parallel-check-success-user";
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 128).await;
+
+    let mut config = ProxyConfig::default();
+    config
+        .access
+        .user_max_tcp_conns
+        .insert(user.to_string(), 128);
+
+    let mut tasks = Vec::new();
+    for i in 0..128u16 {
+        let stats = Arc::clone(&stats);
+        let ip_tracker = Arc::clone(&ip_tracker);
+        let config = config.clone();
+
+        tasks.push(tokio::spawn(async move {
+            let peer = SocketAddr::new(
+                IpAddr::V4(Ipv4Addr::new(10, 10, (i / 255) as u8, (i % 255 + 1) as u8)),
+                32000 + i,
+            );
+            RunningClientHandler::check_user_limits_static(user, &config, &stats, peer, &ip_tracker)
+                .await
+        }));
+    }
+
+    for result in futures::future::join_all(tasks).await {
+        assert!(result.unwrap().is_ok());
+    }
+
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}
+
+#[tokio::test]
+async fn client_parallel_limit_checks_failure_path_leaves_no_residue() {
+    let user = "parallel-check-failure-user";
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 0).await;
+
+    let mut config = ProxyConfig::default();
+    config
+        .access
+        .user_max_tcp_conns
+        .insert(user.to_string(), 512);
+
+    let mut tasks = Vec::new();
+    for i in 0..64u16 {
+        let stats = Arc::clone(&stats);
+        let ip_tracker = Arc::clone(&ip_tracker);
+        let config = config.clone();
+
+        tasks.push(tokio::spawn(async move {
+            let peer = SocketAddr::new(
+                IpAddr::V4(Ipv4Addr::new(172, 16, 0, (i % 250 + 1) as u8)),
+                33000 + i,
+            );
+            RunningClientHandler::check_user_limits_static(user, &config, &stats, peer, &ip_tracker)
+                .await
+        }));
+    }
+
+    let mut _denied = 0usize;
+    for result in futures::future::join_all(tasks).await {
+        match result.unwrap() {
+            Ok(()) => {}
+            Err(ProxyError::ConnectionLimitExceeded { .. }) => _denied += 1,
+            Err(other) => panic!("unexpected error: {other}"),
+        }
+    }
+
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}
+
+#[tokio::test]
+async fn client_churn_mixed_success_failure_converges_to_zero_state() {
+    let user = "mixed-churn-user";
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 4).await;
+
+    let mut config = ProxyConfig::default();
+    config.access.user_max_tcp_conns.insert(user.to_string(), 8);
+
+    let mut tasks = Vec::new();
+    for i in 0..200u16 {
+        let stats = Arc::clone(&stats);
+        let ip_tracker = Arc::clone(&ip_tracker);
+        let config = config.clone();
+
+        tasks.push(tokio::spawn(async move {
+            let peer = SocketAddr::new(
+                IpAddr::V4(Ipv4Addr::new(192, 0, 2, (i % 16 + 1) as u8)),
+                34000 + (i % 32),
+            );
+            let maybe_res = RunningClientHandler::acquire_user_connection_reservation_static(
+                user, &config, stats, peer, ip_tracker,
+            )
+            .await;
+
+            if let Ok(reservation) = maybe_res {
+                tokio::time::sleep(Duration::from_millis((i % 3) as u64)).await;
+                drop(reservation);
+            }
+        }));
+    }
+
+    futures::future::join_all(tasks).await;
+    ip_tracker.drain_cleanup_queue().await;
+
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}
+
+#[tokio::test]
+async fn client_same_ip_parallel_attempts_allow_at_most_one_when_limit_is_one() {
+    let user = "same-ip-user";
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 1).await;
+
+    let mut config = ProxyConfig::default();
+    config.access.user_max_tcp_conns.insert(user.to_string(), 1);
+
+    let peer: SocketAddr = "203.0.113.44:35555".parse().unwrap();
+    let mut tasks = Vec::new();
+
+    for _ in 0..64 {
+        let stats = Arc::clone(&stats);
+        let ip_tracker = Arc::clone(&ip_tracker);
+        let config = config.clone();
+        tasks.push(tokio::spawn(async move {
+            RunningClientHandler::acquire_user_connection_reservation_static(
+                user, &config, stats, peer, ip_tracker,
+            )
+            .await
+        }));
+    }
+
+    let mut granted = 0usize;
+    let mut reservations = Vec::new();
+    for result in futures::future::join_all(tasks).await {
+        match result.unwrap() {
+            Ok(reservation) => {
+                granted += 1;
+                reservations.push(reservation);
+            }
+            Err(ProxyError::ConnectionLimitExceeded { .. }) => {}
+            Err(other) => panic!("unexpected error: {other}"),
+        }
+    }
+
+    assert_eq!(
+        granted, 1,
+        "only one reservation may be granted for same IP with limit=1"
+    );
+    drop(reservations);
+    ip_tracker.drain_cleanup_queue().await;
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}
+
+#[tokio::test]
+async fn client_repeat_acquire_release_cycles_never_accumulate_state() {
+    let user = "repeat-cycle-user";
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 32).await;
+
+    let mut config = ProxyConfig::default();
+    config
+        .access
+        .user_max_tcp_conns
+        .insert(user.to_string(), 32);
+
+    for i in 0..500u16 {
+        let peer = SocketAddr::new(
+            IpAddr::V4(Ipv4Addr::new(198, 18, (i / 250) as u8, (i % 250 + 1) as u8)),
+            36000 + (i % 128),
+        );
+        let reservation = RunningClientHandler::acquire_user_connection_reservation_static(
+            user,
+            &config,
+            stats.clone(),
+            peer,
+            ip_tracker.clone(),
+        )
+        .await
+        .unwrap();
+        drop(reservation);
+    }
+
+    ip_tracker.drain_cleanup_queue().await;
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}
+
+#[tokio::test]
+async fn client_multi_user_isolation_under_parallel_limit_exhaustion() {
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+
+    let mut config = ProxyConfig::default();
+    config.access.user_max_tcp_conns.insert("u1".to_string(), 8);
+    config.access.user_max_tcp_conns.insert("u2".to_string(), 8);
+
+    let mut tasks = Vec::new();
+    for i in 0..128u16 {
+        let stats = Arc::clone(&stats);
+        let ip_tracker = Arc::clone(&ip_tracker);
+        let config = config.clone();
+        tasks.push(tokio::spawn(async move {
+            let user = if i % 2 == 0 { "u1" } else { "u2" };
+            let peer = SocketAddr::new(
+                IpAddr::V4(Ipv4Addr::new(100, 64, (i / 64) as u8, (i % 64 + 1) as u8)),
+                37000 + i,
+            );
+            RunningClientHandler::acquire_user_connection_reservation_static(
+                user, &config, stats, peer, ip_tracker,
+            )
+            .await
+        }));
+    }
+
+    let mut u1_success = 0usize;
+    let mut u2_success = 0usize;
+    let mut reservations = Vec::new();
+    for (idx, result) in futures::future::join_all(tasks)
+        .await
+        .into_iter()
+        .enumerate()
+    {
+        let user = if idx % 2 == 0 { "u1" } else { "u2" };
+        match result.unwrap() {
+            Ok(reservation) => {
+                if user == "u1" {
+                    u1_success += 1;
+                } else {
+                    u2_success += 1;
+                }
+                reservations.push(reservation);
+            }
+            Err(ProxyError::ConnectionLimitExceeded { .. }) => {}
+            Err(other) => panic!("unexpected error: {other}"),
+        }
+    }
+
+    assert_eq!(u1_success, 8, "u1 must get exactly its own configured cap");
+    assert_eq!(u2_success, 8, "u2 must get exactly its own configured cap");
+
+    drop(reservations);
+    ip_tracker.drain_cleanup_queue().await;
+    assert_eq!(stats.get_user_curr_connects("u1"), 0);
+    assert_eq!(stats.get_user_curr_connects("u2"), 0);
+}
+
+#[tokio::test]
+async fn client_limit_recovery_after_full_rejection_wave() {
+    let user = "recover-user";
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 1).await;
+
+    let mut config = ProxyConfig::default();
+    config.access.user_max_tcp_conns.insert(user.to_string(), 1);
+
+    let first_peer: SocketAddr = "198.51.100.50:38001".parse().unwrap();
+    let reservation = RunningClientHandler::acquire_user_connection_reservation_static(
+        user,
+        &config,
+        stats.clone(),
+        first_peer,
+        ip_tracker.clone(),
+    )
+    .await
+    .unwrap();
+
+    for i in 0..64u16 {
+        let peer = SocketAddr::new(
+            IpAddr::V4(Ipv4Addr::new(198, 51, 100, (i % 60 + 1) as u8)),
+            38002 + i,
+        );
+        let denied = RunningClientHandler::acquire_user_connection_reservation_static(
+            user,
+            &config,
+            stats.clone(),
+            peer,
+            ip_tracker.clone(),
+        )
+        .await;
+        assert!(matches!(
+            denied,
+            Err(ProxyError::ConnectionLimitExceeded { .. })
+        ));
+    }
+
+    drop(reservation);
+    ip_tracker.drain_cleanup_queue().await;
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+
+    let recovery_peer: SocketAddr = "198.51.100.200:38999".parse().unwrap();
+    let recovered = RunningClientHandler::acquire_user_connection_reservation_static(
+        user,
+        &config,
+        stats.clone(),
+        recovery_peer,
+        ip_tracker.clone(),
+    )
+    .await;
+    assert!(
+        recovered.is_ok(),
+        "capacity must recover after prior holder drops"
+    );
+}
+
+#[tokio::test]
+async fn client_dual_limit_cross_product_never_leaks_on_reject() {
+    let user = "dual-limit-user";
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 2).await;
+
+    let mut config = ProxyConfig::default();
+    config.access.user_max_tcp_conns.insert(user.to_string(), 2);
+
+    let p1: SocketAddr = "203.0.113.10:39001".parse().unwrap();
+    let p2: SocketAddr = "203.0.113.11:39002".parse().unwrap();
+    let r1 = RunningClientHandler::acquire_user_connection_reservation_static(
+        user,
+        &config,
+        stats.clone(),
+        p1,
+        ip_tracker.clone(),
+    )
+    .await
+    .unwrap();
+    let r2 = RunningClientHandler::acquire_user_connection_reservation_static(
+        user,
+        &config,
+        stats.clone(),
+        p2,
+        ip_tracker.clone(),
+    )
+    .await
+    .unwrap();
+
+    for i in 0..32u16 {
+        let peer = SocketAddr::new(
+            IpAddr::V4(Ipv4Addr::new(203, 0, 113, (50 + i) as u8)),
+            39010 + i,
+        );
+        let denied = RunningClientHandler::acquire_user_connection_reservation_static(
+            user,
+            &config,
+            stats.clone(),
+            peer,
+            ip_tracker.clone(),
+        )
+        .await;
+        assert!(matches!(
+            denied,
+            Err(ProxyError::ConnectionLimitExceeded { .. })
+        ));
+    }
+
+    assert_eq!(stats.get_user_curr_connects(user), 2);
+    drop((r1, r2));
+    ip_tracker.drain_cleanup_queue().await;
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}
+
+#[tokio::test]
+async fn client_check_user_limits_concurrent_churn_no_counter_drift() {
+    let user = "check-drift-user";
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 64).await;
+
+    let mut config = ProxyConfig::default();
+    config
+        .access
+        .user_max_tcp_conns
+        .insert(user.to_string(), 64);
+
+    let mut tasks = Vec::new();
+    for i in 0..512u16 {
+        let stats = Arc::clone(&stats);
+        let ip_tracker = Arc::clone(&ip_tracker);
+        let config = config.clone();
+        tasks.push(tokio::spawn(async move {
+            let peer = SocketAddr::new(
+                IpAddr::V4(Ipv4Addr::new(172, 20, (i / 255) as u8, (i % 255 + 1) as u8)),
+                40000 + (i % 500),
+            );
+            let _ = RunningClientHandler::check_user_limits_static(
+                user,
+                &config,
+                &stats,
+                peer,
+                &ip_tracker,
+            )
+            .await;
+        }));
+    }
+
+    for task in futures::future::join_all(tasks).await {
+        task.unwrap();
+    }
+
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}

src/proxy/tests/client_beobachten_ttl_bounds_security_tests.rs

@@ -0,0 +1,126 @@
+use super::*;
+
+const BEOBACHTEN_TTL_MAX_MINUTES: u64 = 24 * 60;
+
+#[test]
+fn beobachten_ttl_exact_upper_bound_is_preserved() {
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = true;
+    config.general.beobachten_minutes = BEOBACHTEN_TTL_MAX_MINUTES;
+
+    let ttl = beobachten_ttl(&config);
+    assert_eq!(
+        ttl,
+        Duration::from_secs(BEOBACHTEN_TTL_MAX_MINUTES * 60),
+        "upper-bound TTL should remain unchanged"
+    );
+}
+
+#[test]
+fn beobachten_ttl_above_upper_bound_is_clamped() {
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = true;
+    config.general.beobachten_minutes = BEOBACHTEN_TTL_MAX_MINUTES + 1;
+
+    let ttl = beobachten_ttl(&config);
+    assert_eq!(
+        ttl,
+        Duration::from_secs(BEOBACHTEN_TTL_MAX_MINUTES * 60),
+        "TTL above security cap must be clamped"
+    );
+}
+
+#[test]
+fn beobachten_ttl_u64_max_is_clamped_fail_safe() {
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = true;
+    config.general.beobachten_minutes = u64::MAX;
+
+    let ttl = beobachten_ttl(&config);
+    assert_eq!(
+        ttl,
+        Duration::from_secs(BEOBACHTEN_TTL_MAX_MINUTES * 60),
+        "extreme configured TTL must not become multi-century retention"
+    );
+}
+
+#[test]
+fn positive_one_minute_maps_to_exact_60_seconds() {
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = true;
+    config.general.beobachten_minutes = 1;
+
+    assert_eq!(beobachten_ttl(&config), Duration::from_secs(60));
+}
+
+#[test]
+fn adversarial_boundary_triplet_behaves_deterministically() {
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = true;
+
+    config.general.beobachten_minutes = BEOBACHTEN_TTL_MAX_MINUTES - 1;
+    assert_eq!(
+        beobachten_ttl(&config),
+        Duration::from_secs((BEOBACHTEN_TTL_MAX_MINUTES - 1) * 60)
+    );
+
+    config.general.beobachten_minutes = BEOBACHTEN_TTL_MAX_MINUTES;
+    assert_eq!(
+        beobachten_ttl(&config),
+        Duration::from_secs(BEOBACHTEN_TTL_MAX_MINUTES * 60)
+    );
+
+    config.general.beobachten_minutes = BEOBACHTEN_TTL_MAX_MINUTES + 1;
+    assert_eq!(
+        beobachten_ttl(&config),
+        Duration::from_secs(BEOBACHTEN_TTL_MAX_MINUTES * 60)
+    );
+}
+
+#[test]
+fn light_fuzz_random_minutes_match_fail_safe_model() {
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = true;
+
+    let mut seed = 0xD15E_A5E5_F00D_BAADu64;
+    for _ in 0..8192 {
+        seed ^= seed << 7;
+        seed ^= seed >> 9;
+        seed ^= seed << 8;
+
+        config.general.beobachten_minutes = seed;
+        let ttl = beobachten_ttl(&config);
+        let expected = if seed == 0 {
+            Duration::from_secs(60)
+        } else {
+            Duration::from_secs(seed.min(BEOBACHTEN_TTL_MAX_MINUTES) * 60)
+        };
+
+        assert_eq!(ttl, expected, "ttl mismatch for minutes={seed}");
+        assert!(ttl <= Duration::from_secs(BEOBACHTEN_TTL_MAX_MINUTES * 60));
+    }
+}
+
+#[test]
+fn stress_monotonic_minutes_remain_monotonic_until_cap_then_flat() {
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = true;
+
+    let mut prev = Duration::from_secs(0);
+    for minutes in 0..=(BEOBACHTEN_TTL_MAX_MINUTES + 4096) {
+        config.general.beobachten_minutes = minutes;
+        let ttl = beobachten_ttl(&config);
+
+        assert!(ttl >= prev, "ttl must be non-decreasing as minutes grow");
+        assert!(ttl <= Duration::from_secs(BEOBACHTEN_TTL_MAX_MINUTES * 60));
+
+        if minutes > BEOBACHTEN_TTL_MAX_MINUTES {
+            assert_eq!(
+                ttl,
+                Duration::from_secs(BEOBACHTEN_TTL_MAX_MINUTES * 60),
+                "ttl must stay clamped once cap is exceeded"
+            );
+        }
+        prev = ttl;
+    }
+}

src/proxy/tests/client_clever_advanced_tests.rs

@@ -0,0 +1,473 @@
+use super::*;
+use crate::config::{ProxyConfig, UpstreamConfig, UpstreamType};
+use crate::protocol::constants::{MAX_TLS_PLAINTEXT_SIZE, MIN_TLS_CLIENT_HELLO_SIZE};
+use crate::stats::Stats;
+use crate::transport::UpstreamManager;
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
+use std::pin::Pin;
+use std::sync::Arc;
+use std::task::{Context, Poll};
+use std::time::Duration;
+use tokio::io::{AsyncRead, AsyncReadExt, AsyncWriteExt, ReadBuf, duplex};
+use tokio::net::TcpListener;
+
+#[test]
+fn edge_mask_reject_delay_min_greater_than_max_does_not_panic() {
+    let mut config = ProxyConfig::default();
+    config.censorship.server_hello_delay_min_ms = 5000;
+    config.censorship.server_hello_delay_max_ms = 1000;
+
+    let rt = tokio::runtime::Runtime::new().unwrap();
+    rt.block_on(async {
+        let start = std::time::Instant::now();
+        maybe_apply_mask_reject_delay(&config).await;
+        let elapsed = start.elapsed();
+
+        assert!(elapsed >= Duration::from_millis(1000));
+        assert!(elapsed < Duration::from_millis(1500));
+    });
+}
+
+#[test]
+fn edge_handshake_timeout_with_mask_grace_saturating_add_prevents_overflow() {
+    let mut config = ProxyConfig::default();
+    config.timeouts.client_handshake = u64::MAX;
+    config.censorship.mask = true;
+
+    let timeout = handshake_timeout_with_mask_grace(&config);
+    assert_eq!(timeout.as_secs(), u64::MAX);
+}
+
+#[test]
+fn edge_tls_clienthello_len_in_bounds_exact_boundaries() {
+    assert!(tls_clienthello_len_in_bounds(MIN_TLS_CLIENT_HELLO_SIZE));
+    assert!(!tls_clienthello_len_in_bounds(
+        MIN_TLS_CLIENT_HELLO_SIZE - 1
+    ));
+    assert!(tls_clienthello_len_in_bounds(MAX_TLS_PLAINTEXT_SIZE));
+    assert!(!tls_clienthello_len_in_bounds(MAX_TLS_PLAINTEXT_SIZE + 1));
+}
+
+#[test]
+fn edge_synthetic_local_addr_boundaries() {
+    assert_eq!(synthetic_local_addr(0).port(), 0);
+    assert_eq!(synthetic_local_addr(80).port(), 80);
+    assert_eq!(synthetic_local_addr(u16::MAX).port(), u16::MAX);
+}
+
+#[test]
+fn edge_beobachten_record_handshake_failure_class_stream_error_eof() {
+    let beobachten = BeobachtenStore::new();
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = true;
+    config.general.beobachten_minutes = 1;
+
+    let eof_err = ProxyError::Stream(crate::error::StreamError::UnexpectedEof);
+    let peer_ip: IpAddr = "198.51.100.100".parse().unwrap();
+
+    record_handshake_failure_class(&beobachten, &config, peer_ip, &eof_err);
+
+    let snapshot = beobachten.snapshot_text(Duration::from_secs(60));
+    assert!(snapshot.contains("[expected_64_got_0]"));
+}
+
+#[tokio::test]
+async fn adversarial_tls_handshake_timeout_during_masking_delay() {
+    let mut cfg = ProxyConfig::default();
+    cfg.general.beobachten = false;
+    cfg.timeouts.client_handshake = 1;
+    cfg.censorship.mask = true;
+    cfg.censorship.server_hello_delay_min_ms = 3000;
+    cfg.censorship.server_hello_delay_max_ms = 3000;
+
+    let config = Arc::new(cfg);
+    let stats = Arc::new(Stats::new());
+    let (server_side, mut client_side) = duplex(4096);
+
+    let handle = tokio::spawn(handle_client_stream(
+        server_side,
+        "198.51.100.1:55000".parse().unwrap(),
+        config,
+        stats.clone(),
+        Arc::new(UpstreamManager::new(
+            vec![],
+            1,
+            1,
+            1,
+            10,
+            1,
+            false,
+            stats.clone(),
+        )),
+        Arc::new(ReplayChecker::new(128, Duration::from_secs(60))),
+        Arc::new(BufferPool::new()),
+        Arc::new(SecureRandom::new()),
+        None,
+        Arc::new(RouteRuntimeController::new(RelayRouteMode::Direct)),
+        None,
+        Arc::new(UserIpTracker::new()),
+        Arc::new(BeobachtenStore::new()),
+        false,
+    ));
+
+    client_side
+        .write_all(&[0x16, 0x03, 0x01, 0xFF, 0xFF])
+        .await
+        .unwrap();
+
+    let result = tokio::time::timeout(Duration::from_secs(4), handle)
+        .await
+        .unwrap()
+        .unwrap();
+
+    assert!(matches!(result, Err(ProxyError::TgHandshakeTimeout)));
+    assert_eq!(stats.get_handshake_timeouts(), 1);
+}
+
+#[tokio::test]
+async fn blackhat_proxy_protocol_slowloris_timeout() {
+    let mut cfg = ProxyConfig::default();
+    cfg.server.proxy_protocol_header_timeout_ms = 200;
+    let config = Arc::new(cfg);
+    let stats = Arc::new(Stats::new());
+
+    let (server_side, mut client_side) = duplex(4096);
+    let handle = tokio::spawn(handle_client_stream(
+        server_side,
+        "198.51.100.2:55000".parse().unwrap(),
+        config,
+        stats.clone(),
+        Arc::new(UpstreamManager::new(
+            vec![],
+            1,
+            1,
+            1,
+            10,
+            1,
+            false,
+            stats.clone(),
+        )),
+        Arc::new(ReplayChecker::new(128, Duration::from_secs(60))),
+        Arc::new(BufferPool::new()),
+        Arc::new(SecureRandom::new()),
+        None,
+        Arc::new(RouteRuntimeController::new(RelayRouteMode::Direct)),
+        None,
+        Arc::new(UserIpTracker::new()),
+        Arc::new(BeobachtenStore::new()),
+        true,
+    ));
+
+    client_side.write_all(b"PROXY TCP4 192.").await.unwrap();
+    tokio::time::sleep(Duration::from_millis(300)).await;
+
+    let result = tokio::time::timeout(Duration::from_secs(2), handle)
+        .await
+        .unwrap()
+        .unwrap();
+
+    assert!(matches!(result, Err(ProxyError::InvalidProxyProtocol)));
+    assert_eq!(stats.get_connects_bad(), 1);
+}
+
+#[test]
+fn blackhat_ipv4_mapped_ipv6_proxy_source_bypass_attempt() {
+    let trusted = vec!["192.0.2.0/24".parse().unwrap()];
+    let peer_ip = IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc000, 0x0201));
+    assert!(!is_trusted_proxy_source(peer_ip, &trusted));
+}
+
+#[tokio::test]
+async fn negative_proxy_protocol_enabled_but_client_sends_tls_hello() {
+    let mut cfg = ProxyConfig::default();
+    cfg.server.proxy_protocol_header_timeout_ms = 500;
+    let config = Arc::new(cfg);
+    let stats = Arc::new(Stats::new());
+
+    let (server_side, mut client_side) = duplex(4096);
+    let handle = tokio::spawn(handle_client_stream(
+        server_side,
+        "198.51.100.3:55000".parse().unwrap(),
+        config,
+        stats.clone(),
+        Arc::new(UpstreamManager::new(
+            vec![],
+            1,
+            1,
+            1,
+            10,
+            1,
+            false,
+            stats.clone(),
+        )),
+        Arc::new(ReplayChecker::new(128, Duration::from_secs(60))),
+        Arc::new(BufferPool::new()),
+        Arc::new(SecureRandom::new()),
+        None,
+        Arc::new(RouteRuntimeController::new(RelayRouteMode::Direct)),
+        None,
+        Arc::new(UserIpTracker::new()),
+        Arc::new(BeobachtenStore::new()),
+        true,
+    ));
+
+    client_side
+        .write_all(&[0x16, 0x03, 0x01, 0x02, 0x00])
+        .await
+        .unwrap();
+
+    let result = tokio::time::timeout(Duration::from_secs(2), handle)
+        .await
+        .unwrap()
+        .unwrap();
+
+    assert!(matches!(result, Err(ProxyError::InvalidProxyProtocol)));
+    assert_eq!(stats.get_connects_bad(), 1);
+}
+
+#[tokio::test]
+async fn edge_client_stream_exactly_4_bytes_eof() {
+    let config = Arc::new(ProxyConfig::default());
+    let stats = Arc::new(Stats::new());
+    let beobachten = Arc::new(BeobachtenStore::new());
+
+    let (server_side, mut client_side) = duplex(4096);
+    let handle = tokio::spawn(handle_client_stream(
+        server_side,
+        "198.51.100.4:55000".parse().unwrap(),
+        config,
+        stats.clone(),
+        Arc::new(UpstreamManager::new(
+            vec![],
+            1,
+            1,
+            1,
+            10,
+            1,
+            false,
+            stats.clone(),
+        )),
+        Arc::new(ReplayChecker::new(128, Duration::from_secs(60))),
+        Arc::new(BufferPool::new()),
+        Arc::new(SecureRandom::new()),
+        None,
+        Arc::new(RouteRuntimeController::new(RelayRouteMode::Direct)),
+        None,
+        Arc::new(UserIpTracker::new()),
+        beobachten.clone(),
+        false,
+    ));
+
+    client_side
+        .write_all(&[0x16, 0x03, 0x01, 0x00])
+        .await
+        .unwrap();
+    client_side.shutdown().await.unwrap();
+
+    let _ = tokio::time::timeout(Duration::from_secs(2), handle).await;
+
+    let snapshot = beobachten.snapshot_text(Duration::from_secs(60));
+    assert!(snapshot.contains("[expected_64_got_0]"));
+}
+
+#[tokio::test]
+async fn edge_client_stream_tls_header_valid_but_body_1_byte_short_eof() {
+    let config = Arc::new(ProxyConfig::default());
+    let stats = Arc::new(Stats::new());
+
+    let (server_side, mut client_side) = duplex(4096);
+    let handle = tokio::spawn(handle_client_stream(
+        server_side,
+        "198.51.100.5:55000".parse().unwrap(),
+        config,
+        stats.clone(),
+        Arc::new(UpstreamManager::new(
+            vec![],
+            1,
+            1,
+            1,
+            10,
+            1,
+            false,
+            stats.clone(),
+        )),
+        Arc::new(ReplayChecker::new(128, Duration::from_secs(60))),
+        Arc::new(BufferPool::new()),
+        Arc::new(SecureRandom::new()),
+        None,
+        Arc::new(RouteRuntimeController::new(RelayRouteMode::Direct)),
+        None,
+        Arc::new(UserIpTracker::new()),
+        Arc::new(BeobachtenStore::new()),
+        false,
+    ));
+
+    client_side
+        .write_all(&[0x16, 0x03, 0x01, 0x00, 100])
+        .await
+        .unwrap();
+    client_side.write_all(&vec![0x41; 99]).await.unwrap();
+    client_side.shutdown().await.unwrap();
+
+    let _ = tokio::time::timeout(Duration::from_secs(2), handle).await;
+    assert_eq!(stats.get_connects_bad(), 1);
+}
+
+#[tokio::test]
+async fn integration_non_tls_modes_disabled_immediately_masks() {
+    let mut cfg = ProxyConfig::default();
+    cfg.general.modes.classic = false;
+    cfg.general.modes.secure = false;
+    cfg.censorship.mask = true;
+    let config = Arc::new(cfg);
+    let stats = Arc::new(Stats::new());
+
+    let (server_side, mut client_side) = duplex(4096);
+    let handle = tokio::spawn(handle_client_stream(
+        server_side,
+        "198.51.100.6:55000".parse().unwrap(),
+        config,
+        stats.clone(),
+        Arc::new(UpstreamManager::new(
+            vec![],
+            1,
+            1,
+            1,
+            10,
+            1,
+            false,
+            stats.clone(),
+        )),
+        Arc::new(ReplayChecker::new(128, Duration::from_secs(60))),
+        Arc::new(BufferPool::new()),
+        Arc::new(SecureRandom::new()),
+        None,
+        Arc::new(RouteRuntimeController::new(RelayRouteMode::Direct)),
+        None,
+        Arc::new(UserIpTracker::new()),
+        Arc::new(BeobachtenStore::new()),
+        false,
+    ));
+
+    client_side.write_all(b"GET / HTTP/1.1\r\n").await.unwrap();
+    let _ = tokio::time::timeout(Duration::from_secs(2), handle).await;
+    assert_eq!(stats.get_connects_bad(), 1);
+}
+
+struct YieldingReader {
+    data: Vec<u8>,
+    pos: usize,
+    yields_left: usize,
+}
+
+impl AsyncRead for YieldingReader {
+    fn poll_read(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &mut ReadBuf<'_>,
+    ) -> Poll<std::io::Result<()>> {
+        let this = self.get_mut();
+        if this.yields_left > 0 {
+            this.yields_left -= 1;
+            cx.waker().wake_by_ref();
+            return Poll::Pending;
+        }
+        if this.pos >= this.data.len() {
+            return Poll::Ready(Ok(()));
+        }
+        buf.put_slice(&this.data[this.pos..this.pos + 1]);
+        this.pos += 1;
+        this.yields_left = 2;
+        Poll::Ready(Ok(()))
+    }
+}
+
+#[tokio::test]
+async fn fuzz_read_with_progress_heavy_yielding() {
+    let expected_data = b"HEAVY_YIELD_TEST_DATA".to_vec();
+    let mut reader = YieldingReader {
+        data: expected_data.clone(),
+        pos: 0,
+        yields_left: 2,
+    };
+
+    let mut buf = vec![0u8; expected_data.len()];
+    let read_bytes = read_with_progress(&mut reader, &mut buf).await.unwrap();
+
+    assert_eq!(read_bytes, expected_data.len());
+    assert_eq!(buf, expected_data);
+}
+
+#[test]
+fn edge_wrap_tls_application_record_exactly_u16_max() {
+    let payload = vec![0u8; 65535];
+    let wrapped = wrap_tls_application_record(&payload);
+    assert_eq!(wrapped.len(), 65540);
+    assert_eq!(wrapped[0], TLS_RECORD_APPLICATION);
+    assert_eq!(&wrapped[3..5], &65535u16.to_be_bytes());
+}
+
+#[test]
+fn fuzz_wrap_tls_application_record_lengths() {
+    let lengths = [0, 1, 65534, 65535, 65536, 131070, 131071, 131072];
+    for len in lengths {
+        let payload = vec![0u8; len];
+        let wrapped = wrap_tls_application_record(&payload);
+        let expected_chunks = len.div_ceil(65535).max(1);
+        assert_eq!(wrapped.len(), len + 5 * expected_chunks);
+    }
+}
+
+#[tokio::test]
+async fn stress_user_connection_reservation_concurrent_same_ip_exhaustion() {
+    let user = "stress-same-ip-user";
+    let mut config = ProxyConfig::default();
+    config.access.user_max_tcp_conns.insert(user.to_string(), 5);
+
+    let config = Arc::new(config);
+    let stats = Arc::new(Stats::new());
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 10).await;
+
+    let peer = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(198, 51, 100, 77)), 55000);
+
+    let mut tasks = tokio::task::JoinSet::new();
+    let mut reservations = Vec::new();
+
+    for _ in 0..10 {
+        let config = config.clone();
+        let stats = stats.clone();
+        let ip_tracker = ip_tracker.clone();
+        tasks.spawn(async move {
+            RunningClientHandler::acquire_user_connection_reservation_static(
+                user, &config, stats, peer, ip_tracker,
+            )
+            .await
+        });
+    }
+
+    let mut successes = 0;
+    let mut failures = 0;
+
+    while let Some(res) = tasks.join_next().await {
+        match res.unwrap() {
+            Ok(r) => {
+                successes += 1;
+                reservations.push(r);
+            }
+            Err(_) => failures += 1,
+        }
+    }
+
+    assert_eq!(successes, 5);
+    assert_eq!(failures, 5);
+    assert_eq!(stats.get_user_curr_connects(user), 5);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 1);
+
+    for reservation in reservations {
+        reservation.release().await;
+    }
+
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}