auth-sanitizer 0.2.3 → 0.2.5

data/lib/auth/sanitizer/filtered_attributes.rb

@@ -4,13 +4,11 @@ module Auth
   module Sanitizer
     # 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 attribute names to filter via {.filtered_attributes}.
+    # Matching and replacement behavior is delegated to {ThingFilter}, initialized once per object.
     #
-    # 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.
+    # 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.
     #
     # The label used for redaction is resolved from {Auth::Sanitizer.filtered_label}
     # at object initialization time. Host gems may customize this by installing a
@@ -20,7 +18,7 @@ module Auth
         # Hook invoked when the module is included. Extends the including class with
         # class-level helpers and prepends the initializer hook.
         #
-        # @param [Class] base The including class
+        # @param base [Class] The including class
         # @return [void]
         def included(base)
           base.extend(ClassMethods)
@@ -47,7 +45,8 @@ module Auth
         class << self
           # Declare attributes that should be redacted in inspect output.
           #
-          # @param [Array<Symbol, String>] attributes One or more attribute names
+          # @param base [Class] The class the attributes are declared on
+          # @param attributes [Array<Symbol, String>] One or more attribute names
           # @return [void]
           def filtered_attributes(base, *attributes)
             base.instance_variable_set(:@filtered_attribute_names, attributes.map(&:to_sym))
@@ -55,7 +54,7 @@ module Auth
 
           # The configured attribute names to filter.
           #
-          # @param [Class] base The class to get filtered attributes for
+          # @param base [Class] The class to get filtered attributes for
           # @return [Array<Symbol>]
           def filtered_attribute_names(base)
             return [] unless base.instance_variable_defined?(:@filtered_attribute_names)
@@ -66,7 +65,7 @@ module Auth
 
         # Declare attributes that should be redacted in inspect output.
         #
-        # @param [Array<Symbol, String>] attributes One or more attribute names
+        # @param attributes [Array<Symbol, String>] One or more attribute names
         # @return [void]
         def filtered_attributes(*attributes)
           ClassMethods.filtered_attributes(self, *attributes)
@@ -101,7 +100,9 @@ module Auth
 
       private
 
+      # Matches a quoted string literal inside `#inspect` output.
       INSPECTED_STRING_VALUE = /"(?:(?:\\.)|[^"\\])*"/
+      # Matches redactable key/value pairs inside `#inspect` output.
       INSPECTED_REDACTABLE_VALUE = /
         (?:
           (@([A-Za-z_]\w*[!?=]?)=) |
@@ -113,6 +114,10 @@ module Auth
       /x
       private_constant :INSPECTED_STRING_VALUE, :INSPECTED_REDACTABLE_VALUE
 
+      # Redact filtered values from `#inspect` output text.
+      #
+      # @param inspected [String] The `#inspect` output to redact
+      # @return [String] The redacted inspect output
       def redact_inspected_values(inspected)
         inspected.gsub(INSPECTED_REDACTABLE_VALUE) do |match|
           captures = Regexp.last_match.captures

data/lib/auth/sanitizer/sanitized_logger.rb

@@ -2,12 +2,11 @@
 
 module Auth
   module Sanitizer
-    # Logger wrapper that redacts sensitive values from debug output before
-    # delegating to the underlying logger instance.
+    # Logger wrapper that redacts sensitive values from debug output before delegating to the
+    # underlying logger instance.
     #
-    # This class is intentionally narrow in scope: it only sanitizes string
-    # messages emitted through the logging path and leaves request/response
-    # behavior unchanged.
+    # This class is intentionally narrow in scope: it only sanitizes string messages emitted
+    # through the logging path and leaves request/response behavior unchanged.
     #
     # The underlying {ThingFilter} is initialized once when the logger wrapper is
     # created, so later config changes do not alter the behavior of existing
@@ -15,24 +14,24 @@ module Auth
     class SanitizedLogger
       # Create a new sanitized logger wrapper.
       #
-      # @param [#add, #debug, #info, #warn, #error, #fatal, #unknown] logger
+      # @param logger [#add, #debug, #info, #warn, #error, #fatal, #unknown]
       #   The underlying logger instance that will receive sanitized messages.
-      # @param [Array<String>] filtered_keys
+      # @param filtered_keys [Array<String>]
       #   Key names whose values should be redacted in debug output.
       #   Defaults to {Auth::Sanitizer.default_filtered_keys}.
-      # @param [String] label
+      # @param label [String]
       #   Replacement label for redacted values.
       #   Defaults to {Auth::Sanitizer.filtered_label}.
       def initialize(logger, filtered_keys: Auth::Sanitizer.default_filtered_keys, label: Auth::Sanitizer.filtered_label)
         @logger = logger
-        @thing_filter = ThingFilter.new(filtered_keys, label: label)
+        @value_sanitizer = ValueSanitizer.new(filtered_keys: filtered_keys, label: label)
       end
 
       # Add a log entry after sanitizing any string payloads.
       #
-      # @param [Integer, Symbol, String, nil] severity Logger severity
-      # @param [Object, nil] message Optional log message
-      # @param [Object, nil] progname Optional program name
+      # @param severity [Integer, Symbol, String, nil] Logger severity
+      # @param message [Object, nil] Optional log message
+      # @param progname [Object, nil] Optional program name
       # @yieldreturn [Object] Deferred log message
       # @return [Object] The underlying logger result
       def add(severity, message = nil, progname = nil)
@@ -45,7 +44,7 @@ module Auth
 
       # Append a message to the underlying logger after sanitization.
       #
-      # @param [String] message Message to append
+      # @param message [String] Message to append
       # @return [Object] The underlying logger result
       def <<(message)
         @logger << sanitize(message)
@@ -53,7 +52,7 @@ module Auth
 
       # Log a debug message after sanitization.
       #
-      # @param [Object, nil] progname Optional program name
+      # @param progname [Object, nil] Optional program name
       # @yieldreturn [Object] Deferred log message
       # @return [Object] The underlying logger result
       def debug(progname = nil, &block)
@@ -62,7 +61,7 @@ module Auth
 
       # Log an info message after sanitization.
       #
-      # @param [Object, nil] progname Optional program name
+      # @param progname [Object, nil] Optional program name
       # @yieldreturn [Object] Deferred log message
       # @return [Object] The underlying logger result
       def info(progname = nil, &block)
@@ -71,7 +70,7 @@ module Auth
 
       # Log a warning message after sanitization.
       #
-      # @param [Object, nil] progname Optional program name
+      # @param progname [Object, nil] Optional program name
       # @yieldreturn [Object] Deferred log message
       # @return [Object] The underlying logger result
       def warn(progname = nil, &block)
@@ -80,7 +79,7 @@ module Auth
 
       # Log an error message after sanitization.
       #
-      # @param [Object, nil] progname Optional program name
+      # @param progname [Object, nil] Optional program name
       # @yieldreturn [Object] Deferred log message
       # @return [Object] The underlying logger result
       def error(progname = nil, &block)
@@ -89,7 +88,7 @@ module Auth
 
       # Log a fatal message after sanitization.
       #
-      # @param [Object, nil] progname Optional program name
+      # @param progname [Object, nil] Optional program name
       # @yieldreturn [Object] Deferred log message
       # @return [Object] The underlying logger result
       def fatal(progname = nil, &block)
@@ -98,7 +97,7 @@ module Auth
 
       # Log an unknown-severity message after sanitization.
       #
-      # @param [Object, nil] progname Optional program name
+      # @param progname [Object, nil] Optional program name
       # @yieldreturn [Object] Deferred log message
       # @return [Object] The underlying logger result
       def unknown(progname = nil, &block)
@@ -121,7 +120,7 @@ module Auth
 
       # Set the formatter of the underlying logger if supported.
       #
-      # @param [Object] formatter Formatter object
+      # @param formatter [Object] Formatter object
       # @return [void]
       def formatter=(formatter)
         @logger.formatter = formatter if @logger.respond_to?(:formatter=)
@@ -136,7 +135,7 @@ module Auth
 
       # Set the logger level if supported.
       #
-      # @param [Object] level Logger level
+      # @param level [Object] Logger level
       # @return [void]
       def level=(level)
         @logger.level = level if @logger.respond_to?(:level=)
@@ -151,7 +150,7 @@ module Auth
 
       # Set the logger progname if supported.
       #
-      # @param [Object] progname Logger progname
+      # @param progname [Object] Logger progname
       # @return [void]
       def progname=(progname)
         @logger.progname = progname if @logger.respond_to?(:progname=)
@@ -159,8 +158,8 @@ module Auth
 
       # Report support for methods provided by the wrapped logger.
       #
-      # @param [Symbol] method_name Method name to check
-      # @param [Boolean] include_private Whether private methods are considered
+      # @param method_name [Symbol] Method name to check
+      # @param include_private [Boolean] Whether private methods are considered
       # @return [Boolean]
       def respond_to_missing?(method_name, include_private = false)
         @logger.respond_to?(method_name, include_private) || super
@@ -168,8 +167,8 @@ module Auth
 
       # Delegate unsupported methods to the wrapped logger.
       #
-      # @param [Symbol] method_name Method to invoke
-      # @param [Array<Object>] args Method arguments
+      # @param method_name [Symbol] Method to invoke
+      # @param args [Array<Object>] Method arguments
       # @yield Deferred block forwarded to the wrapped logger
       # @return [Object] The delegated result
       def method_missing(method_name, *args, &block)
@@ -182,8 +181,8 @@ module Auth
 
       # Dispatch a severity-specific log call after sanitization.
       #
-      # @param [Symbol] level Logger method name
-      # @param [Object, nil] progname Optional program name
+      # @param level [Symbol] Logger method name
+      # @param progname [Object, nil] Optional program name
       # @yieldreturn [Object] Deferred log message
       # @return [Object] The underlying logger result
       def log(level, progname = nil)
@@ -196,48 +195,12 @@ module Auth
 
       # Sanitize a logger message when it is a String.
       #
-      # @param [Object] message Potential logger payload
+      # @param message [Object] Potential logger payload
       # @return [Object] Unchanged non-String payloads, sanitized String payloads
       def sanitize(message)
         return message unless message.is_a?(String)
 
-        sanitized = message.dup
-        sanitized = sanitize_authorization_header(sanitized)
-        sanitized = sanitize_json_pairs(sanitized)
-        sanitize_form_and_query_pairs(sanitized)
-      end
-
-      # The initialized thing filter used by this logger.
-      #
-      # This is a per-logger snapshot created during initialization.
-      #
-      # @return [ThingFilter]
-      attr_reader :thing_filter
-
-      # Redact Authorization header values.
-      #
-      # @param [String] message Logger message
-      # @return [String] Sanitized logger message
-      def sanitize_authorization_header(message)
-        message.gsub(/(Authorization:\s*)(?:"[^"]*"|[^\r\n]+)/i, "\\1\"#{thing_filter.label}\"")
-      end
-
-      # Redact JSON-style values for configured sensitive key names.
-      #
-      # @param [String] message Logger message
-      # @return [String] Sanitized logger message
-      def sanitize_json_pairs(message)
-        message.gsub(/(["'])(#{thing_filter.pattern_source})\1(\s*:\s*)(["'])(.*?)\4/i) do
-          %(#{$1}#{$2}#{$1}#{$3}#{$4}#{thing_filter.label}#{$4})
-        end
-      end
-
-      # Redact form-encoded and query-string values for configured sensitive key names.
-      #
-      # @param [String] message Logger message
-      # @return [String] Sanitized logger message
-      def sanitize_form_and_query_pairs(message)
-        message.gsub(/(\b(?:#{thing_filter.pattern_source})=)([^&\s"]+)/i, "\\1#{thing_filter.label}")
+        @value_sanitizer.sanitize(message)
       end
     end
   end

data/lib/auth/sanitizer/thing_filter.rb

@@ -13,8 +13,8 @@ module Auth
     class ThingFilter
       # Create a new filter.
       #
-      # @param [Enumerable<#to_s>] things Names that should be filtered
-      # @param [String] label Replacement label to use for filtered values
+      # @param things [Enumerable<#to_s>] Names that should be filtered
+      # @param label [String] Replacement label to use for filtered values
       #
       # The provided values are duplicated and frozen so the filter remains
       # stable for the lifetime of the object.
@@ -39,7 +39,7 @@ module Auth
       # Matching is substring-based so it works naturally with instance-variable
       # names used by `#inspect`, such as `@secret` matching `secret`.
       #
-      # @param [#to_s] thing_name Candidate thing name
+      # @param thing_name [#to_s] Candidate thing name
       # @return [Boolean]
       def filtered?(thing_name)
         thing_name_str = thing_name.to_s

data/lib/auth/sanitizer/value_sanitizer.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Auth
+  module Sanitizer
+    # Sanitizes arbitrary values using a configured {ThingFilter}.
+    class ValueSanitizer
+      # @param filtered_keys [Array<String>] Sensitive key names
+      # @param label [String] Replacement label
+      def initialize(filtered_keys: Auth::Sanitizer.default_filtered_keys, label: Auth::Sanitizer.filtered_label, **options)
+        @thing_filter = ThingFilter.new(filtered_keys, label: label)
+      end
+
+      # Return a sanitized copy. Matching Hash keys are replaced as well as
+      # their values, so a secret used as a key cannot leak through inspect.
+      #
+      # @param value [Object] Value to sanitize
+      # @return [Object]
+      def sanitize(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested), sanitized|
+            sanitized_key = sanitize(key)
+            sanitized[sanitized_key] = sensitive_key?(key) ? @thing_filter.label : sanitize(nested)
+          end
+        when Array
+          value.map { |nested| sanitize(nested) }
+        when String
+          sanitize_string(value)
+        else
+          value
+        end
+      end
+
+      private
+
+      def sensitive_key?(key)
+        @thing_filter.filtered?(key)
+      end
+
+      def sanitize_string(message)
+        sanitized = message.dup.scrub
+        sanitized = sanitized.gsub(/(Authorization:\s*)(?:"[^"]*"|[^\r\n]+)/i, "\\1\"#{@thing_filter.label}\"")
+        sanitized = sanitized.gsub(/(["'])(#{@thing_filter.pattern_source})\1(\s*:\s*)(["'])(.*?)\4/i) do
+          %(#{$1}#{$2}#{$1}#{$3}#{$4}#{@thing_filter.label}#{$4})
+        end
+        key = @thing_filter.pattern_source
+        label = @thing_filter.label
+        sanitized = sanitized.gsub(/((?:"(?:#{key})"|:#{key})\s*=>\s*")[^"]*(")/i) { "#{$1}#{label}#{$2}" }
+        sanitized = sanitized.gsub(/(?<!["'])((?:\b(?:#{key})):\s*")[^"]*(")/i) { "#{$1}#{label}#{$2}" }
+        sanitized.gsub(/(\b(?:#{key})=)([^&\s">]+)/i, "\\1#{label}")
+      end
+    end
+  end
+end

data/lib/auth/sanitizer/version.rb

@@ -2,9 +2,12 @@
 
 module Auth
   module Sanitizer
+    # Version namespace for this gem.
     module Version
-      VERSION = "0.2.3"
+      # Current gem version.
+      VERSION = "0.2.5"
     end
+    # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location
   end
 end

data/lib/auth/sanitizer.rb

@@ -2,11 +2,12 @@
 
 require "version_gem"
 
-require_relative "sanitizer/version"
 require_relative "sanitizer/thing_filter"
 require_relative "sanitizer/core"
+require_relative "sanitizer/value_sanitizer"
 require_relative "sanitizer/filtered_attributes"
 require_relative "sanitizer/sanitized_logger"
+require_relative "sanitizer/version"
 
 Auth::Sanitizer::Version.class_eval do
   extend VersionGem::Basic

data/lib/auth_sanitizer/loader.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
+# Namespace for the isolated loader surface of the auth-sanitizer gem.
 module AuthSanitizer
   # Loader for consumers that need Auth::Sanitizer without defining a top-level
   # Auth constant in the host application.
   module Loader
+    # Gem source files evaluated into the anonymous namespace, in load order.
     FILES = %w[
       auth/sanitizer/version.rb
       auth/sanitizer/thing_filter.rb
       auth/sanitizer/core.rb
+      auth/sanitizer/value_sanitizer.rb
       auth/sanitizer/filtered_attributes.rb
       auth/sanitizer/sanitized_logger.rb
     ].freeze
@@ -39,6 +42,9 @@ module AuthSanitizer
       # the anonymous Auth namespace. This keeps the normal files unchanged while
       # avoiding Object::Auth leakage on runtimes where Module#module_eval still
       # resolves nested module declarations through Object.
+      #
+      # @param path [String] Absolute path to the gem source file
+      # @return [String] The source with the top-level wrapper removed
       def isolated_source(path)
         lines = File.readlines(path)
         wrapper_index = lines.index("module Auth\n")

data/sig/auth/sanitizer.rbs

@@ -5,3 +5,15 @@ module AuthSanitizer
     def self.load_isolated: () -> Module
   end
 end
+
+module Auth
+  module Sanitizer
+    module Version
+      VERSION: String
+    end
+    VERSION: String
+    def self.default_filtered_keys: () -> Array[String]
+    def self.filtered_label: () -> String
+    def self.sanitize: (untyped value, ?filtered_keys: Array[String], ?label: String, **untyped options) -> untyped
+  end
+end