Docs / Security model
Security model
Read-only by design. Here's exactly what we store, what we never touch, and what's yours to protect.
What we never do
- We never hold, generate, or see private keys.
- We never generate deposit addresses, custody funds, or move money. tronhooks only reads the chain.
- We never store your API key or webhook secret in plaintext: keys are SHA-256 hashed; webhook secrets are AES-256-GCM encrypted at rest.
What you must protect
1. The Telegram binding link is a temporary password. Anyone who opens t.me/tronhooks_bot?start=<code> within its 10-minute lifetime binds their chat to your account and receives your deposit alerts. Don't screenshot it, don't forward it. Mitigations on our side: codes are single-use, expire in 10 minutes, issuing a new code voids the old one, the console always shows which chat/group is bound, and the previously bound chat gets an explicit "binding moved" notice on any rebind.
2. Verify webhooks against the RAW body. Compute HMAC-SHA256 over the exact bytes received, before JSON parsing, and compare in constant time — see the verification guide. An unverified webhook endpoint will happily credit deposits an attacker invented.
3. Dedupe on event_id. Deliveries are at-least-once. If your handler isn't idempotent, a retry after a served-but-timed-out request credits a deposit twice.
- API keys (
tw_…) and webhook secrets (whsec_…) are shown once. Store them in a secret manager; rotate by revoking/recreating. - Keys are network-bound (test/live) — use separate keys per environment and never commit either.
Platform hardening (what's already in place)
- Webhook SSRF protection: your webhook URL is validated at creation and re-validated at every delivery — DNS re-resolved, private/reserved ranges rejected, and the connection is pinned to the validated IP (DNS-rebinding defense).
- Finality: events are emitted only from finalized (solidity-node) chain data — no reorg phantom deposits.
- Console: argon2id password hashes, httpOnly/SameSite session cookies, CSRF double-submit tokens, login brute-force lockout.
- Auditability: every delivery attempt is logged with its response code; nothing fails silently.
Out of scope (planned)
Email verification, password reset, 2FA, and team accounts are on the roadmap. Until password reset ships, losing your password means contacting ops@tronhooks.com.
Security reports: ops@tronhooks.com — we read everything.