api_keys 0.3.0 → 0.4.0

data/lib/api_keys/services/authenticator.rb

@@ -13,6 +13,12 @@ module ApiKeys
     class Authenticator
       extend ApiKeys::Logging
 
+      MAX_TOKEN_BYTESIZE = 512
+      MAX_BCRYPT_CANDIDATES = 32
+      MAX_KNOWN_PREFIXES = 1_024
+      TOKEN_CACHE_NAMESPACE = "api_keys:v2:token"
+      KNOWN_PREFIXES_CACHE_KEY = "api_keys:v2:known_prefixes"
+
       # Result object for authentication attempts.
       Result = Struct.new(:success?, :api_key, :error_code, :message, keyword_init: true) do
         def self.success(api_key)
@@ -22,6 +28,14 @@ module ApiKeys
         def self.failure(error_code:, message:)
           new(success?: false, error_code: error_code, message: message)
         end
+
+        # Do not delegate to Struct's default inspection: it recursively inspects
+        # the Active Record object and can expose token digests or public tokens.
+        def inspect
+          "#<#{self.class.name} success?=#{success?.inspect} api_key_id=#{api_key&.id.inspect} error_code=#{error_code.inspect}>"
+        end
+
+        alias_method :to_s, :inspect
       end
 
       # Authenticates the request.
@@ -29,20 +43,18 @@ module ApiKeys
       # @param request [ActionDispatch::Request] The incoming request object.
       # @return [ApiKeys::Services::Authenticator::Result] The result of the authentication attempt.
       def self.call(request)
-        log_debug "[ApiKeys Auth] Authenticator.call started for request: #{request.uuid}"
+        request_uuid = request.uuid if request.respond_to?(:uuid)
+        log_debug "[ApiKeys Auth] Authentication started for request #{request_uuid || '[unknown]'}"
         config = ApiKeys.configuration
-        config.before_authentication&.call(request)
 
         # === HTTPS Check (Production Only) ===
-        if defined?(Rails.env) && Rails.env.production? && config.https_only_production
-          if request.protocol == "http://"
+        if production_environment? && config.https_only_production
+          unless secure_request?(request)
             warning_message = "[ApiKeys Security] API key authentication attempted over insecure HTTP connection in production."
             log_warn warning_message
             if config.https_strict_mode
               log_warn "[ApiKeys Security] Strict mode enabled: Aborting authentication."
-              result = Result.failure(error_code: :insecure_connection, message: "API requests must be made over HTTPS in production.")
-              config.after_authentication&.call(result)
-              return result # Halt execution due to strict mode
+              return Result.failure(error_code: :insecure_connection, message: "API requests must be made over HTTPS in production.")
             end
           end
         end
@@ -52,16 +64,22 @@ module ApiKeys
 
         unless token
           log_debug "[ApiKeys Auth] Token extraction failed."
-          result = Result.failure(error_code: :missing_token, message: "API token is missing")
-          config.after_authentication&.call(result)
-          return result
+          return Result.failure(error_code: :missing_token, message: "API token is missing")
+        end
+
+        unless valid_token?(token)
+          log_debug "[ApiKeys Auth] Rejected a malformed API token."
+          return Result.failure(error_code: :invalid_token, message: "API token is invalid")
         end
 
         log_debug "[ApiKeys Auth] Token extracted successfully. Verifying..."
         # Pass the original token AND config to find_and_verify_key
         api_key = find_and_verify_key(token, config)
 
-        result = if api_key&.active?
+        result = if (configuration_failure = check_key_type_configuration(api_key, config) ||
+                                                check_environment_configuration(api_key, config))
+                   configuration_failure
+                 elsif api_key&.active?
                    log_debug "[ApiKeys Auth] Verification successful. Key ID: #{api_key.id}"
 
                    # Check environment isolation if enabled
@@ -83,22 +101,21 @@ module ApiKeys
                    Result.failure(error_code: :invalid_token, message: "API token is invalid")
                  end
 
-        log_debug "[ApiKeys Auth] Authenticator.call finished. Result: #{result.inspect}"
-        config.after_authentication&.call(result)
+        log_debug "[ApiKeys Auth] Authentication finished. Success: #{result.success?}; error code: #{result.error_code || 'none'}"
         result
       end
 
-      private
-
       # Extracts the token string from the request headers or query parameters.
       def self.extract_token(request, config)
         # Check header first (preferred)
         if config.header.present?
           header_value = request.headers[config.header]
-          log_debug "[ApiKeys Auth] Checking header '#{config.header}': '#{header_value}'"
-          if header_value
+          log_debug "[ApiKeys Auth] Checked configured authentication header. Present: #{!header_value.nil?}"
+          unless header_value.nil?
+            return header_value unless header_value.is_a?(String)
+
             # Handle "Bearer <token>" scheme
-            match = header_value.match(/^Bearer\s+(.*)$/i)
+            match = header_value.match(/\ABearer[ \t]+(.+)\z/i)
             if match
               log_debug "[ApiKeys Auth] Extracted token from Bearer scheme."
               return match[1]
@@ -112,7 +129,7 @@ module ApiKeys
         # Check query parameter as fallback (if configured)
         if config.query_param.present?
           param_value = request.query_parameters[config.query_param]
-          log_debug "[ApiKeys Auth] Checking query param '#{config.query_param}': '#{param_value}'"
+          log_debug "[ApiKeys Auth] Checked configured query parameter. Present: #{param_value.present?}"
           if param_value.present?
             log_debug "[ApiKeys Auth] Extracted token from query parameter."
             return param_value
@@ -129,170 +146,298 @@ module ApiKeys
       # @param config [ApiKeys::Configuration] The current configuration.
       # @return [ApiKeys::ApiKey, nil] The verified ApiKey instance or nil.
       def self.find_and_verify_key(token, config)
-        cache_key = "api_keys:token:#{Digest::SHA1.hexdigest(token)}" # Cache key based on token hash
-        cache_ttl = config.cache_ttl.to_i
-        log_debug "[ApiKeys Auth] Verifying token. Cache key: #{cache_key}, TTL: #{cache_ttl}"
+        cache_key = "#{TOKEN_CACHE_NAMESPACE}:#{Digest::SHA256.hexdigest(token)}"
+        cache_ttl = normalized_cache_ttl(config.cache_ttl)
+        log_debug "[ApiKeys Auth] Verifying token. Cache enabled: #{cache_ttl.positive?}"
 
         if cache_ttl > 0
-          cached_result = rails_cache&.read(cache_key)
-          log_debug "[ApiKeys Auth] Cache check: Result=#{cached_result.inspect}"
-          # Return cached result ONLY if it's a valid ApiKey instance (a true cache hit)
-          if cached_result.is_a?(ApiKeys::ApiKey)
-             log_debug "[ApiKeys Auth] Cache HIT. Returning cached ApiKey ID: #{cached_result.id}"
-             return cached_result
-          elsif cached_result.nil?
-             log_debug "[ApiKeys Auth] Cache MISS. Proceeding to DB lookup."
-             # Continue execution if it's a cache miss (nil)
-          else
-             # Handle unexpected cache values (e.g., old symbol :not_found)
-             log_warn "[ApiKeys Auth] Invalid cache value found: #{cached_result.inspect}. Proceeding to DB lookup."
+          cached_id = safe_cache_read(cache_key)
+          if cache_identifier?(cached_id)
+            cached_key = safe_find_by_id(cached_id)
+            if cached_key && verify_record_token(cached_key, token)
+              log_debug "[ApiKeys Auth] Cache lookup hint verified for key ID: #{cached_key.id}"
+              return cached_key
+            end
           end
         end
 
-        # --- Cache miss or TTL=0: Perform DB lookup & verification ---
         log_debug "[ApiKeys Auth] Performing DB lookup and verification."
+        verified_key = find_sha256_key(token) || find_bcrypt_key(token, config)
 
-        # 1. Determine the expected hashing strategy (assuming single strategy for now)
-        strategy = config.hash_strategy.to_sym
-        log_debug "[ApiKeys Auth] Using strategy: #{strategy}"
-
-        # 2. Find and verify the key based on the strategy.
-        verified_key = nil
-        if strategy == :bcrypt
-          # Optimization: Check against the *configured* prefix first.
-          configured_prefix = config.token_prefix.call
-          matched_prefix = nil
-
-          if token.start_with?(configured_prefix)
-            log_debug "[ApiKeys Auth] Token matches configured prefix: #{configured_prefix}"
-            matched_prefix = configured_prefix
-          else
-            # Fallback: If no match, check against all known prefixes (cached).
-            log_debug "[ApiKeys Auth] Token does not match configured prefix. Checking known prefixes."
-            known_prefixes = fetch_known_prefixes(config)
-            # Sort by length descending to find the longest match first
-            matched_prefix = known_prefixes.sort_by(&:length).reverse.find { |p| token.start_with?(p) }
-            log_debug "[ApiKeys Auth] Known prefixes: #{known_prefixes}. Matched prefix for lookup: #{matched_prefix || 'None'}"
-          end
+        if cache_ttl > 0 && verified_key
+          safe_cache_write(cache_key, verified_key.id, expires_in: cache_ttl)
+        end
 
-          possible_keys_scope = if matched_prefix
-                                  ApiKeys::ApiKey.where(prefix: matched_prefix, digest_algorithm: 'bcrypt')
-                                else
-                                  # This path is now less likely but covers cases where token matches no known prefix.
-                                  log_warn "[ApiKeys Auth] Token does not start with the configured prefix or any known prefix. Cannot perform DB lookup."
-                                  ApiKeys::ApiKey.none # Return an empty relation
-                                end
-
-          log_debug "[ApiKeys Auth] DB Query Scope SQL (bcrypt): #{possible_keys_scope.to_sql}" if possible_keys_scope.respond_to?(:to_sql)
-          possible_keys = possible_keys_scope.to_a
-          log_debug "[ApiKeys Auth] Found #{possible_keys.count} potential key(s) with matching prefix and algorithm for bcrypt."
-
-          # Securely compare the provided token against the digests of potential keys
-          verified_key = possible_keys.find do |key|
-            match_result = Digestor.match?(token: token, stored_digest: key.token_digest, strategy: :bcrypt)
-            log_debug "[ApiKeys Auth] Comparing with Key ID: #{key.id} (bcrypt). Match result: #{match_result}"
-            match_result
-          end
+        verified_key
+      end
+
+      def self.find_sha256_key(token)
+        token_digest = Digest::SHA256.hexdigest(token)
+        key = ApiKeys::ApiKey.find_by(token_digest: token_digest, digest_algorithm: "sha256")
+        key if key && verify_record_token(key, token)
+      end
 
-        elsif strategy == :sha256
-          # For sha256, we hash the incoming token and look for an exact match
-          # Note: Prefix lookup isn't useful here as the full hash is needed for the query.
-          token_digest = Digest::SHA256.hexdigest(token)
-          log_debug "[ApiKeys Auth] Calculated SHA256 digest for lookup: #{token_digest}"
+      def self.find_bcrypt_key(token, config)
+        return nil if token.bytesize > Digestor::BCRYPT_MAX_SECRET_BYTESIZE
 
-          # Find the key directly by the calculated digest and algorithm
-          verified_key = ApiKeys::ApiKey.find_by(token_digest: token_digest, digest_algorithm: 'sha256')
+        cached_prefixes = fetch_known_prefixes(config)
+        return find_bcrypt_key_by_last4(token) unless cached_prefixes
 
-          if verified_key
-            log_debug "[ApiKeys Auth] Found matching key by SHA256 digest. Key ID: #{verified_key.id}"
-          else
-            log_debug "[ApiKeys Auth] No key found matching the SHA256 digest."
-          end
+        key = find_bcrypt_key_for_prefixes(token, cached_prefixes)
+        return key if key
 
-        else
-          # Log unsupported strategy
-          log_warn "[ApiKeys Auth] Authentication attempt with unsupported hash strategy: #{strategy}"
-        end
+        # Prefix caching is only a hint. A stale or poisoned cache entry must not
+        # strand a valid bcrypt key, so retry once with authoritative DB values.
+        fresh_prefixes = fetch_known_prefixes_from_database
+        return find_bcrypt_key_by_last4(token) unless fresh_prefixes
+        return nil if fresh_prefixes == cached_prefixes
+
+        cache_ttl = normalized_cache_ttl(config.cache_ttl)
+        safe_cache_write(KNOWN_PREFIXES_CACHE_KEY, fresh_prefixes, expires_in: cache_ttl) if cache_ttl > 0
+        find_bcrypt_key_for_prefixes(token, fresh_prefixes)
+      end
 
-        log_debug "[ApiKeys Auth] DB Verification result: #{verified_key ? "Key ID: #{verified_key.id}" : 'No match'}"
-        # --- End DB Lookup ---
+      def self.find_bcrypt_key_for_prefixes(token, prefixes)
+        matched_prefix = prefixes.sort_by(&:bytesize).reverse_each.find { |prefix| token.start_with?(prefix) }
+        return nil unless matched_prefix
 
-        # Cache the result (either the found ApiKey instance or nil for a miss)
-        if cache_ttl > 0 && rails_cache
-          log_debug "[ApiKeys Auth] Writing result to cache. Key: #{cache_key}, Value: #{verified_key.inspect}"
-          rails_cache.write(cache_key, verified_key, expires_in: cache_ttl)
+        random_part = token.delete_prefix(matched_prefix)
+        return nil if random_part.length < 4
+
+        candidates = ApiKeys::ApiKey.where(
+          prefix: matched_prefix,
+          last4: random_part.last(4),
+          digest_algorithm: "bcrypt"
+        )
+        find_verified_bcrypt_candidate(candidates, token)
+      end
+
+      # If a deployment has an unusually large number of historical prefixes,
+      # avoid materializing them all in a request. `last4` is the last four
+      # characters of the complete generated token as well as of its random
+      # component, and every install has an index on that column.
+      def self.find_bcrypt_key_by_last4(token)
+        return nil if token.length < 4
+
+        candidates = ApiKeys::ApiKey.where(last4: token.last(4), digest_algorithm: "bcrypt")
+        find_verified_bcrypt_candidate(candidates, token)
+      end
+
+      def self.find_verified_bcrypt_candidate(relation, token)
+        candidates = relation.limit(MAX_BCRYPT_CANDIDATES + 1).to_a
+
+        if candidates.length > MAX_BCRYPT_CANDIDATES
+          log_warn "[ApiKeys Security] Rejected an overfull bcrypt authentication candidate set."
+          return nil
         end
 
-        verified_key
+        candidates.find do |candidate|
+          candidate.prefix.is_a?(String) && token.start_with?(candidate.prefix) &&
+            verify_record_token(candidate, token)
+        end
+      end
+
+      def self.verify_record_token(api_key, token)
+        strategy = api_key.digest_algorithm.to_s
+        return false unless %w[sha256 bcrypt].include?(strategy)
+
+        Digestor.match?(token: token, stored_digest: api_key.token_digest, strategy: strategy.to_sym)
       end
 
       # Helper to fetch (and cache) the distinct prefixes stored in the ApiKey table.
       def self.fetch_known_prefixes(config)
-        cache_key = "api_keys:known_prefixes"
-        cache_ttl = config.cache_ttl.to_i # Use the same TTL as key lookup for consistency
+        cache_ttl = normalized_cache_ttl(config.cache_ttl)
 
         if cache_ttl > 0
-          cached_prefixes = rails_cache&.read(cache_key)
-          return cached_prefixes if cached_prefixes.is_a?(Array)
+          cached_prefixes = safe_cache_read(KNOWN_PREFIXES_CACHE_KEY)
+          if cached_prefixes.is_a?(Array)
+            sanitized_prefixes = sanitize_prefixes(cached_prefixes)
+            return sanitized_prefixes if sanitized_prefixes
+
+            log_warn "[ApiKeys Security] Ignored an overfull known-prefix cache entry."
+            return nil
+          end
           log_debug "[ApiKeys Auth] Known prefixes cache MISS. Fetching from DB."
         end
 
         # Fetch distinct, non-null prefixes from the database
-        prefixes = ApiKeys::ApiKey.distinct.pluck(:prefix).compact
+        prefixes = fetch_known_prefixes_from_database
 
-        if cache_ttl > 0 && rails_cache
-          log_debug "[ApiKeys Auth] Writing known prefixes to cache. Key: #{cache_key}, Value: #{prefixes.inspect}"
-          rails_cache.write(cache_key, prefixes, expires_in: cache_ttl)
+        if cache_ttl > 0 && prefixes
+          safe_cache_write(KNOWN_PREFIXES_CACHE_KEY, prefixes, expires_in: cache_ttl)
         end
 
         prefixes
       end
 
+      def self.fetch_known_prefixes_from_database
+        prefixes = ApiKeys::ApiKey.distinct.limit(MAX_KNOWN_PREFIXES + 1).pluck(:prefix)
+        sanitize_prefixes(prefixes)
+      end
+
+      def self.clear_known_prefixes_cache
+        cache = rails_cache
+        return unless cache
+
+        cache.delete(KNOWN_PREFIXES_CACHE_KEY)
+      rescue StandardError => error
+        log_warn "[ApiKeys Auth] Cache delete failed (#{error.class}); continuing safely."
+      end
+
       # Helper for accessing Rails cache safely
       def self.rails_cache
         defined?(Rails) ? Rails.cache : nil
       end
 
+      def self.safe_cache_read(key)
+        rails_cache&.read(key)
+      rescue StandardError => error
+        log_warn "[ApiKeys Auth] Cache read failed (#{error.class}); falling back to the database."
+        nil
+      end
+
+      def self.safe_cache_write(key, value, expires_in:)
+        rails_cache&.write(key, value, expires_in: expires_in)
+      rescue StandardError => error
+        log_warn "[ApiKeys Auth] Cache write failed (#{error.class}); authentication result was not cached."
+        false
+      end
+
+      def self.normalized_cache_ttl(value)
+        ttl = value.nil? ? 0 : value.to_f
+        ttl.positive? ? ttl : 0
+      rescue ArgumentError, TypeError
+        0
+      end
+
+      def self.cache_identifier?(value)
+        (value.is_a?(Integer) && value >= 0 && value.to_s.bytesize <= 128) ||
+          (value.is_a?(String) && value.bytesize <= 128 && value.match?(/\A[[:alnum:]_-]+\z/))
+      end
+
+      def self.safe_find_by_id(id)
+        ApiKeys::ApiKey.find_by(id: id)
+      rescue StandardError => error
+        log_warn "[ApiKeys Auth] Ignored an invalid cached key identifier (#{error.class})."
+        nil
+      end
+
+      def self.sanitize_prefixes(prefixes)
+        return nil unless prefixes.is_a?(Array)
+        return nil if prefixes.length > MAX_KNOWN_PREFIXES
+
+        prefixes.filter_map do |prefix|
+          prefix if prefix.is_a?(String) && prefix.present? && prefix.valid_encoding? && prefix.bytesize <= 64
+        end.uniq
+      end
+
+      def self.valid_token?(token)
+        return false unless token.is_a?(String)
+        return false if token.empty? || token.bytesize > MAX_TOKEN_BYTESIZE || !token.valid_encoding?
+
+        token.each_codepoint.none? { |codepoint| codepoint <= 0x20 || codepoint == 0x7f }
+      rescue ArgumentError
+        false
+      end
+
+      def self.production_environment?
+        defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+      end
+
+      def self.secure_request?(request)
+        return request.ssl? if request.respond_to?(:ssl?)
+
+        request.respond_to?(:protocol) && request.protocol == "https://"
+      end
+
+      def self.check_key_type_configuration(api_key, config)
+        return nil unless api_key&.key_type.present?
+
+        configured = config.key_types&.keys&.any? { |type| type.to_s == api_key.key_type.to_s }
+        return nil if configured
+
+        log_warn "[ApiKeys Security] Rejected API key ID #{api_key.id} because its key type is not configured."
+        Result.failure(error_code: :unknown_key_type, message: "API key type is not configured")
+      end
+
+      def self.check_environment_configuration(api_key, config)
+        return nil unless api_key&.key_type.present?
+
+        configured = if api_key.environment.present? && config.environments.present?
+                       config.environments.keys.any? { |environment| environment.to_s == api_key.environment.to_s }
+                     else
+                       api_key.environment.present?
+                     end
+        return nil if configured
+
+        log_warn "[ApiKeys Security] Rejected API key ID #{api_key.id} because its environment is not configured."
+        Result.failure(error_code: :unknown_environment, message: "API key environment is not configured")
+      end
+
       # Check if the API key's environment matches the current environment
       # Returns a failure Result if there's a mismatch and strict isolation is enabled
       # Returns nil if the check passes or is not applicable
       def self.check_environment_isolation(api_key, config)
         return nil unless config.strict_environment_isolation
 
-        # Skip check if key doesn't have an environment (legacy keys)
+        # Untyped legacy keys predate environment support and remain exempt.
         key_env = api_key.environment
-        return nil if key_env.blank?
+        return nil if key_env.blank? && api_key.key_type.blank?
+        if key_env.blank?
+          return Result.failure(
+            error_code: :environment_misconfigured,
+            message: "API key environment could not be verified"
+          )
+        end
 
         # Get current environment
         current_env_config = config.current_environment
-        current_env = current_env_config.respond_to?(:call) ? current_env_config.call : current_env_config
+        begin
+          current_env = current_env_config.respond_to?(:call) ? current_env_config.call : current_env_config
+        rescue StandardError => error
+          log_warn "[ApiKeys Security] Current environment resolution failed (#{error.class})."
+          return Result.failure(
+            error_code: :environment_misconfigured,
+            message: "API key environment could not be verified"
+          )
+        end
 
         # Normalize to string first, then check if blank
         # This ensures consistent string comparison and prevents edge cases with empty strings
         current_env = current_env.to_s
         key_env = key_env.to_s
 
-        # Skip isolation check if current environment is blank (not properly configured)
+        # Strict isolation must fail closed when the current environment cannot be resolved.
         if current_env.blank?
-          log_debug "[ApiKeys Auth] Current environment is blank, skipping environment isolation check"
-          return nil
+          log_warn "[ApiKeys Security] Strict environment isolation is enabled, but current_environment resolved to blank."
+          return Result.failure(
+            error_code: :environment_misconfigured,
+            message: "API key environment could not be verified"
+          )
         end
 
         if current_env != key_env
-          log_debug "[ApiKeys Auth] Environment mismatch: Key environment '#{key_env}' does not match current environment '#{current_env}'"
+          log_debug "[ApiKeys Auth] Environment mismatch for key ID #{api_key.id}."
           return Result.failure(
             error_code: :environment_mismatch,
-            message: "API key environment (#{key_env}) does not match current environment (#{current_env})"
+            message: "API key cannot be used in this environment"
           )
         end
 
         nil # Check passed
       end
 
-      # NOTE: Removing the incorrect private `find_key_by_token` method.
-      # def find_key_by_token(token)
-      #   ...
-      # end
+      private_class_method :extract_token, :find_and_verify_key, :find_sha256_key,
+                           :find_bcrypt_key, :find_bcrypt_key_for_prefixes,
+                           :find_bcrypt_key_by_last4, :find_verified_bcrypt_candidate,
+                           :verify_record_token, :fetch_known_prefixes,
+                           :fetch_known_prefixes_from_database, :rails_cache,
+                           :safe_cache_read, :safe_cache_write,
+                           :normalized_cache_ttl, :cache_identifier?,
+                           :safe_find_by_id, :sanitize_prefixes, :valid_token?,
+                           :production_environment?, :secure_request?,
+                           :check_key_type_configuration, :check_environment_configuration,
+                           :check_environment_isolation
     end
   end
 end

data/lib/api_keys/services/digestor.rb

@@ -7,6 +7,17 @@ module ApiKeys
   module Services
     # Handles hashing (digesting) and verifying tokens based on configured strategy.
     class Digestor
+      BCRYPT_MAX_SECRET_BYTESIZE = if BCrypt::Engine.const_defined?(:MAX_SECRET_BYTESIZE)
+                                      BCrypt::Engine::MAX_SECRET_BYTESIZE
+                                    else
+                                      72
+                                    end
+      # Costs above this value can turn a malformed/imported database row into
+      # a multi-second (or worse) CPU denial of service during authentication.
+      # The default bcrypt cost is comfortably below this ceiling.
+      BCRYPT_MAX_SAFE_COST = 16
+      MAX_TOKEN_BYTESIZE = 512
+
       # Creates a digest of the given token using the configured strategy.
       #
       # @param token [String] The plaintext token.
@@ -14,8 +25,20 @@ module ApiKeys
       # @return [Hash] A hash containing the digest and the algorithm used.
       #   e.g., { digest: "...", algorithm: "bcrypt" }
       def self.digest(token:, strategy: ApiKeys.configuration.hash_strategy)
+        validate_token!(token)
+
         case strategy
         when :bcrypt
+          if token.bytesize > BCRYPT_MAX_SECRET_BYTESIZE
+            raise ArgumentError,
+              "BCrypt tokens must not exceed #{BCRYPT_MAX_SECRET_BYTESIZE} bytes because BCrypt truncates longer inputs."
+          end
+
+          unless safe_bcrypt_cost?(BCrypt::Engine.cost)
+            raise ArgumentError,
+              "BCrypt cost must be between #{BCrypt::Engine::MIN_COST} and #{BCRYPT_MAX_SAFE_COST}."
+          end
+
           # BCrypt handles salt generation internally
           digest = BCrypt::Password.create(token, cost: BCrypt::Engine.cost)
           { digest: digest.to_s, algorithm: "bcrypt" }
@@ -38,21 +61,24 @@ module ApiKeys
       # @param comparison_proc [Proc] The secure comparison function.
       # @return [Boolean] True if the token matches the digest, false otherwise.
       def self.match?(token:, stored_digest:, strategy: ApiKeys.configuration.hash_strategy, comparison_proc: ApiKeys.configuration.secure_compare_proc)
-        return false if token.blank? || stored_digest.blank?
+        return false unless valid_match_inputs?(token, stored_digest)
 
         case strategy
         when :bcrypt
-          begin
-            bcrypt_object = BCrypt::Password.new(stored_digest)
-            # BCrypt's `==` operator is designed for secure comparison
-            bcrypt_object == token
-          rescue BCrypt::Errors::InvalidHash
-            # If the stored digest isn't a valid BCrypt hash, comparison fails
-            false
-          end
+          return false if token.bytesize > BCRYPT_MAX_SECRET_BYTESIZE
+
+          bcrypt_object = validated_bcrypt_password(stored_digest)
+          return false unless bcrypt_object
+
+          # BCrypt's `==` operator is designed for secure comparison.
+          bcrypt_object == token
         when :sha256
           # Directly compare the SHA256 hash of the input token with the stored digest
-          comparison_proc.call(stored_digest, Digest::SHA256.hexdigest(token))
+          return false unless stored_digest.match?(/\A\h{64}\z/)
+
+          # A custom comparator is security-sensitive. Accept only the literal
+          # boolean true so truthy sentinel/error values can never authenticate.
+          comparison_proc.call(stored_digest, Digest::SHA256.hexdigest(token)) == true
         else
           # Strategy mismatch or unsupported strategy should fail comparison safely
           if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
@@ -60,13 +86,50 @@ module ApiKeys
           end
           false
         end
-      rescue ArgumentError => e
-        # Catch potential errors from Digest or comparison proc
+      rescue StandardError => error
+        # A malformed digest or application-supplied comparison proc must never
+        # turn an authentication failure into an exception or an availability issue.
         if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-          Rails.logger.error "[ApiKeys] Digestor comparison error: #{e.message}"
+          Rails.logger.error "[ApiKeys] Digestor comparison error (#{error.class})."
         end
         false
       end
+
+      # Returns whether a stored bcrypt digest is structurally valid and has a
+      # bounded cost that is safe to evaluate on an authentication request.
+      def self.valid_bcrypt_digest?(stored_digest)
+        !validated_bcrypt_password(stored_digest).nil?
+      end
+
+      def self.validate_token!(token)
+        valid = token.is_a?(String) && token.present? && token.valid_encoding? && token.bytesize <= MAX_TOKEN_BYTESIZE
+        return if valid
+
+        raise ArgumentError, "Token must be a non-blank valid string of at most #{MAX_TOKEN_BYTESIZE} bytes."
+      end
+
+      def self.valid_match_inputs?(token, stored_digest)
+        token.is_a?(String) && token.present? && token.valid_encoding? && token.bytesize <= MAX_TOKEN_BYTESIZE &&
+          stored_digest.is_a?(String) && stored_digest.present? && stored_digest.valid_encoding? &&
+          stored_digest.bytesize <= 128
+      rescue ArgumentError
+        false
+      end
+
+      def self.validated_bcrypt_password(stored_digest)
+        return nil unless stored_digest.is_a?(String) && stored_digest.valid_encoding? && stored_digest.bytesize <= 128
+
+        password = BCrypt::Password.new(stored_digest)
+        password if safe_bcrypt_cost?(password.cost)
+      rescue BCrypt::Error, ArgumentError
+        nil
+      end
+
+      def self.safe_bcrypt_cost?(cost)
+        cost.is_a?(Integer) && cost.between?(BCrypt::Engine::MIN_COST, BCRYPT_MAX_SAFE_COST)
+      end
+
+      private_class_method :validate_token!, :valid_match_inputs?, :validated_bcrypt_password, :safe_bcrypt_cost?
     end
   end
 end