Auth Laravel Package

Technical Evaluation

Architecture fit. saucebase/auth is a drop-in auth module for the Saucebase modular Laravel starter, not a standalone package. It spans a full vertical slice: controllers, models (SocialAccount, MagicLinkToken), a SocialiteService, form requests with rate limiting and password hashing, domain exceptions, event listeners, notifications, middleware, a Sociable trait for User, Filament admin resources, and Inertia/Vue-or-React pages (Login, Register, MagicLink, SettingsProfile, SettingsSecurity). It assumes a host app that already provides: Saucebase core (settings modal shell, Home::url, Auth::SettingsProfile conventions, navigation registerIcon/registerAction helpers), Filament v3+ with stechstudio/filament-impersonate, Laravel Socialite, and either @saucebase/vue or @saucebase/react. The design is coherent and opinionated — settings are auto-discovered from src/Settings, defaults are seeded, routes deliberately preserve settings.* names for core route resolution — but the coupling means it is a "module for Saucebase," not a portable auth kit.

Integration feasibility. Straightforward inside a Saucebase app (composer install + module registration + env vars + php artisan auth:make-admin). Outside that context, integration is effectively a rewrite of the host's auth surface: you would need to reproduce the settings modal, the core navigation contract, the Inertia page-shell conventions, and the Filament panel contract. The frontend is dual-flavored (Vue and React entry points) which widens fit but also means the maintainers carry two rendering paths.

Technical risk.

• Maturity signal: 2 stars, 0 dependents, no ecosystem usage — unproven in production outside its own starter. The listed last release (2026-10-25) is a future-dated timestamp; treat version/compatibility metadata as unverified until checked against Packagist.
• Documentation orientation: docs are agents/AGENTS.md and skills/saucebase-auth-development/SKILL.md, i.e. written for AI coding agents, not human operators. Excellent for assisted development, weak as an operational runbook.
• Known functional gaps disclosed by the docs: User does not implement MustVerifyEmail, so the verified middleware is a pass-through and email-verification routes are not enforced; password changes do not terminate other sessions pending AuthenticateSession in the web group (tracked as sc-714). Both are security-relevant.
• Flow complexity: Socialite dual-flow (guest login vs authenticated linking), magic-link single-use atomic consumption, modal-mode branching keyed on Modal::HEADER_MODAL / base-URL headers, and impersonation session history. Each is well-reasoned but adds regression surface, especially the modal header logic which is sensitive to header stripping by proxies/CDNs.
• Positive controls: hashed magic-link storage (only plain token in email), atomic UPDATE-based consumption, rate limiting (5/email+ip on login, 6/1 on reset/verification, 5/1 on magic link), disconnect guard preventing sole-login-method removal, account-takeover guard on linking an already-owned social ID, admin protections via Gate::before and UserPolicy, and permission separation between manage users and impersonate users.

Key questions.

1. Which frontend does the target app use — Vue or React — and is the corresponding @saucebase/* package versioned compatibly?
2. Is Saucebase core a hard requirement, and what is the minimum core version for Home::url, settings discovery, and navigation registration?
3. What is the real release history behind the 2026-10-25 date, and is there a tagged, stable Composer constraint?
4. Who is the maintainer of record, and what is the disclosure process for security issues?
5. When will MustVerifyEmail be enabled, and is sc-714 (session invalidation on password change) on a committed roadmap?
6. Are OAuth redirect URIs, cookie domain, and session config compatible with the target deployment topology (load balancer, multiple app nodes)?

Integration Approach

Stack fit. Best fit is greenfield or near-greenfield on the Saucebase starter: Laravel + Inertia + Filament + Socialite, with the module's own Inertia/Vue or Inertia/React frontend. Poor fit for an existing Laravel app with a bespoke auth implementation, blade views, or a non-Inertia SPA — the cost of retrofitting the settings modal shell, navigation registration, and Filament dependency will likely exceed the value.

Migration path.

• Greenfield: install as a module, run migrations, run DatabaseSeeder (grants manage users and impersonate users to nobody — assign deliberately), publish settings defaults, configure GOOGLE_* / GITHUB_* env and redirect URIs, seed an admin via php artisan auth:make-admin {email}, then toggle registration_enabled, magic_link_enabled, login_notification_enabled, and enabled_socialite_providers from AuthenticationSettings.
• Brownfield: treat as a reference implementation. Port the pieces with the highest independent value — hashed single-use magic-link tokens, rate-limited LoginRequest, disconnect validation, admin-safety policy rules — rather than adopting the module wholesale. Reimplementing the Inertia pages and Filament resources against an existing UI kit is a multi-week effort.
• Coexistence: the module owns /auth/* and /settings/*. If the host already has those routes, resolve collisions before install; the settings.* route names are load-bearing for core and PasswordChangedNotification.

Compatibility. Watch for: Laravel version support, Filament v3 vs v4, stechstudio/filament-impersonate version, @saucebase/vue/@saucebase/react peer versions, and Socialite provider config. The verified middleware being a pass-through today means any host relying on it must add enforcement independently.

Sequencing.

1. Confirm core + module versions and lock Composer constraints.
2. Provision core (settings modal, navigation helpers, Home::url) before enabling the module.
3. Migrate and seed; assign manage users / impersonate users to named roles only.
4. Configure OAuth env and redirect URIs per environment; verify provider-enabled middleware returns 404 cleanly when a provider is off.
5. Wire the frontend app entry (icons, actions, global components) and confirm both canonical pages and ModalLink navbar entries behave.
6. Turn on registration and magic link last, behind AuthSettings, after a smoke test of login/reset/verify/magic/impersonate.
7. Before go-live, decide the MustVerifyEmail and session-invalidation posture explicitly; do not assume defaults are production-grade.

Operational Impact

Maintenance. MIT license is permissive and low-friction. The real risk is a small maintainer surface (2 stars, 0 dependents, no visible issue velocity) plus agent-oriented documentation. Plan for the team to own the module's behavior after adoption, including local forks for the two known gaps. Budget ongoing effort for Filament/Inertia major-version bumps, which will ripple through pages, resources, and route middleware.

Support. No third-party dependents means no community answer base; Slack/issue response depends entirely on the Saucebase maintainers. Internal documentation should be written at adoption time — the SKILL.md is a good agent primer but not an on-call guide. For security-sensitive failures (OAuth callback errors, lockouts, magic-link delivery), expect to self-diagnose from the exception classes (AuthException, SocialiteException) and Laravel logs.

Scaling. Auth volume is low relative to application traffic, and the hot paths are well-behaved: hashed token lookup with atomic single-use UPDATE, per-email+ip rate limiting, no unbounded growth in MagicLinkToken beyond one live token per user. Filament user management and impersonation are admin-path operations with bounded session state (recent history capped at 4 IDs). Real scaling constraints are elsewhere: email deliverability for magic links and verification, OAuth callback latency, and the shared session store if password-change invalidation is later enabled.

Failure modes.

• OAuth: provider enabled in settings but env missing → callback error; disabled provider → silent 404 via EnsureSocialiteProviderEnabled. Misconfigured redirect URIs (default /auth/socialite/callback) are the most common break.
• Magic link: email delivery failure blocks login entirely for passwordless users; expired tokens (15-minute default) produce dead links; the flow intentionally does not error on unknown emails, which is good for enumeration resistance but confusing for support tickets.
• Email verification: not enforced today — users can operate with unverified addresses; enabling verified later without MustVerifyEmail on User is a no-op, and enabling both without a UX pass will lock out existing sessions.
• Password change: other devices stay signed in (sc-714) — a security incident response gap.
• Modal mode: if an upstream proxy strips custom headers, the modal falls back to full-page or, worse, renders over the referer. Test through the real edge.
• Impersonation: history entries pointing to deleted users are filtered, but re-impersonation relies on can('impersonate', $target); any custom gate changes must preserve the admin pass-through invariant.
• Admin lockout: no path to delete the last admin and no path for staff to reach an admin record — protective, but also means recovery requires shell access.

Ramp-up. For a developer already fluent in Laravel, Inertia, and Filament, expect roughly 1–2 weeks to be productive and 3–4 weeks to be confident across the socialite/magic-link/modal/impersonation edges. For a team new to the Saucebase stack, double it — the module's breadth (12+ controllers, 8 listeners/notifications, dual frontend, admin plugin) means there is no small surface to learn incrementally. Use the agent skills as scaffolding for AI-assisted work, but pair it with a human-authored runbook covering OAuth setup, admin bootstrap, and the two known security gaps before any production rollout.