fix(telegram): authenticate webhook deliveries with the Telegram secret token

[anhtahaylove]

Fixes #13172.

Problem

POST /api/telegram/update serves two callers, and only one of them was authenticated:

• Mini App ({ initData, message }) — verifies the Telegram initData HMAC. Safe.
• Bot webhook (a Telegram update) — took message.chat.id straight from the body. The only gate was isTelegramEnabled(), which merely checks that a bot token is configured on our side. Nothing proved the request came from Telegram.

chat.id flows into proxyChat(), which mints a real API key for that id and spends upstream model quota. A caller who knows the URL can therefore create unbounded keys and burn quota. They don't get the replies back (those go to the spoofed chat id), so this is resource abuse and key-table growth, not data exfiltration.

setWebhook also never registered a secret_token, so the header needed for verification was never being sent by Telegram in the first place.

Fix

Use Telegram's own mechanism: the secret_token given to setWebhook is echoed back on every delivery as X-Telegram-Bot-Api-Secret-Token.

1. TELEGRAM_WEBHOOK_SECRET config getter (src/lib/telegram/config.ts).
2. setWebhook registers secret_token when configured (src/lib/telegram/botApi.ts).
3. The webhook branch verifies the header before anything reaches proxyChat():
   • secret not configured → 503 (fail closed — an open webhook is what causes the abuse)
   • missing/wrong secret → 401
   • correct → proceeds as before

Comparison uses timingSafeEqual with an up-front length check, mirroring webhookSecretMatches's counterpart in src/app/api/a2a/tasks/route.ts, so the shared-prefix length doesn't leak through response timing.

The Mini App path is untouched and does not require the secret.

Incidental schema fix

The zod body schema typed message as an optional string (the Mini App shape), but a real Telegram update sends message as an object. .passthrough() preserves unknown keys but still type-checks known ones, so realistic webhook deliveries were rejected with 400 before reaching any routing. message now accepts either shape; each branch already narrows the shape it needs (typeof body.message === "string" for Mini App, extractChatMessage() for webhook). This surfaced while writing the test — a body that mirrors a genuine Telegram update.

Verification

tests/unit/telegram-webhook-secret-13172.test.ts — 4/4 pass with the fix, 4/4 fail without it (verified by stashing the source changes):

• no secret header → 401, nothing proxied
• wrong secret → 401
• correct secret → 200
• comparator: equal values match, length mismatch returns false instead of throwing

npx tsc --noEmit clean.

Operator note — breaking for existing webhook deployments

Anyone already running the webhook must set TELEGRAM_WEBHOOK_SECRET and re-run setWebhook so Telegram starts sending the header; until then deliveries return 503. This is deliberate: silently serving an unauthenticated webhook is the vulnerability. Documented in .env.example and docs/reference/ENVIRONMENT.md.

Note check:docs-counts reports 3 pre-existing strict drifts (171 → 172 migrations) on this base; unrelated to this change and fixed by #13160.

[anhtahaylove]

Flagging for review priority: of the 14 open PRs in this audit (queue overview), this is the only one with a security impact rather than a resource-management one.

An unauthenticated caller could POST a synthetic Telegram update with any chat.id; that id reaches proxyChat(), which mints a real API key and spends upstream quota. Replies go to the spoofed chat id, so it is resource abuse and unbounded key creation rather than data exfiltration — but it needs no credentials at all.

Note this is intentionally breaking for existing webhook deployments: operators must set TELEGRAM_WEBHOOK_SECRET and re-run setWebhook, otherwise deliveries return 503. Failing closed seemed clearly right over continuing to serve an open endpoint, but say the word if you'd prefer a deprecation window instead.