jwt 2.8.1 → 2.10.3

data/lib/jwt/jwk/ec.rb

@@ -4,6 +4,7 @@ require 'forwardable'
 
 module JWT
   module JWK
+    # JWK representation for Elliptic Curve (EC) keys
     class EC < KeyBase # rubocop:disable Metrics/ClassLength
       KTY    = 'EC'
       KTYS   = [KTY, OpenSSL::PKey::EC, JWT::JWK::EC].freeze
@@ -65,9 +66,7 @@ module JWT
       end
 
       def []=(key, value)
-        if EC_KEY_ELEMENTS.include?(key.to_sym)
-          raise ArgumentError, 'cannot overwrite cryptographic key attributes'
-        end
+        raise ArgumentError, 'cannot overwrite cryptographic key attributes' if EC_KEY_ELEMENTS.include?(key.to_sym)
 
         super(key, value)
       end
@@ -153,26 +152,26 @@ module JWT
           )
 
           sequence = if jwk_d
-            # https://datatracker.ietf.org/doc/html/rfc5915.html
-            # ECPrivateKey ::= SEQUENCE {
-            #   version        INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1),
-            #   privateKey     OCTET STRING,
-            #   parameters [0] ECParameters {{ NamedCurve }} OPTIONAL,
-            #   publicKey  [1] BIT STRING OPTIONAL
-            # }
-
-            OpenSSL::ASN1::Sequence([
-                                      OpenSSL::ASN1::Integer(1),
-                                      OpenSSL::ASN1::OctetString(OpenSSL::BN.new(decode_octets(jwk_d), 2).to_s(2)),
-                                      OpenSSL::ASN1::ObjectId(curve, 0, :EXPLICIT),
-                                      OpenSSL::ASN1::BitString(point.to_octet_string(:uncompressed), 1, :EXPLICIT)
-                                    ])
-          else
-            OpenSSL::ASN1::Sequence([
-                                      OpenSSL::ASN1::Sequence([OpenSSL::ASN1::ObjectId('id-ecPublicKey'), OpenSSL::ASN1::ObjectId(curve)]),
-                                      OpenSSL::ASN1::BitString(point.to_octet_string(:uncompressed))
-                                    ])
-          end
+                       # https://datatracker.ietf.org/doc/html/rfc5915.html
+                       # ECPrivateKey ::= SEQUENCE {
+                       #   version        INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1),
+                       #   privateKey     OCTET STRING,
+                       #   parameters [0] ECParameters {{ NamedCurve }} OPTIONAL,
+                       #   publicKey  [1] BIT STRING OPTIONAL
+                       # }
+
+                       OpenSSL::ASN1::Sequence([
+                                                 OpenSSL::ASN1::Integer(1),
+                                                 OpenSSL::ASN1::OctetString(OpenSSL::BN.new(decode_octets(jwk_d), 2).to_s(2)),
+                                                 OpenSSL::ASN1::ObjectId(curve, 0, :EXPLICIT),
+                                                 OpenSSL::ASN1::BitString(point.to_octet_string(:uncompressed), 1, :EXPLICIT)
+                                               ])
+                     else
+                       OpenSSL::ASN1::Sequence([
+                                                 OpenSSL::ASN1::Sequence([OpenSSL::ASN1::ObjectId('id-ecPublicKey'), OpenSSL::ASN1::ObjectId(curve)]),
+                                                 OpenSSL::ASN1::BitString(point.to_octet_string(:uncompressed))
+                                               ])
+                     end
 
           OpenSSL::PKey::EC.new(sequence.to_der)
         end

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,9 +62,7 @@ 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)
       end

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

data/lib/jwt/jwk/key_finder.rb

@@ -2,16 +2,17 @@
 
 module JWT
   module JWK
+    # @api private
     class KeyFinder
       def initialize(options)
         @allow_nil_kid = options[:allow_nil_kid]
         jwks_or_loader = options[:jwks]
 
         @jwks_loader = if jwks_or_loader.respond_to?(:call)
-          jwks_or_loader
-        else
-          ->(_options) { jwks_or_loader }
-        end
+                         jwks_or_loader
+                       else
+                         ->(_options) { jwks_or_loader }
+                       end
       end
 
       def key_for(kid)

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/okp_rbnacl.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # JSON Web Key (JWK) representation for Ed25519 keys
     class OKPRbNaCl < KeyBase
       KTY  = 'OKP'
       KTYS = [KTY, JWT::JWK::OKPRbNaCl, RbNaCl::Signatures::Ed25519::SigningKey, RbNaCl::Signatures::Ed25519::VerifyKey].freeze
@@ -10,7 +11,7 @@ module JWT
 
       def initialize(key, params = nil, options = {})
         params ||= {}
-
+        Deprecations.warning('Using the OKP JWK for Ed25519 keys is deprecated and will be removed in a future version of ruby-jwt. Please use the ruby-eddsa gem instead.')
         # For backwards compatibility when kid was a String
         params = { kid: params } if params.is_a?(String)
 
@@ -83,9 +84,7 @@ module JWT
           x: ::JWT::Base64.url_encode(verify_key.to_bytes)
         }
 
-        if signing_key
-          params[:d] = ::JWT::Base64.url_encode(signing_key.to_bytes)
-        end
+        params[:d] = ::JWT::Base64.url_encode(signing_key.to_bytes) if signing_key
 
         params
       end

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'
@@ -64,9 +65,7 @@ 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)
       end

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
@@ -25,7 +27,7 @@ module JWT
                   jwks.map { |k| JWT::JWK.new(k, nil, options) }
                 else
                   raise ArgumentError, 'Can only create new JWKS from Hash, Array and JWK'
-        end
+                end
       end
 
       def export(options = {})

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 = {})

data/lib/jwt/token.rb

@@ -0,0 +1,112 @@
+# 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
+    include Claims::VerificationMethods
+
+    # 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 algorithm [String, Object] the algorithm to use for signing.
+    # @param key [String] the key to use for signing.
+    # @return [void]
+    # @raise [JWT::EncodeError] if the token is already signed or other problems when signing
+    def sign!(algorithm:, key:)
+      raise ::JWT::EncodeError, 'Token already signed' if @signature
+
+      JWA.resolve(algorithm).tap do |algo|
+        header.merge!(algo.header)
+        @signature = algo.sign(data: signing_input, signing_key: key)
+      end
+
+      nil
+    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/verify.rb

@@ -1,117 +1,40 @@
 # frozen_string_literal: true
 
-require 'jwt/error'
+require_relative 'error'
 
 module JWT
-  # JWT verify methods
+  # @deprecated This class is deprecated and will be removed in the next major version of ruby-jwt.
   class Verify
-    DEFAULTS = {
-      leeway: 0
-    }.freeze
+    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
 
+    private_constant(:DEFAULTS, :METHODS)
     class << self
-      %w[verify_aud verify_expiration verify_iat verify_iss verify_jti verify_not_before verify_sub verify_required_claims].each do |method_name|
-        define_method method_name do |payload, options|
+      METHODS.each do |method_name|
+        define_method(method_name) do |payload, options|
           new(payload, options).send(method_name)
         end
       end
 
+      # @deprecated This method is deprecated and will be removed in the next major version of ruby-jwt.
       def verify_claims(payload, options)
-        options.each do |key, val|
-          next unless key.to_s =~ /verify/
-
-          Verify.send(key, payload, options) if val
-        end
+        Deprecations.warning('The ::JWT::Verify.verify_claims method is deprecated and will be removed in the next major version of ruby-jwt')
+        ::JWT::Claims.verify!(payload, options)
+        true
       end
     end
 
+    # @deprecated This class is deprecated and will be removed in the next major version of ruby-jwt.
     def initialize(payload, options)
+      Deprecations.warning('The ::JWT::Verify class is deprecated and will be removed in the next major version of ruby-jwt')
       @payload = payload
       @options = DEFAULTS.merge(options)
     end
 
-    def verify_aud
-      return unless (options_aud = @options[:aud])
-
-      aud = @payload['aud']
-      raise(JWT::InvalidAudError, "Invalid audience. Expected #{options_aud}, received #{aud || '<none>'}") if ([*aud] & [*options_aud]).empty?
-    end
-
-    def verify_expiration
-      return unless contains_key?(@payload, 'exp')
-      raise(JWT::ExpiredSignature, 'Signature has expired') if @payload['exp'].to_i <= (Time.now.to_i - exp_leeway)
-    end
-
-    def verify_iat
-      return unless contains_key?(@payload, 'iat')
-
-      iat = @payload['iat']
-      raise(JWT::InvalidIatError, 'Invalid iat') if !iat.is_a?(Numeric) || iat.to_f > Time.now.to_f
-    end
-
-    def verify_iss
-      return unless (options_iss = @options[:iss])
-
-      iss = @payload['iss']
-
-      options_iss = Array(options_iss).map { |item| item.is_a?(Symbol) ? item.to_s : item }
-
-      case iss
-      when *options_iss
-        nil
-      else
-        raise(JWT::InvalidIssuerError, "Invalid issuer. Expected #{options_iss}, received #{iss || '<none>'}")
+    METHODS.each do |method_name|
+      define_method(method_name) do
+        ::JWT::Claims.verify!(@payload, @options.merge(method_name => true))
       end
     end
-
-    def verify_jti
-      options_verify_jti = @options[:verify_jti]
-      jti = @payload['jti']
-
-      if options_verify_jti.respond_to?(:call)
-        verified = options_verify_jti.arity == 2 ? options_verify_jti.call(jti, @payload) : options_verify_jti.call(jti)
-        raise(JWT::InvalidJtiError, 'Invalid jti') unless verified
-      elsif jti.to_s.strip.empty?
-        raise(JWT::InvalidJtiError, 'Missing jti')
-      end
-    end
-
-    def verify_not_before
-      return unless contains_key?(@payload, 'nbf')
-      raise(JWT::ImmatureSignature, 'Signature nbf has not been reached') if @payload['nbf'].to_i > (Time.now.to_i + nbf_leeway)
-    end
-
-    def verify_sub
-      return unless (options_sub = @options[:sub])
-
-      sub = @payload['sub']
-      raise(JWT::InvalidSubError, "Invalid subject. Expected #{options_sub}, received #{sub || '<none>'}") unless sub.to_s == options_sub.to_s
-    end
-
-    def verify_required_claims
-      return unless (options_required_claims = @options[:required_claims])
-
-      options_required_claims.each do |required_claim|
-        raise(JWT::MissingRequiredClaim, "Missing required claim #{required_claim}") unless contains_key?(@payload, required_claim)
-      end
-    end
-
-    private
-
-    def global_leeway
-      @options[:leeway]
-    end
-
-    def exp_leeway
-      @options[:exp_leeway] || global_leeway
-    end
-
-    def nbf_leeway
-      @options[:nbf_leeway] || global_leeway
-    end
-
-    def contains_key?(payload, key)
-      payload.respond_to?(:key?) && payload.key?(key)
-    end
   end
 end

data/lib/jwt/version.rb

@@ -1,44 +1,65 @@
 # 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
+  # @api private
   module VERSION
-    # major version
     MAJOR = 2
-    # minor version
-    MINOR = 8
-    # tiny version
-    TINY  = 1
-    # alpha, beta, etc. tag
+    MINOR = 10
+    TINY  = 3
     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
 
+  # Checks if the RbNaCl library is defined.
+  #
+  # @return [Boolean] true if RbNaCl is defined, false otherwise.
+  # @api private
   def self.rbnacl?
     defined?(::RbNaCl)
   end
 
+  # Checks if the RbNaCl library version is 6.0.0 or greater.
+  #
+  # @return [Boolean] true if RbNaCl version is 6.0.0 or greater, false otherwise.
+  # @api private
   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/x5c_key_finder.rb

@@ -7,7 +7,7 @@ module JWT
   # See https://tools.ietf.org/html/rfc7515#section-4.1.6
   class X5cKeyFinder
     def initialize(root_certificates, crls = nil)
-      raise(ArgumentError, 'Root certificates must be specified') unless root_certificates
+      raise ArgumentError, 'Root certificates must be specified' unless root_certificates
 
       @store = build_store(root_certificates, crls)
     end
@@ -24,7 +24,7 @@ module JWT
           error = "#{error} Certificate subject: #{current_cert.subject}."
         end
 
-        raise(JWT::VerificationError, error)
+        raise JWT::VerificationError, error
       end
     end
 

data/lib/jwt.rb

@@ -9,6 +9,12 @@ require 'jwt/deprecations'
 require 'jwt/encode'
 require 'jwt/error'
 require 'jwt/jwk'
+require 'jwt/claims'
+require 'jwt/encoded_token'
+require 'jwt/token'
+
+require 'jwt/claims_validator'
+require 'jwt/verify'
 
 # JSON Web Token implementation
 #
@@ -19,6 +25,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,7 +39,16 @@ 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
-    Decode.new(jwt, key, verify, configuration.decode.to_h.merge(options), &keyfinder).decode_segments
+    Deprecations.context do
+      Decode.new(jwt, key, verify, configuration.decode.to_h.merge(options), &keyfinder).decode_segments
+    end
   end
 end

data/ruby-jwt.gemspec

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