chore: oauth2 session authentication hook

docs/pages/docs/features/security/oauth2/installation/index.md

@@ -103,3 +103,31 @@ $ php ./bin/resonance.php generate:defuse-key > oauth2/defuse.key
 ```
 
 Then, change the CHMOD permissions for that key to `0600`.
+
+## Post Session Authentication Hook
+
+If you are using {{tutorials/session-based-authentication/index}} you need
+to return `OAuth2UserSessionAuthenticated` instance
+from your authentication {{docs/features/http/responders}} (see also:
+{{docs/features/http/interceptors}}).
+
+It allows OAuth2 to know that the user is authenticated and that it should
+check if user is in the middle of OAuth2 flow.
+
+```php
+<?php
+
+use Distantmagic\Resonance\OAuth2UserSessionAuthenticated;
+
+final readonly class LoginValidation extends HttpController
+{
+    public function createResponse(): HttpInterceptableInterface 
+    {
+        // ...
+        // perform session authentication somehow
+        // ...
+
+        return new OAuth2UserSessionAuthenticated();
+    }
+}
+```

resources/css/docs-hljs.css

@@ -85,6 +85,7 @@ code[class] {
 .fenced-code {
   background-color: var(--color-block-background);
   box-shadow: 8px 8px #00000033;
+  margin: 20px 0;
 
   @media screen and (min-width: 1024px) {
     position: relative;

src/HttpResponder/OAuth2/PostSessionAuthentication.php → src/HttpInterceptor/OAuth2UserSessionAuthenticatedInterceptor.php

@@ -2,34 +2,44 @@
 
 declare(strict_types=1);
 
-namespace Distantmagic\Resonance\HttpResponder\OAuth2;
+namespace Distantmagic\Resonance\HttpInterceptor;
 
 use Distantmagic\Resonance\Attribute\GrantsFeature;
+use Distantmagic\Resonance\Attribute\Intercepts;
 use Distantmagic\Resonance\Attribute\Singleton;
 use Distantmagic\Resonance\Feature;
 use Distantmagic\Resonance\HttpInterceptableInterface;
-use Distantmagic\Resonance\HttpResponder;
+use Distantmagic\Resonance\HttpInterceptor;
 use Distantmagic\Resonance\HttpResponderInterface;
 use Distantmagic\Resonance\OAuth2AuthorizationCodeFlowControllerInterface;
 use Distantmagic\Resonance\OAuth2AuthorizationRequestSessionStore;
 use Distantmagic\Resonance\OAuth2AuthorizedUser;
+use Distantmagic\Resonance\OAuth2UserSessionAuthenticated;
 use Distantmagic\Resonance\SessionAuthentication;
+use Distantmagic\Resonance\SingletonCollection;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 use RuntimeException;
 
+/**
+ * @template-extends HttpInterceptor<OAuth2UserSessionAuthenticated>
+ */
 #[GrantsFeature(Feature::OAuth2)]
-#[Singleton]
-final readonly class PostSessionAuthentication extends HttpResponder
+#[Intercepts(OAuth2UserSessionAuthenticated::class)]
+#[Singleton(collection: SingletonCollection::HttpInterceptor)]
+final readonly class OAuth2UserSessionAuthenticatedInterceptor extends HttpInterceptor
 {
     public function __construct(
         private OAuth2AuthorizationCodeFlowControllerInterface $authorizationCodeFlowController,
         private OAuth2AuthorizationRequestSessionStore $authorizationRequestSessionStore,
         private SessionAuthentication $sessionAuthentication,
     ) {}
 
-    public function respond(ServerRequestInterface $request, ResponseInterface $response): HttpInterceptableInterface|HttpResponderInterface|ResponseInterface
-    {
+    public function intercept(
+        ServerRequestInterface $request,
+        ResponseInterface $response,
+        object $intercepted,
+    ): HttpInterceptableInterface|HttpResponderInterface|ResponseInterface {
         if (!$this->authorizationRequestSessionStore->has($request)) {
             return $this->authorizationCodeFlowController->redirectToAuthenticatedPage($request, $response);
         }

src/OAuth2UserSessionAuthenticated.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Distantmagic\Resonance;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+final readonly class OAuth2UserSessionAuthenticated implements HttpInterceptableInterface
+{
+    private SwooleContextRequestResponseReader $swooleContextRequestResponseReader;
+
+    /**
+     * @psalm-taint-source file $templatePath
+     */
+    public function __construct(
+        ?ServerRequestInterface $request = null,
+        ?ResponseInterface $response = null,
+    ) {
+        $this->swooleContextRequestResponseReader = new SwooleContextRequestResponseReader(
+            request: $request,
+            response: $response,
+        );
+    }
+
+    public function getResponse(): ResponseInterface
+    {
+        return $this->swooleContextRequestResponseReader->getResponse();
+    }
+
+    public function getServerRequest(): ServerRequestInterface
+    {
+        return $this->swooleContextRequestResponseReader->getServerRequest();
+    }
+}