jwt 2.8.2 → 3.1.1

data/lib/jwt/jwk/hmac.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # JWK for HMAC keys
     class HMAC < KeyBase
       KTY  = 'oct'
       KTYS = [KTY, String, JWT::JWK::HMAC].freeze
@@ -61,17 +62,15 @@ module JWT
       end
 
       def []=(key, value)
-        if HMAC_KEY_ELEMENTS.include?(key.to_sym)
-          raise ArgumentError, 'cannot overwrite cryptographic key attributes'
-        end
+        raise ArgumentError, 'cannot overwrite cryptographic key attributes' if HMAC_KEY_ELEMENTS.include?(key.to_sym)
 
-        super(key, value)
+        super
       end
 
       private
 
       def secret
-        self[:k]
+        @secret ||= ::JWT::Base64.url_decode(self[:k])
       end
 
       def extract_key_params(key)
@@ -79,7 +78,7 @@ module JWT
         when JWT::JWK::HMAC
           key.export(include_private: true)
         when String # Accept String key as input
-          { kty: KTY, k: key }
+          { kty: KTY, k: ::JWT::Base64.url_encode(key) }
         when Hash
           key.transform_keys(&:to_sym)
         else

data/lib/jwt/jwk/key_base.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # Base for JWK implementations
     class KeyBase
       def self.inherited(klass)
         super
@@ -41,6 +42,14 @@ module JWT
         other.is_a?(::JWT::JWK::KeyBase) && self[:kid] == other[:kid]
       end
 
+      def verify(**kwargs)
+        jwa.verify(**kwargs, verification_key: verify_key)
+      end
+
+      def sign(**kwargs)
+        jwa.sign(**kwargs, signing_key: signing_key)
+      end
+
       alias eql? ==
 
       def <=>(other)
@@ -49,7 +58,13 @@ module JWT
         self[:kid] <=> other[:kid]
       end
 
-      private
+      def jwa
+        raise JWT::JWKError, 'Could not resolve the JWA, the "alg" parameter is missing' unless self[:alg]
+
+        JWA.resolve(self[:alg]).tap do |jwa|
+          raise JWT::JWKError, 'none algorithm usage not supported via JWK' if jwa.is_a?(JWA::None)
+        end
+      end
 
       attr_reader :parameters
     end

data/lib/jwt/jwk/key_finder.rb

@@ -2,7 +2,16 @@
 
 module JWT
   module JWK
+    # JSON Web Key keyfinder
+    # To find the key for a given kid
     class KeyFinder
+      # Initializes a new KeyFinder instance.
+      # @param [Hash] options the options to create a KeyFinder with
+      # @option options [Proc, JWT::JWK::Set] :jwks the jwks or a loader proc
+      # @option options [Boolean] :allow_nil_kid whether to allow nil kid
+      # @option options [Array] :key_fields the fields to use for key matching,
+      #                         the order of the fields are used to determine
+      #                         the priority of the keys.
       def initialize(options)
         @allow_nil_kid = options[:allow_nil_kid]
         jwks_or_loader = options[:jwks]
@@ -12,13 +21,16 @@ module JWT
                        else
                          ->(_options) { jwks_or_loader }
                        end
+
+        @key_fields = options[:key_fields] || %i[kid]
       end
 
-      def key_for(kid)
-        raise ::JWT::DecodeError, 'No key id (kid) found from token headers' unless kid || @allow_nil_kid
-        raise ::JWT::DecodeError, 'Invalid type for kid header parameter' unless kid.nil? || kid.is_a?(String)
+      # Returns the verification key for the given kid
+      # @param [String] kid the key id
+      def key_for(kid, key_field = :kid)
+        raise ::JWT::DecodeError, "Invalid type for #{key_field} header parameter" unless kid.nil? || kid.is_a?(String)
 
-        jwk = resolve_key(kid)
+        jwk = resolve_key(kid, key_field)
 
         raise ::JWT::DecodeError, 'No keys found in jwks' unless @jwks.any?
         raise ::JWT::DecodeError, "Could not find public key for kid #{kid}" unless jwk
@@ -26,19 +38,34 @@ module JWT
         jwk.verify_key
       end
 
+      # Returns the key for the given token
+      # @param [JWT::EncodedToken] token the token
+      def call(token)
+        @key_fields.each do |key_field|
+          field_value = token.header[key_field.to_s]
+
+          return key_for(field_value, key_field) if field_value
+        end
+
+        raise ::JWT::DecodeError, 'No key id (kid) or x5t found from token headers' unless @allow_nil_kid
+
+        kid = token.header['kid']
+        key_for(kid)
+      end
+
       private
 
-      def resolve_key(kid)
-        key_matcher = ->(key) { (kid.nil? && @allow_nil_kid) || key[:kid] == kid }
+      def resolve_key(kid, key_field)
+        key_matcher = ->(key) { (kid.nil? && @allow_nil_kid) || key[key_field] == kid }
 
         # First try without invalidation to facilitate application caching
-        @jwks ||= JWT::JWK::Set.new(@jwks_loader.call(kid: kid))
+        @jwks ||= JWT::JWK::Set.new(@jwks_loader.call(key_field => kid))
         jwk = @jwks.find { |key| key_matcher.call(key) }
 
         return jwk if jwk
 
         # Second try, invalidate for backwards compatibility
-        @jwks = JWT::JWK::Set.new(@jwks_loader.call(invalidate: true, kid_not_found: true, kid: kid))
+        @jwks = JWT::JWK::Set.new(@jwks_loader.call(invalidate: true, kid_not_found: true, key_field => kid))
         @jwks.find { |key| key_matcher.call(key) }
       end
     end

data/lib/jwt/jwk/kid_as_key_digest.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # @api private
     class KidAsKeyDigest
       def initialize(jwk)
         @jwk = jwk

data/lib/jwt/jwk/rsa.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # JSON Web Key (JWK) representation of a RSA key
     class RSA < KeyBase # rubocop:disable Metrics/ClassLength
       BINARY = 2
       KTY    = 'RSA'
@@ -50,6 +51,7 @@ module JWT
       def export(options = {})
         exported = parameters.clone
         exported.reject! { |k, _| RSA_PRIVATE_KEY_ELEMENTS.include? k } unless private? && options[:include_private] == true
+
         exported
       end
 
@@ -64,11 +66,9 @@ module JWT
       end
 
       def []=(key, value)
-        if RSA_KEY_ELEMENTS.include?(key.to_sym)
-          raise ArgumentError, 'cannot overwrite cryptographic key attributes'
-        end
+        raise ArgumentError, 'cannot overwrite cryptographic key attributes' if RSA_KEY_ELEMENTS.include?(key.to_sym)
 
-        super(key, value)
+        super
       end
 
       private
@@ -166,6 +166,8 @@ module JWT
           end
         end
 
+        # :nocov:
+        # Before openssl 2.0, we need to use the accessors to set the key
         def create_rsa_key_using_accessors(rsa_parameters) # rubocop:disable Metrics/AbcSize
           validate_rsa_parameters!(rsa_parameters)
 
@@ -180,6 +182,7 @@ module JWT
             rsa_key.iqmp = rsa_parameters[:qi] if rsa_parameters[:qi]
           end
         end
+        # :nocov:
 
         def validate_rsa_parameters!(rsa_parameters)
           return unless rsa_parameters.key?(:d)

data/lib/jwt/jwk/set.rb

@@ -4,6 +4,8 @@ require 'forwardable'
 
 module JWT
   module JWK
+    # JSON Web Key Set (JWKS) representation
+    # https://tools.ietf.org/html/rfc7517
     class Set
       include Enumerable
       extend Forwardable

data/lib/jwt/jwk.rb

@@ -4,6 +4,7 @@ require_relative 'jwk/key_finder'
 require_relative 'jwk/set'
 
 module JWT
+  # JSON Web Key (JWK)
   module JWK
     class << self
       def create_from(key, params = nil, options = {})
@@ -52,4 +53,3 @@ require_relative 'jwk/key_base'
 require_relative 'jwk/ec'
 require_relative 'jwk/rsa'
 require_relative 'jwk/hmac'
-require_relative 'jwk/okp_rbnacl' if JWT.rbnacl?

data/lib/jwt/token.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module JWT
+  # Represents a JWT token
+  #
+  # Basic token signed using the HS256 algorithm:
+  #
+  #   token = JWT::Token.new(payload: {pay: 'load'})
+  #   token.sign!(algorithm: 'HS256', key: 'secret')
+  #   token.jwt # => eyJhb....
+  #
+  # Custom headers will be combined with generated headers:
+  #   token = JWT::Token.new(payload: {pay: 'load'}, header: {custom: "value"})
+  #   token.sign!(algorithm: 'HS256', key: 'secret')
+  #   token.header # => {"custom"=>"value", "alg"=>"HS256"}
+  #
+  class Token
+    # Initializes a new Token instance.
+    #
+    # @param header [Hash] the header of the JWT token.
+    # @param payload [Hash] the payload of the JWT token.
+    def initialize(payload:, header: {})
+      @header  = header&.transform_keys(&:to_s)
+      @payload = payload
+    end
+
+    # Returns the decoded signature of the JWT token.
+    #
+    # @return [String] the decoded signature of the JWT token.
+    def signature
+      @signature ||= ::JWT::Base64.url_decode(encoded_signature || '')
+    end
+
+    # Returns the encoded signature of the JWT token.
+    #
+    # @return [String] the encoded signature of the JWT token.
+    def encoded_signature
+      @encoded_signature ||= ::JWT::Base64.url_encode(signature)
+    end
+
+    # Returns the decoded header of the JWT token.
+    #
+    # @return [Hash] the header of the JWT token.
+    attr_reader :header
+
+    # Returns the encoded header of the JWT token.
+    #
+    # @return [String] the encoded header of the JWT token.
+    def encoded_header
+      @encoded_header ||= ::JWT::Base64.url_encode(JWT::JSON.generate(header))
+    end
+
+    # Returns the payload of the JWT token.
+    #
+    # @return [Hash] the payload of the JWT token.
+    attr_reader :payload
+
+    # Returns the encoded payload of the JWT token.
+    #
+    # @return [String] the encoded payload of the JWT token.
+    def encoded_payload
+      @encoded_payload ||= ::JWT::Base64.url_encode(JWT::JSON.generate(payload))
+    end
+
+    # Returns the signing input of the JWT token.
+    #
+    # @return [String] the signing input of the JWT token.
+    def signing_input
+      @signing_input ||= [encoded_header, encoded_payload].join('.')
+    end
+
+    # Returns the JWT token as a string.
+    #
+    # @return [String] the JWT token as a string.
+    # @raise [JWT::EncodeError] if the token is not signed or other encoding issues
+    def jwt
+      @jwt ||= (@signature && [encoded_header, @detached_payload ? '' : encoded_payload, encoded_signature].join('.')) || raise(::JWT::EncodeError, 'Token is not signed')
+    end
+
+    # Detaches the payload according to https://datatracker.ietf.org/doc/html/rfc7515#appendix-F
+    #
+    def detach_payload!
+      @detached_payload = true
+
+      nil
+    end
+
+    # Signs the JWT token.
+    #
+    # @param key [String, JWT::JWK::KeyBase] the key to use for signing.
+    # @param algorithm [String, Object] the algorithm to use for signing.
+    # @return [void]
+    # @raise [JWT::EncodeError] if the token is already signed or other problems when signing
+    def sign!(key:, algorithm:)
+      raise ::JWT::EncodeError, 'Token already signed' if @signature
+
+      JWA.create_signer(algorithm: algorithm, key: key).tap do |signer|
+        header.merge!(signer.jwa.header) { |_key, old, _new| old }
+        @signature = signer.sign(data: signing_input)
+      end
+
+      nil
+    end
+
+    # Verifies the claims of the token.
+    # @param options [Array<Symbol>, Hash] the claims to verify.
+    # @raise [JWT::DecodeError] if the claims are invalid.
+    def verify_claims!(*options)
+      Claims::Verifier.verify!(self, *options)
+    end
+
+    # Returns the errors of the claims of the token.
+    # @param options [Array<Symbol>, Hash] the claims to verify.
+    # @return [Array<Symbol>] the errors of the claims.
+    def claim_errors(*options)
+      Claims::Verifier.errors(self, *options)
+    end
+
+    # Returns whether the claims of the token are valid.
+    # @param options [Array<Symbol>, Hash] the claims to verify.
+    # @return [Boolean] whether the claims are valid.
+    def valid_claims?(*options)
+      claim_errors(*options).empty?
+    end
+
+    # Returns the JWT token as a string.
+    #
+    # @return [String] the JWT token as a string.
+    alias to_s jwt
+  end
+end

data/lib/jwt/version.rb

@@ -1,44 +1,49 @@
 # frozen_string_literal: true
 
-# Moments version builder module
+# JSON Web Token implementation
+#
+# Should be up to date with the latest spec:
+# https://tools.ietf.org/html/rfc7519
 module JWT
+  # Returns the gem version of the JWT library.
+  #
+  # @return [Gem::Version] the gem version.
   def self.gem_version
-    Gem::Version.new VERSION::STRING
+    Gem::Version.new(VERSION::STRING)
   end
 
-  # Moments version builder module
+  # Version constants
   module VERSION
-    # major version
-    MAJOR = 2
-    # minor version
-    MINOR = 8
-    # tiny version
-    TINY  = 2
-    # alpha, beta, etc. tag
+    MAJOR = 3
+    MINOR = 1
+    TINY  = 1
     PRE   = nil
 
-    # Build version string
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.')
   end
 
+  # Checks if the OpenSSL version is 3 or greater.
+  #
+  # @return [Boolean] true if OpenSSL version is 3 or greater, false otherwise.
+  # @api private
   def self.openssl_3?
     return false if OpenSSL::OPENSSL_VERSION.include?('LibreSSL')
 
     true if 3 * 0x10000000 <= OpenSSL::OPENSSL_VERSION_NUMBER
   end
 
-  def self.rbnacl?
-    defined?(::RbNaCl)
-  end
-
-  def self.rbnacl_6_or_greater?
-    rbnacl? && ::Gem::Version.new(::RbNaCl::VERSION) >= ::Gem::Version.new('6.0.0')
-  end
-
+  # Checks if there is an OpenSSL 3 HMAC empty key regression.
+  #
+  # @return [Boolean] true if there is an OpenSSL 3 HMAC empty key regression, false otherwise.
+  # @api private
   def self.openssl_3_hmac_empty_key_regression?
     openssl_3? && openssl_version <= ::Gem::Version.new('3.0.0')
   end
 
+  # Returns the OpenSSL version.
+  #
+  # @return [Gem::Version] the OpenSSL version.
+  # @api private
   def self.openssl_version
     @openssl_version ||= ::Gem::Version.new(OpenSSL::VERSION)
   end

data/lib/jwt.rb

@@ -5,10 +5,12 @@ require 'jwt/base64'
 require 'jwt/json'
 require 'jwt/decode'
 require 'jwt/configuration'
-require 'jwt/deprecations'
 require 'jwt/encode'
 require 'jwt/error'
 require 'jwt/jwk'
+require 'jwt/claims'
+require 'jwt/encoded_token'
+require 'jwt/token'
 
 # JSON Web Token implementation
 #
@@ -19,6 +21,13 @@ module JWT
 
   module_function
 
+  # Encodes a payload into a JWT.
+  #
+  # @param payload [Hash] the payload to encode.
+  # @param key [String] the key used to sign the JWT.
+  # @param algorithm [String] the algorithm used to sign the JWT.
+  # @param header_fields [Hash] additional headers to include in the JWT.
+  # @return [String] the encoded JWT.
   def encode(payload, key, algorithm = 'HS256', header_fields = {})
     Encode.new(payload: payload,
                key: key,
@@ -26,9 +35,14 @@ module JWT
                headers: header_fields).segments
   end
 
+  # Decodes a JWT to extract the payload and header
+  #
+  # @param jwt [String] the JWT to decode.
+  # @param key [String] the key used to verify the JWT.
+  # @param verify [Boolean] whether to verify the JWT signature.
+  # @param options [Hash] additional options for decoding.
+  # @return [Array<Hash>] the decoded payload and headers.
   def decode(jwt, key = nil, verify = true, options = {}, &keyfinder) # rubocop:disable Style/OptionalBooleanParameter
-    Deprecations.context do
-      Decode.new(jwt, key, verify, configuration.decode.to_h.merge(options), &keyfinder).decode_segments
-    end
+    Decode.new(jwt, key, verify, configuration.decode.to_h.merge(options), &keyfinder).decode_segments
   end
 end

data/ruby-jwt.gemspec

@@ -35,6 +35,8 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'appraisal'
   spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'irb'
+  spec.add_development_dependency 'logger'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'rubocop'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jwt
 version: !ruby/object:Gem::Version
-  version: 2.8.2
+  version: 3.1.1
 platform: ruby
 authors:
 - Tim Rudat
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-18 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -52,6 +51,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -121,40 +148,49 @@ files:
 - CONTRIBUTING.md
 - LICENSE
 - README.md
+- UPGRADING.md
 - lib/jwt.rb
 - lib/jwt/base64.rb
-- lib/jwt/claims_validator.rb
+- lib/jwt/claims.rb
+- lib/jwt/claims/audience.rb
+- lib/jwt/claims/crit.rb
+- lib/jwt/claims/decode_verifier.rb
+- lib/jwt/claims/expiration.rb
+- lib/jwt/claims/issued_at.rb
+- lib/jwt/claims/issuer.rb
+- lib/jwt/claims/jwt_id.rb
+- lib/jwt/claims/not_before.rb
+- lib/jwt/claims/numeric.rb
+- lib/jwt/claims/required.rb
+- lib/jwt/claims/subject.rb
+- lib/jwt/claims/verifier.rb
 - lib/jwt/configuration.rb
 - lib/jwt/configuration/container.rb
 - lib/jwt/configuration/decode_configuration.rb
 - lib/jwt/configuration/jwk_configuration.rb
 - lib/jwt/decode.rb
-- lib/jwt/deprecations.rb
 - lib/jwt/encode.rb
+- lib/jwt/encoded_token.rb
 - lib/jwt/error.rb
 - lib/jwt/json.rb
 - lib/jwt/jwa.rb
 - lib/jwt/jwa/ecdsa.rb
-- lib/jwt/jwa/eddsa.rb
 - lib/jwt/jwa/hmac.rb
-- lib/jwt/jwa/hmac_rbnacl.rb
-- lib/jwt/jwa/hmac_rbnacl_fixed.rb
 - lib/jwt/jwa/none.rb
 - lib/jwt/jwa/ps.rb
 - lib/jwt/jwa/rsa.rb
+- lib/jwt/jwa/signing_algorithm.rb
 - lib/jwt/jwa/unsupported.rb
-- lib/jwt/jwa/wrapper.rb
 - lib/jwt/jwk.rb
 - lib/jwt/jwk/ec.rb
 - lib/jwt/jwk/hmac.rb
 - lib/jwt/jwk/key_base.rb
 - lib/jwt/jwk/key_finder.rb
 - lib/jwt/jwk/kid_as_key_digest.rb
-- lib/jwt/jwk/okp_rbnacl.rb
 - lib/jwt/jwk/rsa.rb
 - lib/jwt/jwk/set.rb
 - lib/jwt/jwk/thumbprint.rb
-- lib/jwt/verify.rb
+- lib/jwt/token.rb
 - lib/jwt/version.rb
 - lib/jwt/x5c_key_finder.rb
 - ruby-jwt.gemspec
@@ -163,9 +199,8 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/jwt/ruby-jwt/issues
-  changelog_uri: https://github.com/jwt/ruby-jwt/blob/v2.8.2/CHANGELOG.md
+  changelog_uri: https://github.com/jwt/ruby-jwt/blob/v3.1.1/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -180,8 +215,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: JSON Web Token implementation in Ruby
 test_files: []

data/lib/jwt/claims_validator.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'error'
-
-module JWT
-  class ClaimsValidator
-    NUMERIC_CLAIMS = %i[
-      exp
-      iat
-      nbf
-    ].freeze
-
-    def initialize(payload)
-      @payload = payload.transform_keys(&:to_sym)
-    end
-
-    def validate!
-      validate_numeric_claims
-
-      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