oauth2 2.0.18 → 2.0.23

data/SECURITY.md

@@ -4,7 +4,7 @@
 
 | Version  | Supported |
 |----------|-----------|
-| 1.latest | ✅         |
+| 2.0.latest | ✅         |
 
 ## Security contact information
 
@@ -12,8 +12,6 @@ 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,
@@ -21,4 +19,3 @@ please consider sponsoring the project / maintainer @ https://liberapay.com/pbol
 or find other sponsorship links in the [README].
 
 [README]: README.md
-[IRP]: IRP.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

@@ -57,28 +57,19 @@ module OAuth2
       def from_hash(client, hash)
         fresh = hash.dup
         # If token_name is present, then use that key name
-        key =
-          if fresh.key?(:token_name)
-            t_key = fresh[:token_name]
-            no_tokens_warning(fresh, t_key)
-            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)
-            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(key) || fresh[key] || ""
+        if fresh.key?(:token_name)
+          t_key = fresh[:token_name]
+          no_tokens_warning(fresh, t_key)
         else
-          fresh.delete(key) || ""
+          # 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 = extract_token_value(fresh, t_key)
+        # :nocov:
         new(client, token, fresh)
       end
 
@@ -111,6 +102,17 @@ Custom token_name (#{key}) is not found in (#{hash.keys})
 You may need to set `snaky: false`. See inline documentation for more info.
         ])
       end
+
+      # :nocov:
+      def extract_token_value(fresh, key)
+        token_value = fresh.delete(key)
+        return token_value || "" if defined?(Hashie::VERSION)
+
+        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 this accounts for.
+        token_value || fresh[key] || ""
+      end
+      # :nocov:
     end
 
     # Initialize an AccessToken
@@ -308,8 +310,8 @@ You may need to set `snaky: false`. See inline documentation for more info.
       # 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 = @params.each_with_object({}) { |(key, value), memo|
+        memo[key.to_sym] = value
       }
       sheesh.merge(hsh)
     end
@@ -378,6 +380,7 @@ You may need to set `snaky: false`. See inline documentation for more info.
 
     def configure_authentication!(opts, verb)
       mode_opt = options[:mode]
+      param_name = options[:param_name]
       mode =
         if mode_opt.respond_to?(:call)
           mode_opt.call(verb)
@@ -391,19 +394,19 @@ You may need to set `snaky: false`. See inline documentation for more info.
 
       case mode
       when :header
-        opts[:headers] ||= {}
-        opts[:headers].merge!(headers)
+        request_headers = opts[:headers] ||= {}
+        request_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
+        request_params = opts[:params] ||= {}
+        request_params[param_name] = token
       when :body
-        opts[:body] ||= {}
-        if opts[:body].is_a?(Hash)
-          opts[:body][options[:param_name]] = token
+        request_body = opts[:body] ||= {}
+        if request_body.is_a?(Hash)
+          request_body[param_name] = token
         else
-          opts[:body] += "&#{options[:param_name]}=#{token}"
+          opts[:body] = "#{request_body}&#{param_name}=#{token}"
         end
         # @todo support for multi-part (file uploads)
       else

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

@@ -51,13 +51,15 @@ 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}")}"
+    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

data/lib/oauth2/client.rb

@@ -42,7 +42,7 @@ module OAuth2
     # @option options [Hash] :connection_opts ({}) Hash of connection options to pass to initialize Faraday
     # @option options [Boolean] :raise_errors (true) whether to raise an OAuth2::Error on responses with 400+ status codes
     # @option options [Integer] :max_redirects (5) maximum number of redirects to follow
-    # @option options [Logger] :logger (::Logger.new($stdout)) Logger instance for HTTP request/response output; requires OAUTH_DEBUG to be true
+    # @option options [Logger] :logger (::Logger.new($stdout)) Logger instance for HTTP request/response output; requires OAUTH_DEBUG to be true. When debug logging is enabled, sensitive values are filtered using {OAuth2::AUTH_SANITIZER::SanitizedLogger} initialized from `OAuth2.config[:filtered_label]` and the key names in `OAuth2.config[:filtered_debug_keys]`.
     # @option options [Class] :access_token_class (AccessToken) class to use for access tokens; you can subclass OAuth2::AccessToken, @version 2.0+
     # @option options [Hash] :ssl SSL options for Faraday
     #
@@ -86,8 +86,9 @@ module OAuth2
       @connection ||=
         Faraday.new(site, options[:connection_opts]) do |builder|
           oauth_debug_logging(builder)
-          if options[:connection_build]
-            options[:connection_build].call(builder)
+          connection_build = options[:connection_build]
+          if connection_build
+            connection_build.call(builder)
           else
             builder.request(:url_encoded)             # form-encode POST params
             builder.adapter(Faraday.default_adapter)  # make requests with Net::HTTP
@@ -149,9 +150,9 @@ module OAuth2
 
       case status
       when 301, 302, 303, 307
-        req_opts[:redirect_count] ||= 0
-        req_opts[:redirect_count] += 1
-        return response if req_opts[:redirect_count] > options[:max_redirects]
+        redirect_count = (req_opts[:redirect_count] || 0).to_i + 1
+        req_opts[:redirect_count] = redirect_count
+        return response if redirect_count > options[:max_redirects]
 
         if status == 303
           verb = :get
@@ -159,8 +160,9 @@ module OAuth2
         end
         location = response.headers["location"]
         if location
-          full_location = response.response.env.url.merge(location)
-          request(verb, full_location, req_opts)
+          current_location = response.response.env.url
+          full_location = resolve_redirect_location(current_location, location)
+          request(verb, full_location, sanitize_redirect_options(req_opts, current_location, full_location))
         else
           error = Error.new(response)
           raise(error, "Got #{status} status code, but no Location header was present")
@@ -337,8 +339,9 @@ module OAuth2
     #
     # @return [Hash] the params to add to a request or URL
     def redirection_params
-      if options[:redirect_uri]
-        {"redirect_uri" => options[:redirect_uri]}
+      redirect_uri = options[:redirect_uri]
+      if redirect_uri
+        {"redirect_uri" => redirect_uri}
       else
         {}
       end
@@ -445,18 +448,18 @@ module OAuth2
       url = connection.build_url(url).to_s
       # See: Hash#partition https://bugs.ruby-lang.org/issues/16252
       req_opts, oauth_opts = opts.
-        partition { |k, _v| RESERVED_REQ_KEYS.include?(k.to_s) }.
-        map { |p| Hash[p] }
+        partition { |key, _value| RESERVED_REQ_KEYS.include?(key.to_s) }.
+        map(&:to_h)
 
       begin
         response = connection.run_request(verb, url, req_opts[:body], req_opts[:headers]) do |req|
           req.params.update(req_opts[:params]) if req_opts[:params]
           yield(req) if block_given?
         end
-      rescue Faraday::ConnectionFailed => e
-        raise ConnectionError, e
-      rescue Faraday::TimeoutError => e
-        raise TimeoutError, e
+      rescue Faraday::ConnectionFailed => exception
+        raise ConnectionError, exception
+      rescue Faraday::TimeoutError => exception
+        raise TimeoutError, exception
       end
 
       parse = oauth_opts.key?(:parse) ? oauth_opts.delete(:parse) : Response::DEFAULT_OPTIONS[:parse]
@@ -465,6 +468,49 @@ module OAuth2
       Response.new(response, parse: parse, snaky: snaky)
     end
 
+    def resolve_redirect_location(current_location, location)
+      return protocol_relative_redirect_location(current_location, location) if location.respond_to?(:start_with?) && location.start_with?("//")
+
+      current_location.merge(location)
+    end
+
+    def protocol_relative_redirect_location(current_location, location)
+      protocol_relative_location = URI.parse(location)
+      authority = +""
+      authority << "#{protocol_relative_location.userinfo}@" if protocol_relative_location.userinfo
+      authority << protocol_relative_location.host.to_s
+      authority << ":#{protocol_relative_location.port}" if protocol_relative_location.port
+
+      current_location.dup.tap do |safe_location|
+        safe_location.path = "///#{authority}#{protocol_relative_location.path}"
+        safe_location.query = protocol_relative_location.query if safe_location.respond_to?(:query=)
+        safe_location.fragment = protocol_relative_location.fragment if safe_location.respond_to?(:fragment=)
+      end
+    end
+
+    def sanitize_redirect_options(req_opts, current_location, next_location)
+      return req_opts unless cross_origin_redirect?(current_location, next_location)
+
+      headers = req_opts[:headers]
+      return req_opts unless headers && headers.any? { |key, _value| authorization_header?(key) }
+
+      safe_opts = req_opts.dup
+      safe_headers = headers.dup
+      safe_headers.delete_if { |key, _value| authorization_header?(key) }
+      safe_opts[:headers] = safe_headers
+      safe_opts
+    end
+
+    def authorization_header?(key)
+      key.to_s.casecmp("Authorization").zero?
+    end
+
+    def cross_origin_redirect?(current_location, next_location)
+      current_location.scheme != next_location.scheme ||
+        current_location.host != next_location.host ||
+        current_location.port != next_location.port
+    end
+
     # Returns the authenticator object
     #
     # @return [Authenticator] the initialized Authenticator
@@ -563,7 +609,18 @@ module OAuth2
     end
 
     def oauth_debug_logging(builder)
-      builder.response(:logger, options[:logger], bodies: true) if OAuth2::OAUTH_DEBUG
+      if OAuth2::OAUTH_DEBUG
+        config = OAuth2.config
+        builder.response(
+          :logger,
+          OAuth2::AUTH_SANITIZER::SanitizedLogger.new(
+            options[:logger],
+            filtered_keys: config[:filtered_debug_keys],
+            label: config[:filtered_label]
+          ),
+          bodies: true
+        )
+      end
     end
   end
 end

data/lib/oauth2/error.rb

@@ -17,10 +17,13 @@ module OAuth2
     # @param [OAuth2::Response, Hash, Object] response A Response or error payload
     def initialize(response)
       @response = response
+      @code = nil
+      @description = nil
       if response.respond_to?(:parsed)
-        if response.parsed.is_a?(Hash)
-          @code = response.parsed["error"]
-          @description = response.parsed["error_description"]
+        parsed_response = response.parsed
+        if parsed_response.is_a?(Hash)
+          @code = parsed_response["error"]
+          @description = parsed_response["error_description"]
         end
       elsif response.is_a?(Hash)
         @code = response["error"]
@@ -44,11 +47,12 @@ module OAuth2
     # @return [String] Message suitable for StandardError
     def error_message(response_body, opts = {})
       lines = []
+      error_description = opts[:error_description]
 
-      lines << opts[:error_description] if opts[:error_description]
+      lines << error_description if error_description
 
-      error_string = if response_body.respond_to?(:encode) && opts[:error_description].respond_to?(:encoding)
-        script_encoding = opts[:error_description].encoding
+      error_string = if response_body.respond_to?(:encode) && error_description.respond_to?(:encoding)
+        script_encoding = error_description.encoding
         response_body.encode(script_encoding, invalid: :replace, undef: :replace)
       else
         response_body

data/lib/oauth2/filtered_attributes.rb

@@ -1,52 +1,10 @@
+# frozen_string_literal: true
+
 module OAuth2
-  # Mixin that redacts sensitive instance variables in #inspect output.
+  # Permanent alias for {OAuth2::AUTH_SANITIZER::FilteredAttributes}.
   #
-  # 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?
-
-      inspected_vars = instance_variables.map do |var|
-        if filtered_attribute_names.any? { |filtered_var| var.to_s.include?(filtered_var.to_s) }
-          "#{var}=[FILTERED]"
-        else
-          "#{var}=#{instance_variable_get(var).inspect}"
-        end
-      end
-      "#<#{self.class}:#{object_id} #{inspected_vars.join(", ")}>"
-    end
-  end
+  # This constant is intentionally kept in the `OAuth2` namespace because it
+  # was part of the public API before the implementation was extracted into the
+  # `auth-sanitizer` gem.  It will **not** be deprecated or removed.
+  FilteredAttributes = OAuth2::AUTH_SANITIZER::FilteredAttributes
 end

data/lib/oauth2/response.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "set"
 require "multi_xml"
 require "rack"
 
@@ -43,18 +44,20 @@ module OAuth2
       "text/plain" => :text,
     }
 
-    # Adds a new content type parser.
-    #
-    # @param [Symbol] key A descriptive symbol key such as :json or :query
-    # @param [Array<String>, String] mime_types One or more mime types to which this parser applies
-    # @yield [String] Block that will be called to parse the response body
-    # @yieldparam [String] body The response body to parse
-    # @return [void]
-    def self.register_parser(key, mime_types, &block)
-      key = key.to_sym
-      @@parsers[key] = block
-      Array(mime_types).each do |mime_type|
-        @@content_types[mime_type] = key
+    class << self
+      # Adds a new content type parser.
+      #
+      # @param [Symbol] key A descriptive symbol key such as :json or :query
+      # @param [Array<String>, String] mime_types One or more mime types to which this parser applies
+      # @yield [String] Block that will be called to parse the response body
+      # @yieldparam [String] body The response body to parse
+      # @return [void]
+      def register_parser(key, mime_types, &block)
+        key = key.to_sym
+        @@parsers[key] = block
+        Array(mime_types).each do |mime_type|
+          @@content_types[mime_type] = key
+        end
       end
     end
 
@@ -106,15 +109,16 @@ module OAuth2
     def parsed
       return @parsed if defined?(@parsed)
 
+      response_parser = parser
       @parsed =
-        if parser.respond_to?(:call)
-          case parser.arity
+        if response_parser.respond_to?(:call)
+          case response_parser.arity
           when 0
-            parser.call
+            response_parser.call
           when 1
-            parser.call(body)
+            response_parser.call(body)
           else
-            parser.call(body, response)
+            response_parser.call(body, response)
           end
         end
 
@@ -130,9 +134,10 @@ module OAuth2
     #
     # @return [String, nil] The content type or nil if headers are not present
     def content_type
-      return unless response.headers
+      response_headers = response.headers
+      return unless response_headers
 
-      ((response.headers.values_at("content-type", "Content-Type").compact.first || "").split(";").first || "").strip.downcase
+      ((response_headers.values_at("content-type", "Content-Type").compact.first || "").split(";").first || "").strip.downcase
     end
 
     # Determines the parser to be used for the response body
@@ -152,11 +157,12 @@ module OAuth2
     def parser
       return @parser if defined?(@parser)
 
+      parse_option = options[:parse]
       @parser =
-        if options[:parse].respond_to?(:call)
-          options[:parse]
-        elsif options[:parse]
-          @@parsers[options[:parse].to_sym]
+        if parse_option.respond_to?(:call)
+          parse_option
+        elsif parse_option
+          @@parsers[parse_option.to_sym]
         end
 
       @parser ||= @@parsers[@@content_types[content_type]]
@@ -169,7 +175,7 @@ end
 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)
+  (defined?(MultiXML) ? MultiXML : MultiXml).parse(body)
 end
 
 # Register JSON parser

data/lib/oauth2/version.rb

@@ -2,6 +2,7 @@
 
 module OAuth2
   module Version
-    VERSION = "2.0.18"
+    VERSION = "2.0.23"
   end
+  VERSION = Version::VERSION # Traditional Constant Location
 end

data/lib/oauth2.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # includes modules from stdlib
-require "cgi"
+require "cgi/escape"
 require "time"
 
 # third party gems
@@ -10,6 +10,7 @@ require "version_gem"
 
 # includes gem files
 require_relative "oauth2/version"
+require_relative "oauth2/auth_sanitizer"
 require_relative "oauth2/filtered_attributes"
 require_relative "oauth2/error"
 require_relative "oauth2/authenticator"
@@ -43,38 +44,59 @@ module OAuth2
   #     config[:silence_no_tokens_warning] = false
   #   end
   #
+  # @example Customize filtered output markers and debug-log value filtering by key name
+  #   OAuth2.configure do |config|
+  #     config[:filtered_label] = "[REDACTED]"
+  #     config[:filtered_debug_keys] += ["client_assertion"]
+  #   end
+  #
+  # Existing objects and logger wrappers snapshot filtering configuration during
+  # initialization. Changing these config values later affects only newly
+  # initialized objects and debug loggers.
+  #
   # @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,
+    filtered_label: "[FILTERED]",
+    filtered_debug_keys: %w[
+      access_token
+      refresh_token
+      id_token
+      client_secret
+      assertion
+      code_verifier
+      token
+    ]
   )
 
   # The current runtime configuration for the library.
   #
   # @return [SnakyHash::SymbolKeyed]
-  @config = DEFAULT_CONFIG.dup
+  CONFIG = DEFAULT_CONFIG.dup
 
   class << self
-    # Access the current configuration.
+    def config
+      CONFIG
+    end
+
+    # Configure global library behavior.
     #
-    # Prefer using {OAuth2.configure} to mutate configuration.
+    # Yields the mutable configuration object so callers can update settings.
     #
-    # @return [SnakyHash::SymbolKeyed]
-    attr_reader :config
+    # @yieldparam [SnakyHash::SymbolKeyed] config the configuration object
+    # @return [void]
+    def configure
+      yield config
+    end
   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
 
+# Wire OAuth2::AUTH_SANITIZER's label provider to read from OAuth2.config so that
+# FilteredAttributes-bearing objects and OAuth2::AUTH_SANITIZER::SanitizedLogger instances
+# pick up OAuth2.config[:filtered_label] at their initialization time.
+OAuth2::AUTH_SANITIZER.filtered_label_provider = -> { OAuth2.config[:filtered_label] }
+
 # Extend OAuth2::Version with VersionGem helpers to provide semantic version helpers.
 OAuth2::Version.class_eval do
   extend VersionGem::Basic