api_keys 0.6.0 → 0.7.0

data/lib/api_keys/models/device_authorization.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "digest"
+require "securerandom"
+
+module ApiKeys
+  # A client's request for an API key on the OAuth 2.0 Device Authorization
+  # Grant (RFC 8628, https://www.rfc-editor.org/rfc/rfc8628):
+  #
+  #   1. The client (an agent, a CLI) asks for a device code and a user code
+  #      and shows the person one link (`request!`, RFC 8628 §3.1, §3.2).
+  #   2. The person opens the link in the host app, compares the user code,
+  #      sees the client's name, its device and the scopes, and approves or
+  #      denies (`approve!`, `deny!`, §3.3).
+  #   3. The client polls. The first poll after the approval creates an
+  #      ordinary API key for the owner and answers with its token, once
+  #      (`poll!`, §3.4, §3.5).
+  #
+  # Both codes are kept as SHA-256 digests. The token is never stored: the
+  # poll that creates the key is the only answer that carries its text.
+  class DeviceAuthorization < ActiveRecord::Base
+    self.table_name = "api_keys_device_authorizations"
+
+    LIFETIME = 10.minutes
+    INTERVAL = 5 # seconds between polls: the RFC 8628 §3.2 default
+    SLOW_DOWN = 5 # "the interval MUST be increased by 5 seconds" (§3.5)
+    # Eight letters from twenty consonants: about 34.5 bits, and no word can
+    # be spelled (§6.1). Shown as BCDF-GHJK.
+    USER_CODE_ALPHABET = "BCDFGHJKLMNPQRSTVWXZ".chars.freeze
+    USER_CODE_LENGTH = 8
+    MAX_NAME_LENGTH = 60 # for client_id and device_name each
+    # `void`: approved, but the app's configuration changed so that the key
+    # can no longer be made as the person approved it. The request is closed.
+    STATES = %w[pending approved denied completed void].freeze
+
+    # Raised when a request that was decided already, or that expired, is
+    # approved or denied.
+    class Closed < ApiKeys::Error; end
+
+    # Raised by `approve!` when the owner may not have another key. The
+    # request stays pending, so the person can revoke a key and approve again
+    # before it expires.
+    class KeyLimitReached < ApiKeys::Error
+      def initialize(message = "this owner has the most API keys it may have: revoke a key, then approve again")
+        super
+      end
+    end
+
+    # The answer to a void request: RFC 6749 §5.2 "invalid_scope ... exceeds
+    # the scope granted by the resource owner". The app can no longer make
+    # the key with the scopes and the type the person approved. It is not
+    # access_denied: the person denied nothing. Clients stop on it.
+    VOID_ERROR = "invalid_scope"
+
+    # What `create_api_key!` raises when it cannot make the key.
+    KEY_CREATION_ERRORS = [
+      ActiveRecord::RecordInvalid, ArgumentError, ApiKeys::Error, ApiKeys::Errors::BaseError
+    ].freeze
+
+    # The answer to one poll: the new key, or the RFC 8628 §3.5 error code.
+    Poll = Struct.new(:api_key, :error, keyword_init: true)
+
+    belongs_to :owner, polymorphic: true, optional: true
+    belongs_to :decided_by, polymorphic: true, optional: true
+    belongs_to :api_key, class_name: "ApiKeys::ApiKey", optional: true
+
+    # In the model, not in the migration: MySQL refuses a literal default on
+    # a JSON column.
+    attribute :scopes, default: -> { [] }
+
+    # The plaintext codes, on the instance `request!` returns only.
+    attr_reader :device_code, :user_code
+
+    validates :client_id, presence: true, length: { maximum: MAX_NAME_LENGTH }
+    validates :device_name, length: { maximum: MAX_NAME_LENGTH }
+    validates :state, inclusion: { in: STATES }
+    validate :key_type_is_configured
+    validate :scopes_are_grantable
+
+    scope :undecided, -> { where(state: "pending").where("expires_at > ?", Time.current) }
+
+    STATES.each { |state| define_method(:"#{state}?") { self.state == state } }
+
+    class << self
+      # A new request. Its `device_code` and `user_code` hold the plaintext
+      # codes on this instance only.
+      #
+      # +key_type+ is the type of the key the approval makes: a configured
+      # type when key types are configured, nil otherwise.
+      #
+      # @return [ApiKeys::DeviceAuthorization]
+      # @raise [ActiveRecord::RecordInvalid] for a missing client_id, a name
+      #   that is too long, or scopes a key of the type does not grant
+      # @raise [ArgumentError] for a key type the configuration does not name
+      def request!(client_id:, scopes:, device_name: nil, requested_from: nil, key_type: nil)
+        check_key_type!(key_type)
+        device_code = SecureRandom.urlsafe_base64(32)
+        user_code = Array.new(USER_CODE_LENGTH) { USER_CODE_ALPHABET[SecureRandom.random_number(USER_CODE_ALPHABET.size)] }.join
+        authorization = create!(
+          device_code_digest: digest(device_code), user_code_digest: digest(user_code),
+          client_id: client_id, device_name: device_name, scopes: Array(scopes).uniq, key_type: key_type&.to_s,
+          requested_from: requested_from, interval: INTERVAL, expires_at: LIFETIME.from_now
+        )
+        authorization.instance_variable_set(:@device_code, device_code)
+        authorization.instance_variable_set(:@user_code, user_code.scan(/.{4}/).join("-"))
+        authorization
+      end
+
+      # The undecided request whose user code a person typed or followed.
+      # Case, spaces and dashes do not matter (§6.1).
+      def find_undecided_by_user_code(code)
+        undecided.find_by(user_code_digest: digest(code.to_s.upcase.gsub(/[^A-Z]/, "")))
+      end
+
+      def find_by_device_code(code)
+        find_by(device_code_digest: digest(code.to_s))
+      end
+
+      # The scopes a client may ask for: the app's `config.default_scopes`,
+      # the scopes a person can give a key, within the permissions of
+      # +key_type+.
+      def grantable_scopes(key_type = nil)
+        permissions = key_type_config(key_type)&.[](:permissions)
+        scopes = ApiKeys.configuration.default_scopes
+        permissions.is_a?(Array) ? scopes & permissions.map(&:to_s) : scopes
+      end
+
+      # The configuration of +key_type+, or nil.
+      def key_type_config(key_type)
+        return nil if key_type.blank?
+
+        ApiKeys.configuration.key_types.find { |name, _settings| name.to_s == key_type.to_s }&.last
+      end
+
+      # With key types configured, every key has a configured type, so the
+      # request must name one. Without them, it must name none. A wrong
+      # setting is the app's error, not the client's: it raises.
+      def check_key_type!(key_type)
+        configured = ApiKeys.configuration.key_types.keys.map(&:to_s)
+        if configured.empty?
+          return if key_type.blank?
+
+          raise ArgumentError, "the device flow names key type #{key_type.inspect}, but no key types are configured"
+        end
+        return if configured.include?(key_type.to_s)
+
+        raise ArgumentError, "the device flow needs a configured key type: set config.default_key_type, " \
+                             "or define device_key_type in the controller (got #{key_type.inspect})"
+      end
+
+      def digest(text)
+        Digest::SHA256.hexdigest(text)
+      end
+
+      # Deletes the requests that expired more than a day ago.
+      # @return [Integer] How many were deleted.
+      def prune!
+        where(expires_at: ...1.day.ago).delete_all
+      end
+    end
+
+    # The poll names the client that asked (RFC 8628 §3.4). A public client
+    # ID is not a secret, but a poll from another client must not get the
+    # grant of this one.
+    def client?(id)
+      client_id == id.to_s.strip
+    end
+
+    # The scopes the key would authorize: the approved scopes within the
+    # type's permissions, or, for a `scopes: :ceiling` type, the type's whole
+    # live ceiling, whatever the key stores.
+    def granted_scopes
+      type_config = self.class.key_type_config(key_type)
+      return Array(scopes) unless type_config
+      return type_config[:permissions].map(&:to_s) if ApiKeys::ApiKey.scopes_follow_ceiling_for?(type_config)
+
+      permissions = type_config[:permissions]
+      permissions.is_a?(Array) ? Array(scopes) & permissions.map(&:to_s) : Array(scopes)
+    end
+
+    # Whether the key would authorize more than the person approved: a
+    # `scopes: :ceiling` type whose ceiling holds a scope that was not asked.
+    def grant_exceeds_approval?
+      (granted_scopes - Array(scopes)).any?
+    end
+
+    # "Fictional agent on build-box": the name the key gets. Characters a
+    # key name cannot hold become hyphens, so every request can become a key.
+    def key_name
+      name = [client_id, device_name.presence].compact.join(" on ")
+      name.gsub(/[^a-zA-Z0-9_ -]/, "-").squeeze("-").first(ApiKeys::ApiKey::MAX_NAME_LENGTH).strip
+    end
+
+    # The person approves for +owner+, a record with `has_api_keys`. The key
+    # is created at the next poll (`poll!`), so its token is never stored.
+    #
+    # @raise [Closed] if the request was decided already or expired
+    # @raise [KeyLimitReached] if the owner may not have another key; the
+    #   request stays pending
+    def approve!(owner, by:)
+      unless owner.respond_to?(:create_api_key!) && owner.persisted?
+        raise ArgumentError, "approve a device authorization for a saved record that has_api_keys"
+      end
+
+      decide!("approved", by: by, owner: owner) do
+        raise KeyLimitReached unless owner.can_create_api_key?(key_type: key_type.presence)
+      end
+    end
+
+    # @raise [Closed] if the request was decided already or expired
+    def deny!(by:)
+      decide!("denied", by: by)
+    end
+
+    # One poll of the client (§3.4, §3.5), under the row's lock. A poll from
+    # another client changes nothing. A poll that comes sooner than the
+    # interval slows the client down by five seconds. A poll never raises
+    # for a key that cannot be made. An owner at its key limit is the one
+    # case that may pass: the client waits, as for a pending request. Every
+    # other failure closes the request.
+    #
+    # @return [Poll] the new key once, or the error code
+    def poll!(client_id:)
+      return Poll.new(error: "invalid_grant") unless client?(client_id)
+
+      with_row_lock do
+        next Poll.new(error: "expired_token") if expires_at.past?
+        # An owner deleted since the approval gets no key.
+        next Poll.new(error: "access_denied") if denied? || (approved? && owner.nil?)
+        next Poll.new(error: "invalid_grant") if completed? # the device code was used
+        next Poll.new(error: VOID_ERROR) if void?
+
+        if approved?
+          key, closed = complete!
+          next Poll.new(api_key: key) if key
+          next Poll.new(error: VOID_ERROR) if closed
+        end
+
+        too_soon = last_polled_at && last_polled_at > interval.seconds.ago
+        update_columns(last_polled_at: Time.current, interval: too_soon ? interval + SLOW_DOWN : interval)
+        Poll.new(error: too_soon ? "slow_down" : "authorization_pending")
+      end
+    end
+
+    private
+
+    # A decided or expired request cannot be decided again. The row lock
+    # makes two decisions, or a decision and a poll, take turns.
+    def decide!(state, by:, owner: nil)
+      with_row_lock do
+        raise Closed, "this device authorization is no longer open" unless pending? && expires_at.future?
+
+        yield if block_given?
+        update!(state: state, owner: owner, decided_by: by, decided_at: Time.current)
+      end
+    end
+
+    # Reloads the row under its lock for the rest of a transaction. SELECT
+    # ... FOR UPDATE locks the row on PostgreSQL and MySQL. SQLite has no
+    # row locks, so there an UPDATE first takes the database's write lock,
+    # which Rails before 8.0 does not take at BEGIN.
+    def with_row_lock
+      transaction do
+        self.class.where(id: id).update_all(updated_at: Time.current) if self.class.connection.adapter_name.match?(/sqlite/i)
+        lock!
+        yield
+      end
+    end
+
+    # Whether the configuration changed since the request, so that no key
+    # can be made as the person approved it: key types turned on for an
+    # untyped request, the request's type removed or renamed, or a ceiling
+    # that would authorize more than the approved scopes. The type stored at
+    # the request is the type of the key; it is never resolved again.
+    def configuration_incompatible?
+      configured = ApiKeys.configuration.key_types.keys.map(&:to_s)
+      return configured.any? if key_type.blank?
+
+      !configured.include?(key_type) || grant_exceeds_approval?
+    end
+
+    # Makes the key: [key, false]. An owner at its key limit gives
+    # [nil, false], and the request stays approved for a later poll. Any
+    # other failure closes the request: [nil, true]. The person who approved
+    # stands behind the key (created_by), when the api_keys table has the
+    # created_by columns.
+    def complete!
+      return [nil, void!] if configuration_incompatible?
+      return [nil, false] unless room_for_key?
+
+      person = { created_by: decided_by } if decided_by && ApiKeys::ApiKey.created_by_columns?
+      key = transaction(requires_new: true) do
+        owner.create_api_key!(name: key_name, scopes: scopes, key_type: key_type.presence, **person.to_h).tap do |made|
+          update_columns(state: "completed", api_key_id: made.id, updated_at: Time.current)
+        end
+      end
+      [key, false]
+    rescue *KEY_CREATION_ERRORS => error
+      ActiveRecord::Base.logger&.warn("[ApiKeys] Device authorization #{id} could not create its key (#{error.class}).")
+      reload
+      # A key made by another request in the meantime can fill the last
+      # place: that is the key limit again, and it passes.
+      error.is_a?(ActiveRecord::RecordInvalid) && !room_for_key? ? [nil, false] : [nil, void!]
+    end
+
+    def room_for_key?
+      owner.can_create_api_key?(key_type: key_type.presence)
+    end
+
+    def void!
+      update_columns(state: "void", updated_at: Time.current)
+      true
+    end
+
+    def key_type_is_configured
+      configured = ApiKeys.configuration.key_types.keys.map(&:to_s)
+      valid = configured.empty? ? key_type.blank? : configured.include?(key_type.to_s)
+      errors.add(:key_type, :inclusion) unless valid
+    end
+
+    # The person approves exactly what the key may do: every scope is one a
+    # key of the type grants, and the type grants nothing more.
+    def scopes_are_grantable
+      grantable = self.class.grantable_scopes(key_type)
+      unless scopes.is_a?(Array) && scopes.any? && scopes.all? { |scope| grantable.include?(scope) }
+        return errors.add(:scopes, :inclusion)
+      end
+
+      errors.add(:scopes, "must hold every permission of a #{key_type} key, which follows its ceiling") if grant_exceeds_approval?
+    end
+  end
+end

data/lib/api_keys/models/idempotency_key.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "digest"
+require "json"
+
+module ApiKeys
+  # One write under one API key's Idempotency-Key header
+  # (draft-ietf-httpapi-idempotency-key-header; ApiKeys::Idempotency).
+  #
+  # The key's row is claimed first, in a commit of its own. The write then
+  # runs in one transaction with the row locked, and the write, the rows it
+  # adds (an audit entry) and the key's answer (the status and the record the
+  # write made or changed) commit together, or nothing does. So an answered
+  # key means the write happened, and a key without an answer means it did
+  # not:
+  #
+  #   answered, the same request     the retry gets the record as it is now
+  #                                  and changes nothing
+  #   answered, another request      refused
+  #   no answer, locked              another request runs it now: Busy
+  #   no answer, free                a refused write or a crash: it runs
+  #
+  # No answer keeps a body, so a secret that was shown once is never stored.
+  # Each API key has its own keys, kept for a day.
+  class IdempotencyKey < ActiveRecord::Base
+    self.table_name = "api_keys_idempotency_keys"
+
+    HEADER = "Idempotency-Key"
+    MAX_LENGTH = 255
+    RETENTION = 24.hours
+    LOCK_TIMEOUT = 2 # seconds a retry waits for the request that holds the key
+
+    # Raised while another request holds the key.
+    class Busy < ApiKeys::Error; end
+
+    belongs_to :api_key, class_name: "ApiKeys::ApiKey"
+    belongs_to :resource, polymorphic: true, optional: true
+
+    validates :key, presence: true, length: { maximum: MAX_LENGTH }
+
+    scope :expired, -> { where(created_at: ...RETENTION.ago) }
+
+    class << self
+      # Deletes the keys older than a day.
+      # @return [Integer] How many were deleted.
+      def prune!
+        expired.delete_all
+      end
+
+      # The digest of a request: its parts (the method and the path, or the
+      # name of a tool) and its parameters, with the names in order, so the
+      # same request has the same digest.
+      def digest_of(*parts, parameters)
+        Digest::SHA256.hexdigest([*parts, canonical(parameters).to_json].join("\n"))
+      end
+
+      # Every value becomes a pair of a tag and its content, so values of
+      # different kinds never encode alike: an upload is never equal to a
+      # text that holds its digest, or to a hash that looks like one. An
+      # upload counts by its bytes, its file name and its content type. A
+      # hash that names a key twice, as a symbol and as a text, is refused:
+      # its order would decide the digest.
+      def canonical(value)
+        if value.is_a?(Hash)
+          pairs = value.map { |name, inner| [name.to_s, canonical(inner)] }
+          duplicates = pairs.map(&:first).tally.select { |_name, count| count > 1 }.keys
+          raise ArgumentError, "the parameters name #{duplicates.join(', ')} twice" if duplicates.any?
+
+          ["object", pairs.sort_by(&:first)]
+        elsif value.is_a?(Array)
+          ["array", value.map { |inner| canonical(inner) }]
+        elsif upload?(value)
+          ["upload", Digest::SHA256.file(value.tempfile.path).hexdigest, value.original_filename.to_s, value.content_type.to_s]
+        else
+          ["value", value]
+        end
+      end
+
+      # Yields the API key's row of +key+, locked, inside the transaction that
+      # the caller's write joins. Raises Busy while another request holds it.
+      #
+      # It runs outside every open transaction, so that the claim commits on
+      # its own: inside one, the claim and the answer are a savepoint, and
+      # the outer rollback removes both. Only transactional tests may run it
+      # inside a transaction, with `config.idempotency_in_test_transactions`.
+      def hold(api_key, key)
+        if connection.transaction_open? && !ApiKeys.configuration.idempotency_in_test_transactions?
+          raise ApiKeys::Error, "ApiKeys::IdempotencyKey.hold runs outside database transactions, so that the key's " \
+                                "claim commits on its own: run run_once_per_idempotency_key outside any transaction. " \
+                                "Transactional tests set config.idempotency_in_test_transactions = true."
+        end
+
+        claim(api_key, key)
+        transaction(requires_new: true) { yield locked(api_key, key) }
+      end
+
+      # The row, locked for the rest of the transaction. The wait is at most
+      # LOCK_TIMEOUT seconds on PostgreSQL and MySQL. SQLite has no row
+      # locks: there an UPDATE takes the database's write lock first, and the
+      # wait is the database's busy timeout.
+      def locked(api_key, key)
+        rows = where(api_key_id: api_key.id, key: key)
+        busy_on_lock_wait do
+          waiting_at_most_lock_timeout do
+            rows.update_all(updated_at: Time.current) if connection.adapter_name.match?(/sqlite/i)
+            rows.lock.take || raise(Busy) # deleted since it was claimed: the client retries
+          end
+        end
+      end
+
+      private
+
+      # Claims the key's row in a transaction of its own. A key that exists
+      # is read without a lock, so a retry never waits here for the request
+      # that holds it: it waits in `locked`. A new key is inserted, and two
+      # first requests with the same key wait for each other's insert at
+      # most LOCK_TIMEOUT. A day-old key is deleted and claimed afresh. The
+      # read comes before the transaction, so on MySQL the insert's fallback
+      # read sees the row that the other request committed.
+      def claim(api_key, key)
+        rows = where(api_key_id: api_key.id, key: key)
+        existing = busy_on_lock_wait { rows.take }
+        return existing if existing && existing.created_at > RETENTION.ago
+
+        busy_on_lock_wait do
+          transaction(requires_new: true) do
+            waiting_at_most_lock_timeout do
+              rows.expired.delete_all if existing
+              # The row keeps the API key's id, never its token.
+              create_or_find_by!(api_key_id: api_key.id, key: key)
+            end
+          end
+        end
+      end
+
+      # ActionDispatch::Http::UploadedFile, and the files of Rack::Test.
+      def upload?(value)
+        %i[tempfile original_filename content_type].all? { |name| value.respond_to?(name) }
+      end
+
+      def busy_on_lock_wait
+        yield
+      rescue ActiveRecord::LockWaitTimeout, ActiveRecord::StatementTimeout
+        raise Busy
+      rescue ActiveRecord::StatementInvalid => error
+        # Rails before 8.0 does not name SQLite's "database is locked".
+        raise Busy if defined?(::SQLite3::BusyException) && error.cause.is_a?(::SQLite3::BusyException)
+
+        raise
+      end
+
+      # The statements hold no input: LOCK_TIMEOUT is 2 seconds in each.
+      def waiting_at_most_lock_timeout
+        case connection.adapter_name
+        when /postg/i
+          # SET LOCAL ends with the transaction, or with a lock wait that
+          # fails it. After the lock, the write waits as it always does.
+          connection.execute("SET LOCAL lock_timeout = '2s'")
+          yield.tap { connection.execute("SET LOCAL lock_timeout TO DEFAULT") }
+        when /mysql|trilogy/i
+          connection.execute("SET @api_keys_lock_wait = @@SESSION.innodb_lock_wait_timeout, SESSION innodb_lock_wait_timeout = 2")
+          begin
+            yield
+          ensure
+            connection.execute("SET SESSION innodb_lock_wait_timeout = @api_keys_lock_wait")
+          end
+        else
+          yield
+        end
+      end
+    end
+
+    def answered?
+      !response_status.nil?
+    end
+
+    def answer!(status, resource)
+      raise ArgumentError, "a write under an Idempotency-Key answers with the record it made or changed" unless resource
+
+      update!(response_status: status, resource: resource)
+    end
+  end
+end

data/lib/api_keys/version.rb

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

data/lib/api_keys.rb

@@ -67,6 +67,12 @@ require "api_keys/restrictions" # Origin/IP request restrictions value object
 require "api_keys/controller" # This can lead to loading jobs, etc.
 require "api_keys/models/concerns/has_api_keys"
 require "api_keys/models/api_key"
+require "api_keys/models/device_authorization"
+require "api_keys/models/idempotency_key"
+
+# Controller concerns a host includes in its own API controllers
+require "api_keys/device_flow"
+require "api_keys/idempotency"
 
 # Helpers for integrators building custom UIs
 require "api_keys/helpers/token_session"

data/lib/generators/api_keys/add_created_by_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module ApiKeys
+  module Generators
+    # Rails generator for the column api_keys 0.7.0 adds to the api_keys
+    # table: `created_by`, the person behind a key.
+    #
+    # This generator is for existing installations; new installs get the
+    # columns from the install generator, so they never need to run this.
+    class AddCreatedByGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # Implement the required interface for Rails::Generators::Migration.
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      # Creates the migration file using the template.
+      def create_migration_file
+        migration_template "add_created_by_to_api_keys.rb.erb",
+                           File.join(db_migrate_path, "add_created_by_to_api_keys.rb")
+      end
+
+      # Displays helpful information to the user after installation.
+      def display_post_install_message
+        say "\n🧑 api_keys created_by migration created!", :green
+        say "\nNext steps:"
+        say "  1. Run `rails db:migrate` to add created_by_type and created_by_id to api_keys."
+        say "\n  2. Name the person when you create a key:"
+        say "       current_organization.create_api_key!(name: \"CI\", created_by: current_user)"
+        say "\n  3. Optional: refuse a key once its person no longer stands behind it:"
+        say "       config.trusted_key_check = ->(api_key) { api_key.owner.managed_by?(api_key.created_by) }"
+        say "     Keys made before the migration have no created_by: decide what the check does with them."
+        say "\nSee the api_keys README for detailed usage and examples.", :cyan
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/api_keys/add_device_authorizations_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module ApiKeys
+  module Generators
+    # Rails generator for the device authorizations table (api_keys 0.7.0),
+    # which ApiKeys::DeviceFlow needs: a client asks for an API key with the
+    # OAuth 2.0 Device Authorization Grant (RFC 8628), and a person approves
+    # or denies it in the app. New and existing installations run it alike.
+    class AddDeviceAuthorizationsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # Implement the required interface for Rails::Generators::Migration.
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      # Creates the migration file using the template.
+      def create_migration_file
+        migration_template "create_api_keys_device_authorizations.rb.erb",
+                           File.join(db_migrate_path, "create_api_keys_device_authorizations.rb")
+      end
+
+      # Displays helpful information to the user after installation.
+      def display_post_install_message
+        say "\n📟 api_keys device authorizations migration created!", :green
+        say "\nNext steps:"
+        say "  1. Run `rails db:migrate` to create the api_keys_device_authorizations table."
+        say "\n  2. Include ApiKeys::DeviceFlow in an API controller, define"
+        say "     device_verification_uri(user_code = nil), and route its create and token actions."
+        say "\n  3. Build the page where a person approves: find the request with"
+        say "     ApiKeys::DeviceAuthorization.find_undecided_by_user_code(code), then call"
+        say "     approve!(owner, by: current_user) or deny!(by: current_user)."
+        say "\n  4. Rate-limit the look-ups and the approvals on that page together (RFC 8628 §5.1), and run"
+        say "     ApiKeys::DeviceAuthorization.prune! once a day."
+        say "\nSee the api_keys README for detailed usage and examples.", :cyan
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end