Skip to content
Chatto v0.5.0

Security & Privacy

Chatto protects accounts, sessions, and message text. You protect the host, the reverse proxy, the secrets, and the backups. This page describes both parts.

  • Serve Chatto over HTTPS and add HSTS at your reverse proxy.
  • Set webserver.url to the public HTTPS address.
  • Set webserver.trusted_proxies to the address of your reverse proxy only.
  • Add rate limits at your reverse proxy or firewall. Chatto has no built-in rate limits.
  • Keep the Content Security Policy header and meta tag from Chatto. Do not inject scripts through your proxy.
  • Protect chatto.toml, the environment variables, the NATS data directory, the search index, and your backups.
  • Keep the operator socket private to the Chatto process.
  • Chatto stores passwords as bcrypt hashes. New passwords must have 8 to 72 UTF-8 bytes. A character can use more than one byte. Chatto rejects passwords outside these limits and does not truncate them. API clients must count UTF-8 bytes when they validate a new password. Existing password hashes remain valid.
  • Sessions use random, opaque credentials, not JWTs. Browser cookies are HttpOnly, SameSite=Lax, and Secure on HTTPS.
  • Other clients get an access token that expires after 15 minutes and a refresh credential that changes at each renewal. Sessions end after 90 days without use. Change these durations with auth.access_token_ttl and auth.token_ttl.
  • A password change or reset makes older sessions and tokens invalid.
  • Sign-in, registration, and password reset give the same response for known and unknown accounts. This prevents account discovery.
  • Email verification codes expire after 30 minutes. Password reset links expire after one hour.

Set webserver.cookie_encryption_secret to encrypt short-lived sign-in state. chatto init generates this secret. Chatto logs a warning when it is missing.

Any Chatto client can ask for access to your server. The client identifies itself with a published metadata document, and the member approves each new client. Approval is not an endorsement: tell members to approve only clients that they recognize.

Authorized clients appear in Server settings → Security → OAuth clients. You can label a client as trusted, or block it. A block stops new authorizations and makes the client’s tokens invalid.

Every API request goes through the permission system. Administrative and moderation permissions become effective only after an administrator enables privileged mode for 15 minutes. Bot API keys do not use privileged mode.

The first owner comes from owners.emails. Chatto matches only verified email addresses, so a user cannot claim ownership with an address that they do not control.

Administrators cannot read conversations that they are not part of through Chatto. This is an application boundary, not a cryptographic one. A person who controls the server, its storage, and its keys can read more.

Chatto encrypts some fields before it stores them. This is not full-disk encryption or end-to-end encryption. The running server decrypts these fields for authorized clients. The table below gives the protection boundary.

DataEncrypted by Chatto
Message text and attachment descriptionsYes
Login name, display name, bio, and verified email addressYes
PasswordsNo. Chatto stores only bcrypt hashes.
Attachments, avatars, branding images, and video derivativesNo. Use storage encryption.
Filenames, authors, room and thread IDs, timestamps, reactions, link previews, statuses, preferences, and other metadataNo
Configuration secrets and runtime recordsNo. Protect the host and NATS storage.

Each account has its own data keys. Chatto encrypts these keys with key-encryption keys, which it keeps in the NATS ENCRYPTION_KEYS bucket.

Encryption protects the encrypted fields when a person gets:

  • the event stream or a data backup, but not the ENCRYPTION_KEYS bucket or a key export
  • changed ciphertext. Chatto finds the change and does not decrypt the field.

Encryption does not protect them from:

  • a person who controls the running server, or who has both the data and the keys
  • code that runs in the Chatto process
  • clients that are authorized to read the data through the API
  • access to asset storage, because Chatto does not encrypt files

A member deletes their account in Account Settings. This needs user.delete-self. An administrator with admin.view-users and user.delete-any deletes other members on the member page in Server Administration. The administrator confirms the login of the account but does not enter a password again.

Deletion destroys the keys of the account (crypto-shredding). After that, Chatto cannot read the message text or protected profile fields of the member, and it shows their messages as unavailable. Chatto also deletes their attachments, avatar, settings, and memberships. The user ID, timestamps, room relationships, and other metadata stay in the event history.

Use Backup & Restore to choose whether to include keys, protect key exports, and restore data. The guide also covers S3 objects and retention after account deletion.

An old backup with keys can make deleted data readable again. Apply your deletion policy to data archives, key exports, object versions, and storage snapshots.

Chatto can get Let’s Encrypt certificates by itself:

[webserver]
url = "https://chat.example.com"
[webserver.tls]
enabled = true
domain = "chat.example.com"
email = "admin@example.com"

Chatto needs ports 80 and 443 for this. It then requires TLS 1.2 or later and redirects HTTP to HTTPS. The certificate cache directory must belong to the Chatto user.

If a reverse proxy terminates TLS, set webserver.url to the HTTPS address. Chatto ignores forwarded-host and client-IP headers unless the request comes from a trusted proxy:

[webserver]
url = "https://chat.example.com"
trusted_proxies = ["172.20.0.0/24"]

Use the narrowest address range that contains your proxy. The proxy must overwrite X-Forwarded-For, X-Real-IP, and X-Forwarded-Host.

Chatto sends these headers with every page:

HeaderValue
X-Content-Type-Optionsnosniff
X-Frame-OptionsDENY
Referrer-Policystrict-origin-when-cross-origin
Content-Security-Policyframe-ancestors 'none'

The page also enforces a Content Security Policy that allows only Chatto’s own scripts. Other sites cannot show Chatto in a frame. All uploaded files are served with a sandbox policy, except passive types: PNG, JPEG, GIF, WebP, AVIF, video, audio, plain text, and PDF. HTML previews open only after the member agrees, in a frame without permissions.

Requests from other origins cannot use session cookies. They must send a bearer token.

The operator API gives root-level access to accounts. It is off by default. When you enable it, it listens only on a Unix socket with mode 0600, never on the web port. File system permissions control access to it.

Your configuration contains these secrets:

  • core.secret_key
  • cookie signing and encryption secrets
  • the asset signing secret
  • S3, NATS, SMTP or JMAP, login provider, Web Push, and LiveKit credentials

A change to core.secret_key signs out every session and makes invitation codes and pending sign-in links invalid. It does not change the encryption keys.

Protect key exports and backups with keys like the secrets above. See Backup & Restore.

Follow the security policy.