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/botlink/client.go

@@ -0,0 +1,131 @@
+package botlink
+
+import (
+	"context"
+	"time"
+
+	"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
+	"go.uber.org/zap"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/keepalive"
+
+	botlinkv1 "scrabble/pkg/proto/botlink/v1"
+)
+
+const (
+	// clientKeepaliveTime is how often the bot pings the gateway to hold the WAN
+	// connection open (kept above the gateway's MinTime to avoid an enforcement ban).
+	clientKeepaliveTime = 30 * time.Second
+	// clientKeepaliveTimeout bounds the wait for a keepalive ping reply.
+	clientKeepaliveTimeout = 10 * time.Second
+)
+
+// ClientConfig configures the bot's dial side of the reverse bot-link.
+type ClientConfig struct {
+	// GatewayAddr is the gateway bot-link endpoint to dial.
+	GatewayAddr string
+	// InstanceID identifies this bot to the gateway.
+	InstanceID string
+	// OwnsUpdates reports whether this bot runs the exclusive getUpdates long-poll.
+	OwnsUpdates bool
+	// Creds is the transport credentials for the dial (mutual TLS in production,
+	// built from pkg/mtls).
+	Creds credentials.TransportCredentials
+	// ReconnectDelay is the pause before re-dialing after the stream ends.
+	ReconnectDelay time.Duration
+}
+
+// Client maintains the long-lived bot-link to the gateway, executing the commands
+// it receives and re-dialing after any break.
+type Client struct {
+	cfg  ClientConfig
+	exec *Executor
+	log  *zap.Logger
+}
+
+// NewClient builds the bot-link client over the executor.
+func NewClient(cfg ClientConfig, exec *Executor, log *zap.Logger) *Client {
+	if log == nil {
+		log = zap.NewNop()
+	}
+	return &Client{cfg: cfg, exec: exec, log: log}
+}
+
+// Run dials the gateway and keeps the bot-link open, re-dialing after each break,
+// until ctx is cancelled. The gRPC connection auto-reconnects the transport; this
+// loop re-opens the Link stream on top of it.
+func (c *Client) Run(ctx context.Context) error {
+	conn, err := grpc.NewClient(c.cfg.GatewayAddr,
+		grpc.WithTransportCredentials(c.cfg.Creds),
+		grpc.WithStatsHandler(otelgrpc.NewClientHandler()),
+		grpc.WithKeepaliveParams(keepalive.ClientParameters{
+			Time:                clientKeepaliveTime,
+			Timeout:             clientKeepaliveTimeout,
+			PermitWithoutStream: true,
+		}),
+	)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = conn.Close() }()
+	client := botlinkv1.NewBotLinkClient(conn)
+
+	for ctx.Err() == nil {
+		if err := c.serve(ctx, client); err != nil && ctx.Err() == nil {
+			c.log.Warn("bot-link stream ended", zap.Error(err))
+		}
+		if !sleep(ctx, c.cfg.ReconnectDelay) {
+			break
+		}
+	}
+	return ctx.Err()
+}
+
+// serve opens one Link stream, registers with a Hello, then executes commands and
+// replies with an Ack each until the stream ends.
+func (c *Client) serve(ctx context.Context, client botlinkv1.BotLinkClient) error {
+	stream, err := client.Link(ctx)
+	if err != nil {
+		return err
+	}
+	if err := stream.Send(&botlinkv1.FromBot{Msg: &botlinkv1.FromBot_Hello{Hello: &botlinkv1.Hello{
+		InstanceId:  c.cfg.InstanceID,
+		OwnsUpdates: c.cfg.OwnsUpdates,
+	}}}); err != nil {
+		return err
+	}
+	c.log.Info("bot-link connected", zap.String("gateway", c.cfg.GatewayAddr), zap.Bool("owns_updates", c.cfg.OwnsUpdates))
+
+	for {
+		msg, err := stream.Recv()
+		if err != nil {
+			return err
+		}
+		cmd := msg.GetCommand()
+		if cmd == nil {
+			continue
+		}
+		delivered, herr := c.exec.Handle(ctx, cmd)
+		ack := &botlinkv1.Ack{CommandId: cmd.GetCommandId(), Delivered: delivered}
+		if herr != nil {
+			ack.Error = herr.Error()
+		}
+		if err := stream.Send(&botlinkv1.FromBot{Msg: &botlinkv1.FromBot_Ack{Ack: ack}}); err != nil {
+			return err
+		}
+	}
+}
+
+// sleep waits for d or until ctx is cancelled, reporting whether it waited the full
+// duration.
+func sleep(ctx context.Context, d time.Duration) bool {
+	t := time.NewTimer(d)
+	defer t.Stop()
+	select {
+	case <-ctx.Done():
+		return false
+	case <-t.C:
+		return true
+	}
+}

platform/telegram/internal/botlink/client_test.go

@@ -0,0 +1,87 @@
+package botlink
+
+import (
+	"fmt"
+	"net"
+	"testing"
+	"time"
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+
+	botlinkv1 "scrabble/pkg/proto/botlink/v1"
+	telegramv1 "scrabble/pkg/proto/telegram/v1"
+)
+
+// testLinkServer registers one bot, pushes a single Notify command, and records the
+// Ack the client returns.
+type testLinkServer struct {
+	botlinkv1.UnimplementedBotLinkServer
+	acks chan *botlinkv1.Ack
+}
+
+func (s *testLinkServer) Link(stream grpc.BidiStreamingServer[botlinkv1.FromBot, botlinkv1.ToBot]) error {
+	hello, err := stream.Recv()
+	if err != nil {
+		return err
+	}
+	if hello.GetHello() == nil {
+		return fmt.Errorf("first message was not Hello")
+	}
+	if err := stream.Send(&botlinkv1.ToBot{Command: &botlinkv1.Command{
+		CommandId: "c1",
+		Payload: &botlinkv1.Command_Notify{Notify: &telegramv1.NotifyRequest{
+			ExternalId: "12345", Kind: "your_turn",
+			Payload: yourTurnPayload("7c9e6679-7425-40de-944b-e07fc1f90ae7"), Language: "en",
+		}},
+	}}); err != nil {
+		return err
+	}
+	for {
+		msg, err := stream.Recv()
+		if err != nil {
+			return err
+		}
+		if ack := msg.GetAck(); ack != nil {
+			s.acks <- ack
+			return nil
+		}
+	}
+}
+
+// TestClientServesCommands verifies the bot client dials, registers, executes a
+// pushed command through the executor, and acks it.
+func TestClientServesCommands(t *testing.T) {
+	lis, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	ts := &testLinkServer{acks: make(chan *botlinkv1.Ack, 1)}
+	srv := grpc.NewServer()
+	botlinkv1.RegisterBotLinkServer(srv, ts)
+	go func() { _ = srv.Serve(lis) }()
+	t.Cleanup(srv.Stop)
+
+	sender := &fakeSender{}
+	client := NewClient(ClientConfig{
+		GatewayAddr:    lis.Addr().String(),
+		InstanceID:     "test",
+		Creds:          insecure.NewCredentials(),
+		ReconnectDelay: 50 * time.Millisecond,
+	}, NewExecutor(sender, 0, nil), nil)
+
+	go func() { _ = client.Run(t.Context()) }()
+
+	select {
+	case ack := <-ts.acks:
+		if ack.GetCommandId() != "c1" || !ack.GetDelivered() {
+			t.Errorf("ack = %+v, want command_id c1 delivered=true", ack)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("server received no ack")
+	}
+	// The channel receive above happens-after the client wrote the sender call.
+	if len(sender.notify) != 1 || sender.notify[0].chatID != 12345 {
+		t.Errorf("sender notify calls = %+v, want one call to chat 12345", sender.notify)
+	}
+}

platform/telegram/internal/botlink/executor.go

@@ -0,0 +1,110 @@
+// Package botlink is the bot side of the reverse Telegram channel: the bot dials
+// the gateway over mTLS (pkg/proto/botlink/v1), opens one long-lived Link stream,
+// and executes the send Commands the gateway pushes, replying with an Ack per
+// command. It keeps the Bot API token and egress on the remote bot host with no
+// inbound port. See docs/ARCHITECTURE.md.
+package botlink
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+
+	"go.uber.org/zap"
+
+	botlinkv1 "scrabble/pkg/proto/botlink/v1"
+	telegramv1 "scrabble/pkg/proto/telegram/v1"
+	"scrabble/platform/telegram/internal/render"
+)
+
+// Sender delivers Telegram messages to a chat. *bot.Bot implements it.
+type Sender interface {
+	// Notify sends a notification with a Mini App launch button to chatID.
+	Notify(ctx context.Context, chatID int64, text, buttonText, startParam string) error
+	// SendText sends a plain text message to chatID.
+	SendText(ctx context.Context, chatID int64, text string) error
+}
+
+// Executor turns a bot-link Command into a Bot API send. The delivered flag mirrors
+// the former connector semantics (false when the kind is not rendered out-of-app,
+// the user never started the bot, or no channel is configured); a returned error is
+// an unexpected or malformed failure carried back in the Ack error field, distinct
+// from a clean not-delivered.
+type Executor struct {
+	sender    Sender
+	channelID int64
+	log       *zap.Logger
+}
+
+// NewExecutor builds the executor over a bot sender and the optional game channel.
+func NewExecutor(sender Sender, channelID int64, log *zap.Logger) *Executor {
+	if log == nil {
+		log = zap.NewNop()
+	}
+	return &Executor{sender: sender, channelID: channelID, log: log}
+}
+
+// Handle dispatches one command to the matching Bot API send.
+func (e *Executor) Handle(ctx context.Context, cmd *botlinkv1.Command) (bool, error) {
+	switch p := cmd.GetPayload().(type) {
+	case *botlinkv1.Command_Notify:
+		return e.notify(ctx, p.Notify)
+	case *botlinkv1.Command_SendToUser:
+		return e.sendToUser(ctx, p.SendToUser)
+	case *botlinkv1.Command_SendToChannel:
+		return e.sendToChannel(ctx, p.SendToChannel)
+	default:
+		return false, fmt.Errorf("botlink: empty command")
+	}
+}
+
+// notify renders an out-of-app push and sends it with a Mini App launch button.
+func (e *Executor) notify(ctx context.Context, req *telegramv1.NotifyRequest) (bool, error) {
+	msg, ok := render.Render(req.GetKind(), req.GetPayload(), req.GetLanguage())
+	if !ok {
+		return false, nil
+	}
+	chat, err := parseChatID(req.GetExternalId())
+	if err != nil {
+		return false, err
+	}
+	if err := e.sender.Notify(ctx, chat, msg.Text, msg.ButtonText, msg.StartParam); err != nil {
+		e.log.Warn("notify delivery failed", zap.String("kind", req.GetKind()), zap.Error(err))
+		return false, nil
+	}
+	return true, nil
+}
+
+// sendToUser sends an admin text message to one user.
+func (e *Executor) sendToUser(ctx context.Context, req *telegramv1.SendToUserRequest) (bool, error) {
+	chat, err := parseChatID(req.GetExternalId())
+	if err != nil {
+		return false, err
+	}
+	if err := e.sender.SendText(ctx, chat, req.GetText()); err != nil {
+		e.log.Warn("send to user failed", zap.Error(err))
+		return false, nil
+	}
+	return true, nil
+}
+
+// sendToChannel posts an admin text message to the bot's game channel.
+func (e *Executor) sendToChannel(ctx context.Context, req *telegramv1.SendToGameChannelRequest) (bool, error) {
+	if e.channelID == 0 {
+		return false, fmt.Errorf("botlink: game channel is not configured")
+	}
+	if err := e.sender.SendText(ctx, e.channelID, req.GetText()); err != nil {
+		e.log.Warn("send to channel failed", zap.Error(err))
+		return false, nil
+	}
+	return true, nil
+}
+
+// parseChatID converts a Telegram identity external_id into a numeric chat id.
+func parseChatID(externalID string) (int64, error) {
+	id, err := strconv.ParseInt(externalID, 10, 64)
+	if err != nil {
+		return 0, fmt.Errorf("invalid external_id %q", externalID)
+	}
+	return id, nil
+}

platform/telegram/internal/botlink/executor_test.go

@@ -0,0 +1,129 @@
+package botlink
+
+import (
+	"context"
+	"testing"
+
+	flatbuffers "github.com/google/flatbuffers/go"
+
+	"scrabble/pkg/fbs/scrabblefb"
+	botlinkv1 "scrabble/pkg/proto/botlink/v1"
+	telegramv1 "scrabble/pkg/proto/telegram/v1"
+)
+
+// fakeSender records the delivery calls the executor makes.
+type fakeSender struct {
+	notify []notifyCall
+	text   []textCall
+	err    error
+}
+
+type notifyCall struct {
+	chatID                       int64
+	text, buttonText, startParam string
+}
+type textCall struct {
+	chatID int64
+	text   string
+}
+
+func (f *fakeSender) Notify(_ context.Context, chatID int64, text, buttonText, startParam string) error {
+	f.notify = append(f.notify, notifyCall{chatID, text, buttonText, startParam})
+	return f.err
+}
+
+func (f *fakeSender) SendText(_ context.Context, chatID int64, text string) error {
+	f.text = append(f.text, textCall{chatID, text})
+	return f.err
+}
+
+func yourTurnPayload(gameID string) []byte {
+	b := flatbuffers.NewBuilder(0)
+	gid := b.CreateString(gameID)
+	scrabblefb.YourTurnEventStart(b)
+	scrabblefb.YourTurnEventAddGameId(b, gid)
+	b.Finish(scrabblefb.YourTurnEventEnd(b))
+	return b.FinishedBytes()
+}
+
+func notifyCmd(externalID, kind string, payload []byte, language string) *botlinkv1.Command {
+	return &botlinkv1.Command{Payload: &botlinkv1.Command_Notify{Notify: &telegramv1.NotifyRequest{
+		ExternalId: externalID, Kind: kind, Payload: payload, Language: language,
+	}}}
+}
+
+func TestExecutorNotifyDelivers(t *testing.T) {
+	const gameID = "7c9e6679-7425-40de-944b-e07fc1f90ae7"
+	sender := &fakeSender{}
+	exec := NewExecutor(sender, 0, nil)
+	delivered, err := exec.Handle(context.Background(), notifyCmd("12345", "your_turn", yourTurnPayload(gameID), "en"))
+	if err != nil {
+		t.Fatalf("handle: %v", err)
+	}
+	if !delivered {
+		t.Fatal("expected delivered=true")
+	}
+	if len(sender.notify) != 1 {
+		t.Fatalf("notify calls = %d, want 1", len(sender.notify))
+	}
+	if got := sender.notify[0]; got.chatID != 12345 || got.startParam != "g"+gameID {
+		t.Errorf("notify call = %+v, want chatID 12345 startParam g%s", got, gameID)
+	}
+}
+
+func TestExecutorNotifySkipsUnrenderedKind(t *testing.T) {
+	sender := &fakeSender{}
+	exec := NewExecutor(sender, 0, nil)
+	delivered, err := exec.Handle(context.Background(), notifyCmd("12345", "opponent_moved", nil, "en"))
+	if err != nil {
+		t.Fatalf("handle: %v", err)
+	}
+	if delivered {
+		t.Error("expected delivered=false for an unrendered kind")
+	}
+	if len(sender.notify) != 0 {
+		t.Errorf("sender called %d times, want 0", len(sender.notify))
+	}
+}
+
+func TestExecutorNotifyInvalidExternalID(t *testing.T) {
+	exec := NewExecutor(&fakeSender{}, 0, nil)
+	if _, err := exec.Handle(context.Background(), notifyCmd("not-a-number", "your_turn", yourTurnPayload("g"), "en")); err == nil {
+		t.Error("expected an error for a non-numeric external_id")
+	}
+}
+
+func TestExecutorSendToUser(t *testing.T) {
+	sender := &fakeSender{}
+	exec := NewExecutor(sender, 0, nil)
+	cmd := &botlinkv1.Command{Payload: &botlinkv1.Command_SendToUser{SendToUser: &telegramv1.SendToUserRequest{ExternalId: "999", Text: "hi"}}}
+	delivered, err := exec.Handle(context.Background(), cmd)
+	if err != nil {
+		t.Fatalf("handle: %v", err)
+	}
+	if !delivered || len(sender.text) != 1 || sender.text[0].chatID != 999 || sender.text[0].text != "hi" {
+		t.Errorf("send to user = %v / calls %+v", delivered, sender.text)
+	}
+}
+
+func TestExecutorSendToChannel(t *testing.T) {
+	channelCmd := &botlinkv1.Command{Payload: &botlinkv1.Command_SendToChannel{SendToChannel: &telegramv1.SendToGameChannelRequest{Text: "news"}}}
+
+	t.Run("unconfigured", func(t *testing.T) {
+		exec := NewExecutor(&fakeSender{}, 0, nil)
+		if _, err := exec.Handle(context.Background(), channelCmd); err == nil {
+			t.Error("expected an error when no channel is configured")
+		}
+	})
+	t.Run("configured", func(t *testing.T) {
+		sender := &fakeSender{}
+		exec := NewExecutor(sender, 555, nil)
+		delivered, err := exec.Handle(context.Background(), channelCmd)
+		if err != nil {
+			t.Fatalf("handle: %v", err)
+		}
+		if !delivered || len(sender.text) != 1 || sender.text[0].chatID != 555 {
+			t.Errorf("send to channel: %+v", sender.text)
+		}
+	})
+}