Update type hints and documentation comments for better typechecking

kelvinmo · Feb 11, 2022 · 26b2d80 · 26b2d80
1 parent cef45b4
commit 26b2d80
Show file tree

Hide file tree

Showing 10 changed files with 30 additions and 10 deletions.
diff --git a/src/SimpleJWT/Crypt/AlgorithmFactory.php b/src/SimpleJWT/Crypt/AlgorithmFactory.php
@@ -96,7 +96,9 @@ static public function create($alg, $use = null) {
                     if (!is_subclass_of($cls, $superclass, true)) throw new \UnexpectedValueException('Unexpected use for algorithm: ' . $alg);
                 }
 
-                return new $cls($alg);
+                /** @var Algorithm $obj */
+                $obj = new $cls($alg);
+                return $obj;
             }
         }
         throw new \UnexpectedValueException('Algorithm not supported: ' . $alg);
@@ -120,6 +122,7 @@ static public function getSupportedAlgs($use) {
         foreach ($classes as $cls) {
             if (!is_subclass_of($cls, $superclass, true)) continue;
 
+            /** @var Algorithm $obj */
             $obj = new $cls(null);
             $results = array_merge($results, $obj->getSupportedAlgs());
         }

diff --git a/src/SimpleJWT/Crypt/RSAES.php b/src/SimpleJWT/Crypt/RSAES.php
@@ -75,7 +75,7 @@ public function getKeyCriteria() {
      * Generates a seed for OAEP encoding.  This uses {@link SimpleJWT\Util\Util::random_bytes()}
      * to generate random bytes.
      *
-     * @param int $len the length of the seed required, in octets
+     * @param int<1, max> $len the length of the seed required, in octets
      * @return string the seed
      */
     protected function generateSeed($len) {

diff --git a/src/SimpleJWT/JWE.php b/src/SimpleJWT/JWE.php
@@ -332,7 +332,7 @@ public function encrypt($keys, $kid = null, $format = self::COMPACT_FORMAT) {
      * (This method is separated from the rest of the {@link encrypt()}
      * function to enable testing.)
      * 
-     * @param int $length the length of the content encryption key, in bytes
+     * @param int<1, max> $length the length of the content encryption key, in bytes
      * @return string the generated content encryption key as a binary
      * string
      */

diff --git a/src/SimpleJWT/JWT.php b/src/SimpleJWT/JWT.php
@@ -155,12 +155,12 @@ public static function decode($token, $keys, $expected_alg, $kid = null, $skip_v
         // Check time, etc
         $time = time();
         if (isset($claims['nbf']) && !in_array('nbf', $skip_validation)) {
-            if (!is_numeric($claims['nbf'])) throw new InvalidTokenException('nbf claim is not an integer', InvalidTokenException::TOKEN_PARSE_ERROR);
+            if (!is_integer($claims['nbf'])) throw new InvalidTokenException('nbf claim is not an integer', InvalidTokenException::TOKEN_PARSE_ERROR);
             if ($time < $claims['nbf'] - self::$TIME_ALLOWANCE) throw new InvalidTokenException('Too early due to nbf claim', InvalidTokenException::TOO_EARLY_ERROR, null, $claims['nbf']);
         }
 
         if (isset($claims['exp']) && !in_array('exp', $skip_validation)) {
-            if (!is_numeric($claims['exp'])) throw new InvalidTokenException('exp claim is not an integer', InvalidTokenException::TOKEN_PARSE_ERROR);
+            if (!is_integer($claims['exp'])) throw new InvalidTokenException('exp claim is not an integer', InvalidTokenException::TOKEN_PARSE_ERROR);
             if ($time > $claims['exp'] + self::$TIME_ALLOWANCE) throw new InvalidTokenException('Too late due to exp claim', InvalidTokenException::TOO_LATE_ERROR, null, $claims['exp']);
         }
 

diff --git a/src/SimpleJWT/Keys/Key.php b/src/SimpleJWT/Keys/Key.php
@@ -64,13 +64,16 @@ abstract class Key {
      * @param string $format the format
      * @param string $password the password, if the key is password protected
      * @param string $alg the algorithm, if the key is password protected
+     * @throws KeyException if the key cannot be created
      */
     public function __construct($data = [], $format = 'php', $password = null, $alg = 'PBES2-HS256+A128KW') {
         switch ($format) {
             case 'php':
+                if (!is_array($data)) throw new KeyException('Incorrect key data format');
                 $this->data = $data;
                 break;
             case 'json':
+                if (!is_string($data)) throw new KeyException('Incorrect key data format - string expected');
                 $jwk = json_decode($data, true);
 
                 if (isset($jwk['ciphertext'])) {
@@ -80,6 +83,7 @@ public function __construct($data = [], $format = 'php', $password = null, $alg
                 }
                 break;
             case 'jwe':
+                if (!is_string($data)) throw new KeyException('Incorrect key data format - string expected');
                 $this->data = self::decrypt($data, $password, $alg);
         }
 

diff --git a/src/SimpleJWT/Keys/KeyFactory.php b/src/SimpleJWT/Keys/KeyFactory.php
@@ -108,6 +108,7 @@ static public function create($data, $format = null, $password = null, $alg = 'P
 
         // 2. Decode JSON
         if ($format == 'json') {
+            /* @var string $data */
             $json = json_decode($data, true);
             if (isset($json['ciphertext'])) {
                 $format = 'jwe';

diff --git a/src/SimpleJWT/Keys/KeySet.php b/src/SimpleJWT/Keys/KeySet.php
@@ -91,6 +91,7 @@ function toJWKS($password = null, $format = JWE::COMPACT_FORMAT) {
             return $key->getKeyData();
         }, $this->keys);
         $json = json_encode(['keys' => $result]);
+        assert($json !== false);
         if ($password == null) return $json;
 
         $keys = KeySet::createFromSecret($password, 'bin');
@@ -297,7 +298,9 @@ protected function find($criteria) {
         if (count($results) == 0) return null;
         if (count($results) == 1) {
             $kids = array_keys($results);
-            return [$this->getById($kids[0])];
+            $key = $this->getById($kids[0]);
+            assert($key != null);
+            return [$key];
         }
 
         // 4. Optional criteria
@@ -306,7 +309,9 @@ protected function find($criteria) {
         if (count($non_mandatory) == 0) {
             $kids = array_keys($results);
             return array_map(function($kid) {
-                return $this->getById($kid);
+                $key = $this->getById($kid);
+                assert($key != null);
+                return $key;
             }, $kids);
         }
 
@@ -323,7 +328,9 @@ protected function find($criteria) {
         arsort($results);
         $kids = array_keys($results);
         return array_map(function($kid) {
-            return $this->getById($kid);
+            $key = $this->getById($kid);
+            assert($key != null);
+            return $key;
         }, $kids);
     }
 

diff --git a/src/SimpleJWT/Keys/SymmetricKey.php b/src/SimpleJWT/Keys/SymmetricKey.php
@@ -68,20 +68,23 @@ public function __construct($data, $format, $password = null, $alg = 'PBES2-HS25
                 parent::__construct($data, $format, $password, $alg);
                 break;
             case 'base64url':
+                if (!is_string($data)) throw new KeyException('Incorrect key data format - string expected');
                 $jwk = [
                     'kty' => self::KTY,
                     'k' => $data
                 ];
                 parent::__construct($jwk);
                 break;
             case 'base64':
+                if (!is_string($data)) throw new KeyException('Incorrect key data format - string expected');
                 $jwk = [
                     'kty' => self::KTY,
                     'k' => trim(strtr($data, '+/', '-_'), '=')  // convert base64 to base64url
                 ];
                 parent::__construct($jwk);
                 break;
             case 'bin':
+                if (!is_string($data)) throw new KeyException('Incorrect key data format - string expected');
                 $jwk = [
                     'kty' => self::KTY,
                     'k' => Util::base64url_encode($data)

diff --git a/src/SimpleJWT/Util/Helper.php b/src/SimpleJWT/Util/Helper.php
@@ -144,7 +144,9 @@ function getJWTObject($keys, $expected_jwe_alg, $expected_jwt_alg, $dummy = null
         // @phpstan-ignore-next-line
         switch ($this->type) {
             case 'JWT':
-                return $this->getObject($keys, $expected_jwt_alg, $jwt_kid);
+                /** @var JWT $jwt */
+                $jwt = $this->getObject($keys, $expected_jwt_alg, $jwt_kid);
+                return $jwt;
             case 'JWE':
                 $jwe = JWE::decrypt($this->data, $keys, $expected_jwe_alg);
                 if ($jwe->getHeader('cty') != 'JWT') {

diff --git a/src/SimpleJWT/Util/Util.php b/src/SimpleJWT/Util/Util.php
@@ -106,7 +106,7 @@ static function packInt64($x) {
      * This function is retained for compatibility with earlier versions
      * of SimpleJWT.
      *
-     * @param int $num_bytes the number of bytes to generate
+     * @param int<1, max> $num_bytes the number of bytes to generate
      * @return string a string containing random bytes
      */
     static function random_bytes($num_bytes) {