fix(core): keep the cause of a load or verification failure

The loaders, the verifier, the decrypter and the serializer managers all
swallowed the exception explaining why a token could not be used, and the
caller was left with a bare "Unable to load and verify the token." with no
previous exception.

The last error met along the way is now chained as the previous exception. The
per-key failures of JWSVerifier and JWEDecrypter, which cannot throw without
changing the return semantics, are reported through a callable accepted as an
additional argument; it will become part of the signature in 5.0.0.

Closes #681

Author: Spomky

src/Library/Encryption/JWEDecrypter.php

@@ -19,6 +19,8 @@
 use Jose\Component\Encryption\Algorithm\KeyEncryptionAlgorithm;
 use Throwable;
 use function count;
+use function func_num_args;
+use function is_callable;
 use function is_string;
 use function sprintf;
 use function strlen;
@@ -80,6 +82,12 @@ public function decryptUsingKey(JWE &$jwe, JWK $jwk, int $recipient, ?JWK $sende
     /**
      * This method will try to decrypt the given JWE and recipient using a JWKSet.
      *
+     * A key that cannot be used, or that does not decrypt the recipient, does not abort the decryption: the next key of
+     * the key set is tried and the reason of the failure is otherwise lost. A callable is accepted as an additional
+     * argument to observe those failures; it is called with every discarded Throwable. That argument is not part of the
+     * signature yet (it will be in 5.0.0) and is read with func_num_args()/func_get_arg(5), so that classes extending
+     * this one remain compatible.
+     *
      * @param JWE $jwe A JWE object to decrypt
      * @param JWKSet $jwkset The key set used to decrypt the input
      * @param JWK $jwk The key used to decrypt the token in case of success
@@ -92,6 +100,10 @@ public function decryptUsingKeySet(
         ?JWK &$jwk = null,
         ?JWK $senderKey = null
     ): bool {
+        $onError = func_num_args() >= 6 ? func_get_arg(5) : null;
+        if (! is_callable($onError)) {
+            $onError = null;
+        }
         if ($jwkset->count() === 0) {
             throw new InvalidArgumentException('No key in the key set.');
         }
@@ -102,7 +114,7 @@ public function decryptUsingKeySet(
             throw new InvalidArgumentException('The JWE does not contain any recipient.');
         }
 
-        $plaintext = $this->decryptRecipientKey($jwe, $jwkset, $recipient, $jwk, $senderKey);
+        $plaintext = $this->decryptRecipientKey($jwe, $jwkset, $recipient, $jwk, $senderKey, $onError);
         if ($plaintext !== null) {
             $jwe = $jwe->withPayload($plaintext);
 
@@ -120,13 +132,16 @@ public function decryptUsingKeySet(
      *
      * The shared unprotected header is never a valid source for "alg" and "enc": it is not covered by the
      * AAD and, unlike the per-recipient header, nothing requires those parameters to be located there.
+     *
+     * @param callable(Throwable): void|null $onError
      */
     private function decryptRecipientKey(
         JWE $jwe,
         JWKSet $jwkset,
         int $i,
         ?JWK &$successJwk = null,
-        ?JWK $senderKey = null
+        ?JWK $senderKey = null,
+        ?callable $onError = null
     ): ?string {
         $recipient = $jwe->getRecipient($i);
         $sharedProtectedHeader = $jwe->getSharedProtectedHeader();
@@ -167,8 +182,11 @@ private function decryptRecipientKey(
                 $successJwk = $recipientKey;
 
                 return $payload;
-            } catch (Throwable) {
-                // We do nothing, we continue with other keys
+            } catch (Throwable $throwable) {
+                if ($onError !== null) {
+                    $onError($throwable);
+                }
+
                 continue;
             }
         }

src/Library/Encryption/JWELoader.php

@@ -61,35 +61,52 @@ public function loadAndDecryptWithKey(string $token, JWK $key, ?int &$recipient)
     /**
      * This method will try to load and decrypt the given token using a JWKSet. If succeeded, the methods will populate
      * the $recipient variable and returns the JWE.
+     *
+     * The failure semantics are unchanged, but the last error met along the way - a serialization failure, a rejected
+     * header or a key that could not decrypt the recipient - is chained as the previous exception, so that the reason
+     * of the failure remains available to the caller.
      */
     public function loadAndDecryptWithKeySet(string $token, JWKSet $keyset, ?int &$recipient): JWE
     {
+        $lastError = null;
         try {
             $jwe = $this->serializerManager->unserialize($token);
             $nbRecipients = $jwe->countRecipients();
             for ($i = 0; $i < $nbRecipients; ++$i) {
-                if ($this->processRecipient($jwe, $keyset, $i)) {
+                if ($this->processRecipient($jwe, $keyset, $i, $lastError)) {
                     $recipient = $i;
 
                     return $jwe;
                 }
             }
-        } catch (Throwable) {
-            // Nothing to do. Exception thrown just after
+        } catch (Throwable $throwable) {
+            $lastError = $throwable;
         }
 
-        throw new RuntimeException('Unable to load and decrypt the token.');
+        throw new RuntimeException('Unable to load and decrypt the token.', 0, $lastError);
     }
 
-    private function processRecipient(JWE &$jwe, JWKSet $keyset, int $recipient): bool
+    private function processRecipient(JWE &$jwe, JWKSet $keyset, int $recipient, ?Throwable &$lastError): bool
     {
         try {
             if ($this->headerCheckerManager !== null) {
                 $this->headerCheckerManager->check($jwe, $recipient);
             }
+            $jwk = null;
+
+            return $this->jweDecrypter->decryptUsingKeySet(
+                $jwe,
+                $keyset,
+                $recipient,
+                $jwk,
+                null,
+                static function (Throwable $throwable) use (&$lastError): void {
+                    $lastError = $throwable;
+                }
+            );
+        } catch (Throwable $throwable) {
+            $lastError = $throwable;
 
-            return $this->jweDecrypter->decryptUsingKeySet($jwe, $keyset, $recipient);
-        } catch (Throwable) {
             return false;
         }
     }

src/Library/Encryption/Serializer/JWESerializerManager.php

@@ -50,23 +50,29 @@ public function serialize(string $name, JWE $jws, ?int $recipientIndex = null):
     /**
      * Loads data and return a JWE object. Throws an exception if none of the serializer was able to convert the input.
      *
+     * When no serializer is able to convert the input, the exception thrown by the last one is chained as the previous
+     * exception, so that the actual reason of the failure remains available to the caller.
+     *
      * @param string $input A string that represents a JWE
      * @param string|null $name the name of the serializer if the input is unserialized
      */
     public function unserialize(string $input, ?string &$name = null): JWE
     {
+        $lastError = null;
         foreach ($this->serializers as $serializer) {
             try {
                 $jws = $serializer->unserialize($input);
                 $name = $serializer->name();
 
                 return $jws;
-            } catch (InvalidArgumentException) {
+            } catch (InvalidArgumentException $invalidArgumentException) {
+                $lastError = $invalidArgumentException;
+
                 continue;
             }
         }
 
-        throw new InvalidArgumentException('Unsupported input.');
+        throw new InvalidArgumentException('Unsupported input.', 0, $lastError);
     }
 
     /**

src/Library/Signature/JWSLoader.php

@@ -61,39 +61,61 @@ public function loadAndVerifyWithKey(string $token, JWK $key, ?int &$signature,
     /**
      * This method will try to load and verify the token using the given key set. It returns a JWS and will populate the
      * $signature variable in case of success, otherwise an exception is thrown.
+     *
+     * The failure semantics are unchanged, but the last error met along the way - a serialization failure, a rejected
+     * header or a key that could not verify the signature - is chained as the previous exception, so that the reason of
+     * the failure remains available to the caller.
      */
     public function loadAndVerifyWithKeySet(
         string $token,
         JWKSet $keyset,
         ?int &$signature,
         ?string $payload = null
     ): JWS {
+        $lastError = null;
         try {
             $jws = $this->serializerManager->unserialize($token);
             $nbSignatures = $jws->countSignatures();
             for ($i = 0; $i < $nbSignatures; ++$i) {
-                if ($this->processSignature($jws, $keyset, $i, $payload)) {
+                if ($this->processSignature($jws, $keyset, $i, $payload, $lastError)) {
                     $signature = $i;
 
                     return $jws;
                 }
             }
-        } catch (Throwable) {
-            // Nothing to do. Exception thrown just after
+        } catch (Throwable $throwable) {
+            $lastError = $throwable;
         }
 
-        throw new Exception('Unable to load and verify the token.');
+        throw new Exception('Unable to load and verify the token.', 0, $lastError);
     }
 
-    private function processSignature(JWS $jws, JWKSet $keyset, int $signature, ?string $payload): bool
-    {
+    private function processSignature(
+        JWS $jws,
+        JWKSet $keyset,
+        int $signature,
+        ?string $payload,
+        ?Throwable &$lastError
+    ): bool {
         try {
             if ($this->headerCheckerManager !== null) {
                 $this->headerCheckerManager->check($jws, $signature);
             }
+            $jwk = null;
+
+            return $this->jwsVerifier->verifyWithKeySet(
+                $jws,
+                $keyset,
+                $signature,
+                $payload,
+                $jwk,
+                static function (Throwable $throwable) use (&$lastError): void {
+                    $lastError = $throwable;
+                }
+            );
+        } catch (Throwable $throwable) {
+            $lastError = $throwable;
 
-            return $this->jwsVerifier->verifyWithKeySet($jws, $keyset, $signature, $payload);
-        } catch (Throwable) {
             return false;
         }
     }

src/Library/Signature/JWSVerifier.php

@@ -14,6 +14,8 @@
 use Jose\Component\Signature\Algorithm\MacAlgorithm;
 use Jose\Component\Signature\Algorithm\SignatureAlgorithm;
 use Throwable;
+use function func_num_args;
+use function is_callable;
 use function sprintf;
 
 class JWSVerifier
@@ -48,6 +50,12 @@ public function verifyWithKey(JWS $jws, JWK $jwk, int $signature, ?string $detac
      * This method will try to verify the JWS object using the given key set and for the given signature. It returns
      * true if the signature is verified, otherwise false.
      *
+     * A key that cannot be used, or that does not verify the signature, does not abort the verification: the next key
+     * of the key set is tried and the reason of the failure is otherwise lost. A callable is accepted as an additional
+     * argument to observe those failures; it is called with every discarded Throwable. That argument is not part of the
+     * signature yet (it will be in 5.0.0) and is read with func_num_args()/func_get_arg(5), so that classes extending
+     * this one remain compatible.
+     *
      * @param JWS $jws A JWS object
      * @param JWKSet $jwkset The signature will be verified using keys in the key set
      * @param JWK $jwk The key used to verify the signature in case of success
@@ -62,6 +70,10 @@ public function verifyWithKeySet(
         ?string $detachedPayload = null,
         ?JWK &$jwk = null
     ): bool {
+        $onError = func_num_args() >= 6 ? func_get_arg(5) : null;
+        if (! is_callable($onError)) {
+            $onError = null;
+        }
         if ($jwkset->count() === 0) {
             throw new InvalidArgumentException('There is no key in the key set.');
         }
@@ -71,15 +83,19 @@ public function verifyWithKeySet(
         $this->checkPayload($jws, $detachedPayload);
         $signature = $jws->getSignature($signatureIndex);
 
-        return $this->verifySignature($jws, $jwkset, $signature, $detachedPayload, $jwk);
+        return $this->verifySignature($jws, $jwkset, $signature, $detachedPayload, $jwk, $onError);
     }
 
+    /**
+     * @param callable(Throwable): void|null $onError
+     */
     private function verifySignature(
         JWS $jws,
         JWKSet $jwkset,
         Signature $signature,
         ?string $detachedPayload = null,
-        ?JWK &$successJwk = null
+        ?JWK &$successJwk = null,
+        ?callable $onError = null
     ): bool {
         $input = $this->getInputToVerify($jws, $signature, $detachedPayload);
         $algorithm = $this->getAlgorithm($signature);
@@ -92,8 +108,11 @@ private function verifySignature(
 
                     return true;
                 }
-            } catch (Throwable) {
-                // We do nothing, we continue with other keys
+            } catch (Throwable $throwable) {
+                if ($onError !== null) {
+                    $onError($throwable);
+                }
+
                 continue;
             }
         }

src/Library/Signature/Serializer/JWSSerializerManager.php

@@ -48,23 +48,29 @@ public function serialize(string $name, JWS $jws, ?int $signatureIndex = null):
     /**
      * Loads data and return a JWS object.
      *
+     * When no serializer is able to convert the input, the exception thrown by the last one is chained as the previous
+     * exception, so that the actual reason of the failure remains available to the caller.
+     *
      * @param string $input A string that represents a JWS
      * @param string|null $name the name of the serializer if the input is unserialized
      */
     public function unserialize(string $input, ?string &$name = null): JWS
     {
+        $lastError = null;
         foreach ($this->serializers as $serializer) {
             try {
                 $jws = $serializer->unserialize($input);
                 $name = $serializer->name();
 
                 return $jws;
-            } catch (InvalidArgumentException) {
+            } catch (InvalidArgumentException $invalidArgumentException) {
+                $lastError = $invalidArgumentException;
+
                 continue;
             }
         }
 
-        throw new InvalidArgumentException('Unsupported input.');
+        throw new InvalidArgumentException('Unsupported input.', 0, $lastError);
     }
 
     private function add(JWSSerializer $serializer): void