feat: PR-6 - Key rotation and maintenance commands + DEK-based encryption (Issue #50)

[kevalyq]

Summary

Implements PR-6 from Issue #50: Key rotation and maintenance commands with major architectural improvement - migrates from Laravel's APP_KEY encryption to proper tenant DEK-based envelope encryption.

Key Management Commands

✨ New Artisan Commands

1. keys:generate-tenant - Generate new tenant with envelope keys
2. keys:rotate-kek - Rotate KEK and re-wrap all tenant keys with automatic backup
3. keys:rotate-dek - Rotate DEK for specific tenant and re-encrypt all data
4. idx:rebuild - Rebuild blind indexes for specific tenant

🔐 Major Architectural Change

Before: Person model used Laravel's 'encrypted' cast → encrypted with APP_KEY
After: Person model uses new EncryptedWithDek cast → encrypted with tenant-specific DEK

This enables:

• ✅ True envelope encryption per tenant
• ✅ DEK rotation without KEK compromise
• ✅ Tenant isolation at the encryption layer
• ✅ Proper key lifecycle management

Implementation Details

New Files

• app/Casts/EncryptedWithDek.php - Custom cast for DEK-based field encryption
• app/Console/Commands/GenerateTenantCommand.php - Tenant key generation
• app/Console/Commands/RotateKekCommand.php - KEK rotation with re-wrap
• app/Console/Commands/RotateDekCommand.php - DEK rotation with re-encryption
• app/Console/Commands/RebuildIndexCommand.php - Blind index rebuild
• tests/Feature/KeyRotationTest.php - Comprehensive test suite (12 tests)

Modified Files

• app/Models/Person.php - Changed casts from 'encrypted' to EncryptedWithDek::class
• app/Models/TenantKey.php - Made loadKek() and getKekPath() public for Command access
• phpstan.neon - Excluded tests/ (Pest dynamic properties), added treatPhpDocTypesAsCertain: false

Command Features

• Progress bars for long-running operations
• KEK backup with timestamp (.bak file) on rotation
• Key version tracking (increments on DEK rotation)
• Direct DB updates during re-encryption to bypass casts
• Graceful error handling with proper exit codes
• Security: sodium_memzero() cleans up key material after use

Storage Format

Encrypted fields now stored as JSON:

{
  "ciphertext": "base64_encoded_ciphertext",
  "nonce": "base64_encoded_nonce"
}

This allows:

• Proper nonce storage per field
• Clean separation of concerns
• Easy key rotation detection

Testing

Test Coverage

• ✅ 12 new tests covering all 4 commands (100% coverage)
• ✅ 107 total tests passing (95 existing + 12 new)
• ✅ Test categories:
  • Key generation correctness
  • Rotation correctness (KEK and DEK)
  • Data integrity after rotation
  • Search functionality preservation
  • Graceful failure handling

Quality Metrics

• ✅ TDD approach - Tests written first, then implementation
• ✅ DRY principles - Consistent command structure, centralized test helpers
• ✅ PHPStan Level 9 - Clean (production code)
• ✅ Pint PSR-12 - Compliant
• ✅ REUSE compliant - All files properly licensed
• ✅ LOC: ~822 new (includes necessary EncryptedWithDek cast)

Security Improvements

Before (Insecure)

• All tenants' data encrypted with single APP_KEY
• No per-tenant key isolation
• DEK rotation impossible
• KEK compromise = all data compromised

After (Secure)

• Each tenant has unique DEK
• True envelope encryption (KEK → DEK → data)
• DEK rotation without KEK exposure
• Tenant data isolation at encryption layer
• KEK rotation with automatic re-wrap
• All keys properly zeroed from memory

Migration Impact

⚠️ BREAKING CHANGE: Existing encrypted data uses APP_KEY format and must be migrated to new DEK format.

Migration path:

1. Deploy this PR
2. Run migration script (to be provided in PR-7)
3. Old APP_KEY encrypted data converted to DEK format
4. Blind indexes remain compatible

Commands Usage

# Generate new tenant with envelope keys
php artisan keys:generate-tenant

# Rotate KEK (re-wraps all tenant DEKs)
php artisan keys:rotate-kek

# Rotate DEK for specific tenant (re-encrypts all data)
php artisan keys:rotate-dek {tenant_id}

# Rebuild blind indexes for specific tenant
php artisan idx:rebuild {tenant_id}

Related

• Issue: SecPal API: Multi-tenant security, field encryption & blind indexes, Sanctum & Spatie Teams — TDD/PEST, DRY, best practices #50 PR-6 checklist
• Depends on: PR-0 through PR-5 (merged)
• Next: PR-7 - Hardening & Cleanups

Checklist

• TDD approach followed
• All tests passing (107/107)
• PHPStan Level 9 clean
• Pint PSR-12 compliant
• REUSE compliant
• DRY principles applied
• Security: sodium_memzero() used
• Documentation in command help text
• Progress bars for UX
• Graceful error handling

[Copilot]

Pull Request Overview

This PR implements key rotation functionality for the encryption system, introducing commands to rotate encryption keys at different levels (KEK, DEK) and rebuild blind indexes. The changes include:

• New console commands for key rotation: keys:generate-tenant, keys:rotate-kek, keys:rotate-dek, and idx:rebuild
• A new custom cast EncryptedWithDek to handle DEK-based encryption/decryption
• Updated Person model to use the new custom cast
• Changed visibility of TenantKey::getKekPath() and TenantKey::loadKek() from protected to public
• Updated PHPStan configuration to exclude tests directory to avoid false positives with Pest's dynamic properties
• Comprehensive test coverage for all key rotation scenarios

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/Feature/KeyRotationTest.php	Comprehensive test suite covering all key rotation commands and scenarios
phpstan.neon	Updated to exclude tests directory and simplified configuration by removing Pest-specific ignores
app/Models/TenantKey.php	Changed visibility of getKekPath() and loadKek() methods to public for command access
app/Models/Person.php	Migrated from Laravel's built-in 'encrypted' cast to custom EncryptedWithDek cast
app/Console/Commands/RotateKekCommand.php	New command to rotate KEK and re-wrap all tenant keys
app/Console/Commands/RotateDekCommand.php	New command to rotate DEK for a specific tenant and re-encrypt data
app/Console/Commands/RebuildIndexCommand.php	New command to rebuild blind indexes for a specific tenant
app/Console/Commands/GenerateTenantCommand.php	New command to generate a new tenant with envelope keys
app/Casts/EncryptedWithDek.php	Custom cast for DEK-based encryption supporting key rotation