laravel-session-guard maintained by boneybone
boneybone/laravel-session-guard
Stops users losing their work to "419 Page Expired". Install it and every page for logged-in users gets a small guard that:
-
warns before the session idles out ("Your session expires in 4:59" with a Stay signed in button);
-
renews the session while the user is typing or clicking, so a long form never times out under them;
-
replaces the 419 page with a notice ("Don't refresh — anything you've typed is still here") when the session has expired anyway. The user signs in again in a new tab, comes back, and submits again. The original tab notices the new sign-in by itself;
-
sends the app's own CSRF token, so another app's domain-wide
XSRF-TOKENcan't cause random 419s (see below); -
tells the user what's wrong with their browser when cookies are blocked (privacy extension, blocked site), sent twice, or the computer's clock is off so far that cookies expire as soon as they're set.
-
Works on Laravel 9–13 with Inertia (React/Vue), Livewire 2–4, Blade forms and plain
fetch/XHR. There's nothing to change in your frontend code. -
Plain JS with its own styles inside a Shadow DOM. There's no build step, so your Tailwind/Bootstrap can't break it and it can't affect your styles.
-
Sits alongside
boneybone/laravel-bug-reportand keeps its notices clear of the bug-report button.
Install
composer require boneybone/laravel-session-guard:^1.0
That's it. The guard appears for logged-in users on every HTML page served through the web middleware group. There are no migrations and no assets to publish.
Optional:
php artisan vendor:publish --tag=session-guard-config
SESSION_GUARD_ENABLED=true
SESSION_GUARD_LOGIN_URL=/ # opened in a new tab by "Sign in (new tab)"
SESSION_GUARD_XSRF_COOKIE=my-app-xsrf # defaults to "<APP_NAME slug>-xsrf"; empty to turn off
SESSION_GUARD_THEME=auto # auto | system | light | dark
To place the script yourself instead of auto-injecting it, set auto_inject to false and put @sessionGuard in your layout's <head>.
Why random 419s happen
A 419 means the CSRF token the browser sent doesn't match the session. The usual causes, and what the guard does about each:
| Cause | What the user sees without the guard | What the guard does |
|---|---|---|
The tab sat idle longer than SESSION_LIFETIME |
419 on submit, input lost | Warns 5 minutes before, renews while they're active, keeps the page when it does expire |
Another app on the same parent domain sets XSRF-TOKEN for the whole domain (SESSION_DOMAIN=.example.com) |
Random 419s whenever the other app was used recently | Issues the token under an app-specific cookie too and uses that one (below) |
| Privacy extension or blocked cookies | Signed out on every click, every submit is a 419 | Tells them to allow cookies for the site |
| Computer clock hours ahead | Same as above: the browser treats every cookie as already expired | Tells them how far off the clock is and to fix it |
| The same cookie stored twice (host-only + domain, old path) | Random sign-outs and 419s | Tells them to clear the site's cookies |
The shared-domain XSRF-TOKEN problem
Every Laravel app names its CSRF cookie XSRF-TOKEN. If one app on *.example.com uses SESSION_DOMAIN=.example.com, its XSRF-TOKEN is sent to every other *.example.com app too. The browser then holds two cookies with the same name, and axios/Inertia read whichever comes first. If that's the other app's, the token can't be decrypted with this app's key and the request fails with 419. It goes away when the other app's cookie expires, so it looks random.
The guard adds a second cookie named <APP_NAME slug>-xsrf holding the same token, and puts it in the X-XSRF-TOKEN header of every same-origin POST/PUT/PATCH/DELETE made with fetch or XHR (which covers axios, Inertia and Livewire). Laravel's CSRF check accepts it unchanged. XSRF-TOKEN is still set for anything else that reads it.
If your own code builds the header itself, it keeps working: the guard swaps in the right token. To read it directly, use window.SessionGuard.xsrfToken().
How it works
On the server, a middleware appended to the web group:
- stamps each response that went through the session with
X-Session-Guard: <server time in ms>, which tells the script the session was just renewed and how far the computer's clock is off; - adds
X-Session-Guard-Duplicateswhen the browser sent the session or CSRF cookie more than once (the session cookie is HttpOnly, so only the server can see this); - adds the app-specific CSRF cookie;
- injects the script into HTML pages for logged-in users, right after
<head>so it wrapsfetch/XHR before your scripts run.
GET /session-guard/ping (behind web + auth) answers 200 while the session is alive and 401 once it's gone. The script calls it when the user clicks Stay signed in or I've signed in, when the countdown runs out (30 seconds after, so a session that really idled out is never renewed by the check), and when the user types after 10 quiet minutes.
In the browser, the script:
- counts the session down from
SESSION_LIFETIME, restarting on every stamped response. Tabs share it throughlocalStorage, so a background tab doesn't warn while the user works in another; - turns 419s into the expired notice: it cancels Inertia's
invalidmodal and Livewire's "page expired" confirm, watchesfetch/XHR, and holds native form posts while expired (so the browser doesn't navigate to the 419 page); - checks after each response that the CSRF cookie is still there exactly once.
window.SessionGuard.state() returns the current status for debugging.
Testing
composer install
vendor/bin/pest
GitLab CI runs the suite on Laravel 9–13.