# Encryption key rotation (production) This runbook describes how to rotate `ENCRYPTION_KEY` without data loss. The application encrypts user PII, TOTP secrets, hot-wallet keys, and other sensitive columns at rest. ## Prerequisites - Maintenance window (API can stay up; rotation is I/O heavy on large tables). - Current and new 32-byte keys (base64 or hex per your `ENCRYPTION_KEY` format). - Database backup before starting. - Shell access to the API host or a job runner with `DATABASE_URL` and keys. ## Settings | Variable | Purpose | |----------|---------| | `ENCRYPTION_KEY` | Active encryption key (after rotation: the **new** key) | | `ENCRYPTION_KEY_PREVIOUS` | Previous key; required during rotation so `decrypt()` can read legacy ciphertext | | `ENCRYPTION_KEY_ROTATION_REMIND_DAYS` | Optional; days before daily reminder (default `90`) | The API records `encryption_key_rotated_at` in `system_settings` when rotation completes successfully. ## Rotation steps 1. **Generate a new key** (example): ```bash node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" ``` 2. **Set environment** on the rotation job (not production API yet): ```bash export ENCRYPTION_KEY_PREVIOUS="" export ENCRYPTION_KEY="" export DATABASE_URL="" ``` 3. **Run the rotation script** from `backend/`: ```bash npm run rotate-encryption-key ``` This re-encrypts all managed columns and updates `encryption_key_rotated_at`. 4. **Deploy the new `ENCRYPTION_KEY`** to all API/worker processes. Remove `ENCRYPTION_KEY_PREVIOUS` from runtime env after verification. 5. **Verify**: - Login, 2FA, withdrawals, and admin user detail (email decrypt). - Check logs for decrypt errors. - Confirm `encryption_key_rotated_at` in `system_settings`. ## Scheduled reminder On boot, the API runs a daily check (`encryptionRotationReminderService`). If the key is older than `ENCRYPTION_KEY_ROTATION_REMIND_DAYS`, it logs a warning and creates an admin notification. Rotation itself is **manual** (script above). Do not auto-rotate keys without updating deployment secrets in the same change window. ## Cron example (optional) Run rotation from a secure CI job or cron **only** when keys are pre-staged: ```cron # Example: quarterly rotation at 03:00 UTC on the 1st — adjust to your policy 0 3 1 */3 * cd /opt/games-app/backend && ENCRYPTION_KEY_PREVIOUS=... ENCRYPTION_KEY=... npm run rotate-encryption-key >> /var/log/encryption-rotation.log 2>&1 ``` After the job succeeds, update the orchestrator secrets and redeploy before removing `ENCRYPTION_KEY_PREVIOUS`. ## Rollback If rotation fails mid-run: 1. Stop the script. 2. Restore `ENCRYPTION_KEY` to the **previous** value across all services. 3. Restore database from backup if partial writes occurred. 4. Investigate logs from `rotate-encryption-key` before retrying.