Repository navigation
feat(server): rotate ENCRYPTION_KEY without losing unexpired secrets - #170
Merged
Merged
Conversation
Hold a keyring (primary ENCRYPTION_KEY plus read-only ENCRYPTION_PREVIOUS_KEYS) and tag every ciphertext and digest at rest with the id of the key that wrote it. Add a rotate-keys command that re-encrypts vault metadata with the primary key and reports when previous keys can be removed. Reads of entries whose key is not loaded now fail without consuming a failed attempt.
- Catch decrypt failures in the webhook 'failed' listener so a removed key can't cause an unhandled rejection. - Skip the per-key PBKDF2 legacy fallback for values that can't be base64 ciphertext (plaintext IP restrictions). - Stop logging and printing key ids, which act as an offline verifier for weak keys; report counts instead. - Don't count hm1/m1 values on the primary key as depending on previous keys. - Dedupe SCAN results and page through queued webhook jobs. - Cache per-key HMAC keys in the keyring; share format prefix constants; simplify field accessors and drop a leftover alias.
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Today, changing
ENCRYPTION_KEYmakes every unexpired secret unreadable. This adds a keyring so the key can be rotated without losing data, following the keyset pattern used by Google Tink and Rails Active Record Encryption: one primary key for writes, previous keys for reads only, and a key id stored with each value.machine):createKeyring,encryptWithKeyring,decryptWithKeyring,digestWithKeyringanddigestCandidates. New formats arem2:<kid>:(AES-256-GCM, with the header bound as associated data so a relabelled key id fails) andhm2:<kid>:(HMAC-SHA-256). The key id is derived from the key, so operators never manage ids. Existingm1/hm1/legacy PBKDF2 values still read under any key in the ring.ENCRYPTION_PREVIOUS_KEYS(comma-separated, read-only). The vault and the BullMQ webhook queue use the keyring. On startup the server logs how many previous keys it loaded. Key ids are never logged or printed, because they are derived from the keys and would let anyone reading the output check guesses of a weak key offline.rotate-keyscommand (pnpm --filter @crypt.fyi/server keys:rotate, ornode packages/server/dist/rotate-keys.jsin Docker, with optional--dry-run): re-encrypts IP restrictions, webhook URLs and delete tokens with the primary key. Each write is a compare-and-set that keeps the entry's TTL, so it never overwrites a concurrent read, decrement or burn. It then reports when previous keys can be removed (previousKeysNeededUntil,safeToRemovePreviousKeys). Only counts are printed.Verification-hash digests are one-way HMACs (required by SPECIFICATION §6.2), so they can't be re-keyed without the original hash. Entries created before a rotation keep needing the old key until they expire, at most the max TTL. The runbook and the command's report cover this.
Docs: README "Rotating
ENCRYPTION_KEY" runbook, SPECIFICATION §6.2 and §7.2.1,docker-compose.yaml,.env-example, and a changeset.Changeset
This is a
minorbump. Because the packages are versioned together, everything moves to 0.2.0.Testing
h).fc, dry run, unreadable entries, no burn when a key is missing).pnpm lint,pnpm typecheckandpnpm format:checkpass for the touched packages. Ran the CLI by hand with--dry-run.pnpm test:e2ewas not run locally.