🔒️ Redact sensitive values from debug logging output

- Add `OAuth2.config[:filtered_label]` to configure the placeholder used for filtered sensitive values in inspected objects and debug logging output.
- Add `OAuth2.config[:filtered_debug_keys]` to configure which key names have their values redacted from debug logging output.
- Add `OAuth2::ThingFilter` as the shared filtering primitive used by inspect-time and debug-log filtering.
- Make inspect-time and debug-log filters snapshot their configuration at initialization time rather than tracking later config changes.
- Automatically redacted values include:
  - Authorization headers
  - common token/secret fields in headers
  - query strings
  - form bodies
  - JSON payloads
- NOTE: debug logging has always been, and remains, opt-in. It is turned off by default.

Co-authored-by: autobolt <autobots@9thbit.net>

Author: pboling

CHANGELOG.md

@@ -20,8 +20,14 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Added
 
+- Add `OAuth2.config[:filtered_label]` to configure the placeholder used for filtered sensitive values in inspected objects and debug logging output.
+- Add `OAuth2.config[:filtered_debug_keys]` to configure which key names have their values redacted from debug logging output.
+- Add `OAuth2::ThingFilter` as the shared filtering primitive used by inspect-time and debug-log filtering.
+
 ### Changed
 
+- Make inspect-time and debug-log filters snapshot their configuration at initialization time rather than tracking later config changes.
+
 ### Deprecated
 
 ### Removed
@@ -30,6 +36,9 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+- Redact sensitive values from debug logging output, including Authorization headers and common token/secret fields in headers, query strings, form bodies, and JSON payloads.
+  - NOTE: debug logging has always been, and remains, opt-in. It is turned off by defualt.
+
 ## [2.0.18] - 2025-11-08
 
 - TAG: [v2.0.18][2.0.18t]

README.md

@@ -330,6 +330,19 @@ OAuth2.configure do |config|
 end
 ```
 
+Filtering-related settings:
+
+```ruby
+OAuth2.configure do |config|
+  config.filtered_label = "[REDACTED]" # default: "[FILTERED]"
+  config.filtered_debug_keys += ["client_assertion"]
+end
+```
+
+- `filtered_label` controls the placeholder used when sensitive values are filtered from inspected objects and debug logging output.
+- `filtered_debug_keys` controls which key names have their values redacted from debug logging output when `OAUTH_DEBUG=true`.
+- Debug logging remains opt-in and should still be used cautiously in production environments.
+
 ## 🔧 Basic Usage
 
 ### Client Initialization Options

lib/oauth2.rb

@@ -10,7 +10,9 @@
 
 # includes gem files
 require_relative "oauth2/version"
+require_relative "oauth2/thing_filter"
 require_relative "oauth2/filtered_attributes"
+require_relative "oauth2/sanitized_logger"
 require_relative "oauth2/error"
 require_relative "oauth2/authenticator"
 require_relative "oauth2/client"
@@ -43,10 +45,30 @@ 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.

lib/oauth2/client.rb

@@ -42,7 +42,7 @@ class Client # rubocop:disable Metrics/ClassLength
     # @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 a {ThingFilter} 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
     #
@@ -563,7 +563,7 @@ def build_access_token_legacy(response, access_token_opts, extract_access_token)
     end
 
     def oauth_debug_logging(builder)
-      builder.response(:logger, options[:logger], bodies: true) if OAuth2::OAUTH_DEBUG
+      builder.response(:logger, SanitizedLogger.new(options[:logger]), bodies: true) if OAuth2::OAUTH_DEBUG
     end
   end
 end

lib/oauth2/filtered_attributes.rb

@@ -1,17 +1,38 @@
+# frozen_string_literal: true
+
 module OAuth2
-  # Mixin that redacts sensitive instance variables in #inspect output.
+  # Mixin that redacts sensitive instance variables in `#inspect` output.
+  #
+  # Classes include this module and declare which attribute names should be
+  # filtered via {.filtered_attributes}. Matching and replacement behavior is
+  # delegated to {ThingFilter}, which is initialized once per object.
   #
-  # 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.
+  # This means existing objects keep the filter configuration that was present
+  # when they were initialized, even if global config or class-level filter
+  # declarations change later.
   module FilteredAttributes
     # Hook invoked when the module is included. Extends the including class with
-    # class-level helpers.
+    # class-level helpers and prepends the initializer hook.
     #
     # @param [Class] base The including class
     # @return [void]
     def self.included(base)
       base.extend(ClassMethods)
+      base.prepend(InitializerMethods)
+    end
+
+    # Initializer hook that snapshots the thing filter for this object.
+    #
+    # The snapshot captures both the class-level filtered attribute names and
+    # the current `OAuth2.config[:filtered_label]` value.
+    module InitializerMethods
+      def initialize(*args, &block)
+        super(*args, &block)
+        @thing_filter = ThingFilter.new(
+          self.class.filtered_attribute_names,
+          label: OAuth2.config[:filtered_label],
+        )
+      end
     end
 
     # Class-level helpers for configuring filtered attributes.
@@ -50,16 +71,24 @@ def filtered_attribute_names
       end
     end
 
+    # The initialized thing filter used by this object.
+    #
+    # This is a per-instance snapshot created during initialization.
+    #
+    # @return [ThingFilter]
+    def thing_filter
+      @thing_filter
+    end
+
     # Custom inspect that redacts configured attributes.
     #
     # @return [String]
     def inspect
-      filtered_attribute_names = ClassMethods.filtered_attribute_names(self.class)
-      return super if filtered_attribute_names.empty?
+      return super if thing_filter.things.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]"
+        if thing_filter.filtered?(var)
+          "#{var}=#{thing_filter.label}"
         else
           "#{var}=#{instance_variable_get(var).inspect}"
         end