feat: add secret labels and per-secret metrics (#60)

Associate human-readable labels with configured secrets and surface
per-secret connection metrics in logs and stats endpoints.

- `-S SECRET:LABEL` syntax (backward compatible, label is optional)
- Per-secret active/total connection counters in /stats and /metrics
- Matched secret label logged at handshake (no raw secrets in logs)
- Docker: SECRET_LABEL_N env vars and inline label support
- Works for both ME relay and direct-to-DC modes

Closes #60

Author: dvershinin

README.md

@@ -33,7 +33,7 @@ The table below compares it with the original and the two main third-party alter
 | Fake-TLS (EE mode) | Yes | Yes | Yes | Yes |
 | Direct-to-DC mode | No | Yes | Yes | Yes |
 | Ad proxy tag | Yes | Yes | No | Yes |
-| Multiple secrets | Yes | Yes (up to 16) | No | Yes |
+| Multiple secrets | Yes | Yes (up to 16, with labels) | No | Yes |
 | Anti-replay protection | Weak | Yes | Yes | Partial |
 | Constant-time HMAC | No | Yes | — | Yes |
 | ***Censorship resistance*** | | | | |
@@ -143,7 +143,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>`.
+- `<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.
 - `--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.
@@ -463,9 +463,11 @@ docker run -d \
 - `SECRET`: Proxy secret(s) — 32 hex characters each (auto-generated if not provided)
   - Single: `SECRET=cafe1234567890abcdef1234567890ab`
   - Multiple (comma-separated): `SECRET=secret1,secret2,secret3`
+  - With labels: `SECRET=hex1:family,hex2:friends` (see [Secret Labels](#secret-labels))
   - Multiple (numbered): `SECRET_1=aabb...`, `SECRET_2=ccdd...` (up to `SECRET_16`)
   - 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)
 - `PORT`: Port for client connections (default: 443)
 - `STATS_PORT`: Port for statistics endpoint (default: 8888)
 - `WORKERS`: Number of worker processes (default: 1)
@@ -489,7 +491,7 @@ curl http://localhost:8888/stats
 curl http://localhost:8888/metrics
 ```
 
-Returns metrics in [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/), ready for scraping. Available on the same `--http-stats` port, restricted to private networks.
+Returns metrics in [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/), ready for scraping. Available on the same `--http-stats` port, restricted to private networks. Includes per-secret connection metrics when [secret labels](#secret-labels) are configured.
 
 ### Using Docker Compose
 
@@ -529,6 +531,34 @@ SECRET_2=friends_secret_hex
 SECRET_3=public_secret_hex
 ```
 
+#### Secret Labels
+
+Labels let you identify which secret a connection is using — useful for revoking leaked
+secrets or monitoring per-group traffic:
+
+```bash
+# Inline labels (CLI)
+./mtproto-proxy ... -S cafe1234567890abcdef1234567890ab:family -S dead1234567890abcdef1234567890ef:friends
+
+# Inline labels (Docker)
+SECRET=cafe1234567890abcdef1234567890ab:family,dead1234567890abcdef1234567890ef:friends
+
+# Separate label env vars (Docker)
+SECRET_1=cafe1234567890abcdef1234567890ab
+SECRET_LABEL_1=family
+SECRET_2=dead1234567890abcdef1234567890ef
+SECRET_LABEL_2=friends
+```
+
+Labels appear in:
+- **Logs**: `TLS handshake matched secret [family] from 1.2.3.4:12345`
+- **Prometheus** (`/metrics`): `mtproxy_secret_connections{secret="family"} 3`
+- **Stats** (`/stats`): `secret_family_connections	3`
+
+If no label is given, secrets are auto-labeled `secret_0`, `secret_1`, etc.
+
+Label rules: max 32 characters, alphanumeric plus `_` and `-` only.
+
 And reference it in your `docker-compose.yml`:
 ```yaml
 services:

mtproto/mtproto-proxy.c

@@ -196,6 +196,7 @@ struct ext_connection_ref {
 };
 
 long long ext_connections, ext_connections_created;
+long long per_secret_connections[16], per_secret_connections_created[16];
 
 struct ext_connection_ref OutExtConnections[EXT_CONN_TABLE_SIZE];
 struct ext_connection *InExtConnectionHash[EXT_CONN_HASH_SIZE];
@@ -410,6 +411,9 @@ struct worker_stats {
 
   long long ext_connections, ext_connections_created;
   long long http_queries, http_bad_headers;
+
+  long long per_secret_connections[16];
+  long long per_secret_connections_created[16];
 };
 
 struct worker_stats *WStats, SumStats;
@@ -464,8 +468,12 @@ static void update_local_stats_copy (struct worker_stats *S) {
   UPD (connections_failed_flood);
   UPD (ext_connections); 
   UPD (ext_connections_created); 
-  UPD (http_queries); 
+  UPD (http_queries);
   UPD (http_bad_headers);
+  { int _i; for (_i = 0; _i < 16; _i++) {
+    UPD (per_secret_connections[_i]);
+    UPD (per_secret_connections_created[_i]);
+  }}
 #undef UPD
   __sync_synchronize();
   S->cnt++;
@@ -538,10 +546,14 @@ static inline void add_stats (struct worker_stats *W) {
   UPD (direct_dc_connections_active);
   UPD (connections_failed_lru);
   UPD (connections_failed_flood);
-  UPD (ext_connections); 
-  UPD (ext_connections_created); 
-  UPD (http_queries); 
+  UPD (ext_connections);
+  UPD (ext_connections_created);
+  UPD (http_queries);
   UPD (http_bad_headers);
+  { int _i; for (_i = 0; _i < 16; _i++) {
+    UPD (per_secret_connections[_i]);
+    UPD (per_secret_connections_created[_i]);
+  }}
 #undef UPD
 }
 
@@ -735,6 +747,17 @@ void mtfront_prepare_stats (stats_buffer_t *sb) {
 	     S(direct_dc_connections_created),
 	     S(direct_dc_connections_active)
   );
+
+  { int _sc = tcp_rpcs_get_ext_secret_count();
+    int _i;
+    for (_i = 0; _i < _sc; _i++) {
+      sb_printf (sb,
+	       "secret_%s_connections\t%lld\n"
+	       "secret_%s_connections_created\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]));
+    }
+  }
 #undef S
 #undef S1
 #undef SW
@@ -888,6 +911,26 @@ void mtfront_prepare_prometheus_stats (stats_buffer_t *sb) {
 	     S(direct_dc_connections_active)
   );
 
+  { int _sc = tcp_rpcs_get_ext_secret_count();
+    if (_sc > 0) {
+      int _i;
+      sb_printf (sb,
+	       "# HELP mtproxy_secret_connections Current connections per configured secret.\n"
+	       "# TYPE mtproxy_secret_connections gauge\n");
+      for (_i = 0; _i < _sc; _i++) {
+        sb_printf (sb, "mtproxy_secret_connections{secret=\"%s\"} %lld\n",
+	         tcp_rpcs_get_ext_secret_label (_i), S(per_secret_connections[_i]));
+      }
+      sb_printf (sb,
+	       "# HELP mtproxy_secret_connections_created_total Total connections per configured secret.\n"
+	       "# TYPE mtproxy_secret_connections_created_total counter\n");
+      for (_i = 0; _i < _sc; _i++) {
+        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]));
+      }
+    }
+  }
+
 #undef S
 #undef S1
 #undef SW
@@ -1255,13 +1298,22 @@ int mtproto_http_close (connection_job_t C, int who) {
 int mtproto_ext_rpc_ready (connection_job_t C) {
   assert ((unsigned) CONN_INFO(C)->fd < MAX_CONNECTIONS);
   vkprintf (3, "ext_rpc connection ready (%d)\n", CONN_INFO(C)->fd);
+  int sid = TCP_RPC_DATA(C)->extra_int2;
+  if (sid > 0 && sid <= 16) {
+    per_secret_connections[sid - 1]++;
+    per_secret_connections_created[sid - 1]++;
+  }
   lru_insert_conn (C);
   return 0;
 }
 
 int mtproto_ext_rpc_close (connection_job_t C, int who) {
   assert ((unsigned) CONN_INFO(C)->fd < MAX_CONNECTIONS);
   vkprintf (3, "ext_rpc connection closing (%d) by %d\n", CONN_INFO(C)->fd, who);
+  int sid = TCP_RPC_DATA(C)->extra_int2;
+  if (sid > 0 && sid <= 16) {
+    per_secret_connections[sid - 1]--;
+  }
   struct ext_connection *Ex = get_ext_connection_by_in_fd (CONN_INFO(C)->fd);
   if (Ex) {
     remove_ext_connection (Ex, 1);
@@ -2393,7 +2445,36 @@ int f_parse_option (int val) {
   case 'S':
   case 'P':
     {
-      if (strlen (optarg) != 32) {
+      char *label = NULL;
+      int hex_len;
+
+      if (val == 'S') {
+        char *colon = strchr (optarg, ':');
+        if (colon) {
+          hex_len = colon - optarg;
+          label = colon + 1;
+          if (strlen (label) == 0) {
+            label = NULL;
+          } else if (strlen (label) > EXT_SECRET_LABEL_MAX) {
+            kprintf ("Secret label too long (max %d chars)\n", EXT_SECRET_LABEL_MAX);
+            usage ();
+          } else {
+            const char *p;
+            for (p = label; *p; p++) {
+              if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') || (*p >= '0' && *p <= '9') || *p == '_' || *p == '-')) {
+                kprintf ("Secret label contains invalid character '%c' (allowed: a-z, A-Z, 0-9, _, -)\n", *p);
+                usage ();
+              }
+            }
+          }
+        } else {
+          hex_len = strlen (optarg);
+        }
+      } else {
+        hex_len = strlen (optarg);
+      }
+
+      if (hex_len != 32) {
         kprintf ("'%c' option requires exactly 32 hex digits\n", val);
         usage ();
       }
@@ -2418,7 +2499,7 @@ int f_parse_option (int val) {
         }
       }
       if (val == 'S') {
-	tcp_rpcs_set_ext_secret (secret);
+	tcp_rpcs_set_ext_secret (secret, label);
 	secret_count++;
       } else {
 	memcpy (proxy_tag, secret, sizeof (proxy_tag));
@@ -2446,7 +2527,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 mode");
+  parse_option ("mtproto-secret", required_argument, 0, 'S', "16-byte secret in hex, optionally followed by :LABEL (e.g. -S abcdef01234567890abcdef012345678:myapp)");
   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-common.h

@@ -134,7 +134,7 @@ struct tcp_rpc_data {
     void *extra;
   };
   int extra_int;
-  int extra_int2;
+  int extra_int2;  /* matched secret index + 1 (0 = unset) */
   int extra_int3;
   int extra_int4;
   double extra_double, extra_double2;

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

@@ -177,6 +177,7 @@ int tcp_proxy_pass_write_packet (connection_job_t C, struct raw_message *raw) {
 
 extern int direct_mode;
 extern long long direct_dc_connections_created, direct_dc_connections_active;
+extern long long per_secret_connections[16], per_secret_connections_created[16];
 
 static int tcp_direct_client_parse_execute (connection_job_t C);
 static int tcp_direct_dc_parse_execute (connection_job_t C);
@@ -278,6 +279,10 @@ static int tcp_direct_close (connection_job_t C, int who) {
   vkprintf (1, "closing direct connection #%d %s:%d -> %s:%d\n", c->fd, show_our_ip (C), c->our_port, show_remote_ip (C), c->remote_port);
   if ((c->type == &ct_direct_client || c->type == &ct_direct_client_drs) && direct_dc_connections_active > 0) {
     direct_dc_connections_active--;
+    int sid = TCP_RPC_DATA(C)->extra_int2;
+    if (sid > 0 && sid <= 16) {
+      per_secret_connections[sid - 1]--;
+    }
   }
   if (c->extra) {
     job_t E = PTR_MOVE (c->extra);
@@ -430,6 +435,12 @@ static int direct_connect_to_dc (connection_job_t C, int target_dc) {
   direct_dc_connections_created++;
   direct_dc_connections_active++;
 
+  int sid = TCP_RPC_DATA(C)->extra_int2;
+  if (sid > 0 && sid <= 16) {
+    per_secret_connections[sid - 1]++;
+    per_secret_connections_created[sid - 1]++;
+  }
+
   assert (CONN_INFO(EJ)->io_conn);
   unlock_job (JOB_REF_PASS (EJ));
 
@@ -447,10 +458,27 @@ int tcp_rpcs_default_execute (connection_job_t c, int op, struct raw_message *ms
 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];
 
-void tcp_rpcs_set_ext_secret (unsigned char secret[16]) {
+void tcp_rpcs_set_ext_secret (unsigned char secret[16], const char *label) {
   assert (ext_secret_cnt < 16);
-  memcpy (ext_secret[ext_secret_cnt ++], secret, 16);
+  int idx = ext_secret_cnt++;
+  memcpy (ext_secret[idx], secret, 16);
+  if (label && label[0]) {
+    snprintf (ext_secret_label[idx], sizeof (ext_secret_label[idx]), "%s", 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]);
+}
+
+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_count (void) {
+  return ext_secret_cnt;
 }
 
 void tcp_rpcs_set_ext_rand_pad_only(int set) {
@@ -1419,6 +1447,9 @@ int tcp_rpcs_compact_parse_execute (connection_job_t C) {
           RETURN_TLS_ERROR(info);
         }
 
+        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);
+
         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");
@@ -1576,7 +1607,8 @@ int tcp_rpcs_compact_parse_execute (connection_job_t C) {
 
           int target = *(short *)(random_header + 60);
           D->extra_int4 = target;
-          vkprintf (1, "tcp opportunistic encryption mode detected, tag = %08x, target=%d\n", tag, target);
+          D->extra_int2 = secret_id + 1;
+          vkprintf (1, "tcp opportunistic encryption mode detected, tag = %08x, target=%d, secret [%s]\n", tag, target, ext_secret_label[secret_id]);
           ok = 1;
           break;
         } else {

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

@@ -29,8 +29,12 @@ extern conn_type_t ct_tcp_rpc_ext_server;
 
 int tcp_rpcs_compact_parse_execute (connection_job_t c);
 
-void tcp_rpcs_set_ext_secret(unsigned char secret[16]);
+#define EXT_SECRET_LABEL_MAX 32
+
+void tcp_rpcs_set_ext_secret(unsigned char secret[16], const char *label);
 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_count(void);
 
 void tcp_rpc_add_proxy_domain (const char *domain);
 

start.sh

@@ -62,7 +62,15 @@ _i=1
 while [ "$_i" -le 16 ]; do
     eval "_val=\${SECRET_${_i}:-}"
     _val=$(printf '%s' "$_val" | tr -d '[:space:]')
-    [ -n "$_val" ] && set -- "$@" "$_val"
+    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"
+        fi
+    fi
     _i=$((_i + 1))
 done
 
@@ -156,16 +164,21 @@ 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)
+    _secret_hex=$(printf '%s' "$_s" | cut -d: -f1)
+    _label=$(printf '%s' "$_s" | grep -o ':.*' | cut -c2- || true)
     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')
-        _full="ee${_s}${_domain_hex}"
+        _full="ee${_secret_hex}${_domain_hex}"
     elif [ "$RANDOM_PADDING" = "true" ]; then
-        _full="dd${_s}"
+        _full="dd${_secret_hex}"
     else
-        _full="$_s"
+        _full="$_secret_hex"
     fi
-    echo "https://t.me/proxy?server=${_host}&port=${PORT}&secret=${_full}"
+    _label_display=""
+    [ -n "$_label" ] && _label_display=" [$_label]"
+    echo "https://t.me/proxy?server=${_host}&port=${PORT}&secret=${_full}${_label_display}"
 done
 if [ "$_host" = "<YOUR_SERVER_IP>" ]; then
     echo "(Set EXTERNAL_IP to show your server's IP)"