jwt 2.8.2 → 3.1.1

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+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?
+      end
+
+      private
+
+      attr_reader :expected_audience
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module JWT
+  module Claims
+    # Context class to contain the data passed to individual claim validators
+    #
+    # @api private
+    VerificationContext = Struct.new(:payload, keyword_init: true)
+
+    # Verifiers to support the ::JWT.decode method
+    #
+    # @api private
+    module DecodeVerifier
+      VERIFIERS = {
+        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_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]) },
+        required_claims: ->(options) { Claims::Required.new(required_claims: options[:required_claims]) }
+      }.freeze
+
+      private_constant(:VERIFIERS)
+
+      class << self
+        # @api private
+        def verify!(payload, options)
+          VERIFIERS.each do |key, verifier_builder|
+            next unless options[key] || options[key.to_s]
+
+            verifier_builder&.call(options)&.verify!(context: VerificationContext.new(payload: payload))
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/jwt/claims/expiration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+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')
+
+        raise JWT::ExpiredSignature, 'Signature has expired' if context.payload['exp'].to_i <= (Time.now.to_i - leeway)
+      end
+
+      private
+
+      attr_reader :leeway
+    end
+  end
+end

data/lib/jwt/claims/issued_at.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+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')
+
+        iat = context.payload['iat']
+        raise(JWT::InvalidIatError, 'Invalid iat') if !iat.is_a?(::Numeric) || iat.to_f > Time.now.to_f
+      end
+    end
+  end
+end

data/lib/jwt/claims/issuer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+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
+          nil
+        else
+          raise JWT::InvalidIssuerError, "Invalid issuer. Expected #{issuers}, received #{iss || '<none>'}"
+        end
+      end
+
+      private
+
+      attr_reader :issuers
+    end
+  end
+end

data/lib/jwt/claims/jwt_id.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+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)
+          verified = validator.arity == 2 ? validator.call(jti, context.payload) : validator.call(jti)
+          raise(JWT::InvalidJtiError, 'Invalid jti') unless verified
+        elsif jti.to_s.strip.empty?
+          raise(JWT::InvalidJtiError, 'Missing jti')
+        end
+      end
+
+      private
+
+      attr_reader :validator
+    end
+  end
+end

data/lib/jwt/claims/not_before.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+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')
+
+        raise JWT::ImmatureSignature, 'Signature nbf has not been reached' if context.payload['nbf'].to_i > (Time.now.to_i + leeway)
+      end
+
+      private
+
+      attr_reader :leeway
+    end
+  end
+end

data/lib/jwt/claims/numeric.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+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
+      # List of numeric claims that can be validated.
+      NUMERIC_CLAIMS = %i[
+        exp
+        iat
+        nbf
+      ].freeze
+
+      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
+
+      private
+
+      def validate_numeric_claims(payload)
+        NUMERIC_CLAIMS.each do |claim|
+          validate_is_numeric(payload, claim)
+        end
+      end
+
+      def validate_is_numeric(payload, claim)
+        return unless payload.is_a?(Hash)
+        return unless payload.key?(claim) ||
+                      payload.key?(claim.to_s)
+
+        return if payload[claim].is_a?(::Numeric) || payload[claim.to_s].is_a?(::Numeric)
+
+        raise InvalidPayload, "#{claim} claim must be a Numeric value but it is a #{(payload[claim] || payload[claim.to_s]).class}"
+      end
+    end
+  end
+end

data/lib/jwt/claims/required.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+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)
+
+          raise JWT::MissingRequiredClaim, "Missing required claim #{required_claim}"
+        end
+      end
+
+      private
+
+      attr_reader :required_claims
+    end
+  end
+end

data/lib/jwt/claims/subject.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+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
+      end
+
+      private
+
+      attr_reader :expected_subject
+    end
+  end
+end

data/lib/jwt/claims/verifier.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module JWT
+  module Claims
+    # @api private
+    module Verifier
+      VERIFIERS = {
+        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 },
+        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
+
+      private_constant(:VERIFIERS)
+
+      class << self
+        # @api private
+        def verify!(context, *options)
+          iterate_verifiers(*options) do |verifier, verifier_options|
+            verify_one!(context, verifier, verifier_options)
+          end
+          nil
+        end
+
+        # @api private
+        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)
+          end
+          errors
+        end
+
+        private
+
+        def iterate_verifiers(*options)
+          options.each do |element|
+            if element.is_a?(Hash)
+              element.each_key { |key| yield(key, element) }
+            else
+              yield(element, {})
+            end
+          end
+        end
+
+        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)
+        end
+      end
+    end
+  end
+end

data/lib/jwt/claims.rb

@@ -0,0 +1,67 @@
+# 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'
+require_relative 'claims/jwt_id'
+require_relative 'claims/not_before'
+require_relative 'claims/numeric'
+require_relative 'claims/required'
+require_relative 'claims/subject'
+require_relative 'claims/verifier'
+
+module JWT
+  # JWT Claim verifications
+  # https://datatracker.ietf.org/doc/html/rfc7519#section-4
+  #
+  # Verification is supported for the following claims:
+  # exp
+  # nbf
+  # iss
+  # iat
+  # jti
+  # aud
+  # sub
+  # required
+  # numeric
+  module Claims
+    # Represents a claim verification error
+    Error = Struct.new(:message, keyword_init: true)
+
+    class << self
+      # Checks if the claims in the JWT payload are valid.
+      # @example
+      #
+      #   ::JWT::Claims.verify_payload!({"exp" => Time.now.to_i + 10}, :exp)
+      #   ::JWT::Claims.verify_payload!({"exp" => Time.now.to_i - 10}, exp: { leeway: 11})
+      #
+      # @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.
+      def verify_payload!(payload, *options)
+        Verifier.verify!(VerificationContext.new(payload: payload), *options)
+      end
+
+      # Checks if the claims in the JWT payload are valid.
+      #
+      # @param payload [Hash] the JWT payload.
+      # @param options [Array] the options for verifying the claims.
+      # @return [Boolean] true if the claims are valid, false otherwise
+      def valid_payload?(payload, *options)
+        payload_errors(payload, *options).empty?
+      end
+
+      # Returns the errors in the claims of the JWT token.
+      #
+      # @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)
+        Verifier.errors(VerificationContext.new(payload: payload), *options)
+      end
+    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)