refactor!: consolidate optional send*/handle* parameters into ContextList

src/IdentityProviderWrapper.php

@@ -31,11 +31,15 @@
 use Litesaml\Models\Descriptors\Entity;
 use Litesaml\Models\Descriptors\Idp;
 use Litesaml\Models\Descriptors\Sp;
-use Litesaml\Models\Messages\Attribute;
 use Litesaml\Models\Messages\AuthnRequest;
+use Litesaml\Models\Messages\Context\Attribute;
+use Litesaml\Models\Messages\Context\ContextList;
+use Litesaml\Models\Messages\Context\NameId;
+use Litesaml\Models\Messages\Context\RelayState;
+use Litesaml\Models\Messages\Context\SessionIndex;
+use Litesaml\Models\Messages\Context\Validate;
 use Litesaml\Models\Messages\LogoutRequest;
 use Litesaml\Models\Messages\LogoutResponse;
-use Litesaml\Models\Messages\NameId;
 use Litesaml\Support\MessageHandler;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
@@ -77,17 +81,17 @@ public function generateMetadata(): string
         $entityDescriptor = (new EntityDescriptor($this->idp->entityId))
             ->addItem($idpSsoDescriptor);
 
-        $context = new SerializationContext();
-        $entityDescriptor->serialize($context->getDocument(), $context);
+        $serializationContext = new SerializationContext();
+        $entityDescriptor->serialize($serializationContext->getDocument(), $serializationContext);
 
-        return (string) $context->getDocument()->saveXML();
+        return (string) $serializationContext->getDocument()->saveXML();
     }
 
-    /**
-     * @param Attribute[] $attributes
-     */
-    public function sendAuthnResponse(Sp $recipient, array $attributes, ?NameId $nameId = null): ResponseInterface
+    public function sendAuthnResponse(Sp $recipient, ContextList $context = new ContextList()): ResponseInterface
     {
+        $attributes = $context->all(Attribute::class);
+        $nameId = $context->first(NameId::class);
+
         $response = new LightSamlAuthnResponse();
 
         $response
@@ -170,7 +174,7 @@ public function sendAuthnResponse(Sp $recipient, array $attributes, ?NameId $nam
         return $this->messageHandler->send($response, $this->idp, $recipient->acs);
     }
 
-    public function handleAuthnRequest(ServerRequestInterface $request, bool $validate = false, ?Entity $issuer = null): AuthnRequest
+    public function handleAuthnRequest(ServerRequestInterface $request, ContextList $context = new ContextList()): AuthnRequest
     {
         $message = $this->messageHandler->unpack($request);
 
@@ -185,13 +189,17 @@ public function handleAuthnRequest(ServerRequestInterface $request, bool $valida
             nameIdPolicyFormat: $message->getNameIDPolicy()?->getFormat(),
         );
 
-        $this->validateIfRequested($message, $validate, $issuer);
+        $this->validateIfRequested($message, $context);
 
         return $dto;
     }
 
-    public function sendLogoutRequest(Entity $recipient, NameId $nameId, ?string $relayState = null, ?string $sessionIndex = null): ResponseInterface
+    public function sendLogoutRequest(Entity $recipient, ContextList $context = new ContextList()): ResponseInterface
     {
+        $nameId = $context->required(NameId::class, 'A NameId is required to send a LogoutRequest');
+        $relayState = $context->first(RelayState::class)?->value;
+        $sessionIndex = $context->first(SessionIndex::class)?->value;
+
         $logoutRequest = (new LightSamlLogoutRequest())
             ->setID(Helper::generateID())
             ->setIssueInstant(new DateTime())
@@ -216,7 +224,7 @@ public function sendLogoutResponse(Entity $recipient): ResponseInterface
         return $this->messageHandler->send($logoutResponse, $this->idp, $recipient->slo);
     }
 
-    public function handleLogoutRequest(ServerRequestInterface $request, bool $validate = false, ?Entity $issuer = null): LogoutRequest
+    public function handleLogoutRequest(ServerRequestInterface $request, ContextList $context = new ContextList()): LogoutRequest
     {
         $message = $this->messageHandler->unpack($request);
 
@@ -232,12 +240,12 @@ public function handleLogoutRequest(ServerRequestInterface $request, bool $valid
             relayState: $message->getRelayState(),
         );
 
-        $this->validateIfRequested($message, $validate, $issuer);
+        $this->validateIfRequested($message, $context);
 
         return $dto;
     }
 
-    public function handleLogoutResponse(ServerRequestInterface $request, bool $validate = false, ?Entity $issuer = null): LogoutResponse
+    public function handleLogoutResponse(ServerRequestInterface $request, ContextList $context = new ContextList()): LogoutResponse
     {
         $message = $this->messageHandler->unpack($request);
 
@@ -251,22 +259,20 @@ public function handleLogoutResponse(ServerRequestInterface $request, bool $vali
             relayState: $message->getRelayState(),
         );
 
-        $this->validateIfRequested($message, $validate, $issuer);
+        $this->validateIfRequested($message, $context);
 
         return $dto;
     }
 
-    private function validateIfRequested(SamlMessage $message, bool $validate, ?Entity $issuer): void
+    private function validateIfRequested(SamlMessage $message, ContextList $context): void
     {
-        if (!$validate) {
-            return;
-        }
+        $validate = $context->first(Validate::class);
 
-        if ($issuer === null) {
-            throw new SamlException('An issuer must be provided to validate the signature');
+        if ($validate === null) {
+            return;
         }
 
-        if (!$this->messageHandler->validateSignature($message, $issuer)) {
+        if (!$this->messageHandler->validateSignature($message, $validate->issuer)) {
             throw new SamlException('Invalid signature');
         }
     }

src/Models/Messages/AuthnResponse.php

@@ -3,6 +3,8 @@
 namespace Litesaml\Models\Messages;
 
 use Litesaml\Enums\Status;
+use Litesaml\Models\Messages\Context\Attribute;
+use Litesaml\Models\Messages\Context\NameId;
 
 readonly class AuthnResponse extends Message
 {

src/Models/Messages/Attribute.php → src/Models/Messages/Context/Attribute.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace Litesaml\Models\Messages;
+namespace Litesaml\Models\Messages\Context;
 
-readonly class Attribute
+readonly class Attribute implements Context
 {
     /**
      * @param array<mixed> $values

src/Models/Messages/Context/Context.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace Litesaml\Models\Messages\Context;
+
+interface Context
+{
+}

src/Models/Messages/Context/ContextList.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace Litesaml\Models\Messages\Context;
+
+use Litesaml\Exceptions\SamlException;
+
+final class ContextList
+{
+    /** @var array<class-string<Context>, Context[]> */
+    private array $items = [];
+
+    public function __construct(Context ...$items)
+    {
+        foreach ($items as $item) {
+            $this->items[$item::class][] = $item;
+        }
+    }
+
+    /**
+     * @template T of Context
+     *
+     * @param class-string<T> $class
+     *
+     * @return T[]
+     */
+    public function all(string $class): array
+    {
+        return $this->items[$class] ?? [];
+    }
+
+    /**
+     * @template T of Context
+     *
+     * @param class-string<T> $class
+     *
+     * @return T|null
+     */
+    public function first(string $class): ?Context
+    {
+        return $this->items[$class][0] ?? null;
+    }
+
+    /**
+     * @template T of Context
+     *
+     * @param class-string<T> $class
+     *
+     * @return T
+     */
+    public function required(string $class, string $message): Context
+    {
+        return $this->first($class) ?? throw new SamlException($message);
+    }
+}

src/Models/Messages/NameId.php → src/Models/Messages/Context/NameId.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace Litesaml\Models\Messages;
+namespace Litesaml\Models\Messages\Context;
 
-readonly class NameId
+readonly class NameId implements Context
 {
     public function __construct(
         public string $value,

src/Models/Messages/Context/NameIdPolicyFormat.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Litesaml\Models\Messages\Context;
+
+readonly class NameIdPolicyFormat implements Context
+{
+    public function __construct(
+        public string $value,
+    ) {
+    }
+}

src/Models/Messages/Context/RelayState.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Litesaml\Models\Messages\Context;
+
+readonly class RelayState implements Context
+{
+    public function __construct(
+        public string $value,
+    ) {
+    }
+}

src/Models/Messages/Context/SessionIndex.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Litesaml\Models\Messages\Context;
+
+readonly class SessionIndex implements Context
+{
+    public function __construct(
+        public string $value,
+    ) {
+    }
+}

src/Models/Messages/Context/Validate.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Litesaml\Models\Messages\Context;
+
+use Litesaml\Models\Descriptors\Entity;
+
+readonly class Validate implements Context
+{
+    public function __construct(
+        public Entity $issuer,
+    ) {
+    }
+}

src/Models/Messages/LogoutRequest.php

@@ -2,6 +2,8 @@
 
 namespace Litesaml\Models\Messages;
 
+use Litesaml\Models\Messages\Context\NameId;
+
 readonly class LogoutRequest extends Message
 {
     public function __construct(