games_app/deploy/ENCRYPTION_KEY_ROTATION.md
2026-07-07 15:03:17 +02:00

78 lines
2.9 KiB
Markdown

# 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="<current-key>"
export ENCRYPTION_KEY="<new-key>"
export DATABASE_URL="<production-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.