api_keys 0.5.1 → 0.7.0

data/lib/api_keys/authentication.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "active_support/cache"
 require "active_support/concern"
 require_relative "services/authenticator"
 require_relative "logging"
@@ -17,6 +18,13 @@ module ApiKeys
     # The key itself is fine, so these answer 403 rather than 401 — the same
     # distinction `:missing_scope` already makes.
     FORBIDDEN_ERROR_CODES = %i[origin_not_allowed ip_not_allowed restriction_misconfigured].freeze
+    # Names the per-key reservation that lets one stats job per kind be
+    # enqueued within a debounce interval (see reserve_stats_enqueue?).
+    STATS_ENQUEUE_NAMESPACE = "api_keys:v1:stats_enqueue"
+    # The methods that read. Every other method writes. RFC 9110 §9.2.1 also
+    # names OPTIONS and TRACE safe, but an API action does not serve them,
+    # so they count as writes and need the stricter scope.
+    READ_METHODS = %w[GET HEAD].freeze
 
     included do
       # Helper methods to access the authenticated key and its owner
@@ -49,7 +57,13 @@ module ApiKeys
     private
 
     # The core authentication method.
+    #
+    # @param scope [String, Array<String>, Hash, nil] The scope(s) the key
+    #   needs. A Hash names them by HTTP method, in one line:
+    #   `scope: { read: "read", write: "write" }` asks GET and HEAD for the
+    #   read scope and every other method for the write scope.
     def authenticate_api_key!(scope: nil)
+      scope = scope_for_request_method(scope) if scope.is_a?(Hash)
       @current_api_key = nil
       remove_instance_variable(:@current_api_tenant) if instance_variable_defined?(:@current_api_tenant)
       log_debug "[ApiKeys Auth] authenticate_api_key! started for request: #{request.uuid}"
@@ -78,6 +92,7 @@ module ApiKeys
           after_auth_context[:required_scope_check] = { required: scope, passed: false }
           after_auth_context[:success] = false
           after_auth_context[:error_code] = :missing_scope
+          refused_key = @current_api_key
           @current_api_key = nil
           render_unauthorized(
             error_code: :missing_scope,
@@ -85,6 +100,20 @@ module ApiKeys
             status: :forbidden,
             required_scope: scope
           )
+          record_key_refusal(refused_key, :missing_scope)
+        elsif !api_key_trusted?(@current_api_key)
+          log_debug "[ApiKeys Auth] Trust check failed for key ID #{@current_api_key.id}."
+          after_auth_context[:required_scope_check] = { required: scope, passed: true } if scope
+          after_auth_context[:success] = false
+          after_auth_context[:error_code] = :untrusted_key
+          refused_key = @current_api_key
+          @current_api_key = nil
+          render_unauthorized(
+            error_code: :untrusted_key,
+            message: "API key is no longer trusted: the person behind it no longer stands behind it",
+            status: :forbidden
+          )
+          record_key_refusal(refused_key, :untrusted_key)
         else
           after_auth_context[:required_scope_check] = { required: scope, passed: true } if scope
           # Authentication and scope check successful, enqueue stats update
@@ -95,6 +124,8 @@ module ApiKeys
         log_debug "[ApiKeys Auth] Authentication failed. Error: #{result.error_code}, Message: #{result.message}"
         status = FORBIDDEN_ERROR_CODES.include?(result.error_code) ? :forbidden : :unauthorized
         render_unauthorized(error_code: result.error_code, message: result.message, status: status)
+        # Only identified refusals carry a key; lookup failures have none to stamp.
+        record_key_refusal(result.api_key, result.error_code) if result.api_key
       end
 
       # Enqueue after_authentication callback asynchronously regardless of success/failure
@@ -115,7 +146,35 @@ module ApiKeys
       end
     end
 
+    # Whether this request reads (GET or HEAD).
+    def reading_request?
+      READ_METHODS.include?(request.request_method)
+    end
+
+    # The scope of `scope: { read:, write: }` for this request's method. Both
+    # are required, so a forgotten one never leaves its requests unchecked.
+    # A value of nil asks for no scope.
+    def scope_for_request_method(scopes)
+      scopes = scopes.to_h.transform_keys(&:to_sym)
+      unless scopes.keys.sort == %i[read write]
+        raise ArgumentError, "scope: by HTTP method takes exactly { read: ..., write: ... }"
+      end
+
+      reading_request? ? scopes[:read] : scopes[:write]
+    end
+
+    # Whether the person behind the key still stands behind it, as the host's
+    # `config.trusted_key_check` answers. Without a check, every valid key is
+    # trusted. An error in the check is not rescued: the request fails, and
+    # never passes as trusted.
+    def api_key_trusted?(api_key)
+      check = ApiKeys.configuration.trusted_key_check
+      check.nil? || check.call(api_key) ? true : false
+    end
+
     # Renders a standard JSON error response for authentication failures.
+    # Every refusal of the gem renders here, so a host that overrides it
+    # renders them all in its own error shape.
     def render_unauthorized(error_code:, message:, status: :unauthorized, required_scope: nil)
       error_message = I18n.t("api_keys.errors.#{error_code}", default: message) rescue message
       response_body = { error: error_code, message: error_message }
@@ -129,10 +188,14 @@ module ApiKeys
       return unless ApiKeys.configuration.enable_async_operations
       return unless current_api_key
 
-      if stats_update_debounced?
+      if stats_update_debounced?(current_api_key.last_used_at)
         log_debug "[ApiKeys Auth] Skipping a recently recorded last-used update for ApiKey ID: #{current_api_key.id}"
         return
       end
+      unless reserve_stats_enqueue?(:used, current_api_key.id)
+        log_debug "[ApiKeys Auth] Skipping a last-used update already enqueued for ApiKey ID: #{current_api_key.id}"
+        return
+      end
 
       # Check ActiveJob configuration and warn if using suboptimal adapters
       adapter = ActiveJob::Base.queue_adapter
@@ -145,22 +208,126 @@ module ApiKeys
       begin
         timestamp = Time.current # Capture time once for the job
         log_debug "[ApiKeys Auth] Enqueuing UpdateStatsJob for ApiKey ID: #{current_api_key.id} at #{timestamp}"
-        ApiKeys::Jobs::UpdateStatsJob.perform_later(current_api_key.id, timestamp)
+        # Active Job answers false (instead of raising) when the adapter
+        # failed to enqueue; either way the reservation is freed.
+        unless ApiKeys::Jobs::UpdateStatsJob.perform_later(current_api_key.id, timestamp)
+          release_stats_enqueue(:used, current_api_key.id)
+          log_error "[ApiKeys Auth] UpdateStatsJob was not enqueued for key #{current_api_key.id}."
+        end
       rescue StandardError => error
+        release_stats_enqueue(:used, current_api_key.id)
         log_error "[ApiKeys Auth] Failed to enqueue UpdateStatsJob for key #{current_api_key.id} (#{error.class})."
       end
     end
 
-    def stats_update_debounced?
+    # Enqueues the refusal half of UpdateStatsJob for a key that presented its
+    # real token and was refused by a policy. It moves only last_refused_at,
+    # last_refusal_code and (with track_requests_count) refusals_count; a
+    # refusal never counts as a use. Debounced exactly like last_used_at, so a
+    # client hammering a refused key costs no more writes than a working one.
+    # Never raises: the refusal response has already been rendered.
+    def record_key_refusal(api_key, error_code)
+      return unless ApiKeys.configuration.enable_async_operations
+      return unless api_key&.id
+
+      code = error_code.to_s
+      return unless ApiKeys::ApiKey::REFUSAL_CODES.include?(code)
+      return unless ApiKeys::ApiKey.refusal_stats_columns?
+
+      if stats_update_debounced?(api_key.last_refused_at)
+        log_debug "[ApiKeys Auth] Skipping a recently recorded refusal update for ApiKey ID: #{api_key.id}"
+        return
+      end
+      unless reserve_stats_enqueue?(:refused, api_key.id)
+        log_debug "[ApiKeys Auth] Skipping a refusal update already enqueued for ApiKey ID: #{api_key.id}"
+        return
+      end
+
+      begin
+        # Active Job answers false (instead of raising) when the adapter
+        # failed to enqueue; either way the reservation is freed.
+        unless ApiKeys::Jobs::UpdateStatsJob.perform_later(api_key.id, Time.current, refusal_code: code)
+          release_stats_enqueue(:refused, api_key.id)
+          log_error "[ApiKeys Auth] A refusal stats update was not enqueued for key #{api_key.id}."
+        end
+      rescue StandardError
+        release_stats_enqueue(:refused, api_key.id)
+        raise
+      end
+    rescue StandardError => error
+      log_error "[ApiKeys Auth] Failed to enqueue a refusal stats update for key #{api_key&.id} (#{error.class})."
+    end
+
+    def stats_update_debounced?(last_recorded_at)
+      seconds = stats_debounce_seconds
+      return false unless seconds && last_recorded_at
+
+      last_recorded_at >= Time.current - seconds
+    end
+
+    # The debounce interval in seconds, or nil when every request must be
+    # recorded (exact counting with track_requests_count, or no interval).
+    def stats_debounce_seconds
       config = ApiKeys.configuration
-      return false if config.track_requests_count
+      return nil if config.track_requests_count
 
       interval = config.stats_update_interval
       seconds = interval.to_f if interval.respond_to?(:to_f)
-      return false unless seconds&.finite? && seconds.positive?
-      return false unless current_api_key.last_used_at
+      seconds&.finite? && seconds.positive? ? seconds : nil
+    end
+
+    # The persisted timestamp only debounces once a worker has written it, so
+    # a burst of requests arriving before that would each enqueue a job. With
+    # a shared cache, the first request in an interval reserves the enqueue
+    # for its key and kind (:used or :refused) atomically, with
+    # `write(..., unless_exist: true, expires_in: interval)`, and the rest of
+    # the burst is skipped.
+    #
+    # A request is skipped only when the reservation is confirmed to exist:
+    # the write answered false (not stored) and the key is then present.
+    # Stores also answer false or nil when the write itself failed (Redis
+    # returns nil on a handled error, Memcached false), and suppressing the
+    # job then would lose statistics silently. So a nil answer, an absent
+    # key, or any error enqueues. It also enqueues when debouncing does not
+    # apply or there is no shared cache (`NullStore`, or no Rails.cache):
+    # the persisted timestamp is then the only debounce, as before 0.6.0.
+    def reserve_stats_enqueue?(kind, api_key_id)
+      seconds = stats_debounce_seconds
+      return true unless seconds
+
+      cache = stats_enqueue_cache
+      return true unless cache
+
+      key = stats_enqueue_key(kind, api_key_id)
+      written = cache.write(key, true, unless_exist: true, expires_in: seconds)
+      return true unless written == false
+
+      cache.exist?(key) ? false : true
+    rescue StandardError => error
+      log_debug "[ApiKeys Auth] Stats enqueue reservation unavailable (#{error.class}); relying on the persisted timestamp."
+      true
+    end
+
+    # Frees a reservation whose job could not be enqueued, so the next
+    # request can try again.
+    def release_stats_enqueue(kind, api_key_id)
+      return unless stats_debounce_seconds
+
+      stats_enqueue_cache&.delete(stats_enqueue_key(kind, api_key_id))
+    rescue StandardError
+      nil
+    end
+
+    def stats_enqueue_key(kind, api_key_id)
+      "#{STATS_ENQUEUE_NAMESPACE}:#{kind}:#{api_key_id}"
+    end
+
+    # A cache every process shares can deduplicate; NullStore remembers nothing.
+    def stats_enqueue_cache
+      cache = Rails.cache if defined?(Rails) && Rails.respond_to?(:cache)
+      return nil if cache.nil? || cache.is_a?(ActiveSupport::Cache::NullStore)
 
-      current_api_key.last_used_at >= Time.current - seconds
+      cache
     end
 
     # Helper to safely enqueue callback jobs.

data/lib/api_keys/configuration.rb

@@ -63,6 +63,31 @@ module ApiKeys
     # Tenant Resolution
     attr_reader :tenant_resolver
 
+    # The person behind a key
+    #
+    # @!attribute [rw] trusted_key_check
+    #   @return [#call, nil] Callable receiving the authenticated ApiKey and
+    #     answering whether the person behind it still stands behind it. When
+    #     it answers false or nil, `authenticate_api_key!` refuses the request
+    #     with 403 `untrusted_key`. It runs after the scope check. nil (the
+    #     default) trusts every valid key.
+    #   @example A key acts while its creator still manages the organization
+    #     config.trusted_key_check = ->(api_key) { api_key.owner.managed_by?(api_key.created_by) }
+    attr_reader :trusted_key_check
+
+    # Idempotency-Key, for tests only
+    #
+    # @!attribute [rw] idempotency_in_test_transactions
+    #   @return [Boolean] Lets ApiKeys::IdempotencyKey.hold run inside an open
+    #     database transaction, as transactional tests open one around each
+    #     test. There the key's claim is a savepoint that the test's rollback
+    #     removes. It takes true only when Rails.env is test, and it counts
+    #     only while Rails.env is test.
+    #     Default: false.
+    #   @example config/environments/test.rb, or the test helper
+    #     ApiKeys.configuration.idempotency_in_test_transactions = true
+    attr_reader :idempotency_in_test_transactions
+
     # Callbacks (Placeholders for future extension)
     attr_reader :before_authentication, :after_authentication
 
@@ -107,6 +132,13 @@ module ApiKeys
     #     - :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.
+    #     - :scopes [Symbol] Where scope checks for keys of this type look.
+    #       `:stored` (default) checks the scopes each key stored at creation,
+    #       capped by the type's permissions. `:ceiling` makes the type's live
+    #       `permissions` list the contract: every key of the type is authorized
+    #       for exactly that list, so widening or narrowing it applies to existing
+    #       keys immediately, and stored scopes become metadata. `:ceiling`
+    #       requires a finite, non-empty permissions list (never `:all`).
     #   @example
     #     config.key_types = {
     #       publishable: { prefix: "pk", permissions: %w[read], public: true, limit: 1,
@@ -147,6 +179,9 @@ module ApiKeys
     VALID_HASH_STRATEGIES = %i[sha256 bcrypt].freeze
     VALID_TOKEN_ALPHABETS = %i[base58 hex].freeze
     VALID_DASHBOARD_CONTENT_SECURITY_POLICIES = [:default, :strict, false, nil].freeze
+    # Where a key type's scope checks look: the scopes each key stored at
+    # creation (default), or the type's live permission ceiling.
+    KEY_TYPE_SCOPE_SOURCES = %w[stored ceiling].freeze
     TOKEN_LENGTH_RANGE = (16..64)
     MAX_CONFIGURED_SCOPES = 100
     CONFIG_NAME_PATTERN = /\A[a-zA-Z0-9_-]{1,64}\z/
@@ -264,6 +299,27 @@ module ApiKeys
       @tenant_resolver = value
     end
 
+    def idempotency_in_test_transactions=(value)
+      raise ArgumentError, "idempotency_in_test_transactions must be true or false" unless [true, false].include?(value)
+      if value && !test_environment?
+        raise ArgumentError, "idempotency_in_test_transactions is for transactional tests only: Rails.env must be test"
+      end
+
+      @idempotency_in_test_transactions = value
+    end
+
+    # Whether hold may run inside an open transaction: the switch is on, and
+    # Rails.env is still test when it is used.
+    def idempotency_in_test_transactions?
+      @idempotency_in_test_transactions == true && test_environment?
+    end
+
+    def trusted_key_check=(value)
+      raise ArgumentError, "trusted_key_check must be callable or nil" unless value.nil? || value.respond_to?(:call)
+
+      @trusted_key_check = value
+    end
+
     def client_ip_resolver=(value)
       raise ArgumentError, "client_ip_resolver must be callable" unless value.respond_to?(:call)
 
@@ -392,6 +448,10 @@ module ApiKeys
 
     private
 
+    def test_environment?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.test? ? true : false
+    end
+
     def validate_resolved_prefix!(prefix)
       valid = prefix.is_a?(String) && prefix.present? && prefix.valid_encoding? && prefix.bytesize <= 64 &&
         prefix.each_codepoint.none? { |codepoint| codepoint <= 0x20 || codepoint == 0x7f }
@@ -434,6 +494,7 @@ module ApiKeys
         end
 
         validate_restriction_kinds!(name, type_config[:restrictions]) if type_config.key?(:restrictions)
+        validate_scope_source!(name, type_config[:scopes], permissions) if type_config.key?(:scopes)
 
         next unless type_config[:public] == true
 
@@ -457,6 +518,21 @@ module ApiKeys
             "Key type '#{name}' restrictions must be an Array containing any of: #{ApiKeys::Restrictions::KIND_NAMES.join(', ')}"
     end
 
+    # `scopes: :ceiling` makes the type's permission list authoritative for every
+    # existing key of the type. Against `:all` (or an empty list) that would turn
+    # each key into an unbounded or useless credential, so only a finite,
+    # non-empty ceiling may be the contract.
+    def validate_scope_source!(name, source, permissions)
+      unless (source.is_a?(Symbol) || source.is_a?(String)) && KEY_TYPE_SCOPE_SOURCES.include?(source.to_s)
+        raise ArgumentError, "Key type '#{name}' scopes must be :stored or :ceiling"
+      end
+      return unless source.to_s == "ceiling"
+      return if permissions.is_a?(Array) && permissions.any?
+
+      raise ArgumentError,
+            "Key type '#{name}' uses scopes: :ceiling, so its permissions must be a finite, non-empty list (never :all)"
+    end
+
     def validate_config_name!(value, label)
       return if valid_config_name?(value)
 
@@ -631,6 +707,12 @@ module ApiKeys
       # Tenant Resolution
       @tenant_resolver = ->(api_key) { api_key.owner if api_key.respond_to?(:owner) }
 
+      # The person behind a key: no check, every valid key is trusted
+      @trusted_key_check = nil
+
+      # Idempotency-Key: refuse every open transaction (tests may opt out)
+      @idempotency_in_test_transactions = false
+
       # Key Types & Environments (default to empty/disabled for backwards compatibility)
       @key_types = {}.freeze  # Empty = feature disabled, legacy behavior
       @environments = {}.freeze  # Empty = no environment-based prefixes

data/lib/api_keys/device_flow.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module ApiKeys
+  # The two endpoints of the OAuth 2.0 Device Authorization Grant (RFC 8628)
+  # for an API controller of the host app: `create` is the device
+  # authorization endpoint (§3.1, §3.2), and `token` is the token endpoint
+  # that the client polls (§3.4, §3.5). The host routes them and names the
+  # page where a person approves (ApiKeys::DeviceAuthorization#approve!):
+  #
+  #   class Api::DeviceAuthorizationsController < ActionController::API
+  #     include ApiKeys::DeviceFlow
+  #
+  #     private
+  #
+  #     def device_verification_uri(user_code = nil)
+  #       device_approval_url(code: user_code)
+  #     end
+  #   end
+  #
+  #   post "api/device", to: "api/device_authorizations#create"
+  #   post "api/token", to: "api/device_authorizations#token"
+  #
+  # Neither request carries a key. Errors follow RFC 6749 §5.2
+  # (`{ error, error_description }`, status 400), as OAuth device clients
+  # expect, and no answer may be cached (RFC 6749 §5.1).
+  module DeviceFlow
+    extend ActiveSupport::Concern
+
+    GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code" # RFC 8628 §3.4
+
+    # Override any of them with I18n: api_keys.device_flow.errors.<error>.
+    ERROR_DESCRIPTIONS = {
+      "authorization_pending" => "The person has not decided yet. Poll again after the interval.",
+      "slow_down" => "Polled too soon. Wait 5 seconds longer between polls from now on.",
+      "access_denied" => "The person denied the request.",
+      "expired_token" => "The codes expired. Ask for new ones.",
+      "invalid_grant" => "This device code is unknown, was used already, or belongs to another client_id.",
+      "unsupported_grant_type" => "Send grant_type=#{GRANT_TYPE}.",
+      "invalid_scope" => "Ask for scopes among: %{scopes}.",
+      # The token endpoint's invalid_scope (RFC 6749 §5.2: "exceeds the scope
+      # granted by the resource owner").
+      "scope_exceeds_approval" => "The app can no longer make the key the person approved. Ask for new codes.",
+      "invalid_request" => "Send client_id, the client's name, and device_name, the device's name: " \
+                           "at most #{ApiKeys::DeviceAuthorization::MAX_NAME_LENGTH} characters each."
+    }.freeze
+
+    # RFC 8628 §3.1 and §3.2. `scope` lists the scopes, space-separated
+    # (RFC 6749 §3.3). A client may ask for any of `config.default_scopes`
+    # that a key of `device_key_type` grants. A type whose scopes follow
+    # its ceiling grants the whole ceiling, so the request asks for all of it.
+    def create
+      key_type = device_key_type
+      ApiKeys::DeviceAuthorization.check_key_type!(key_type)
+      scopes = params.fetch(:scope) { device_default_scope }.to_s.split.uniq
+      if scopes.empty? || (scopes - ApiKeys::DeviceAuthorization.grantable_scopes(key_type)).any?
+        return render_oauth_error("invalid_scope")
+      end
+
+      authorization = ApiKeys::DeviceAuthorization.request!(
+        client_id: params[:client_id].to_s.strip, device_name: params[:device_name].to_s.strip.presence,
+        scopes: scopes, key_type: key_type, requested_from: ApiKeys.configuration.client_ip_resolver.call(request)
+      )
+      render_without_cache json: {
+        device_code: authorization.device_code, user_code: authorization.user_code,
+        verification_uri: device_verification_uri,
+        verification_uri_complete: device_verification_uri(authorization.user_code),
+        expires_in: ApiKeys::DeviceAuthorization::LIFETIME.to_i, interval: authorization.interval
+      }
+    rescue ActiveRecord::RecordInvalid => error
+      render_oauth_error(error.record.errors.include?(:scopes) ? "invalid_scope" : "invalid_request")
+    end
+
+    # RFC 8628 §3.4 and §3.5. The answer that carries the token is the only
+    # one there is. A poll from another client_id changes nothing, so the
+    # grant waits for its own client.
+    def token
+      return render_oauth_error("unsupported_grant_type") unless params[:grant_type] == GRANT_TYPE
+
+      authorization = ApiKeys::DeviceAuthorization.find_by_device_code(params[:device_code])
+      return render_oauth_error("invalid_grant") unless authorization
+
+      poll = nil
+      body = ApiKeys::DeviceAuthorization.transaction do
+        poll = authorization.poll!(client_id: params[:client_id])
+        device_token_response(authorization, poll.api_key) if poll.api_key
+      end
+      if poll.error == "invalid_scope"
+        return render_oauth_error("invalid_scope", oauth_error_description("scope_exceeds_approval"))
+      end
+      return render_oauth_error(poll.error) if poll.error
+
+      render_without_cache json: body
+    end
+
+    private
+
+    # The approval page of the host app, with the user code filled in when
+    # one is given (`verification_uri_complete`, RFC 8628 §3.3.1).
+    def device_verification_uri(_user_code = nil)
+      raise NotImplementedError,
+            "#{self.class.name} must define device_verification_uri(user_code = nil): the URL of its approval page"
+    end
+
+    # The type of the keys this flow makes. With key types configured, it
+    # must name one; the default is `config.default_key_type`.
+    def device_key_type
+      ApiKeys.configuration.default_key_type
+    end
+
+    # The scope a request without `scope` asks for, space-separated. With
+    # nil (the default) such a request fails with invalid_scope, as RFC 6749
+    # §3.3 allows.
+    def device_default_scope
+      nil
+    end
+
+    # The token response (RFC 6749 §5.1). It runs in the transaction that
+    # creates the key, so a row it writes (an audit entry) commits with the
+    # key, or neither does. Override it to add fields, and call super.
+    def device_token_response(_authorization, api_key)
+      { access_token: api_key.token, token_type: "Bearer", scope: api_key.scopes.join(" ") }
+    end
+
+    # An error response (RFC 6749 §5.2). A rate limit's `with:` can use it:
+    #   rate_limit to: 20, within: 1.hour, only: :create,
+    #     with: -> { render_oauth_error("slow_down", "Too many requests.", status: :too_many_requests) }
+    def render_oauth_error(error, description = nil, status: :bad_request)
+      description ||= oauth_error_description(error)
+      render_without_cache json: { error: error, error_description: description.presence }.compact, status: status
+    end
+
+    def oauth_error_description(name)
+      scopes = ApiKeys::DeviceAuthorization.grantable_scopes(device_key_type).join(" ")
+      I18n.t("api_keys.device_flow.errors.#{name}", default: ERROR_DESCRIPTIONS[name].to_s, scopes: scopes)
+    end
+
+    # RFC 6749 §5.1: an answer that carries a credential is never cached.
+    def render_without_cache(**options)
+      response.headers["Cache-Control"] = "no-store"
+      response.headers["Pragma"] = "no-cache"
+      render(**options)
+    end
+  end
+end

data/lib/api_keys/engine.rb

@@ -14,6 +14,15 @@ module ApiKeys
     # value takes precedence over this fallback.
     config.parent_controller = nil
 
+    # The device flow's codes are in its requests: a device code redeems a
+    # key, and a user code lets a person approve one. Request logs show
+    # neither, nor a token (RFC 8628 §5.1, RFC 6749 §10.3).
+    FILTERED_PARAMETERS = %i[device_code user_code token].freeze
+
+    initializer "api_keys.filter_parameters" do |app|
+      app.config.filter_parameters |= FILTERED_PARAMETERS
+    end
+
     # Add has_api_keys method to ActiveRecord::Base
     initializer "api_keys.active_record" do
       ActiveSupport.on_load(:active_record) do

data/lib/api_keys/errors.rb

@@ -80,5 +80,16 @@ module ApiKeys
         )
       end
     end
+
+    # Raised when a key is given a `created_by` but the columns are missing
+    class CreatedByMigrationRequiredError < BaseError
+      def initialize(message = nil)
+        super(
+          message ||
+            "A key was given a created_by, but the created_by columns are missing from api_keys. " \
+            "Run: rails generate api_keys:add_created_by && rails db:migrate"
+        )
+      end
+    end
   end
 end

data/lib/api_keys/form_builder_extensions.rb

@@ -71,7 +71,9 @@ module ApiKeys
     #   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.
+    #   render a box for every scope the key may hold, or save it through
+    #   `ApiKey#scopes_after_form_edit(offered:, checked:)`, which edits only
+    #   the offered scopes and keeps the rest.
     #   - 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