auth-sanitizer 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a459f96a2569fc0a45f1f0fcc919d6324f64902e4ed7364a617aebed42b6936a
-  data.tar.gz: 7e27c3b29c2f47b0afcf740098f14472f3f936828df479e4a3e808d8259523ad
+  metadata.gz: fe6ea000d97d7116cf66f7a69b7c8f7d4ea7dc6e1dbdc7df6f073a79841c8513
+  data.tar.gz: 77955bc562916c9de289b05111325bcc5b42d40633747f241e5c33a82d99ad1a
 SHA512:
-  metadata.gz: 86ea9c3a4721881b599ba6e63a50cc0d9f4b5a9d5c8dbe1c7bd140ce802c4d28d1df0278b4f16aee472c7feabe34e30c6d16dc5943c12a4c6a9a429519de9e82
-  data.tar.gz: 381e1f25c5bd0301f3d1ba91f6f20a6370e6d6158a87270f166e85a84abc556dc865b0c1a2f8d449ba7b08b82ad34b8c4589601bb8ff09bfc72c96c4ef14b2e0
+  metadata.gz: 31f37a6ccaa844c1de2b88e0f80b3bf361dd73be273dd1a7825464c5c1f1b9a80a7740e75e8a4654e1ba036a8e1d4597aa527f6b853306cf605d2bf99312618a
+  data.tar.gz: a6317b6c5419c44f15be4d53c858d54a233b892f9f0a52324d8620e1d2037d1494190cebcab91d44ba223805b35326cdc563d5b2d1bdbe39c422b35df6d3f33a

data/CHANGELOG.md

@@ -30,6 +30,18 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.1.3] - 2026-05-20
+
+- TAG: [v0.1.3][0.1.3t]
+- COVERAGE: 100.00% -- 135/135 lines in 6 files
+- BRANCH COVERAGE: 100.00% -- 28/28 branches in 6 files
+- 84.62% documented
+
+### Added
+
+- Add `AuthSanitizer::Loader.load_isolated` for isolated loading without defining top-level `Auth`
+- Document zero-top-level-namespace loading for consumers that need to avoid defining `Auth` or `AuthSanitizer`
+
 ## [0.1.2] - 2026-05-15
 
 - TAG: [v0.1.2][0.1.2t]
@@ -67,7 +79,9 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com//ruby-oauth/auth-sanitizer/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com//ruby-oauth/auth-sanitizer/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com//ruby-oauth/auth-sanitizer/compare/v0.1.2...v0.1.3
+[0.1.3t]: https://github.com//ruby-oauth/auth-sanitizer/releases/tag/v0.1.3
 [0.1.2]: https://github.com//ruby-oauth/auth-sanitizer/compare/v0.1.1...v0.1.2
 [0.1.2t]: https://github.com//ruby-oauth/auth-sanitizer/releases/tag/v0.1.2
 [0.1.1]: https://github.com//ruby-oauth/auth-sanitizer/compare/v0.1.0...v0.1.1

data/README.md

@@ -58,6 +58,25 @@ a provider, or per logger by passing `label:` to `Auth::Sanitizer::SanitizedLogg
 The library snapshots filter configuration when a redacting object is initialized. That keeps already-created objects
 and logger wrappers stable even if a host application changes its configuration later.
 
+Consumers that need to avoid defining the generic top-level `Auth` namespace can use the isolated loader:
+
+```ruby
+require "auth_sanitizer/loader"
+
+AUTH_SANITIZER = AuthSanitizer::Loader.load_isolated
+```
+
+The returned module is an anonymously namespaced `Auth::Sanitizer`, suitable for internal assignment in host gems.
+Use `require: false` in gems that want to avoid every new top-level namespace, including `AuthSanitizer`; see
+[Zero Top-Level Namespace Additions](#zero-top-level-namespace-additions).
+
+This gem is used by the following libraries to ensure clean output:
+
+- oauth
+- oauth-tty
+- oauth2
+- omniauth-ldap
+
 ## 💡 Info you can shake a stick at
 
 | Tokens to Remember      | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace]                                                                                                                                                                                                                                                                          |
@@ -176,6 +195,107 @@ NOTE: Be prepared to track down certs for signed gems and add them the same way
 Most applications can use the defaults. Configuration is available when a host gem or application wants to align
 redaction with its own logging conventions.
 
+### Loading Mode
+
+This gem has two supported loading modes.
+
+The direct API defines the top-level `Auth` namespace:
+
+```ruby
+require "auth/sanitizer"
+
+class TokenResponse
+  include Auth::Sanitizer::FilteredAttributes
+end
+```
+
+This is convenient for applications that already own or intentionally use `Auth`.
+
+Libraries and applications that need to avoid the generic top-level `Auth` namespace should use the isolated loader:
+
+```ruby
+require "auth_sanitizer/loader"
+
+AUTH_SANITIZER = AuthSanitizer::Loader.load_isolated
+
+class TokenResponse
+  include AUTH_SANITIZER::FilteredAttributes
+end
+```
+
+`AuthSanitizer::Loader.load_isolated` evaluates the sanitizer implementation inside an anonymous module and returns that
+module's `Auth::Sanitizer` constant. Assign the returned module to a constant owned by your library or application, then
+include from that constant.
+
+When declaring the dependency in a Gemfile, prefer one of these explicit forms:
+
+```ruby
+gem "auth-sanitizer", require: false
+```
+
+or:
+
+```ruby
+gem "auth-sanitizer", require: "auth_sanitizer/loader"
+```
+
+Use `require: false` when the consuming library will decide which loading mode to use internally. Use
+`require: "auth_sanitizer/loader"` when Bundler should make the isolated loader available during `Bundler.require`.
+
+#### Zero Top-Level Namespace Additions
+
+A gem that needs zero new top-level namespaces from this dependency can load the loader itself inside an anonymous
+namespace. On Ruby 3.1+, use `Kernel.load(path, module)`:
+
+```ruby
+auth_sanitizer_spec = Gem.loaded_specs["auth-sanitizer"] ||
+  Gem::Specification.find_by_name("auth-sanitizer")
+auth_sanitizer_loader_path = File.join(
+  auth_sanitizer_spec.full_gem_path,
+  "lib/auth_sanitizer/loader.rb",
+)
+
+auth_sanitizer_loader_namespace = Module.new
+Kernel.load(auth_sanitizer_loader_path, auth_sanitizer_loader_namespace)
+
+AUTH_SANITIZER = auth_sanitizer_loader_namespace
+  .const_get(:AuthSanitizer)
+  .const_get(:Loader)
+  .load_isolated
+```
+
+That pattern leaves both `Auth` and `AuthSanitizer` undefined at top level. The consuming gem should assign the returned
+module under its own namespace and use that internal constant.
+
+<details markdown="1">
+  <summary>Ruby 2.2-compatible zero-top-level loading</summary>
+
+Ruby 2.2 through Ruby 3.0 do not support `Kernel.load(path, module)`. For those versions, evaluate the loader source
+inside an anonymous namespace with `Module#module_eval`:
+
+```ruby
+auth_sanitizer_spec = Gem.loaded_specs["auth-sanitizer"] ||
+  Gem::Specification.find_by_name("auth-sanitizer")
+auth_sanitizer_loader_path = File.join(
+  auth_sanitizer_spec.full_gem_path,
+  "lib/auth_sanitizer/loader.rb",
+)
+
+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 = auth_sanitizer_loader_namespace
+  .const_get(:AuthSanitizer)
+  .const_get(:Loader)
+  .load_isolated
+```
+
+</details>
+
 ### Filtered Label
 
 The default replacement label is:
@@ -293,6 +413,19 @@ Require the gem:
 require "auth/sanitizer"
 ```
 
+Or load it without defining top-level `Auth`. This still defines top-level `AuthSanitizer`; see
+[Zero Top-Level Namespace Additions](#zero-top-level-namespace-additions) for the stricter loading pattern.
+
+```ruby
+require "auth_sanitizer/loader"
+
+AUTH_SANITIZER = AuthSanitizer::Loader.load_isolated
+
+class TokenResponse
+  include AUTH_SANITIZER::FilteredAttributes
+end
+```
+
 ### Redact `#inspect`
 
 Use `Auth::Sanitizer::FilteredAttributes` for objects that may appear in exception messages, console sessions, or debug
@@ -767,7 +900,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.134-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.135-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/REEK

@@ -1,2 +1,2 @@
-Error: No such file - is
-Error: No such file - empty
+./reek: 1: Error:: not found
+./reek: 2: Error:: not found

data/lib/auth/sanitizer/core.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "version_gem"
+
+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/lib/auth/sanitizer/version.rb

@@ -3,7 +3,7 @@
 module Auth
   module Sanitizer
     module Version
-      VERSION = "0.1.2"
+      VERSION = "0.1.3"
     end
     VERSION = Version::VERSION # Traditional Constant Location
   end

data/lib/auth/sanitizer.rb

@@ -1,77 +1,7 @@
 # frozen_string_literal: true
 
-require "version_gem"
 require_relative "sanitizer/version"
 require_relative "sanitizer/thing_filter"
+require_relative "sanitizer/core"
 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/lib/auth_sanitizer/loader.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module AuthSanitizer
+  # Loader for consumers that need Auth::Sanitizer without defining a top-level
+  # Auth constant in the host application.
+  module Loader
+    FILES = %w[
+      auth/sanitizer/version.rb
+      auth/sanitizer/thing_filter.rb
+      auth/sanitizer/core.rb
+      auth/sanitizer/filtered_attributes.rb
+      auth/sanitizer/sanitized_logger.rb
+    ].freeze
+
+    class << self
+      # Load Auth::Sanitizer into an anonymous namespace and return the
+      # nested Auth::Sanitizer module from that namespace.
+      #
+      # This uses Module#module_eval with explicit file and line metadata so it
+      # works on Ruby 2.2+, where Kernel.load(path, module) is unavailable.
+      #
+      # @return [Module] isolated Auth::Sanitizer module
+      def load_isolated
+        namespace = Module.new
+        FILES.each do |relative_path|
+          path = File.expand_path("../#{relative_path}", __dir__)
+          namespace.module_eval(File.read(path), path, 1)
+        end
+        namespace.const_get(:Auth).const_get(:Sanitizer)
+      end
+    end
+  end
+end

data/sig/auth/sanitizer.rbs

@@ -4,3 +4,11 @@ module Auth
     # See the writing guide of rbs: https://github.com/ruby/rbs#guides
   end
 end
+
+module AuthSanitizer
+  module Loader
+    FILES: Array[String]
+
+    def self.load_isolated: () -> Module
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: auth-sanitizer
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Peter H. Boling
@@ -239,20 +239,22 @@ files:
 - RUBOCOP.md
 - SECURITY.md
 - lib/auth/sanitizer.rb
+- lib/auth/sanitizer/core.rb
 - lib/auth/sanitizer/filtered_attributes.rb
 - lib/auth/sanitizer/sanitized_logger.rb
 - lib/auth/sanitizer/thing_filter.rb
 - lib/auth/sanitizer/version.rb
+- lib/auth_sanitizer/loader.rb
 - sig/auth/sanitizer.rbs
 homepage: https://github.com/ruby-oauth/auth-sanitizer
 licenses:
 - MIT
 metadata:
   homepage_uri: https://auth-sanitizer.galtzo.com/
-  source_code_uri: https://github.com/ruby-oauth/auth-sanitizer/tree/v0.1.2
-  changelog_uri: https://github.com/ruby-oauth/auth-sanitizer/blob/v0.1.2/CHANGELOG.md
+  source_code_uri: https://github.com/ruby-oauth/auth-sanitizer/tree/v0.1.3
+  changelog_uri: https://github.com/ruby-oauth/auth-sanitizer/blob/v0.1.3/CHANGELOG.md
   bug_tracker_uri: https://github.com/ruby-oauth/auth-sanitizer/issues
-  documentation_uri: https://www.rubydoc.info/gems/auth-sanitizer/0.1.2
+  documentation_uri: https://www.rubydoc.info/gems/auth-sanitizer/0.1.3
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/ruby-oauth/auth-sanitizer/wiki
   news_uri: https://www.railsbling.com/tags/auth-sanitizer