jwt 2.9.3 → 2.10.0

data/lib/jwt/encode.rb

@@ -2,68 +2,29 @@
 
 require_relative 'jwa'
 
-# JWT::Encode module
 module JWT
-  # Encoding logic for JWT
+  # The Encode class is responsible for encoding JWT tokens.
   class Encode
+    # Initializes a new Encode instance.
+    #
+    # @param options [Hash] the options for encoding the JWT token.
+    # @option options [Hash] :payload the payload of the JWT token.
+    # @option options [Hash] :headers the headers of the JWT token.
+    # @option options [String] :key the key used to sign the JWT token.
+    # @option options [String] :algorithm the algorithm used to sign the JWT token.
     def initialize(options)
-      @payload          = options[:payload]
-      @key              = options[:key]
-      @algorithm        = JWA.resolve(options[:algorithm])
-      @headers          = options[:headers].transform_keys(&:to_s)
+      @token     = Token.new(payload: options[:payload], header: options[:headers])
+      @key       = options[:key]
+      @algorithm = options[:algorithm]
     end
 
+    # Encodes the JWT token and returns its segments.
+    #
+    # @return [String] the encoded JWT token.
     def segments
-      validate_claims!
-      combine(encoded_header_and_payload, encoded_signature)
-    end
-
-    private
-
-    def encoded_header
-      @encoded_header ||= encode_header
-    end
-
-    def encoded_payload
-      @encoded_payload ||= encode_payload
-    end
-
-    def encoded_signature
-      @encoded_signature ||= encode_signature
-    end
-
-    def encoded_header_and_payload
-      @encoded_header_and_payload ||= combine(encoded_header, encoded_payload)
-    end
-
-    def encode_header
-      encode_data(@headers.merge(@algorithm.header(signing_key: @key)))
-    end
-
-    def encode_payload
-      encode_data(@payload)
-    end
-
-    def signature
-      @algorithm.sign(data: encoded_header_and_payload, signing_key: @key)
-    end
-
-    def validate_claims!
-      return unless @payload.is_a?(Hash)
-
-      Claims.verify_payload!(@payload, :numeric)
-    end
-
-    def encode_signature
-      ::JWT::Base64.url_encode(signature)
-    end
-
-    def encode_data(data)
-      ::JWT::Base64.url_encode(JWT::JSON.generate(data))
-    end
-
-    def combine(*parts)
-      parts.join('.')
+      @token.verify_claims!(:numeric)
+      @token.sign!(algorithm: @algorithm, key: @key)
+      @token.jwt
     end
   end
 end

data/lib/jwt/encoded_token.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module JWT
+  # Represents an encoded JWT token
+  #
+  # Processing an encoded and signed token:
+  #
+  #   token = JWT::Token.new(payload: {pay: 'load'})
+  #   token.sign!(algorithm: 'HS256', key: 'secret')
+  #
+  #   encoded_token = JWT::EncodedToken.new(token.jwt)
+  #   encoded_token.verify_signature!(algorithm: 'HS256', key: 'secret')
+  #   encoded_token.payload # => {'pay' => 'load'}
+  class EncodedToken
+    include Claims::VerificationMethods
+
+    # Returns the original token provided to the class.
+    # @return [String] The JWT token.
+    attr_reader :jwt
+
+    # Initializes a new EncodedToken instance.
+    #
+    # @param jwt [String] the encoded JWT token.
+    # @raise [ArgumentError] if the provided JWT is not a String.
+    def initialize(jwt)
+      raise ArgumentError, 'Provided JWT must be a String' unless jwt.is_a?(String)
+
+      @jwt = jwt
+      @encoded_header, @encoded_payload, @encoded_signature = jwt.split('.')
+    end
+
+    # Returns the decoded signature of the JWT token.
+    #
+    # @return [String] the decoded signature.
+    def signature
+      @signature ||= ::JWT::Base64.url_decode(encoded_signature || '')
+    end
+
+    # Returns the encoded signature of the JWT token.
+    #
+    # @return [String] the encoded signature.
+    attr_reader :encoded_signature
+
+    # Returns the decoded header of the JWT token.
+    #
+    # @return [Hash] the header.
+    def header
+      @header ||= parse_and_decode(@encoded_header)
+    end
+
+    # Returns the encoded header of the JWT token.
+    #
+    # @return [String] the encoded header.
+    attr_reader :encoded_header
+
+    # Returns the payload of the JWT token.
+    #
+    # @return [Hash] the payload.
+    def payload
+      @payload ||= decode_payload
+    end
+
+    # Sets or returns the encoded payload of the JWT token.
+    #
+    # @return [String] the encoded payload.
+    attr_accessor :encoded_payload
+
+    # Returns the signing input of the JWT token.
+    #
+    # @return [String] the signing input.
+    def signing_input
+      [encoded_header, encoded_payload].join('.')
+    end
+
+    # Verifies the signature of the JWT token.
+    #
+    # @param algorithm [String, Array<String>, Object, Array<Object>] the algorithm(s) to use for verification.
+    # @param key [String, Array<String>] the key(s) to use for verification.
+    # @param key_finder [#call] an object responding to `call` to find the key for verification.
+    # @return [nil]
+    # @raise [JWT::VerificationError] if the signature verification fails.
+    # @raise [ArgumentError] if neither key nor key_finder is provided, or if both are provided.
+    def verify_signature!(algorithm:, key: nil, key_finder: nil)
+      raise ArgumentError, 'Provide either key or key_finder, not both or neither' if key.nil? == key_finder.nil?
+
+      key ||= key_finder.call(self)
+
+      return if valid_signature?(algorithm: algorithm, key: key)
+
+      raise JWT::VerificationError, 'Signature verification failed'
+    end
+
+    # Checks if the signature of the JWT token is valid.
+    #
+    # @param algorithm [String, Array<String>, Object, Array<Object>] the algorithm(s) to use for verification.
+    # @param key [String, Array<String>] the key(s) to use for verification.
+    # @return [Boolean] true if the signature is valid, false otherwise.
+    def valid_signature?(algorithm:, key:)
+      Array(JWA.resolve_and_sort(algorithms: algorithm, preferred_algorithm: header['alg'])).any? do |algo|
+        Array(key).any? do |one_key|
+          algo.verify(data: signing_input, signature: signature, verification_key: one_key)
+        end
+      end
+    end
+
+    alias to_s jwt
+
+    private
+
+    def decode_payload
+      raise JWT::DecodeError, 'Encoded payload is empty' if encoded_payload == ''
+
+      if unencoded_payload?
+        verify_claims!(crit: ['b64'])
+        return parse_unencoded(encoded_payload)
+      end
+
+      parse_and_decode(encoded_payload)
+    end
+
+    def unencoded_payload?
+      header['b64'] == false
+    end
+
+    def parse_and_decode(segment)
+      parse(::JWT::Base64.url_decode(segment || ''))
+    end
+
+    def parse_unencoded(segment)
+      parse(segment)
+    end
+
+    def parse(segment)
+      JWT::JSON.parse(segment)
+    rescue ::JSON::ParserError
+      raise JWT::DecodeError, 'Invalid segment encoding'
+    end
+  end
+end

data/lib/jwt/error.rb

@@ -1,23 +1,57 @@
 # frozen_string_literal: true
 
 module JWT
+  # The EncodeError class is raised when there is an error encoding a JWT.
   class EncodeError < StandardError; end
+
+  # The DecodeError class is raised when there is an error decoding a JWT.
   class DecodeError < StandardError; end
+
+  # The RequiredDependencyError class is raised when a required dependency is missing.
   class RequiredDependencyError < StandardError; end
 
+  # The VerificationError class is raised when there is an error verifying a JWT.
   class VerificationError < DecodeError; end
+
+  # The ExpiredSignature class is raised when the JWT signature has expired.
   class ExpiredSignature < DecodeError; end
+
+  # The IncorrectAlgorithm class is raised when the JWT algorithm is incorrect.
   class IncorrectAlgorithm < DecodeError; end
+
+  # The ImmatureSignature class is raised when the JWT signature is immature.
   class ImmatureSignature < DecodeError; end
+
+  # The InvalidIssuerError class is raised when the JWT issuer is invalid.
   class InvalidIssuerError < DecodeError; end
+
+  # The UnsupportedEcdsaCurve class is raised when the ECDSA curve is unsupported.
   class UnsupportedEcdsaCurve < IncorrectAlgorithm; end
+
+  # The InvalidIatError class is raised when the JWT issued at (iat) claim is invalid.
   class InvalidIatError < DecodeError; end
+
+  # The InvalidAudError class is raised when the JWT audience (aud) claim is invalid.
   class InvalidAudError < DecodeError; end
+
+  # The InvalidSubError class is raised when the JWT subject (sub) claim is invalid.
   class InvalidSubError < DecodeError; end
+
+  # The InvalidCritError class is raised when the JWT crit header is invalid.
+  class InvalidCritError < DecodeError; end
+
+  # The InvalidJtiError class is raised when the JWT ID (jti) claim is invalid.
   class InvalidJtiError < DecodeError; end
+
+  # The InvalidPayload class is raised when the JWT payload is invalid.
   class InvalidPayload < DecodeError; end
+
+  # The MissingRequiredClaim class is raised when a required claim is missing from the JWT.
   class MissingRequiredClaim < DecodeError; end
+
+  # The Base64DecodeError class is raised when there is an error decoding a Base64-encoded string.
   class Base64DecodeError < DecodeError; end
 
+  # The JWKError class is raised when there is an error with the JSON Web Key (JWK).
   class JWKError < DecodeError; end
 end

data/lib/jwt/json.rb

@@ -3,7 +3,7 @@
 require 'json'
 
 module JWT
-  # JSON wrapper
+  # @api private
   class JSON
     class << self
       def generate(data)

data/lib/jwt/jwa/compat.rb

@@ -2,7 +2,10 @@
 
 module JWT
   module JWA
+    # Provides backwards compatibility for algorithms
+    # @api private
     module Compat
+      # @api private
       module ClassMethods
         def from_algorithm(algorithm)
           new(algorithm)

data/lib/jwt/jwa/ecdsa.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # ECDSA signing algorithm
     class Ecdsa
       include JWT::JWA::SigningAlgorithm
 
@@ -13,9 +14,7 @@ module JWT
       def sign(data:, signing_key:)
         curve_definition = curve_by_name(signing_key.group.curve_name)
         key_algorithm = curve_definition[:algorithm]
-        if alg != key_algorithm
-          raise IncorrectAlgorithm, "payload algorithm is #{alg} but #{key_algorithm} signing key was provided"
-        end
+        raise IncorrectAlgorithm, "payload algorithm is #{alg} but #{key_algorithm} signing key was provided" if alg != key_algorithm
 
         asn1_to_raw(signing_key.dsa_sign_asn1(digest.digest(data)), signing_key)
       end
@@ -23,9 +22,7 @@ module JWT
       def verify(data:, signature:, verification_key:)
         curve_definition = curve_by_name(verification_key.group.curve_name)
         key_algorithm = curve_definition[:algorithm]
-        if alg != key_algorithm
-          raise IncorrectAlgorithm, "payload algorithm is #{alg} but #{key_algorithm} verification key was provided"
-        end
+        raise IncorrectAlgorithm, "payload algorithm is #{alg} but #{key_algorithm} verification key was provided" if alg != key_algorithm
 
         verification_key.dsa_verify_asn1(digest.digest(data), raw_to_asn1(signature, verification_key))
       rescue OpenSSL::PKey::PKeyError

data/lib/jwt/jwa/eddsa.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the EdDSA family of algorithms
     class Eddsa
       include JWT::JWA::SigningAlgorithm
 
@@ -10,17 +11,17 @@ module JWT
       end
 
       def sign(data:, signing_key:)
-        unless signing_key.is_a?(RbNaCl::Signatures::Ed25519::SigningKey)
-          raise_encode_error!("Key given is a #{signing_key.class} but has to be an RbNaCl::Signatures::Ed25519::SigningKey")
-        end
+        raise_sign_error!("Key given is a #{signing_key.class} but has to be an RbNaCl::Signatures::Ed25519::SigningKey") unless signing_key.is_a?(RbNaCl::Signatures::Ed25519::SigningKey)
+
+        Deprecations.warning('Using Ed25519 keys is deprecated and will be removed in a future version of ruby-jwt. Please use the ruby-eddsa gem instead.')
 
         signing_key.sign(data)
       end
 
       def verify(data:, signature:, verification_key:)
-        unless verification_key.is_a?(RbNaCl::Signatures::Ed25519::VerifyKey)
-          raise_decode_error!("key given is a #{verification_key.class} but has to be a RbNaCl::Signatures::Ed25519::VerifyKey")
-        end
+        raise_verify_error!("key given is a #{verification_key.class} but has to be a RbNaCl::Signatures::Ed25519::VerifyKey") unless verification_key.is_a?(RbNaCl::Signatures::Ed25519::VerifyKey)
+
+        Deprecations.warning('Using Ed25519 keys is deprecated and will be removed in a future version of ruby-jwt. Please use the ruby-eddsa gem instead.')
 
         verification_key.verify(signature, data)
       rescue RbNaCl::CryptoError

data/lib/jwt/jwa/hmac.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the HMAC family of algorithms
     class Hmac
       include JWT::JWA::SigningAlgorithm
 
@@ -20,9 +21,7 @@ module JWT
 
         OpenSSL::HMAC.digest(digest.new, signing_key, data)
       rescue OpenSSL::HMACError => e
-        if signing_key == '' && e.message == 'EVP_PKEY_new_mac_key: malloc failure'
-          raise_verify_error!('OpenSSL 3.0 does not support nil or empty hmac_secret')
-        end
+        raise_verify_error!('OpenSSL 3.0 does not support nil or empty hmac_secret') if signing_key == '' && e.message == 'EVP_PKEY_new_mac_key: malloc failure'
 
         raise e
       end

data/lib/jwt/jwa/hmac_rbnacl.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the HMAC family of algorithms (using RbNaCl)
     class HmacRbNaCl
       include JWT::JWA::SigningAlgorithm
 

data/lib/jwt/jwa/hmac_rbnacl_fixed.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the HMAC family of algorithms (using RbNaCl prior to a certain version)
     class HmacRbNaClFixed
       include JWT::JWA::SigningAlgorithm
 

data/lib/jwt/jwa/none.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the none algorithm
     class None
       include JWT::JWA::SigningAlgorithm
 

data/lib/jwt/jwa/ps.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the RSASSA-PSS family of algorithms
     class Ps
       include JWT::JWA::SigningAlgorithm
 
@@ -11,9 +12,7 @@ module JWT
       end
 
       def sign(data:, signing_key:)
-        unless signing_key.is_a?(::OpenSSL::PKey::RSA)
-          raise_sign_error!("The given key is a #{signing_key.class}. It has to be an OpenSSL::PKey::RSA instance.")
-        end
+        raise_sign_error!("The given key is a #{signing_key.class}. It has to be an OpenSSL::PKey::RSA instance.") unless signing_key.is_a?(::OpenSSL::PKey::RSA)
 
         signing_key.sign_pss(digest_algorithm, data, salt_length: :digest, mgf1_hash: digest_algorithm)
       end

data/lib/jwt/jwa/rsa.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Implementation of the RSA family of algorithms
     class Rsa
       include JWT::JWA::SigningAlgorithm
 
@@ -11,9 +12,7 @@ module JWT
       end
 
       def sign(data:, signing_key:)
-        unless signing_key.is_a?(OpenSSL::PKey::RSA)
-          raise_sign_error!("The given key is a #{signing_key.class}. It has to be an OpenSSL::PKey::RSA instance")
-        end
+        raise_sign_error!("The given key is a #{signing_key.class}. It has to be an OpenSSL::PKey::RSA instance") unless signing_key.is_a?(OpenSSL::PKey::RSA)
 
         signing_key.sign(digest, data)
       end

data/lib/jwt/jwa/signing_algorithm.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 module JWT
+  # JSON Web Algorithms
   module JWA
+    # Base functionality for signing algorithms
     module SigningAlgorithm
+      # Class methods for the SigningAlgorithm module
       module ClassMethods
         def register_algorithm(algo)
           ::JWT::JWA.register_algorithm(algo)

data/lib/jwt/jwa/unsupported.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # Represents an unsupported algorithm
     module Unsupported
       class << self
         include JWT::JWA::SigningAlgorithm

data/lib/jwt/jwa/wrapper.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWA
+    # @api private
     class Wrapper
       include SigningAlgorithm
 

data/lib/jwt/jwa.rb

@@ -18,9 +18,7 @@ require_relative 'jwa/rsa'
 require_relative 'jwa/unsupported'
 require_relative 'jwa/wrapper'
 
-if JWT.rbnacl?
-  require_relative 'jwa/eddsa'
-end
+require_relative 'jwa/eddsa' if JWT.rbnacl?
 
 if JWT.rbnacl_6_or_greater?
   require_relative 'jwa/hmac_rbnacl'
@@ -29,8 +27,10 @@ elsif JWT.rbnacl?
 end
 
 module JWT
+  # The JWA module contains all supported algorithms.
   module JWA
     class << self
+      # @api private
       def resolve(algorithm)
         return find(algorithm) if algorithm.is_a?(String) || algorithm.is_a?(Symbol)
 
@@ -42,7 +42,15 @@ module JWT
         algorithm
       end
 
+      # @api private
+      def resolve_and_sort(algorithms:, preferred_algorithm:)
+        algs = Array(algorithms).map { |alg| JWA.resolve(alg) }
+        algs.partition { |alg| alg.valid_alg?(preferred_algorithm) }.flatten
+      end
+
+      # @deprecated The `::JWT::JWA.create` method is deprecated and will be removed in the next major version of ruby-jwt.
       def create(algorithm)
+        Deprecations.warning('The ::JWT::JWA.create method is deprecated and will be removed in the next major version of ruby-jwt.')
         resolve(algorithm)
       end
     end

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

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,6 +2,7 @@
 
 module JWT
   module JWK
+    # @api private
     class KeyFinder
       def initialize(options)
         @allow_nil_kid = options[:allow_nil_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

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