Encryption key rotation with XChaCha20-Poly1305

[TomK]

encrypter is a single-key illuminate/encryption instance, so rotating [security] encryption_key (e.g. after a leak) makes every existing encrypted cookie undecryptable at once. Its AES-CBC + HMAC JSON payload is also large, and it unserializes decrypted data without restriction.

Adds Cubex\Encryption:

• Encrypter implements EncrypterInterface (string in, string out) with XChaCha20-Poly1305. A payload is base64url of a version byte, a random 24-byte nonce and the ciphertext with its tag. The version byte is bound as additional data. The cipher key is derived with HKDF-SHA256 from each configured key, which must be at least 16 bytes.
• Key list: encryption_key can now be a list. The first key encrypts; later keys only decrypt. An empty first entry throws, so an unset env var can't promote an old key. A missing item or [] keeps the existing default key.
• Old cookies: Legacy\IlluminateFallbackEncrypter decrypts payloads written by Cubex 2.6, using AES-128/256-CBC chosen by key length. It never writes that format and can be deleted once old cookies have expired.
• encrypter binding: now an IlluminateEncrypterAdapter implementing Illuminate's contract, so EncryptCookies keeps working. It unserializes with allowed_classes => false. EncrypterInterface is bound too.
• Dependencies: illuminate/encryption moves to require-dev (compatibility tests only), and illuminate/contracts is required directly. Sodium is optional: ext-sodium or paragonie/sodium_compat is listed under suggest and checked only when an encrypter is constructed. There is no fallback algorithm.

Previous keys are normally compromised, so payloads they decrypt may be forged. Keep the window short, and consumers can re-issue cookies onto the new key. Payloads are roughly half the size: 45 bytes of plaintext becomes 115 characters instead of 244.

Test plan

New tests for Encrypter, the legacy fallback, the adapter and the service cover:

• round trip, rotation, and wrong key
• tampering with the version, nonce, ciphertext or tag
• malformed payloads, and empty or short keys
• missing sodium, simulated with a test subclass
• real illuminate/encryption 5.5.44 AES-128 and AES-256 payloads (including serialized cookies) decrypting, and never being produced
• tampered legacy payloads, and objects coming back as __PHP_Incomplete_Class without __wakeup

Ran vendor/bin/phpunit --coverage-text on PHP 7.4.33 with PHPUnit 9.6: 338 tests passed with 99.26% line coverage (threshold 98). The new classes have 100% coverage. The 9 createPartialMock warnings in CubexKernelTest also appear on 2.0 without this change.

Rollout

1. Release 2.7.0 from 2.0 with gh release create.
2. megameld bumps cubex/framework in every app that shares the cookie key, then sets encryption_key[] = {{ENV:COOKIE_ENCRYPTION_KEY}} followed by encryption_key[] = <old key>.
3. Remove the old key after a short window.

🤖 Generated with Claude Code