feat: add per-secret connection limits (#66)

Cap concurrent connections per secret to prevent a leaked secret from
consuming all proxy resources. When the limit is reached, new TLS
connections are proxied to the configured domain (indistinguishable from
a normal website), and obfuscated2 connections are silently dropped.
Existing connections and other secrets are unaffected.

- CLI: -S secret:label:1000 (limit is optional, backward-compatible)
- Docker: SECRET_LIMIT_N env vars
- Stats: secret_<label>_limit, secret_<label>_rejected
- Prometheus: mtproxy_secret_connection_limit, mtproxy_secret_connections_rejected_total
- Multi-worker: limit divided across workers for approximate enforcement

Closes #66

Author: dvershinin

.github/workflows/test.yml

@@ -37,6 +37,9 @@ jobs:
     - name: Run Multi-Secret Tests
       run: make test-multi-secret
 
+    - name: Run Secret Limit Tests
+      run: make test-secret-limit
+
   test-arm64:
     runs-on: ubuntu-24.04-arm
     steps:

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.4.0] - 2026-03-27
+
+### Added
+- **Per-secret connection limits** — cap concurrent connections per secret to prevent a leaked or widely-shared secret from consuming all proxy resources. Syntax: `-S secret:label:1000`. Fake-TLS connections are proxied to the domain on rejection (indistinguishable from a normal website); obfuscated2 connections are silently dropped. Docker: `SECRET_LIMIT_N` env vars. New stats: `secret_<label>_limit`, `secret_<label>_rejected`, and Prometheus equivalents ([#66](https://github.com/GetPageSpeed/MTProxy/issues/66))
+
 ## [3.3.1] - 2026-03-27
 
 ### Fixed

Makefile

@@ -59,7 +59,7 @@ DEPDIRS := ${DEP} $(addprefix ${DEP}/,${PROJECTS})
 ALLDIRS := ${DEPDIRS} ${OBJDIRS}
 
 
-.PHONY:	all clean lint tests test test-tls test-multi-secret test-ip-acl docker-image-amd64 docker-run-help-amd64 docker-image-arm64 docker-run-help-arm64 fuzz fuzz-run
+.PHONY:	all clean lint tests test test-tls test-multi-secret test-secret-limit test-ip-acl docker-image-amd64 docker-run-help-amd64 docker-image-arm64 docker-run-help-arm64 fuzz fuzz-run
 
 EXELIST	:= ${EXE}/mtproto-proxy
 
@@ -198,6 +198,16 @@ test-multi-secret:
 		(echo "FAIL: No connection links found in proxy logs"; exit 1)
 	docker compose -f tests/docker-compose.multi-secret-test.yml down
 
+test-secret-limit:
+	@export MTPROXY_SECRET_1=$$(head -c 16 /dev/urandom | xxd -ps) && \
+	export MTPROXY_SECRET_2=$$(head -c 16 /dev/urandom | xxd -ps) && \
+	echo "Using secrets: $$MTPROXY_SECRET_1 (unlimited), $$MTPROXY_SECRET_2 (limit=5)" && \
+	timeout 300s docker compose -f tests/docker-compose.secret-limit-test.yml up --build --exit-code-from tester || \
+		(echo "Secret limit test timed out or failed"; \
+		docker compose -f tests/docker-compose.secret-limit-test.yml logs mtproxy; \
+		docker compose -f tests/docker-compose.secret-limit-test.yml down; exit 1)
+	docker compose -f tests/docker-compose.secret-limit-test.yml down
+
 test-ip-acl:
 	@if [ -z "$$MTPROXY_SECRET" ]; then \
 		export MTPROXY_SECRET=$$(head -c 16 /dev/urandom | xxd -ps); \

README.md

@@ -162,7 +162,7 @@ head -c 16 /dev/urandom | xxd -ps
 - `nobody` is the username. `mtproto-proxy` calls `setuid()` to drop privilegies.
 - `443` is the port, used by clients to connect to the proxy.
 - `8888` is the local port for statistics (requires `--http-stats`). Like `curl http://localhost:8888/stats`. Stats are accessible from private networks (loopback, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) but not from public IPs.
-- `<secret>` is the secret generated at step 3. Also you can set multiple secrets: `-S <secret1> -S <secret2>`. Each secret can have an optional label: `-S <secret>:family -S <secret>:friends`. Labels appear in logs and stats instead of raw secrets, making it easy to identify which secret a connection used.
+- `<secret>` is the secret generated at step 3. Also you can set multiple secrets: `-S <secret1> -S <secret2>`. Each secret can have an optional label: `-S <secret>:family -S <secret>:friends`. Labels appear in logs and stats instead of raw secrets, making it easy to identify which secret a connection used. You can also set a per-secret connection limit: `-S <secret>:family:1000` (see [Per-Secret Connection Limits](#per-secret-connection-limits)).
 - `--aes-pwd proxy-secret` points to the `proxy-secret` file downloaded at step 1, which contains the encryption key used for MTProto key exchange with Telegram DCs.
 - `proxy-secret` and `proxy-multi.conf` are obtained at steps 1 and 2.
 - `1` is the number of workers. You can increase the number of workers, if you have a powerful server.
@@ -487,6 +487,7 @@ docker run -d \
   - If both `SECRET` and `SECRET_N` are set, all are combined
   - Maximum 16 secrets (binary limit)
 - `SECRET_LABEL_1`, `SECRET_LABEL_2`, ...: Optional labels for numbered secrets (e.g. `SECRET_LABEL_1=family`). See [Secret Labels](#secret-labels)
+- `SECRET_LIMIT_1`, `SECRET_LIMIT_2`, ...: Optional per-secret connection limits (e.g. `SECRET_LIMIT_1=1000`). See [Per-Secret Connection Limits](#per-secret-connection-limits)
 - `PORT`: Port for client connections (default: 443)
 - `STATS_PORT`: Port for statistics endpoint (default: 8888)
 - `WORKERS`: Number of worker processes (default: 1)
@@ -578,6 +579,47 @@ If no label is given, secrets are auto-labeled `secret_0`, `secret_1`, etc.
 
 Label rules: max 32 characters, alphanumeric plus `_` and `-` only.
 
+#### Per-Secret Connection Limits
+
+Prevent a leaked or widely-shared secret from consuming all proxy resources by setting
+a maximum number of concurrent connections per secret:
+
+```bash
+# CLI: append :LIMIT after the label
+./mtproto-proxy ... -S cafe...90ab:family:1000 -S dead...90ef:public:200
+
+# Without a label, use an empty label field
+./mtproto-proxy ... -S cafe...90ab::500
+
+# Docker: numbered env vars
+SECRET_1=cafe1234567890abcdef1234567890ab
+SECRET_LABEL_1=family
+SECRET_LIMIT_1=1000
+SECRET_2=dead1234567890abcdef1234567890ef
+SECRET_LABEL_2=public
+SECRET_LIMIT_2=200
+
+# Docker: inline (comma-separated)
+SECRET=cafe...90ab:family:1000,dead...90ef:public:200
+```
+
+When the limit is reached, new connections using that secret are rejected:
+- **Fake-TLS (EE mode)**: rejected during the TLS handshake — the client is proxied to the
+  configured domain, so it sees a normal website (indistinguishable from a non-proxy server).
+- **Obfuscated2 (DD mode)**: the connection is silently dropped.
+
+Existing connections are not affected. Other secrets continue operating normally.
+
+**Multi-worker note**: with `-M N` workers, each worker enforces `limit / N` independently.
+For single-worker mode (`-M 0` or `-M 1`), the limit is exact.
+
+Limits appear in stats and Prometheus metrics:
+- **Stats** (`/stats`): `secret_family_limit	1000`, `secret_family_rejected	42`
+- **Prometheus** (`/metrics`): `mtproxy_secret_connection_limit{secret="family"} 1000`,
+  `mtproxy_secret_connections_rejected_total{secret="family"} 42`
+
+Secrets without a limit are unlimited (the default, backward-compatible behavior).
+
 And reference it in your `docker-compose.yml`:
 ```yaml
 services:

mtproto/mtproto-proxy.c

@@ -197,6 +197,7 @@ struct ext_connection_ref {
 
 long long ext_connections, ext_connections_created;
 long long per_secret_connections[16], per_secret_connections_created[16];
+long long per_secret_connections_rejected[16];
 
 struct ext_connection_ref OutExtConnections[EXT_CONN_TABLE_SIZE];
 struct ext_connection *InExtConnectionHash[EXT_CONN_HASH_SIZE];
@@ -414,6 +415,7 @@ struct worker_stats {
 
   long long per_secret_connections[16];
   long long per_secret_connections_created[16];
+  long long per_secret_connections_rejected[16];
 };
 
 struct worker_stats *WStats, SumStats;
@@ -473,6 +475,7 @@ static void update_local_stats_copy (struct worker_stats *S) {
   { int _i; for (_i = 0; _i < 16; _i++) {
     UPD (per_secret_connections[_i]);
     UPD (per_secret_connections_created[_i]);
+    UPD (per_secret_connections_rejected[_i]);
   }}
 #undef UPD
   __sync_synchronize();
@@ -553,6 +556,7 @@ static inline void add_stats (struct worker_stats *W) {
   { int _i; for (_i = 0; _i < 16; _i++) {
     UPD (per_secret_connections[_i]);
     UPD (per_secret_connections_created[_i]);
+    UPD (per_secret_connections_rejected[_i]);
   }}
 #undef UPD
 }
@@ -753,9 +757,15 @@ void mtfront_prepare_stats (stats_buffer_t *sb) {
     for (_i = 0; _i < _sc; _i++) {
       sb_printf (sb,
 	       "secret_%s_connections\t%lld\n"
-	       "secret_%s_connections_created\t%lld\n",
+	       "secret_%s_connections_created\t%lld\n"
+	       "secret_%s_rejected\t%lld\n",
 	       tcp_rpcs_get_ext_secret_label (_i), S(per_secret_connections[_i]),
-	       tcp_rpcs_get_ext_secret_label (_i), S(per_secret_connections_created[_i]));
+	       tcp_rpcs_get_ext_secret_label (_i), S(per_secret_connections_created[_i]),
+	       tcp_rpcs_get_ext_secret_label (_i), S(per_secret_connections_rejected[_i]));
+      int _lim = tcp_rpcs_get_ext_secret_limit (_i);
+      if (_lim > 0) {
+        sb_printf (sb, "secret_%s_limit\t%d\n", tcp_rpcs_get_ext_secret_label (_i), _lim);
+      }
     }
   }
 #undef S
@@ -928,6 +938,20 @@ void mtfront_prepare_prometheus_stats (stats_buffer_t *sb) {
         sb_printf (sb, "mtproxy_secret_connections_created_total{secret=\"%s\"} %lld\n",
 	         tcp_rpcs_get_ext_secret_label (_i), S(per_secret_connections_created[_i]));
       }
+      sb_printf (sb,
+	       "# HELP mtproxy_secret_connection_limit Configured connection limit per secret (0=unlimited).\n"
+	       "# TYPE mtproxy_secret_connection_limit gauge\n");
+      for (_i = 0; _i < _sc; _i++) {
+        sb_printf (sb, "mtproxy_secret_connection_limit{secret=\"%s\"} %d\n",
+	         tcp_rpcs_get_ext_secret_label (_i), tcp_rpcs_get_ext_secret_limit (_i));
+      }
+      sb_printf (sb,
+	       "# HELP mtproxy_secret_connections_rejected_total Connections rejected due to per-secret limit.\n"
+	       "# TYPE mtproxy_secret_connections_rejected_total counter\n");
+      for (_i = 0; _i < _sc; _i++) {
+        sb_printf (sb, "mtproxy_secret_connections_rejected_total{secret=\"%s\"} %lld\n",
+	         tcp_rpcs_get_ext_secret_label (_i), S(per_secret_connections_rejected[_i]));
+      }
     }
   }
 
@@ -2447,12 +2471,30 @@ int f_parse_option (int val) {
     {
       char *label = NULL;
       int hex_len;
+      int conn_limit = 0;
 
       if (val == 'S') {
         char *colon = strchr (optarg, ':');
         if (colon) {
           hex_len = colon - optarg;
           label = colon + 1;
+
+          /* Look for optional :LIMIT after label */
+          char *colon2 = strchr (label, ':');
+          if (colon2) {
+            *colon2 = '\0';
+            char *limit_str = colon2 + 1;
+            if (*limit_str) {
+              char *endp;
+              long lv = strtol (limit_str, &endp, 10);
+              if (*endp || lv < 1) {
+                kprintf ("Invalid connection limit '%s' (must be a positive integer)\n", limit_str);
+                usage ();
+              }
+              conn_limit = (int)lv;
+            }
+          }
+
           if (strlen (label) == 0) {
             label = NULL;
           } else if (strlen (label) > EXT_SECRET_LABEL_MAX) {
@@ -2499,7 +2541,7 @@ int f_parse_option (int val) {
         }
       }
       if (val == 'S') {
-	tcp_rpcs_set_ext_secret (secret, label);
+	tcp_rpcs_set_ext_secret (secret, label, conn_limit);
 	secret_count++;
       } else {
 	memcpy (proxy_tag, secret, sizeof (proxy_tag));
@@ -2527,7 +2569,7 @@ int f_parse_option (int val) {
 
 void mtfront_prepare_parse_options (void) {
   parse_option ("http-stats", no_argument, 0, 2000, "allow http server to answer on stats queries");
-  parse_option ("mtproto-secret", required_argument, 0, 'S', "16-byte secret in hex, optionally followed by :LABEL (e.g. -S abcdef01234567890abcdef012345678:myapp)");
+  parse_option ("mtproto-secret", required_argument, 0, 'S', "16-byte secret in hex, optionally :LABEL:LIMIT (e.g. -S abcdef01234567890abcdef012345678:myapp:1000)");
   parse_option ("proxy-tag", required_argument, 0, 'P', "16-byte proxy tag in hex mode to be passed along with all forwarded queries");
   parse_option ("domain", required_argument, 0, 'D', "adds allowed domain or host:port for TLS-transport mode, disables other transports; can be specified more than once");
   parse_option ("max-special-connections", required_argument, 0, 'C', "sets maximal number of accepted client connections per worker");

net/net-tcp-rpc-ext-server.c

@@ -176,8 +176,10 @@ int tcp_proxy_pass_write_packet (connection_job_t C, struct raw_message *raw) {
  */
 
 extern int direct_mode;
+extern int workers;
 extern long long direct_dc_connections_created, direct_dc_connections_active;
 extern long long per_secret_connections[16], per_secret_connections_created[16];
+extern long long per_secret_connections_rejected[16];
 
 static int tcp_direct_client_parse_execute (connection_job_t C);
 static int tcp_direct_dc_parse_execute (connection_job_t C);
@@ -466,8 +468,9 @@ static unsigned char ext_secret[16][16];
 static int ext_secret_cnt = 0;
 static int ext_rand_pad_only = 0;
 static char ext_secret_label[16][EXT_SECRET_LABEL_MAX + 1];
+static int ext_secret_limit[16];  /* 0 = unlimited */
 
-void tcp_rpcs_set_ext_secret (unsigned char secret[16], const char *label) {
+void tcp_rpcs_set_ext_secret (unsigned char secret[16], const char *label, int limit) {
   assert (ext_secret_cnt < 16);
   int idx = ext_secret_cnt++;
   memcpy (ext_secret[idx], secret, 16);
@@ -476,18 +479,36 @@ void tcp_rpcs_set_ext_secret (unsigned char secret[16], const char *label) {
   } else {
     snprintf (ext_secret_label[idx], sizeof (ext_secret_label[idx]), "secret_%d", idx);
   }
-  vkprintf (0, "Added secret #%d label=[%s]\n", idx, ext_secret_label[idx]);
+  ext_secret_limit[idx] = limit;
+  if (limit > 0) {
+    vkprintf (0, "Added secret #%d label=[%s] limit=%d\n", idx, ext_secret_label[idx], limit);
+  } else {
+    vkprintf (0, "Added secret #%d label=[%s] (unlimited)\n", idx, ext_secret_label[idx]);
+  }
 }
 
 const char *tcp_rpcs_get_ext_secret_label (int index) {
   assert (index >= 0 && index < ext_secret_cnt);
   return ext_secret_label[index];
 }
 
+int tcp_rpcs_get_ext_secret_limit (int index) {
+  assert (index >= 0 && index < ext_secret_cnt);
+  return ext_secret_limit[index];
+}
+
 int tcp_rpcs_get_ext_secret_count (void) {
   return ext_secret_cnt;
 }
 
+static int secret_over_limit (int secret_id) {
+  int limit = ext_secret_limit[secret_id];
+  if (limit <= 0) { return 0; }
+  int eff = workers > 1 ? limit / workers : limit;
+  if (eff < 1) { eff = 1; }
+  return per_secret_connections[secret_id] >= eff;
+}
+
 void tcp_rpcs_set_ext_rand_pad_only(int set) {
   ext_rand_pad_only = set;
 }
@@ -1457,6 +1478,12 @@ int tcp_rpcs_compact_parse_execute (connection_job_t C) {
         D->extra_int2 = secret_id + 1;
         vkprintf (1, "TLS handshake matched secret [%s] from %s:%d\n", ext_secret_label[secret_id], show_remote_ip (C), c->remote_port);
 
+        if (secret_over_limit (secret_id)) {
+          per_secret_connections_rejected[secret_id]++;
+          vkprintf (1, "TLS connection rejected: secret [%s] at limit %d from %s:%d\n", ext_secret_label[secret_id], ext_secret_limit[secret_id], show_remote_ip (C), c->remote_port);
+          RETURN_TLS_ERROR(info);
+        }
+
         unsigned char cipher_suite_id;
         if (tls_parse_client_hello_ciphers (client_hello, read_len, &cipher_suite_id) < 0) {
           vkprintf (1, "Can't find supported cipher suite\n");
@@ -1626,6 +1653,17 @@ int tcp_rpcs_compact_parse_execute (connection_job_t C) {
       }
 
       if (ok) {
+        /* Check per-secret connection limit (non-TLS; TLS checked during handshake) */
+        if (!(c->flags & C_IS_TLS)) {
+          int _sid = D->extra_int2;
+          if (_sid > 0 && _sid <= 16 && secret_over_limit (_sid - 1)) {
+            per_secret_connections_rejected[_sid - 1]++;
+            vkprintf (1, "connection rejected: secret [%s] at limit %d from %s:%d\n", ext_secret_label[_sid - 1], ext_secret_limit[_sid - 1], show_remote_ip (C), c->remote_port);
+            fail_connection (C, -1);
+            return 0;
+          }
+        }
+
         /* Activate DRS for TLS connections */
         if (c->flags & C_IS_TLS) {
           static int drs_types_checked;

net/net-tcp-rpc-ext-server.h

@@ -31,9 +31,10 @@ int tcp_rpcs_compact_parse_execute (connection_job_t c);
 
 #define EXT_SECRET_LABEL_MAX 32
 
-void tcp_rpcs_set_ext_secret(unsigned char secret[16], const char *label);
+void tcp_rpcs_set_ext_secret(unsigned char secret[16], const char *label, int limit);
 void tcp_rpcs_set_ext_rand_pad_only(int set);
 const char *tcp_rpcs_get_ext_secret_label(int index);
+int tcp_rpcs_get_ext_secret_limit(int index);
 int tcp_rpcs_get_ext_secret_count(void);
 
 void tcp_rpc_add_proxy_domain (const char *domain);

start.sh

@@ -65,11 +65,16 @@ while [ "$_i" -le 16 ]; do
     if [ -n "$_val" ]; then
         eval "_lbl=\${SECRET_LABEL_${_i}:-}"
         _lbl=$(printf '%s' "$_lbl" | tr -d '[:space:]')
-        if [ -n "$_lbl" ]; then
-            set -- "$@" "${_val}:${_lbl}"
-        else
-            set -- "$@" "$_val"
+        eval "_lim=\${SECRET_LIMIT_${_i}:-}"
+        _lim=$(printf '%s' "$_lim" | tr -d '[:space:]')
+        _suffix=""
+        if [ -n "$_lbl" ] || [ -n "$_lim" ]; then
+            _suffix=":${_lbl}"
+        fi
+        if [ -n "$_lim" ]; then
+            _suffix="${_suffix}:${_lim}"
         fi
+        set -- "$@" "${_val}${_suffix}"
     fi
     _i=$((_i + 1))
 done
@@ -164,9 +169,9 @@ echo ""
 echo "===== Connection Links ====="
 _host="${EXTERNAL_IP:-<YOUR_SERVER_IP>}"
 for _s in "$@"; do
-    # Strip :LABEL suffix for URLs (labels are for the proxy, not for clients)
+    # Strip :LABEL:LIMIT suffix for URLs (labels/limits are for the proxy, not for clients)
     _secret_hex=$(printf '%s' "$_s" | cut -d: -f1)
-    _label=$(printf '%s' "$_s" | grep -o ':.*' | cut -c2- || true)
+    _label=$(printf '%s' "$_s" | cut -d: -f2 -s)
     if [ -n "$EE_DOMAIN" ]; then
         _domain_only=$(printf '%s' "$EE_DOMAIN" | cut -d: -f1)
         _domain_hex=$(printf '%s' "$_domain_only" | od -An -tx1 | tr -d ' \n')

tests/Dockerfile

@@ -3,6 +3,6 @@ WORKDIR /app
 COPY requirements.txt .
 RUN pip install -r requirements.txt
 ENV PYTHONUNBUFFERED=1
-COPY test_proxy.py test_tls_e2e.py test_multi_secret_tls.py test_ip_acl.py test_direct_e2e.py ./
+COPY test_proxy.py test_tls_e2e.py test_multi_secret_tls.py test_ip_acl.py test_direct_e2e.py test_secret_limit.py ./
 CMD ["python", "test_proxy.py"]