api_keys 0.5.0 → 0.5.1

data/lib/api_keys/form_builder_extensions.rb

@@ -21,6 +21,8 @@ module ApiKeys
   #       <%= scope %>
   #     </label>
   #   <% end %>
+  #   (The helper prepends an empty `api_key[scopes][]` sentinel so that
+  #   clearing every box submits "no scopes" instead of nothing.)
   #
   module FormBuilderExtensions
     # Renders a select field for API key expiration presets.
@@ -62,6 +64,25 @@ module ApiKeys
     #   - :none - no scopes checked
     #   - Array - specific scopes to check
     #   - nil - uses the object's current scopes
+    # @param include_hidden [Boolean, nil] With a block, whether to render an
+    #   empty `name="api_key[scopes][]" value=""` sentinel before the boxes.
+    #   Browsers omit unchecked boxes, so without it clearing every box submits
+    #   no scopes parameter at all, and a create would silently get the default
+    #   scopes while an update would keep the old ones. With the sentinel the
+    #   server receives `[""]`, which `ApiKey#scopes=` and `create_api_key!`
+    #   read as "no scopes". The submitted list replaces the key's scopes, so
+    #   render a box for every scope the key may hold.
+    #   - nil (default): render it when there is at least one box and the
+    #     form's key enforces its scopes (`ApiKey#scopes_enforced?`). Elsewhere
+    #     an empty list would mean "unrestricted" and clearing the boxes would
+    #     widen the key. Per-owner default scopes are read through the key's
+    #     `owner`, so build the form's key from its owner
+    #     (`owner.api_keys.build`): a form with no object, or on a bare
+    #     `ApiKey.new`, cannot see them and renders no sentinel.
+    #   - true: render it whenever there is at least one box, without asking
+    #     the key. Use it on those ownerless forms when an empty list grants
+    #     nothing in your app.
+    #   - false: never render it.
     # @return [String, Array] HTML if block given, otherwise array of scope data
     #
     # @example With block (recommended for custom styling)
@@ -72,27 +93,30 @@ module ApiKeys
     #     </label>
     #   <% end %>
     #
-    # @example Simple rendering without block
+    # @example Simple rendering without block (render the sentinel yourself)
+    #   <%= hidden_field_tag "api_key[scopes][]", "", id: nil %>
     #   <% form.api_key_scopes_checkboxes(@scopes).each do |scope_data| %>
     #     <%= check_box_tag "api_key[scopes][]", scope_data[:value], scope_data[:checked] %>
     #     <%= scope_data[:value] %>
     #   <% end %>
     #
-    def api_key_scopes_checkboxes(scopes, checked: nil, &block)
+    def api_key_scopes_checkboxes(scopes, checked: nil, include_hidden: nil, &block)
       # Determine which scopes should be checked
       checked_scopes = resolve_checked_scopes(scopes, checked)
+      field_name = "#{object_name}[scopes][]"
 
       scope_data = scopes.map do |scope|
         {
           value: scope,
           checked: checked_scopes.include?(scope),
-          field_name: "#{object_name}[scopes][]"
+          field_name: field_name
         }
       end
 
       if block_given?
         # Yield each scope for custom rendering
         safe_buffer = ActiveSupport::SafeBuffer.new
+        safe_buffer << @template.hidden_field_tag(field_name, "", id: nil) if render_scope_sentinel?(scopes, include_hidden)
         scope_data.each do |data|
           safe_buffer << @template.capture { yield(data[:value], data[:checked]) }
         end
@@ -135,6 +159,19 @@ module ApiKeys
 
     private
 
+    # The sentinel is only safe where an empty list grants nothing. With no
+    # boxes there is nothing to clear, so it is never rendered then. By
+    # default it also needs a key that enforces its scopes; where the key does
+    # not, an empty list would mean "unrestricted", so the parameter is left
+    # out and the key keeps the scopes it has. `include_hidden: true` skips
+    # that question for forms whose key cannot answer it.
+    def render_scope_sentinel?(scopes, include_hidden)
+      return false if include_hidden == false || scopes.empty?
+      return true if include_hidden == true
+
+      object.respond_to?(:scopes_enforced?) && object.scopes_enforced?
+    end
+
     def safe_key_type(value)
       case value.to_s
       when "publishable" then :publishable

data/lib/api_keys/helpers/token_session.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require "active_support/cache"
 require "active_support/core_ext/numeric/time"
 require "active_support/message_encryptor"
+require "digest"
 require "json"
+require "securerandom"
+require_relative "../logging"
 
 module ApiKeys
   module Helpers
@@ -16,6 +20,18 @@ module ApiKeys
     # 2. On the success page, decrypt, retrieve, and clear the token
     # 3. If the user refreshes, the token is gone
     #
+    # Deleting the payload from the session only consumes it in that session.
+    # A copy of the session taken before retrieval (a copied CookieStore
+    # cookie, or two requests racing with the same cookie) would still carry
+    # it. So each handoff also has a random ID, and the first retrieval
+    # records an atomic consumption marker for that ID in `Rails.cache`
+    # (`write(..., unless_exist: true)`). Any later retrieval of the same
+    # handoff finds the marker and gets nil. This guarantee needs a cache store
+    # that every application process shares and that implements
+    # `unless_exist:` atomically. With `ActiveSupport::Cache::NullStore` the
+    # marker cannot be recorded, so deleting the payload from the session is
+    # the only protection, as it was before 0.5.1.
+    #
     # @example In your controller
     #   # After creating a key:
     #   def create
@@ -31,13 +47,20 @@ module ApiKeys
     #   end
     #
     class TokenSession
+      extend ApiKeys::Logging
+
       # Default session key for storing the token
       DEFAULT_SESSION_KEY = :api_keys_new_token
       MAX_TOKEN_BYTESIZE = 512
       MAX_CIPHERTEXT_BYTESIZE = 4096
       MAX_KEY_ID_BYTESIZE = 128
+      # The wire format is unchanged since 0.4.0, so processes on 0.5.0 and
+      # 0.5.1 can read each other's handoffs during a rolling deploy. 0.5.1
+      # adds a random handoff ID inside the encrypted payload.
       HANDOFF_VERSION = 2
       HANDOFF_TTL = 10.minutes
+      HANDOFF_ID_PATTERN = /\A[A-Za-z0-9_-]{22,64}\z/
+      CONSUMPTION_CACHE_NAMESPACE = "api_keys:v1:token_handoff_consumed"
       ENCRYPTION_CIPHER = "aes-256-gcm"
       ENCRYPTION_SALT = "api_keys/token_session/v2"
       ENCRYPTION_PURPOSE = "api_keys.token_session"
@@ -68,7 +91,7 @@ module ApiKeys
 
           api_key_id = normalize_api_key_id(api_key.id) if api_key.respond_to?(:id)
           encrypted_payload = token_encryptor.encrypt_and_sign(
-            { "token" => token, "api_key_id" => api_key_id },
+            { "token" => token, "api_key_id" => api_key_id, "handoff_id" => SecureRandom.urlsafe_base64(24) },
             expires_in: HANDOFF_TTL,
             purpose: ENCRYPTION_PURPOSE
           )
@@ -81,7 +104,8 @@ module ApiKeys
         end
 
         # Retrieve and clear the token from the session.
-        # Returns nil if no token is stored (e.g., page was refreshed).
+        # Returns nil if no token is stored (e.g., page was refreshed), or if
+        # this handoff was already retrieved through any copy of the session.
         #
         # @param session [ActionDispatch::Request::Session] The Rails session
         # @param key [Symbol] Optional custom session key (default: :api_keys_new_token)
@@ -96,6 +120,11 @@ module ApiKeys
           decoded_payload = decode_payload(payload)
           return nil unless decoded_payload
 
+          # Any authentic retrieval attempt uses the handoff up, matching the
+          # session deletion above: a mismatched or replayed attempt never
+          # leaves the handoff available to a later one.
+          return nil unless consume_handoff(decoded_payload)
+
           token = decoded_payload["token"] || decoded_payload[:token]
           stored_id = decoded_payload["api_key_id"] || decoded_payload[:api_key_id]
           return nil if expected_id && stored_id.to_s != expected_id.to_s
@@ -121,8 +150,9 @@ module ApiKeys
           token = decoded_payload["token"] || decoded_payload[:token]
           stored_id = decoded_payload["api_key_id"] || decoded_payload[:api_key_id]
           return false if expected_id && stored_id.to_s != expected_id.to_s
+          return false unless valid_token_payload?(token)
 
-          valid_token_payload?(token)
+          !handoff_consumed?(decoded_payload)
         end
 
         private
@@ -146,6 +176,11 @@ module ApiKeys
           inner_id = normalize_api_key_id(decoded["api_key_id"] || decoded[:api_key_id])
           return nil unless outer_id == inner_id
 
+          # Handoffs written before 0.5.1 carry no ID; a present ID must be
+          # well formed, since it names the consumption marker.
+          handoff_id = decoded["handoff_id"]
+          return nil unless handoff_id.nil? || (handoff_id.is_a?(String) && handoff_id.match?(HANDOFF_ID_PATTERN))
+
           decoded
         rescue ActiveSupport::MessageEncryptor::InvalidMessage, ArgumentError
           nil
@@ -161,6 +196,60 @@ module ApiKeys
           nil
         end
 
+        # Records the consumption marker. Answers true only to the first
+        # consumer of a handoff; every later one, and any cache failure, is
+        # treated as "no token" (fail closed).
+        def consume_handoff(decoded_payload)
+          cache = consumption_cache
+          return true unless cache
+
+          marker = consumption_marker_key(decoded_payload)
+          return true unless marker
+
+          cache.write(marker, true, unless_exist: true, expires_in: HANDOFF_TTL) ? true : false
+        rescue StandardError => error
+          log_warn "[ApiKeys Security] Token handoff consumption could not be recorded (#{error.class}); withholding the token."
+          false
+        end
+
+        def handoff_consumed?(decoded_payload)
+          cache = consumption_cache
+          return false unless cache
+
+          marker = consumption_marker_key(decoded_payload)
+          return false unless marker
+
+          cache.exist?(marker)
+        rescue StandardError => error
+          log_warn "[ApiKeys Security] Token handoff consumption could not be checked (#{error.class})."
+          true
+        end
+
+        # The cache that can enforce one-time retrieval across copies of a
+        # session, or nil when there is none. NullStore accepts every write and
+        # remembers nothing, so it cannot enforce anything.
+        def consumption_cache
+          cache = Rails.cache if defined?(Rails) && Rails.respond_to?(:cache)
+          return nil if cache.nil? || cache.is_a?(ActiveSupport::Cache::NullStore)
+
+          cache
+        end
+
+        # Handoffs written by 0.5.1 are named by their random ID. Handoffs
+        # written before it have none; they are named by a domain-separated
+        # digest of their token, which the encryption authenticates and which
+        # is identical in every copy of the session. (Bare-string handoffs from
+        # before 0.4.0 are returned before decoding and have no marker.)
+        def consumption_marker_key(decoded_payload)
+          handoff_id = decoded_payload["handoff_id"]
+          return "#{CONSUMPTION_CACHE_NAMESPACE}:#{handoff_id}" if handoff_id
+
+          token = decoded_payload["token"]
+          return nil unless valid_token_payload?(token)
+
+          "#{CONSUMPTION_CACHE_NAMESPACE}:token-#{Digest::SHA256.hexdigest("api_keys token handoff\0#{token}")}"
+        end
+
         def normalize_api_key_id(value)
           return nil if value.nil?
 

data/lib/api_keys/models/api_key.rb

@@ -64,16 +64,18 @@ module ApiKeys
     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.
+    # 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)
-                     wrapped = ApiKeys::Restrictions.wrap(value)
-                     wrapped.malformed? ? value : wrapped.to_h
+                     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
@@ -212,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?
@@ -350,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
@@ -590,8 +641,6 @@ module ApiKeys
         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(', ')}")
@@ -599,6 +648,12 @@ module ApiKeys
 
       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)

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

@@ -386,10 +386,18 @@ module ApiKeys
             raise ArgumentError, "restrictions must be a Hash or ApiKeys::Restrictions"
           end
 
-          attributes = ApiKeys::Restrictions.wrap(restrictions).to_h
+          # `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?
-          ApiKeys::Restrictions.wrap(attributes).to_h
+          attributes
         end
 
         # True when any configured key type declares a restriction ceiling.

data/lib/api_keys/restrictions.rb

@@ -55,9 +55,11 @@ module ApiKeys
         known, extras = value.partition { |key, _entries| KIND_NAMES.include?(key.to_s) }
         known = known.to_h { |key, entries| [key.to_s, entries] }
 
+        # Only an absent kind means "no list". A kind that is present must
+        # hold a list; `"ips" => nil` is as malformed as `"ips" => false`.
         new(
-          origins: coerce_list(known["origins"]),
-          ips: coerce_list(known["ips"]),
+          origins: known.key?("origins") ? coerce_list(known["origins"]) : [],
+          ips: known.key?("ips") ? coerce_list(known["ips"]) : [],
           extras: extras.to_h
         )
       rescue StandardError
@@ -67,6 +69,27 @@ module ApiKeys
         new(origins: [], ips: [], extras: {}, malformed: true)
       end
 
+      # Reads a restrictions hash a caller passes in (`ApiKey#restrictions=`
+      # and `create_api_key!(restrictions:)`). A kind given as `nil` or blank
+      # text is cleared, exactly as the `allowed_origins=` / `allowed_ips=`
+      # writers clear it. Everything else passes through untouched, so
+      # `false`, wrong types, and malformed list members still fail
+      # validation. Stored rows never go through here: `wrap` reads them
+      # strictly, and a stored `null` refuses authentication.
+      #
+      # @param value [Hash, Object] Caller input; non-hashes are returned as is.
+      # @return [Hash, Object]
+      def normalize_input(value)
+        return value unless value.is_a?(Hash)
+
+        value.to_h do |kind, entries|
+          cleared = KIND_NAMES.include?(kind.to_s) && blank_input?(entries)
+          [kind, cleared ? [] : entries]
+        end
+      rescue StandardError
+        value
+      end
+
       # The shared empty instance: no origins, no IPs, no restrictions at all.
       # @return [ApiKeys::Restrictions]
       def none
@@ -128,6 +151,11 @@ module ApiKeys
       end
 
       # Splits raw input into candidate entries without interpreting them.
+      #
+      # `nil` and blank text are the raw-input spellings of an empty list (a
+      # cleared dashboard field). Every other non-string value, including
+      # `false` and a `nil` inside an array, is kept as an entry so that
+      # validation rejects it: malformed input must never read as "unrestricted".
       # @api private
       def tokenize(value)
         entries = case value
@@ -137,11 +165,14 @@ module ApiKeys
                   else [value]
                   end
 
-        entries.filter_map do |entry|
-          next entry unless entry.is_a?(String)
+        entries.each_with_object([]) do |entry, tokens|
+          unless entry.is_a?(String)
+            tokens << entry
+            next
+          end
 
           trimmed = entry.strip
-          trimmed unless trimmed.empty?
+          tokens << trimmed unless trimmed.empty?
         end
       end
 
@@ -190,26 +221,46 @@ module ApiKeys
         nil
       end
 
-      # Coerces one stored list into an array of entries, preserving anything
-      # that is not a string so validations can report it instead of the value
-      # disappearing silently.
+      # Coerces one present list (storage shape) into an array of entries.
+      #
+      # Nothing is ever dropped: `false`, `nil`, numbers, hashes, and blank
+      # strings inside an array stay as entries, and a scalar that is not a
+      # string (`false`, `nil`, `42`) becomes a single entry, so validation
+      # rejects them at write time and authentication refuses them at read
+      # time. The only spelling of an intentionally empty list is `[]` (or
+      # leaving the kind out). A string is accepted as a raw list
+      # ("a.com, b.com"), but it must contain at least one entry.
       # @api private
       def coerce_list(value)
-        entries = case value
-                  when nil then []
-                  when String then value.split(ENTRY_SEPARATOR)
-                  when Array then value
-                  else [value]
-                  end
+        case value
+        when Array
+          value.map { |entry| coerce_entry(entry) }
+        when String
+          entries = value.split(ENTRY_SEPARATOR).reject(&:empty?).map { |entry| coerce_entry(entry) }
+          entries.empty? ? [value] : entries
+        else
+          [value]
+        end
+      rescue ArgumentError
+        # A string with invalid encoding cannot be split; keep it as the
+        # invalid entry it is.
+        [value]
+      end
 
-        entries.filter_map do |entry|
-          next entry unless entry.is_a?(String)
+      # @api private
+      def blank_input?(entries)
+        entries.nil? || (entries.is_a?(String) && entries.strip.empty?)
+      rescue ArgumentError
+        false
+      end
 
-          trimmed = entry.strip.downcase
-          trimmed unless trimmed.empty?
-        rescue ArgumentError
-          entry
-        end
+      # @api private
+      def coerce_entry(entry)
+        return entry unless entry.is_a?(String)
+
+        entry.strip.downcase
+      rescue ArgumentError
+        entry
       end
 
       # Whether a stored origin entry is shaped like a host or `*.host`.
@@ -278,7 +329,7 @@ module ApiKeys
 
     # @return [Array<Symbol>] The restriction kinds actually in use.
     def kinds
-      KINDS.select { |kind| public_send(kind).any? }
+      KINDS.reject { |kind| public_send(kind).empty? }
     end
 
     # The storage shape: known lists that have entries, plus any unrecognized
@@ -286,8 +337,8 @@ module ApiKeys
     # @return [Hash]
     def to_h
       hash = {}
-      hash["origins"] = deep_copy(origins) if origins.any?
-      hash["ips"] = deep_copy(ips) if ips.any?
+      hash["origins"] = deep_copy(origins) unless origins.empty?
+      hash["ips"] = deep_copy(ips) unless ips.empty?
       hash.merge(deep_copy(extras))
     end
 

data/lib/api_keys/services/authenticator.rb

@@ -15,6 +15,12 @@ module ApiKeys
       extend ApiKeys::Logging
 
       MAX_TOKEN_BYTESIZE = 512
+      # The longest authentication header that can still carry a valid token:
+      # the token plus the "Bearer" scheme and generous separator whitespace.
+      MAX_CREDENTIAL_HEADER_BYTESIZE = MAX_TOKEN_BYTESIZE + 64
+      # Stands in for a header refused before parsing. It is not a String, so
+      # it can never match a key and always yields :invalid_token.
+      MALFORMED_CREDENTIAL = Object.new.freeze
       MAX_BCRYPT_CANDIDATES = 32
       MAX_KNOWN_PREFIXES = 1_024
       TOKEN_CACHE_NAMESPACE = "api_keys:v2:token"
@@ -125,6 +131,15 @@ module ApiKeys
           unless header_value.nil?
             return header_value unless header_value.is_a?(String)
 
+            # Check the raw header before parsing it: a regular expression over
+            # invalid UTF-8 raises, and an oversized value should never be
+            # scanned. A refused header is not a String, so valid_token?
+            # answers with the ordinary invalid_token failure.
+            unless acceptable_raw_credential?(header_value)
+              log_debug "[ApiKeys Auth] Rejected a malformed authentication header before parsing it."
+              return MALFORMED_CREDENTIAL
+            end
+
             # Handle "Bearer <token>" scheme
             match = header_value.match(/\ABearer[ \t]+(.+)\z/i)
             if match
@@ -342,6 +357,12 @@ module ApiKeys
         end.uniq
       end
 
+      # Encoding and size of the raw header, checked without any regular
+      # expression so that hostile bytes cannot raise or cost a scan.
+      def self.acceptable_raw_credential?(value)
+        value.bytesize <= MAX_CREDENTIAL_HEADER_BYTESIZE && value.valid_encoding?
+      end
+
       def self.valid_token?(token)
         return false unless token.is_a?(String)
         return false if token.empty? || token.bytesize > MAX_TOKEN_BYTESIZE || !token.valid_encoding?
@@ -464,7 +485,7 @@ module ApiKeys
           )
         end
 
-        if restrictions.origins.any?
+        unless restrictions.origins.empty?
           origin_host = ApiKeys::Restrictions.extract_origin_host(request)
           unless restrictions.origin_allowed?(origin_host)
             log_warn "[ApiKeys Security] Rejected API key ID #{api_key.id} because the request origin is not allowed."
@@ -476,7 +497,7 @@ module ApiKeys
           end
         end
 
-        if restrictions.ips.any?
+        unless restrictions.ips.empty?
           unless restrictions.ip_allowed?(resolve_client_ip(request, config))
             log_warn "[ApiKeys Security] Rejected API key ID #{api_key.id} because the request IP address is not allowed."
             return Result.failure(
@@ -510,6 +531,7 @@ module ApiKeys
                            :safe_cache_read, :safe_cache_write,
                            :normalized_cache_ttl, :cache_identifier?,
                            :safe_find_by_id, :sanitize_prefixes, :valid_token?,
+                           :acceptable_raw_credential?,
                            :production_environment?, :secure_request?,
                            :check_key_type_configuration, :check_environment_configuration,
                            :check_environment_isolation, :check_request_restrictions,

data/lib/api_keys/version.rb

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

data/lib/generators/api_keys/add_restrictions_generator.rb

@@ -41,8 +41,11 @@ module ApiKeys
         say "                        restrictions: [:origins] },"
         say "         secret:      { prefix: 'sk', permissions: :all, restrictions: [:ips] }"
         say "       }"
-        say "\n  4. Behind a CDN or proxy, make sure the client IP is truthful:"
+        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

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

@@ -300,14 +300,22 @@ ApiKeys.configure do |config|
   #   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 }
-  #
+  # 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") }
 
   # ============================================================================