Lumos Laravel Package

Technical Evaluation

• Architecture fit: esplora/lumos is a Laravel package that likely wraps GPG encryption/decryption. The new symmetric decryption support (passphrase-based) complements existing asymmetric (key-based) workflows, making it suitable for Laravel applications that need to process encrypted payloads from third parties (e.g., bank files, partner integrations) or protect sensitive data at rest. The package should follow standard Laravel conventions (service provider, facade, config publishing), but this must be verified.
• Integration feasibility: Composer-based installation is straightforward. However, GPG decryption requires either the PHP gnupg extension or a system GPG binary. This introduces a dependency outside pure PHP, which may conflict with hardened or minimal container environments. Laravel version compatibility (e.g., Laravel 9/10/11) and PHP version constraints must be checked before adoption.
• Technical risk: The version jump from 0.2.0 to 1.1.0 implies a 1.0.0 release not shown in the notes; breaking changes may exist between 0.2.0 and 1.0.0. Symmetric decryption introduces passphrase management risk: how are passphrases stored? Are they read from env/config, or passed at runtime? If the package logs or exposes passphrases, that is a serious security concern. GPG binary/extension availability and version mismatches can cause runtime failures.
• Key questions:
  • Which Laravel and PHP versions are supported?
  • Does it require the gnupg PHP extension or shell out to gpg?
  • How are symmetric passphrases supplied and protected?
  • What is the public API for decryption (facade, service, or helper)?
  • Are there breaking changes between 0.2.0 and 1.0.0?
  • Is the package actively maintained and documented?

Integration Approach

• Stack fit: Fits Laravel/PHP stacks that already use GPG for file or message encryption. It is less suitable for teams without GPG operational experience or for serverless environments where installing system binaries is difficult.
• Migration path: Start by reviewing the full changelog from 0.2.0 to 1.1.0. Install in a development branch via Composer, publish any config, and add required environment variables for key/passphrase storage. Write integration tests covering both asymmetric and symmetric decryption paths before touching production.
• Compatibility: Confirm compatibility with the team’s Laravel and PHP versions, and with the GPG version available in CI and production images. Ensure the GPG extension or binary is present in all environments, including local, CI, staging, and production.
• Sequencing:
  1. Spike in a sandbox to validate decryption with sample payloads.
  2. Add dependency and configuration in development.
  3. Implement feature-flagged decryption paths.
  4. Roll out to staging with production-like GPG keys/passphrases.
  5. Enable in production gradually, monitoring for decryption failures.
  6. Document runbooks for key rotation and passphrase updates.

Operational Impact

• Maintenance: Adds a third-party dependency that wraps an external binary/extension. Regular updates may be needed for GPG security patches. The package’s release cadence and maintainer responsiveness should be monitored.
• Support: Community-supported package; no commercial SLA. Internal documentation and runbooks are essential. Teams must own GPG key and passphrase lifecycle management.
• Scaling: GPG decryption is CPU-bound and synchronous. High-volume decryption may require queue workers or horizontal scaling. Memory usage depends on payload size; streaming large files may not be supported.
• Failure modes: Missing gnupg extension, incorrect GPG binary path, invalid or rotated passphrase, corrupted ciphertext, unsupported GPG algorithm, and permission issues on keyrings. These should surface as clear exceptions; otherwise, debugging is difficult. A fallback or dead-letter queue is recommended for batch decryption jobs.
• Ramp-up: Developers need basic GPG literacy (symmetric vs asymmetric, keyrings, passphrases). Security and operations teams must agree on secret storage (e.g., Laravel encrypted env, Vault, AWS Secrets Manager). Expect a short learning curve but non-trivial operational setup.