From e71e40eef5da3fe97841acc788bd4a3639258b9b Mon Sep 17 00:00:00 2001 From: Ilia Denisov Date: Sun, 21 Jun 2026 14:46:51 +0200 Subject: [PATCH] feat(telegram): promo bot + channel-chat moderation gate Add a second standalone promo bot to the bot container (answers /start with a localized message + a URL button into the main bot's Mini App) and gate write access in a channel's linked discussion chat: grant on join when the Telegram user is registered and neither admin-suspended nor holding a new chat_muted role, and revoke/grant on the matching moderation change for a member currently in the chat. Eligibility (registered AND NOT suspended AND NOT chat_muted; the game suspension dominates) is resolved once in the backend and reached two ways: the bot's join-time unary ResolveChatEligibility over the existing mTLS bot-link, and a backend chat_access_changed event -> gateway -> ChatGate command (idempotent; a temporary-block-expiry sweeper may over-emit). The bot guards the block/unblock path with getChatMember, since bots cannot list members. A web_app button cannot open another bot's Mini App (it signs initData with the sending bot's token), so the promo button is a t.me ?startapp URL reusing the UI's VITE_TELEGRAM_LINK. The bot must be a chat admin with the restrict-members right and chat_member in its allowed updates. No schema change: chat_muted reuses the data-driven account_roles table. --- .gitea/workflows/ci.yaml | 5 + PRERELEASE.md | 32 +++ backend/README.md | 7 + backend/cmd/backend/main.go | 10 + backend/internal/account/account.go | 8 + backend/internal/account/roles.go | 10 +- backend/internal/account/suspension.go | 25 ++ .../internal/account/suspension_sweeper.go | 84 ++++++ .../account/suspension_sweeper_test.go | 80 ++++++ backend/internal/inttest/chat_access_test.go | 272 ++++++++++++++++++ backend/internal/notify/events.go | 10 + backend/internal/notify/notify.go | 7 + backend/internal/server/chataccess.go | 131 +++++++++ backend/internal/server/handlers.go | 7 + .../internal/server/handlers_admin_console.go | 6 + .../server/handlers_admin_feedback.go | 6 + deploy/.env.example | 4 + deploy/docker-compose.yml | 10 + docs/ARCHITECTURE.md | 25 +- docs/FUNCTIONAL.md | 13 +- docs/FUNCTIONAL_ru.md | 13 +- gateway/cmd/gateway/main.go | 36 ++- gateway/internal/backendclient/api.go | 28 ++ gateway/internal/botlink/command.go | 12 + gateway/internal/botlink/hub.go | 39 ++- gateway/internal/botlink/hub_test.go | 70 ++++- gateway/internal/botlink/mtls_test.go | 2 +- pkg/proto/botlink/v1/botlink.pb.go | 241 ++++++++++++++-- pkg/proto/botlink/v1/botlink.proto | 34 +++ pkg/proto/botlink/v1/botlink_grpc.pb.go | 53 +++- platform/telegram/README.md | 25 +- platform/telegram/cmd/bot/main.go | 39 ++- platform/telegram/internal/bot/bot.go | 158 +++++++++- platform/telegram/internal/bot/chat_test.go | 165 +++++++++++ platform/telegram/internal/botlink/client.go | 53 ++-- .../telegram/internal/botlink/client_test.go | 6 +- .../telegram/internal/botlink/executor.go | 23 ++ .../internal/botlink/executor_test.go | 57 +++- platform/telegram/internal/config/config.go | 27 ++ .../telegram/internal/config/config_test.go | 48 ++++ .../telegram/internal/promobot/promobot.go | 164 +++++++++++ .../internal/promobot/promobot_test.go | 105 +++++++ 42 files changed, 2082 insertions(+), 68 deletions(-) create mode 100644 backend/internal/account/suspension_sweeper.go create mode 100644 backend/internal/account/suspension_sweeper_test.go create mode 100644 backend/internal/inttest/chat_access_test.go create mode 100644 backend/internal/server/chataccess.go create mode 100644 platform/telegram/internal/bot/chat_test.go create mode 100644 platform/telegram/internal/promobot/promobot.go create mode 100644 platform/telegram/internal/promobot/promobot_test.go diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 2af44b9..1299e62 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -260,11 +260,16 @@ jobs: GM_BASICAUTH_HASH: ${{ secrets.TEST_GM_BASICAUTH_HASH }} GRAFANA_ADMIN_PASSWORD: ${{ secrets.TEST_GRAFANA_ADMIN_PASSWORD }} TELEGRAM_BOT_TOKEN: ${{ secrets.TEST_TELEGRAM_BOT_TOKEN }} + TELEGRAM_PROMO_BOT_TOKEN: ${{ secrets.TEST_TELEGRAM_PROMO_BOT_TOKEN }} GM_BASICAUTH_USER: ${{ vars.TEST_GM_BASICAUTH_USER }} GRAFANA_ROOT_URL: ${{ vars.TEST_GRAFANA_ROOT_URL }} CADDY_SITE_ADDRESS: ${{ vars.TEST_CADDY_SITE_ADDRESS }} TELEGRAM_MINIAPP_URL: ${{ vars.TEST_TELEGRAM_MINIAPP_URL }} TELEGRAM_GAME_CHANNEL_ID: ${{ vars.TEST_TELEGRAM_GAME_CHANNEL_ID }} + TELEGRAM_CHAT_ID: ${{ vars.TEST_TELEGRAM_CHAT_ID }} + TELEGRAM_BOT_USERNAME: ${{ vars.TEST_TELEGRAM_BOT_USERNAME }} + # The promo button reuses the UI's Mini App link variable. + TELEGRAM_BOT_LINK: ${{ vars.TEST_VITE_TELEGRAM_LINK }} # The test contour always uses Telegram's test environment — pinned here, # not an operator variable. The prod workflow leaves it false. TELEGRAM_TEST_ENV: "true" diff --git a/PRERELEASE.md b/PRERELEASE.md index 718f609..db9dcba 100644 --- a/PRERELEASE.md +++ b/PRERELEASE.md @@ -41,6 +41,7 @@ the edge before prod. Each phase maps back to the owner's raw pre-release TODO l | DV | Dictionary version hygiene: CI + image/compose seed track the current release (`v1.2.1`); a **seed-drift guard** records the flat dir's seed in an authoritative `.seed_version` marker so a bumped build seed on a live volume is ignored (it can't relabel live bytes — which would mis-serve the dictionary + void games pinned to the prior label); `DICT_VERSION` is the fresh-volume seed only, a live contour migrates through the admin console | owner ad-hoc | **done** | | TX | Telegram egress off the main host: split the connector into a home **validator** (Mini App / Login-Widget HMAC, no VPN, no Bot API — so game login no longer depends on Telegram being reachable) and a remote **bot** (Bot API long-poll + `sendMessage`) that holds **no inbound port** and dials the gateway over a reverse **mTLS bot-link** (`pkg/proto/botlink/v1`); the gateway funnels out-of-app push (fire-and-forget, at-most-once) and the backend admin broadcasts (a relay that awaits the bot's ack) down the link. The bot is Telegram-rate-limited; **one bot now**, with seams (a bot registry + `owns_updates` + command ids) for N later; **no 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; certs from `deploy/gen-certs.sh`). 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** (Stage 18). | owner ad-hoc | **done** (code + test contour; prod wiring → Stage 18) | | AG | Anti-abuse IP ban + honeypot/honeytoken (prod-only): a fail2ban-style in-memory `ratelimit.Banlist` keyed by client IP, fed by sustained rate-limiter rejections (the IP-keyed public/email/admin classes — the user class stays the soft-flag's concern), a **honeypot** decoy path (the contour caddy tags `/.env`, `/.git`, `/wp-*`, … with `X-Scrabble-Honeypot` and routes them to the gateway), and a **honeytoken** (`GATEWAY_HONEYTOKEN`, a planted bearer). The `abuseGuard` edge middleware refuses a banned IP with **429** before any work — closing the R3 gap that the static SPA/landing was outside the token bucket. Off by default — it keys by the real client IP the shared-NAT test contour does not expose (detection still logs there); enabled in prod via `GATEWAY_ABUSE_BAN_ENABLED`. Operators see + lift bans on the console **Throttled** page; the gateway syncs its active set to the backend (`/api/v1/internal/bans/sync`, `internal/banview`) every 30 s and applies operator unbans. | owner ad-hoc | **done** (code + test contour; ban enabled in prod → Stage 18) | +| CM | Channel-chat moderation + promo bot: a second standalone bot in the bot container answers `/start` with a localized message + a **URL** button into the **main** bot's Mini App (`?startapp`; a `web_app` button would sign initData with the promo token, which the main validator rejects). The **main** bot gates write access in a channel's linked discussion chat — granting on join when the Telegram user is registered and neither admin-suspended nor holding a new **`chat_muted`** role, and revoking/granting on the matching moderation change for a member currently in the chat (a `getChatMember` guard, since bots cannot list members). Eligibility = `registered AND NOT suspended AND NOT chat_muted` (the game suspension dominates), resolved once in the backend and reached two ways: the bot's join-time unary `ResolveChatEligibility` over the existing mTLS bot-link, and a backend `chat_access_changed` event → gateway → `ChatGate` command (idempotent, so a temporary-block-expiry sweeper may over-emit). No schema change — `chat_muted` reuses `account_roles`. | owner ad-hoc | **done** | | → | Stage 18 — prod contour deploy | — | see [`PLAN.md`](PLAN.md) | ## Key findings (these reshaped the raw list — read before starting a phase) @@ -579,3 +580,34 @@ Then Stage 18. (`game_limit_test.go`: count rule + HTTP gate 409 + accept bypass), server unit (error mapping), gateway transcode round-trip, UI codec + lobbycache unit, e2e (`gamelimit.spec.ts`). Bake-back: `docs/FUNCTIONAL.md` (+`_ru`), `docs/ARCHITECTURE.md` §8, `docs/UI_DESIGN.md`, `backend/README.md`. + +- **CM — Channel-chat moderation + promo bot** (owner ad-hoc, not on the raw TODO list): + - **Locked decisions (interview):** the promo bot is a **goroutine in `cmd/bot`** (its own token, no + bot-link); the moderated chat's default-no-send is configured by a **human** in the group settings (the + bot only grants, never `setChatPermissions`); a non-eligible joiner is **left muted silently**; a + temporary-suspension expiry is handled by a **backend sweeper** that emits the re-evaluate event; and a new + **`chat_muted` role** is a chat-only mute with the **game suspension dominating** + (`eligible = registered AND NOT suspended AND NOT chat_muted`). + - **Bot API reality (verified against the docs):** a cross-bot Mini App launch must be a **URL button** to the + main bot's `t.me/?startapp` link — a `web_app` button signs initData with the *sending* bot's token, + which the main validator rejects — so the promo button reuses the UI's `VITE_TELEGRAM_LINK`. `chat_member` + updates arrive **only** when the bot is a chat **admin** with the "Ban users" right (the client label for the + Bot API `can_restrict_members`) and `chat_member` is in `allowed_updates`; bots cannot list members but can + `getChatMember` a single user, which is the membership guard on the block/unblock path. + - **Wire:** `pkg/proto/botlink/v1` gains a `ChatGateCommand` in the `Command` oneof and a unary + `ResolveChatEligibility`; the backend gains `notify.KindChatAccessChanged` (no payload, infra-only — never an + out-of-app message) and an internal `POST /api/v1/internal/chat-access` resolver; the gateway resolves the + join (by external_id) and the event (by user_id) through it and pushes the chat-gate command fire-and-forget + (at-most-once, recovered by the next moderation action or a re-join). + - **No schema change → no contour DB wipe:** `chat_muted` is a new `account.KnownRoles` entry (the + `account_roles` table is data-driven). The suspension-expiry sweeper is a new `account.SuspensionSweeper` + (a 1-minute window, idempotent) started in `cmd/backend`, alongside the guest reaper. + - **Deploy:** new `TEST_`/`PROD_` `TELEGRAM_PROMO_BOT_TOKEN` (secret), `TELEGRAM_BOT_USERNAME` and + `TELEGRAM_CHAT_ID` (variables); the promo link reuses the existing `*_VITE_TELEGRAM_LINK` variable as + `TELEGRAM_BOT_LINK`. The bot must be promoted to admin in the real discussion group, and the group default + set to no-send, as part of the Stage 18 prod cutover (the test contour exercises the code path). + - **Bake-back:** `docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md` (+`_ru`), `platform/telegram/README.md`, + `backend/README.md`, Go Doc comments. Tests: backend resolver truth table + publish on block/unblock/role + + the sweeper window (unit + integration); gateway hub `ResolveChatEligibility` + the chat-gate command; bot + `chat_member` grant + `ApplyChatGate` getChatMember-guard; promo `/start` localization + URL button; config + parsing. diff --git a/backend/README.md b/backend/README.md index bde9d55..a833500 100644 --- a/backend/README.md +++ b/backend/README.md @@ -106,6 +106,13 @@ Telegram `external_id`, language and `notifications_in_app_only` flag) lets the route out-of-app push to the Telegram bot over the gateway bot-link; the Telegram login seeds a new account's language and display name from the launch fields, and the `accounts.notifications_in_app_only` flag (default true). +The gateway-only `POST /api/v1/internal/chat-access` resolves a Telegram identity (the +bot's join-time query) or an account id (a `chat_access_changed` event) to its +**moderated-chat write eligibility** — `registered AND NOT suspended AND NOT chat_muted`. +That event is emitted on an admin block/unblock, a `chat_muted` role grant/revoke, or — via +the `account.SuspensionSweeper` started in `cmd/backend` — a temporary block lapsing; +`chat_muted` is an `account.KnownRoles` entry, a chat-only mute distinct from the game +suspension (which dominates it). `accounts.is_guest` marks an ephemeral guest — a durable row with no identity, excluded from statistics. The server-rendered **admin console** at `/_gm` (`internal/adminconsole` + `internal/server/handlers_admin_console.go`; diff --git a/backend/cmd/backend/main.go b/backend/cmd/backend/main.go index c4c17a4..69ee34a 100644 --- a/backend/cmd/backend/main.go +++ b/backend/cmd/backend/main.go @@ -15,6 +15,7 @@ import ( "syscall" "time" + "github.com/google/uuid" "go.uber.org/zap" "scrabble/backend/internal/account" @@ -160,6 +161,15 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error { zap.Duration("interval", cfg.GuestReapInterval), zap.Duration("retention", cfg.GuestRetention)) + // Re-evaluate moderated-chat write access when a temporary block self-expires: + // no operator action fires then, so the sweeper emits the chat-access-changed + // event for lapsed blocks and the gateway re-pushes the chat-gate command. + chatSweeper := account.NewSuspensionSweeper(accounts, func(id uuid.UUID) { + hub.Publish(notify.ChatAccessChanged(id)) + }, logger) + go chatSweeper.Run(ctx) + logger.Info("suspension expiry sweeper started", zap.Duration("interval", chatSweeper.Interval())) + // Lobby & social domains. Their REST and stream surface lives in the gateway, // so they are handed to the server (like the route groups) for the handlers. mailer := newMailer(cfg.SMTP, logger) diff --git a/backend/internal/account/account.go b/backend/internal/account/account.go index 14e143a..1cdacbc 100644 --- a/backend/internal/account/account.go +++ b/backend/internal/account/account.go @@ -303,6 +303,14 @@ func (s *Store) CountAccounts(ctx context.Context) (int, error) { return int(dest.Count), nil } +// AccountByIdentity returns the account bound to (kind, externalID), or ErrNotFound +// when none exists. Unlike ProvisionByIdentity it never creates one: the chat-access +// resolver uses it to tell a registered Telegram user (eligible to be granted chat +// write access) from an unregistered one (left muted). +func (s *Store) AccountByIdentity(ctx context.Context, kind, externalID string) (Account, error) { + return s.findByIdentity(ctx, kind, externalID) +} + // findByIdentity joins identities to accounts and returns the matching account, // or ErrNotFound. func (s *Store) findByIdentity(ctx context.Context, kind, externalID string) (Account, error) { diff --git a/backend/internal/account/roles.go b/backend/internal/account/roles.go index 5aa2725..acc1d6d 100644 --- a/backend/internal/account/roles.go +++ b/backend/internal/account/roles.go @@ -24,11 +24,19 @@ const ( // unconditionally, overriding the usual eligibility (a free account with an // empty hint wallet otherwise sees it). See internal/ads. RoleNoBanner = "no_banner" + + // RoleChatMuted forbids the account from writing in the moderated Telegram + // discussion chat, without otherwise restricting the game (the chat-only + // counterpart to a full account suspension). It is one input to the chat-access + // gate; an active admin suspension mutes the player regardless, so this role only + // matters for an account that is not suspended. Granting or revoking it re-pushes + // the chat-gate command for a member currently in the chat. + RoleChatMuted = "chat_muted" ) // KnownRoles is the set of roles the console may grant or revoke; an operator // cannot assign an unrecognised role. -var KnownRoles = []string{RoleFeedbackBanned, RoleNoBanner} +var KnownRoles = []string{RoleFeedbackBanned, RoleNoBanner, RoleChatMuted} // IsKnownRole reports whether role is a recognised account role. func IsKnownRole(role string) bool { diff --git a/backend/internal/account/suspension.go b/backend/internal/account/suspension.go index 155f289..fe55962 100644 --- a/backend/internal/account/suspension.go +++ b/backend/internal/account/suspension.go @@ -161,6 +161,31 @@ func (s *Store) queryCurrentSuspension(ctx context.Context, accountID uuid.UUID, return modelToSuspension(row), true, nil } +// SuspensionsExpiredBetween returns the distinct account ids whose temporary block lapsed in the +// half-open window (since, until]: a non-lifted suspension with a blocked_until in that range. The +// chat-access sweeper uses it to re-evaluate chat write access when a temporary block self-expires, +// since no operator action fires then. An account that still has another active block may be +// included; the eligibility resolver returns the true state, so emitting for it is harmless. +func (s *Store) SuspensionsExpiredBetween(ctx context.Context, since, until time.Time) ([]uuid.UUID, error) { + rows, err := s.db.QueryContext(ctx, + `SELECT DISTINCT account_id FROM backend.account_suspensions + WHERE lifted_at IS NULL AND blocked_until > $1 AND blocked_until <= $2`, + since.UTC(), until.UTC()) + if err != nil { + return nil, fmt.Errorf("account: suspensions expired between: %w", err) + } + defer rows.Close() + var out []uuid.UUID + for rows.Next() { + var id uuid.UUID + if err := rows.Scan(&id); err != nil { + return nil, fmt.Errorf("account: scan expired suspension: %w", err) + } + out = append(out, id) + } + return out, rows.Err() +} + // invalidateSuspension drops the account's cached block so the next CurrentSuspension re-reads it. // Called after Suspend and LiftSuspension. func (s *Store) invalidateSuspension(accountID uuid.UUID) { diff --git a/backend/internal/account/suspension_sweeper.go b/backend/internal/account/suspension_sweeper.go new file mode 100644 index 0000000..f838398 --- /dev/null +++ b/backend/internal/account/suspension_sweeper.go @@ -0,0 +1,84 @@ +package account + +import ( + "context" + "time" + + "github.com/google/uuid" + "go.uber.org/zap" +) + +// suspensionSweepInterval is how often the sweeper re-checks for temporary blocks +// that lapsed. A minute is well under the coarsest block grain (operators pick day +// presets) while keeping the query trivial. +const suspensionSweepInterval = time.Minute + +// suspensionExpiryQuerier is the slice of the account store the sweeper depends on: +// the accounts whose temporary block lapsed in a window. *Store satisfies it; a fake +// drives the sweeper's unit tests. +type suspensionExpiryQuerier interface { + SuspensionsExpiredBetween(ctx context.Context, since, until time.Time) ([]uuid.UUID, error) +} + +// SuspensionSweeper re-evaluates chat write access when a temporary block self- +// expires. No operator action fires on expiry — the suspension gate just re-reads +// the wall clock — so without this a temporarily blocked player would stay muted in +// the moderated discussion chat after their block lapsed. Each tick it finds blocks +// that expired since the previous tick and calls onExpire for the affected accounts; +// onExpire is wired to publish the chat-access-changed event, after which the gateway +// re-resolves the true eligibility. A liberal call (an account that still has another +// active block) is therefore harmless. The window is in-memory, so a block that +// expires while the process is down is not re-granted until the next operator action +// or the player rejoins — an accepted best-effort gap. +type SuspensionSweeper struct { + store suspensionExpiryQuerier + onExpire func(accountID uuid.UUID) + log *zap.Logger + // since is the upper bound of the previous swept window; the next sweep covers + // (since, now]. It advances only on a successful query, so a failed tick retries + // the same window rather than dropping expiries. + since time.Time +} + +// NewSuspensionSweeper builds the sweeper over the account store, the per-account +// expiry callback (publishing the chat-access-changed event) and a logger. The first +// window opens at construction time, so blocks that lapsed earlier are not re-emitted. +func NewSuspensionSweeper(store *Store, onExpire func(accountID uuid.UUID), log *zap.Logger) *SuspensionSweeper { + if log == nil { + log = zap.NewNop() + } + return &SuspensionSweeper{store: store, onExpire: onExpire, log: log, since: time.Now().UTC()} +} + +// Interval reports the sweep cadence, for the startup log line. +func (w *SuspensionSweeper) Interval() time.Duration { return suspensionSweepInterval } + +// Run sweeps every Interval until ctx is cancelled. +func (w *SuspensionSweeper) Run(ctx context.Context) { + ticker := time.NewTicker(suspensionSweepInterval) + defer ticker.Stop() + for { + select { + case <-ctx.Done(): + return + case <-ticker.C: + w.sweep(ctx) + } + } +} + +// sweep emits a chat-access-changed signal for every account whose temporary block +// lapsed in (since, now], then advances the window. On a query error it keeps the +// window so the next tick retries it. +func (w *SuspensionSweeper) sweep(ctx context.Context) { + now := time.Now().UTC() + ids, err := w.store.SuspensionsExpiredBetween(ctx, w.since, now) + if err != nil { + w.log.Warn("suspension expiry sweep failed", zap.Error(err)) + return + } + w.since = now + for _, id := range ids { + w.onExpire(id) + } +} diff --git a/backend/internal/account/suspension_sweeper_test.go b/backend/internal/account/suspension_sweeper_test.go new file mode 100644 index 0000000..55c5d45 --- /dev/null +++ b/backend/internal/account/suspension_sweeper_test.go @@ -0,0 +1,80 @@ +package account + +import ( + "context" + "errors" + "testing" + "time" + + "github.com/google/uuid" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "go.uber.org/zap" +) + +// fakeExpiryQuerier records the `since` bound of each call and replays a scripted +// result/error per call, so the sweeper's window and dispatch logic is testable +// without a database. +type fakeExpiryQuerier struct { + results [][]uuid.UUID + errs []error + sinces []time.Time + idx int +} + +func (f *fakeExpiryQuerier) SuspensionsExpiredBetween(_ context.Context, since, _ time.Time) ([]uuid.UUID, error) { + f.sinces = append(f.sinces, since) + i := f.idx + f.idx++ + if i < len(f.errs) && f.errs[i] != nil { + return nil, f.errs[i] + } + if i < len(f.results) { + return f.results[i], nil + } + return nil, nil +} + +func newSweeper(store suspensionExpiryQuerier, onExpire func(uuid.UUID)) *SuspensionSweeper { + return &SuspensionSweeper{ + store: store, + onExpire: onExpire, + log: zap.NewNop(), + since: time.Now().Add(-time.Minute).UTC(), + } +} + +func TestSuspensionSweeperDispatchesAndAdvances(t *testing.T) { + id1, id2 := uuid.New(), uuid.New() + fake := &fakeExpiryQuerier{results: [][]uuid.UUID{{id1, id2}, nil}} + var got []uuid.UUID + w := newSweeper(fake, func(id uuid.UUID) { got = append(got, id) }) + + first := w.since + w.sweep(context.Background()) + assert.Equal(t, []uuid.UUID{id1, id2}, got, "every expired account is dispatched") + assert.True(t, w.since.After(first), "the window advances on success") + + // A second sweep opens the next window at the previous upper bound. + prev := w.since + w.sweep(context.Background()) + require.Len(t, fake.sinces, 2) + assert.True(t, fake.sinces[1].After(fake.sinces[0]), "consecutive windows are contiguous and forward") + assert.True(t, fake.sinces[1].Equal(prev), "the next window starts at the previous upper bound") +} + +func TestSuspensionSweeperKeepsWindowOnError(t *testing.T) { + fake := &fakeExpiryQuerier{errs: []error{errors.New("db down")}} + w := newSweeper(fake, func(uuid.UUID) { t.Fatal("onExpire must not run when the query fails") }) + + before := w.since + w.sweep(context.Background()) + assert.True(t, w.since.Equal(before), "the window is retained on error so the next tick retries it") +} + +func TestNewSuspensionSweeperDefaults(t *testing.T) { + w := NewSuspensionSweeper(nil, func(uuid.UUID) {}, nil) + assert.Equal(t, time.Minute, w.Interval()) + assert.NotNil(t, w.log, "a nil logger is tolerated") + assert.WithinDuration(t, time.Now().UTC(), w.since, time.Second, "the first window opens at construction time") +} diff --git a/backend/internal/inttest/chat_access_test.go b/backend/internal/inttest/chat_access_test.go new file mode 100644 index 0000000..065af0d --- /dev/null +++ b/backend/internal/inttest/chat_access_test.go @@ -0,0 +1,272 @@ +//go:build integration + +package inttest + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" + "time" + + "github.com/google/uuid" + "go.uber.org/zap/zaptest" + + "scrabble/backend/internal/account" + "scrabble/backend/internal/notify" + "scrabble/backend/internal/server" +) + +// chatAccessBody mirrors the backend's /internal/chat-access JSON for the test. +type chatAccessBody struct { + ExternalID string `json:"external_id"` + Registered bool `json:"registered"` + Eligible bool `json:"eligible"` +} + +// chatAccess issues the gateway-internal chat-access query and asserts a 200. +func chatAccess(t *testing.T, srv *server.Server, body string) chatAccessBody { + t.Helper() + rec := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/internal/chat-access", strings.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + srv.Handler().ServeHTTP(rec, req) + if rec.Code != http.StatusOK { + t.Fatalf("chat-access %s = %d: %s", body, rec.Code, rec.Body.String()) + } + var b chatAccessBody + if err := json.Unmarshal(rec.Body.Bytes(), &b); err != nil { + t.Fatalf("decode chat-access: %v", err) + } + return b +} + +// TestChatAccessResolver drives the gateway-internal eligibility resolver over HTTP: +// the registered/suspended/chat_muted truth table by Telegram identity and by account +// id, the suspension dominating the chat_muted role, an unknown identity reported +// unregistered, and an account with no Telegram identity carrying an empty external_id. +func TestChatAccessResolver(t *testing.T) { + ctx := context.Background() + accounts := account.NewStore(testDB) + srv := server.New(":0", server.Deps{Logger: zaptest.NewLogger(t), DB: testDB, Accounts: accounts}) + + ext := "tg-" + uuid.NewString() + acc, err := accounts.ProvisionTelegram(ctx, ext, "en", "", "Chatter") + if err != nil { + t.Fatalf("provision: %v", err) + } + id := acc.ID + + byExt := func() chatAccessBody { return chatAccess(t, srv, `{"external_id":"`+ext+`"}`) } + byUser := func() chatAccessBody { return chatAccess(t, srv, `{"user_id":"`+id.String()+`"}`) } + + // A registered, unsuspended, unmuted account is eligible by either address, and the + // account-id query resolves back to its Telegram identity. + if b := byExt(); !b.Registered || !b.Eligible || b.ExternalID != ext { + t.Fatalf("fresh by external_id = %+v, want registered+eligible+ext", b) + } + if b := byUser(); !b.Registered || !b.Eligible || b.ExternalID != ext { + t.Fatalf("fresh by user_id = %+v, want registered+eligible+ext", b) + } + + // A suspension mutes; a lift restores. + if _, err := accounts.Suspend(ctx, id, nil, "", "", nil); err != nil { + t.Fatalf("suspend: %v", err) + } + if b := byExt(); !b.Registered || b.Eligible { + t.Fatalf("suspended = %+v, want registered but not eligible", b) + } + if err := accounts.LiftSuspension(ctx, id); err != nil { + t.Fatalf("lift: %v", err) + } + if b := byExt(); !b.Eligible { + t.Fatalf("after lift = %+v, want eligible", b) + } + + // The chat_muted role mutes independently; a revoke restores. + if err := accounts.GrantRole(ctx, id, account.RoleChatMuted); err != nil { + t.Fatalf("grant chat_muted: %v", err) + } + if b := byExt(); !b.Registered || b.Eligible { + t.Fatalf("chat_muted = %+v, want registered but not eligible", b) + } + + // Suspension dominates: while chat_muted is set, lifting a concurrent suspension + // must not re-grant chat (the role still mutes). + if _, err := accounts.Suspend(ctx, id, nil, "", "", nil); err != nil { + t.Fatalf("suspend over mute: %v", err) + } + if b := byExt(); b.Eligible { + t.Fatalf("suspended+muted = %+v, want not eligible", b) + } + if err := accounts.LiftSuspension(ctx, id); err != nil { + t.Fatalf("lift over mute: %v", err) + } + if b := byExt(); b.Eligible { + t.Fatalf("lifted but still muted = %+v, want not eligible", b) + } + if err := accounts.RevokeRole(ctx, id, account.RoleChatMuted); err != nil { + t.Fatalf("revoke chat_muted: %v", err) + } + if b := byExt(); !b.Eligible { + t.Fatalf("after revoke = %+v, want eligible", b) + } + + // An unknown Telegram identity is unregistered (and thus left muted). + if b := chatAccess(t, srv, `{"external_id":"tg-missing-`+uuid.NewString()+`"}`); b.Registered || b.Eligible { + t.Fatalf("unknown identity = %+v, want neither registered nor eligible", b) + } + + // An account with no Telegram identity (a guest) carries an empty external_id, so + // the gateway has nothing to gate. + guest := provisionGuest(t) + if b := chatAccess(t, srv, `{"user_id":"`+guest.String()+`"}`); b.ExternalID != "" || b.Registered { + t.Fatalf("guest by user_id = %+v, want empty external_id and not registered", b) + } + + // A request naming neither address is a bad request. + rec := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/internal/chat-access", strings.NewReader(`{}`)) + req.Header.Set("Content-Type", "application/json") + srv.Handler().ServeHTTP(rec, req) + if rec.Code != http.StatusBadRequest { + t.Fatalf("empty query = %d, want 400", rec.Code) + } +} + +// captureNotifier records every published intent so a test can assert which live +// events a console action emitted. +type captureNotifier struct { + mu sync.Mutex + intents []notify.Intent +} + +func (c *captureNotifier) Publish(in ...notify.Intent) { + c.mu.Lock() + defer c.mu.Unlock() + c.intents = append(c.intents, in...) +} + +// count returns how many intents of kind addressed to user were captured. +func (c *captureNotifier) count(user uuid.UUID, kind string) int { + c.mu.Lock() + defer c.mu.Unlock() + n := 0 + for _, in := range c.intents { + if in.UserID == user && in.Kind == kind { + n++ + } + } + return n +} + +// TestChatAccessPublishedOnModeration drives the admin console and asserts each +// moderation action that can change chat eligibility — block, unblock, and the +// chat_muted role grant/revoke — emits the chat_access_changed signal the gateway +// turns into a chat-gate command. +func TestChatAccessPublishedOnModeration(t *testing.T) { + notifier := &captureNotifier{} + srv := server.New(":0", server.Deps{ + Logger: zaptest.NewLogger(t), + DB: testDB, + Accounts: account.NewStore(testDB), + Games: newGameService(), + Registry: testRegistry, + DictDir: dictDir(), + Notifier: notifier, + }) + h := srv.Handler() + id := provisionAccount(t) + base := "http://admin.test/_gm/users/" + id.String() + const origin = "http://admin.test" + + steps := []struct { + name, path, body string + want string + }{ + {"block", "/block", "duration=permanent", "Blocked"}, + {"unblock", "/unblock", "", "Unblocked"}, + {"grant chat_muted", "/grant-role", "role=chat_muted", "Role granted"}, + {"revoke chat_muted", "/revoke-role", "role=chat_muted", "Role revoked"}, + } + for i, s := range steps { + code, body := consoleDo(h, http.MethodPost, base+s.path, s.body, origin) + if code != http.StatusOK || !strings.Contains(body, s.want) { + t.Fatalf("%s = %d, has %q = %v", s.name, code, s.want, strings.Contains(body, s.want)) + } + if got := notifier.count(id, notify.KindChatAccessChanged); got != i+1 { + t.Fatalf("after %s: chat_access_changed count = %d, want %d", s.name, got, i+1) + } + } +} + +// TestSuspensionsExpiredBetween checks the sweeper's window query: a non-lifted +// temporary block whose expiry falls in the window is returned, while one outside the +// window, a permanent block, and a lifted block are not. +func TestSuspensionsExpiredBetween(t *testing.T) { + ctx := context.Background() + accounts := account.NewStore(testDB) + + // A temporary block whose expiry already lapsed at a known instant. + tempID := provisionAccount(t) + expiry := time.Now().Add(-time.Hour).Truncate(time.Second) + if _, err := accounts.Suspend(ctx, tempID, &expiry, "", "", nil); err != nil { + t.Fatalf("suspend temp: %v", err) + } + + contains := func(ids []uuid.UUID, want uuid.UUID) bool { + for _, id := range ids { + if id == want { + return true + } + } + return false + } + + // A window straddling the expiry returns the account. + got, err := accounts.SuspensionsExpiredBetween(ctx, expiry.Add(-time.Minute), expiry.Add(time.Minute)) + if err != nil { + t.Fatalf("expired between: %v", err) + } + if !contains(got, tempID) { + t.Fatalf("window over expiry missing the lapsed block %s", tempID) + } + // A window entirely after the expiry does not. + got, err = accounts.SuspensionsExpiredBetween(ctx, expiry.Add(time.Minute), expiry.Add(2*time.Minute)) + if err != nil { + t.Fatalf("expired between (after): %v", err) + } + if contains(got, tempID) { + t.Fatalf("window after expiry should not return %s", tempID) + } + + // A permanent block never appears, even in a wide window. + permID := provisionAccount(t) + if _, err := accounts.Suspend(ctx, permID, nil, "", "", nil); err != nil { + t.Fatalf("suspend perm: %v", err) + } + // A lifted block does not appear either. The block must still be in force when lifted + // (LiftSuspension only lifts in-force blocks), so its expiry is in the future and the + // wide window below still covers it — yet lifted_at excludes it. + liftID := provisionAccount(t) + liftExpiry := time.Now().Add(30 * time.Minute).Truncate(time.Second) + if _, err := accounts.Suspend(ctx, liftID, &liftExpiry, "", "", nil); err != nil { + t.Fatalf("suspend lift: %v", err) + } + if err := accounts.LiftSuspension(ctx, liftID); err != nil { + t.Fatalf("lift: %v", err) + } + wide, err := accounts.SuspensionsExpiredBetween(ctx, time.Now().Add(-2*time.Hour), time.Now().Add(time.Hour)) + if err != nil { + t.Fatalf("expired between (wide): %v", err) + } + if contains(wide, permID) { + t.Fatalf("permanent block %s must not be reported as expired", permID) + } + if contains(wide, liftID) { + t.Fatalf("lifted block %s must not be reported as expired", liftID) + } +} diff --git a/backend/internal/notify/events.go b/backend/internal/notify/events.go index bc9769c..795f287 100644 --- a/backend/internal/notify/events.go +++ b/backend/internal/notify/events.go @@ -216,6 +216,16 @@ func BannerChanged(userID uuid.UUID) Intent { return Notification(userID, NotifyBanner) } +// ChatAccessChanged signals that userID's eligibility to write in the moderated +// Telegram discussion chat may have changed (an admin block/unblock, a chat_muted +// grant/revoke, or a temporary block lapsing). It carries no payload: the gateway +// resolves the user's Telegram identity and current eligibility and pushes the +// resulting chat-gate command to the bot. Unlike the lobby notifications it is an +// infra signal — a distinct top-level kind, never an out-of-app rendered message. +func ChatAccessChanged(userID uuid.UUID) Intent { + return Intent{UserID: userID, Kind: KindChatAccessChanged, EventID: eventID()} +} + // eventID returns a best-effort correlation id for one emitted event. func eventID() string { if id, err := uuid.NewV7(); err == nil { diff --git a/backend/internal/notify/notify.go b/backend/internal/notify/notify.go index 583987a..4b2204a 100644 --- a/backend/internal/notify/notify.go +++ b/backend/internal/notify/notify.go @@ -35,6 +35,13 @@ const ( // KindGameOver announces a finished game to each seated player, driving the // out-of-app "game over" push. KindGameOver = "game_over" + // KindChatAccessChanged signals that a player's eligibility to write in the + // moderated Telegram discussion chat may have changed (an admin block or unblock, + // a chat_muted grant or revoke, or a temporary block lapsing). It carries no + // payload and is never fanned out to in-app clients: the gateway consumes it to + // resolve the player's Telegram identity and current eligibility and push the + // resulting chat-gate command to the bot. + KindChatAccessChanged = "chat_access_changed" ) // Notification sub-kinds carried in a KindNotification event payload; the client diff --git a/backend/internal/server/chataccess.go b/backend/internal/server/chataccess.go new file mode 100644 index 0000000..141b6f3 --- /dev/null +++ b/backend/internal/server/chataccess.go @@ -0,0 +1,131 @@ +package server + +import ( + "context" + "errors" + "net/http" + + "github.com/gin-gonic/gin" + "github.com/google/uuid" + + "scrabble/backend/internal/account" + "scrabble/backend/internal/notify" +) + +// chatAccessRequest is the gateway's chat write-eligibility query, addressed either +// by Telegram identity (ExternalID — the join path, when the bot sees a user enter +// the chat) or by account id (UserID — the change path, resolving an emitted +// chat-access-changed event). Exactly one field is set. +type chatAccessRequest struct { + ExternalID string `json:"external_id"` + UserID string `json:"user_id"` +} + +// chatAccessResponse is the resolved eligibility. ExternalID echoes the account's +// Telegram identity (empty when it has none — the gateway then has nothing to gate); +// Registered reports whether the lookup found an account at all; Eligible is the +// final gate the bot applies (registered and neither admin-suspended nor chat-muted). +type chatAccessResponse struct { + ExternalID string `json:"external_id"` + Registered bool `json:"registered"` + Eligible bool `json:"eligible"` +} + +// handleChatAccess resolves whether a Telegram user may write in the moderated +// discussion chat. It is gateway-internal: the gateway's bot-link serves the bot's +// join-time query (by external_id) and resolves an emitted chat-access-changed event +// (by user_id) through it. +func (s *Server) handleChatAccess(c *gin.Context) { + var req chatAccessRequest + if err := c.ShouldBindJSON(&req); err != nil { + abortBadRequest(c, "invalid body") + return + } + switch { + case req.ExternalID != "": + s.respondChatAccessByExternalID(c, req.ExternalID) + case req.UserID != "": + s.respondChatAccessByUserID(c, req.UserID) + default: + abortBadRequest(c, "external_id or user_id required") + } +} + +// respondChatAccessByExternalID answers the join-path query: an unknown identity is +// reported unregistered (and left muted); a known one carries its current eligibility. +func (s *Server) respondChatAccessByExternalID(c *gin.Context, externalID string) { + ctx := c.Request.Context() + resp := chatAccessResponse{ExternalID: externalID} + acc, err := s.accounts.AccountByIdentity(ctx, account.KindTelegram, externalID) + if errors.Is(err, account.ErrNotFound) { + c.JSON(http.StatusOK, resp) + return + } + if err != nil { + s.abortErr(c, err) + return + } + resp.Registered = true + eligible, err := s.chatEligible(ctx, acc.ID) + if err != nil { + s.abortErr(c, err) + return + } + resp.Eligible = eligible + c.JSON(http.StatusOK, resp) +} + +// respondChatAccessByUserID answers the change-path query: an account with no +// Telegram identity carries an empty external_id (nothing for the gateway to gate); +// otherwise it carries the identity and the current eligibility. +func (s *Server) respondChatAccessByUserID(c *gin.Context, raw string) { + ctx := c.Request.Context() + uid, err := uuid.Parse(raw) + if err != nil { + abortBadRequest(c, "invalid user_id") + return + } + var resp chatAccessResponse + ext, err := s.accounts.IdentityExternalID(ctx, uid, account.KindTelegram) + if errors.Is(err, account.ErrNotFound) { + c.JSON(http.StatusOK, resp) + return + } + if err != nil { + s.abortErr(c, err) + return + } + resp.ExternalID = ext + resp.Registered = true + eligible, err := s.chatEligible(ctx, uid) + if err != nil { + s.abortErr(c, err) + return + } + resp.Eligible = eligible + c.JSON(http.StatusOK, resp) +} + +// chatEligible reports whether the account may write in the moderated discussion +// chat: not currently admin-suspended and not holding the chat_muted role. A +// suspension dominates — it mutes regardless of the role. Registration is established +// by the caller's identity lookup. +func (s *Server) chatEligible(ctx context.Context, accountID uuid.UUID) (bool, error) { + if _, blocked, err := s.accounts.CurrentSuspension(ctx, accountID); err != nil { + return false, err + } else if blocked { + return false, nil + } + muted, err := s.accounts.HasRole(ctx, accountID, account.RoleChatMuted) + if err != nil { + return false, err + } + return !muted, nil +} + +// publishChatAccessChange emits the chat-access-changed signal for the account, so +// the gateway re-resolves the player's chat eligibility and pushes the chat-gate +// command to the bot. Best-effort (notify.Nop when no notifier is wired). +func (s *Server) publishChatAccessChange(id uuid.UUID) { + s.notifier.Publish(notify.ChatAccessChanged(id)) +} diff --git a/backend/internal/server/handlers.go b/backend/internal/server/handlers.go index 118fdbf..764ed4e 100644 --- a/backend/internal/server/handlers.go +++ b/backend/internal/server/handlers.go @@ -37,6 +37,13 @@ func (s *Server) registerRoutes() { // before delivering an out-of-app notification. in.POST("/push-target", s.handlePushTarget) } + if s.accounts != nil { + // Moderated-chat write eligibility for the Telegram bot: resolve a Telegram + // identity (the bot's join-time query) or an account id (a chat-access-changed + // event) to whether the user may write in the discussion chat. It needs only the + // account store, not the session service, so it registers independently. + s.internal.POST("/chat-access", s.handleChatAccess) + } if s.ratewatch != nil { // The gateway's periodic rate-limiter rejection summary: feeds the // admin console's throttled view and the high-rate auto-flag. diff --git a/backend/internal/server/handlers_admin_console.go b/backend/internal/server/handlers_admin_console.go index cb6ed2f..4e7c1f8 100644 --- a/backend/internal/server/handlers_admin_console.go +++ b/backend/internal/server/handlers_admin_console.go @@ -987,6 +987,9 @@ func (s *Server) consoleBlockUser(c *gin.Context) { s.consoleError(c, err) return } + // Re-evaluate the player's moderated-chat write access: a block mutes them in + // the discussion chat if they are currently in it. + s.publishChatAccessChange(id) s.renderConsoleMessage(c, "Blocked", fmt.Sprintf("account blocked; %d game(s) forfeited", forfeited), back) } @@ -1001,6 +1004,9 @@ func (s *Server) consoleUnblockUser(c *gin.Context) { s.consoleError(c, err) return } + // Re-evaluate the player's moderated-chat write access: an unblock restores it + // (unless they are still chat-muted) for a member currently in the chat. + s.publishChatAccessChange(id) s.renderConsoleMessage(c, "Unblocked", "the block was lifted; lost games are not restored", "/_gm/users/"+id.String()) } diff --git a/backend/internal/server/handlers_admin_feedback.go b/backend/internal/server/handlers_admin_feedback.go index 582e6fe..664bf10 100644 --- a/backend/internal/server/handlers_admin_feedback.go +++ b/backend/internal/server/handlers_admin_feedback.go @@ -248,6 +248,9 @@ func (s *Server) consoleGrantRole(c *gin.Context) { if role == account.RoleNoBanner { s.publishBannerChange(id) } + if role == account.RoleChatMuted { + s.publishChatAccessChange(id) + } s.renderConsoleMessage(c, "Role granted", "granted "+role, back) } @@ -270,6 +273,9 @@ func (s *Server) consoleRevokeRole(c *gin.Context) { if role == account.RoleNoBanner { s.publishBannerChange(id) } + if role == account.RoleChatMuted { + s.publishChatAccessChange(id) + } s.renderConsoleMessage(c, "Role revoked", "revoked "+role, back) } diff --git a/deploy/.env.example b/deploy/.env.example index 9dd4eea..584b9af 100644 --- a/deploy/.env.example +++ b/deploy/.env.example @@ -46,6 +46,10 @@ GRAFANA_ADMIN_PASSWORD=admin AWG_CONF= # required; AmneziaWG sidecar config (the bot's Telegram egress) TELEGRAM_BOT_TOKEN= # required TELEGRAM_GAME_CHANNEL_ID= +TELEGRAM_CHAT_ID= # moderated discussion chat (channel's linked group); empty disables gating +TELEGRAM_PROMO_BOT_TOKEN= # optional standalone promo bot token; empty disables it +TELEGRAM_BOT_USERNAME= # main bot @username without the @ (promo message); required when the promo token is set +TELEGRAM_BOT_LINK= # main bot Mini App link for the promo button (reuse VITE_TELEGRAM_LINK); required when the promo token is set TELEGRAM_MINIAPP_URL= # required TELEGRAM_TEST_ENV=false TELEGRAM_API_BASE_URL= diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml index 664efa8..e18fd1f 100644 --- a/deploy/docker-compose.yml +++ b/deploy/docker-compose.yml @@ -268,6 +268,16 @@ services: # at boot; an empty value leaves the bot down while the rest of the contour comes up. TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN:-} TELEGRAM_GAME_CHANNEL_ID: ${TELEGRAM_GAME_CHANNEL_ID:-} + # The moderated discussion chat (a channel's linked group) the bot gates write + # access in. Empty disables gating; the bot must be an admin there with the + # "Ban users" right and receives chat_member updates only as an admin. + TELEGRAM_CHAT_ID: ${TELEGRAM_CHAT_ID:-} + # The optional standalone promo bot (its own token) answering /start with a button + # into the main bot's app. Empty disables it; when set it needs the main bot's + # @username and the Mini App link (reused from the UI's VITE_TELEGRAM_LINK). + TELEGRAM_PROMO_BOT_TOKEN: ${TELEGRAM_PROMO_BOT_TOKEN:-} + TELEGRAM_BOT_USERNAME: ${TELEGRAM_BOT_USERNAME:-} + TELEGRAM_BOT_LINK: ${TELEGRAM_BOT_LINK:-} TELEGRAM_MINIAPP_URL: ${TELEGRAM_MINIAPP_URL:?set TELEGRAM_MINIAPP_URL} TELEGRAM_TEST_ENV: ${TELEGRAM_TEST_ENV:-false} TELEGRAM_API_BASE_URL: ${TELEGRAM_API_BASE_URL:-} diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 278bf19..b27b7d5 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -824,7 +824,13 @@ the bot renders the message and skips the rest — so in-app-only sub-kinds like block-state sync to the blocker) never become a platform push. Operator broadcasts (`SendToUser` / `SendToGameChannel`, §10 admin) render in an **operator-chosen** language in the console; the backend calls them on the **gateway's bot-link relay**, which forwards them -to the bot and **awaits its delivery ack** (so the console still reports delivered/not). +to the bot and **awaits its delivery ack** (so the console still reports delivered/not). Beyond +messages the same bot-link carries a **chat-gate control path** — a `ChatGate` command sets a user's +write access in the moderated discussion chat and the bot's unary `ResolveChatEligibility` resolves a +joiner's eligibility (neither renders a message; see *Moderated discussion chat* below). An optional +**standalone promo bot** runs in the bot container (`TELEGRAM_PROMO_BOT_TOKEN`): a second bot +answering `/start` with a URL button into the **main** bot's Mini App (`?startapp`, since a `web_app` +button would sign initData with the promo token); it is self-contained — no bot-link, no gateway. Session-revocation events and cursor-based stream resume stay deferred (single-instance MVP). A separate **advertising-banner** channel feeds the client's one-line strip (UI_DESIGN.md), @@ -987,9 +993,24 @@ revoked token would fail session resolution at the gateway *before* the gate, se login instead of the blocked screen). A block instantly **forfeits** every active game the player is in (the opponent wins, exactly as a resignation — the engine resigns off-turn) and cancels their open matchmaking games; a temporary block lapses automatically once its expiry passes (no -sweeper — the gate recomputes against `now`). No operator identity is recorded (shared +sweeper for the gate — it recomputes against `now`). No operator identity is recorded (shared Basic-Auth). +**Moderated discussion chat.** A channel's linked discussion group is gated by the Telegram bot +(`TELEGRAM_CHAT_ID`): the group defaults to no-send, and a user may write only while they are +**registered and neither admin-suspended nor holding the chat-only `chat_muted` role** +(`eligible = registered AND NOT suspended AND NOT chat_muted` — the game suspension dominates). A +single backend resolver behind `POST /api/v1/internal/chat-access` answers both directions: the +bot's join-time `ResolveChatEligibility` (over the mTLS bot-link) grants write access to an +eligible joiner, and a `chat_access_changed` event — emitted on a block/unblock, a `chat_muted` +grant/revoke, or a temporary block lapsing (a dedicated `account.SuspensionSweeper`, since no +request fires then) — drives a `ChatGate` command the gateway pushes to the bot. The bot applies it +only to a member currently in the chat (a per-user `getChatMember` probe, since bots cannot list +members); the signal is idempotent and is never an in-app or out-of-app message. `chat_muted` is an +`account_roles` entry (an operator toggle in the console), so it needs no schema change. The bot +must be an administrator in the group with the **restrict-members** right and `chat_member` in its +allowed updates. + **Short numeric codes** (email confirm-codes and friend codes) are stored only as SHA-256 hashes and are short-lived and single-use. The unauthenticated email path carries a tight per-IP sub-limit (5 / 10 min); the **friend-code redeem** diff --git a/docs/FUNCTIONAL.md b/docs/FUNCTIONAL.md index 49646a7..07a63e6 100644 --- a/docs/FUNCTIONAL.md +++ b/docs/FUNCTIONAL.md @@ -33,7 +33,10 @@ App** launch authenticates from the platform's signed `initData`, themes the UI the Telegram colours, and — on first contact — seeds the new account's interface language from the Telegram client. Telegram runs a **single bot**: every player uses the same bot, and all of its chat and out-of-app notifications are written in the -player's own **interface language** (en/ru). Guests are session-only with restricted features +player's own **interface language** (en/ru). A separate optional **promo bot** can run alongside the +main one — its only job is to answer `/start` with a short message and a button that opens the +**main** bot's app, where the player picks their game variant; it is an onboarding entry point that +touches nothing else. Guests are session-only with restricted features (auto-match only; no friends, stats or history); an abandoned guest that never joined a game and has been idle past the retention window is garbage-collected. While the app is open the client keeps a live stream and receives in-app updates in real time — the opponent's move, @@ -320,6 +323,14 @@ plus the reason when one was given, and the app stops all background traffic wit temporary block lifts itself when it expires; the operator can also **unblock** from the user card at any time (games already lost stay lost). +Where the bot manages a channel's **linked discussion chat**, only a **registered** player who is +**not blocked** may write there: the bot grants the right to write when such a player joins, while an +unregistered or blocked one stays muted (the promo bot points newcomers at the game so they register). +An operator can also **mute a player in the chat only** — a `chat_muted` role on the user card — +without a full account block; an account block mutes them in the chat regardless. Muting/unmuting and +blocking/unblocking take effect for a player already in the chat; one who is not in it is unaffected +until they next join. + From the user card the operator can also **top up a player's hint wallet**: an additive grant (1–100 hints per action) that raises the balance shown on the card. Grants are **raise-only** — the console can never lower a wallet (a player only loses hints by spending them in a game), so an diff --git a/docs/FUNCTIONAL_ru.md b/docs/FUNCTIONAL_ru.md index 58bae72..a43119a 100644 --- a/docs/FUNCTIONAL_ru.md +++ b/docs/FUNCTIONAL_ru.md @@ -34,7 +34,10 @@ Mini App** авторизует по подписанным `initData` плат в цвета Telegram и — при первом контакте — задаёт язык интерфейса нового аккаунта по языку Telegram-клиента. Telegram держит **единого бота**: все игроки пользуются одним и тем же ботом, а весь его чат и внеприложенческие уведомления пишутся на **языке -интерфейса** самого игрока (en/ru). Гость — только сессия, с урезанными функциями (только +интерфейса** самого игрока (en/ru). Рядом с основным может работать отдельный опциональный +**промо-бот** — его единственная задача отвечать на `/start` коротким сообщением и кнопкой, +открывающей приложение **основного** бота, где игрок выбирает нужный вариант игры; это точка входа +для онбординга, не затрагивающая больше ничего. Гость — только сессия, с урезанными функциями (только авто-подбор; без друзей, статистики и истории); заброшенный гость, не вошедший ни в одну игру и простаивавший дольше окна удержания, удаляется сборщиком. Пока приложение открыто, клиент держит живой стрим и получает обновления в реальном времени — ход соперника, ваш ход, @@ -329,6 +332,14 @@ high-rate флага. С карточки пользователя операт истечении срока; оператор также может **разблокировать** с карточки пользователя в любой момент (уже проигранные партии не возвращаются). +Там, где бот ведёт **привязанный к каналу чат-обсуждение**, писать в нём может только +**зарегистрированный** игрок, который **не заблокирован**: при входе такого игрока бот выдаёт право +писать, а незарегистрированному или заблокированному — оставляет немым (промо-бот направляет +новичков в игру, чтобы они зарегистрировались). Оператор также может **замьютить игрока только в +чате** — роль `chat_muted` на карточке пользователя — без полной блокировки аккаунта; блокировка +аккаунта всё равно мьютит его в чате. Мьют/размьют и блокировка/разблокировка срабатывают для +игрока, уже находящегося в чате; того, кого в чате нет, это не затрагивает до его следующего входа. + С карточки пользователя оператор также может **пополнить кошелёк подсказок** игрока: аддитивное начисление (1–100 подсказок за раз), которое **только увеличивает** баланс на карточке. Начисления **только в плюс** — понизить кошелёк из консоли нельзя (игрок теряет подсказки только тратя их в diff --git a/gateway/cmd/gateway/main.go b/gateway/cmd/gateway/main.go index 35e1f65..e06f443 100644 --- a/gateway/cmd/gateway/main.go +++ b/gateway/cmd/gateway/main.go @@ -147,7 +147,11 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error { // fire-and-forget; the backend admin relay (plaintext, internal) awaits the Ack. var botHub *botlink.Hub if cfg.BotLinkEnabled() { - botHub = botlink.NewHub(logger, tel.MeterProvider().Meter("scrabble/gateway/botlink")) + botHub = botlink.NewHub(logger, tel.MeterProvider().Meter("scrabble/gateway/botlink"), + func(ctx context.Context, externalID string) (bool, bool, error) { + r, rerr := backend.ChatEligibility(ctx, externalID) + return r.Registered, r.Eligible, rerr + }) tlsCfg, terr := mtls.ServerConfig(cfg.BotLink.CertFile, cfg.BotLink.KeyFile, cfg.BotLink.CAFile) if terr != nil { return terr @@ -361,6 +365,15 @@ func runPushPump(ctx context.Context, backend *backendclient.Client, hub *push.H } break } + // A chat-access-changed event is an infra signal, not an in-app event: + // resolve the recipient's Telegram identity and current eligibility and + // push the chat-gate command to the bot, without fanning it out to clients. + if ev.GetKind() == chatAccessChangedKind { + if bot != nil { + go deliverChatGate(ctx, backend, bot, ev.GetUserId(), logger) + } + continue + } hub.Publish(push.Event{ UserID: ev.GetUserId(), Kind: ev.GetKind(), @@ -398,6 +411,27 @@ func deliverOutOfApp(ctx context.Context, backend *backendclient.Client, bot *bo bot.Send(botlink.NotifyCommand(target.ExternalID, kind, payload, target.Language)) } +// chatAccessChangedKind is the backend event signalling that a player's moderated-chat +// write eligibility may have changed; the gateway turns it into a bot-link chat-gate +// command rather than an in-app event (it mirrors notify.KindChatAccessChanged). +const chatAccessChangedKind = "chat_access_changed" + +// deliverChatGate resolves a chat-access-changed event to the recipient's Telegram +// identity and current eligibility and pushes the chat-gate command to the bot. It is +// best-effort: a recipient with no Telegram identity is skipped, and a resolve failure +// is logged and dropped (the next moderation action, or a re-join, re-applies the gate). +func deliverChatGate(ctx context.Context, backend *backendclient.Client, bot *botlink.Hub, userID string, logger *zap.Logger) { + res, err := backend.ChatAccessByUser(ctx, userID) + if err != nil { + logger.Warn("chat-gate resolve failed", zap.String("user_id", userID), zap.Error(err)) + return + } + if res.ExternalID == "" { + return // no Telegram identity, nothing to gate + } + bot.Send(botlink.ChatGateCommand(res.ExternalID, res.Eligible)) +} + // 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 { diff --git a/gateway/internal/backendclient/api.go b/gateway/internal/backendclient/api.go index 3a5e656..cb039f4 100644 --- a/gateway/internal/backendclient/api.go +++ b/gateway/internal/backendclient/api.go @@ -215,6 +215,34 @@ func (c *Client) PushTarget(ctx context.Context, userID string) (PushTargetResp, return out, err } +// ChatAccessResp is a user's moderated-chat write eligibility: ExternalID is their +// Telegram identity (empty when they have none, so the gateway has nothing to gate), +// Registered whether an account was found, and Eligible the final gate the bot applies +// (registered and neither admin-suspended nor chat-muted). +type ChatAccessResp struct { + ExternalID string `json:"external_id"` + Registered bool `json:"registered"` + Eligible bool `json:"eligible"` +} + +// ChatEligibility resolves a Telegram identity to its moderated-chat write +// eligibility — the join path, when the bot sees a user enter the chat. +func (c *Client) ChatEligibility(ctx context.Context, externalID string) (ChatAccessResp, error) { + var out ChatAccessResp + err := c.do(ctx, http.MethodPost, "/api/v1/internal/chat-access", "", "", + map[string]string{"external_id": externalID}, &out) + return out, err +} + +// ChatAccessByUser resolves an account id to its Telegram identity and current +// moderated-chat write eligibility — the change path, for a chat-access-changed event. +func (c *Client) ChatAccessByUser(ctx context.Context, userID string) (ChatAccessResp, error) { + var out ChatAccessResp + err := c.do(ctx, http.MethodPost, "/api/v1/internal/chat-access", "", "", + map[string]string{"user_id": userID}, &out) + return out, err +} + // GuestAuth provisions a guest account and mints a session. func (c *Client) GuestAuth(ctx context.Context) (SessionResp, error) { var out SessionResp diff --git a/gateway/internal/botlink/command.go b/gateway/internal/botlink/command.go index 1173725..b2c01b1 100644 --- a/gateway/internal/botlink/command.go +++ b/gateway/internal/botlink/command.go @@ -36,3 +36,15 @@ func SendToGameChannelCommand(text string) *botlinkv1.Command { }}, } } + +// ChatGateCommand builds a chat-gate command that sets whether the Telegram user +// identified by externalID may write in the moderated discussion chat. The bot +// applies it only to a member currently in the chat (guarded on getChatMember). +func ChatGateCommand(externalID string, allow bool) *botlinkv1.Command { + return &botlinkv1.Command{ + Payload: &botlinkv1.Command_ChatGate{ChatGate: &botlinkv1.ChatGateCommand{ + ExternalId: externalID, + Allow: allow, + }}, + } +} diff --git a/gateway/internal/botlink/hub.go b/gateway/internal/botlink/hub.go index fa0a773..fc45b05 100644 --- a/gateway/internal/botlink/hub.go +++ b/gateway/internal/botlink/hub.go @@ -31,13 +31,21 @@ var ErrNoBot = errors.New("botlink: no bot connected") // (at-most-once under backpressure). const outboundBuffer = 64 +// EligibilityResolver answers a Telegram identity's moderated-chat write eligibility +// for the bot's join-time ResolveChatEligibility query: registered reports whether the +// identity maps to an account, eligible is the final gate the bot acts on (registered +// and neither admin-suspended nor chat-muted). The gateway backs it with the backend +// chat-access endpoint. +type EligibilityResolver func(ctx context.Context, externalID string) (registered, eligible bool, err error) + // Hub registers connected bots and routes send commands to them. A single bot is // expected today; the registry already holds a set so adding more later needs no // rewrite. type Hub struct { botlinkv1.UnimplementedBotLinkServer - log *zap.Logger + log *zap.Logger + eligibility EligibilityResolver mu sync.Mutex links map[*link]struct{} @@ -56,15 +64,18 @@ type link struct { out chan *botlinkv1.ToBot } -// NewHub builds a Hub. A nil meter disables metrics; a nil logger is tolerated. -func NewHub(log *zap.Logger, meter metric.Meter) *Hub { +// NewHub builds a Hub. resolve answers the bot's join-time chat-eligibility query +// (nil rejects it as unavailable). A nil meter disables metrics; a nil logger is +// tolerated. +func NewHub(log *zap.Logger, meter metric.Meter, resolve EligibilityResolver) *Hub { if log == nil { log = zap.NewNop() } h := &Hub{ - log: log, - links: make(map[*link]struct{}), - pending: make(map[string]chan *botlinkv1.Ack), + log: log, + eligibility: resolve, + links: make(map[*link]struct{}), + pending: make(map[string]chan *botlinkv1.Ack), } if meter != nil { h.connected, _ = meter.Int64UpDownCounter("botlink_connected_bots", @@ -120,6 +131,22 @@ func (h *Hub) Link(stream grpc.BidiStreamingServer[botlinkv1.FromBot, botlinkv1. } } +// ResolveChatEligibility serves the bot's join-time query: whether the Telegram user +// identified in the request may write in the moderated discussion chat. It delegates +// to the configured resolver (the backend chat-access endpoint), unlike the streamed +// Commands it is a plain request/response over the same mTLS channel. +func (h *Hub) ResolveChatEligibility(ctx context.Context, req *botlinkv1.ChatEligibilityRequest) (*botlinkv1.ChatEligibilityResponse, error) { + if h.eligibility == nil { + return nil, status.Error(codes.Unavailable, "chat eligibility resolver not configured") + } + registered, eligible, err := h.eligibility(ctx, req.GetExternalId()) + if err != nil { + h.log.Warn("resolve chat eligibility failed", zap.String("external_id", req.GetExternalId()), zap.Error(err)) + return nil, status.Error(codes.Internal, "resolve chat eligibility") + } + return &botlinkv1.ChatEligibilityResponse{Registered: registered, Eligible: eligible}, nil +} + // register adds a connected bot. func (h *Hub) register(l *link) { h.mu.Lock() diff --git a/gateway/internal/botlink/hub_test.go b/gateway/internal/botlink/hub_test.go index f2d1716..eae28fc 100644 --- a/gateway/internal/botlink/hub_test.go +++ b/gateway/internal/botlink/hub_test.go @@ -8,7 +8,9 @@ import ( "time" "google.golang.org/grpc" + "google.golang.org/grpc/codes" "google.golang.org/grpc/credentials/insecure" + "google.golang.org/grpc/status" "google.golang.org/grpc/test/bufconn" botlinkv1 "scrabble/pkg/proto/botlink/v1" @@ -23,12 +25,18 @@ type fakeBot struct { received chan *botlinkv1.Command } -// startHub registers a Hub on an in-memory gRPC server and returns the hub plus a -// dialer for fake bots. +// startHub registers a Hub (no chat-eligibility resolver) on an in-memory gRPC +// server and returns the hub plus a dialer for fake bots. func startHub(t *testing.T) (*Hub, func(t *testing.T) botlinkv1.BotLinkClient) { + return startHubWith(t, nil) +} + +// startHubWith is startHub with an explicit chat-eligibility resolver, for the +// ResolveChatEligibility tests. +func startHubWith(t *testing.T, resolve EligibilityResolver) (*Hub, func(t *testing.T) botlinkv1.BotLinkClient) { t.Helper() lis := bufconn.Listen(1 << 20) - hub := NewHub(nil, nil) + hub := NewHub(nil, nil, resolve) srv := grpc.NewServer() botlinkv1.RegisterBotLinkServer(srv, hub) go func() { _ = srv.Serve(lis) }() @@ -162,6 +170,62 @@ func TestHubSendAsync(t *testing.T) { } } +func TestHubSendChatGate(t *testing.T) { + hub, dial := startHub(t) + ctx := t.Context() + bot := &fakeBot{ack: false} + bot.connect(t, ctx, hub, dial(t)) + + hub.Send(ChatGateCommand("42", true)) + select { + case cmd := <-bot.received: + cg := cmd.GetChatGate() + if cg.GetExternalId() != "42" || !cg.GetAllow() { + t.Errorf("chat_gate = %+v, want external_id=42 allow=true", cg) + } + case <-time.After(time.Second): + t.Fatal("bot received no command") + } +} + +func TestHubResolveChatEligibility(t *testing.T) { + var gotExt string + _, dial := startHubWith(t, func(_ context.Context, ext string) (bool, bool, error) { + gotExt = ext + return true, ext == "good", nil + }) + client := dial(t) + ctx := t.Context() + + resp, err := client.ResolveChatEligibility(ctx, &botlinkv1.ChatEligibilityRequest{ExternalId: "good"}) + if err != nil { + t.Fatalf("ResolveChatEligibility: %v", err) + } + if gotExt != "good" { + t.Errorf("resolver external_id = %q, want good", gotExt) + } + if !resp.GetRegistered() || !resp.GetEligible() { + t.Errorf("resp = %+v, want registered+eligible", resp) + } + + resp, err = client.ResolveChatEligibility(ctx, &botlinkv1.ChatEligibilityRequest{ExternalId: "muted"}) + if err != nil { + t.Fatalf("ResolveChatEligibility(muted): %v", err) + } + if !resp.GetRegistered() || resp.GetEligible() { + t.Errorf("resp = %+v, want registered but not eligible", resp) + } +} + +func TestHubResolveChatEligibilityUnconfigured(t *testing.T) { + _, dial := startHub(t) // nil resolver + client := dial(t) + _, err := client.ResolveChatEligibility(t.Context(), &botlinkv1.ChatEligibilityRequest{ExternalId: "x"}) + if status.Code(err) != codes.Unavailable { + t.Fatalf("err = %v, want Unavailable", err) + } +} + func TestRelayServerNoBot(t *testing.T) { hub, _ := startHub(t) relay := NewRelayServer(hub, 200*time.Millisecond) diff --git a/gateway/internal/botlink/mtls_test.go b/gateway/internal/botlink/mtls_test.go index c7a6367..ff97e73 100644 --- a/gateway/internal/botlink/mtls_test.go +++ b/gateway/internal/botlink/mtls_test.go @@ -94,7 +94,7 @@ func startMTLSHub(t *testing.T) (hub *Hub, addr, caFile, cliCert, cliKey string) if err != nil { t.Fatalf("listen: %v", err) } - hub = NewHub(nil, nil) + hub = NewHub(nil, nil, nil) srv := grpc.NewServer(grpc.Creds(credentials.NewTLS(tlsCfg))) botlinkv1.RegisterBotLinkServer(srv, hub) go func() { _ = srv.Serve(lis) }() diff --git a/pkg/proto/botlink/v1/botlink.pb.go b/pkg/proto/botlink/v1/botlink.pb.go index 07cdf3d..46bd55d 100644 --- a/pkg/proto/botlink/v1/botlink.pb.go +++ b/pkg/proto/botlink/v1/botlink.pb.go @@ -224,6 +224,7 @@ type Command struct { // *Command_Notify // *Command_SendToUser // *Command_SendToChannel + // *Command_ChatGate Payload isCommand_Payload `protobuf_oneof:"payload"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -300,6 +301,15 @@ func (x *Command) GetSendToChannel() *v1.SendToGameChannelRequest { return nil } +func (x *Command) GetChatGate() *ChatGateCommand { + if x != nil { + if x, ok := x.Payload.(*Command_ChatGate); ok { + return x.ChatGate + } + } + return nil +} + type isCommand_Payload interface { isCommand_Payload() } @@ -316,12 +326,18 @@ type Command_SendToChannel struct { SendToChannel *v1.SendToGameChannelRequest `protobuf:"bytes,4,opt,name=send_to_channel,json=sendToChannel,proto3,oneof"` } +type Command_ChatGate struct { + ChatGate *ChatGateCommand `protobuf:"bytes,5,opt,name=chat_gate,json=chatGate,proto3,oneof"` +} + func (*Command_Notify) isCommand_Payload() {} func (*Command_SendToUser) isCommand_Payload() {} func (*Command_SendToChannel) isCommand_Payload() {} +func (*Command_ChatGate) 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 @@ -386,6 +402,166 @@ func (x *Ack) GetError() string { return "" } +// ChatGateCommand sets a Telegram user's write access in the moderated discussion +// chat. external_id is the user's Telegram identity (as in the backend identities +// table); allow grants the right to write when true and revokes it when false. The +// bot applies it only to a user currently in the chat — it guards on getChatMember, +// so a command for an absent user is a no-op. The gateway emits one whenever the +// user's eligibility may have changed: an admin block or unblock, a chat_muted +// grant or revoke, or a temporary block lapsing. +type ChatGateCommand struct { + state protoimpl.MessageState `protogen:"open.v1"` + ExternalId string `protobuf:"bytes,1,opt,name=external_id,json=externalId,proto3" json:"external_id,omitempty"` + Allow bool `protobuf:"varint,2,opt,name=allow,proto3" json:"allow,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ChatGateCommand) Reset() { + *x = ChatGateCommand{} + mi := &file_botlink_v1_botlink_proto_msgTypes[5] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ChatGateCommand) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ChatGateCommand) ProtoMessage() {} + +func (x *ChatGateCommand) ProtoReflect() protoreflect.Message { + mi := &file_botlink_v1_botlink_proto_msgTypes[5] + 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 ChatGateCommand.ProtoReflect.Descriptor instead. +func (*ChatGateCommand) Descriptor() ([]byte, []int) { + return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{5} +} + +func (x *ChatGateCommand) GetExternalId() string { + if x != nil { + return x.ExternalId + } + return "" +} + +func (x *ChatGateCommand) GetAllow() bool { + if x != nil { + return x.Allow + } + return false +} + +// ChatEligibilityRequest asks whether the Telegram user identified by external_id +// may write in the moderated discussion chat. +type ChatEligibilityRequest struct { + state protoimpl.MessageState `protogen:"open.v1"` + ExternalId string `protobuf:"bytes,1,opt,name=external_id,json=externalId,proto3" json:"external_id,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ChatEligibilityRequest) Reset() { + *x = ChatEligibilityRequest{} + mi := &file_botlink_v1_botlink_proto_msgTypes[6] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ChatEligibilityRequest) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ChatEligibilityRequest) ProtoMessage() {} + +func (x *ChatEligibilityRequest) ProtoReflect() protoreflect.Message { + mi := &file_botlink_v1_botlink_proto_msgTypes[6] + 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 ChatEligibilityRequest.ProtoReflect.Descriptor instead. +func (*ChatEligibilityRequest) Descriptor() ([]byte, []int) { + return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{6} +} + +func (x *ChatEligibilityRequest) GetExternalId() string { + if x != nil { + return x.ExternalId + } + return "" +} + +// ChatEligibilityResponse is the eligibility answer. registered reports whether the +// external_id maps to an account at all; eligible is the final gate the bot acts on +// (registered and neither admin-suspended nor chat-muted). +type ChatEligibilityResponse struct { + state protoimpl.MessageState `protogen:"open.v1"` + Registered bool `protobuf:"varint,1,opt,name=registered,proto3" json:"registered,omitempty"` + Eligible bool `protobuf:"varint,2,opt,name=eligible,proto3" json:"eligible,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ChatEligibilityResponse) Reset() { + *x = ChatEligibilityResponse{} + mi := &file_botlink_v1_botlink_proto_msgTypes[7] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ChatEligibilityResponse) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ChatEligibilityResponse) ProtoMessage() {} + +func (x *ChatEligibilityResponse) ProtoReflect() protoreflect.Message { + mi := &file_botlink_v1_botlink_proto_msgTypes[7] + 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 ChatEligibilityResponse.ProtoReflect.Descriptor instead. +func (*ChatEligibilityResponse) Descriptor() ([]byte, []int) { + return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{7} +} + +func (x *ChatEligibilityResponse) GetRegistered() bool { + if x != nil { + return x.Registered + } + return false +} + +func (x *ChatEligibilityResponse) GetEligible() bool { + if x != nil { + return x.Eligible + } + return false +} + var File_botlink_v1_botlink_proto protoreflect.FileDescriptor const file_botlink_v1_botlink_proto_rawDesc = "" + @@ -400,22 +576,36 @@ const file_botlink_v1_botlink_proto_rawDesc = "" + "\x05Hello\x12\x1f\n" + "\vinstance_id\x18\x01 \x01(\tR\n" + "instanceId\x12!\n" + - "\fowns_updates\x18\x02 \x01(\bR\vownsUpdates\"\x99\x02\n" + + "\fowns_updates\x18\x02 \x01(\bR\vownsUpdates\"\xde\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" + + "\x0fsend_to_channel\x18\x04 \x01(\v2..scrabble.telegram.v1.SendToGameChannelRequestH\x00R\rsendToChannel\x12C\n" + + "\tchat_gate\x18\x05 \x01(\v2$.scrabble.botlink.v1.ChatGateCommandH\x00R\bchatGateB\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" + + "\x05error\x18\x03 \x01(\tR\x05error\"H\n" + + "\x0fChatGateCommand\x12\x1f\n" + + "\vexternal_id\x18\x01 \x01(\tR\n" + + "externalId\x12\x14\n" + + "\x05allow\x18\x02 \x01(\bR\x05allow\"9\n" + + "\x16ChatEligibilityRequest\x12\x1f\n" + + "\vexternal_id\x18\x01 \x01(\tR\n" + + "externalId\"U\n" + + "\x17ChatEligibilityResponse\x12\x1e\n" + + "\n" + + "registered\x18\x01 \x01(\bR\n" + + "registered\x12\x1a\n" + + "\beligible\x18\x02 \x01(\bR\beligible2\xc4\x01\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" + "\x04Link\x12\x1c.scrabble.botlink.v1.FromBot\x1a\x1a.scrabble.botlink.v1.ToBot(\x010\x01\x12s\n" + + "\x16ResolveChatEligibility\x12+.scrabble.botlink.v1.ChatEligibilityRequest\x1a,.scrabble.botlink.v1.ChatEligibilityResponseB)Z'scrabble/pkg/proto/botlink/v1;botlinkv1b\x06proto3" var ( file_botlink_v1_botlink_proto_rawDescOnce sync.Once @@ -429,31 +619,37 @@ func file_botlink_v1_botlink_proto_rawDescGZIP() []byte { return file_botlink_v1_botlink_proto_rawDescData } -var file_botlink_v1_botlink_proto_msgTypes = make([]protoimpl.MessageInfo, 5) +var file_botlink_v1_botlink_proto_msgTypes = make([]protoimpl.MessageInfo, 8) 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 + (*ChatGateCommand)(nil), // 5: scrabble.botlink.v1.ChatGateCommand + (*ChatEligibilityRequest)(nil), // 6: scrabble.botlink.v1.ChatEligibilityRequest + (*ChatEligibilityResponse)(nil), // 7: scrabble.botlink.v1.ChatEligibilityResponse + (*v1.NotifyRequest)(nil), // 8: scrabble.telegram.v1.NotifyRequest + (*v1.SendToUserRequest)(nil), // 9: scrabble.telegram.v1.SendToUserRequest + (*v1.SendToGameChannelRequest)(nil), // 10: 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 + 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 + 8, // 3: scrabble.botlink.v1.Command.notify:type_name -> scrabble.telegram.v1.NotifyRequest + 9, // 4: scrabble.botlink.v1.Command.send_to_user:type_name -> scrabble.telegram.v1.SendToUserRequest + 10, // 5: scrabble.botlink.v1.Command.send_to_channel:type_name -> scrabble.telegram.v1.SendToGameChannelRequest + 5, // 6: scrabble.botlink.v1.Command.chat_gate:type_name -> scrabble.botlink.v1.ChatGateCommand + 0, // 7: scrabble.botlink.v1.BotLink.Link:input_type -> scrabble.botlink.v1.FromBot + 6, // 8: scrabble.botlink.v1.BotLink.ResolveChatEligibility:input_type -> scrabble.botlink.v1.ChatEligibilityRequest + 1, // 9: scrabble.botlink.v1.BotLink.Link:output_type -> scrabble.botlink.v1.ToBot + 7, // 10: scrabble.botlink.v1.BotLink.ResolveChatEligibility:output_type -> scrabble.botlink.v1.ChatEligibilityResponse + 9, // [9:11] is the sub-list for method output_type + 7, // [7:9] is the sub-list for method input_type + 7, // [7:7] is the sub-list for extension type_name + 7, // [7:7] is the sub-list for extension extendee + 0, // [0:7] is the sub-list for field type_name } func init() { file_botlink_v1_botlink_proto_init() } @@ -469,6 +665,7 @@ func file_botlink_v1_botlink_proto_init() { (*Command_Notify)(nil), (*Command_SendToUser)(nil), (*Command_SendToChannel)(nil), + (*Command_ChatGate)(nil), } type x struct{} out := protoimpl.TypeBuilder{ @@ -476,7 +673,7 @@ func file_botlink_v1_botlink_proto_init() { 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, + NumMessages: 8, NumExtensions: 0, NumServices: 1, }, diff --git a/pkg/proto/botlink/v1/botlink.proto b/pkg/proto/botlink/v1/botlink.proto index 15e96e9..9c4f868 100644 --- a/pkg/proto/botlink/v1/botlink.proto +++ b/pkg/proto/botlink/v1/botlink.proto @@ -20,6 +20,13 @@ 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); + + // ResolveChatEligibility answers whether the Telegram user identified by + // external_id may write in the moderated discussion chat: registered with an + // account and neither admin-suspended nor chat-muted. The bot calls it over the + // same mTLS channel when a user joins the chat, to decide whether to grant the + // write permission. Delivery of the answer is request/response (not best-effort). + rpc ResolveChatEligibility(ChatEligibilityRequest) returns (ChatEligibilityResponse); } // FromBot is a message the bot sends to the gateway: the opening Hello, then one @@ -53,6 +60,7 @@ message Command { scrabble.telegram.v1.NotifyRequest notify = 2; scrabble.telegram.v1.SendToUserRequest send_to_user = 3; scrabble.telegram.v1.SendToGameChannelRequest send_to_channel = 4; + ChatGateCommand chat_gate = 5; } } @@ -65,3 +73,29 @@ message Ack { bool delivered = 2; string error = 3; } + +// ChatGateCommand sets a Telegram user's write access in the moderated discussion +// chat. external_id is the user's Telegram identity (as in the backend identities +// table); allow grants the right to write when true and revokes it when false. The +// bot applies it only to a user currently in the chat — it guards on getChatMember, +// so a command for an absent user is a no-op. The gateway emits one whenever the +// user's eligibility may have changed: an admin block or unblock, a chat_muted +// grant or revoke, or a temporary block lapsing. +message ChatGateCommand { + string external_id = 1; + bool allow = 2; +} + +// ChatEligibilityRequest asks whether the Telegram user identified by external_id +// may write in the moderated discussion chat. +message ChatEligibilityRequest { + string external_id = 1; +} + +// ChatEligibilityResponse is the eligibility answer. registered reports whether the +// external_id maps to an account at all; eligible is the final gate the bot acts on +// (registered and neither admin-suspended nor chat-muted). +message ChatEligibilityResponse { + bool registered = 1; + bool eligible = 2; +} diff --git a/pkg/proto/botlink/v1/botlink_grpc.pb.go b/pkg/proto/botlink/v1/botlink_grpc.pb.go index 93e4782..80f26ca 100644 --- a/pkg/proto/botlink/v1/botlink_grpc.pb.go +++ b/pkg/proto/botlink/v1/botlink_grpc.pb.go @@ -26,7 +26,8 @@ import ( const _ = grpc.SupportPackageIsVersion9 const ( - BotLink_Link_FullMethodName = "/scrabble.botlink.v1.BotLink/Link" + BotLink_Link_FullMethodName = "/scrabble.botlink.v1.BotLink/Link" + BotLink_ResolveChatEligibility_FullMethodName = "/scrabble.botlink.v1.BotLink/ResolveChatEligibility" ) // BotLinkClient is the client API for BotLink service. @@ -41,6 +42,12 @@ 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) + // ResolveChatEligibility answers whether the Telegram user identified by + // external_id may write in the moderated discussion chat: registered with an + // account and neither admin-suspended nor chat-muted. The bot calls it over the + // same mTLS channel when a user joins the chat, to decide whether to grant the + // write permission. Delivery of the answer is request/response (not best-effort). + ResolveChatEligibility(ctx context.Context, in *ChatEligibilityRequest, opts ...grpc.CallOption) (*ChatEligibilityResponse, error) } type botLinkClient struct { @@ -64,6 +71,16 @@ func (c *botLinkClient) Link(ctx context.Context, opts ...grpc.CallOption) (grpc // 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] +func (c *botLinkClient) ResolveChatEligibility(ctx context.Context, in *ChatEligibilityRequest, opts ...grpc.CallOption) (*ChatEligibilityResponse, error) { + cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...) + out := new(ChatEligibilityResponse) + err := c.cc.Invoke(ctx, BotLink_ResolveChatEligibility_FullMethodName, in, out, cOpts...) + if err != nil { + return nil, err + } + return out, nil +} + // BotLinkServer is the server API for BotLink service. // All implementations must embed UnimplementedBotLinkServer // for forward compatibility. @@ -76,6 +93,12 @@ 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 + // ResolveChatEligibility answers whether the Telegram user identified by + // external_id may write in the moderated discussion chat: registered with an + // account and neither admin-suspended nor chat-muted. The bot calls it over the + // same mTLS channel when a user joins the chat, to decide whether to grant the + // write permission. Delivery of the answer is request/response (not best-effort). + ResolveChatEligibility(context.Context, *ChatEligibilityRequest) (*ChatEligibilityResponse, error) mustEmbedUnimplementedBotLinkServer() } @@ -89,6 +112,9 @@ type UnimplementedBotLinkServer struct{} func (UnimplementedBotLinkServer) Link(grpc.BidiStreamingServer[FromBot, ToBot]) error { return status.Errorf(codes.Unimplemented, "method Link not implemented") } +func (UnimplementedBotLinkServer) ResolveChatEligibility(context.Context, *ChatEligibilityRequest) (*ChatEligibilityResponse, error) { + return nil, status.Errorf(codes.Unimplemented, "method ResolveChatEligibility not implemented") +} func (UnimplementedBotLinkServer) mustEmbedUnimplementedBotLinkServer() {} func (UnimplementedBotLinkServer) testEmbeddedByValue() {} @@ -117,13 +143,36 @@ func _BotLink_Link_Handler(srv interface{}, stream grpc.ServerStream) error { // 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] +func _BotLink_ResolveChatEligibility_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { + in := new(ChatEligibilityRequest) + if err := dec(in); err != nil { + return nil, err + } + if interceptor == nil { + return srv.(BotLinkServer).ResolveChatEligibility(ctx, in) + } + info := &grpc.UnaryServerInfo{ + Server: srv, + FullMethod: BotLink_ResolveChatEligibility_FullMethodName, + } + handler := func(ctx context.Context, req interface{}) (interface{}, error) { + return srv.(BotLinkServer).ResolveChatEligibility(ctx, req.(*ChatEligibilityRequest)) + } + return interceptor(ctx, in, info, handler) +} + // 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{}, + Methods: []grpc.MethodDesc{ + { + MethodName: "ResolveChatEligibility", + Handler: _BotLink_ResolveChatEligibility_Handler, + }, + }, Streams: []grpc.StreamDesc{ { StreamName: "Link", diff --git a/platform/telegram/README.md b/platform/telegram/README.md index fda04f1..147f5e4 100644 --- a/platform/telegram/README.md +++ b/platform/telegram/README.md @@ -42,6 +42,23 @@ Telegram identity to an account from a browser. Both map a rejection to gRPC launch button; a deep-link payload routes the launch to a game / invitation / friend code. This is **self-contained** — the bot never calls back into the game, so `/start` onboarding works even when the game is down. +- **Moderated-chat gating.** When `TELEGRAM_CHAT_ID` names a channel's linked discussion + group, the bot gates who may write there. The group is configured **default no-send** + (a human setting); the bot grants write access to a user who **joins** when they are + registered and neither admin-suspended nor `chat_muted`, asking the gateway over the + bot-link (`ResolveChatEligibility`). When an operator blocks/unblocks an account or + toggles its `chat_muted` role, the gateway pushes a `ChatGate` command and the bot + applies it — but only to a member currently in the chat (it probes one user with + `getChatMember`, since bots cannot list members). The bot must be an **administrator** + there with the **"Ban users"** right (the Bot API `can_restrict_members`), and it + subscribes to `chat_member` updates, which Telegram delivers only to a chat admin. +- **Promo bot (optional).** When `TELEGRAM_PROMO_BOT_TOKEN` is set, the container also + runs a **second, standalone** bot whose only job is to answer `/start` with a localized + message and a button that opens the **main** bot's Mini App. The button is a **URL** to + the main bot's direct link (`TELEGRAM_BOT_LINK`, the same link the UI uses) with + `?startapp` — a `web_app` button would launch under the promo bot's identity (its token + would sign the initData), which the main bot's validator rejects. It is fully + self-contained: no bot-link, no gateway, no game. - **Rate limiting.** Outbound sends are throttled (`TELEGRAM_SEND_RATE_PER_SECOND`, default 25) to respect the Bot API flood limits. @@ -57,7 +74,9 @@ parsing is Telegram-specific. gateway also implements `SendToUser` / `SendToGameChannel` as the backend's admin relay. - `pkg/proto/botlink/v1`, service `BotLink` — the reverse bidi stream the **bot** dials - on the gateway (`Hello` / `Command` / `Ack`). Generated Go is committed under `pkg`. + on the gateway (`Hello` / `Command` / `Ack`), now also carrying a `ChatGateCommand` (set + a user's chat write access) and a unary `ResolveChatEligibility` (the bot's join-time + query) over the same mTLS channel. Generated Go is committed under `pkg`. ## Deep-link scheme @@ -101,6 +120,10 @@ Bot (`cmd/bot`): | `TELEGRAM_BOTLINK_SERVER_NAME` | — (required) | the gateway certificate's expected SNI / CN | | `TELEGRAM_BOTLINK_TLS_CERT` / `_KEY` / `_CA` | — (required) | the bot client cert, its key, and the CA that signs the gateway server cert | | `TELEGRAM_GAME_CHANNEL_ID` | — | the bot's game channel chat id for `SendToGameChannel` | +| `TELEGRAM_CHAT_ID` | — | the moderated discussion chat id (a channel's linked group); empty disables chat gating | +| `TELEGRAM_PROMO_BOT_TOKEN` | — | the optional standalone promo bot's token; empty disables it | +| `TELEGRAM_BOT_USERNAME` | — | the main bot's @username without the @ (promo message); required when the promo bot runs | +| `TELEGRAM_BOT_LINK` | — | the main bot's Mini App link for the promo button (the UI's `VITE_TELEGRAM_LINK`); required when the promo bot runs | | `TELEGRAM_OWNS_UPDATES` | `true` | run the exclusive `getUpdates` long-poll (one bot per token) | | `TELEGRAM_SEND_RATE_PER_SECOND` | `25` | outbound Bot API send cap (0 disables) | | `TELEGRAM_INSTANCE_ID` | hostname | bot identity reported to the gateway | diff --git a/platform/telegram/cmd/bot/main.go b/platform/telegram/cmd/bot/main.go index 777807a..bca70a9 100644 --- a/platform/telegram/cmd/bot/main.go +++ b/platform/telegram/cmd/bot/main.go @@ -22,6 +22,7 @@ import ( "scrabble/platform/telegram/internal/bot" "scrabble/platform/telegram/internal/botlink" "scrabble/platform/telegram/internal/config" + "scrabble/platform/telegram/internal/promobot" ) // telemetryShutdownTimeout bounds the OpenTelemetry flush during process exit. @@ -70,6 +71,7 @@ func run(ctx context.Context, cfg config.BotConfig, logger *zap.Logger) error { TestEnv: cfg.TestEnv, MiniAppURL: cfg.MiniAppURL, SendRatePerSecond: cfg.SendRatePerSecond, + ChatID: cfg.ChatID, }, logger) if err != nil { return err @@ -80,19 +82,47 @@ func run(ctx context.Context, cfg config.BotConfig, logger *zap.Logger) error { return err } exec := botlink.NewExecutor(b, cfg.GameChannelID, logger) - client := botlink.NewClient(botlink.ClientConfig{ + client, err := botlink.NewClient(botlink.ClientConfig{ GatewayAddr: cfg.BotLink.GatewayAddr, InstanceID: cfg.BotLink.InstanceID, OwnsUpdates: cfg.OwnsUpdates, Creds: credentials.NewTLS(tlsCfg), ReconnectDelay: cfg.BotLink.ReconnectDelay, }, exec, logger) + if err != nil { + return err + } + defer func() { _ = client.Close() }() + // The chat-join eligibility query rides the same bot-link connection; wire it into + // the bot after the client is built — the late binding that breaks the bot <-> + // client construction cycle. + b.SetEligibilityResolver(client.ResolveChatEligibility) + + // The optional standalone promo bot: a second bot (its own token) that only answers + // /start with a button opening the main bot's Mini App. It is self-contained — no + // bot-link, no gateway — so onboarding works even when the game is down. + var promo *promobot.Bot + if cfg.PromoBotToken != "" { + promo, err = promobot.New(promobot.Config{ + Token: cfg.PromoBotToken, + APIBaseURL: cfg.APIBaseURL, + TestEnv: cfg.TestEnv, + BotUsername: cfg.BotUsername, + BotLinkURL: cfg.BotLinkURL, + SendRatePerSecond: cfg.SendRatePerSecond, + }, logger) + if err != nil { + return err + } + } logger.Info("telegram bot starting", zap.String("gateway", cfg.BotLink.GatewayAddr), zap.String("miniapp_url", cfg.MiniAppURL), zap.Bool("owns_updates", cfg.OwnsUpdates), - zap.Bool("test_env", cfg.TestEnv)) + zap.Bool("test_env", cfg.TestEnv), + zap.Bool("chat_gating", cfg.ChatID != 0), + zap.Bool("promo_bot", promo != nil)) var wg sync.WaitGroup // The long-poll holds the exclusive getUpdates lease (one bot per token); a bot @@ -105,6 +135,11 @@ func run(ctx context.Context, cfg config.BotConfig, logger *zap.Logger) error { logger.Error("bot-link client stopped", zap.Error(err)) } }) + // The promo bot runs its own getUpdates long-poll on its own token (no 409 with + // the main bot's lease). + if promo != nil { + wg.Go(func() { promo.Run(ctx) }) + } <-ctx.Done() wg.Wait() diff --git a/platform/telegram/internal/bot/bot.go b/platform/telegram/internal/bot/bot.go index 8c3aae9..c88fd06 100644 --- a/platform/telegram/internal/bot/bot.go +++ b/platform/telegram/internal/bot/bot.go @@ -8,6 +8,7 @@ package bot import ( "context" "net/url" + "strconv" "strings" tgbot "github.com/go-telegram/bot" @@ -30,8 +31,19 @@ type Config struct { // Telegram Bot API flood limits; 0 disables the limiter. The burst equals the // per-second rate. SendRatePerSecond int + // ChatID is the moderated discussion chat the bot gates write access in; 0 + // disables chat gating (and the chat_member long-poll subscription). Gating needs + // the bot to be an administrator there with the restrict-members right. + ChatID int64 } +// EligibilityResolver answers whether the Telegram user identified by externalID +// (the decimal user id) may write in the moderated chat: registered and neither +// admin-suspended nor chat-muted. The bot calls it when a user joins the chat. It is +// late-bound (SetEligibilityResolver) because it is backed by the bot-link client, +// which is built after the bot. +type EligibilityResolver func(ctx context.Context, externalID string) (eligible bool, err error) + // Bot wraps a Telegram Bot API client and the Mini App launch URL. type Bot struct { api *tgbot.Bot @@ -40,6 +52,11 @@ type Bot struct { // limiter throttles outbound sends to stay under the Bot API flood limits; nil // disables throttling. limiter *rate.Limiter + // chatID is the moderated discussion chat (0 disables gating). + chatID int64 + // eligibility resolves a joining user's chat write eligibility; nil leaves a + // joiner muted (fail-closed) until it is wired. + eligibility EligibilityResolver } // New builds the bot wrapper, registering the /start handler and a default handler @@ -49,15 +66,25 @@ func New(cfg Config, log *zap.Logger) (*Bot, error) { if log == nil { log = zap.NewNop() } - t := &Bot{miniAppURL: cfg.MiniAppURL, log: log} + t := &Bot{miniAppURL: cfg.MiniAppURL, log: log, chatID: cfg.ChatID} if cfg.SendRatePerSecond > 0 { t.limiter = rate.NewLimiter(rate.Limit(cfg.SendRatePerSecond), cfg.SendRatePerSecond) } opts := []tgbot.Option{ - tgbot.WithDefaultHandler(t.handleStart), + tgbot.WithDefaultHandler(t.handleUpdate), tgbot.WithMessageTextHandler("/start", tgbot.MatchTypePrefix, t.handleStart), } + if cfg.ChatID != 0 { + // chat_member updates are off by default; subscribe explicitly (alongside + // messages) so the bot sees joins in the moderated chat. The bot must also be an + // administrator there for Telegram to deliver them. + opts = append(opts, tgbot.WithAllowedUpdates(tgbot.AllowedUpdates{ + models.AllowedUpdateMessage, + models.AllowedUpdateMyChatMember, + models.AllowedUpdateChatMember, + })) + } if cfg.TestEnv { // Route to the Bot API test environment (.../bot/test/METHOD). opts = append(opts, tgbot.UseTestEnvironment()) @@ -176,3 +203,130 @@ func startPayload(text string) string { } return strings.TrimSpace(strings.TrimPrefix(text, cmd)) } + +// handleUpdate is the default-handler dispatcher: a chat-member change in the +// moderated chat drives the write-access gate; anything else is treated as a message +// and gets the Mini App launch reply. +func (t *Bot) handleUpdate(ctx context.Context, api *tgbot.Bot, update *models.Update) { + if update.ChatMember != nil { + t.handleChatMember(ctx, update.ChatMember) + return + } + t.handleStart(ctx, api, update) +} + +// SetEligibilityResolver wires the chat-eligibility resolver after construction (the +// bot-link client backing it is built after the bot). +func (t *Bot) SetEligibilityResolver(resolve EligibilityResolver) { + t.eligibility = resolve +} + +// handleChatMember grants write access to a user who joins the moderated chat when +// they are registered and not blocked. A non-eligible joiner is left muted (the chat +// defaults to no-send), and a resolve failure fails closed (also left muted). Other +// status changes (leaves, restrictions, admin edits) are ignored. +func (t *Bot) handleChatMember(ctx context.Context, cm *models.ChatMemberUpdated) { + if t.chatID == 0 || cm.Chat.ID != t.chatID { + return + } + // Only a transition into plain membership is a join to evaluate. + if cm.NewChatMember.Type != models.ChatMemberTypeMember || cm.OldChatMember.Type == models.ChatMemberTypeMember { + return + } + user := chatMemberUser(cm.NewChatMember) + if user == nil || user.IsBot { + return + } + if t.eligibility == nil { + return // resolver not wired: leave muted (fail closed) + } + eligible, err := t.eligibility(ctx, strconv.FormatInt(user.ID, 10)) + if err != nil { + t.log.Warn("chat join eligibility failed", zap.Int64("user_id", user.ID), zap.Error(err)) + return + } + if !eligible { + return // not registered or blocked: leave muted + } + if err := t.setChatWrite(ctx, user.ID, true); err != nil { + t.log.Warn("grant chat write failed", zap.Int64("user_id", user.ID), zap.Error(err)) + } +} + +// ApplyChatGate applies a chat-gate command (an admin block/unblock or chat_muted +// change relayed by the gateway): it sets the user's write access, but only when they +// are currently in the chat. Bots cannot list members, so it probes the single user +// with getChatMember and is a no-op when they are absent (left/kicked) or an +// administrator (who cannot be restricted). It reports whether a restriction was +// applied. +func (t *Bot) ApplyChatGate(ctx context.Context, userID int64, allow bool) (bool, error) { + if t.chatID == 0 { + return false, nil + } + member, err := t.api.GetChatMember(ctx, &tgbot.GetChatMemberParams{ChatID: t.chatID, UserID: userID}) + if err != nil { + return false, err + } + switch member.Type { + case models.ChatMemberTypeMember, models.ChatMemberTypeRestricted: + if err := t.setChatWrite(ctx, userID, allow); err != nil { + return false, err + } + return true, nil + default: + return false, nil // absent, or an admin/owner who cannot be restricted + } +} + +// setChatWrite restricts the user in the moderated chat to either the full send +// permission set (allow) or none (mute); the non-send permissions stay at their +// default-deny either way. +func (t *Bot) setChatWrite(ctx context.Context, userID int64, allow bool) error { + perms := models.ChatPermissions{} + if allow { + perms = chatWritePerms() + } + _, err := t.api.RestrictChatMember(ctx, &tgbot.RestrictChatMemberParams{ + ChatID: t.chatID, + UserID: userID, + Permissions: &perms, + }) + return err +} + +// chatWritePerms grants a member the ability to send every kind of message; the +// non-send permissions stay denied. +func chatWritePerms() models.ChatPermissions { + return models.ChatPermissions{ + CanSendMessages: true, + CanSendAudios: true, + CanSendDocuments: true, + CanSendPhotos: true, + CanSendVideos: true, + CanSendVideoNotes: true, + CanSendVoiceNotes: true, + CanSendPolls: true, + CanSendOtherMessages: true, + CanAddWebPagePreviews: true, + } +} + +// chatMemberUser returns the user a ChatMember refers to across the union variants, +// or nil for an unrecognised type. +func chatMemberUser(m models.ChatMember) *models.User { + switch m.Type { + case models.ChatMemberTypeOwner: + return m.Owner.User + case models.ChatMemberTypeAdministrator: + return &m.Administrator.User + case models.ChatMemberTypeMember: + return m.Member.User + case models.ChatMemberTypeRestricted: + return m.Restricted.User + case models.ChatMemberTypeLeft: + return m.Left.User + case models.ChatMemberTypeBanned: + return m.Banned.User + } + return nil +} diff --git a/platform/telegram/internal/bot/chat_test.go b/platform/telegram/internal/bot/chat_test.go new file mode 100644 index 0000000..1fefb5e --- /dev/null +++ b/platform/telegram/internal/bot/chat_test.go @@ -0,0 +1,165 @@ +package bot + +import ( + "context" + "encoding/json" + "io" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/go-telegram/bot/models" + "go.uber.org/zap" +) + +const testChatID = 555 + +// chatAPI is a fake Bot API for the chat-gating tests: it answers getMe, returns a +// scripted getChatMember status, and records restrictChatMember calls. +type chatAPI struct { + memberStatus string // the status getChatMember reports (default "left") + restricts []restrictCall +} + +type restrictCall struct { + userID string + canSend bool // can_send_messages in the applied permissions +} + +func (a *chatAPI) ServeHTTP(w http.ResponseWriter, r *http.Request) { + switch { + case strings.HasSuffix(r.URL.Path, "/getMe"): + io.WriteString(w, `{"ok":true,"result":{"id":1,"is_bot":true,"first_name":"t","username":"tb"}}`) + case strings.HasSuffix(r.URL.Path, "/getChatMember"): + status := a.memberStatus + if status == "" { + status = "left" + } + io.WriteString(w, `{"ok":true,"result":{"status":"`+status+`","user":{"id":`+r.FormValue("user_id")+`,"is_bot":false,"first_name":"u"}}}`) + case strings.HasSuffix(r.URL.Path, "/restrictChatMember"): + var perms struct { + CanSendMessages bool `json:"can_send_messages"` + } + _ = json.Unmarshal([]byte(r.FormValue("permissions")), &perms) + a.restricts = append(a.restricts, restrictCall{userID: r.FormValue("user_id"), canSend: perms.CanSendMessages}) + io.WriteString(w, `{"ok":true,"result":true}`) + default: + io.WriteString(w, `{"ok":true,"result":true}`) + } +} + +// newChatBot builds a gating bot (ChatID set) over the fake API, without an +// eligibility resolver — each test wires the one it needs. +func newChatBot(t *testing.T, api *chatAPI) *Bot { + t.Helper() + srv := httptest.NewServer(api) + t.Cleanup(srv.Close) + b, err := New(Config{Token: "123:ABC", APIBaseURL: srv.URL, MiniAppURL: "https://example.com/", ChatID: testChatID}, zap.NewNop()) + if err != nil { + t.Fatalf("new bot: %v", err) + } + return b +} + +// chatMemberUpdate builds a status transition oldType -> member for userID in chatID. +func chatMemberUpdate(chatID, userID int64, oldType models.ChatMemberType) *models.ChatMemberUpdated { + return &models.ChatMemberUpdated{ + Chat: models.Chat{ID: chatID}, + OldChatMember: models.ChatMember{Type: oldType, Left: &models.ChatMemberLeft{User: &models.User{ID: userID}}}, + NewChatMember: models.ChatMember{Type: models.ChatMemberTypeMember, Member: &models.ChatMemberMember{User: &models.User{ID: userID}}}, + } +} + +func TestHandleChatMemberGrantsEligibleJoin(t *testing.T) { + api := &chatAPI{} + b := newChatBot(t, api) + b.SetEligibilityResolver(func(context.Context, string) (bool, error) { return true, nil }) + + b.handleChatMember(context.Background(), chatMemberUpdate(testChatID, 777, models.ChatMemberTypeLeft)) + + if len(api.restricts) != 1 || api.restricts[0].userID != "777" || !api.restricts[0].canSend { + t.Fatalf("restricts = %+v, want one grant (can_send=true) for 777", api.restricts) + } +} + +func TestHandleChatMemberSkipsIneligibleJoin(t *testing.T) { + api := &chatAPI{} + b := newChatBot(t, api) + b.SetEligibilityResolver(func(context.Context, string) (bool, error) { return false, nil }) + + b.handleChatMember(context.Background(), chatMemberUpdate(testChatID, 777, models.ChatMemberTypeLeft)) + + if len(api.restricts) != 0 { + t.Fatalf("an ineligible joiner was restricted: %+v (want left muted, no call)", api.restricts) + } +} + +func TestHandleChatMemberFailsClosedOnResolveError(t *testing.T) { + api := &chatAPI{} + b := newChatBot(t, api) + b.SetEligibilityResolver(func(context.Context, string) (bool, error) { return true, context.DeadlineExceeded }) + + b.handleChatMember(context.Background(), chatMemberUpdate(testChatID, 777, models.ChatMemberTypeLeft)) + + if len(api.restricts) != 0 { + t.Fatalf("a resolve error still granted write: %+v (want fail-closed)", api.restricts) + } +} + +func TestHandleChatMemberIgnoresOtherChatAndNonJoins(t *testing.T) { + api := &chatAPI{} + b := newChatBot(t, api) + b.SetEligibilityResolver(func(context.Context, string) (bool, error) { return true, nil }) + ctx := context.Background() + + // A different chat is ignored. + b.handleChatMember(ctx, chatMemberUpdate(999, 777, models.ChatMemberTypeLeft)) + // A non-join transition (already a member) is ignored. + b.handleChatMember(ctx, chatMemberUpdate(testChatID, 777, models.ChatMemberTypeMember)) + + if len(api.restricts) != 0 { + t.Fatalf("restricts = %+v, want none for a foreign chat / non-join", api.restricts) + } +} + +func TestApplyChatGatePresentMember(t *testing.T) { + for _, tc := range []struct { + name string + allow bool + }{{"grant", true}, {"mute", false}} { + t.Run(tc.name, func(t *testing.T) { + api := &chatAPI{memberStatus: "member"} + b := newChatBot(t, api) + applied, err := b.ApplyChatGate(context.Background(), 777, tc.allow) + if err != nil { + t.Fatalf("apply: %v", err) + } + if !applied { + t.Fatal("applied = false, want true for a present member") + } + if len(api.restricts) != 1 || api.restricts[0].canSend != tc.allow { + t.Fatalf("restricts = %+v, want one with can_send=%v", api.restricts, tc.allow) + } + }) + } +} + +func TestApplyChatGateSkipsAbsentAndAdmin(t *testing.T) { + for _, status := range []string{"left", "kicked", "administrator", "creator"} { + t.Run(status, func(t *testing.T) { + api := &chatAPI{memberStatus: status} + b := newChatBot(t, api) + applied, err := b.ApplyChatGate(context.Background(), 777, false) + if err != nil { + t.Fatalf("apply: %v", err) + } + if applied { + t.Errorf("applied = true for status %q, want a no-op", status) + } + if len(api.restricts) != 0 { + t.Errorf("restricts = %+v for status %q, want none", api.restricts, status) + } + }) + } +} diff --git a/platform/telegram/internal/botlink/client.go b/platform/telegram/internal/botlink/client.go index f415abb..8de04f6 100644 --- a/platform/telegram/internal/botlink/client.go +++ b/platform/telegram/internal/botlink/client.go @@ -37,27 +37,25 @@ type ClientConfig struct { } // Client maintains the long-lived bot-link to the gateway, executing the commands -// it receives and re-dialing after any break. +// it receives and re-dialing after any break. The same mTLS connection also serves +// the unary chat-eligibility query the bot makes on a chat join. type Client struct { - cfg ClientConfig - exec *Executor - log *zap.Logger + cfg ClientConfig + exec *Executor + log *zap.Logger + conn *grpc.ClientConn + client botlinkv1.BotLinkClient } -// NewClient builds the bot-link client over the executor. -func NewClient(cfg ClientConfig, exec *Executor, log *zap.Logger) *Client { +// NewClient builds the bot-link client over the executor, dialing the gateway. The +// gRPC connection is lazy, so the dial does not block on the gateway being up; the +// caller must Close it. The bot-link command stream is opened by Run. +func NewClient(cfg ClientConfig, exec *Executor, log *zap.Logger) (*Client, error) { 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), + conn, err := grpc.NewClient(cfg.GatewayAddr, + grpc.WithTransportCredentials(cfg.Creds), grpc.WithStatsHandler(otelgrpc.NewClientHandler()), grpc.WithKeepaliveParams(keepalive.ClientParameters{ Time: clientKeepaliveTime, @@ -66,13 +64,30 @@ func (c *Client) Run(ctx context.Context) error { }), ) if err != nil { - return err + return nil, err } - defer func() { _ = conn.Close() }() - client := botlinkv1.NewBotLinkClient(conn) + return &Client{cfg: cfg, exec: exec, log: log, conn: conn, client: botlinkv1.NewBotLinkClient(conn)}, nil +} +// Close releases the bot-link connection. +func (c *Client) Close() error { return c.conn.Close() } + +// ResolveChatEligibility asks the gateway whether the Telegram user identified by +// externalID may write in the moderated chat. The bot calls it on a chat join, over +// the same mTLS connection as the command stream. +func (c *Client) ResolveChatEligibility(ctx context.Context, externalID string) (bool, error) { + resp, err := c.client.ResolveChatEligibility(ctx, &botlinkv1.ChatEligibilityRequest{ExternalId: externalID}) + if err != nil { + return false, err + } + return resp.GetEligible(), nil +} + +// Run keeps the bot-link command stream open, re-opening it after each break, until +// ctx is cancelled. The gRPC connection auto-reconnects the transport underneath. +func (c *Client) Run(ctx context.Context) error { for ctx.Err() == nil { - if err := c.serve(ctx, client); err != nil && ctx.Err() == nil { + if err := c.serve(ctx, c.client); err != nil && ctx.Err() == nil { c.log.Warn("bot-link stream ended", zap.Error(err)) } if !sleep(ctx, c.cfg.ReconnectDelay) { diff --git a/platform/telegram/internal/botlink/client_test.go b/platform/telegram/internal/botlink/client_test.go index 09c4690..2fff57d 100644 --- a/platform/telegram/internal/botlink/client_test.go +++ b/platform/telegram/internal/botlink/client_test.go @@ -63,12 +63,16 @@ func TestClientServesCommands(t *testing.T) { t.Cleanup(srv.Stop) sender := &fakeSender{} - client := NewClient(ClientConfig{ + client, err := NewClient(ClientConfig{ GatewayAddr: lis.Addr().String(), InstanceID: "test", Creds: insecure.NewCredentials(), ReconnectDelay: 50 * time.Millisecond, }, NewExecutor(sender, 0, nil), nil) + if err != nil { + t.Fatalf("new client: %v", err) + } + t.Cleanup(func() { _ = client.Close() }) go func() { _ = client.Run(t.Context()) }() diff --git a/platform/telegram/internal/botlink/executor.go b/platform/telegram/internal/botlink/executor.go index 0dae3cf..1175622 100644 --- a/platform/telegram/internal/botlink/executor.go +++ b/platform/telegram/internal/botlink/executor.go @@ -23,6 +23,10 @@ type Sender interface { 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 + // ApplyChatGate sets the Telegram user's write access in the moderated discussion + // chat, but only when they are currently in it; it reports whether a restriction + // was applied. + ApplyChatGate(ctx context.Context, userID int64, allow bool) (bool, error) } // Executor turns a bot-link Command into a Bot API send. The delivered flag mirrors @@ -53,11 +57,30 @@ func (e *Executor) Handle(ctx context.Context, cmd *botlinkv1.Command) (bool, er return e.sendToUser(ctx, p.SendToUser) case *botlinkv1.Command_SendToChannel: return e.sendToChannel(ctx, p.SendToChannel) + case *botlinkv1.Command_ChatGate: + return e.chatGate(ctx, p.ChatGate) default: return false, fmt.Errorf("botlink: empty command") } } +// chatGate applies a chat-gate command: it parses the target Telegram user id and +// sets their write access in the moderated chat (a no-op when they are not in it). A +// Bot API failure is logged and reported as not-delivered, not a hard error. +func (e *Executor) chatGate(ctx context.Context, req *botlinkv1.ChatGateCommand) (bool, error) { + userID, err := parseChatID(req.GetExternalId()) + if err != nil { + return false, err + } + applied, err := e.sender.ApplyChatGate(ctx, userID, req.GetAllow()) + if err != nil { + e.log.Warn("chat gate apply failed", + zap.String("external_id", req.GetExternalId()), zap.Bool("allow", req.GetAllow()), zap.Error(err)) + return false, nil + } + return applied, nil +} + // 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()) diff --git a/platform/telegram/internal/botlink/executor_test.go b/platform/telegram/internal/botlink/executor_test.go index 5e039cc..502eb84 100644 --- a/platform/telegram/internal/botlink/executor_test.go +++ b/platform/telegram/internal/botlink/executor_test.go @@ -13,9 +13,11 @@ import ( // fakeSender records the delivery calls the executor makes. type fakeSender struct { - notify []notifyCall - text []textCall - err error + notify []notifyCall + text []textCall + gate []gateCall + applied bool // ApplyChatGate's reported result + err error } type notifyCall struct { @@ -26,6 +28,10 @@ type textCall struct { chatID int64 text string } +type gateCall struct { + userID int64 + allow bool +} func (f *fakeSender) Notify(_ context.Context, chatID int64, text, buttonText, startParam string) error { f.notify = append(f.notify, notifyCall{chatID, text, buttonText, startParam}) @@ -37,6 +43,11 @@ func (f *fakeSender) SendText(_ context.Context, chatID int64, text string) erro return f.err } +func (f *fakeSender) ApplyChatGate(_ context.Context, userID int64, allow bool) (bool, error) { + f.gate = append(f.gate, gateCall{userID, allow}) + return f.applied, f.err +} + func yourTurnPayload(gameID string) []byte { b := flatbuffers.NewBuilder(0) gid := b.CreateString(gameID) @@ -106,6 +117,46 @@ func TestExecutorSendToUser(t *testing.T) { } } +func chatGateCmd(externalID string, allow bool) *botlinkv1.Command { + return &botlinkv1.Command{Payload: &botlinkv1.Command_ChatGate{ChatGate: &botlinkv1.ChatGateCommand{ + ExternalId: externalID, Allow: allow, + }}} +} + +func TestExecutorChatGateApplied(t *testing.T) { + sender := &fakeSender{applied: true} + exec := NewExecutor(sender, 0, nil) + delivered, err := exec.Handle(context.Background(), chatGateCmd("777", true)) + if err != nil { + t.Fatalf("handle: %v", err) + } + if !delivered || len(sender.gate) != 1 || sender.gate[0].userID != 777 || !sender.gate[0].allow { + t.Errorf("chat gate = %v / calls %+v", delivered, sender.gate) + } +} + +func TestExecutorChatGateNotInChat(t *testing.T) { + sender := &fakeSender{applied: false} // user not in the chat + exec := NewExecutor(sender, 0, nil) + delivered, err := exec.Handle(context.Background(), chatGateCmd("888", false)) + if err != nil { + t.Fatalf("handle: %v", err) + } + if delivered { + t.Error("expected delivered=false when the user is not in the chat") + } + if len(sender.gate) != 1 { + t.Errorf("gate calls = %d, want 1", len(sender.gate)) + } +} + +func TestExecutorChatGateInvalidExternalID(t *testing.T) { + exec := NewExecutor(&fakeSender{}, 0, nil) + if _, err := exec.Handle(context.Background(), chatGateCmd("not-a-number", true)); err == nil { + t.Error("expected an error for a non-numeric external_id") + } +} + func TestExecutorSendToChannel(t *testing.T) { channelCmd := &botlinkv1.Command{Payload: &botlinkv1.Command_SendToChannel{SendToChannel: &telegramv1.SendToGameChannelRequest{Text: "news"}}} diff --git a/platform/telegram/internal/config/config.go b/platform/telegram/internal/config/config.go index b5ea2fa..cbda8a1 100644 --- a/platform/telegram/internal/config/config.go +++ b/platform/telegram/internal/config/config.go @@ -37,6 +37,24 @@ type BotConfig struct { // 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 + // ChatID is the chat id of the moderated discussion supergroup (a channel's linked + // chat) whose write access the bot gates by registration and moderation + // (TELEGRAM_CHAT_ID, optional; 0 disables chat gating). The bot must be an admin + // there with the "Ban users" right, and "chat_member" in its allowed updates. + ChatID int64 + // PromoBotToken is the API token of the optional standalone promo bot run in this + // container — a second bot whose only job is to answer /start with a button that + // opens the main bot's Mini App (TELEGRAM_PROMO_BOT_TOKEN, optional; empty disables + // the promo bot). + PromoBotToken string + // BotUsername is the main bot's @username without the leading @, used in the promo + // bot's message text (TELEGRAM_BOT_USERNAME; required when the promo bot runs). + BotUsername string + // BotLinkURL is the main bot's Mini App direct link — the same value the UI builds + // share links from (VITE_TELEGRAM_LINK), e.g. https://t.me//. The promo + // button appends ?startapp= to it (TELEGRAM_BOT_LINK; required when the + // promo bot runs). It is distinct from the BotLink mTLS dial config below. + BotLinkURL string // 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 @@ -114,6 +132,9 @@ func LoadBot() (BotConfig, error) { TestEnv: os.Getenv("TELEGRAM_TEST_ENV") == "true", OwnsUpdates: os.Getenv("TELEGRAM_OWNS_UPDATES") != "false", SendRatePerSecond: defaultSendRatePerSecond, + PromoBotToken: os.Getenv("TELEGRAM_PROMO_BOT_TOKEN"), + BotUsername: strings.TrimPrefix(os.Getenv("TELEGRAM_BOT_USERNAME"), "@"), + BotLinkURL: os.Getenv("TELEGRAM_BOT_LINK"), LogLevel: envOr("TELEGRAM_LOG_LEVEL", "info"), BotLink: BotLinkClientConfig{ GatewayAddr: os.Getenv("TELEGRAM_GATEWAY_ADDR"), @@ -128,6 +149,9 @@ func LoadBot() (BotConfig, error) { if cfg.GameChannelID, err = envInt64("TELEGRAM_GAME_CHANNEL_ID", 0); err != nil { return BotConfig{}, err } + if cfg.ChatID, err = envInt64("TELEGRAM_CHAT_ID", 0); err != nil { + return BotConfig{}, err + } if cfg.SendRatePerSecond, err = envInt("TELEGRAM_SEND_RATE_PER_SECOND", defaultSendRatePerSecond); err != nil { return BotConfig{}, err } @@ -155,6 +179,9 @@ func LoadBot() (BotConfig, error) { if cfg.BotLink.CertFile == "" || cfg.BotLink.KeyFile == "" || cfg.BotLink.CAFile == "" { return BotConfig{}, fmt.Errorf("config: TELEGRAM_BOTLINK_TLS_CERT, _KEY and _CA are required") } + if cfg.PromoBotToken != "" && (cfg.BotUsername == "" || cfg.BotLinkURL == "") { + return BotConfig{}, fmt.Errorf("config: TELEGRAM_BOT_USERNAME and TELEGRAM_BOT_LINK are required when TELEGRAM_PROMO_BOT_TOKEN is set") + } return cfg, nil } diff --git a/platform/telegram/internal/config/config_test.go b/platform/telegram/internal/config/config_test.go index df6230f..2aa5483 100644 --- a/platform/telegram/internal/config/config_test.go +++ b/platform/telegram/internal/config/config_test.go @@ -103,6 +103,54 @@ func TestLoadBotRequired(t *testing.T) { } } +// TestLoadBotChatAndPromo verifies the moderated-chat id and the promo-bot +// configuration parse, the @-prefix is stripped from the username, and a promo token +// without a username/link is rejected. +func TestLoadBotChatAndPromo(t *testing.T) { + t.Run("parsed", func(t *testing.T) { + setBotRequired(t) + t.Setenv("TELEGRAM_CHAT_ID", "-100222") + t.Setenv("TELEGRAM_PROMO_BOT_TOKEN", "promo-token") + t.Setenv("TELEGRAM_BOT_USERNAME", "@ScrabbleBot") + t.Setenv("TELEGRAM_BOT_LINK", "https://t.me/ScrabbleBot/app") + c, err := LoadBot() + if err != nil { + t.Fatalf("LoadBot: %v", err) + } + if c.ChatID != -100222 { + t.Errorf("ChatID = %d, want -100222", c.ChatID) + } + if c.PromoBotToken != "promo-token" { + t.Errorf("PromoBotToken = %q", c.PromoBotToken) + } + if c.BotUsername != "ScrabbleBot" { + t.Errorf("BotUsername = %q, want the leading @ stripped", c.BotUsername) + } + if c.BotLinkURL != "https://t.me/ScrabbleBot/app" { + t.Errorf("BotLinkURL = %q", c.BotLinkURL) + } + }) + + t.Run("promo token requires username and link", func(t *testing.T) { + setBotRequired(t) + t.Setenv("TELEGRAM_PROMO_BOT_TOKEN", "promo-token") + if _, err := LoadBot(); err == nil { + t.Fatal("LoadBot: expected an error for a promo token without username/link") + } + }) + + t.Run("disabled by default", func(t *testing.T) { + setBotRequired(t) + c, err := LoadBot() + if err != nil { + t.Fatalf("LoadBot: %v", err) + } + if c.PromoBotToken != "" || c.ChatID != 0 { + t.Errorf("defaults: promo=%q chat=%d, want empty/0", c.PromoBotToken, c.ChatID) + } + }) +} + // TestLoadRejectsUnsupportedExporter verifies an exporter outside the supported set // fails validation (the validator path). func TestLoadRejectsUnsupportedExporter(t *testing.T) { diff --git a/platform/telegram/internal/promobot/promobot.go b/platform/telegram/internal/promobot/promobot.go new file mode 100644 index 0000000..f4911ff --- /dev/null +++ b/platform/telegram/internal/promobot/promobot.go @@ -0,0 +1,164 @@ +// Package promobot is the standalone promo bot: a second Telegram bot in the bot +// container whose only job is to answer /start with a localized message and a button +// that opens the MAIN bot's Mini App. It is self-contained — it never calls the +// gateway or the game — so onboarding works even when the game is down. The button is +// a URL to the main bot's direct Mini App link: a web_app button would launch the Mini +// App under the promo bot's identity (its token would sign the initData), which the +// main bot's validator would reject, so the cross-bot launch must be a t.me link. It +// reuses the same link the UI builds invitation links from (VITE_TELEGRAM_LINK). +package promobot + +import ( + "context" + "net/url" + "strings" + + tgbot "github.com/go-telegram/bot" + "github.com/go-telegram/bot/models" + "go.uber.org/zap" + "golang.org/x/time/rate" +) + +// Config configures the promo bot. +type Config struct { + // Token is the promo bot's Bot API token. + Token string + // APIBaseURL overrides the Bot API host ("" uses https://api.telegram.org). + APIBaseURL string + // TestEnv routes requests to the Bot API test environment. + TestEnv bool + // BotUsername is the main bot's @username without the leading @, named in the + // message text. + BotUsername string + // BotLinkURL is the main bot's Mini App direct link; the button appends + // ?startapp= to it. + BotLinkURL string + // SendRatePerSecond caps outbound sends to respect the Bot API flood limits; 0 + // disables the limiter. The burst equals the per-second rate. + SendRatePerSecond int +} + +// Bot is the promo bot wrapper around a Telegram Bot API client. +type Bot struct { + api *tgbot.Bot + username string + linkURL string + log *zap.Logger + limiter *rate.Limiter +} + +// New builds the promo bot, registering a /start (and default) handler that replies +// with the launch button. It does not start polling; call Run for that. +func New(cfg Config, log *zap.Logger) (*Bot, error) { + if log == nil { + log = zap.NewNop() + } + t := &Bot{username: cfg.BotUsername, linkURL: cfg.BotLinkURL, log: log} + if cfg.SendRatePerSecond > 0 { + t.limiter = rate.NewLimiter(rate.Limit(cfg.SendRatePerSecond), cfg.SendRatePerSecond) + } + opts := []tgbot.Option{ + tgbot.WithDefaultHandler(t.handleStart), + tgbot.WithMessageTextHandler("/start", tgbot.MatchTypePrefix, t.handleStart), + } + if cfg.TestEnv { + opts = append(opts, tgbot.UseTestEnvironment()) + } + if cfg.APIBaseURL != "" { + opts = append(opts, tgbot.WithServerURL(cfg.APIBaseURL)) + } + api, err := tgbot.New(cfg.Token, opts...) + if err != nil { + return nil, err + } + t.api = api + return t, nil +} + +// Run sets the bot command, then blocks on the long-poll update loop until ctx is +// cancelled. +func (t *Bot) Run(ctx context.Context) { + if _, err := t.api.SetMyCommands(ctx, &tgbot.SetMyCommandsParams{ + Commands: []models.BotCommand{{Command: "start", Description: "Open Scrabble"}}, + }); err != nil { + t.log.Warn("promo: set commands failed", zap.Error(err)) + } + t.api.Start(ctx) +} + +// handleStart replies to any message (typically /start) with the localized promo text +// and a button that opens the main bot's Mini App, forwarding any /start payload. +func (t *Bot) handleStart(ctx context.Context, api *tgbot.Bot, update *models.Update) { + if update.Message == nil { + return + } + if err := t.throttle(ctx); err != nil { + return + } + lang := "" + if update.Message.From != nil { + lang = update.Message.From.LanguageCode + } + text, button := promoText(lang, t.username) + if _, err := api.SendMessage(ctx, &tgbot.SendMessageParams{ + ChatID: update.Message.Chat.ID, + Text: text, + ReplyMarkup: t.launchMarkup(button, startPayload(update.Message.Text)), + }); err != nil { + t.log.Warn("promo: reply to start failed", zap.Error(err)) + } +} + +// launchMarkup builds the single URL button that opens the main bot's Mini App at the +// optional startapp payload. +func (t *Bot) launchMarkup(buttonText, startParam string) *models.InlineKeyboardMarkup { + return &models.InlineKeyboardMarkup{ + InlineKeyboard: [][]models.InlineKeyboardButton{{ + {Text: buttonText, URL: t.launchURL(startParam)}, + }}, + } +} + +// launchURL appends the startapp payload to the main bot's Mini App link; an empty +// payload returns the base link unchanged. +func (t *Bot) launchURL(startParam string) string { + if startParam == "" { + return t.linkURL + } + u, err := url.Parse(t.linkURL) + if err != nil { + return t.linkURL + } + q := u.Query() + q.Set("startapp", startParam) + u.RawQuery = q.Encode() + return u.String() +} + +// throttle blocks until the rate limiter admits one send, or ctx is cancelled. It is +// a no-op when no limiter is configured. +func (t *Bot) throttle(ctx context.Context) error { + if t.limiter == nil { + return nil + } + return t.limiter.Wait(ctx) +} + +// startPayload extracts the deep-link payload from a "/start " command; any +// other text yields an empty payload (open the lobby). +func startPayload(text string) string { + const cmd = "/start" + if !strings.HasPrefix(text, cmd) { + return "" + } + return strings.TrimSpace(strings.TrimPrefix(text, cmd)) +} + +// promoText returns the localized message body and button label, naming the main bot +// (Russian for a "ru" language code, English otherwise). +func promoText(lang, username string) (text, button string) { + if strings.HasPrefix(strings.ToLower(lang), "ru") { + return "Откройте @" + username + " и выберите в настройках профиля нужный вариант игры.", "🤩 Хочу играть!" + } + return "Open @" + username + " and choose your game variant in the profile settings.", "🤩 I want to play!" +} diff --git a/platform/telegram/internal/promobot/promobot_test.go b/platform/telegram/internal/promobot/promobot_test.go new file mode 100644 index 0000000..459d650 --- /dev/null +++ b/platform/telegram/internal/promobot/promobot_test.go @@ -0,0 +1,105 @@ +package promobot + +import ( + "context" + "io" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/go-telegram/bot/models" + "go.uber.org/zap" +) + +func TestPromoTextLocalization(t *testing.T) { + en, enBtn := promoText("en", "ScrabbleBot") + if !strings.Contains(en, "@ScrabbleBot") || !strings.Contains(en, "profile settings") { + t.Errorf("en text = %q", en) + } + if enBtn != "🤩 I want to play!" { + t.Errorf("en button = %q", enBtn) + } + + ru, ruBtn := promoText("ru-RU", "ScrabbleBot") + if !strings.Contains(ru, "@ScrabbleBot") || !strings.Contains(ru, "Откройте") { + t.Errorf("ru text = %q", ru) + } + if ruBtn != "🤩 Хочу играть!" { + t.Errorf("ru button = %q", ruBtn) + } + + // An unknown language falls back to English. + if got, _ := promoText("de", "B"); !strings.Contains(got, "Open @B") { + t.Errorf("fallback text = %q, want English", got) + } +} + +func TestLaunchURLAppendsStartapp(t *testing.T) { + b := &Bot{linkURL: "https://t.me/bot/app"} + if got := b.launchURL(""); got != "https://t.me/bot/app" { + t.Errorf("empty payload = %q, want the base link unchanged", got) + } + if got := b.launchURL("g123"); got != "https://t.me/bot/app?startapp=g123" { + t.Errorf("launchURL = %q, want startapp=g123 appended", got) + } +} + +func TestLaunchMarkupIsURLButton(t *testing.T) { + b := &Bot{linkURL: "https://t.me/bot/app"} + btn := b.launchMarkup("Play", "f99").InlineKeyboard[0][0] + if btn.WebApp != nil { + t.Error("the promo button must not be a web_app button (it would sign initData with the promo token, which the main bot rejects)") + } + if !strings.Contains(btn.URL, "startapp=f99") { + t.Errorf("button URL = %q, want startapp=f99", btn.URL) + } +} + +// fakeAPI answers getMe (so New succeeds offline) and records the last sendMessage. +type fakeAPI struct { + chatID, text, replyMarkup string +} + +func (f *fakeAPI) ServeHTTP(w http.ResponseWriter, r *http.Request) { + switch { + case strings.HasSuffix(r.URL.Path, "/getMe"): + io.WriteString(w, `{"ok":true,"result":{"id":1,"is_bot":true,"first_name":"t","username":"promo"}}`) + case strings.HasSuffix(r.URL.Path, "/sendMessage"): + f.chatID = r.FormValue("chat_id") + f.text = r.FormValue("text") + f.replyMarkup = r.FormValue("reply_markup") + io.WriteString(w, `{"ok":true,"result":{"message_id":1}}`) + default: + io.WriteString(w, `{"ok":true,"result":true}`) + } +} + +func TestHandleStartReplies(t *testing.T) { + api := &fakeAPI{} + srv := httptest.NewServer(api) + t.Cleanup(srv.Close) + b, err := New(Config{Token: "1:2", APIBaseURL: srv.URL, BotUsername: "ScrabbleBot", BotLinkURL: "https://t.me/bot/app"}, zap.NewNop()) + if err != nil { + t.Fatalf("new: %v", err) + } + + b.handleStart(context.Background(), b.api, &models.Update{Message: &models.Message{ + Chat: models.Chat{ID: 42}, + From: &models.User{LanguageCode: "ru"}, + Text: "/start f99", + }}) + + if api.chatID != "42" { + t.Errorf("chat_id = %q, want 42", api.chatID) + } + if !strings.Contains(api.text, "@ScrabbleBot") { + t.Errorf("text = %q, want the @mention", api.text) + } + if strings.Contains(api.replyMarkup, "web_app") { + t.Errorf("reply_markup = %q has a web_app button; want a url button", api.replyMarkup) + } + if !strings.Contains(api.replyMarkup, "startapp=f99") { + t.Errorf("reply_markup = %q, want startapp=f99 (the /start payload forwarded)", api.replyMarkup) + } +}