Oauth2 Server Scope Manager Laravel Package

Product Decisions This Supports

• API permission taxonomy (scopes). The package exists to answer one narrow question: given a requested scope string, is it valid, is it registered, and may this client/user hold it? That is the decision layer behind any "what can this integration actually do" question — useful when defining a scope vocabulary (orders:read, orders:write, payouts:initiate) and deciding how coarse or fine-grained it should be.
• Consent and permission UX. Scope definitions drive the authorization screen ("Acme wants to read your orders and issue refunds"). Whether you show one bundled consent, granular per-scope toggles, or incremental/step-up consent is a product decision that maps directly onto how scopes are modeled here.
• Partner / developer platform access tiers. If the roadmap includes third-party apps, a scope manager is the enforcement point for tiering (free vs. partner vs. internal) and for scoped API keys per integration.
• Build vs. buy for authorization. This package is a component, not a solution. It sharpens the build-vs-buy conversation: scope-validation logic is small and well-understood, so the real buy decision is the full authorization server (Laravel Passport, league/oauth2-server), not this class.
• Compliance and least-privilege positioning. Data-minimization commitments (GDPR, SOC 2, enterprise security questionnaires) are easier to evidence when token issuance is scope-bounded and auditable — a scope manager is the concrete artifact behind that claim.
• Roadmap signal: low star count, zero dependents, and a parent project that has been largely superseded by league/oauth2-server mean this is best treated as a design reference, not a dependency. It informs the decision; it shouldn't be the implementation.

When to Consider This Package

Consider it only if all of the following hold:

• You are already running spomky-labs/oauth2-server (or a legacy fork of it) and need to swap or extend the ScopeManagerInterface implementation without re-platforming.
• You need a pluggable, framework-agnostic scope-resolution contract in a non-Laravel PHP service and want a reference implementation of the interface shape.
• Your team has accepted the maintenance burden of a low-activity, zero-dependent dependency and can pin/vendor it.

Look elsewhere in essentially every other case:

• Greenfield Laravel work: use Laravel Passport (full OAuth2 server, scopes built in) or Sanctum if you only need first-party token auth and don't need OAuth2 scopes at all.
• Framework-agnostic or high-assurance OAuth2: use league/oauth2-server, which is actively maintained, widely depended upon, and has a ScopeInterface plus scope-validation hooks covering the same ground.
• You only need role/permission checks, not OAuth2: a policy/ability layer (Laravel Gates & Policies, or a permission package) is the right tool — a scope manager is overkill and introduces OAuth2 ceremony you don't need.
• You need a maintained, supported dependency: zero stars, zero dependents, and a superseded parent project are disqualifying for anything customer-facing or long-lived.

How to Pitch It (Stakeholders)

Executive summary. This is a small, single-purpose library that validates and enforces OAuth2 scopes — the mechanism that limits what a third-party app or integration can do with a user's data. It is not a product feature on its own; it is plumbing that sits under an API permissions model. The package itself is unmaintained and has essentially no adoption, and the broader project it belongs to has been superseded by a well-supported alternative. Recommendation: do not adopt it as a dependency. Use it, if at all, as a design reference when we scope out an API permissions model, and implement that model on Laravel Passport or league/oauth2-server.

For engineering. The package contributes one piece of the OAuth2 authorization flow: parsing a requested scope string, resolving it against registered scopes, and deciding grant/deny per client and per user. That logic is a few hundred lines and is already provided, better maintained, inside league/oauth2-server (and therefore Passport). Adopting it means carrying an unowned dependency for functionality we'd get for free from a library we're already likely to install. If we're on the legacy Spomky stack, pin and vendor it; if we're building new, port the interface shape — a ScopeManager that answers "is this scope registered / is it granted to this client / does this token carry it" — and back it with Passport's scope repository.

Risk framing for the decision log. Low technical risk to skip it; moderate long-term risk to depend on it (no maintainer activity, no downstream users to surface bugs, no security patch path). The product need — bounded, auditable, consent-visible API permissions — is real and on the roadmap. The package is not the way to meet it.