oauth2 2.0.17 → 2.0.19

data/REEK

@@ -0,0 +1,2 @@
+./reek: 1: Error:: not found
+./reek: 2: Error:: not found

data/SECURITY.md

@@ -12,6 +12,8 @@ To report a security vulnerability, please use the
 [Tidelift security contact](https://tidelift.com/security).
 Tidelift will coordinate the fix and disclosure.
 
+More detailed explanation of the process is in [IRP.md][IRP].
+
 ## Additional Support
 
 If you are interested in support for versions older than the latest release,
@@ -19,3 +21,4 @@ please consider sponsoring the project / maintainer @ https://liberapay.com/pbol
 or find other sponsorship links in the [README].
 
 [README]: README.md
+[IRP]: IRP.md

data/THREAT_MODEL.md

@@ -0,0 +1,94 @@
+# Threat Model Outline for oauth2 Ruby Gem
+
+## 1. Overview
+This document outlines the threat model for the `oauth2` Ruby gem, which implements OAuth 2.0, 2.1, and OIDC Core protocols. The gem is used to facilitate secure authorization and authentication in Ruby applications.
+
+## 2. Assets to Protect
+- OAuth access tokens, refresh tokens, and ID tokens
+- User credentials (if handled)
+- Client secrets and application credentials
+- Sensitive user data accessed via OAuth
+- Private keys and certificates (for signing/verifying tokens)
+
+## 3. Potential Threat Actors
+- External attackers (internet-based)
+- Malicious OAuth clients or resource servers
+- Insiders (developers, maintainers)
+- Compromised dependencies
+
+## 4. Attack Surfaces
+- OAuth endpoints (authorization, token, revocation, introspection)
+- HTTP request/response handling
+- Token storage and management
+- Configuration files and environment variables
+- Dependency supply chain
+
+## 5. Threats and Mitigations
+
+### 5.1 Token Leakage
+- **Threat:** Tokens exposed via logs, URLs, or insecure storage
+- **Mitigations:**
+  - Avoid logging sensitive tokens
+  - Use secure storage mechanisms
+  - Never expose tokens in URLs
+
+### 5.2 Token Replay and Forgery
+- **Threat:** Attackers reuse or forge tokens
+- **Mitigations:**
+  - Validate token signatures and claims
+  - Use short-lived tokens and refresh tokens
+  - Implement token revocation
+
+### 5.3 Insecure Communication
+- **Threat:** Data intercepted via MITM attacks
+- **Mitigations:**
+  - Enforce HTTPS for all communications
+  - Validate SSL/TLS certificates
+
+### 5.4 Client Secret Exposure
+- **Threat:** Client secrets leaked in code or version control
+- **Mitigations:**
+  - Store secrets in environment variables or secure vaults
+  - Never commit secrets to source control
+
+### 5.5 Dependency Vulnerabilities
+- **Threat:** Vulnerabilities in third-party libraries
+- **Mitigations:**
+  - Regularly update dependencies
+  - Use tools like `bundler-audit` for vulnerability scanning
+
+### 5.6 Improper Input Validation
+- **Threat:** Injection attacks via untrusted input
+- **Mitigations:**
+  - Validate and sanitize all inputs
+  - Use parameterized queries and safe APIs
+
+### 5.7 Request-Target Trust Boundary Expansion
+- **Threat:** Applications may pass untrusted or insufficiently validated absolute URLs into request paths that can carry OAuth credentials or authenticated state.
+- **Risk:** This can expand trust boundaries, contributing to token leakage, authenticated requests to unintended hosts, or SSRF-like pivoting in the surrounding application.
+- **Mitigations:**
+  - Prefer relative paths where practical
+  - Do not pass untrusted absolute URLs into token-bearing clients
+  - Validate or allowlist outbound request targets at the application layer
+  - Treat request-target validation as a separate concern from log redaction and token storage
+
+### 5.8 Insufficient Logging and Monitoring
+- **Threat:** Attacks go undetected
+- **Mitigations:**
+  - Log security-relevant events (without sensitive data)
+  - Monitor for suspicious activity
+
+## 6. Assumptions
+- The gem is used in a secure environment with up-to-date Ruby and dependencies
+- End-users are responsible for secure configuration and deployment
+
+## 7. Out of Scope
+- Security of external OAuth providers
+- Application-level business logic
+
+## 8. References
+- [OAuth 2.0 Threat Model and Security Considerations (RFC 6819)](https://tools.ietf.org/html/rfc6819)
+- [OWASP Top Ten](https://owasp.org/www-project-top-ten/)
+
+---
+This outline should be reviewed and updated regularly as the project evolves.

data/lib/oauth2/access_token.rb

@@ -57,26 +57,23 @@ module OAuth2
       def from_hash(client, hash)
         fresh = hash.dup
         # If token_name is present, then use that key name
-        key =
-          if fresh.key?(:token_name)
-            t_key = fresh[:token_name]
-            no_tokens_warning(fresh, t_key)
-            t_key
-          else
-            # Otherwise, if one of the supported default keys is present, use whichever has precedence
-            supported_keys = TOKEN_KEY_LOOKUP & fresh.keys
-            t_key = supported_keys[0]
-            extra_tokens_warning(supported_keys, t_key)
-            t_key
-          end
+        if fresh.key?(:token_name)
+          t_key = fresh[:token_name]
+          no_tokens_warning(fresh, t_key)
+        else
+          # Otherwise, if one of the supported default keys is present, use whichever has precedence
+          supported_keys = TOKEN_KEY_LOOKUP & fresh.keys
+          t_key = supported_keys[0]
+          extra_tokens_warning(supported_keys, t_key)
+        end
         # :nocov:
         # TODO: Get rid of this branching logic when dropping Hashie < v3.2
         token = if !defined?(Hashie::VERSION) # i.e. <= "1.1.0"; the first Hashie to ship with a VERSION constant
           warn("snaky_hash and oauth2 will drop support for Hashie v0 in the next major version. Please upgrade to a modern Hashie.")
           # There is a bug in Hashie v0, which is accounts for.
-          fresh.delete(key) || fresh[key] || ""
+          fresh.delete(t_key) || fresh[t_key] || ""
         else
-          fresh.delete(key) || ""
+          fresh.delete(t_key) || ""
         end
         # :nocov:
         new(client, token, fresh)
@@ -134,7 +131,7 @@ You may need to set `snaky: false`. See inline documentation for more info.
     # @option opts [FixNum, String] :expires_latency (nil) the number of seconds by which AccessToken validity will be reduced to offset latency, @version 2.0+
     # @option opts [Symbol, Hash, or callable] :mode (:header) the transmission mode of the Access Token parameter value:
     #    either one of :header, :body or :query; or a Hash with verb symbols as keys mapping to one of these symbols
-    #    (e.g., {get: :query, post: :header, delete: :header}); or a callable that accepts a request-verb parameter
+    #    (e.g., `{get: :query, post: :header, delete: :header}`); or a callable that accepts a request-verb parameter
     #    and returns one of these three symbols.
     # @option opts [String] :header_format ('Bearer %s') the string format to use for the Authorization header
     #

data/lib/oauth2/authenticator.rb

@@ -51,13 +51,15 @@ module OAuth2
       end
     end
 
-    # Encodes a Basic Authorization header value for the provided credentials.
-    #
-    # @param [String] user The client identifier
-    # @param [String] password The client secret
-    # @return [String] The value to use for the Authorization header
-    def self.encode_basic_auth(user, password)
-      "Basic #{Base64.strict_encode64("#{user}:#{password}")}"
+    class << self
+      # Encodes a Basic Authorization header value for the provided credentials.
+      #
+      # @param [String] user The client identifier
+      # @param [String] password The client secret
+      # @return [String] The value to use for the Authorization header
+      def encode_basic_auth(user, password)
+        "Basic #{Base64.strict_encode64("#{user}:#{password}")}"
+      end
     end
 
   private

data/lib/oauth2/client.rb

@@ -42,7 +42,7 @@ module OAuth2
     # @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 {Auth::Sanitizer::SanitizedLogger} 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,15 @@ module OAuth2
     end
 
     def oauth_debug_logging(builder)
-      builder.response(:logger, options[:logger], bodies: true) if OAuth2::OAUTH_DEBUG
+      builder.response(
+        :logger,
+        Auth::Sanitizer::SanitizedLogger.new(
+          options[:logger],
+          filtered_keys: OAuth2.config[:filtered_debug_keys],
+          label: OAuth2.config[:filtered_label],
+        ),
+        bodies: true,
+      ) if OAuth2::OAUTH_DEBUG
     end
   end
 end

data/lib/oauth2/error.rb

@@ -17,6 +17,8 @@ module OAuth2
     # @param [OAuth2::Response, Hash, Object] response A Response or error payload
     def initialize(response)
       @response = response
+      @code = nil
+      @description = nil
       if response.respond_to?(:parsed)
         if response.parsed.is_a?(Hash)
           @code = response.parsed["error"]

data/lib/oauth2/filtered_attributes.rb

@@ -1,52 +1,13 @@
+# frozen_string_literal: true
+
 module OAuth2
-  # Mixin that redacts sensitive instance variables in #inspect output.
+  # Permanent alias for {Auth::Sanitizer::FilteredAttributes}.
   #
-  # 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.
-  module FilteredAttributes
-    # Hook invoked when the module is included. Extends the including class with
-    # class-level helpers.
-    #
-    # @param [Class] base The including class
-    # @return [void]
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
-
-    # Class-level helpers for configuring filtered attributes.
-    module ClassMethods
-      # 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)
-        @filtered_attribute_names = attributes.map(&:to_sym)
-      end
-
-      # The configured attribute names to filter.
-      #
-      # @return [Array<Symbol>]
-      def filtered_attribute_names
-        @filtered_attribute_names || []
-      end
-    end
-
-    # Custom inspect that redacts configured attributes.
-    #
-    # @return [String]
-    def inspect
-      filtered_attribute_names = self.class.filtered_attribute_names
-      return super if filtered_attribute_names.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]"
-        else
-          "#{var}=#{instance_variable_get(var).inspect}"
-        end
-      end
-      "#<#{self.class}:#{object_id} #{inspected_vars.join(", ")}>"
-    end
-  end
+  # This constant is intentionally kept in the `OAuth2` namespace because it
+  # was part of the public API before the implementation was extracted into the
+  # `auth-sanitizer` gem.  It will **not** be deprecated or removed.
+  #
+  # New code that does not need the `OAuth2::` namespace can use
+  # {Auth::Sanitizer::FilteredAttributes} directly.
+  FilteredAttributes = Auth::Sanitizer::FilteredAttributes
 end

data/lib/oauth2/response.rb

@@ -43,18 +43,20 @@ module OAuth2
       "text/plain" => :text,
     }
 
-    # Adds a new content type parser.
-    #
-    # @param [Symbol] key A descriptive symbol key such as :json or :query
-    # @param [Array<String>, String] mime_types One or more mime types to which this parser applies
-    # @yield [String] Block that will be called to parse the response body
-    # @yieldparam [String] body The response body to parse
-    # @return [void]
-    def self.register_parser(key, mime_types, &block)
-      key = key.to_sym
-      @@parsers[key] = block
-      Array(mime_types).each do |mime_type|
-        @@content_types[mime_type] = key
+    class << self
+      # Adds a new content type parser.
+      #
+      # @param [Symbol] key A descriptive symbol key such as :json or :query
+      # @param [Array<String>, String] mime_types One or more mime types to which this parser applies
+      # @yield [String] Block that will be called to parse the response body
+      # @yieldparam [String] body The response body to parse
+      # @return [void]
+      def register_parser(key, mime_types, &block)
+        key = key.to_sym
+        @@parsers[key] = block
+        Array(mime_types).each do |mime_type|
+          @@content_types[mime_type] = key
+        end
       end
     end
 

data/lib/oauth2/strategy/assertion.rb

@@ -66,8 +66,8 @@ module OAuth2
       #   @see https://datatracker.ietf.org/doc/html/rfc7518#section-3.1
       #
       # The object type of `:key` may depend on the value of `:algorithm`.  Sample arguments:
-      #   get_token(claim_set, {:algorithm => 'HS256', :key => 'secret_key'})
-      #   get_token(claim_set, {:algorithm => 'RS256', :key => OpenSSL::PKCS12.new(File.read('my_key.p12'), 'not_secret')})
+      #   `get_token(claim_set, {:algorithm => 'HS256', :key => 'secret_key'})`
+      #   `get_token(claim_set, {:algorithm => 'RS256', :key => OpenSSL::PKCS12.new(File.read('my_key.p12'), 'not_secret')})`
       #
       # @param [Hash] request_opts options that will be used to assemble the request
       # @option request_opts [String] :scope the url parameter `scope` that may be required by some endpoints

data/lib/oauth2/version.rb

@@ -2,6 +2,6 @@
 
 module OAuth2
   module Version
-    VERSION = "2.0.17"
+    VERSION = "2.0.19"
   end
 end

data/lib/oauth2.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 # includes modules from stdlib
-require "cgi"
+require "cgi/escape"
 require "time"
 
 # third party gems
+require "auth/sanitizer"
 require "snaky_hash"
 require "version_gem"
 
@@ -43,38 +44,59 @@ 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.
   #
   # @return [SnakyHash::SymbolKeyed]
-  @config = DEFAULT_CONFIG.dup
+  CONFIG = DEFAULT_CONFIG.dup
 
   class << self
-    # Access the current configuration.
+    def config
+      CONFIG
+    end
+
+    # Configure global library behavior.
     #
-    # Prefer using {OAuth2.configure} to mutate configuration.
+    # Yields the mutable configuration object so callers can update settings.
     #
-    # @return [SnakyHash::SymbolKeyed]
-    attr_reader :config
+    # @yieldparam [SnakyHash::SymbolKeyed] config the configuration object
+    # @return [void]
+    def configure
+      yield config
+    end
   end
-
-  # Configure global library behavior.
-  #
-  # Yields the mutable configuration object so callers can update settings.
-  #
-  # @yieldparam [SnakyHash::SymbolKeyed] config the configuration object
-  # @return [void]
-  def configure
-    yield @config
-  end
-  module_function :configure
 end
 
+# Wire Auth::Sanitizer's label provider to read from OAuth2.config so that
+# FilteredAttributes-bearing objects and Auth::Sanitizer::SanitizedLogger instances
+# pick up OAuth2.config[:filtered_label] at their initialization time.
+Auth::Sanitizer.filtered_label_provider = -> { OAuth2.config[:filtered_label] }
+
 # Extend OAuth2::Version with VersionGem helpers to provide semantic version helpers.
 OAuth2::Version.class_eval do
   extend VersionGem::Basic

data/sig/oauth2/filtered_attributes.rbs

@@ -1,6 +1,11 @@
 module OAuth2
   module FilteredAttributes
+    module InitializerMethods
+      def initialize: (*untyped args) { () -> untyped } -> untyped
+    end
+
     def self.included: (untyped) -> untyped
-    def filtered_attributes: (*String) -> void
+    def filtered_attributes: (*(String | Symbol)) -> void
+    def thing_filter: () -> OAuth2::ThingFilter
   end
 end

data/sig/oauth2/sanitized_logger.rbs

@@ -0,0 +1,32 @@
+module OAuth2
+  class SanitizedLogger
+    def initialize: (untyped logger) -> void
+
+    def add: (untyped severity, ?untyped message, ?untyped progname) { () -> untyped } -> untyped
+    def <<: (String message) -> untyped
+    def debug: (?untyped progname) { () -> untyped } -> untyped
+    def info: (?untyped progname) { () -> untyped } -> untyped
+    def warn: (?untyped progname) { () -> untyped } -> untyped
+    def error: (?untyped progname) { () -> untyped } -> untyped
+    def fatal: (?untyped progname) { () -> untyped } -> untyped
+    def unknown: (?untyped progname) { () -> untyped } -> untyped
+    def close: () -> void
+    def formatter: () -> untyped
+    def formatter=: (untyped formatter) -> void
+    def level: () -> untyped
+    def level=: (untyped level) -> void
+    def progname: () -> untyped
+    def progname=: (untyped progname) -> void
+    def respond_to_missing?: (Symbol method_name, ?bool include_private) -> bool
+    def method_missing: (Symbol method_name, *untyped args) { () -> untyped } -> untyped
+
+    private
+
+    def log: (Symbol level, ?untyped progname) { () -> untyped } -> untyped
+    def sanitize: (untyped message) -> untyped
+    def thing_filter: () -> OAuth2::ThingFilter
+    def sanitize_authorization_header: (String message) -> String
+    def sanitize_json_pairs: (String message) -> String
+    def sanitize_form_and_query_pairs: (String message) -> String
+  end
+end

data/sig/oauth2/thing_filter.rbs

@@ -0,0 +1,10 @@
+module OAuth2
+  class ThingFilter
+    attr_reader things: Array[String]
+    attr_reader label: String
+
+    def initialize: (Enumerable[untyped] things, label: String) -> void
+    def filtered?: (untyped thing_name) -> bool
+    def pattern_source: () -> String
+  end
+end