Merge bf501a80f7 into 8d143d7bde

contrib/sni-router/README.md

 If you disable one, disable all three, otherwise the backend will fail
 to parse the connection.
 
+## Fronting loop (why `[domain-fronting]` is set explicitly)
+
+When mtg sees TLS traffic that isn't valid Telegram (a probe or a
+browser hitting your domain on `:443`), it forwards that connection to
+a real web server — "domain fronting".  By default mtg uses the
+secret's hostname as the fronting target and resolves it via DNS.
+
+In this setup that hostname resolves back to **this** server, so mtg's
+fronting dial would hit HAProxy on `:443`, HAProxy would see the SNI
+matching the secret and route the connection back to mtg → loop.
+
+The trigger is DNS, not name equality: the loop reproduces whenever
+the secret's hostname resolves to this host, regardless of how it
+relates to the domain Caddy serves (same name, subdomain, parent, or
+unrelated).  In an SNI-router deployment the secret's hostname has to
+point here for clients to reach mtg in the first place, so the loop
+is the default state unless mtg is steered away from HAProxy.
+
+To break the loop, `mtg-config.toml` pins the fronting target to
+Caddy's container address directly:
+
+```toml
+[domain-fronting]
+ip = "172.28.0.10"
+port = 8443
+proxy-protocol = true
+```
+
+The IP matches `services.web.networks.sni.ipv4_address` in
+`docker-compose.yml` (mtg's `domain-fronting.ip` only accepts a literal
+IP, not a hostname, hence the static `sni` network).  `proxy-protocol =
+true` matches Caddy's `:8443` listener wrapper so the real client IP
+still propagates to Caddy's logs.
+
+If you change Caddy's pinned IP, update both files together.  If
+`172.28.0.0/24` collides with another network on this host, change the
+subnet in `docker-compose.yml` and the IP in `mtg-config.toml` to match.
+
+> Caveat for IPv6 clients: when an IPv6 probe is fronted, mtg's
+> outbound PROXY v2 header has an IPv6 source but an IPv4 destination
+> (Caddy's pinned address).  Caddy may refuse the mixed-family header
+> and log the docker-network address instead of the real client IP for
+> that connection.  Telegram traffic is unaffected.
+
 ## ACME (Let's Encrypt) notes
 
 HAProxy passes `/.well-known/acme-challenge/` requests on `:80` to

contrib/sni-router/docker-compose.yml

     restart: unless-stopped
     sysctls:
       - net.ipv4.ip_unprivileged_port_start=80
+    networks:
+      - sni
 
   mtg:
     image: nineseconds/mtg:2
     restart: unless-stopped
     extra_hosts:
       - "host.containers.internal:host-gateway"
+    networks:
+      - sni
 
   web:
     image: caddy:alpine
     environment:
       DOMAIN: ${DOMAIN:-example.com}
     restart: unless-stopped
+    networks:
+      sni:
+        # Pinned IP so mtg's `domain-fronting.ip` (which only accepts a
+        # literal IP, not a hostname) can target Caddy directly and
+        # bypass HAProxy.  See README "Fronting loop" section.
+        ipv4_address: 172.28.0.10
 
 volumes:
   caddy_data:
+
+networks:
+  sni:
+    driver: bridge
+    ipam:
+      config:
+        - subnet: 172.28.0.0/24

contrib/sni-router/mtg-config.toml

 # real client IP.  Keep this in sync with haproxy.cfg (`send-proxy-v2`).
 proxy-protocol-listener = true
 
+# Domain-fronting target.  Without an explicit IP here, mtg resolves the
+# secret's hostname via DNS, which points back to this server -> lands
+# on HAProxy -> SNI matches the secret -> routed back to mtg -> loop.
+#
+# The IP below pins Caddy's container address (see docker-compose.yml
+# `networks.sni.ipv4_address`) so mtg dials Caddy directly, bypassing
+# HAProxy.  `proxy-protocol = true` matches Caddy's :8443 listener
+# wrapper so the real client IP propagates end-to-end.
+[domain-fronting]
+ip = "172.28.0.10"
+port = 8443
+proxy-protocol = true
+
 [defense.anti-replay]
 enabled = true
 max-size = "1mib"