Sanctum Refresh Tokens Laravel Package

Product Decisions This Supports

• Build vs. buy on auth plumbing. Refresh-token rotation, hashed storage, replay protection, and TTL enforcement are well-understood but easy to get subtly wrong. This release is evidence the package treats them as first-class (dedicated Pest suite, cross-database runs against SQLite/PostgreSQL/MySQL, PHPStan/Larastan level 6). The defensible PM call is to buy this and spend engineering time on differentiated product instead.
• Whether you can offer scoped/delegated access at all. The headline fix matters commercially: AuthService::refresh() previously reset token abilities to ['*'], silently widening a scoped token to full permissions on every refresh. Any roadmap item that depends on least-privilege tokens — third-party integrations, partner APIs, per-client permissions, read-only tokens, multi-tenant delegation — was effectively unsafe before this version. Scopes now live on the refresh token and survive refreshes and access-token pruning, which makes those features viable.
• Session lifetime and re-login friction. Persisted abilities plus enforced TTL give you honest knobs for the "how long should a user stay signed in" product decision, without trading away scope integrity to get long sessions.
• Laravel 13 upgrade timing. Laravel 13 support means this dependency no longer blocks a framework upgrade. But the same release drops Laravel 11 and raises PHP to 8.3, so it also sets the upgrade calendar — plan the two together rather than discovering the coupling mid-sprint.
• Security/compliance review effort. MIT LICENSE, a rewritten README, a real test suite, and static analysis reduce the paperwork in procurement and security review. This is the kind of thing that shortens a vendor questionnaire from weeks to days.
• Bug-fix signal for existing users. The getUserFromCredentials() fix (calling getEmailField() on a class-string, fatal for models with a custom email column) unblocks teams whose user model doesn't use a plain email column — a common setup for multi-identifier or SSO-adjacent products.

When to Consider This Package

Adopt when:

• You are on Laravel 12 or 13 with PHP 8.3+, use Sanctum for API auth, and need sessions that outlive a short-lived access token.
• You need per-token scopes that persist across refreshes — this is the decisive reason to be on v4 rather than v3.
• You want rotation, hashing, and replay protection as maintained behavior rather than in-house code.
• Your security review needs test coverage, static analysis, and a permissive license on record.

Look elsewhere — or stay put — when:

• You are on Laravel 11 or PHP 8.2. v4 is a hard break; remain on 3.1.x and treat this as a scheduled migration, not a routine bump.
• You need full OAuth2 (authorization code, grants, client registry, introspection) — that is Laravel Passport's job, not a refresh-token add-on.
• You need JWT/OIDC interoperability or token introspection endpoints.
• You require commercial support, an SLA, or a security-response commitment. Verify maintainer responsiveness, release cadence, and whether a security policy exists before making this load-bearing. Single-maintainer concentration is a real risk to price in — this release is a positive signal (CI matrix, cross-DB jobs, changelog hygiene), but it is one data point.
• Your users are first-party SPA clients on the same domain, where Sanctum's cookie-based SPA auth removes the need for refresh tokens entirely.

Before committing, confirm the upgrade cost on your side: the new abilities column requires a migration on personal_refresh_tokens, the three newly declared dependencies (illuminate/auth, illuminate/notifications, laravel/framework) should be checked against your lockfile, and existing refresh tokens issued under v3 will not carry persisted abilities — decide whether to invalidate them or grandfather them.

How to Pitch It (Stakeholders)

For executives: This is a small, MIT-licensed dependency that removes a category of self-inflicted security risk from our auth stack. The v4 release fixes a privilege-escalation flaw where a narrowly scoped token could silently regain full permissions on refresh — the kind of defect that becomes a customer-facing incident. It also arrives with automated tests, static analysis, multi-database verification, and a clear license, which lowers our compliance and review overhead. Cost is zero; the main commitment is a scheduled upgrade window because the release drops older framework and PHP support. Recommendation: adopt v4 and align the upgrade with our Laravel 13 migration rather than running them as separate projects.

For engineering: v4 persists abilities on personal_refresh_tokens via a new migration, so scope survives refresh and access-token pruning — that closes the ['*'] widening bug and lets us build scoped tokens safely. It also fixes getUserFromCredentials() resolving getEmailField() on a class-string, which fatals for custom email columns. Breaking changes are explicit: Laravel 11 dropped (^12.0|^13.0), PHP floor raised to 8.3, and illuminate/auth, illuminate/notifications, and laravel/framework are now declared rather than assumed. The repo gains a Pest + Orchestra Testbench suite, cross-database CI, a PHP 8.3/8.4/8.5 × Laravel 12/13 matrix, PHPStan level 6, .gitattributes to keep dev files out of the dist archive, and a rewritten README. Plan the migration, decide the disposition of pre-existing refresh tokens, and re-run our auth integration tests against Postgres and MySQL, not just SQLite.