oauth2 1.4.7 → 2.0.20

data/lib/oauth2/error.rb

@@ -1,40 +1,79 @@
+# 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
-    attr_reader :response, :code, :description
+    # @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 values include:
-    # :invalid_request, :invalid_client, :invalid_token, :invalid_grant, :unsupported_grant_type, :invalid_scope
+    # Create a new OAuth2::Error
+    #
+    # @param [OAuth2::Response, Hash, Object] response A Response or error payload
     def initialize(response)
-      response.error = self
       @response = response
-
-      if response.parsed.is_a?(Hash)
-        @code = response.parsed['error']
-        @description = response.parsed['error_description']
-        error_description = "#{@code}: #{@description}"
+      @code = nil
+      @description = nil
+      if response.respond_to?(:parsed)
+        if response.parsed.is_a?(Hash)
+          @code = response.parsed["error"]
+          @description = response.parsed["error_description"]
+        end
+      elsif response.is_a?(Hash)
+        @code = response["error"]
+        @description = response["error_description"]
       end
-
-      super(error_message(response.body, :error_description => error_description))
+      @body = if response.respond_to?(:body)
+        response.body
+      else
+        @response
+      end
+      message_opts = parse_error_description(@code, @description)
+      super(error_message(@body, message_opts))
     end
 
-    # Makes a error message
-    # @param [String] response_body response body of request
-    # @param [String] opts :error_description error description to show first line
+  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 = {})
-      message = []
+      lines = []
 
-      opts[:error_description] && message << opts[:error_description]
+      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
+
+      lines << error_string
+
+      lines.join("\n")
+    end
 
-      error_message = if opts[:error_description] && 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
+    # 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
 
-      message << error_message
+      error_description = ""
+      error_description += "#{code}: " if code
+      error_description += description if description
 
-      message.join("\n")
+      {error_description: error_description}
     end
   end
 end

data/lib/oauth2/filtered_attributes.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OAuth2
+  # Permanent alias for {OAuth2::AUTH_SANITIZER::FilteredAttributes}.
+  #
+  # This constant is intentionally kept in the `OAuth2` namespace because it
+  # was part of the public API before the implementation was extracted into the
+  # `auth-sanitizer` gem.  It will **not** be deprecated or removed.
+  FilteredAttributes = OAuth2::AUTH_SANITIZER::FilteredAttributes
+end

data/lib/oauth2/response.rb

@@ -1,91 +1,186 @@
-require 'multi_json'
-require 'multi_xml'
-require 'rack'
+# frozen_string_literal: true
+
+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
-    attr_accessor :error, :options
 
-    # Procs that, when called, will parse a response body according
-    # to the specified format.
+    # @return [Hash] The options hash for this instance
+    attr_accessor :options
+
+    # @private
+    # Storage for response body parser procedures
+    #
+    # @return [Hash<Symbol, Proc>] Hash of parser procs keyed by format symbol
     @@parsers = {
-      :json => lambda { |body| MultiJson.load(body) rescue body }, # rubocop:disable Style/RescueModifier
-      :query => lambda { |body| Rack::Utils.parse_query(body) },
-      :text => lambda { |body| body },
+      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/json' => :json,
-      'text/javascript' => :json,
-      '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.
-    def self.register_parser(key, mime_types, &block)
-      key = key.to_sym
-      @@parsers[key] = block
-      Array(mime_types).each do |mime_type|
-        @@content_types[mime_type] = key
+    class << self
+      # Adds a new content type parser.
+      #
+      # @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 register_parser(key, mime_types, &block)
+        key = key.to_sym
+        @@parsers[key] = block
+        Array(mime_types).each do |mime_type|
+          @@content_types[mime_type] = key
+        end
       end
     end
 
     # Initializes a Response instance
     #
     # @param [Faraday::Response] response The Faraday response instance
-    # @param [Hash] opts options in which to initialize the instance
-    # @option opts [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)
-    def initialize(response, opts = {})
+    # @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 => :automatic}.merge(opts)
+      @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 parsed response body.
-    #   Will attempt to parse application/x-www-form-urlencoded and
-    #   application/json Content-Type response bodies
+    # The parsed response body
+    #
+    # @return [Object, SnakyHash::StringKeyed] The parsed response body
+    # @return [nil] If no parser is available
     def parsed
-      return nil unless @@parsers.key?(parser)
+      return @parsed if defined?(@parsed)
+
+      @parsed =
+        if parser.respond_to?(:call)
+          case parser.arity
+          when 0
+            parser.call
+          when 1
+            parser.call(body)
+          else
+            parser.call(body, response)
+          end
+        end
+
+      if options[:snaky] && @parsed.is_a?(Hash)
+        hash_klass = options[:snaky_hash_klass] || DEFAULT_OPTIONS[:snaky_hash_klass]
+        @parsed = hash_klass[@parsed]
+      end
 
-      @parsed ||= @@parsers[parser].call(body)
+      @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
-      ((response.headers.values_at('content-type', 'Content-Type').compact.first || '').split(';').first || '').strip
+      return unless response.headers
+
+      ((response.headers.values_at("content-type", "Content-Type").compact.first || "").split(";").first || "").strip.downcase
     end
 
-    # Determines the parser that will be used to supply the content of #parsed
+    # Determines the parser to be used for the response body
+    #
+    # @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.
+    #
+    # @note If no +:parse+ option is supplied, the lookup Symbol will be determined
+    #       by looking up {#content_type} in {@@content_types}.
+    #
+    # @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] The parser proc or callable object
+    # @return [nil] If no suitable parser is found
     def parser
-      return options[:parse].to_sym if @@parsers.key?(options[:parse])
+      return @parser if defined?(@parser)
 
-      @@content_types[content_type]
+      @parser =
+        if options[:parse].respond_to?(:call)
+          options[:parse]
+        elsif options[:parse]
+          @@parsers[options[:parse].to_sym]
+        end
+
+      @parser ||= @@parsers[@@content_types[content_type]]
     end
   end
 end
 
-OAuth2::Response.register_parser(:xml, ['text/xml', 'application/rss+xml', 'application/rdf+xml', 'application/atom+xml']) do |body|
-  MultiXml.parse(body) rescue body # rubocop:disable Style/RescueModifier
+# 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
+
+# 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)
+  next body if body.respond_to?(:empty?) && body.empty?
+
+  JSON.parse(body)
 end

data/lib/oauth2/strategy/assertion.rb

@@ -1,22 +1,31 @@
-require 'jwt'
+# frozen_string_literal: true
+
+require "jwt"
 
 module OAuth2
   module Strategy
     # The Client Assertion Strategy
     #
-    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-4.1.3
+    # @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-10#section-4.1.3
     #
     # Sample usage:
     #   client = OAuth2::Client.new(client_id, client_secret,
-    #                               :site => 'http://localhost:8080')
+    #                               :site => 'http://localhost:8080',
+    #                               :auth_scheme => :request_body)
+    #
+    #   claim_set = {
+    #     :iss => "http://localhost:3001",
+    #     :aud => "http://localhost:8080/oauth2/token",
+    #     :sub => "me@example.com",
+    #     :exp => Time.now.utc.to_i + 3600,
+    #   }
     #
-    #   params = {:hmac_secret => "some secret",
-    #             # or :private_key => "private key string",
-    #             :iss => "http://localhost:3001",
-    #             :prn => "me@here.com",
-    #             :exp => Time.now.utc.to_i + 3600}
+    #   encoding = {
+    #     :algorithm => 'HS256',
+    #     :key => 'secret_key',
+    #   }
     #
-    #   access = client.assertion.get_token(params)
+    #   access = client.assertion.get_token(claim_set, encoding)
     #   access.token                 # actual access_token string
     #   access.get("/api/stuff")     # making api calls with access token in header
     #
@@ -25,50 +34,71 @@ 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.
       #
-      # @param [Hash] params assertion params
-      # pass either :hmac_secret or :private_key, but not both.
+      # @param [Hash] claims the hash representation of the claims that should be encoded as a JWT (JSON Web Token)
+      #
+      # For reading on JWT and claim keys:
+      #   @see https://github.com/jwt/ruby-jwt
+      #   @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+      #   @see https://datatracker.ietf.org/doc/html/rfc7523#section-3
+      #   @see https://www.iana.org/assignments/jwt/jwt.xhtml
+      #
+      # There are many possible claim keys, and applications may ask for their own custom keys.
+      # Some typically required ones:
+      #   :iss (issuer)
+      #   :aud (audience)
+      #   :sub (subject) -- formerly :prn https://datatracker.ietf.org/doc/html/draft-ietf-oauth-json-web-token-06#appendix-F
+      #   :exp, (expiration time) -- in seconds, e.g. Time.now.utc.to_i + 3600
+      #
+      # Note that this method does *not* validate presence of those four claim keys indicated as required by RFC 7523.
+      # There are endpoints that may not conform with this RFC, and this gem should still work for those use cases.
+      #
+      # @param [Hash] encoding_opts a hash containing instructions on how the JWT should be encoded
+      # @option algorithm [String] the algorithm with which you would like the JWT to be encoded
+      # @option key [Object] the key with which you would like to encode the JWT
       #
-      #   params :hmac_secret, secret string.
-      #   params :private_key, private key string.
+      # These two options are passed directly to `JWT.encode`.  For supported encoding arguments:
+      #   @see https://github.com/jwt/ruby-jwt#algorithms-and-usage
+      #   @see https://datatracker.ietf.org/doc/html/rfc7518#section-3.1
       #
-      #   params :iss, issuer
-      #   params :aud, audience, optional
-      #   params :prn, principal, current user
-      #   params :exp, expired at, in seconds, like Time.now.utc.to_i + 3600
+      # The object type of `:key` may depend on the value of `:algorithm`.  Sample arguments:
+      #   `get_token(claim_set, {:algorithm => 'HS256', :key => 'secret_key'})`
+      #   `get_token(claim_set, {:algorithm => 'RS256', :key => OpenSSL::PKCS12.new(File.read('my_key.p12'), 'not_secret')})`
       #
-      # @param [Hash] opts options
-      def get_token(params = {}, opts = {})
-        hash = build_request(params)
-        @client.get_token(hash, opts.merge('refresh_token' => nil))
+      # @param [Hash] request_opts options that will be used to assemble the request
+      # @option request_opts [String] :scope the url parameter `scope` that may be required by some endpoints
+      #   @see https://datatracker.ietf.org/doc/html/rfc7521#section-4.1
+      #
+      # @param [Hash] response_opts this will be merged with the token response to create the AccessToken object
+      #   @see the access_token_opts argument to Client#get_token
+
+      def get_token(claims, encoding_opts, request_opts = {}, response_opts = {})
+        assertion = build_assertion(claims, encoding_opts)
+        params = build_request(assertion, request_opts)
+
+        @client.get_token(params, response_opts)
       end
 
-      def build_request(params)
-        assertion = build_assertion(params)
+    private
+
+      def build_request(assertion, request_opts = {})
         {
-          :grant_type => 'assertion',
-          :assertion_type => 'urn:ietf:params:oauth:grant-type:jwt-bearer',
-          :assertion => assertion,
-          :scope => params[:scope],
-        }
+          grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+          assertion: assertion,
+        }.merge(request_opts)
       end
 
-      def build_assertion(params)
-        claims = {
-          :iss => params[:iss],
-          :aud => params[:aud],
-          :prn => params[:prn],
-          :exp => params[:exp],
-        }
-        if params[:hmac_secret]
-          JWT.encode(claims, params[:hmac_secret], 'HS256')
-        elsif params[:private_key]
-          JWT.encode(claims, params[:private_key], 'RS256')
-        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?
+
+        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

@@ -1,20 +1,33 @@
+# frozen_string_literal: true
+
 module OAuth2
   module Strategy
     # The Authorization Code Strategy
     #
-    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.1
+    # 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
       #
       # @param [Hash] params additional query parameters for the URL
       def authorize_url(params = {})
+        assert_valid_params(params)
         @client.authorize_url(authorize_params.merge(params))
       end
 
@@ -22,12 +35,22 @@ module OAuth2
       #
       # @param [String] code The Authorization Code value
       # @param [Hash] params additional params
-      # @param [Hash] opts options
+      # @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)
+        end
+
+        @client.get_token(params_dup, opts)
+      end
+
+    private
 
-        @client.get_token(params, opts)
+      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")
       end
     end
   end

data/lib/oauth2/strategy/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OAuth2
   module Strategy
     class Base

data/lib/oauth2/strategy/client_credentials.rb

@@ -1,14 +1,16 @@
+# frozen_string_literal: true
+
 module OAuth2
   module Strategy
     # The Client Credentials Strategy
     #
-    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.4
+    # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-15#section-4.4
     class ClientCredentials < 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 client.
@@ -16,8 +18,8 @@ module OAuth2
       # @param [Hash] params additional params
       # @param [Hash] opts options
       def get_token(params = {}, opts = {})
-        params = params.merge('grant_type' => 'client_credentials')
-        @client.get_token(params, opts.merge('refresh_token' => nil))
+        params = params.merge("grant_type" => "client_credentials")
+        @client.get_token(params, opts)
       end
     end
   end

data/lib/oauth2/strategy/implicit.rb

@@ -1,20 +1,31 @@
+# frozen_string_literal: true
+
 module OAuth2
   module Strategy
     # The Implicit Strategy
     #
-    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-26#section-4.2
+    # 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
       #
       # @param [Hash] params additional query parameters for the URL
       def authorize_url(params = {})
+        assert_valid_params(params)
         @client.authorize_url(authorize_params.merge(params))
       end
 
@@ -22,7 +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")
       end
     end
   end