Oauth2 Laravel Package

Technical Evaluation

What the package claims to be — and the ambiguity to resolve first. The description positions splash/oauth2 as an authorization server: it issues and validates Bearer tokens, ships middleware and scopes, and is backed by Eloquent models for clients, tokens, and scopes, with authorization-code, client-credentials, and password grants. That is the laravel/passport problem space. Earlier internal notes in this repo evaluated it as a client-side connector library (the league/oauth2-client problem space). Those are opposite halves of the protocol and imply opposite decisions: "replace Passport for our own API" versus "wire up third-party integrations." Resolving that scope question is the TPM's first deliverable — before any engineer spends a day on it. If the description is right, the comparison set is Passport/league/oauth2-server; if the notes are right, it is league/oauth2-client/Socialite.

Architecture fit. As an authorization server, the fit is real but narrow. The Laravel-shaped packaging (service provider, publishable config and migrations, route middleware, Eloquent persistence) is exactly the shape of a drop-in Passport alternative, and the value proposition — "don't implement OAuth2 grant flows and token validation yourself" — is a legitimate build-versus-buy call. The risk is that the category is already solved: laravel/passport is first-party, and league/oauth2-server is the audited protocol engine underneath it. A package with zero dependents is competing against a first-party default, so its only defensible niche is convention fit with the Splash toolchain or a materially simpler surface.

Integration feasibility. Unverified and gated. Three checks decide go/no-go in an afternoon: (1) the GitLab repository is publicly readable and the code is Composer-installable or vendorable; (2) a declared license permits internal and redistributed use — an unlicensed repo is legally unusable regardless of quality; (3) composer.json constraints accept the target PHP/Laravel majors, and its migrations and service-provider bindings do not collide with Passport. Zero stars and zero dependents on a non-GitHub host means this was almost certainly extracted from one company's product, not built as a library.

Technical risk.

• Security surface. Authorization-server code is the highest-consequence code in the auth stack: client secret handling, redirect URI allowlisting, state/PKCE enforcement, scope escalation, token revocation, and refresh-token rotation. Password grant is deprecated in OAuth 2.1 — shipping it by default is a design signal, not just a feature.
• No adoption signal. No downstream consumers means the grant edge cases and error paths have never been pressure-tested by anyone but the original author.
• Bus factor of ~1, with no support commitment and a real chance the GitLab project goes read-only without notice.
• Protocol primitives reimplemented. If it hand-rolls grants rather than delegating to league/oauth2-server, that is a hard stop for production use.
• Token-at-rest posture unknown — encryption, key rotation, log redaction, and audit trails are all unpriced until read.

Key questions for the maintainer (or the code).

1. Is this an authorization server or a client/connector layer? Which side of the protocol?
2. Does it delegate to league/oauth2-server / league/oauth2-client, or reimplement grants?
3. Which grants — authorization code (+PKCE), client credentials, password, refresh, device code — and is PKCE enforced or optional?
4. Are tokens encrypted at rest, with what key management and rotation story?
5. Redirect URI validation: exact-match allowlist or prefix matching?
6. Refresh-token rotation and reuse detection — or long-lived opaque refresh tokens?
7. Is it single-flight safe under concurrent refresh across workers?
8. Supported PHP/Laravel versions, test suite and provider/server mocks, and license?
9. Is the GitLab project public, archived, or internal-only?

Integration Approach

Stack fit. Only two situations make this worth a look. First, you are already inside the Splash/SplashTools ecosystem and its Laravel conventions, so the package drops in without translation. Second, you need to stand up an OAuth2 server for your own API and want a smaller, more readable alternative to Passport — in which case Passport remains the default and this must earn its way in. If the real need is third-party connectors, this is the wrong tool and the earlier connector assessments already make the case for league/oauth2-client + socialiteproviders. If the real need is user login, Socialite already covers it.

Migration path. Treat it as source material, not a dependency. Mirror the repository into your own GitLab group, pin to a commit SHA, and place it behind an internal interface (OAuthServer or OAuthConnector) that application code depends on. That adapter boundary is the entire strategy: it lets you patch now and swap to Passport, league/oauth2-server, or a maintained alternative later without touching call sites. If you must consume via Composer, use a VCS repository entry with an explicit commit ref — never a floating branch, never a GitLab URL resolved at build time in CI.

Compatibility. Verify before anything else: PHP constraint, Laravel major, Guzzle major, and whether its migrations collide with existing oauth_clients / oauth_tokens tables (a naming collision with Passport in the same database is a migration-order problem, not a cosmetic one). Confirm the service provider is auto-discovered or manually registrable, that config is publishable, and that publishing does not overwrite an existing config/oauth2.php. A Guzzle 6 pin alone would disqualify it on a modern Laravel 10/11 codebase.

Sequencing.

1. Recon and scope disambiguation (1–2 days). Clone, read composer.json, LICENSE, src/, and the service provider. Confirm server-vs-client. Kill here if it reimplements grants or lacks a license.
2. Decision memo. One page: what it is, what it replaces, what it would cost to own, and a written kill criterion.
3. Fork, pin, and instrument. Internal mirror, CI running its test suite, Dependabot/Renovate on the fork, named owner on the repo.
4. Adapter layer. Define our contract and token/client persistence; the package sits behind it and is never called directly from controllers.
5. Pilot behind a low-risk surface. One non-critical scope set, staging-first, exercising a full token lifecycle — issue, use, expire, refresh, revoke.
6. Harden. Refresh locking, token encryption verification, audit logging, revocation UX, config validation at boot.
7. Expand or exit — expand only after the pilot survives a real expiry and a real revocation; otherwise delete the fork and move to the standard library.

Operational Impact

Maintenance. Ownership transfers to us on day one. Assume zero upstream responsiveness and plan for our fork to be the maintained line, with recurring budget for security patching of the OAuth2 primitives underneath it. CVEs in OAuth2 libraries are not hypothetical, and a dormant fork turns a routine patch into a project. Assign one named owner with explicit time allocation; unowned forks rot within two quarters, and an unowned auth fork is worse than no abstraction.

Support. No community, no issue history, no Stack Overflow corpus. Internal documentation of the token lifecycle, config keys, grant behavior, and failure semantics becomes mandatory rather than nice-to-have. Every question a new engineer would have asked the maintainer must be answered in the repo README or it will be re-derived at cost.

Scaling. Three hazards. First, refresh stampedes: concurrent workers noticing an expired token and all hitting the token endpoint, which rotation-enabled providers answer by invalidating the refresh token — verify single-flight refresh exists or add a distributed lock at the adapter layer. Second, token table growth and key management as tenant and client counts rise; confirm indexes on client/tenant/expiry and a cleanup job for expired tokens. Third, key rotation, which is straightforward in Passport and unknown here. Confirm secrets are encrypted, not merely base64'd.

Failure modes to instrument.

• Refresh token expired or revoked → terminal "reconnect required" state surfaced to the user, not a silent retry loop.
• Token endpoint 5xx or provider outage → bounded retry with backoff; never cascade into user-facing request failures.
• Clock skew → tokens treated as valid past expiry; enforce a safety margin.
• Redirect URI mismatch or misconfigured client → opaque provider errors; validate config at boot, fail loudly on startup, not at 2 a.m.
• Token leakage via logs, exception traces, or Telescope/dump payloads → redaction must be verified, not assumed.
• Concurrent refresh with rotation → lost tokens; the most damaging and least obvious failure, and the one to test deliberately in the pilot.
• Scope escalation or missing scope enforcement on a route → verify middleware is deny-by-default.

Ramp-up. A Laravel engineer fluent in OAuth2 can be productive in the fork within a day or two, provided the repo is documented and the adapter boundary is real. The genuine ramp-up cost is organizational: convincing a team to put a zero-dependent package on the credential path. That argument cannot be won with a judgment call — it requires the pilot, the security read, and a harden step. Given the thin adoption signal and the unresolved server-vs-client ambiguity, fund this only as a scoped spike with a written kill criterion, and do not let it become a shared platform dependency until a forked, pinned, adapter-wrapped version has survived one full token lifecycle in production. The measurable outcome to commit to is "auth surface shipped N days sooner with a reusable, security-reviewed flow and a named owner" — not "added a dependency."