feat: implement JWT authentication and scope validation middleware (#11)

Reviewed-on: #11
Co-authored-by: Ron Rise <ron@siteworxpro.com>
Co-committed-by: Ron Rise <ron@siteworxpro.com>

src/Http/Middleware/ScopeMiddleware.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Http\Middleware;
+
+use League\Route\Dispatcher;
+use League\Route\Route;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use Siteworxpro\App\Annotations\Guards\Scope;
+use Siteworxpro\App\Http\JsonResponseFactory;
+use Siteworxpro\HttpStatus\CodesEnum;
+
+class ScopeMiddleware implements MiddlewareInterface
+{
+    /**
+     * @throws \JsonException
+     */
+    public function process(ServerRequestInterface $request, RequestHandlerInterface | Dispatcher $handler): ResponseInterface
+    {
+        if (!$handler instanceof Dispatcher) {
+            return $handler->handle($request);
+        }
+
+        /** @var Route | null $lastSegment */
+        $lastSegment = array_last($handler->getMiddlewareStack());
+
+        if ($lastSegment === null) {
+            return $handler->handle($request);
+        }
+
+        $callable = $lastSegment->getCallable();
+        $class = null;
+        $method = null;
+
+        if (is_array($callable) && count($callable) === 2) {
+            [$class, $method] = $callable;
+        } elseif (is_string($callable)) {
+            // Handle the case where the callable is a string (e.g., 'ClassName::methodName')
+            [$class, $method] = explode('::', $callable);
+        }
+
+        if (class_exists($class)) {
+            $reflectionClass = new \ReflectionClass($class);
+            if ($reflectionClass->hasMethod($method)) {
+                $reflectionMethod = $reflectionClass->getMethod($method);
+                $attributes = $reflectionMethod->getAttributes(Scope::class);
+
+                foreach ($attributes as $attribute) {
+                    /** @var Scope $scopeInstance */
+                    $scopeInstance = $attribute->newInstance();
+                    $requiredScopes = $scopeInstance->getScopes();
+
+                    $userScopes = $request->getAttribute('scopes', []);
+
+                    if (array_any($requiredScopes, fn($requiredScope) => !in_array($requiredScope, $userScopes, true))) {
+                        return JsonResponseFactory::createJsonResponse([
+                            'error' => 'insufficient_scope',
+                            'error_description' => 'The request requires higher privileges than provided by the access token.'
+                        ], CodesEnum::FORBIDDEN);
+                    }
+                }
+            }
+        }
+
+        return $handler->handle($request);
+    }
+}