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

title, tags, created, status

title	tags	created	status
Task 5.8 Telegram Security, Compliance, and Abuse Controls	taskmaster telegram security compliance abuse	2026-05-24	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, 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.
• 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.