api_keys 0.4.3 → 0.5.1

data/lib/generators/api_keys/add_restrictions_generator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module ApiKeys
+  module Generators
+    # Rails generator for adding the `restrictions` column to the api_keys table.
+    # This generator is for existing installations that want to lock keys to
+    # specific web origins or IP addresses. New installs get the column from the
+    # install generator, so they never need to run this.
+    class AddRestrictionsGenerator < 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_restrictions_to_api_keys.rb.erb",
+                           File.join(db_migrate_path, "add_restrictions_to_api_keys.rb")
+      end
+
+      # Displays helpful information to the user after installation.
+      def display_post_install_message
+        say "\n🌐 Request restrictions migration created!", :green
+        say "\nNext steps:"
+        say "  1. Run `rails db:migrate` to add the restrictions column."
+        say "\n  2. Lock a key to the places it may be used from:"
+        say "       user.create_api_key!(name: 'Widget key', allowed_origins: 'example.com, *.example.com')"
+        say "       key.allowed_ips = '203.0.113.7, 10.0.0.0/8'"
+        say "\n     Keys without restrictions keep working from anywhere; presence is the toggle."
+        say "\n  3. Optionally cap which restriction kinds each key type may carry:"
+        say "       config.key_types = {"
+        say "         publishable: { prefix: 'pk', permissions: %w[read], public: true,"
+        say "                        restrictions: [:origins] },"
+        say "         secret:      { prefix: 'sk', permissions: :all, restrictions: [:ips] }"
+        say "       }"
+        say "\n  4. Make sure the client IP is truthful before relying on allowed_ips:"
+        say "       # Behind a proxy that is the only way in: list it in trusted_proxies, keep the default."
+        say "       config.action_dispatch.trusted_proxies = ..."
+        say "       # Rails directly reachable: check the socket peer, or X-Forwarded-For can be forged."
+        say "       config.client_ip_resolver = ->(request) { request.remote_addr }"
+        say "       # Trust a vendor header only when ingress blocks requests that bypass that vendor."
+        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_restrictions_to_api_keys.rb.erb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Migration to add the `restrictions` column to the api_keys table.
+# This enables request restrictions: locking a key to specific web origins
+# (with `*.` subdomain wildcards) and/or to specific IP addresses and CIDR
+# ranges.
+#
+# Run this migration if you're upgrading from a version of api_keys that
+# didn't have request restrictions support. The column defaults to an empty
+# object, which means "unrestricted", so existing keys are unaffected.
+class AddRestrictionsToApiKeys < ActiveRecord::Migration<%= migration_version %>
+  CONSTRAINT_NAME = "api_keys_restrictions_is_object"
+
+  def up
+    add_column :api_keys, :restrictions, json_column_type, default: {}, null: false
+    add_restrictions_object_constraint
+  end
+
+  def down
+    remove_column :api_keys, :restrictions
+  end
+
+  private
+
+  # 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
+
+  # JSON columns can also hold arrays and scalars. The application requires an
+  # object so damaged or validation-bypassing writes cannot erase a policy.
+  def add_restrictions_object_constraint
+    return unless connection.supports_check_constraints?
+
+    expression = case connection.adapter_name.downcase
+                 when /postgres/
+                   "jsonb_typeof(restrictions) = 'object'"
+                 when /sqlite/
+                   "json_valid(restrictions) AND json_type(restrictions) = 'object'"
+                 when /mysql|trilogy/
+                   "JSON_TYPE(restrictions) = 'OBJECT'"
+                 end
+    add_check_constraint :api_keys, expression, name: CONSTRAINT_NAME if expression
+  end
+end

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

@@ -2,6 +2,8 @@
 
 # Migration responsible for creating the core api_keys table.
 class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
+  RESTRICTIONS_CONSTRAINT_NAME = "api_keys_restrictions_is_object"
+
   def change
     primary_key_type, foreign_key_type = primary_and_foreign_key_types
 
@@ -30,6 +32,10 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
       # Optional freeform metadata for tagging
       t.send(json_column_type, :metadata, default: {}, null: false)
 
+      # Optional request restrictions: which web origins and IP addresses may
+      # present this key. An empty object means the key is unrestricted.
+      t.send(json_column_type, :restrictions, default: {}, null: false)
+
       # Optional auto-expiration timestamp
       t.datetime :expires_at
 
@@ -67,6 +73,8 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
       t.index :environment
       t.index [:owner_type, :owner_id, :key_type, :environment], name: "index_api_keys_owner_type_env"
     end
+
+    add_restrictions_object_constraint
   end
 
   private
@@ -94,4 +102,18 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
     # Fallback during initial setup or if connection isn't available
     :text
   end
+
+  def add_restrictions_object_constraint
+    return unless connection.supports_check_constraints?
+
+    expression = case connection.adapter_name.downcase
+                 when /postgres/
+                   "jsonb_typeof(restrictions) = 'object'"
+                 when /sqlite/
+                   "json_valid(restrictions) AND json_type(restrictions) = 'object'"
+                 when /mysql|trilogy/
+                   "JSON_TYPE(restrictions) = 'OBJECT'"
+                 end
+    add_check_constraint :api_keys, expression, name: RESTRICTIONS_CONSTRAINT_NAME if expression
+  end
 end

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

@@ -139,23 +139,28 @@ ApiKeys.configure do |config|
   # - 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. Public types must
+  # - public:      If true, 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. Public types must
   #                use a finite, non-empty permissions array (never :all). (default: false)
   #                SECURITY: NEVER set public: true on secret keys!
+  # - restrictions: Which request-restriction kinds keys of this type may carry:
+  #                any subset of [:origins, :ips]. Omitted = both allowed.
+  #                `restrictions: []` forbids restrictions for this type.
+  #                See "REQUEST RESTRICTIONS" below.
   #
   # 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
+  #     limit: 1,                        # Only 1 publishable key per environment
+  #     restrictions: [:origins]         # Browser keys lock to domains, not IPs
   #   },
   #   secret: {
   #     prefix: "sk",                    # → sk_test_, sk_live_
-  #     permissions: :all                # No scope restrictions
+  #     permissions: :all,               # No scope restrictions
+  #     restrictions: [:ips]             # Server keys lock to addresses, not domains
   #     # revocable: true (default)
   #     # public: false (default) - NEVER store secret keys!
   #     # limit: nil (default = unlimited)
@@ -275,6 +280,44 @@ ApiKeys.configure do |config|
   # Default: true
   # config.https_strict_mode = true
 
+  # ============================================================================
+  # REQUEST RESTRICTIONS (origin and IP allowlists)
+  # ============================================================================
+  #
+  # Any key can be locked to the places it may be used from:
+  #
+  #   user.create_api_key!(name: "Widget key", allowed_origins: "example.com, *.example.com")
+  #   key.allowed_ips = "203.0.113.7, 10.0.0.0/8"
+  #
+  # Origins are matched against the browser's Origin header (falling back to
+  # Referer); IPs are matched with CIDR support. Within a list any entry
+  # admits the request; every list that is set must pass. Keys with no
+  # restrictions work from anywhere, so nothing changes until you opt in.
+  # Policy mismatches answer 403 with `origin_not_allowed` / `ip_not_allowed`.
+  # Malformed stored policy also fails closed with `restriction_misconfigured`.
+  #
+  # Requires the restrictions column:
+  #   rails generate api_keys:add_restrictions && rails db:migrate
+  # ============================================================================
+
+  # How the client IP is resolved for `allowed_ips` checks. Pick the line that
+  # matches how clients reach this Rails server:
+  #
+  # Behind a load balancer, reverse proxy, or CDN that is the ONLY way in and
+  # that overwrites or appends X-Forwarded-For, with its addresses covered by
+  # config.action_dispatch.trusted_proxies: keep the default.
+  # config.client_ip_resolver = ->(request) { request.remote_ip } # default
+  #
+  # Directly reachable (no proxy, or a proxy that can be bypassed): check the
+  # socket peer. With remote_ip, a client could send
+  # `X-Forwarded-For: <an allowed address>` and pass the check.
+  # config.client_ip_resolver = ->(request) { request.remote_addr }
+  #
+  # trusted_proxies alone is not a boundary: it does not stop a client that
+  # bypasses the proxy from sending the header. Trust a vendor header only
+  # when your network ingress rejects requests that bypass that vendor:
+  # config.client_ip_resolver = ->(request) { request.headers.fetch("CF-Connecting-IP") }
+
   # ============================================================================
   # BACKGROUND JOBS & CALLBACKS
   # ============================================================================

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_keys
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.1
 platform: ruby
 authors:
 - rameerez
@@ -84,6 +84,7 @@ files:
 - app/views/api_keys/keys/_key_status.html.erb
 - app/views/api_keys/keys/_keys_table.html.erb
 - app/views/api_keys/keys/_publishable_keys.html.erb
+- app/views/api_keys/keys/_restriction_fields.html.erb
 - app/views/api_keys/keys/_secret_keys.html.erb
 - app/views/api_keys/keys/_show_token.html.erb
 - app/views/api_keys/keys/_token_display.html.erb
@@ -94,6 +95,9 @@ files:
 - app/views/api_keys/security/best_practices.html.erb
 - app/views/layouts/api_keys/application.html.erb
 - config/routes.rb
+- docs/reviews/2026-10-18-0-5-1/01-astra-review-of-0-5-0.md
+- docs/reviews/2026-10-18-0-5-1/02-astra-re-review-of-0-5-1.md
+- docs/reviews/2026-10-18-0-5-1/03-opus-review-of-0-5-1.md
 - lib/api_keys.rb
 - lib/api_keys/authentication.rb
 - lib/api_keys/configuration.rb
@@ -109,6 +113,7 @@ files:
 - lib/api_keys/logging.rb
 - lib/api_keys/models/api_key.rb
 - lib/api_keys/models/concerns/has_api_keys.rb
+- lib/api_keys/restrictions.rb
 - lib/api_keys/services/authenticator.rb
 - lib/api_keys/services/digestor.rb
 - lib/api_keys/services/token_generator.rb
@@ -116,9 +121,11 @@ files:
 - 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/add_restrictions_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/add_restrictions_to_api_keys.rb.erb
 - 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