api_keys 0.2.1 → 0.3.0

data/lib/generators/api_keys/add_key_types_generator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module ApiKeys
+  module Generators
+    # Rails generator for adding key_type and environment columns to the api_keys table.
+    # This generator is for existing installations that want to enable the key types feature.
+    class AddKeyTypesGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # Implement the required interface for Rails::Generators::Migration.
+      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 "add_key_types_to_api_keys.rb.erb",
+                           File.join(db_migrate_path, "add_key_types_to_api_keys.rb")
+      end
+
+      # Displays helpful information to the user after installation.
+      def display_post_install_message
+        say "\n🔑 Key types migration created!", :green
+        say "\nNext steps:"
+        say "  1. Run `rails db:migrate` to add the key_type and environment columns."
+        say "\n  2. Configure key types in `config/initializers/api_keys.rb`:"
+        say "       ApiKeys.configure do |config|"
+        say "         config.key_types = {"
+        say "           publishable: {"
+        say "             prefix: 'pk',"
+        say "             permissions: %w[read validate],"
+        say "             revocable: false,"
+        say "             limit: 1"
+        say "           },"
+        say "           secret: {"
+        say "             prefix: 'sk',"
+        say "             permissions: :all"
+        say "           }"
+        say "         }"
+        say ""
+        say "         config.environments = {"
+        say "           test: { prefix_segment: 'test' },"
+        say "           live: { prefix_segment: 'live' }"
+        say "         }"
+        say ""
+        say "         config.current_environment = -> { Rails.env.production? ? :live : :test }"
+        say "         config.strict_environment_isolation = true"
+        say "       end"
+        say "\n  3. Create typed API keys:"
+        say "       user.create_api_key!(name: 'My Key', key_type: :publishable)"
+        say "       user.create_api_key!(name: 'Admin Key', key_type: :secret)"
+        say "\nSee the api_keys README for detailed usage and examples.", :cyan
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Migration to add key_type and environment columns to the api_keys table.
+# This enables the Stripe-style publishable/secret key types feature.
+#
+# Run this migration if you're upgrading from a version of api_keys that
+# didn't have key types support.
+class AddKeyTypesToApiKeys < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :api_keys, :key_type, :string
+    add_column :api_keys, :environment, :string
+
+    add_index :api_keys, :key_type
+    add_index :api_keys, :environment
+    add_index :api_keys, [:owner_type, :owner_id, :key_type, :environment],
+              name: "index_api_keys_owner_type_env"
+  end
+end

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

@@ -42,6 +42,12 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
       # Timestamp when the key was revoked (null means active)
       t.datetime :revoked_at
 
+      # Key type identifier (e.g., "publishable", "secret") for Stripe-style key types
+      t.string :key_type
+
+      # Environment identifier (e.g., "test", "live") for environment isolation
+      t.string :environment
+
       t.timestamps
 
       # Critical index for authentication performance
@@ -58,6 +64,9 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
       t.index :expires_at
       t.index :revoked_at
       t.index :last_used_at
+      t.index :key_type
+      t.index :environment
+      t.index [:owner_type, :owner_id, :key_type, :environment], name: "index_api_keys_owner_type_env"
     end
   end
 

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

@@ -1,77 +1,188 @@
 # frozen_string_literal: true
 
 ApiKeys.configure do |config|
-  # === Core Authentication ===
+  # ============================================================================
+  # 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).
+  # WARNING: Query parameters appear in logs, browser history, and Referer headers.
+  # Only enable for development/testing. Set to nil to disable (recommended).
   # Default: nil
   # config.query_param = "api_key"
 
-  # === Token Generation ===
+  # ============================================================================
+  # DASHBOARD CONFIGURATION
+  # ============================================================================
+  #
+  # The api_keys engine provides a web UI for users to manage their API keys.
+  # Configure how the dashboard integrates with your application's auth system.
+  # ============================================================================
 
-  # 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 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)
+  #
+  # Example for Organization-owned keys:
+  # config.current_owner_method = :current_organization
 
-  # 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 method that authenticates/requires login for the dashboard.
+  # This should be a before_action-style method that ensures the owner is logged in.
+  # Default: :authenticate_user! (works with Devise out of the box)
+  #
+  # Example for Organization-owned keys:
+  # config.authenticate_owner_method = :authenticate_organization!
 
-  # 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
+  # Dashboard environment filtering (only applies when key_types is configured).
+  # When false (default), dashboard only shows keys matching current_environment.
+  # When true, dashboard shows keys from all environments.
+  # Default: false
+  #
+  # config.dashboard_allow_cross_environment = false
 
-  # === Storage & Verification ===
+  # URL for the "back" link in the dashboard UI.
+  # Default: "/"
+  # config.return_url = "/settings"
 
-  # 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
+  # Text for the "back" link.
+  # Default: "‹ Home"
+  # config.return_text = "‹ Back to Settings"
 
-  # === Dashboard Configuration ===
+  # ============================================================================
+  # TOKEN PREFIXES
+  # ============================================================================
+  #
+  # API keys are generated with a prefix followed by random characters:
+  #   "ak_7Hq2mJvK9pRs3xYz..."
+  #   prefix        = ak_
+  #   random part   = 7Hq2mJvK9pRs3xYz...
+  #
+  # The prefix system has two modes:
+  #
+  # 1. SIMPLE MODE (default): All keys use the same prefix from `token_prefix`
+  #    Example: ak_7Hq2mJvK9pRs3xYz...
+  #
+  # 2. KEY TYPES MODE: Different key types get different prefixes based on
+  #    their type and environment (Stripe-style)
+  #    Example: pk_test_7Hq2mJvK..., sk_live_9xYz3pRs...
+  #
+  # See "KEY TYPES & ENVIRONMENTS" section below to enable key types mode.
 
-  # IMPORTANT: Owner Context Configuration
-  # The api_keys dashboard needs to know how to find the current owner
-  # of API keys in your application. By default, it assumes you have
-  # a User model with current_user/authenticate_user! methods (Devise-style).
+  # ----------------------------------------------------------------------------
+  # Simple Prefix (when NOT using KEY TYPES)
+  # ----------------------------------------------------------------------------
   #
-  # If your API keys belong to a different model (e.g., Organization),
-  # you MUST configure these methods:
+  # A lambda/proc that returns the prefix for newly generated tokens.
+  # This is ONLY used when:
+  #   - key_types is not configured (empty hash), OR
+  #   - Creating a key without specifying a key_type
+  #
+  # 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!
+  # Default: -> { "ak_" }
+  # config.token_prefix = -> { "myapp_" }
 
-  # The method that returns the current API key owner in your controllers.
-  # This should return the object that has_api_keys (e.g., current_organization).
-  # Default: :current_user
-  # config.current_owner_method = :current_organization
+  # ============================================================================
+  # KEY TYPES & ENVIRONMENTS (Stripe-style Publishable/Secret Keys)
+  # ============================================================================
+  #
+  # For applications that distribute software with embedded API keys (desktop
+  # apps, mobile apps, CLI tools), you can create different key types with
+  # different permission levels - similar to Stripe's publishable/secret pattern.
+  #
+  # When enabled:
+  # - Keys get type+environment prefixes: pk_test_, pk_live_, sk_test_, sk_live_
+  # - Each type can have different permissions, revocability, and limits
+  # - The `token_prefix` setting above is IGNORED for typed keys
+  #
+  # By default, this feature is DISABLED (empty hash) for backwards compatibility.
+  # Existing keys without key_type/environment continue to work normally.
+  # ============================================================================
 
-  # The method that authenticates/requires login for the dashboard.
-  # This should ensure the owner is logged in before accessing the dashboard.
-  # Default: :authenticate_user!
-  # config.authenticate_owner_method = :authenticate_organization!
+  # Define your key types with their properties:
+  #
+  # - prefix:      The token prefix for this type (e.g., "pk" becomes pk_test_)
+  # - permissions: Scope ceiling - array of allowed scopes, or :all for unrestricted
+  # - revocable:   Whether keys of this type can be revoked/deleted (default: true)
+  # - 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)
+  #                SECURITY: NEVER set public: true on secret keys!
+  #
+  # config.key_types = {
+  #   publishable: {
+  #     prefix: "pk",                    # → pk_test_, pk_live_
+  #     permissions: %w[read validate],  # Can ONLY have these scopes
+  #     revocable: false,                # Cannot be revoked - protects deployed apps!
+  #     public: true,                    # Store token for later viewing in dashboard
+  #     limit: 1                         # Only 1 publishable key per environment
+  #   },
+  #   secret: {
+  #     prefix: "sk",                    # → sk_test_, sk_live_
+  #     permissions: :all                # No scope restrictions
+  #     # revocable: true (default)
+  #     # public: false (default) - NEVER store secret keys!
+  #     # limit: nil (default = unlimited)
+  #   }
+  # }
+
+  # Define your environments with their prefix segments:
+  #
+  # - prefix_segment: The middle part of the prefix (e.g., "test" → pk_test_)
+  #   Set to nil for single-environment setups (prefix becomes just "pk_")
+  #
+  # config.environments = {
+  #   test: { prefix_segment: "test" },  # Development/staging → pk_test_, sk_test_
+  #   live: { prefix_segment: "live" }   # Production → pk_live_, sk_live_
+  # }
+  #
+  # Alternative naming (Stripe's newer convention):
+  # config.environments = {
+  #   sandbox: { prefix_segment: "test" },
+  #   live: { prefix_segment: "live" }
+  # }
+
+  # Lambda that returns the current environment.
+  # Used to auto-select environment when creating keys and for isolation checks.
+  # Default: -> { :default }
+  #
+  # config.current_environment = -> { Rails.env.production? ? :live : :test }
 
-  # Example for Organization-owned keys:
-  # config.current_owner_method = :current_organization
-  # config.authenticate_owner_method = :authenticate_organization!
+  # Enable strict environment isolation.
+  # When true, keys can ONLY authenticate in their matching environment:
+  # - test keys return :environment_mismatch error in production
+  # - live keys return :environment_mismatch error in development/test
+  # Default: false
+  #
+  # config.strict_environment_isolation = true
+
+  # Default key type when not specified in create_api_key!
+  # When set and key_types is configured, keys created without explicit
+  # key_type will use this default.
+  # Default: nil (must specify key_type explicitly when key_types is configured)
+  #
+  # config.default_key_type = :secret
 
-  # === Optional Behaviors ===
+  # ============================================================================
+  # KEY LIMITS & 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.
+  # Can be overridden per-model with `max_keys` in the `has_api_keys` block, like:
+  #   has_api_keys max_keys: 5
   # 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.
+  # Require a name when creating keys.
+  # Can be overridden per-model with `require_name` in the `has_api_keys` block.
   # Default: false
   # config.require_key_name = true
 
@@ -81,104 +192,115 @@ ApiKeys.configure do |config|
   # 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.
+  # Can be overridden per-model with `default_scopes` in the `has_api_keys` block.
   # 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 ===
+  # ============================================================================
+  # TOKEN GENERATION
+  # ============================================================================
+  #
+  # The number of random bytes to generate for the token (before encoding).
+  # More bytes = more entropy = harder to guess.
+  # SECURITY: Minimum recommended is 16 bytes (128 bits). Default provides 192 bits.
+  # Default: 24 (generates ~32 Base58 chars or 48 hex chars)
+  # config.token_length = 24
 
-  # If true, logs a warning if the gem is used over HTTP in production.
-  # Default: true
-  # config.https_only_production = true
+  # The encoding alphabet for the random part of the token.
+  #   :base58 - shorter tokens, avoids ambiguous chars (0, O, I, l) - RECOMMENDED
+  #   :hex    - standard hexadecimal encoding, longer tokens
+  # Default: :base58
+  # config.token_alphabet = :base58
 
-  # 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
+  # ============================================================================
+  # STORAGE & VERIFICATION
+  # ============================================================================
 
-  # 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`)
+  # The hashing strategy used to store token digests in the database.
   #
-  # *** 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). ***
+  # :sha256 (RECOMMENDED for API keys)
+  #   - Fast, performant, O(1) database lookups
+  #   - Secure for high-entropy tokens (192+ bits from SecureRandom)
+  #   - Industry standard for API keys (used by Stripe, GitHub, AWS)
   #
-  # - 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.
+  # :bcrypt (for extra security at cost of performance)
+  #   - 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
   #
-  # 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.
+  # Default: :sha256
+  # config.hash_strategy = :sha256
 
-  # === Background Job Queues ===
+  # ============================================================================
+  # SECURITY
+  # ============================================================================
 
-  # Configure the ActiveJob queue name for processing API key usage statistics.
-  # Default: :default
-  # config.stats_job_queue = :api_keys_stats
+  # Log a warning if API authentication is attempted over HTTP in production.
+  # API keys should always be transmitted over HTTPS.
+  # Default: true
+  # config.https_only_production = true
 
-  # Configure the ActiveJob queue name for processing asynchronous callbacks.
-  # Default: :default
-  # config.callbacks_job_queue = :api_keys_callbacks
+  # Raise an error (instead of just warning) for HTTP in production.
+  # Only applies when https_only_production is true.
+  # Default: false
+  # config.https_strict_mode = false
 
-  # === Global Async Toggle ===
+  # ============================================================================
+  # BACKGROUND JOBS & CALLBACKS
+  # ============================================================================
+  #
+  # The gem can update usage statistics and execute callbacks asynchronously
+  # using ActiveJob. For reliable operation, configure a persistent job backend
+  # (Sidekiq, GoodJob, SolidQueue, etc.).
+  #
+  # WARNING: The default :async adapter may lose jobs on app restart.
+  # The :inline adapter runs synchronously, impacting request performance.
+  # ============================================================================
 
-  # 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.
+  # Master toggle for all background job operations.
+  # When false, last_used_at, requests_count, and callbacks are NOT processed.
   # Default: true
-  # config.enable_async_operations = false
-
-  # === Usage Statistics ===
+  # config.enable_async_operations = true
 
-  # 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.
+  # Track request counts (increments requests_count on each authentication).
+  # Note: High-frequency counter updates can impact database performance.
   # Default: false
-  # config.track_requests_count = true
+  # config.track_requests_count = false
 
-  # === 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) }
+  # Queue names for background jobs.
+  # Default: :default
+  # config.stats_job_queue = :default
+  # config.callbacks_job_queue = :default
 
-  # === Engine UI Configuration ===
+  # Callbacks executed on authentication attempts.
+  # before_authentication: receives the request object
+  # after_authentication: receives the Result object (success/failure info)
+  #
+  # Default: empty procs (no-op)
+  # config.before_authentication = ->(request) { Rails.logger.info "Auth: #{request.uuid}" }
+  # config.after_authentication = ->(result) { Analytics.track(result) }
 
-  # 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"
+  # ============================================================================
+  # PERFORMANCE
+  # ============================================================================
 
-  # The text displayed for the return link.
-  # Default: "‹ Home"
-  # config.return_text = "‹ Back to Settings"
+  # 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
+  #
+  # Trade-off: A revoked key may still work for up to `cache_ttl` seconds
+  # until the cache expires.
+  #
+  # Set to 0 or nil to disable caching entirely.
+  # Default: 5.seconds
+  # config.cache_ttl = 5.seconds
 
-  # === Debugging ===
+  # ============================================================================
+  # DEBUGGING
+  # ============================================================================
 
-  # Enable verbose logging for debugging purposes.
+  # Enable verbose debug logging.
   # Default: false
-  # config.debug_logging = true
+  # config.debug_logging = false
 end