oauth2 2.0.9 → 2.0.17

data/lib/oauth2/error.rb

@@ -1,55 +1,73 @@
 # frozen_string_literal: true
 
 module OAuth2
+  # Represents an OAuth2 error condition.
+  #
+  # Wraps details from an OAuth2::Response or Hash payload returned by an
+  # authorization server, exposing error code and description per RFC 6749.
   class Error < StandardError
+    # @return [OAuth2::Response, Hash, Object] Original response or payload used to build the error
+    # @return [String] Raw body content (if available)
+    # @return [String, nil] Error code (e.g., 'invalid_grant')
+    # @return [String, nil] Human-readable description for the error
     attr_reader :response, :body, :code, :description
 
-    # standard error codes include:
-    # 'invalid_request', 'invalid_client', 'invalid_token', 'invalid_grant', 'unsupported_grant_type', 'invalid_scope'
-    # response might be a Response object, or the response.parsed hash
+    # Create a new OAuth2::Error
+    #
+    # @param [OAuth2::Response, Hash, Object] response A Response or error payload
     def initialize(response)
       @response = response
       if response.respond_to?(:parsed)
         if response.parsed.is_a?(Hash)
-          @code = response.parsed['error']
-          @description = response.parsed['error_description']
+          @code = response.parsed["error"]
+          @description = response.parsed["error_description"]
         end
       elsif response.is_a?(Hash)
-        @code = response['error']
-        @description = response['error_description']
+        @code = response["error"]
+        @description = response["error_description"]
       end
       @body = if response.respond_to?(:body)
-                response.body
-              else
-                @response
-              end
+        response.body
+      else
+        @response
+      end
       message_opts = parse_error_description(@code, @description)
       super(error_message(@body, message_opts))
     end
 
   private
 
+    # Builds a multi-line error message including description and raw body.
+    #
+    # @param [String, #encode] response_body Response body content
+    # @param [Hash] opts Options including :error_description
+    # @return [String] Message suitable for StandardError
     def error_message(response_body, opts = {})
       lines = []
 
       lines << opts[:error_description] if opts[:error_description]
 
       error_string = if response_body.respond_to?(:encode) && opts[:error_description].respond_to?(:encoding)
-                       script_encoding = opts[:error_description].encoding
-                       response_body.encode(script_encoding, invalid: :replace, undef: :replace)
-                     else
-                       response_body
-                     end
+        script_encoding = opts[:error_description].encoding
+        response_body.encode(script_encoding, invalid: :replace, undef: :replace)
+      else
+        response_body
+      end
 
       lines << error_string
 
       lines.join("\n")
     end
 
+    # Formats the OAuth2 error code and description into a single string.
+    #
+    # @param [String, nil] code OAuth2 error code
+    # @param [String, nil] description OAuth2 error description
+    # @return [Hash] Options hash containing :error_description when present
     def parse_error_description(code, description)
       return {} unless code || description
 
-      error_description = ''
+      error_description = ""
       error_description += "#{code}: " if code
       error_description += description if description
 

data/lib/oauth2/filtered_attributes.rb

@@ -0,0 +1,52 @@
+module OAuth2
+  # Mixin that redacts sensitive instance variables in #inspect output.
+  #
+  # Classes include this module and declare which attributes should be filtered
+  # using {.filtered_attributes}. Any instance variable name that includes one of
+  # those attribute names will be shown as [FILTERED] in the object's inspect.
+  module FilteredAttributes
+    # Hook invoked when the module is included. Extends the including class with
+    # class-level helpers.
+    #
+    # @param [Class] base The including class
+    # @return [void]
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class-level helpers for configuring filtered attributes.
+    module ClassMethods
+      # Declare attributes that should be redacted in inspect output.
+      #
+      # @param [Array<Symbol, String>] attributes One or more attribute names
+      # @return [void]
+      def filtered_attributes(*attributes)
+        @filtered_attribute_names = attributes.map(&:to_sym)
+      end
+
+      # The configured attribute names to filter.
+      #
+      # @return [Array<Symbol>]
+      def filtered_attribute_names
+        @filtered_attribute_names || []
+      end
+    end
+
+    # Custom inspect that redacts configured attributes.
+    #
+    # @return [String]
+    def inspect
+      filtered_attribute_names = self.class.filtered_attribute_names
+      return super if filtered_attribute_names.empty?
+
+      inspected_vars = instance_variables.map do |var|
+        if filtered_attribute_names.any? { |filtered_var| var.to_s.include?(filtered_var.to_s) }
+          "#{var}=[FILTERED]"
+        else
+          "#{var}=#{instance_variable_get(var).inspect}"
+        end
+      end
+      "#<#{self.class}:#{object_id} #{inspected_vars.join(", ")}>"
+    end
+  end
+end

data/lib/oauth2/response.rb

@@ -1,37 +1,55 @@
 # frozen_string_literal: true
 
-require 'json'
-require 'multi_xml'
-require 'rack'
+require "json"
+require "multi_xml"
+require "rack"
 
 module OAuth2
-  # OAuth2::Response class
+  # The Response class handles HTTP responses in the OAuth2 gem, providing methods
+  # to access and parse response data in various formats.
+  #
+  # @since 1.0.0
   class Response
+    # Default configuration options for Response instances
+    #
+    # @return [Hash] The default options hash
     DEFAULT_OPTIONS = {
       parse: :automatic,
       snaky: true,
+      snaky_hash_klass: SnakyHash::StringKeyed,
     }.freeze
+
+    # @return [Faraday::Response] The raw Faraday response object
     attr_reader :response
+
+    # @return [Hash] The options hash for this instance
     attr_accessor :options
 
-    # Procs that, when called, will parse a response body according
-    # to the specified format.
+    # @private
+    # Storage for response body parser procedures
+    #
+    # @return [Hash<Symbol, Proc>] Hash of parser procs keyed by format symbol
     @@parsers = {
       query: ->(body) { Rack::Utils.parse_query(body) },
       text: ->(body) { body },
     }
 
-    # Content type assignments for various potential HTTP content types.
+    # @private
+    # Maps content types to parser symbols
+    #
+    # @return [Hash<String, Symbol>] Hash of content types mapped to parser symbols
     @@content_types = {
-      'application/x-www-form-urlencoded' => :query,
-      'text/plain' => :text,
+      "application/x-www-form-urlencoded" => :query,
+      "text/plain" => :text,
     }
 
     # Adds a new content type parser.
     #
-    # @param [Symbol] key A descriptive symbol key such as :json or :query.
-    # @param [Array] mime_types One or more mime types to which this parser applies.
-    # @yield [String] A block returning parsed content.
+    # @param [Symbol] key A descriptive symbol key such as :json or :query
+    # @param [Array<String>, String] mime_types One or more mime types to which this parser applies
+    # @yield [String] Block that will be called to parse the response body
+    # @yieldparam [String] body The response body to parse
+    # @return [void]
     def self.register_parser(key, mime_types, &block)
       key = key.to_sym
       @@parsers[key] = block
@@ -43,38 +61,48 @@ module OAuth2
     # Initializes a Response instance
     #
     # @param [Faraday::Response] response The Faraday response instance
-    # @param [Symbol] parse (:automatic) how to parse the response body.  one of :query (for x-www-form-urlencoded),
-    #   :json, or :automatic (determined by Content-Type response header)
-    # @param [true, false] snaky (true) Convert @parsed to a snake-case,
-    #   indifferent-access SnakyHash::StringKeyed, which is a subclass of Hashie::Mash (from hashie gem)?
-    # @param [Hash] options all other options for initializing the instance
-    def initialize(response, parse: :automatic, snaky: true, **options)
+    # @param [Symbol] parse (:automatic) How to parse the response body
+    # @param [Boolean] snaky (true) Whether to convert parsed response to snake_case using SnakyHash
+    # @param [Class, nil] snaky_hash_klass (nil) Custom class for snake_case hash conversion
+    # @param [Hash] options Additional options for the response
+    # @option options [Symbol] :parse (:automatic) Parse strategy (:query, :json, or :automatic)
+    # @option options [Boolean] :snaky (true) Enable/disable snake_case conversion
+    # @option options [Class] :snaky_hash_klass (SnakyHash::StringKeyed) Class to use for hash conversion
+    # @return [OAuth2::Response] The new Response instance
+    def initialize(response, parse: :automatic, snaky: true, snaky_hash_klass: nil, **options)
       @response = response
       @options = {
         parse: parse,
         snaky: snaky,
+        snaky_hash_klass: snaky_hash_klass,
       }.merge(options)
     end
 
     # The HTTP response headers
+    #
+    # @return [Hash] The response headers
     def headers
       response.headers
     end
 
     # The HTTP response status code
+    #
+    # @return [Integer] The response status code
     def status
       response.status
     end
 
     # The HTTP response body
+    #
+    # @return [String] The response body or empty string if nil
     def body
-      response.body || ''
+      response.body || ""
     end
 
-    # The {#response} {#body} as parsed by {#parser}.
+    # The parsed response body
     #
-    # @return [Object] As returned by {#parser} if it is #call-able.
-    # @return [nil] If the {#parser} is not #call-able.
+    # @return [Object, SnakyHash::StringKeyed] The parsed response body
+    # @return [nil] If no parser is available
     def parsed
       return @parsed if defined?(@parsed)
 
@@ -90,34 +118,37 @@ module OAuth2
           end
         end
 
-      @parsed = SnakyHash::StringKeyed.new(@parsed) if options[:snaky] && @parsed.is_a?(Hash)
+      if options[:snaky] && @parsed.is_a?(Hash)
+        hash_klass = options[:snaky_hash_klass] || DEFAULT_OPTIONS[:snaky_hash_klass]
+        @parsed = hash_klass[@parsed]
+      end
 
       @parsed
     end
 
-    # Attempts to determine the content type of the response.
+    # Determines the content type of the response
+    #
+    # @return [String, nil] The content type or nil if headers are not present
     def content_type
-      return nil unless response.headers
+      return unless response.headers
 
-      ((response.headers.values_at('content-type', 'Content-Type').compact.first || '').split(';').first || '').strip.downcase
+      ((response.headers.values_at("content-type", "Content-Type").compact.first || "").split(";").first || "").strip.downcase
     end
 
-    # Determines the parser (a Proc or other Object which responds to #call)
-    # that will be passed the {#body} (and optional {#response}) to supply
-    # {#parsed}.
+    # Determines the parser to be used for the response body
     #
-    # The parser can be supplied as the +:parse+ option in the form of a Proc
-    # (or other Object responding to #call) or a Symbol. In the latter case,
-    # the actual parser will be looked up in {@@parsers} by the supplied Symbol.
+    # @note The parser can be supplied as the +:parse+ option in the form of a Proc
+    #       (or other Object responding to #call) or a Symbol. In the latter case,
+    #       the actual parser will be looked up in {@@parsers} by the supplied Symbol.
     #
-    # If no +:parse+ option is supplied, the lookup Symbol will be determined
-    # by looking up {#content_type} in {@@content_types}.
+    # @note If no +:parse+ option is supplied, the lookup Symbol will be determined
+    #       by looking up {#content_type} in {@@content_types}.
     #
-    # If {#parser} is a Proc, it will be called with no arguments, just
-    # {#body}, or {#body} and {#response}, depending on the Proc's arity.
+    # @note If {#parser} is a Proc, it will be called with no arguments, just
+    #       {#body}, or {#body} and {#response}, depending on the Proc's arity.
     #
-    # @return [Proc, #call] If a parser was found.
-    # @return [nil] If no parser was found.
+    # @return [Proc, #call] The parser proc or callable object
+    # @return [nil] If no suitable parser is found
     def parser
       return @parser if defined?(@parser)
 
@@ -133,16 +164,21 @@ module OAuth2
   end
 end
 
-OAuth2::Response.register_parser(:xml, ['text/xml', 'application/rss+xml', 'application/rdf+xml', 'application/atom+xml', 'application/xml']) do |body|
+# Register XML parser
+# @api private
+OAuth2::Response.register_parser(:xml, ["text/xml", "application/rss+xml", "application/rdf+xml", "application/atom+xml", "application/xml"]) do |body|
   next body unless body.respond_to?(:to_str)
 
   MultiXml.parse(body)
 end
 
-OAuth2::Response.register_parser(:json, ['application/json', 'text/javascript', 'application/hal+json', 'application/vnd.collection+json', 'application/vnd.api+json', 'application/problem+json']) do |body|
+# Register JSON parser
+# @api private
+OAuth2::Response.register_parser(:json, ["application/json", "text/javascript", "application/hal+json", "application/vnd.collection+json", "application/vnd.api+json", "application/problem+json"]) do |body|
   next body unless body.respond_to?(:to_str)
 
-  body = body.dup.force_encoding(::Encoding::ASCII_8BIT) if body.respond_to?(:force_encoding)
+  body = body.dup.force_encoding(Encoding::ASCII_8BIT) if body.respond_to?(:force_encoding)
+  next body if body.respond_to?(:empty?) && body.empty?
 
-  ::JSON.parse(body)
+  JSON.parse(body)
 end

data/lib/oauth2/strategy/assertion.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'jwt'
+require "jwt"
 
 module OAuth2
   module Strategy
@@ -34,7 +34,7 @@ module OAuth2
       #
       # @raise [NotImplementedError]
       def authorize_url
-        raise(NotImplementedError, 'The authorization endpoint is not used in this strategy')
+        raise(NotImplementedError, "The authorization endpoint is not used in this strategy")
       end
 
       # Retrieve an access token given the specified client.
@@ -87,15 +87,18 @@ module OAuth2
 
       def build_request(assertion, request_opts = {})
         {
-          grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+          grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
           assertion: assertion,
         }.merge(request_opts)
       end
 
       def build_assertion(claims, encoding_opts)
-        raise ArgumentError.new(message: 'Please provide an encoding_opts hash with :algorithm and :key') if !encoding_opts.is_a?(Hash) || (%i[algorithm key] - encoding_opts.keys).any?
+        raise ArgumentError.new(message: "Please provide an encoding_opts hash with :algorithm and :key") if !encoding_opts.is_a?(Hash) || (%i[algorithm key] - encoding_opts.keys).any?
 
-        JWT.encode(claims, encoding_opts[:key], encoding_opts[:algorithm])
+        headers = {}
+        headers[:kid] = encoding_opts[:kid] if encoding_opts.key?(:kid)
+
+        JWT.encode(claims, encoding_opts[:key], encoding_opts[:algorithm], headers)
       end
     end
   end

data/lib/oauth2/strategy/auth_code.rb

@@ -4,13 +4,23 @@ module OAuth2
   module Strategy
     # The Authorization Code Strategy
     #
+    # OAuth 2.1 notes:
+    # - PKCE is required for all OAuth clients using the authorization code flow (especially public clients).
+    #   This library does not enforce PKCE generation/verification; implement PKCE in your application when required.
+    # - Redirect URIs must be compared using exact string matching by the Authorization Server.
+    #   This client forwards redirect_uri but does not perform server-side validation.
+    #
+    # References:
+    # - OAuth 2.1 draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13
+    # - OAuth for native apps (RFC 8252) and PKCE (RFC 7636)
+    #
     # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-15#section-4.1
     class AuthCode < Base
       # The required query parameters for the authorize URL
       #
       # @param [Hash] params additional query parameters
       def authorize_params(params = {})
-        params.merge('response_type' => 'code', 'client_id' => @client.id)
+        params.merge("response_type" => "code", "client_id" => @client.id)
       end
 
       # The authorization URL endpoint of the provider
@@ -28,7 +38,7 @@ module OAuth2
       # @param [Hash] opts access_token_opts, @see Client#get_token
       # @note that you must also provide a :redirect_uri with most OAuth 2.0 providers
       def get_token(code, params = {}, opts = {})
-        params = {'grant_type' => 'authorization_code', 'code' => code}.merge(@client.redirection_params).merge(params)
+        params = {"grant_type" => "authorization_code", "code" => code}.merge(@client.redirection_params).merge(params)
         params_dup = params.dup
         params.each_key do |key|
           params_dup[key.to_s] = params_dup.delete(key) if key.is_a?(Symbol)
@@ -40,7 +50,7 @@ module OAuth2
     private
 
       def assert_valid_params(params)
-        raise(ArgumentError, 'client_secret is not allowed in authorize URL query params') if params.key?(:client_secret) || params.key?('client_secret')
+        raise(ArgumentError, "client_secret is not allowed in authorize URL query params") if params.key?(:client_secret) || params.key?("client_secret")
       end
     end
   end

data/lib/oauth2/strategy/client_credentials.rb

@@ -10,7 +10,7 @@ module OAuth2
       #
       # @raise [NotImplementedError]
       def authorize_url
-        raise(NotImplementedError, 'The authorization endpoint is not used in this strategy')
+        raise(NotImplementedError, "The authorization endpoint is not used in this strategy")
       end
 
       # Retrieve an access token given the specified client.
@@ -18,7 +18,7 @@ module OAuth2
       # @param [Hash] params additional params
       # @param [Hash] opts options
       def get_token(params = {}, opts = {})
-        params = params.merge('grant_type' => 'client_credentials')
+        params = params.merge("grant_type" => "client_credentials")
         @client.get_token(params, opts)
       end
     end

data/lib/oauth2/strategy/implicit.rb

@@ -4,13 +4,21 @@ module OAuth2
   module Strategy
     # The Implicit Strategy
     #
+    # IMPORTANT (OAuth 2.1): The Implicit grant (response_type=token) is omitted from the OAuth 2.1 draft specification.
+    # It remains here for backward compatibility with OAuth 2.0 providers. Prefer the Authorization Code flow with PKCE.
+    #
+    # References:
+    # - OAuth 2.1 draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13
+    # - Why drop implicit: https://aaronparecki.com/2019/12/12/21/its-time-for-oauth-2-dot-1
+    # - Background: https://fusionauth.io/learn/expert-advice/oauth/differences-between-oauth-2-oauth-2-1/
+    #
     # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-26#section-4.2
     class Implicit < Base
       # The required query parameters for the authorize URL
       #
       # @param [Hash] params additional query parameters
       def authorize_params(params = {})
-        params.merge('response_type' => 'token', 'client_id' => @client.id)
+        params.merge("response_type" => "token", "client_id" => @client.id)
       end
 
       # The authorization URL endpoint of the provider
@@ -25,13 +33,13 @@ module OAuth2
       #
       # @raise [NotImplementedError]
       def get_token(*)
-        raise(NotImplementedError, 'The token is accessed differently in this strategy')
+        raise(NotImplementedError, "The token is accessed differently in this strategy")
       end
 
     private
 
       def assert_valid_params(params)
-        raise(ArgumentError, 'client_secret is not allowed in authorize URL query params') if params.key?(:client_secret) || params.key?('client_secret')
+        raise(ArgumentError, "client_secret is not allowed in authorize URL query params") if params.key?(:client_secret) || params.key?("client_secret")
       end
     end
   end

data/lib/oauth2/strategy/password.rb

@@ -4,13 +4,21 @@ module OAuth2
   module Strategy
     # The Resource Owner Password Credentials Authorization Strategy
     #
+    # IMPORTANT (OAuth 2.1): The Resource Owner Password Credentials grant is omitted in OAuth 2.1.
+    # It remains here for backward compatibility with OAuth 2.0 providers. Prefer Authorization Code + PKCE.
+    #
+    # References:
+    # - OAuth 2.1 draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13
+    # - Okta explainer: https://developer.okta.com/blog/2019/12/13/oauth-2-1-how-many-rfcs
+    # - FusionAuth blog: https://fusionauth.io/blog/2020/04/15/whats-new-in-oauth-2-1
+    #
     # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-15#section-4.3
     class Password < Base
       # Not used for this strategy
       #
       # @raise [NotImplementedError]
       def authorize_url
-        raise(NotImplementedError, 'The authorization endpoint is not used in this strategy')
+        raise(NotImplementedError, "The authorization endpoint is not used in this strategy")
       end
 
       # Retrieve an access token given the specified End User username and password.
@@ -19,9 +27,11 @@ module OAuth2
       # @param [String] password the End User password
       # @param [Hash] params additional params
       def get_token(username, password, params = {}, opts = {})
-        params = {'grant_type' => 'password',
-                  'username' => username,
-                  'password' => password}.merge(params)
+        params = {
+          "grant_type" => "password",
+          "username" => username,
+          "password" => password,
+        }.merge(params)
         @client.get_token(params, opts)
       end
     end

data/lib/oauth2/version.rb

@@ -2,6 +2,6 @@
 
 module OAuth2
   module Version
-    VERSION = '2.0.9'.freeze
+    VERSION = "2.0.17"
   end
 end

data/lib/oauth2.rb

@@ -1,40 +1,81 @@
 # frozen_string_literal: true
 
 # includes modules from stdlib
-require 'cgi'
-require 'time'
+require "cgi"
+require "time"
 
 # third party gems
-require 'snaky_hash'
-require 'version_gem'
+require "snaky_hash"
+require "version_gem"
 
 # includes gem files
-require 'oauth2/version'
-require 'oauth2/error'
-require 'oauth2/authenticator'
-require 'oauth2/client'
-require 'oauth2/strategy/base'
-require 'oauth2/strategy/auth_code'
-require 'oauth2/strategy/implicit'
-require 'oauth2/strategy/password'
-require 'oauth2/strategy/client_credentials'
-require 'oauth2/strategy/assertion'
-require 'oauth2/access_token'
-require 'oauth2/response'
+require_relative "oauth2/version"
+require_relative "oauth2/filtered_attributes"
+require_relative "oauth2/error"
+require_relative "oauth2/authenticator"
+require_relative "oauth2/client"
+require_relative "oauth2/strategy/base"
+require_relative "oauth2/strategy/auth_code"
+require_relative "oauth2/strategy/implicit"
+require_relative "oauth2/strategy/password"
+require_relative "oauth2/strategy/client_credentials"
+require_relative "oauth2/strategy/assertion"
+require_relative "oauth2/access_token"
+require_relative "oauth2/response"
 
 # The namespace of this library
+#
+# This module is the entry point and top-level namespace for the oauth2 gem.
+# It exposes configuration, constants, and requires the primary public classes.
 module OAuth2
-  DEFAULT_CONFIG = SnakyHash::SymbolKeyed.new(silence_extra_tokens_warning: false)
+  # When true, enables verbose HTTP logging via Faraday's logger middleware.
+  # Controlled by the OAUTH_DEBUG environment variable. Any case-insensitive
+  # value equal to "true" will enable debugging.
+  #
+  # @return [Boolean]
+  OAUTH_DEBUG = ENV.fetch("OAUTH_DEBUG", "false").casecmp("true").zero?
+
+  # Default configuration values for the oauth2 library.
+  #
+  # @example Toggle warnings
+  #   OAuth2.configure do |config|
+  #     config[:silence_extra_tokens_warning] = false
+  #     config[:silence_no_tokens_warning] = false
+  #   end
+  #
+  # @return [SnakyHash::SymbolKeyed] A mutable Hash-like config with symbol keys
+  DEFAULT_CONFIG = SnakyHash::SymbolKeyed.new(
+    silence_extra_tokens_warning: true,
+    silence_no_tokens_warning: true,
+  )
+
+  # The current runtime configuration for the library.
+  #
+  # @return [SnakyHash::SymbolKeyed]
   @config = DEFAULT_CONFIG.dup
+
   class << self
-    attr_accessor :config
+    # Access the current configuration.
+    #
+    # Prefer using {OAuth2.configure} to mutate configuration.
+    #
+    # @return [SnakyHash::SymbolKeyed]
+    attr_reader :config
   end
+
+  # Configure global library behavior.
+  #
+  # Yields the mutable configuration object so callers can update settings.
+  #
+  # @yieldparam [SnakyHash::SymbolKeyed] config the configuration object
+  # @return [void]
   def configure
     yield @config
   end
   module_function :configure
 end
 
+# Extend OAuth2::Version with VersionGem helpers to provide semantic version helpers.
 OAuth2::Version.class_eval do
   extend VersionGem::Basic
 end