Documentation menu

Getting started

New in v2.0

Feature deep dives

System atlas

Reference

Learn

Security

Telegram Automation Security & Isolation

How the platform keeps tenants apart: fail-closed identity scoping across bot, dashboard, mobile, REST and gRPC, AES-256-GCM at rest — and its stated limits.

Verified against the checkout built for v2.2.4 · updated 20 Oct 2026

On this page

Security deep dives
Isolation model
Where it is enforced
Cryptography
Secrets handling
Network posture
Audit trail
Known limits

AutoTelegramForward runs one installation for one operator's accounts — and optionally for many. The design decision that shapes everything else is that isolation is fail-closed: the default answer to "may this caller read this row?" is no, and a caller who has not linked a Telegram account can read nothing at all.

Security deep dives

This page states the model. Three companions show the machinery underneath it — which query carries the owner, where a secret can be read back, and what a hostile request meets before it reaches a handler.

Tenant isolation

Owner scoping per surface, the three refusals, the owner-zero trap and the tests that enforce it.

Secrets & keys

What is encrypted, what is write-only, what redaction does to a phone number, and how to rotate each credential.

Request hardening

Body caps, server timeouts, the endpoint guard that blocks SSRF, and the shutdown drain.

Isolation model

Identity is a number, not a claim. Each surface resolves the caller to a numeric Telegram user id, that id travels with the request through every layer, and each data access is scoped by it.

Telegram bot

Commands resolve the caller to a numeric user id and load only that account's tasks, sessions and history.

Web dashboard

Bearer token from the authentication routes; every request carries the resolved identity into the handler.

Mobile app

Signs in through the same routes and talks to the same API — there is no second, weaker path.

REST API

Tenant-scoped handlers; an unlinked account resolves to id 0 and therefore owns nothing.

gRPC services

Internal calls carry the caller identity that the control plane verified, never one the client asserts.

Administration

Mounted behind RequireAdmin: without admin rights the route set is unreachable, not merely hidden.

Where it is enforced

Isolation controls and what happens when they say no
Control	Implementation	Failure mode
Ownership checks	Every task, session, filter, AI configuration and prompt template is read through the caller's own scope.	Not-yours and not-found return the same 404, so ids cannot be probed.
Unlinked accounts	A zero user id is treated as owning nothing.	Empty collections, never a fallback to a shared account.
Admin routes	Mounted behind an admin requirement in the parent mux	The route does not exist for non-admins.
Simulation	The dry-run endpoint loads the rule through the same ownership check	You can only preview rules you own.
Log history	Queries are filtered server-side by actor and scope before returning rows	No client-side filtering to bypass.
Backups	Export and import are tenant-scoped and encrypted	A stolen file is useless without the passphrase.

Ownership checks
Implementation
Every task, session, filter, AI configuration and prompt template is read through the caller's own scope.
Failure mode
Not-yours and not-found return the same 404, so ids cannot be probed.
Unlinked accounts
Implementation
A zero user id is treated as owning nothing.
Failure mode
Empty collections, never a fallback to a shared account.
Admin routes
Implementation
Mounted behind an admin requirement in the parent mux
Failure mode
The route does not exist for non-admins.
Simulation
Implementation
The dry-run endpoint loads the rule through the same ownership check
Failure mode
You can only preview rules you own.
Log history
Implementation
Queries are filtered server-side by actor and scope before returning rows
Failure mode
No client-side filtering to bypass.
Backups
Implementation
Export and import are tenant-scoped and encrypted
Failure mode
A stolen file is useless without the passphrase.

Cryptography

Cryptographic primitives in use
Data	Protection	Notes
Session strings and API keys at rest	AES-256-GCM	Authenticated encryption; a modified ciphertext fails to decrypt rather than decrypting wrongly.
Account passwords	PBKDF2-SHA256, 240 000 iterations, per-user salt	Verified in constant time; the iteration count is stored per row so it can be raised later.
Configuration backups	AES-256-GCM bundle	Portable between servers: export on one host, import on the next.
Session backups	Encrypted archive	Written only after the export succeeds, and never in plaintext.
Web traffic	TLS	Terminate at your reverse proxy; the app itself is meant to sit behind one.

Session strings and API keys at rest
Protection
AES-256-GCM
Notes
Authenticated encryption; a modified ciphertext fails to decrypt rather than decrypting wrongly.
Account passwords
Protection
PBKDF2-SHA256, 240 000 iterations, per-user salt
Notes
Verified in constant time; the iteration count is stored per row so it can be raised later.
Configuration backups
Protection
AES-256-GCM bundle
Notes
Portable between servers: export on one host, import on the next.
Session backups
Protection
Encrypted archive
Notes
Written only after the export succeeds, and never in plaintext.
Web traffic
Protection
TLS
Notes
Terminate at your reverse proxy; the app itself is meant to sit behind one.

Secrets handling

The API never echoes a secret. The environment-contract route reports set: true/false per key plus a fix hint — never the value.
Validation scans for committed secrets as part of the read-only check set, alongside layout, compose, catalog parity and ports.
Backups can be exported without secrets, so a configuration bundle can be shared for review while credentials stay home.
Setup writes .env with restrictive permissions and refuses to continue when a required key is missing or malformed.

Environment key contract

Network posture

What listens where, and how to tighten it
Surface	Default exposure	Hardening
Dashboard/API	Behind your reverse proxy	TLS at the proxy; the app trusts only what the proxy forwards.
Bot	Outbound to Telegram only	No inbound listener beyond the Telegram connection itself.
gRPC core	Loopback inside the compose network	Containers reach each other by service name; nothing is published.
Logger service	Loopback inside the compose network	The API proxies log queries, so clients never address it directly.
PostgreSQL	Loopback unless you expose it	Use the bundled default for single-host installs.
Health endpoints	Public	Return booleans and latencies only — never configuration values.

Dashboard/API
Default exposure
Behind your reverse proxy
Hardening
TLS at the proxy; the app trusts only what the proxy forwards.
Bot
Default exposure
Outbound to Telegram only
Hardening
No inbound listener beyond the Telegram connection itself.
gRPC core
Default exposure
Loopback inside the compose network
Hardening
Containers reach each other by service name; nothing is published.
Logger service
Default exposure
Loopback inside the compose network
Hardening
The API proxies log queries, so clients never address it directly.
PostgreSQL
Default exposure
Loopback unless you expose it
Hardening
Use the bundled default for single-host installs.
Health endpoints
Default exposure
Public
Hardening
Return booleans and latencies only — never configuration values.

Audit trail

The access logger mirrors every request — successes included, not just failures — into the central logger with the verified actor, the subject task and the correlation id. That is what makes "who changed this rule, and what did it do next" answerable after the fact.

Attributable entries

Each entry names the actor, the service, the level and the subject.

Bounded queries

Filter by service, level, text and time; results page instead of flooding.

Exportable evidence

History exports as JSON or CSV, and purge is an explicit, scoped action.

Known limits

Being straight about the boundaries is part of the design. These are the things you should know before you rely on the platform in a regulated setting.

Static analysis reports pre-existing findings in the backup export helper. They are known, tracked and do not grant a tenant access to another tenant's data — but the export path deserves your own review before you handle third-party data.
TLS is expected at your reverse proxy. The service itself speaks plain HTTP on the internal network by design.
Encryption keys are your responsibility: lose the key material and encrypted backups cannot be recovered, by us or by anyone.
Your Telegram accounts remain subject to Telegram's own rate limits and terms; the platform is built to respect FloodWait rather than defeat it.