oauth2 1.4.7 → 2.0.20

data/lib/oauth2/authenticator.rb

@@ -1,9 +1,26 @@
-require 'base64'
+# frozen_string_literal: true
+
+require "base64"
 
 module OAuth2
+  # Builds and applies client authentication to token and revoke requests.
+  #
+  # Depending on the selected mode, credentials are applied as Basic Auth
+  # headers, request body parameters, or only the client_id is sent (TLS).
   class Authenticator
+    include FilteredAttributes
+
+    # @return [Symbol, String] Authentication mode (e.g., :basic_auth, :request_body, :tls_client_auth, :private_key_jwt)
+    # @return [String, nil] Client identifier
+    # @return [String, nil] Client secret (filtered in inspected output)
     attr_reader :mode, :id, :secret
+    filtered_attributes :secret
 
+    # Create a new Authenticator
+    #
+    # @param [String, nil] id Client identifier
+    # @param [String, nil] secret Client secret
+    # @param [Symbol, String] mode Authentication mode
     def initialize(id, secret, mode)
       @id = id
       @secret = secret
@@ -12,7 +29,7 @@ module OAuth2
 
     # Apply the request credentials used to authenticate to the Authorization Server
     #
-    # Depending on configuration, this might be as request params or as an
+    # Depending on the configuration, this might be as request params or as an
     # Authorization header.
     #
     # User-provided params and header take precedence.
@@ -34,35 +51,59 @@ module OAuth2
       end
     end
 
-    def self.encode_basic_auth(user, password)
-      'Basic ' + Base64.encode64(user + ':' + password).delete("\n")
+    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
 
     # Adds client_id and client_secret request parameters if they are not
     # already set.
+    #
+    # @param [Hash] params Request parameters
+    # @return [Hash] Updated parameters including client_id and client_secret
     def apply_params_auth(params)
-      {'client_id' => id, 'client_secret' => secret}.merge(params)
+      result = {}
+      result["client_id"] = id unless id.nil?
+      result["client_secret"] = secret unless secret.nil?
+      result.merge(params)
     end
 
-    # When using schemes that don't require the client_secret to be passed i.e TLS Client Auth,
+    # When using schemes that don't require the client_secret to be passed (e.g., TLS Client Auth),
     # we don't want to send the secret
+    #
+    # @param [Hash] params Request parameters
+    # @return [Hash] Updated parameters including only client_id
     def apply_client_id(params)
-      {'client_id' => id}.merge(params)
+      result = {}
+      result["client_id"] = id unless id.nil?
+      result.merge(params)
     end
 
     # Adds an `Authorization` header with Basic Auth credentials if and only if
     # it is not already set in the params.
+    #
+    # @param [Hash] params Request parameters (may include :headers)
+    # @return [Hash] Updated parameters with Authorization header
     def apply_basic_auth(params)
       headers = params.fetch(:headers, {})
       headers = basic_auth_header.merge(headers)
-      params.merge(:headers => headers)
+      params.merge(headers: headers)
     end
 
-    # @see https://tools.ietf.org/html/rfc2617#section-2
+    # Build the Basic Authorization header.
+    #
+    # @see https://datatracker.ietf.org/doc/html/rfc2617#section-2
+    # @return [Hash] Header hash containing the Authorization entry
     def basic_auth_header
-      {'Authorization' => self.class.encode_basic_auth(id, secret)}
+      {"Authorization" => self.class.encode_basic_auth(id, secret)}
     end
   end
 end