Search by

boneybone / laravel-session-guard

tohawk89

Stops users losing their work to "419 Page Expired": warns before the session times out, replaces the 419 page with a sign-in-again notice, and detects blocked or duplicate cookies and wrong clocks.

Package info

gitlab.com/nazarsyafiq89/bb-laravel-session-guard

Issues

pkg:composer/boneybone/laravel-session-guard

Statistics

Installs: 4

Dependents: 0

Suggesters: 0

Stars: 0

v1.0.1 2026-11-19 12:36 UTC

This package is auto-updated.

Last update: 2026-11-19 04:44:27 UTC


README

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-TOKEN can'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-report and 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:

CauseWhat the user sees without the guardWhat the guard does
The tab sat idle longer than SESSION_LIFETIME419 on submit, input lostWarns 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 recentlyIssues the token under an app-specific cookie too and uses that one (below)
Privacy extension or blocked cookiesSigned out on every click, every submit is a 419Tells them to allow cookies for the site
Computer clock hours aheadSame as above: the browser treats every cookie as already expiredTells 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 419sTells 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-Duplicates when 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 wraps fetch/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 through localStorage, so a background tab doesn't warn while the user works in another;
  • turns 419s into the expired notice: it cancels Inertia's invalid modal and Livewire's "page expired" confirm, watches fetch/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.

License

MIT. See LICENSE.