api_keys 0.3.0 → 0.4.0

data/lib/api_keys/services/token_generator.rb

@@ -7,13 +7,25 @@ module ApiKeys
   module Services
     # Generates secure, random API tokens according to configured settings.
     class TokenGenerator
+      MIN_RANDOM_BYTES = 16
+      MAX_RANDOM_BYTES = 64
+      MAX_PREFIX_BYTESIZE = 64
+
       # Generates a new token string.
       #
       # @param length [Integer] The desired byte length of the random part (before encoding).
       # @param prefix [String] The prefix to prepend to the token.
       # @param alphabet [Symbol] The encoding alphabet (:base58 or :hex).
       # @return [String] The generated token including the prefix.
-      def self.call(length: ApiKeys.configuration.token_length, prefix: ApiKeys.configuration.token_prefix.call, alphabet: ApiKeys.configuration.token_alphabet)
+      def self.call(length: nil, prefix: nil, alphabet: nil)
+        length ||= ApiKeys.configuration.token_length
+        prefix ||= ApiKeys.configuration.resolved_token_prefix
+        alphabet ||= ApiKeys.configuration.token_alphabet
+
+        validate_length!(length)
+        validate_prefix!(prefix)
+        validate_alphabet!(alphabet)
+
         random_bytes = SecureRandom.bytes(length)
 
         random_part = case alphabet
@@ -27,6 +39,34 @@ module ApiKeys
 
         "#{prefix}#{random_part}"
       end
+
+      def self.validate_length!(length)
+        return if length.is_a?(Integer) && length.between?(MIN_RANDOM_BYTES, MAX_RANDOM_BYTES)
+
+        raise ArgumentError,
+          "Token length must be an Integer between #{MIN_RANDOM_BYTES} and #{MAX_RANDOM_BYTES} random bytes."
+      end
+
+      def self.validate_prefix!(prefix)
+        valid = prefix.is_a?(String) && prefix.present? && prefix.valid_encoding? &&
+          prefix.bytesize <= MAX_PREFIX_BYTESIZE &&
+          prefix.each_codepoint.none? { |codepoint| codepoint <= 0x20 || codepoint == 0x7f }
+        return if valid
+
+        raise ArgumentError,
+          "Token prefix must be a non-blank string of at most #{MAX_PREFIX_BYTESIZE} bytes without whitespace or control characters."
+      rescue ArgumentError
+        raise ArgumentError,
+          "Token prefix must be a non-blank string of at most #{MAX_PREFIX_BYTESIZE} bytes without whitespace or control characters."
+      end
+
+      def self.validate_alphabet!(alphabet)
+        return if %i[base58 hex].include?(alphabet)
+
+        raise ArgumentError, "Unsupported token alphabet: #{alphabet}. Use :base58 or :hex."
+      end
+
+      private_class_method :validate_length!, :validate_prefix!, :validate_alphabet!
     end
   end
 end

data/lib/api_keys/tenant_resolution.rb

@@ -15,8 +15,6 @@ module ApiKeys
       alias_method :current_api_key_tenant, :current_api_tenant
       alias_method :current_api_account, :current_api_tenant
       alias_method :current_api_key_account, :current_api_tenant
-      alias_method :current_api_owner, :current_api_tenant
-      alias_method :current_api_key_owner, :current_api_tenant
     end
 
     # Returns the tenant associated with the current API key.
@@ -31,10 +29,10 @@ module ApiKeys
 
       resolver = ApiKeys.configuration.tenant_resolver
       @current_api_tenant = resolver&.call(current_api_key)
-    rescue StandardError => e
+    rescue StandardError => error
       # Log error but don't break the request if resolver fails
       if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-        Rails.logger.error "[ApiKeys] Tenant resolution failed: #{e.message}"
+        Rails.logger.error "[ApiKeys] Tenant resolution failed (#{error.class})."
       end
       @current_api_tenant = nil
     end

data/lib/api_keys/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ApiKeys
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/generators/api_keys/add_authentication_index_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module ApiKeys
+  module Generators
+    # Adds the bounded bcrypt authentication lookup index to existing installs.
+    class AddAuthenticationIndexGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(number)
+      end
+
+      def create_migration_file
+        migration_template "add_authentication_index_to_api_keys.rb.erb",
+                           File.join(db_migrate_path, "add_authentication_index_to_api_keys.rb")
+      end
+
+      def display_post_install_message
+        say "\n🔐 API key authentication index migration created.", :green
+        say "Run `rails db:migrate` before deploying bcrypt authentication changes."
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/api_keys/templates/add_authentication_index_to_api_keys.rb.erb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class AddAuthenticationIndexToApiKeys < ActiveRecord::Migration<%= migration_version %>
+  INDEX_NAME = "index_api_keys_authentication_lookup"
+  COLUMNS = %i[prefix last4 digest_algorithm].freeze
+
+  disable_ddl_transaction!
+
+  def up
+    return if index_exists?(:api_keys, COLUMNS, name: INDEX_NAME)
+
+    options = { name: INDEX_NAME }
+    options[:algorithm] = :concurrently if connection.adapter_name.downcase.include?("postgres")
+    add_index :api_keys, COLUMNS, **options
+  end
+
+  def down
+    return unless index_exists?(:api_keys, COLUMNS, name: INDEX_NAME)
+
+    options = { name: INDEX_NAME }
+    options[:algorithm] = :concurrently if connection.adapter_name.downcase.include?("postgres")
+    remove_index :api_keys, **options
+  end
+
+  private
+
+  def migration_version
+    major = ActiveRecord::VERSION::MAJOR
+    minor = ActiveRecord::VERSION::MINOR
+    major >= 5 ? "[#{major}.#{minor}]" : ""
+  end
+end

data/lib/generators/api_keys/templates/create_api_keys_table.rb.erb

@@ -55,12 +55,11 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
 
       # Index to optimize prefix-based lookups (especially for bcrypt)
       t.index [:prefix, :digest_algorithm], name: "index_api_keys_on_prefix_and_digest_algorithm"
+      t.index [:prefix, :last4, :digest_algorithm], name: "index_api_keys_authentication_lookup"
 
       # Optional indexes
       t.index :prefix
       t.index :last4 # Index potentially useful for UI lookups/filtering by masked token
-      t.index :owner_id if foreign_key_type # Index owner_id only if it's a separate column
-      t.index :owner_type if foreign_key_type # Index owner_type only if it's a separate column
       t.index :expires_at
       t.index :revoked_at
       t.index :last_used_at
@@ -106,4 +105,4 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
       ""
     end
   end
-end 
+end

data/lib/generators/api_keys/templates/initializer.rb

@@ -23,6 +23,12 @@ ApiKeys.configure do |config|
   # Configure how the dashboard integrates with your application's auth system.
   # ============================================================================
 
+  # Controller class that the engine dashboard inherits from. Configure this in
+  # the initializer before engine controllers load. Accepts a Class or constant
+  # name string.
+  # Default: "::ApplicationController"
+  # config.parent_controller = "Admin::ApplicationController"
+
   # The method that returns the current API key owner in your controllers.
   # This should return the model instance that has_api_keys.
   # Default: :current_user (works with Devise out of the box)
@@ -84,7 +90,11 @@ ApiKeys.configure do |config|
   # When key_types IS configured and you specify a key_type, this setting
   # is IGNORED - the prefix comes from the key type's configuration instead.
   #
-  # WARNING: Once set, do NOT change or existing keys will fail authentication!
+  # Changing this later is SAFE for existing keys: every key stores its own
+  # prefix, so authentication keeps finding keys minted under retired
+  # prefixes (sha256 looks up by pure token digest; bcrypt uses a bounded
+  # stored-prefix lookup with an indexed last-four fallback for deployments
+  # with many retired prefixes). Only NEW keys wear the new prefix.
   # Default: -> { "ak_" }
   # config.token_prefix = -> { "myapp_" }
 
@@ -113,7 +123,8 @@ ApiKeys.configure do |config|
   # - limit:       Max keys of this type per owner per environment (nil = unlimited)
   # - public:      If true AND revocable: false, stores plaintext token in metadata
   #                so it can be viewed again in the dashboard. Use ONLY for publishable
-  #                keys designed to be embedded in distributed apps. (default: false)
+  #                keys designed to be embedded in distributed apps. Public types must
+  #                use a finite, non-empty permissions array (never :all). (default: false)
   #                SECURITY: NEVER set public: true on secret keys!
   #
   # config.key_types = {
@@ -227,6 +238,7 @@ ApiKeys.configure do |config|
   #   - Includes salt, computationally expensive by design
   #   - 10x-50x slower than SHA256 - impacts every API request
   #   - Better for low-entropy secrets (passwords), overkill for random API keys
+  #   - Prefix + encoded random token must fit bcrypt's 72-byte input limit
   #
   # Default: :sha256
   # config.hash_strategy = :sha256
@@ -240,10 +252,10 @@ ApiKeys.configure do |config|
   # Default: true
   # config.https_only_production = true
 
-  # Raise an error (instead of just warning) for HTTP in production.
+  # Reject authentication (instead of just warning) over HTTP in production.
   # Only applies when https_only_production is true.
-  # Default: false
-  # config.https_strict_mode = false
+  # Default: true
+  # config.https_strict_mode = true
 
   # ============================================================================
   # BACKGROUND JOBS & CALLBACKS
@@ -263,34 +275,41 @@ ApiKeys.configure do |config|
   # config.enable_async_operations = true
 
   # Track request counts (increments requests_count on each authentication).
-  # Note: High-frequency counter updates can impact database performance.
+  # Exact counting bypasses last-used debouncing and therefore enqueues one stats
+  # job per successful request. High-frequency updates can impact queue/database
+  # performance.
   # Default: false
   # config.track_requests_count = false
 
+  # Minimum interval between last_used_at jobs when exact request counting is
+  # disabled. Set to 0 or nil to update on every successful authentication.
+  # Default: 1.minute
+  # config.stats_update_interval = 1.minute
+
   # Queue names for background jobs.
   # Default: :default
   # config.stats_job_queue = :default
   # config.callbacks_job_queue = :default
 
-  # Callbacks executed on authentication attempts.
-  # before_authentication: receives the request object
-  # after_authentication: receives the Result object (success/failure info)
+  # Callbacks enqueued on authentication attempts. Contexts are serializable
+  # hashes and never contain the token, request, result, or ApiKey object.
+  # before_authentication: { request_uuid: String }
+  # after_authentication:  { success:, error_code:, api_key_id:,
+  #                          required_scope_check: (optional) }
   #
   # Default: empty procs (no-op)
-  # config.before_authentication = ->(request) { Rails.logger.info "Auth: #{request.uuid}" }
-  # config.after_authentication = ->(result) { Analytics.track(result) }
+  # config.before_authentication = ->(context) { Rails.logger.info "Auth request: #{context[:request_uuid]}" }
+  # config.after_authentication = ->(context) { Analytics.track_auth(context) }
 
   # ============================================================================
   # PERFORMANCE
   # ============================================================================
 
-  # Time-to-live (TTL) for caching API key lookups in Rails.cache.
-  #
-  # Higher values = better performance (fewer DB queries)
-  # Lower values = faster propagation of revocations/changes
+  # Time-to-live (TTL) for caching API key ID lookup hints in Rails.cache.
   #
-  # Trade-off: A revoked key may still work for up to `cache_ttl` seconds
-  # until the cache expires.
+  # Cache entries are never authorization authority. Every hit reloads the
+  # current database row and cryptographically re-verifies the token, so
+  # revocation, expiration, and permission changes remain immediate.
   #
   # Set to 0 or nil to disable caching entirely.
   # Default: 5.seconds

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: api_keys
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-07-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -41,16 +41,22 @@ dependencies:
   name: bcrypt
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.1.22
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.1.22
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '4'
 description: Add secure, production-ready API key authentication to your Rails app
   in minutes. Handles key generation, hashing, expiration, revocation, per-key scopes;
   plus a drop-in dashboard for your users to self-issue and manage their own API keys.
@@ -60,14 +66,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".simplecov"
-- AGENTS.md
-- Appraisals
 - CHANGELOG.md
-- CLAUDE.md
 - LICENSE.txt
 - README.md
-- Rakefile
+- SECURITY.md
 - api_keys_dashboard.webp
 - api_keys_permissions.webp
 - api_keys_token.webp
@@ -92,10 +94,6 @@ files:
 - app/views/api_keys/security/best_practices.html.erb
 - app/views/layouts/api_keys/application.html.erb
 - config/routes.rb
-- context7.json
-- gemfiles/rails_7.2.gemfile
-- gemfiles/rails_8.0.gemfile
-- gemfiles/rails_8.1.gemfile
 - lib/api_keys.rb
 - lib/api_keys/authentication.rb
 - lib/api_keys/configuration.rb
@@ -116,8 +114,10 @@ files:
 - lib/api_keys/services/token_generator.rb
 - lib/api_keys/tenant_resolution.rb
 - lib/api_keys/version.rb
+- lib/generators/api_keys/add_authentication_index_generator.rb
 - lib/generators/api_keys/add_key_types_generator.rb
 - lib/generators/api_keys/install_generator.rb
+- lib/generators/api_keys/templates/add_authentication_index_to_api_keys.rb.erb
 - lib/generators/api_keys/templates/add_key_types_to_api_keys.rb.erb
 - lib/generators/api_keys/templates/create_api_keys_table.rb.erb
 - lib/generators/api_keys/templates/initializer.rb
@@ -144,7 +144,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Gate your Rails API with secure, self-serve API keys in minutes
 test_files: []

data/.simplecov

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-# SimpleCov configuration file (auto-loaded before test suite)
-# This keeps test_helper.rb clean and follows best practices
-
-SimpleCov.start do
-  # Use SimpleFormatter for terminal-only output (no HTML generation)
-  formatter SimpleCov::Formatter::SimpleFormatter
-
-  # Track coverage for the lib directory (gem source code)
-  add_filter "/test/"
-
-  # Track the lib and app directories
-  track_files "{lib,app}/**/*.rb"
-
-  # Enable branch coverage for more detailed metrics
-  enable_coverage :branch
-
-  # Set minimum coverage threshold to prevent coverage regression
-  # Starting at 60% - can be increased as coverage improves
-  minimum_coverage line: 60, branch: 60
-
-  # Disambiguate parallel test runs
-  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
-end
-
-# Print coverage summary to terminal after tests complete
-SimpleCov.at_exit do
-  SimpleCov.result.format!
-  puts "\n" + "=" * 60
-  puts "COVERAGE SUMMARY"
-  puts "=" * 60
-  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
-  puts "Branch Coverage: #{SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || 'N/A'}%"
-  puts "=" * 60
-end

data/AGENTS.md

@@ -1,5 +0,0 @@
-# AGENTS.md
-
-This file provides guidance to AI Agents (like OpenAI's Codex, Cursor Agent, Claude Code, etc) when working with code in this repository.
-
-Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/Appraisals

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-# Test against multiple Rails versions
-# This is our most critical dependency point
-
-appraise "rails-7.2" do
-  gem "rails", "~> 7.2.3"
-end
-
-appraise "rails-8.0" do
-  gem "rails", "~> 8.0"
-end
-
-# Test against Rails 8.1 (latest)
-appraise "rails-8.1" do
-  gem "rails", "~> 8.1.2"
-end

data/CLAUDE.md

@@ -1,5 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/Rakefile

@@ -1,37 +0,0 @@
-begin
-  require "bundler/setup"
-rescue LoadError
-  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
-end
-
-require "bundler/gem_tasks"
-
-require "rdoc/task"
-
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = "rdoc"
-  rdoc.title = "Pay"
-  rdoc.options << "--line-numbers"
-  rdoc.rdoc_files.include("README.md")
-  rdoc.rdoc_files.include("lib/**/*.rb")
-end
-
-# Removed loading of engine tasks to avoid pulling in dummy app/vendor tests
-# APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
-# load "rails/tasks/engine.rake"
-
-# Removed Rails statistics task; not needed for gem tests
-# load "rails/tasks/statistics.rake"
-
-require "rake/testtask"
-
-# Ensure any test task created by engine.rake is cleared so only this suite runs
-Rake::Task[:test].clear if Rake::Task.task_defined?(:test)
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.verbose = false
-  t.test_files = FileList['test/**/*_test.rb'].exclude('test/dummy/**/*')
-end
-
-task default: :test

data/context7.json

@@ -1,4 +0,0 @@
-{
-  "url": "https://context7.com/rameerez/api_keys",
-  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
-}

data/gemfiles/rails_7.2.gemfile

@@ -1,21 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "rake", "~> 13.0"
-gem "rails", "~> 7.2.3"
-
-group :development, :test do
-  gem "appraisal"
-  gem "minitest", "~> 6.0"
-  gem "minitest-mock"
-  gem "minitest-reporters"
-  gem "rack-test"
-  gem "simplecov", require: false
-  gem "sqlite3", ">= 2.1"
-  gem "bootsnap", require: false
-  gem "mocha", "~> 2.0"
-  gem "ostruct"
-end
-
-gemspec path: "../"

data/gemfiles/rails_8.0.gemfile

@@ -1,21 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "rake", "~> 13.0"
-gem "rails", "~> 8.0"
-
-group :development, :test do
-  gem "appraisal"
-  gem "minitest", "~> 6.0"
-  gem "minitest-mock"
-  gem "minitest-reporters"
-  gem "rack-test"
-  gem "simplecov", require: false
-  gem "sqlite3", ">= 2.1"
-  gem "bootsnap", require: false
-  gem "mocha", "~> 2.0"
-  gem "ostruct"
-end
-
-gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -1,21 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "rake", "~> 13.0"
-gem "rails", "~> 8.1.2"
-
-group :development, :test do
-  gem "appraisal"
-  gem "minitest", "~> 6.0"
-  gem "minitest-mock"
-  gem "minitest-reporters"
-  gem "rack-test"
-  gem "simplecov", require: false
-  gem "sqlite3", ">= 2.1"
-  gem "bootsnap", require: false
-  gem "mocha", "~> 2.0"
-  gem "ostruct"
-end
-
-gemspec path: "../"