KESTREL docs
 v1.0.0
Get help
● Operate · Keys, vault, sign-in

Security model
how keys, accounts and sessions are protected.

What KESTREL does to keep exchange keys and accounts safe, what you as the operator must do, and the one secret you must never lose.

AES-256-GCM vaultTrade-only keys2FA (TOTP)Sessions

01The layers

  1. Trade-only keys. A key with withdraw permission (on Binance, also one with internal transfer enabled) is refused, and there is no deposit or withdrawal feature at all (Why).
  2. IP whitelist. Each key works only from your server's IP.
  3. Encrypted vault. Keys are stored encrypted and never returned by any endpoint.
  4. Signed-in users only. Every trading route needs a session; the console has its own separate accounts.
  5. Audit. Every key action is recorded with its source and IP.

02The encrypted vault

Each secret (API key, secret, passphrase) is encrypted with its own fresh 256-bit data key using AES-256-GCM, and that data key is in turn encrypted with the master key, also AES-256-GCM (envelope encryption, server/src/vault/crypto.ts). The data key is wiped from memory after use. Keys are decrypted only in memory when the server talks to the exchange, and the cached connection is dropped when a key is rotated or removed.

The secret is write-only: the app sends it once, the server checks its permissions, encrypts it and stores it. No endpoint returns it; the app shows only a hint such as AbCd…wXyZ.

03The master key

Back it up, keep it private

KESTREL_MASTER_KEY in .env decrypts every stored exchange key, and the console's secrets are encrypted with a key derived from it (unless you set ADMIN_SECRET_KEY). If it is lost, every stored key is unreadable: users must enter their keys again. If it leaks together with the database, the keys can be decrypted, which is why they must be trade-only and IP-bound.

  • Copy .env into a password manager or onto an encrypted drive the day you install.
  • ./backup.sh copies .env next to each database backup. Store those backups privately, away from the server.
  • Never email it, never commit it, never paste it into a support request.
  • Moving to a new server: bring the old .env with the same master key, or the restored database cannot be read.

04User accounts

  • Passwords are at least 10 characters and stored as scrypt hashes.
  • Two-factor sign-in (TOTP). Settings, Security, Turn on 2FA: add the setup link or secret to an authenticator app and enter the code. Sign-in then asks for a code. The app recommends turning it on before connecting a live account. Turning it off needs a valid code and ends every other session.
  • Sessions. Settings, Security, Sessions lists every signed-in device with when it was last seen. Sign any of them out; ending a session also closes its live connections at once. The server stores only a hash of each session token.
  • New sign-in notifications: every successful sign-in creates a security notification.
  • Email verification with a 6-digit code before any email is sent to an address.
  • Rate limits on sign-in, registration, two-factor and verification attempts.
  • Disable: the operator can disable an account in the console, which ends its sessions and refuses sign-in.

05Connections

  • HTTPS through Caddy with an automatic certificate. The server container is not published; only Caddy is reachable from outside.
  • Live connection tickets. The app opens its WebSocket with a single-use ticket valid 30 seconds and bound to the session; session tokens are never put in a URL. At most 5 sockets per user, with a message rate limit.
  • CORS and WebSocket origins are limited to your PUBLIC_URL by the installer.
  • The console uses its own cookie session and roles. An app token never opens it.

06What you must do as the operator

  • Back up .env and the database, and keep the backups private (they contain two-factor secrets and session hashes as well as the encrypted keys).
  • Keep the server updated: sudo apt update && sudo apt upgrade, and ./update.sh for new KESTREL versions.
  • Allow only SSH, 80 and 443 in the firewall; use SSH keys rather than passwords.
  • Turn on two-factor sign-in for your console account, and require it for managers under Security & alerts.
  • Never set ADMIN_DEMO_PASSWORD on a real install.
  • Tell your users the three key rules: trade-only, withdrawals off, IP whitelist.

07Reporting a security issue

Report a vulnerability privately through the support tab of the item page, with steps to reproduce. Please do not post it in public comments (Support).