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
+}