This lesson's interactive features are locked, please to keep using them

Key Management and Rotation

Encrypted data is only as safe as the key used to encrypt it. But a single unversioned key means replacing it makes every value encrypted with the old key unreadable!

Instead, use a keyring. This isn't as complex as it sounds: start with one key and call it version 1 (v1):

DOCUMENT_ENC_KEY_V1=A927FD...

Then, whenever you encrypt a value, store its key version with the ciphertext:

Ciphertext	Key Version
`0xdeadbeef...`	`v1`
`0xfeedface...`	`v1`
...	...

Rotate Without Losing Data

When you need to rotate your key, add a new one and change the active version:

DOCUMENT_ENC_KEY_V1=A927FD...
DOCUMENT_ENC_KEY_V2=3B1C9A...
DOCUMENT_ENC_ACTIVE_VERSION=v2

Your application should always decrypt with the version recorded on the payload and encrypt with the current active version. That way, old ciphertext remains readable after rotation.

If a key was compromised, rotate it and re-encrypt live data as soon as you can. This limits future exposure, but it can't protect ciphertext an attacker already copied with the old key.

Losing an encryption key can mean permanently losing the data it protects. Treat rotation, backup recovery, access control, and key retirement as one lifecycle.

Assignment

Bearly Secure already routes TOTP secrets through encryptStringWithKeyring and decryptStringWithKeyring in src/storage/keyring.ts, but both are insecure pass-throughs, and the app treats the keyring as optional. Complete the versioned keyring so TOTP secrets are encrypted at rest with the active key.

Add a couple of placeholders to .env.example:

DATA_ENCRYPTION_ACTIVE_VERSION=v1
DATA_ENCRYPTION_KEY_V1=replace_with_64_hex_characters

Add those same variables to your local .env file, replacing DATA_ENCRYPTION_KEY_V1 with an actual random hex key: openssl rand -hex 32.
In src/storage/keyring.ts:
1. Import encrypt and decrypt from ./encryption.ts.
2. Write and export a new encryptWithKeyring(plaintext: Buffer, keyring: Keyring | undefined): VersionedEncryptedPayload function:
  1. Require the configured keyring with the provided requireKeyring helper.
  2. Get (using the .keys.get method) the key for the keyring's .activeVersion. Throw an error if it's missing.
  3. Encrypt the plaintext with that key.
  4. Return the object created with the encrypt function, including a new keyVersion property set to the active version.
3. Write and export a new decryptWithKeyring(payload: VersionedEncryptedPayload, keyring: Keyring | undefined): Buffer function:
  1. Require the configured keyring, then get the key for the payload's .keyVersion, not the active version. Throw an error if it's missing.
  2. Decrypt the payload with that key and return the plaintext.
4. Update encryptStringWithKeyring and decryptStringWithKeyring, to use the provided serializeEncryptedPayload and deserializeEncryptedPayload to convert between a versioned payload object and the string format that should be stored in the database.
In src/dependencies.ts use loadKeyring instead of loadOptionalKeyring so that missing or malformed key configuration prevents startup.
Start the app. The existing startup migration in src/storage/migrations.ts should encrypt any plaintext TOTP secrets already in the database, so seeded users like Wendy can still log in.

Run and submit the CLI tests from the project root.