permission_forge 0.14.1

data/lib/permission_forge/admin/bulk_people_matcher.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Resolves pasted emails/names (one per line or comma-separated) to people
+    # for bulk assignment. Exact, case-insensitive matches only — a near miss
+    # is reported as "not found" rather than guessed. Only people within
+    # config.user_list_resolver match (PeopleDirectory#find_all): anyone else
+    # is "not found" too.
+    class BulkPeopleMatcher
+      FIRST_LAST_COLUMNS = [%w[first_name last_name], %w[firstname lastname]].freeze
+      # Same-named people considered per pasted line before the resolver
+      # narrows them.
+      CANDIDATES_PER_TOKEN = 20
+
+      Result = Struct.new(:to_assign, :already, :not_found, keyword_init: true)
+
+      # @param directory [PeopleDirectory, nil] share the request's directory,
+      #   so an array-returning resolver is evaluated once per request
+      def initialize(configuration: PermissionForge.configuration, directory: nil)
+        @configuration = configuration
+        @directory = directory
+      end
+
+      # @param text [String] pasted identifiers
+      # @param user_ids [Array] people picked with checkboxes
+      # @param permission_set [PermissionSet]
+      def call(text:, user_ids:, permission_set:)
+        found, not_found = resolve(tokens(text))
+        picked(user_ids).each { |user| found[user.id] = user }
+
+        already, to_assign = partition_assigned(found.values, permission_set)
+        Result.new(to_assign: to_assign, already: already, not_found: not_found)
+      end
+
+      private
+
+      # [already assigned, not yet assigned]
+      def partition_assigned(users, permission_set)
+        assigned = permission_set.permission_set_users.where(user_id: users.map(&:id)).pluck(:user_id)
+        users.partition { |user| assigned.include?(user.id) }
+      end
+
+      def tokens(text)
+        PeopleDirectory.search_text(text).split(/[\n,;]+/).map(&:strip).reject(&:empty?).uniq
+      end
+
+      # [{ id => user } for matched tokens, unmatched tokens]
+      def resolve(tokens)
+        found = {}
+        not_found = tokens.reject do |token|
+          user = lookup(token)
+          found[user.id] = user if user
+        end
+        [found, not_found]
+      end
+
+      def model
+        @configuration.user_model
+      end
+
+      def lookup(token)
+        needle = token.downcase
+        return exact(column_if_present('email'), needle) if token.include?('@')
+
+        exact(name_column, needle) || first_last_match(needle)
+      end
+
+      def exact(column, needle)
+        column && first_listed(model.where(model.arel_table[column].lower.eq(needle)))
+      end
+
+      # The first match that config.user_list holds.
+      def first_listed(matches)
+        directory.find_all(matches.limit(CANDIDATES_PER_TOKEN).ids).first
+      end
+
+      def directory
+        @directory ||= PeopleDirectory.new(configuration: @configuration)
+      end
+
+      def column_if_present(column)
+        column if model.column_names.include?(column)
+      end
+
+      # "Ana Krasniqi" against separate first/last name columns.
+      def first_last_match(needle)
+        first, last = needle.split(/\s+/, 2)
+        pair = first_last_columns
+        return nil unless pair && last
+
+        table = model.arel_table
+        first_listed(model.where(table[pair.first].lower.eq(first).and(table[pair.last].lower.eq(last))))
+      end
+
+      def first_last_columns
+        FIRST_LAST_COLUMNS.find { |cols| (cols - model.column_names).empty? }
+      end
+
+      def name_column
+        (%w[name full_name display_name] & model.column_names).first
+      end
+
+      def picked(ids)
+        directory.find_all(ids)
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/change_set.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Batched edits to one Permission Set (set header, resource CRUD/scope
+    # flags, field levels, new fields, action toggles, new actions) as
+    # submitted by the editor forms.
+    #
+    # Computes the list of real changes — after the same cascades the UI
+    # shows (Read off => Edit/Delete/View All/Modify All off and Editable
+    # fields downgraded; Edit off => Modify All off and Editable fields
+    # downgraded) — and applies them in one transaction. Muting sets have
+    # inverted semantics, so no cascades or dependencies apply to them.
+    #
+    # Params shape (all optional):
+    #   set:        { name:, description:, is_active:, permission_set_group_id: }
+    #   resources:  { "<id>" => { read_access: "1", ..., label:, description: } }
+    #   fields:     { "<field id>" => { level: "masked", mask_strategy:, label:, description:, is_active: } }
+    #   new_fields: { "<resource id>" => { "<column>" => { level: } } }
+    #   actions:    { "<action id>" => { is_permitted: "1" } }
+    #   bulk:       { resource_id:, keys: [...], level: }
+    #   new_actions:  { "<resource id>" => { "<key>" => { is_permitted: "1" } } }
+    #   bulk_actions: { resource_id:, is_permitted: "1" } — every discovered action without a row
+    class ChangeSet
+      # Collaborators, in evaluation order: later parts see earlier parts'
+      # in-memory edits (field levels depend on the resource's new Edit flag).
+      PARTS = [
+        ChangeSetParts::SetAttrs,
+        ChangeSetParts::ResourceFlags,
+        ChangeSetParts::FieldLevels,
+        ChangeSetParts::NewFields,
+        ChangeSetParts::Actions,
+        ChangeSetParts::NewActions
+      ].freeze
+
+      # kind: :set_attr | :resource_flag | :resource_text | :field_level | :field_attr | :new_field | :action |
+      #       :new_action
+      Change = Struct.new(:kind, :record, :attribute, :from, :to, :cascaded, :resource, keyword_init: true) do
+        # Blank-ish values (nil, "") are equal; false is a real value.
+        def unchanged?
+          from == to || (from.blank? && to.blank? && from != false && to != false)
+        end
+
+        # Captures the record's current value as `from` and assigns `to`.
+        # Returns self, or nil (nothing assigned) when effectively unchanged.
+        def assign
+          self.from = record.public_send(attribute)
+          return if unchanged?
+
+          record.public_send("#{attribute}=", to)
+          self
+        end
+      end
+
+      class Invalid < StandardError
+        attr_reader :record
+
+        def initialize(record)
+          @record = record
+          super(record.errors.full_messages.to_sentence)
+        end
+      end
+
+      attr_reader :permission_set
+
+      # @param catalog [ControllerCatalog, nil] the app's controller actions,
+      #   for new_actions; built on first use when nil
+      def initialize(permission_set:, params:, sensitive: SensitiveColumns.new, catalog: nil)
+        @permission_set = permission_set
+        @context = ChangeSetParts::Context.new(permission_set: permission_set, params: normalize(params),
+                                               sensitive: sensitive, catalog: catalog)
+      end
+
+      def changes
+        @changes ||= PARTS.flat_map { |part| part.new(@context).call }
+      end
+
+      def empty?
+        changes.empty?
+      end
+
+      # Saves every pending record, all or nothing, under one audit
+      # correlation id. Its own savepoint (requires_new) rolls back the saves
+      # before a failing one — and their audit events — also when the caller's
+      # transaction rescues Invalid and goes on to commit.
+      #
+      # @return [Array<Change>]
+      # @raise [Invalid] a record failed validation; nothing was saved
+      def apply!
+        PermissionForge::Audit.correlate do
+          ActiveRecord::Base.transaction(requires_new: true) do
+            pending_records.each { |record| save!(record) }
+          end
+        end
+        changes
+      end
+
+      private
+
+      # Anything but a Hash of sections (a String, an Array) changes nothing.
+      def normalize(params)
+        hash = if params.respond_to?(:to_unsafe_h) then params.to_unsafe_h
+               elsif params.is_a?(Hash) then params
+               else {}
+               end
+        hash.deep_stringify_keys
+      end
+
+      def save!(record)
+        raise Invalid, record unless record.save
+      end
+
+      # Records with assigned-but-unsaved attributes, in dependency order.
+      def pending_records
+        changes.map(&:record).uniq.select { |record| pending?(record) }
+      end
+
+      def pending?(record)
+        record.new_record? || record.changed?
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/change_set_parts/actions.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module ChangeSetParts
+      # Custom action is_permitted toggles (actions of locked resources are ignored).
+      class Actions < Base
+        def call
+          section('actions').filter_map do |id, attrs|
+            action = action_index[id.to_s]
+            next unless action && attrs.is_a?(Hash) && attrs.key?('is_permitted')
+
+            assign_change(kind: :action, record: action, attribute: 'is_permitted', to: truthy?(attrs['is_permitted']),
+                          resource: resource_of(action))
+          end
+        end
+
+        private
+
+        def action_index
+          @action_index ||= resources.values.reject { |r| locked?(r) }.flat_map(&:resource_actions)
+                                     .index_by { |action| action.id.to_s }
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/change_set_parts/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module ChangeSetParts
+      # Base for the ChangeSet collaborators. Each part turns one params
+      # section into a list of ChangeSet::Change and assigns (never saves) the
+      # new values on the in-memory records; ChangeSet#apply! persists them.
+      class Base
+        def initialize(context)
+          @context = context
+        end
+
+        private
+
+        delegate :permission_set, :params, :sensitive, :muting?, :section, :resources, :resource_of,
+                 to: :@context
+
+        def change(**attrs)
+          ChangeSet::Change.new(**attrs)
+        end
+
+        # Assigns the change on its record; nil when effectively unchanged.
+        def assign_change(**attrs)
+          change(**attrs).assign
+        end
+
+        def valid_level?(level)
+          FieldLevel.valid?(level, muting: muting?)
+        end
+
+        def flags_for(level)
+          FieldLevel.flags_for(level, muting: muting?)
+        end
+
+        # The resource for `id`, unless missing or locked.
+        def unlocked_resource(id)
+          resource = resources[id.to_s]
+          resource unless resource.nil? || locked?(resource)
+        end
+
+        def bulk
+          section('bulk')
+        end
+
+        # Records flagged is_editable: false are managed by the system/API and
+        # are never changed from the admin UI (their disabled inputs still post).
+        def locked?(record)
+          record.respond_to?(:is_editable) && record.is_editable == false
+        end
+
+        def truthy?(value)
+          Values.truthy?(value)
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/change_set_parts/context.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module ChangeSetParts
+      # State shared by every ChangeSet collaborator: the permission set, the
+      # normalized params and the in-memory resources. Each part mutates these
+      # same resource/field objects, so later parts see earlier parts' edits
+      # (e.g. field levels see the resource's new Edit flag).
+      class Context
+        attr_reader :permission_set, :params, :sensitive
+
+        def initialize(permission_set:, params:, sensitive:, catalog: nil)
+          @permission_set = permission_set
+          @params = params
+          @sensitive = sensitive
+          @controller_catalog = catalog
+          @muting = permission_set.is_muting
+        end
+
+        # The app's controller actions (see NewActions). Built on first use:
+        # most change sets never read the route table.
+        def controller_catalog
+          @controller_catalog ||= ControllerCatalog.new
+        end
+
+        def muting?
+          @muting
+        end
+
+        # One params section (e.g. 'fields', 'bulk'), or an empty hash — also
+        # when the request sent something else than a Hash there.
+        def section(key)
+          value = @params[key]
+          value.is_a?(Hash) ? value : {}
+        end
+
+        def resources
+          @resources ||= @permission_set.resources.includes(:resource_fields).index_by { |r| r.id.to_s }
+        end
+
+        # The in-memory resource (with this change set's flag edits applied) — not
+        # record.resource, which may be a separately loaded copy.
+        def resource_of(record)
+          resources[record.resource_id.to_s]
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/change_set_parts/field_edit.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module ChangeSetParts
+      # Edits to one existing field: level (+ mask strategy), then
+      # label/description/active. `resource` is the in-memory resource with
+      # this change set's flag edits already applied.
+      class FieldEdit
+        ATTRS = %w[label description is_active].freeze
+        MASK_LEVELS = %w[masked mask].freeze
+        CASTS = {
+          'label' => ->(value, field) { value.to_s.strip.presence || field.name.humanize },
+          'is_active' => ->(value, _field) { Values.truthy?(value) }
+        }.freeze
+        TEXT_CAST = ->(value, _field) { value.to_s.strip.presence }
+
+        def initialize(field, resource, muting:)
+          @field = field
+          @resource = resource
+          @muting = muting
+        end
+
+        def changes(attrs)
+          level_change(attrs) + attr_changes(attrs.slice(*ATTRS))
+        end
+
+        # Cascade: Editable => Read-only. Returns the (cascaded) change or nil.
+        def downgrade_to_read
+          assign_level('read').first&.tap { |change| change.cascaded = true }
+        end
+
+        private
+
+        def level_change(attrs)
+          level = attrs['level'].to_s
+          return [] unless FieldLevel.valid?(level, muting: @muting)
+
+          assign_level(Values.effective_level(level, @resource, muting: @muting), attrs['mask_strategy'])
+        end
+
+        def assign_level(level, strategy = nil)
+          from = [FieldLevel.level_of(@field, muting: @muting), @field.mask_strategy]
+          write_level(level, strategy)
+          return [] if from.first == level && !@field.mask_strategy_changed?
+
+          [change('level', [level, @field.mask_strategy], kind: :field_level, from: from)]
+        end
+
+        def write_level(level, strategy)
+          @field.assign_attributes(FieldLevel.flags_for(level, muting: @muting))
+          @field.mask_strategy = strategy if strategy.present? && MASK_LEVELS.include?(level)
+        end
+
+        def attr_changes(attrs)
+          attrs.filter_map do |attr, value|
+            change(attr, CASTS.fetch(attr, TEXT_CAST).call(value, @field), kind: :field_attr).assign
+          end
+        end
+
+        def change(attribute, to, **attrs)
+          ChangeSet::Change.new(record: @field, resource: @resource, attribute: attribute, to: to, **attrs)
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/change_set_parts/field_levels.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module ChangeSetParts
+      # Existing fields: explicit edits and bulk level selections (see
+      # FieldEdit), plus the Edit-off cascade to Read-only.
+      class FieldLevels < Base
+        def call
+          requested = requested_field_attrs
+          changes = requested.flat_map { |id, attrs| changes_for_field(field_index[id], attrs) }
+          changes + cascaded_field_changes(requested.keys)
+        end
+
+        private
+
+        def field_index
+          @field_index ||= resources.values.flat_map(&:resource_fields).index_by { |field| field.id.to_s }
+        end
+
+        # Merges explicit field params with bulk selections.
+        def requested_field_attrs
+          out = explicit_field_attrs
+          level = bulk['level'].to_s
+          return out unless valid_level?(level)
+
+          bulk_fields.each { |field| (out[field.id.to_s] ||= {})['level'] = level }
+          out
+        end
+
+        def explicit_field_attrs
+          section('fields').select { |id, attrs| field_index.key?(id.to_s) && attrs.is_a?(Hash) }.transform_keys(&:to_s)
+        end
+
+        def bulk_fields
+          resource = resources[bulk['resource_id'].to_s]
+          return [] unless resource
+
+          fields = Array(bulk['keys']).filter_map { |key| resource.resource_fields.find { |field| field.name == key.to_s } }
+          fields.reject { |field| field.is_editable == false }
+        end
+
+        def changes_for_field(field, attrs)
+          return [] if field.nil? || locked?(field) || locked?(resource_of(field))
+
+          field_edit(field).changes(attrs)
+        end
+
+        # Editable fields on resources whose Edit (or Read) was just turned off
+        # are downgraded to Read-only so field and resource stay consistent.
+        def cascaded_field_changes(already)
+          return [] if muting?
+
+          resources.values.reject(&:edit_access).flat_map(&:resource_fields).filter_map do |field|
+            field_edit(field).downgrade_to_read if cascadable?(field, already)
+          end
+        end
+
+        # A locked field, or a field of a locked Resource, keeps its level.
+        def cascadable?(field, already)
+          !already.include?(field.id.to_s) && !locked?(field) && !locked?(resource_of(field)) &&
+            FieldLevel.level_of(field, muting: false) == 'edit'
+        end
+
+        def field_edit(field)
+          FieldEdit.new(field, resource_of(field), muting: muting?)
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/change_set_parts/new_actions.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module ChangeSetParts
+      # New actions: controller actions that discovery lists for a resource and
+      # that have no ResourceAction row in this set yet — picked one by one
+      # (`new_actions`), or all at once (`bulk_actions`).
+      #
+      # Only keys the controller catalog lists for the resource are created;
+      # free-text keys go through ResourceActionsController. Nothing is created
+      # while controller_action_discovery is off, in a locked set, in a locked
+      # resource, or for a key that already has a row. A blank is_permitted
+      # means "don't add". In a muting set is_permitted means "block".
+      class NewActions < Base
+        def call
+          return [] unless creatable?
+
+          explicit = hash_section('new_actions').flat_map { |resource_id, keys| explicit_new_actions(resource_id, keys) }
+          explicit + bulk_new_actions
+        end
+
+        private
+
+        delegate :controller_catalog, to: :@context
+
+        def creatable?
+          PermissionForge.configuration.controller_action_discovery? && !locked?(permission_set)
+        end
+
+        # A params section, or {} when the request sent something else there.
+        def hash_section(key)
+          value = section(key)
+          value.is_a?(Hash) ? value : {}
+        end
+
+        # The route table is only read once a row actually asks to be added.
+        def explicit_new_actions(resource_id, keys)
+          resource = unlocked_resource(resource_id)
+          chosen = chosen_keys(keys)
+          return [] unless resource && chosen.any?
+
+          addable = addable_keys(resource)
+          chosen.filter_map { |key, permitted| build_new_action(resource, key, permitted) if addable.include?(key) }
+        end
+
+        # { 'export' => '1' } for the keys with a non-blank choice.
+        def chosen_keys(keys)
+          return {} unless keys.is_a?(Hash)
+
+          keys.each_with_object({}) do |(key, attrs), chosen|
+            permitted = attrs.is_a?(Hash) ? attrs['is_permitted'].to_s.strip : ''
+            chosen[key.to_s] = permitted unless permitted.empty?
+          end
+        end
+
+        # Every discovered key that neither has a row nor an explicit pick.
+        def bulk_new_actions
+          bulk = hash_section('bulk_actions')
+          permitted = bulk['is_permitted'].to_s.strip
+          resource = unlocked_resource(bulk['resource_id']) unless permitted.empty?
+          return [] unless resource
+
+          addable_keys(resource).map { |key| build_new_action(resource, key, permitted) }
+        end
+
+        # Discovered keys for the resource without a row — including the rows
+        # this change set has already built.
+        def addable_keys(resource)
+          discovered_keys(resource.name) - existing_names(resource)
+        end
+
+        # The catalog only lists valid keys; the grep is defence in depth.
+        def discovered_keys(resource_name)
+          controller_catalog.keys_for(resource_name).grep(PermissionForge::ControllerActions::KEY_FORMAT)
+        end
+
+        def existing_names(resource)
+          resource.resource_actions.map(&:name)
+        end
+
+        def build_new_action(resource, key, permitted)
+          action = resource.resource_actions.build(name: key, label: key.humanize, is_active: true,
+                                                   is_permitted: truthy?(permitted))
+          change(kind: :new_action, record: action, attribute: 'is_permitted', from: nil, to: action.is_permitted,
+                 resource: resource)
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/change_set_parts/new_fields.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module ChangeSetParts
+      # New fields: columns without a ResourceField row, picked one by one or
+      # through a bulk selection.
+      class NewFields < Base
+        def call
+          explicit = section('new_fields').flat_map { |resource_id, columns| explicit_new_fields(resource_id, columns) }
+          explicit + bulk_new_fields
+        end
+
+        private
+
+        def explicit_new_fields(resource_id, columns)
+          resource = unlocked_resource(resource_id)
+          return [] unless resource && columns.is_a?(Hash)
+
+          existing = existing_names(resource)
+          columns.filter_map do |column, attrs|
+            name = column.to_s
+            next if existing.include?(name) || !attrs.is_a?(Hash)
+
+            build_new_field(resource, name, attrs['level'].to_s)
+          end
+        end
+
+        def bulk_new_fields
+          level = bulk['level'].to_s
+          resource = unlocked_resource(bulk['resource_id'])
+          return [] unless resource && valid_level?(level)
+
+          bulk_columns(resource).filter_map { |column| build_new_field(resource, column, level) }
+        end
+
+        # Bulk-selected columns that have neither a field nor an explicit pick.
+        def bulk_columns(resource)
+          Array(bulk['keys']).map(&:to_s).uniq - existing_names(resource) - explicit_columns(resource)
+        end
+
+        def existing_names(resource)
+          resource.resource_fields.map(&:name)
+        end
+
+        def explicit_columns(resource)
+          (params.dig('new_fields', resource.id.to_s) || {}).keys.map(&:to_s)
+        end
+
+        def build_new_field(resource, column, level)
+          return nil unless valid_level?(level) && level != 'leave'
+
+          level = Values.effective_level(level, resource, muting: muting?)
+          field = resource.resource_fields.build(name: column, label: column.humanize, is_active: true, is_editable: true)
+          field.assign_attributes(flags_for(level))
+          field.mask_strategy = sensitive.match(column)&.strategy || 'full'
+          change(kind: :new_field, record: field, attribute: 'level', from: nil, to: [level, field.mask_strategy],
+                 resource: resource)
+        end
+      end
+    end
+  end
+end