Revamp error hierarchy

CHANGELOG.md

@@ -1,12 +1,13 @@
 # Changelog
 
-## [v3.2.1](https://github.com/jwt/ruby-jwt/tree/v3.2.1) (NEXT)
+## [v3.3.0](https://github.com/jwt/ruby-jwt/tree/v3.3.0) (NEXT)
 
-[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v3.2.0...v3.2.1)
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v3.2.0...v3.3.0)
 
 **Features:**
 
 - Allow a leeway to be given for the `iat` claim verification [#747](https://github.com/jwt/ruby-jwt/pull/747) - ([@denis1011101](https://github.com/denis1011101))
+- Revamp error hierarchy: introduce `JWT::Error`, `JWT::TokenError`, `JWT::MalformedTokenError`, `JWT::SignatureError`, `JWT::VerificationKeyError` and `JWT::ClaimValidationError` grouping classes. `JWT::DecodeError` is deprecated but keeps its meaning: every error class except `JWT::EncodeError` still inherits from it. An unusable verification key now raises `JWT::VerificationKeyError`, a subclass of `JWT::VerificationError`, so existing rescues keep working while callers can distinguish an unusable key from a signature that does not match. `RS*` and `PS*` verification now reject a key of the wrong type instead of letting a `NoMethodError` escape. Signing failures now consistently raise `JWT::EncodeError`: an ECDSA signing key with a mismatched or unsupported curve previously surfaced as `JWT::IncorrectAlgorithm` or `JWT::UnsupportedEcdsaCurve` from `JWT.encode`. Code wrapping `JWT.encode` in `rescue JWT::DecodeError` should rescue `JWT::Error` or `JWT::EncodeError` instead [#722](https://github.com/jwt/ruby-jwt/pull/722) ([@anakinj](https://github.com/anakinj))
 - Your contribution here
 
 **Fixes and enhancements:**

README.md

@@ -640,7 +640,7 @@ end
 
 begin
   JWT.decode(token, nil, true, { x5c: { root_certificates: root_certificates, crls: crls } })
-rescue JWT::DecodeError
+rescue JWT::TokenError
   # Handle error, e.g. x5c header certificate revoked or expired
 end
 ```
@@ -705,8 +705,8 @@ begin
   JWT.decode(token, nil, true, { algorithms: ['RS512'], jwks: jwks_loader })
 rescue JWT::JWKError
   # Handle problems with the provided JWKs
-rescue JWT::DecodeError
-  # Handle other decode related issues e.g. no kid in header, no matching public key found etc.
+rescue JWT::TokenError
+  # Handle other token related issues e.g. no kid in header, no matching public key found etc.
 end
 ```
 

lib/jwt/claims.rb

@@ -41,7 +41,7 @@ class << self
       # @param payload [Hash] the JWT payload.
       # @param options [Array] the options for verifying the claims.
       # @return [void]
-      # @raise [JWT::DecodeError] if any claim is invalid.
+      # @raise [JWT::ClaimValidationError] if any claim is invalid.
       def verify_payload!(payload, *options)
         Verifier.verify!(VerificationContext.new(payload: payload), *options)
       end

lib/jwt/claims/verifier.rb

@@ -33,8 +33,10 @@ def errors(context, *options)
           errors = []
           iterate_verifiers(*options) do |verifier, verifier_options|
             verify_one!(context, verifier, verifier_options)
-          rescue ::JWT::DecodeError => e
-            errors << Error.new(message: e.message)
+          rescue ::JWT::ClaimValidationError, ::JWT::MalformedTokenError => e
+            # A payload that cannot be decoded has no valid claims either, so the
+            # predicate API reports it instead of raising.
+            errors << JWT::Claims::Error.new(message: e.message)
           end
           errors
         end

lib/jwt/decode.rb

@@ -18,9 +18,9 @@ class Decode
     # @param verify [Boolean] whether to verify the token's signature.
     # @param options [Hash] additional options for decoding and verification.
     # @param keyfinder [Proc] an optional key finder block to dynamically find the key for verification.
-    # @raise [JWT::DecodeError] if decoding or verification fails.
+    # @raise [JWT::Error] if decoding or verification fails.
     def initialize(jwt, key, verify, options, &keyfinder)
-      raise JWT::DecodeError, 'Nil JSON web token' unless jwt
+      raise JWT::MalformedTokenError, 'Nil JSON web token' unless jwt
 
       @token = EncodedToken.new(jwt)
       @key = key
@@ -51,14 +51,14 @@ def decode_segments
     def verify_signature
       return if none_algorithm?
 
-      raise JWT::DecodeError, 'No verification key available' unless @key
+      raise JWT::SignatureError, 'No verification key available' unless @key
 
       token.verify_signature!(algorithm: allowed_and_valid_algorithms, key: @key)
     end
 
     def verify_algo
       raise JWT::IncorrectAlgorithm, 'An algorithm must be specified' if allowed_algorithms.empty?
-      raise JWT::DecodeError, 'Token header not a JSON object' unless valid_token_header?
+      raise JWT::MalformedTokenError, 'Token header not a JSON object' unless valid_token_header?
       raise JWT::IncorrectAlgorithm, 'Token is missing alg header' unless alg_in_header
       raise JWT::IncorrectAlgorithm, 'Expected a different algorithm' if allowed_and_valid_algorithms.empty?
     end
@@ -100,7 +100,7 @@ def find_key(&keyfinder)
       # key can be of type [string, nil, OpenSSL::PKey, Array]
       return key if key && !Array(key).empty?
 
-      raise JWT::DecodeError, 'No verification key available'
+      raise JWT::SignatureError, 'No verification key available'
     end
 
     def validate_segment_count!
@@ -109,7 +109,7 @@ def validate_segment_count!
       return if !@verify && segment_count == 2 # If no verifying required, the signature is not needed
       return if segment_count == 2 && none_algorithm?
 
-      raise JWT::DecodeError, 'Not enough or too many segments'
+      raise JWT::MalformedTokenError, 'Not enough or too many segments'
     end
 
     def none_algorithm?

lib/jwt/encoded_token.rb

@@ -63,10 +63,10 @@ def header
     # Returns the payload of the JWT token. Access requires the signature and claims to have been verified.
     #
     # @return [Hash] the payload.
-    # @raise [JWT::DecodeError] if the signature has not been verified.
+    # @raise [JWT::TokenError] if the signature has not been verified.
     def payload
-      raise JWT::DecodeError, 'Verify the token signature before accessing the payload' unless @signature_verified
-      raise JWT::DecodeError, 'Verify the token claims before accessing the payload' unless @claims_verified
+      raise JWT::TokenError, 'Verify the token signature before accessing the payload' unless @signature_verified
+      raise JWT::TokenError, 'Verify the token claims before accessing the payload' unless @claims_verified
 
       decoded_payload
     end
@@ -98,7 +98,7 @@ def signing_input
     # @param signature [Hash] the parameters for signature verification (see {#verify_signature!}).
     # @param claims [Array<Symbol>, Hash] the claims to verify (see {#verify_claims!}).
     # @return [nil]
-    # @raise [JWT::DecodeError] if the signature or claim verification fails.
+    # @raise [JWT::Error] if the signature or claim verification fails.
     def verify!(signature:, claims: nil)
       verify_signature!(**signature)
       claims.is_a?(Array) ? verify_claims!(*claims) : verify_claims!(claims)
@@ -152,7 +152,8 @@ def valid_signature?(algorithm: nil, key: nil, key_finder: nil)
 
     # Verifies the claims of the token.
     # @param options [Array<Symbol>, Hash] the claims to verify. By default, it checks the 'exp' claim.
-    # @raise [JWT::DecodeError] if the claims are invalid.
+    # @raise [JWT::ClaimValidationError] if the claims are invalid.
+    # @raise [JWT::MalformedTokenError] if the payload cannot be decoded, which happens before any claim is validated.
     def verify_claims!(*options)
       Claims::Verifier.verify!(ClaimsContext.new(self), *claims_options(options)).tap do
         @claims_verified = true
@@ -187,7 +188,7 @@ def claims_options(options)
     end
 
     def decode_payload
-      raise JWT::DecodeError, 'Encoded payload is empty' if encoded_payload == ''
+      raise JWT::MalformedTokenError, 'Encoded payload is empty' if encoded_payload == ''
 
       if unencoded_payload?
         verify_claims!(crit: ['b64'])
@@ -212,7 +213,7 @@ def parse_unencoded(segment)
     def parse(segment)
       JWT::JSON.parse(segment)
     rescue ::JSON::ParserError
-      raise JWT::DecodeError, 'Invalid segment encoding'
+      raise JWT::MalformedTokenError, 'Invalid segment encoding'
     end
 
     def decoded_payload

lib/jwt/error.rb

@@ -1,53 +1,77 @@
 # frozen_string_literal: true
 
 module JWT
+  # The base error class for all JWT errors.
+  class Error < StandardError; end
+
   # The EncodeError class is raised when there is an error encoding a JWT.
-  class EncodeError < StandardError; end
+  class EncodeError < Error; end
 
-  # The DecodeError class is raised when there is an error decoding a JWT.
-  class DecodeError < StandardError; end
+  # The historical grouping of every error that is not an encoding error. Every
+  # error class below is a descendant, so `rescue JWT::DecodeError` keeps its
+  # original meaning.
+  #
+  # @deprecated Use {JWT::Error}, {JWT::TokenError} or a more specific error class instead.
+  class DecodeError < Error; end
 
-  # The VerificationError class is raised when there is an error verifying a JWT.
-  class VerificationError < DecodeError; end
+  # The TokenError class is the base class for all errors related to token processing.
+  class TokenError < DecodeError; end
 
-  # The ExpiredSignature class is raised when the JWT signature has expired.
-  class ExpiredSignature < DecodeError; end
+  # The MalformedTokenError class is raised when the token is structurally invalid.
+  class MalformedTokenError < TokenError; end
 
-  # The IncorrectAlgorithm class is raised when the JWT algorithm is incorrect.
-  class IncorrectAlgorithm < DecodeError; end
+  # The Base64DecodeError class is raised when there is an error decoding a Base64-encoded string.
+  class Base64DecodeError < MalformedTokenError; end
 
-  # The ImmatureSignature class is raised when the JWT signature is immature.
-  class ImmatureSignature < DecodeError; end
+  # The SignatureError class is the base class for signature and algorithm related errors.
+  class SignatureError < TokenError; end
 
-  # The InvalidIssuerError class is raised when the JWT issuer is invalid.
-  class InvalidIssuerError < DecodeError; end
+  # The VerificationError class is raised when the signature of a token does not
+  # match the one calculated from the signing input.
+  class VerificationError < SignatureError; end
+
+  # The VerificationKeyError class is raised when the key or algorithm given for
+  # verification cannot be used, as opposed to a signature that does not match.
+  class VerificationKeyError < VerificationError; end
+
+  # The IncorrectAlgorithm class is raised when the JWT algorithm is incorrect.
+  class IncorrectAlgorithm < SignatureError; end
 
   # The UnsupportedEcdsaCurve class is raised when the ECDSA curve is unsupported.
   class UnsupportedEcdsaCurve < IncorrectAlgorithm; end
 
+  # The ClaimValidationError class is the base class for all claim validation errors.
+  class ClaimValidationError < TokenError; end
+
+  # The ExpiredSignature class is raised when the JWT token has expired.
+  class ExpiredSignature < ClaimValidationError; end
+
+  # The ImmatureSignature class is raised when the JWT token is not yet valid (nbf).
+  class ImmatureSignature < ClaimValidationError; end
+
+  # The InvalidIssuerError class is raised when the JWT issuer is invalid.
+  class InvalidIssuerError < ClaimValidationError; end
+
   # The InvalidIatError class is raised when the JWT issued at (iat) claim is invalid.
-  class InvalidIatError < DecodeError; end
+  class InvalidIatError < ClaimValidationError; end
 
   # The InvalidAudError class is raised when the JWT audience (aud) claim is invalid.
-  class InvalidAudError < DecodeError; end
+  class InvalidAudError < ClaimValidationError; end
 
   # The InvalidSubError class is raised when the JWT subject (sub) claim is invalid.
-  class InvalidSubError < DecodeError; end
+  class InvalidSubError < ClaimValidationError; end
 
   # The InvalidCritError class is raised when the JWT crit header is invalid.
-  class InvalidCritError < DecodeError; end
+  class InvalidCritError < ClaimValidationError; end
 
   # The InvalidJtiError class is raised when the JWT ID (jti) claim is invalid.
-  class InvalidJtiError < DecodeError; end
+  class InvalidJtiError < ClaimValidationError; end
 
   # The InvalidPayload class is raised when the JWT payload is invalid.
-  class InvalidPayload < DecodeError; end
+  class InvalidPayload < ClaimValidationError; end
 
   # The MissingRequiredClaim class is raised when a required claim is missing from the JWT.
-  class MissingRequiredClaim < DecodeError; end
-
-  # The Base64DecodeError class is raised when there is an error decoding a Base64-encoded string.
-  class Base64DecodeError < DecodeError; end
+  class MissingRequiredClaim < ClaimValidationError; end
 
   # The JWKError class is raised when there is an error with the JSON Web Key (JWK).
   class JWKError < DecodeError; end

lib/jwt/jwa.rb

@@ -37,7 +37,7 @@ def resolve_and_sort(algorithms:, preferred_algorithm:)
       # @api private
       def create_signer(algorithm:, key:)
         if key.is_a?(JWK::KeyBase)
-          validate_jwk_algorithms!(key, algorithm, DecodeError)
+          validate_jwk_algorithms!(key, algorithm, EncodeError)
 
           return key
         end
@@ -49,7 +49,7 @@ def create_signer(algorithm:, key:)
       def create_verifiers(algorithms:, keys:, preferred_algorithm:)
         jwks, other_keys = keys.partition { |key| key.is_a?(JWK::KeyBase) }
 
-        validate_jwk_algorithms!(jwks, algorithms, VerificationError)
+        validate_jwk_algorithms!(jwks, algorithms, VerificationKeyError)
 
         jwks + resolve_and_sort(algorithms: algorithms,
                                 preferred_algorithm: preferred_algorithm)

lib/jwt/jwa/ecdsa.rb

@@ -15,10 +15,8 @@ def sign(data:, signing_key:)
         raise_sign_error!("The given key is a #{signing_key.class}. It has to be an OpenSSL::PKey::EC instance") unless signing_key.is_a?(::OpenSSL::PKey::EC)
         raise_sign_error!('The given key is not a private key') unless signing_key.private?
 
-        curve_definition = curve_by_name(signing_key.group.curve_name)
-        key_algorithm = curve_definition[:algorithm]
-
-        raise IncorrectAlgorithm, "payload algorithm is #{alg} but #{key_algorithm} signing key was provided" if alg != key_algorithm
+        key_algorithm = signing_key_algorithm(signing_key)
+        raise_sign_error!("payload algorithm is #{alg} but #{key_algorithm} signing key was provided") if alg != key_algorithm
 
         asn1_to_raw(signing_key.dsa_sign_asn1(OpenSSL::Digest.new(digest).digest(data)), signing_key)
       end
@@ -95,6 +93,13 @@ def curve_by_name(name)
         self.class.curve_by_name(name)
       end
 
+      # Signing-side counterpart of {.curve_by_name}. An unsupported curve on the
+      # signing key is an encoding problem, so it raises a JWT::EncodeError.
+      def signing_key_algorithm(signing_key)
+        curve_name = signing_key.group.curve_name
+        NAMED_CURVES.fetch(curve_name) { raise_sign_error!("The ECDSA curve '#{curve_name}' is not supported") }[:algorithm]
+      end
+
       def raw_to_asn1(signature, private_key)
         byte_size = (private_key.group.degree + 7) / 8
         sig_bytes = signature[0..(byte_size - 1)]

lib/jwt/jwa/hmac.rb

@@ -21,15 +21,13 @@ def initialize(alg, digest)
       end
 
       def sign(data:, signing_key:)
-        ensure_valid_key!(signing_key)
-        validate_key_length!(signing_key)
+        validate_key!(signing_key) { |message| raise_sign_error!(message) }
 
         OpenSSL::HMAC.digest(digest.new, signing_key, data)
       end
 
       def verify(data:, signature:, verification_key:)
-        ensure_valid_key!(verification_key)
-        validate_key_length!(verification_key)
+        validate_key!(verification_key) { |message| raise_verify_error!(message) }
 
         SecurityUtils.secure_compare(signature, OpenSSL::HMAC.digest(digest.new, verification_key, data))
       end
@@ -42,18 +40,16 @@ def verify(data:, signature:, verification_key:)
 
       attr_reader :digest
 
-      def ensure_valid_key!(key)
-        raise_verify_error!('HMAC key expected to be a String') unless key.is_a?(String)
-        raise_verify_error!('HMAC key cannot be empty') if key.empty?
-      end
+      # Yields a message for the first problem found with the key. The caller
+      # raises it, so signing and verification failures keep their own error class.
+      def validate_key!(key)
+        yield 'HMAC key expected to be a String' unless key.is_a?(String)
+        yield 'HMAC key cannot be empty' if key.empty?
 
-      def validate_key_length!(key)
         return unless JWT.configuration.decode.enforce_hmac_key_length
 
         min_length = MIN_KEY_LENGTHS[alg]
-        return if key.bytesize >= min_length
-
-        raise_verify_error!("HMAC key must be at least #{min_length} bytes for #{alg} algorithm")
+        yield "HMAC key must be at least #{min_length} bytes for #{alg} algorithm" if key.bytesize < min_length
       end
 
       # Copy of https://github.com/rails/rails/blob/v7.0.3.1/activesupport/lib/active_support/security_utils.rb

lib/jwt/jwa/ps.rb

@@ -19,6 +19,8 @@ def sign(data:, signing_key:)
       end
 
       def verify(data:, signature:, verification_key:)
+        raise_verify_error!("The given key is a #{verification_key.class}. It has to be an OpenSSL::PKey::RSA instance") unless verification_key.is_a?(::OpenSSL::PKey::RSA)
+
         verification_key.verify_pss(digest_algorithm, signature, data, salt_length: :auto, mgf1_hash: digest_algorithm)
       rescue OpenSSL::PKey::PKeyError
         raise JWT::VerificationError, 'Signature verification raised'

lib/jwt/jwa/rsa.rb

@@ -19,6 +19,8 @@ def sign(data:, signing_key:)
       end
 
       def verify(data:, signature:, verification_key:)
+        raise_verify_error!("The given key is a #{verification_key.class}. It has to be an OpenSSL::PKey::RSA instance") unless verification_key.is_a?(::OpenSSL::PKey::RSA)
+
         verification_key.verify(OpenSSL::Digest.new(digest), signature, data)
       rescue OpenSSL::PKey::PKeyError
         raise JWT::VerificationError, 'Signature verification raised'

lib/jwt/jwa/signing_algorithm.rb

@@ -35,7 +35,7 @@ def verify(*)
       end
 
       def raise_verify_error!(message)
-        raise(DecodeError.new(message).tap { |e| e.set_backtrace(caller(1)) })
+        raise(VerificationKeyError.new(message).tap { |e| e.set_backtrace(caller(1)) })
       end
 
       def raise_sign_error!(message)

lib/jwt/jwa/unsupported.rb

@@ -12,7 +12,7 @@ def sign(*)
         end
 
         def verify(*)
-          raise JWT::VerificationError, 'Algorithm not supported'
+          raise_verify_error!('Algorithm not supported')
         end
       end
     end