jwt 3.2.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bb396cd444a952a2c732720675f053ce5c4557978acf54acc0753a98b81f402
-  data.tar.gz: deeb4ea2635a1620f8dab94b4b7b2d6b7a01087ea0f45b9f79b408c9a7b23c25
+  metadata.gz: 9b0bbac64c8b97deb791cc74f29243c6c04cbc2c3a63904484259c5379a2650f
+  data.tar.gz: 0252d7993ad937c9cb961d4f2ff4ce9cef9fc7b503fadb2ba4e85923752ed6b4
 SHA512:
-  metadata.gz: d9913bf66785a88c127148c5a4a3fd6dcd9a28820f53c20635ab5469cebdfb159366566ba8b198154c9a541927224c11e75ced5c9f5b69c1d32a9e01764ca0dd
-  data.tar.gz: e2d4765fa99b67229f3204b917aea480a1d4027c23a216f307f92d6ffa8acd049b72071377d7e0c4c8fcba5eb845f9751c944dbc87e9a597020665859edd40c1
+  metadata.gz: cdef3e40a9879182bd028df5dad15676280ba567839a12d3ca31f9569c9b1d44b02f959b256e1d95d1c9d3e882a3ab6d944dbcce0f22d31a0658cd5589e14917
+  data.tar.gz: 88f3879e2061b072b15c1a001ff7c62e674fcf61a2edd610b19f95b9aac9dfd7fd07ce2aa416a3859bcc1afb3e59f18cf12e95898027102bd16f13103d04aa26

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [v3.3.0](https://github.com/jwt/ruby-jwt/tree/v3.3.0) (2026-09-11)
+
+[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 the error hierarchy under a new `JWT::Error` base class; signing failures now consistently raise `JWT::EncodeError`, see [UPGRADING.md](UPGRADING.md) [#722](https://github.com/jwt/ruby-jwt/pull/722) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Refactor `JWT::JWK::Set#initialize` so each construction path is a named method [#758](https://github.com/jwt/ruby-jwt/pull/758) ([@anakinj](https://github.com/anakinj))
+- Fix rejection of unknown algorithms from JWKs for RFC compliance and pquip [#728](https://github.com/jwt/ruby-jwt/pull/728)
+- Fix the `Style/DirectiveScope` RuboCop offense failing the build [#752](https://github.com/jwt/ruby-jwt/pull/752)
+- Fix `JWT::JWK::Set` sharing its key collection with the set it was copied from [#751](https://github.com/jwt/ruby-jwt/pull/751)
+- Reset the decoded payload and verification state in `JWT::EncodedToken#encoded_payload=` [#749](https://github.com/jwt/ruby-jwt/issues/749)
+- Fix `JWT::Token#detach_payload!` not invalidating an already rendered token [#748](https://github.com/jwt/ruby-jwt/issues/748)
+
 ## [v3.2.0](https://github.com/jwt/ruby-jwt/tree/v3.2.0) (2026-05-13)
 
 [Full Changelog](https://github.com/jwt/ruby-jwt/compare/v3.1.2...v3.2.0)

data/README.md

@@ -532,7 +532,9 @@ end
 
 From [Oauth JSON Web Token 4.1.6. "iat" (Issued At) Claim](https://tools.ietf.org/html/rfc7519#section-4.1.6):
 
-> The `iat` (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT. The `leeway` option is not taken into account when verifying this claim. The `iat_leeway` option was removed in version 2.2.0. Its value MUST be a number containing a **_NumericDate_** value. Use of this claim is OPTIONAL.
+> The `iat` (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT. Its value MUST be a number containing a **_NumericDate_** value. Use of this claim is OPTIONAL.
+
+The global `leeway` option does not apply to `iat`. To allow for clock drift, pass `leeway` under `verify_iat`, as shown below. The `iat_leeway` option was removed in version 2.2.0.
 
 ```ruby
 iat = Time.now.to_i
@@ -548,6 +550,12 @@ rescue JWT::InvalidIatError
 end
 ```
 
+By default, `iat` verification allows no clock drift. To allow drift between the issuer and verifier clocks, pass a leeway value explicitly:
+
+```ruby
+decoded_token = JWT.decode(token, hmac_secret, true, { verify_iat: { leeway: 30 }, algorithm: 'HS256' })
+```
+
 ### Subject Claim
 
 From [Oauth JSON Web Token 4.1.2. "sub" (Subject) Claim](https://tools.ietf.org/html/rfc7519#section-4.1.2):
@@ -632,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
 ```
@@ -697,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
 ```
 

data/UPGRADING.md

@@ -1,3 +1,57 @@
+# Upgrading ruby-jwt to >= 3.3.0
+
+## Error hierarchy revamp
+
+The [error classes were reorganised](https://github.com/jwt/ruby-jwt/pull/722) under a new `JWT::Error` base class, so failures can be rescued by category instead of one class at a time:
+
+- `JWT::Error` is the base class for everything the gem raises.
+- `JWT::TokenError` covers every failure in processing a token, and splits into `JWT::MalformedTokenError` (the token is structurally invalid), `JWT::SignatureError` (signature and algorithm problems) and `JWT::ClaimValidationError` (a claim did not verify).
+- `JWT::VerificationKeyError`, a subclass of `JWT::VerificationError`, says the key or algorithm given for verification cannot be used, as opposed to a signature that does not match.
+
+### Backwards compatibility
+
+This is a backwards compatible change for effectively every application. The new classes were inserted above the existing ones rather than replacing them, so every error class you already rescue keeps its name, its meaning and everything it used to catch. In the ordinary case, upgrading needs no code change at all.
+
+There is one exception, and it is narrow enough to be worth stating precisely. It applies only if all three of the following are true:
+
+1. You rescue around `JWT.encode`, not around `JWT.decode`.
+2. The class you rescue is `JWT::DecodeError`, `JWT::IncorrectAlgorithm`, `JWT::UnsupportedEcdsaCurve` or `ArgumentError`.
+3. That rescue is reached at all, which takes a key or algorithm that cannot sign in the first place.
+
+If any one of the three does not hold, there is nothing to do. If all three do, the fix is a one line change, described in the next section.
+
+Why that is a small target in practice:
+
+- **Decoding is untouched.** `JWT::DecodeError` is deprecated in favour of the classes above, but it keeps its meaning: every error class except `JWT::EncodeError` still inherits from it. A `rescue JWT::DecodeError` around `JWT.decode` catches everything it caught before, and the specific classes it has always raised, such as `JWT::ExpiredSignature`, are unchanged.
+- **Signing that currently works is untouched.** Every case in the table below is an unusable key or algorithm, a misconfiguration that fails on every call made with that key. None of them can be triggered by a particular payload or token, so an application that signs tokens successfully today does not reach them at all.
+- **Failures you let escape are untouched.** All of these raised before and still raise; only the class changed. Code that does not rescue them behaves exactly as it did.
+
+One decode-side behaviour did change, but in the direction of catching more: `RS*` and `PS*` now reject a key of the wrong type with a `JWT::VerificationKeyError`, which is a `JWT::DecodeError`, instead of letting a `NoMethodError` escape.
+
+### Signing failures now raise `JWT::EncodeError`
+
+Signing failures used to surface as decode errors, and are now consistently `JWT::EncodeError`, which is deliberately not a `JWT::DecodeError`:
+
+| Signing with | Used to raise | Now raises |
+| --- | --- | --- |
+| a `nil`, empty or too short HMAC key | `JWT::DecodeError` | `JWT::EncodeError` |
+| an ECDSA key whose curve does not match the algorithm | `JWT::IncorrectAlgorithm` | `JWT::EncodeError` |
+| an ECDSA key on an unsupported curve | `JWT::UnsupportedEcdsaCurve` | `JWT::EncodeError` |
+| a JWK whose `alg` does not match the algorithm | `JWT::DecodeError` | `JWT::EncodeError` |
+| an `RS*` or `PS*` public key | `ArgumentError` | `JWT::EncodeError` |
+
+If you wrap `JWT.encode` in `rescue JWT::DecodeError`, `rescue JWT::IncorrectAlgorithm` or `rescue JWT::UnsupportedEcdsaCurve`, rescue `JWT::EncodeError` or `JWT::Error` instead.
+
+### Why this is a minor release
+
+The exception described above is a real incompatibility, and 3.3.0 is still deliberately a minor release rather than a new major.
+
+The reason is that nothing here turns a call that used to succeed into one that fails, or the other way round. Every case in the table raised an error before and raises an error now, only under a different class. No token is signed that would previously have been refused, no token verifies that would previously have been rejected, and no signature is produced or accepted on different terms than before. What changed is which `rescue` clause matches on a path that was already failing.
+
+Weighed against the cost of a second major migration so soon after 3.0.0, that did not seem to warrant one.
+
+If you find a case where this change affects whether a call succeeds, rather than which error it raises when it fails, please [open an issue](https://github.com/jwt/ruby-jwt/issues). That would be a bug rather than an intended consequence of the reorganisation.
+
 # Upgrading ruby-jwt to >= 3.0.0
 
 ## Removal of the indirect [RbNaCl](https://github.com/RubyCrypto/rbnacl) dependency

data/lib/jwt/claims/decode_verifier.rb

@@ -15,7 +15,7 @@ module JWT
         verify_expiration: ->(options) { Claims::Expiration.new(leeway: options[:exp_leeway] || options[:leeway]) },
         verify_not_before: ->(options) { Claims::NotBefore.new(leeway: options[:nbf_leeway] || options[:leeway]) },
         verify_iss: ->(options) { options[:iss] && Claims::Issuer.new(issuers: options[:iss]) },
-        verify_iat: ->(*) { Claims::IssuedAt.new },
+        verify_iat: ->(options) { Claims::IssuedAt.new(leeway: options[:verify_iat].is_a?(Hash) ? options[:verify_iat][:leeway] : nil) },
         verify_jti: ->(options) { Claims::JwtId.new(validator: options[:verify_jti]) },
         verify_aud: ->(options) { options[:aud] && Claims::Audience.new(expected_audience: options[:aud]) },
         verify_sub: ->(options) { options[:sub] && Claims::Subject.new(expected_subject: options[:sub]) },

data/lib/jwt/claims/issued_at.rb

@@ -4,6 +4,13 @@ module JWT
   module Claims
     # The IssuedAt class is responsible for validating the issued at claim ('iat') in a JWT token.
     class IssuedAt
+      # Initializes a new IssuedAt instance.
+      #
+      # @param leeway [Integer] the drift (in seconds) to allow between the clock of the issuer and the clock of the verifier. Default: 0.
+      def initialize(leeway: 0)
+        @leeway = leeway || 0
+      end
+
       # Verifies the issued at claim ('iat') in the JWT token.
       #
       # @param context [Object] the context containing the JWT payload.
@@ -15,8 +22,12 @@ module JWT
         return unless context.payload.key?('iat')
 
         iat = context.payload['iat']
-        raise(JWT::InvalidIatError, 'Invalid iat') if !iat.is_a?(::Numeric) || iat.to_f > Time.now.to_f
+        raise(JWT::InvalidIatError, 'Invalid iat') if !iat.is_a?(::Numeric) || iat.to_f > (Time.now.to_f + leeway)
       end
+
+      private
+
+      attr_reader :leeway
     end
   end
 end

data/lib/jwt/claims/verifier.rb

@@ -8,7 +8,7 @@ module JWT
         exp: ->(options) { Claims::Expiration.new(leeway: options.dig(:exp, :leeway)) },
         nbf: ->(options) { Claims::NotBefore.new(leeway: options.dig(:nbf, :leeway)) },
         iss: ->(options) { Claims::Issuer.new(issuers: options[:iss]) },
-        iat: ->(*)       { Claims::IssuedAt.new },
+        iat: ->(options) { Claims::IssuedAt.new(leeway: options.dig(:iat, :leeway)) },
         jti: ->(options) { Claims::JwtId.new(validator: options[:jti]) },
         aud: ->(options) { Claims::Audience.new(expected_audience: options[:aud]) },
         sub: ->(options) { Claims::Subject.new(expected_subject: options[:sub]) },
@@ -33,8 +33,10 @@ module JWT
           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

data/lib/jwt/claims.rb

@@ -41,7 +41,7 @@ module JWT
       # @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

data/lib/jwt/configuration/decode_configuration.rb

@@ -11,7 +11,7 @@ module JWT
       # @!attribute [rw] verify_iss
       #   @return [Boolean] whether to verify the issuer claim.
       # @!attribute [rw] verify_iat
-      #   @return [Boolean] whether to verify the issued at claim.
+      #   @return [Boolean, Hash] whether to verify the issued at claim. A hash can be given to configure the claim, currently only `leeway` is supported.
       # @!attribute [rw] verify_jti
       #   @return [Boolean] whether to verify the JWT ID claim.
       # @!attribute [rw] verify_aud

data/lib/jwt/decode.rb

@@ -18,9 +18,9 @@ module JWT
     # @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 @@ module JWT
     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 @@ module JWT
       # 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 @@ module JWT
       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?

data/lib/jwt/encoded_token.rb

@@ -63,10 +63,10 @@ module JWT
     # 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
@@ -77,10 +77,21 @@ module JWT
       decoded_payload
     end
 
-    # Sets or returns the encoded payload of the JWT token.
+    # Returns the encoded payload of the JWT token.
     #
     # @return [String] the encoded payload.
-    attr_accessor :encoded_payload
+    attr_reader :encoded_payload
+
+    # Sets the encoded payload of the JWT token.
+    #
+    # Resets the verification state, requiring the token to be verified again.
+    #
+    # @param encoded_payload [String] the encoded payload.
+    def encoded_payload=(encoded_payload)
+      @encoded_payload = encoded_payload
+      @decoded_payload = nil
+      @signature_verified = @claims_verified = false
+    end
 
     # Returns the signing input of the JWT token.
     #
@@ -98,7 +109,7 @@ module JWT
     # @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 +163,8 @@ module JWT
 
     # 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,11 +199,11 @@ module JWT
     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'])
-        return parse_unencoded(encoded_payload)
+        return parse(encoded_payload)
       end
 
       parse_and_decode(encoded_payload)
@@ -205,14 +217,10 @@ module JWT
       parse(::JWT::Base64.url_decode(segment || ''))
     end
 
-    def parse_unencoded(segment)
-      parse(segment)
-    end
-
     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

data/lib/jwt/error.rb

@@ -1,54 +1,81 @@
 # 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
+
+  # Raised when a JWK uses a key type (kty) that this library does not support.
+  class UnsupportedKeyType < JWKError; end
 end

data/lib/jwt/jwa/ecdsa.rb

@@ -15,10 +15,8 @@ module JWT
         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 @@ module JWT
         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)]

data/lib/jwt/jwa/hmac.rb

@@ -21,15 +21,13 @@ module JWT
       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,22 +40,20 @@ module JWT
 
       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
-      # rubocop:disable Naming/MethodParameterName, Style/StringLiterals, Style/NumericPredicate
+      # rubocop:disable-next Naming/MethodParameterName, Style/StringLiterals, Style/NumericPredicate
       module SecurityUtils
         # Constant time string comparison, for fixed length strings.
         #
@@ -73,7 +69,7 @@ module JWT
           def fixed_length_secure_compare(a, b)
             raise ArgumentError, "string length mismatch." unless a.bytesize == b.bytesize
 
-            l = a.unpack "C#{a.bytesize}"
+            l = a.unpack("C#{a.bytesize}")
 
             res = 0
             b.each_byte { |byte| res |= byte ^ l.shift }
@@ -94,7 +90,6 @@ module JWT
         end
         module_function :secure_compare
       end
-      # rubocop:enable Naming/MethodParameterName, Style/StringLiterals, Style/NumericPredicate
     end
   end
 end

data/lib/jwt/jwa/ps.rb

@@ -13,12 +13,15 @@ module JWT
 
       def sign(data:, signing_key:)
         raise_sign_error!("The given key is a #{signing_key.class}. It has to be an OpenSSL::PKey::RSA instance.") unless signing_key.is_a?(::OpenSSL::PKey::RSA)
+        raise_sign_error!('The given key is not a private key') unless signing_key.private?
         raise_sign_error!('The key length must be greater than or equal to 2048 bits') if signing_key.n.num_bits < 2048
 
         signing_key.sign_pss(digest_algorithm, data, salt_length: :digest, mgf1_hash: digest_algorithm)
       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'

data/lib/jwt/jwa/rsa.rb

@@ -13,12 +13,15 @@ module JWT
 
       def sign(data:, signing_key:)
         raise_sign_error!("The given key is a #{signing_key.class}. It has to be an OpenSSL::PKey::RSA instance") unless signing_key.is_a?(OpenSSL::PKey::RSA)
+        raise_sign_error!('The given key is not a private key') unless signing_key.private?
         raise_sign_error!('The key length must be greater than or equal to 2048 bits') if signing_key.n.num_bits < 2048
 
         signing_key.sign(OpenSSL::Digest.new(digest), data)
       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'

data/lib/jwt/jwa/signing_algorithm.rb

@@ -35,7 +35,7 @@ module JWT
       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)

data/lib/jwt/jwa/unsupported.rb

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

data/lib/jwt/jwa.rb

@@ -37,7 +37,7 @@ module JWT
       # @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 @@ module JWT
       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)

data/lib/jwt/jwk/ec.rb

@@ -54,7 +54,7 @@ module JWT
 
       def export(options = {})
         exported = parameters.clone
-        exported.reject! { |k, _| EC_PRIVATE_KEY_ELEMENTS.include? k } unless private? && options[:include_private] == true
+        exported.reject! { |k, _| EC_PRIVATE_KEY_ELEMENTS.include?(k) } unless private? && options[:include_private] == true
         exported
       end
 

data/lib/jwt/jwk/hmac.rb

@@ -47,7 +47,7 @@ module JWT
       # See https://tools.ietf.org/html/rfc7517#appendix-A.3
       def export(options = {})
         exported = parameters.clone
-        exported.reject! { |k, _| HMAC_PRIVATE_KEY_ELEMENTS.include? k } unless private? && options[:include_private] == true
+        exported.reject! { |k, _| HMAC_PRIVATE_KEY_ELEMENTS.include?(k) } unless private? && options[:include_private] == true
         exported
       end
 

data/lib/jwt/jwk/key_finder.rb

@@ -28,12 +28,12 @@ module JWT
       # Returns the verification key for the given kid
       # @param [String] kid the key id
       def key_for(kid, key_field = :kid)
-        raise ::JWT::DecodeError, "Invalid type for #{key_field} header parameter" unless kid.nil? || kid.is_a?(String)
+        raise ::JWT::MalformedTokenError, "Invalid type for #{key_field} header parameter" unless kid.nil? || kid.is_a?(String)
 
         jwk = resolve_key(kid, key_field)
 
-        raise ::JWT::DecodeError, 'No keys found in jwks' unless @jwks.any?
-        raise ::JWT::DecodeError, "Could not find public key for kid #{kid}" unless jwk
+        raise ::JWT::SignatureError, 'No keys found in jwks' unless @jwks.any?
+        raise ::JWT::SignatureError, "Could not find public key for kid #{kid}" unless jwk
 
         jwk.verify_key
       end
@@ -47,7 +47,7 @@ module JWT
           return key_for(field_value, key_field) if field_value
         end
 
-        raise ::JWT::DecodeError, 'No key id (kid) or x5t found from token headers' unless @allow_nil_kid
+        raise ::JWT::SignatureError, 'No key id (kid) or x5t found from token headers' unless @allow_nil_kid
 
         kid = token.header['kid']
         key_for(kid)

data/lib/jwt/jwk/rsa.rb

@@ -50,7 +50,7 @@ module JWT
 
       def export(options = {})
         exported = parameters.clone
-        exported.reject! { |k, _| RSA_PRIVATE_KEY_ELEMENTS.include? k } unless private? && options[:include_private] == true
+        exported.reject! { |k, _| RSA_PRIVATE_KEY_ELEMENTS.include?(k) } unless private? && options[:include_private] == true
 
         exported
       end

data/lib/jwt/jwk/set.rb

@@ -12,24 +12,24 @@ module JWT
 
       attr_reader :keys
 
-      def initialize(jwks = nil, options = {}) # rubocop:disable Metrics/CyclomaticComplexity
-        jwks ||= {}
-
+      def initialize(jwks = nil, options = {})
         @keys = case jwks
-                when JWT::JWK::Set # Simple duplication
-                  jwks.keys
-                when JWT::JWK::KeyBase # Singleton
-                  [jwks]
-                when Hash
-                  jwks = jwks.transform_keys(&:to_sym)
-                  [*jwks[:keys]].map { |k| JWT::JWK.new(k, nil, options) }
-                when Array
-                  jwks.map { |k| JWT::JWK.new(k, nil, options) }
-                else
-                  raise ArgumentError, 'Can only create new JWKS from Hash, Array and JWK'
+                when nil               then []
+                when JWT::JWK::Set     then jwks.keys.dup
+                when JWT::JWK::KeyBase then [jwks]
+                when Hash              then build_supported_keys(jwks.transform_keys(&:to_sym)[:keys], options)
+                when Array             then build_keys(jwks, options)
+                else raise ArgumentError, 'Can only create new JWKS from Hash, Array and JWK'
                 end
       end
 
+      # Ensures a duplicated set owns its key collection. The keys themselves are
+      # intentionally shared; only the collection is copied.
+      def initialize_copy(other)
+        super
+        @keys = @keys.dup
+      end
+
       def export(options = {})
         { keys: @keys.map { |k| k.export(options) } }
       end
@@ -77,6 +77,20 @@ module JWT
       alias | union
       alias + union
       alias << add
+
+      private
+
+      def build_keys(keys, options)
+        [*keys].map { |key| JWT::JWK.new(key, nil, options) }
+      end
+
+      def build_supported_keys(keys, options)
+        [*keys].each_with_object([]) do |key, arr|
+          arr << JWT::JWK.new(key, nil, options)
+        rescue JWT::UnsupportedKeyType
+          nil
+        end
+      end
     end
   end
 end

data/lib/jwt/jwk.rb

@@ -13,7 +13,7 @@ module JWT
           raise JWT::JWKError, 'Key type (kty) not provided' unless jwk_kty
 
           return mappings.fetch(jwk_kty.to_s) do |kty|
-            raise JWT::JWKError, "Key type #{kty} not supported"
+            raise JWT::UnsupportedKeyType, "Key type #{kty} not supported"
           end.new(key, params, options)
         end
 

data/lib/jwt/token.rb

@@ -81,6 +81,7 @@ module JWT
     #
     def detach_payload!
       @detached_payload = true
+      @jwt = nil
 
       nil
     end
@@ -104,7 +105,7 @@ module JWT
 
     # Verifies the claims of the token.
     # @param options [Array<Symbol>, Hash] the claims to verify.
-    # @raise [JWT::DecodeError] if the claims are invalid.
+    # @raise [JWT::ClaimValidationError] if the claims are invalid.
     def verify_claims!(*options)
       Claims::Verifier.verify!(self, *options)
     end

data/lib/jwt/version.rb

@@ -15,7 +15,7 @@ module JWT
   # Version constants
   module VERSION
     MAJOR = 3
-    MINOR = 2
+    MINOR = 3
     TINY  = 0
     PRE   = nil
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jwt
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.3.0
 platform: ruby
 authors:
 - Tim Rudat
@@ -202,7 +202,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/jwt/ruby-jwt/issues
-  changelog_uri: https://github.com/jwt/ruby-jwt/blob/v3.2.0/CHANGELOG.md
+  changelog_uri: https://github.com/jwt/ruby-jwt/blob/v3.3.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -218,7 +218,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: JSON Web Token implementation in Ruby
 test_files: []