🔄 Migration Guide¶

This document summarises breaking changes between major versions and how to upgrade. For the full per-release changelog, see CHANGELOG.md.

📋 Index¶

Upgrading to this release — token-version revocation & hashed ephemeral tokens
Upgrading to the next release (Unreleased)
Upgrading to v5.x
Upgrading to v4.x — Config\Auth split
General upgrade checklist

Upgrading to this release — token-version revocation & hashed ephemeral tokens¶

This release ships two additive migrations and several behavioural changes that upgraders must be aware of. There are no destructive schema changes — the schema deltas are the additive users.token_version column and the new auth_webauthn_credentials table.

Required steps¶

Run migrations — two new migrations ship with this release:

Migration	Adds
`2026-05-08-000001_add_jwt_token_version_to_users`	`users.token_version` (`int`, `NOT NULL`, default `0`)
`2026-06-03-000001_create_webauthn_credentials`	`auth_webauthn_credentials` — the dedicated WebAuthn / passkey credential table

php spark migrate --all

2026-05-08-000001 backs JWT access-token revocation (see below); its down() simply drops the column. 2026-06-03-000001 creates the passkey table; it is only used when AuthSecurity::$webauthnEnabled is true, but the table is created regardless so enabling the flag later requires no further migration. See WebAuthn / Passkeys — Storage.

Schedule php spark auth:purge — AuthSecurity::$rememberMePurgeChance now defaults to 0 (was 20). Expired remember-me tokens are now rejected at validation time regardless, so the old probabilistic on-login purge is pure table maintenance. Move that maintenance to a scheduled command instead:

# Run on a schedule (cron / daycry/jobs)
php spark auth:purge            # purges expired remember-me tokens + terminated device sessions older than 30 days
php spark auth:purge --days 7   # use a 7-day retention window for terminated device sessions

auth:purge (command group Auth) removes expired rows from auth_remember_tokens and terminated auth_device_sessions rows older than --days (default 30). If you want to keep inline purging, set AuthSecurity::$rememberMePurgeChance back to a non-zero value — but a scheduled command is recommended.

Behavioural changes you must know about¶

Change	What it means for upgraders
Magic-link / password-reset tokens are now hashed at rest	`TokenEmailSender` stores `hash('sha256', $token)` in `auth_users_identities.secret`; the raw token is e-mailed and `UserIdentityModel::getIdentityBySecret()` hashes the looked-up value before matching. This is a storage-format change for those ephemeral identity types only — not a schema change. Any unconsumed magic-link / password-reset tokens issued before the upgrade become invalid. Users simply request a new link.
`auth()` throws on unknown methods	`Daycry\Auth\Auth::__call()` now throws `\BadMethodCallException` when the resolved authenticator has no such method (previously returned `null` silently). A `Session`-only method (e.g. `startLogin`, `getPendingUser`, `remember`) called while a stateless authenticator is active will now surface immediately. Audit any code that called those methods through `auth()` regardless of the active authenticator.
Access-token / JWT login logging is fingerprinted	The login-attempt log (`auth_logins.identifier`) now stores a non-reversible `hash('sha256', $token)` fingerprint for `AccessToken` and `JWT` credentials — never the raw bearer token. Session login still logs the email/username identifier (not a secret). Any tooling that parsed raw tokens out of the login log must be updated.

JWT access-token revocation (new `token_version`)¶

The new users.token_version column powers stateless, denylist-free revocation of JWT access tokens:

JwtController now mints the access-token payload as {uid, tv}, where tv is the user's current token_version. Legacy scalar payloads (a bare user id) are still accepted — the tv check is skipped for them.
The JWT authenticator's check() rejects a token whose embedded tv does not match the user's current token_version, returning lang('Auth.revokedToken').
User::revokeIssuedTokens() bumps token_version atomically, invalidating all outstanding access tokens for that user. It is called automatically by Bannable::ban() and Services\PasswordChangeRecorder::record() (on password reset/change). Call it directly for a "log out everywhere" action:

$user->revokeIssuedTokens(); // every previously-issued JWT access token now fails check()

JwtController routes refresh / logout / issue through service('jwtTokenRepository'): refresh is now one-time-use rotation, and logout soft-revokes the refresh token.

Other behaviour now enforced automatically (no action needed)¶

Remember-me expiry & theft detection — RememberMe::checkRememberMeToken() enforces expiry at validation time (an expired cookie can no longer authenticate). On theft detection (selector matches but validator does not) it purges all of the user's remember-me tokens, writes the login.suspicious audit event, and fires Events::trigger('remember-me-theft', $userId, $selector).
TOTP lockout & anti-replay — TOTP / backup-code verification now goes through the same per-user lockout as password login (UserLockoutManager), and a TOTP code is single-use within its acceptance window (a code at or below the last consumed time-step is rejected).
Device-session revocation actually invalidates the live session — when Auth::$sessionConfig['trackDeviceSessions'] is true, every authenticated request verifies the current PHP session maps to a non-terminated auth_device_sessions row (DeviceSessionModel::isSessionActive()). A remotely-revoked or concurrent-limit-evicted session is forced to re-authenticate. (Previously "revoke" only flipped a DB column and the cookie kept working.)

Optional — opt-in to new behaviour¶

Option	Default	Meaning
`AuthSecurity::$activeDateThrottle`	`60`	Minimum seconds between `users.last_active` writes on the authenticated hot path. `0` = write every request (legacy behaviour).
`AuthSecurity::$gateFallbackToRbac`	`true`	A Gate ability whose name contains a scope (e.g. `users.edit`) with no registered closure/policy falls back to `User::can()`. Set `false` to keep Gate and RBAC fully independent.
`AuthOAuth` provider option `'allowUnverifiedEmailLink'`	unset (`false`)	Per provider in `$providers`. When a social account's e-mail matches an existing local (password) account, auto-linking only happens if the provider asserts the e-mail is verified. Providers that cannot assert verification (Facebook, GitHub) refuse the merge unless this is `true`; refusal throws `AuthenticationException` with `lang('Auth.oauthEmailUnverified')`.

New explicit OAuth account-linking flow¶

A logged-in user can deliberately link an additional provider via:

Method	HTTP route	Route name	Controller
`GET`	`oauth/link/(:segment)`	`oauth-link`	`OauthController::link($provider)`

The route requires an authenticated user, stashes the current user (session key oauth_link_user_id), and the shared callback links the provider to the current user — no e-mail merge and no verified-email requirement, because the user is authenticated and acting deliberately. Linking a social account already bound to a different local user is refused with lang('Auth.oauthAlreadyLinked').

Filter argument changes¶

Filter	New argument form	Effect
`rates`	`rates:<limit>,<period>`	Overrides the global limit/time for that route. `<period>` is a number of seconds or a named unit: `SECOND`, `MINUTE`, `HOUR`, `DAY`, `WEEK`. A configured endpoint DB row still overrides. (The registered alias is `rates`.)
`password-confirm`	`password-confirm:<seconds>`	Requires a password confirmation no older than `<seconds>` for that route, regardless of the global `AuthSecurity::$passwordConfirmationLifetime` ("sudo mode" for the most sensitive routes).
`gate`	`gate:users.edit`	Honors the Gate → RBAC fallback (`$gateFallbackToRbac`), so `gate:users.edit` and `permission:users.edit` can share semantics.

Upgrading to the next release (`Unreleased`)¶

The Unreleased section in CHANGELOG.md adds 13 features and a handful of internal improvements. No breaking changes — all new behaviour is opt-in.

Required steps¶

Run migrations — six new migrations ship with this release:

Migration	Adds
`2026-05-07-000001_add_identities_user_type_revoked_index`	Composite index on `auth_identities(user_id, type, revoked_at)`
`2026-05-07-000002_create_audit_logs_table`	`auth_audit_logs`
`2026-05-07-000003_create_totp_backup_codes_table`	`auth_totp_backup_codes`
`2026-05-07-000004_add_trusted_until_to_device_sessions`	`auth_device_sessions.trusted_until`
`2026-05-07-000005_create_password_history_table`	`auth_password_history`
`2026-05-07-000006_add_password_changed_at_to_users`	`users.password_changed_at`

php spark migrate --all

Rename test helpers (deprecated, BC kept) — if your tests use the typo'd helpers, the corrected names are now available; the old ones still work as deprecated aliases.

Before (deprecated)	After
`$this->inkectMockAttributes(...)`	`$this->injectMockAttributes(...)`
`$this->inkectMockAttributesSecurity(...)`	`$this->injectMockAttributesSecurity(...)`
`$this->inkectMockAttributesOAuth(...)`	`$this->injectMockAttributesOAuth(...)`

The deprecated names will be removed in v6.

Optional — opt-in to new features¶

Each of these defaults to "off / unchanged" — adopt only what fits your security posture.

Feature	Where to enable	Reference
Throttle access-token `last_used_at` writes	`AuthSecurity::$tokenLastUsedThrottle = 60`	Authentication — Access Token
Concurrent session limit	`Auth::$maxConcurrentSessions = 5`	Device Sessions — Concurrent Limit
Trusted devices (2FA bypass)	`AuthSecurity::$trustedDeviceLifetime = 30 * DAY`	TOTP — Trust This Device
TOTP backup codes	(automatic on TOTP confirmation)	TOTP — Backup Codes
Compromised-password recheck on login	`AuthSecurity::$recheckPwnedOnLogin = true`	Audit & Compliance
Suspicious login alerts	`AuthSecurity::$suspiciousLoginAlerts = true` + listener	Audit & Compliance
Password history (no reuse)	`AuthSecurity::$passwordHistorySize = 5` + add `HistoryValidator`	Audit & Compliance
Password rotation policy	`AuthSecurity::$passwordMaxAge = 90 * DAY` + apply `password-age` filter	Audit & Compliance
API token scope enforcement	Apply `token-scope:` filter on routes	Filters — Token Scope
Login activity feed	Wire `UserSecurityController::loginActivity` route	Controllers — `loginActivity()`

What runs automatically (no action needed)¶

The audit log starts capturing events immediately for: TOTP enable/disable, password changes, lockouts, group/permission grants & revokes, token revocations, JWT logout. Use auth:audit to read.
OauthManager::handleCallback() now compares the OAuth state with hash_equals() (timing-safe) — drop-in replacement.
UserLockoutManager::recordFailedAttempt() now increments failed_login_count atomically — drop-in replacement.
DeviceSessionRecorder no longer propagates DB errors — they are logged and swallowed so a misconfigured tracking table can't break login.

Upgrading to v5.x¶

What changed¶

OauthManager now delegates all identity CRUD to a new OAuthTokenRepository.
ProfileResolverFactory::create() accepts an optional array $providerConfig second argument.
New OAuth events fire from OauthManager::handleCallback():
oauth-login — (User $user, string $providerName)
oauth-profile-fetched — (User $user, string $providerName, array $profileData)
extra JSON on OAuth identities now stores scopes_granted and profile_fetched_at alongside the existing refresh_token and profile.

What you must do¶

If your code…	Do this
Calls `model(UserIdentityModel::class)` to find an OAuth identity	Inject `OAuthTokenRepository` and use `findByUserAndProvider()` / `findByProviderAndSocialId()`
Listens for OAuth login via `auth-login` or similar custom event	Switch to the new `oauth-login` event (see `docs/07-logging.md`)
Uses `'oauth_' . $provider` string concatenation	Use `IdentityType::oauthProvider($name)`
Relied on the legacy plain-string format in the `extra` column	No action required — `parseExtra()` handles both legacy and JSON formats

No database migrations are required for the v4 → v5 transition. Existing extra columns continue to work unchanged.

Upgrading to v4.x — `Config\Auth` split¶

What changed¶

Config\Auth was split into three classes to keep concerns separate. Properties moved according to this table:

Property	Old class	New class
`$minimumPasswordLength`, `$passwordValidators`, `$maxSimilarity`	`Auth`	`AuthSecurity`
`$hashAlgorithm`, `$hashCost`, `$hashMemoryCost`, `$hashTimeCost`, `$hashThreads`	`Auth`	`AuthSecurity`
`$supportOldDangerousPassword`	`Auth`	`AuthSecurity`
`$recordLoginAttempt`, `$recordActiveDate`, `$enableLogs`	`Auth`	`AuthSecurity`
`$userMaxAttempts`, `$userLockoutTime`	`Auth`	`AuthSecurity`
`$enableInvalidAttempts`, `$maxAttempts`, `$timeBlocked`	`Auth`	`AuthSecurity`
`$limitMethod`, `$requestLimit`, `$timeLimit`	`Auth`	`AuthSecurity`
`$accessTokenEnabled`, `$unusedAccessTokenLifetime`, `$strictApiAndAuth`	`Auth`	`AuthSecurity`
`$allowMagicLinkLogins`, `$magicLinkLifetime`	`Auth`	`AuthSecurity`
`$passwordResetLifetime`, `$jwtRefreshLifetime`	`Auth`	`AuthSecurity`
`$totpIssuer`, `$permissionCacheEnabled`, `$permissionCacheTTL`	`Auth`	`AuthSecurity`
`RECORD_LOGIN_ATTEMPT_*` constants	`Auth`	`AuthSecurity`
`$providers`	`Auth`	`AuthOAuth`

Constructor signatures changed:

Passwords and BaseValidator accept AuthSecurity instead of Auth. Custom password validators extending BaseValidator must update their type hints.
OauthManager accepts AuthOAuth instead of Auth.

What you must do¶

Step 1. Create the two new config files in app/Config/:

// app/Config/AuthSecurity.php
namespace Config;

use Daycry\Auth\Config\AuthSecurity as AuthSecurityConfig;

class AuthSecurity extends AuthSecurityConfig
{
    // Move every customised security/lockout/password property here.
    public int $minimumPasswordLength = 10;
    public int $userMaxAttempts        = 5;
    // ...
}

// app/Config/AuthOAuth.php
namespace Config;

use Daycry\Auth\Config\AuthOAuth as AuthOAuthConfig;

class AuthOAuth extends AuthOAuthConfig
{
    public array $providers = [
        // Move your existing $providers array verbatim from app/Config/Auth.php.
    ];
}

Step 2. Remove the moved properties from app/Config/Auth.php. Anything not in the table above stays in Auth.

Step 3. Search-and-replace setting('Auth.X') → setting('AuthSecurity.X') (or setting('AuthOAuth.X')) for every property listed above. Common offenders:

Before	After
`setting('Auth.recordLoginAttempt')`	`setting('AuthSecurity.recordLoginAttempt')`
`setting('Auth.requestLimit')`	`setting('AuthSecurity.requestLimit')`
`setting('Auth.userMaxAttempts')`	`setting('AuthSecurity.userMaxAttempts')`
`setting('Auth.totpIssuer')`	`setting('AuthSecurity.totpIssuer')`
`setting('Auth.providers')`	`setting('AuthOAuth.providers')`

Step 4. Update custom password validators:

use Daycry\Auth\Authentication\Passwords\BaseValidator;
use Daycry\Auth\Config\AuthSecurity;

class MyValidator extends BaseValidator
{
    public function __construct(AuthSecurity $config)
    {
        parent::__construct($config);
    }
}

Step 5. Run the test suite — the type system will catch most missed renames.

General upgrade checklist¶

After any major version bump:

composer update daycry/auth
php spark migrate --all — applies any new migrations.
composer test — runs PHPUnit + code-style.
Review your app/Config/Auth.php, app/Config/AuthSecurity.php, app/Config/AuthOAuth.php against the published versions for any new options worth adopting (e.g. permissionCacheEnabled, tokenLastUsedThrottle).
Check CHANGELOG.md for any non-breaking deprecations to plan ahead of v6.

🔄 Migration Guide¶

📋 Index¶

Upgrading to this release — token-version revocation & hashed ephemeral tokens¶

Required steps¶

Behavioural changes you must know about¶

JWT access-token revocation (new token_version)¶

Other behaviour now enforced automatically (no action needed)¶

Optional — opt-in to new behaviour¶

New explicit OAuth account-linking flow¶

Filter argument changes¶

Upgrading to the next release (Unreleased)¶

Required steps¶

Optional — opt-in to new features¶

What runs automatically (no action needed)¶

Upgrading to v5.x¶

What changed¶

What you must do¶

Upgrading to v4.x — Config\Auth split¶

What changed¶

What you must do¶

General upgrade checklist¶

JWT access-token revocation (new `token_version`)¶

Upgrading to the next release (`Unreleased`)¶

Upgrading to v4.x — `Config\Auth` split¶