RBAC support

Author: KroderDev

README.md

@@ -86,6 +86,77 @@ Route::middleware(['jwt.auth'])->group(function () {
 
 ---
 
+### LoadAccess
+
+**Alias**: the string you assign to `load_access` in `middleware_aliases`, e.g. `load.access`.  
+**Class**: `Kroderdev\LaravelMicroserviceCore\Http\Middleware\LoadAccess`
+
+#### Description
+
+Loads the authenticated user's roles and permissions, typically from a centralized permission service (such as an API Gateway or dedicated permissions microservice).  
+By default, the `ValidateJwt` middleware will automatically load `roles` and `permissions` from the JWT payload if they are present.  
+However, if you have a centralized permission service, you can use `LoadAccess` to fetch and hydrate the latest roles and permissions for the user, ensuring up-to-date authorization data.
+
+#### Usage
+
+Apply after JWT authentication, or use the `microservice.auth` group for both:
+
+```php
+// In routes/api.php
+Route::middleware(['jwt.auth', 'load.access'])->group(function () {
+    // protected routes with up-to-date permissions…
+});
+
+// Or simply:
+Route::middleware('microservice.auth')->group(function () {
+    // protected routes…
+});
+```
+
+---
+
+### Permission Middleware
+
+**Alias**: the string you assign to `permission` in `middleware_aliases`, e.g. `permission`.  
+**Class**: `Kroderdev\LaravelMicroserviceCore\Http\Middleware\PermissionMiddleware`
+
+#### Description
+
+Restricts access to routes based on user permissions.  
+Checks if the authenticated user has the required permission(s) before allowing access.  
+Returns a 403 Forbidden response if the user lacks the necessary permission.
+
+#### Usage
+
+```php
+// In routes/api.php
+Route::middleware(['permission:orders.view'])->get('/orders', [OrderController::class, 'index']);
+Route::middleware(['permission:orders.create'])->post('/orders', [OrderController::class, 'store']);
+```
+
+---
+
+### Role Middleware
+
+**Alias**: the string you assign to `role` in `middleware_aliases`, e.g. `role`.  
+**Class**: `Kroderdev\LaravelMicroserviceCore\Http\Middleware\RoleMiddleware`
+
+#### Description
+
+Restricts access to routes based on user roles.  
+Checks if the authenticated user has the required role(s) before allowing access.  
+Returns a 403 Forbidden response if the user does not have the required role.
+
+#### Usage
+
+```php
+// In routes/api.php
+Route::middleware(['role:admin'])->get('/admin', [AdminController::class, 'dashboard']);
+Route::middleware(['role:manager'])->post('/reports', [ReportController::class, 'generate']);
+```
+
+---
+
 ### Correlation ID
 
 **Alias**: the string you assign to `correlation_id` in `middleware_aliases`, e.g. `correlation.id`.
@@ -123,6 +194,29 @@ X-Correlation-ID: 123e4567-e89b-12d3-a456-426614174000
 
 ---
 
+### Auth Middleware Group
+
+For convenience, you can use the built-in `microservice.auth` group, which runs:
+
+1. **ValidateJwt** – decode JWT, hydrate `ExternalUser`, set `Auth::user()`  
+2. **LoadAccess** – fetch roles & permissions via ApiGateway
+
+#### Usage
+
+```php
+// routes/api.php
+
+Route::middleware('microservice.auth')->group(function () {
+    // Here you already have a valid ExternalUser with roles & permissions loaded:
+    Route::get('/orders',   [OrderController::class, 'index']);
+    Route::post('/orders',  [OrderController::class, 'store']);
+});
+```
+
+You no longer need to stack `jwt.auth` + `load.access` manually—just use `microservice.auth` wherever you need full auth + authorization.
+
+---
+
 ## Public Release and Future Goals
 
 This repository is brand new, and I’m excited to develop it further! My plan is to continuously strengthen the core, add more middleware modules, expand test coverage, and refine configuration options.  

src/Http/Middleware/LoadAccess.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Kroderdev\LaravelMicroserviceCore\Http\Middleware;
+
+use Closure;
+use Firebase\JWT\JWT;
+use Firebase\JWT\Key;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Kroderdev\LaravelMicroserviceCore\Auth\ExternalUser;
+use Kroderdev\LaravelMicroserviceCore\Services\PermissionsClient;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * Fetch roles & permissions for the current User from the ApiGateway.
+ */
+class LoadAccess
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
+     */
+    public function handle(Request $request, Closure $next): Response
+    {
+        $user = Auth::user();
+
+        // If no user, skip
+        if (! $user) {
+            return response()->json([
+                'error'   => 'unauthorized',
+                'message' => 'No authenticated user',
+                'status'  => Response::HTTP_UNAUTHORIZED,
+            ], Response::HTTP_UNAUTHORIZED);
+        }
+
+        try {
+            $access = app(PermissionsClient::class)->getAccessFor($user);
+            $user->loadAccess(
+                $access['roles'] ?? [],
+                $access['permissions'] ?? []
+            );
+        } catch (\Throwable $e) {
+            // Do nothing
+            // $user->loadAccess([], []);
+        }
+
+        return $next($request);
+    }
+}

src/Http/Middleware/PermissionMiddleware.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Kroderdev\LaravelMicroserviceCore\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * Check that the authenticated ExternalUser has the given permission.
+ * Usage: ->middleware(['permission:posts.create'])
+ */
+class PermissionMiddleware
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param  \Closure(\Illuminate\Http\Request, string): (\Symfony\Component\HttpFoundation\Response)  $next
+     */
+    public function handle(Request $request, Closure $next, string $permission): Response
+    {
+        $user = Auth::user();
+        if (! $user || ! $user->hasPermissionTo($permission)) {
+            return response()->json([
+                'error'   => 'forbidden',
+                'message' => "User does not have required permission: {$permission}",
+                'status'  => Response::HTTP_FORBIDDEN,
+            ], Response::HTTP_FORBIDDEN);
+        }
+        return $next($request);
+    }
+}

src/Http/Middleware/RoleMiddleware.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Kroderdev\LaravelMicroserviceCore\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * Check that the authenticated User has the given role.
+ * Usage: ->middleware(['role:admin'])
+ */
+class RoleMiddleware
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param  \Closure(\Illuminate\Http\Request, string): (\Symfony\Component\HttpFoundation\Response)  $next
+     */
+    public function handle(Request $request, Closure $next, string $role): Response
+    {
+        $user = Auth::user();
+        if (! $user || ! $user->hasRole($role)) {
+            return response()->json([
+                'error'   => 'forbidden',
+                'message' => "User does not have required role: {$role}",
+                'status'  => Response::HTTP_FORBIDDEN,
+            ], Response::HTTP_FORBIDDEN);
+        }
+        return $next($request);
+    }
+}

src/Http/Middleware/ValidateJwt.php

@@ -37,24 +37,13 @@ public function handle(Request $request, Closure $next): Response
 
             // Auth from JWT
             $user = new ExternalUser((array) $decoded);
-
-            // Get Permissions, permits tolerance
-            try {
-                $access = app(PermissionsClient::class)->getAccessFor($user);
-            } catch (\Throwable $e) {
-                $access = [
-                    'roles' => [],
-                    'permissions' => [],
-                ];
-            }
-
             $user->loadAccess(
-                $access['roles'] ?? [],
-                $access['permissions'] ?? []
+                $user->attributes['roles'] ?? [],
+                $user->attributes['permissions'] ?? []
             );
-
             Auth::setUser($user);
             $request->setUserResolver(fn () => $user);
+
         } catch (\Throwable $e) {
             return response()->json(['error' => 'Invalid token', 'message' => $e->getMessage()], Response::HTTP_UNAUTHORIZED);
         }

src/Providers/MicroserviceServiceProvider.php

@@ -7,6 +7,9 @@
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\ServiceProvider;
 use Kroderdev\LaravelMicroserviceCore\Contracts\ApiGatewayClientInterface;
+use Kroderdev\LaravelMicroserviceCore\Http\Middleware\LoadAccess;
+use Kroderdev\LaravelMicroserviceCore\Http\Middleware\PermissionMiddleware;
+use Kroderdev\LaravelMicroserviceCore\Http\Middleware\RoleMiddleware;
 use Kroderdev\LaravelMicroserviceCore\Http\Middleware\ValidateJwt;
 use Kroderdev\LaravelMicroserviceCore\Services\ApiGatewayClient;
 use Kroderdev\LaravelMicroserviceCore\Services\ApiGatewayClientFactory;
@@ -56,6 +59,27 @@ public function boot(Router $router): void
             $router->prependMiddlewareToGroup('api', CorrelationId::class);
         }
 
+        // Role middleware alias
+        if (! empty($aliases['role'] ?? '')) {
+            $router->aliasMiddleware($aliases['role'], RoleMiddleware::class);
+        }
+
+        // Permission middleware alias
+        if (! empty($aliases['permission'] ?? '')) {
+            $router->aliasMiddleware($aliases['permission'], PermissionMiddleware::class);
+        }
+
+        // LoadAccess middleware alias
+        if (! empty($aliases['load_access'] ?? '')) {
+            $router->aliasMiddleware($aliases['load.access'], PermissionMiddleware::class);
+        }
+
+        // Auth middleware group
+        $router->middlewareGroup('microservice.auth', [
+            ValidateJwt::class,
+            LoadAccess::class,
+        ]);
+
         // HTTP
         Http::macro('apiGateway', function () {
             return Http::acceptJson()

src/config/microservice.php

@@ -14,6 +14,9 @@
     'middleware_aliases' => [
         'jwt_auth'       => 'jwt.auth',         // e.g. 'jwt.auth' or null
         'correlation_id' => 'correlation.id',   // e.g. 'correlation.id' or ''
+        'load_access'    => 'load.access',
+        'role'           => 'role',
+        'permission'     => 'permission',
     ],