api_keys 0.4.3 → 0.5.1

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,64 @@ 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; a kind given as `nil` or blank text
+    # is cleared, as the list writers do. Anything malformed is stored
+    # untouched so the validation, rather than a silent coercion, reports it.
+    def restrictions=(value)
+      ensure_restrictions_column!
+
+      normalized = if value.nil?
+                     {}
+                   elsif value.is_a?(Hash)
+                     input = ApiKeys::Restrictions.normalize_input(value)
+                     wrapped = ApiKeys::Restrictions.wrap(input)
+                     wrapped.malformed? ? input : 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 +138,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 +168,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.
@@ -139,9 +214,30 @@ module ApiKeys
 
     # == Instance Methods ==
 
+    # Revocation is the emergency control, so it must not hinge on whether the
+    # rest of the row still satisfies today's policy. A key issued before its
+    # type's permission or restriction ceiling was narrowed keeps
+    # authenticating within the narrower ceiling; refusing to revoke it would
+    # leave a credential nobody can switch off.
+    #
+    # The revocability guard always applies. When the revocation is the only
+    # pending change, the row is saved without validations: only `revoked_at`
+    # (and `updated_at`) are written, and save callbacks run as before. Other
+    # unsaved edits on the same instance are never written unvalidated: in
+    # that case the whole save is validated, exactly as before 0.5.1.
+    #
+    # The authenticator's token cache holds only a key ID and reloads the row
+    # on every hit, so the next request is refused as revoked with no cache
+    # invalidation needed.
     def revoke!
       raise ApiKeys::Errors::KeyNotRevocableError unless revocable?
-      update!(revoked_at: Time.current)
+
+      self.revoked_at = Time.current
+      if persisted? && (changes_to_save.keys - %w[revoked_at]).empty?
+        save!(validate: false)
+      else
+        save!
+      end
     end
 
     def revoked?
@@ -201,9 +297,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 +319,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
@@ -274,6 +373,34 @@ module ApiKeys
       ceiling == :all || ceiling.include?(required)
     end
 
+    # Whether this key's scope list is enforced, so an empty list grants no
+    # permissions. True for typed keys, whenever `key_types` or the global
+    # `default_scopes` are configured, and when the owner model's
+    # `has_api_keys` declares `default_scopes`. The last case is read through
+    # `owner`, so a key that does not know its owner yet (a bare `ApiKey.new`)
+    # cannot see it: build keys from their owner (`owner.api_keys.build`).
+    # False otherwise, where an empty list keeps its legacy meaning:
+    # unrestricted. Forms use it to decide whether "every box cleared" can be
+    # submitted as an empty list without widening the key.
+    #
+    # @return [Boolean]
+    def scopes_enforced?
+      scope_policy_enabled?
+    end
+
+    # Whether a scope is inside this key's current permission ceiling: its
+    # type's `permissions:`, or the configured scopes for an untyped key.
+    # A held scope outside it (left behind when a ceiling was narrowed) is
+    # already denied by `allows_scope?` and fails the ceiling validation on
+    # the next save.
+    #
+    # @param scope [String, Symbol]
+    # @return [Boolean]
+    def scope_within_ceiling?(scope)
+      ceiling = permission_ceiling
+      ceiling == :all || ceiling.include?(scope.to_s)
+    end
+
     # Alias for scopes - provides a more user-friendly API that matches
     # the configuration DSL where key types use `permissions` for scope ceiling.
     # Note: We use a method instead of alias_method because `scopes` is defined
@@ -306,8 +433,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 +550,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 +628,74 @@ 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
+
+      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) }
+
+      # Whatever made the policy malformed, it never saves: a policy that
+      # authentication would refuse must not be written in the first place.
+      if restrictions.malformed? && errors[:restrictions].empty?
+        errors.add(:restrictions, "must contain valid restriction data")
+      end
+    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,38 @@ 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
+
+          # `nil` or blank text for a kind clears it, as the list writers do.
+          # A malformed policy goes to the model as it came, so validation
+          # rejects it. Normalizing it first could reduce it to `{}`, which
+          # would create the key unrestricted.
+          input = ApiKeys::Restrictions.normalize_input(restrictions)
+          wrapped = ApiKeys::Restrictions.wrap(input)
+          return input if wrapped.malformed?
+
+          attributes = wrapped.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?
+          attributes
+        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 +419,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]