Scoped Auth Laravel Package

Technical Evaluation

Architecture fit. mpyw/scoped-auth targets a specific Laravel auth gap: applying scope/ownership constraints to authentication and authorization resolution so that a single user model (or guard) can be resolved differently per context (e.g., tenant, role domain, or guard scope). For applications already leaning on Laravel's native gate/policy and guard system, this is a thin, additive layer rather than a framework fork — which is the right shape for a TPM to sponsor. It fits best where multi-tenant or multi-context auth is a first-class domain concern and where the team wants to avoid hand-rolling scope logic into every policy.

Integration feasibility. The package is small in surface area and installable via Composer with no runtime services, no external infrastructure, and no data-store assumptions beyond what Laravel already provides. The v2.1.1 release is a patch: CI coverage for PHP 8.5, a documentation correction for Fortify, and declared support for Laravel 14. There are no migrations, no config-breaking changes, and no deprecations in this release. Integration effort is therefore dominated by our auth model complexity, not by the package.

Technical risk. Three risks are worth naming:

1. Forward-version coupling. Laravel 14 support landing in a patch release means the package tracks framework releases quickly, which is good for currency but means we may be an early adopter on a framework version with a short production track record. Treat "supports Laravel 14" as compatible, not battle-tested at our scale.
2. Fortify interaction. The Fortify note is a documentation fix tied to Fortify v1.33.0, not a code change. That implies the integration is real but lightly exercised in CI; Fortify flows (2FA, login pipelines, password reset) are exactly where scoped auth is most likely to misbehave, so this needs targeted verification rather than a changelog read.
3. Single-maintainer concentration. The release cadence is healthy, but the project is maintainer-led. Bus factor is a genuine operational risk for anything on the authentication path.

Key questions for the maintainer / our architects.

• What is the intended semantics when a user matches multiple scopes — first-match, explicit precedence, or exception?
• Which Fortify features are covered by tests versus only documented (2FA, email verification, remember-me, session invalidation)?
• Is Laravel 14 support validated against a stable Laravel 14 release or a pre-release/RC?
• What is the upgrade contract across major versions — is there a documented BC policy?
• Are there known interactions with Sanctum/Passport token guards and with Octane's long-lived workers?

Integration Approach

Stack fit. Assumes Laravel (11+), PHP 8.2+, Composer, and optionally Fortify. It slots into the authorization layer alongside policies and gates rather than replacing them, so it does not force a rewrite of existing AuthServiceProvider or middleware. Applications on a custom auth implementation will see less benefit; applications on stock guards with ad-hoc scope checks in controllers are the strongest fit.

Migration path. Brownfield adoption should be incremental: introduce the package, model one low-risk scope (e.g., read-only tenant isolation on a single resource), validate against existing policy behavior, then expand. There is no data migration — scope resolution is evaluated at request time — which keeps rollback cheap (remove the dependency and the scope bindings).

Compatibility. Laravel 14 and PHP 8.5 are declared; confirm the lower bounds your platform actually runs (Laravel 11/12/13, PHP 8.2–8.4) are still covered by the CI matrix rather than assumed. If we are on Fortify, pin Fortify ≥ 1.33.0 to align with the documented behavior. Pin the package to a minor range (^2.1) rather than floating, given the pace of Laravel-version additions.

Sequencing.

1. Week 1 — Feasibility spike (2–3 days). Install in a sandbox branch; replicate one real tenant-isolation rule; run the existing auth test suite against it.
2. Week 1–2 — Fortify verification. Explicit test pass over login, 2FA challenge, password reset, email verification, and logout/session invalidation under scoped resolution.
3. Week 2 — Decision gate. Go/no-go based on spike results plus answers to the multi-scope precedence question. If precedence semantics don't match our domain model, stop here — cheaper than adapting around it.
4. Week 3+ — Pilot. One bounded surface area in staging, feature-flagged, with an auth regression suite as the gate to production.
5. Post-pilot — Expand scope-by-scope, each with its own regression check.

Operational Impact

Maintenance. Low ongoing code maintenance: no schema, no background jobs, no config drift. The real maintenance obligation is version tracking — the package adds Laravel version support aggressively, so our dependency-update cadence must include re-running the auth regression suite whenever either the package or Laravel bumps. Budget roughly a half-day per framework minor upgrade for auth regression, not zero.

Support. Support path is upstream GitHub issues from a single primary maintainer. For anything on the authentication path, that is insufficient as a sole escalation route. Mitigation: designate an internal owner (one backend engineer) who can read the package internals and, if needed, vendor a fork. This is a small package; the fork option is credible and should be treated as a live contingency, not a theoretical one.

Scaling. Scope resolution is per-request and in-process, so there is no new network hop or datastore. The scaling concern is query shape: scoped resolution that translates into additional constraints or joins can multiply query count on hot auth paths (every request authenticates). Under Octane, verify no per-request state is retained across workers. Load-test the authenticated path specifically — auth is the one code path every single request traverses, so a 5 ms regression is a fleet-wide 5 ms.

Failure modes.

• Silent over-permission — a scope that fails open returns broader access than intended. Highest-severity failure; must be covered by explicit negative tests (assert cross-tenant access denied), not just positive tests.
• Silent under-permission / lockout — a scope misconfiguration locks users out of legitimate resources, including admin recovery paths. Requires a documented break-glass procedure that does not depend on the scoped layer.
• Guard interaction regressions — Sanctum/Passport token guards and Fortify pipelines resolving scopes differently than session guards.
• Framework upgrade breakage — Laravel minor bump changing guard internals; surfaces as auth failures at deploy time unless the regression suite runs pre-merge.
• Maintainer abandonment — no upstream fix available; fork required under time pressure.

Ramp-up. Small: an engineer familiar with Laravel guards and policies needs roughly half a day of reading plus the spike to be productive. The non-obvious part is scope precedence semantics, which should be written down internally as a short ADR after the spike so that later contributors don't reverse-engineer intent from behavior. Documentation is community-grade (README plus Fortify notes), so internal documentation is a real deliverable, not overhead.

TPM recommendation. Proceed to a time-boxed feasibility spike (≈3 engineer-days) with a hard go/no-go gate contingent on Fortify verification and a satisfactory answer on multi-scope precedence. Do not adopt broadly before an internal owner is named and the auth regression suite exists. The v2.1.1 release itself carries no migration cost and is a positive maintenance signal — the decision rests on domain fit and single-maintainer risk, not on this changelog.