Add typehinting on methods

kelvinmo · Jan 15, 2024 · c1ee3a5 · c1ee3a5
1 parent 76851bd
commit c1ee3a5
Show file tree

Hide file tree

Showing 39 changed files with 239 additions and 222 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@ All notable changes to this project will be documented in this file.
   `InvalidArgumentException`
 - Changed: `JWT` and `JWE` methods now check for validity of
   algorithm classes
+- Changed: Additional type hinting on public API methods
 - Removed: Support for PHP 7.2
 
 ## 0.8.1

diff --git a/src/SimpleJWT/Crypt/AlgorithmFactory.php b/src/SimpleJWT/Crypt/AlgorithmFactory.php
@@ -87,7 +87,7 @@ class AlgorithmFactory {
      * use
      * @return AlgorithmInterface the algorithm
      */
-    static public function create($alg, $use = null) {
+    static public function create(string $alg, ?string $use = null): AlgorithmInterface {
         if (($use != null) && !isset(self::$use_map[$use])) throw new \InvalidArgumentException('Invalid use');
 
         foreach (self::$alg_map as $regex => $cls) {
@@ -116,7 +116,7 @@ static public function create($alg, $use = null) {
      * @param string $use the use
      * @return array<string> an array of algorithms
      */
-    static public function getSupportedAlgs($use) {
+    static public function getSupportedAlgs(string $use): array {
         $results = [];
 
         if (!isset(self::$use_map[$use])) throw new \InvalidArgumentException('Invalid use');

diff --git a/src/SimpleJWT/Crypt/AlgorithmInterface.php b/src/SimpleJWT/Crypt/AlgorithmInterface.php
@@ -56,7 +56,7 @@ interface AlgorithmInterface {
      *
      * @return string|null the algorithm
      */
-    public function getAlg();
+    public function getAlg(): ?string;
 
     /**
      * Get `alg` or `enc` values supported by this class.
@@ -69,7 +69,7 @@ public function getAlg();
      *
      * @return array<string> an array of supported algorithms
      */
-    public function getSupportedAlgs();
+    public function getSupportedAlgs(): array;
 }
 
 ?>
diff --git a/src/SimpleJWT/Crypt/BaseAlgorithm.php b/src/SimpleJWT/Crypt/BaseAlgorithm.php
@@ -66,7 +66,7 @@ abstract class BaseAlgorithm implements AlgorithmInterface {
      * @throws \UnexpectedValueException if the `$alg` parameter is not supported
      * by this class
      */
-    protected function __construct($alg = null) {
+    protected function __construct(?string $alg = null) {
         if (($alg != null) && !in_array($alg, $this->getSupportedAlgs())) throw new \UnexpectedValueException('Algorithm not supported: ' . $alg);
         $this->alg = $alg;
     }
@@ -76,7 +76,7 @@ protected function __construct($alg = null) {
      *
      * @return string|null the algorithm
      */
-    public function getAlg() {
+    public function getAlg(): ?string {
         return $this->alg;
     }
 
@@ -99,7 +99,7 @@ public function getAlg() {
      * @param array<string, mixed>|string $args the criteria
      * @return KeyInterface|null the found key, or null
      */
-    protected function selectKey($keys, ...$args) {
+    protected function selectKey(KeySet $keys, ...$args): ?KeyInterface {
         $criteria = $this->getKeyCriteria();
 
         foreach ($args as $arg) {
@@ -119,7 +119,7 @@ protected function selectKey($keys, ...$args) {
      *
      * @return array<string, mixed> the key selection criteria
      */
-    abstract public function getKeyCriteria();
+    abstract public function getKeyCriteria(): array;
 }
 
 ?>
diff --git a/src/SimpleJWT/Crypt/Encryption/AESCBC_HMACSHA2.php b/src/SimpleJWT/Crypt/Encryption/AESCBC_HMACSHA2.php
@@ -52,14 +52,14 @@ class AESCBC_HMACSHA2 extends BaseAlgorithm implements EncryptionAlgorithm {
         'A256CBC-HS512' => ['cipher' => 'AES-256-CBC', 'hash' => 'sha512', 'key' => 64, 'tag' => 32],
     ];
 
-    public function __construct($alg) {
+    public function __construct(?string $alg) {
         parent::__construct($alg);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function getSupportedAlgs() {
+    public function getSupportedAlgs(): array {
         $ciphers = array_map('strtoupper', openssl_get_cipher_methods());
         $hashes = hash_algos();
         $results = [];
@@ -76,14 +76,14 @@ public function getSupportedAlgs() {
     /**
      * {@inheritdoc}
      */
-    public function getKeyCriteria() {
+    public function getKeyCriteria(): array {
         return ['kty' => 'oct', '@use' => 'enc', '@key_ops' => ['encrypt', 'decrypt']];
     }
 
     /**
      * {@inheritdoc}
      */
-    public function encryptAndSign($plaintext, $cek, $additional, $iv) {
+    public function encryptAndSign(string $plaintext, string $cek, string $additional, ?string $iv): array {
         $params = self::$alg_params[$this->getAlg()];
 
         if (strlen($cek) != $this->getCEKSize() / 8) throw new CryptException('Incorrect key length');
@@ -120,7 +120,7 @@ public function encryptAndSign($plaintext, $cek, $additional, $iv) {
     /**
      * {@inheritdoc}
      */
-    public function decryptAndVerify($ciphertext, $tag, $cek, $additional, $iv) {
+    public function decryptAndVerify(string $ciphertext, string $tag, string $cek, string $additional, string $iv): string {
         $params = self::$alg_params[$this->getAlg()];
 
         if (strlen($cek) != $this->getCEKSize() / 8) throw new CryptException('Incorrect key length');

diff --git a/src/SimpleJWT/Crypt/Encryption/AESGCM.php b/src/SimpleJWT/Crypt/Encryption/AESGCM.php
@@ -55,14 +55,14 @@ class AESGCM extends BaseAlgorithm implements EncryptionAlgorithm {
     /** Size of the authentication tag in bits */
     const TAG_SIZE = 128;
 
-    public function __construct($alg) {
+    public function __construct(?string $alg) {
         parent::__construct($alg);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function getSupportedAlgs() {
+    public function getSupportedAlgs(): array {
         if (!version_compare(PHP_VERSION, '7.1', '>=')) return [];
 
         $ciphers = array_map('strtolower', openssl_get_cipher_methods());
@@ -80,14 +80,14 @@ public function getSupportedAlgs() {
     /**
      * {@inheritdoc}
      */
-    public function getKeyCriteria() {
+    public function getKeyCriteria(): array {
         return ['kty' => 'oct', '@use' => 'enc', '@key_ops' => ['encrypt', 'decrypt']];
     }
 
     /**
      * {@inheritdoc}
      */
-    public function encryptAndSign($plaintext, $cek, $additional, $iv) {
+    public function encryptAndSign(string $plaintext, string $cek, string $additional, ?string $iv): array {
         $params = self::$alg_params[$this->getAlg()];
 
         if (strlen($cek) != $this->getCEKSize() / 8) throw new CryptException('Incorrect key length');
@@ -116,7 +116,7 @@ public function encryptAndSign($plaintext, $cek, $additional, $iv) {
     /**
      * {@inheritdoc}
      */
-    public function decryptAndVerify($ciphertext, $tag, $cek, $additional, $iv) {
+    public function decryptAndVerify(string $ciphertext, string $tag, string $cek, string $additional, string $iv): string {
         $params = self::$alg_params[$this->getAlg()];
 
         if (strlen($cek) != $this->getCEKSize() / 8) throw new CryptException('Incorrect key length');

diff --git a/src/SimpleJWT/Crypt/Encryption/EncryptionAlgorithm.php b/src/SimpleJWT/Crypt/Encryption/EncryptionAlgorithm.php
@@ -55,7 +55,7 @@ interface EncryptionAlgorithm extends AlgorithmInterface {
      * `iv` (the initialisation vector), with all values as base64url encoded strings
      * @throws CryptException if there is an error in the cryptographic process
      */
-    public function encryptAndSign($plaintext, $cek, $additional, $iv);
+    public function encryptAndSign(string $plaintext, string $cek, string $additional, ?string $iv): array;
 
     /**
      * Decrypts ciphertext and verifies the authentication tag.
@@ -72,7 +72,7 @@ public function encryptAndSign($plaintext, $cek, $additional, $iv);
      * @throws CryptException if there is an error in the cryptographic process, including
      * if the authentication tag does not match
      */
-    public function decryptAndVerify($ciphertext, $tag, $cek, $additional, $iv);
+    public function decryptAndVerify(string $ciphertext, string $tag, string $cek, string $additional, string $iv): string;
 
     /**
      * Returns the required size of the content encryption key for this algorithm.

diff --git a/src/SimpleJWT/Crypt/KeyManagement/AESGCMKeyWrap.php b/src/SimpleJWT/Crypt/KeyManagement/AESGCMKeyWrap.php
@@ -38,6 +38,7 @@
 use SimpleJWT\Crypt\BaseAlgorithm;
 use SimpleJWT\Crypt\CryptException;
 use SimpleJWT\Crypt\Encryption\AESGCM;
+use SimpleJWT\Keys\KeySet;
 use SimpleJWT\Keys\SymmetricKey;
 use SimpleJWT\Util\Util;
 
@@ -50,17 +51,17 @@ class AESGCMKeyWrap extends BaseAlgorithm implements KeyEncryptionAlgorithm {
     /** @var AESGCM $aesgcm */
     private $aesgcm;
 
-    public function __construct($alg) {
+    public function __construct(?string $alg) {
         $this->aesgcm = new AESGCM(substr($alg, 0, -2));
         parent::__construct($alg);
     }
 
-    public function getSupportedAlgs() {
+    public function getSupportedAlgs(): array {
         $aesgcm_algs = $this->aesgcm->getSupportedAlgs();
         return array_map(function ($alg) { return $alg . 'KW'; }, $aesgcm_algs);
     }
 
-    public function getKeyCriteria() {
+    public function getKeyCriteria(): array {
         return [
             'kty' => 'oct',
             '~alg' => $this->getAlg(),
@@ -72,7 +73,7 @@ public function getKeyCriteria() {
     /**
      * {@inheritdoc}
      */
-    public function encryptKey($cek, $keys, &$headers, $kid = null) {
+    public function encryptKey(string $cek, KeySet $keys, array &$headers, ?string $kid = null): string {
         /** @var SymmetricKey $key */
         $key = $this->selectKey($keys, $kid);
         if ($key == null) {
@@ -89,7 +90,7 @@ public function encryptKey($cek, $keys, &$headers, $kid = null) {
     /**
      * {@inheritdoc}
      */
-    public function decryptKey($encrypted_key, $keys, $headers, $kid = null) {
+    public function decryptKey(string $encrypted_key, KeySet $keys, array $headers, ?string $kid = null): string {
         /** @var SymmetricKey $key */
         $key = $this->selectKey($keys, $kid);
         if ($key == null) {
@@ -110,7 +111,7 @@ public function decryptKey($encrypted_key, $keys, $headers, $kid = null) {
      *
      * @return string the initialisation vector as a binary string
      */
-    protected function generateIV() {
+    protected function generateIV(): string {
         /** @var int<1, max> $len */
         $len = intval($this->aesgcm->getIVSize() / 8);
         return Util::random_bytes($len);

diff --git a/src/SimpleJWT/Crypt/KeyManagement/AESKeyWrap.php b/src/SimpleJWT/Crypt/KeyManagement/AESKeyWrap.php
@@ -39,6 +39,7 @@
 use SimpleJWT\Crypt\CryptException;
 use SimpleJWT\Util\Util;
 use SimpleJWT\Keys\KeyInterface;
+use SimpleJWT\Keys\KeySet;
 use SimpleJWT\Keys\SymmetricKey;
 
 /**
@@ -58,14 +59,14 @@ class AESKeyWrap extends BaseAlgorithm implements KeyEncryptionAlgorithm {
         'A256KW' => ['cipher' => 'AES-256-ECB', 'key' => 32],
     ];
 
-    public function __construct($alg) {
+    public function __construct(?string $alg) {
         parent::__construct($alg);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function getSupportedAlgs() {
+    public function getSupportedAlgs(): array {
         $ciphers = array_map('strtoupper', openssl_get_cipher_methods());
         $results = [];
 
@@ -81,7 +82,7 @@ public function getSupportedAlgs() {
     /**
      * {@inheritdoc}
      */
-    public function getKeyCriteria() {
+    public function getKeyCriteria(): array {
         $alg = $this->getAlg();
         $size = self::$alg_params[$alg]['key'] * 8;
         return [
@@ -96,7 +97,7 @@ public function getKeyCriteria() {
     /**
      * {@inheritdoc}
      */
-    public function encryptKey($cek, $keys, &$headers, $kid = null) {
+    public function encryptKey(string $cek, KeySet $keys, array &$headers, ?string $kid = null): string {
         /** @var SymmetricKey $key */
         $key = $this->selectKey($keys, $kid);
         if ($key == null) {
@@ -133,7 +134,7 @@ public function encryptKey($cek, $keys, &$headers, $kid = null) {
     /**
      * {@inheritdoc}
      */
-    public function decryptKey($encrypted_key, $keys, $headers, $kid = null) {
+    public function decryptKey(string $encrypted_key, KeySet $keys, array $headers, ?string $kid = null): string {
         /** @var SymmetricKey $key */
         $key = $this->selectKey($keys, $kid);
         if ($key == null) {
@@ -173,7 +174,7 @@ public function decryptKey($encrypted_key, $keys, $headers, $kid = null) {
      * @param string $x the value
      * @return string the most significant half
      */
-    protected function msb($x) {
+    protected function msb(string $x): string {
         return substr($x, 0, (int) (strlen($x) / 2));
     }
 
@@ -183,7 +184,7 @@ protected function msb($x) {
      * @param string $x the value
      * @return string the least significant half
      */
-    protected function lsb($x) {
+    protected function lsb(string $x): string {
         return substr($x, (int) (strlen($x) / 2));
     }
 

diff --git a/src/SimpleJWT/Crypt/KeyManagement/AESKeyWrapTrait.php b/src/SimpleJWT/Crypt/KeyManagement/AESKeyWrapTrait.php
@@ -57,7 +57,7 @@ trait AESKeyWrapTrait {
      * @param string $alg the AES key wrap algorithm parameter
      * @return void
      */
-    protected function initAESKW($alg = null) {
+    protected function initAESKW(?string $alg = null) {
         if ($alg == null) {
             $this->aeskw = new AESKeyWrap(null);
         } else {
@@ -70,7 +70,7 @@ protected function initAESKW($alg = null) {
      * 
      * @return array<string> an array of AES Key Wrap algorithms
      */
-    protected function getAESKWAlgs() {
+    protected function getAESKWAlgs(): array {
         return $this->aeskw->getSupportedAlgs();
     }
 
@@ -79,7 +79,7 @@ protected function getAESKWAlgs() {
      *
      * @return int the key size, in bits
      */
-    protected function getAESKWKeySize() {
+    protected function getAESKWKeySize(): int {
         $criteria = $this->aeskw->getKeyCriteria();
         return $criteria[KeyInterface::SIZE_PROPERTY];
     }
@@ -92,7 +92,7 @@ protected function getAESKWKeySize() {
      * @param array<string, mixed> &$headers the JWE header, which can be modified
      * @return string the wrapped key as a binary string
      */
-    protected function wrapKey($plain_key, $wrapping_key, &$headers) {
+    protected function wrapKey(string $plain_key, string $wrapping_key, array &$headers): string {
         $keys = $this->createKeySet($wrapping_key);
         return $this->aeskw->encryptKey($plain_key, $keys, $headers);
     }
@@ -105,7 +105,7 @@ protected function wrapKey($plain_key, $wrapping_key, &$headers) {
      * @param array<string, mixed> $headers the JWE header, which can be modified
      * @return string the unwrapped key as a binary string
      */
-    protected function unwrapKey($encrypted_key, $unwrapping_key, $headers) {
+    protected function unwrapKey(string $encrypted_key, string $unwrapping_key, array $headers): string {
         $keys = $this->createKeySet($unwrapping_key);
         return $this->aeskw->decryptKey($encrypted_key, $keys, $headers);
     }
@@ -114,7 +114,7 @@ protected function unwrapKey($encrypted_key, $unwrapping_key, $headers) {
      * @param string $key
      * @return KeySet
      */
-    private function createKeySet($key) {
+    private function createKeySet(string $key): KeySet {
         $keys = new KeySet();
         $keys->add(new SymmetricKey($key, 'bin'));
         return $keys;
@@ -125,7 +125,7 @@ private function createKeySet($key) {
      * 
      * @return AESKeyWrap the underlying AES key wrap algorithm
      */
-    public function getAESKW() {
+    public function getAESKW(): AESKeyWrap {
         return $this->aeskw;
     }
 }