Telegram Mini App Security Auditor

Audit Telegram Mini App projects for launch safety before connecting bot tokens or public channels. Use when Codex needs to review a Telegram WebApp/Mini App, TMA frontend, FastAPI/Node backend, BotFather launch runbook, Colab/ngrok deployment, or OpenClaw/Codex skill that handles Telegram initData, bot tokens, admin endpoints, CORS, PII, request forms, or public channel launch readiness.

Audit Telegram Mini Apps with a static, evidence-first workflow. Prefer the bundled script for repeatability, then inspect the flagged files before giving launch advice.

Quick Start

Run the static auditor from the skill folder:

python3 {baseDir}/scripts/audit_tma.py \
  /path/to/project \
  --out-dir /tmp/tma-audit

Expected outputs:

• tma_security_audit.json
• tma_security_audit.md

Decision meanings:

• PASS: no blocking or review-triggering evidence found by this static pass.
• REVIEW: launch only after a human verifies the listed risks.
• BLOCK: do not launch or connect production bot tokens until fixed.

Workflow

1. Run scripts/audit_tma.py against the project root or Mini App subdirectory.
2. Read the Markdown report and inspect every BLOCK and REVIEW file reference.
3. If the app is not detected as a Telegram Mini App, confirm whether the user passed the correct path.
4. For production launch, require all of these:
   • server-side Telegram initData validation,
   • no committed bot tokens or token-like literals,
   • admin endpoints protected by server-side authorization,
   • no broad CORS in production,
   • request forms reject or avoid contact details, handles, secrets, and payment terms when governance requires it,
   • local/browser QA evidence before BotFather or channel changes.
5. If packaging as a ClawHub/Codex skill, run TrustClaw after this audit:

trustclaw scan /path/to/skill --format markdown

Finding Triage

Treat script output as static evidence, not a final safety determination.

• hardcoded-telegram-token: always BLOCK; rotate the token if it was committed.
• initdata-no-server-validation: BLOCK; Mini App users must not be trusted from client-side data alone.
• insecure-initdata-bypass: usually REVIEW; acceptable only for clearly documented local dev commands and disabled-by-default server behavior.
• cors-wildcard: REVIEW, or BLOCK if credentials are also enabled.
• admin-endpoint-without-guard: BLOCK.
• unsafe-innerhtml: REVIEW; verify escaping or sanitization.

For detailed rules and manual checks, read references/tma-security-checklist.md only when needed.

Output Contract

When answering a user, lead with:

1. decision,
2. highest-severity findings with file paths,
3. launch recommendation,
4. artifacts produced,
5. any limitations of the audit.

Keep live Telegram/BotFather/channel changes out of scope unless the user explicitly asks to launch and the project has passed audit and QA.