api_keys 0.6.0 → 0.7.0

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/helpers/view_helpers.rb

@@ -31,7 +31,8 @@ module ApiKeys
         "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"
+        "missing_scope" => "the key lacks a permission the endpoint requires",
+        "untrusted_key" => "the person behind the key no longer stands behind it"
       }.freeze
       UNKNOWN_REFUSAL_REASON = "the request was refused for an unrecognized reason"
 

data/lib/api_keys/idempotency.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require_relative "authentication"
+
+module ApiKeys
+  # Writes that run once per Idempotency-Key, for an API controller that
+  # authenticates with `authenticate_api_key!`
+  # (draft-ietf-httpapi-idempotency-key-header, ApiKeys::IdempotencyKey):
+  #
+  #   class Api::BaseController < ActionController::API
+  #     include ApiKeys::Controller
+  #     include ApiKeys::Idempotency
+  #
+  #     before_action :authenticate_api_key!
+  #     around_action :run_once_per_idempotency_key
+  #
+  #     private
+  #
+  #     # The JSON for a record: the first answer and every retry use it.
+  #     def resource_json(record, **options)
+  #       record.as_json(only: %i[id name])
+  #     end
+  #
+  #     # Whether this API key may read the record now. A retry answers only
+  #     # records it may read: a record moved to another owner is not found.
+  #     def idempotent_replay_allowed?(record)
+  #       record.owner == current_api_owner
+  #     end
+  #   end
+  #
+  #   class Api::ProjectsController < Api::BaseController
+  #     def create
+  #       render_resource current_api_owner.projects.create!(project_params), status: :created
+  #     end
+  #   end
+  #
+  # The around_action runs outside any transaction the app opens: the key's
+  # claim must commit on its own (ApiKeys::IdempotencyKey.hold refuses).
+  #
+  # Every request but GET and HEAD needs the header. A write answers with
+  # `render_resource`, so the key keeps the record it made or changed, and a
+  # retry with the same key and the same request answers that record as it
+  # is now, with `Idempotent-Replayed: true`. Refusals render through
+  # `render_unauthorized`, like the gem's other refusals:
+  #
+  #   400 idempotency_key_required   no header, or longer than 255 characters
+  #   409 idempotency_key_in_use     a request with this key still runs
+  #   422 idempotency_key_reused     the key was used for another request
+  module Idempotency
+    extend ActiveSupport::Concern
+    include ApiKeys::Authentication
+
+    REPLAYED_HEADER = "Idempotent-Replayed"
+    # The methods a host defines: the gem cannot know how to render a record,
+    # or who may read it.
+    HOST_METHODS = %i[resource_json idempotent_replay_allowed?].freeze
+
+    private
+
+    # The around_action. A write and its answer commit together; a refused
+    # write (any status but 2xx) or an error commits nothing and leaves the
+    # key free for the next attempt.
+    def run_once_per_idempotency_key
+      return yield if reading_request?
+      raise ApiKeys::Error, "run authenticate_api_key! before run_once_per_idempotency_key" unless current_api_key
+
+      require_idempotency_host_methods!
+
+      key = request.headers[ApiKeys::IdempotencyKey::HEADER].to_s
+      if key.blank? || key.length > ApiKeys::IdempotencyKey::MAX_LENGTH
+        return render_unauthorized(
+          error_code: :idempotency_key_required, status: :bad_request,
+          message: "Send an Idempotency-Key header with every write: a unique text of " \
+                   "1 to #{ApiKeys::IdempotencyKey::MAX_LENGTH} characters, the same when you retry."
+        )
+      end
+
+      ApiKeys::IdempotencyKey.hold(current_api_key, key) do |record|
+        next replay_idempotent_request(record) if record.answered?
+
+        record.update!(request_digest: idempotency_request_digest)
+        yield
+        response.successful? ? record.answer!(response.status, @api_keys_idempotent_resource) : raise(ActiveRecord::Rollback)
+      end
+    rescue ApiKeys::IdempotencyKey::Busy
+      render_unauthorized(error_code: :idempotency_key_in_use, status: :conflict,
+                          message: "A request with this Idempotency-Key is still running. Retry in a moment.")
+    end
+
+    # A write's answer: the record it made or changed, as `resource_json`
+    # renders it. The key keeps the record, so a retry answers the same way.
+    # Options go to `resource_json` for this answer only: a secret shown
+    # once is never in a retry's answer.
+    def render_resource(record, status: :ok, **options)
+      @api_keys_idempotent_resource = record
+      render json: resource_json(record, **options), status: status
+    end
+
+    # The JSON for a record. Define it in the host controller.
+    def resource_json(_record, **_options)
+      raise NotImplementedError,
+            "#{self.class.name} must define resource_json(record, **options) for ApiKeys::Idempotency"
+    end
+
+    # Whether current_api_key may read +record+ now. Define it in the host
+    # controller. A retry runs no action, so this is the only check before a
+    # record's current state goes back to the client.
+    def idempotent_replay_allowed?(_record)
+      raise NotImplementedError,
+            "#{self.class.name} must define idempotent_replay_allowed?(record) for ApiKeys::Idempotency: " \
+            "whether current_api_key may read the record that a retry answers with"
+    end
+
+    # Both host methods are checked on the first write, not on the first
+    # retry, so a missing one shows in development and tests.
+    def require_idempotency_host_methods!
+      missing = HOST_METHODS.select { |name| method(name).owner == ApiKeys::Idempotency }
+      return if missing.empty?
+
+      raise NotImplementedError, "#{self.class.name} must define #{missing.join(' and ')} for ApiKeys::Idempotency: " \
+                                 "resource_json(record, **options) renders a record, and " \
+                                 "idempotent_replay_allowed?(record) answers whether current_api_key may read it"
+    end
+
+    # The answer to a retry: the record as it is now, never a stored body,
+    # so it is current and holds no secret. A record that no longer exists,
+    # or that this API key may no longer read, is not found
+    # (ActiveRecord::RecordNotFound, which Rails answers 404).
+    def replay_idempotent_request(record)
+      if record.request_digest != idempotency_request_digest
+        return render_unauthorized(error_code: :idempotency_key_reused, status: 422,
+                                   message: "This Idempotency-Key was used for another request. Use a new key.")
+      end
+
+      resource = record.resource
+      unless resource && idempotent_replay_allowed?(resource)
+        raise ActiveRecord::RecordNotFound, "the record of this Idempotency-Key is not found for this API key"
+      end
+
+      response.headers[REPLAYED_HEADER] = "true"
+      render json: resource_json(resource), status: record.response_status
+    end
+
+    # The request a key stands for: the method, the path, the query, and
+    # the body. The query and the body count apart, so a name that moves
+    # from one to the other makes another request.
+    def idempotency_request_digest
+      @api_keys_idempotency_request_digest ||= ApiKeys::IdempotencyKey.digest_of(
+        request.request_method, request.path,
+        { "query" => request.query_parameters, "body" => request.request_parameters }
+      )
+    end
+  end
+end

data/lib/api_keys/models/api_key.rb

@@ -10,6 +10,9 @@ module ApiKeys
   # The core ActiveRecord model representing an API key.
   class ApiKey < ActiveRecord::Base
     MAX_SCOPES = 100
+    # A key name: letters, numbers, underscores, hyphens and spaces.
+    MAX_NAME_LENGTH = 60
+    NAME_FORMAT = /\A[a-zA-Z0-9_ -]+\z/
     MAX_SCOPE_BYTESIZE = 128
     MAX_METADATA_BYTESIZE = 16_384
     MAX_RESTRICTION_ENTRIES = 100
@@ -29,11 +32,17 @@ module ApiKeys
       revoked_key expired_key unknown_key_type unknown_environment
       environment_misconfigured environment_mismatch
       origin_not_allowed ip_not_allowed restriction_misconfigured missing_scope
+      untrusted_key
     ].freeze
+    # The person who created the key (0.7.0). Optional columns.
+    CREATED_BY_COLUMNS = %w[created_by_type created_by_id].freeze
     # Deliberately excludes `restrictions`: owners must be able to tighten a
-    # request policy even when the key itself is non-revocable.
+    # request policy even when the key itself is non-revocable. Includes the
+    # person who created the key: `config.trusted_key_check` may trust a key
+    # because of that person, so no update can name another one.
     IMMUTABLE_IDENTITY_ATTRIBUTES = %w[
       token_digest digest_algorithm prefix last4 owner_type owner_id key_type environment
+      created_by_type created_by_id
     ].freeze
 
     self.table_name = "api_keys"
@@ -43,6 +52,10 @@ module ApiKeys
 
     # == Associations ==
     belongs_to :owner, polymorphic: true, optional: true
+    # The person behind the key, when the host names one at creation:
+    # `create_api_key!(created_by: current_user)`. Needs the created_by
+    # columns (`rails generate api_keys:add_created_by`).
+    belongs_to :created_by, polymorphic: true, optional: true
 
     # == Attributes & Serialization ==
     # Expose the plaintext token only immediately after creation
@@ -52,6 +65,11 @@ module ApiKeys
     # saves can never set or clear it, so no update path (a form, mass
     # assignment, a stray `update`) can reopen a handoff that was claimed.
     attr_readonly :token_shown_at
+    # The person behind the key is fixed at creation. `config.trusted_key_check`
+    # may trust a key because of that person, so no save (with or without
+    # validations) and no update_column can name another one. A backfill of
+    # keys made before the columns existed writes them with SQL (update_all).
+    attr_readonly :created_by_type, :created_by_id
     attr_accessor :expires_at_preset
 
     # JSON attributes (:scopes, :metadata) are defined in the engine initializer
@@ -138,9 +156,9 @@ module ApiKeys
     # validates :scopes, presence: true # Default handled by attribute def
     # validates :metadata, presence: true # Default handled by attribute def
     validates :name,
-              length: { maximum: 60 },
+              length: { maximum: MAX_NAME_LENGTH },
               # Allow letters, numbers, underscores, hyphens, and spaces. No leading/trailing spaces.
-              format: { with: /\A[a-zA-Z0-9_ -]+\z/, message: "can only contain letters, numbers, underscores, hyphens, and spaces (no leading / trailing spaces)" },
+              format: { with: NAME_FORMAT, message: "can only contain letters, numbers, underscores, hyphens, and spaces (no leading / trailing spaces)" },
               allow_blank: true # Apply length and format only if name is present
 
     validates :name, presence: true, if: :name_required? # Only require presence conditionally
@@ -564,6 +582,15 @@ module ApiKeys
       false
     end
 
+    # Whether the `created_by` columns exist. Installations that predate
+    # v0.7.0 keep working untouched until they run the generator.
+    # @return [Boolean]
+    def self.created_by_columns?
+      (CREATED_BY_COLUMNS - column_names).empty?
+    rescue StandardError
+      false
+    end
+
     # Whether the refused-traffic columns exist. Installations that predate
     # v0.6.0 keep authenticating untouched until they run the generator.
     # @return [Boolean]

data/lib/api_keys/models/concerns/has_api_keys.rb

@@ -225,13 +225,20 @@ module ApiKeys
         #   Accepts the raw string a form field submits ("example.com, *.example.com").
         # @param allowed_ips [String, Array, nil] Convenience form of the IP list
         #   ("203.0.113.7, 10.0.0.0/8").
+        # @param created_by [ActiveRecord::Base, nil] The person behind the key, for
+        #   `config.trusted_key_check`. Needs the created_by columns.
         # @return [ApiKeys::ApiKey] The newly created ApiKey instance. The plaintext token
         #                           is available via the `#token` attribute on this instance
         #                           *only until it's reloaded*.
         def create_api_key!(name: nil, scopes: nil, expires_at: nil, expires_at_preset: nil, metadata: nil,
-                            key_type: nil, environment: nil, restrictions: nil, allowed_origins: nil, allowed_ips: nil)
+                            key_type: nil, environment: nil, restrictions: nil, allowed_origins: nil, allowed_ips: nil,
+                            created_by: nil)
           config = ApiKeys.configuration
 
+          if created_by && !ApiKeys::ApiKey.created_by_columns?
+            raise ApiKeys::Errors::CreatedByMigrationRequiredError
+          end
+
           # Parse expires_at_preset if provided (takes precedence over expires_at)
           if expires_at_preset.present?
             expires_at = ApiKeys::Helpers::ExpirationOptions.parse(expires_at_preset)
@@ -302,6 +309,7 @@ module ApiKeys
             # prefix, token_digest, digest_algorithm are set by ApiKey callbacks
           }
           attributes[:restrictions] = requested_restrictions if requested_restrictions
+          attributes[:created_by] = created_by if created_by
 
           api_key = self.class.transaction do
             self.api_keys.create!(**attributes)