api_keys 0.1.0

data/lib/api_keys/authentication.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require_relative "services/authenticator"
+require_relative "logging"
+require_relative "jobs/update_stats_job"
+require_relative "jobs/callbacks_job"
+
+module ApiKeys
+  # Controller concern for handling API key authentication.
+  # Provides `authenticate_api_key!` method and helper methods.
+  module Authentication
+    extend ActiveSupport::Concern
+    include ApiKeys::Logging
+
+    included do
+      # Helper methods to access the authenticated key and its owner
+      helper_method :current_api_key, :current_api_owner, :current_api_user
+    end
+
+    # Returns the currently authenticated API key instance if authentication was
+    # successful, otherwise returns nil.
+    #
+    # @return [ApiKeys::ApiKey, nil]
+    def current_api_key
+      @current_api_key
+    end
+
+    # Returns the owner of the currently authenticated ApiKey, if any.
+    # @return [Object, nil] The polymorphic owner instance (e.g., User).
+    def current_api_owner
+      current_api_key&.owner
+    end
+
+    # Convenience helper: returns the owner if it's a User instance.
+    # @return [User, nil]
+    def current_api_user
+      owner = current_api_owner
+      owner if owner.is_a?(::User) # Assumes a User class exists
+    end
+
+    private
+
+    # The core authentication method.
+    def authenticate_api_key!(scope: nil)
+      log_debug "[ApiKeys Auth] authenticate_api_key! started for request: #{request.uuid}"
+
+      # Enqueue before_authentication callback asynchronously
+      enqueue_callback(:before_authentication, { request_uuid: request.uuid })
+
+      # Perform synchronous authentication
+      result = Services::Authenticator.call(request)
+      log_debug "[ApiKeys Auth] Authenticator result: #{result.inspect}"
+
+      # Prepare context for after_authentication callback
+      after_auth_context = {
+        success: result.success?,
+        error_code: result.error_code,
+        message: result.message,
+        api_key_id: result.api_key&.id # Pass ID only, not the full object
+      }
+
+      if result.success?
+        @current_api_key = result.api_key
+        log_debug "[ApiKeys Auth] Authentication successful. Key ID: #{@current_api_key.id}"
+
+        if scope && !check_api_key_scopes(scope)
+          log_debug "[ApiKeys Auth] Scope check failed. Required: #{scope}, Key scopes: #{@current_api_key.scopes}"
+          # Add required scope info to context before rendering/enqueueing
+          after_auth_context[:required_scope_check] = { required: scope, passed: false }
+          render_unauthorized(error_code: :missing_scope, message: "API key does not have the required scope(s): #{scope}", required_scope: scope)
+        else
+          after_auth_context[:required_scope_check] = { required: scope, passed: true } if scope
+          # Authentication and scope check successful, enqueue stats update
+          update_key_usage_stats # Enqueues UpdateStatsJob
+        end
+      else
+        # Authentication failed
+        log_debug "[ApiKeys Auth] Authentication failed. Error: #{result.error_code}, Message: #{result.message}"
+        render_unauthorized(error_code: result.error_code, message: result.message)
+      end
+
+      # Enqueue after_authentication callback asynchronously regardless of success/failure
+      enqueue_callback(:after_authentication, after_auth_context)
+    end
+
+    # Checks if the current_api_key has the required scope(s).
+    # Handles single scope string or array of scopes.
+    #
+    # @param required_scopes [String, Array<String>] The required scope(s).
+    # @return [Boolean] True if the key has all required scopes, false otherwise.
+    def check_api_key_scopes(required_scopes)
+      return true unless current_api_key # Should not happen if authenticate_api_key! ran
+      return true if required_scopes.blank?
+
+      Array(required_scopes).all? do |req_scope|
+        current_api_key.allows_scope?(req_scope)
+      end
+    end
+
+    # Renders a standard JSON error response for authentication failures.
+    def render_unauthorized(error_code:, message:, status: :unauthorized, required_scope: nil)
+      error_message = I18n.t("api_keys.errors.#{error_code}", default: message) rescue message
+      response_body = { error: error_code, message: error_message }
+      response_body[:required_scope] = required_scope if error_code == :missing_scope && required_scope
+      render json: response_body, status: status
+    end
+
+    # Enqueues the UpdateStatsJob.
+    def update_key_usage_stats
+      # Return early if async operations are globally disabled
+      return unless ApiKeys.configuration.enable_async_operations
+      return unless current_api_key
+
+      # Check ActiveJob configuration and warn if using suboptimal adapters
+      adapter = ActiveJob::Base.queue_adapter
+      if adapter.is_a?(ActiveJob::QueueAdapters::InlineAdapter)
+        log_warn "[ApiKeys] ActiveJob adapter is :inline. ApiKey stats updates will run synchronously within the request cycle, potentially impacting performance."
+      elsif adapter.is_a?(ActiveJob::QueueAdapters::AsyncAdapter)
+        log_warn "[ApiKeys] ActiveJob adapter is :async. ApiKey stats updates run in-process and may be lost on application restarts. Configure a persistent backend (Sidekiq, GoodJob, SolidQueue, etc.) for reliability."
+      end
+
+      begin
+        timestamp = Time.current # Capture time once for the job
+        log_debug "[ApiKeys Auth] Enqueuing UpdateStatsJob for ApiKey ID: #{current_api_key.id} at #{timestamp}"
+        ApiKeys::Jobs::UpdateStatsJob.perform_later(current_api_key.id, timestamp)
+      rescue StandardError => e
+        log_error "[ApiKeys Auth] Failed to enqueue UpdateStatsJob for key #{current_api_key.id}: #{e.message}"
+      end
+    end
+
+    # Helper to safely enqueue callback jobs.
+    def enqueue_callback(callback_type, context)
+      # Return early if async operations are globally disabled
+      return unless ApiKeys.configuration.enable_async_operations
+
+      # Determine the configuration method name (e.g., :before_authentication)
+      config_method = callback_type # Assuming callback_type directly matches config accessor
+
+      # Get the configured proc
+      callback_proc = ApiKeys.configuration.public_send(config_method)
+
+      # Skip enqueueing if the callback is the default empty proc
+      if callback_proc == ApiKeys::Configuration::DEFAULT_CALLBACK
+        log_debug "[ApiKeys Auth] Skipping enqueue for default empty callback: #{callback_type}"
+        return
+      end
+
+      # Proceed with enqueueing if it's a configured callback
+      begin
+        log_debug "[ApiKeys Auth] Enqueuing CallbacksJob for type: #{callback_type} with context: #{context.inspect}"
+        ApiKeys::Jobs::CallbacksJob.perform_later(callback_type, context)
+      rescue StandardError => e
+        log_error "[ApiKeys Auth] Failed to enqueue CallbacksJob for type #{callback_type}: #{e.message}"
+        # Don't fail the request if callback enqueueing fails
+      end
+    end
+
+  end
+end

data/lib/api_keys/configuration.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/numeric/time"
+require "active_support/security_utils"
+
+module ApiKeys
+  # Defines the configuration options for the ApiKeys gem.
+  # These options can be set in an initializer, e.g., config/initializers/api_keys.rb
+  class Configuration
+    # Default empty callback proc
+    DEFAULT_CALLBACK = ->(_context){}.freeze
+
+    # == Accessors ==
+
+    # Core Authentication
+    attr_accessor :header, :query_param
+
+    # Token Generation
+    attr_accessor :token_prefix, :token_length, :token_alphabet
+
+    # Storage & Verification
+    attr_accessor :hash_strategy, :secure_compare_proc, :key_store_adapter, :policy_provider
+
+    # Engine Configuration
+    attr_accessor :parent_controller
+
+    # Optional Behaviors
+    attr_accessor :default_max_keys_per_owner, :require_key_name
+    attr_accessor :expire_after, :default_scopes, :track_requests_count
+
+    # Performance
+    attr_accessor :cache_ttl
+
+    # Security
+    attr_accessor :https_only_production, :https_strict_mode
+
+    # Tenant Resolution
+    attr_accessor :tenant_resolver
+
+    # Callbacks (Placeholders for future extension)
+    attr_accessor :before_authentication, :after_authentication
+
+    # Background Job Queues
+    attr_accessor :stats_job_queue, :callbacks_job_queue
+
+    # Global Async Toggle
+    attr_accessor :enable_async_operations
+
+    # Engine UI Configuration
+    attr_accessor :return_url, :return_text
+
+    # Debugging
+    attr_accessor :debug_logging
+
+    # == Initialization ==
+
+    def initialize
+      set_defaults
+    end
+
+    private
+
+    def set_defaults
+      # Core Authentication
+      @header = "Authorization" # Expects "Bearer <token>"
+      @query_param = nil # No query param lookup by default
+
+      # Token Generation
+      @token_prefix = -> { "ak_" }
+      @token_length = 24 # Bytes of entropy
+      @token_alphabet = :base58 # Avoid ambiguous chars (0, O, I, l)
+
+      # Storage & Verification
+      @hash_strategy = :sha256 # sha256 or :bcrypt
+      @secure_compare_proc = ->(a, b) { ActiveSupport::SecurityUtils.secure_compare(a, b) }
+      @key_store_adapter = :active_record # Default storage backend
+      # TODO: Define and implement ApiKeys::BasePolicy in later versions
+      # This will define the authorization policy class used to check if a key is valid beyond basic checks.
+      # Allows injecting custom logic (IP allow-listing, time-of-day checks, etc.).
+      # Must be a class name (String or Class) responding to `.new(api_key, request).valid?`
+      # Default: "ApiKeys::BasePolicy" (a basic implementation should be provided)
+      @policy_provider = "ApiKeys::BasePolicy" # Default authorization policy class name
+
+      # Engine Configuration
+      @parent_controller = '::ApplicationController'
+
+      # Optional Behaviors
+      @default_max_keys_per_owner = nil # No global key limit per owner
+      @require_key_name = false # Don't require names for keys globally
+      @expire_after = nil # Keys do not expire by default (e.g., 90.days)
+      @default_scopes = [] # No default scopes assigned globally
+
+      # Performance
+      @cache_ttl = 5.seconds # Good balance: fast revocation, mostly-cached – still allows most repeated requests to benefit from cache
+
+      # Security
+      @https_only_production = true # Warn if used over HTTP in production
+      @https_strict_mode = false # Don't raise error, just warn
+
+      # Background Job Queues
+      @stats_job_queue = :default
+      @callbacks_job_queue = :default
+
+      # Global Async Toggle
+      @enable_async_operations = true # Default to true to enable jobs
+
+      # Usage Statistics
+      @track_requests_count = false # Don't increment `requests_count` by default
+
+      # Callbacks
+      @before_authentication = DEFAULT_CALLBACK
+      @after_authentication = DEFAULT_CALLBACK
+
+      # Engine UI Configuration
+      @return_url = "/" # Default fallback path
+      @return_text = "‹ Home" # Default link text
+
+      # Debugging
+      @debug_logging = false # Disable debug logging by default (warn and error get logged regardless of this)
+
+      # Tenant Resolution
+      @tenant_resolver = ->(api_key) { api_key.owner if api_key.respond_to?(:owner) }
+    end
+  end
+end

data/lib/api_keys/controller.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require_relative "authentication"       # Include authentication logic
+require_relative "tenant_resolution"    # Include tenant resolution logic
+
+module ApiKeys
+  # Unified controller concern that bundles common ApiKeys functionality
+  # for easy inclusion in controllers.
+  #
+  # Includes:
+  #   - ApiKeys::Authentication (provides authenticate_api_key!, current_api_key, etc.)
+  #   - ApiKeys::TenantResolution (provides current_api_tenant)
+  #
+  # == Usage
+  #
+  #   class Api::BaseController < ActionController::API
+  #     include ApiKeys::Controller
+  #
+  #     before_action :authenticate_api_key!
+  #
+  #     def show
+  #       # Access helpers provided by the included concerns
+  #       key = current_api_key
+  #       owner = current_api_owner
+  #       tenant = current_api_tenant
+  #       # ...
+  #     end
+  #   end
+  #
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      # Bring in the functionality from the specific concerns
+      include ApiKeys::Authentication
+      include ApiKeys::TenantResolution
+
+      # You could add further convenience methods here if needed,
+      # potentially combining logic from both included concerns.
+    end
+
+    # Add any class methods specific to this unified concern if necessary
+    # module ClassMethods
+    # end
+  end
+end

data/lib/api_keys/engine.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+require_relative "models/concerns/has_api_keys" # Ensure concern is loaded
+
+module ApiKeys
+  # Rails engine for ApiKeys
+  class Engine < ::Rails::Engine
+    isolate_namespace ApiKeys
+
+    # Allows configuring the parent controller for the engine's controllers
+    # Defaults to ::ApplicationController, assuming a standard Rails app structure.
+    config.parent_controller = '::ApplicationController'
+
+    # Ensure our models load first
+    config.autoload_paths << File.expand_path("../models", __dir__)
+    config.autoload_paths << File.expand_path("../models/concerns", __dir__)
+
+    # Set up autoloading paths
+    initializer "api_keys.autoload", before: :set_autoload_paths do |app|
+      app.config.autoload_paths << root.join("lib")
+      app.config.autoload_paths << root.join("lib/api_keys/models")
+      app.config.autoload_paths << root.join("lib/api_keys/models/concerns")
+    end
+
+    # Add has_api_keys method to ActiveRecord::Base
+    initializer "api_keys.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        # Extend all AR models with the ClassMethods module from HasApiKeys
+        # This makes the `has_api_keys` method available directly on models like User.
+        extend ApiKeys::Models::Concerns::HasApiKeys::ClassMethods
+      end
+    end
+
+
+    # Load JSON attribute types after ActiveRecord initialization
+    # and database connection is established.
+    initializer "api_keys.model_attributes" do
+      ActiveSupport.on_load(:active_record) do
+        ApiKeys::ApiKey.class_eval do
+          # Define JSON attributes for ApiKey model
+          # Ensure the ApiKey model class is loaded before reopening
+          # Use require_dependency for development/test, rely on autoloading in production
+          # Or simply let Zeitwerk handle loading if structure is correct.
+          require_dependency "api_keys/models/api_key" if defined?(Rails) && !Rails.env.production?
+
+          # == JSON Attribute Casting ==
+          # Make the gem work in any database (postgres, sqlite3, mysql...)
+          # Configure the right json-like attributes for the different databases
+          # according to the migration (jsonb = postgres; text = elsewhere)
+          # So that the JSON attributes work in any database
+          # and the gem works everywhere, transparent to end users
+          json_col_type = ApiKeys::ApiKey.connection.adapter_name.downcase.include?('postg') ? :jsonb : :json
+          ApiKeys::ApiKey.attribute :scopes, json_col_type, default: []
+          ApiKeys::ApiKey.attribute :metadata, json_col_type, default: {}
+
+        end
+      end
+    end
+
+
+    # Add other initializers here if needed (e.g., for configuration loading,
+    # middleware injection, asset precompilation, etc.)
+
+    # Example: Load configuration defaults
+    # initializer "api_keys.configuration" do
+    #   require_relative "../config"
+    #   # Potentially load default config values here
+    # end
+
+    # Example: Add middleware if needed
+    # initializer "api_keys.middleware" do |app|
+    #   # app.middleware.use ApiKeys::Middleware::SomeMiddleware
+    # end
+  end
+end

data/lib/api_keys/jobs/callbacks_job.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "active_job"
+require_relative "../logging"
+require_relative "../configuration" # Access configuration for callbacks
+
+module ApiKeys
+  module Jobs
+    # Background job to execute configured lifecycle callbacks asynchronously.
+    class CallbacksJob < ActiveJob::Base
+      include ApiKeys::Logging
+
+      # Use the queue name specified in the configuration (evaluated at load time)
+      queue_as ApiKeys.configuration.callbacks_job_queue
+
+      # Executes the appropriate callback based on the type.
+      #
+      # @param callback_type [Symbol] :before_authentication or :after_authentication
+      # @param context [Hash] Serializable context data for the callback.
+      def perform(callback_type, context = {})
+        config = ApiKeys.configuration
+
+        case callback_type
+        when :before_authentication
+          execute_callback(config.before_authentication, context)
+        when :after_authentication
+          execute_callback(config.after_authentication, context)
+        else
+          log_warn "[ApiKeys::Jobs::CallbacksJob] Unknown callback type: #{callback_type}"
+        end
+      rescue StandardError => e
+        log_error "[ApiKeys::Jobs::CallbacksJob] Error executing callback #{callback_type} with context #{context.inspect}: #{e.class}: #{e.message}
+#{e.backtrace.join("
+")}"
+        # Avoid retrying callback errors by default, as the original request succeeded.
+        # Depending on callback importance, users might configure retries separately.
+      end
+
+      private
+
+      # Safely executes a user-provided callback lambda.
+      #
+      # @param callback_proc [Proc, Lambda] The configured callback.
+      # @param context [Hash] The context data to pass.
+      def execute_callback(callback_proc, context)
+        unless callback_proc.is_a?(Proc)
+          log_debug "[ApiKeys::Jobs::CallbacksJob] Callback is not a Proc, skipping execution."
+          return
+        end
+
+        arity = callback_proc.arity
+        log_debug "[ApiKeys::Jobs::CallbacksJob] Executing callback with arity #{arity}"
+
+        begin
+          if arity == 1 || arity < 0 # Handle procs accepting one arg or variable args (*args)
+            callback_proc.call(context)
+          elsif arity == 0 # Handle procs accepting no args
+            callback_proc.call
+          else
+            log_warn "[ApiKeys::Jobs::CallbacksJob] Callback has unexpected arity (#{arity}). Expected 0 or 1 argument (context hash). Skipping execution."
+          end
+        rescue StandardError => e
+          # Log the specific error from the user's callback code
+          raise # Re-raise to be caught by the main perform rescue block for logging
+        end
+      end
+    end
+  end
+end

data/lib/api_keys/jobs/update_stats_job.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "active_job"
+require_relative "../models/api_key"
+require_relative "../logging"
+
+module ApiKeys
+  module Jobs
+    # Background job to update API key usage statistics (last_used_at, requests_count).
+    # Enqueued by the Authentication concern after a successful request.
+    class UpdateStatsJob < ActiveJob::Base
+      include ApiKeys::Logging # Include logging helpers
+
+      # Use the queue name specified in the configuration (evaluated at load time)
+      queue_as ApiKeys.configuration.stats_job_queue
+
+      # Perform the database updates for the given ApiKey.
+      #
+      # @param api_key_id [Integer, String] The ID of the ApiKey to update.
+      # @param timestamp [Time] The timestamp of the request (when it was authenticated).
+      def perform(api_key_id, timestamp)
+        api_key = ApiKey.find_by(id: api_key_id)
+
+        unless api_key
+          log_warn "[ApiKeys::Jobs::UpdateStatsJob] ApiKey not found with ID: #{api_key_id}. Skipping stats update."
+          return
+        end
+
+        log_debug "[ApiKeys::Jobs::UpdateStatsJob] Updating stats for ApiKey ID: #{api_key_id} at #{timestamp}"
+
+        # Use provided timestamp for consistency
+        # Use update_column to skip validations/callbacks for performance
+        api_key.update_column(:last_used_at, timestamp)
+
+        # Conditionally increment requests_count if configured
+        if ApiKeys.configuration.track_requests_count
+          # Use increment_counter for atomic updates
+          ApiKey.increment_counter(:requests_count, api_key.id)
+          log_debug "[ApiKeys::Jobs::UpdateStatsJob] Incremented requests_count for ApiKey ID: #{api_key_id}"
+        end
+
+        log_debug "[ApiKeys::Jobs::UpdateStatsJob] Finished updating stats for ApiKey ID: #{api_key_id}"
+
+      rescue ActiveRecord::ActiveRecordError => e
+        # Log error but don't automatically retry unless configured to do so.
+        # Frequent stats updates might tolerate occasional failures better than endless retries.
+        log_error "[ApiKeys::Jobs::UpdateStatsJob] Failed to update stats for ApiKey ID: #{api_key_id}. Error: #{e.message}"
+        # Depending on ActiveJob adapter, specific retry logic might be needed here
+        # or configured globally. For now, just log.
+      rescue StandardError => e
+        log_error "[ApiKeys::Jobs::UpdateStatsJob] Unexpected error processing ApiKey ID: #{api_key_id}. Error: #{e.class}: #{e.message}
+#{e.backtrace.join("
+")}"
+        # Consider re-raising or using a dead-letter queue strategy depending on job system
+      end
+    end
+  end
+end

data/lib/api_keys/logging.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ApiKeys
+  # Shared logging utilities for the ApiKeys gem.
+  module Logging
+    private
+
+    # Helper for conditional debug logging based on configuration.
+    #
+    # @param message [String] The message to log.
+    def log_debug(message)
+      # Only log if debug_logging is enabled and a logger is available
+      if ApiKeys.configuration.debug_logging && logger
+        logger.debug(message)
+      end
+    end
+
+    # Helper for conditional warning logging.
+    # Warnings are logged regardless of debug flag, if logger available.
+    #
+    # @param message [String] The message to log.
+    def log_warn(message)
+      logger.warn(message) if logger
+    end
+
+    # Helper for logging errors.
+    # Errors are logged regardless of debug flag, if logger available.
+    #
+    # @param message [String] The message to log.
+    def log_error(message)
+      logger.error(message) if logger
+    end
+
+    # Provides access to the logger instance (Rails.logger if defined).
+    #
+    # @return [Logger, nil] The logger instance or nil.
+    def logger
+      # Memoize the logger instance for performance
+      @_api_keys_logger ||= defined?(Rails) ? Rails.logger : nil
+    end
+  end
+end