Document telegram-native task 5 foundation

09 - Audits/Task 5.3 Telegram Bot Command and Notification Foundation.md

@@ -0,0 +1,48 @@
+---
+title: Task 5.3 Telegram Bot Command and Notification Foundation
+tags: [taskmaster, telegram, bot, notifications]
+created: 2026-05-24
+status: partial-foundation
+---
+
+# Task 5.3 Telegram Bot Command and Notification Foundation
+
+This document captures the first backend bot foundation pass.
+
+## Implemented foundation
+
+- `/api/telegram/status` reports feature and webhook readiness without leaking
+  bot or webhook secrets.
+- `/api/telegram/webhook` is mounted only when Telegram features are enabled.
+- Webhook requests require `x-telegram-bot-api-secret-token` to match
+  `TELEGRAM_WEBHOOK_SECRET_TOKEN`.
+- Webhook update handling dedupes by `update_id` or callback ID.
+- Webhook handler classifies updates as:
+  - `command`
+  - `callback`
+  - `noop`
+  - `duplicate`
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `TELEGRAM_WEBHOOK_ENABLED` | Enables webhook route |
+| `TELEGRAM_WEBHOOK_SECRET_TOKEN` | Telegram webhook secret token |
+| `TELEGRAM_WEBHOOK_REPLAY_WINDOW_MS` | Duplicate update replay window |
+
+## Tests
+
+- Service-level tests cover command/callback/noop classification and duplicate
+  handling.
+- Route-level tests cover secret-token rejection and accepted command webhook
+  processing.
+
+## Remaining work
+
+- Implement actual command actions for `/start`, `/help`, `/link`, `/status`,
+  `/request`, `/offer`, `/payment`, `/dispute`, and `/settings`.
+- Add signed opaque callback payload issuance and resolution.
+- Add outbound notification delivery, blocked-bot detection, retry metrics, and
+  notification preferences.
+- Persist webhook dedupe keys in shared storage instead of process memory.