For product/data context, see docs/PRODUCT_DIRECTION.md and docs/DATA_MODEL.md. Security rules apply to Server Mode; Local Mode stays on-device unless a future explicit migration/import flow is designed.

Last reviewed 2026-10-21. Status means: In place — enforced in code and covered by a guardrail or test; Partial — enforced with a documented limitation; To be added — not implemented yet.

Evidence for every row lives in Security Posture and the control-by-control inventory with file:line citations in SECURITY_CONTROLS.md. The "To be added" table is the reference checklist's items this project does not implement yet, plus the verified gaps recorded in that inventory.

If you discover a security vulnerability, please report it privately. Do not open a public issue.

Contact: Report a vulnerability privately through GitHub's private vulnerability reporting (the repository's "Security" tab), or email the repository owner directly.

Include:

• Description of the vulnerability.
• Steps to reproduce.
• Potential impact.
• Suggested fix (if any).

We aim to acknowledge reports within 48 hours and provide a fix or mitigation plan within 7 days.

• Passwords are hashed with PBKDF2 (configurable iterations via AUTH_PBKDF2_ITERATIONS, default 310,000).
• Passwords are never logged, returned in API responses, or stored in plaintext.
• Client-side credential envelopes optionally encrypt credentials in transit using an RSA key pair (AUTH_CREDENTIALS_PRIVATE_KEY).

• Sessions use encrypted JWT (JWE) via Nimbus JOSE JWT + BouncyCastle key derivation.
• Session lifetime is configurable (AUTH_SESSION_MAX_AGE_SEC, default 24h).
• Sessions are delivered in HTTP-only authjs cookies: __Secure-authjs.session-token in production and authjs.session-token elsewhere. Bearer tokens are also accepted for API clients.
• Sessions persist across browser/app restarts (no session-only cookies).
• Server-enforced token versioning (tokenVersion on User model) revokes all sessions on password change or sign-out.
• The Ktor pipeline intercept validates tokens on every request by checking tokenVersion, expiry, role, and approval status against the database before route handlers read the session.
• Mobile sessions use encrypted cookie storage with session restoration on app launch.

• New accounts default to PENDING approval status.
• Only APPROVED users can access protected API routes and app pages.
• Admin approval is required before new users gain access.

• Auth endpoints are rate-limited per IP and per email (configurable windows and thresholds).
• App-layer request throttling protects /api/**, /health, /api/mobile/probe, POST /api/todo/summary, POST /api/user/change-password, and /ws.
• Exponential lockout activates after repeated credential failures (AUTH_LOCKOUT_* settings).
• Rate limit and lockout state is stored in the database (AuthThrottle model).

• Admin routes require both APPROVED status and ADMIN role.
• Admin checks are centralized in the shared auth context helper used by routes and services.

All API requests pass through Ktor plugins that enforce:

• Authentication: Security.kt reads a JWE token from the Authorization header or session cookies and attaches validated claims to the call.
• Approval gate: call.withAuth { } rejects unapproved users from private REST routes, and /ws rejects pending users during the handshake.
• Token refresh: Claims are verified against the database on every request (role, approval, tokenVersion).
• Request throttling: RateLimiting.kt applies route-specific 429 responses before protected handlers run.

Every response includes (via SecurityHeaders.kt):

• The Docker host port is bound to 127.0.0.1 (localhost only) by default, preventing direct external HTTP access. Traffic reaches the backend through a tunnel or VPN — see Remote Access for all supported methods (Cloudflare Tunnel, Tailscale, WireGuard, ZeroTier, SSH tunnels, ngrok, frp).
• Direct external access is opt-in: set TDAY_HOST_BIND=0.0.0.0 in the project-root .env file. This is discouraged for production.
• Production deployments should use a method that provides TLS termination (Cloudflare Tunnel, ngrok, Caddy reverse proxy, or Tailscale Funnel).
• VPN-based methods (Tailscale, WireGuard, ZeroTier) encrypt traffic at the tunnel layer; browser-trusted HTTPS is optional but recommended for production cookie security.
• HSTS headers are applied when TDAY_ENV=production (NODE_ENV=production is still accepted as a compatibility fallback).

• Sensitive database fields can be encrypted/decrypted transparently at the service layer.
• Uses AES-256-GCM with configurable key ID and AAD (DATA_ENCRYPTION_* variables).
• Key rotation is supported: keep previous keys in DATA_ENCRYPTION_KEYS during rollover.

• Android server URL and credentials are stored in EncryptedSharedPreferences.
• iOS server config, credentials, cookies, and mode state are stored through Keychain-backed SecureStore.
• Session cookies persist in encrypted platform stores.
• Android task data is cached in Room; iOS task data is cached in SwiftData. Both caches are local app data and are cleared through logout/session invalidation flows where appropriate.
• Local Mode does not send task/list/floater data to a server and should not silently migrate local-only data into Server Mode.
• Optional public-key fingerprint pinning for self-hosted servers.
• All local user data (credentials, cache, cookies) is wiped on logout or session invalidation.
• Custom client headers (X-Tday-Client, X-Tday-App-Version, X-Tday-Device-Id) for audit trails.
• OkHttp logging redacts Cookie and Set-Cookie headers.

• Production secrets should come from a secrets manager or mounted files.
• The Ktor backend (AppConfig.kt) supports _FILE suffix for all sensitive variables: AUTH_SECRET, DATABASE_URL, DATA_ENCRYPTION_KEY, DATA_ENCRYPTION_KEYS, DATA_ENCRYPTION_AAD.
• Never commit real secrets. .env.example contains placeholder values only; .env.docker is a local ignored runtime file created from that template.
• Rotate secrets on a fixed schedule (recommended: 60-90 days).

• Keep dependencies updated regularly.
• Review npm audit output before merging dependency updates.
• Pin major versions in tday-web/package.json to avoid surprise breaking changes.
• Android and backend dependencies are version-locked in build.gradle.kts.

Structured security event codes are emitted to the eventLog database table:

The request-rate event includes a reason detail such as api_rate_limit, infra_rate_limit, summary_rate_limit, change_password_rate_limit, or websocket_rate_limit.

Alert when auth_lockout grows rapidly, auth_limit_ip spikes from a narrow IP range, session-clearing events cluster unexpectedly, or request_rate_limit_triggered starts clustering on one path.