StorageKeyRotationManager
The storage key rotation state machine (docs/storage-key-rotation.md): STABLE → PREPARING → MIGRATING → RETIRING → STABLE, over a backend that persists the state and records and a keyProvider that holds the key material.
Order, each step committed before the next one starts: allocate the key ID → provider creates the key and it is read back → activate it → re-encryption batches → prove that no record uses the retiring key and commit RETIRING → prove it again → remove the provider key → STABLE. The storage never names a key the provider has not persisted, and a key is never removed before the proof committed. Every step can be interrupted and resumed. Provider keys the storage does not name as retiring (for example one created by an abandoned start) are never removed.
Functions
Advances a rotation by one bounded step and returns the new status: PREPARING finishes the start like rotate; MIGRATING re-encrypts up to maxRecords records and, when none are left, proves that no record uses the retiring key and retires it; RETIRING removes the retiring key from the provider (again) and ends the rotation; STABLE does nothing.
Starts a rotation and returns the new current key ID. In PREPARING it finishes the interrupted start with the key ID already allocated. Throws StorageKeyRotationInProgressException while migrating or retiring; StorageEncryptionException.KeyIdsExhausted if no key ID is left; StorageEncryptionException.KeyUnavailable if the provider cannot create or return the key (the storage then still uses its current key).
The rotation status. Key IDs only.