api_keys 0.5.0 → 0.6.0

data/lib/api_keys/models/api_key.rb

@@ -15,6 +15,21 @@ module ApiKeys
     MAX_RESTRICTION_ENTRIES = 100
     MAX_RESTRICTION_ENTRY_BYTESIZE = 255
     RESTRICTIONS_COLUMN = "restrictions"
+    # Refused-but-identified traffic (0.6.0). Kept apart from last_used_at and
+    # requests_count, which only ever describe successful authentications.
+    REFUSAL_STATS_COLUMNS = %w[last_refused_at refusals_count last_refusal_code].freeze
+    # Durable one-time token handoff (0.6.0): stamped by the first retrieval
+    # of the key's token through ApiKeys::TokenSession, and never cleared.
+    TOKEN_SHOWN_AT_COLUMN = "token_shown_at"
+    # Every refusal that happens after the presented token was verified, so the
+    # key is known: lifecycle, type/environment configuration, isolation,
+    # request restrictions, and scopes. Lookup failures (missing or invalid
+    # token, insecure transport) name no key and are never stamped on one.
+    REFUSAL_CODES = %w[
+      revoked_key expired_key unknown_key_type unknown_environment
+      environment_misconfigured environment_mismatch
+      origin_not_allowed ip_not_allowed restriction_misconfigured missing_scope
+    ].freeze
     # Deliberately excludes `restrictions`: owners must be able to tighten a
     # request policy even when the key itself is non-revocable.
     IMMUTABLE_IDENTITY_ATTRIBUTES = %w[
@@ -32,6 +47,11 @@ module ApiKeys
     # == Attributes & Serialization ==
     # Expose the plaintext token only immediately after creation
     attr_reader :token
+
+    # Written only by the atomic claim in `claim_token_handoff!`. Ordinary
+    # saves can never set or clear it, so no update path (a form, mass
+    # assignment, a stray `update`) can reopen a handoff that was claimed.
+    attr_readonly :token_shown_at
     attr_accessor :expires_at_preset
 
     # JSON attributes (:scopes, :metadata) are defined in the engine initializer
@@ -64,16 +84,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 +234,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?
@@ -333,11 +376,23 @@ module ApiKeys
     # - Key types mode: blank scopes means "no permissions". When you've configured
     #   key types with permission ceilings, an empty scope list should deny access,
     #   not silently bypass the entire permission system.
+    #
+    # Key types configured with `scopes: :ceiling` skip the stored list: the
+    # type's live permission ceiling is the contract, so a widened ceiling
+    # reaches existing keys and a narrowed one takes effect on the next request.
     def allows_scope?(required_scope)
       return false unless respond_to?(:scopes)
       return false unless required_scope.present?
       return false unless scopes.is_a?(Array)
 
+      if scopes_follow_ceiling?
+        # Stored scopes are metadata here, but a damaged list still means
+        # something wrote around validation: refuse rather than guess.
+        return false unless scopes.all? { |scope| valid_scope_value?(scope) }
+
+        return followed_ceiling.include?(required_scope.to_s)
+      end
+
       if scopes.blank?
         return !scope_policy_enabled?
       end
@@ -350,6 +405,78 @@ 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
+
+    # The scopes to save after a form that offered only some scopes as
+    # checkboxes was submitted: the rule the dashboard's edit form uses, for
+    # host forms built with `api_key_scopes_checkboxes`.
+    #
+    # - Offered scopes are set from the boxes: checked ones are granted,
+    #   unchecked ones removed.
+    # - Every other scope the key holds is kept, in its current order.
+    # - A checked value that was never offered is ignored, so a crafted
+    #   request cannot grant it.
+    # - A held scope outside the key's current ceiling is dropped, offered or
+    #   not. Authentication already denies it, and keeping it would make every
+    #   save of the key fail the ceiling validation. A newly checked scope
+    #   outside the ceiling is kept, so the validation reports it.
+    # - `checked: nil` means the form submitted no scopes at all (no boxes and
+    #   no sentinel): nothing is granted or removed except held scopes outside
+    #   the ceiling.
+    # - A `scopes: :ceiling` key returns its stored scopes unchanged: they are
+    #   metadata there, and the type's live ceiling authorizes the key.
+    #
+    # It only computes the list; assign it (`key.update(scopes: ...)`) to save.
+    #
+    # @param offered [Array<String, Symbol>] The scopes the form rendered as boxes.
+    # @param checked [Array<String, Symbol>, nil] The submitted values; blank
+    #   entries (the sentinel) are ignored.
+    # @return [Array<String>]
+    # @raise [ArgumentError] when +offered+ or +checked+ is not an Array (or nil for +checked+).
+    def scopes_after_form_edit(offered:, checked:)
+      raise ArgumentError, "offered must be an Array of scope names" unless offered.is_a?(Array)
+      unless checked.nil? || checked.is_a?(Array)
+        raise ArgumentError, "checked must be an Array of scope names, or nil when no scopes were submitted"
+      end
+      return scopes.deep_dup if scopes_follow_ceiling?
+
+      offered = checked.nil? ? [] : offered.map(&:to_s)
+      checked = Array(checked).reject { |scope| scope.respond_to?(:blank?) && scope.blank? }.map(&:to_s)
+      held = Array(scopes)
+
+      kept = held.select do |scope|
+        scope_within_ceiling?(scope) && (!offered.include?(scope) || checked.include?(scope))
+      end
+      added = offered.select { |scope| checked.include?(scope) && !held.include?(scope) }
+      kept + added
+    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
@@ -366,6 +493,52 @@ module ApiKeys
       allows_scope?(required_permission)
     end
 
+    # Whether scope checks for this key read its type's live permission ceiling
+    # instead of the scopes stored at creation (`scopes: :ceiling` key types).
+    # Untyped keys, keys whose type is no longer configured, and every other
+    # type answer false and keep the stored-scope behavior.
+    # @return [Boolean]
+    def scopes_follow_ceiling?
+      return false if key_type.blank?
+
+      self.class.scopes_follow_ceiling_for?(key_type_config)
+    end
+
+    # == Refused-but-identified traffic ==
+    # Stamped asynchronously when a request presents this key's real token and a
+    # policy refuses it. Installations that have not run
+    # `rails generate api_keys:add_key_activity` read nil / 0 instead of raising.
+
+    # @return [Time, nil] When the most recently recorded refusal happened.
+    def last_refused_at
+      self.class.refusal_stats_columns? ? self[:last_refused_at] : nil
+    end
+
+    # @return [Integer] Refusals counted while `track_requests_count` is on.
+    def refusals_count
+      self.class.refusal_stats_columns? ? self[:refusals_count].to_i : 0
+    end
+
+    # @return [String, nil] The error code of the most recently recorded refusal.
+    def last_refusal_code
+      self.class.refusal_stats_columns? ? self[:last_refusal_code] : nil
+    end
+
+    # == One-time token handoff ==
+
+    # When this key's token was released through the one-time handoff
+    # (ApiKeys::TokenSession). Nil when it never was, and on installations that
+    # have not run `rails generate api_keys:add_key_activity` yet.
+    # @return [Time, nil]
+    def token_shown_at
+      self.class.token_shown_at_column? ? self[:token_shown_at] : nil
+    end
+
+    # @return [Boolean] Whether the one-time handoff already released this key's token.
+    def token_shown?
+      !token_shown_at.nil?
+    end
+
     # Provides a masked version of the token for display (e.g., ak_live_••••rj4p)
     # Requires the plaintext token to be available (only right after creation).
     def masked_token
@@ -391,6 +564,105 @@ module ApiKeys
       false
     end
 
+    # Whether the refused-traffic columns exist. Installations that predate
+    # v0.6.0 keep authenticating untouched until they run the generator.
+    # @return [Boolean]
+    def self.refusal_stats_columns?
+      (REFUSAL_STATS_COLUMNS - column_names).empty?
+    rescue StandardError
+      false
+    end
+
+    # Whether the `token_shown_at` column exists. Without it the one-time
+    # handoff falls back to the cache marker alone, as in 0.5.1.
+    # @return [Boolean]
+    def self.token_shown_at_column?
+      column_names.include?(TOKEN_SHOWN_AT_COLUMN)
+    rescue StandardError
+      false
+    end
+
+    # Durably claims the one-time token handoff of the key with +id+ in one
+    # conditional statement:
+    #
+    #   UPDATE api_keys SET token_shown_at = now WHERE id = ? AND token_shown_at IS NULL
+    #
+    # The database applies it atomically, so exactly one caller ever gets true
+    # for a key: across processes, across copies of a session, and after the
+    # cache is flushed. Zero rows changed means the token was already shown or
+    # the key no longer exists, and answers false (fail closed).
+    #
+    # Answers nil when the column does not exist yet (nothing can be recorded
+    # durably). Database errors are raised, not rescued: the caller withholds
+    # the token.
+    #
+    # @param id [Integer, String] The key's primary key.
+    # @return [Boolean, nil]
+    def self.claim_token_handoff!(id)
+      return nil unless column_names.include?(TOKEN_SHOWN_AT_COLUMN)
+      return false if id.nil?
+
+      where(primary_key => id, TOKEN_SHOWN_AT_COLUMN => nil)
+        .update_all(TOKEN_SHOWN_AT_COLUMN => Time.current) == 1
+    end
+
+    # Read-only companion of `claim_token_handoff!`: whether a claim for +id+
+    # could still succeed. Nil without the column. Raises on database errors.
+    #
+    # @param id [Integer, String] The key's primary key.
+    # @return [Boolean, nil]
+    def self.token_handoff_claimable?(id)
+      return nil unless column_names.include?(TOKEN_SHOWN_AT_COLUMN)
+      return false if id.nil?
+
+      where(primary_key => id, TOKEN_SHOWN_AT_COLUMN => nil).exists?
+    end
+
+    # Single source of truth for `scopes: :ceiling`. The finite-ceiling check
+    # repeats the configuration validation on purpose: a ceiling of `:all` must
+    # never become the contract, however the configuration was produced.
+    def self.scopes_follow_ceiling_for?(type_config)
+      return false unless type_config.is_a?(Hash) && type_config[:scopes].to_s == "ceiling"
+
+      permissions = type_config[:permissions]
+      permissions.is_a?(Array) && permissions.any?
+    end
+
+    # Add-only merge of a key type's current permission ceiling into the stored
+    # scopes of every non-revoked key of that type: the backfill for types that
+    # keep stored scopes after their ceiling was widened. It only ever adds
+    # permissions the type already allows, and it re-adds any a user removed
+    # by hand, so run it only for types whose users do not curate scopes.
+    #
+    # @param key_type [Symbol, String] A configured type with a finite ceiling.
+    # @return [Integer] How many keys gained scopes.
+    def self.reconcile_scopes!(key_type:)
+      type_name, type_config = ApiKeys.configuration.key_types.find { |name, _settings| name.to_s == key_type.to_s }
+      raise ArgumentError, "Unknown key type '#{key_type}'" unless type_config
+
+      ceiling = type_config[:permissions]
+      unless ceiling.is_a?(Array) && ceiling.any?
+        raise ArgumentError, "Key type '#{key_type}' has no finite permission ceiling to reconcile"
+      end
+
+      ceiling = ceiling.map(&:to_s)
+      where(key_type: type_name.to_s, revoked_at: nil).find_each.count do |api_key|
+        api_key.with_lock do
+          # with_lock reloads the row: a key revoked (or retyped) after it was
+          # selected is skipped, so a revoked key never gains scopes.
+          next false if api_key.revoked_at.present? || api_key.key_type.to_s != type_name.to_s
+
+          stored = api_key.scopes
+          next false unless stored.is_a?(Array) && stored.all? { |scope| api_key.send(:valid_scope_value?, scope) }
+
+          merged = stored | ceiling
+          next false if merged == stored || merged.length > MAX_SCOPES
+
+          api_key.update_columns(scopes: merged, updated_at: Time.current)
+        end
+      end
+    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)
@@ -590,8 +862,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 +869,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)
@@ -651,6 +927,11 @@ module ApiKeys
 
     def scopes_respect_permission_ceiling
       return unless scopes.is_a?(Array)
+      # On a `scopes: :ceiling` key the stored list authorizes nothing. Narrowing
+      # the ceiling must not leave every existing key of the type unsaveable
+      # (which would also block tightening its request restrictions), so only
+      # writes to the scopes themselves are held to the current ceiling.
+      return if persisted? && scopes_follow_ceiling? && !will_save_change_to_attribute?(:scopes)
 
       ceiling = permission_ceiling
       return if ceiling == :all
@@ -699,6 +980,11 @@ module ApiKeys
       false
     end
 
+    # The live ceiling a `scopes: :ceiling` key is authorized for.
+    def followed_ceiling
+      Array(key_type_config&.[](:permissions)).map(&:to_s)
+    end
+
     def permission_ceiling
       if key_type.present?
         config = key_type_config

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.6.0"
 end

data/lib/api_keys.rb

@@ -42,6 +42,13 @@ module ApiKeys
     def reset_configuration!
       @configuration = ::ApiKeys::Configuration.new
     end
+
+    # Add-only backfill after widening a key type's `permissions:` ceiling, for
+    # types that keep stored scopes. See ApiKeys::ApiKey.reconcile_scopes!.
+    # @return [Integer] How many keys gained scopes.
+    def reconcile_scopes!(key_type:)
+      ::ApiKeys::ApiKey.reconcile_scopes!(key_type: key_type)
+    end
   end
 end