api_keys 0.4.3 → 0.5.0

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,36 @@ 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.
+  # The default trusts Rails' own resolution, which honors
+  # config.action_dispatch.trusted_proxies. Behind a CDN that terminates the
+  # connection, configure trusted_proxies whenever possible. Trust a vendor
+  # header directly only when your network ingress rejects requests that
+  # bypass that vendor; otherwise callers can spoof the address being checked.
+  # Default: ->(request) { request.remote_ip }
+  #
+  # 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.0
 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
@@ -109,6 +110,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 +118,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