---
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.