api_keys 0.5.1 → 0.6.0

data/lib/api_keys/helpers/token_session.rb

@@ -23,14 +23,36 @@ module ApiKeys
     # 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.
+    # it. Two more layers make retrieval one-time across copies:
+    #
+    # 1. Durable (0.6.0): the first retrieval of a key's handoff claims the
+    #    key's `token_shown_at` column with one conditional UPDATE
+    #    (`... WHERE id = ? AND token_shown_at IS NULL`). The database makes
+    #    exactly one claim succeed, and a cache flush cannot undo it. Zero rows
+    #    changed (already shown, or the key is gone) returns nil. Installations
+    #    without the column skip this layer and behave as 0.5.1.
+    #
+    #    The claim is only durable once it commits, so it must run outside any
+    #    database transaction: the plaintext is returned before an enclosing
+    #    transaction could roll the claim back. A retrieval attempted inside an
+    #    open transaction on the ApiKey connection is therefore refused,
+    #    whatever the cache: it withholds the token with `:inside_transaction`,
+    #    records nothing, and leaves the handoff in the session, so the host
+    #    can retrieve it again outside the transaction. The check is Active
+    #    Record's transaction manager on that connection, so a transaction
+    #    opened with raw SQL (`BEGIN`) is not detected. The dashboard opens no
+    #    transaction itself; a host `around_action` that wraps its requests in
+    #    one sees the refusal.
+    # 2. Cache marker (0.5.1): each handoff has a random ID, and retrieval
+    #    records it in `Rails.cache` with `write(..., unless_exist: true)`;
+    #    a later retrieval of the same handoff finds the marker and gets nil.
+    #    With the column it is a second layer (it also covers handoffs that
+    #    name no key); without it, it is the only one, and it needs a cache
+    #    store every process shares, with an atomic `unless_exist:`, that
+    #    keeps the marker for the handoff lifetime. With
+    #    `ActiveSupport::Cache::NullStore` the marker cannot be recorded.
+    #
+    # Any failure in either layer withholds the token (fail closed).
     #
     # @example In your controller
     #   # After creating a key:
@@ -61,6 +83,48 @@ module ApiKeys
       HANDOFF_TTL = 10.minutes
       HANDOFF_ID_PATTERN = /\A[A-Za-z0-9_-]{22,64}\z/
       CONSUMPTION_CACHE_NAMESPACE = "api_keys:v1:token_handoff_consumed"
+
+      # The outcome of `retrieve_once_with_status`. `token` is set only when
+      # `status` is `:retrieved`. The other statuses are:
+      # - `:already_shown`: an authentic handoff for this key whose token an
+      #   earlier retrieval already released (a replayed copy of the session).
+      # - `:withheld`: the database or cache could not record the retrieval,
+      #   so the token is withheld rather than risk a second release.
+      # - `:inside_transaction`: retrieval ran inside an open Active Record
+      #   transaction on the ApiKey connection, where its one-time claim could
+      #   be rolled back after the token was shown. The token is withheld,
+      #   nothing is recorded, and the handoff stays in the session for a
+      #   retry outside the transaction.
+      # - `:missing`: no usable handoff for this key (none stored, expired,
+      #   tampered, or bound to another key).
+      #
+      # Inspection never prints the token.
+      Retrieval = Struct.new(:token, :status) do
+        def retrieved?
+          status == :retrieved
+        end
+
+        def already_shown?
+          status == :already_shown
+        end
+
+        # Struct's default inspection, string, pretty-print and JSON forms
+        # would all print the plaintext token; these say only whether there
+        # is one. Read it through #token.
+        def inspect
+          "#<#{self.class.name} status=#{status.inspect} token=#{token.nil? ? 'nil' : '[REDACTED]'}>"
+        end
+
+        alias_method :to_s, :inspect
+
+        def pretty_print(printer)
+          printer.text(inspect)
+        end
+
+        def as_json(*)
+          { "status" => status.to_s, "token" => (token.nil? ? nil : "[REDACTED]") }
+        end
+      end
       ENCRYPTION_CIPHER = "aes-256-gcm"
       ENCRYPTION_SALT = "api_keys/token_session/v2"
       ENCRYPTION_PURPOSE = "api_keys.token_session"
@@ -111,26 +175,46 @@ module ApiKeys
         # @param key [Symbol] Optional custom session key (default: :api_keys_new_token)
         # @return [String, nil] The token, or nil if not present
         def retrieve_once(session, key: DEFAULT_SESSION_KEY, api_key: nil, api_key_id: nil)
+          retrieve_once_with_status(session, key: key, api_key: api_key, api_key_id: api_key_id).token
+        end
+
+        # Same as `retrieve_once`, and also says why no token came back, so a
+        # page can tell a replayed handoff ("already shown") from a missing
+        # one. The token is consumed exactly as `retrieve_once` consumes it.
+        #
+        # @return [Retrieval]
+        def retrieve_once_with_status(session, key: DEFAULT_SESSION_KEY, api_key: nil, api_key_id: nil)
           payload = session.delete(key)
           expected_id = normalize_api_key_id(api_key_id || (api_key.id if api_key.respond_to?(:id)))
 
           # Plain string payloads from older versions remain readable only when
           # the caller does not request ID binding.
-          return payload if expected_id.nil? && valid_token_payload?(payload)
+          return Retrieval.new(payload, :retrieved).freeze if expected_id.nil? && valid_token_payload?(payload)
           decoded_payload = decode_payload(payload)
-          return nil unless decoded_payload
+          return Retrieval.new(nil, :missing).freeze unless decoded_payload
+
+          token = decoded_payload["token"] || decoded_payload[:token]
+          stored_id = decoded_payload["api_key_id"] || decoded_payload[:api_key_id]
+          bound_elsewhere = expected_id && stored_id.to_s != expected_id.to_s
 
           # 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)
+          status = 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
-          return nil unless valid_token_payload?(token)
+          # A handoff bound to another key says nothing about this one.
+          return Retrieval.new(nil, :missing).freeze if bound_elsewhere
 
-          token
+          if status == :inside_transaction
+            # Nothing was recorded, so the handoff goes back into the session
+            # and a retrieval outside the transaction can still release it.
+            session[key] = payload
+            return Retrieval.new(nil, :inside_transaction).freeze
+          end
+          return Retrieval.new(nil, status).freeze unless status == :consumed
+          return Retrieval.new(nil, :missing).freeze unless valid_token_payload?(token)
+
+          Retrieval.new(token, :retrieved).freeze
         end
 
         # Check if a token is available in the session without removing it.
@@ -196,23 +280,99 @@ 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).
+        # Uses the handoff up, durably first and then in the cache. Answers
+        # :consumed only to the first consumer of a handoff; a later one gets
+        # :already_shown, and any failure :withheld (fail closed).
         def consume_handoff(decoded_payload)
+          stored_id = decoded_payload["api_key_id"]
+          return refuse_inside_transaction(stored_id) if claim_could_roll_back?(stored_id)
+
+          durable = claim_durably(decoded_payload)
+          return durable unless durable.nil? || durable == :consumed
+
+          consume_cache_marker(decoded_payload)
+        rescue StandardError => error
+          log_warn "[ApiKeys Security] Token handoff could not be checked against the database (#{error.class}); withholding the token."
+          :withheld
+        end
+
+        # Whether this handoff has a durable claim that an open transaction on
+        # the api_keys connection could roll back after the token was shown.
+        # Raises on database errors (the caller withholds the token).
+        def claim_could_roll_back?(stored_id)
+          return false if stored_id.nil? || !defined?(::ApiKeys::ApiKey)
+          return false unless ::ApiKeys::ApiKey.column_names.include?(::ApiKeys::ApiKey::TOKEN_SHOWN_AT_COLUMN)
+
+          ::ApiKeys::ApiKey.connection_pool.with_connection(&:transaction_open?)
+        end
+
+        # Inside a transaction the claim is not durable until the host commits,
+        # and the token would be returned before that. No cache can stand in
+        # for it: a process-local store protects one process, and after a
+        # rollback another process would release the token again. So the
+        # retrieval is refused and records nothing (no claim, no marker). Only
+        # a read tells an already-used handoff apart, which is not put back.
+        def refuse_inside_transaction(stored_id)
+          return :already_shown if ::ApiKeys::ApiKey.token_handoff_claimable?(stored_id) == false
+
+          log_warn "[ApiKeys Security] Token handoff retrieval ran inside an open database transaction, where its " \
+                   "one-time claim could be rolled back; withholding the token and leaving the handoff in place. " \
+                   "Retrieve it outside the transaction."
+          :inside_transaction
+        end
+
+        # The durable layer: the key's `token_shown_at`, claimed by one
+        # conditional UPDATE. nil when there is no durable layer for this
+        # handoff (the column does not exist yet, or the handoff names no key).
+        def claim_durably(decoded_payload)
+          stored_id = decoded_payload["api_key_id"]
+          return nil if stored_id.nil? || !defined?(::ApiKeys::ApiKey)
+
+          case ::ApiKeys::ApiKey.claim_token_handoff!(stored_id)
+          when nil then nil
+          when true then :consumed
+          else :already_shown
+          end
+        rescue StandardError => error
+          log_warn "[ApiKeys Security] Token handoff could not be recorded in the database (#{error.class}); withholding the token."
+          :withheld
+        end
+
+        # The cache layer from 0.5.1: an atomic marker named by the handoff ID.
+        def consume_cache_marker(decoded_payload)
           cache = consumption_cache
-          return true unless cache
+          return :consumed unless cache
 
           marker = consumption_marker_key(decoded_payload)
-          return true unless marker
+          return :consumed unless marker
+          return :consumed if cache.write(marker, true, unless_exist: true, expires_in: HANDOFF_TTL)
 
-          cache.write(marker, true, unless_exist: true, expires_in: HANDOFF_TTL) ? true : false
+          # Refused: normally the marker is already there (a replay), but some
+          # stores also answer false on error, so only a marker that is
+          # really present counts as "already shown".
+          cache.exist?(marker) ? :already_shown : :withheld
         rescue StandardError => error
           log_warn "[ApiKeys Security] Token handoff consumption could not be recorded (#{error.class}); withholding the token."
-          false
+          :withheld
         end
 
+        # Read-only: whether either layer says the handoff was used up. A
+        # failed check reads as consumed (fail closed).
         def handoff_consumed?(decoded_payload)
+          durably_consumed?(decoded_payload) || cache_marker_present?(decoded_payload)
+        end
+
+        def durably_consumed?(decoded_payload)
+          stored_id = decoded_payload["api_key_id"]
+          return false if stored_id.nil? || !defined?(::ApiKeys::ApiKey)
+
+          ::ApiKeys::ApiKey.token_handoff_claimable?(stored_id) == false
+        rescue StandardError => error
+          log_warn "[ApiKeys Security] Token handoff consumption could not be checked in the database (#{error.class})."
+          true
+        end
+
+        def cache_marker_present?(decoded_payload)
           cache = consumption_cache
           return false unless cache
 

data/lib/api_keys/helpers/view_helpers.rb

@@ -19,6 +19,39 @@ module ApiKeys
     #   end
     #
     module ViewHelpers
+      # Plain-language reasons for every code ApiKeys::ApiKey::REFUSAL_CODES can
+      # stamp on a key. Written to finish the sentence "...refused, because".
+      REFUSAL_REASONS = {
+        "revoked_key" => "the key has been revoked",
+        "expired_key" => "the key has expired",
+        "unknown_key_type" => "the key's type is no longer configured",
+        "unknown_environment" => "the key's environment is no longer configured",
+        "environment_misconfigured" => "the key's environment could not be verified",
+        "environment_mismatch" => "the key was used in the wrong environment",
+        "origin_not_allowed" => "the request came from a web origin the key does not allow",
+        "ip_not_allowed" => "the request came from an IP address the key does not allow",
+        "restriction_misconfigured" => "the key's stored request restrictions could not be verified",
+        "missing_scope" => "the key lacks a permission the endpoint requires"
+      }.freeze
+      UNKNOWN_REFUSAL_REASON = "the request was refused for an unrecognized reason"
+
+      # Explains the most recently recorded refusal of a key: a request that
+      # presented the key's real token and was refused by a policy. Never echoes
+      # the stored code itself, so a tampered value cannot reach the page.
+      #
+      # @param api_key [ApiKeys::ApiKey] The API key
+      # @return [String, nil] A reason, or nil when no refusal has been recorded
+      #
+      # @example
+      #   "Last refused because #{api_key_refusal_reason(@key)}"
+      #   # => "Last refused because the request came from a web origin the key does not allow"
+      #
+      def api_key_refusal_reason(api_key)
+        return nil if api_key.last_refused_at.nil?
+
+        REFUSAL_REASONS.fetch(api_key.last_refusal_code.to_s, UNKNOWN_REFUSAL_REASON)
+      end
+
       # Returns the status of an API key as a symbol.
       #
       # @param api_key [ApiKeys::ApiKey] The API key

data/lib/api_keys/jobs/update_stats_job.rb

@@ -9,6 +9,11 @@ module ApiKeys
   module Jobs
     # Background job to update API key usage statistics (last_used_at, requests_count).
     # Enqueued by the Authentication concern after a successful request.
+    #
+    # With `refusal_code:` it records refused-but-identified traffic instead
+    # (last_refused_at, last_refusal_code, refusals_count). The two halves never
+    # share a write: a refusal is not a use, so it can never move last_used_at
+    # or requests_count, whatever the code says.
     class UpdateStatsJob < ActiveJob::Base
       include ApiKeys::Logging # Include logging helpers
 
@@ -21,7 +26,9 @@ module ApiKeys
       #
       # @param api_key_id [Integer, String] The ID of the ApiKey to update.
       # @param timestamp [Time] The timestamp of the request (when it was authenticated).
-      def perform(api_key_id, timestamp)
+      # @param refusal_code [String, nil] Present when the request was refused
+      #   after the key was identified; one of ApiKeys::ApiKey::REFUSAL_CODES.
+      def perform(api_key_id, timestamp, refusal_code: nil)
         api_key = ApiKey.find_by(id: api_key_id)
 
         unless api_key
@@ -40,6 +47,13 @@ module ApiKeys
           return
         end
 
+        # Any refusal marker at all, even a blank or unrecognized one, takes the
+        # refusal branch: the usage branch runs only for a genuine success.
+        unless refusal_code.nil?
+          record_refusal(api_key, timestamp, refusal_code)
+          return
+        end
+
         log_debug "[ApiKeys::Jobs::UpdateStatsJob] Updating stats for ApiKey ID: #{api_key_id}"
 
         # Jobs may execute out of order. Update only when this event is newer so
@@ -68,6 +82,36 @@ module ApiKeys
         log_error "[ApiKeys::Jobs::UpdateStatsJob] Unexpected error processing ApiKey ID: #{api_key_id} (#{error.class})."
         # Consider re-raising or using a dead-letter queue strategy depending on job system
       end
+
+      private
+
+      # Stamps a refusal. An installation that has not run
+      # `rails generate api_keys:add_key_activity` yet skips it quietly, so a
+      # deploy that ships code before the migration never fails these jobs.
+      def record_refusal(api_key, timestamp, refusal_code)
+        unless ApiKey.refusal_stats_columns?
+          log_debug "[ApiKeys::Jobs::UpdateStatsJob] Refusal stats columns are missing; skipping. " \
+                    "Run: rails generate api_keys:add_key_activity && rails db:migrate"
+          return
+        end
+
+        code = refusal_code.to_s
+        unless ApiKey::REFUSAL_CODES.include?(code)
+          log_warn "[ApiKeys::Jobs::UpdateStatsJob] Ignored an unrecognized refusal code for ApiKey ID: #{api_key.id}."
+          return
+        end
+
+        # Same ordering guard as last_used_at: an older refusal processed late
+        # cannot overwrite a newer one, and the code always matches its timestamp.
+        ApiKey
+          .where(id: api_key.id)
+          .where("last_refused_at IS NULL OR last_refused_at < ?", timestamp)
+          .update_all(last_refused_at: timestamp, last_refusal_code: code)
+
+        # Counted under the same switch as requests_count, which is also the only
+        # mode in which no refusal is debounced away, so the count is exact.
+        ApiKey.increment_counter(:refusals_count, api_key.id) if ApiKeys.configuration.track_requests_count
+      end
     end
   end
 end

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
@@ -356,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
@@ -401,6 +433,50 @@ module ApiKeys
       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
@@ -417,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
@@ -442,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)
@@ -706,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
@@ -754,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/version.rb

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