Decompresso Laravel Package

Getting Started

Lumos is Esplora's Laravel wrapper around GPG/PGP encryption, aimed at projects that need to encrypt or decrypt payloads and files without shelling out to gpg by hand.

Start with:

1. composer require esplora/lumos — note that the package jumped from 0.2.0 straight to 1.1.0, so treat the install as a potential breaking upgrade if you were on the pre-1.0 line. Pin the constraint (^1.1) before touching an existing project.
2. Publish the config (php artisan vendor:publish --tag=lumos-config or the equivalent tag documented in the README) and read the config file first — key paths, passphrase handling, and default cipher/digest settings are the things you will actually change day-to-day.
3. Put your key material somewhere outside public/ (typically storage/app/keys or an env-driven path) and confirm the process user can read the private key.
4. Verify your environment has a working GPG backend — either the PHP gnupg extension or a gpg binary on PATH, depending on which driver the package uses.

The first real use case is inbound decryption: a partner or internal service sends you an armored PGP message, and you decrypt it in a controller or job rather than in a one-off script. As of 1.1.0 you also have symmetric decryption, which is the faster path when both sides share a passphrase rather than a keypair — useful for internal service-to-service payloads and for decrypting files produced by gpg --symmetric.

Implementation Patterns

Wrap it in a service, not a controller. Resolve Lumos once in a small PayloadDecryptor / FileEncryptor class and inject that. You want a single place to swap key paths per environment and a single place to add logging when decryption fails.

Environment-specific keys. Keep public keys for outbound encryption and private keys for inbound decryption in separate config values, and point them at different files per environment (staging key vs production key). Loading a private key you don't need is a needless blast-radius increase.

Asymmetric for external, symmetric for internal. The 1.1.0 symmetric support is a good fit for:

• Webhook payloads where you and the sender agreed on a shared secret.
• Re-encrypting already-trusted data at rest where the overhead of a keypair is unjustified.
• Test fixtures — a fixed passphrase is far easier to seed in CI than a full keyring.

Keep asymmetric (public-key) flows for anything crossing a trust boundary with a third party.

Decrypt at the edge of your application. Do it in middleware, a form request, or the first line of a job handler, then pass plaintext around internally. Don't scatter decrypt calls through your domain layer.

Queue long-running crypto. Decrypting large files is CPU-bound; push it to a job rather than blocking a request. Pair this with the package's exception types so a bad passphrase retries or fails cleanly rather than throwing an opaque error into the queue log.

Log the envelope, never the contents. Record which key ID / which passphrase identifier was used and the outcome; never log ciphertext-adjacent plaintext or the passphrase itself.

Gotchas and Tips

• The 0.2.0 → 1.1.0 jump is the headline risk. Semver says a major bump means breaking changes, and there is no 1.0.0 in the compare range shown, so the maintainers appear to have collapsed pre-1.0 work into 1.1.0. Before upgrading an existing install, diff the public API (facade methods, config keys, exception classes) rather than assuming the only change is the new symmetric feature.
• Symmetric decryption is not a drop-in for the asymmetric path. It needs a passphrase, not a private key, and it will fail loudly if the cipher/digest used to encrypt doesn't match what the package expects. Test against a ciphertext produced by the exact gpg invocation your counterparty uses — gpg --symmetric defaults have shifted across GPG versions.
• Key format mismatches are the most common failure. Armored (.asc) vs binary (.gpg/.kbx) keys are not interchangeable, and an armored key pasted into an env var will lose its newlines. Prefer file paths over inline env strings for keys.
• Passphrase handling. Read passphrases from your secrets store, not from config/*.php committed to git. If the package supports a passphrase callback, use it so the secret isn't held in memory longer than needed.
• Extension vs binary driver. If you're on the PHP gnupg extension, confirm it's installed in every environment including CI and your queue workers — a missing extension often surfaces as a confusing "no encryption backend" error rather than an install error.
• Error handling is where the package's value lies. Catch the package's own decryption exceptions and translate them into domain outcomes (InvalidSignature, DecryptionFailed) so callers don't have to string-match GPG stderr output.
• Test with real ciphertext, faked at the boundary. Generate a handful of known-good encrypted fixtures once and check them in; assert on your service's behaviour and stub the package for everything else. Generating fresh GPG output per test run is slow and flaky.
• Verify before you trust. For asymmetric flows, confirm the package exposes signature verification and use it — decryption alone tells you the message was readable, not who sent it. Symmetric decryption gives you no sender authentication at all, so pair it with an HMAC or a signed header if origin matters.