Cilician Laravel Package

Technical Evaluation

Architecture fit. Cilician occupies a narrow, low-coupling position in the stack: it is an HTTP client with no persistence, no queue worker, no middleware, and no domain model beyond request/response DTOs. Whether we treat it as a generic "framework-native toolkit" (per description.md) or — as the two engineering assessments independently concluded — a thin wrapper over the Have I Been Pwned (HIBP) REST API, the architectural verdict is the same: it is a swappable transport detail that should sit behind an internal interface (BreachLookup, PasswordRangeLookup) rather than be called directly from controllers or models. The advertised Laravel surface (auto-discovered service provider, optional facade, publishable config, typed PHP 8 API, extensible contracts, PHPUnit/Pest coverage) is exactly the shape we want for a framework-native integration, and it is the main reason this is worth evaluating at all. But the advertised shape and the observed shape do not agree, and that gap is itself the finding.

Integration feasibility. Mechanically trivial: composer require, instantiate the client with an API key, call a method. The friction is entirely in the metadata:

• Discovery/provenance. Hosted on Codeberg, not on the ecosystem's discovery surface. 0 stars, 0 dependents, no Packagist traction observed. We cannot confirm tagged semver releases, licence, or a maintained CI pipeline from the listing.
• Description drift. description.md describes a general-purpose "domain-specific integrations" toolkit. Both engineering assessments read it as a HIBP client. A package whose own summary does not match its code is a documentation-quality signal, and it means the PM cannot rely on the README for scope, cost, or compliance claims.
• Capability surface unverified. Whether the provider/facade/config actually exist, whether contracts are genuinely extensible, and whether the test suite mocks the HTTP layer are all unconfirmed.
• Consumption model. If it is not on Packagist we need a VCS repository entry pinned to a commit SHA — acceptable for a vendored dependency, but a clear signal we are adopting source code, not consuming a supported product.

Technical risk. High risk, low reward. This is a security-adjacent integration (it handles user email addresses and an API key), and the trust surface is unattractive:

• Supply chain. No audit history, no security disclosure process, no CVE record, no observable review. A zero-audience package in this position is a poor place to put credentials.
• Abandonment. Single maintainer, no dependents. We become the maintainer on day one.
• API drift. HIBP v3 and the Pwned Passwords k-anonymity protocol are stable but not frozen; HIBP adds endpoints and adjusts rate-limit behaviour. An unmaintained client lags silently.
• Correctness details that actually matter in production. 429 + Retry-After handling, jittered backoff, hibp-api-key header injection, User-Agent requirements, Add-Padding on password ranges, response caching for breach metadata, and — critically — whether request URLs, emails, or keys are ever logged or surfaced in traces. All unverified.
• The one genuinely differentiating constraint in its favour: the Pwned Passwords range endpoint uses k-anonymity, so only a 5-character SHA-1 prefix leaves our infrastructure and no plaintext or full hash is transmitted. That materially simplifies the privacy review — but it is a property of the HIBP protocol, not of this package, and it is ~150 lines to implement.

Key questions for the maintainer / spike.

1. Is the package on Packagist? What are the tagged releases, licence, and minimum PHP/Laravel versions?
2. Which HIBP API version does it target, and does it cover Pwned Passwords range queries as well as the authenticated breach/paste endpoints?
3. Do the advertised service provider, facade, publishable config, and contracts actually exist — and is config genuinely environment-aware (timeouts, retries, base URL, key source)?
4. Is there a PSR-18/PSR-17 seam, or does it construct its own transport?
5. Does the test suite mock the HTTP layer, and does it cover 200, 404, 429, 503, and timeout?
6. Does any code path log request URLs, email addresses, or the API key?
7. Does it fail open or closed when HIBP is unreachable, and is that behaviour configurable?
8. Who is jgxvx? What is the release cadence, and is there a stated support or disclosure policy?

Integration Approach

Stack fit. Assume a PHP 8.1+ / Laravel application. Cilician is unverified on both the Laravel-native axis and the PSR-18 axis, and the two assessments disagree on whether the framework wiring exists. Either way, we must not couple domain code to its types. The integration contract we own is:

• PasswordRangeLookup::isPwned(string $password): bool — k-anonymity, keyless.
• BreachLookup::breachesFor(string $email): Collection — authenticated, paid key.

The package, a fork of it, or a first-party client is an implementation detail behind those two interfaces. This is the single most important design decision, because it makes the build-vs-buy question reversible at any point.

Migration path — do not adopt directly. Three options, in recommended order:

1. Build a thin internal client (recommended). Wrap Illuminate\Support\Facades\Http (or Guzzle) with explicit connect/read timeouts, retry with jittered exponential backoff, Retry-After respect, k-anonymity range handling with prefix caching, and a single config block. Test with Http::fake() against HIBP's documented test vectors covering 200, 404, 429, 503, and timeout. Estimated 1–2 engineer-days including tests — cheaper than the provenance review required to adopt an unmaintained third party.
2. Vendor a pinned fork. If Cilician's API shape proves genuinely convenient during the spike, mirror it behind our own namespace, pin to a commit SHA, add the missing retry/timeout/logging controls, and treat it as adopted source code rather than a dependency. Budget ongoing ownership accordingly.
3. Direct composer require. Not recommended for a security-adjacent integration on these adoption signals.

Compatibility. Target PHP 8.1+ (the typed API implies 8.0+, but 8.1 is our floor) and the Laravel versions in our support matrix. Confirm no transitive dependency conflicts with our lockfile; an HTTP client that reuses the framework's own transport (or is zero-dependency Guzzle) is the ideal shape. Pin the version explicitly and mirror behind our namespace to insulate against the Codeberg repo disappearing.

Sequencing.

1. Spike (0.5 day). Clone, read src/ end to end, and run the keyless Pwned Passwords endpoint (count('password123')) to confirm autoloading, transport, and error behaviour. Resolve the description-drift question here.
2. Decision gate. If retry, timeout, backoff, and PII-safe logging are missing — highly likely — take route 1. If the API shape is materially better than we would write, take route 2.
3. Define interfaces (PasswordRangeLookup, BreachLookup) and implement, with contract tests against Http::fake().
4. Integrate at the domain boundary behind a feature flag: password screening at registration and reset first (highest leverage, keyless, no procurement dependency); breached-account scanning second (needs the paid key).
5. Operationalise. Secret management for HIBP_API_KEY, metrics on lookup latency and error rate, alerting on 429/5xx spikes, and a documented fail-open/fail-closed policy per call site.

Operational Impact

Maintenance. Effectively zero upstream maintenance. 0 stars and 0 dependents means no community patch flow: any bug, PHP 9 incompatibility, or HIBP API change is ours. The package also carries a nonzero chance of never being updated again. Owning ~150 lines of our own client is strictly cheaper than owning a fork of someone else's, which is the decisive economic argument against adoption.

Support. No SLA, no disclosure policy, no observable issue-tracker responsiveness, single maintainer on a non-mainstream forge. Our escalation path terminates at our own team regardless — so we should choose the option where that is true by design rather than by accident. The paid HIBP API key carries HIBP's own commercial terms; the package does not remove that cost or that contract.

Scaling. The binding constraints are upstream and architectural, not in the client:

• HIBP enforces per-key rate limits; authenticated breach lookups are subject to contractual limits, and keyless Pwned Passwords calls have their own throttling.
• Move checks off the request path. Inline HIBP calls at registration add external latency to a latency-sensitive flow. Queue them, with a synchronous fast-path only for the password range check if the UX demands it.
• Cache aggressively. Breach metadata is cacheable with a TTL tuned to data recency (24h is a reasonable default). Pwned Passwords prefix responses are large (hundreds of hashes per prefix) but the prefix space is highly cacheable — a local prefix cache cuts egress dramatically and is the single biggest lever on both cost and tail latency.
• Batch where possible. Bulk exposure scans of a user base should be a queued, rate-aware job, not a loop of synchronous calls.

Failure modes to design and test for.

• 429 / 503 upstream. Respect Retry-After, add jittered exponential backoff, and cap retries. Define fail-open vs fail-closed per call site: fail open for signup password screening (log, allow, alert) and fail closed only where compliance policy explicitly demands it. Make this configurable, not hard-coded.
• API key rotation / 401. Alert on auth failure rather than retrying; rotate via secret store with no deploy.
• Timeout-induced latency on the registration path. Strict connect/read timeouts plus a circuit breaker so a degraded HIBP cannot degrade signup.
• PII leakage. Email addresses must never appear in application logs, traces, or error reporting. Verify this explicitly in whatever client we adopt — including Cilician, whose logging behaviour is unverified. This is a privacy-review blocker, not a nice-to-have.
• Stale data reading as "safe." HIBP updates continuously; a cached "not pwned" is a point-in-time claim. Communicate freshness expectations to stakeholders and surface it in any customer-facing security report.

Ramp-up. Technically trivial — an engineer unfamiliar with HIBP is productive in under an hour, and the whole integration is a 1–2 day build. The real ramp-up cost is trust and compliance onboarding: provenance review, licence confirmation, data-handling assessment, and documenting a deviation from our "prefer maintained dependencies" policy if we adopt it. That review overhead exceeds the cost of writing the client ourselves, which is why the recommendation is unambiguous.

Recommendation. Reject Cilician as a production dependency. Build a thin internal client behind PasswordRangeLookup / BreachLookup; fork and pin only if the spike shows the API shape is materially better than what we would write. Ship password screening at registration/reset first behind a flag — it is keyless, high-visibility, and directly answers enterprise security questionnaires. Revisit the package only if it gains tags, tests, a disclosure policy, and observable adoption.