permission_forge 0.14.1

data/lib/permission_forge/admin/field_across_sets.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Every Permission Set containing a resource, with one field's row there
+    # (granting sets first, then by name) and the set's people count. Backs
+    # the field drawer's "In other sets" list and "Who can see …?".
+    class FieldAcrossSets
+      # @return [Array<Hash>] { resource:, set:, field: (ResourceField or nil), people:, in_effect: }
+      #   in_effect is whether the row (or, without a row, the resource) counts
+      #   right now, as in ActionAcrossSets#rows.
+      def self.call(resource_name, key) = new(resource_name, key).call
+
+      def initialize(resource_name, key)
+        @resource_name = resource_name
+        @key = key
+      end
+
+      def call
+        resources.map do |resource|
+          field = field_in(resource)
+          { resource: resource, set: resource.permission_set, field: field, people: people_count(resource),
+            in_effect: resource.in_effect? && (field.nil? || field.is_active) }
+        end
+      end
+
+      private
+
+      def resources
+        PermissionForge::Resource.where(name: @resource_name).includes(:permission_set, :resource_fields)
+                                 .sort_by { |resource| sort_key(resource.permission_set) }
+      end
+
+      def sort_key(permission_set)
+        [permission_set.is_muting ? 1 : 0, permission_set.name]
+      end
+
+      def field_in(resource)
+        resource.resource_fields.find { |field| field.name == @key }
+      end
+
+      def people_count(resource)
+        people_counts.fetch(resource.permission_set_id, 0)
+      end
+
+      def people_counts
+        @people_counts ||= PermissionForge::PermissionSetUser.active_assignments.group(:permission_set_id).count
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/field_detail.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # What the field drawer (resource_fields/show) shows for one column of a
+    # Resource, decided here so the template only lays it out: the level and
+    # mask strategy in force, which notes apply, whether the recommendation
+    # can be applied, and which person is being explained.
+    #
+    # Words stay in the template (I18n); this answers which note, not what it
+    # says.
+    #
+    # @example
+    #   detail = FieldDetail.new(resource: resource, row: rows.row('email'), rows: rows)
+    #   detail.locked?               # => false
+    #   detail.unconfigured_note     # => :not_configured
+    #   detail.recommendation        # => :apply
+    class FieldDetail
+      DEFAULT_STRATEGY = 'full'
+      CONTEXT_KEYS = %i[rules across people_count explain_people explain explain_user_id].freeze
+
+      attr_reader :resource, :row, :rows, :rules, :across, :people_count, :explain, :explain_people
+
+      # rows: the FieldRows the row came from (it knows the model).
+      # explain: { user:, field: } for the person picked in "Explain for a person", else nil.
+      def initialize(resource:, row:, rows:, configuration: PermissionForge.configuration, **context)
+        @resource = resource
+        @row = row
+        @rows = rows
+        @configuration = configuration
+        unknown = context.keys - CONTEXT_KEYS
+        raise ArgumentError, "unknown context: #{unknown.join(', ')}" if unknown.any?
+
+        @rules = context.fetch(:rules, [])
+        @across = context[:across]
+        @people_count = context[:people_count]
+        @explain_people = context.fetch(:explain_people, [])
+        @explain = context[:explain]
+        @explain_user_id = context[:explain_user_id].to_s
+      end
+
+      def permission_set = resource.permission_set
+      def key = row.name
+      def field = row.field
+      def label = row.label
+      def muting? = permission_set.is_muting
+      def level = row.level
+
+      # Locked when the field, its Resource or its Permission Set is (is_editable: false).
+      def locked? = !EditableLock.locked_record(field, resource).nil?
+
+      # The mask strategy the select starts on: the saved one, else the
+      # recommended one for a sensitive column, else 'full'.
+      def strategy
+        field&.mask_strategy || row.match&.strategy || DEFAULT_STRATEGY
+      end
+
+      # Other columns that follow this one (`_id` → `_uuid`, `_cents` → base name).
+      def variants
+        @variants ||= @configuration.field_variants_for(key)
+      end
+
+      # The edit level needs edit access on the Resource, except in a muting set.
+      def edit_disabled? = !muting? && !resource.edit_access
+
+      def in_force? = row.in_force?
+
+      # The note under the level control while no setting is in force, as the
+      # suffix of a locale key under `resource_fields.show` — or nil.
+      def unconfigured_note
+        return nil if row.in_force?
+
+        implicit = row.implicit_grant
+        if row.configured?
+          implicit ? :turned_off_implicit : :turned_off
+        else
+          implicit ? :not_configured_implicit : :not_configured
+        end
+      end
+
+      # Setting the note links to.
+      def unconfigured_setting
+        row.implicit_grant ? 'extra_fields_default_access' : 'unconfigured_field_strategy'
+      end
+
+      # What happens to a field nobody set up (a key under `ui.unconfigured`).
+      def unconfigured_behaviour = @configuration.unconfigured_field_strategy
+
+      def sensitive? = row.sensitive?
+
+      # The privacy recommendation banner: only for a sensitive field in a granting set.
+      def recommendation_banner? = sensitive? && !muting?
+
+      # :applied (already masked with the recommended strategy), :apply (offer
+      # the button) or nil (locked: nothing to offer).
+      def recommendation
+        return :applied if level == 'masked' && strategy == row.match.strategy
+        return nil if locked?
+
+        :apply
+      end
+
+      def virtual? = row.virtual
+      def declared? = row.declared
+      def extra_fields_method = @configuration.extra_fields_method
+      def model_masks_virtual? = rows.model&.masked_on_model?(key) || false
+
+      # The person the explain select starts on.
+      def explain_selected?(user) = @explain_user_id == user.id.to_s
+    end
+  end
+end

data/lib/permission_forge/admin/field_level.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Maps the admin UI's single "access level" choice 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).
+    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
+
+      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.
+      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
+end

data/lib/permission_forge/admin/field_rows.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # One row per field on a Resource page: configured ResourceFields, model
+    # columns nobody configured yet, and virtual fields — with the flags the
+    # UI needs (sensitive, virtual, column missing, level).
+    class FieldRows
+      # `declared` — a virtual field the model lists in extra_fields_method
+      # (a virtual row that is not declared was discovered). `implicit_grant` —
+      # no setting in force here (none, or one that is turned off), and
+      # ExtraFieldDefaults makes the field readable and editable right now
+      # (extra_fields_default_access = :grant).
+      Row = Struct.new(:name, :label, :field, :match, :virtual, :missing, :level, :declared, :implicit_grant,
+                       keyword_init: true) do
+        def configured? = !field.nil?
+        def sensitive? = !match.nil?
+        def locked? = field && field.is_editable == false
+        def active? = field.nil? || field.is_active
+
+        # A setting the engine applies: it exists and is turned on. A row that
+        # is configured and not in force is turned off (is_active false); the
+        # engine skips it, so the field is treated like one with no setting.
+        def in_force? = configured? && active?
+      end
+
+      GRANTING_FILTERS = %w[all hidden masked read edit sensitive unconfigured].freeze
+      MUTING_FILTERS = %w[all leave mask hide sensitive unconfigured].freeze
+
+      attr_reader :resource, :model
+
+      def initialize(resource, catalog: ModelCatalog.new, sensitive: SensitiveColumns.new)
+        @resource = resource
+        @muting = resource.permission_set.is_muting
+        @model = catalog.find(resource.name)
+        @sensitive = sensitive
+      end
+
+      def filters
+        @muting ? MUTING_FILTERS : GRANTING_FILTERS
+      end
+
+      def rows
+        @rows ||= (configured_rows + unconfigured_rows).sort_by { |r| [r.configured? ? 0 : 1, r.name] }
+      end
+
+      def filtered(filter: 'all', query: nil)
+        needle = query.to_s.strip.downcase
+        rows.select { |r| match_filter?(r, filter) && (needle.empty? || "#{r.name} #{r.label}".downcase.include?(needle)) }
+      end
+
+      def counts
+        filters.index_with { |filter| rows.count { |r| match_filter?(r, filter) } }
+      end
+
+      def row(name)
+        rows.find { |r| r.name == name.to_s }
+      end
+
+      # --- sync with model -----------------------------------------------------
+
+      # Managed columns and virtual fields nobody configured in this resource.
+      def new_columns
+        return [] unless @model
+
+        @model.managed_field_names - configured_names
+      end
+
+      def missing_fields
+        rows.select(&:missing)
+      end
+
+      def ignored_columns
+        Array(@model&.ignored_column_names)
+      end
+
+      def sync_needed?
+        new_columns.any? || missing_fields.any?
+      end
+
+      private
+
+      # Every row counts, switched off or not: a field with a row cannot get a
+      # second one.
+      def configured_names
+        @configured_names ||= @resource.resource_fields.map(&:name)
+      end
+
+      def configured_rows
+        @resource.resource_fields.map { |field| configured_row(field) }
+      end
+
+      def configured_row(field)
+        name = field.name
+        virtual = virtual?(name)
+        Row.new(name: name, label: field.label.presence || human(name), field: field, match: @sensitive.match(name),
+                virtual: virtual, missing: @model.present? && !virtual && @model.column_names.exclude?(name),
+                level: FieldLevel.level_of(field, muting: @muting), declared: declared?(name),
+                implicit_grant: !field.is_active && implicit_grant?(name))
+      end
+
+      def unconfigured_rows
+        new_columns.map do |name|
+          Row.new(name: name, label: human(name), field: nil, match: @sensitive.match(name), virtual: virtual?(name),
+                  missing: false, level: nil, declared: declared?(name), implicit_grant: implicit_grant?(name))
+        end
+      end
+
+      def implicit_grant?(name)
+        @model.present? && @model.implicit_grant?(name)
+      end
+
+      # A field configured while discovery was on stays virtual (not "column
+      # missing") after discovery is turned off.
+      def virtual?(name)
+        @model.present? && @model.virtual_field?(name)
+      end
+
+      def declared?(name)
+        @model.present? && @model.declared_virtual_field_names.include?(name)
+      end
+
+      def human(name)
+        @model ? @model.klass.human_attribute_name(name) : name.to_s.humanize
+      end
+
+      def match_filter?(row, filter)
+        case filter
+        when 'all' then true
+        when 'sensitive' then row.sensitive?
+        when 'unconfigured' then !row.configured?
+        else row.level == filter
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/last_changes.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/numeric/time' # UNSEEN_AFTER, read as this file loads
+
+module PermissionForge
+  module Admin
+    # The latest recorded change event of each of a list of records: who
+    # really made the last edit, and when. `updated_by` alone cannot say —
+    # an edit by nobody, by an HTTP Basic login or by an API client keeps the
+    # previous editor — so wherever the admin shows "last edited by", an
+    # event wins over the columns (see AuditTrail::Entry and the footer).
+    #
+    # Two queries per record type and slice: the newest event id per record
+    # (the ids grow with every insert), then those events.
+    class LastChanges
+      SLICE = 500
+
+      # @param records [Array<ActiveRecord::Base>] permission records
+      # @param events [Array<String>, nil] only these change events (e.g.
+      #   %w[assignment.granted] — who granted it); nil: any change event
+      def initialize(records, events: nil)
+        @records = Array(records).compact
+        @events = events
+      end
+
+      # Edits this much later than the last event are edits the log did not see.
+      UNSEEN_AFTER = 1.second
+
+      # @return [AuditEvent, nil] the latest (matching) change event of the record
+      def [](record)
+        index[key(record.class.base_class.name, record.id)]
+      end
+
+      # The latest change event when it is the record's last edit; nil when
+      # the record was edited after it (updated_at more than UNSEEN_AFTER
+      # later — an edit made while auditing was off): the columns are newer.
+      #
+      # @return [AuditEvent, nil]
+      def last_edit(record)
+        event = self[record]
+        return nil unless event
+
+        updated = record.try(:updated_at)
+        updated && updated > event.occurred_at + UNSEEN_AFTER ? nil : event
+      end
+
+      # Whether the record is one of those this lookup was built for.
+      def covers?(record)
+        @keys ||= @records.to_set { |candidate| key(candidate.class.base_class.name, candidate.id) }
+        @keys.include?(key(record.class.base_class.name, record.id))
+      end
+
+      private
+
+      def key(type, id)
+        "#{type}##{id}"
+      end
+
+      def index
+        @index ||= available? ? load_index : {}
+      end
+
+      def available?
+        @records.any? && PermissionForge::Audit.enabled?
+      rescue StandardError
+        false
+      end
+
+      def load_index
+        ids_by_type.each_with_object({}) do |(type, ids), out|
+          ids.each_slice(SLICE) { |slice| index_latest(out, type, slice) }
+        end
+      end
+
+      def index_latest(index, type, ids)
+        latest(type, ids).each { |event| index[key(type, event.record_id)] = event }
+      end
+
+      # { record type => [ids as Strings] }
+      def ids_by_type
+        @records.group_by { |record| record.class.base_class.name }
+                .transform_values { |records| records.map { |record| record.id.to_s }.uniq }
+      end
+
+      def latest(type, ids)
+        events = PermissionForge::AuditEvent
+        matching = events.where(category: 'change', record_type: type, record_id: ids)
+        matching = matching.where(event: @events) if @events
+        newest = matching.group(:record_id).select(events.arel_table[:id].maximum)
+        events.where(id: newest).to_a
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/model_catalog.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Read-only reflection over the host app's ActiveRecord models, so the
+    # admin UI only ever offers real models, columns and associations (no
+    # free-text names that silently do nothing when misspelled).
+    class ModelCatalog
+      Column = Struct.new(:name, :label, :type, :enum_values, :user_reference, :virtual, keyword_init: true) do
+        def user_reference? = user_reference
+        def virtual? = virtual
+      end
+
+      Association = Struct.new(:name, :label, :class_name, :foreign_key, :macro, keyword_init: true) do
+        # @param reflection [ActiveRecord::Reflection::AssociationReflection] (non-polymorphic)
+        # @param target [Class] the reflection's resolved class
+        # @param owner [Class] the model declaring the association
+        def self.from(reflection, target, owner)
+          name = reflection.name
+          new(name: name.to_s, label: owner.human_attribute_name(name), class_name: target.name,
+              foreign_key: reflection.foreign_key.to_s, macro: reflection.macro)
+        end
+      end
+
+      # A model the admin can protect. Its virtual fields come from
+      # PermissionForge::VirtualFields.
+      class ModelInfo
+        attr_reader :klass
+
+        # Whether a field with no active ResourceField row gets the implicit
+        # read + edit entry from ExtraFieldDefaults right now.
+        delegate :implicit_grant?, to: :virtual_fields
+
+        def initialize(klass, configuration)
+          @klass = klass
+          @configuration = configuration
+        end
+
+        def name = @klass.name
+        def label = @klass.model_name.human
+        def plural_label = @klass.model_name.human(count: 2)
+
+        def column_names
+          @column_names ||= @klass.column_names
+        end
+
+        # Columns PermissionForge manages (ignored_fields removed).
+        def managed_column_names
+          column_names - ignored_column_names
+        end
+
+        def ignored_column_names
+          column_names & Array(@configuration.ignored_fields).map(&:to_s)
+        end
+
+        # Virtual fields the model declares through extra_fields_method.
+        def declared_virtual_field_names
+          virtual_fields.declared
+        end
+
+        # Declared + discovered (config.virtual_field_discovery), never a
+        # column or an ignored field.
+        def virtual_field_names
+          virtual_fields.names
+        end
+
+        # Every field the admin configures: managed columns, then virtual fields.
+        def managed_field_names
+          managed_column_names + virtual_field_names
+        end
+
+        def virtual_field?(name)
+          virtual_fields.include?(name)
+        end
+
+        # Whether code that reads a virtual field straight from the model gets
+        # the field's level: its reader is wrapped on the class and
+        # config.mask_virtual_attributes selects the model.
+        def masked_on_model?(name)
+          PermissionForge::Concerns::MaskedAttributes::VirtualReaders.masked?(@klass, name)
+        end
+
+        def columns
+          @columns ||= managed_column_names.map { |name| column(name) } +
+                       virtual_field_names.map { |name| virtual_column(name) }
+        end
+
+        def column(name)
+          name = name.to_s
+          return virtual_column(name) unless column_names.include?(name)
+
+          Column.new(name: name, label: @klass.human_attribute_name(name), type: column_type(name),
+                     enum_values: enum_values(name), user_reference: user_reference?(name), virtual: false)
+        end
+
+        def associations
+          @associations ||= @klass.reflect_on_all_associations.filter_map { |ref| build_association(ref) }
+        end
+
+        def association(name)
+          associations.find { |association| association.name == name.to_s }
+        end
+
+        private
+
+        def virtual_fields
+          @virtual_fields ||= PermissionForge::VirtualFields.new(@klass, @configuration)
+        end
+
+        # nil for polymorphic or unresolvable associations.
+        def build_association(ref)
+          target = safe_klass(ref) unless ref.polymorphic?
+          Association.from(ref, target, @klass) if target
+        end
+
+        def virtual_column(name)
+          Column.new(name: name, label: @klass.human_attribute_name(name), type: :string,
+                     enum_values: nil, user_reference: false, virtual: true)
+        end
+
+        def column_type(name)
+          @klass.type_for_attribute(name).type || :string
+        rescue StandardError
+          :string
+        end
+
+        def enum_values(name)
+          return nil unless @klass.respond_to?(:defined_enums)
+
+          @klass.defined_enums[name]&.keys
+        end
+
+        def user_reference?(name)
+          user_class = @configuration.user_class.to_s
+          @klass.reflect_on_all_associations(:belongs_to).any? do |ref|
+            !ref.polymorphic? && ref.foreign_key.to_s == name && safe_klass(ref)&.name == user_class
+          end
+        end
+
+        def safe_klass(ref)
+          ref.klass
+        rescue StandardError
+          nil
+        end
+      end
+
+      def initialize(configuration: PermissionForge.configuration)
+        @configuration = configuration
+      end
+
+      # @return [Array<ModelInfo>] sorted by label
+      def models
+        @models ||= model_classes.map { |k| ModelInfo.new(k, @configuration) }.sort_by(&:label)
+      end
+
+      # @return [ModelInfo, nil] for a model name, whether or not it is listed.
+      #   One ModelInfo per name for this catalog, so its reflection runs once
+      #   however many Permission Sets contain the model.
+      def find(name)
+        key = name.to_s
+        @found ||= {}
+        @found.fetch(key) { @found[key] = build_info(key) }
+      end
+
+      private
+
+      def build_info(name)
+        klass = name.safe_constantize
+        ModelInfo.new(klass, @configuration) if usable?(klass)
+      end
+
+      def model_classes
+        classes = if @configuration.admin_model_resolver
+                    Array(@configuration.admin_model_resolver.call)
+                  else
+                    default_model_classes
+                  end
+        classes.select { |k| usable?(k) }.uniq
+      end
+
+      def default_model_classes
+        eager_load_app_models
+        ActiveRecord::Base.descendants.select { |k| k.name.present? && app_model?(k) }
+      end
+
+      def usable?(klass)
+        klass.is_a?(Class) && klass < ActiveRecord::Base && !klass.abstract_class? &&
+          !klass.name.to_s.start_with?('PermissionForge::') && klass.table_exists?
+      rescue StandardError
+        false
+      end
+
+      # Only models defined inside the host app (not gems/frameworks).
+      def app_model?(klass)
+        return true unless defined?(Rails) && Rails.root
+
+        file = Object.const_source_location(klass.name)&.first
+        file.nil? || file.start_with?(Rails.root.to_s)
+      rescue StandardError
+        true
+      end
+
+      def eager_load_app_models
+        return unless defined?(Rails) && Rails.root && Rails.respond_to?(:autoloaders)
+
+        eager_load_dir(Rails.autoloaders.main, Rails.root.join('app', 'models').to_s)
+      rescue StandardError => e
+        Rails.logger&.debug("[PermissionForge] model eager load skipped: #{e.class}")
+      end
+
+      def eager_load_dir(loader, dir)
+        loader.eager_load_dir(dir) if File.directory?(dir) && loader.respond_to?(:eager_load_dir)
+      end
+    end
+  end
+end