Jwt Refresh Token Bundle Laravel Package

Technical Evaluation

Architecture fit — mismatch at the framework level. Despite landing in a Laravel package request, free-work-agsi/jwt-refresh-token-bundle is a Symfony bundle, not a Laravel package. It depends on Symfony's Bundle/Kernel registration, the DI container, Symfony\Security authenticator factories, the EventDispatcher, and — in its upstream lineage — Doctrine ORM plus lexik/jwt-authentication-bundle. Laravel ships a subset of Symfony components (HttpFoundation, Console, Process) but does not boot the FrameworkBundle, so a bundle cannot be auto-discovered, registered, or wired into a Laravel guard. There is no service provider, no publishable config, no facade, no auth driver. This is a structural incompatibility, not a packaging detail a shim can fix.

Integration feasibility — effectively zero as a Composer dependency. A TPM should rule out "install and configure" before any engineering time is spent. Composer may resolve the constraint graph (Laravel's Symfony component pins can overlap), but successful composer require is not evidence of fitness. The one viable consumption path is pattern extraction: read the refresh-token entity shape, the rotation/revocation semantics, TTL and cookie/header handling, and reimplement Laravel-natively (est. 200–400 LOC) on top of tymon/jwt-auth, Passport, or Sanctum. The bundle's value to us is as a reference implementation of a well-understood pattern, and a modest one at that — the upstream gesdinet project is the better reference anyway.

Technical risk — high, driven by provenance rather than code quality. 0 stars, 0 dependents, score 0, and an unfamiliar agency namespace (free-work-agsi) indicate a private fork or mirror of the canonical gesdinet/jwt-refresh-token-bundle. Concrete risks:

• Provenance / supply chain. Unclear publisher, unclear tagging/reproducibility, unclear whether it tracks upstream. MIT license is the one clean signal — permissive, no legal friction for reading or reusing the pattern.
• Security-patch lag. Refresh-token rotation and reuse-detection are security-critical paths. A fork diverges from upstream CVE fixes by default and has no community to flag regressions.
• Zero field validation. No dependents means no public evidence of production use, no issue corpus, no failure-mode folklore to lean on.
• Unbounded token table risk. Upstream-style implementations persist one row per active session; without a GC job this is an operational bug waiting to happen.

Key questions for the requesting team

1. What is the actual requirement — long-lived sessions, token revocation, "log out all devices," or full OAuth2 refresh grants? Several Laravel-native options cover the first three.
2. Is any part of the target system genuinely Symfony? If yes, scope changes entirely and we should evaluate gesdinet upstream directly.
3. Was this package chosen deliberately (vendor relationship, existing Symfony estate), or surfaced by a search and triaged on the word "PHP"?
4. If we adopt or vendor it, who owns security-patch intake and the upstream diff review?
5. Do we need reuse detection and family-based revocation (the hard part), or just a longer-lived credential with a blacklist?

Integration Approach

Stack fit. The package presumes Symfony 4/5/6+, lexik/jwt-authentication-bundle, Doctrine ORM/DBAL, and Security firewalls. Laravel 10/11 pins Symfony components at 6.x/7.x for HTTP/Console/Process only. Satisfying Composer constraints does not make the bundle functional — do not let a green composer install be read as feasibility. Treat the Symfony route as out of scope unless a platform mandate says otherwise.

Migration path — Laravel target.

• Do not integrate the bundle. Run a short timeboxed spike (1–2 days) to confirm the mismatch in writing, then close it out with a decision record.
• Choose a Laravel-native equivalent instead:
  • tymon/jwt-auth — closest conceptual match (access + refresh, blacklist), mature Laravel integration, good if we want JWT semantics.
  • Passport — if clients require an OAuth2-compliant refresh grant (third-party API consumers, scoped issuance).
  • Sanctum — if first-party SPA/mobile with simple revocation suffices; cheapest to operate.
• Extract the pattern from this bundle or upstream gesdinet — token entity shape, rotation-on-use, invalidation events, TTL configuration — and implement it on whichever guard we pick. Then add our own tests around rotation and revocation.
• Symfony target (only if real): Composer-install, register the bundle in bundles.php, run the refresh-token table migration, wire the firewall and token extractor. Straightforward mechanically — but validate provenance and diff against upstream before production.

Compatibility checks (Symfony path only). PHP constraint, Symfony minor range, Doctrine DBAL version, exact Lexik version, and whether the fork has drifted from upstream in ways that break documented config keys. On the Laravel path, the compatibility question is inverted: verify our chosen native package against our Laravel and PHP versions, not this one.

Sequencing.

1. Answer the framework question — Symfony or Laravel. This single fact collapses most of the decision space and should be forced to a decision, not left ambiguous.
2. Provenance and upstream-diff review — composer show, namespace check in vendor/, tag comparison against gesdinet.
3. Timeboxed spike behind a feature flag on a throwaway branch, to produce evidence rather than opinion.
4. Decision record: adopt / extract-pattern / reject. Circulate it — this question will recur.
5. Only then token-lifecycle design, rotation and revocation test coverage, GC job scheduling, and client SDK coordination.

Operational Impact

Maintenance. If adopted, we own it outright. A 0-dependent fork has no community to absorb upgrades; every upstream security fix becomes a manual cherry-pick with a named engineer accountable. Budget this as recurring cost, not a one-time integration line item. If we extract the pattern instead, maintenance collapses to our own auth code — smaller surface, our tests, our on-call rotation, and full control over rotation semantics.

Support. No vendor SLA, no visible active issue tracker, no Stack Overflow corpus, no blog posts describing failure modes. Incidents will be debugged from source by whoever is on call. Contrast with Passport/Sanctum/tymon, where the failure modes are documented and widely encountered — a real operational advantage that should be weighted in the decision, not dismissed as "not technical."

Scaling. Refresh-token stores are write-heavy: rotation writes a row per refresh, and the table grows monotonically with active sessions. Plan for hashed-token storage with a unique index, a scheduled pruning/GC job, and database connection headroom. At high refresh volume, per-request writes become a throughput consideration — validate against projected session counts before committing to this design over a stateless alternative.

Failure modes to design for

• Database unavailability → all refreshes fail → mass forced logout. Needs a documented degradation story.
• Reuse/revocation gaps → silent session hijack persistence. This is the failure that matters most and is the hardest to test; rotation and family-revocation tests are non-negotiable.
• Clock skew and expiry-boundary bugs → intermittent 401s that are expensive to diagnose in production.
• Signing-key rotation without an overlap window → coordinated outage across all clients.
• Cookie vs. header storage misconfiguration → CSRF or XSS exposure depending on which direction it's wrong.
• Unbounded token table → storage creep and slow lookups; mitigate with GC from day one.

Ramp-up. Symfony's Security model (firewalls, authenticators, token extractors) is a different mental model from Laravel guards and middleware. Any engineer maintaining a Symfony-derived implementation needs Symfony-specific context — a real cost on a Laravel team, and a direct argument for a native alternative. Extracting the pattern onto a Laravel-native package keeps ramp-up at near zero for a Laravel developer.

TPM recommendation: treat this as a reference for token semantics, not a dependency. Escalate the framework mismatch to the requester, force the Symfony-vs-Laravel question to a written decision, and default to a Laravel-native auth package (Sanctum for first-party, Passport for OAuth2, tymon/jwt-auth for JWT-style) unless a vendor or platform mandate overrides. Record the decision so the same 0-star fork doesn't resurface in the next backlog grooming.