Skip to content

feat: KMS column-encryption rotation drill with resumable state and audit - #811

Open
Fash004 wants to merge 21 commits into
RevoraOrg:masterfrom
Fash004:feat/kms-column-rotation
Open

feat: KMS column-encryption rotation drill with resumable state and audit#811
Fash004 wants to merge 21 commits into
RevoraOrg:masterfrom
Fash004:feat/kms-column-rotation

Conversation

@Fash004

@Fash004 Fash004 commented Aug 3, 2026

Copy link
Copy Markdown

Closes:#557

Summary

Implements background column-level re-encryption (ColumnEncryptionRotator) for at-rest encrypted data when KMS keys are rotated. Tracks per-row key generation, maintains persisted resumable state across restarts, emits rotation.rows_reencrypted metric counter, and logs security audit events.


Requirements & Context

  • Secure, tested, and documented: AES-256-GCM column encryption with versioned KMS key generations.
  • Resumable Batch State: Persisted rotation state table (kms_rotation_state) tracks batch cursor and status across service restarts.
  • Crash Mid-Batch Safety: Re-encryption queries filter rows where key_generation < target_key_generation, preventing double re-encryption if process crashes mid-batch.
  • Metrics: Emits rotation.rows_reencrypted counter metric via MetricsCollector.
  • Audit Log: Emits security audit events for job start, batch progress, completion, and failures.

Detailed Changes

Security & Rotator Service

  • src/security/kmsKeyProvider.ts: KMSKeyProvider interface and LocalKMSKeyProvider implementing AES-256-GCM column encryption tagged with key generation IDs (keyGeneration) and key rotation support (rotateKey()).
  • src/security/columnEncryptionRotator.ts: ColumnEncryptionRotator service managing background column re-encryption jobs:
    • startRotation(targetTable, targetColumn, options)
    • processBatch(jobId, batchSize)
    • resumePendingRotations(batchSize)
    • Emits rotation.rows_reencrypted metric counter.
    • Logs KEY_ROTATION audit events.
  • src/security/types.ts: Added KMSRotationJobState, KMSRotationOptions interfaces and added 'KEY_ROTATION' event type to AuditEvent.
  • src/security/index.ts: Re-exported KMS encryption primitives and rotator service.

Database Migration

  • src/db/migrations/020_create_kms_rotation_state.sql: Added database migration for kms_rotation_state persistence table and kms_sample_records demonstration table.

Unit & Integration Tests

  • src/security/columnEncryptionRotator.test.ts: Comprehensive test suite testing KMS key rotation, batch re-encryption, crash mid-batch resumption without double re-encryption, metric counter emission, and audit log generation.
  • package.json: Added test:kms-rotation test script.

Revora Dev and others added 21 commits July 28, 2026 15:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant