api_keys 0.5.0 → 0.6.0

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,40 @@ 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. 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:
     #   def create
@@ -31,13 +69,62 @@ 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"
+
+      # 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"
@@ -68,7 +155,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,27 +168,53 @@ 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)
         # @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]
-          return nil if expected_id && stored_id.to_s != expected_id.to_s
-          return nil unless valid_token_payload?(token)
+          bound_elsewhere = expected_id && stored_id.to_s != expected_id.to_s
 
-          token
+          # 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.
+          status = consume_handoff(decoded_payload)
+
+          # A handoff bound to another key says nothing about this one.
+          return Retrieval.new(nil, :missing).freeze if bound_elsewhere
+
+          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.
@@ -121,8 +234,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 +260,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 +280,136 @@ module ApiKeys
           nil
         end
 
+        # 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 :consumed unless cache
+
+          marker = consumption_marker_key(decoded_payload)
+          return :consumed unless marker
+          return :consumed if cache.write(marker, true, unless_exist: true, expires_in: HANDOFF_TTL)
+
+          # 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."
+          :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
+
+          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/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