jwt 2.3.0 → 2.10.1

data/lib/jwt/base64.rb

@@ -3,14 +3,31 @@
 require 'base64'
 
 module JWT
-  # Base64 helpers
+  # 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.encode64(str).tr('+/', '-_').gsub(/[\n=]/, '')
+        ::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('-_', '+/'))
       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,77 @@
+# 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
+      # The Compat class provides backward compatibility for numeric claim validation.
+      # @api private
+      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
+
+      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
+
+      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/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

@@ -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,74 @@
+# 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/verification_methods'
+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
+      # @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
+
+      # 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/claims_validator.rb

@@ -1,35 +1,18 @@
-require_relative './error'
+# frozen_string_literal: true
 
 module JWT
+  # @deprecated Use `Claims.verify_payload!` directly instead.
   class ClaimsValidator
-    NUMERIC_CLAIMS = %i[
-      exp
-      iat
-      nbf
-    ].freeze
-
+    # @deprecated Use `Claims.verify_payload!` directly instead.
     def initialize(payload)
-      @payload = payload.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+      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!
-      validate_numeric_claims
-
+      Claims.verify_payload!(@payload, :numeric)
       true
     end
-
-    private
-
-    def validate_numeric_claims
-      NUMERIC_CLAIMS.each do |claim|
-        validate_is_numeric(claim) if @payload.key?(claim)
-      end
-    end
-
-    def validate_is_numeric(claim)
-      return if @payload[claim].is_a?(Numeric)
-
-      raise InvalidPayload, "#{claim} claim must be a Numeric value but it is a #{@payload[claim].class}"
-    end
   end
 end