api_keys 0.4.3 → 0.5.0

data/lib/api_keys/configuration.rb

@@ -3,6 +3,7 @@
 require "active_support/core_ext/numeric/time"
 require "active_support/core_ext/string/inflections"
 require "active_support/security_utils"
+require_relative "restrictions"
 
 module ApiKeys
   # Defines the configuration options for the ApiKeys gem.
@@ -41,6 +42,19 @@ module ApiKeys
     # Security
     attr_reader :https_only_production, :https_strict_mode
 
+    # Request Restrictions
+    #
+    # @!attribute [rw] client_ip_resolver
+    #   @return [#call] Callable receiving the request and returning the client
+    #     IP address used to evaluate a key's `allowed_ips` list. The default
+    #     honors Rails' trusted-proxy handling via `request.remote_ip`; behind a
+    #     CDN, configure `config.action_dispatch.trusted_proxies` whenever
+    #     possible. A resolver that trusts a vendor header is safe only when
+    #     network ingress rejects requests that bypass that vendor.
+    #   @example
+    #     config.client_ip_resolver = ->(request) { request.headers.fetch("CF-Connecting-IP") }
+    attr_reader :client_ip_resolver
+
     # Tenant Resolution
     attr_reader :tenant_resolver
 
@@ -81,13 +95,18 @@ module ApiKeys
     #     - :permissions [Array<String>, :all] Scope ceiling for this type
     #     - :revocable [Boolean] Whether keys can be revoked (default: true)
     #     - :limit [Integer, nil] Max keys per owner per environment (nil = unlimited)
-    #     - :public [Boolean] If true AND revocable: false, store plaintext token in
-    #       metadata so it can be viewed again in dashboard. Use ONLY for publishable
-    #       keys that are designed to be embedded in distributed apps. (default: false)
+    #     - :public [Boolean] If true, store the 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 have a
+    #       finite, non-empty permissions list. (default: false)
+    #     - :restrictions [Array<Symbol>] Which request-restriction kinds keys of this
+    #       type may carry: any subset of [:origins, :ips]. Omitted means both are
+    #       allowed; `[]` forbids restrictions entirely for this type.
     #   @example
     #     config.key_types = {
-    #       publishable: { prefix: "pk", permissions: %w[read], revocable: false, public: true, limit: 1 },
-    #       secret: { prefix: "sk", permissions: :all }
+    #       publishable: { prefix: "pk", permissions: %w[read], public: true, limit: 1,
+    #                      restrictions: [:origins] },
+    #       secret: { prefix: "sk", permissions: :all, restrictions: [:ips] }
     #     }
     #
     # @!attribute [rw] environments
@@ -240,6 +259,12 @@ module ApiKeys
       @tenant_resolver = value
     end
 
+    def client_ip_resolver=(value)
+      raise ArgumentError, "client_ip_resolver must be callable" unless value.respond_to?(:call)
+
+      @client_ip_resolver = value
+    end
+
     def secure_compare_proc=(value)
       raise ArgumentError, "secure_compare_proc must be callable" unless value.respond_to?(:call)
 
@@ -403,11 +428,10 @@ module ApiKeys
           raise ArgumentError, "Key type '#{name}' limit must be a positive Integer or nil"
         end
 
+        validate_restriction_kinds!(name, type_config[:restrictions]) if type_config.key?(:restrictions)
+
         next unless type_config[:public] == true
 
-        unless type_config[:revocable] == false
-          raise ArgumentError, "Public key type '#{name}' must explicitly set revocable: false"
-        end
         unless permissions.is_a?(Array) && permissions.any?
           raise ArgumentError, "Public key type '#{name}' must have a finite, non-empty permissions list"
         end
@@ -416,6 +440,18 @@ module ApiKeys
       validate_key_type_prefixes!(key_types_hash)
     end
 
+    # A key type may declare which request-restriction kinds its keys can carry.
+    # Omitting the setting allows every kind; `[]` forbids all of them.
+    def validate_restriction_kinds!(name, kinds)
+      valid = kinds.is_a?(Array) && kinds.all? do |kind|
+        (kind.is_a?(Symbol) || kind.is_a?(String)) && ApiKeys::Restrictions::KIND_NAMES.include?(kind.to_s)
+      end
+      return if valid
+
+      raise ArgumentError,
+            "Key type '#{name}' restrictions must be an Array containing any of: #{ApiKeys::Restrictions::KIND_NAMES.join(', ')}"
+    end
+
     def validate_config_name!(value, label)
       return if valid_config_name?(value)
 
@@ -555,6 +591,11 @@ module ApiKeys
       @https_only_production = true # Warn if used over HTTP in production
       @https_strict_mode = true # Fail closed if a production request is not HTTPS
 
+      # Request Restrictions
+      # Rails' remote_ip already honors config.action_dispatch.trusted_proxies,
+      # so the sensible default is simply to trust what Rails resolved.
+      @client_ip_resolver = ->(request) { request.remote_ip }
+
       # Background Job Queues
       @stats_job_queue = :default
       @callbacks_job_queue = :default

data/lib/api_keys/engine.rb

@@ -39,6 +39,12 @@ module ApiKeys
           ApiKeys::ApiKey.attribute :scopes, json_col_type, default: []
           ApiKeys::ApiKey.attribute :metadata, json_col_type, default: {}
 
+          # Request restrictions arrived in 0.5.0. Installations that have not
+          # run `rails generate api_keys:add_restrictions` yet must not gain a
+          # virtual attribute that silently accepts writes it cannot persist.
+          if ApiKeys::ApiKey.restrictions_column?
+            ApiKeys::ApiKey.attribute :restrictions, json_col_type, default: {}
+          end
         end
       end
     end

data/lib/api_keys/errors.rb

@@ -69,5 +69,16 @@ module ApiKeys
         )
       end
     end
+
+    # Raised when request restrictions are used but the `restrictions` column is missing
+    class RestrictionsMigrationRequiredError < BaseError
+      def initialize(message = nil)
+        super(
+          message ||
+            "Request restrictions are configured but the `restrictions` database column is missing. " \
+            "Run: rails generate api_keys:add_restrictions && rails db:migrate"
+        )
+      end
+    end
   end
 end

data/lib/api_keys/models/api_key.rb

@@ -4,6 +4,7 @@ require "active_record"
 require "json"
 require_relative "../services/token_generator"
 require_relative "../services/digestor"
+require_relative "../restrictions"
 
 module ApiKeys
   # The core ActiveRecord model representing an API key.
@@ -11,6 +12,11 @@ module ApiKeys
     MAX_SCOPES = 100
     MAX_SCOPE_BYTESIZE = 128
     MAX_METADATA_BYTESIZE = 16_384
+    MAX_RESTRICTION_ENTRIES = 100
+    MAX_RESTRICTION_ENTRY_BYTESIZE = 255
+    RESTRICTIONS_COLUMN = "restrictions"
+    # Deliberately excludes `restrictions`: owners must be able to tighten a
+    # request policy even when the key itself is non-revocable.
     IMMUTABLE_IDENTITY_ATTRIBUTES = %w[
       token_digest digest_algorithm prefix last4 owner_type owner_id key_type environment
     ].freeze
@@ -26,6 +32,7 @@ module ApiKeys
     # == Attributes & Serialization ==
     # Expose the plaintext token only immediately after creation
     attr_reader :token
+    attr_accessor :expires_at_preset
 
     # JSON attributes (:scopes, :metadata) are defined in the engine initializer
     # using ActiveSupport.on_load(:active_record) to ensure DB connection is ready.
@@ -45,6 +52,62 @@ module ApiKeys
       super(cleaned)
     end
 
+    # == Request Restrictions ==
+    # Where this key may be used from. Reads always answer with a value object,
+    # so `key.restrictions.origins` works even on a key that has none.
+    #
+    # @return [ApiKeys::Restrictions]
+    def restrictions
+      return ApiKeys::Restrictions.none unless self.class.restrictions_column?
+
+      ApiKeys::Restrictions.wrap(self[:restrictions])
+    end
+
+    # Accepts a Restrictions instance, a hash of lists, or nil. Hashes are
+    # normalized into the storage shape; anything else is stored untouched so
+    # the validation, rather than a silent coercion, is what reports it.
+    def restrictions=(value)
+      ensure_restrictions_column!
+
+      normalized = if value.nil?
+                     {}
+                   elsif value.is_a?(Hash)
+                     wrapped = ApiKeys::Restrictions.wrap(value)
+                     wrapped.malformed? ? value : wrapped.to_h
+                   elsif value.is_a?(ApiKeys::Restrictions)
+                     value.malformed? ? { "__malformed__" => true } : value.to_h
+                   else
+                     value
+                   end
+      super(normalized)
+    end
+
+    # @return [Array<String>] Allowed web origins (hosts and `*.host` wildcards).
+    def allowed_origins
+      restrictions.origins
+    end
+
+    # @return [Array<String>] Allowed IP addresses and CIDR ranges.
+    def allowed_ips
+      restrictions.ips
+    end
+
+    # Accepts an array or a raw string ("example.com, *.example.com") and
+    # normalizes it, so host applications never need their own parser.
+    def allowed_origins=(value)
+      self.restrictions = restrictions.to_h.merge("origins" => ApiKeys::Restrictions.normalize_origins(value))
+    end
+
+    # Accepts an array or a raw string ("203.0.113.7, 10.0.0.0/8").
+    def allowed_ips=(value)
+      self.restrictions = restrictions.to_h.merge("ips" => ApiKeys::Restrictions.normalize_ips(value))
+    end
+
+    # @return [Boolean] true when this key carries any request restriction.
+    def restricted?
+      restrictions.restricted?
+    end
+
     # == Validations ==
     validates :token_digest, presence: true, uniqueness: { case_sensitive: true }
     validates :prefix, presence: true, length: { maximum: 64 }
@@ -73,6 +136,8 @@ module ApiKeys
     validate :token_digest_matches_algorithm
     validate :token_identifiers_are_well_formed
     validate :metadata_is_well_formed
+    validate :restrictions_are_well_formed
+    validate :restrictions_respect_key_type, if: -> { key_type.present? }
     validate :authentication_identity_is_immutable, on: :update
 
     # TODO: Add validation for scope string format
@@ -101,7 +166,15 @@ module ApiKeys
     # .publishable returns only keys with key_type: "publishable"
     # .secret returns keys that are NOT publishable (includes legacy keys with nil/blank key_type)
     scope :publishable, -> { where(key_type: "publishable") }
-    scope :secret, -> { where.not(key_type: "publishable") }
+    # SQL `!=` excludes NULL, so include pre-key-types rows explicitly. Those
+    # legacy credentials have always had secret-key capabilities.
+    scope :secret, -> {
+      where(key_type: nil).or(where.not(key_type: "publishable"))
+    }
+
+    # Keys that carry request restrictions, and keys usable from anywhere.
+    scope :restricted, -> { where.not(restrictions: [nil, {}]) }
+    scope :unrestricted, -> { where(restrictions: [nil, {}]) }
 
     # === Usage Analytics Scopes ===
     # These scopes help admin dashboards analyze API key usage patterns.
@@ -201,9 +274,12 @@ module ApiKeys
     # Keys with a key_type check the configuration
     def revocable?
       return true if key_type.blank?
-      config = key_type_config
-      return false if config.nil?
-      config.fetch(:revocable, true)
+      self.class.revocable_for(key_type_config)
+    end
+
+    # Non-revocable keys are permanent by design; other key types may expire.
+    def expirable?
+      revocable?
     end
 
     # Returns the configuration hash for this key's type
@@ -220,17 +296,17 @@ module ApiKeys
       configured_pair&.last
     end
 
-    # Returns true if this key type is configured as public AND non-revocable.
-    # Only these keys have their plaintext token stored in metadata for later viewing.
+    # Returns true if this key type is explicitly configured as public.
+    # Only these keys have their plaintext token stored for later viewing.
     # This is used for publishable keys that are designed to be embedded in distributed apps.
     def public_key_type?
       return false if key_type.blank?
       config = key_type_config
       return false if config.nil?
-      config[:public] == true && config[:revocable] == false
+      config[:public] == true
     end
 
-    # Returns the stored plaintext token for public, non-revocable keys.
+    # Returns the stored plaintext token for public keys.
     # Returns nil for all other key types (the token is only available at creation time).
     # @return [String, nil] The full plaintext token, or nil if not stored
     def viewable_token
@@ -306,8 +382,41 @@ module ApiKeys
     # == Class Methods ==
     # Most creation logic is handled by standard ActiveRecord methods + callbacks
 
+    # Whether the `restrictions` column exists. Installations that predate
+    # v0.5.0 keep working untouched until they run the generator.
+    # @return [Boolean]
+    def self.restrictions_column?
+      column_names.include?(RESTRICTIONS_COLUMN)
+    rescue StandardError
+      false
+    end
+
+    # Single source of truth for a key type's request-restriction ceiling.
+    # Omitting the setting allows every supported restriction kind.
+    def self.restriction_kinds_for(type_config)
+      return ApiKeys::Restrictions::KINDS.dup unless type_config.is_a?(Hash) && type_config.key?(:restrictions)
+
+      Array(type_config[:restrictions]).map(&:to_sym)
+    end
+
+    # Single source of truth for lifecycle policy in model and dashboard code.
+    def self.revocable_for(type_config)
+      type_config.is_a?(Hash) && type_config.fetch(:revocable, true)
+    end
+
+    # @return [Array<Symbol>] Restriction kinds this key's type permits.
+    def allowed_restriction_kinds
+      self.class.restriction_kinds_for(key_type_config)
+    end
+
     private
 
+    def ensure_restrictions_column!
+      return if self.class.restrictions_column?
+
+      raise ApiKeys::Errors::RestrictionsMigrationRequiredError
+    end
+
     # Set defaults for attributes not handled by the `attribute` API in the engine.
     def set_defaults
       # NOTE: Defaults for scopes/metadata handled by `attribute` definitions in engine initializer.
@@ -390,10 +499,11 @@ module ApiKeys
         self.expires_at = ApiKeys.configuration.expire_after.from_now
       end
 
-      # Store plaintext token in metadata for public, non-revocable keys.
+      # Store plaintext token in metadata for explicitly public keys.
       # This allows users to view the token again in the dashboard.
       # SECURITY: Only do this for keys explicitly configured as public: true
-      # AND revocable: false (e.g., publishable keys for distributed apps).
+      # Public key types must have a finite permission ceiling, but may be
+      # revocable and expirable like any other credential.
       if public_key_type?
         self.metadata = (self.metadata || {}).merge("token" => @token)
       end
@@ -467,6 +577,70 @@ module ApiKeys
       errors.add(:metadata, "must contain valid JSON data")
     end
 
+    # Restrictions are security policy: a malformed list must fail loudly at
+    # write time rather than quietly protecting nothing at authentication time.
+    def restrictions_are_well_formed
+      return unless self.class.restrictions_column?
+
+      raw = self[:restrictions]
+      return if raw.nil?
+
+      unless raw.is_a?(Hash)
+        errors.add(:restrictions, "must be an object")
+        return
+      end
+
+      errors.add(:restrictions, "must contain valid restriction data") if restrictions.malformed? && raw.keys.empty?
+
+      unknown_kinds = raw.keys.map(&:to_s) - ApiKeys::Restrictions::KIND_NAMES
+      if unknown_kinds.any?
+        errors.add(:restrictions, "contains unknown restriction kinds: #{unknown_kinds.sort.join(', ')}")
+      end
+
+      validate_restriction_list(:origins) { |entry| ApiKeys::Restrictions.valid_origin_entry?(entry) }
+      validate_restriction_list(:ips) { |entry| ApiKeys::Restrictions.valid_ip_entry?(entry) }
+    end
+
+    def validate_restriction_list(kind)
+      entries = restrictions.public_send(kind)
+
+      if entries.length > MAX_RESTRICTION_ENTRIES
+        errors.add(:restrictions, "#{kind} cannot contain more than #{MAX_RESTRICTION_ENTRIES} entries")
+      end
+
+      if entries.any? { |entry| !valid_restriction_entry_size?(entry) }
+        errors.add(:restrictions, "#{kind} entries cannot exceed #{MAX_RESTRICTION_ENTRY_BYTESIZE} bytes")
+      end
+
+      return if entries.all? { |entry| yield(entry) }
+
+      message = if kind == :origins
+                  "origins must be bare hosts like example.com or *.example.com"
+                else
+                  "ips must be valid IPv4/IPv6 addresses or CIDR ranges"
+                end
+      errors.add(:restrictions, message)
+    end
+
+    # Non-string entries are reported by the shape check below, not here.
+    def valid_restriction_entry_size?(entry)
+      return true unless entry.is_a?(String)
+      return false unless entry.valid_encoding?
+
+      entry.bytesize <= MAX_RESTRICTION_ENTRY_BYTESIZE
+    rescue ArgumentError
+      false
+    end
+
+    # Key types may declare a ceiling on the restriction kinds their keys carry,
+    # mirroring the way `permissions:` caps scopes.
+    def restrictions_respect_key_type
+      exceeded = restrictions.kinds - allowed_restriction_kinds
+      return if exceeded.empty?
+
+      errors.add(:restrictions, "#{exceeded.sort.join(', ')} are not allowed for #{key_type} keys")
+    end
+
     def authentication_identity_is_immutable
       IMMUTABLE_IDENTITY_ATTRIBUTES.each do |attribute_name|
         next unless will_save_change_to_attribute?(attribute_name)

data/lib/api_keys/models/concerns/has_api_keys.rb

@@ -219,10 +219,17 @@ module ApiKeys
         #   Must be defined in ApiKeys.configuration.key_types if provided.
         # @param environment [Symbol, nil] The environment (e.g., :test, :live).
         #   Defaults to current_environment if key_types feature is enabled.
+        # @param restrictions [Hash, ApiKeys::Restrictions, nil] Request restrictions in
+        #   storage shape, e.g. { origins: ["example.com"], ips: ["10.0.0.0/8"] }.
+        # @param allowed_origins [String, Array, nil] Convenience form of the origins list.
+        #   Accepts the raw string a form field submits ("example.com, *.example.com").
+        # @param allowed_ips [String, Array, nil] Convenience form of the IP list
+        #   ("203.0.113.7, 10.0.0.0/8").
         # @return [ApiKeys::ApiKey] The newly created ApiKey instance. The plaintext token
         #                           is available via the `#token` attribute on this instance
         #                           *only until it's reloaded*.
-        def create_api_key!(name: nil, scopes: nil, expires_at: nil, expires_at_preset: nil, metadata: nil, key_type: nil, environment: nil)
+        def create_api_key!(name: nil, scopes: nil, expires_at: nil, expires_at_preset: nil, metadata: nil,
+                            key_type: nil, environment: nil, restrictions: nil, allowed_origins: nil, allowed_ips: nil)
           config = ApiKeys.configuration
 
           # Parse expires_at_preset if provided (takes precedence over expires_at)
@@ -240,6 +247,13 @@ module ApiKeys
             check_required_columns!
           end
 
+          # Requesting restrictions (directly, or through a key type that
+          # declares a ceiling) requires the column that stores them.
+          requested_restrictions = build_restrictions(restrictions, allowed_origins, allowed_ips)
+          if requested_restrictions || restriction_ceilings_configured?(config)
+            check_restrictions_column!
+          end
+
           # Use default_key_type if not specified and key_types feature is enabled
           resolved_key_type = key_type
           if resolved_key_type.nil? && key_types_feature_enabled?(config) && config.default_key_type.present?
@@ -278,16 +292,19 @@ module ApiKeys
           # ApiKey's creation callback locks the owner row before quota validation.
           # Keep an explicit transaction here so the helper's creation workflow is
           # a single atomic unit; direct ApiKey.create! calls are protected too.
+          attributes = {
+            name: name,
+            scopes: key_scopes,
+            expires_at: expires_at,
+            metadata: metadata || {}, # Ensure metadata is at least an empty hash
+            key_type: resolved_key_type&.to_s,
+            environment: resolved_environment&.to_s
+            # prefix, token_digest, digest_algorithm are set by ApiKey callbacks
+          }
+          attributes[:restrictions] = requested_restrictions if requested_restrictions
+
           api_key = self.class.transaction do
-            self.api_keys.create!(
-              name: name,
-              scopes: key_scopes,
-              expires_at: expires_at,
-              metadata: metadata || {}, # Ensure metadata is at least an empty hash
-              key_type: resolved_key_type&.to_s,
-              environment: resolved_environment&.to_s
-              # prefix, token_digest, digest_algorithm are set by ApiKey callbacks
-            )
+            self.api_keys.create!(**attributes)
           end
 
           # Return the ApiKey instance itself.
@@ -357,6 +374,30 @@ module ApiKeys
           scopes.select { |scope| permissions.include?(scope.to_s) }
         end
 
+        # Merges the three ways a caller can express restrictions into one
+        # storage hash. Returns nil when the caller asked for none of them, so
+        # the column keeps its default and legacy installs stay untouched.
+        #
+        # @return [Hash, nil]
+        def build_restrictions(restrictions, allowed_origins, allowed_ips)
+          return nil if restrictions.nil? && allowed_origins.nil? && allowed_ips.nil?
+
+          unless restrictions.nil? || restrictions.is_a?(Hash) || restrictions.is_a?(ApiKeys::Restrictions)
+            raise ArgumentError, "restrictions must be a Hash or ApiKeys::Restrictions"
+          end
+
+          attributes = ApiKeys::Restrictions.wrap(restrictions).to_h
+          attributes["origins"] = ApiKeys::Restrictions.normalize_origins(allowed_origins) unless allowed_origins.nil?
+          attributes["ips"] = ApiKeys::Restrictions.normalize_ips(allowed_ips) unless allowed_ips.nil?
+          ApiKeys::Restrictions.wrap(attributes).to_h
+        end
+
+        # True when any configured key type declares a restriction ceiling.
+        def restriction_ceilings_configured?(config)
+          config.key_types.present? &&
+            config.key_types.any? { |_type, settings| settings.is_a?(Hash) && settings.key?(:restrictions) }
+        end
+
         # Check that required columns exist for key_types feature
         # Raises MigrationRequiredError if columns are missing
         def check_required_columns!
@@ -370,6 +411,14 @@ module ApiKeys
           end
         end
 
+        # Check that the restrictions column exists before writing to it.
+        # Raises RestrictionsMigrationRequiredError naming the generator.
+        def check_restrictions_column!
+          return if ApiKeys::ApiKey.restrictions_column?
+
+          raise ApiKeys::Errors::RestrictionsMigrationRequiredError
+        end
+
         # Example: Check if the owner has reached their API key limit.
         # def reached_api_key_limit?
         #   limit = self.class.api_keys_settings[:max_keys]