oauth2 2.0.11 → 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/SECURITY.md

@@ -2,25 +2,34 @@
 
 ## Supported Versions
 
-| Version  | Supported | EOL     | Post-EOL / Enterprise                 |
-|----------|-----------|---------|---------------------------------------|
-| 2.latest | ✅         | 04/2026 | [Tidelift Subscription][tidelift-ref] |
-| 1.latest | ✅         | 10/2025 | [Tidelift Subscription][tidelift-ref] |
-| <= 1     | ⛔         | ⛔       | ⛔                                     |
+| Version  | Supported | Post-EOL / Enterprise                 |
+|----------|-----------|---------------------------------------|
+| 2.latest | ✅         | [Tidelift Subscription][tidelift-ref] |
+| 1.latest | ✅         | [Tidelift Subscription][tidelift-ref] |
+| <= 1     | ⛔         | ⛔                                     |
 
 ### EOL Policy
 
 Non-commercial support for the oldest version of Ruby (which itself is going EOL) will be dropped each year in April.
 
-## Reporting a Vulnerability
+## Security contact information
 
-To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
 Tidelift will coordinate the fix and disclosure.
 
-## OAuth2 for Enterprise
+## Additional Support
+
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
+
+[README]: README.md
+
+## Enterprise Support
 
 Available as part of the Tidelift Subscription.
 
-The maintainers of oauth2 and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. [Learn more.][tidelift-ref]
+The maintainers of this library and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. [Learn more.][tidelift-ref]
 
 [tidelift-ref]: https://tidelift.com/subscription/pkg/rubygems-oauth2?utm_source=rubygems-oauth2&utm_medium=referral&utm_campaign=enterprise&utm_term=repo

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/strategy/assertion.rb

@@ -95,7 +95,10 @@ module OAuth2
       def build_assertion(claims, encoding_opts)
         raise ArgumentError.new(message: "Please provide an encoding_opts hash with :algorithm and :key") if !encoding_opts.is_a?(Hash) || (%i[algorithm key] - encoding_opts.keys).any?
 
-        JWT.encode(claims, encoding_opts[:key], encoding_opts[:algorithm])
+        headers = {}
+        headers[:kid] = encoding_opts[:kid] if encoding_opts.key?(:kid)
+
+        JWT.encode(claims, encoding_opts[:key], encoding_opts[:algorithm], headers)
       end
     end
   end

data/lib/oauth2/version.rb

@@ -2,6 +2,6 @@
 
 module OAuth2
   module Version
-    VERSION = "2.0.11"
+    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