All Docs
FeaturesCalmony Sanctions MonitorUpdated March 12, 2026

HIPAA-06: Encryption Key Rotation — What Changed and How to Use It

HIPAA-06: Encryption Key Rotation — What Changed and How to Use It

Version: v0.1.160 Compliance Framework: HIPAA Control: HIPAA-06

Background

The sanctions screening platform encrypts sensitive fields at rest. While the encryption module (src/lib/encryption.ts) has always documented that key rotation involves replacing ENCRYPTION_SECRET and re-encrypting stored data, no tooling or step-by-step procedure existed to do this safely.

In practice, this meant encryption keys were never rotated — the operational complexity of manually re-encrypting every record was a barrier that made rotation effectively impossible without risk of data loss or downtime. HIPAA-06 requires that encryption keys be rotatable as part of a sound data-protection posture.

v0.1.160 closes this gap.

What Was Implemented

1. Key Rotation Script

A new script at scripts/rotate-encryption-key.ts automates the full rotation process:

  • Reads all database records that contain encrypted fields.
  • Decrypts each value using the previous key (read from ENCRYPTION_SECRET_PREVIOUS).
  • Re-encrypts each value using the new key (read from ENCRYPTION_SECRET).
  • Persists updates back to the database in batches, limiting the blast radius of any failure mid-run.

2. Graceful Dual-Key Support

A new environment variable, ENCRYPTION_SECRET_PREVIOUS, enables the application to serve live traffic during a rotation window:

  • All new writes use ENCRYPTION_SECRET.
  • Reads of legacy ciphertext fall back to ENCRYPTION_SECRET_PREVIOUS if decryption with the current key fails.
  • Once the migration script has completed and all records are re-encrypted, ENCRYPTION_SECRET_PREVIOUS can be removed from the environment.

This approach means key rotation no longer requires a maintenance window.

3. Runbook Documentation

The RUNBOOK.md file now contains a dedicated Encryption Key Rotation section covering the end-to-end procedure.

How to Rotate the Encryption Key

Follow these steps in order. Do not skip steps.

Step 1 — Generate a new key

Generate a cryptographically secure random key. The key must meet the same length/entropy requirements as the current ENCRYPTION_SECRET.

openssl rand -base64 32

Step 2 — Deploy with both keys set

Update your environment / secrets manager so that both variables are present simultaneously:

ENCRYPTION_SECRET=<new-key>
ENCRYPTION_SECRET_PREVIOUS=<old-key>

Deploy this configuration. The application will now accept live traffic while being capable of decrypting data encrypted under the old key.

Step 3 — Run the migration script

npx ts-node scripts/rotate-encryption-key.ts

The script will log progress per batch. Wait for it to complete successfully before proceeding.

Step 4 — Validate

Spot-check a sample of records to confirm they decrypt correctly under ENCRYPTION_SECRET alone. Review application logs for any decryption errors.

Step 5 — Remove the previous key

Once validation passes, remove ENCRYPTION_SECRET_PREVIOUS from your environment and redeploy.

ENCRYPTION_SECRET=<new-key>
# ENCRYPTION_SECRET_PREVIOUS removed

Environment Variables Reference

VariableRequiredPurpose
ENCRYPTION_SECRETAlwaysThe active encryption key used for all new writes and reads.
ENCRYPTION_SECRET_PREVIOUSDuring rotation onlyThe key used to decrypt records encrypted before the rotation. Remove after migration completes.

Security Notes

  • Do not set ENCRYPTION_SECRET_PREVIOUS permanently. It should only be present during the active rotation window.
  • The migration script should be run in a controlled environment with appropriate database access controls in place.
  • Treat both the old and new key values with the same level of secrecy as production credentials — rotate via your secrets manager, not environment files committed to source control.
  • Refer to RUNBOOK.md for the full operational procedure including rollback guidance.

Compliance Reference

This change remediates HIPAA-06 under the HIPAA compliance framework. The control requires that encryption mechanisms include a documented and executable key rotation procedure. The combination of the migration script, dual-key support, and runbook documentation satisfies this requirement.