Download the PHP package bbs-lab/nova-password-rotation without Composer

Nova Password Rotation

Force any authenticatable model to rotate its password every N days. When the password expires, a Laravel Nova middleware redirects the logged-in user to a native, Nova-styled change-password screen. Light, secure, and works almost out of the box.

The rotatable subject is not tied to the User model: everything keys off the MustRotatePassword interface on whatever user Nova authenticated, and the password history is polymorphic, so any model works.

Screenshots

Each screenshot is split diagonally: light theme (top-left) / dark theme (bottom-right).

Forced password-change screen — shown when a password has expired:

Reset action (expiry_action: reset) — instead of the in-panel form, a single button that emails a reset link and signs the user out:

Expiry warning — a Nova notification while the password nears expiry:

Sign-in screen

Features

• 🔒 Forces a password change once the current one is older than days
• 🧭 Nova middleware redirect to a native-looking change screen, styled with Nova's own CSS
• 🧬 Interface-gated: only enforced when the authenticated user implements MustRotatePassword
• 🗂️ Polymorphic password history — any authenticatable model is supported
• 🚫 Reuse prevention: rejects the last N hashed passwords, and forbids reusing the current one
• 👋 First-login enforcement: admin-provisioned accounts must set their own password
• ⏰ Expiry warning: a Nova notification a few days before expiry (once per day, best-effort)
• 📊 password-rotation:report Artisan command to audit account status
• 📣 A PasswordRotated event you can listen to
• 🌍 English & French translations, publishable
• 🧪 100% line coverage, PHPStan level 8, no final classes, strict types everywhere

Requirements

• PHP ^8.2
• Laravel Nova ^4.0 || ^5.0
• Laravel ^11.0 || ^12.0 || ^13.0

Both Nova majors are exercised in CI. Note that Nova 4 (through its inertiajs/inertia-laravel dependency) tops out at PHP 8.4 and Laravel 11; on PHP 8.5 or Laravel 12+, use Nova 5. Composer resolves the right combination for you.

Installation

Because Nova is a paid, private package, make sure your application is already authenticated against nova.laravel.com, then:

The service provider auto-registers via Laravel package discovery. It builds on bbs-lab/laravel-password-rotation, which owns the generic rotation domain (the interface, trait, history model, rule, event and report command); Composer pulls it in automatically and its password_histories migration runs on install. Publish what you want to tweak:

The published users migration adds the nullable rotation column (password_changed_at by default) and backfills existing rows to now() so no one is locked out on deploy. Edit the stub to target the correct table if your rotatable model is not users.

Quick start

Add the interface and trait to the authenticatable model you want to rotate:

The trait implements the whole interface, casts the rotation column to a datetime, stamps it on every password change, records history, and fires PasswordRotated. On create it stamps the column too — unless force_on_first_login is on (the default), in which case the column is left null so the account is forced to set its own password on first login. Run the published migration and you are done — expired users are redirected on their next full page load in Nova.

Configuration

The generic rotation keys live in the base package's config/laravel-password-rotation.php; the Nova-specific keys live in this package's config/nova-password-rotation.php. Each is driven by an environment variable.

Shared rotation keys (config/laravel-password-rotation.php, from bbs-lab/laravel-password-rotation):

Nova-specific keys (config/nova-password-rotation.php, this package):

The models array only feeds the report command. The middleware works off the interface on the authenticated user, so any model is enforced regardless of this list.

Usage

The forced-change flow

On every Nova page load, EnsurePasswordIsNotExpired checks the authenticated user. If it implements MustRotatePassword and its password has expired, the user is redirected to the change screen. Nova 5's auth pages are Vue/Inertia rather than Blade, so the screen is a self-contained Blade page styled with Nova's own CSS (loaded when Nova's assets are published) — it looks native without a JS build. On a successful update the user is sent back to the Nova dashboard with a success flash.

Because the middleware runs on Nova's web stack only, a mid-session expiry takes effect on the next full page load — which is acceptable and avoids breaking XHR requests.

With expiry_action set to reset, the screen shows a single Send password reset link button instead of the change form. Submitting it emails a standard Laravel password reset link (default broker), signs the user out of the Nova guard (so the emailed guest link is reachable) and redirects to the Nova login. Nova's login is a Vue SPA, so the "reset link sent" confirmation cannot be shown as a Nova toast — the email is the real signal.

Reuse prevention

When history_count > 0, every password change is hashed and stored in the polymorphic password_histories table (only the newest N rows are kept per user). The change screen rejects any of those previous passwords, and always rejects reusing the current one. You can reuse the rule directly:

First login

With force_on_first_login enabled (the default), a null rotation column counts as expired. Admin-provisioned accounts are therefore forced to set their own password before using Nova. The published migration backfills existing rows so current users are not caught out.

Expiry warning

When warn_days > 0, a still-valid user whose password is within the warning window receives a Nova warning notification, at most once per day. It is best-effort: if the nova_notifications table is not installed, it is silently skipped and Nova keeps working.

The password-rotation:report command

Audit the accounts declared in config('laravel-password-rotation.models'):

It renders a table of identifier, last-changed, expires-at and status (expired / expiring soon / ok). Classes that do not exist or do not implement MustRotatePassword are skipped.

The PasswordRotated event

Dispatched after a password change is persisted (not on the initial create). Listen for it to log, notify, or revoke sessions:

Automatic middleware registration

By default the package wires EnsurePasswordIsNotExpired into Nova for you. It does so two ways so it works on both Nova majors and even when config/nova.php has not been published: it appends the middleware to config('nova.middleware') (Nova 4 reads this inline, Nova 5 builds its nova router group from it), and — once the app has booted — it also pushes the middleware onto Nova 5's nova router group. Both are gated by enabled and auto_register_middleware, and neither ever registers the middleware twice.

Manual middleware registration

If you set auto_register_middleware to false, add the middleware to Nova's stack yourself in config/nova.php — it works on both Nova 4 and Nova 5:

Testing

A full embedded Nova app (via Orchestra Workbench) lets you exercise the flow in a real Nova instance:

Security

Passwords are stored only as hashes — the history table keeps a copy of the already-hashed value, never plaintext. Reuse checks run through Hash::check. Hash::make is idempotent against a hashed cast, so passwords stay single-hashed. If you discover a security issue, please email [email protected] instead of using the issue tracker.

Filament

Using Filament instead of Nova? Its twin, bbs-lab/filament-password-rotation, brings the same password rotation to Filament panels.

Changelog

Please see CHANGELOG for what has changed recently. Upgrading from v1.x? See UPGRADE.md.

Contributing

Please see CONTRIBUTING for details.

Credits

• Big Boss Studio

License

The MIT License (MIT). Please see License File for more information.