permission_forge 0.14.1 → 0.15.0

data/lib/permission_forge/docs/configuration_reference.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module PermissionForge
+  # Generators of the gem's own documentation (development only; nothing here
+  # runs in a host application).
+  #
+  # @api private
+  module Docs
+    # The "Option reference" of docs/configuration.md, rendered from the code:
+    # Admin::SettingsCatalog::DEFINITIONS give the sections, the options and
+    # their order (the admin's Settings page), Configuration.new the defaults,
+    # Configuration::StrategyValues::ALLOWED what a strategy option takes, and
+    # the en locale the section titles and the first text of an option that
+    # has none yet. Every other public writer of Configuration follows under
+    # "Other options". The prose under each heading is kept from the document
+    # as it stands; the headings, their order and the `**Default:**` lines are
+    # regenerated (`bundle exec rake docs:configuration`;
+    # docs/configuration_reference_test.rb fails while the file is stale).
+    #
+    # @api private
+    class ConfigurationReference
+      START_MARK = '<!-- option-reference:start -->'
+      END_MARK = '<!-- option-reference:end -->'
+      NOTE = "<!-- Generated by `bundle exec rake docs:configuration` from SettingsCatalog and Configuration.new.\n     " \
+             "Edit the text under a heading here (or settings.items.<option> in the en locale for a new option):\n     " \
+             'the headings, their order and the **Default:** lines are regenerated. -->'
+      GENERATED_LINE = /\A\*\*Default:\*\*/
+      OTHER_SECTION = 'Other options'
+      PLACEHOLDER = '_Describe this option._'
+      LOCALE = File.expand_path('../../../config/locales/permission_forge.en.yml', __dir__)
+
+      # One `###` section of the reference: its title and the options under it.
+      Section = Struct.new(:title, :keys) do
+        def text(reference, existing)
+          intro = existing.section(title)
+          "### #{title}\n\n#{"#{intro}\n\n" unless intro.empty?}#{keys.map { |key| reference.entry(key, existing) }.join}"
+        end
+      end
+
+      attr_reader :document
+
+      # @param document [String] docs/configuration.md as it stands
+      def initialize(document:, configuration: Configuration.new, definitions: Admin::SettingsCatalog::DEFINITIONS,
+                     locale: LOCALE)
+        @document = document
+        @configuration = configuration
+        @definitions = definitions
+        @locale = YAML.load_file(locale).dig('en', 'permission_forge', 'settings')
+        @values = Admin::SettingsValues.new
+      end
+
+      # The document with its reference regenerated.
+      def render
+        before, region, after = split
+        existing = ExistingProse.new(region)
+        "#{before}#{START_MARK}\n#{NOTE}\n\n#{sections.map { |section| section.text(self, existing) }.join}#{END_MARK}#{after}"
+      end
+
+      def stale? = render != document
+
+      # The option headings the reference holds, in order.
+      def keys = sections.flat_map(&:keys)
+
+      # One option's entry: heading, the generated default line, the text.
+      def entry(key, existing)
+        "#### #{key}\n\n#{default_line(key)}\n\n#{option_text(key, existing)}\n\n"
+      end
+
+      private
+
+      # The document before the start mark, the region between the marks, the rest.
+      def split
+        start = document.index(START_MARK) or raise ArgumentError, "#{START_MARK} not found in the document"
+        stop = document.index(END_MARK, start) or raise ArgumentError, "#{END_MARK} not found in the document"
+        [document[0...start], document[(start + START_MARK.length)...stop], document[(stop + END_MARK.length)..]]
+      end
+
+      def sections
+        @sections ||= begin
+          by_section = @definitions.group_by(&:section)
+          catalog = Admin::SettingsCatalog::SECTIONS.map { |key| Section.new(@locale['sections'].fetch(key), by_section.fetch(key, []).map(&:key)) }
+          others = writers - @definitions.map(&:key)
+          others.empty? ? catalog : catalog << Section.new(OTHER_SECTION, others)
+        end
+      end
+
+      def writers
+        (@configuration.class.public_instance_methods - Object.public_instance_methods)
+          .grep(/\A\w+=\z/).map { |name| name.to_s.chomp('=') }.sort
+      end
+
+      # The text under an option: what the document says, else the Settings page's name and description.
+      def option_text(key, existing)
+        text = existing.option(key)
+        return text unless text.empty?
+
+        name, desc = @locale['items'].fetch(key, {}).values_at('name', 'desc')
+        name ? "**#{name.sub(/\.\z/, '')}.** #{desc}" : PLACEHOLDER
+      end
+
+      def default_line(key)
+        takes = takes_text(key)
+        "**Default:** #{default_text(key)}#{" Takes #{takes}." if takes}"
+      end
+
+      def takes_text(key)
+        allowed = Configuration::StrategyValues::ALLOWED[key.to_sym] or return
+        values = allowed.map { |value| "`#{value.inspect}`" }
+        list = values.size > 1 ? "#{values[0..-2].join(', ')} or #{values.last}" : values.first
+        "#{list} (or its String)#{', or nil' if Configuration::StrategyValues::BLANK_ALLOWED.include?(key.to_sym)}"
+      end
+
+      def default_text(key)
+        value = @configuration.public_send(key)
+        case value
+        when nil then nil_text(definition(key))
+        when Proc then "the gem's own lambda"
+        when Hash then hash_text(key, value)
+        else "`#{@values.ruby_literal(value)}`"
+        end
+      end
+
+      def definition(key) = @definitions.find { |candidate| candidate.key == key }
+
+      def nil_text(definition)
+        case definition&.nil_label
+        when :default then '`nil` (the built-in behaviour)'
+        when :disabled then '`nil` (off)'
+        else '`nil`'
+        end
+      end
+
+      def hash_text(key, value)
+        return '`{}`' if value.empty?
+        return '`PermissionForge::Configuration::DEFAULT_GDPR_FIELD_PATTERNS`' if value == Configuration::DEFAULT_GDPR_FIELD_PATTERNS
+
+        pairs = @values.normalize(definition(key) || Admin::SettingsCatalog.d(key, 'other', :map), value)
+        pairs.map { |pattern, target| "`#{pattern}` (#{target})" }.join(', ')
+      end
+
+      # What the document says under each heading of the region: the section
+      # intros (keyed by title) and the option texts (keyed by option), the
+      # generated lines and the note left out.
+      class ExistingProse
+        def initialize(region)
+          @sections = Hash.new { |hash, key| hash[key] = +'' }
+          @options = Hash.new { |hash, key| hash[key] = +'' }
+          collect(region.sub(/\A\s*<!--.*?-->/m, ''))
+        end
+
+        def section(title) = @sections[title].strip
+        def option(key) = @options[key].strip
+
+        private
+
+        def collect(region)
+          bucket = +''
+          region.each_line do |line|
+            case line.chomp
+            when /\A### (.+)\z/ then bucket = @sections[Regexp.last_match(1).strip]
+            when /\A#### (\w+)\s*\z/ then bucket = @options[Regexp.last_match(1)]
+            when ConfigurationReference::GENERATED_LINE then next
+            else bucket << line
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/encrypted_attributes.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # The one reader of a model's Active Record encryption declarations
+  # (`encrypts :email`): which columns hold ciphertext. Rails keeps the
+  # column's name, so nothing in the schema says so — the column of an
+  # encrypted attribute stores `{"p":"…","h":{…}}`, and SQL that compares it
+  # with a value compares the ciphertext:
+  #
+  # - a record rule cannot compare one (Operators::RuleColumn#encrypted?,
+  #   Operators::ValueTyping: every built-in operator that takes a value
+  #   matches nothing; is_null / is_not_null work, as the ciphertext is NULL
+  #   exactly when the value is; RuleProblem :encrypted_column), whichever
+  #   table of the rule's query it is in ({.models_on}: a table the query
+  #   joins that is on no model along the rule's path);
+  # - the admin's people search leaves one out of its LIKE, and bulk matching
+  #   of its lower-cased equality; a deterministically encrypted one matches
+  #   a whole value exactly (`where(email: value)` encrypts the value);
+  # - a person's label reads one decrypted (Admin::PersonLabel).
+  #
+  # Rails' `encrypted_attributes` (no rdoc; a canary watches it) is nil on a
+  # model that encrypts nothing and holds Symbols — an `ignore_case`
+  # attribute's `original_<name>` column among them. Under single-table
+  # inheritance it is per class, and a subclass's `encrypts` adds to its
+  # parent's Set when the parent has one (`||= Set.new`): the parent's
+  # answer depends on what encrypts what, and in which order. A column holds
+  # ciphertext when any class that stores rows in it says so, so the answer
+  # is the hierarchy's on the model's table ({.family}): the class, its base
+  # class and every loaded class of the hierarchy on that table. A subclass
+  # Rails has not loaded yet (lazy loading in development) is not seen.
+  #
+  # The value Rails reads from a column it cannot decrypt is no value
+  # ({.decrypt}): under `support_unencrypted_data` Rails answers with the
+  # stored ciphertext instead of raising.
+  #
+  # @api private
+  module EncryptedAttributes
+    module_function
+
+    # Whether the column holds ciphertext: an attribute of that name is
+    # declared with `encrypts` by the model or a class of its hierarchy on
+    # its table ({.family}).
+    #
+    # @param model [Class, nil] a model class (anything else has none)
+    # @param name [String, Symbol] a column or attribute name, as the model has it
+    # @return [Boolean]
+    def encrypted?(model, name)
+      names(model).include?(name.to_s.to_sym)
+    end
+
+    # Whether the attribute is encrypted deterministically: the same value
+    # always gives the same ciphertext, so `where(name => value)` finds it.
+    #
+    # @param model [Class, nil]
+    # @param name [String, Symbol]
+    # @return [Boolean]
+    def deterministic?(model, name)
+      encrypted?(model, name) && Array(model.deterministic_encrypted_attributes).include?(name.to_s.to_sym)
+    end
+
+    # @param model [Class, nil]
+    # @return [Array<Symbol>] the encrypted attributes of the model's
+    #   hierarchy on its table ({.family}; none for a non-model)
+    def names(model)
+      return [] unless model.respond_to?(:encrypted_attributes)
+
+      family(model).flat_map { |klass| Array(klass.encrypted_attributes) }.uniq
+    end
+
+    # The classes that store rows in the model's table: the model, its base
+    # class and every loaded descendant of the base class on the same table
+    # (single-table inheritance). Just the model for an abstract class or a
+    # class without a base class.
+    #
+    # @param model [Class]
+    # @return [Array<Class>]
+    def family(model)
+      return [model] unless model.respond_to?(:base_class) && !model.abstract_class?
+
+      base = model.base_class
+      table = model.table_name
+      [model, base, *base.descendants.select { |klass| !klass.abstract_class? && klass.table_name == table }].uniq
+    end
+
+    # Every loaded model class that stores rows in a table of that name:
+    # what a table a query joins stands for when it is on no model the
+    # caller knows (a `has_many :through`'s join table, a table a default
+    # scope or a host's join brings in: Operators::EncryptedAlias). Any
+    # loaded, non-abstract Active Record class whose table (its last
+    # segment, without a schema) is the name — the classes of a
+    # single-table hierarchy among them, so {.names} of any one of them
+    # covers the hierarchy. A class the application has not loaded yet
+    # (lazy loading in development) is not seen; nor is the database a
+    # class is on told apart (a table of that name in another database
+    # counts too: fail closed).
+    #
+    # @param table [String] the table's name, as the query gives it
+    # @param exact [Boolean] compare names as written (PostgreSQL), else
+    #   without regard to case (Operators::RuleColumn.same_name?)
+    # @return [Array<Class>]
+    def models_on(table, exact: false)
+      ActiveRecord::Base.descendants.select do |klass|
+        next false if klass.abstract_class?
+
+        own = klass.table_name.to_s.split('.').last
+        own.present? && Operators::RuleColumn.same_name?(own, table.to_s, exact)
+      rescue StandardError
+        false # a class that cannot name its table (an anonymous one without `table_name`) stores rows in none
+      end
+    end
+
+    # Of `names` (column names), those that do not hold ciphertext: what SQL
+    # can compare as written.
+    #
+    # @param model [Class]
+    # @param names [Array<String>]
+    # @return [Array<String>]
+    def plain(model, names)
+      names.reject { |name| encrypted?(model, name) }
+    end
+
+    # Of `names`, the deterministically encrypted ones.
+    #
+    # @param model [Class]
+    # @param names [Array<String>]
+    # @return [Array<String>]
+    def deterministic(model, names)
+      names.select { |name| deterministic?(model, name) }
+    end
+
+    # The value a stored ciphertext holds, read through the attribute's type
+    # (past any reader the model overrides, as MaskedAttributes does); nil
+    # when this application cannot decrypt it (another key, not ciphertext).
+    # Under `support_unencrypted_data` Rails answers a value it cannot
+    # decrypt with the stored value itself: a result that is still
+    # ciphertext is nil too. A value stored in plaintext reads as written
+    # there (Rails' own reading).
+    #
+    # @param model [Class]
+    # @param name [String, Symbol]
+    # @param raw [Object] the value as stored (read_attribute_before_type_cast)
+    # @return [Object, nil]
+    def decrypt(model, name, raw)
+      value = model.type_for_attribute(name.to_s).deserialize(raw)
+      value unless value.is_a?(String) && ActiveRecord::Encryption.encryptor.encrypted?(value)
+    rescue ActiveRecord::Encryption::Errors::Base
+      nil
+    end
+  end
+end

data/lib/permission_forge/engine.rb

@@ -1,7 +1,9 @@
 require_relative 'query_scoping_warnings'
+require_relative 'cache_warnings'
 require_relative 'boot_checks'
 require_relative 'masking_sync'
 require_relative 'masked_models'
+require_relative 'admin_method_override'
 
 module PermissionForge
   # Wires the gem into the host application: initializers, the executor and
@@ -16,6 +18,41 @@ module PermissionForge
       g.test_framework :minitest
     end
 
+    # The admin's edit and delete forms POST with a hidden `_method`: the
+    # engine's own stack (it runs for the engine's routes only) turns them
+    # into PATCH / DELETE, so an API-only host, which has no
+    # Rack::MethodOverride, needs nothing for it. The JSON API's paths are
+    # left alone (AdminMethodOverride).
+    config.middleware.use PermissionForge::AdminMethodOverride
+
+    # Every request the host application serves is a web request
+    # (PermissionForge::WebRequest) from the top of its stack until the
+    # response is finished: masked_attributes_nil_user_strategy
+    # :hide_in_requests hides there, and :bypass records
+    # field.unmasked_without_user. At the top of the stack (unless a
+    # middleware is inserted above it with insert_before 0: StackCheck names
+    # it at boot), so that a middleware or a before_action that reads a model
+    # before anyone is signed in counts too.
+    config.app_middleware.unshift PermissionForge::WebRequest::Middleware
+
+    # A denial nobody rescues answers 403, not 500: the row-rule refusal of
+    # find_by / find_by! and the action guard's refusal (Rails' exceptions
+    # app renders the status: public/403.html when the host has one, else an
+    # empty body). A host's rescue_from runs first and still decides.
+    #
+    # Set as the gem loads, as ActiveRecord's railtie sets its own: before
+    # ActionDispatch copies the setting into ExceptionWrapper, and before the
+    # host's config/application.rb, whose entry for either name wins. Class
+    # names, not constants: nothing is loaded for this.
+    config.action_dispatch.rescue_responses.merge!(
+      'PermissionForge::Concerns::PermissionScopedFindable::NotAuthorizedError' => :forbidden,
+      'PermissionForge::ActionNotAuthorizedError' => :forbidden,
+      # A request value the admin cannot read (ParamShapes::InvalidParam, an
+      # ActionController::BadRequest): 400 as its parent, which Rails maps by
+      # exact class name only. The API answers it with a 422 itself.
+      'PermissionForge::ParamShapes::InvalidParam' => :bad_request
+    )
+
     # The models (app/models/permission_forge) are autoloaded like any engine
     # model: their class bodies read the configuration after the host's
     # config/initializers, so nothing is re-declared after boot. No engine
@@ -47,7 +84,11 @@ module PermissionForge
         new_filters = PermissionForge.gdpr_filter_parameters
         app.config.filter_parameters += new_filters
 
-        Rails.logger.info "[PermissionForge] Added #{new_filters.size} GDPR patterns to filter_parameters."
+        # Not while a generator boots the app (BootChecks): the install
+        # generator's boot predates the initializer it writes.
+        unless PermissionForge::BootChecks.generator_running?
+          Rails.logger.info "[PermissionForge] Added #{new_filters.size} GDPR patterns to filter_parameters."
+        end
       end
     end
 
@@ -87,6 +128,10 @@ module PermissionForge
       PermissionForge::BootChecks.run(PermissionForge.configuration)
     end
 
+    # The checks that read the routes, once they are drawn: at boot, or at
+    # their first use where Rails 8 draws them lazily (eager_load off).
+    config.after_routes_loaded { |app| PermissionForge::BootChecks.routes_loaded(app) }
+
     # A setting a model reads as it loads (user_class, audit_user_class,
     # tenant_model) changed by the host's own after_initialize, once a
     # production boot has eager-loaded the models: the classes keep what they
@@ -96,18 +141,5 @@ module PermissionForge
     initializer 'permission_forge.model_bindings', after: :load_config_initializers do |app|
       app.config.after_initialize { PermissionForge::ModelBindings.warn! }
     end
-
-    # Deprecated: the masking machinery left the Engine (0.14). Removed in
-    # PermissionForge::Deprecation::HORIZON.
-    #
-    # @return [Boolean] what MaskedModels.apply returns
-    def self.apply_masked_attributes_to_managed_models(only: nil)
-      PermissionForge::Deprecation.warn(
-        'PermissionForge::Engine.apply_masked_attributes_to_managed_models is deprecated; ' \
-        'use PermissionForge::MaskedModels.apply(only:)',
-        callstack: caller_locations(1) # the host's call, not this method
-      )
-      PermissionForge::MaskedModels.apply(only: only)
-    end
   end
 end

data/lib/permission_forge/execution_state/restore.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module ExecutionState
+    # What .set_until_restored hands back: puts back what the slot held when
+    # it was set — once, and only where it was set (ExecutionState.owner: the
+    # fiber of a :fiber slot, the execution context of an :execution slot).
+    # Called from anywhere else (a Rack server finishing the response on
+    # another thread) it does nothing there, and the slot stays set where it
+    # was.
+    #
+    # @api private
+    class Restore
+      # @param name [Symbol] a key of KEYS
+      # @param previous [Object, nil] what the slot held
+      def initialize(name, previous)
+        @name = name
+        @previous = previous
+        @owner = ExecutionState.owner(name)
+        @done = false
+      end
+
+      # Takes and ignores the arguments a `rack.response_finished` callback
+      # is given.
+      #
+      # @return [Boolean] whether it put the value back (false: done
+      #   already, or called elsewhere)
+      def call(*)
+        return false if @done || !ExecutionState.owner(@name).equal?(@owner)
+
+        @done = true
+        ExecutionState.put_back(@name, @previous)
+        true
+      end
+    end
+
+    class << self
+      # Sets the slot past the end of the current block: for a value that
+      # must outlive the call that sets it (a Rack middleware keeps it until
+      # the response is finished, after its #call returned).
+      #
+      # @param name [Symbol] a key of KEYS
+      # @return [Restore] puts back what the slot held
+      def set_until_restored(name, value)
+        restore = Restore.new(name, self[name])
+        self[name] = value
+        restore
+      end
+
+      # A read-only reader of one slot, for a hot path that asks the same slot
+      # on every call without the lookup of #[] (WebRequest.active?): the
+      # store is looked up once, here.
+      #
+      # @param name [Symbol] a key of KEYS
+      # @return [Proc] returns what the slot holds
+      def reader(name)
+        store = storage(name)
+        -> { store[name] }
+      end
+
+      # Puts `previous` back in the slot (nil empties it), as .with does when
+      # its block ends.
+      #
+      # @param name [Symbol] a key of KEYS
+      # @param previous [Object, nil]
+      # @return [void]
+      def put_back(name, previous)
+        store = storage(name)
+        previous.nil? ? store.delete(name) : store[name] = previous
+        nil
+      end
+    end
+  end
+end

data/lib/permission_forge/execution_state.rb

@@ -122,7 +122,11 @@ module PermissionForge
       Key.new(:pf_audit_transaction_correlation, :execution, :clean,
               '[transaction, id] of the correlation id minted for the outermost open transaction'),
       Key.new(:pf_audit_runtime_once, :execution, :clean,
-              'Hash of the runtime audit events published once per request (Audit::Runtime.once?)')
+              'Hash of the runtime audit events published once per request (Audit::Runtime.once?)'),
+      Key.new(:pf_web_request, :execution, :keep,
+              'the Rack env of the web request in progress (WebRequest::Middleware, until the response is finished). ' \
+              'Execution: under :thread isolation every fiber of the request sees it. Seen elsewhere it hides more (fails closed); emptied ' \
+              'inside the request by a run completed there it would hide nothing: kept, the middleware puts it back')
     ].to_h { |key| [key.name, key] }.freeze
 
     CLEANED = KEYS.values.select { |key| key.at_run_end == :clean }.map(&:name).freeze
@@ -227,6 +231,9 @@ module PermissionForge
         end
       end
 
+      # Where slot `name` is kept now, the fiber or the execution context (Restore compares it).
+      def owner(name) = storage(name).equal?(FiberStorage) ? Fiber.current : ActiveSupport::IsolatedExecutionState.context
+
       # Empties every slot of this fiber and execution context: tests.
       #
       # @return [void]

data/lib/permission_forge/field_level.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # Maps the single "access level" of a field row to ResourceField flags and
+  # back. Granting sets offer Hidden / Masked / Read-only / Editable; muting
+  # sets offer Unchanged / Force mask / Hide, where the same flags mean
+  # "remove" (see PermissionHashBuilder#mute_single_field). The admin's
+  # controls, the ChangeSet, the effective-access views and the one row
+  # builder (ResourceFieldGenerator::RowBuilder) all read the tables here.
+  # Before 0.15.0 this lived at PermissionForge::Admin::FieldLevel, which is
+  # kept as an alias.
+  #
+  # @api private
+  module FieldLevel
+    GRANTING = {
+      'hidden' => { read_access: false, edit_access: false, mask_access: false },
+      'masked' => { read_access: true, edit_access: false, mask_access: true },
+      'read' => { read_access: true, edit_access: false, mask_access: false },
+      'edit' => { read_access: true, edit_access: true, mask_access: false }
+    }.freeze
+
+    MUTING = {
+      'leave' => { read_access: false, edit_access: false, mask_access: false },
+      'mask' => { read_access: false, edit_access: false, mask_access: true },
+      'hide' => { read_access: true, edit_access: true, mask_access: false }
+    }.freeze
+
+    # Ordered from most closed to most open (granting) — used to rank levels.
+    GRANTING_ORDER = %w[hidden masked read edit].freeze
+
+    module_function
+
+    def levels_for(muting:)
+      muting ? MUTING.keys : GRANTING.keys
+    end
+
+    # The level of a column with no setting: Unchanged in a Muting
+    # Permission Set (it mutes nothing: one state, one name), none in a
+    # granting one (unconfigured_field_strategy decides, and the row says so).
+    def unconfigured_level(muting:)
+      muting ? 'leave' : nil
+    end
+
+    # Whether a level is a row: every level of the set's kind, except
+    # Unchanged in a Muting Permission Set — it mutes nothing, which is what
+    # no row means. The one definition every path that creates rows reads
+    # (the row builder, the admin's presets and bulk add, the generator).
+    #
+    # @return [Boolean]
+    def row?(level, muting:)
+      valid?(level, muting: muting) && !(muting && level.to_s == 'leave')
+    end
+
+    # The level a row gets on its Resource: on a granting set Editable needs
+    # the Resource's Edit (the admin's level control disables it, turning
+    # the Resource's Edit off cascades Editable rows to Read-only, the
+    # effective-access views cap it), so without it Editable is Read-only —
+    # the row says what the field allows. A muting set's levels take access
+    # away and are never capped. The one definition every path that writes a
+    # level reads: the row builder (after the privacy default, so an
+    # Editable personal-data field becomes Read-only, never Masked) and the
+    # Fields tab's level edits.
+    #
+    # @param level [String]
+    # @param resource_edit [Boolean] the Resource grants Edit
+    # @param muting [Boolean]
+    # @return [String]
+    def capped(level, resource_edit:, muting:)
+      level = level.to_s
+      level == 'edit' && !muting && !resource_edit ? 'read' : level
+    end
+
+    def flags_for(level, muting:)
+      (muting ? MUTING : GRANTING).fetch(level.to_s) { raise ArgumentError, "Unknown field level: #{level.inspect}" }
+    end
+
+    def valid?(level, muting:)
+      (muting ? MUTING : GRANTING).key?(level.to_s)
+    end
+
+    # Derives the level from a field's flags. Flag combinations the UI never
+    # writes (e.g. edit + mask) collapse to the closest level.
+    # What a muting row takes away, for provenance (the WHY panel): its
+    # level, except a row that mutes edit but not read (API / console
+    # only), which takes editing away and leaves the field readable:
+    # 'no_edit', a level no form offers.
+    def muting_provenance(field)
+      level = level_of(field, muting: true)
+      level == 'hide' && !field.read_access ? 'no_edit' : level
+    end
+
+    def level_of(field, muting:)
+      read = field.read_access
+      edit = field.edit_access
+      mask = field.mask_access
+      return muting_level(read, edit, mask) if muting
+
+      return 'hidden' unless read
+      return 'masked' if mask
+
+      edit ? 'edit' : 'read'
+    end
+
+    def muting_level(read, edit, mask)
+      return 'hide' if read || edit
+
+      mask ? 'mask' : 'leave'
+    end
+
+    # Level an engine field-permission entry resolves to
+    # ({ read_access:, edit_access:, mask_access: } from the permissions hash).
+    def effective_level(entry)
+      return 'hidden' if entry.nil? || !entry[:read_access]
+      return 'masked' if entry[:mask_access]
+
+      entry[:edit_access] ? 'edit' : 'read'
+    end
+
+    def rank(level)
+      GRANTING_ORDER.index(level.to_s) || -1
+    end
+  end
+end