Laravel Janitor Laravel Package

Technical Evaluation

Architecture fit. The package implements a Backend-for-Frontend (BFF) login proxy: the SPA posts credentials to your Laravel app, which exchanges them with an OAuth2 authorization server (typically Laravel Passport) and returns tokens as HttpOnly cookies. That is a sound, well-understood pattern — it keeps access and refresh tokens out of JavaScript, which is the main reason teams reach for it. Fit is binary and must be settled before any code is written:

• Fits: separate-origin SPA + Laravel API + a centralized Passport-style token issuer, where you want cookie-based sessions in the browser but bearer tokens server-side.
• Does not fit: Laravel Sanctum first-party SPA auth (redundant — Sanctum already does cookie sessions), a third-party IdP using Authorization Code + PKCE (wrong grant), native/mobile clients, or machine-to-machine callers.

If the topology is right, the package is genuinely useful; if it is wrong, no amount of integration work rescues it.

Integration feasibility. Code volume is small — a service provider, config, a login/refresh/logout controller pair, and cookie-aware middleware. composer require, publish config, mount routes, point at the token endpoint. The real effort is not code but the identity contract: token endpoint URL, grant type, client ID/secret, scopes, cookie domain and SameSite policy, and the SPA's fetch configuration (credentials: 'include', CSRF header handling). Budget 2–5 engineer-days for an end-to-end spike, most of it spent on cross-origin cookie and CORS debugging, which is where these integrations reliably burn time.

Technical risk. Three concerns, in order:

1. Archived, security-sensitive path. Last release 2023-08-03 and no maintainer. Authentication code with no upstream patching is an accepted-liability decision, not a neutral one.
2. Framework drift. Composer constraints almost certainly stop before current Laravel/PHP majors, and Passport has been steering the ecosystem away from the password grant that a proxy like this typically consumes. Expect constraint resolution to fail against a modern stack.
3. Low scrutiny. 60 stars and a single maintainer means subtle cookie, CSRF, refresh-rotation, or token-revocation defects are unlikely to have been found and fixed.

The mitigating factor is that the surface area is small enough to own. Recommendation: treat this as source code to adopt, not a dependency to consume — vendor or fork it under your namespace and add contract tests, or reimplement the ~200–400 LOC yourself if the constraints don't resolve. Do not ship it as an unmodified third-party dependency on a security boundary.

Key questions to resolve before committing:

• Which authorization server and grant type — Passport password grant, or an OIDC provider?
• Exact Laravel/PHP/Passport versions in target services, and do the package's constraints resolve?
• Does the package handle refresh-token rotation, revocation on logout, and token expiry propagation, or only the happy path?
• Is there any login throttling/brute-force protection, or does that fall to us?
• How are cookies scoped (domain, Secure, HttpOnly, SameSite), and does that survive a multi-subdomain or cross-site SPA deployment?
• Are there tests and CI in the repo, and what is our tolerance for auth code without coverage?
• What is the exit cost if the identity provider changes in 18 months?

Integration Approach

Stack fit. Assume a Laravel 8/9/10-era codebase. Verify composer.json constraints against your actual matrix before estimating anything; a failed resolve turns this from a half-day install into a fork-and-patch exercise, which changes the plan but not the conclusion.

Migration path. Two viable routes, decided by the constraint check:

• Fork and own (preferred). Import into a private package repository (Private Packagist or Satis) or inline into app/Support/. Pin the fork, add dependency automation, and treat it as first-party code. Lowest risk, fastest path, and the fork is small enough to fully review.
• Reimplement. If constraints don't resolve or the security review finds gaps in refresh/revocation/throttling, rewrite the proxy directly. Given the code volume, this is days, not weeks, and removes the archived-dependency conversation from future architecture reviews permanently.

Do not take a third option of installing as-is and hoping.

Compatibility checklist. PHP version and Laravel major; Passport major and whether password grant is enabled; session/cookie driver and encryption keys; HTTPS-only enforcement; SameSite policy for the SPA's origin relationship; CSRF middleware interaction with proxy routes; CORS allowed origins and supports_credentials.

Sequencing.

1. Confirm auth topology and grant type — stop here if the fit is wrong.
2. Run the constraint-resolution check against the real target stack.
3. Spike end-to-end in a throwaway branch with one SPA and one API.
4. Security review of cookie flags, CSRF, throttling, token logging, and logout revocation.
5. Fork/vendor, pin, and add contract tests covering login, refresh, logout, and expired-token paths.
6. Roll out behind a feature flag to a single low-risk frontend before fleet-wide adoption.
7. Instrument login success/failure rates and token-refresh latency before widening.

Operational Impact

Maintenance. Adopting this package means accepting ownership of an auth component. Assign a named owner, enable dependency scanning on the fork, and schedule an annual review. Realistic steady-state cost is low — a few engineer-days per year for framework bumps — but it is not zero, and it must be budgeted rather than discovered.

Support. There is no upstream to escalate to. You need an internal runbook covering cookie misconfiguration, token endpoint outages, and refresh failures, plus a documented decision record explaining why the pattern was chosen so a future team doesn't relitigate it from scratch.

Scaling. The proxy is effectively stateless and scales horizontally with the API tier; it adds one internal hop per login and per refresh, not per request, so throughput impact is negligible. The real scaling considerations are token validation cost on the API side (cache JWKS if applicable) and a shared store for revocation/refresh state if you implement it.

Failure modes to design for.

• Identity provider outage = total login outage for every frontend behind the proxy. This is a single point of failure you are deliberately introducing.
• Cookie misconfiguration (domain, SameSite, Secure) produces silent auth failures that look like application bugs and consume disproportionate debugging time.
• Refresh race conditions when multiple tabs refresh concurrently.
• Clock skew causing premature expiry rejection.
• Token leakage into logs if proxy requests are logged with bodies or headers.
• Grant-type deprecation upstream, which would force a migration you currently have no vendor to guide you through.

Ramp-up. A mid-level Laravel engineer can read and understand the whole package in half a day. Operating it safely is a different bar: whoever owns the fork needs enough OAuth fluency to evaluate refresh rotation, revocation, and cookie security independently, because no one upstream will. Plan for a security-literate reviewer on the initial adoption and at each annual review — that is the true cost of the archived status, and it is manageable, provided it is acknowledged rather than assumed away.