refactor: address PR review feedback on types, grammar, and aud handling

- DeleteInstanceTrait: declare exitRemoteCall() as never to enforce
  termination contract; keep deleteInstance() as void with @return never doc
- SSOTokenGenerator: accept string|array<string> for aud claim, validate
  all array elements are non-empty strings before passing to permittedFor()
- SSODataTrait: rename $val to $value in getLocale/getTags for consistency
- SharedDataTrait: fix grammar 'a editor' -> 'an editor' in docblock
- SSOTokenTest: apply operator_linebreak cs-fixer fix

Co-Authored-By: Opencode <opencode@noreply.opencode.ai>
Co-Authored-By: GitHub Copilot <copilot@noreply.github.com>

Author: 3 people

src/RemoteCall/DeleteInstanceTrait.php

@@ -11,13 +11,21 @@ trait DeleteInstanceTrait
      *
      * if a remote call was not handled by the user we die hard here
      */
-    protected function exitRemoteCall(): void
+    protected function exitRemoteCall(): never
     {
         error_log("Warning: The exit procedure for a remote call was not properly handled.");
         exit;
     }
 
-    private function deleteInstance(string $instanceId, RemoteCallInterface $remoteCallHandler): never
+    /**
+     * Handle the delete-instance remote call and terminate the request.
+     *
+     * @param string $instanceId
+     * @param RemoteCallInterface $remoteCallHandler
+     *
+     * @return never
+     */
+    private function deleteInstance(string $instanceId, RemoteCallInterface $remoteCallHandler): void
     {
         if ($remoteCallHandler instanceof DeleteInstanceCallHandlerInterface) {
             $result = $remoteCallHandler->deleteInstance($instanceId);

src/SSOData/SSODataTrait.php

@@ -207,8 +207,8 @@ public function getThemeBackgroundColor(): ?string
      */
     public function getLocale(): string
     {
-        $val = $this->getClaimSafe(SSODataClaimsInterface::CLAIM_USER_LOCALE);
-        return is_string($val) ? $val : '';
+        $value = $this->getClaimSafe(SSODataClaimsInterface::CLAIM_USER_LOCALE);
+        return is_string($value) ? $value : '';
     }
 
     /**
@@ -218,7 +218,7 @@ public function getLocale(): string
      */
     public function getTags(): ?array
     {
-        $val = $this->getClaimSafe(SSODataClaimsInterface::CLAIM_USER_TAGS);
-        return is_array($val) ? $val : null;
+        $value = $this->getClaimSafe(SSODataClaimsInterface::CLAIM_USER_TAGS);
+        return is_array($value) ? $value : null;
     }
 }

src/SSOData/SharedDataTrait.php

@@ -121,7 +121,7 @@ public function getSubject(): ?string
      *
      * If this is set to "editor", the requesting user may manage the contents
      * of the plugin instance, i.e. she has administration rights.
-     * The type of the accessing entity can be either a "user" or a "editor".
+     * The type of the accessing entity can be either a "user" or an "editor".
      *
      * @return null|string
      */

src/SSOTokenGenerator.php

@@ -54,8 +54,22 @@ private static function buildToken(Configuration $config, array $tokenData): Tok
         $builder = $config->builder();
         // Validate and coerce required registered claims to the expected types
         $audience = $tokenData[SSOData\SharedClaimsInterface::CLAIM_AUDIENCE] ?? '';
-        if (!is_string($audience) || $audience === '') {
-            throw new \InvalidArgumentException('aud claim must be a non-empty string for token generation');
+        if (is_string($audience)) {
+            if ($audience === '') {
+                throw new \InvalidArgumentException('aud claim must be a non-empty string or array for token generation');
+            }
+            /** @var non-empty-list<non-empty-string> $audiences */
+            $audiences = [$audience];
+        } elseif (is_array($audience) && $audience !== []) {
+            foreach ($audience as $aud) {
+                if (!is_string($aud) || $aud === '') {
+                    throw new \InvalidArgumentException('aud claim array must contain only non-empty strings for token generation');
+                }
+            }
+            /** @var non-empty-list<non-empty-string> $audiences */
+            $audiences = array_values($audience);
+        } else {
+            throw new \InvalidArgumentException('aud claim must be a non-empty string or array for token generation');
         }
 
         $issuedAt = $tokenData[SSOData\SharedClaimsInterface::CLAIM_ISSUED_AT] ?? null;
@@ -74,7 +88,7 @@ private static function buildToken(Configuration $config, array $tokenData): Tok
         }
 
         $token = $builder
-            ->permittedFor($audience)
+            ->permittedFor(...$audiences)
             ->issuedAt($issuedAt)
             ->canOnlyBeUsedAfter($notBefore)
             ->expiresAt($expiresAt);

test/SSOTokenTest.php

@@ -208,8 +208,8 @@ public function testAccessorsGiveCorrectValues(): void
                 $data = $data->getTimestamp();
             }
 
-            $data = is_array($data) ? print_r($data, true) :
-                (is_scalar($data) || is_null($data) ? (string) ($data ?? '') : '[complex_type]');
+            $data = is_array($data) ? print_r($data, true)
+                : (is_scalar($data) || is_null($data) ? (string) ($data ?? '') : '[complex_type]');
 
             $this->assertEquals(
                 $tokenData[$key],