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.go

@@ -1,4 +1,8 @@
-// Package config loads the Telegram connector's environment configuration.
+// Package config loads the environment configuration for the two Telegram
+// platform binaries: the home validator (HMAC of Mini App / Login Widget data, no
+// Telegram egress) and the remote bot (Bot API long-poll + sendMessage, dialing
+// the gateway over the reverse mTLS bot-link). The bot token lives in both
+// processes — the validator needs it only as the HMAC secret (ARCHITECTURE.md §12).
 package config
 
 import (
@@ -6,73 +10,173 @@ import (
 	"os"
 	"strconv"
 	"strings"
+	"time"
 
 	pkgtel "scrabble/pkg/telemetry"
 )
 
-// Config is the Telegram connector's runtime configuration, read from the
-// environment. The bot token lives only in this process (ARCHITECTURE.md §12).
-type Config struct {
-	// Token is the Telegram Bot API token (TELEGRAM_BOT_TOKEN, required). It both
-	// authenticates the Bot API client and is the HMAC secret for Mini App initData
-	// and Login Widget validation.
+// ValidatorConfig is the home validator's runtime configuration.
+type ValidatorConfig struct {
+	// Token is the Telegram Bot API token (TELEGRAM_BOT_TOKEN, required). The
+	// validator uses it only as the HMAC secret for Mini App initData and Login
+	// Widget validation; it never calls the Bot API.
 	Token string
-	// GameChannelID is the chat id of the bot's game channel for SendToGameChannel
-	// (TELEGRAM_GAME_CHANNEL_ID, optional; 0 disables channel posts).
-	GameChannelID int64
-	// GRPCAddr is the listen address of the connector gRPC server that gateway and
-	// backend call (TELEGRAM_GRPC_ADDR, default :9091).
+	// GRPCAddr is the listen address of the validator gRPC server the gateway calls
+	// (TELEGRAM_VALIDATOR_GRPC_ADDR, default :9091).
 	GRPCAddr string
-	// MiniAppURL is the HTTPS origin of the Mini App registered with BotFather; it
-	// is the base of every launch button, to which a deep-link adds a startapp
-	// query parameter (TELEGRAM_MINIAPP_URL, required).
-	MiniAppURL string
-	// APIBaseURL overrides the Bot API host (TELEGRAM_API_BASE_URL, optional;
-	// default https://api.telegram.org) — used for a local mock or a self-hosted
-	// Bot API server.
-	APIBaseURL string
-	// TestEnv routes the Bot API client to Telegram's test environment
-	// (.../bot<token>/test/METHOD) (TELEGRAM_TEST_ENV=true, default false).
-	TestEnv bool
 	// LogLevel is the zap log level (TELEGRAM_LOG_LEVEL, default info).
 	LogLevel string
 	// Telemetry configures the OpenTelemetry providers (shared bootstrap).
 	Telemetry pkgtel.Config
 }
 
-// Load reads the connector configuration from the environment, applying defaults
-// and validating the required fields.
-func Load() (Config, error) {
-	cfg := Config{
-		Token:      os.Getenv("TELEGRAM_BOT_TOKEN"),
-		GRPCAddr:   envOr("TELEGRAM_GRPC_ADDR", ":9091"),
-		MiniAppURL: os.Getenv("TELEGRAM_MINIAPP_URL"),
-		APIBaseURL: os.Getenv("TELEGRAM_API_BASE_URL"),
-		TestEnv:    os.Getenv("TELEGRAM_TEST_ENV") == "true",
-		LogLevel:   envOr("TELEGRAM_LOG_LEVEL", "info"),
+// BotConfig is the remote bot's runtime configuration.
+type BotConfig struct {
+	// Token is the Telegram Bot API token (TELEGRAM_BOT_TOKEN, required).
+	Token string
+	// GameChannelID is the chat id of the bot's game channel for the admin channel
+	// post (TELEGRAM_GAME_CHANNEL_ID, optional; 0 disables channel posts).
+	GameChannelID int64
+	// MiniAppURL is the HTTPS origin of the Mini App registered with BotFather; it is
+	// the base of every launch button (TELEGRAM_MINIAPP_URL, required).
+	MiniAppURL string
+	// APIBaseURL overrides the Bot API host (TELEGRAM_API_BASE_URL, optional;
+	// default https://api.telegram.org).
+	APIBaseURL string
+	// TestEnv routes the Bot API client to Telegram's test environment
+	// (TELEGRAM_TEST_ENV=true, default false).
+	TestEnv bool
+	// OwnsUpdates reports whether this bot runs the exclusive getUpdates long-poll
+	// (TELEGRAM_OWNS_UPDATES, default true). Exactly one bot per token must own it.
+	OwnsUpdates bool
+	// SendRatePerSecond caps outbound Bot API sends to respect Telegram flood limits
+	// (TELEGRAM_SEND_RATE_PER_SECOND, default 25; 0 disables the limiter).
+	SendRatePerSecond int
+	// BotLink configures the reverse mTLS channel the bot dials.
+	BotLink BotLinkClientConfig
+	// LogLevel is the zap log level (TELEGRAM_LOG_LEVEL, default info).
+	LogLevel string
+	// Telemetry configures the OpenTelemetry providers (shared bootstrap).
+	Telemetry pkgtel.Config
+}
+
+// BotLinkClientConfig is the bot's dial side of the reverse bot-link.
+type BotLinkClientConfig struct {
+	// GatewayAddr is the gateway bot-link endpoint to dial (TELEGRAM_GATEWAY_ADDR,
+	// required), e.g. "gateway.example.com:9443".
+	GatewayAddr string
+	// ServerName is the gateway certificate's expected SNI / CN
+	// (TELEGRAM_BOTLINK_SERVER_NAME, required).
+	ServerName string
+	// InstanceID identifies this bot to the gateway (TELEGRAM_INSTANCE_ID, default
+	// the hostname).
+	InstanceID string
+	// CertFile, KeyFile and CAFile are the bot client certificate, its key and the
+	// CA bundle that signs the gateway server certificate (required).
+	CertFile string
+	KeyFile  string
+	CAFile   string
+	// ReconnectDelay is the pause before re-dialing after the stream ends
+	// (TELEGRAM_BOTLINK_RECONNECT_DELAY, default 2s).
+	ReconnectDelay time.Duration
+}
+
+const (
+	defaultValidatorGRPCAddr = ":9091"
+	defaultBotReconnectDelay = 2 * time.Second
+	defaultSendRatePerSecond = 25
+)
+
+// LoadValidator reads the validator configuration from the environment.
+func LoadValidator() (ValidatorConfig, error) {
+	cfg := ValidatorConfig{
+		Token:    os.Getenv("TELEGRAM_BOT_TOKEN"),
+		GRPCAddr: envOr("TELEGRAM_VALIDATOR_GRPC_ADDR", defaultValidatorGRPCAddr),
+		LogLevel: envOr("TELEGRAM_LOG_LEVEL", "info"),
 	}
-	if v := strings.TrimSpace(os.Getenv("TELEGRAM_GAME_CHANNEL_ID")); v != "" {
-		id, err := strconv.ParseInt(v, 10, 64)
-		if err != nil {
-			return Config{}, fmt.Errorf("config: TELEGRAM_GAME_CHANNEL_ID %q: %w", v, err)
-		}
-		cfg.GameChannelID = id
+	tel, err := loadTelemetry("scrabble-telegram-validator")
+	if err != nil {
+		return ValidatorConfig{}, err
 	}
-	tel := pkgtel.DefaultConfig("scrabble-telegram")
+	cfg.Telemetry = tel
+	if cfg.Token == "" {
+		return ValidatorConfig{}, fmt.Errorf("config: TELEGRAM_BOT_TOKEN is required")
+	}
+	return cfg, nil
+}
+
+// LoadBot reads the bot configuration from the environment.
+func LoadBot() (BotConfig, error) {
+	cfg := BotConfig{
+		Token:             os.Getenv("TELEGRAM_BOT_TOKEN"),
+		MiniAppURL:        os.Getenv("TELEGRAM_MINIAPP_URL"),
+		APIBaseURL:        os.Getenv("TELEGRAM_API_BASE_URL"),
+		TestEnv:           os.Getenv("TELEGRAM_TEST_ENV") == "true",
+		OwnsUpdates:       os.Getenv("TELEGRAM_OWNS_UPDATES") != "false",
+		SendRatePerSecond: defaultSendRatePerSecond,
+		LogLevel:          envOr("TELEGRAM_LOG_LEVEL", "info"),
+		BotLink: BotLinkClientConfig{
+			GatewayAddr: os.Getenv("TELEGRAM_GATEWAY_ADDR"),
+			ServerName:  os.Getenv("TELEGRAM_BOTLINK_SERVER_NAME"),
+			InstanceID:  envOr("TELEGRAM_INSTANCE_ID", hostname()),
+			CertFile:    os.Getenv("TELEGRAM_BOTLINK_TLS_CERT"),
+			KeyFile:     os.Getenv("TELEGRAM_BOTLINK_TLS_KEY"),
+			CAFile:      os.Getenv("TELEGRAM_BOTLINK_TLS_CA"),
+		},
+	}
+	var err error
+	if cfg.GameChannelID, err = envInt64("TELEGRAM_GAME_CHANNEL_ID", 0); err != nil {
+		return BotConfig{}, err
+	}
+	if cfg.SendRatePerSecond, err = envInt("TELEGRAM_SEND_RATE_PER_SECOND", defaultSendRatePerSecond); err != nil {
+		return BotConfig{}, err
+	}
+	if cfg.BotLink.ReconnectDelay, err = envDuration("TELEGRAM_BOTLINK_RECONNECT_DELAY", defaultBotReconnectDelay); err != nil {
+		return BotConfig{}, err
+	}
+	tel, err := loadTelemetry("scrabble-telegram-bot")
+	if err != nil {
+		return BotConfig{}, err
+	}
+	cfg.Telemetry = tel
+
+	if cfg.Token == "" {
+		return BotConfig{}, fmt.Errorf("config: TELEGRAM_BOT_TOKEN is required")
+	}
+	if cfg.MiniAppURL == "" {
+		return BotConfig{}, fmt.Errorf("config: TELEGRAM_MINIAPP_URL is required")
+	}
+	if cfg.BotLink.GatewayAddr == "" {
+		return BotConfig{}, fmt.Errorf("config: TELEGRAM_GATEWAY_ADDR is required")
+	}
+	if cfg.BotLink.ServerName == "" {
+		return BotConfig{}, fmt.Errorf("config: TELEGRAM_BOTLINK_SERVER_NAME is required")
+	}
+	if cfg.BotLink.CertFile == "" || cfg.BotLink.KeyFile == "" || cfg.BotLink.CAFile == "" {
+		return BotConfig{}, fmt.Errorf("config: TELEGRAM_BOTLINK_TLS_CERT, _KEY and _CA are required")
+	}
+	return cfg, nil
+}
+
+// loadTelemetry builds the shared OpenTelemetry config with the given default
+// service name, applying the TELEGRAM_* overrides and validating the result.
+func loadTelemetry(defaultService string) (pkgtel.Config, error) {
+	tel := pkgtel.DefaultConfig(defaultService)
 	tel.ServiceName = envOr("TELEGRAM_SERVICE_NAME", tel.ServiceName)
 	tel.TracesExporter = envOr("TELEGRAM_OTEL_TRACES_EXPORTER", tel.TracesExporter)
 	tel.MetricsExporter = envOr("TELEGRAM_OTEL_METRICS_EXPORTER", tel.MetricsExporter)
-	cfg.Telemetry = tel
-	if cfg.Token == "" {
-		return Config{}, fmt.Errorf("config: TELEGRAM_BOT_TOKEN is required")
+	if err := tel.Validate(); err != nil {
+		return pkgtel.Config{}, fmt.Errorf("config: %w", err)
 	}
-	if cfg.MiniAppURL == "" {
-		return Config{}, fmt.Errorf("config: TELEGRAM_MINIAPP_URL is required")
+	return tel, nil
+}
+
+// hostname returns the machine hostname, or "telegram-bot" when it cannot be read.
+func hostname() string {
+	if h, err := os.Hostname(); err == nil && h != "" {
+		return h
 	}
-	if err := cfg.Telemetry.Validate(); err != nil {
-		return Config{}, fmt.Errorf("config: %w", err)
-	}
-	return cfg, nil
+	return "telegram-bot"
 }
 
 // envOr returns the environment value for key, or def when it is unset or empty.
@@ -82,3 +186,45 @@ func envOr(key, def string) string {
 	}
 	return def
 }
+
+// envInt parses the environment variable named key as an int, returning fallback
+// when unset and an error when set but malformed.
+func envInt(key string, fallback int) (int, error) {
+	v := strings.TrimSpace(os.Getenv(key))
+	if v == "" {
+		return fallback, nil
+	}
+	n, err := strconv.Atoi(v)
+	if err != nil {
+		return 0, fmt.Errorf("config: %s %q: %w", key, v, err)
+	}
+	return n, nil
+}
+
+// envInt64 parses the environment variable named key as an int64, returning
+// fallback when unset and an error when set but malformed.
+func envInt64(key string, fallback int64) (int64, error) {
+	v := strings.TrimSpace(os.Getenv(key))
+	if v == "" {
+		return fallback, nil
+	}
+	n, err := strconv.ParseInt(v, 10, 64)
+	if err != nil {
+		return 0, fmt.Errorf("config: %s %q: %w", key, v, err)
+	}
+	return n, nil
+}
+
+// envDuration parses the environment variable named key as a Go duration,
+// returning fallback when unset and an error when set but malformed.
+func envDuration(key string, fallback time.Duration) (time.Duration, error) {
+	v := strings.TrimSpace(os.Getenv(key))
+	if v == "" {
+		return fallback, nil
+	}
+	d, err := time.ParseDuration(v)
+	if err != nil {
+		return 0, fmt.Errorf("config: %s %q: %w", key, v, err)
+	}
+	return d, nil
+}

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
 }