oauth2 2.0.10 → 2.0.17

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -2,25 +2,20 @@
 
 ## Supported Versions
 
-| Version  | Supported | EOL     | Post-EOL / Enterprise                 |
-|----------|-----------|---------|---------------------------------------|
-| 2.latest | ✅         | 04/2026 | [Tidelift Subscription][tidelift-ref] |
-| 1.latest | ✅         | 10/2025 | [Tidelift Subscription][tidelift-ref] |
-| <= 1     | ⛔         | ⛔       | ⛔                                     |
+| Version  | Supported |
+|----------|-----------|
+| 1.latest | ✅         |
 
-### EOL Policy
+## Security contact information
 
-Non-commercial support for the oldest version of Ruby (which itself is going EOL) will be dropped each year in April.
-
-## Reporting a Vulnerability
-
-To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
 Tidelift will coordinate the fix and disclosure.
 
-## OAuth2 for Enterprise
-
-Available as part of the Tidelift Subscription.
+## Additional Support
 
-The maintainers of oauth2 and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. [Learn more.][tidelift-ref]
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
 
-[tidelift-ref]: https://tidelift.com/subscription/pkg/rubygems-oauth2?utm_source=rubygems-oauth2&utm_medium=referral&utm_campaign=enterprise&utm_term=repo
+[README]: README.md

data/lib/oauth2/access_token.rb

@@ -1,5 +1,20 @@
 # frozen_string_literal: true
 
+# :nocov:
+begin
+  # The first version of hashie that has a version file was 1.1.0
+  # The first version of hashie that required the version file at runtime was 3.2.0
+  # If it has already been loaded then this is very low cost, as Kernel.require uses maintains a cache
+  # If this it hasn't this will work to get it loaded, and then we will be able to use
+  #   defined?(Hashie::Version)
+  # as a test.
+  # TODO: get rid this mess when we drop Hashie < 3.2, as Hashie will self-load its version then
+  require "hashie/version"
+rescue LoadError
+  nil
+end
+# :nocov:
+
 module OAuth2
   class AccessToken # rubocop:disable Metrics/ClassLength
     TOKEN_KEYS_STR = %w[access_token id_token token accessToken idToken].freeze
@@ -54,7 +69,16 @@ module OAuth2
             extra_tokens_warning(supported_keys, t_key)
             t_key
           end
-        token = fresh.delete(key) || ""
+        # :nocov:
+        # TODO: Get rid of this branching logic when dropping Hashie < v3.2
+        token = if !defined?(Hashie::VERSION) # i.e. <= "1.1.0"; the first Hashie to ship with a VERSION constant
+          warn("snaky_hash and oauth2 will drop support for Hashie v0 in the next major version. Please upgrade to a modern Hashie.")
+          # There is a bug in Hashie v0, which is accounts for.
+          fresh.delete(key) || fresh[key] || ""
+        else
+          fresh.delete(key) || ""
+        end
+        # :nocov:
         new(client, token, fresh)
       end
 
@@ -108,9 +132,15 @@ You may need to set `snaky: false`. See inline documentation for more info.
     # @option opts [FixNum, String] :expires_in (nil) the number of seconds in which the AccessToken will expire
     # @option opts [FixNum, String] :expires_at (nil) the epoch time in seconds in which AccessToken will expire
     # @option opts [FixNum, String] :expires_latency (nil) the number of seconds by which AccessToken validity will be reduced to offset latency, @version 2.0+
-    # @option opts [Symbol] :mode (:header) the transmission mode of the Access Token parameter value
-    #    one of :header, :body or :query
+    # @option opts [Symbol, Hash, or callable] :mode (:header) the transmission mode of the Access Token parameter value:
+    #    either one of :header, :body or :query; or a Hash with verb symbols as keys mapping to one of these symbols
+    #    (e.g., {get: :query, post: :header, delete: :header}); or a callable that accepts a request-verb parameter
+    #    and returns one of these three symbols.
     # @option opts [String] :header_format ('Bearer %s') the string format to use for the Authorization header
+    #
+    # @example Verb-dependent Hash mode
+    #   # Send token in query for GET, in header for POST/DELETE, in body for PUT/PATCH
+    #   OAuth2::AccessToken.new(client, token, mode: {get: :query, post: :header, delete: :header, put: :body, patch: :body})
     # @option opts [String] :param_name ('access_token') the parameter name to use for transmission of the
     #    Access Token value in :body or :query transmission mode
     # @option opts [String] :token_name (nil) the name of the response parameter that identifies the access token
@@ -300,7 +330,7 @@ You may need to set `snaky: false`. See inline documentation for more info.
     #
     # @see OAuth2::Client#request
     def request(verb, path, opts = {}, &block)
-      configure_authentication!(opts)
+      configure_authentication!(opts, verb)
       @client.request(verb, path, opts, &block)
     end
 
@@ -346,12 +376,26 @@ You may need to set `snaky: false`. See inline documentation for more info.
 
   private
 
-    def configure_authentication!(opts)
-      case options[:mode]
+    def configure_authentication!(opts, verb)
+      mode_opt = options[:mode]
+      mode =
+        if mode_opt.respond_to?(:call)
+          mode_opt.call(verb)
+        elsif mode_opt.is_a?(Hash)
+          key = verb.to_sym
+          # Try symbol key first, then string key; default to :header when missing
+          mode_opt[key] || mode_opt[key.to_s] || :header
+        else
+          mode_opt
+        end
+
+      case mode
       when :header
         opts[:headers] ||= {}
         opts[:headers].merge!(headers)
       when :query
+        # OAuth 2.1 note: Bearer tokens in the query string are omitted from the spec due to security risks.
+        # Prefer the default :header mode whenever possible.
         opts[:params] ||= {}
         opts[:params][options[:param_name]] = token
       when :body
@@ -363,7 +407,7 @@ You may need to set `snaky: false`. See inline documentation for more info.
         end
         # @todo support for multi-part (file uploads)
       else
-        raise("invalid :mode option of #{options[:mode]}")
+        raise("invalid :mode option of #{mode}")
       end
     end
 

data/lib/oauth2/authenticator.rb

@@ -3,12 +3,24 @@
 require "base64"
 
 module OAuth2
+  # Builds and applies client authentication to token and revoke requests.
+  #
+  # Depending on the selected mode, credentials are applied as Basic Auth
+  # headers, request body parameters, or only the client_id is sent (TLS).
   class Authenticator
     include FilteredAttributes
 
+    # @return [Symbol, String] Authentication mode (e.g., :basic_auth, :request_body, :tls_client_auth, :private_key_jwt)
+    # @return [String, nil] Client identifier
+    # @return [String, nil] Client secret (filtered in inspected output)
     attr_reader :mode, :id, :secret
     filtered_attributes :secret
 
+    # Create a new Authenticator
+    #
+    # @param [String, nil] id Client identifier
+    # @param [String, nil] secret Client secret
+    # @param [Symbol, String] mode Authentication mode
     def initialize(id, secret, mode)
       @id = id
       @secret = secret
@@ -39,6 +51,11 @@ module OAuth2
       end
     end
 
+    # Encodes a Basic Authorization header value for the provided credentials.
+    #
+    # @param [String] user The client identifier
+    # @param [String] password The client secret
+    # @return [String] The value to use for the Authorization header
     def self.encode_basic_auth(user, password)
       "Basic #{Base64.strict_encode64("#{user}:#{password}")}"
     end
@@ -47,6 +64,9 @@ module OAuth2
 
     # Adds client_id and client_secret request parameters if they are not
     # already set.
+    #
+    # @param [Hash] params Request parameters
+    # @return [Hash] Updated parameters including client_id and client_secret
     def apply_params_auth(params)
       result = {}
       result["client_id"] = id unless id.nil?
@@ -54,8 +74,11 @@ module OAuth2
       result.merge(params)
     end
 
-    # When using schemes that don't require the client_secret to be passed i.e TLS Client Auth,
+    # When using schemes that don't require the client_secret to be passed (e.g., TLS Client Auth),
     # we don't want to send the secret
+    #
+    # @param [Hash] params Request parameters
+    # @return [Hash] Updated parameters including only client_id
     def apply_client_id(params)
       result = {}
       result["client_id"] = id unless id.nil?
@@ -64,13 +87,19 @@ module OAuth2
 
     # Adds an `Authorization` header with Basic Auth credentials if and only if
     # it is not already set in the params.
+    #
+    # @param [Hash] params Request parameters (may include :headers)
+    # @return [Hash] Updated parameters with Authorization header
     def apply_basic_auth(params)
       headers = params.fetch(:headers, {})
       headers = basic_auth_header.merge(headers)
       params.merge(headers: headers)
     end
 
+    # Build the Basic Authorization header.
+    #
     # @see https://datatracker.ietf.org/doc/html/rfc2617#section-2
+    # @return [Hash] Header hash containing the Authorization entry
     def basic_auth_header
       {"Authorization" => self.class.encode_basic_auth(id, secret)}
     end

data/lib/oauth2/client.rb

@@ -19,7 +19,7 @@ module OAuth2
   # The OAuth2::Client class
   class Client # rubocop:disable Metrics/ClassLength
     RESERVED_REQ_KEYS = %w[body headers params redirect_count].freeze
-    RESERVED_PARAM_KEYS = (RESERVED_REQ_KEYS + %w[parse snaky token_method]).freeze
+    RESERVED_PARAM_KEYS = (RESERVED_REQ_KEYS + %w[parse snaky snaky_hash_klass token_method]).freeze
 
     include FilteredAttributes
 
@@ -256,10 +256,10 @@ module OAuth2
     # @see https://datatracker.ietf.org/doc/html/rfc7009#section-2.1
     def revoke_token(token, token_type_hint = nil, params = {}, &block)
       params[:token_method] ||= :post_with_query_string
+      params[:token] = token
+      params[:token_type_hint] = token_type_hint if token_type_hint
+
       req_opts = params_to_req_opts(params)
-      req_opts[:params] ||= {}
-      req_opts[:params][:token] = token
-      req_opts[:params][:token_type_hint] = token_type_hint if token_type_hint
 
       request(http_method, revoke_url, req_opts, &block)
     end
@@ -321,6 +321,9 @@ module OAuth2
     # requesting authorization. If it is provided at authorization time it MUST
     # also be provided with the token exchange request.
     #
+    # OAuth 2.1 note: Authorization Servers must compare redirect URIs using exact string matching.
+    # This client simply forwards the configured redirect_uri; the exact-match validation happens server-side.
+    #
     # Providing :redirect_uri to the OAuth2::Client instantiation will take
     # care of managing this.
     #
@@ -330,6 +333,7 @@ module OAuth2
     # @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3
     # @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.2.1
     # @see https://datatracker.ietf.org/doc/html/rfc6749#section-10.6
+    # @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13
     #
     # @return [Hash] the params to add to a request or URL
     def redirection_params
@@ -342,14 +346,26 @@ module OAuth2
 
   private
 
-    # A generic token request options parser
+    # Processes request parameters and transforms them into request options
+    #
+    # @param [Hash] params the request parameters to process
+    # @option params [Symbol] :parse (:automatic) parsing strategy for the response
+    # @option params [Boolean] :snaky (true) whether to convert response keys to snake_case
+    # @option params [Class] :snaky_hash_klass (SnakyHash::StringKeyed) class to use for snake_case hash conversion
+    # @option params [Symbol] :token_method (:post) HTTP method to use for token request
+    # @option params [Hash] :headers Additional HTTP headers for the request
+    #
+    # @return [Hash] the processed request options
+    #
+    # @api private
     def params_to_req_opts(params)
-      parse, snaky, token_method, params, headers = parse_snaky_params_headers(params)
+      parse, snaky, snaky_hash_klass, token_method, params, headers = parse_snaky_params_headers(params)
       req_opts = {
         raise_errors: options[:raise_errors],
         token_method: token_method || options[:token_method],
         parse: parse,
         snaky: snaky,
+        snaky_hash_klass: snaky_hash_klass,
       }
       if req_opts[:token_method] == :post
         # NOTE: If proliferation of request types continues, we should implement a parser solution for Request,
@@ -369,19 +385,22 @@ module OAuth2
       req_opts
     end
 
-    # Processes and transforms the input parameters for OAuth requests
+    # Processes and transforms parameters for OAuth requests
     #
     # @param [Hash] params the input parameters to process
-    # @option params [Symbol, nil] :parse (:automatic) parsing strategy for the response
+    # @option params [Symbol] :parse (:automatic) parsing strategy for the response
     # @option params [Boolean] :snaky (true) whether to convert response keys to snake_case
+    # @option params [Class] :snaky_hash_klass (SnakyHash::StringKeyed) class to use for snake_case hash conversion
+    # @option params [Symbol] :token_method overrides the default token method for this request
     # @option params [Hash] :headers HTTP headers for the request
     #
-    # @return [Array<(Symbol, Boolean, Hash, Hash)>] Returns an array containing:
-    #   - [Symbol, nil] parse strategy
-    #   - [Boolean] snaky flag for response key transformation
-    #   - [Symbol, nil] token_method overrides options[:token_method] for a request
-    #   - [Hash] processed parameters
-    #   - [Hash] HTTP headers
+    # @return [Array<(Symbol, Boolean, Class, Symbol, Hash, Hash)>] Returns an array containing:
+    #   - parse strategy (Symbol)
+    #   - snaky flag for response key transformation (Boolean)
+    #   - hash class for snake_case conversion (Class)
+    #   - token method override (Symbol, nil)
+    #   - processed parameters (Hash)
+    #   - HTTP headers (Hash)
     #
     # @api private
     def parse_snaky_params_headers(params)
@@ -394,11 +413,12 @@ module OAuth2
       end.to_h
       parse = params.key?(:parse) ? params.delete(:parse) : Response::DEFAULT_OPTIONS[:parse]
       snaky = params.key?(:snaky) ? params.delete(:snaky) : Response::DEFAULT_OPTIONS[:snaky]
+      snaky_hash_klass = params.key?(:snaky_hash_klass) ? params.delete(:snaky_hash_klass) : Response::DEFAULT_OPTIONS[:snaky_hash_klass]
       token_method = params.delete(:token_method) if params.key?(:token_method)
       params = authenticator.apply(params)
       # authenticator may add :headers, and we separate them from params here
       headers = params.delete(:headers) || {}
-      [parse, snaky, token_method, params, headers]
+      [parse, snaky, snaky_hash_klass, token_method, params, headers]
     end
 
     # Executes an HTTP request with error handling and response processing

data/lib/oauth2/error.rb

@@ -1,12 +1,20 @@
 # 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)
@@ -29,6 +37,11 @@ module OAuth2
 
   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 = []
 
@@ -46,6 +59,11 @@ module OAuth2
       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
 

data/lib/oauth2/filtered_attributes.rb

@@ -1,19 +1,40 @@
 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?