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.
2026-06-21 00:19:07 +02:00
parent 2a8717c930
commit 6aeb529f13
42 changed files with 3073 additions and 714 deletions
@@ -0,0 +1,68 @@
+// Package mtls builds mutual-TLS configurations for the one inter-service link
+// that crosses an untrusted network: the reverse bot-link between a remote
+// Telegram bot and the gateway (pkg/proto/botlink/v1). Both peers present a
+// certificate signed by a shared private CA and verify the other against it, so the
+// gateway accepts only our bot and the bot trusts only our gateway. Every other
+// inter-service hop stays on the trusted internal network and uses plaintext
+// (docs/ARCHITECTURE.md §12).
+package mtls
+
+import (
+	"crypto/tls"
+	"crypto/x509"
+	"fmt"
+	"os"
+)
+
+// ServerConfig builds a TLS config for the gateway's bot-link listener. It loads
+// the server certificate from certFile/keyFile, trusts client certificates signed
+// by the CA in caFile, and requires every client to present a valid one.
+func ServerConfig(certFile, keyFile, caFile string) (*tls.Config, error) {
+	cert, err := tls.LoadX509KeyPair(certFile, keyFile)
+	if err != nil {
+		return nil, fmt.Errorf("mtls: load server keypair: %w", err)
+	}
+	pool, err := loadCAPool(caFile)
+	if err != nil {
+		return nil, err
+	}
+	return &tls.Config{
+		Certificates: []tls.Certificate{cert},
+		ClientCAs:    pool,
+		ClientAuth:   tls.RequireAndVerifyClientCert,
+		MinVersion:   tls.VersionTLS13,
+	}, nil
+}
+
+// ClientConfig builds a TLS config for the bot dialing the gateway. It presents the
+// client certificate from certFile/keyFile, verifies the gateway's certificate
+// against the CA in caFile, and pins the expected serverName.
+func ClientConfig(certFile, keyFile, caFile, serverName string) (*tls.Config, error) {
+	cert, err := tls.LoadX509KeyPair(certFile, keyFile)
+	if err != nil {
+		return nil, fmt.Errorf("mtls: load client keypair: %w", err)
+	}
+	pool, err := loadCAPool(caFile)
+	if err != nil {
+		return nil, err
+	}
+	return &tls.Config{
+		Certificates: []tls.Certificate{cert},
+		RootCAs:      pool,
+		ServerName:   serverName,
+		MinVersion:   tls.VersionTLS13,
+	}, nil
+}
+
+// loadCAPool reads a PEM bundle and returns a certificate pool trusting it.
+func loadCAPool(caFile string) (*x509.CertPool, error) {
+	pem, err := os.ReadFile(caFile)
+	if err != nil {
+		return nil, fmt.Errorf("mtls: read CA %s: %w", caFile, err)
+	}
+	pool := x509.NewCertPool()
+	if !pool.AppendCertsFromPEM(pem) {
+		return nil, fmt.Errorf("mtls: CA %s contains no certificates", caFile)
+	}
+	return pool, nil
+}
@@ -0,0 +1,490 @@
+// Code generated by protoc-gen-go. DO NOT EDIT.
+// versions:
+// 	protoc-gen-go v1.36.11
+// 	protoc        (unknown)
+// source: botlink/v1/botlink.proto
+
+// Package scrabble.botlink.v1 is the reverse control channel between a remote
+// Telegram bot and the gateway. The bot dials the gateway and opens a single
+// long-lived Link stream (mTLS); once the stream is open the gateway pushes send
+// Commands down it and the bot returns one Ack per command. This keeps the bot
+// egress (the Bot API token, getUpdates long-poll and sendMessage) off the main
+// host with no inbound port on the bot. See docs/ARCHITECTURE.md.
+
+package botlinkv1
+
+import (
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
+	reflect "reflect"
+	v1 "scrabble/pkg/proto/telegram/v1"
+	sync "sync"
+	unsafe "unsafe"
+)
+
+const (
+	// Verify that this generated code is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
+	// Verify that runtime/protoimpl is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
+)
+
+// FromBot is a message the bot sends to the gateway: the opening Hello, then one
+// Ack per Command.
+type FromBot struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Types that are valid to be assigned to Msg:
+	//
+	//	*FromBot_Hello
+	//	*FromBot_Ack
+	Msg           isFromBot_Msg `protobuf_oneof:"msg"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *FromBot) Reset() {
+	*x = FromBot{}
+	mi := &file_botlink_v1_botlink_proto_msgTypes[0]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *FromBot) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*FromBot) ProtoMessage() {}
+
+func (x *FromBot) ProtoReflect() protoreflect.Message {
+	mi := &file_botlink_v1_botlink_proto_msgTypes[0]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use FromBot.ProtoReflect.Descriptor instead.
+func (*FromBot) Descriptor() ([]byte, []int) {
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{0}
+}
+
+func (x *FromBot) GetMsg() isFromBot_Msg {
+	if x != nil {
+		return x.Msg
+	}
+	return nil
+}
+
+func (x *FromBot) GetHello() *Hello {
+	if x != nil {
+		if x, ok := x.Msg.(*FromBot_Hello); ok {
+			return x.Hello
+		}
+	}
+	return nil
+}
+
+func (x *FromBot) GetAck() *Ack {
+	if x != nil {
+		if x, ok := x.Msg.(*FromBot_Ack); ok {
+			return x.Ack
+		}
+	}
+	return nil
+}
+
+type isFromBot_Msg interface {
+	isFromBot_Msg()
+}
+
+type FromBot_Hello struct {
+	Hello *Hello `protobuf:"bytes,1,opt,name=hello,proto3,oneof"`
+}
+
+type FromBot_Ack struct {
+	Ack *Ack `protobuf:"bytes,2,opt,name=ack,proto3,oneof"`
+}
+
+func (*FromBot_Hello) isFromBot_Msg() {}
+
+func (*FromBot_Ack) isFromBot_Msg() {}
+
+// ToBot is a message the gateway sends to the bot. Only Command is carried today.
+type ToBot struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Command       *Command               `protobuf:"bytes,1,opt,name=command,proto3" json:"command,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ToBot) Reset() {
+	*x = ToBot{}
+	mi := &file_botlink_v1_botlink_proto_msgTypes[1]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ToBot) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ToBot) ProtoMessage() {}
+
+func (x *ToBot) ProtoReflect() protoreflect.Message {
+	mi := &file_botlink_v1_botlink_proto_msgTypes[1]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ToBot.ProtoReflect.Descriptor instead.
+func (*ToBot) Descriptor() ([]byte, []int) {
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{1}
+}
+
+func (x *ToBot) GetCommand() *Command {
+	if x != nil {
+		return x.Command
+	}
+	return nil
+}
+
+// Hello registers the bot on connect. instance_id identifies the bot process for
+// gateway-side logging and metrics; owns_updates reports whether this bot runs the
+// exclusive getUpdates long-poll (exactly one bot must, else Telegram returns 409).
+type Hello struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	InstanceId    string                 `protobuf:"bytes,1,opt,name=instance_id,json=instanceId,proto3" json:"instance_id,omitempty"`
+	OwnsUpdates   bool                   `protobuf:"varint,2,opt,name=owns_updates,json=ownsUpdates,proto3" json:"owns_updates,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *Hello) Reset() {
+	*x = Hello{}
+	mi := &file_botlink_v1_botlink_proto_msgTypes[2]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Hello) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Hello) ProtoMessage() {}
+
+func (x *Hello) ProtoReflect() protoreflect.Message {
+	mi := &file_botlink_v1_botlink_proto_msgTypes[2]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Hello.ProtoReflect.Descriptor instead.
+func (*Hello) Descriptor() ([]byte, []int) {
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{2}
+}
+
+func (x *Hello) GetInstanceId() string {
+	if x != nil {
+		return x.InstanceId
+	}
+	return ""
+}
+
+func (x *Hello) GetOwnsUpdates() bool {
+	if x != nil {
+		return x.OwnsUpdates
+	}
+	return false
+}
+
+// Command is one send instruction addressed by command_id, which the bot echoes in
+// its Ack. Exactly one payload is set; the payloads reuse the connector request
+// shapes from scrabble.telegram.v1.
+type Command struct {
+	state     protoimpl.MessageState `protogen:"open.v1"`
+	CommandId string                 `protobuf:"bytes,1,opt,name=command_id,json=commandId,proto3" json:"command_id,omitempty"`
+	// Types that are valid to be assigned to Payload:
+	//
+	//	*Command_Notify
+	//	*Command_SendToUser
+	//	*Command_SendToChannel
+	Payload       isCommand_Payload `protobuf_oneof:"payload"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *Command) Reset() {
+	*x = Command{}
+	mi := &file_botlink_v1_botlink_proto_msgTypes[3]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Command) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Command) ProtoMessage() {}
+
+func (x *Command) ProtoReflect() protoreflect.Message {
+	mi := &file_botlink_v1_botlink_proto_msgTypes[3]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Command.ProtoReflect.Descriptor instead.
+func (*Command) Descriptor() ([]byte, []int) {
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{3}
+}
+
+func (x *Command) GetCommandId() string {
+	if x != nil {
+		return x.CommandId
+	}
+	return ""
+}
+
+func (x *Command) GetPayload() isCommand_Payload {
+	if x != nil {
+		return x.Payload
+	}
+	return nil
+}
+
+func (x *Command) GetNotify() *v1.NotifyRequest {
+	if x != nil {
+		if x, ok := x.Payload.(*Command_Notify); ok {
+			return x.Notify
+		}
+	}
+	return nil
+}
+
+func (x *Command) GetSendToUser() *v1.SendToUserRequest {
+	if x != nil {
+		if x, ok := x.Payload.(*Command_SendToUser); ok {
+			return x.SendToUser
+		}
+	}
+	return nil
+}
+
+func (x *Command) GetSendToChannel() *v1.SendToGameChannelRequest {
+	if x != nil {
+		if x, ok := x.Payload.(*Command_SendToChannel); ok {
+			return x.SendToChannel
+		}
+	}
+	return nil
+}
+
+type isCommand_Payload interface {
+	isCommand_Payload()
+}
+
+type Command_Notify struct {
+	Notify *v1.NotifyRequest `protobuf:"bytes,2,opt,name=notify,proto3,oneof"`
+}
+
+type Command_SendToUser struct {
+	SendToUser *v1.SendToUserRequest `protobuf:"bytes,3,opt,name=send_to_user,json=sendToUser,proto3,oneof"`
+}
+
+type Command_SendToChannel struct {
+	SendToChannel *v1.SendToGameChannelRequest `protobuf:"bytes,4,opt,name=send_to_channel,json=sendToChannel,proto3,oneof"`
+}
+
+func (*Command_Notify) isCommand_Payload() {}
+
+func (*Command_SendToUser) isCommand_Payload() {}
+
+func (*Command_SendToChannel) isCommand_Payload() {}
+
+// Ack reports the outcome of the Command with command_id. delivered mirrors the
+// connector delivery semantics (false when the kind is not rendered out-of-app, the
+// user never started the bot, or no channel is configured); error carries an
+// unexpected transport/render failure, distinct from a clean not-delivered.
+type Ack struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	CommandId     string                 `protobuf:"bytes,1,opt,name=command_id,json=commandId,proto3" json:"command_id,omitempty"`
+	Delivered     bool                   `protobuf:"varint,2,opt,name=delivered,proto3" json:"delivered,omitempty"`
+	Error         string                 `protobuf:"bytes,3,opt,name=error,proto3" json:"error,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *Ack) Reset() {
+	*x = Ack{}
+	mi := &file_botlink_v1_botlink_proto_msgTypes[4]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Ack) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Ack) ProtoMessage() {}
+
+func (x *Ack) ProtoReflect() protoreflect.Message {
+	mi := &file_botlink_v1_botlink_proto_msgTypes[4]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Ack.ProtoReflect.Descriptor instead.
+func (*Ack) Descriptor() ([]byte, []int) {
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{4}
+}
+
+func (x *Ack) GetCommandId() string {
+	if x != nil {
+		return x.CommandId
+	}
+	return ""
+}
+
+func (x *Ack) GetDelivered() bool {
+	if x != nil {
+		return x.Delivered
+	}
+	return false
+}
+
+func (x *Ack) GetError() string {
+	if x != nil {
+		return x.Error
+	}
+	return ""
+}
+
+var File_botlink_v1_botlink_proto protoreflect.FileDescriptor
+
+const file_botlink_v1_botlink_proto_rawDesc = "" +
+	"\n" +
+	"\x18botlink/v1/botlink.proto\x12\x13scrabble.botlink.v1\x1a\x1atelegram/v1/telegram.proto\"r\n" +
+	"\aFromBot\x122\n" +
+	"\x05hello\x18\x01 \x01(\v2\x1a.scrabble.botlink.v1.HelloH\x00R\x05hello\x12,\n" +
+	"\x03ack\x18\x02 \x01(\v2\x18.scrabble.botlink.v1.AckH\x00R\x03ackB\x05\n" +
+	"\x03msg\"?\n" +
+	"\x05ToBot\x126\n" +
+	"\acommand\x18\x01 \x01(\v2\x1c.scrabble.botlink.v1.CommandR\acommand\"K\n" +
+	"\x05Hello\x12\x1f\n" +
+	"\vinstance_id\x18\x01 \x01(\tR\n" +
+	"instanceId\x12!\n" +
+	"\fowns_updates\x18\x02 \x01(\bR\vownsUpdates\"\x99\x02\n" +
+	"\aCommand\x12\x1d\n" +
+	"\n" +
+	"command_id\x18\x01 \x01(\tR\tcommandId\x12=\n" +
+	"\x06notify\x18\x02 \x01(\v2#.scrabble.telegram.v1.NotifyRequestH\x00R\x06notify\x12K\n" +
+	"\fsend_to_user\x18\x03 \x01(\v2'.scrabble.telegram.v1.SendToUserRequestH\x00R\n" +
+	"sendToUser\x12X\n" +
+	"\x0fsend_to_channel\x18\x04 \x01(\v2..scrabble.telegram.v1.SendToGameChannelRequestH\x00R\rsendToChannelB\t\n" +
+	"\apayload\"X\n" +
+	"\x03Ack\x12\x1d\n" +
+	"\n" +
+	"command_id\x18\x01 \x01(\tR\tcommandId\x12\x1c\n" +
+	"\tdelivered\x18\x02 \x01(\bR\tdelivered\x12\x14\n" +
+	"\x05error\x18\x03 \x01(\tR\x05error2O\n" +
+	"\aBotLink\x12D\n" +
+	"\x04Link\x12\x1c.scrabble.botlink.v1.FromBot\x1a\x1a.scrabble.botlink.v1.ToBot(\x010\x01B)Z'scrabble/pkg/proto/botlink/v1;botlinkv1b\x06proto3"
+
+var (
+	file_botlink_v1_botlink_proto_rawDescOnce sync.Once
+	file_botlink_v1_botlink_proto_rawDescData []byte
+)
+
+func file_botlink_v1_botlink_proto_rawDescGZIP() []byte {
+	file_botlink_v1_botlink_proto_rawDescOnce.Do(func() {
+		file_botlink_v1_botlink_proto_rawDescData = protoimpl.X.CompressGZIP(unsafe.Slice(unsafe.StringData(file_botlink_v1_botlink_proto_rawDesc), len(file_botlink_v1_botlink_proto_rawDesc)))
+	})
+	return file_botlink_v1_botlink_proto_rawDescData
+}
+
+var file_botlink_v1_botlink_proto_msgTypes = make([]protoimpl.MessageInfo, 5)
+var file_botlink_v1_botlink_proto_goTypes = []any{
+	(*FromBot)(nil),                     // 0: scrabble.botlink.v1.FromBot
+	(*ToBot)(nil),                       // 1: scrabble.botlink.v1.ToBot
+	(*Hello)(nil),                       // 2: scrabble.botlink.v1.Hello
+	(*Command)(nil),                     // 3: scrabble.botlink.v1.Command
+	(*Ack)(nil),                         // 4: scrabble.botlink.v1.Ack
+	(*v1.NotifyRequest)(nil),            // 5: scrabble.telegram.v1.NotifyRequest
+	(*v1.SendToUserRequest)(nil),        // 6: scrabble.telegram.v1.SendToUserRequest
+	(*v1.SendToGameChannelRequest)(nil), // 7: scrabble.telegram.v1.SendToGameChannelRequest
+}
+var file_botlink_v1_botlink_proto_depIdxs = []int32{
+	2, // 0: scrabble.botlink.v1.FromBot.hello:type_name -> scrabble.botlink.v1.Hello
+	4, // 1: scrabble.botlink.v1.FromBot.ack:type_name -> scrabble.botlink.v1.Ack
+	3, // 2: scrabble.botlink.v1.ToBot.command:type_name -> scrabble.botlink.v1.Command
+	5, // 3: scrabble.botlink.v1.Command.notify:type_name -> scrabble.telegram.v1.NotifyRequest
+	6, // 4: scrabble.botlink.v1.Command.send_to_user:type_name -> scrabble.telegram.v1.SendToUserRequest
+	7, // 5: scrabble.botlink.v1.Command.send_to_channel:type_name -> scrabble.telegram.v1.SendToGameChannelRequest
+	0, // 6: scrabble.botlink.v1.BotLink.Link:input_type -> scrabble.botlink.v1.FromBot
+	1, // 7: scrabble.botlink.v1.BotLink.Link:output_type -> scrabble.botlink.v1.ToBot
+	7, // [7:8] is the sub-list for method output_type
+	6, // [6:7] is the sub-list for method input_type
+	6, // [6:6] is the sub-list for extension type_name
+	6, // [6:6] is the sub-list for extension extendee
+	0, // [0:6] is the sub-list for field type_name
+}
+
+func init() { file_botlink_v1_botlink_proto_init() }
+func file_botlink_v1_botlink_proto_init() {
+	if File_botlink_v1_botlink_proto != nil {
+		return
+	}
+	file_botlink_v1_botlink_proto_msgTypes[0].OneofWrappers = []any{
+		(*FromBot_Hello)(nil),
+		(*FromBot_Ack)(nil),
+	}
+	file_botlink_v1_botlink_proto_msgTypes[3].OneofWrappers = []any{
+		(*Command_Notify)(nil),
+		(*Command_SendToUser)(nil),
+		(*Command_SendToChannel)(nil),
+	}
+	type x struct{}
+	out := protoimpl.TypeBuilder{
+		File: protoimpl.DescBuilder{
+			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
+			RawDescriptor: unsafe.Slice(unsafe.StringData(file_botlink_v1_botlink_proto_rawDesc), len(file_botlink_v1_botlink_proto_rawDesc)),
+			NumEnums:      0,
+			NumMessages:   5,
+			NumExtensions: 0,
+			NumServices:   1,
+		},
+		GoTypes:           file_botlink_v1_botlink_proto_goTypes,
+		DependencyIndexes: file_botlink_v1_botlink_proto_depIdxs,
+		MessageInfos:      file_botlink_v1_botlink_proto_msgTypes,
+	}.Build()
+	File_botlink_v1_botlink_proto = out.File
+	file_botlink_v1_botlink_proto_goTypes = nil
+	file_botlink_v1_botlink_proto_depIdxs = nil
+}
@@ -0,0 +1,67 @@
+syntax = "proto3";
+
+// Package scrabble.botlink.v1 is the reverse control channel between a remote
+// Telegram bot and the gateway. The bot dials the gateway and opens a single
+// long-lived Link stream (mTLS); once the stream is open the gateway pushes send
+// Commands down it and the bot returns one Ack per command. This keeps the bot
+// egress (the Bot API token, getUpdates long-poll and sendMessage) off the main
+// host with no inbound port on the bot. See docs/ARCHITECTURE.md.
+package scrabble.botlink.v1;
+
+option go_package = "scrabble/pkg/proto/botlink/v1;botlinkv1";
+
+import "telegram/v1/telegram.proto";
+
+// BotLink is the reverse (bot-dials-gateway) control channel. The bot is the gRPC
+// client; once the stream is open the gateway (server) sends Commands at will and
+// the bot returns one Ack per command. Delivery is best-effort, at-most-once: a
+// command lost across a reconnect is not replayed.
+service BotLink {
+  // Link opens the single bot <-> gateway stream. The first client message is
+  // Hello; thereafter the client sends one Ack per received Command.
+  rpc Link(stream FromBot) returns (stream ToBot);
+}
+
+// FromBot is a message the bot sends to the gateway: the opening Hello, then one
+// Ack per Command.
+message FromBot {
+  oneof msg {
+    Hello hello = 1;
+    Ack ack = 2;
+  }
+}
+
+// ToBot is a message the gateway sends to the bot. Only Command is carried today.
+message ToBot {
+  Command command = 1;
+}
+
+// Hello registers the bot on connect. instance_id identifies the bot process for
+// gateway-side logging and metrics; owns_updates reports whether this bot runs the
+// exclusive getUpdates long-poll (exactly one bot must, else Telegram returns 409).
+message Hello {
+  string instance_id = 1;
+  bool owns_updates = 2;
+}
+
+// Command is one send instruction addressed by command_id, which the bot echoes in
+// its Ack. Exactly one payload is set; the payloads reuse the connector request
+// shapes from scrabble.telegram.v1.
+message Command {
+  string command_id = 1;
+  oneof payload {
+    scrabble.telegram.v1.NotifyRequest notify = 2;
+    scrabble.telegram.v1.SendToUserRequest send_to_user = 3;
+    scrabble.telegram.v1.SendToGameChannelRequest send_to_channel = 4;
+  }
+}
+
+// Ack reports the outcome of the Command with command_id. delivered mirrors the
+// connector delivery semantics (false when the kind is not rendered out-of-app, the
+// user never started the bot, or no channel is configured); error carries an
+// unexpected transport/render failure, distinct from a clean not-delivered.
+message Ack {
+  string command_id = 1;
+  bool delivered = 2;
+  string error = 3;
+}
@@ -0,0 +1,136 @@
+// Code generated by protoc-gen-go-grpc. DO NOT EDIT.
+// versions:
+// - protoc-gen-go-grpc v1.5.1
+// - protoc             (unknown)
+// source: botlink/v1/botlink.proto
+
+// Package scrabble.botlink.v1 is the reverse control channel between a remote
+// Telegram bot and the gateway. The bot dials the gateway and opens a single
+// long-lived Link stream (mTLS); once the stream is open the gateway pushes send
+// Commands down it and the bot returns one Ack per command. This keeps the bot
+// egress (the Bot API token, getUpdates long-poll and sendMessage) off the main
+// host with no inbound port on the bot. See docs/ARCHITECTURE.md.
+
+package botlinkv1
+
+import (
+	context "context"
+	grpc "google.golang.org/grpc"
+	codes "google.golang.org/grpc/codes"
+	status "google.golang.org/grpc/status"
+)
+
+// This is a compile-time assertion to ensure that this generated file
+// is compatible with the grpc package it is being compiled against.
+// Requires gRPC-Go v1.64.0 or later.
+const _ = grpc.SupportPackageIsVersion9
+
+const (
+	BotLink_Link_FullMethodName = "/scrabble.botlink.v1.BotLink/Link"
+)
+
+// BotLinkClient is the client API for BotLink service.
+//
+// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.
+//
+// BotLink is the reverse (bot-dials-gateway) control channel. The bot is the gRPC
+// client; once the stream is open the gateway (server) sends Commands at will and
+// the bot returns one Ack per command. Delivery is best-effort, at-most-once: a
+// command lost across a reconnect is not replayed.
+type BotLinkClient interface {
+	// Link opens the single bot <-> gateway stream. The first client message is
+	// Hello; thereafter the client sends one Ack per received Command.
+	Link(ctx context.Context, opts ...grpc.CallOption) (grpc.BidiStreamingClient[FromBot, ToBot], error)
+}
+
+type botLinkClient struct {
+	cc grpc.ClientConnInterface
+}
+
+func NewBotLinkClient(cc grpc.ClientConnInterface) BotLinkClient {
+	return &botLinkClient{cc}
+}
+
+func (c *botLinkClient) Link(ctx context.Context, opts ...grpc.CallOption) (grpc.BidiStreamingClient[FromBot, ToBot], error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	stream, err := c.cc.NewStream(ctx, &BotLink_ServiceDesc.Streams[0], BotLink_Link_FullMethodName, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	x := &grpc.GenericClientStream[FromBot, ToBot]{ClientStream: stream}
+	return x, nil
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type BotLink_LinkClient = grpc.BidiStreamingClient[FromBot, ToBot]
+
+// BotLinkServer is the server API for BotLink service.
+// All implementations must embed UnimplementedBotLinkServer
+// for forward compatibility.
+//
+// BotLink is the reverse (bot-dials-gateway) control channel. The bot is the gRPC
+// client; once the stream is open the gateway (server) sends Commands at will and
+// the bot returns one Ack per command. Delivery is best-effort, at-most-once: a
+// command lost across a reconnect is not replayed.
+type BotLinkServer interface {
+	// Link opens the single bot <-> gateway stream. The first client message is
+	// Hello; thereafter the client sends one Ack per received Command.
+	Link(grpc.BidiStreamingServer[FromBot, ToBot]) error
+	mustEmbedUnimplementedBotLinkServer()
+}
+
+// UnimplementedBotLinkServer must be embedded to have
+// forward compatible implementations.
+//
+// NOTE: this should be embedded by value instead of pointer to avoid a nil
+// pointer dereference when methods are called.
+type UnimplementedBotLinkServer struct{}
+
+func (UnimplementedBotLinkServer) Link(grpc.BidiStreamingServer[FromBot, ToBot]) error {
+	return status.Errorf(codes.Unimplemented, "method Link not implemented")
+}
+func (UnimplementedBotLinkServer) mustEmbedUnimplementedBotLinkServer() {}
+func (UnimplementedBotLinkServer) testEmbeddedByValue()                 {}
+
+// UnsafeBotLinkServer may be embedded to opt out of forward compatibility for this service.
+// Use of this interface is not recommended, as added methods to BotLinkServer will
+// result in compilation errors.
+type UnsafeBotLinkServer interface {
+	mustEmbedUnimplementedBotLinkServer()
+}
+
+func RegisterBotLinkServer(s grpc.ServiceRegistrar, srv BotLinkServer) {
+	// If the following call pancis, it indicates UnimplementedBotLinkServer was
+	// embedded by pointer and is nil.  This will cause panics if an
+	// unimplemented method is ever invoked, so we test this at initialization
+	// time to prevent it from happening at runtime later due to I/O.
+	if t, ok := srv.(interface{ testEmbeddedByValue() }); ok {
+		t.testEmbeddedByValue()
+	}
+	s.RegisterService(&BotLink_ServiceDesc, srv)
+}
+
+func _BotLink_Link_Handler(srv interface{}, stream grpc.ServerStream) error {
+	return srv.(BotLinkServer).Link(&grpc.GenericServerStream[FromBot, ToBot]{ServerStream: stream})
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type BotLink_LinkServer = grpc.BidiStreamingServer[FromBot, ToBot]
+
+// BotLink_ServiceDesc is the grpc.ServiceDesc for BotLink service.
+// It's only intended for direct use with grpc.RegisterService,
+// and not to be introspected or modified (even as a copy)
+var BotLink_ServiceDesc = grpc.ServiceDesc{
+	ServiceName: "scrabble.botlink.v1.BotLink",
+	HandlerType: (*BotLinkServer)(nil),
+	Methods:     []grpc.MethodDesc{},
+	Streams: []grpc.StreamDesc{
+		{
+			StreamName:    "Link",
+			Handler:       _BotLink_Link_Handler,
+			ServerStreams: true,
+			ClientStreams: true,
+		},
+	},
+	Metadata: "botlink/v1/botlink.proto",
+}