api_keys 0.4.3 → 0.5.1

data/lib/api_keys/configuration.rb

@@ -3,6 +3,7 @@
 require "active_support/core_ext/numeric/time"
 require "active_support/core_ext/string/inflections"
 require "active_support/security_utils"
+require_relative "restrictions"
 
 module ApiKeys
   # Defines the configuration options for the ApiKeys gem.
@@ -41,6 +42,24 @@ module ApiKeys
     # Security
     attr_reader :https_only_production, :https_strict_mode
 
+    # Request Restrictions
+    #
+    # @!attribute [rw] client_ip_resolver
+    #   @return [#call] Callable receiving the request and returning the client
+    #     IP address used to evaluate a key's `allowed_ips` list. The default,
+    #     `request.remote_ip`, is right only behind a proxy that is the sole way
+    #     in, rewrites `X-Forwarded-For`, and is covered by
+    #     `config.action_dispatch.trusted_proxies`. When the Rails server is
+    #     directly reachable, a client can forge `X-Forwarded-For`; resolve the
+    #     socket peer with `request.remote_addr` instead. A resolver that trusts
+    #     a vendor header is safe only when network ingress rejects requests
+    #     that bypass that vendor.
+    #   @example Directly reachable server
+    #     config.client_ip_resolver = ->(request) { request.remote_addr }
+    #   @example Behind Cloudflare, with direct origin access blocked
+    #     config.client_ip_resolver = ->(request) { request.headers.fetch("CF-Connecting-IP") }
+    attr_reader :client_ip_resolver
+
     # Tenant Resolution
     attr_reader :tenant_resolver
 
@@ -81,13 +100,18 @@ module ApiKeys
     #     - :permissions [Array<String>, :all] Scope ceiling for this type
     #     - :revocable [Boolean] Whether keys can be revoked (default: true)
     #     - :limit [Integer, nil] Max keys per owner per environment (nil = unlimited)
-    #     - :public [Boolean] If true AND revocable: false, store plaintext token in
-    #       metadata so it can be viewed again in dashboard. Use ONLY for publishable
-    #       keys that are designed to be embedded in distributed apps. (default: false)
+    #     - :public [Boolean] If true, store the plaintext token in metadata so it
+    #       can be viewed again in the dashboard. Use ONLY for publishable keys
+    #       designed to be embedded in distributed apps. Public types must have a
+    #       finite, non-empty permissions list. (default: false)
+    #     - :restrictions [Array<Symbol>] Which request-restriction kinds keys of this
+    #       type may carry: any subset of [:origins, :ips]. Omitted means both are
+    #       allowed; `[]` forbids restrictions entirely for this type.
     #   @example
     #     config.key_types = {
-    #       publishable: { prefix: "pk", permissions: %w[read], revocable: false, public: true, limit: 1 },
-    #       secret: { prefix: "sk", permissions: :all }
+    #       publishable: { prefix: "pk", permissions: %w[read], public: true, limit: 1,
+    #                      restrictions: [:origins] },
+    #       secret: { prefix: "sk", permissions: :all, restrictions: [:ips] }
     #     }
     #
     # @!attribute [rw] environments
@@ -240,6 +264,12 @@ module ApiKeys
       @tenant_resolver = value
     end
 
+    def client_ip_resolver=(value)
+      raise ArgumentError, "client_ip_resolver must be callable" unless value.respond_to?(:call)
+
+      @client_ip_resolver = value
+    end
+
     def secure_compare_proc=(value)
       raise ArgumentError, "secure_compare_proc must be callable" unless value.respond_to?(:call)
 
@@ -403,11 +433,10 @@ module ApiKeys
           raise ArgumentError, "Key type '#{name}' limit must be a positive Integer or nil"
         end
 
+        validate_restriction_kinds!(name, type_config[:restrictions]) if type_config.key?(:restrictions)
+
         next unless type_config[:public] == true
 
-        unless type_config[:revocable] == false
-          raise ArgumentError, "Public key type '#{name}' must explicitly set revocable: false"
-        end
         unless permissions.is_a?(Array) && permissions.any?
           raise ArgumentError, "Public key type '#{name}' must have a finite, non-empty permissions list"
         end
@@ -416,6 +445,18 @@ module ApiKeys
       validate_key_type_prefixes!(key_types_hash)
     end
 
+    # A key type may declare which request-restriction kinds its keys can carry.
+    # Omitting the setting allows every kind; `[]` forbids all of them.
+    def validate_restriction_kinds!(name, kinds)
+      valid = kinds.is_a?(Array) && kinds.all? do |kind|
+        (kind.is_a?(Symbol) || kind.is_a?(String)) && ApiKeys::Restrictions::KIND_NAMES.include?(kind.to_s)
+      end
+      return if valid
+
+      raise ArgumentError,
+            "Key type '#{name}' restrictions must be an Array containing any of: #{ApiKeys::Restrictions::KIND_NAMES.join(', ')}"
+    end
+
     def validate_config_name!(value, label)
       return if valid_config_name?(value)
 
@@ -555,6 +596,11 @@ module ApiKeys
       @https_only_production = true # Warn if used over HTTP in production
       @https_strict_mode = true # Fail closed if a production request is not HTTPS
 
+      # Request Restrictions
+      # Rails' remote_ip already honors config.action_dispatch.trusted_proxies,
+      # so the sensible default is simply to trust what Rails resolved.
+      @client_ip_resolver = ->(request) { request.remote_ip }
+
       # Background Job Queues
       @stats_job_queue = :default
       @callbacks_job_queue = :default

data/lib/api_keys/engine.rb

@@ -39,6 +39,12 @@ module ApiKeys
           ApiKeys::ApiKey.attribute :scopes, json_col_type, default: []
           ApiKeys::ApiKey.attribute :metadata, json_col_type, default: {}
 
+          # Request restrictions arrived in 0.5.0. Installations that have not
+          # run `rails generate api_keys:add_restrictions` yet must not gain a
+          # virtual attribute that silently accepts writes it cannot persist.
+          if ApiKeys::ApiKey.restrictions_column?
+            ApiKeys::ApiKey.attribute :restrictions, json_col_type, default: {}
+          end
         end
       end
     end

data/lib/api_keys/errors.rb

@@ -69,5 +69,16 @@ module ApiKeys
         )
       end
     end
+
+    # Raised when request restrictions are used but the `restrictions` column is missing
+    class RestrictionsMigrationRequiredError < BaseError
+      def initialize(message = nil)
+        super(
+          message ||
+            "Request restrictions are configured but the `restrictions` database column is missing. " \
+            "Run: rails generate api_keys:add_restrictions && rails db:migrate"
+        )
+      end
+    end
   end
 end

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?