Add jws.IsVerificationError (#1049)

* Add jws.IsVerificationError

* tweak document

Changes

@@ -4,6 +4,12 @@ Changes
 v2 has many incompatibilities with v1. To see the full list of differences between
 v1 and v2, please read the Changes-v2.md file (https://github.com/lestrrat-go/jwx/blob/develop/v2/Changes-v2.md)
 
+v2.0.19 UNRELEASED
+[New Features]
+  * [jws] Added jws.IsVerificationError to check if the error returned by `jws.Verify`
+    was caused by actual verification step or something else, for example, while fetching
+    a key from datasource
+
 v2.0.18 03 Dec 2023
 [Security Fixes]
   * [jwe] A large number in p2c parameter for PBKDF2 based encryptions could cause a DoS attack,

jws/jws.go

@@ -477,6 +477,19 @@ func (e *verifyError) As(target interface{}) bool {
 	return false
 }
 
+// IsVerificationError returns true if the error came from the verification part of the
+// jws.Verify function, allowing you to check if the error is a result of actual
+// verification failure.
+//
+// For example, if the error happened while fetching a key
+// from a datasource, feeding that error should to this function return false, whereas
+// a failure to compute the signature for whatever reason would be a verification error
+// and returns true.
+func IsVerificationError(err error) bool {
+	var ve *verifyError
+	return errors.As(err, &ve)
+}
+
 // get the value of b64 header field.
 // If the field does not exist, returns true (default)
 // Otherwise return the value specified by the header field.