oauth2 1.4.7 → 2.0.20

data/REEK

@@ -0,0 +1,2 @@
+./reek: 1: ./reek:: not found
+./reek: 2: ./reek:: not found

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

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported Versions
+
+| Version  | Supported |
+|----------|-----------|
+| 1.latest | ✅         |
+
+## Security contact information
+
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+More detailed explanation of the process is in [IRP.md][IRP].
+
+## Additional Support
+
+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].
+
+[README]: README.md
+[IRP]: IRP.md

data/THREAT_MODEL.md

@@ -0,0 +1,94 @@
+# Threat Model Outline for oauth2 Ruby Gem
+
+## 1. Overview
+This document outlines the threat model for the `oauth2` Ruby gem, which implements OAuth 2.0, 2.1, and OIDC Core protocols. The gem is used to facilitate secure authorization and authentication in Ruby applications.
+
+## 2. Assets to Protect
+- OAuth access tokens, refresh tokens, and ID tokens
+- User credentials (if handled)
+- Client secrets and application credentials
+- Sensitive user data accessed via OAuth
+- Private keys and certificates (for signing/verifying tokens)
+
+## 3. Potential Threat Actors
+- External attackers (internet-based)
+- Malicious OAuth clients or resource servers
+- Insiders (developers, maintainers)
+- Compromised dependencies
+
+## 4. Attack Surfaces
+- OAuth endpoints (authorization, token, revocation, introspection)
+- HTTP request/response handling
+- Token storage and management
+- Configuration files and environment variables
+- Dependency supply chain
+
+## 5. Threats and Mitigations
+
+### 5.1 Token Leakage
+- **Threat:** Tokens exposed via logs, URLs, or insecure storage
+- **Mitigations:**
+  - Avoid logging sensitive tokens
+  - Use secure storage mechanisms
+  - Never expose tokens in URLs
+
+### 5.2 Token Replay and Forgery
+- **Threat:** Attackers reuse or forge tokens
+- **Mitigations:**
+  - Validate token signatures and claims
+  - Use short-lived tokens and refresh tokens
+  - Implement token revocation
+
+### 5.3 Insecure Communication
+- **Threat:** Data intercepted via MITM attacks
+- **Mitigations:**
+  - Enforce HTTPS for all communications
+  - Validate SSL/TLS certificates
+
+### 5.4 Client Secret Exposure
+- **Threat:** Client secrets leaked in code or version control
+- **Mitigations:**
+  - Store secrets in environment variables or secure vaults
+  - Never commit secrets to source control
+
+### 5.5 Dependency Vulnerabilities
+- **Threat:** Vulnerabilities in third-party libraries
+- **Mitigations:**
+  - Regularly update dependencies
+  - Use tools like `bundler-audit` for vulnerability scanning
+
+### 5.6 Improper Input Validation
+- **Threat:** Injection attacks via untrusted input
+- **Mitigations:**
+  - Validate and sanitize all inputs
+  - Use parameterized queries and safe APIs
+
+### 5.7 Request-Target Trust Boundary Expansion
+- **Threat:** Applications may pass untrusted or insufficiently validated absolute URLs into request paths that can carry OAuth credentials or authenticated state.
+- **Risk:** This can expand trust boundaries, contributing to token leakage, authenticated requests to unintended hosts, or SSRF-like pivoting in the surrounding application.
+- **Mitigations:**
+  - Prefer relative paths where practical
+  - Do not pass untrusted absolute URLs into token-bearing clients
+  - Validate or allowlist outbound request targets at the application layer
+  - Treat request-target validation as a separate concern from log redaction and token storage
+
+### 5.8 Insufficient Logging and Monitoring
+- **Threat:** Attacks go undetected
+- **Mitigations:**
+  - Log security-relevant events (without sensitive data)
+  - Monitor for suspicious activity
+
+## 6. Assumptions
+- The gem is used in a secure environment with up-to-date Ruby and dependencies
+- End-users are responsible for secure configuration and deployment
+
+## 7. Out of Scope
+- Security of external OAuth providers
+- Application-level business logic
+
+## 8. References
+- [OAuth 2.0 Threat Model and Security Considerations (RFC 6819)](https://tools.ietf.org/html/rfc6819)
+- [OWASP Top Ten](https://owasp.org/www-project-top-ten/)
+
+---
+This outline should be reviewed and updated regularly as the project evolves.

data/lib/oauth2/access_token.rb

@@ -1,57 +1,179 @@
+# 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
-    attr_reader :client, :token, :expires_in, :expires_at, :params
-    attr_accessor :options, :refresh_token
+  class AccessToken # rubocop:disable Metrics/ClassLength
+    TOKEN_KEYS_STR = %w[access_token id_token token accessToken idToken].freeze
+    TOKEN_KEYS_SYM = %i[access_token id_token token accessToken idToken].freeze
+    TOKEN_KEY_LOOKUP = TOKEN_KEYS_STR + TOKEN_KEYS_SYM
+
+    include FilteredAttributes
+
+    attr_reader :client, :token, :expires_in, :expires_at, :expires_latency, :params
+    attr_accessor :options, :refresh_token, :response
+    filtered_attributes :token, :refresh_token
 
-    # Should these methods be deprecated?
     class << self
       # Initializes an AccessToken from a Hash
       #
-      # @param [Client] the OAuth2::Client instance
-      # @param [Hash] a hash of AccessToken property values
-      # @return [AccessToken] the initalized AccessToken
+      # @param [OAuth2::Client] client the OAuth2::Client instance
+      # @param [Hash] hash a hash containing the token and other properties
+      # @option hash [String] 'access_token' the access token value
+      # @option hash [String] 'id_token' alternative key for the access token value
+      # @option hash [String] 'token' alternative key for the access token value
+      # @option hash [String] 'refresh_token' (optional) the refresh token value
+      # @option hash [Integer, String] 'expires_in' (optional) number of seconds until token expires
+      # @option hash [Integer, String] 'expires_at' (optional) epoch time in seconds when token expires
+      # @option hash [Integer, String] 'expires_latency' (optional) seconds to reduce token validity by
+      #
+      # @return [OAuth2::AccessToken] the initialized AccessToken
+      #
+      # @note The method will use the first found token key in the following order:
+      #   'access_token', 'id_token', 'token' (or their symbolic versions)
+      # @note If multiple token keys are present, a warning will be issued unless
+      #   OAuth2.config.silence_extra_tokens_warning is true
+      # @note If no token keys are present, a warning will be issued unless
+      #   OAuth2.config.silence_no_tokens_warning is true
+      # @note For "soon-to-expire"/"clock-skew" functionality see the `:expires_latency` option.
+      # @note If snaky key conversion is being used, token_name needs to match the converted key.
+      #
+      # @example
+      #   hash = { 'access_token' => 'token_value', 'refresh_token' => 'refresh_value' }
+      #   access_token = OAuth2::AccessToken.from_hash(client, hash)
       def from_hash(client, hash)
-        hash = hash.dup
-        new(client, hash.delete('access_token') || hash.delete(:access_token), hash)
+        fresh = hash.dup
+        # If token_name is present, then use that key name
+        if fresh.key?(:token_name)
+          t_key = fresh[:token_name]
+          no_tokens_warning(fresh, t_key)
+        else
+          # Otherwise, if one of the supported default keys is present, use whichever has precedence
+          supported_keys = TOKEN_KEY_LOOKUP & fresh.keys
+          t_key = supported_keys[0]
+          extra_tokens_warning(supported_keys, t_key)
+        end
+        # :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(t_key) || fresh[t_key] || ""
+        else
+          fresh.delete(t_key) || ""
+        end
+        # :nocov:
+        new(client, token, fresh)
       end
 
       # Initializes an AccessToken from a key/value application/x-www-form-urlencoded string
       #
       # @param [Client] client the OAuth2::Client instance
       # @param [String] kvform the application/x-www-form-urlencoded string
-      # @return [AccessToken] the initalized AccessToken
+      # @return [AccessToken] the initialized AccessToken
       def from_kvform(client, kvform)
         from_hash(client, Rack::Utils.parse_query(kvform))
       end
+
+    private
+
+      # Having too many is sus, and may lead to bugs. Having none is fine (e.g. refresh flow doesn't need a token).
+      def extra_tokens_warning(supported_keys, key)
+        return if OAuth2.config.silence_extra_tokens_warning
+        return if supported_keys.length <= 1
+
+        warn("OAuth2::AccessToken.from_hash: `hash` contained more than one 'token' key (#{supported_keys}); using #{key.inspect}.")
+      end
+
+      def no_tokens_warning(hash, key)
+        return if OAuth2.config.silence_no_tokens_warning
+        return if key && hash.key?(key)
+
+        warn(%[
+OAuth2::AccessToken#from_hash key mismatch.
+Custom token_name (#{key}) is not found in (#{hash.keys})
+You may need to set `snaky: false`. See inline documentation for more info.
+        ])
+      end
     end
 
-    # Initalize an AccessToken
+    # Initialize an AccessToken
+    #
+    # @note For "soon-to-expire"/"clock-skew" functionality see the `:expires_latency` option.
+    # @note If no token is provided, the AccessToken will be considered invalid.
+    #   This is to prevent the possibility of a token being accidentally
+    #   created with no token value.
+    #   If you want to create an AccessToken with no token value,
+    #   you can pass in an empty string or nil for the token value.
+    #   If you want to create an AccessToken with no token value and
+    #   no refresh token, you can pass in an empty string or nil for the
+    #   token value and nil for the refresh token, and `raise_errors: false`.
     #
     # @param [Client] client the OAuth2::Client instance
-    # @param [String] token the Access Token value
+    # @param [String] token the Access Token value (optional, may not be used in refresh flows)
     # @param [Hash] opts the options to create the Access Token with
     # @option opts [String] :refresh_token (nil) the refresh_token value
     # @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 [Symbol] :mode (:header) the transmission mode of the Access Token parameter value
-    #    one of :header, :body or :query
+    # @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, 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
-    def initialize(client, token, opts = {}) # rubocop:disable Metrics/AbcSize
+    # @option opts [String] :token_name (nil) the name of the response parameter that identifies the access token
+    #    When nil one of TOKEN_KEY_LOOKUP will be used
+    def initialize(client, token, opts = {})
       @client = client
       @token = token.to_s
       opts = opts.dup
-      [:refresh_token, :expires_in, :expires_at].each do |arg|
+      %i[refresh_token expires_in expires_at expires_latency].each do |arg|
         instance_variable_set("@#{arg}", opts.delete(arg) || opts.delete(arg.to_s))
       end
-      @expires_in ||= opts.delete('expires')
+      no_tokens = (@token.nil? || @token.empty?) && (@refresh_token.nil? || @refresh_token.empty?)
+      if no_tokens
+        if @client.options[:raise_errors]
+          raise Error.new({
+            error: "OAuth2::AccessToken has no token",
+            error_description: "Options are: #{opts.inspect}",
+          })
+        elsif !OAuth2.config.silence_no_tokens_warning
+          warn("OAuth2::AccessToken has no token")
+        end
+      end
+      # @option opts [Fixnum, String] :expires is deprecated
+      @expires_in ||= opts.delete("expires")
       @expires_in &&= @expires_in.to_i
       @expires_at &&= convert_expires_at(@expires_at)
-      @expires_at ||= Time.now.to_i + @expires_in if @expires_in
-      @options = {:mode => opts.delete(:mode) || :header,
-                  :header_format => opts.delete(:header_format) || 'Bearer %s',
-                  :param_name => opts.delete(:param_name) || 'access_token'}
+      @expires_latency &&= @expires_latency.to_i
+      @expires_at ||= Time.now.to_i + @expires_in if @expires_in && !@expires_in.zero?
+      @expires_at -= @expires_latency if @expires_latency
+      @options = {
+        mode: opts.delete(:mode) || :header,
+        header_format: opts.delete(:header_format) || "Bearer %s",
+        param_name: opts.delete(:param_name) || "access_token",
+      }
+      @options[:token_name] = opts.delete(:token_name) if opts.key?(:token_name)
+
       @params = opts
     end
 
@@ -62,40 +184,131 @@ module OAuth2
       @params[key]
     end
 
-    # Whether or not the token expires
+    # Whether the token expires
     #
     # @return [Boolean]
     def expires?
       !!@expires_at
     end
 
-    # Whether or not the token is expired
+    # Check if token is expired
     #
-    # @return [Boolean]
+    # @return [Boolean] true if the token is expired, false otherwise
     def expired?
-      expires? && (expires_at < Time.now.to_i)
+      expires? && (expires_at <= Time.now.to_i)
     end
 
     # Refreshes the current Access Token
     #
-    # @return [AccessToken] a new AccessToken
-    # @note options should be carried over to the new AccessToken
-    def refresh!(params = {})
-      raise('A refresh_token is not available') unless refresh_token
+    # @param [Hash] params additional params to pass to the refresh token request
+    # @param [Hash] access_token_opts options that will be passed to the AccessToken initialization
+    #
+    # @yield [opts] The block to modify the refresh token request options
+    # @yieldparam [Hash] opts The options hash that can be modified
+    #
+    # @return [OAuth2::AccessToken] a new AccessToken instance
+    #
+    # @note current token's options are carried over to the new AccessToken
+    def refresh(params = {}, access_token_opts = {}, &block)
+      raise OAuth2::Error.new({error: "A refresh_token is not available"}) unless refresh_token
 
-      params[:grant_type] = 'refresh_token'
+      params[:grant_type] = "refresh_token"
       params[:refresh_token] = refresh_token
-      new_token = @client.get_token(params)
+      new_token = @client.get_token(params, access_token_opts, &block)
       new_token.options = options
-      new_token.refresh_token = refresh_token unless new_token.refresh_token
+      if new_token.refresh_token
+        # Keep it if there is one
+      else
+        new_token.refresh_token = refresh_token
+      end
       new_token
     end
+    # A compatibility alias
+    # @note does not modify the receiver, so bang is not the default method
+    alias_method :refresh!, :refresh
+
+    # Revokes the token at the authorization server
+    #
+    # @param [Hash] params additional parameters to be sent during revocation
+    # @option params [String, Symbol, nil] :token_type_hint ('access_token' or 'refresh_token') hint about which token to revoke
+    # @option params [Symbol] :token_method (:post_with_query_string) overrides OAuth2::Client#options[:token_method]
+    #
+    # @yield [req] The block is passed the request being made, allowing customization
+    # @yieldparam [Faraday::Request] req The request object that can be modified
+    #
+    # @return [OAuth2::Response] OAuth2::Response instance
+    #
+    # @api public
+    #
+    # @raise [OAuth2::Error] if token_type_hint is invalid or the specified token is not available
+    #
+    # @note If the token passed to the request
+    #    is an access token, the server MAY revoke the respective refresh
+    #    token as well.
+    # @note If the token passed to the request
+    #    is a refresh token and the authorization server supports the
+    #    revocation of access tokens, then the authorization server SHOULD
+    #    also invalidate all access tokens based on the same authorization
+    #    grant
+    # @note If the server responds with HTTP status code 503, your code must
+    #    assume the token still exists and may retry after a reasonable delay.
+    #    The server may include a "Retry-After" header in the response to
+    #    indicate how long the service is expected to be unavailable to the
+    #    requesting client.
+    #
+    # @see https://datatracker.ietf.org/doc/html/rfc7009
+    # @see https://datatracker.ietf.org/doc/html/rfc7009#section-2.1
+    def revoke(params = {}, &block)
+      token_type_hint_orig = params.delete(:token_type_hint)
+      token_type_hint = nil
+      revoke_token = case token_type_hint_orig
+      when "access_token", :access_token
+        token_type_hint = "access_token"
+        token
+      when "refresh_token", :refresh_token
+        token_type_hint = "refresh_token"
+        refresh_token
+      when nil
+        if token
+          token_type_hint = "access_token"
+          token
+        elsif refresh_token
+          token_type_hint = "refresh_token"
+          refresh_token
+        end
+      else
+        raise OAuth2::Error.new({error: "token_type_hint must be one of [nil, :refresh_token, :access_token], so if you need something else consider using a subclass or entirely custom AccessToken class."})
+      end
+      raise OAuth2::Error.new({error: "#{token_type_hint || "unknown token type"} is not available for revoking"}) unless revoke_token && !revoke_token.empty?
+
+      @client.revoke_token(revoke_token, token_type_hint, params, &block)
+    end
+    # A compatibility alias
+    # @note does not modify the receiver, so bang is not the default method
+    alias_method :revoke!, :revoke
 
     # Convert AccessToken to a hash which can be used to rebuild itself with AccessToken.from_hash
     #
+    # @note Don't return expires_latency because it has already been deducted from expires_at
+    #
     # @return [Hash] a hash of AccessToken property values
     def to_hash
-      params.merge(:access_token => token, :refresh_token => refresh_token, :expires_at => expires_at)
+      hsh = {
+        access_token: token,
+        refresh_token: refresh_token,
+        expires_at: expires_at,
+        mode: options[:mode],
+        header_format: options[:header_format],
+        param_name: options[:param_name],
+      }
+      hsh[:token_name] = options[:token_name] if options.key?(:token_name)
+      # TODO: Switch when dropping Ruby < 2.5 support
+      # params.transform_keys(&:to_sym) # Ruby 2.5 only
+      # Old Ruby transform_keys alternative:
+      sheesh = @params.each_with_object({}) { |(k, v), memo|
+        memo[k.to_sym] = v
+      }
+      sheesh.merge(hsh)
     end
 
     # Make a request with the Access Token
@@ -103,9 +316,18 @@ module OAuth2
     # @param [Symbol] verb the HTTP request method
     # @param [String] path the HTTP URL path of the request
     # @param [Hash] opts the options to make the request with
-    # @see Client#request
+    # @option opts [Hash] :params additional URL parameters
+    # @option opts [Hash, String] :body the request body
+    # @option opts [Hash] :headers request headers
+    #
+    # @yield [req] The block to modify the request
+    # @yieldparam [Faraday::Request] req The request object that can be modified
+    #
+    # @return [OAuth2::Response] the response from the request
+    #
+    # @see OAuth2::Client#request
     def request(verb, path, opts = {}, &block)
-      configure_authentication!(opts)
+      configure_authentication!(opts, verb)
       @client.request(verb, path, opts, &block)
     end
 
@@ -146,17 +368,31 @@ module OAuth2
 
     # Get the headers hash (includes Authorization token)
     def headers
-      {'Authorization' => options[:header_format] % token}
+      {"Authorization" => options[:header_format] % token}
     end
 
   private
 
-    def configure_authentication!(opts) # rubocop:disable Metrics/AbcSize
-      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
@@ -164,11 +400,11 @@ module OAuth2
         if opts[:body].is_a?(Hash)
           opts[:body][options[:param_name]] = token
         else
-          opts[:body] << "&#{options[:param_name]}=#{token}"
+          opts[:body] += "&#{options[:param_name]}=#{token}"
         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/auth_sanitizer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OAuth2
+  AUTH_SANITIZER = begin
+    auth_sanitizer_requirement = Gem::Requirement.new("~> 0.1", ">= 0.1.3")
+    auth_sanitizer_spec = Gem.loaded_specs["auth-sanitizer"]
+    unless auth_sanitizer_spec && auth_sanitizer_requirement.satisfied_by?(auth_sanitizer_spec.version)
+      # :nocov:
+      auth_sanitizer_spec = Gem::Specification.find_by_name("auth-sanitizer", auth_sanitizer_requirement)
+      # :nocov:
+    end
+
+    auth_sanitizer_loader_path = File.join(
+      auth_sanitizer_spec.full_gem_path,
+      "lib/auth_sanitizer/loader.rb",
+    )
+    unless File.file?(auth_sanitizer_loader_path)
+      # :nocov:
+      raise LoadError, "oauth2 requires auth-sanitizer #{auth_sanitizer_requirement}; " \
+        "loader not found at #{auth_sanitizer_loader_path}"
+      # :nocov:
+    end
+
+    auth_sanitizer_loader_namespace = Module.new
+    auth_sanitizer_loader_namespace.module_eval(
+      File.read(auth_sanitizer_loader_path),
+      auth_sanitizer_loader_path,
+      1,
+    )
+
+    auth_sanitizer_loader_namespace.
+      const_get(:AuthSanitizer).
+      const_get(:Loader).
+      load_isolated
+  end
+end