api_keys 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d5beb5e03e8d5bc749e2a05456c2b0ac0105fb9ee7be6bb1c15e0a47800f759
-  data.tar.gz: 1da205c1b54d157cf01ef194382eae9e69b8cb1ec920f1497ab791438ad30408
+  metadata.gz: aa734bb277bbb577d7e2ad46f6adc22c735c96d958ae85551385d61175153572
+  data.tar.gz: 8628007d90fc67798f388c2c8079ba1c98386ab43f764ac1c2948d141eaa5b85
 SHA512:
-  metadata.gz: be22eed1e97b88042860f23968f3a6c84cd1ec8e60ff8547f097293d456d743fc3ad819c20696357ba3453b60fbcb3ff1e81f593160ce7b4e86e71e6777a3f8c
-  data.tar.gz: 22061fc8c3fe051cb2104dfd3e19a85226469c85bdd0190b7f22291b8e44d4d0cfacbc34dbfe8168c1ce61983f1dcb229bdac2deb220826eac11acbfd23e789d
+  metadata.gz: a7ffa6b96cc5e9bd5c02eacae8a2b542422c1b5182d0b5886ffa53b9a44860e4c7ad543af8d6c6459498c885942a37138c1f6a1384d94bd7f710cd32b8c5c9de
+  data.tar.gz: 46ab93c5d3df04e62dcd1c130f5c4cc7867626ede3beae5545d409ab57252c5801064f335aa429744c01671e43d8ee86a9ecef97d26b20ede49812e5ac7f3204

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [0.2.0] - 2025-06-03
+
+- Make gem owner-agnostic: API keys can now belong to any model (User, Organization, Team, etc.)
+- Add flexible dashboard configuration for custom owner models
+- Add support for multi-tenant and team-based API key ownership
+- Improve documentation with common ownership scenarios
+- Add configuration options for current_owner_method and authenticate_owner_method
+
 ## [0.1.0] - 2025-04-30
 
 - Initial release

data/README.md

@@ -1,8 +1,8 @@
-# 🔑 `api_keys` – Gate your Rails API with secure, self-serve API keys
+# 🔑 `api_keys` – Secure API keys for your Rails app
 
-[![Gem Version](https://badge.fury.io/rb/pay.svg)](https://badge.fury.io/rb/pay)
+[![Gem Version](https://badge.fury.io/rb/api_keys.svg)](https://badge.fury.io/rb/api_keys)
 
-`api_keys` makes it dead simple to add secure, production-ready API key authentication to your Rails app. Generate keys, restrict scopes, auto-expire tokens, revoke tokens. It also provides a self-serve dashboard for your users to self-issue and manage their API keys themselves. All tokens are hashed securely by default, and never stored in plaintext.
+`api_keys` makes it simple to add secure, production-ready API key authentication to any Rails app. Generate keys, restrict scopes, auto-expire tokens, revoke tokens, gate endpoints. It also provides a self-serve dashboard for your users to self-issue and manage their API keys themselves. All tokens are hashed securely by default, and never stored in plaintext.
 
 [ 🟢 [Live interactive demo website](https://apikeys.rameerez.com) ]
 
@@ -50,9 +50,9 @@ end
 
 It'd work the same if you want your `Organization` or your `Project` records to have API keys.
 
-### Mount the dashboard engine
+### Mount the dashboard engine so your users can self-serve API keys
 
-The goal of `api_keys` is to allow you to turn your Rails app into an API platform with secure key authentication in minutes, as in: drop in this gem and you're pretty much done.
+The goal of `api_keys` is to allow you to turn your Rails app into an API platform with secure key authentication in minutes, as in: drop in this gem and you're pretty much done with API key management.
 
 To achieve that, the gem provides a ready-to-go dashboard you can just mount in your `routes.rb` like this:
 
@@ -60,7 +60,70 @@ To achieve that, the gem provides a ready-to-go dashboard you can just mount in
 mount ApiKeys::Engine => '/settings/api-keys'
 ```
 
-Now your users can:
+#### Default behavior (User-owned keys)
+
+By default, the dashboard expects:
+- A `current_user` method that returns the currently logged-in user
+- An `authenticate_user!` method that ensures a user is logged in
+
+This works out-of-the-box with Devise and most authentication solutions where `User` owns the API keys.
+
+#### Custom owner models (Organization, Team, etc.)
+
+If your API keys belong to a different model (e.g., `Organization`), you **must** configure the dashboard in your initializer:
+
+```ruby
+# config/initializers/api_keys.rb
+ApiKeys.configure do |config|
+  # Tell the dashboard how to find the current API key owner
+  config.current_owner_method = :current_organization
+  
+  # Tell the dashboard how to ensure the owner is authenticated
+  config.authenticate_owner_method = :authenticate_organization!
+end
+```
+
+These methods must exist in your `ApplicationController` (or wherever the engine is mounted). For example:
+
+```ruby
+class ApplicationController < ActionController::Base
+  def current_organization
+    # Your logic to return the current organization
+    @current_organization ||= Organization.find(session[:organization_id])
+  end
+  
+  def authenticate_organization!
+    redirect_to login_path unless current_organization
+  end
+end
+```
+
+#### Common scenarios
+
+**Organization with user membership:**
+```ruby
+# When organizations own keys but users manage them
+config.current_owner_method = :current_organization
+config.authenticate_owner_method = :require_organization_member!
+```
+
+**Multi-tenant applications:**
+```ruby
+# When each tenant/account owns keys
+config.current_owner_method = :current_account
+config.authenticate_owner_method = :authenticate_account!
+```
+
+**Team-based ownership:**
+```ruby
+# When teams own keys
+config.current_owner_method = :current_team  
+config.authenticate_owner_method = :ensure_team_access!
+```
+
+#### What the dashboard provides
+
+Once configured, your users can:
 - self-issue new API keys
 - set expiration dates
 - attach scopes / permissions to individual keys

data/app/controllers/api_keys/application_controller.rb

@@ -13,50 +13,44 @@ module ApiKeys
     # Include the main controller concern which bundles authentication and tenant resolution
     include ApiKeys::Controller
 
-    # Ensure user is authenticated for all actions within this engine
-    # IMPORTANT: This assumes the host application provides a `current_user` method
-    # and potentially a `authenticate_user!` method (like Devise).
-    # You might need to adjust this based on the host app's authentication system.
-    before_action :authenticate_api_keys_user!
+    # Ensure the owner is authenticated for all actions within this engine
+    # This uses the configured authentication method (defaults to authenticate_user!)
+    before_action :authenticate_api_keys_owner!
 
     private
 
-    # Placeholder method to authenticate the user accessing the engine.
-    # Relies on the host application providing `authenticate_user!` and `current_user`.
-    # Developers might need to override this in their application or configure
-    # the authentication method if it differs from standard Devise/similar patterns.
-    def authenticate_api_keys_user!
-      # Try common authentication methods
-      if defined?(authenticate_user!)
-        authenticate_user!
-      elsif defined?(require_login)
-        require_login # Common in Sorcery
+    # Authenticates the owner accessing the engine.
+    # Uses the configured authentication method from ApiKeys.configuration
+    def authenticate_api_keys_owner!
+      auth_method = ApiKeys.configuration.authenticate_owner_method
+
+      # Try to call the configured authentication method
+      if auth_method && respond_to?(auth_method, true)
+        send(auth_method)
+      elsif auth_method && defined?(auth_method)
+        send(auth_method)
       else
-        # Fallback or raise error if no known authentication method is found
-        unless current_api_keys_user
-          # Redirect or render error if no user context is available
-          # Choose the appropriate action based on expected host app behavior
-          redirect_to main_app.root_path, alert: "You need to sign in or sign up before continuing." rescue render plain: "Unauthorized", status: :unauthorized
+        # Fallback: check if owner is present
+        unless current_api_keys_owner
+          redirect_to main_app.root_path, alert: "You need to sign in before continuing." rescue render plain: "Unauthorized", status: :unauthorized
         end
       end
     end
 
-    # Helper method to access the current user from the host application.
-    # Assumes the host app provides `current_user`.
-    def current_api_keys_user
-      # Use `super` if the parent controller defines `current_user`
-      # Otherwise, try calling `current_user` directly on self if it's mixed in.
-      if defined?(super)
-        super
-      elsif defined?(current_user)
-        current_user
+    # Helper method to access the current owner from the host application.
+    # Uses the configured method name (defaults to :current_user)
+    def current_api_keys_owner
+      owner_method = ApiKeys.configuration.current_owner_method
+
+      if owner_method && respond_to?(owner_method, true)
+        send(owner_method)
       else
-        nil # No user context found
+        nil # No owner context found
       end
     end
 
-    # Expose current_api_keys_user as a helper method for views
-    helper_method :current_api_keys_user
+    # Expose current_api_keys_owner as a helper method for views
+    helper_method :current_api_keys_owner
 
   end
 end

data/app/controllers/api_keys/keys_controller.rb

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
 module ApiKeys
-  # Controller for managing API keys belonging to the current user.
+  # Controller for managing API keys belonging to the current owner.
   class KeysController < ApplicationController
     before_action :set_api_key, only: [:show, :edit, :update, :revoke]
 
     # GET /keys
     def index
       # Fetch only active keys for the main list, maybe sorted by creation date
-      @api_keys = current_api_keys_user.api_keys.active.order(created_at: :desc)
+      @api_keys = current_api_keys_owner.api_keys.active.order(created_at: :desc)
       # Optionally, fetch inactive ones for a separate section or filter
-      @inactive_api_keys = current_api_keys_user.api_keys.inactive.order(created_at: :desc)
+      @inactive_api_keys = current_api_keys_owner.api_keys.inactive.order(created_at: :desc)
     end
 
     # GET /keys/:id
@@ -30,7 +30,7 @@ module ApiKeys
 
     # GET /keys/new
     def new
-      @api_key = current_api_keys_user.api_keys.build
+      @api_key = current_api_keys_owner.api_keys.build
     end
 
     # POST /keys
@@ -38,7 +38,7 @@ module ApiKeys
       # Use the HasApiKeys helper method to create the key
       begin
         # create_api_key! now returns the ApiKey instance
-        @api_key = current_api_keys_user.create_api_key!(
+        @api_key = current_api_keys_owner.create_api_key!(
           name: api_key_params[:name],
           scopes: api_key_params[:scopes],
           expires_at: parse_expiration(api_key_params[:expires_at_preset])
@@ -59,7 +59,7 @@ module ApiKeys
         render :new, status: :unprocessable_entity
       rescue => e # Catch other potential errors
         flash.now[:alert] = "An unexpected error occurred: #{e.message}"
-        @api_key = current_api_keys_user.api_keys.build(api_key_params) # Rebuild form
+        @api_key = current_api_keys_owner.api_keys.build(api_key_params) # Rebuild form
         render :new, status: :unprocessable_entity
       end
     end
@@ -93,7 +93,7 @@ module ApiKeys
 
     # Use callbacks to share common setup or constraints between actions.
     def set_api_key
-      @api_key = current_api_keys_user.api_keys.find(params[:id])
+      @api_key = current_api_keys_owner.api_keys.find(params[:id])
     rescue ActiveRecord::RecordNotFound
       redirect_to keys_path, alert: "API key not found."
     end

data/app/views/api_keys/keys/_form.html.erb

@@ -38,7 +38,7 @@
     <%# containing an array of scope strings allowed for this context. %>
     <%# This list might come from global configuration or owner-specific settings. %>
     <%# Example: @available_scopes = ["read", "write", "admin"] %>
-    <% @available_scopes = current_api_keys_user.class.api_keys_settings.dig(:default_scopes) %>
+    <% @available_scopes = current_api_keys_owner.class.api_keys_settings.dig(:default_scopes) %>
     <% if defined?(@available_scopes) && @available_scopes.present? %>
       <div>
         <%= form.label :scopes, "Permissions" %>
@@ -70,7 +70,7 @@
     <%# Define available scopes for the edit form context %>
     <%# This assumes the available scopes are the same as the default ones. %>
     <%# Consider passing @available_scopes from the controller if logic is more complex. %>
-    <% @available_scopes = current_api_keys_user.class.api_keys_settings.dig(:default_scopes) %>
+    <% @available_scopes = current_api_keys_owner.class.api_keys_settings.dig(:default_scopes) %>
     <% if defined?(@available_scopes) && @available_scopes.present? %>
       <div>
         <%= form.label :scopes, "Permissions / Scopes" %>

data/lib/api_keys/configuration.rb

@@ -24,6 +24,9 @@ module ApiKeys
     # Engine Configuration
     attr_accessor :parent_controller
 
+    # Owner Context Configuration
+    attr_accessor :current_owner_method, :authenticate_owner_method
+
     # Optional Behaviors
     attr_accessor :default_max_keys_per_owner, :require_key_name
     attr_accessor :expire_after, :default_scopes, :track_requests_count
@@ -84,6 +87,10 @@ module ApiKeys
       # Engine Configuration
       @parent_controller = '::ApplicationController'
 
+      # Owner Context Configuration
+      @current_owner_method = :current_user # Default to current_user for backward compatibility
+      @authenticate_owner_method = :authenticate_user! # Default to authenticate_user! for Devise compatibility
+
       # 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

data/lib/api_keys/version.rb

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

data/lib/api_keys.rb

@@ -2,22 +2,15 @@
 
 # This is the entry point to the gem.
 
+# Global requires that don't depend on ApiKeys module structure
 require "rails"
 require "active_record"
-require "active_support/all"
+require "active_support/all" # For ActiveSupport::SecurityUtils, etc. used in Configuration
 
-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
+# --------- Core ApiKeys Module Definition ---------
+# Define the ApiKeys module itself and its primary interface methods early.
+# This ensures that ApiKeys.configuration and ApiKeys.configure are available
+# when other gem files are loaded and potentially use them at load time.
 module ApiKeys
   # Custom error classes
   class Error < StandardError; end
@@ -25,24 +18,56 @@ module ApiKeys
   class << self
     attr_writer :configuration
 
+    # Provides access to the gem's configuration.
+    # Initializes with default settings if not already configured.
+    # Note: ApiKeys::Configuration class must be loaded before this method
+    # is called in a way that triggers instantiation (e.g. first call).
     def configuration
-      @configuration ||= Configuration.new
+      # Ensure @configuration is initialized with an instance of ApiKeys::Configuration.
+      # The ApiKeys::Configuration class itself is defined in 'api_keys/configuration.rb'.
+      @configuration ||= ::ApiKeys::Configuration.new
     end
 
-    # Configure the gem with a block (main entry point)
+    # Main configuration block for the gem.
+    # Example:
+    #   ApiKeys.configure do |config|
+    #     config.token_prefix = "my_app_"
+    #   end
     def configure
       yield(configuration)
     end
 
     # Resets the configuration to its default values.
-    # Useful for testing.
+    # Useful primarily for testing environments.
     def reset_configuration!
-      @configuration = Configuration.new
+      @configuration = ::ApiKeys::Configuration.new
     end
-
   end
 end
 
+# --------- Gem Component Requires ---------
+# Order is important here.
+# 1. Version: Typically first.
+# 2. Configuration class: Needed by ApiKeys.configuration method.
+# 3. Other components: Controllers, models, engine, etc., which might use the configuration.
+
+require "api_keys/version"
+require "api_keys/configuration" # Defines the ApiKeys::Configuration class
+
+# Files that might depend on ApiKeys.configuration being available
+require "api_keys/controller" # This can lead to loading jobs, etc.
+require "api_keys/models/concerns/has_api_keys"
+require "api_keys/models/api_key"
+
+# Rails integration (Engine)
+# The Engine might also access ApiKeys.configuration during its initialization.
+require "api_keys/engine" if defined?(Rails)
+
+# Consider if a Railtie is needed and where its require should go.
+# If it also needs ApiKeys.configuration, it should be after the main module definition
+# and after api_keys/configuration.
+# require "api_keys/railtie" if defined?(Rails::Railtie)
+
 # TODO: Require other necessary files like configuration, engine, etc.
 # require_relative "api_keys/configuration"
 # require_relative "api_keys/engine"

data/lib/generators/api_keys/install_generator.rb

@@ -46,8 +46,19 @@ module ApiKeys
         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 "\n  3. IMPORTANT: If API keys belong to a model other than User (e.g., Organization),"
+        say "     configure the owner context in `config/initializers/api_keys.rb`:", :yellow
+        say "       # For Organization-owned API keys:"
+        say "       config.current_owner_method = :current_organization"
+        say "       config.authenticate_owner_method = :authenticate_organization!"
+        say "\n     The dashboard requires these methods to exist in your ApplicationController"
+        say "     or wherever you mount the engine. They should:"
+        say "     - `current_owner_method`: return the logged-in owner (e.g., current_organization)"
+        say "     - `authenticate_owner_method`: ensure the owner is authenticated"
+        say "\n  4. Mount the API keys dashboard in your `routes.rb` to provide a self-serve interface:"
+        say "       # In config/routes.rb"
+        say "       mount ApiKeys::Engine => '/settings/api-keys'"
+        say "\n  5. In your app's API controllers, verify API keys by including `ApiKeys::Controller`:"
         say "       # Example for app/controllers/api/base_controller.rb"
         say "       class Api::BaseController < ActionController::API"
         say "         include ApiKeys::Controller"

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

@@ -38,6 +38,30 @@ ApiKeys.configure do |config|
   # Default: :sha256
   # config.hash_strategy = :bcrypt
 
+  # === Dashboard Configuration ===
+
+  # 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).
+  #
+  # If your API keys belong to a different model (e.g., Organization),
+  # you MUST configure these methods:
+
+  # 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
+
+  # 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!
+
+  # Example for Organization-owned keys:
+  # config.current_owner_method = :current_organization
+  # config.authenticate_owner_method = :authenticate_organization!
+
   # === Optional Behaviors ===
 
   # Global limit on the number of *active* keys an owner can have.
@@ -70,7 +94,7 @@ ApiKeys.configure do |config|
   # 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
+  # config.cache_ttl = 30.seconds # Higher TTL = higher risk of "revoked-but-still-valid" edge cases
 
   # === Security ===
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: api_keys
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2025-04-30 00:00:00.000000000 Z
+date: 2025-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails