oauth2 2.0.12 → 2.0.13

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/lib/oauth2/authenticator.rb

@@ -3,12 +3,24 @@
 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
@@ -39,6 +51,11 @@ 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}")}"
     end
@@ -47,6 +64,9 @@ module OAuth2
 
     # 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)
       result = {}
       result["client_id"] = id unless id.nil?
@@ -54,8 +74,11 @@ module OAuth2
       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)
       result = {}
       result["client_id"] = id unless id.nil?
@@ -64,13 +87,19 @@ module OAuth2
 
     # 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)
     end
 
+    # 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)}
     end

data/lib/oauth2/client.rb

@@ -256,10 +256,10 @@ module OAuth2
     # @see https://datatracker.ietf.org/doc/html/rfc7009#section-2.1
     def revoke_token(token, token_type_hint = nil, params = {}, &block)
       params[:token_method] ||= :post_with_query_string
+      params[:token] = token
+      params[:token_type_hint] = token_type_hint if token_type_hint
+
       req_opts = params_to_req_opts(params)
-      req_opts[:params] ||= {}
-      req_opts[:params][:token] = token
-      req_opts[:params][:token_type_hint] = token_type_hint if token_type_hint
 
       request(http_method, revoke_url, req_opts, &block)
     end

data/lib/oauth2/error.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
 module OAuth2
+  # Represents an OAuth2 error condition.
+  #
+  # Wraps details from an OAuth2::Response or Hash payload returned by an
+  # authorization server, exposing error code and description per RFC 6749.
   class Error < StandardError
+    # @return [OAuth2::Response, Hash, Object] Original response or payload used to build the error
+    # @return [String] Raw body content (if available)
+    # @return [String, nil] Error code (e.g., 'invalid_grant')
+    # @return [String, nil] Human-readable description for the error
     attr_reader :response, :body, :code, :description
 
-    # standard error codes include:
-    # 'invalid_request', 'invalid_client', 'invalid_token', 'invalid_grant', 'unsupported_grant_type', 'invalid_scope'
-    # response might be a Response object, or the response.parsed hash
+    # Create a new OAuth2::Error
+    #
+    # @param [OAuth2::Response, Hash, Object] response A Response or error payload
     def initialize(response)
       @response = response
       if response.respond_to?(:parsed)
@@ -29,6 +37,11 @@ module OAuth2
 
   private
 
+    # Builds a multi-line error message including description and raw body.
+    #
+    # @param [String, #encode] response_body Response body content
+    # @param [Hash] opts Options including :error_description
+    # @return [String] Message suitable for StandardError
     def error_message(response_body, opts = {})
       lines = []
 
@@ -46,6 +59,11 @@ module OAuth2
       lines.join("\n")
     end
 
+    # Formats the OAuth2 error code and description into a single string.
+    #
+    # @param [String, nil] code OAuth2 error code
+    # @param [String, nil] description OAuth2 error description
+    # @return [Hash] Options hash containing :error_description when present
     def parse_error_description(code, description)
       return {} unless code || description
 

data/lib/oauth2/filtered_attributes.rb

@@ -1,19 +1,40 @@
 module OAuth2
+  # Mixin that redacts sensitive instance variables in #inspect output.
+  #
+  # 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?

data/lib/oauth2/version.rb

@@ -2,6 +2,6 @@
 
 module OAuth2
   module Version
-    VERSION = "2.0.12"
+    VERSION = "2.0.13"
   end
 end

data/lib/oauth2.rb

@@ -24,22 +24,58 @@ require_relative "oauth2/access_token"
 require_relative "oauth2/response"
 
 # The namespace of this library
+#
+# This module is the entry point and top-level namespace for the oauth2 gem.
+# It exposes configuration, constants, and requires the primary public classes.
 module OAuth2
+  # When true, enables verbose HTTP logging via Faraday's logger middleware.
+  # Controlled by the OAUTH_DEBUG environment variable. Any case-insensitive
+  # value equal to "true" will enable debugging.
+  #
+  # @return [Boolean]
   OAUTH_DEBUG = ENV.fetch("OAUTH_DEBUG", "false").casecmp("true").zero?
+
+  # Default configuration values for the oauth2 library.
+  #
+  # @example Toggle warnings
+  #   OAuth2.configure do |config|
+  #     config[:silence_extra_tokens_warning] = false
+  #     config[:silence_no_tokens_warning] = false
+  #   end
+  #
+  # @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,
   )
+
+  # The current runtime configuration for the library.
+  #
+  # @return [SnakyHash::SymbolKeyed]
   @config = DEFAULT_CONFIG.dup
+
   class << self
+    # Access the current configuration.
+    #
+    # Prefer using {OAuth2.configure} to mutate configuration.
+    #
+    # @return [SnakyHash::SymbolKeyed]
     attr_reader :config
   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
 
+# Extend OAuth2::Version with VersionGem helpers to provide semantic version helpers.
 OAuth2::Version.class_eval do
   extend VersionGem::Basic
 end

data/sig/oauth2/access_token.rbs

@@ -0,0 +1,25 @@
+module OAuth2
+  class AccessToken
+    def self.from_hash: (OAuth2::Client, Hash[untyped, untyped]) -> OAuth2::AccessToken
+    def self.from_kvform: (OAuth2::Client, String) -> OAuth2::AccessToken
+
+    def initialize: (OAuth2::Client, String, ?Hash[Symbol, untyped]) -> void
+    def []: (String | Symbol) -> untyped
+    def expires?: () -> bool
+    def expired?: () -> bool
+    def refresh: (?Hash[untyped, untyped], ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::AccessToken
+    def revoke: (?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def to_hash: () -> Hash[Symbol, untyped]
+    def request: (Symbol, String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def get: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def post: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def put: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def patch: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def delete: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+    def headers: () -> Hash[String, String]
+    def configure_authentication!: (Hash[Symbol, untyped]) -> void
+    def convert_expires_at: (untyped) -> (Time | Integer | nil)
+
+    attr_accessor response: OAuth2::Response
+  end
+end

data/sig/oauth2/authenticator.rbs

@@ -0,0 +1,22 @@
+module OAuth2
+  class Authenticator
+    include OAuth2::FilteredAttributes
+
+    attr_reader mode: (Symbol | String)
+    attr_reader id: String?
+    attr_reader secret: String?
+
+    def initialize: (String? id, String? secret, (Symbol | String) mode) -> void
+
+    def apply: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+
+    def self.encode_basic_auth: (String, String) -> String
+
+    private
+
+    def apply_params_auth: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+    def apply_client_id: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+    def apply_basic_auth: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+    def basic_auth_header: () -> Hash[String, String]
+  end
+end

data/sig/oauth2/client.rbs

@@ -0,0 +1,52 @@
+module OAuth2
+  class Client
+    RESERVED_REQ_KEYS: Array[String]
+    RESERVED_PARAM_KEYS: Array[String]
+
+    include OAuth2::FilteredAttributes
+
+    attr_reader id: String
+    attr_reader secret: String
+    attr_reader site: String?
+    attr_accessor options: Hash[Symbol, untyped]
+    attr_writer connection: untyped
+
+    def initialize: (String client_id, String client_secret, ?Hash[Symbol, untyped]) { (untyped) -> void } -> void
+
+    def site=: (String) -> String
+
+    def connection: () -> untyped
+
+    def authorize_url: (?Hash[untyped, untyped]) -> String
+    def token_url: (?Hash[untyped, untyped]) -> String
+    def revoke_url: (?Hash[untyped, untyped]) -> String
+
+    def request: (Symbol verb, String url, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+
+    def get_token: (Hash[untyped, untyped] params, ?Hash[Symbol, untyped] access_token_opts, ?Proc) { (Hash[Symbol, untyped]) -> void } -> (OAuth2::AccessToken | nil)
+
+    def revoke_token: (String token, ?String token_type_hint, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response
+
+    def http_method: () -> Symbol
+
+    def auth_code: () -> OAuth2::Strategy::AuthCode
+    def implicit: () -> OAuth2::Strategy::Implicit
+    def password: () -> OAuth2::Strategy::Password
+    def client_credentials: () -> OAuth2::Strategy::ClientCredentials
+    def assertion: () -> OAuth2::Strategy::Assertion
+
+    def redirection_params: () -> Hash[String, String]
+
+    private
+
+    def params_to_req_opts: (Hash[untyped, untyped]) -> Hash[Symbol, untyped]
+    def parse_snaky_params_headers: (Hash[untyped, untyped]) -> [Symbol, bool, untyped, (Symbol | nil), Hash[untyped, untyped], Hash[String, String]]
+    def execute_request: (Symbol verb, String url, ?Hash[Symbol, untyped]) { (Faraday::Request) -> void } -> OAuth2::Response
+    def authenticator: () -> OAuth2::Authenticator
+    def parse_response_legacy: (OAuth2::Response, Hash[Symbol, untyped], Proc) -> (OAuth2::AccessToken | nil)
+    def parse_response: (OAuth2::Response, Hash[Symbol, untyped]) -> (OAuth2::AccessToken | nil)
+    def build_access_token: (OAuth2::Response, Hash[Symbol, untyped], untyped) -> OAuth2::AccessToken
+    def build_access_token_legacy: (OAuth2::Response, Hash[Symbol, untyped], Proc) -> (OAuth2::AccessToken | nil)
+    def oauth_debug_logging: (untyped) -> void
+  end
+end

data/sig/oauth2/error.rbs

@@ -0,0 +1,8 @@
+module OAuth2
+  class Error < StandardError
+    def initialize: (OAuth2::Response) -> void
+    def code: () -> (String | Integer | nil)
+    def description: () -> (String | nil)
+    def response: () -> OAuth2::Response
+  end
+end

data/sig/oauth2/filtered_attributes.rbs

@@ -0,0 +1,6 @@
+module OAuth2
+  module FilteredAttributes
+    def self.included: (untyped) -> untyped
+    def filtered_attributes: (*String) -> void
+  end
+end

data/sig/oauth2/response.rbs

@@ -0,0 +1,18 @@
+module OAuth2
+  class Response
+    DEFAULT_OPTIONS: Hash[Symbol, untyped]
+
+    def self.register_parser: (Symbol key, (Array[String] | String) mime_types) { (String) -> untyped } -> void
+
+    def initialize: (untyped response, parse: Symbol?, snaky: bool?, snaky_hash_klass: untyped?, options: Hash[Symbol, untyped]?) -> void
+    def headers: () -> Hash[untyped, untyped]
+    def status: () -> Integer
+    def body: () -> String
+    def parsed: () -> untyped
+    def content_type: () -> (String | nil)
+    def parser: () -> (untyped | nil)
+
+    attr_reader response: untyped
+    attr_accessor options: Hash[Symbol, untyped]
+  end
+end

data/sig/oauth2/strategy.rbs

@@ -0,0 +1,34 @@
+module OAuth2
+  module Strategy
+    class Base
+      def initialize: (OAuth2::Client) -> void
+    end
+
+    class AuthCode < Base
+      def authorize_params: (?Hash[untyped, untyped]) -> Hash[untyped, untyped]
+      def authorize_url: (?Hash[untyped, untyped]) -> String
+      def get_token: (String, ?Hash[untyped, untyped], ?Hash[Symbol, untyped]) -> OAuth2::AccessToken
+    end
+
+    class Implicit < Base
+      def authorize_params: (?Hash[untyped, untyped]) -> Hash[untyped, untyped]
+      def authorize_url: (?Hash[untyped, untyped]) -> String
+      def get_token: (*untyped) -> void
+    end
+
+    class Password < Base
+      def authorize_url: () -> void
+      def get_token: (String, String, ?Hash[untyped, untyped], ?Hash[Symbol, untyped]) -> OAuth2::AccessToken
+    end
+
+    class ClientCredentials < Base
+      def authorize_url: () -> void
+      def get_token: (?Hash[untyped, untyped], ?Hash[Symbol, untyped]) -> OAuth2::AccessToken
+    end
+
+    class Assertion < Base
+      def authorize_url: () -> void
+      def get_token: (Hash[untyped, untyped], Hash[Symbol, untyped], ?Hash[Symbol, untyped], ?Hash[Symbol, untyped]) -> OAuth2::AccessToken
+    end
+  end
+end

data/sig/oauth2/version.rbs

@@ -0,0 +1,5 @@
+module OAuth2
+  module Version
+    VERSION: String
+  end
+end

data/sig/oauth2.rbs

@@ -0,0 +1,9 @@
+module OAuth2
+  OAUTH_DEBUG: bool
+
+  DEFAULT_CONFIG: untyped
+  @config: untyped
+
+  def self.config: () -> untyped
+  def self.configure: () { (untyped) -> void } -> void
+end