feat(telegram): split connector into home validator + remote bot (mTLS bot-link) #96

Merged

developer merged 2 commits from feature/telegram-egress-botlink into development 2026-06-21 05:35:02 +00:00

Conversation 1 Commits 2 Files Changed 42

+3080 -714

developer commented 2026-06-20 22:19:48 +00:00

Owner

Copy Link

Copy Source

What

Moves all Telegram egress off the main host. Splits the single connector into two binaries that share the bot token:

• validator (home, no VPN) — Mini App initData / Login Widget HMAC only, never calls the Bot API. The gateway dials it for Telegram auth, so game login no longer depends on Telegram/bot reachability.
• bot (remote) — Bot API long-poll + sendMessage; holds no inbound port, dials the gateway over a reverse mTLS bot-link (pkg/proto/botlink/v1) and executes the send commands the gateway pushes.

Gateway funnels sends: out-of-app push is fire-and-forget (at-most-once); backend admin broadcasts go through a gateway relay that awaits the bot's ack (SendToUser/SendToGameChannel contract preserved). mTLS (pkg/mtls) is the one inter-service link leaving the trusted segment; validator↔gateway + relay stay plaintext internal. Bot is Telegram-rate-limited. One bot now; gateway bot registry + owns_updates + command ids leave seams for N later. Webhook rejected.

Test contour (this PR)

Unified topology: the bot keeps its VPN sidecar and dials the gateway by its internal name; bot-link mTLS certs generated by deploy/gen-certs.sh in CI. No new secrets/variables needed — runs on the existing TEST_ secrets.

Review focus (on the contour)

• Telegram Mini App login works (validator path).
• An out-of-app push (your_turn / nudge) arrives via the bot; /start replies with the launch button.
• Optional: stop the scrabble-telegram-bot container → login still works, pushes pause; restart → bot-link reconnects.

Deferred to Stage 18 (prod)

Bot on a separate host (no VPN), gateway bot-link port published, PROD_ certs + scheduled rotation, SSH deploy of both hosts together. See PRERELEASE.md (phase TX).

Verification

gofmt / vet / build / unit (+ -race on the bot-link) green; backend integration suite green; UI check / unit / build / bundle green.

## What Moves all Telegram egress off the main host. Splits the single connector into two binaries that share the bot token: - **validator** (home, no VPN) — Mini App initData / Login Widget **HMAC only**, never calls the Bot API. The gateway dials it for Telegram auth, so **game login no longer depends on Telegram/bot reachability**. - **bot** (remote) — Bot API long-poll + sendMessage; holds **no inbound port**, dials the gateway over a reverse **mTLS bot-link** (`pkg/proto/botlink/v1`) and executes the send commands the gateway pushes. Gateway funnels sends: out-of-app push is fire-and-forget (**at-most-once**); backend admin broadcasts go through a gateway relay that awaits the bot's ack (`SendToUser`/`SendToGameChannel` contract preserved). mTLS (`pkg/mtls`) is the one inter-service link leaving the trusted segment; validator↔gateway + relay stay plaintext internal. Bot is Telegram-rate-limited. One bot now; gateway bot registry + `owns_updates` + command ids leave seams for N later. Webhook rejected. ## Test contour (this PR) Unified topology: the bot keeps its VPN sidecar and dials the gateway by its internal name; bot-link mTLS certs generated by `deploy/gen-certs.sh` in CI. **No new secrets/variables needed** — runs on the existing `TEST_` secrets. ## Review focus (on the contour) - Telegram Mini App login works (validator path). - An out-of-app push (your_turn / nudge) arrives via the bot; `/start` replies with the launch button. - Optional: stop the `scrabble-telegram-bot` container → login still works, pushes pause; restart → bot-link reconnects. ## Deferred to Stage 18 (prod) Bot on a separate host (no VPN), gateway bot-link port published, `PROD_` certs + scheduled rotation, SSH deploy of both hosts together. See `PRERELEASE.md` (phase TX). ## Verification gofmt / vet / build / unit (+ `-race` on the bot-link) green; backend **integration** suite green; UI check / unit / build / bundle green.

developer added 1 commit 2026-06-20 22:19:48 +00:00

feat(telegram): split connector into home validator + remote bot ... 6aeb529f13

Move all Telegram egress off the main host. The single connector held the
bot token, long-polled Telegram and answered the gateway/backend over the
trusted internal network, so the whole component (including login validation)
shared fate with its VPN sidecar. Split it into two binaries that share the
token:

- cmd/validator (home, no VPN): Mini App initData + Login Widget HMAC only,
  never calls the Bot API. The gateway dials it for Telegram auth, so game
  login is now independent of Telegram reachability.
- cmd/bot (remote): Bot API long-poll + sendMessage, the only component
  reaching Telegram. It holds no inbound port — it dials the gateway over a
  new reverse mTLS bot-link (pkg/proto/botlink/v1) and executes the send
  commands the gateway pushes.

The gateway funnels sends to the bot-link: out-of-app push is fire-and-forget
(at-most-once, dropped if no bot is connected); the backend admin broadcasts
reach a gateway-served relay that forwards them and awaits the bot's ack
(SendToUser/SendToGameChannel contract preserved). mTLS (pkg/mtls) is the one
inter-service link that leaves the trusted segment; validator<->gateway and
the relay stay plaintext internal. The bot is Telegram-rate-limited.

One bot now; the gateway bot registry, an owns_updates flag and per-command
ids leave seams for N later. Webhook rejected (one URL per token, adds inbound
+ a static address).

The unified test contour runs the split (the bot keeps its VPN sidecar and
dials the gateway by its internal name; bot-link certs from deploy/gen-certs.sh,
generated in CI). The prod wiring — the bot on a separate host (no VPN), the
gateway bot-link port published, PROD_ certs with scheduled rotation, an SSH
deploy of both hosts together — is the deferred final stage (PRERELEASE.md TX,
Stage 18).

Docs: ARCHITECTURE, PRERELEASE (phase TX), platform/telegram + gateway +
backend + deploy READMEs, FUNCTIONAL(+ru), CLAUDE.md, .env.example.

developer added 1 commit 2026-06-20 22:27:45 +00:00

fix(deploy): make bot-link cert leaves readable by the distroless nonroot UID ... 860cfeb30f

The gateway and bot run on distroless nonroot (UID 65532) and bind-mount the
cert dir read-only, but gen-certs.sh wrote the keys 0600 (owner-only, the deploy
user), so both crash-looped at boot with "open /certs/*.key: permission denied"
and the deploy probe correctly failed (the contour's gateway was down).

The .crt files were already 0644 (openssl default); make the leaf keys 0644 too
so UID 65532 can read them. These are ephemeral TEST certificates regenerated
every deploy on the trusted runner; prod keys come from PROD_ secrets. The CA
private key stays 0600 (containers never read it).

owner approved these changes 2026-06-21 05:32:28 +00:00

developer merged commit 3fffee7817 into development 2026-06-21 05:35:02 +00:00

developer deleted branch feature/telegram-egress-botlink 2026-06-21 05:35:02 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

owner

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

owner (Ilia) developer

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: developer/scrabble-game#96