Thanks to visit codestin.com
Credit goes to github.com

Skip to content

feat: Add LOCKBOX_MASTER_KEY rotation script with interactive key input #14662

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
gsmithun4 merged 13 commits into from
Dec 23, 2025
Merged

feat: Add LOCKBOX_MASTER_KEY rotation script with interactive key input #14662

gsmithun4 merged 13 commits into from
Dec 23, 2025
+781 −3

Conversation

@adishM98
Copy link
Collaborator

@adishM98 adishM98 commented Nov 27, 2025 •
edited by vamshik0
Loading

Summary

Adds a key rotation script to securely rotate the LOCKBOX_MASTER_KEY used for encrypting sensitive data in the database. The script uses an interactive prompt for the old key, ensuring a clean and secure
workflow without storing multiple keys in environment variables.

Changes

New Files

  • server/scripts/services/rotation.service.ts - DualKeyEncryptionService for handling two encryption keys simultaneously during rotation
  • server/scripts/rotate-lockbox-key.ts - Main rotation script with transaction safety, dry-run mode, and verification

Modified Files

  • server/package.json - Added rotate:keys and rotate:keys:prod npm scripts
  • package.json - Added root-level wrapper scripts for key rotation

Features

🔐 Secure Rotation Process

Rotates encryption keys for all 5 encrypted tables:

  • credentials (value_ciphertext)
  • org_environment_constant_values (value)
  • sso_configs (configs with secret fields)
  • organization_tjdb_configurations (pg_password)
  • user_details (user_metadata)

✅ Safety Features

  • Transaction-based: All changes committed atomically using dbTransactionWrap or rolled back on failure
  • Dry-run mode: Test rotation without making changes (--dry-run flag)
  • Pre-flight validation: Validates key format and tests encryption/decryption before starting
  • Post-rotation verification: Confirms all data can be decrypted with new key
  • Backup confirmation: Prompts for database backup confirmation before production rotation
  • Progress tracking: Real-time progress indicators for all 5 tables

Usage

1. Update Environment Variable

# Set LOCKBOX_MASTER_KEY to your NEW key in .env
LOCKBOX_MASTER_KEY=<new-key-64-hex-chars>

2. Test with Dry Run

npm run rotate:keys -- --dry-run

# When prompted, enter your current/old key:
# Please enter the old key: <old-key-64-hex-chars>

3. Perform Actual Rotation

npm run rotate:keys

# Enter old key when prompted
# Confirm database backup
# Wait for rotation to complete

4. Restart Application

# No .env changes needed - LOCKBOX_MASTER_KEY is already correct!
npm run start:prod

Docker/Kubernetes Deployments

# Update LOCKBOX_MASTER_KEY in docker-compose.yml or k8s secrets
# Run rotation in one-off container
docker-compose run --rm server npm run rotate:keys:prod

# Enter old key when prompted
# Restart services after completion
docker-compose restart server

Workflow

Step 1: Validating new master key...
Step 2: Enter old master key... (interactive prompt)
Step 3: Testing encryption keys...
Step 4: Backup confirmation...
Step 5: Connecting to database...
        (processes all 5 tables in single transaction)
Step 6: Verifying rotation...
Step 7: Committing changes...

Security Considerations

Before Rotation

1. Stop the application - Prevent writes during rotation
2. Backup database - Take full database backup (script prompts for confirmation)
3. Test in staging - Always test with --dry-run first
4. Update .env - Set LOCKBOX_MASTER_KEY to new key value

After Rotation

1. Restart application - No .env changes needed
2. Verify application starts - Ensure no decryption errors in logs
3. Test critical flows - Verify credentials, SSO configs, etc. work correctly
4. Monitor logs - Check for any encryption/decryption errors
5. Secure old key - Store old key securely for emergency rollback (24-48 hour window recommended)

Rollback Plan

If issues occur after rotation:
1. Stop application
2. Restore database from backup (taken before rotation)
3. Revert LOCKBOX_MASTER_KEY in .env to old key value
4. Restart application

Testing

Tested in development environment:
- ✅ Dry-run mode completes successfully
- ✅ All 5 tables rotated successfully
- ✅ Verification passes
- ✅ Application starts and functions after rotation
- ✅ Transaction rollback works on errors
- ✅ Interactive prompt works cleanly

⚠️ Important: This is a sensitive operation affecting encrypted data. Always test thoroughly in staging with --dry-run before production use.

QA Checklist

  • Integration Testing.
  • Smoke Testing.
  • Bug Fixes Verification.
  • Cross browser UI check. (Firefox, safari,chrome)
  • Verify features on Dark and Light mode.
  • Automation Testing.
  • Test System Upgrade/Staging Instance(for cloud) (Sanity + Test System Specific. Cases)
  • Performance Benchmark

@adishM98
update lockbox key rotation script to correct environment variable usage
b3c5280
@adishM98
Merge branch 'lts-3.16' into feat/rotate-key
ab590c5
@adishM98
implement dual key encryption service for lockbox key rotation
45c2e6e 
- Refactor lockbox key rotation script to use a new DualKeyEncryptionService.
- Remove dependency on old environment variable for old master key.
- Add prompts for user input to enhance usability during key rotation.
- Implement automatic transaction management using dbTransactionWrap.
- Improve validation and error handling for key formats.
- Update documentation within the script for clarity on usage and steps.
@adishM98 adishM98 changed the title feat: add key rotation scripts and dual key encryption service feat: Add LOCKBOX_MASTER_KEY rotation script with interactive key input Dec 10, 2025
@adishM98 adishM98 added testing and removed testing labels Dec 10, 2025
@gsmithun4 gsmithun4 merged commit 6a34c81 into lts-3.16 Dec 23, 2025
13 checks passed
@gsmithun4 gsmithun4 deleted the feat/rotate-key branch December 23, 2025 16:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@gsmithun4 gsmithun4 Awaiting requested review from gsmithun4 gsmithun4 is a code owner

@shah21 shah21 Awaiting requested review from shah21 shah21 is a code owner

@akshaysasidrn akshaysasidrn Awaiting requested review from akshaysasidrn akshaysasidrn is a code owner

@johnsoncherian johnsoncherian Awaiting requested review from johnsoncherian johnsoncherian is a code owner

@kavinvenkatachalam kavinvenkatachalam Awaiting requested review from kavinvenkatachalam kavinvenkatachalam is a code owner

Assignees

No one assigned

Labels

run-cypress-platform-ee

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@adishM98 @gsmithun4 @vamshik0