permission_forge 0.14.1

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module ChangeSetParts
+      # Edits to one resource: label/description, then CRUD/scope flags with
+      # the Read/Edit cascades (skipped for muting sets — inverted semantics).
+      class ResourceEdit
+        FLAGS = %w[read_access create_access edit_access delete_access view_all modify_all is_active].freeze
+        TEXT = %w[label description].freeze
+        READ_DEPENDENT = %w[edit_access delete_access view_all modify_all].freeze
+
+        def initialize(resource, muting:)
+          @resource = resource
+          @muting = muting
+        end
+
+        def changes(attrs)
+          text_changes(attrs.slice(*TEXT)) + flag_changes(attrs.slice(*FLAGS).transform_values { |v| Values.truthy?(v) })
+        end
+
+        private
+
+        def text_changes(texts)
+          texts.filter_map { |attr, value| change(attr, value.to_s.strip.presence, kind: :resource_text).assign }
+        end
+
+        # A flag is "cascaded" when its new value differs from (or was not
+        # part of) the request.
+        def flag_changes(requested)
+          wanted = wanted_flags(requested)
+          FLAGS.filter_map do |flag|
+            to = wanted[flag]
+            change(flag, to, kind: :resource_flag, cascaded: requested.fetch(flag, :absent) != to).assign
+          end
+        end
+
+        def wanted_flags(requested)
+          wanted = FLAGS.to_h { |flag| [flag, requested.fetch(flag) { @resource.public_send(flag) }] }
+          cascade!(wanted) unless @muting
+          wanted
+        end
+
+        def cascade!(flags)
+          READ_DEPENDENT.each { |flag| flags[flag] = false } unless flags['read_access']
+          flags['modify_all'] = false unless flags['edit_access'] && flags['view_all']
+        end
+
+        def change(attribute, to, **attrs)
+          ChangeSet::Change.new(record: @resource, resource: @resource, attribute: attribute, to: to, **attrs)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module ChangeSetParts
+      # Resource label/description and CRUD/scope flags (see ResourceEdit).
+      class ResourceFlags < Base
+        def call
+          section('resources').flat_map do |id, attrs|
+            resource = unlocked_resource(id)
+            next [] unless resource && attrs.is_a?(Hash)
+
+            ResourceEdit.new(resource, muting: muting?).changes(attrs)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module ChangeSetParts
+      # Set header: name, description, active, group.
+      class SetAttrs < Base
+        SET_ATTRS = %w[name description is_active permission_set_group_id].freeze
+        # A group id that is neither blank (no group) nor digits.
+        NOT_A_GROUP = Object.new.freeze
+        TEXT_CAST = ->(value) { value.to_s.strip.presence if value.is_a?(String) || value.is_a?(Numeric) }
+        CASTS = {
+          'is_active' => ->(value) { Values.truthy?(value) },
+          'permission_set_group_id' => lambda { |value|
+            next nil if value.blank?
+
+            RecordId.cast(value) || NOT_A_GROUP
+          }
+        }.freeze
+
+        def call
+          section('set').slice(*SET_ATTRS).filter_map do |attr, value|
+            to = cast(attr, value)
+            next if to.equal?(NOT_A_GROUP)
+            next if attr == 'permission_set_group_id' && locked_group_move?(to)
+
+            assign_change(kind: :set_attr, record: permission_set, attribute: attr, to: to)
+          end
+        end
+
+        private
+
+        # A move into or out of a locked Permission Set Group is skipped
+        # (the controller refuses it first).
+        def locked_group_move?(group_id)
+          EditableLock.locked_group_for_move(from: permission_set.permission_set_group_id, to: group_id).present?
+        end
+
+        def cast(attr, value)
+          CASTS.fetch(attr, TEXT_CAST).call(value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module ChangeSetParts
+      # Stateless value rules shared by the ChangeSet collaborators.
+      module Values
+        def self.truthy?(value)
+          ActiveModel::Type::Boolean.new.cast(value) == true
+        end
+
+        # Edit on a resource without Edit is downgraded to Read (muting sets
+        # have inverted semantics, so Edit is always available there).
+        def self.effective_level(level, resource, muting:)
+          level == 'edit' && !(muting || resource.edit_access) ? 'read' : level
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/column_fields.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Creates ResourceFields for model columns and virtual fields at one level,
+    # applying privacy defaults: sensitive names start Masked when gdpr_defaults
+    # is on, and the muting 'hide_sensitive' level hides only sensitive names.
+    class ColumnFields
+      def initialize(resource, muting:, sensitive: SensitiveColumns.new, configuration: PermissionForge.configuration)
+        @resource = resource
+        @muting = muting
+        @sensitive = sensitive
+        @configuration = configuration
+      end
+
+      # @return [Integer] number of fields created (columns whose level resolves to nil are skipped)
+      def create(columns, level)
+        columns.filter_map { |column| create_field(column, level) }.size
+      end
+
+      private
+
+      def create_field(column, level)
+        match = @sensitive.match(column)
+        column_level = @muting ? muting_level(level, match) : granting_level(level, match)
+        return unless column_level
+
+        attrs = FieldLevel.flags_for(column_level, muting: @muting)
+        @resource.resource_fields.create!(attrs.merge(name: column, label: column.humanize, is_active: true, is_editable: true,
+                                                      mask_strategy: match&.strategy || 'full'))
+      end
+
+      def muting_level(level, match)
+        return 'hide' if level == 'hide_sensitive' && match
+        return nil if %w[hide_sensitive leave].include?(level) || level.blank?
+
+        FieldLevel.valid?(level, muting: true) ? level : nil
+      end
+
+      def granting_level(level, match)
+        return nil unless FieldLevel.valid?(level, muting: false)
+        return 'masked' if match && %w[read edit].include?(level) && @configuration.gdpr_defaults
+
+        level
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/conditions_form.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+module PermissionForge
+  module Admin
+    # Activation conditions form (Conditions tab): turns the posted IP list,
+    # hour window and session flag into PermissionSet attributes, collecting
+    # per-input errors (:ips => [messages], :flag => message).
+    class ConditionsForm
+      FLAG_FORMAT = /\A[\w.:-]{1,100}\z/
+
+      attr_reader :errors
+
+      # @param params [ActionController::Parameters, Hash]
+      def initialize(params)
+        @params = params
+        @errors = {}
+      end
+
+      # Evaluated in order, so errors are keyed :ips before :flag.
+      def attributes
+        @attributes ||= {
+          allowed_ips: ips.join(',').presence,
+          allowed_hours_start: hour(:allowed_hours_start),
+          allowed_hours_end: hour(:allowed_hours_end),
+          requires_session_flag: session_flag
+        }
+      end
+
+      private
+
+      def ips
+        list = @params[:allowed_ips].to_s.split(/[\n,]/).map(&:strip).reject(&:empty?)
+        bad = list.each_with_index.reject { |ip, _| valid_ip?(ip) }
+        @errors[:ips] = bad.map { |ip, i| I18n.t('permission_forge.errors.admin.ip', line: i + 1, ip: ip) } if bad.any?
+        list
+      end
+
+      public
+
+      # Whether the hour window was switched on in the posted form.
+      def hours_enabled?
+        @params[:hours_enabled] == '1'
+      end
+
+      # The hour posted for `key` as an Integer, or nil when it is not a
+      # number (blank, a Hash, an Array) — what the form shows again.
+      def submitted_hour(key)
+        RecordId.cast(@params[key])
+      end
+
+      private
+
+      # nil unless the hour window is enabled.
+      def hour(key)
+        submitted_hour(key) if hours_enabled?
+      end
+
+      def session_flag
+        custom = @params[:requires_session_flag_custom].to_s.strip
+        flag = custom.presence || @params[:requires_session_flag].to_s.strip
+        return flag.presence if flag.blank? || flag.match?(FLAG_FORMAT)
+
+        @errors[:flag] = I18n.t('permission_forge.errors.admin.flag')
+        nil
+      end
+
+      # IPAddr::Error is an ArgumentError.
+      def valid_ip?(value)
+        IPAddr.new(value)
+        true
+      rescue ArgumentError
+        false
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/controller_catalog.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # The host app's controller actions, resolved the way the runtime guard
+    # resolves them (ControllerActions::Mapping) — so the admin lists exactly
+    # what the guard checks.
+    #
+    # Reads the route table once per instance. Routes without a static
+    # controller and action (mounted engines and Rack apps, redirects, dynamic
+    # segments), internal routes, excluded controllers and actions whose name
+    # cannot be a ResourceAction key are skipped. A
+    # controller that fails to load, or a host resolver that raises, drops
+    # that one entry instead of the whole catalog.
+    #
+    # @example
+    #   catalog = ControllerCatalog.new
+    #   catalog.keys_for('Customer')     # => ['archive', 'export']
+    #   catalog.for_resource('Customer') # => [#<struct Entry controller_path="customers", action_name="archive", ...>]
+    #   catalog.any_guarded?             # => true once a listed controller runs the guard
+    class ControllerCatalog
+      # Shown for a route that answers every HTTP verb.
+      ANY_VERB = 'ANY'
+      FORMAT_SUFFIX = '(.:format)'
+
+      # One mapped controller action. `key` is the action key the guard asks
+      # for; `crud` is :read / :create / :edit / :delete when the action means
+      # a CRUD permission, nil for a custom action. `guarded` is whether the
+      # controller runs the guard (ControllerActions.guarded?).
+      Entry = Struct.new(:controller_path, :action_name, :verbs, :paths, :resource, :key, :crud, :guarded,
+                         keyword_init: true) do
+        def crud? = !crud.nil?
+        def guarded? = guarded == true
+
+        # 'customers#export'
+        def endpoint = "#{controller_path}##{action_name}"
+
+        # A custom (non-CRUD) action of the named resource.
+        def custom_for?(resource_name) = resource == resource_name && !crud?
+
+        def sort_key = [resource, key, controller_path, action_name]
+      end
+
+      # Reads one route: its static controller and action, verbs and path.
+      class RoutedAction
+        def initialize(route)
+          @route = route
+        end
+
+        # @return [Array(String, String), nil] [controller_path, action_name];
+        #   nil for an internal route or one without a static controller and
+        #   action (mounted apps, redirects, dynamic segments)
+        def target
+          return nil if @route.respond_to?(:internal) && @route.internal
+
+          parts = @route.defaults.values_at(:controller, :action)
+          parts.map(&:to_s) if parts.all? { |part| part.is_a?(String) || part.is_a?(Symbol) }
+        end
+
+        def verbs
+          verbs = @route.verb.to_s.split('|').reject(&:empty?)
+          verbs.empty? ? [ANY_VERB] : verbs
+        end
+
+        def path
+          @route.path.spec.to_s.delete_suffix(FORMAT_SUFFIX)
+        end
+
+        # Adds this route's verbs and path to its target's entry in `found`.
+        def merge_into(found)
+          merged = (found[target] ||= { verbs: [], paths: [] })
+          merged[:verbs] |= verbs
+          merged[:paths] |= [path]
+        end
+      end
+      private_constant :RoutedAction
+
+      def initialize(configuration: PermissionForge.configuration, routes: Rails.application.routes)
+        @configuration = configuration
+        @routes = routes
+        @controller_classes = {}
+        # controller_path => conventional resource, filled by Mapping: one
+        # lookup per controller instead of one per route.
+        @conventions = {}
+      end
+
+      # @return [Array<Entry>] one per mapped (controller_path, action_name),
+      #   sorted by resource, key, controller and action
+      def entries
+        @entries ||= routed_actions.filter_map { |(path, action), route| build_entry(path, action, route) }
+                                   .sort_by(&:sort_key).freeze
+      end
+
+      # @param resource_name [String, Symbol] e.g. 'Customer'
+      # @return [Array<Entry>] the resource's custom (non-CRUD) entries, sorted by key
+      def for_resource(resource_name)
+        name = resource_name.to_s
+        entries.select { |entry| entry.custom_for?(name) }
+      end
+
+      # @param resource_name [String, Symbol]
+      # @return [Array<String>] unique custom action keys, sorted
+      def keys_for(resource_name)
+        for_resource(resource_name).map(&:key).uniq
+      end
+
+      # @return [Boolean] whether any listed controller runs the guard (see
+      #   ControllerActions.guarded?). When false, permitting or blocking an
+      #   action changes nothing at runtime.
+      def any_guarded?
+        entries.any?(&:guarded)
+      end
+
+      private
+
+      # { ['customers', 'export'] => { verbs: ['GET'], paths: ['/customers/export'] } }
+      def routed_actions
+        @routes.routes.each_with_object({}) do |route, found|
+          routed = RoutedAction.new(route)
+          routed.merge_into(found) if listed?(routed.target)
+        end
+      end
+
+      # Has a static target, and its controller is not excluded from discovery.
+      def listed?(target)
+        target && !@configuration.controller_excluded?(target.first)
+      end
+
+      def build_entry(path, action, route)
+        klass = controller_class(path)
+        target = ControllerActions::Mapping.call(controller_path: path, action_name: action, controller_class: klass,
+                                                 configuration: @configuration, conventions: @conventions)
+        return nil unless target&.manageable?
+
+        Entry.new(controller_path: path, action_name: action, verbs: route[:verbs].sort, paths: route[:paths].sort,
+                  resource: target.resource, key: target.action, crud: target.crud,
+                  guarded: ControllerActions.guarded?(klass))
+      rescue StandardError => e
+        log_skipped("#{path}##{action}", e)
+        nil
+      end
+
+      # The controller's class, or nil when it does not exist or cannot be loaded.
+      def controller_class(path)
+        @controller_classes.fetch(path) { @controller_classes[path] = load_controller(path) }
+      end
+
+      # A controller file that fails to load must not take the catalog down.
+      def load_controller(path)
+        ControllerActions.controller_class_for(path)
+      rescue StandardError, ScriptError => e
+        log_skipped(path, e)
+        nil
+      end
+
+      # Logged once per catalog: a raising resolver would otherwise repeat the
+      # same line for every route.
+      def log_skipped(what, error)
+        return if @logged
+
+        @logged = true
+        Rails.logger&.warn("[PermissionForge] controller catalog skipped #{what}: #{error.class}: #{error.message}")
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/csv.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # @api private
+  module Admin
+    # The one CSV writer of the admin exports (audit trail, audit log, who
+    # holds what): RFC 4180 quoting, CRLF line ends, and a leading apostrophe
+    # on any value a spreadsheet would run as a formula (CSV injection).
+    module Csv
+      # Characters that make Excel, LibreOffice or Google Sheets treat a cell
+      # as a formula (or a DDE call) when they open the file — also after
+      # leading spaces or line breaks, which some of them skip (and which the
+      # audit columns get when a leading tab is cleaned into a space).
+      FORMULA_START = /\A(?:[\t\r]|\s*[=+\-@])/
+      NEEDS_QUOTES = /[",\r\n]/
+      LINE_END = "\r\n"
+
+      module_function
+
+      # @param value [Object] anything; nil is an empty cell
+      # @return [String] the cell as written to the file
+      def cell(value)
+        text = value.to_s
+        text = "'#{text}" if text.match?(FORMULA_START)
+        text.match?(NEEDS_QUOTES) || text != text.strip ? %("#{text.gsub('"', '""')}") : text
+      end
+
+      # @param values [Array] the cells of one row
+      # @return [String] the row, with its line end
+      def line(values)
+        values.map { |value| cell(value) }.join(',') << LINE_END
+      end
+
+      # @param rows [Array<Array>]
+      # @return [String]
+      def document(rows)
+        rows.map { |row| line(row) }.join
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/editable_lock.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # The is_editable lock, walked up what a record belongs to: a record is
+    # locked when it, its Resource, its Permission Set, or (for a membership)
+    # its Permission Set Group has is_editable: false. The admin screens and
+    # the JSON API ask this one walk before every change, so a locked
+    # Permission Set gains and loses no resources, fields, rules, actions or
+    # holders through either surface, and a locked Resource keeps its fields,
+    # rules and actions.
+    #
+    # A set's group is not part of its chain: a locked group freezes its own
+    # name, its members and its list of sets (see .locked_group_for_move),
+    # not the content of the sets in it — as on the group page.
+    #
+    # The lock never blocks narrowing access, and always blocks widening it
+    # (.widening_lock). Which way a change to the holders goes depends on
+    # the set: a granting set gives its holders access, so removing a holder
+    # or ending their assignment sooner narrows, and adding a holder,
+    # restoring a removal, clearing or extending an end date widens. A
+    # Muting Permission Set takes access away from its holders, so each of
+    # those changes goes the other way: adding a holder or keeping them
+    # longer narrows, removing one or ending their assignment sooner widens.
+    #
+    # @example
+    #   EditableLock.locked_record(field)          # => the locked Resource or Permission Set, or nil
+    #   EditableLock.chain(rule)                   # => [rule, resource, permission_set]
+    #   EditableLock.widening_lock(set, :revoke)   # => the set when it is locked and muting, else nil
+    module EditableLock
+      # What each record belongs to, for the lock: the first that is present.
+      PARENTS = {
+        'PermissionForge::Resource' => %i[permission_set],
+        'PermissionForge::ResourceField' => %i[resource],
+        'PermissionForge::ResourceAction' => %i[resource],
+        'PermissionForge::PermissionSetRule' => %i[resource permission_set],
+        'PermissionForge::PermissionSetUser' => %i[permission_set],
+        'PermissionForge::PermissionSetGroupUser' => %i[permission_set_group]
+      }.freeze
+
+      # What a record is listed in: deleting it changes that list, so a
+      # locked container refuses the deletion (a set in a locked group).
+      CONTAINERS = { 'PermissionForge::PermissionSet' => :permission_set_group }.freeze
+
+      module_function
+
+      # @param record [ActiveRecord::Base, nil]
+      # @return [Array<ActiveRecord::Base>] the record, then what it belongs to
+      def chain(record)
+        records = []
+        while record && records.none? { |seen| seen.equal?(record) }
+          records << record
+          record = parent_of(record)
+        end
+        records
+      end
+
+      # @param records [Array<ActiveRecord::Base, nil>]
+      # @return [ActiveRecord::Base, nil] the first locked record in their chains
+      def locked_record(*records)
+        records.flatten.compact.each do |record|
+          locked = chain(record).find { |link| locked?(link) }
+          return locked if locked
+        end
+        nil
+      end
+
+      # @return [Boolean] whether the record itself is flagged is_editable: false
+      def locked?(record)
+        record.respond_to?(:is_editable) && record.is_editable == false
+      end
+
+      # Moving a set from one Permission Set Group to another changes both
+      # groups' lists of sets: refused when either is locked (the group
+      # page's add/remove set refuses the same).
+      #
+      # @param from [Integer, nil] the group id the set has
+      # @param to [Integer, String, nil] the group id it would get
+      # @return [PermissionForge::PermissionSetGroup, nil] the locked group, if any
+      def locked_group_for_move(from:, to:)
+        to = RecordId.cast(to)
+        return nil if to == from
+
+        PermissionForge::PermissionSetGroup.where(id: [from, to].compact).detect { |group| locked?(group) }
+      end
+
+      # The container whose list deleting `record` would change, or nil.
+      #
+      # @return [ActiveRecord::Base, nil] e.g. a set's Permission Set Group
+      def container_of(record)
+        association = CONTAINERS[record.class.name]
+        association && record.public_send(association)
+      end
+
+      # How a change moves a person's holding of a set: +1 they hold it more
+      # (added, or kept longer), -1 less (removed, or ended sooner), 0 not at
+      # all (the same end date again).
+      HOLDING = {
+        grant: ->(**) { 1 },
+        revoke: ->(**) { -1 },
+        change_expiry: ->(from:, to:) { expiry_direction(from: from, to: to) }
+      }.freeze
+
+      # Whether a change to the holders of `permission_set` gives anybody
+      # more access: holding a granting set more, or a Muting Permission Set
+      # less.
+      #
+      # @param permission_set [PermissionForge::PermissionSet]
+      # @param change [Symbol] :grant, :revoke, or :change_expiry (with from:/to:)
+      # @param from [Time, nil] the end date the assignment has (:change_expiry)
+      # @param to [Time, nil] the one it would get (:change_expiry)
+      # @return [Boolean]
+      def widens_access?(permission_set, change, **expiry)
+        direction = HOLDING.fetch(change).call(**expiry)
+        permission_set.is_muting ? direction.negative? : direction.positive?
+      end
+
+      # The locked record that refuses a change to the holders of
+      # `permission_set`: the set itself when the change widens access
+      # (.widens_access?) and the set is locked; nil when the change may go
+      # ahead — a narrowing one always may.
+      #
+      # @return [PermissionForge::PermissionSet, nil]
+      def widening_lock(permission_set, change, **expiry)
+        return nil unless widens_access?(permission_set, change, **expiry)
+
+        locked_record(permission_set)
+      end
+
+      # +1 when the end date moves later or is cleared, -1 when it moves
+      # earlier or is set where there was none, 0 when it stays. Compared at
+      # the column's precision (microseconds): a preset computes its end with
+      # nanoseconds (end_of_day), the stored value has none, and choosing the
+      # same preset again is no change.
+      #
+      # @param from [Time, nil] the end date the assignment has
+      # @param to [Time, nil] the one it would get
+      # @return [Integer]
+      def expiry_direction(from:, to:)
+        return 0 if from.nil? && to.nil?
+        return 1 if to.nil?
+        return -1 if from.nil?
+
+        to.floor(6) <=> from.floor(6)
+      end
+
+      def parent_of(record)
+        PARENTS.fetch(record.class.name, []).each do |association|
+          parent = record.public_send(association)
+          return parent if parent
+        end
+        nil
+      end
+      private_class_method :parent_of
+    end
+  end
+end