Lighthouse Graphql Passport Auth Laravel Package

Technical Evaluation

Package: joselfonseca/lighthouse-graphql-passport-auth — GraphQL auth mutations (register, login, refresh, logout, forgot/reset password, social login) for Laravel apps running Lighthouse GraphQL on top of Laravel Passport.

Architecture fit: Narrow but well-defined. It sits at the intersection of three moving parts — Laravel, Lighthouse (schema directives + GraphQL execution), and Passport (OAuth2 token issuance). For teams already committed to that trio, it removes a meaningful amount of boilerplate (token issuance, refresh-token rotation, password grant wiring, schema type definitions). It is a poor fit for teams not already on Lighthouse, or for teams using Sanctum/session auth — it does not abstract over auth strategies.

Integration feasibility: Straightforward mechanically — composer require, publish config, run Passport migrations, register the provided schema/types and directives. The real cost is version-matrix alignment: this package's majors track Passport majors, which in turn track Laravel majors. That cascades into the Lighthouse version, PHP version, and laravel/passport constraint simultaneously.

Technical risk — this release: 11.0.0 is a major bump whose entire documented delta is one line: "Passport 13 Support." By semver convention a major bump signals breaking changes, and the changelog does not say what breaks. The most probable breaking surface, none of it documented:

• Minimum PHP / Laravel / Lighthouse / Passport constraints raised; Passport 12 and possibly older Laravel lines dropped.
• Possible removal or renaming of config keys, directives, or mutation input fields to match Passport 13's API.
• Possible changes to refresh-token or password-grant behavior, since Passport 13 reshaped parts of those flows.
• No migration guide, no deprecation notice, no test matrix published in the notes.

Additional structural risk: single-maintainer package, low bus factor, and "New Contributors" indicates this release's headline feature came from a first-time contributor — good for the project, but it means the core maintainer did not necessarily author the compatibility work. Release cadence is event-driven (it bumps when Passport bumps), so upgrades are externally forced rather than schedulable on your terms.

Key questions to resolve before adopting 11.0.0:

1. What is the exact composer.json constraint set for laravel/framework, laravel/passport, nuwave/lighthouse, and PHP in 11.0.0 vs 10.0.4?
2. Does 11.0.0 support Passport 12, or is it a hard cutover? (Determines whether this is a forced upgrade for us.)
3. Are any public schema artifacts — directive names, mutation signatures, input types, config keys — changed? Diff the src/ and graphql/ trees, not just the changelog.
4. Is there a published CI matrix (Passport 12/13 × Lighthouse versions × Laravel versions)? Absent one, assume compatibility is asserted, not proven.
5. Does the password-grant / refresh flow behave differently under Passport 13 (token TTLs, revocation semantics, hashed client secrets)?

Integration Approach

Stack fit: Assume Laravel 11/12, PHP 8.2+, Lighthouse 6.x, Passport 13. If we are on Passport 12 or Lighthouse 5.x, 11.0.0 is likely unavailable to us and we should stay pinned at 10.0.4 until we plan the broader framework upgrade. This package should never be the item that drives a Laravel major upgrade; it should follow one.

Migration path (10.0.4 → 11.0.0):

1. Confirm the constraint diff by inspecting composer.json at both tags and running composer why-not against our lockfile.
2. Upgrade laravel/passport to 13 first, in isolation, and validate existing token issuance before touching this package.
3. Bump this package to ^11.0, then run the full auth test suite: register, login, refresh, logout, forgot/reset password, and any social-login path we expose.
4. Verify the GraphQL schema is byte-identical (php artisan lighthouse:print-schema diff against the pre-upgrade output) — this is the fastest way to catch undocumented directive or type changes.
5. Only then remove the explicit 10.0.4 pin.

Compatibility: Treat the version as a three-way lock: Passport major ↔ this package major ↔ Lighthouse major. Document that tuple in the repo. Anything outside it is unsupported in practice regardless of what Composer resolves.

Sequencing: Do not adopt 11.0.0 reactively on release day. Gate it behind the Passport 13 upgrade ticket and a staging soak covering token refresh and expiry, which are the flows most likely to break silently (they fail at TTL boundaries, not on the first request).

Operational Impact

Maintenance: Low ongoing code footprint, but the upgrade obligation is externally imposed: every Passport major will force a corresponding major here, on Passport's schedule, not ours. Sparse release notes mean each bump costs real investigation time. Budget roughly one engineer-day per major bump for constraint analysis, schema diffing, and auth regression testing.

Support: GitHub issues only, no vendor, no SLA. For an auth-critical dependency that is a genuine consideration — mitigate by keeping the surface small (use the package for token issuance, not for business logic) and by owning an integration test suite that does not depend on the maintainer's tests.

Scaling: Token issuance is database- and crypto-bound via Passport, not by this package. The scaling concerns are Passport's: token table growth and pruning (passport:purge), key rotation, and per-request token lookups on authenticated queries. This package adds a thin GraphQL layer that does not materially change throughput characteristics. Auth mutations are inherently write-heavy and low-QPS relative to query traffic.

Failure modes to instrument:

• Silent breakage of refresh-token rotation after a major bump — surfaces as a wave of 401s at token expiry, hours after deploy.
• Schema drift from an undocumented directive change — surfaces as client-side GraphQL validation errors for a subset of operations.
• Passport key/secret misconfiguration or rotation without overlap — hard auth outage, all mutations failing.
• Expired/absent OAuth encryption keys in a new environment — works locally, fails on first deploy.
• Error masking: Lighthouse wraps resolver exceptions, so Passport failures can reach clients as generic GraphQL errors with the real cause only in logs.

Ramp-up: Low for a Laravel developer familiar with Lighthouse directives — an afternoon to read the schema definitions and config. Moderate for teams new to Lighthouse, because debugging requires comfort with both GraphQL execution order and Passport's grant flows; failures in either layer can look identical from the client side. Recommend that whoever owns this package also owns the Passport upgrade path, so the two are never out of step.

Recommendation: Adopt 11.0.0 only when Passport 13 is already in place or planned in the same cycle. Before merging, obtain answers to questions 1–3 — specifically the constraint diff and the schema diff — since the release notes alone are insufficient to characterize a major version. If we remain on Passport 12, hold at 10.0.4, pin it explicitly, and open a ticket to track the Passport 13 upgrade.