auth-sanitizer 0.1.0

data/lib/auth/sanitizer/filtered_attributes.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # 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
+    # provider via {Auth::Sanitizer.filtered_label_provider=}.
+    module FilteredAttributes
+      class << self
+        # 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
+        # @return [void]
+        def included(base)
+          base.extend(ClassMethods)
+          base.prepend(InitializerMethods)
+        end
+      end
+
+      # Initializer hook that snapshots the thing filter for this object.
+      #
+      # The snapshot captures both the class-level filtered attribute names and
+      # the current {Auth::Sanitizer.filtered_label} value.
+      module InitializerMethods
+        def initialize(*args, &block)
+          super(*args, &block)
+          @thing_filter = ThingFilter.new(
+            self.class.filtered_attribute_names,
+            label: Auth::Sanitizer.filtered_label,
+          )
+        end
+      end
+
+      # Class-level helpers for configuring filtered attributes.
+      module ClassMethods
+        class << self
+          # Declare attributes that should be redacted in inspect output.
+          #
+          # @param [Array<Symbol, String>] attributes One or more attribute names
+          # @return [void]
+          def filtered_attributes(base, *attributes)
+            base.instance_variable_set(:@filtered_attribute_names, attributes.map(&:to_sym))
+          end
+
+          # The configured attribute names to filter.
+          #
+          # @param [Class] base The class to get filtered attributes for
+          # @return [Array<Symbol>]
+          def filtered_attribute_names(base)
+            return [] unless base.instance_variable_defined?(:@filtered_attribute_names)
+
+            base.instance_variable_get(:@filtered_attribute_names) || []
+          end
+        end
+
+        # 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)
+          ClassMethods.filtered_attributes(self, *attributes)
+        end
+
+        # The configured attribute names to filter.
+        #
+        # @return [Array<Symbol>]
+        def filtered_attribute_names
+          ClassMethods.filtered_attribute_names(self)
+        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
+        return super if thing_filter.things.empty?
+
+        inspected_vars = instance_variables.map do |var|
+          if thing_filter.filtered?(var)
+            "#{var}=#{thing_filter.label}"
+          else
+            "#{var}=#{instance_variable_get(var).inspect}"
+          end
+        end
+        "#<#{self.class}:#{object_id} #{inspected_vars.join(", ")}>"
+      end
+    end
+  end
+end

data/lib/auth/sanitizer/sanitized_logger.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Auth
+  module Sanitizer
+    # 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.
+    #
+    # The underlying {ThingFilter} is initialized once when the logger wrapper is
+    # created, so later config changes do not alter the behavior of existing
+    # logger instances.
+    class SanitizedLogger
+      # Create a new sanitized logger wrapper.
+      #
+      # @param [#add, #debug, #info, #warn, #error, #fatal, #unknown] logger
+      #   The underlying logger instance that will receive sanitized messages.
+      # @param [Array<String>] filtered_keys
+      #   Key names whose values should be redacted in debug output.
+      #   Defaults to {Auth::Sanitizer.default_filtered_keys}.
+      # @param [String] label
+      #   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)
+      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
+      # @yieldreturn [Object] Deferred log message
+      # @return [Object] The underlying logger result
+      def add(severity, message = nil, progname = nil)
+        if block_given?
+          @logger.add(severity, sanitize(message), sanitize(progname)) { sanitize(yield) }
+        else
+          @logger.add(severity, sanitize(message), sanitize(progname))
+        end
+      end
+
+      # Append a message to the underlying logger after sanitization.
+      #
+      # @param [String] message Message to append
+      # @return [Object] The underlying logger result
+      def <<(message)
+        @logger << sanitize(message)
+      end
+
+      # Log a debug message after sanitization.
+      #
+      # @param [Object, nil] progname Optional program name
+      # @yieldreturn [Object] Deferred log message
+      # @return [Object] The underlying logger result
+      def debug(progname = nil, &block)
+        log(:debug, progname, &block)
+      end
+
+      # Log an info message after sanitization.
+      #
+      # @param [Object, nil] progname Optional program name
+      # @yieldreturn [Object] Deferred log message
+      # @return [Object] The underlying logger result
+      def info(progname = nil, &block)
+        log(:info, progname, &block)
+      end
+
+      # Log a warning message after sanitization.
+      #
+      # @param [Object, nil] progname Optional program name
+      # @yieldreturn [Object] Deferred log message
+      # @return [Object] The underlying logger result
+      def warn(progname = nil, &block)
+        log(:warn, progname, &block)
+      end
+
+      # Log an error message after sanitization.
+      #
+      # @param [Object, nil] progname Optional program name
+      # @yieldreturn [Object] Deferred log message
+      # @return [Object] The underlying logger result
+      def error(progname = nil, &block)
+        log(:error, progname, &block)
+      end
+
+      # Log a fatal message after sanitization.
+      #
+      # @param [Object, nil] progname Optional program name
+      # @yieldreturn [Object] Deferred log message
+      # @return [Object] The underlying logger result
+      def fatal(progname = nil, &block)
+        log(:fatal, progname, &block)
+      end
+
+      # Log an unknown-severity message after sanitization.
+      #
+      # @param [Object, nil] progname Optional program name
+      # @yieldreturn [Object] Deferred log message
+      # @return [Object] The underlying logger result
+      def unknown(progname = nil, &block)
+        log(:unknown, progname, &block)
+      end
+
+      # Close the underlying logger if supported.
+      #
+      # @return [void]
+      def close
+        @logger.close if @logger.respond_to?(:close)
+      end
+
+      # Access the formatter of the underlying logger if supported.
+      #
+      # @return [Object, nil]
+      def formatter
+        @logger.formatter if @logger.respond_to?(:formatter)
+      end
+
+      # Set the formatter of the underlying logger if supported.
+      #
+      # @param [Object] formatter Formatter object
+      # @return [void]
+      def formatter=(formatter)
+        @logger.formatter = formatter if @logger.respond_to?(:formatter=)
+      end
+
+      # Access the logger level if supported.
+      #
+      # @return [Object, nil]
+      def level
+        @logger.level if @logger.respond_to?(:level)
+      end
+
+      # Set the logger level if supported.
+      #
+      # @param [Object] level Logger level
+      # @return [void]
+      def level=(level)
+        @logger.level = level if @logger.respond_to?(:level=)
+      end
+
+      # Access the logger progname if supported.
+      #
+      # @return [Object, nil]
+      def progname
+        @logger.progname if @logger.respond_to?(:progname)
+      end
+
+      # Set the logger progname if supported.
+      #
+      # @param [Object] progname Logger progname
+      # @return [void]
+      def progname=(progname)
+        @logger.progname = progname if @logger.respond_to?(:progname=)
+      end
+
+      # 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
+      # @return [Boolean]
+      def respond_to_missing?(method_name, include_private = false)
+        @logger.respond_to?(method_name, include_private) || super
+      end
+
+      # Delegate unsupported methods to the wrapped logger.
+      #
+      # @param [Symbol] method_name Method to invoke
+      # @param [Array<Object>] args Method arguments
+      # @yield Deferred block forwarded to the wrapped logger
+      # @return [Object] The delegated result
+      def method_missing(method_name, *args, &block)
+        return super unless @logger.respond_to?(method_name)
+
+        @logger.public_send(method_name, *args, &block)
+      end
+
+      private
+
+      # Dispatch a severity-specific log call after sanitization.
+      #
+      # @param [Symbol] level Logger method name
+      # @param [Object, nil] progname Optional program name
+      # @yieldreturn [Object] Deferred log message
+      # @return [Object] The underlying logger result
+      def log(level, progname = nil)
+        if block_given?
+          @logger.public_send(level, sanitize(progname)) { sanitize(yield) }
+        else
+          @logger.public_send(level, sanitize(progname))
+        end
+      end
+
+      # Sanitize a logger message when it is a String.
+      #
+      # @param [Object] message 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}")
+      end
+    end
+  end
+end

data/lib/auth/sanitizer/thing_filter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Auth
+  module Sanitizer
+    # Small value object for matching and filtering named things.
+    #
+    # Used by multiple filtering surfaces in the library, such as inspected
+    # object attributes and debug-log key filtering.
+    #
+    # `ThingFilter` snapshots and duplicates its inputs on initialization so later
+    # mutation of caller-owned arrays or strings does not affect existing filter
+    # instances.
+    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
+      #
+      # The provided values are duplicated and frozen so the filter remains
+      # stable for the lifetime of the object.
+      def initialize(things, label:)
+        @things = Array(things).map { |thing| thing.to_s.dup.freeze }.freeze
+        @label = label.to_s.dup.freeze
+        @pattern_source = Regexp.union(@things).source.freeze
+      end
+
+      # The configured names that should be filtered.
+      #
+      # @return [Array<String>]
+      attr_reader :things
+
+      # The configured replacement label.
+      #
+      # @return [String]
+      attr_reader :label
+
+      # True when the provided name matches any configured filter entry.
+      #
+      # 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
+      # @return [Boolean]
+      def filtered?(thing_name)
+        thing_name_str = thing_name.to_s
+        things.any? { |thing| thing_name_str.include?(thing) }
+      end
+
+      # Build a regular-expression source for the configured thing names.
+      #
+      # Useful when a filtering surface needs regex-based replacement rather than
+      # direct name checks.
+      #
+      # @return [String]
+      attr_reader :pattern_source
+    end
+  end
+end

data/lib/auth/sanitizer/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Auth
+  module Sanitizer
+    module Version
+      VERSION = "0.1.0"
+    end
+    VERSION = Version::VERSION # Traditional Constant Location
+  end
+end

data/lib/auth/sanitizer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "version_gem"
+require_relative "sanitizer/version"
+require_relative "sanitizer/thing_filter"
+require_relative "sanitizer/filtered_attributes"
+require_relative "sanitizer/sanitized_logger"
+
+Auth::Sanitizer::Version.class_eval do
+  extend VersionGem::Basic
+end
+
+module Auth
+  module Sanitizer
+    class Error < StandardError; end
+
+    # Default keys filtered from debug log output.
+    DEFAULT_FILTERED_KEYS = %w[
+      access_token
+      refresh_token
+      id_token
+      client_secret
+      assertion
+      code_verifier
+      token
+    ].freeze
+
+    # Default replacement label for redacted values.
+    DEFAULT_FILTERED_LABEL = "[FILTERED]"
+
+    # Default callable used to provide the filtered replacement label.
+    DEFAULT_FILTERED_LABEL_PROVIDER = -> { DEFAULT_FILTERED_LABEL }
+
+    filtered_label_provider = DEFAULT_FILTERED_LABEL_PROVIDER
+    filtered_label_provider_mutex = Mutex.new
+
+    # Returns the current filtered label by calling the installed provider.
+    #
+    # Host gems may install a provider that reads from their own config by
+    # calling {filtered_label_provider=}.
+    #
+    # @return [String]
+    define_singleton_method(:filtered_label) do
+      filtered_label_provider_mutex.synchronize { filtered_label_provider }.call
+    end
+
+    # Install a custom provider for the filtered label.
+    #
+    # The provider is called each time a new {FilteredAttributes}- or
+    # {SanitizedLogger}-bearing object is initialized, allowing the label to
+    # track a host gem's live configuration while still being snapshotted per
+    # object instance.
+    #
+    # @example Delegate to a host gem's config
+    #   Auth::Sanitizer.filtered_label_provider = -> { MyGem.config[:filtered_label] }
+    #
+    # @param [#call] provider A callable that returns the label string
+    # @return [void]
+    define_singleton_method(:filtered_label_provider=) do |provider|
+      filtered_label_provider_mutex.synchronize do
+        filtered_label_provider = provider
+      end
+    end
+
+    class << self
+      # Returns the default set of key names filtered from debug log output.
+      #
+      # Host gems may override this by passing `filtered_keys:` directly to
+      # {SanitizedLogger#initialize}.
+      #
+      # @return [Array<String>]
+      def default_filtered_keys
+        DEFAULT_FILTERED_KEYS
+      end
+    end
+  end
+end

data/sig/auth/sanitizer.rbs

@@ -0,0 +1,6 @@
+module Auth
+  module Sanitizer
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

data.tar.gz.sig

@@ -0,0 +1 @@
+rlV�w����|�S6���[={ۿ��-Y��^�rv�ql�pT�ګ����k��b��%j�k�U�LY��NF�'�
�N(�my/�Z�����U�F�f7/*à�J����n�hH_���3#Н�Xf��� (��}���/f-d��FG�u<��L�&�M ��x2�&V[>6#��ǭf<�kG̲m�k�P�q’�ڴtz&�|�1}@?<�&�ی�/iM�����+��7l�_���D:6��̄����B9�r�Xi+�~�Gl��7A̡^Cޢm[��{�o:J�.�x �|��ȟ��^�gq|]ܤ�E��'ا�0Nh1:#P#dBѨ�9�r���mٴ��l��g��:��L$�B���,AvU���G����"�A_�EGв�6