api_keys 0.1.0

data/lib/api_keys/services/token_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "base58"
+
+module ApiKeys
+  module Services
+    # Generates secure, random API tokens according to configured settings.
+    class TokenGenerator
+      # 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)
+        random_bytes = SecureRandom.bytes(length)
+
+        random_part = case alphabet
+                      when :base58
+                        Base58.binary_to_base58(random_bytes, :bitcoin)
+                      when :hex
+                        random_bytes.unpack1("H*") # Equivalent to SecureRandom.hex
+                      else
+                        raise ArgumentError, "Unsupported token alphabet: #{alphabet}. Use :base58 or :hex."
+                      end
+
+        "#{prefix}#{random_part}"
+      end
+    end
+  end
+end

data/lib/api_keys/tenant_resolution.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module ApiKeys
+  # Controller concern to resolve and provide access to the tenant
+  # associated with the currently authenticated API key.
+  module TenantResolution
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :current_api_tenant
+
+      # Alias for convenience and explicitness
+      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.
+    # Uses the configured `tenant_resolver` lambda.
+    # Returns nil if no key is authenticated, no owner exists,
+    # or the resolver returns nil.
+    #
+    # @return [Object, nil] The resolved tenant object, or nil.
+    def current_api_tenant
+      return @current_api_tenant if defined?(@current_api_tenant)
+      return nil unless current_api_key # Requires Authentication concern to be included first
+
+      resolver = ApiKeys.configuration.tenant_resolver
+      @current_api_tenant = resolver&.call(current_api_key)
+    rescue StandardError => e
+      # Log error but don't break the request if resolver fails
+      Rails.logger.error "[ApiKeys] Tenant resolution failed: #{e.message}" if defined?(Rails.logger)
+      @current_api_tenant = nil
+    end
+  end
+end

data/lib/api_keys/version.rb

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

data/lib/api_keys.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# This is the entry point to the gem.
+
+require "rails"
+require "active_record"
+require "active_support/all"
+
+require "api_keys/version"
+require "api_keys/configuration"
+
+require "api_keys/models/concerns/has_api_keys"
+
+require "api_keys/models/api_key"
+
+# Rails integration
+require "api_keys/engine" if defined?(Rails)
+
+# Main module that serves as the primary interface to the gem.
+# Most methods here delegate to Configuration, which is the single source of truth for all config in the initializer
+module ApiKeys
+  # Custom error classes
+  class Error < StandardError; end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the gem with a block (main entry point)
+    def configure
+      yield(configuration)
+    end
+
+    # Resets the configuration to its default values.
+    # Useful for testing.
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+  end
+end
+
+# TODO: Require other necessary files like configuration, engine, etc.
+# require_relative "api_keys/configuration"
+# require_relative "api_keys/engine"
+# require_relative "api_keys/railtie" if defined?(Rails::Railtie)

data/lib/generators/api_keys/install_generator.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module ApiKeys
+  module Generators
+    # Rails generator for installing the ApiKeys gem.
+    # Creates the necessary migration and initializer file.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # Implement the required interface for Rails::Generators::Migration.
+      # Borrowed from ActiveRecord::Generators::Base
+      # https://github.com/rails/rails/blob/main/activerecord/lib/rails/generators/active_record/base.rb#L31
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      # Creates the migration file using the template.
+      def create_migration_file
+        migration_template "create_api_keys_table.rb.erb",
+                           File.join(db_migrate_path, "create_api_keys_table.rb")
+      end
+
+      # Creates the initializer file using the template.
+      def create_initializer
+        template "initializer.rb", "config/initializers/api_keys.rb"
+      end
+
+      # Displays helpful information to the user after installation.
+      def display_post_install_message
+        say "\n🎉 api_keys gem successfully installed!", :green
+        say "\nNext steps:"
+        say "  1. Run `rails db:migrate` to create the `api_keys` table."
+        say "     ☢️  Run migrations before starting your application!", :yellow
+        say "\n  2. Add `has_api_keys` to any models that need to have API keys, with an optional block for configuration:"
+        say "       # Example for app/models/user.rb"
+        say "       class User < ApplicationRecord"
+        say "         has_api_keys do"
+        say "           # Optional settings:"
+        say "           # max_keys 10"
+        say "         end"
+        say "         # ..."
+        say "       end"
+        say "\n  3. Optionally, configure the gem behavior in `config/initializers/api_keys.rb` if needed."
+        say "\n  4. In your app's API controllers, verify API keys by including `ApiKeys::Controller`, and adding the before_action to the desired endpoints:"
+        say "       # Example for app/controllers/api/base_controller.rb"
+        say "       class Api::BaseController < ActionController::API"
+        say "         include ApiKeys::Controller"
+        say "         before_action :authenticate_api_key! # Enforce authentication"
+        say "         # ..."
+        say "       end"
+        say "\nSee the api_keys README for detailed usage and examples.
+", :cyan
+        say "Happy coding! 🚀", :green
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# Migration responsible for creating the core api_keys table.
+class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :api_keys, id: primary_key_type do |t|
+      # Identifiable prefix (e.g., "ak_live_", "ak_test_") for env/debugging
+      t.string   :prefix,        null: false
+
+      # Secure digest of the token (e.g., sha256 or bcrypt hash)
+      t.string   :token_digest,  null: false
+
+      # Algorithm used for the digest (e.g., "bcrypt", "sha256")
+      t.string   :digest_algorithm, null: false
+
+      # Last 4 characters of the random part of the token for display
+      t.string   :last4,            null: false, limit: 4
+
+      # Optional, user-provided name for the key
+      t.string   :name
+
+      # Who owns this key? Can be null for ownerless keys.
+      t.references :owner, polymorphic: true, null: true, type: foreign_key_type
+
+      # Optional list of permissions granted to this key (array of strings)
+      t.send(json_column_type, :scopes, default: [], null: false)
+
+      # Optional freeform metadata for tagging
+      t.send(json_column_type, :metadata, default: {}, null: false)
+
+      # Optional auto-expiration timestamp
+      t.datetime :expires_at
+
+      # Timestamp of the last successful authentication using this key
+      t.datetime :last_used_at
+
+      # Optional counter cache for total requests made with this key.
+      t.bigint   :requests_count, default: 0, null: false
+
+      # Timestamp when the key was revoked (null means active)
+      t.datetime :revoked_at
+
+      t.timestamps
+
+      # Critical index for authentication performance
+      t.index :token_digest, unique: true
+
+      # Index to optimize prefix-based lookups (especially for bcrypt)
+      t.index [:prefix, :digest_algorithm], name: "index_api_keys_on_prefix_and_digest_algorithm"
+
+      # 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
+    end
+  end
+
+  private
+
+  # Helper method to determine the appropriate primary and foreign key types
+  # based on the Rails application's configuration.
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint # Assuming bigint is a safe default for foreign keys
+    [primary_key_type, foreign_key_type]
+  end
+
+  # Helper method to determine the appropriate JSON column type based on the database adapter.
+  # Uses :jsonb for PostgreSQL for better performance and indexing, :json otherwise.
+  def json_column_type
+    # Check connection availability for adapter name inspection
+    if ActiveRecord::Base.connection.adapter_name.downcase.include?('postgresql')
+      :jsonb
+    else
+      :json
+    end
+  rescue ActiveRecord::ConnectionNotEstablished
+    # Fallback during initial setup or if connection isn't available
+    :text
+  end
+
+  # Provides the appropriate migration version syntax for the current Rails version.
+  def migration_version
+    major = ActiveRecord::VERSION::MAJOR
+    minor = ActiveRecord::VERSION::MINOR
+    if major >= 5
+      "[#{major}.#{minor}]"
+    else
+      ""
+    end
+  end
+end 

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+ApiKeys.configure do |config|
+  # === Core Authentication ===
+
+  # The HTTP header name where the API key is expected.
+  # Default: "Authorization" (expects "Bearer <token>")
+  # config.header = "Authorization"
+
+  # The query parameter name to check as a fallback if the header is missing.
+  # Set to nil to disable query parameter lookup (recommended for security).
+  # Default: nil
+  # config.query_param = "api_key"
+
+  # === Token Generation ===
+
+  # A lambda/proc that returns the prefix for newly generated tokens.
+  # Defaults to "ak_".
+  # Once set, do NOT change or all previously generated keys may become invalid!
+  # config.token_prefix = -> { "ak_" }
+
+  # The number of random bytes to generate for the token (before encoding).
+  # More bytes = more entropy = harder to guess.
+  # Default: 24 (generates ~32 Base58 chars or 48 hex chars)
+  # config.token_length = 32
+
+  # The encoding alphabet for the random part of the token.
+  # :base58 (recommended) - shorter, avoids ambiguous chars (0, O, I, l)
+  # :hex - standard hexadecimal encoding
+  # Default: :base58
+  # config.token_alphabet = :hex
+
+  # === Storage & Verification ===
+
+  # The hashing strategy used to store token digests in the database.
+  # :sha256 (recommended) - fast, performant, O(1) lookups, but less secure if database is compromised (salted with prefix only)
+  # :bcrypt - for security-critical tokens: includes salt, computationally expensive, can cause lags, 10x-50x slower than sha256
+  # Default: :sha256
+  # config.hash_strategy = :bcrypt
+
+  # === Optional Behaviors ===
+
+  # Global limit on the number of *active* keys an owner can have.
+  # Can be overridden by `max_keys` in the `has_api_keys` block.
+  # Set to nil for no global limit.
+  # Default: nil
+  # config.default_max_keys_per_owner = 10
+
+  # If true, requires a `name` when creating keys.
+  # Can be overridden by `require_name` in the `has_api_keys` block.
+  # Default: false
+  # config.require_key_name = true
+
+  # Automatically expire keys after a certain period from creation.
+  # Set to nil for no automatic expiration.
+  # Default: nil
+  # config.expire_after = 90.days
+
+  # Default scopes to assign to newly created keys if none are specified.
+  # Applies globally unless overridden by `has_api_keys` in the owner model.
+  # Default: []
+  # config.default_scopes = ["read"]
+
+  # === Performance ===
+
+  # Time-to-live (TTL) for caching ApiKey lookups.
+  # Higher values improve performance by reducing database lookups and
+  # expensive comparisons (like bcrypt), but increase the delay for changes
+  # (like revocation or expiration) to take effect for already cached keys.
+  # Set to 0 or nil to disable caching.
+  # Uses Rails.cache.
+  # Default: 5.seconds
+  # config.cache_ttl = 30.seconds # Higher TTL = higher risk of “revoked-but-still-valid” edge cases
+
+  # === Security ===
+
+  # If true, logs a warning if the gem is used over HTTP in production.
+  # Default: true
+  # config.https_only_production = true
+
+  # If true (and https_only_production is true), raises an error instead of
+  # just logging a warning when used over HTTP in production.
+  # Default: false
+  # config.https_strict_mode = true
+
+  # IMPORTANT: Usage Statistics & Background Jobs
+  # ---------------------------------------------
+  # The api_keys gem executes callbacks and updates the `last_used_at` timestamp on every successful authentication
+  # and optionally increments `requests_count` if `track_requests_count` is true.
+  # To avoid blocking the request cycle, these calls and updates are performed asynchronously
+  # using ActiveJob (`ApiKeys::Jobs::UpdateStatsJob` and `ApiKeys::Jobs::CallbacksJob`)
+  #
+  # *** For callbacks to be executed, and for reliable and performant usage statistics, you MUST configure a persistent
+  # ActiveJob backend adapter in your Rails app! (e.g., Sidekiq, GoodJob, SolidQueue, Resque, Delayed::Job). ***
+  #
+  # - Using the default :async adapter is NOT recommended for production as updates
+  #   run in-process and may be lost if the application restarts unexpectedly.
+  # - Using the :inline adapter will perform updates synchronously within the request,
+  #   negating the performance benefits and potentially slowing down responses.
+  #
+  # If you do not have a persistent background job system configured, callbacks won't fire and stats updates
+  # might be unreliable or impact performance. Consider disabling `track_requests_count` and avoid using callbacks
+  # if you cannot use a persistent backend and performance is critical.
+
+  # === Background Job Queues ===
+
+  # Configure the ActiveJob queue name for processing API key usage statistics.
+  # Default: :default
+  # config.stats_job_queue = :api_keys_stats
+
+  # Configure the ActiveJob queue name for processing asynchronous callbacks.
+  # Default: :default
+  # config.callbacks_job_queue = :api_keys_callbacks
+
+  # === Global Async Toggle ===
+
+  # Set to false to completely disable all background job enqueueing performed
+  # by this gem (stats updates and callbacks). If false, `last_used_at`,
+  # `requests_count`, and configured callbacks will NOT be processed.
+  # Useful if you handle these concerns externally or cannot use ActiveJob.
+  # Default: true
+  # config.enable_async_operations = false
+
+  # === Usage Statistics ===
+
+  # If true, automatically update `last_used_at` and increment `requests_count`
+  # on the ApiKey record upon successful authentication.
+  # Note: Incrementing counters frequently can impact DB performance.
+  # Default: false
+  # config.track_requests_count = true
+
+  # === Callbacks ===
+
+  # A lambda/proc to run *before* token extraction and verification.
+  # Receives the request object.
+  # Default: ->(request) { }
+  # config.before_authentication = ->(request) { Rails.logger.info "Authenticating request: #{request.uuid}" }
+
+  # A lambda/proc to run *after* authentication attempt (success or failure).
+  # Receives the ApiKeys::Services::Authenticator::Result object.
+  # Default: ->(result) { }
+  # config.after_authentication = ->(result) { MyAnalytics.track_auth(result) }
+
+  # === Engine UI Configuration ===
+
+  # The URL or path helper method (as a string) to link back to from the engine's UI.
+  # Useful when embedding the engine within a larger application context.
+  # Default: "/" (Root path)
+  # config.return_url = "/app/settings"
+
+  # The text displayed for the return link.
+  # Default: "‹ Home"
+  # config.return_text = "‹ Back to Settings"
+
+  # === Debugging ===
+
+  # Enable verbose logging for debugging purposes.
+  # Default: false
+  # config.debug_logging = true
+end

metadata

@@ -0,0 +1,184 @@
+--- !ruby/object:Gem::Specification
+name: api_keys
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rameerez
+bindir: exe
+cert_chain: []
+date: 2025-04-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: base58
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: bcrypt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+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.
+email:
+- rubygems@rameerez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- api_keys_dashboard.webp
+- api_keys_permissions.webp
+- api_keys_token.webp
+- app/controllers/api_keys/application_controller.rb
+- app/controllers/api_keys/keys_controller.rb
+- app/controllers/api_keys/security_controller.rb
+- app/views/api_keys/keys/_form.html.erb
+- app/views/api_keys/keys/_key_row.html.erb
+- app/views/api_keys/keys/_keys_table.html.erb
+- app/views/api_keys/keys/_show_token.html.erb
+- app/views/api_keys/keys/edit.html.erb
+- app/views/api_keys/keys/index.html.erb
+- app/views/api_keys/keys/new.html.erb
+- app/views/api_keys/keys/show.html.erb
+- app/views/api_keys/security/best_practices.html.erb
+- app/views/layouts/api_keys/application.html.erb
+- config/routes.rb
+- lib/api_keys.rb
+- lib/api_keys/authentication.rb
+- lib/api_keys/configuration.rb
+- lib/api_keys/controller.rb
+- lib/api_keys/engine.rb
+- lib/api_keys/jobs/callbacks_job.rb
+- lib/api_keys/jobs/update_stats_job.rb
+- lib/api_keys/logging.rb
+- lib/api_keys/models/api_key.rb
+- lib/api_keys/models/concerns/has_api_keys.rb
+- lib/api_keys/services/authenticator.rb
+- lib/api_keys/services/digestor.rb
+- lib/api_keys/services/token_generator.rb
+- lib/api_keys/tenant_resolution.rb
+- lib/api_keys/version.rb
+- lib/generators/api_keys/install_generator.rb
+- lib/generators/api_keys/templates/create_api_keys_table.rb.erb
+- lib/generators/api_keys/templates/initializer.rb
+homepage: https://github.com/rameerez/api_keys
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://apikeys.rameerez.com
+  source_code_uri: https://github.com/rameerez/api_keys
+  changelog_uri: https://github.com/rameerez/api_keys/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Gate your Rails API with secure, self-serve API keys in minutes
+test_files: []