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

2.9 KiB

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):

    node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
    
  2. Set environment on the rotation job (not production API yet):

    export ENCRYPTION_KEY_PREVIOUS="<current-key>"
    export ENCRYPTION_KEY="<new-key>"
    export DATABASE_URL="<production-database-url>"
    
  3. Run the rotation script from backend/:

    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:

# 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.