api_keys 0.1.0

data/lib/api_keys/models/api_key.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "active_record"
+require_relative "../services/token_generator"
+require_relative "../services/digestor"
+
+module ApiKeys
+  # The core ActiveRecord model representing an API key.
+  class ApiKey < ActiveRecord::Base
+    self.table_name = "api_keys"
+
+    # == Concerns ==
+    # TODO: Potentially extract token generation/hashing logic into concerns
+
+    # == Associations ==
+    belongs_to :owner, polymorphic: true, optional: true
+
+    # == Attributes & Serialization ==
+    # Expose the plaintext token only immediately after creation
+    attr_reader :token
+
+    # JSON attributes (:scopes, :metadata) are defined in the engine initializer
+    # using ActiveSupport.on_load(:active_record) to ensure DB connection is ready.
+
+    # == Validations ==
+    validates :token_digest, presence: true, uniqueness: { case_sensitive: true }
+    validates :prefix, presence: true
+    validates :digest_algorithm, presence: true
+    validates :last4, presence: true, length: { is: 4 }
+    # validates :scopes, presence: true # Default handled by attribute def
+    # validates :metadata, presence: true # Default handled by attribute def
+    validates :name,
+              length: { maximum: 60 },
+              # Allow letters, numbers, underscores, hyphens, and spaces. No leading/trailing spaces.
+              format: { with: /\A[a-zA-Z0-9_ -]+\z/, message: "can only contain letters, numbers, underscores, hyphens, and spaces (no leading / trailing spaces)" },
+              allow_blank: true # Apply length and format only if name is present
+
+    validates :name, presence: true, if: :name_required? # Only require presence conditionally
+    validate :within_quota, on: :create, if: -> { owner.present? && (owner_configured? || ApiKeys.configuration.default_max_keys_per_owner.present?) }
+
+    # TODO: Add validation for expires_at > Time.current if present
+    validate :expiration_date_cannot_be_in_the_past, if: :expires_at?
+
+    # TODO: Add validation for scope string format
+    # TODO: Add validation for prefix format (e.g., must end with _)
+
+    # == Callbacks ==
+    before_validation :set_defaults, on: :create
+    # Generate digest BEFORE validation runs
+    before_validation :generate_token_and_digest, on: :create
+
+    # == Scopes ==
+    scope :active, -> { where(revoked_at: nil).where("expires_at IS NULL OR expires_at > ?", Time.current) }
+    scope :revoked, -> { where.not(revoked_at: nil) }
+    scope :expired, -> { where("expires_at <= ?", Time.current) }
+    scope :inactive, -> { revoked.or(expired) }
+    scope :for_prefix, ->(prefix) { where(prefix: prefix) }
+    scope :for_owner, ->(owner) { where(owner: owner) }
+    # TODO: Add more scopes as needed (e.g., for_owner)
+
+    # == Instance Methods ==
+
+    def revoke!
+      update!(revoked_at: Time.current)
+    end
+
+    def revoked?
+      revoked_at.present?
+    end
+
+    def expired?
+      expires_at? && expires_at <= Time.current
+    end
+
+    def active?
+      !revoked? && !expired?
+    end
+
+    # Basic scope check. Assumes scopes are stored as an array of strings.
+    # Returns true if the key has no specific scopes (allowing all) or includes the required scope.
+    def allows_scope?(required_scope)
+      # Type casting for scopes/metadata happens via the attribute definition in the engine.
+      # Ensure the attribute is loaded/defined before using it.
+      # Check if the attribute method exists before calling .blank? or .include?
+      return true unless respond_to?(:scopes) # Guard clause if loaded before attribute definition
+      scopes.blank? || scopes.include?(required_scope.to_s)
+    end
+
+    # Provides a masked version of the token for display (e.g., ak_live_••••rj4p)
+    # Requires the plaintext token to be available (only right after creation).
+    def masked_token
+      # return "[Token not available]" unless token # No longer needed
+      # Show prefix, 4 bullets, last 4 chars of the random part
+      # random_part = token.delete_prefix(prefix) # No longer needed
+      # "#{prefix}••••#{random_part.last(4)}" # No longer needed
+
+      # Use the stored prefix and last4 attributes
+      return "[Invalid Key Data]" unless prefix.present? && last4.present?
+      "#{prefix}••••#{last4}"
+    end
+
+    # == Class Methods ==
+    # Most creation logic is handled by standard ActiveRecord methods + callbacks
+
+    private
+
+    # Set defaults for attributes not handled by the `attribute` API in the engine.
+    def set_defaults
+      # NOTE: Defaults for scopes/metadata handled by `attribute` definitions in engine initializer.
+
+      # Determine the prefix: owner-specific setting > global config
+      # Note: `owner` might not be set yet if called outside normal AR flow.
+      owner_prefix_config = nil
+      if owner.present? && owner.class.respond_to?(:api_keys_settings)
+        owner_prefix_config = owner.class.api_keys_settings[:token_prefix]
+      end
+
+      # Use owner setting if present, otherwise fall back to global config
+      prefix_config = owner_prefix_config || ApiKeys.configuration.token_prefix
+
+      # Evaluate the prefix config (it might be a Proc)
+      # Ensure `self.prefix` is only set if it's not already present.
+      self.prefix ||= prefix_config.is_a?(Proc) ? prefix_config.call : prefix_config
+
+      # Removed default scopes logic here. It's correctly handled in the
+      # HasApiKeys#create_api_key! helper method, which is the intended
+      # way to create keys with proper default scope application.
+    end
+
+    # Generates the secure token, hashes it, and sets relevant attributes.
+    # Called before validation on create.
+    def generate_token_and_digest
+      # Generate token only if digest isn't already set (allows creating records with pre-hashed keys if needed)
+      return if token_digest.present?
+
+      # Ensure prefix default is set if needed (e.g., if validation skipped or called directly)
+      set_defaults unless self.prefix.present?
+
+      # Use the configured generator
+      generated_token = ApiKeys::Services::TokenGenerator.call(prefix: self.prefix)
+      @token = generated_token # Store plaintext temporarily in instance var for display
+
+      # Safety check: Ensure generated token starts with the expected prefix
+      unless @token.start_with?(self.prefix)
+        raise ApiKeys::Error, "Generated token '#{@token}' does not match expected prefix '#{self.prefix}'. Check TokenGenerator."
+      end
+
+      # Use the configured digestor
+      digest_result = ApiKeys::Services::Digestor.digest(token: @token)
+
+      self.token_digest = digest_result[:digest]
+      self.digest_algorithm = digest_result[:algorithm]
+
+      # Extract and store the last 4 chars of the random part
+      random_part = @token.delete_prefix(self.prefix)
+      self.last4 = random_part.last(4) # Store last4
+
+      # Set default expiration if configured globally and not set individually
+      # Needs to happen here since it relies on Time.current
+      if ApiKeys.configuration.expire_after.present? && self.expires_at.nil?
+        self.expires_at = ApiKeys.configuration.expire_after.from_now
+      end
+    end
+
+    # == Validation Helpers ==
+
+    def owner_present_and_configured?
+      owner.present? && owner_configured?
+    end
+
+    def owner_configured?
+      owner.class.respond_to?(:api_keys_settings)
+    end
+
+    def name_required?
+      if owner_configured?
+        owner.class.api_keys_settings[:require_name]
+      else
+        ApiKeys.configuration.require_key_name
+      end
+    end
+
+    def within_quota
+      # Determine the applicable limit: owner-specific setting first, then global config.
+      limit = if owner_configured?
+                owner.class.api_keys_settings[:max_keys]
+              else
+                ApiKeys.configuration.default_max_keys_per_owner
+              end
+
+      # Only validate if a limit is actually set (either per-owner or globally).
+      return unless limit.present?
+
+      # Count only *active* keys for the quota check.
+      # Ensure `owner` association is loaded if needed, or use SQL count.
+      # Note: Ensure the owner association is set before this validation runs.
+      current_active_keys = owner.api_keys.active.count
+
+      if current_active_keys >= limit
+        errors.add(:base, "exceeds maximum allowed API keys (#{limit}) for this owner")
+      end
+    end
+
+    def expiration_date_cannot_be_in_the_past
+      errors.add(:expires_at, "can't be in the past") if expires_at.present? && expires_at < Time.current
+    end
+
+  end
+end

data/lib/api_keys/models/concerns/has_api_keys.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module ApiKeys
+  module Models
+    module Concerns
+      # Concern to add API key capabilities to an owner model (e.g., User, Organization).
+      # This module provides the `has_api_keys` class method when extended onto ActiveRecord::Base.
+      module HasApiKeys
+        extend ActiveSupport::Concern
+
+        # Module containing class methods to be extended onto ActiveRecord::Base
+        module ClassMethods
+          # Defines the association and allows configuration for the specific owner model.
+          #
+          # Example:
+          #   class User < ApplicationRecord
+          #     # Using keyword arguments:
+          #     has_api_keys max_keys: 5, require_name: true
+          #
+          #     # Or using a block:
+          #     has_api_keys do
+          #       max_keys 10
+          #       require_name false
+          #       default_scopes %w[read write]
+          #     end
+          #   end
+          def has_api_keys(**options, &block)
+            # Include the concern's instance methods into the calling class (e.g., User)
+            # Ensures any instance-level helpers in HasApiKeys are available on the owner.
+            include ApiKeys::Models::Concerns::HasApiKeys unless included_modules.include?(ApiKeys::Models::Concerns::HasApiKeys)
+
+            # Define the core association on the specific class calling this method
+            has_many :api_keys,
+                     class_name: "ApiKeys::ApiKey",
+                     as: :owner,
+                     dependent: :destroy # Consider :nullify based on requirements
+
+            # Define class_attribute for settings if not already defined.
+            # This ensures inheritance works correctly (subclasses get their own copy).
+            unless respond_to?(:api_keys_settings)
+              class_attribute :api_keys_settings, instance_writer: false, default: {}
+            end
+
+            # Initialize settings for this specific class, merging defaults and options
+            current_settings = {
+              # Default to global config values first
+              max_keys: ApiKeys.configuration&.default_max_keys_per_owner,
+              require_name: ApiKeys.configuration&.require_key_name,
+              default_scopes: ApiKeys.configuration&.default_scopes || []
+            }.merge(options) # Merge keyword arguments first
+
+            # Apply DSL block if provided, allowing overrides
+            if block_given?
+              dsl = DslProvider.new(current_settings)
+              dsl.instance_eval(&block)
+            end
+
+            # Assign the final settings hash to the class attribute for this class
+            self.api_keys_settings = current_settings
+
+            # TODO: Add validation hook to check key limit on create?
+            # validates_with ApiKeys::Validators::MaxKeysValidator, on: :create, if: -> { api_keys_settings[:max_keys].present? }
+          end
+        end
+
+        # DSL provider class to handle the block configuration
+        class DslProvider # Keep nested or move to a separate file if it grows
+          def initialize(settings)
+            @settings = settings # Operates directly on the hash passed in
+          end
+
+          def max_keys(value)
+            @settings[:max_keys] = value
+          end
+
+          def require_name(value)
+            @settings[:require_name] = value
+          end
+
+          def default_scopes(value)
+            @settings[:default_scopes] = Array(value)
+          end
+
+          # Placeholder for future scope definitions
+          # def define_scope(name, description:)
+          #   # In v1, this might just store metadata for documentation/future use
+          #   # Could store in a separate class attribute or within settings hash.
+          #   @settings[:defined_scopes] ||= {}
+          #   @settings[:defined_scopes][name.to_s] = description
+          # end
+        end
+
+        # --- Instance Methods ---
+        # Methods included in the owner model (e.g., User).
+
+        # Creates a new API key for this owner instance and returns the ApiKey instance.
+        # Raises ActiveRecord::RecordInvalid if creation fails.
+        #
+        # @param name [String] The name for the new API key (required).
+        # @param scopes [Array<String>, nil] Scopes for the key. Defaults to owner/global settings.
+        # @param expires_at [Time, nil] Optional expiration timestamp.
+        # @param metadata [Hash, nil] Optional metadata hash.
+        # @return [ApiKeys::ApiKey] The newly created ApiKey instance. The plaintext token
+        #                           is available via the `#token` attribute on this instance
+        #                           *only until it's reloaded*.
+        def create_api_key!(name: nil, scopes: nil, expires_at: nil, metadata: nil)
+          # Fetch default scopes from this owner class's settings, falling back to global config.
+          owner_settings = self.class.api_keys_settings
+          default_scopes = owner_settings&.[](:default_scopes) || ApiKeys.configuration.default_scopes || []
+
+          # Use provided scopes if given, otherwise use the calculated defaults.
+          key_scopes = scopes.nil? ? default_scopes : Array(scopes)
+
+          # Create the key using the association, letting AR handle owner_id/type.
+          api_key = self.api_keys.create!(
+            name: name,
+            scopes: key_scopes,
+            expires_at: expires_at,
+            metadata: metadata || {} # Ensure metadata is at least an empty hash
+            # prefix, token_digest, digest_algorithm are set by ApiKey callbacks
+          )
+
+          # Return the ApiKey instance itself.
+          # The plaintext token is available via `api_key.token` immediately after this.
+          api_key
+        end
+
+        # Example: Check if the owner has reached their API key limit.
+        # def reached_api_key_limit?
+        #   limit = self.class.api_keys_settings[:max_keys]
+        #   # Ensure api_keys association is loaded or query count
+        #   limit && api_keys.count >= limit # Or use a counter cache
+        # end
+
+        # Example: Get the specific settings for this owner instance's class.
+        # def api_keys_config
+        #   self.class.api_keys_settings
+        # end
+      end
+    end
+  end
+end

data/lib/api_keys/services/authenticator.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "active_support/cache"
+require "active_support/core_ext/object/blank"
+require "digest"
+require_relative "../models/api_key"
+require_relative "../services/digestor"
+require_relative "../logging"
+
+module ApiKeys
+  module Services
+    # Authenticates an incoming request by extracting and verifying an API key.
+    class Authenticator
+      extend ApiKeys::Logging
+
+      # Result object for authentication attempts.
+      Result = Struct.new(:success?, :api_key, :error_code, :message, keyword_init: true) do
+        def self.success(api_key)
+          new(success?: true, api_key: api_key)
+        end
+
+        def self.failure(error_code:, message:)
+          new(success?: false, error_code: error_code, message: message)
+        end
+      end
+
+      # Authenticates the request.
+      #
+      # @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}"
+        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://"
+            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
+            end
+          end
+        end
+        # === End HTTPS Check ===
+
+        token = extract_token(request, config)
+
+        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
+        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?
+                   log_debug "[ApiKeys Auth] Verification successful. Key ID: #{api_key.id}"
+                   # TODO: Optionally update last_used_at and requests_count
+                   Result.success(api_key)
+                 elsif api_key&.revoked?
+                   log_debug "[ApiKeys Auth] Verification failed: Key revoked. Key ID: #{api_key.id}"
+                   Result.failure(error_code: :revoked_key, message: "API key has been revoked")
+                 elsif api_key&.expired?
+                   log_debug "[ApiKeys Auth] Verification failed: Key expired. Key ID: #{api_key.id}"
+                   Result.failure(error_code: :expired_key, message: "API key has expired")
+                 else # Not found, mismatch, or inactive
+                   log_debug "[ApiKeys Auth] Verification failed: Token invalid or key not found."
+                   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)
+        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
+            # Handle "Bearer <token>" scheme
+            match = header_value.match(/^Bearer\s+(.*)$/i)
+            if match
+              log_debug "[ApiKeys Auth] Extracted token from Bearer scheme."
+              return match[1]
+            end
+            # Fallback: return the raw header value if no Bearer scheme
+            log_debug "[ApiKeys Auth] No Bearer scheme, using raw header value as token."
+            return header_value
+          end
+        end
+
+        # 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}'"
+          if param_value.present?
+            log_debug "[ApiKeys Auth] Extracted token from query parameter."
+            return param_value
+          end
+        end
+
+        log_debug "[ApiKeys Auth] No token found in headers or query parameters."
+        nil # No token found
+      end
+
+      # Finds the ApiKey record corresponding to the token and verifies it securely.
+      # Uses caching if enabled.
+      # @param token [String] The plaintext token from the request.
+      # @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}"
+
+        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."
+          end
+        end
+
+        # --- Cache miss or TTL=0: Perform DB lookup & verification ---
+        log_debug "[ApiKeys Auth] Performing DB lookup and verification."
+
+        # 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
+
+          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
+
+        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}"
+
+          # Find the key directly by the calculated digest and algorithm
+          verified_key = ApiKeys::ApiKey.find_by(token_digest: token_digest, digest_algorithm: 'sha256')
+
+          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
+
+        else
+          # Log unsupported strategy
+          log_warn "[ApiKeys Auth] Authentication attempt with unsupported hash strategy: #{strategy}"
+        end
+
+        log_debug "[ApiKeys Auth] DB Verification result: #{verified_key ? "Key ID: #{verified_key.id}" : 'No match'}"
+        # --- End DB Lookup ---
+
+        # 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)
+        end
+
+        verified_key
+      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
+
+        if cache_ttl > 0
+          cached_prefixes = rails_cache&.read(cache_key)
+          return cached_prefixes if cached_prefixes.is_a?(Array)
+          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
+
+        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)
+        end
+
+        prefixes
+      end
+
+      # Helper for accessing Rails cache safely
+      def self.rails_cache
+        defined?(Rails) ? Rails.cache : nil
+      end
+
+      # NOTE: Removing the incorrect private `find_key_by_token` method.
+      # def find_key_by_token(token)
+      #   ...
+      # end
+    end
+  end
+end

data/lib/api_keys/services/digestor.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "bcrypt"
+require "digest"
+
+module ApiKeys
+  module Services
+    # Handles hashing (digesting) and verifying tokens based on configured strategy.
+    class Digestor
+      # Creates a digest of the given token using the configured strategy.
+      #
+      # @param token [String] The plaintext token.
+      # @param strategy [Symbol] The hashing strategy (:bcrypt or :sha256).
+      # @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)
+        case strategy
+        when :bcrypt
+          # BCrypt handles salt generation internally
+          digest = BCrypt::Password.create(token, cost: BCrypt::Engine.cost)
+          { digest: digest.to_s, algorithm: "bcrypt" }
+        when :sha256
+          # Note: Simple SHA256 without salt/pepper. Consider enhancing if needed.
+          # BCrypt is generally preferred for password/token hashing.
+          digest = Digest::SHA256.hexdigest(token)
+          { digest: digest, algorithm: "sha256" }
+        else
+          raise ArgumentError, "Unsupported hash strategy: #{strategy}. Use :bcrypt or :sha256."
+        end
+      end
+
+      # Securely compares a plaintext token against a stored digest.
+      # Uses the configured secure comparison proc and hash strategy.
+      #
+      # @param token [String] The plaintext token provided by the user/client.
+      # @param stored_digest [String] The hashed digest stored in the database.
+      # @param strategy [Symbol] The hashing strategy used to create the stored_digest.
+      # @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?
+
+        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
+        when :sha256
+          # Directly compare the SHA256 hash of the input token with the stored digest
+          comparison_proc.call(stored_digest, Digest::SHA256.hexdigest(token))
+        else
+          # Strategy mismatch or unsupported strategy should fail comparison safely
+          Rails.logger.error "[ApiKeys] Digestor comparison failed: Unsupported hash strategy '#{strategy}' for digest check." if defined?(Rails.logger)
+          false
+        end
+      rescue ArgumentError => e
+        # Catch potential errors from Digest or comparison proc
+        Rails.logger.error "[ApiKeys] Digestor comparison error: #{e.message}" if defined?(Rails.logger)
+        false
+      end
+    end
+  end
+end