139 lines
5.2 KiB
Markdown
139 lines
5.2 KiB
Markdown
---
|
|
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.
|