feat(telegram): split connector into home validator + remote bot

Move all Telegram egress off the main host. The single connector held the
bot token, long-polled Telegram and answered the gateway/backend over the
trusted internal network, so the whole component (including login validation)
shared fate with its VPN sidecar. Split it into two binaries that share the
token:

- cmd/validator (home, no VPN): Mini App initData + Login Widget HMAC only,
  never calls the Bot API. The gateway dials it for Telegram auth, so game
  login is now independent of Telegram reachability.
- cmd/bot (remote): Bot API long-poll + sendMessage, the only component
  reaching Telegram. It holds no inbound port — it dials the gateway over a
  new reverse mTLS bot-link (pkg/proto/botlink/v1) and executes the send
  commands the gateway pushes.

The gateway funnels sends to the bot-link: out-of-app push is fire-and-forget
(at-most-once, dropped if no bot is connected); the backend admin broadcasts
reach a gateway-served relay that forwards them and awaits the bot's ack
(SendToUser/SendToGameChannel contract preserved). mTLS (pkg/mtls) is the one
inter-service link that leaves the trusted segment; validator<->gateway and
the relay stay plaintext internal. The bot is Telegram-rate-limited.

One bot now; the gateway bot registry, an owns_updates flag and per-command
ids leave seams for N later. Webhook rejected (one URL per token, adds inbound
+ a static address).

The unified test contour runs the split (the bot keeps its VPN sidecar and
dials the gateway by its internal name; bot-link certs from deploy/gen-certs.sh,
generated in CI). The prod wiring — the bot on a separate host (no VPN), the
gateway bot-link port published, PROD_ certs with scheduled rotation, an SSH
deploy of both hosts together — is the deferred final stage (PRERELEASE.md TX,
Stage 18).

Docs: ARCHITECTURE, PRERELEASE (phase TX), platform/telegram + gateway +
backend + deploy READMEs, FUNCTIONAL(+ru), CLAUDE.md, .env.example.

platform/telegram/internal/config/config_test.go

@@ -6,71 +6,110 @@ import (
 	pkgtel "scrabble/pkg/telemetry"
 )
 
-// setRequired sets the required connector variables (the bot token + the Mini App
-// URL) so Load reaches the telemetry checks.
-func setRequired(t *testing.T) {
+// setBotRequired sets every required bot variable so LoadBot reaches the optional
+// parsing and telemetry checks.
+func setBotRequired(t *testing.T) {
 	t.Helper()
-	t.Setenv("TELEGRAM_BOT_TOKEN", "test-token")
+	t.Setenv("TELEGRAM_BOT_TOKEN", "bot-token")
 	t.Setenv("TELEGRAM_MINIAPP_URL", "https://example.org/app")
+	t.Setenv("TELEGRAM_GATEWAY_ADDR", "gateway.example.org:9443")
+	t.Setenv("TELEGRAM_BOTLINK_SERVER_NAME", "gateway.example.org")
+	t.Setenv("TELEGRAM_BOTLINK_TLS_CERT", "/certs/bot.crt")
+	t.Setenv("TELEGRAM_BOTLINK_TLS_KEY", "/certs/bot.key")
+	t.Setenv("TELEGRAM_BOTLINK_TLS_CA", "/certs/ca.crt")
 }
 
-// TestLoadBot verifies the bot parsing: the token is read and the game channel id is
-// parsed when present.
-func TestLoadBot(t *testing.T) {
-	t.Setenv("TELEGRAM_MINIAPP_URL", "https://example.org/app")
-	t.Setenv("TELEGRAM_BOT_TOKEN", "bot-token")
-	t.Setenv("TELEGRAM_GAME_CHANNEL_ID", "-100111")
-	c, err := Load()
+// TestLoadValidator verifies the validator reads the token, defaults its address
+// and names its telemetry service.
+func TestLoadValidator(t *testing.T) {
+	t.Setenv("TELEGRAM_BOT_TOKEN", "secret")
+	c, err := LoadValidator()
 	if err != nil {
-		t.Fatalf("Load: %v", err)
+		t.Fatalf("LoadValidator: %v", err)
+	}
+	if c.Token != "secret" {
+		t.Errorf("Token = %q, want secret", c.Token)
+	}
+	if c.GRPCAddr != defaultValidatorGRPCAddr {
+		t.Errorf("GRPCAddr = %q, want %q", c.GRPCAddr, defaultValidatorGRPCAddr)
+	}
+	if c.Telemetry.ServiceName != "scrabble-telegram-validator" {
+		t.Errorf("ServiceName = %q, want scrabble-telegram-validator", c.Telemetry.ServiceName)
+	}
+}
+
+// TestLoadValidatorRequiresToken verifies the validator fails without a token.
+func TestLoadValidatorRequiresToken(t *testing.T) {
+	t.Setenv("TELEGRAM_BOT_TOKEN", "")
+	if _, err := LoadValidator(); err == nil {
+		t.Fatal("LoadValidator: expected an error without a token, got nil")
+	}
+}
+
+// TestLoadBot verifies the bot parses the token, channel id and owns_updates and
+// names its telemetry service.
+func TestLoadBot(t *testing.T) {
+	setBotRequired(t)
+	t.Setenv("TELEGRAM_GAME_CHANNEL_ID", "-100111")
+	c, err := LoadBot()
+	if err != nil {
+		t.Fatalf("LoadBot: %v", err)
 	}
 	if c.Token != "bot-token" || c.GameChannelID != -100111 {
 		t.Errorf("config = token %q / channel %d, want bot-token / -100111", c.Token, c.GameChannelID)
 	}
+	if !c.OwnsUpdates {
+		t.Error("OwnsUpdates = false, want true by default")
+	}
+	if c.SendRatePerSecond != defaultSendRatePerSecond {
+		t.Errorf("SendRatePerSecond = %d, want %d", c.SendRatePerSecond, defaultSendRatePerSecond)
+	}
+	if c.Telemetry.ServiceName != "scrabble-telegram-bot" {
+		t.Errorf("ServiceName = %q, want scrabble-telegram-bot", c.Telemetry.ServiceName)
+	}
 }
 
-// TestLoadOptionalChannel verifies the game channel id defaults to 0 when unset.
-func TestLoadOptionalChannel(t *testing.T) {
-	setRequired(t)
-	c, err := Load()
+// TestLoadBotOwnsUpdatesOptOut verifies TELEGRAM_OWNS_UPDATES=false disables the
+// long-poll ownership.
+func TestLoadBotOwnsUpdatesOptOut(t *testing.T) {
+	setBotRequired(t)
+	t.Setenv("TELEGRAM_OWNS_UPDATES", "false")
+	c, err := LoadBot()
 	if err != nil {
-		t.Fatalf("Load: %v", err)
+		t.Fatalf("LoadBot: %v", err)
 	}
-	if c.GameChannelID != 0 {
-		t.Errorf("GameChannelID = %d, want 0", c.GameChannelID)
+	if c.OwnsUpdates {
+		t.Error("OwnsUpdates = true, want false")
 	}
 }
 
-// TestLoadRequiresBot verifies Load fails when no bot token is configured.
-func TestLoadRequiresBot(t *testing.T) {
-	t.Setenv("TELEGRAM_MINIAPP_URL", "https://example.org/app")
-	if _, err := Load(); err == nil {
-		t.Fatal("Load: expected an error when no bot token is set, got nil")
+// TestLoadBotRequired verifies LoadBot fails when a required variable is missing.
+func TestLoadBotRequired(t *testing.T) {
+	cases := []string{
+		"TELEGRAM_BOT_TOKEN",
+		"TELEGRAM_MINIAPP_URL",
+		"TELEGRAM_GATEWAY_ADDR",
+		"TELEGRAM_BOTLINK_SERVER_NAME",
+		"TELEGRAM_BOTLINK_TLS_CERT",
+	}
+	for _, missing := range cases {
+		t.Run(missing, func(t *testing.T) {
+			setBotRequired(t)
+			t.Setenv(missing, "")
+			if _, err := LoadBot(); err == nil {
+				t.Fatalf("LoadBot: expected an error without %s, got nil", missing)
+			}
+		})
 	}
 }
 
-// TestLoadTelemetryDefaults verifies the connector telemetry defaults: the
-// "scrabble-telegram" service name and both exporters off.
-func TestLoadTelemetryDefaults(t *testing.T) {
-	setRequired(t)
-	c, err := Load()
-	if err != nil {
-		t.Fatalf("Load: %v", err)
-	}
-	if c.Telemetry.ServiceName != "scrabble-telegram" {
-		t.Errorf("Telemetry.ServiceName = %q, want scrabble-telegram", c.Telemetry.ServiceName)
-	}
-	if c.Telemetry.TracesExporter != pkgtel.ExporterNone || c.Telemetry.MetricsExporter != pkgtel.ExporterNone {
-		t.Errorf("exporters = %q/%q, want none/none", c.Telemetry.TracesExporter, c.Telemetry.MetricsExporter)
-	}
-}
-
-// TestLoadRejectsUnsupportedExporter verifies an exporter outside the supported
-// set fails validation.
+// TestLoadRejectsUnsupportedExporter verifies an exporter outside the supported set
+// fails validation (the validator path).
 func TestLoadRejectsUnsupportedExporter(t *testing.T) {
-	setRequired(t)
+	t.Setenv("TELEGRAM_BOT_TOKEN", "secret")
 	t.Setenv("TELEGRAM_OTEL_TRACES_EXPORTER", "jaeger")
-	if _, err := Load(); err == nil {
-		t.Fatal("Load: expected an error for an unsupported exporter, got nil")
+	if _, err := LoadValidator(); err == nil {
+		t.Fatal("LoadValidator: expected an error for an unsupported exporter, got nil")
 	}
+	_ = pkgtel.ExporterNone
 }