oauth2 2.0.10 → 2.0.17

data/lib/oauth2/response.rb

@@ -5,23 +5,39 @@ 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,
@@ -29,9 +45,11 @@ module OAuth2
 
     # 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 || ""
     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)
 
@@ -91,36 +119,36 @@ module OAuth2
         end
 
       if options[:snaky] && @parsed.is_a?(Hash)
-        parsed = SnakyHash::StringKeyed.new(@parsed)
-        @parsed = parsed.to_h
+        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 unless response.headers
 
       ((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)
 
@@ -136,12 +164,16 @@ module OAuth2
   end
 end
 
+# 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)
 

data/lib/oauth2/strategy/assertion.rb

@@ -95,7 +95,10 @@ module OAuth2
       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?
 
-        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,6 +4,16 @@ 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

data/lib/oauth2/strategy/implicit.rb

@@ -4,6 +4,14 @@ 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

data/lib/oauth2/strategy/password.rb

@@ -4,6 +4,14 @@ 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

data/lib/oauth2/version.rb

@@ -2,6 +2,6 @@
 
 module OAuth2
   module Version
-    VERSION = "2.0.10"
+    VERSION = "2.0.17"
   end
 end

data/lib/oauth2.rb

@@ -24,22 +24,58 @@ 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
+  # 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
+    # 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

data/sig/oauth2/access_token.rbs

@@ -0,0 +1,25 @@
+module OAuth2
+  class AccessToken
+    def self.from_hash: (OAuth2::Client, Hash[untyped, untyped]) -> OAuth2::AccessToken
+    def self.from_kvform: (OAuth2::Client, String) -> OAuth2::AccessToken
+
+    def initialize: (OAuth2::Client, String, ?Hash[Symbol, untyped]) -> void
+    def []: (String | Symbol) -> untyped
+    def expires?: () -> bool
+    def expired?: () -> bool
+    def refresh: (?Hash[untyped, untyped], ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::AccessToken
+    def revoke: (?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def to_hash: () -> Hash[Symbol, untyped]
+    def request: (Symbol, String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def get: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def post: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def put: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def patch: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def delete: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def headers: () -> Hash[String, String]
+    def configure_authentication!: (Hash[Symbol, untyped], Symbol) -> void
+    def convert_expires_at: (untyped) -> (Time | Integer | nil)
+
+    attr_accessor response: OAuth2::Response
+  end
+end

data/sig/oauth2/authenticator.rbs

@@ -0,0 +1,22 @@
+module OAuth2
+  class Authenticator
+    include OAuth2::FilteredAttributes
+
+    attr_reader mode: (Symbol | String)
+    attr_reader id: String?
+    attr_reader secret: String?
+
+    def initialize: (String? id, String? secret, (Symbol | String) mode) -> void
+
+    def apply: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+
+    def self.encode_basic_auth: (String, String) -> String
+
+    private
+
+    def apply_params_auth: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+    def apply_client_id: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+    def apply_basic_auth: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+    def basic_auth_header: () -> Hash[String, String]
+  end
+end

data/sig/oauth2/client.rbs

@@ -0,0 +1,52 @@
+module OAuth2
+  class Client
+    RESERVED_REQ_KEYS: Array[String]
+    RESERVED_PARAM_KEYS: Array[String]
+
+    include OAuth2::FilteredAttributes
+
+    attr_reader id: String
+    attr_reader secret: String
+    attr_reader site: String?
+    attr_accessor options: Hash[Symbol, untyped]
+    attr_writer connection: untyped
+
+    def initialize: (String client_id, String client_secret, ?Hash[Symbol, untyped]) { (untyped) -> void } -> void
+
+    def site=: (String) -> String
+
+    def connection: () -> untyped
+
+    def authorize_url: (?Hash[untyped, untyped]) -> String
+    def token_url: (?Hash[untyped, untyped]) -> String
+    def revoke_url: (?Hash[untyped, untyped]) -> String
+
+    def request: (Symbol verb, String url, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+
+    def get_token: (Hash[untyped, untyped] params, ?Hash[Symbol, untyped] access_token_opts, ?Proc) { (Hash[Symbol, untyped]) -> void } -> (OAuth2::AccessToken | nil)
+
+    def revoke_token: (String token, ?String token_type_hint, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+
+    def http_method: () -> Symbol
+
+    def auth_code: () -> OAuth2::Strategy::AuthCode
+    def implicit: () -> OAuth2::Strategy::Implicit
+    def password: () -> OAuth2::Strategy::Password
+    def client_credentials: () -> OAuth2::Strategy::ClientCredentials
+    def assertion: () -> OAuth2::Strategy::Assertion
+
+    def redirection_params: () -> Hash[String, String]
+
+    private
+
+    def params_to_req_opts: (Hash[untyped, untyped]) -> Hash[Symbol, untyped]
+    def parse_snaky_params_headers: (Hash[untyped, untyped]) -> [Symbol, bool, untyped, (Symbol | nil), Hash[untyped, untyped], Hash[String, String]]
+    def execute_request: (Symbol verb, String url, ?Hash[Symbol, untyped]) { (Faraday::Request) -> void } -> OAuth2::Response
+    def authenticator: () -> OAuth2::Authenticator
+    def parse_response_legacy: (OAuth2::Response, Hash[Symbol, untyped], Proc) -> (OAuth2::AccessToken | nil)
+    def parse_response: (OAuth2::Response, Hash[Symbol, untyped]) -> (OAuth2::AccessToken | nil)
+    def build_access_token: (OAuth2::Response, Hash[Symbol, untyped], untyped) -> OAuth2::AccessToken
+    def build_access_token_legacy: (OAuth2::Response, Hash[Symbol, untyped], Proc) -> (OAuth2::AccessToken | nil)
+    def oauth_debug_logging: (untyped) -> void
+  end
+end

data/sig/oauth2/error.rbs

@@ -0,0 +1,8 @@
+module OAuth2
+  class Error < StandardError
+    def initialize: (OAuth2::Response) -> void
+    def code: () -> (String | Integer | nil)
+    def description: () -> (String | nil)
+    def response: () -> OAuth2::Response
+  end
+end

data/sig/oauth2/filtered_attributes.rbs

@@ -0,0 +1,6 @@
+module OAuth2
+  module FilteredAttributes
+    def self.included: (untyped) -> untyped
+    def filtered_attributes: (*String) -> void
+  end
+end

data/sig/oauth2/response.rbs

@@ -0,0 +1,18 @@
+module OAuth2
+  class Response
+    DEFAULT_OPTIONS: Hash[Symbol, untyped]
+
+    def self.register_parser: (Symbol key, (Array[String] | String) mime_types) { (String) -> untyped } -> void
+
+    def initialize: (untyped response, parse: Symbol?, snaky: bool?, snaky_hash_klass: untyped?, options: Hash[Symbol, untyped]?) -> void
+    def headers: () -> Hash[untyped, untyped]
+    def status: () -> Integer
+    def body: () -> String
+    def parsed: () -> untyped
+    def content_type: () -> (String | nil)
+    def parser: () -> (untyped | nil)
+
+    attr_reader response: untyped
+    attr_accessor options: Hash[Symbol, untyped]
+  end
+end

data/sig/oauth2/strategy.rbs

@@ -0,0 +1,34 @@
+module OAuth2
+  module Strategy
+    class Base
+      def initialize: (OAuth2::Client) -> void
+    end
+
+    class AuthCode < Base
+      def authorize_params: (?Hash[untyped, untyped]) -> Hash[untyped, untyped]
+      def authorize_url: (?Hash[untyped, untyped]) -> String
+      def get_token: (String, ?Hash[untyped, untyped], ?Hash[Symbol, untyped]) -> OAuth2::AccessToken
+    end
+
+    class Implicit < Base
+      def authorize_params: (?Hash[untyped, untyped]) -> Hash[untyped, untyped]
+      def authorize_url: (?Hash[untyped, untyped]) -> String
+      def get_token: (*untyped) -> void
+    end
+
+    class Password < Base
+      def authorize_url: () -> void
+      def get_token: (String, String, ?Hash[untyped, untyped], ?Hash[Symbol, untyped]) -> OAuth2::AccessToken
+    end
+
+    class ClientCredentials < Base
+      def authorize_url: () -> void
+      def get_token: (?Hash[untyped, untyped], ?Hash[Symbol, untyped]) -> OAuth2::AccessToken
+    end
+
+    class Assertion < Base
+      def authorize_url: () -> void
+      def get_token: (Hash[untyped, untyped], Hash[Symbol, untyped], ?Hash[Symbol, untyped], ?Hash[Symbol, untyped]) -> OAuth2::AccessToken
+    end
+  end
+end

data/sig/oauth2/version.rbs

@@ -0,0 +1,5 @@
+module OAuth2
+  module Version
+    VERSION: String
+  end
+end

data/sig/oauth2.rbs

@@ -0,0 +1,9 @@
+module OAuth2
+  OAUTH_DEBUG: bool
+
+  DEFAULT_CONFIG: untyped
+  @config: untyped
+
+  def self.config: () -> untyped
+  def self.configure: () { (untyped) -> void } -> void
+end