Merge remote-tracking branch 'origin/stable' into v2

Author: 9seconds

.github/workflows/ci.yaml

@@ -48,6 +48,16 @@ jobs:
       - uses: jdx/mise-action@v3
         name: Install mise
 
+      - name: Cache Go modules and build
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/go/pkg/mod
+            ~/.cache/go-build
+          key: ${{ runner.os }}-go-${{ hashFiles('go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
       - name: Run tests
         run: mise tasks run covtest
 
@@ -69,6 +79,16 @@ jobs:
       - uses: jdx/mise-action@v3
         name: Install mise
 
+      - name: Cache Go modules and build
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/go/pkg/mod
+            ~/.cache/go-build
+          key: ${{ runner.os }}-go-${{ hashFiles('go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
       - name: Run fuzzing
         run: mise tasks run 'test:fuzz:*'
 
@@ -86,6 +106,16 @@ jobs:
       - uses: jdx/mise-action@v3
         name: Install mise
 
+      - name: Cache Go modules and build
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/go/pkg/mod
+            ~/.cache/go-build
+          key: ${{ runner.os }}-go-${{ hashFiles('go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
       - name: Run linter
         run: mise tasks run lint
 
@@ -123,14 +153,6 @@ jobs:
       - name: Setup BuildX
         uses: docker/setup-buildx-action@v3
 
-      - name: Setup cache
-        uses: actions/cache@v5
-        with:
-          path: /tmp/buildx-cache
-          key: ${{ runner.os }}-buildx-${{ github.sha }}
-          restore-keys: |
-            ${{ runner.os }}-buildx-
-
       - name: Login to DockerHub
         if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
@@ -147,13 +169,13 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build and push
-        uses: docker/build-push-action@v2
+        uses: docker/build-push-action@v6
         with:
           pull: true
           context: .
           platforms: linux/amd64,linux/arm64,linux/386,linux/arm/v7,linux/arm/v6
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=local,src=/tmp/buildx-cache
-          cache-to: type=local,dest=/tmp/buildx-cache
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/govulncheck.yml

@@ -35,6 +35,7 @@ jobs:
       uses: actions/setup-go@v6
       with:
         go-version-file: go.mod
+        cache: true
 
     - name: Check for vulnerabilities
       run: |

.goreleaser.yml

@@ -54,6 +54,8 @@ archives:
       - LICENSE
       - README.md
       - SECURITY.md
+      - BEST_PRACTICES.md
+      - example.config.toml
 
 gomod:
   proxy: true

.mise.toml

@@ -33,11 +33,11 @@ run = "govulncheck ./..."
 
 [tasks.test]
 description = "Run tests"
-run = "go test -v ./..."
+run = "go test -v -race ./..."
 
 [tasks.covtest]
 description = "Run tests with code coverage"
-run = "go test -coverprofile=coverage.txt -covermode=atomic -parallel 2 -race -v ./..."
+run = "go test -coverprofile=coverage.txt -covermode=atomic -count=2 -race -v ./..."
 
 [tasks.test-all]
 description = "Run all tests"
@@ -48,7 +48,7 @@ depends = [
 
 [tasks."test:fuzz:client-hello"]
 description = "Run fuzzy test for ClientHello"
-run = "go test -v {{ vars.fuzzflags }} -fuzz=FuzzClientHello ./mtglib/internal/faketls"
+run = "go test -v {{ vars.fuzzflags }} -fuzz=FuzzReadClientHello ./mtglib/internal/tls/fake"
 
 [tasks."test:fuzz:client-handshake"]
 description = "Run fuzzy test for ClientHandshake"

BEST_PRACTICES.md

@@ -0,0 +1,55 @@
+# Best practices
+
+This is unfortunate, but since 2018 many things were changed. Most of them
+became way worse. Previous iterations of censorship systems were very dumb,
+DPI were primitive and filtered very obvious things. Nowadays they are
+way more intelligent and it is very naive to treat them frivolously.
+
+In 2026 is not enough to pretend that your mtg installation is a Microsoft
+website that sits in Amsterdam Digital Ocean location. Now your installation
+has to be a website that is mtg in disguise. Yes, it requires a bit more effort
+but this effort is probably less than rotating proxies each other day.
+
+mtproto traffic, even with FakeTLS, has its specifics that are probably
+very well known by DPI systems. These specifics are not something unique but
+could mark an IP address as suspicious. Now let's think:
+
+1. You have a proxy in Amsterdam Digital Ocean that tells it is microsoft.com
+   how hard could it be to find out that this is probably fake? 1 or probably 2
+   DNS queries for `microsoft.com`? In case of some CDN, there are ECS-powered
+   resolvers that are very capable to return results from POV of some subnets.
+   If censor sees no relevant results, will they be afraid to block IP?
+2. You have a proxy in Amsterdam Digital Ocean that tells it is a website from
+   the same public subnet. But not the same. Would it be hard to make these DNS
+   queries and ban IP?
+
+The correct way of having this proxy is following:
+
+1. Register a domain name
+2. Get some VPS, probably in your domestic location
+3. Set that domain name from a step 1 to IP address of that VPS
+4. Generate a couple of HTML pages by LLMs or even copy them from elsewhere
+5. Set some webserver and issue TLS certificates with Let's Encrypt or any other
+   name
+6. Set mtg before this webserver.
+7. Use sing-box or anything like that to provide local socks5 interface and
+   have VPNized uplinks
+8. Set up mtg to use socks5 from a 7 step.
+
+In that case you will get a match of DNS and SNI in requests. As a side effect,
+your proxy will work with XTLS and its friends: XTLS in sniff mode ignores
+IP address a client wants to connect to. Instead, it reads SNI and connect
+to resolved address: a clever idea if user does not have a trustworthy DNS
+set up.
+
+Yes, this is much longer that usual technique, and requires more effort. But
+this is could probably be very well automated to some reasonable extent.
+
+Unfortunately, this is a best practice right now.
+
+Do not also forget about other implementation, like
+[telemt](https://github.com/telemt/telemt). Try everything. Use VPNs. It does
+not really matter which project you are going to use as long it helps you to
+stay connected.
+
+_March 2026._

Dockerfile

@@ -5,14 +5,19 @@ FROM golang:1.26-alpine AS build
 
 ENV CGO_ENABLED=0
 
-RUN set -x \
-  && apk --no-cache --update add \
-    bash \
-    ca-certificates \
-    git
+RUN --mount=type=cache,target=/var/cache/apk \
+    set -x \
+    && apk --update add \
+      bash \
+      ca-certificates \
+      git
+
+COPY go.mod go.sum /app/
+WORKDIR /app
+
+RUN go mod download
 
 COPY . /app
-WORKDIR /app
 
 RUN set -x \
   && version="$(git describe --exact-match HEAD 2>/dev/null || git describe --tags --always)" \

README.md

@@ -38,6 +38,33 @@ goal: to give a possibility to connect to Telegram in a restricted,
 censored environment. But it does it slightly differently in details
 that probably matter.
 
+* **Domain fronting**
+
+  For years mtg supports domain fronting. This technique means that it fallbacks
+  to accessing a real website in case if request fails. It could fail by many
+  reasons: anti-replay protection, accidental access to the webserver or
+  stale request. Anyway, if mtg rejects this request, it does not break a
+  connection. It connects to the websites and replicates everything that client
+  has sent, and simply proxies it back as is. Users will see a response from
+  the real website, _byte-to-byte identical_ to the response of the real netloc.
+
+* **Doppelganger**
+
+  mtg also is a doppelganger of the website it fronts. Sure, with domain fronting
+  users will see replies of the real website in case if something will go wrong.
+  But what about such cases when _everything is fine_?
+
+  In that case mtg mimics TLS connection statistical characteristics as close as
+  possible. Different application have different statistics of their patterns.
+  Big CDN steadily pumping the data, small websites burst with short easily
+  compressiable chunks of traffic.
+
+  mtg artificially emulates those delays to be statistically indistinguishable
+  from the real website even if it covers connection of the very specific app.
+  It also follows 2 most common patterns of traffic chunking, so censors
+  will have to put more resources to find out that we have Telegram here
+  but not a hookah webshop served by nginx.
+
 * **Resource-efficient**
 
   It has to be resource-efficient. It does not mean that you will see
@@ -93,6 +120,8 @@ that probably matter.
   software (written in Golang) with a minimum effort + you can replace
   some parts with those you want.
 
+Please also to read about [best practices](https://github.com/9seconds/mtg/blob/master/BEST_PRACTICES.md).
+
 ### Version 2
 
 If you use version 1.x before, you are probably noticed some major
@@ -398,6 +427,55 @@ or if you are using docker:
 $ docker exec mtg-proxy /mtg access /config.toml
 ```
 
+## Doppelganger
+
+mtg can mimic real websites, please take a look at relevant section in example
+config file.
+
+mtg comes with some very good precollected statistics coming from
+[ok.ru](https://ok.ru/). It does not mean that you have to cover yourself
+by pretending that mtg is _ok.ru_. **Do not do that: ok.ru comes from very specific
+ASNs, but not from VPS providers you are going to use.** What I want to say
+is that defaults are very good enough to use as is because ok.ru for public
+pages has a very generic profile of TLS packets delay.
+
+But for better results it is recommended to teach mtg about the website you
+will use as a domain front. In order to do that, you need to specify URLs
+from this website. Just go to it, open WebDeveloper console and pick up
+random URLs. For better results they have to be **from the same domain name
+you are going to use as a disguise** but serve light and heavy content: pages,
+images etc. Do not use many, 2-3 will probably work.
+
+mtg will crawl these pages periodically, accumulating statistics and
+using it as you go.
+
+```toml
+[defense.doppelganger]
+urls = [
+  "https://lalala.com/index.html",
+  "https://lalala.com/contacts.html",
+]
+```
+
+This is not very necessary. Keep in mind these rules:
+
+1. If you are not sure what is this all about, do nothing. Defaults are good.
+2. All URLs must be HTTPS
+3. All URLs should be from the same domain name (but this is not a rule)
+4. Do not use a lot of pages. Use _different_ pages. mtg will start using this
+   statistics when it will accumulate enough anyway.
+5. These URLs should be directly accessible from mtg without proxies whatsoever
+6. Do not create huge raids. mtg will repeatedly crawl in raids, making N repeats.
+   Do not use high N, you do not want to be noticeable.
+7. It makes no sense to have small delay between raids. Usually webservers
+   do not update their TLS settings each hour.
+8. If you have some specific knowledge if webserver is using
+   [TLS Dynamic Record Sizing](https://blog.cloudflare.com/optimizing-tls-over-tcp-to-reduce-latency/), you
+   can use a very specific setting. This are Cloudflare, Go standard webservers,
+   [caddy](https://caddyserver.com/) and [H2O](https://h2o.examp1e.net/). If so,
+   you can enable `drs` setting.
+9. **If you are not sure, touch nothing!**
+
 ## Metrics
 
 Out of the box, mtg works with

example.config.toml

@@ -206,6 +206,66 @@ tcp = "5s"
 http = "10s"
 idle = "1m"
 
+# mtg has to mimic real websites. It does not mean domain fronting, it also
+# means that traffic characteristics should be similar to real world traffic.
+# websites and applications behave differently, their traffic patterns are also
+# different. Applications do bursts of RPC-style messages (or JSON communication,
+# does not really matter), while websites pump heavy content in HTTP2 streams
+#
+# It means that statistically there is a different between traffic shape:
+# delays between packets are also different.
+# In order to avoid censorship detection based on these patterns, there is a
+# mtg subsystem called "Doppelganger" that aims to mimic website statistics
+# as close as it could.
+#
+# Delays between TLS packets are not constant. There are many factors
+# that come in play. Application should generate some response, it could
+# send some headers first and stream content with chunked encoding. So
+# some first packets could come as soon as possible, with some delays
+# after first ones. Such phenomenon is described by different statistic
+# distribution. There are 2 distribution that describe it: lognormal
+# distribution and Weibul distribution. Lognormal is all about steady streams
+# of heavy content like a video. Weibul is great about short bursts like
+# user who requested a static page an a couple of images.
+[defense.doppelganger]
+# This is a list of URLs that would be crawled by mtg to approximate delay
+# statistics. They MUST be HTTPS urls.
+#
+# You can come to the website and collect different URLs, with light and
+# heavy content. We recommend to search for CDNs.
+urls = [
+    # "https://st-ok.cdn-vk.ru/res/react/vendor/clsx-2.1.1-amd.js"
+]
+# A collection is done in raids. Each raid makes this number of requests to
+# each URL in this list. Do not use a huge number, 10 is probably ok.
+repeats-per-raid = 10
+# This is a duration between each raid. It makes no sense to have a small number
+# here as you would start to make a noticeable activity. Usually traffic patterns
+# do not change a lot, so do not expect different results if you request
+# each 10 minutes.
+raid-each = "6h"
+# This enables dynamic tls record sizing.
+#
+# Some modern stacks and platforms start to use the technique that is called
+# DRS. They start with small TLS packets and ramp up eventually. First packets
+# are usually about MTU size, after that we get 4k and eventually max size.
+# This is done with a good intention: to minimize a time to the first byte,
+# so application could start doing something with the data right after first
+# RTT.
+#
+# Apparently, about 90% of application do not employ this technique, they use
+# max size always: nginx, apache, java stuff. But Golang tools, angie and
+# some specific patches activate this technique.
+#
+# In order to mimic a real website we need to know something about software
+# it uses. Usually nobody cares: openssl does 16384, Python does it, nginx
+# does it. So this setting is disabled by default.
+#
+#      https://blog.cloudflare.com/optimizing-tls-over-tcp-to-reduce-latency/
+#      https://aws.github.io/s2n-tls/usage-guide/ch08-record-sizes.html
+#      https://github.com/cloudflare/sslconfig/blob/master/patches/nginx__dynamic_tls_records.patch
+drs = false
+
 # Some countries do active probing on Telegram connections. This technique
 # allows to protect from such effort.
 #