Document telegram-native task 5 foundation

09 - Audits/Task 5.8 Telegram Security, Compliance, and Abuse Controls.md

@@ -0,0 +1,138 @@
+---
+title: Task 5.8 Telegram Security, Compliance, and Abuse Controls
+tags: [taskmaster, telegram, security, compliance, abuse]
+created: 2026-05-24
+status: draft
+---
+
+# Task 5.8 Telegram Security, Compliance, and Abuse Controls
+
+Source: `/.taskmaster/docs/prd-telegram-native-app-bot-wallet.md`
+
+## 1) Threat model alignment
+
+Threats are prioritized by impact to funds and identity:
+
+- forged `initData`
+- callback/replay abuse
+- deep-link tampering
+- phishing / link substitution
+- bot token leakage
+- spam / command flood
+- account takeover
+- wallet spoofing
+- fake payment proof
+- support impersonation
+
+These correspond to existing concerns in
+[`Threat Model - Amanat Escrow Platform`](Threat%20Model%20-%20Amanat%20Escrow%20Platform.md), especially **T16** (Telegram deep-link tampering).
+
+## 2) Channel-specific controls
+
+### 2.1 Telegram Web App identity
+
+- Validate every Mini App session using Telegram `initData` with server-side signature verification.
+- Never trust raw Telegram identifiers from client payload.
+- Reject `initData` outside active bot context.
+- Enforce short TTL and replay window for session and deep-link context tokens.
+
+### 2.2 Bot callback and command surface
+
+- Signed opaque callback payloads only; no mutable business state in query strings.
+- Update callback handling is idempotent with dedupe key `(callbackId, telegramUpdateId, telegramUserId)`.
+- Unknown callback payloads are rejected with audit logging and zero state mutation.
+- Hard rate limits on `/api/telegram/webhook` per IP and per Telegram user.
+
+### 2.3 Deep-link and redirect controls
+
+- Signed link payloads with short expiry and bound context.
+- Reject tampered/deprecated deep links by schema/nonce/version checks.
+- No direct redirect to non-whitelisted hosts.
+- Re-validate request ownership after deep-link state resolution.
+
+### 2.4 Wallet and payment evidence controls
+
+- Recipient, token, amount, and network checks must run before trust decisions.
+- Payment proof replay rejected when payload hash differs from signed first-seen proof.
+- Require provider-normalized reconciliation confirmation before marking funds complete.
+
+### 2.5 Bot token and secrets
+
+Secrets must never be in client-side code and must not be logged:
+
+- `TELEGRAM_BOT_TOKEN`
+- `TELEGRAM_WEBHOOK_SECRET`
+- `TELEGRAM_WALLET_PAY_TOKEN` (if Wallet Pay enabled)
+- `TON_CONNECT_MANIFEST_URL` / TON secret artifacts
+- provider API secrets and webhook keys for request-network/SHKeeper paths
+
+Apply Task 4 secret principles:
+
+- separate sandbox and production tokens/environments,
+- short rotation cadence,
+- strict allowlist for secret-bearing hosts.
+
+## 3) Compliance and secure configuration
+
+### 3.1 CORS / CSP / framing
+
+- Restrict Telegram endpoints to required app origins only.
+- CSP in Telegram surfaces should avoid wildcard connect/script allowances.
+- Add explicit `frame-ancestors` constraints for web entry surfaces that can be embedded.
+
+### 3.2 Access and authorization
+
+- Apply existing ownership rules from
+  [`Authorization Matrix - REST and Socket.IO`](Authorization%20Matrix%20-%20REST%20and%20Socket.IO.md).
+- Telegram-originated actions use the same actor checks as web actions, including admin step-up and two-person control for high-value override actions.
+- Dispute hold checks remain blocking for release/refund.
+
+## 4) Abuse controls
+
+1. **Spam / abuse**
+   - per-user command/chat throttle,
+   - per-IP flood detection on webhook.
+2. **Account takeover**
+   - suspicious Telegram session behavior triggers notification disable and forced re-link.
+3. **Wallet spoofing**
+   - signed wallet ownership checks + reconciliation proof checks.
+4. **Fake proof**
+   - malformed proofs logged; never auto-complete payment with unverifiable proof.
+5. **Support impersonation**
+   - support tools require signed admin context, with explicit role and actor logs.
+
+## 5) Monitoring and alerting
+
+Signals (and baseline targets):
+
+- `telegram_update_failures_total` (high if sustained >0.5%)
+- `telegram_initdata_invalid_total`
+- `telegram_callback_replay_total`
+- `telegram_payment_proof_mismatch_total`
+- `telegram_notification_blocked_total`
+- `telegram_payment_abnormal_status_jump_total`
+
+Alert rules (initial):
+
+- warning after 10 minutes, critical after 30 minutes or sustained spike above baseline.
+- any sudden increase in payment mismatch ratio requires incident triage.
+
+Where to emit:
+
+- Sentry for exception/error trending,
+- backend logs for structured events,
+- existing dashboard metrics hooks and runbook scripts where available.
+
+## 6) Operational controls required before launch
+
+- Secrets rotation checklist completed (bot token and payment/provider keys).
+- CORS/CSP reviewed and restricted to Telegram and known frontend origin.
+- webhook secrets configured separately for sandbox and production.
+- callback replay suppression validated in QA scenarios.
+- support impersonation checks and audit trails validated.
+
+## 7) Outstanding controls not yet implemented in this task layer
+
+- Two-way admin alerting channel for Telegram-specific abuse currently depends on operations integration.
+- Formal cryptographic replay store for deep-link one-time tokens (recommended before general rollout).
+- Telegram payment-specific policy page and end-user risk consent copy.