Security
Security
Security model
WhelkMail is intended for personal or small trusted deployments. This page describes what it protects and what it deliberately does not.
Authentication
- Single shared password + optional 2FA:
APP_PASSWORDprotects the whole deployment. Two-factor authentication (TOTP, RFC 6238) can be enabled in Settings → Security; it is off by default and works with any authenticator app. Recovery codes are shown once and stored only as SHA-256 hashes. - Sessions: random 256-bit session IDs; only their SHA-256 hashes are stored in D1 (
sessions). TTL is 7 days. Cookies areHttpOnly,SameSite=Lax, andSecureon HTTPS. Logout revokes the session. Deleting thesessionstable rows invalidates all sessions. - Brute-force protection: login and 2FA attempts are rate limited per IP in D1 (10 attempts per 15 minutes, then a 15-minute block).
- Origin check: mutating requests with a foreign
Originheader are rejected.
OAuth
- One-time state stored in D1 with a 10-minute TTL.
- PKCE (
S256) for Google, Microsoft and Google Drive.
Credential encryption
- IMAP/SMTP passwords, OAuth refresh tokens and relay API keys are encrypted with AES-256-GCM using
TOKEN_ENC_KEY(32 raw bytes, base64 encoded). - Session/challenge signatures use an HKDF-derived subkey.
- Key rotation: changing
TOKEN_ENC_KEYmakes all stored credentials unreadable and invalidates sessions and pending OAuth states. Users must re-enter passwords and reconnect OAuth accounts.
Response headers
CSP, HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy and Cross-Origin-Opener-Policy are set on static assets (public/_headers) and API responses (middleware).
Email rendering
- HTML bodies are rendered in a sandboxed iframe with a restrictive CSP.
- Scripts and forms are blocked.
- Remote images and tracking pixels are blocked by default and can be enabled per message (or globally in Settings).
- Small
cid:inline images are embedded as data URIs; larger ones use the authenticated attachment endpoint. - Links open in a new tab.
Data protection
- By default, messages, sent copies, drafts and attachments stay on the mail provider.
- The D1 body cache is short-lived and bounded (512 KB per body, 3 days, 64 MB total).
- Long-term archiving on R2 or Google Drive is strictly opt-in per account.
- Deleting an account never deletes mail from the provider.
Secrets hygiene
.dev.vars,.envand.wranglerare gitignored.- Production secrets belong in the Pages project settings.
- The public repository must never contain
wrangler.toml,worker/wrangler.toml,.dev.vars,.env*or any secret.
No multi-tenancy
There is no per-user isolation. This is intended for personal or small trusted deployments. Put Cloudflare Access in front for stronger authentication. Login and 2FA rate limiting are present but per-IP only, and are not a substitute for Cloudflare Access or a WAF.
Account authentication methods
| Provider | Method |
|---|---|
| Google accounts | OAuth2 (recommended) or app password (2-Step Verification required) |
| Outlook / Microsoft 365 | OAuth2 + XOAUTH2 (basic auth is no longer supported by Microsoft) |
| Yahoo | App password |
| iCloud | App-specific password |
| Generic IMAP | Account password or app password |
| Relay accounts | Provider HTTP API key (+ secret/domain where required) |
Recovering from lost 2FA
If you lose both the authenticator and the recovery codes, disable 2FA from a D1 console:
DELETE FROM app_settings WHERE key IN ('totp_enabled', 'totp_secret_enc', 'totp_recovery_json');
DELETE FROM sessions;
Known security limitations
- The reply alias comes from headers that aren’t signed. Forwarding headers only count when the receiving server’s topmost
Authentication-Resultsreports a passing DKIM signature for the domain, which stops a forged header on mail delivered straight to the inbox. A receiving server that adds noAuthentication-Resultsof its own, or a genuinely signed message replayed with a forwarding header, can still mislead it. The address is always limited to the relay’s exact domain and is shown in the From field before sending. - Provider error details are returned to the authenticated admin to help with IMAP/SMTP setup. Generic API errors carry a stable
code; only authenticated administrators see provider details. - There is no audit log.
Hardening checklist
- Use a long random
APP_PASSWORD. - Enable TOTP two-factor authentication.
- Keep
TOKEN_ENC_KEYsecret and backed up. - Serve the app over HTTPS only.
- Put Cloudflare Access in front for anything beyond a personal deployment.
- Rotate secrets according to the procedure in Deployment.