auth-sanitizer 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48345c9c15c3bcfefec251d9258d1a949ce27ed13f46a23c1458efffa1a20ebe
-  data.tar.gz: 55a0935c3ac081f62bf9767f3a1157911dbf5fae71e5f7c669954d3dfeffd842
+  metadata.gz: a459f96a2569fc0a45f1f0fcc919d6324f64902e4ed7364a617aebed42b6936a
+  data.tar.gz: 7e27c3b29c2f47b0afcf740098f14472f3f936828df479e4a3e808d8259523ad
 SHA512:
-  metadata.gz: fa2206c9f38364d722d6ddc5cb1d52d626c57f37ee681f4c3dd745b3add67720435f8507033eb9fd6d765532b791723946282ed3fa1da70521df53d86300318e
-  data.tar.gz: 54a1aaa99bf99ffa69079bf000fbc9ab3b995bfda620eb797f488fefd83fa26f1854bd89428ad91ae25d0cc2c3bd38add165002d2833391d2541dead0bd199a6
+  metadata.gz: 86ea9c3a4721881b599ba6e63a50cc0d9f4b5a9d5c8dbe1c7bd140ce802c4d28d1df0278b4f16aee472c7feabe34e30c6d16dc5943c12a4c6a9a429519de9e82
+  data.tar.gz: 381e1f25c5bd0301f3d1ba91f6f20a6370e6d6158a87270f166e85a84abc556dc865b0c1a2f8d449ba7b08b82ad34b8c4589601bb8ff09bfc72c96c4ef14b2e0

data/CHANGELOG.md

@@ -30,6 +30,32 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.1.2] - 2026-05-15
+
+- TAG: [v0.1.2][0.1.2t]
+- COVERAGE: 100.00% -- 134/134 lines in 5 files
+- BRANCH COVERAGE: 100.00% -- 28/28 branches in 5 files
+- 87.50% documented
+
+### Added
+
+- gemspec description, summary
+
+### Changed
+
+- gemspec contact email
+
+## [0.1.1] - 2026-05-15
+
+- TAG: [v0.1.1][0.1.1t]
+- COVERAGE: 100.00% -- 134/134 lines in 5 files
+- BRANCH COVERAGE: 100.00% -- 28/28 branches in 5 files
+- 87.50% documented
+
+### Added
+
+- Usage documentation in README.md
+
 ## [0.1.0] - 2026-05-15
 
 - TAG: [v0.1.0][0.1.0t]
@@ -41,6 +67,10 @@ 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.0...HEAD
+[Unreleased]: https://github.com//ruby-oauth/auth-sanitizer/compare/v0.1.2...HEAD
+[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
+[0.1.1t]: https://github.com//ruby-oauth/auth-sanitizer/releases/tag/v0.1.1
 [0.1.0]: https://github.com/ruby-oauth/auth-sanitizer/compare/21d6165dca7eef8e7b9bb01fdfc4cc8bab4e5b96...v0.1.0
 [0.1.0t]: https://github.com/ruby-oauth/auth-sanitizer/releases/tag/v0.1.0

data/README.md

@@ -7,7 +7,7 @@
 [🖼️oauth2-i]: https://logos.galtzo.com/assets/images/oauth/oauth2/avatar-192px.svg
 [🖼️oauth2]: https://github.com/ruby-oauth/oauth2
 
-# 🍲 Auth::Sanitizer
+# 🟥 Auth::Sanitizer
 
 [![Version][👽versioni]][👽version] [![GitHub tag (latest SemVer)][⛳️tag-img]][⛳️tag] [![License: MIT][📄license-img]][📄license-ref] [![Downloads Rank][👽dl-ranki]][👽dl-rank] [![CodeCov Test Coverage][🏀codecovi]][🏀codecov] [![Coveralls Test Coverage][🏀coveralls-img]][🏀coveralls] [![QLTY Test Coverage][🏀qlty-covi]][🏀qlty-cov] [![QLTY Maintainability][🏀qlty-mnti]][🏀qlty-mnt] [![CI Heads][🚎3-hd-wfi]][🚎3-hd-wf] [![CI Runtime Dependencies @ HEAD][🚎12-crh-wfi]][🚎12-crh-wf] [![CI Current][🚎11-c-wfi]][🚎11-c-wf] [![CI Truffle Ruby][🚎9-t-wfi]][🚎9-t-wf] [![CI JRuby][🚎10-j-wfi]][🚎10-j-wf] [![Deps Locked][🚎13-🔒️-wfi]][🚎13-🔒️-wf] [![Deps Unlocked][🚎14-🔓️-wfi]][🚎14-🔓️-wf] [![CI Test Coverage][🚎2-cov-wfi]][🚎2-cov-wf] [![CI Style][🚎5-st-wfi]][🚎5-st-wf] [![CodeQL][🖐codeQL-img]][🖐codeQL] [![Apache SkyWalking Eyes License Compatibility Check][🚎15-🪪-wfi]][🚎15-🪪-wf]
 
@@ -28,6 +28,36 @@ I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-ta
 
 ## 🌻 Synopsis
 
+`auth-sanitizer` provides small, dependency-light helpers for keeping OAuth and authentication secrets out of object
+inspection and log output.
+
+The gem is intentionally narrow in scope. It does not change HTTP requests, token objects, persistence, or application
+configuration for you. Instead, it gives host gems and applications two reusable redaction surfaces:
+
+- `Auth::Sanitizer::FilteredAttributes` redacts selected instance variables from `#inspect`.
+- `Auth::Sanitizer::SanitizedLogger` wraps an existing logger and redacts sensitive values from string log messages.
+
+Out of the box, logger sanitization filters the key names most commonly found in OAuth and OpenID Connect debug output:
+
+```ruby
+Auth::Sanitizer.default_filtered_keys
+# => [
+#      "access_token",
+#      "refresh_token",
+#      "id_token",
+#      "client_secret",
+#      "assertion",
+#      "code_verifier",
+#      "token",
+#    ]
+```
+
+Redacted values are replaced with `"[FILTERED]"` by default. The replacement label can be changed globally by installing
+a provider, or per logger by passing `label:` to `Auth::Sanitizer::SanitizedLogger.new`.
+
+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.
+
 ## 💡 Info you can shake a stick at
 
 | Tokens to Remember      | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace]                                                                                                                                                                                                                                                                          |
@@ -143,8 +173,235 @@ NOTE: Be prepared to track down certs for signed gems and add them the same way
 
 ## ⚙️ Configuration
 
+Most applications can use the defaults. Configuration is available when a host gem or application wants to align
+redaction with its own logging conventions.
+
+### Filtered Label
+
+The default replacement label is:
+
+```ruby
+Auth::Sanitizer.filtered_label
+# => "[FILTERED]"
+```
+
+To use a different label globally, install a callable provider:
+
+```ruby
+Auth::Sanitizer.filtered_label_provider = -> { "[REDACTED]" }
+```
+
+The provider is called when a `FilteredAttributes` object or `SanitizedLogger` wrapper is initialized. Existing
+instances keep the label they captured at initialization time:
+
+```ruby
+Auth::Sanitizer.filtered_label_provider = -> { "[FILTERED]" }
+logger = Auth::Sanitizer::SanitizedLogger.new(Logger.new($stdout))
+
+Auth::Sanitizer.filtered_label_provider = -> { "[REDACTED]" }
+
+# `logger` still uses "[FILTERED]"; new wrappers use "[REDACTED]".
+```
+
+This makes it safe for libraries to delegate the label to host configuration:
+
+```ruby
+Auth::Sanitizer.filtered_label_provider = -> { MyGem.config.filtered_label }
+```
+
+### Logger Keys
+
+`Auth::Sanitizer::SanitizedLogger` defaults to `Auth::Sanitizer.default_filtered_keys`. Pass `filtered_keys:` when your
+application logs additional sensitive fields:
+
+```ruby
+logger = Auth::Sanitizer::SanitizedLogger.new(
+  Logger.new($stdout),
+  filtered_keys: Auth::Sanitizer.default_filtered_keys + %w[
+    api_key
+    private_key
+    session_secret
+  ],
+)
+```
+
+You can also replace the list entirely:
+
+```ruby
+logger = Auth::Sanitizer::SanitizedLogger.new(
+  Logger.new($stdout),
+  filtered_keys: %w[my_secret],
+  label: "[GONE]",
+)
+```
+
+Logger key matching is case-insensitive for supported string formats. The keys are used to redact:
+
+- JSON-style pairs, such as `"access_token": "abc123"` and `'client_secret': 'abc123'`
+- query-string and form-encoded pairs, such as `access_token=abc123&scope=read`
+- `Authorization:` header values, regardless of `filtered_keys`
+
+Only string payloads are sanitized. Non-string log payloads are delegated unchanged to the wrapped logger.
+
+### Inspect Attributes
+
+Classes opt in to inspect redaction by including `Auth::Sanitizer::FilteredAttributes` and declaring the attribute names
+that should be hidden:
+
+```ruby
+class OAuthCredential
+  include Auth::Sanitizer::FilteredAttributes
+
+  attr_reader :access_token, :expires_at
+
+  filtered_attributes :access_token
+
+  def initialize(access_token, expires_at)
+    @access_token = access_token
+    @expires_at = expires_at
+  end
+end
+```
+
+Declared names are matched against instance variable names. For example, `filtered_attributes :access_token` redacts
+`@access_token` in `#inspect`.
+
+Calling `filtered_attributes` again replaces the class-level list:
+
+```ruby
+OAuthCredential.filtered_attributes(:access_token, :refresh_token)
+OAuthCredential.filtered_attribute_names
+# => [:access_token, :refresh_token]
+```
+
+Passing no attributes clears the class-level list for subsequently initialized objects:
+
+```ruby
+OAuthCredential.filtered_attributes
+OAuthCredential.filtered_attribute_names
+# => []
+```
+
+As with logger wrappers, the per-object filter is captured during initialization. Objects that already exist keep their
+original inspect behavior.
+
 ## 🔧 Basic Usage
 
+Require the gem:
+
+```ruby
+require "auth/sanitizer"
+```
+
+### Redact `#inspect`
+
+Use `Auth::Sanitizer::FilteredAttributes` for objects that may appear in exception messages, console sessions, or debug
+output through `#inspect`:
+
+```ruby
+class TokenResponse
+  include Auth::Sanitizer::FilteredAttributes
+
+  attr_reader :access_token, :refresh_token, :scope
+
+  filtered_attributes :access_token, :refresh_token
+
+  def initialize(access_token:, refresh_token:, scope:)
+    @access_token = access_token
+    @refresh_token = refresh_token
+    @scope = scope
+  end
+end
+
+response = TokenResponse.new(
+  access_token: "access-token-value",
+  refresh_token: "refresh-token-value",
+  scope: "profile email",
+)
+
+response.inspect
+# => #<TokenResponse:123456 @access_token=[FILTERED], @refresh_token=[FILTERED], @scope="profile email">
+```
+
+Only the configured attributes are redacted. Other instance variables remain visible so inspected objects are still
+useful while debugging.
+
+### Redact Logger Output
+
+Wrap an existing logger with `Auth::Sanitizer::SanitizedLogger`:
+
+```ruby
+require "logger"
+require "auth/sanitizer"
+
+logger = Auth::Sanitizer::SanitizedLogger.new(Logger.new($stdout))
+
+logger.debug("access_token=abc123&scope=profile")
+# Logs: access_token=[FILTERED]&scope=profile
+
+logger.debug('{"client_secret": "super-secret", "grant_type": "client_credentials"}')
+# Logs: {"client_secret": "[FILTERED]", "grant_type": "client_credentials"}
+
+logger.debug("Authorization: Bearer abc123")
+# Logs: Authorization: "[FILTERED]"
+```
+
+The wrapper implements the common Ruby logger methods and sanitizes string values passed through them:
+
+```ruby
+logger.add(Logger::DEBUG, "refresh_token=abc123", "oauth")
+logger << "id_token=abc123"
+
+logger.debug { "code_verifier=abc123" }
+logger.info("token=abc123")
+logger.warn("client_secret=abc123")
+logger.error("assertion=abc123")
+logger.fatal("Authorization: Bearer abc123")
+logger.unknown("access_token=abc123")
+```
+
+The wrapper also delegates common logger configuration to the wrapped logger when supported:
+
+```ruby
+logger.level = Logger::WARN
+logger.progname = "my-app"
+logger.formatter = proc { |_severity, _time, _progname, message| "#{message}\n" }
+logger.close
+```
+
+Methods not implemented by the wrapper are delegated to the underlying logger when that logger responds to them.
+
+### Custom Logger Keys
+
+Use `filtered_keys:` for application-specific secrets:
+
+```ruby
+logger = Auth::Sanitizer::SanitizedLogger.new(
+  Logger.new($stdout),
+  filtered_keys: %w[access_token api_key signing_secret],
+  label: "[SECRET]",
+)
+
+logger.debug("api_key=12345&access_token=abc123")
+# Logs: api_key=[SECRET]&access_token=[SECRET]
+```
+
+`filtered_keys:` applies to JSON-style, query-string, and form-encoded key/value pairs. `Authorization:` headers are
+always redacted by `SanitizedLogger`, even if `Authorization` is not listed as a filtered key.
+
+### Important Limits
+
+`auth-sanitizer` is a logging and inspection helper, not a complete secret-management system.
+
+- It redacts supported string patterns before delegating to a logger.
+- It does not mutate source hashes, token objects, HTTP requests, or HTTP responses.
+- It does not recursively sanitize arbitrary Ruby objects passed to a logger as non-string payloads.
+- It cannot protect secrets that are logged through a different logger, printed directly, or interpolated into an
+  unsupported format.
+
+For best results, wrap the logger as close as possible to the code that emits authentication debug output, and avoid
+logging raw token structures unless they pass through the sanitizer first.
+
 ## 🦷 FLOSS Funding
 
 While ruby-oauth tools are free software and will always be, the project would benefit immensely from some funding.

data/lib/auth/sanitizer/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: auth-sanitizer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Peter H. Boling
@@ -213,9 +213,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.0.3
-description: "\U0001F372 TODO: Write a longer description or delete this line."
+description: "\U0001F7E5 Configurable KV output redaction. Sanitize/filter your secrets."
 email:
-- peter.boling@gmail.com
+- floss@galtzo.com
 executables: []
 extensions: []
 extra_rdoc_files:
@@ -249,10 +249,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://auth-sanitizer.galtzo.com/
-  source_code_uri: https://github.com/ruby-oauth/auth-sanitizer/tree/v0.1.0
-  changelog_uri: https://github.com/ruby-oauth/auth-sanitizer/blob/v0.1.0/CHANGELOG.md
+  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
   bug_tracker_uri: https://github.com/ruby-oauth/auth-sanitizer/issues
-  documentation_uri: https://www.rubydoc.info/gems/auth-sanitizer/0.1.0
+  documentation_uri: https://www.rubydoc.info/gems/auth-sanitizer/0.1.2
   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
@@ -260,8 +260,7 @@ metadata:
   rubygems_mfa_required: 'true'
 rdoc_options:
 - "--title"
-- "auth-sanitizer - \U0001F372 TODO: Write a short summary, because RubyGems requires
-  one."
+- "auth-sanitizer - \U0001F7E5 Configurable KV output redaction"
 - "--main"
 - README.md
 - "--exclude"
@@ -284,5 +283,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.11
 specification_version: 4
-summary: "\U0001F372 TODO: Write a short summary, because RubyGems requires one."
+summary: "\U0001F7E5 Configurable KV output redaction"
 test_files: []