oauth2 2.0.9 → 2.0.22

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/2024 | [Tidelift Subscription][tidelift-ref] |
-| 1.latest | ✅         | 04/2023 | [Tidelift Subscription][tidelift-ref] |
-| <= 1     | ⛔         | ⛔       | ⛔                                     |
+| Version  | Supported |
+|----------|-----------|
+| 2.0.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/certs/pboling.pem

@@ -0,0 +1,27 @@
+-----BEGIN CERTIFICATE-----
+MIIEgDCCAuigAwIBAgIBATANBgkqhkiG9w0BAQsFADBDMRUwEwYDVQQDDAxwZXRl
+ci5ib2xpbmcxFTATBgoJkiaJk/IsZAEZFgVnbWFpbDETMBEGCgmSJomT8ixkARkW
+A2NvbTAeFw0yNTA1MDQxNTMzMDlaFw00NTA0MjkxNTMzMDlaMEMxFTATBgNVBAMM
+DHBldGVyLmJvbGluZzEVMBMGCgmSJomT8ixkARkWBWdtYWlsMRMwEQYKCZImiZPy
+LGQBGRYDY29tMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAruUoo0WA
+uoNuq6puKWYeRYiZekz/nsDeK5x/0IEirzcCEvaHr3Bmz7rjo1I6On3gGKmiZs61
+LRmQ3oxy77ydmkGTXBjruJB+pQEn7UfLSgQ0xa1/X3kdBZt6RmabFlBxnHkoaGY5
+mZuZ5+Z7walmv6sFD9ajhzj+oIgwWfnEHkXYTR8I6VLN7MRRKGMPoZ/yvOmxb2DN
+coEEHWKO9CvgYpW7asIihl/9GMpKiRkcYPm9dGQzZc6uTwom1COfW0+ZOFrDVBuV
+FMQRPswZcY4Wlq0uEBLPU7hxnCL9nKK6Y9IhdDcz1mY6HZ91WImNslOSI0S8hRpj
+yGOWxQIhBT3fqCBlRIqFQBudrnD9jSNpSGsFvbEijd5ns7Z9ZMehXkXDycpGAUj1
+to/5cuTWWw1JqUWrKJYoifnVhtE1o1DZ+LkPtWxHtz5kjDG/zR3MG0Ula0UOavlD
+qbnbcXPBnwXtTFeZ3C+yrWpE4pGnl3yGkZj9SMTlo9qnTMiPmuWKQDatAgMBAAGj
+fzB9MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBQE8uWvNbPVNRXZ
+HlgPbc2PCzC4bjAhBgNVHREEGjAYgRZwZXRlci5ib2xpbmdAZ21haWwuY29tMCEG
+A1UdEgQaMBiBFnBldGVyLmJvbGluZ0BnbWFpbC5jb20wDQYJKoZIhvcNAQELBQAD
+ggGBAJbnUwfJQFPkBgH9cL7hoBfRtmWiCvdqdjeTmi04u8zVNCUox0A4gT982DE9
+wmuN12LpdajxZONqbXuzZvc+nb0StFwmFYZG6iDwaf4BPywm2e/Vmq0YG45vZXGR
+L8yMDSK1cQXjmA+ZBKOHKWavxP6Vp7lWvjAhz8RFwqF9GuNIdhv9NpnCAWcMZtpm
+GUPyIWw/Cw/2wZp74QzZj6Npx+LdXoLTF1HMSJXZ7/pkxLCsB8m4EFVdb/IrW/0k
+kNSfjtAfBHO8nLGuqQZVH9IBD1i9K6aSs7pT6TW8itXUIlkIUI2tg5YzW6OFfPzq
+QekSkX3lZfY+HTSp/o+YvKkqWLUV7PQ7xh1ZYDtocpaHwgxe/j3bBqHE+CUPH2vA
+0V/FwdTRWcwsjVoOJTrYcff8pBZ8r2MvtAc54xfnnhGFzeRHfcltobgFxkAXdE6p
+DVjBtqT23eugOqQ73umLcYDZkc36vnqGxUBSsXrzY9pzV5gGr2I8YUxMqf6ATrZt
+L9nRqA==
+-----END CERTIFICATE-----

data/lib/oauth2/access_token.rb

@@ -1,27 +1,81 @@
 # 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
     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
 
     class << self
       # Initializes an AccessToken from a Hash
       #
-      # @param [Client] client the OAuth2::Client instance
-      # @param [Hash] hash a hash of AccessToken property values
-      # @option hash [String, Symbol] 'access_token', 'id_token', 'token', :access_token, :id_token, or :token the access token
-      # @return [AccessToken] the initialized 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)
         fresh = hash.dup
-        supported_keys = TOKEN_KEY_LOOKUP & fresh.keys
-        key = supported_keys[0]
-        extra_tokens_warning(supported_keys, key)
-        token = fresh.delete(key)
+        # 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
 
@@ -43,10 +97,31 @@ module OAuth2
 
         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
 
     # 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 (optional, may not be used in refresh flows)
     # @param [Hash] opts the options to create the Access Token with
@@ -54,15 +129,22 @@ module OAuth2
     # @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
+    #    When nil one of TOKEN_KEY_LOOKUP will be used
     def initialize(client, token, opts = {})
       @client = client
       @token = token.to_s
-
       opts = opts.dup
       %i[refresh_token expires_in expires_at expires_latency].each do |arg|
         instance_variable_set("@#{arg}", opts.delete(arg) || opts.delete(arg.to_s))
@@ -70,22 +152,28 @@ module OAuth2
       no_tokens = (@token.nil? || @token.empty?) && (@refresh_token.nil? || @refresh_token.empty?)
       if no_tokens
         if @client.options[:raise_errors]
-          error = Error.new(opts)
-          raise(error)
-        else
-          warn('OAuth2::AccessToken has no token')
+          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 ||= opts.delete("expires")
       @expires_in &&= @expires_in.to_i
       @expires_at &&= convert_expires_at(@expires_at)
       @expires_latency &&= @expires_latency.to_i
-      @expires_at ||= Time.now.to_i + @expires_in if @expires_in
+      @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 = {
+        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
 
@@ -96,33 +184,40 @@ 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)
     end
 
     # Refreshes the current Access Token
     #
-    # @return [AccessToken] a new AccessToken
-    # @note options should be carried over to the new AccessToken
-    def refresh(params = {}, access_token_opts = {})
-      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, access_token_opts)
+      new_token = @client.get_token(params, access_token_opts, &block)
       new_token.options = options
       if new_token.refresh_token
-        # Keep it, if there is one
+        # Keep it if there is one
       else
         new_token.refresh_token = refresh_token
       end
@@ -130,13 +225,90 @@ module OAuth2
     end
     # A compatibility alias
     # @note does not modify the receiver, so bang is not the default method
-    alias refresh! refresh
+    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
@@ -144,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
 
@@ -187,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)
-      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
@@ -209,7 +404,7 @@ module OAuth2
         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.2", ">= 0.2.1")
+    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

data/lib/oauth2/authenticator.rb

@@ -1,11 +1,26 @@
 # frozen_string_literal: true
 
-require 'base64'
+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
@@ -14,7 +29,7 @@ module OAuth2
 
     # Apply the request credentials used to authenticate to the Authorization Server
     #
-    # Depending on configuration, this might be as request params or as an
+    # Depending on the configuration, this might be as request params or as an
     # Authorization header.
     #
     # User-provided params and header take precedence.
@@ -36,40 +51,59 @@ module OAuth2
       end
     end
 
-    def self.encode_basic_auth(user, password)
-      "Basic #{Base64.strict_encode64("#{user}:#{password}")}"
+    class << self
+      # 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 encode_basic_auth(user, password)
+        "Basic #{Base64.strict_encode64("#{user}:#{password}")}"
+      end
     end
 
   private
 
     # 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?
-      result['client_secret'] = secret unless secret.nil?
+      result["client_id"] = id unless id.nil?
+      result["client_secret"] = secret unless secret.nil?
       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?
+      result["client_id"] = id unless id.nil?
       result.merge(params)
     end
 
     # 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)}
+      {"Authorization" => self.class.encode_basic_auth(id, secret)}
     end
   end
 end