permission_forge 0.14.1 → 0.15.0

data/lib/permission_forge/unique_conflict.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # The validation error a uniqueness race would have shown.
+  #
+  # Four models validate uniqueness with a unique index behind the validation
+  # (a Resource or a field name per set or resource, one assignment or
+  # membership per person): two requests that pass the validation together
+  # leave the second INSERT to the index, which raises
+  # ActiveRecord::RecordNotUnique. The admin and the API answer it the way
+  # they answer the validation — a 422 keyed by the attribute, the form's
+  # page with the message — from the index the error names. The adapters
+  # word the error differently (SQLite names the columns, PostgreSQL and
+  # MySQL the index), so the index name and every `table.column` of the
+  # index are looked for, and nothing else of the message is parsed.
+  #
+  # @api private
+  module UniqueConflict
+    # A uniqueness validation (its attribute and validator) of a model.
+    Conflict = Data.define(:model, :attribute, :validator) do
+      # The validation's own errors, as `record.errors` would hold them:
+      # `:taken` with the validator's `message:` option, as the validator
+      # adds it.
+      #
+      # @return [ActiveModel::Errors]
+      def errors
+        list = model.new.errors
+        list.add(attribute, :taken, **validator.options.slice(:message))
+        list
+      end
+    end
+
+    class << self
+      # `{ user_id: ["has already been taken"] }`: the validation's message
+      # for the unique index `error` names, keyed by the attribute like
+      # `record.errors.messages`; nil when the index belongs to no
+      # uniqueness validation of the models (a uuid index, a host's own
+      # index, a message naming nothing).
+      #
+      # @param error [ActiveRecord::RecordNotUnique]
+      # @return [Hash{Symbol => Array<String>}, nil]
+      def messages(error)
+        find(error)&.errors&.messages
+      end
+
+      # The same as one sentence in the current locale ("Name already exists
+      # in this permission set", Admin::ErrorSentence); nil as for .messages.
+      #
+      # @param error [ActiveRecord::RecordNotUnique]
+      # @return [String, nil]
+      def sentence(error)
+        conflict = find(error)
+        conflict && Admin::ErrorSentence.first(conflict.errors)
+      end
+
+      # The uniqueness validation behind the unique index `error` names.
+      #
+      # @param error [ActiveRecord::RecordNotUnique]
+      # @return [Conflict, nil]
+      def find(error)
+        text = error.message.to_s
+        models.each do |model|
+          index = unique_indexes(model).find { |candidate| names?(text, candidate, model.table_name) }
+          return conflict_for(model, index) if index
+        end
+        nil
+      end
+
+      # The uniqueness validator of `model` whose attribute and scope are
+      # exactly the columns of `index`, with that attribute.
+      #
+      # @param model [Class] one of the models
+      # @param index [ActiveRecord::ConnectionAdapters::IndexDefinition]
+      # @return [Conflict, nil]
+      def conflict_for(model, index)
+        columns = Array(index.columns).map(&:to_s).sort
+        model.validators.each do |validator|
+          attribute = validated_attribute(validator, columns)
+          return Conflict.new(model: model, attribute: attribute, validator: validator) if attribute
+        end
+        nil
+      end
+
+      private
+
+      # The attribute of a uniqueness validator that, with the validator's
+      # scope, is exactly `columns` (sorted); nil for any other validator.
+      def validated_attribute(validator, columns)
+        return unless validator.kind == :uniqueness
+
+        scope = Array(validator.options[:scope]).map(&:to_s)
+        validator.attributes.find { |name| ([name.to_s] + scope).sort == columns }
+      end
+
+      def models
+        PermissionForge::MODEL_NAMES.map { |name| PermissionForge.const_get(name) }
+      end
+
+      # The unique indexes of the model's table; none when the table cannot
+      # be read (no table yet, no database): nothing is named then.
+      def unique_indexes(model)
+        model.connection_pool.with_connection { |connection| connection.indexes(model.table_name) }.select(&:unique)
+      rescue ActiveRecord::ActiveRecordError
+        []
+      end
+
+      # Whether the adapter's message names the index: by its name
+      # (PostgreSQL, MySQL) or by each of its columns as table.column (SQLite).
+      def names?(text, index, table)
+        return true if index.name.present? && text.match?(/\b#{Regexp.escape(index.name.to_s)}\b/)
+
+        columns = Array(index.columns).map(&:to_s)
+        columns.any? && columns.all? { |column| text.include?("#{table}.#{column}") }
+      end
+    end
+  end
+end

data/lib/permission_forge/version.rb

@@ -1,3 +1,3 @@
 module PermissionForge
-  VERSION = '0.14.1'.freeze
+  VERSION = '0.15.0'.freeze
 end

data/lib/permission_forge/virtual_fields/discovery.rb

@@ -31,7 +31,8 @@ module PermissionForge
 
       # @return [Array<String>] discovered names, never a column
       def call
-        SOURCES.flat_map { |source| send(source) }.uniq - @klass.column_names
+        names = SOURCES.flat_map { |source| send(source) }.uniq
+        names - SchemaRead.columns_among(@klass, names)
       rescue StandardError
         []
       end

data/lib/permission_forge/virtual_fields.rb

@@ -47,9 +47,12 @@ module PermissionForge
       @extra = extra_unreadable(e)
     end
 
-    # Declared names that are neither a column nor an ignored field.
+    # Declared names that are neither a column nor an ignored field. Whether
+    # a declared name is a column is asked once more after the schema is
+    # read again (PermissionForge::SchemaRead): a migration may have turned
+    # it into one.
     def declared
-      @declared ||= extra - excluded
+      @declared ||= extra.reject { |name| ignored_fields.include?(name) || SchemaRead.column?(@klass, name, ignored: false) }
     end
 
     # Listed only while discovery is on; never implicitly granted.
@@ -74,10 +77,13 @@ module PermissionForge
     end
 
     # Whether the model has `name` as a virtual field, listed or not (a
-    # field configured while discovery was on stays a virtual field).
+    # field configured while discovery was on stays a virtual field). A name
+    # that is no column is asked again after the schema is read again, once
+    # (PermissionForge::SchemaRead): a field a migration just turned into a
+    # column is a column.
     def include?(name)
       name = name.to_s
-      @klass.column_names.exclude?(name) && (extra.include?(name) || discoverable.include?(name))
+      !SchemaRead.column?(@klass, name, ignored: false) && (extra.include?(name) || discoverable.include?(name))
     end
 
     private
@@ -87,7 +93,11 @@ module PermissionForge
     end
 
     def excluded
-      @klass.column_names + Array(@configuration.ignored_fields).map(&:to_s)
+      SchemaRead.column_names(@klass) + ignored_fields
+    end
+
+    def ignored_fields
+      Array(@configuration.ignored_fields).map(&:to_s)
     end
 
     # Keeps the error for callers that must say what it costs them (reader

data/lib/permission_forge/warnings.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require 'concurrent/map'
+
+module PermissionForge
+  # The one emitter of the gem's boot and configuration warnings (a per-process
+  # cache, a fail-open setting, a model that cannot be masked, ...). Every such
+  # warning is one `emit` call; this module decides the channel, so that a
+  # warning about a fail-open condition is read by somebody.
+  #
+  # The channel policy (`channels`):
+  # - the log (Rails.logger.warn) always;
+  # - the terminal (standard error) where the log is not read: in development
+  #   (`bin/rails server` boots before it attaches its console logger; a
+  #   console, `bin/rails runner`, a rake task and `db:seed` never attach one)
+  #   and, in every other environment but test, in any process that is not a
+  #   web server (a console, a runner, a rake task, a seed, a job worker) —
+  #   unless the logger already writes to standard output or error (a
+  #   container, RAILS_LOG_TO_STDOUT), which would print it twice;
+  # - nothing while `bin/rails generate` or `destroy` boots the app
+  #   (generator_running?): the install generator boots before it writes the
+  #   initializer, so its warnings describe a configuration the app is about
+  #   to stop having (R5 #120);
+  # - the terminal gets a key once per process (a human needs one line); the
+  #   log gets every emission the site makes — a site that may repeat (a
+  #   retried model, a store outage) decides itself when its condition is new.
+  #
+  # A SECURITY warning (severity :security) is a condition under which access
+  # is wider than configured, or a change goes unrecorded; it carries the
+  # prefix `SECURITY warning:`. Adding a severity is one SEVERITIES entry.
+  #
+  # A warning's audience (AUDIENCES) is the processes it is about. :all (the
+  # default): every process — the cache, the models, the rules, the audit
+  # table are used by a runner, a rake task, a job as much as by a server.
+  # :server: a warning about the admin screens or the JSON API, which only
+  # a web server process serves (HTTP Basic credentials, the actor of an
+  # admin change, the API's authorization lambdas, an API-only host's
+  # middlewares, tenantless admin access); outside a server process
+  # (server_process?) it goes to the log only. A runner does not serve the
+  # admin, and the credentials it would warn about are often set for the
+  # server alone (round 7, a-onboarding #23).
+  #
+  # Nothing here raises for a channel: a terminal that cannot be written is
+  # skipped, a missing logger is skipped. Never called at require time.
+  #
+  # @example
+  #   PermissionForge::Warnings.emit(:api_authorization_gap,
+  #                                  'API is enabled but ... (privilege escalation).', severity: :security)
+  #
+  # @api private
+  module Warnings
+    # The text each severity puts before the message.
+    SEVERITIES = { security: 'SECURITY warning: ', config: '' }.freeze
+
+    # Every warning starts with it.
+    PREFIX = '[PermissionForge] '
+
+    # The commands `bin/rails generate` and `bin/rails destroy` run: Rails
+    # loads the command's class before it boots the app (canary
+    # :generator_commands). Rails::Generators alone does not say it: a gem may
+    # require rails/generators as it loads.
+    GENERATOR_COMMANDS = %w[Rails::Command::GenerateCommand Rails::Command::DestroyCommand].freeze
+
+    # The processes a warning is about (see the module): every process, or
+    # a web server's only. Adding an audience is one entry here and a rule
+    # in .channels.
+    AUDIENCES = %i[all server].freeze
+
+    # What a web server's own command has loaded before it boots the app,
+    # never what `require "<gem>"` (Bundler.require in a runner) loads:
+    # `bin/rails server` (Rails::Server), `puma` (Puma::CLI), `unicorn` and
+    # `unicorn_rails` (Unicorn::Launcher), Passenger's Rack loaders
+    # (PhusionPassenger::App), `falcon serve` / `falcon host`
+    # (Falcon::Command). Another server (thin, a custom Rack launcher)
+    # counts as a process whose log is not read: its standard error gets
+    # the warning unless the logger already writes there, and a :server
+    # warning goes to its log only.
+    SERVER_COMMANDS = %w[Rails::Server Puma::CLI Unicorn::Launcher PhusionPassenger::App Falcon::Command].freeze
+
+    # Servers whose command defines no constant of its own, by program name
+    # (the basename of Process.argv0, the name the process was started
+    # with, or of $PROGRAM_NAME): `pitchfork` (bin/pitchfork requires what
+    # `require "pitchfork"` does, and pitchfork rewrites $0 into its process
+    # title: Process.argv0 keeps the name), `rackup` (`bundle exec rackup`
+    # boots Rack's handler, never Puma::CLI; `bundle exec` loads a Ruby
+    # binstub in its own process and sets $0 to it, so Process.argv0 reads
+    # `bundle` there). A server started some other way counts as a process
+    # whose log is not read (see SERVER_COMMANDS).
+    SERVER_PROGRAMS = %w[pitchfork rackup].freeze
+
+    # The channels, in writing order.
+    CHANNELS = %i[log terminal].freeze
+
+    # What the channel policy reads about the process a warning is written
+    # from: the environment (an ActiveSupport::EnvironmentInquirer), whether
+    # it is a web server, whether a generator is booting it, and its logger.
+    # Warnings.context builds the current one; tests build their own.
+    Context = Data.define(:env, :server, :generator, :logger)
+
+    # Writes warnings to a terminal under a Context. Warnings.emit uses one
+    # for this process; tests inject an io and a Context.
+    class Emitter
+      # @param io [IO] the terminal
+      # @param context [Context]
+      def initialize(io: $stderr, context: Warnings.context)
+        @io = io
+        @context = context
+      end
+
+      # @param key [Symbol, String] what the warning is about (the terminal
+      #   gets each key once per process); a per-subject warning puts the
+      #   subject in the key (`"masked_models.unmaskable.#{name}"`)
+      # @param message [String] the sentence(s), without the gem prefix: it
+      #   names the condition, its consequence and the remedy
+      # @param severity [Symbol] a SEVERITIES key: :security for a condition
+      #   under which access widens or a change goes unrecorded, else :config
+      # @param audience [Symbol] an AUDIENCES entry: :server for a warning
+      #   about the admin or the API a server process serves (the log only
+      #   in any other process), else :all
+      # @return [String] the text written
+      # @raise [ArgumentError] for a severity not in SEVERITIES, an audience
+      #   not in AUDIENCES
+      def emit(key, message, severity: :config, audience: :all)
+        text = "#{PREFIX}#{Warnings.severity_prefix(severity)}#{message}"
+        Warnings.channels(@context, audience: audience).each do |channel|
+          channel == :log ? @context.logger&.warn(text) : terminal(key, text)
+        end
+        text
+      end
+
+      private
+
+      # Once per process and key. A terminal that is closed or gone (a
+      # broken pipe) is skipped: the log has the warning.
+      def terminal(key, text)
+        return unless Warnings.first_on_terminal?(key)
+
+        @io.puts(text)
+      rescue IOError, SystemCallError
+        nil
+      end
+    end
+
+    class << self
+      # Writes one warning where the policy says (an Emitter for this process).
+      #
+      # @param (see Emitter#emit)
+      # @return [String] the text written
+      def emit(key, message, severity: :config, audience: :all)
+        Emitter.new.emit(key, message, severity: severity, audience: audience)
+      end
+
+      # The channels a warning goes to under `context`: [] while a generator
+      # runs, [:log] where the log is read — and for a :server warning in a
+      # process that is not a server —, [:log, :terminal] elsewhere (see the
+      # module).
+      #
+      # @param context [Context]
+      # @param audience [Symbol] an AUDIENCES entry
+      # @return [Array<Symbol>]
+      # @raise [ArgumentError] for an audience not in AUDIENCES
+      def channels(context = context(), audience: :all)
+        check_audience!(audience)
+        return [] if context.generator
+        return CHANNELS.first(1) if audience == :server && !context.server
+
+        terminal?(context) ? CHANNELS : CHANNELS.first(1)
+      end
+
+      # This process, with `overrides` for a test.
+      #
+      # @param overrides [Hash] env:, server:, generator:, logger:
+      # @return [Context]
+      def context(**overrides)
+        current = { env: Rails.env, server: server_process?, generator: generator_running?, logger: current_logger }
+        Context.new(**current, **overrides)
+      end
+
+      # Forgets which keys the terminal got (tests; a process has one boot).
+      #
+      # @return [void]
+      def reset!
+        written.clear
+      end
+
+      # Whether `bin/rails generate` or `bin/rails destroy` is booting the
+      # app: their command class is loaded; a server, a console, a runner or
+      # a rake task loads its own.
+      #
+      # @return [Boolean]
+      def generator_running?
+        GENERATOR_COMMANDS.any? { |name| Object.const_defined?(name, false) }
+      end
+
+      # Whether this process is a web server (SERVER_COMMANDS,
+      # SERVER_PROGRAMS): its log is where its warnings are read, outside
+      # development, and the :server warnings are about it.
+      #
+      # @param started_as [String] the name the process was started with (Process.argv0)
+      # @param program_name [String] $PROGRAM_NAME as it is now
+      # @return [Boolean]
+      def server_process?(started_as: Process.argv0, program_name: $PROGRAM_NAME)
+        SERVER_COMMANDS.any? { |name| Object.const_defined?(name, false) } ||
+          [started_as, program_name].any? { |program| SERVER_PROGRAMS.include?(File.basename(program.to_s)) }
+      end
+
+      # Whether `logger` already writes to standard output or error (a
+      # container setup, RAILS_LOG_TO_STDOUT, a logger the app configured):
+      # the terminal then has the warning once the log is written.
+      #
+      # @param logger [Logger, nil]
+      # @return [Boolean]
+      def logger_on_terminal?(logger = current_logger)
+        !logger.nil? && ActiveSupport::Logger.logger_outputs_to?(logger, $stdout, $stderr)
+      end
+
+      # @param severity [Symbol]
+      # @return [String] what SEVERITIES puts before the message
+      # @raise [ArgumentError] for a severity not in SEVERITIES
+      def severity_prefix(severity)
+        SEVERITIES.fetch(severity) do
+          raise ArgumentError, "unknown warning severity #{severity.inspect}; one of #{SEVERITIES.keys.inspect}"
+        end
+      end
+
+      # Whether the terminal has not had `key` in this process yet (and
+      # remembers that it now has).
+      #
+      # @param key [Symbol, String]
+      # @return [Boolean]
+      def first_on_terminal?(key)
+        written.put_if_absent(key.to_s, true).nil?
+      end
+
+      private
+
+      def check_audience!(audience)
+        return if AUDIENCES.include?(audience)
+
+        raise ArgumentError, "unknown warning audience #{audience.inspect}; one of #{AUDIENCES.inspect}"
+      end
+
+      # Rails.logger, nil before the app has one.
+      def current_logger
+        Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
+      end
+
+      # Never in test (a test run reads its log); in development always; in
+      # any other environment in a process that is not a server — each unless
+      # the log already shows on the terminal.
+      def terminal?(context)
+        env = context.env
+        return false if env.test?
+
+        (env.development? || !context.server) && !logger_on_terminal?(context.logger)
+      end
+
+      def written
+        @written ||= Concurrent::Map.new
+      end
+    end
+  end
+end

data/lib/permission_forge/web_request.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require 'rack/body_proxy'
+
+module PermissionForge
+  # The one definition of "a web request is in progress": the Rack request
+  # the host application is serving right now, from Middleware until the
+  # response is finished. The engine puts Middleware at the top of the
+  # host's stack (Engine: `config.app_middleware.unshift`), unless a
+  # middleware is inserted above it (`config.middleware.insert_before 0`, as
+  # rack-cors documents, or a gem that inserts at 0 later): StackCheck warns
+  # at boot and SecurityAudit lists them. So the host's own controllers, the
+  # mounted engine's admin screens and API, every middleware below it (a
+  # tenant lookup, an authentication middleware) and the before_actions of
+  # the host's ApplicationController count.
+  #
+  # Outside one: background jobs run by a worker, `perform_later` on an
+  # adapter that runs elsewhere (`:async` runs on its own threads), Action
+  # Cable channel actions (they run on the cable server's worker pool), rake
+  # tasks, `bin/rails runner`, the console, and ActionController::TestCase
+  # controller tests (they call the controller without the middleware
+  # stack; integration and system tests go through it). Inside one: a job
+  # run with `perform_now` (or the `:inline` adapter) and a mail delivered
+  # with `deliver_now` during the request.
+  #
+  # It decides config.masked_attributes_nil_user_strategy = :hide_in_requests
+  # (Configuration#masked_attributes_without_user_for) and where
+  # field.unmasked_without_user is recorded.
+  #
+  # The state is ExecutionState slot :pf_web_request (the request's env), in
+  # the :execution scope, kept at the end of an executor run: the middleware
+  # sets it before the request's run starts and puts back what it found when
+  # the response is finished (`rack.response_finished`, else when the server
+  # closes the body), or at once when the application raises. Under Rails'
+  # :thread isolation (the default) every fiber of the request's thread sees
+  # it (an Enumerator, a streamed body), and so does the thread
+  # ActionController::Live runs the action in (it shares the request's
+  # isolated state). Under `isolation_level = :fiber` each fiber has a state
+  # of its own: a fiber the request starts (Enumerator#next, a Live thread)
+  # does not see it, and a read there is outside the request — Falcon needs
+  # :fiber, as Rails itself does.
+  #
+  # A slot left behind (a server that neither runs the callbacks nor closes
+  # the body) hides more where it is seen, never less, and is never put back
+  # by a later request: an env whose application call has returned is not
+  # a request in progress around the next one.
+  #
+  # @api private
+  module WebRequest
+    KEY = :pf_web_request
+
+    # Recorded request values are cut to this many characters (as the audit
+    # context's request id and IP are).
+    VALUE_LIMIT = 255
+
+    # Reads the slot (ExecutionState.reader).
+    READ = ExecutionState.reader(KEY)
+
+    class << self
+      # @return [Boolean] whether this code runs inside a web request (asked
+      #   on every guarded read with nobody signed in: the slot's store is
+      #   read directly)
+      def active?
+        !READ.call.nil?
+      end
+
+      # @return [Hash, nil] the Rack env of the request in progress
+      def env
+        ExecutionState[KEY]
+      end
+
+      # The request in progress, for an audit event or a log line: its
+      # method, path (without the query string) and, once the router has
+      # matched it, endpoint ("controller_path#action"); {} outside a
+      # request. Read when asked, never kept.
+      #
+      # @return [Hash{String => String, nil}]
+      def details
+        env = self.env
+        return {} unless env
+
+        request = ActionDispatch::Request.new(env)
+        { 'method' => cut(request.request_method), 'path' => cut(request.path), 'endpoint' => endpoint(request) }
+      rescue StandardError
+        {}
+      end
+
+      # Runs the block as a web request (tests; Middleware keeps it past the
+      # block itself).
+      #
+      # @param env [Hash] a Rack env
+      # @return the block's value
+      def within(env = {}, &)
+        ExecutionState.with(KEY, env, &)
+      end
+
+      private
+
+      # What the router matched, read without writing: Request#path_parameters
+      # would store {} in the env of a request not routed yet (canary
+      # :path_parameters_key).
+      def endpoint(request)
+        params = request.get_header(ActionDispatch::Http::Parameters::PARAMETERS_KEY)
+        controller = params[:controller] if params.is_a?(Hash)
+        cut("#{controller}##{params[:action]}") if controller
+      end
+
+      def cut(value)
+        value.to_s[0, VALUE_LIMIT].presence
+      end
+    end
+
+    # Marks every request the host application serves (see WebRequest). At
+    # the top of the host's middleware stack, above ActionDispatch::Executor
+    # (StackCheck names what was inserted above it).
+    #
+    # @api private
+    class Middleware
+      # Set in the env once the application has returned the response: an
+      # env still in the slot then is no request around the next one.
+      RETURNED = 'permission_forge.web_request.returned'
+
+      # @param app [#call] the next middleware
+      def initialize(app)
+        @app = app
+      end
+
+      # @param env [Hash]
+      # @return [Array] the Rack response, its body wrapped when the server
+      #   does not announce `rack.response_finished`
+      def call(env)
+        finish = Finish.new(env)
+        returned = false
+        begin
+          status, headers, body = @app.call(env)
+          returned = true
+        ensure
+          returned ? env[RETURNED] = true : finish.call
+        end
+        [status, headers, finished(env, body, finish)]
+      end
+
+      private
+
+      # Until the response is finished: Rack 3 servers call the
+      # `rack.response_finished` callbacks once it is sent (ActionDispatch::Executor
+      # completes its run there too); others close the body.
+      def finished(env, body, finish)
+        callbacks = env['rack.response_finished']
+        return Rack::BodyProxy.new(body, &finish) unless callbacks
+
+        callbacks << finish
+        body
+      end
+    end
+
+    # The end of one request: puts back what the slot held (a request around
+    # it, or nothing) and, for the outermost request, forgets what runtime
+    # events it published once (Audit::Runtime.once?): reads made above
+    # ActionDispatch::Executor are outside its run, which would not clear
+    # them.
+    #
+    # @api private
+    class Finish
+      # @param env [Hash] the request's env, which the slot holds from now on
+      def initialize(env)
+        ExecutionState.put_back(KEY, nil) if Finish.left_behind?(ExecutionState[KEY])
+        @outermost = !WebRequest.active?
+        @restore = ExecutionState.set_until_restored(KEY, env)
+      end
+
+      # Whether the env in the slot is a request left behind: its application
+      # call returned and nobody finished its response (not a request around
+      # the next one).
+      #
+      # @param env [Hash, nil]
+      # @return [Boolean]
+      def self.left_behind?(env)
+        env.is_a?(Hash) && env[Middleware::RETURNED] == true
+      end
+
+      # Takes and ignores the arguments of a `rack.response_finished` callback.
+      # @return [void]
+      def call(*)
+        Audit::Runtime.reset! if @restore.call && @outermost
+      end
+
+      # @return [Proc] for Rack::BodyProxy's block
+      def to_proc = method(:call).to_proc
+    end
+
+    # Whether anything sits above Middleware in the built stack, read once the
+    # application has booted (BootChecks; SecurityAudit): a read there is
+    # outside the request, so :hide_in_requests does not hide it and :bypass
+    # does not record it.
+    #
+    # @api private
+    module StackCheck
+      class << self
+        # @param application [Rails::Application, nil]
+        # @return [Array<String>, nil] the names above Middleware (every name
+        #   when it is not in the stack at all); nil when the stack cannot be
+        #   read yet
+        def middlewares_above(application = default_application)
+          names = application && ApiOnlyAdmin.middleware_names(application)
+          return unless names
+
+          names.first(names.index(Middleware.name) || names.size)
+        end
+
+        # The boot warning, under the strategies that depend on the request
+        # being marked: :hide_in_requests (reads above are not hidden) and
+        # :bypass (they are not recorded).
+        #
+        # @param config [Configuration]
+        # @return [void]
+        def check(config, application = default_application)
+          strategy = config.masked_attributes_nil_user_strategy
+          return if strategy == :hide
+
+          above = middlewares_above(application)
+          return if above.blank?
+
+          if strategy == :hide_in_requests
+            Warnings.emit(:web_request_middleware_above_hide, message(above, 'are not hidden'), severity: :security, audience: :server)
+          else
+            Warnings.emit(:web_request_middleware_above_record, message(above, 'are not recorded'), severity: :config, audience: :server)
+          end
+        end
+
+        # @param above [Array<String>]
+        # @return [String]
+        def message(above, consequence)
+          "#{above.join(', ')} #{above.one? ? 'runs' : 'run'} above PermissionForge::WebRequest::Middleware: masked " \
+            "attributes read there with nobody signed in #{consequence} (masked_attributes_nil_user_strategy). Move " \
+            'the middleware below it (config.middleware.insert_after PermissionForge::WebRequest::Middleware, ...) ' \
+            'if it reads masked models.'
+        end
+
+        private
+
+        def default_application
+          Rails.application if defined?(Rails) && Rails.respond_to?(:application)
+        end
+      end
+    end
+  end
+end