Jwt Refresh Bundle Laravel Package

Technical Evaluation

Verdict up front: this is not a Laravel package, and cannot be adopted as one. yivoff/jwt-refresh-bundle is a Symfony bundle built to complement LexikJWTAuthenticationBundle. Its Composer constraints pull symfony/framework-bundle, symfony/security-bundle, and Lexik. Laravel has no bundle kernel, no compile-time DI container, and no Symfony firewall/event system, so composer require in a Laravel app will either fail resolution or install dead, un-wired code. Any "leverage" here is architectural, not dependency-level.

Architecture fit

• The problem it solves is real for Laravel APIs: short-lived stateless access tokens paired with a stateful, revocable, rotating refresh token. Laravel teams typically reach for Passport, Sanctum, or tymon/jwt-auth; the rotation-and-reuse-detection pattern is exactly what tymon/jwt-auth lacks out of the box.
• The implementation is tightly bound to Symfony: Lexik events (AuthenticationSuccessEvent, JWTCreatedEvent), a firewall factory, Doctrine ORM mappings for the refresh token entity, and Symfony config tree definitions. None of these have Laravel analogues that can consume the code directly.
• Net fit for a Laravel codebase: low as a package, moderate as a design reference.

Integration feasibility

• As a dependency: effectively zero without a Symfony service container present.
• As a port: tractable. The domain surface is small — a token entity, a manager with issue/rotate/revoke/invalidate operations, a controller endpoint, and a security listener. Mapping to Eloquent + a service provider + a route/middleware is a few hundred lines of work, not a rewrite of a framework.
• As inspiration only: highest value-to-effort ratio. Extract the state machine (issue → rotate on use → detect reuse → revoke token family) and implement it natively.

Technical risk

• Adoption signal is the headline risk: 3 stars, 0 dependents, low composite score. Single-maintainer, effectively unexercised in production. No downstream users means no incidental security review and no CVE-reporting gravity.
• Refresh token handling is security-critical (long-lived credentials, replay windows, revocation semantics). Betting that on an unvetted 3-star dependency is a poor trade.
• MIT license is clean; no legal friction.
• Framework version drift is likely — Symfony 5/6-era bundles age quickly, and there is no evidence of active maintenance.

Key questions to resolve before committing any effort

1. Does it hash refresh tokens at rest, or store them plaintext in the DB?
2. Does it implement rotation with reuse detection (revoke the family on replay), or only simple expiry?
3. Is multi-device / multi-session supported (one token per device), or single-token-per-user?
4. What are the hard version constraints on PHP, Symfony, and Lexik?
5. Is there an idempotency/grace window for concurrent refreshes, or does a double-submit invalidate the session?
6. Are there tests covering the replay and revocation paths?

Integration Approach

Stack fit

• If the target is Laravel and OAuth2 semantics are acceptable, Laravel Passport already delivers hashed-at-rest refresh tokens, revocation, scopes, and a maintained security story. This is the default recommendation.
• For first-party SPAs, Sanctum (cookie sessions) removes the refresh-token problem entirely.
• Only if the product needs a JWT-shaped access token with custom rotation semantics should a hand-rolled implementation be considered — and in that case, port the pattern from this bundle rather than the code.

Migration path (if a port is chosen)

1. Replace the Doctrine entity with an Eloquent model: refresh_tokens table (id, user_id, token_hash, expires_at, revoked_at, parent_id/family_id, device_fingerprint, timestamps).
2. Replace the Symfony manager with a Laravel service (RefreshTokenService) bound in a service provider; expose issue(), rotate(), revoke(), revokeFamily().
3. Replace the Lexik listener with a controller action plus a route (POST /auth/refresh), guarded by throttle and a token-in-body-or-cookie extraction rule.
4. Replace the config tree with config/jwt-refresh.php (ttl, refresh_ttl, rotate, reuse_detection, prune_after).
5. Wire the access token minting to whichever library is already in place (tymon/jwt-auth or firebase/php-jwt).

Compatibility

• Source package targets Symfony/Lexik-era PHP; a Laravel port would target PHP 8.1+ and Laravel 10/11 conventions. There is no shared runtime to reconcile — the port is a re-implementation, so treat the original strictly as a spec.
• Data model is simple enough that nothing in the port blocks on the upstream project's future.

Sequencing

1. Audit the existing auth stack and confirm whether Passport/Sanctum already covers the need (often it does — stop here).
2. If not, write a one-page spec of the rotation state machine, citing the bundle's README as precedent.
3. Implement storage + issue/rotate with tests for: reuse detection, concurrent refresh, expiry, revocation, and logout-all-devices.
4. Ship behind a feature flag per client; migrate sessions on next login rather than invalidating everyone.
5. Add the pruning job before enabling in production.

Operational Impact

Maintenance

• As a Composer dependency in Laravel: there is no viable support path. No Laravel community answers, no issue traffic, no maintainer throughput signal.
• As a fork/port: your team owns it outright. That is the honest cost of adopting anything here — the code is small, but it is security-sensitive code you must now review, test, and patch.

Support

• Upstream support is Symfony-shaped at best. Any Laravel-specific question is unanswerable by the maintainer. Do not expect upstream security advisories to reach you through normal dependency channels.

Scaling

• The refresh token table grows one row per login per device. Without pruning it will dominate the auth schema over time. Required: index on token_hash (unique), index on user_id, index on expires_at for the prune sweep, and a scheduled refresh_tokens:prune command.
• Read/write volume is trivial relative to access token traffic; no sharding or cache layer needed at typical SaaS scale.
• Rotation writes one row per refresh; at high refresh frequency, consider an update-in-place with a short audit trail rather than unbounded insert history.

Failure modes to design against

• Double-submit on rotation — two concurrent refreshes from the same client revoke the session. Mitigate with a short grace window returning the same rotated token, plus client-side single-flight.
• Reuse-detection false positives — aggressive revocation families log out legitimate users on flaky networks. Log and alert on family revocations; make the threshold configurable.
• Clock skew / TTL drift — access token expiry and refresh token expiry must be independently validated server-side.
• Prune job failure — silent table bloat; alert on row count and job success, not just on errors.
• Hashed-token lookup cost — if lookup is by hash of a high-entropy random token, this is fine; if by a slow KDF, refresh latency becomes a bottleneck. Confirm the hashing strategy before porting.

Ramp-up

• An engineer comfortable with Symfony security can read the bundle and produce an equivalent Laravel spec in roughly 2–3 days; a Laravel-only team should budget ~5 days including tests, pruning, and rollout.
• Recommended TPM posture: do not add this as a dependency, and do not fund a port unless Passport and Sanctum have both been explicitly ruled out. If a port does proceed, the justification is the documented rotation pattern — the 3-star, zero-dependent upstream is a liability, not an asset.