Mandatory members (#91)

* Support for mandatory header parameters and claims

Author: Spomky

src/Component/Checker/ClaimCheckerManager.php

@@ -79,14 +79,17 @@ public function getCheckers(): array
      * This method returns an array with all checked claims.
      * It is up to the implementor to decide use the claims that have not been checked.
      *
-     * @param array $claims
+     * @param array    $claims
+     * @param string[] $mandatoryClaims
      *
      * @throws InvalidClaimException
+     * @throws MissingMandatoryClaimException
      *
      * @return array
      */
-    public function check(array $claims): array
+    public function check(array $claims, array $mandatoryClaims = []): array
     {
+        $this->checkMandatoryClaims($mandatoryClaims, $claims);
         $checkedClaims = [];
         foreach ($this->checkers as $claim => $checker) {
             if (array_key_exists($claim, $claims)) {
@@ -97,4 +100,22 @@ public function check(array $claims): array
 
         return $checkedClaims;
     }
+
+    /**
+     * @param string[] $mandatoryClaims
+     * @param array    $claims
+     *
+     * @throws MissingMandatoryClaimException
+     */
+    private function checkMandatoryClaims(array $mandatoryClaims, array $claims)
+    {
+        if (empty($mandatoryClaims)) {
+            return;
+        }
+        $diff = array_keys(array_diff_key(array_flip($mandatoryClaims), $claims));
+
+        if (!empty($diff)) {
+            throw new MissingMandatoryClaimException(sprintf('The following claims are mandatory: %s.', implode(', ', $diff)), $diff);
+        }
+    }
 }

src/Component/Checker/HeaderCheckerManager.php

@@ -99,19 +99,22 @@ private function add(HeaderChecker $checker): self
      * All header parameters are checked against the header parameter checkers.
      * If one fails, the InvalidHeaderException is thrown.
      *
-     * @param JWT $jwt
-     * @param int $index
+     * @param JWT      $jwt
+     * @param int      $index
+     * @param string[] $mandatoryHeaderParameters
      *
      * @throws InvalidHeaderException
+     * @throws MissingMandatoryHeaderParameterException
      */
-    public function check(JWT $jwt, int $index)
+    public function check(JWT $jwt, int $index, array $mandatoryHeaderParameters = [])
     {
         foreach ($this->tokenTypes as $tokenType) {
             if ($tokenType->supports($jwt)) {
                 $protected = [];
                 $unprotected = [];
                 $tokenType->retrieveTokenHeaders($jwt, $index, $protected, $unprotected);
                 $this->checkDuplicatedHeaderParameters($protected, $unprotected);
+                $this->checkMandatoryHeaderParameters($mandatoryHeaderParameters, $protected, $unprotected);
                 $this->checkHeaders($protected, $unprotected);
 
                 return;
@@ -133,6 +136,25 @@ private function checkDuplicatedHeaderParameters(array $header1, array $header2)
         }
     }
 
+    /**
+     * @param string[] $mandatoryHeaderParameters
+     * @param array    $protected
+     * @param array    $unprotected
+     *
+     * @throws MissingMandatoryHeaderParameterException
+     */
+    private function checkMandatoryHeaderParameters(array $mandatoryHeaderParameters, array $protected, array $unprotected)
+    {
+        if (empty($mandatoryHeaderParameters)) {
+            return;
+        }
+        $diff = array_keys(array_diff_key(array_flip($mandatoryHeaderParameters), array_merge($protected, $unprotected)));
+
+        if (!empty($diff)) {
+            throw new MissingMandatoryHeaderParameterException(sprintf('The following header parameters are mandatory: %s.', implode(', ', $diff)), $diff);
+        }
+    }
+
     /**
      * @param array $protected
      * @param array $header

src/Component/Checker/MissingMandatoryClaimException.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2014-2018 Spomky-Labs
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license.  See the LICENSE file for details.
+ */
+
+namespace Jose\Component\Checker;
+
+class MissingMandatoryClaimException extends \Exception
+{
+    /**
+     * @var string[]
+     */
+    private $claims;
+
+    /**
+     * MissingMandatoryClaimException constructor.
+     *
+     * @param string   $message
+     * @param string[] $claims
+     */
+    public function __construct(string $message, array $claims)
+    {
+        parent::__construct($message);
+
+        $this->claims = $claims;
+    }
+
+    /**
+     * @return string[]
+     */
+    public function getClaims(): array
+    {
+        return $this->claims;
+    }
+}

src/Component/Checker/MissingMandatoryHeaderParameterException.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2014-2018 Spomky-Labs
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license.  See the LICENSE file for details.
+ */
+
+namespace Jose\Component\Checker;
+
+class MissingMandatoryHeaderParameterException extends \Exception
+{
+    /**
+     * @var string[]
+     */
+    private $parameters;
+
+    /**
+     * MissingMandatoryHeaderParameterException constructor.
+     *
+     * @param string   $message
+     * @param string[] $parameters
+     */
+    public function __construct(string $message, array $parameters)
+    {
+        parent::__construct($message);
+
+        $this->parameters = $parameters;
+    }
+
+    /**
+     * @return string[]
+     */
+    public function getParameters(): array
+    {
+        return $this->parameters;
+    }
+}

src/Component/Checker/Tests/ClaimCheckerManagerFactoryTest.php

@@ -72,6 +72,25 @@ public function iCanCheckValidPayloadClaims()
         self::assertEquals($expected, $result);
     }
 
+    /**
+     * @test
+     * @expectedException \Jose\Component\Checker\MissingMandatoryClaimException
+     * @expectedExceptionMessage The following claims are mandatory: bar.
+     */
+    public function theMandatoryClaimsAreNotSet()
+    {
+        $payload = [
+            'exp' => time() + 3600,
+            'iat' => time() - 1000,
+            'nbf' => time() - 100,
+            'foo' => 'bar',
+        ];
+        $expected = $payload;
+        unset($expected['foo']);
+        $manager = $this->getClaimCheckerManagerFactory()->create(['exp', 'iat', 'nbf', 'aud']);
+        $manager->check($payload, ['exp', 'foo', 'bar']);
+    }
+
     /**
      * @var ClaimCheckerManagerFactory|null
      */

src/Component/Checker/Tests/HeaderCheckerManagerFactoryTest.php

@@ -125,6 +125,21 @@ public function theHeaderContainsUnknownParametersAndIsSuccessfullyChecked()
         self::assertTrue(true);
     }
 
+    /**
+     * @test
+     * @expectedException \Jose\Component\Checker\MissingMandatoryHeaderParameterException
+     * @expectedExceptionMessage The following header parameters are mandatory: mandatory.
+     */
+    public function theHeaderDoesNotContainSomeMandatoryParameters()
+    {
+        $headerCheckerManager = $this->getHeaderCheckerManagerFactory()->create(['aud', 'iss']);
+        $payload = [];
+        $protected = ['aud' => 'Audience', 'iss' => 'Another Service'];
+        $unprotected = ['foo' => 'bar'];
+        $token = Token::create(json_encode($payload), $protected, $unprotected);
+        $headerCheckerManager->check($token, 0, ['aud', 'iss', 'mandatory']);
+    }
+
     /**
      * @test
      * @expectedException \InvalidArgumentException