jwt 2.9.1 → 2.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36a35f6010f641283fa3bd38a40b8446661861990aa2b9b9bc415100da4fd255
-  data.tar.gz: 56033dd532a0fbab8c737a753fb92bea4da4bcfac320d179a22ec48e366aa304
+  metadata.gz: bd2c497012269d18de9e39316124f41be2e7b095fa25068f4eb1a9e82ce74bcb
+  data.tar.gz: ae2c8d4ad25c8c49aa00c7c3e75ff80fab5eb59be7b76cb9ee4e272200e53b30
 SHA512:
-  metadata.gz: afc6d521e351e4e6224baa39bb0c31e5d6e15e53a64a62cfcf10d63d0012e9b3558307fd44eca9a95efe7fca63192736c4ed838cecc3867db90542aed7768055
-  data.tar.gz: 99b4fcd45418b931b4ed18f6275b5dc673f34a49bf45d92be734a452129a3b81c97c7966f4dda855ba646c8619b504db26b927b99feddd72a86dfdd75a0d2028
+  metadata.gz: 20ffc73333a32ef4ff3c15972f9487b16cb191fadd9980ae1895b4a0a2ce3074a5d51e2183b36aa98abd3b1e9822f2546e20fc39dd60d193c08e9f30a3329624
+  data.tar.gz: 1500f0aef9ba50725c8090021ad5be31e100733a502e069c93b6caa6fce58b0e0b48704cccf0efab7e868655a572ba65eb7c96681f9f184bd0337515bb847966

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## Upcoming breaking changes
+
+Notable changes in the upcoming **version 3.0**:
+
+- The indirect dependency to [rbnacl](https://github.com/RubyCrypto/rbnacl) will be removed:
+  - Support for the nonstandard SHA512256 algorithm will be removed.
+  - Support for Ed25519 will be moved to a [separate gem](https://github.com/anakinj/jwt-eddsa) for better dependency handling.
+
+- Base64 decoding will no longer fallback on the looser RFC 2045.
+
+- 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) and lead 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. No recommended alternatives.
+  - 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)`
+
+- The internal algorithms were [restructured](https://github.com/jwt/ruby-jwt/pull/607) to support extensions from separate libraries. The changes lead 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.
+
+## [v2.9.2](https://github.com/jwt/ruby-jwt/tree/v2.9.2) (2024-10-03)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.9.1...v2.9.2)
+
+**Features:**
+
+- Standalone claim verification interface [#626](https://github.com/jwt/ruby-jwt/pull/626) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Updated README to correctly document `OpenSSL::HMAC` documentation [#617](https://github.com/jwt/ruby-jwt/pull/617) ([@aedryan](https://github.com/aedryan))
+- Verify JWT header format [#622](https://github.com/jwt/ruby-jwt/pull/622) ([@304](https://github.com/304))
+- Bring back `::JWT::ClaimsValidator`, `::JWT::Verify` and a few other removed interfaces for preserved backwards compatibility [#624](https://github.com/jwt/ruby-jwt/pull/624) ([@anakinj](https://github.com/anakinj))
+
 ## [v2.9.1](https://github.com/jwt/ruby-jwt/tree/v2.9.1) (2024-09-23)
 
 [Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.9.0...v2.9.1)

data/README.md

@@ -240,7 +240,7 @@ module CustomHS512Algorithm
   end
 
   def self.sign(data:, signing_key:)
-    OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha512'), data, signing_key)
+    OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha512'), signing_key, data)
   end
 
   def self.verify(data:, signature:, verification_key:)
@@ -530,6 +530,24 @@ rescue JWT::InvalidSubError
 end
 ```
 
+### Standalone claim verification
+
+The JWT claim verifications can be used to verify any Hash to include expected keys and values.
+
+A few example on verifying the claims for a payload:
+```ruby
+JWT::Claims.verify_payload!({"exp" => Time.now.to_i + 10}, :numeric, :exp)
+JWT::Claims.valid_payload?({"exp" => Time.now.to_i + 10}, :exp)
+# => true
+JWT::Claims.payload_errors({"exp" => Time.now.to_i - 10}, :exp)
+# => [#<struct JWT::Claims::Error message="Signature has expired">]
+JWT::Claims.verify_payload!({"exp" => Time.now.to_i - 10}, exp: { leeway: 11})
+
+JWT::Claims.verify_payload!({"exp" => Time.now.to_i + 10, "sub" => "subject"}, :exp, sub: "subject")
+```
+
+
+
 ### Finding a Key
 
 To dynamically find the key for verifying the JWT signature, pass a block to the decode block. The block receives headers and the original payload as parameters. It should return with the key to verify the signature that was used to sign the JWT.

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
+    #
+    # @private
+    VerificationContext = Struct.new(:payload, keyword_init: true)
+
+    # Verifiers to support the ::JWT.decode method
+    #
+    # @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
+        # @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/numeric.rb

@@ -3,10 +3,14 @@
 module JWT
   module Claims
     class Numeric
-      def self.verify!(payload:, **_args)
-        return unless payload.is_a?(Hash)
+      class Compat
+        def initialize(payload)
+          @payload = payload
+        end
 
-        new(payload).verify!
+        def verify!
+          JWT::Claims.verify_payload!(@payload, :numeric)
+        end
       end
 
       NUMERIC_CLAIMS = %i[
@@ -15,28 +19,36 @@ module JWT
         nbf
       ].freeze
 
-      def initialize(payload)
-        @payload = payload.transform_keys(&:to_sym)
+      def self.new(*args)
+        return super if args.empty?
+
+        Compat.new(*args)
       end
 
-      def verify!
-        validate_numeric_claims
+      def verify!(context:)
+        validate_numeric_claims(context.payload)
+      end
 
-        true
+      def self.verify!(payload:, **_args)
+        JWT::Claims.verify_payload!(payload, :numeric)
       end
 
       private
 
-      def validate_numeric_claims
+      def validate_numeric_claims(payload)
         NUMERIC_CLAIMS.each do |claim|
-          validate_is_numeric(claim) if @payload.key?(claim)
+          validate_is_numeric(payload, claim)
         end
       end
 
-      def validate_is_numeric(claim)
-        return if @payload[claim].is_a?(::Numeric)
+      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].class}"
+        raise InvalidPayload, "#{claim} claim must be a Numeric value but it is a #{(payload[claim] || payload[claim.to_s]).class}"
       end
     end
   end

data/lib/jwt/claims/verifier.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module JWT
+  module Claims
+    # @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]) },
+
+        required: ->(options) { Claims::Required.new(required_claims: options[:required]) },
+        numeric: ->(*)        { Claims::Numeric.new }
+      }.freeze
+
+      private_constant(:VERIFIERS)
+
+      class << self
+        # @private
+        def verify!(context, *options)
+          iterate_verifiers(*options) do |verifier, verifier_options|
+            verify_one!(context, verifier, verifier_options)
+          end
+          nil
+        end
+
+        # @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
+
+        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)
+        end
+      end
+    end
+  end
+end

data/lib/jwt/claims.rb

@@ -9,29 +9,73 @@ 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
+  # 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
-    VerificationContext = Struct.new(:payload, keyword_init: true)
-
-    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
+    # 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)
-        VERIFIERS.each do |key, verifier_builder|
-          next unless options[key]
+        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)
+        verify_token!(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)
+        token_errors(VerificationContext.new(payload: payload), *options)
+      end
+
+      private
+
+      def verify_token!(token, *options)
+        Verifier.verify!(token, *options)
+      end
 
-          verifier_builder&.call(options)&.verify!(context: VerificationContext.new(payload: payload))
-        end
+      def token_errors(token, *options)
+        Verifier.errors(token, *options)
       end
     end
   end

data/lib/jwt/claims_validator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module JWT
+  class ClaimsValidator
+    def initialize(payload)
+      @payload = payload
+    end
+
+    def validate!
+      Claims.verify_payload!(@payload, :numeric)
+    end
+  end
+end

data/lib/jwt/decode.rb

@@ -49,6 +49,7 @@ module JWT
 
     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::IncorrectAlgorithm, 'Token is missing alg header' unless alg_in_header
       raise JWT::IncorrectAlgorithm, 'Expected a different algorithm' if allowed_and_valid_algorithms.empty?
     end
@@ -111,7 +112,7 @@ module JWT
     end
 
     def verify_claims
-      Claims.verify!(payload, @options)
+      Claims::DecodeVerifier.verify!(payload, @options)
     end
 
     def validate_segment_count!

data/lib/jwt/encode.rb

@@ -51,7 +51,7 @@ module JWT
     def validate_claims!
       return unless @payload.is_a?(Hash)
 
-      Claims::Numeric.new(@payload).verify!
+      Claims.verify_payload!(@payload, :numeric)
     end
 
     def encode_signature

data/lib/jwt/jwa/compat.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module JWT
+  module JWA
+    module Compat
+      module ClassMethods
+        def from_algorithm(algorithm)
+          new(algorithm)
+        end
+
+        def sign(algorithm, msg, key)
+          Deprecations.warning('Support for calling sign with positional arguments will be removed in future ruby-jwt versions')
+
+          from_algorithm(algorithm).sign(data: msg, signing_key: key)
+        end
+
+        def verify(algorithm, key, signing_input, signature)
+          Deprecations.warning('Support for calling verify with positional arguments will be removed in future ruby-jwt versions')
+
+          from_algorithm(algorithm).verify(data: signing_input, signature: signature, verification_key: key)
+        end
+      end
+
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/jwt/jwa/ecdsa.rb

@@ -59,6 +59,10 @@ module JWT
         register_algorithm(new(v[:algorithm], v[:digest]))
       end
 
+      def self.from_algorithm(algorithm)
+        new(algorithm, algorithm.downcase.gsub('es', 'sha'))
+      end
+
       def self.curve_by_name(name)
         NAMED_CURVES.fetch(name) do
           raise UnsupportedEcdsaCurve, "The ECDSA curve '#{name}' is not supported"

data/lib/jwt/jwa/hmac.rb

@@ -5,6 +5,10 @@ module JWT
     class Hmac
       include JWT::JWA::SigningAlgorithm
 
+      def self.from_algorithm(algorithm)
+        new(algorithm, OpenSSL::Digest.new(algorithm.downcase.gsub('hs', 'sha')))
+      end
+
       def initialize(alg, digest)
         @alg = alg
         @digest = digest

data/lib/jwt/jwa/hmac_rbnacl.rb

@@ -5,6 +5,10 @@ module JWT
     class HmacRbNaCl
       include JWT::JWA::SigningAlgorithm
 
+      def self.from_algorithm(algorithm)
+        new(algorithm, ::RbNaCl::HMAC.const_get(algorithm.upcase.gsub('HS', 'SHA')))
+      end
+
       def initialize(alg, hmac)
         @alg = alg
         @hmac = hmac

data/lib/jwt/jwa/hmac_rbnacl_fixed.rb

@@ -5,6 +5,10 @@ module JWT
     class HmacRbNaClFixed
       include JWT::JWA::SigningAlgorithm
 
+      def self.from_algorithm(algorithm)
+        new(algorithm, ::RbNaCl::HMAC.const_get(algorithm.upcase.gsub('HS', 'SHA')))
+      end
+
       def initialize(alg, hmac)
         @alg = alg
         @hmac = hmac

data/lib/jwt/jwa/signing_algorithm.rb

@@ -11,6 +11,7 @@ module JWT
 
       def self.included(klass)
         klass.extend(ClassMethods)
+        klass.include(JWT::JWA::Compat)
       end
 
       attr_reader :alg

data/lib/jwt/jwa.rb

@@ -8,6 +8,7 @@ rescue LoadError
   raise if defined?(RbNaCl)
 end
 
+require_relative 'jwa/compat'
 require_relative 'jwa/signing_algorithm'
 require_relative 'jwa/ecdsa'
 require_relative 'jwa/hmac'
@@ -34,12 +35,16 @@ module JWT
         return find(algorithm) if algorithm.is_a?(String) || algorithm.is_a?(Symbol)
 
         unless algorithm.is_a?(SigningAlgorithm)
-          Deprecations.warning('Custom algorithms are required to include JWT::JWA::SigningAlgorithm')
+          Deprecations.warning('Custom algorithms are required to include JWT::JWA::SigningAlgorithm. Custom algorithms that do not include this module may stop working in the next major version of ruby-jwt.')
           return Wrapper.new(algorithm)
         end
 
         algorithm
       end
+
+      def create(algorithm)
+        resolve(algorithm)
+      end
     end
   end
 end

data/lib/jwt/verify.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module JWT
+  class Verify
+    DEFAULTS = { leeway: 0 }.freeze
+    METHODS = %w[verify_aud verify_expiration verify_iat verify_iss verify_jti verify_not_before verify_sub verify_required_claims].freeze
+
+    class << self
+      METHODS.each do |method_name|
+        define_method(method_name) do |payload, options|
+          new(payload, options).send(method_name)
+        end
+      end
+
+      def verify_claims(payload, options)
+        ::JWT::Claims.verify!(payload, options)
+      end
+    end
+
+    def initialize(payload, options)
+      @payload = payload
+      @options = DEFAULTS.merge(options)
+    end
+
+    METHODS.each do |method_name|
+      define_method(method_name) do
+        ::JWT::Claims.verify!(@payload, @options.merge(method_name => true))
+      end
+    end
+  end
+end

data/lib/jwt/version.rb

@@ -13,7 +13,7 @@ module JWT
     # minor version
     MINOR = 9
     # tiny version
-    TINY  = 1
+    TINY  = 2
     # alpha, beta, etc. tag
     PRE   = nil
 

data/lib/jwt.rb

@@ -11,6 +11,9 @@ require 'jwt/error'
 require 'jwt/jwk'
 require 'jwt/claims'
 
+require 'jwt/claims_validator'
+require 'jwt/verify'
+
 # JSON Web Token implementation
 #
 # Should be up to date with the latest spec:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jwt
 version: !ruby/object:Gem::Version
-  version: 2.9.1
+  version: 2.9.2
 platform: ruby
 authors:
 - Tim Rudat
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-09-23 00:00:00.000000000 Z
+date: 2024-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -125,6 +125,7 @@ files:
 - lib/jwt/base64.rb
 - lib/jwt/claims.rb
 - lib/jwt/claims/audience.rb
+- lib/jwt/claims/decode_verifier.rb
 - lib/jwt/claims/expiration.rb
 - lib/jwt/claims/issued_at.rb
 - lib/jwt/claims/issuer.rb
@@ -133,6 +134,8 @@ files:
 - lib/jwt/claims/numeric.rb
 - lib/jwt/claims/required.rb
 - lib/jwt/claims/subject.rb
+- lib/jwt/claims/verifier.rb
+- lib/jwt/claims_validator.rb
 - lib/jwt/configuration.rb
 - lib/jwt/configuration/container.rb
 - lib/jwt/configuration/decode_configuration.rb
@@ -143,6 +146,7 @@ files:
 - lib/jwt/error.rb
 - lib/jwt/json.rb
 - lib/jwt/jwa.rb
+- lib/jwt/jwa/compat.rb
 - lib/jwt/jwa/ecdsa.rb
 - lib/jwt/jwa/eddsa.rb
 - lib/jwt/jwa/hmac.rb
@@ -164,6 +168,7 @@ files:
 - lib/jwt/jwk/rsa.rb
 - lib/jwt/jwk/set.rb
 - lib/jwt/jwk/thumbprint.rb
+- lib/jwt/verify.rb
 - lib/jwt/version.rb
 - lib/jwt/x5c_key_finder.rb
 - ruby-jwt.gemspec
@@ -172,7 +177,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/jwt/ruby-jwt/issues
-  changelog_uri: https://github.com/jwt/ruby-jwt/blob/v2.9.1/CHANGELOG.md
+  changelog_uri: https://github.com/jwt/ruby-jwt/blob/v2.9.2/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []