jwt 2.9.3 → 3.1.2

data/UPGRADING.md

@@ -0,0 +1,47 @@
+# Upgrading ruby-jwt to >= 3.0.0
+
+## Removal of the indirect [RbNaCl](https://github.com/RubyCrypto/rbnacl) dependency
+
+Historically, the set of supported algorithms was extended by including the `rbnacl` gem in the application's Gemfile. On load, ruby-jwt tried to load the gem and, if available, extend the algorithms to those provided by the `rbnacl/libsodium` libraries. This indirect dependency has caused some maintenance pain and confusion about which versions of the gem are supported.
+
+Some work to ease the way alternative algorithms can be implemented has been done. This enables the extraction of the algorithm provided by `rbnacl`.
+
+The extracted algorithms now live in the [jwt-eddsa](https://rubygems.org/gems/jwt-eddsa) gem.
+
+### Dropped support for HS512256
+
+The algorithm HS512256 (HMAC-SHA-512 truncated to 256-bits) is not part of any JWA/JWT RFC and therefore will not be supported anymore. It was part of the HMAC algorithms provided by the indirect [RbNaCl](https://github.com/RubyCrypto/rbnacl) dependency. Currently, there are no direct substitutes for the algorithm.
+
+### `JWT::EncodedToken#payload` will raise before token is verified
+
+To avoid accidental use of unverified tokens, the `JWT::EncodedToken#payload` method will raise an error if accessed before the token signature has been verified.
+
+To access the payload before verification, use the method `JWT::EncodedToken#unverified_payload`.
+
+## Stricter requirements on Base64 encoded data
+
+Base64 decoding will no longer fallback on the looser RFC 2045. The biggest difference is that the looser version was ignoring whitespaces and newlines, whereas the stricter version raises errors in such cases.
+
+If you, for example, read tokens from files, there could be problems with trailing newlines. Make sure you trim your input before passing it to the decoding mechanisms.
+
+## Claim verification revamp
+
+Claim verification has been [split into separate classes](https://github.com/jwt/ruby-jwt/pull/605) and has [a new API](https://github.com/jwt/ruby-jwt/pull/626), leading to the following deprecations:
+
+- The `::JWT::ClaimsValidator` class will be removed in favor of the functionality provided by `::JWT::Claims`.
+- The `::JWT::Claims::verify!` method will be removed in favor of `::JWT::Claims::verify_payload!`.
+- The `::JWT::JWA.create` method will be removed.
+- The `::JWT::Verify` class will be removed in favor of the functionality provided by `::JWT::Claims`.
+- Calling `::JWT::Claims::Numeric.new` with a payload will be removed in favor of `::JWT::Claims::verify_payload!(payload, :numeric)`.
+- Calling `::JWT::Claims::Numeric.verify!` with a payload will be removed in favor of `::JWT::Claims::verify_payload!(payload, :numeric)`.
+
+## Algorithm restructuring
+
+The internal algorithms were [restructured](https://github.com/jwt/ruby-jwt/pull/607) to support extensions from separate libraries. The changes led to a few deprecations and new requirements:
+
+- The `sign` and `verify` static methods on all the algorithms (`::JWT::JWA`) will be removed.
+- Custom algorithms are expected to include the `JWT::JWA::SigningAlgorithm` module.
+
+## Base64 the `k´ value for HMAC JWKs
+
+The gem was missing the Base64 encoding and decoding when representing and parsing a HMAC key as a JWK. This issue is now addressed. The added encoding will break compatibility with JWKs produced by older versions of the gem.

data/lib/jwt/base64.rb

@@ -4,29 +4,23 @@ require 'base64'
 
 module JWT
   # Base64 encoding and decoding
+  # @api private
   class Base64
     class << self
       # Encode a string with URL-safe Base64 complying with RFC 4648 (not padded).
+      # @api private
       def url_encode(str)
         ::Base64.urlsafe_encode64(str, padding: false)
       end
 
       # Decode a string with URL-safe Base64 complying with RFC 4648.
-      # Deprecated support for RFC 2045 remains for now. ("All line breaks or other characters not found in Table 1 must be ignored by decoding software")
+      # @api private
       def url_decode(str)
         ::Base64.urlsafe_decode64(str)
       rescue ArgumentError => e
         raise unless e.message == 'invalid base64'
-        raise Base64DecodeError, 'Invalid base64 encoding' if JWT.configuration.strict_base64_decoding
 
-        loose_urlsafe_decode64(str).tap do
-          Deprecations.warning('Invalid base64 input detected, could be because of invalid padding, trailing whitespaces or newline chars. Graceful handling of invalid input will be dropped in the next major version of ruby-jwt', only_if_valid: true)
-        end
-      end
-
-      def loose_urlsafe_decode64(str)
-        str += '=' * (4 - str.length.modulo(4))
-        ::Base64.decode64(str.tr('-_', '+/'))
+        raise Base64DecodeError, 'Invalid base64 encoding'
       end
     end
   end

data/lib/jwt/claims/audience.rb

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

data/lib/jwt/claims/crit.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module JWT
+  module Claims
+    # Responsible of validation the crit header
+    class Crit
+      # Initializes a new Crit instance.
+      #
+      # @param expected_crits [String] the expected crit header values for the JWT token.
+      def initialize(expected_crits:)
+        @expected_crits = Array(expected_crits)
+      end
+
+      # Verifies the critical claim ('crit') in the JWT token header.
+      #
+      # @param context [Object] the context containing the JWT payload and header.
+      # @param _args [Hash] additional arguments (not used).
+      # @raise [JWT::InvalidCritError] if the crit claim is invalid.
+      # @return [nil]
+      def verify!(context:, **_args)
+        raise(JWT::InvalidCritError, 'Crit header missing') unless context.header['crit']
+        raise(JWT::InvalidCritError, 'Crit header should be an array') unless context.header['crit'].is_a?(Array)
+
+        missing = (expected_crits - context.header['crit'])
+        raise(JWT::InvalidCritError, "Crit header missing expected values: #{missing.join(', ')}") if missing.any?
+
+        nil
+      end
+
+      private
+
+      attr_reader :expected_crits
+    end
+  end
+end

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,37 +2,27 @@
 
 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
-      class Compat
-        def initialize(payload)
-          @payload = payload
-        end
-
-        def verify!
-          JWT::Claims.verify_payload!(@payload, :numeric)
-        end
-      end
-
+      # List of numeric claims that can be validated.
       NUMERIC_CLAIMS = %i[
         exp
         iat
         nbf
       ].freeze
 
-      def self.new(*args)
-        return super if args.empty?
-
-        Compat.new(*args)
-      end
+      private_constant(:NUMERIC_CLAIMS)
 
+      # 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
 
-      def self.verify!(payload:, **_args)
-        JWT::Claims.verify_payload!(payload, :numeric)
-      end
-
       private
 
       def validate_numeric_claims(payload)

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/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,6 @@ 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/verifier'
 
 module JWT
@@ -26,17 +27,11 @@ module JWT
   # sub
   # required
   # numeric
-  #
   module Claims
     # Represents a claim verification error
     Error = Struct.new(:message, keyword_init: true)
 
     class << self
-      # @deprecated Use {verify_payload!} instead. Will be removed in the next major version of ruby-jwt.
-      def verify!(payload, options)
-        DecodeVerifier.verify!(payload, options)
-      end
-
       # Checks if the claims in the JWT payload are valid.
       # @example
       #
@@ -48,7 +43,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 +60,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/configuration/container.rb

@@ -5,23 +5,42 @@ 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
-        @strict_base64_decoding = false
 
         self.deprecation_warnings = :once
       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