Security model

Reporting vulnerabilities

Email [email protected]. Please do not open public GitHub issues for unpatched vulnerabilities. Acknowledgement target: 72 hours. Fixes are disclosed in the CHANGELOG once a release ships.

End-user support

For product help (setup, disconnect, billing questions): email [email protected]. Do not use the security address for general support.

Trust boundaries

Every database lookup for user content is intended to be scoped to the owning user. Compromise of one account should not expose another account unless the service, key derivation, or deployment boundary itself is compromised.

What the server sees

• Plaintext MTProto traffic and tool content in memory. The service must decrypt the session and message/action fields while processing them.
• Encrypted Communication Agent content at rest. When the listener is enabled, relevant message bodies and proposed action payloads are durably stored for queue recovery, policy evaluation, approval, and conversation context.
• Audit metadata, persisted separately. Tool/action name, redacted peer reference, status, and redacted error text. Audit rows do not contain Telegram message bodies.

Communication Agent safety boundary

The model prompt and model output are not trusted as a security boundary. The server-side listener, state machine, policy engine, approval flow, and Telegram send gate remain authoritative.

• Explicit enablement. Only profiles with the listener enabled receive durable Telegram updates. Disabling a profile removes the listener account and immediately stops its pinned Telegram client.
• Crash-safe ingestion. Incoming event, queue job, and conversation activity timestamp are committed in one transaction. Database failures are returned to Telegram's update manager so the update watermark is not acknowledged and gap recovery can retry.
• Saved Messages privacy. Only an explicit first-token /mctl command is stored and routed. Ordinary notes in Saved Messages are ignored.
• Human takeover. A genuine owner reply, including a media-only reply, moves the conversation to taken_over. Programmatic text/media sends are correlated by their Telegram message ID so their echo is not mistaken for a human reply.
• Fail-closed policy. Unknown modes, states, and action types are denied. The global kill switch, off/paused profiles, blocked senders, peer mismatch, missing disclosure, unsafe links/credentials/phone-like content, and invalid structural limits deny an action.
• Approval modes. observe mode requires owner approval for replies. guarded mode can allow only allowlisted replies that satisfy every server-side policy, turn budget, and rate constraint; other actions require approval or are denied.
• No blind retry after a possible send. The action lifecycle uses compare-and-set transitions. If a process crashes after entering executing, that action is not automatically retried, avoiding duplicate messages.

Enabling the listener does not bypass the existing ALLOW_SEND, scope, per-account, and per-peer send gates.

Communication Agent storage and retention

• incoming_events and conversation_messages may contain third-party Telegram message bodies.
• agent_actions may contain proposed reply payloads and approval/policy metadata.
• Message bodies and action payloads are AES-256-GCM sealed with the owner's derived key before database storage.
• A daily sweeper deletes stored agent message content older than AGENT_RETENTION_DAYS; default is 30 days. Setting it to 0 keeps rows indefinitely.
• Audit retention is separate: AUDIT_RETENTION_DAYS defaults to 90 days and audit rows contain no message body.

Local Bridge mode

When an account is set to mode='local', its MTProto session lives on the user's machine instead of the hosted server:

• Session bytes are not stored on the server. session_encrypted is NULL for local-mode accounts.
• Tool arguments and responses still pass through relay memory. The relay can see plaintext while routing the call and does not provide end-to-end encryption from the MCP client to the daemon.
• Audit content remains metadata-only. The call_path marks local relay calls, while message bodies are excluded from audit rows and stdout.
• Communication Agent limitation. A hosted listener requires an active server-side Telegram client. Do not assume Local Bridge automatically provides the same always-on listener semantics without an explicitly deployed local listener path.

What logs and audit rows never persist

• Telegram message bodies or proposed reply payloads
• Phone numbers, login codes, or 2FA passwords
• Raw MTProto session bytes
• OAuth signing secrets, encryption keys, or derived per-user keys
• Authorization: Bearer header contents

This guarantee applies to logs and audit rows. Communication Agent message/action tables intentionally store encrypted content as described above.

Known coupling: shared-hmac-legacy mode

AUTH_MODE=shared-hmac-legacy validates JWTs using secret material shared with an external authorization service. This coupling does not apply to the default local-jwt mode.

• Impact: compromise of either service's shared secret can affect both trust domains.
• Mitigation: rotate the shared secret for both services in the same change and prefer local-jwt for new deployments.

Cryptographic invariants

• ENCRYPTION_KEY must be 32 random bytes, hex-encoded as 64 characters. Production must set it.
• MTProto session blobs, agent message bodies, and action payloads are AES-256-GCM sealed with per-user HKDF-derived keys.
• Legacy single-key session blobs are migrated to the per-user format when read.
• The deployment operator or an attacker controlling the running pod and key material can decrypt user data. Hosted mode is not zero-knowledge.

Send gate (defense in depth)

On production tg.mctl.ai, ALLOW_SEND=false is the safe default. Real Telegram sends through send_message or send_media require all of:

1. Server flag ALLOW_SEND=true.
2. Identity has telegram:messages:send scope.
3. telegram_accounts.send_enabled = true for that operator.
4. The per-peer send rate limit is not exhausted.

Any failed condition returns a dry-run result (sent=false) with a dry_reason; no send RPC reaches Telegram. A denied media call does not fetch its URL or decode its base64 payload.

Authentication-required mode

• AUTH_REQUIRED=false is for local development only. Production must use authenticated OAuth mode.
• AUTH_MODE=local-dev returns a fixed platform-admin identity and must not be reachable from a public production interface.

Rate limiting

The default per-identity token bucket is 30 requests/minute with the same burst. Write paths additionally use per-peer limits so one recipient cannot be targeted up to the global ceiling. Public and well-known endpoints are limited at the ingress layer.

Session TTL

• Idle TTL — 30 days. A session not used within the idle window is revoked.
• Absolute TTL — 90 days. A session past expires_at is revoked.
• An hourly sweeper applies the same predicate to abandoned rows.

Tamper-evident audit log

Audit rows form a SHA-256 hash chain using prev_hash and entry_hash. You can ask the server to verify the chain:

GET /api/account/audit/verify
{
  "ok": true,
  "verified": 42
}

A non-OK response includes first_bad_id and a reason. Rows created before hash chaining are skipped.

Prompt-injection content boundary

Read tools wrap Telegram message bodies in <telegram-content origin="telegram" peer="redacted" untrusted="true">…</telegram-content> and escape literal closing tags inside message text. This is a signalling boundary for the MCP client, not a substitute for the server-side Communication Agent policy engine.