Filament Lockscreen Laravel Package

Technical Evaluation

Architecture fit. marjose123/filament-lockscreen is a Filament panel plugin, so it slots into the existing TALL-stack architecture (Laravel + Livewire + Alpine + Tailwind) without introducing a new runtime, queue, or datastore. The intended integration surface is a single ->plugin(LockscreenPlugin::make()) call in a PanelProvider, which is the lowest-friction extension point Filament offers. Functionally it is a thin UX layer over Laravel's session: a flag that gates panel routes behind an unlock screen requiring credential re-entry, without destroying the authenticated session. That is architecturally appropriate — it is a "presence" control, not an authentication control — but it is important that the business does not mistake it for one. v3.4.1 materially sharpens this picture: the release includes refactor: enhance session idle management and prevent premature locking (PR #105), which indicates the plugin now performs server-side idle tracking and auto-lock, not just a user-initiated flag. That moves it closer to — but still not equivalent to — an idle-timeout control, and raises the compliance misread risk rather than lowering it.

Integration feasibility. High for a single-panel Filament app on a supported version. The real feasibility question is version compatibility: Filament's plugin contracts and asset pipeline changed between v3 and v4, and a package with 62 stars and 0 dependents has a narrow tested matrix. Before committing, confirm the composer.json constraint against our pinned Filament major, confirm the package is registered per-panel (not global), and confirm whether it needs vendor:publish for config/assets — unpublished Filament assets after a deploy are a classic silent-failure mode. v3.4.1 does not resolve the Filament-major question: the only CI changes are Dependabot bumps to GitHub Actions workflows (fetch-metadata 2.5.0→3.1.0, checkout 6→7), which demonstrate the repo is actively maintained but say nothing about a Laravel × Filament × PHP test matrix.

Technical risk. The dominant risk remains adoption, not technology: one maintainer, near-zero dependent count, no downstream production signal. v3.4.1 is mildly reassuring (a substantive, self-authored fix landed rather than the repo going quiet) but also introduces a new, specific risk: a behavioral change to idle/lock timing shipped as a patch release. The commit message explicitly acknowledges "premature locking" as a defect class, meaning users on ≤v3.4 were being locked out earlier than intended. Secondary risks are security-shaped:

Key questions for the maintainer / spike.

• Is enforcement server-side middleware, and where does it sit relative to Authenticate and the panel's authMiddleware? (unanswered by v3.4.1)
• Supported Filament major(s) and Laravel major(s), and is there a CI matrix proving it? (v3.4.1 touched only workflow actions; still unanswered)
• What exactly changed in PR #105 — is idle auto-lock new, configurable, and opt-in or default-on? What is the default timeout, and is it a breaking behavior change for existing installs?
• Is "premature locking" fixed by a timing correction, a clock/skew guard, or a client-heartbeat change? Is there a regression test for it?
• Does auto-lock survive page reloads, SPA navigation, and Livewire polling requests (which could reset the idle timer or keep it from firing)?
• Behaviour under ->spa(), multi-panel, impersonation (->impersonate()), and "remember me" sessions? (impersonation × the new idle logic is the highest-risk untested combination)
• Does unlocking require the current password, and is that attempt rate-limited?
• Is lock state session-only, or does it write to the database on each request? Did v3.4.1 add any schema change?
• i18n coverage for the unlock UI, and theming/override hooks for our design system?
• Release cadence and issue responsiveness over the last 12 months — and specifically, is the maintainer shipping behavior changes in patch slots by policy or by accident?

Integration Approach

Stack fit. Native. No new services, no new dependencies beyond the package itself, no schema changes anticipated (verify — if it persists lock state or last-activity timestamps to a table, we inherit a migration and a per-request write). It composes with Filament's existing navigation/user-menu render hooks, so the "Lock" affordance lands where users already expect account actions. Works alongside our existing auth stack; it does not replace laravel/fortify, Sanctum, or Filament's own login flow.

Migration path. Additive and reversible:

1. composer require marjose123/filament-lockscreen pinned to an exact patch version ("3.4.1", not ^3.4 and not 3.4.*). v3.4.1 is the evidence for this: a user-facing idle-behavior refactor shipped in a patch slot, so a floating constraint can change lock timing without a deliberate decision on our side.
2. Register the plugin in the target PanelProvider only — start with an internal/admin panel, not a customer-facing one.
3. Publish config and assets; add the publish step to the deploy pipeline so assets cannot go stale. Explicitly set the idle timeout in config rather than inheriting the default.
4. Feature-flag the plugin registration behind an env toggle so rollback is a config change, not a revert-and-deploy.
5. Write a thin internal adapter (a small service provider or trait) around the plugin registration so a future fork or replacement touches one file.

Compatibility. Gate on a concrete matrix: Laravel major × Filament major × PHP version × session driver. Explicitly test the session drivers we actually run (Redis/database vs. file) and the cache driver, since lock and idle state almost certainly ride on the session. Add clock/timezone and long-lived-session cases — idle logic is timestamp arithmetic, and a refactor to fix "premature locking" is exactly where timezone and stale-timestamp bugs hide. If we run Filament in SPA mode, use multiple panels sharing a guard, or have components with wire:poll, those are the configurations most likely to expose defects and should be in the spike scope.

Sequencing.

• Week 1 — spike in a branch on 3.4.1 specifically: install, register, verify server-side enforcement, read the PR #105 diff and the surrounding idle code (it is small enough to audit fully), and confirm whether auto-lock is default-on.
• Week 2 — harden: add or confirm unlock throttling, set the idle timeout to match our internal policy explicitly, and write feature tests for "locked user cannot reach panel routes," "unlock with wrong password is rejected and rate-limited," and "lock does not fire before the configured idle threshold, and does fire after it." Add one browser test for the happy path.
• Week 3 — pilot on the internal admin panel with a small user group; collect feedback on the lock/unlock friction and on false-positive auto-locks, which is the defect class v3.4.1 just addressed.
• Week 4 — document for support (what the screen means, how to recover a locked-out user, how to adjust the timeout) before wider rollout.

Do not sequence this as a security deliverable. Ship it as UX; keep idle timeout and step-up auth on their own track — even now that the package has an idle mechanism of its own.

Operational Impact

Maintenance. Low steady-state effort but non-zero, and v3.4.1 raises the ownership bar slightly. Two facts matter: the package must be bumped in lockstep with Filament majors, and its versioning is not a reliable signal for behavioral change. Budget for a maintained internal fork from day one — MIT license makes this trivial — and treat upstream as a source of patches rather than a dependency we passively consume. Add a calendar reminder to review the repo's activity each quarter; an unmaintained Filament plugin becomes a blocker at the next major upgrade. The recent Dependabot activity on CI workflows is a weak positive maintenance signal (someone is watching the repo), but it is about Actions versions, not the runtime dependency graph or a supported-version matrix.

Support. No vendor, no SLA — GitHub issues only. Tier-1 support needs a short runbook: what the lock screen is, why a user sees it, how they unlock, what to do if the unlock form fails (clear session, re-login), and — new — how to adjust or disable the idle timeout, since an auto-lock that fires too eagerly will generate tickets that read like a bug report about lost work. The runbook plus a documented timeout default is the difference between a two-minute resolution and an escalation.

Scaling. Effectively free. Lock and idle state live in the session, so there is no additional query per request, no new table growth, and no cross-region concern — it scales exactly as the existing panel does. The scaling caveat is unchanged and now more acute given idle tracking: on multi-instance deployments with a shared session store, confirm lock and last-activity state are genuinely in the session and not in per-instance memory or cache, or users will bounce between locked and unlocked — and see inconsistent idle timers — as load balancing shifts them between nodes.

Failure modes to instrument and rehearse.

• Premature locking — the exact defect v3.4.1 set out to fix; treat it as a known, recently-patched class rather than a closed issue, and alert on unexpected lock-screen view volume after any upgrade.
• Idle timer never firing — the inverse regression: background Livewire wire:poll traffic can keep a session warm and defeat the intent of an idle lock. Verify interaction with polling components explicitly.
• Lock loop — unlock form errors leave the user unable to proceed and unable to reach the logout route; ensure a recovery path exists.
• Stale assets after deploy — the unlock UI renders unstyled or non-functional; enforce asset publishing in CI.
• Multi-tab desync — locking in one tab and continuing in another; verify server-side enforcement makes this moot.
• Impersonation — an admin impersonating a user may inherit or trip lock/idle state in confusing ways, especially with the new idle logic; test and document.
• Clock skew / timezone — timestamp-based idle detection mis-fires across DST or between app and session-store clocks.
• Cookie/session driver edge cases — the cookie session driver has a size ceiling; confirm the lock payload plus any added idle metadata fits.

Ramp-up. Developer ramp-up is under a day for anyone fluent in Filament plugins — the codebase is small and the integration is one line — but v3.4.1 adds roughly half a day of diff-reading and idle-timing test-writing before we can trust the auto-lock behavior. User ramp-up is negligible if the lock is manual and moderate now that idle auto-lock is in play, since it introduces a real interruption to admin workflows; pilot and expect tuning of the timeout. The organizational ramp-up cost is documentation: one internal page explaining what this control is and is not, what timeout we have configured and why, what the real idle-timeout control is, and who to contact when the unlock screen misbehaves.