Laravel Crypto Laravel Package

Technical Evaluation

Architecture fit. laravel-crypto is a drop-in extension of Laravel's Encrypter, wired in through the service container and consumed via Eloquent casts/traits. The v3.0.0-alpha1 headline feature — per-user encryption (PR #41) — shifts the package from "one app-wide key" to "a key per user/tenant," which is a materially different architecture: it introduces a key-derivation and key-lookup layer that the application must own. For multi-tenant SaaS or any product with per-customer data-isolation requirements (health, finance, GDPR-scoped records), this is a genuine differentiator over stock Laravel encryption. For single-tenant internal apps, it is largely unnecessary complexity.

Integration feasibility. Low mechanical effort (Composer require, publish config, swap casts), but the real cost sits in key management, not code. Per-user encryption requires deciding where the per-user key material lives (DB, KMS, derived from a master secret + user salt), how it is rotated, and how it is recovered. That design work is ours, not the package's.

Technical risk. High for this release specifically:

• Alpha, major-version bump. v3.0.0-alpha1 is explicitly pre-stable. The public API, config schema, and on-disk ciphertext format may change before GA. Do not ship to production on an alpha.
• Ciphertext incompatibility. Moving from v2's single-key model to per-user keys almost certainly makes v3 ciphertext unreadable by v2 and vice versa. A migration/re-encryption strategy is mandatory and is not described in the release notes.
• Blast radius of key loss. With per-user keys, losing or corrupting key material means losing that user's data with no app-wide recovery path. This is a new, sharper failure mode than v2.
• Single-maintainer signal. One contributor on the release PR; bus-factor risk on a security-critical dependency.
• Sparse release notes. "Feat/per user encryptio" tells us nothing about upgrade steps, config changes, or deprecations. We must read PR #41 and the diff directly before scoring this.

Key questions to put to the maintainer / our team:

1. What is the exact v2 → v3 migration path, and is there a re-encryption command or dual-read mode?
2. Where and how is per-user key material stored and derived — app-owned or package-owned? Is a KMS/HSM backend supported?
3. Is the on-disk ciphertext format stable from alpha1 to GA, or should we expect another break?
4. What is the key-rotation story for an individual user without downtime?
5. What is the target Laravel/PHP support matrix for v3, and the GA timeline?
6. Is there a security review / CVE history / disclosure policy for the package?

Integration Approach

Stack fit. Assumes Laravel 9–11 and PHP 8.1+, consistent with v2. Confirm the exact constraint from composer.json before committing — alpha releases often bump minimum PHP/Laravel. It slots into existing Eloquent models via casts, so it is additive to the current data layer rather than a rewrite.

Migration path. Treat this as a data migration, not a dependency bump:

1. Inventory every column currently encrypted under v2 and classify by tenant/user ownership.
2. Stand up a shadow path: keep v2 read/write live, add v3 read-only decryption in a branch, and validate round-trip fidelity on a production-shaped dataset.
3. Design the backfill: for each row, decrypt with the v2 app key, re-encrypt with the resolved per-user key, write to a new column or new table, then cut reads over in a single deploy with the old columns retained for rollback. Never do this in-place without a fallback.
4. Only after a clean backfill do you drop v2 ciphertext.

Compatibility. The alpha API may move. Pin to an exact alpha tag (not ^3.0@alpha), wrap the package behind our own thin EncryptionService interface so an API change or a swap to an alternative (e.g. Laravel's native encrypted cast + a custom key resolver) is a one-file change. Do not let package classes leak into domain code.

Sequencing.

1. Spike (1–2 wks): branch install, read PR #41, prototype per-user key derivation, benchmark decrypt throughput on realistic row sizes.
2. Design review: key custody, rotation, recovery, and the backfill/rollback runbook signed off by security.
3. Non-production soak: full backfill in staging; chaos-test key loss and rotation.
4. Canary: one low-risk tenant or non-critical dataset in production.
5. GA gate: do not expand to regulated/PII data until v3.0.0 stable ships and the ciphertext format is declared frozen.

Operational Impact

Maintenance. We inherit a security-critical dependency on an alpha track. Budget ongoing effort for: tracking upstream releases, re-validating ciphertext after any format change, and owning the key-management layer the package does not provide. Pin versions; subscribe to the repo's releases; review every diff that touches key derivation.

Support. Effectively self-support. One active contributor, no vendor SLA, sparse release notes. Our on-call runbook must document decryption failure handling end-to-end, because there is no one to escalate to at 3 a.m. Add a named internal owner for this package.

Scaling. Two new bottlenecks versus v2: (a) key resolution per decrypt — cache per-user keys in memory/Redis with a short TTL, or every model hydration becomes a key-store round trip; (b) key-store availability — if keys live in a DB or KMS, that store is now on the critical path for every read of encrypted data. Load-test decrypt-heavy endpoints (exports, list views) before rollout; per-user key derivation (if KDF-based) is CPU-bound and should be memoized, never recomputed per row.

Failure modes to instrument and rehearse:

• Key unavailable / KMS timeout → encrypted reads fail. Define fail-closed vs. degraded behavior per endpoint; alert on resolution error rate.
• Key loss or corruption → permanent, per-user data loss. Enforce key-store backups and test restore quarterly.
• Wrong-key resolution (tenant A key used for tenant B) → either decrypt failure or, worse, a silent isolation breach. Add a key-ID/AAD binding to ciphertext and assert it on decrypt; log and alert on mismatch.
• Partial backfill → mixed v2/v3 ciphertext. Dual-read during migration with a metric on v2-ciphertext count; block v2 removal until it hits zero.
• Upstream alpha regression → ciphertext written by a bad alpha build. Restrict alpha use to staging; checksum-verify round-trips in CI.

Ramp-up. Expect 1–2 weeks for the spike and 3–5 days of engineering for the migration tooling and backfill runbook, plus security review time. The team does not need deep cryptography knowledge to use the package, but it does need enough to own key custody, rotation, and recovery — if that expertise is absent, budget for it or choose a managed KMS-backed alternative. Document the decision and its rationale in an ADR so the next engineer understands why per-user encryption was adopted and what the recovery contract is.