jwt 2.9.3 → 2.10.0

data/lib/jwt/claims/decode_verifier.rb

@@ -4,12 +4,12 @@ module JWT
   module Claims
     # Context class to contain the data passed to individual claim validators
     #
-    # @private
+    # @api private
     VerificationContext = Struct.new(:payload, keyword_init: true)
 
     # Verifiers to support the ::JWT.decode method
     #
-    # @private
+    # @api private
     module DecodeVerifier
       VERIFIERS = {
         verify_expiration: ->(options) { Claims::Expiration.new(leeway: options[:exp_leeway] || options[:leeway]) },
@@ -25,7 +25,7 @@ module JWT
       private_constant(:VERIFIERS)
 
       class << self
-        # @private
+        # @api private
         def verify!(payload, options)
           VERIFIERS.each do |key, verifier_builder|
             next unless options[key] || options[key.to_s]

data/lib/jwt/claims/expiration.rb

@@ -2,11 +2,21 @@
 
 module JWT
   module Claims
+    # The Expiration class is responsible for validating the expiration claim ('exp') in a JWT token.
     class Expiration
+      # Initializes a new Expiration instance.
+      #
+      # @param leeway [Integer] the amount of leeway (in seconds) to allow when validating the expiration time. Default: 0.
       def initialize(leeway:)
         @leeway = leeway || 0
       end
 
+      # Verifies the expiration claim ('exp') in the JWT token.
+      #
+      # @param context [Object] the context containing the JWT payload.
+      # @param _args [Hash] additional arguments (not used).
+      # @raise [JWT::ExpiredSignature] if the token has expired.
+      # @return [nil]
       def verify!(context:, **_args)
         return unless context.payload.is_a?(Hash)
         return unless context.payload.key?('exp')

data/lib/jwt/claims/issued_at.rb

@@ -2,7 +2,14 @@
 
 module JWT
   module Claims
+    # The IssuedAt class is responsible for validating the issued at claim ('iat') in a JWT token.
     class IssuedAt
+      # Verifies the issued at claim ('iat') in the JWT token.
+      #
+      # @param context [Object] the context containing the JWT payload.
+      # @param _args [Hash] additional arguments (not used).
+      # @raise [JWT::InvalidIatError] if the issued at claim is invalid.
+      # @return [nil]
       def verify!(context:, **_args)
         return unless context.payload.is_a?(Hash)
         return unless context.payload.key?('iat')

data/lib/jwt/claims/issuer.rb

@@ -2,11 +2,21 @@
 
 module JWT
   module Claims
+    # The Issuer class is responsible for validating the issuer claim ('iss') in a JWT token.
     class Issuer
+      # Initializes a new Issuer instance.
+      #
+      # @param issuers [String, Symbol, Array<String, Symbol>] the expected issuer(s) for the JWT token.
       def initialize(issuers:)
         @issuers = Array(issuers).map { |item| item.is_a?(Symbol) ? item.to_s : item }
       end
 
+      # Verifies the issuer claim ('iss') in the JWT token.
+      #
+      # @param context [Object] the context containing the JWT payload.
+      # @param _args [Hash] additional arguments (not used).
+      # @raise [JWT::InvalidIssuerError] if the issuer claim is invalid.
+      # @return [nil]
       def verify!(context:, **_args)
         case (iss = context.payload['iss'])
         when *issuers

data/lib/jwt/claims/jwt_id.rb

@@ -2,11 +2,21 @@
 
 module JWT
   module Claims
+    # The JwtId class is responsible for validating the JWT ID claim ('jti') in a JWT token.
     class JwtId
+      # Initializes a new JwtId instance.
+      #
+      # @param validator [#call] an object responding to `call` to validate the JWT ID.
       def initialize(validator:)
         @validator = validator
       end
 
+      # Verifies the JWT ID claim ('jti') in the JWT token.
+      #
+      # @param context [Object] the context containing the JWT payload.
+      # @param _args [Hash] additional arguments (not used).
+      # @raise [JWT::InvalidJtiError] if the JWT ID claim is invalid or missing.
+      # @return [nil]
       def verify!(context:, **_args)
         jti = context.payload['jti']
         if validator.respond_to?(:call)

data/lib/jwt/claims/not_before.rb

@@ -2,11 +2,21 @@
 
 module JWT
   module Claims
+    # The NotBefore class is responsible for validating the 'nbf' (Not Before) claim in a JWT token.
     class NotBefore
+      # Initializes a new NotBefore instance.
+      #
+      # @param leeway [Integer] the amount of leeway (in seconds) to allow when validating the 'nbf' claim. Defaults to 0.
       def initialize(leeway:)
         @leeway = leeway || 0
       end
 
+      # Verifies the 'nbf' (Not Before) claim in the JWT token.
+      #
+      # @param context [Object] the context containing the JWT payload.
+      # @param _args [Hash] additional arguments (not used).
+      # @raise [JWT::ImmatureSignature] if the 'nbf' claim has not been reached.
+      # @return [nil]
       def verify!(context:, **_args)
         return unless context.payload.is_a?(Hash)
         return unless context.payload.key?('nbf')

data/lib/jwt/claims/numeric.rb

@@ -2,7 +2,11 @@
 
 module JWT
   module Claims
+    # The Numeric class is responsible for validating numeric claims in a JWT token.
+    # The numeric claims are: exp, iat and nbf
     class Numeric
+      # The Compat class provides backward compatibility for numeric claim validation.
+      # @api private
       class Compat
         def initialize(payload)
           @payload = payload
@@ -13,23 +17,41 @@ module JWT
         end
       end
 
+      # List of numeric claims that can be validated.
       NUMERIC_CLAIMS = %i[
         exp
         iat
         nbf
       ].freeze
 
+      private_constant(:NUMERIC_CLAIMS)
+
+      # @api private
       def self.new(*args)
         return super if args.empty?
 
+        Deprecations.warning('Calling ::JWT::Claims::Numeric.new with the payload will be removed in the next major version of ruby-jwt')
         Compat.new(*args)
       end
 
+      # Verifies the numeric claims in the JWT context.
+      #
+      # @param context [Object] the context containing the JWT payload.
+      # @raise [JWT::InvalidClaimError] if any numeric claim is invalid.
+      # @return [nil]
       def verify!(context:)
         validate_numeric_claims(context.payload)
       end
 
+      # Verifies the numeric claims in the JWT payload.
+      #
+      # @param payload [Hash] the JWT payload containing the claims.
+      # @param _args [Hash] additional arguments (not used).
+      # @raise [JWT::InvalidClaimError] if any numeric claim is invalid.
+      # @return [nil]
+      # @deprecated The ::JWT::Claims::Numeric.verify! method will be removed in the next major version of ruby-jwt
       def self.verify!(payload:, **_args)
+        Deprecations.warning('The ::JWT::Claims::Numeric.verify! method will be removed in the next major version of ruby-jwt.')
         JWT::Claims.verify_payload!(payload, :numeric)
       end
 

data/lib/jwt/claims/required.rb

@@ -2,11 +2,21 @@
 
 module JWT
   module Claims
+    # The Required class is responsible for validating that all required claims are present in a JWT token.
     class Required
+      # Initializes a new Required instance.
+      #
+      # @param required_claims [Array<String>] the list of required claims.
       def initialize(required_claims:)
         @required_claims = required_claims
       end
 
+      # Verifies that all required claims are present in the JWT payload.
+      #
+      # @param context [Object] the context containing the JWT payload.
+      # @param _args [Hash] additional arguments (not used).
+      # @raise [JWT::MissingRequiredClaim] if any required claim is missing.
+      # @return [nil]
       def verify!(context:, **_args)
         required_claims.each do |required_claim|
           next if context.payload.is_a?(Hash) && context.payload.key?(required_claim)

data/lib/jwt/claims/subject.rb

@@ -2,11 +2,21 @@
 
 module JWT
   module Claims
+    # The Subject class is responsible for validating the subject claim ('sub') in a JWT token.
     class Subject
+      # Initializes a new Subject instance.
+      #
+      # @param expected_subject [String] the expected subject for the JWT token.
       def initialize(expected_subject:)
         @expected_subject = expected_subject.to_s
       end
 
+      # Verifies the subject claim ('sub') in the JWT token.
+      #
+      # @param context [Object] the context containing the JWT payload.
+      # @param _args [Hash] additional arguments (not used).
+      # @raise [JWT::InvalidSubError] if the subject claim is invalid.
+      # @return [nil]
       def verify!(context:, **_args)
         sub = context.payload['sub']
         raise(JWT::InvalidSubError, "Invalid subject. Expected #{expected_subject}, received #{sub || '<none>'}") unless sub.to_s == expected_subject

data/lib/jwt/claims/verification_methods.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module JWT
+  module Claims
+    # @api private
+    module VerificationMethods
+      def verify_claims!(*options)
+        Verifier.verify!(self, *options)
+      end
+
+      def claim_errors(*options)
+        Verifier.errors(self, *options)
+      end
+
+      def valid_claims?(*options)
+        claim_errors(*options).empty?
+      end
+    end
+  end
+end

data/lib/jwt/claims/verifier.rb

@@ -2,7 +2,7 @@
 
 module JWT
   module Claims
-    # @private
+    # @api private
     module Verifier
       VERIFIERS = {
         exp: ->(options) { Claims::Expiration.new(leeway: options.dig(:exp, :leeway)) },
@@ -12,7 +12,7 @@ module JWT
         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]) },
-
+        crit: ->(options) { Claims::Crit.new(expected_crits: options[:crit]) },
         required: ->(options) { Claims::Required.new(required_claims: options[:required]) },
         numeric: ->(*)        { Claims::Numeric.new }
       }.freeze
@@ -20,7 +20,7 @@ module JWT
       private_constant(:VERIFIERS)
 
       class << self
-        # @private
+        # @api private
         def verify!(context, *options)
           iterate_verifiers(*options) do |verifier, verifier_options|
             verify_one!(context, verifier, verifier_options)
@@ -28,7 +28,7 @@ module JWT
           nil
         end
 
-        # @private
+        # @api private
         def errors(context, *options)
           errors = []
           iterate_verifiers(*options) do |verifier, verifier_options|
@@ -39,7 +39,8 @@ module JWT
           errors
         end
 
-        # @private
+        private
+
         def iterate_verifiers(*options)
           options.each do |element|
             if element.is_a?(Hash)
@@ -50,8 +51,6 @@ module JWT
           end
         end
 
-        private
-
         def verify_one!(context, verifier, options)
           verifier_builder = VERIFIERS.fetch(verifier) { raise ArgumentError, "#{verifier} not a valid claim verifier" }
           verifier_builder.call(options || {}).verify!(context: context)

data/lib/jwt/claims.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative 'claims/audience'
+require_relative 'claims/crit'
+require_relative 'claims/decode_verifier'
 require_relative 'claims/expiration'
 require_relative 'claims/issued_at'
 require_relative 'claims/issuer'
@@ -9,7 +11,7 @@ require_relative 'claims/not_before'
 require_relative 'claims/numeric'
 require_relative 'claims/required'
 require_relative 'claims/subject'
-require_relative 'claims/decode_verifier'
+require_relative 'claims/verification_methods'
 require_relative 'claims/verifier'
 
 module JWT
@@ -26,7 +28,6 @@ module JWT
   # sub
   # required
   # numeric
-  #
   module Claims
     # Represents a claim verification error
     Error = Struct.new(:message, keyword_init: true)
@@ -34,6 +35,7 @@ module JWT
     class << self
       # @deprecated Use {verify_payload!} instead. Will be removed in the next major version of ruby-jwt.
       def verify!(payload, options)
+        Deprecations.warning('The ::JWT::Claims.verify! method is deprecated will be removed in the next major version of ruby-jwt')
         DecodeVerifier.verify!(payload, options)
       end
 
@@ -48,7 +50,7 @@ module JWT
       # @return [void]
       # @raise [JWT::DecodeError] if any claim is invalid.
       def verify_payload!(payload, *options)
-        verify_token!(VerificationContext.new(payload: payload), *options)
+        Verifier.verify!(VerificationContext.new(payload: payload), *options)
       end
 
       # Checks if the claims in the JWT payload are valid.
@@ -65,17 +67,7 @@ module JWT
       # @param options [Array] the options for verifying the claims.
       # @return [Array<JWT::Claims::Error>] the errors in the claims of the JWT
       def payload_errors(payload, *options)
-        token_errors(VerificationContext.new(payload: payload), *options)
-      end
-
-      private
-
-      def verify_token!(token, *options)
-        Verifier.verify!(token, *options)
-      end
-
-      def token_errors(token, *options)
-        Verifier.errors(token, *options)
+        Verifier.errors(VerificationContext.new(payload: payload), *options)
       end
     end
   end

data/lib/jwt/claims_validator.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
-require_relative 'error'
-
 module JWT
+  # @deprecated Use `Claims.verify_payload!` directly instead.
   class ClaimsValidator
+    # @deprecated Use `Claims.verify_payload!` directly instead.
     def initialize(payload)
+      Deprecations.warning('The ::JWT::ClaimsValidator class is deprecated and will be removed in the next major version of ruby-jwt')
       @payload = payload
     end
 
+    # @deprecated Use `Claims.verify_payload!` directly instead.
     def validate!
       Claims.verify_payload!(@payload, :numeric)
       true

data/lib/jwt/configuration/container.rb

@@ -5,14 +5,28 @@ require_relative 'jwk_configuration'
 
 module JWT
   module Configuration
+    # The Container class holds the configuration settings for JWT.
     class Container
+      # @!attribute [rw] decode
+      #   @return [DecodeConfiguration] the decode configuration.
+      # @!attribute [rw] jwk
+      #   @return [JwkConfiguration] the JWK configuration.
+      # @!attribute [rw] strict_base64_decoding
+      #   @return [Boolean] whether strict Base64 decoding is enabled.
       attr_accessor :decode, :jwk, :strict_base64_decoding
+
+      # @!attribute [r] deprecation_warnings
+      #   @return [Symbol] the deprecation warnings setting.
       attr_reader :deprecation_warnings
 
+      # Initializes a new Container instance and resets the configuration.
       def initialize
         reset!
       end
 
+      # Resets the configuration to default values.
+      #
+      # @return [void]
       def reset!
         @decode                 = DecodeConfiguration.new
         @jwk                    = JwkConfiguration.new
@@ -22,6 +36,12 @@ module JWT
       end
 
       DEPRECATION_WARNINGS_VALUES = %i[once warn silent].freeze
+      private_constant(:DEPRECATION_WARNINGS_VALUES)
+      # Sets the deprecation warnings setting.
+      #
+      # @param value [Symbol] the deprecation warnings setting. Must be one of `:once`, `:warn`, or `:silent`.
+      # @raise [ArgumentError] if the value is not one of the supported values.
+      # @return [void]
       def deprecation_warnings=(value)
         raise ArgumentError, "Invalid deprecation_warnings value #{value}. Supported values: #{DEPRECATION_WARNINGS_VALUES}" unless DEPRECATION_WARNINGS_VALUES.include?(value)
 

data/lib/jwt/configuration/decode_configuration.rb

@@ -2,7 +2,29 @@
 
 module JWT
   module Configuration
+    # The DecodeConfiguration class holds the configuration settings for decoding JWT tokens.
     class DecodeConfiguration
+      # @!attribute [rw] verify_expiration
+      #   @return [Boolean] whether to verify the expiration claim.
+      # @!attribute [rw] verify_not_before
+      #   @return [Boolean] whether to verify the not before claim.
+      # @!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.
+      # @!attribute [rw] verify_jti
+      #   @return [Boolean] whether to verify the JWT ID claim.
+      # @!attribute [rw] verify_aud
+      #   @return [Boolean] whether to verify the audience claim.
+      # @!attribute [rw] verify_sub
+      #   @return [Boolean] whether to verify the subject claim.
+      # @!attribute [rw] leeway
+      #   @return [Integer] the leeway in seconds for time-based claims.
+      # @!attribute [rw] algorithms
+      #   @return [Array<String>] the list of acceptable algorithms.
+      # @!attribute [rw] required_claims
+      #   @return [Array<String>] the list of required claims.
+
       attr_accessor :verify_expiration,
                     :verify_not_before,
                     :verify_iss,
@@ -14,6 +36,7 @@ module JWT
                     :algorithms,
                     :required_claims
 
+      # Initializes a new DecodeConfiguration instance with default settings.
       def initialize
         @verify_expiration = true
         @verify_not_before = true
@@ -27,6 +50,7 @@ module JWT
         @required_claims = []
       end
 
+      # @api private
       def to_h
         {
           verify_expiration: verify_expiration,

data/lib/jwt/configuration/jwk_configuration.rb

@@ -5,6 +5,7 @@ require_relative '../jwk/thumbprint'
 
 module JWT
   module Configuration
+    # @api private
     class JwkConfiguration
       def initialize
         self.kid_generator_type = :key_digest

data/lib/jwt/configuration.rb

@@ -3,11 +3,19 @@
 require_relative 'configuration/container'
 
 module JWT
+  # The Configuration module provides methods to configure JWT settings.
   module Configuration
+    # Configures the JWT settings.
+    #
+    # @yield [config] Gives the current configuration to the block.
+    # @yieldparam config [JWT::Configuration::Container] the configuration container.
     def configure
       yield(configuration)
     end
 
+    # Returns the JWT configuration container.
+    #
+    # @return [JWT::Configuration::Container] the configuration container.
     def configuration
       @configuration ||= ::JWT::Configuration::Container.new
     end

data/lib/jwt/decode.rb

@@ -3,69 +3,67 @@
 require 'json'
 require 'jwt/x5c_key_finder'
 
-# JWT::Decode module
 module JWT
-  # Decoding logic for JWT
+  # The Decode class is responsible for decoding and verifying JWT tokens.
   class Decode
+    # Initializes a new Decode instance.
+    #
+    # @param jwt [String] the JWT to decode.
+    # @param key [String, Array<String>] the key(s) to use for verification.
+    # @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.
     def initialize(jwt, key, verify, options, &keyfinder)
       raise JWT::DecodeError, 'Nil JSON web token' unless jwt
 
-      @jwt = jwt
+      @token = EncodedToken.new(jwt)
       @key = key
       @options = options
-      @segments = jwt.split('.')
       @verify = verify
-      @signature = ''
       @keyfinder = keyfinder
     end
 
+    # Decodes the JWT token and verifies its segments if verification is enabled.
+    #
+    # @return [Array<Hash>] an array containing the decoded payload and header.
     def decode_segments
       validate_segment_count!
       if @verify
-        decode_signature
         verify_algo
         set_key
         verify_signature
-        verify_claims
+        Claims::DecodeVerifier.verify!(token.payload, @options)
       end
-      raise JWT::DecodeError, 'Not enough or too many segments' unless header && payload
 
-      [payload, header]
+      [token.payload, token.header]
     end
 
     private
 
-    def verify_signature
-      return unless @key || @verify
+    attr_reader :token
 
+    def verify_signature
       return if none_algorithm?
 
       raise JWT::DecodeError, 'No verification key available' unless @key
 
-      return if Array(@key).any? { |key| verify_signature_for?(key) }
-
-      raise JWT::VerificationError, 'Signature verification failed'
+      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 header.is_a?(Hash)
+      raise JWT::DecodeError, 'Token header not a JSON object' unless token.header.is_a?(Hash)
       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
 
     def set_key
       @key = find_key(&@keyfinder) if @keyfinder
-      @key = ::JWT::JWK::KeyFinder.new(jwks: @options[:jwks], allow_nil_kid: @options[:allow_nil_kid]).key_for(header['kid']) if @options[:jwks]
+      @key = ::JWT::JWK::KeyFinder.new(jwks: @options[:jwks], allow_nil_kid: @options[:allow_nil_kid]).key_for(token.header['kid']) if @options[:jwks]
       return unless (x5c_options = @options[:x5c])
 
-      @key = X5cKeyFinder.new(x5c_options[:root_certificates], x5c_options[:crls]).from(header['x5c'])
-    end
-
-    def verify_signature_for?(key)
-      allowed_and_valid_algorithms.any? do |alg|
-        alg.verify(data: signing_input, signature: @signature, verification_key: key)
-      end
+      @key = X5cKeyFinder.new(x5c_options[:root_certificates], x5c_options[:crls]).from(token.header['x5c'])
     end
 
     def allowed_and_valid_algorithms
@@ -91,70 +89,32 @@ module JWT
     end
 
     def resolve_allowed_algorithms
-      algs = given_algorithms.map { |alg| JWA.resolve(alg) }
-
-      sort_by_alg_header(algs)
-    end
-
-    # Move algorithms matching the JWT alg header to the beginning of the list
-    def sort_by_alg_header(algs)
-      return algs if algs.size <= 1
-
-      algs.partition { |alg| alg.valid_alg?(alg_in_header) }.flatten
+      given_algorithms.map { |alg| JWA.resolve(alg) }
     end
 
     def find_key(&keyfinder)
-      key = (keyfinder.arity == 2 ? yield(header, payload) : yield(header))
+      key = (keyfinder.arity == 2 ? yield(token.header, token.payload) : yield(token.header))
       # key can be of type [string, nil, OpenSSL::PKey, Array]
       return key if key && !Array(key).empty?
 
       raise JWT::DecodeError, 'No verification key available'
     end
 
-    def verify_claims
-      Claims::DecodeVerifier.verify!(payload, @options)
-    end
-
     def validate_segment_count!
-      return if segment_length == 3
-      return if !@verify && segment_length == 2 # If no verifying required, the signature is not needed
-      return if segment_length == 2 && none_algorithm?
+      segment_count = token.jwt.count('.') + 1
+      return if segment_count == 3
+      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'
     end
 
-    def segment_length
-      @segments.count
-    end
-
     def none_algorithm?
       alg_in_header == 'none'
     end
 
-    def decode_signature
-      @signature = ::JWT::Base64.url_decode(@segments[2] || '')
-    end
-
     def alg_in_header
-      header['alg']
-    end
-
-    def header
-      @header ||= parse_and_decode @segments[0]
-    end
-
-    def payload
-      @payload ||= parse_and_decode @segments[1]
-    end
-
-    def signing_input
-      @segments.first(2).join('.')
-    end
-
-    def parse_and_decode(segment)
-      JWT::JSON.parse(::JWT::Base64.url_decode(segment))
-    rescue ::JSON::ParserError
-      raise JWT::DecodeError, 'Invalid segment encoding'
+      token.header['alg']
     end
   end
 end

data/lib/jwt/deprecations.rb

@@ -2,6 +2,7 @@
 
 module JWT
   # Deprecations module to handle deprecation warnings in the gem
+  # @api private
   module Deprecations
     class << self
       def context