Cilician Bundle Laravel Package

Technical Evaluation

Architecture fit

The decisive fact is a metadata contradiction that a TPM must resolve before any engineering hour is spent. The package description and documentation.md describe a Laravel/PHP bundle — "auto-discovered service provider," "publishable configuration," "works with Octane." The technical assessment describes a Symfony bundle shipping a Bundle class and Symfony DependencyInjection service definitions. These cannot both be true of the same artifact. The most likely explanation is that the description text is generic template boilerplate that was never reconciled with the actual source, and the source is Symfony. Either way, the documentation is not a reliable specification of the artifact, and any decision must be made from reading the code, not the listing.

Assume the Symfony reading is correct. Fit against a Laravel codebase is then poor as a dependency: Laravel's container does not boot Symfony bundles, so the package's only real value-add (DI wiring, YAML config, autowiring) evaporates. What remains is a thin HTTP facade over the HIBP v3 REST API — breachedAccount, pasteAccount, breaches, breach/{name}, dataClasses, latestBreach. There is no algorithm, schema, or storage layer to inherit. Architecturally the package is a reference implementation of request semantics (API-key header, mandatory User-Agent, 404-means-not-breached, 429 backoff), and those semantics are the entire thing worth having.

Integration feasibility

Three paths exist: (a) install via a VCS repositories entry and hand-wire the non-bundle classes, (b) fork and strip the Symfony DI layer, (c) reimplement natively in Laravel. Option (c) is the only one with a defensible cost/benefit ratio, and the effort is hours, not sprints — the client logic is on the order of 100–200 lines. Options (a) and (b) import a maintenance liability and a provenance question into an authentication path in exchange for saving an afternoon.

Composer installability is an unresolved blocker. The package is Codeberg-hosted with no evidence of a Packagist release, tagged versions, or semver. Stars are blank, dependents are 0, score is 0 — there is no adoption signal and no production track record.

Technical risk

• Supply chain. Unknown maintainer, non-GitHub hosting, no visible CI, no test suite, no security advisory channel. Pulling arbitrary VCS code into a PII-handling auth path is hard to justify to any reviewer.
• Abandonment. Zero dependents and zero score imply unmaintained or pre-release. HIBP's API has changed materially over time (v2 → v3, mandatory keys, rate-limit enforcement); an unmaintained wrapper rots silently.
• Secret and PII handling. A package reading an HIBP key from framework config must be audited for whether it logs request URLs, email addresses, or key material. On the breach-lookup endpoints, the query parameter is the user's email.
• Licensing. No licence is stated. This blocks even snippet reuse until confirmed.
• Scope misrepresentation. The generic description invites a team to assume Laravel compatibility that the code may not provide. That is a procurement risk in itself: it will pass a skim and fail at integration.

Key questions

1. Is this a Symfony bundle or a Laravel package — and which is the artifact actually published on Codeberg?
2. Is there a Packagist entry with tagged, semver-stable releases, or is this VCS-only?
3. What is the licence, and does it permit commercial reuse of the client classes?
4. Which HIBP v3 endpoints are covered, and does it implement the paid-key hibp-api-key header and the mandatory User-Agent?
5. Does it treat 404 as "not breached" rather than an error, and expose backoff on 429?
6. Does it support the free Pwned Passwords range API (k-anonymity, 5-char SHA-1 prefix) — the only endpoint requiring no paid key?
7. Is there any test coverage, mocking strategy, or recorded fixture set?

Integration Approach

Stack fit

Recommendation: do not depend on the bundle; reimplement natively. A first-party service — an interface plus an Http-backed implementation bound in a service provider — reproduces the package's entire surface area and inherits Laravel's retry, timeout, and RateLimiter primitives. Configuration lives in config/services.php (hibp.key, hibp.user_agent, hibp.base_url, hibp.timeout), with the key from the environment and excluded from version control. Reuse only the bundle's request/response mapping knowledge as documentation, subject to licence review — not its code.

Migration path

There is nothing to migrate: no Laravel application can be running this bundle today. Treat it as greenfield. Where a team already calls HIBP through ad-hoc Http::get() in controllers, the migration is a refactor behind the new interface plus a grep-and-replace — contained and reversible.

Compatibility

Laravel 10/11/12 on PHP 8.1+ supplies every primitive needed (Http, RateLimiter, Cache, Queue); no Symfony dependency is required. Note the recurring commercial constraint: HIBP v3 requires a paid API key (~$4/month) for the breach and paste endpoints, and anything built here inherits that cost plus terms-of-use obligations (no bulk enumeration, respect rate limits, no resale). The Pwned Passwords range API is free and hashed — which is precisely why it should be the v1 scope.

Sequencing

1. Resolve the Symfony-vs-Laravel question and confirm licence and endpoint coverage; expect to reimplement.
2. Land config + interface + Http client with explicit 404/401/429 handling and a constant User-Agent.
3. Add caching (the breach catalogue is near-static — cache for hours) and a RateLimiter keyed to HIBP's ~1.5 req/sec ceiling.
4. Move email lookups into queued jobs; emit domain events (EmailBreachDetected) for notification and risk-scoring consumers.
5. Contract tests against recorded fixtures, plus a fake implementation so local and CI runs need no key.
6. Only then wire user-facing surfaces: signup guard, password-reset check, admin lookup.

Operational Impact

Maintenance

Depending on the bundle means owning a fork of an unmaintained third party regardless — you will patch it when HIBP changes headers or status semantics. Owning ~150 lines of first-party code is strictly less maintenance and removes the code-review and provenance burden. The breach catalogue is maintained upstream and is near-immutable per record; caching reduces both API spend and the blast radius of upstream outages.

Support

No vendor, no SLA, no maintainer responsiveness signal, no advisory channel. The escalation path for a broken integration is "read HIBP's docs and patch it yourself" — which argues for first-party code where that patch is a one-line PR rather than a vendored fork. Internal support burden is low either way: one HTTP dependency, one credential, one documented rate limit.

Scaling

Throughput is bound entirely by HIBP's rate limits and key tier, not by application code — the package contributes nothing here. Queue lookups, cache aggressively, and never call HIBP synchronously on signup, login, or password reset without a timeout budget. At volume, self-host the Pwned Passwords range dataset rather than network-calling in a hot path.

Failure modes

• HIBP outage or latency spike blocks signup/login if wired synchronously. Mitigation: short timeouts, circuit breaker, and fail-open — an HIBP failure must never deny authentication.
• Rate-limit exhaustion (429) degrades silently into errors if backoff is unhandled. Mitigation: queueing plus a limiter; treat 429 as a retryable signal, not a failure.
• Silent rot from an unmaintained wrapper — an API change turns into a runtime exception discovered in production. Mitigation: first-party code plus contract tests against fixtures.
• PII leakage through unvetted logging of request URLs containing email addresses. Mitigation: audit logging before enabling breach lookups.
• Procurement failure discovered late — licence unknown, zero dependents, single maintainer. Mitigation: settle this in week one, not at security review.

Ramp-up

Low for a Laravel team: one interface, one adapter, one config file, one queued job — a day or two including tests. The genuine ramp-up cost is not technical but governance: deciding whether HIBP email lookups send user addresses to a third party (DPA, privacy-notice update, DPIA entry, data-residency review). Ship the free, hashed, password-only check first precisely because it defers that work and delivers the visible NIST/OWASP-aligned control now. Treat this package as evidence for the pattern — wrap HIBP behind an internal interface — not as the artifact to adopt.