How auth-server-laravel works

auth-server-laravel is a thin glue layer over auth-server-php. Heavy lifting (JWT validation, transport, error mapping) lives in the core. What this package adds:

Service provider

VenAuthServiceProvider is auto-discovered by Laravel. It:

1. Merges config/vauth.php from the publishable defaults.
2. Constructs the auth-server-php AuthClient as a singleton, bound to the Vendidit\AuthServer\AuthClient class name in the container.
3. Registers the vendidit-jwt guard driver and the vendidit user provider with Laravel’s Auth manager.
4. Registers all six middleware aliases via the $middlewareAliases contract.
5. Registers all five Blade directives via Blade::directive(...).
6. Sets up a Laravel↔PSR-16 cache bridge so PSR-16 ports use the app’s configured cache store.

Custom Guard — VenJwtGuard

When config/auth.php’s web guard is set to vendidit-jwt:

1. The guard reads Authorization: Bearer ... from the current request.
2. It calls AuthClient::validateBearer(...) from auth-server-php.
3. On success, it constructs a VenAuthUser (a lightweight Authenticatable implementing only what’s needed) — or, in Pattern B, calls the registered vendidit user provider to hydrate the local Eloquent model from the token claims.
4. Stores the principal on the request and the user on the guard.

Auth::user() then returns the user instance. Auth::check() returns true.

User provider — VenUserProvider

In Pattern B, the provider:

1. Looks up users by vendidit_id = $claims->uid.
2. If not found, inserts a row populated from the claims (email, first_name, last_name, etc.).
3. Syncs role / permission caches on the model via HasVenAuth.

The local model still acts as the canonical “user with app-specific data” — the vendidit_id is the platform’s unified identifier.

Middleware aliases

Alias	Class	Behaviour
vauth	VendiditAuthenticate	Validate bearer; abort 401 if invalid.
vauth.role:r1,r2	VendiditRequireRole	Abort 403 unless the principal’s roles intersect.
vauth.permission:p1,p2	VendiditRequirePermission	Abort 403 unless permissions include at least one.
vauth.app:code1	VendiditRequireApp	Abort 403 unless app_code claim matches.
vauth.org:slug-or-id	VendiditRequireOrg	Abort 403 unless org_id / org_slug matches.
vauth.no_imp	VendiditRefuseImpersonation	Abort 403 if the token carries impersonation claims.

All check system_admin first and let it through.

Blade directives

Directive	Compiled to
@vauth … @endvauth	if (auth()->check())
@vrole('r') … @endvrole	if (VenAuth::hasRole('r'))
@vperm('p') … @endvperm	if (VenAuth::hasPermission('p'))
@vapp('code') … @endvapp	if (VenAuth::isApp('code'))
@vimpersonating … @endvimpersonating	if (VenAuth::isImpersonating())

Cache bridge

LaravelCacheBridge adapts Laravel’s Illuminate\Contracts\Cache\Repository to PSR-16. This lets auth-server-php’s RevocationCache use the configured cache store (Redis in prod, array in tests) without an extra dependency.

Error mapping

Every VenAuthException thrown by the guard / middleware is mapped to the Laravel exception with the matching status code, plus a JSON envelope { error: <code>, message: <message> }. Customize via the default exception handler.