doorkeeper 5.9.9 → 6.0.0.beta1

data/lib/doorkeeper/config/validations.rb

@@ -8,14 +8,68 @@ module Doorkeeper
       # Validates configuration options to be set properly.
       #
       def validate!
+        validate_client_authentication_conflict
+        validate_client_authentication_registered
         validate_reuse_access_token_value
         validate_token_reuse_limit
         validate_secret_strategies
         validate_pkce_code_challenge_methods
+        validate_custom_metadata
+        validate_refresh_token_flow
+        validate_issuer_format
+        validate_issuer_metadata_discoverability
       end
 
       private
 
+      # Warn once, at configuration time, when both the deprecated
+      # +client_credentials+ and the new +client_authentication+ options are
+      # set. +client_authentication+ takes precedence; the warning lives here
+      # (rather than in the memoised resolver) so it is not swallowed and
+      # surfaces during boot instead of on the first request.
+      def validate_client_authentication_conflict
+        return unless instance_variable_defined?(:@client_credentials_methods) &&
+                      instance_variable_defined?(:@client_authentication)
+
+        ::Rails.logger.warn(
+          "[DOORKEEPER] Both client_credentials and client_authentication are set, " \
+          "using client_authentication",
+        )
+      end
+
+      # Warn about configured client authentication methods that are not
+      # registered (e.g. a typo, or an extension that failed to load). Such
+      # names are silently ignored when resolving the methods, which could
+      # otherwise leave the application with no usable authentication methods.
+      def validate_client_authentication_registered
+        # The deprecated client_credentials path already validates its own input.
+        return if instance_variable_defined?(:@client_credentials_methods) &&
+                  !instance_variable_defined?(:@client_authentication)
+
+        configured = client_authentication
+        unknown = configured.reject { |name| Doorkeeper::ClientAuthentication.get(name) }
+
+        unless unknown.empty?
+          ::Rails.logger.warn(
+            "[DOORKEEPER] Unknown client authentication method(s) configured and will be ignored: " \
+            "#{unknown.map(&:inspect).join(", ")}. " \
+            "Ensure each method is registered (e.g. by the extension that provides it).",
+          )
+        end
+
+        # A configuration that resolves to zero usable methods fails every
+        # client authentication attempt (all requests fall back to no
+        # credentials), so make that loud rather than silent.
+        return unless (configured - unknown).empty?
+
+        ::Rails.logger.error(
+          "[DOORKEEPER] No usable client authentication methods are configured " \
+          "(client_authentication resolved to an empty set). All client authentication " \
+          "will fail. Configure at least one registered method, e.g. " \
+          "client_authentication #{Doorkeeper::ClientAuthentication::DEFAULT_METHODS.inspect}.",
+        )
+      end
+
       # Determine whether +reuse_access_token+ and a non-restorable
       # +token_secret_strategy+ have both been activated.
       #
@@ -51,7 +105,15 @@ module Doorkeeper
       end
 
       def validate_pkce_code_challenge_methods
-        return if pkce_code_challenge_methods.all? { |method| method =~ /^plain$|^S256$/ }
+        methods = pkce_code_challenge_methods.map(&:to_s)
+        if methods.all? { |method| method.match?(/\A(?:plain|S256)\z/) }
+          # Persist the normalized (string) values only when the option was
+          # explicitly configured — the default is already normalized, and an
+          # unconfigured option should stay undefined rather than have
+          # validation flip its instance_variable_defined? signal.
+          @pkce_code_challenge_methods = methods if instance_variable_defined?(:@pkce_code_challenge_methods)
+          return
+        end
 
         ::Rails.logger.warn(
           "[DOORKEEPER] You have configured an invalid value for pkce_code_challenge_methods option. " \
@@ -60,6 +122,105 @@ module Doorkeeper
 
         @pkce_code_challenge_methods = ["plain", "S256"]
       end
+
+      def validate_custom_metadata
+        return if custom_metadata.is_a? Hash
+
+        ::Rails.logger.warn(
+          "[DOORKEEPER] You have configured an invalid value for custom_metadata option. " \
+          "It must be a Hash, and will be overridden with an empty hash.",
+        )
+
+        @custom_metadata = {}
+      end
+
+      # Warn when the refresh_token grant flow is enabled but refresh tokens
+      # are never issued: refresh token requests would always fail because
+      # there are no tokens to refresh. The flow is enabled automatically
+      # when +use_refresh_token+ is configured, so it doesn't need to be
+      # listed in +grant_flows+ explicitly.
+      #
+      # +calculate_grant_flows+ is used (rather than the raw +grant_flows+) so
+      # that the flow is also detected when enabled through a registered
+      # grant-flow alias. When +use_refresh_token+ is not configured the
+      # refresh_token flow is not appended implicitly, so its presence there
+      # means it was requested explicitly (directly or via an alias).
+      def validate_refresh_token_flow
+        return if refresh_token_enabled?
+        return unless calculate_grant_flows.map(&:to_s).include?("refresh_token")
+
+        ::Rails.logger.warn(
+          "[DOORKEEPER] You have enabled the refresh_token grant flow without " \
+          "configuring use_refresh_token, so refresh tokens will not be issued. " \
+          "Configure use_refresh_token to issue refresh tokens (the refresh_token " \
+          "grant flow is then enabled automatically).",
+        )
+      end
+
+      # Warn when a configured issuer is not RFC-compliant. RFC 8414 (the
+      # metadata issuer) and RFC 9207 (the authorization response iss parameter)
+      # both require an https URL with a host and no query or fragment component.
+      # The value is still used as-is - this is a warning, not a hard failure, so
+      # local setups using e.g. http://localhost keep working - but a
+      # non-compliant issuer produces responses that strict clients may reject.
+      def validate_issuer_format
+        return if issuer.blank?
+
+        uri =
+          begin
+            URI.parse(issuer.to_s)
+          rescue URI::InvalidURIError
+            nil
+          end
+
+        return if uri.is_a?(URI::HTTPS) && uri.host.present? &&
+                  uri.query.nil? && uri.fragment.nil?
+
+        ::Rails.logger.warn(
+          "[DOORKEEPER] issuer #{redacted_issuer.inspect} is not RFC-compliant: " \
+          "RFC 8414 and RFC 9207 require an https URL with a host and no query " \
+          "or fragment component. It is still advertised in the metadata and " \
+          "emitted as the iss parameter as-is, but strict clients may reject it.",
+        )
+      end
+
+      # Warn when a path-bearing issuer cannot be discovered. RFC 8414 clients
+      # build the metadata URL by inserting the well-known path into the issuer,
+      # so an issuer of https://host/tenant is looked up at
+      # https://host/.well-known/oauth-authorization-server/tenant. Doorkeeper
+      # only serves the document at the root well-known path, so such a value is
+      # not discoverable (and its advertised issuer would not match the lookup).
+      # This is a separate concern from validate_issuer_format: a path component
+      # is valid per RFC 8414, just unsupported by Doorkeeper's fixed route.
+      def validate_issuer_metadata_discoverability
+        return if issuer.blank?
+
+        uri =
+          begin
+            URI.parse(issuer.to_s)
+          rescue URI::InvalidURIError
+            nil
+          end
+
+        return if uri&.host.blank?
+        return if uri.path.blank? || uri.path == "/"
+
+        ::Rails.logger.warn(
+          "[DOORKEEPER] issuer #{redacted_issuer.inspect} has a path component, but " \
+          "Doorkeeper serves its RFC 8414 metadata only at the root " \
+          "/.well-known/oauth-authorization-server. RFC 8414 clients derive the " \
+          "metadata URL from the issuer path (…/.well-known/" \
+          "oauth-authorization-server#{uri.path}), so they will not discover the " \
+          "document. Use a host-only issuer, or route the derived well-known path " \
+          "to Doorkeeper.",
+        )
+      end
+
+      # Redact any userinfo (e.g. a misconfigured user:pass@host) before the
+      # issuer is written to the log, so credentials are not leaked there.
+      def redacted_issuer
+        issuer.to_s.sub(%r{//[^/@]*@}, "//***@")
+      end
     end
   end
 end

data/lib/doorkeeper/config.rb

@@ -65,17 +65,50 @@ module Doorkeeper
       end
 
       # Change the way client credentials are retrieved from the request object.
-      # By default it retrieves first from the `HTTP_AUTHORIZATION` header, then
-      # falls back to the `:client_id` and `:client_secret` params from the
-      # `params` object.
       #
-      # NOTE: a list that includes a callable extractor opts out of the RFC 6749
-      # §2.3 validation applied to the symbol extractors — see
-      # +Doorkeeper::OAuth::Client::Credentials.from_request+.
+      # @deprecated Use the +client_authentication+ option instead. The legacy
+      #   +:from_basic+ / +:from_params+ methods are automatically converted to
+      #   the +:client_secret_basic+ / +:client_secret_post+ authentication
+      #   methods. +:none+ (public client support) is appended only when
+      #   +:from_params+ was configured, since that is the only legacy method
+      #   that accepted a bare +client_id+ without a secret — +:from_basic+ on
+      #   its own never did, so it is not broadened. Callable extractors are
+      #   wrapped in a legacy adapter so they keep working during the
+      #   deprecation window.
       #
       # @param methods [Array] Define client credentials
       def client_credentials(*methods)
-        @config.instance_variable_set(:@client_credentials_methods, methods)
+        deprecated(
+          "client_credentials",
+          "Use the client_authentication option instead. Automatically converting to client_authentication",
+        )
+
+        client_authentication = Doorkeeper::ClientAuthentication.from_legacy_client_credentials(methods)
+
+        if client_authentication.empty?
+          Kernel.warn(
+            "[DOORKEEPER] No known client_credentials method detected, " \
+            "cannot automatically convert to client_authentication option",
+          )
+        else
+          @config.instance_variable_set(:@client_credentials_methods, client_authentication)
+        end
+      end
+
+      # Declare which client authentication methods (RFC 6749 §2.3) are
+      # accepted and the order in which they are tried. Accepts either an array
+      # or varargs, so both forms are honoured exactly as written:
+      #
+      #   client_authentication %i[client_secret_basic client_secret_post none]
+      #   client_authentication :client_secret_basic, :client_secret_post
+      #
+      # Unlike the deprecated +client_credentials+ option, the listed methods
+      # are used verbatim — nothing (in particular +:none+) is appended, so a
+      # restrictive configuration is never silently broadened.
+      #
+      # @param methods [Array<Symbol>] the client authentication method names
+      def client_authentication(*methods)
+        @config.instance_variable_set(:@client_authentication, methods.flatten)
       end
 
       # Change the way access token is authenticated from the request object.
@@ -206,6 +239,13 @@ module Doorkeeper
 
       private
 
+      def deprecated(name, message = nil)
+        warning = "[DOORKEEPER] #{name} has been deprecated and will soon be removed"
+        warning = "#{warning}\n#{message}" if message.present?
+
+        Kernel.warn(warning)
+      end
+
       # Configure the secret storing functionality
       def configure_secrets_for(type, using:, fallback:)
         raise ArgumentError, "Invalid type #{type}" if %i[application token].exclude?(type)
@@ -329,9 +369,7 @@ module Doorkeeper
     option :allow_grant_flow_for_client,    default: ->(_grant_flow, _client) { true }
 
     # Allows to forbid specific Application redirect URI's by custom rules.
-    # Doesn't forbid any URI by default. Redirect URIs with a script scheme
-    # (`javascript`, `vbscript`, `data`) are always rejected, regardless of
-    # this option.
+    # Doesn't forbid any URI by default.
     #
     # @param forbid_redirect_uri [Proc] Block or any object respond to #call
     #
@@ -343,6 +381,10 @@ module Doorkeeper
     #
     option :realm,                          default: "Doorkeeper"
 
+    # Issuer URL advertised in the OAuth 2.0 Authorization Server Metadata
+    # (RFC 8414). When nil, the request base URL is used instead.
+    option :issuer,                         default: nil
+
     # Forces the usage of the HTTPS protocol in non-native redirect uris
     # (enabled by default in non-development environments). OAuth2
     # delegates security in communication to the HTTPS protocol so it is
@@ -419,6 +461,10 @@ module Doorkeeper
     option :application_class,
            default: "Doorkeeper::Application"
 
+    # Allows setting a hash of custom data merged into the OAuth 2.0
+    # Authorization Server Metadata response (RFC 8414).
+    option :custom_metadata, default: {}
+
     # Allows to set blank redirect URIs for Applications in case
     # server configured to use URI-less grant flows.
     #
@@ -602,8 +648,57 @@ module Doorkeeper
       pkce_code_challenge_methods
     end
 
+    # Resolves the configured client authentication methods (RFC 6749 §2.3)
+    # into the registered +Doorkeeper::ClientAuthentication::Method+ objects.
+    #
+    # Honors the deprecated +client_credentials+ option for backwards
+    # compatibility: if it was used it provides the source of truth, unless
+    # +client_authentication+ was also set explicitly, in which case the
+    # latter wins.
+    def client_authentication_methods
+      return @client_authentication_methods if defined?(@client_authentication_methods)
+
+      # When both the deprecated +client_credentials+ and the new
+      # +client_authentication+ are set, +client_authentication+ wins. The
+      # conflict is warned about at validation time (see Validations), not here,
+      # so the message is not swallowed by this memoised resolver.
+      only_legacy = instance_variable_defined?(:@client_credentials_methods) &&
+                    !instance_variable_defined?(:@client_authentication)
+      names = only_legacy ? @client_credentials_methods : client_authentication
+
+      # Names configured more than once resolve to the same registered Method
+      # instance, so identity-based #uniq drops the duplicates (which would
+      # otherwise be matched against requests twice and advertised twice in
+      # the server metadata) while distinct legacy callable adapters survive.
+      @client_authentication_methods = names.filter_map do |name|
+        # Legacy callables are already wrapped as Method adapters (see #client_credentials).
+        name.is_a?(Doorkeeper::ClientAuthentication::Method) ? name : Doorkeeper::ClientAuthentication.get(name)
+      end.uniq
+    end
+
+    # The configured client authentication method names (RFC 6749 §2.3),
+    # defaulting to the registry's DEFAULT_METHODS when not set.
+    def client_authentication
+      return Doorkeeper::ClientAuthentication::DEFAULT_METHODS.dup unless instance_variable_defined?(:@client_authentication)
+
+      @client_authentication
+    end
+
+    # @deprecated Renamed to +client_authentication_methods+. This alias keeps
+    #   external callers (e.g. doorkeeper-openid_connect) working for one release
+    #   and will be removed afterwards. It returns the legacy symbol names
+    #   (e.g. +:from_basic+) rather than the internal Method objects so that
+    #   consumers mapping from those symbols keep working unchanged.
     def client_credentials_methods
-      @client_credentials_methods ||= %i[from_basic from_params]
+      unless defined?(@client_credentials_methods_rename_warned)
+        Kernel.warn(
+          "[DOORKEEPER] Doorkeeper.config.client_credentials_methods has been renamed to " \
+          "client_authentication_methods and will be removed in a future version.",
+        )
+        @client_credentials_methods_rename_warned = true
+      end
+
+      Doorkeeper::ClientAuthentication.to_legacy_client_credentials_names(client_authentication_methods)
     end
 
     def access_token_methods
@@ -671,13 +766,17 @@ module Doorkeeper
     def calculate_token_grant_types
       types = grant_flows - ["implicit"]
       types << "refresh_token" if refresh_token_enabled?
-      types
+      types.uniq
     end
 
     # Calculates grant flows configured by the user in Doorkeeper
     # configuration considering registered aliases that is exposed
     # to single or multiple other flows.
     #
+    # The refresh_token flow is added implicitly when +use_refresh_token+
+    # is configured, so the result lists every enabled flow (useful for
+    # RFC 8414 authorization server metadata).
+    #
     def calculate_grant_flows
       configured_flows = grant_flows.map(&:to_s)
       aliases = Doorkeeper::GrantFlow.aliases.keys.map(&:to_s)
@@ -689,6 +788,8 @@ module Doorkeeper
         flows.concat(Doorkeeper::GrantFlow.expand_alias(flow_alias))
       end
 
+      flows << "refresh_token" if refresh_token_enabled?
+
       flows.flatten.uniq
     end
 
@@ -719,9 +820,7 @@ module Doorkeeper
     end
 
     def calculate_token_grant_flows
-      flows = enabled_grant_flows.select(&:handles_grant_type?)
-      flows << Doorkeeper::GrantFlow.get("refresh_token") if refresh_token_enabled?
-      flows
+      enabled_grant_flows.select(&:handles_grant_type?)
     end
   end
 end

data/lib/doorkeeper/errors.rb

@@ -75,6 +75,7 @@ module Doorkeeper
     UnableToGenerateToken = Class.new(DoorkeeperError)
     TokenGeneratorNotFound = Class.new(DoorkeeperError)
     NoOrmCleaner = Class.new(DoorkeeperError)
+    MissingConfigurationBuilderClass = Class.new(DoorkeeperError)
 
     InvalidRequest = Class.new(BaseResponseError)
     InvalidToken = Class.new(BaseResponseError)

data/lib/doorkeeper/models/access_token_mixin.rb

@@ -92,13 +92,16 @@ module Doorkeeper
       #   A nil value will ignore custom attributes, while an empty hash will
       #   only match tokens that have no custom attributes set.
       #
+      # @yield [token] optional additional predicate a token must satisfy to
+      #   count as a match (e.g. the refresh token requirement of the request).
+      #
       # @return [Doorkeeper::AccessToken, nil] Access Token instance or
       #   nil if matching record was not found
       #
-      def matching_token_for(application, resource_owner, scopes, custom_attributes: nil, include_expired: true)
+      def matching_token_for(application, resource_owner, scopes, custom_attributes: nil, include_expired: true, &filter)
         tokens = authorized_tokens_for(application&.id, resource_owner)
         tokens = tokens.not_expired unless include_expired
-        find_matching_token(tokens, application, custom_attributes, scopes)
+        find_matching_token(tokens, application, custom_attributes, scopes, &filter)
       end
 
       # Interface to enumerate access token records in batches in order not
@@ -131,7 +134,7 @@ module Doorkeeper
       # @return [Doorkeeper::AccessToken, nil] Access Token instance or
       #   nil if matching record was not found
       #
-      def find_matching_token(relation, application, custom_attributes, scopes)
+      def find_matching_token(relation, application, custom_attributes, scopes, &filter)
         return nil unless relation
 
         matching_tokens = []
@@ -140,7 +143,8 @@ module Doorkeeper
         find_access_token_in_batches(relation, batch_size: batch_size) do |batch|
           tokens = batch.select do |token|
             scopes_match?(token.scopes, scopes, application&.scopes) &&
-              custom_attributes_match?(token, custom_attributes)
+              custom_attributes_match?(token, custom_attributes) &&
+              (filter.nil? || filter.call(token))
           end
 
           matching_tokens.concat(tokens)
@@ -149,6 +153,32 @@ module Doorkeeper
         matching_tokens.max_by(&:created_at)
       end
 
+      # Checks whether a candidate token for reuse matches the refresh token
+      # requirement of the current request.
+      #
+      # The candidate's refresh token presence must match what the request asks
+      # for, in both directions. A request that expects a refresh token (e.g. an
+      # authorization_code or password grant while `use_refresh_token` is
+      # enabled) must not reuse a token issued without one, or the response would
+      # silently omit the refresh token. Conversely, a request that does not ask
+      # for a refresh token must not reuse a token that carries one, or the
+      # response would return a refresh token the request never requested (this
+      # is reachable when `refresh_token_enabled` is a per-request callable).
+      # When no matching token satisfies the requirement a fresh token is
+      # issued instead.
+      #
+      # @param access_token [Doorkeeper::AccessToken]
+      #   the candidate token for reuse
+      # @param token_attributes [Hash]
+      #   attributes for the token being requested
+      #
+      # @return [Boolean] true if the candidate token's refresh token presence
+      #   matches the request's refresh token requirement, false otherwise
+      #
+      def refresh_token_matches?(access_token, token_attributes)
+        access_token.refresh_token.present? == !!token_attributes[:use_refresh_token]
+      end
+
       # Checks whether the token scopes match the scopes from the parameters
       #
       # @param token_scopes [#to_s]
@@ -226,9 +256,14 @@ module Doorkeeper
           # attributes when matching, while an empty hash only matches tokens
           # that have no custom attributes set.
           custom_attributes = extract_custom_attributes(token_attributes)
+          # The refresh token requirement participates in the matching itself
+          # rather than being checked on its single newest result: the newest
+          # matching token may carry the wrong refresh token presence (e.g. it
+          # was issued through a grant with a different `use_refresh_token`)
+          # while an older token satisfies the request and can still be reused.
           access_token = matching_token_for(
             application, resource_owner, scopes, custom_attributes: custom_attributes, include_expired: false,
-          )
+          ) { |token| refresh_token_matches?(token, token_attributes) }
 
           return access_token if access_token&.reusable?
         end

data/lib/doorkeeper/models/application_mixin.rb

@@ -5,6 +5,7 @@ module Doorkeeper
     extend ActiveSupport::Concern
 
     include OAuth::Helpers
+    include Models::Concerns::WriteToPrimary
     include Models::Orderable
     include Models::SecretStorable
     include Models::Scopes
@@ -27,9 +28,8 @@ module Doorkeeper
         app = by_uid(uid)
         return unless app
         return app if secret.blank? && !app.confidential?
-        return unless app.secret_matches?(secret)
 
-        app
+        app if app.secret_matches?(secret)
       end
 
       # Returns an instance of the Doorkeeper::Application with specific UID.
@@ -76,18 +76,26 @@ module Doorkeeper
     # @return [Boolean] Whether the given secret matches the stored secret
     #                of this application.
     #
+    # @note When the secret matches only via the fallback strategy, the stored
+    #       secret is upgraded to the active strategy as a side-effect (mirrors
+    #       the find_by_plaintext_token -> find_by_fallback_token pattern).
+    #
     def secret_matches?(input)
       # return false if either is nil, since secure_compare depends on strings
       # but Application secrets MAY be nil depending on confidentiality.
       return false if input.nil? || secret.nil?
 
+      input = input.to_s
+
       # When matching the secret by comparer function, all is well.
       return true if secret_strategy.secret_matches?(input, secret)
 
-      # When fallback lookup is enabled, ensure applications
-      # with plain secrets can still be found
-      if fallback_secret_strategy
-        fallback_secret_strategy.secret_matches?(input, secret)
+      # When fallback lookup is enabled, ensure applications with plain secrets
+      # can still be found, upgrading the stored secret to the active strategy
+      # on a successful match.
+      if fallback_secret_strategy&.secret_matches?(input, secret)
+        self.class.upgrade_fallback_value(self, :secret, input)
+        true
       else
         false
       end

data/lib/doorkeeper/models/concerns/secret_storable.rb

@@ -84,7 +84,16 @@ module Doorkeeper
         #
         def upgrade_fallback_value(instance, attr, plain_secret)
           upgraded = secret_strategy.store_secret(instance, attr, plain_secret)
-          instance.update(attr => upgraded)
+
+          # The upgrade is a write on what is otherwise a read path (finding a
+          # record by its secret), so it must reach the primary database when
+          # automatic role switching would route the surrounding request to a
+          # read replica.
+          if respond_to?(:with_primary_role)
+            with_primary_role { instance.update(attr => upgraded) }
+          else
+            instance.update(attr => upgraded)
+          end
         end
 
         ##

data/lib/doorkeeper/oauth/authorization/uri_builder.rb

@@ -10,6 +10,17 @@ module Doorkeeper
           def uri_with_query(url, parameters = {})
             uri = URI.parse(url)
             original_query = Rack::Utils.parse_query(uri.query)
+            # `parse_query` yields string keys while `parameters` uses symbol
+            # keys, so a naive merge cannot dedupe a collision (e.g. a registered
+            # redirect_uri already carrying `state`) and would emit the param
+            # twice. Normalize keys so the response parameters win over any
+            # same-named query already present in the redirect_uri. Blank
+            # response parameters are dropped before the merge: they carry no
+            # value to respond with, and letting them clobber a same-named
+            # registered parameter would violate RFC 6749 §3.1.2 (the registered
+            # query component "MUST be retained when adding additional query
+            # parameters").
+            parameters = parameters.transform_keys(&:to_s).reject { |_, value| value.blank? }
             uri.query = build_query(original_query.merge(parameters))
             uri.to_s
           end

data/lib/doorkeeper/oauth/authorization_code_request.rb

@@ -13,6 +13,9 @@ module Doorkeeper
       attr_reader :grant, :client, :redirect_uri, :access_token, :code_verifier,
                   :invalid_request_reason, :missing_param
 
+      # A scope parameter is deliberately not read here: RFC 6749 does not
+      # define one for the authorization_code token request (§4.1.3), so it
+      # is ignored and the access token inherits the scopes of the grant.
       def initialize(server, grant, client, parameters = {})
         super()
         @server = server
@@ -64,7 +67,7 @@ module Doorkeeper
         @missing_param =
           if grant&.uses_pkce? && code_verifier.blank?
             :code_verifier
-          elsif client && !client.confidential && Doorkeeper.config.force_pkce? && code_verifier.blank?
+          elsif client && Doorkeeper.config.force_pkce? && code_verifier.blank?
             :code_verifier
           elsif redirect_uri.blank?
             :redirect_uri

data/lib/doorkeeper/oauth/client.rb

@@ -1,8 +1,26 @@
 # frozen_string_literal: true
 
+# The full registry rather than just credentials: requiring only
+# client_authentication/credentials fires the ClientAuthentication autoload
+# mid-load, which re-requires the in-progress file and warns under -w
+# ("circular require considered harmful").
+require "doorkeeper/client_authentication"
+
 module Doorkeeper
   module OAuth
     class Client
+      # @deprecated Moved to +Doorkeeper::ClientAuthentication::Credentials+.
+      #   This alias keeps the long-standing +Doorkeeper::OAuth::Client::Credentials+
+      #   constant resolvable for one release so referencing code does not raise
+      #   +NameError+; update references to the new constant. Note the legacy
+      #   +.from_request+/+.from_basic+/+.from_params+ class methods are gone —
+      #   client credential extraction now goes through the client authentication
+      #   registry (RFC 6749 §2.3). Marked with +deprecate_constant+, so Ruby
+      #   warns on access when deprecation warnings are enabled
+      #   (+Warning[:deprecated] = true+ or +-W:deprecated+).
+      Credentials = Doorkeeper::ClientAuthentication::Credentials
+      deprecate_constant :Credentials
+
       attr_reader :application
 
       delegate :id, :name, :uid, :redirect_uri, :scopes, :confidential, to: :@application

data/lib/doorkeeper/oauth/client_authentication/client_secret_basic.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module OAuth
+    module ClientAuthentication
+      # RFC 6749 §2.3.1 "client_secret_basic": client credentials are sent
+      # using HTTP Basic authentication.
+      #
+      # Known deviation: §2.3.1 also requires the client_id and client_secret
+      # to be form-urlencoded before being placed into the Basic header.
+      # Doorkeeper has never URL-decoded them (like much of the ecosystem),
+      # and this strategy deliberately keeps that behaviour — adding the
+      # decoding now would break every existing client whose credentials
+      # contain URL-encodable characters.
+      class ClientSecretBasic
+        # Match whenever the header decodes to a non-blank +client_id+ — i.e.
+        # whenever a Basic authentication *attempt* is present. The secret may
+        # be empty (public clients) or missing; those are still Basic auth
+        # attempts and must be claimed here so that invalid credentials fail
+        # with +invalid_client+ instead of silently falling through to another
+        # configured method or the fallback (which would downgrade a failed
+        # authentication attempt to "no authentication provided").
+        def self.matches_request?(request)
+          credentials_from(request).present?
+        end
+
+        def self.authenticate(request)
+          client_id, client_secret = credentials_from(request)
+          return unless client_id
+
+          Doorkeeper::ClientAuthentication::Credentials.new(client_id, client_secret)
+        end
+
+        # Returns the decoded [client_id, client_secret] pair, or nil when the
+        # request carries no HTTP Basic +client_id+. A header that merely
+        # starts with "Basic " but decodes to an empty/blank client_id (e.g.
+        # an empty payload or a leading ":") is not a usable attempt and does
+        # not match.
+        def self.credentials_from(request)
+          authorization = request.authorization.to_s
+          return unless authorization.downcase.start_with?("basic ")
+
+          value = authorization.split(" ", 2).last
+          client_id, client_secret = Base64.decode64(value.to_s).split(":", 2)
+          return if client_id.blank?
+
+          [client_id, client_secret]
+        end
+        private_class_method :credentials_from
+      end
+    end
+  end
+end