Decompresso Laravel Package

Technical Evaluation

What changed in 1.1.0. The only documented change is symmetric GPG decryption support (PR #7). This extends the package from asymmetric (keypair-based) decryption to passphrase-based symmetric decryption — i.e., a shared-secret unlock path alongside the existing private-key path. No deprecations or breaking changes are stated.

Version-signal risk (most important finding). The compare link jumps 0.2.0 → 1.1.0, yet "What's Changed" lists a single PR. That means the 1.0.0 and 1.0.x release notes were not aggregated into this one. Two things follow: (a) the project has crossed the 1.0 line and is now asserting semver API stability, and (b) we cannot see from this note alone what landed in 1.0.0 — the very release most likely to contain breaking changes. Treat the "no breaking changes" implication as unverified until the 1.0.0 release page and CHANGELOG.md are read directly.

Architecture fit. The package is a Laravel-style secret-handling add-on (service provider + config + artisan surface) that shells out to or wraps GPG for encrypt/decrypt. That fits naturally where we already need encrypted-at-rest secrets in .env files, deployed artifacts, or CI variables, and where we want decryption to happen inside the framework rather than in bespoke shell scripts. It fits poorly if our target is a managed secrets service (Vault, AWS Secrets Manager, SOPS+age) — this is a file-and-key-centric model, and adopting it now creates a migration to unwind later.

Technical risk.

• Passphrase custody. Symmetric mode collapses key management into "one passphrase everywhere." It must reach the runtime or CI without landing in the repo, the image layer, or build logs. This is a process and secrets-distribution risk more than a code risk.
• External binary dependency. GPG is a host dependency, not a Composer one. Container base image, CI runner image, and developer laptops must all carry a compatible gpg version, or decryption fails in ways that surface only at boot.
• Failure-mode opacity. The key question is whether a wrong/missing passphrase throws a loud exception or yields an empty/partial decrypted value. Silent-empty on a secret decrypt is the dangerous case — it turns a config error into an auth failure three layers away.
• Contributor concentration. The visible change is authored by a single maintainer under a small org. Bus factor and security-review depth are the dominant long-term risks for a package that holds decryption keys.
• Pre-1.0 → 1.x without a readable changelog means we are being asked to trust a stability promise we cannot yet audit.

Key questions for the maintainers / spike.

1. What shipped in 1.0.0, and were there breaking changes from 0.2.0?
2. Does the symmetric path use a passphrase from env/config/file, and is there a documented rotation procedure?
3. Is decryption performed via the gnupg PHP extension or by invoking the CLI? (Affects container hardening and proc_open/exec policy.)
4. What is the failure contract on bad passphrase, missing key, or missing binary — exception, log, or empty string?
5. Minimum PHP/Laravel versions and the CI matrix we'd be inheriting.
6. Does it cache decrypted values, or decrypt on every access?
7. Any security policy / disclosure process for a crypto-adjacent package?

Integration Approach

Stack fit. Standard Laravel integration: Composer install, publish config, add the service provider (or rely on package discovery), set the relevant env vars. The gating item is not PHP — it is provisioning gpg into every runtime image and confirming the version pin matches what the package expects. Add that to the base image before any application work begins.

Migration path (from 0.2.0, if already in use anywhere) and from ad-hoc scripts.

1. Freeze on the current constraint; do not float to ^1.0 until 1.0.0's changes are read.
2. Read CHANGELOG.md and the 1.0.0 release page; diff the public API surface we actually call (facade, config keys, artisan commands).
3. Pin to an exact version (1.1.0) in composer.json and lock it.
4. Prove in a throwaway branch: encrypt a known value, decrypt with both keypair and passphrase, assert byte-identical round-trip.
5. Stage against a non-production environment with real GPG installed, then promote.

If we are not yet a consumer, the migration path is simply "adopt at 1.1.0 pinned," and the 1.0.0 ambiguity costs us nothing but diligence.

Compatibility work to schedule.

• PHP and Laravel version floors vs. our oldest supported app.
• gpg version parity across local / CI / container / prod. Drift here is the single most likely source of "works on my machine."
• Coexistence with any existing APP_KEY-based encrypt()/decrypt() usage — the two schemes should not be mixed on the same values.
• Whether symmetric mode can be adopted incrementally (one secret at a time) or requires a flag-day config switch.

Sequencing.

1. Spike (read-only, ~1–2 days): answer the key questions above; confirm failure contract empirically.
2. CI-first pilot: use symmetric decryption only for CI/deploy-time secret material. Low blast radius, no production runtime exposure, immediate value.
3. Container baseline: add gpg to base images; document version; add a smoke test asserting the binary exists and can decrypt a fixture.
4. Application runtime: adopt for config secrets behind a feature flag, with a rollback that reverts to the previous env-injection mechanism.
5. Decommission the hand-rolled decryption scripts, one secret domain at a time.

Do not skip step 3 — the pilot in step 2 will pass on a developer laptop and fail in a distroless or Alpine container otherwise.

Operational Impact

Maintenance. Modest but non-zero: a Composer dependency plus an OS package plus a passphrase. Budget for a quarterly review of the pin and a re-read of release notes, since the project's release hygiene (single aggregated note for a 0.2.0→1.1.0 jump) suggests changelogs will not be self-explanatory. Small-team project — plan on us being the de facto QA for our own upgrade path rather than relying on an LTS promise.

Support. Community GitHub issues, no vendor SLA. Acceptable for internal tooling behind a CI gate; questionable for anything on the critical boot path of a customer-facing service. If it lands there, we need at least one engineer who can read the source and one documented fallback procedure.

Scaling. Decryption is CPU-bound and, if it shells out, process-spawning — roughly milliseconds per invocation but with a fork/exec cost that is not free at high request rates or in a high-fan-out queue worker fleet. Two mitigations to insist on: (a) decrypt once at boot / build time and cache the plaintext for the process lifetime, and (b) never decrypt inside a hot request path or per-job loop. If the package decrypts per-access with no cache, that is a design constraint we must wrap ourselves. Horizontal scaling is otherwise unaffected — no shared state or network dependency, which is a genuine advantage over a secrets-service call in the boot path.

Failure modes to instrument and alert on.

• gpg binary absent or version-mismatched in a new image → boot failure or, worse, empty secrets. Alert on process-start failure and on unexpected empty config values.
• Passphrase missing/typo'd at deploy time → auth failures downstream. Fail fast and loudly at boot; add a startup assertion that a known ciphertext decrypts to a known plaintext.
• Passphrase rotation without re-encrypting stored ciphertexts → partial outage. Rotation must be a documented, rehearsed runbook with a dual-read window.
• Log/exception leakage of decrypted plaintext — verify error paths do not dump secrets; add a log-scrubbing test.
• Keyring/permission drift inside containers (running as non-root, $HOME unset) causing gpg to fail opaquely.
• Supply-chain: unpinned transitive Composer dependencies in a package holding decryption material — use composer.lock and a dependency audit in CI.

Ramp-up. Low for the Laravel mechanics (config publish, env vars, artisan commands) — a mid-level Laravel developer is productive in under a day. The real ramp is GPG literacy: keypairs vs. symmetric passphrases, what "trust" means for a key, and why a passphrase in a CI variable is a different control than a private key in a vault. Budget a short internal write-up and a runbook before the production rollout, not after. Expect roughly one engineer-week end-to-end for the first domain, and materially less for each subsequent one.

Recommendation. Conditional go. 1.1.0 is a small, additive feature and symmetric GPG support is genuinely useful for CI-time secret handling. But the release note does not let us verify what changed in 1.0.0, and the package sits on a security-sensitive path with a thin maintainer base. Approve the CI-first pilot; gate production runtime adoption on (a) a clean read of the 1.0.0 changelog, (b) a confirmed fail-loud contract on bad passphrase, and (c) gpg baked into the base image with a smoke test.