Sanctum Refresh Tokens Laravel Package

Technical Evaluation

Architecture fit: The package extends Laravel Sanctum with refresh-token behavior and now persists token abilities on personal_refresh_tokens, which aligns with Laravel’s guard/ability model and fixes a material scoping defect. It remains a Laravel-native package: migration-driven schema change, service-layer auth flow, and an AuthenticatableUser base that depends on Illuminate\Foundation\Auth\User.

Integration feasibility: Feasible for Laravel 12/13 and PHP 8.3+ applications using Sanctum. The release improves adoption confidence through Pest/Testbench coverage, SQLite/PostgreSQL/MySQL CI, PHPStan/Larastan level 6, and explicit dependencies on illuminate/auth, illuminate/notifications, and laravel/framework. The abilities migration is the primary integration step.

Technical risk: Moderate upgrade risk due to breaking changes: Laravel 11 and PHP 8.2 are dropped. Security risk is materially reduced because v4 fixes the refresh flow that previously reset scoped access-token abilities to ['*'], which could widen permissions. Residual risk centers on existing refresh-token rows after the migration: the team must confirm how abilities is defaulted/backfilled and whether old tokens should be invalidated or reissued. The custom email-column fix is low risk but should be validated if the app uses nonstandard user models.

Key questions: Are we on Laravel 11 or PHP 8.2 anywhere this package is deployed? Do we rely on token abilities/scopes? What is the backfill/default behavior for existing personal_refresh_tokens.abilities rows? Is there an upgrade guide for v3.1.0 → v4.0.0? What Sanctum versions are supported beyond Laravel 12/13? Who owns third-party security monitoring for this package?

Integration Approach

Stack fit: Best fit is a Laravel 12/13 + Sanctum application on PHP 8.3–8.5 with MySQL, PostgreSQL, or SQLite. Teams using scoped API tokens should prioritize this upgrade because it preserves abilities across refreshes and after access-token pruning.

Migration path: Treat this as a framework-level upgrade gate, not a routine patch. Confirm Laravel and PHP baselines first, then upgrade the package, run the new abilities migration, and define an explicit backfill or token-reissue strategy. If existing refresh tokens cannot be mapped to correct abilities, invalidate them and force reauthentication rather than risk over- or under-permissioned tokens.

Compatibility: The release declares Laravel ^12.0|^13.0 and PHP 8.3+. Cross-database CI reduces migration risk, but the team should still validate against the exact database engine/version in production, especially if using PostgreSQL or MySQL with existing token data.

Sequencing: 1) Inventory Laravel/PHP versions and token-scope usage. 2) Upgrade Laravel/PHP where required. 3) Upgrade the package in a branch. 4) Run the migration and backfill/reissue plan in staging. 5) Exercise login, refresh, logout, password reset, replay protection, and scoped-token refresh paths. 6) Deploy with token-table monitoring. 7) Prune legacy refresh tokens after the new behavior is verified.

Operational Impact

Maintenance: Positive signals: MIT license, rewritten README, CI matrix, cross-database tests, and static analysis. The package still requires internal ownership for dependency tracking and security review, but v4.0.0 shows stronger release discipline and semver-visible breaking changes.

Support: Community/open-source support only; no commercial SLA. The improved test suite and README reduce support burden, but the team should maintain an internal runbook for token migration, rollback, and reauthentication/backfill decisions.

Scaling: Refresh-token tables grow with active sessions and token rotation. The abilities column adds minor storage but improves authorization correctness. Teams need a pruning/retention job and should monitor token issuance, refresh failures, replay-protection triggers, and TTL enforcement.

Failure modes: Primary failure modes are failed abilities migration, incorrectly defaulted abilities on legacy tokens, accidental permission widening or denial after upgrade, custom user-model/email-column regressions, and dependency conflicts during Laravel 13 adoption. The prior ['*'] refresh bug is a serious failure mode now fixed, so delaying the upgrade is riskier for scoped-token deployments.

Ramp-up: Low-to-moderate. Laravel teams familiar with Sanctum can integrate quickly, but the breaking-change gate and token backfill require deliberate planning. Allocate time for staging validation across auth flows and database engines before production rollout.