permission_forge 0.14.1

data/lib/permission_forge/admin/people_candidates.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Uniform filter / search / paging over the people list, whether
+    # config.user_list returns an ActiveRecord relation (filtered in SQL) or an
+    # array (filtered in Ruby). Each operation returns a new candidates object.
+    module PeopleCandidates
+      def self.wrap(list, configuration:)
+        list.respond_to?(:where) ? Relation.new(list) : List.new(list, configuration)
+      end
+
+      # SQL-backed: searches whichever of the usual name/email columns exist.
+      class Relation
+        # Common person columns; only those the user table has are searched.
+        SEARCH_COLUMNS = %w[name email full_name display_name first_name last_name firstname lastname
+                            username login].freeze
+        # A query of digits also matches the id — up to a bigint's length.
+        NUMERIC = /\A\d{1,18}\z/
+
+        def initialize(relation)
+          @relation = relation
+        end
+
+        def only(ids)
+          Relation.new(@relation.where(id: ids))
+        end
+
+        def excluding(ids)
+          Relation.new(@relation.where.not(id: ids))
+        end
+
+        def search(query)
+          columns = SEARCH_COLUMNS & @relation.klass.column_names
+          id = query.to_i if query.match?(NUMERIC)
+          return Relation.new(@relation.none) if columns.empty? && id.nil?
+
+          Relation.new(@relation.where(word_conditions(columns, query.downcase, id)))
+        end
+
+        def count
+          @relation.except(:order, :limit, :offset).count
+        end
+
+        def take(offset, limit)
+          @relation.offset(offset).limit(limit).to_a
+        end
+
+        private
+
+        # Every word must match some column, so "ana kras" finds Ana Krasniqi
+        # whether the name lives in one column or in first/last name columns.
+        # A numeric query also matches the id.
+        def word_conditions(columns, needle, id)
+          words = needle.split
+          matched = words.map { |word| any_column(columns, word) }.compact.reduce(:and)
+          return table[:id].eq(id) if matched.nil?
+
+          id ? matched.or(table[:id].eq(id)) : matched
+        end
+
+        def any_column(columns, word)
+          like = "%#{ActiveRecord::Base.sanitize_sql_like(word)}%"
+          columns.map { |column| table[column].lower.matches(like) }.reduce(:or)
+        end
+
+        def table
+          @relation.klass.arel_table
+        end
+      end
+
+      # Array-backed (custom resolvers): searches the person's display label.
+      class List
+        def initialize(people, configuration)
+          @people = people
+          @configuration = configuration
+        end
+
+        def only(ids)
+          List.new(@people.select { |u| ids.include?(u.id) }, @configuration)
+        end
+
+        def excluding(ids)
+          List.new(@people.reject { |u| ids.include?(u.id) }, @configuration)
+        end
+
+        def search(query)
+          needle = query.downcase
+          List.new(@people.select { |u| label_text(u).include?(needle) }, @configuration)
+        end
+
+        def count
+          @people.size
+        end
+
+        def take(offset, limit)
+          Array(@people)[offset, limit] || []
+        end
+
+        private
+
+        def label_text(user)
+          PersonLabel.new(user, configuration: @configuration).search_text
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/people_directory.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Searches and filters the people shown on the People page and in pickers.
+    # The candidate list comes from config.user_list_resolver (or
+    # user_model.order(:id)); search runs in SQL on whichever of the usual
+    # name/email columns exist, or in Ruby for array-returning resolvers
+    # (see PeopleCandidates).
+    class PeopleDirectory
+      FILTERS = %w[all ending expired muting no_access].freeze
+      ENDING_WINDOW_DAYS = 7
+      DEFAULT_PER_PAGE = 25
+      # Beyond this the offset overflows the database's integer; the page is
+      # empty long before.
+      MAX_PAGE = (2**31) - 1
+      # Filters that keep everyone *except* the matching people.
+      EXCLUDING_FILTERS = %w[no_access].freeze
+
+      # Assignments whose people a filter keeps ('no_access' keeps everyone else).
+      FILTER_ASSIGNMENTS = {
+        'ending' => lambda {
+          PermissionForge::PermissionSetUser.where(expires_at: Time.current..ENDING_WINDOW_DAYS.days.from_now.end_of_day)
+        },
+        'expired' => -> { PermissionForge::PermissionSetUser.expired },
+        'muting' => lambda {
+          PermissionForge::PermissionSetUser.active_assignments.where(permission_set_id: PermissionForge::PermissionSet.muting.select(:id))
+        },
+        'no_access' => lambda {
+          PermissionForge::PermissionSetUser.active_assignments.where(permission_set_id: PermissionForge::PermissionSet.active.select(:id))
+        }
+      }.freeze
+
+      Page = Struct.new(:people, :total, :page, :per_page, keyword_init: true) do
+        def more? = total > page * per_page
+        def shown = [total, page * per_page].min
+      end
+
+      def initialize(configuration: PermissionForge.configuration)
+        @configuration = configuration
+      end
+
+      # Typed or pasted text, as it is searched for people: without NUL bytes
+      # (the search builds quoted literals, and a NUL would cut the SQL
+      # statement short) and without surrounding white space. The one input
+      # boundary for people search and the bulk matcher.
+      #
+      # @return [String]
+      def self.search_text(text)
+        text.to_s.delete("\0").strip
+      end
+
+      # Paging options: page: (1-based, default 1), per_page: (default 25).
+      # @return [Page]
+      def search(query: nil, filter: 'all', **paging)
+        filter = 'all' unless FILTERS.include?(filter.to_s)
+        candidates = apply_query(apply_filter(base_candidates, filter.to_s), query)
+        paginate(candidates, paging[:page].to_s.to_i.clamp(1, MAX_PAGE), paging.fetch(:per_page, DEFAULT_PER_PAGE))
+      end
+
+      # Counts for the filter chips (respecting the search query).
+      def counts(query: nil)
+        base = apply_query(base_candidates, query)
+        FILTERS.index_with { |filter| apply_filter(base, filter).count }
+      end
+
+      # People matching a query, capped (for the person picker).
+      def pick(query:, limit: nil)
+        limit ||= @configuration.user_list_limit || 500
+        candidates = apply_query(base_candidates, query)
+        total = candidates.count
+        Page.new(people: candidates.take(0, limit), total: total, page: 1, per_page: limit)
+      end
+
+      # The person `id` names, looked up within config.user_list
+      # (user_list_resolver): the one lookup of a person by id for the admin
+      # and the API. Someone the resolver leaves out (another tenant's user,
+      # an account the host keeps out of the admin) is nobody here: nil,
+      # which callers answer with a 404 / "not found".
+      #
+      # @param id [String, Integer] anything else (a Hash, an Array) names nobody
+      # @return [Object, nil] the user
+      def find(id)
+        find_all([id]).first
+      end
+
+      # The people `ids` name within config.user_list; ids that name nobody
+      # there (or are not keys at all) are dropped.
+      #
+      # @param ids [Array, String, Integer]
+      # @return [Array] users
+      def find_all(ids)
+        ids = Ids.cast(ids, configuration: @configuration)
+        ids.empty? ? [] : base_candidates.only(ids).take(0, ids.size)
+      end
+
+      # Request values cast to the user model's primary-key type. Only a
+      # String or an Integer can name a person; for an integer key only
+      # digits do (the database would read '1abc' as 1), and never past a
+      # bigint. A NUL byte names nobody.
+      module Ids
+        INTEGER_KEY = /\A\d{1,19}\z/
+        MAX_INTEGER_KEY = (2**63) - 1
+
+        # @return [Array] distinct cast ids, in order
+        def self.cast(ids, configuration: PermissionForge.configuration)
+          model = configuration.user_model
+          type = model.type_for_attribute(model.primary_key)
+          (ids.is_a?(Array) ? ids : [ids]).filter_map { |id| cast_one(id, type) }.uniq
+        end
+
+        def self.cast_one(id, type)
+          return nil unless id.is_a?(String) || id.is_a?(Integer)
+
+          text = id.to_s.strip
+          return nil if text.empty? || text.include?("\0")
+          return nil if type.type == :integer && !integer_key?(text)
+
+          type.cast(text)
+        end
+
+        def self.integer_key?(text)
+          text.match?(INTEGER_KEY) && text.to_i <= MAX_INTEGER_KEY
+        end
+        private_class_method :cast_one, :integer_key?
+      end
+
+      private
+
+      # Memoized: an array-returning resolver is evaluated once per directory
+      # (the bulk matcher asks once per pasted line).
+      def base_candidates
+        @base_candidates ||= PeopleCandidates.wrap(@configuration.user_list, configuration: @configuration)
+      end
+
+      def apply_filter(candidates, filter)
+        ids = filter_ids(filter)
+        return candidates if ids.nil?
+
+        candidates.public_send(EXCLUDING_FILTERS.include?(filter) ? :excluding : :only, ids)
+      end
+
+      def filter_ids(filter)
+        FILTER_ASSIGNMENTS[filter]&.call&.select(:user_id)
+      end
+
+      def apply_query(candidates, query)
+        query = self.class.search_text(query)
+        query.empty? ? candidates : candidates.search(query)
+      end
+
+      def paginate(candidates, page, per_page)
+        Page.new(people: candidates.take((page - 1) * per_page, per_page), total: candidates.count, page: page,
+                 per_page: per_page)
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/permission_set_factory.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Creates Permission Sets from the admin UI: fresh, started from another
+    # set, or duplicated. Copies are deep (resources, fields, actions, rules,
+    # conditions) — never assignments — with every copied record unlocked.
+    module PermissionSetFactory
+      # @param attrs [Hash] name:, is_muting:, permission_set_group:
+      # @param source [PermissionSet, nil] set to start from
+      def self.create(attrs, source: nil)
+        return clone_unlocked(source, attrs.merge(is_active: true)) if source
+
+        PermissionForge::PermissionSet.create!(attrs.merge(is_active: true, is_editable: true))
+      end
+
+      # An editable copy. A source in a locked Permission Set Group is copied
+      # outside it: the copy would change the locked group's list of sets.
+      def self.duplicate(source, name:)
+        attrs = { name: name, is_editable: true }
+        attrs[:permission_set_group] = nil if EditableLock.locked?(source.permission_set_group)
+        clone_unlocked(source, attrs)
+      end
+
+      # Case-insensitive.
+      def self.name_taken?(name)
+        PermissionForge::PermissionSet.where('LOWER(name) = ?', name.downcase).exists?
+      end
+
+      # `base`, else "`base` 2", "`base` 3", ... — the first free name.
+      def self.unique_name(base)
+        candidate = base
+        suffix = 2
+        while name_taken?(candidate)
+          candidate = "#{base} #{suffix}"
+          suffix += 1
+        end
+        candidate
+      end
+
+      # Every copied row is created unlocked, so its create event holds the
+      # state it has (no second, unaudited write).
+      def self.clone_unlocked(source, attrs)
+        PermissionForge::Services::PermissionSetCloner.call(permission_set: source, attrs: attrs.merge(is_editable: true), unlock: true)
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/person_label.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Display name / email / initials for a host-app user in the admin UI.
+    #
+    # Honors config.user_label_formatter for the name. Otherwise tries :name,
+    # :full_name, :display_name, then composes first_name/last_name (or firstname/lastname). Attribute
+    # reads go raw-column-first (read_attribute_before_type_cast) so
+    # MaskedAttributes on the User model never garbles admin lists; virtual
+    # attributes and blank columns fall back to the public reader.
+    class PersonLabel
+      NAME_METHODS = %i[name full_name display_name].freeze
+
+      def initialize(user, configuration: PermissionForge.configuration)
+        @user = user
+        @configuration = configuration
+      end
+
+      def name
+        @name ||= formatted_name || default_name || email || fallback
+      end
+
+      def email
+        @email ||= raw_value(:email).to_s.strip.presence
+      end
+
+      # Email shown under the name — omitted when the name already is the email.
+      def secondary
+        email unless email == name
+      end
+
+      def initials
+        initial_letters(name.to_s.scan(/[[:alnum:]]+/)).join.upcase.presence || '?'
+      end
+
+      # Lower-cased "name email" for in-memory search.
+      def search_text
+        "#{name} #{email}".downcase
+      end
+
+      def first_name
+        name.to_s.split(/\s+/).first.presence || name
+      end
+
+      private
+
+      # First letters of the first and last word, or the first two letters of a single word.
+      def initial_letters(words)
+        words.size > 1 ? [words.first[0], words.last[0]] : [words.first.to_s[0, 2]]
+      end
+
+      def formatted_name
+        formatter = @configuration.user_label_formatter
+        return nil unless formatter
+
+        formatter.call(@user).to_s.strip.presence
+      end
+
+      def default_name
+        NAME_METHODS.each do |method|
+          value = raw_value(method).to_s.strip
+          return value unless value.empty?
+        end
+        composed(:first_name, :last_name) || composed(:firstname, :lastname)
+      end
+
+      def composed(first, last)
+        [raw_value(first), raw_value(last)].compact.map { |part| part.to_s.strip }.reject(&:empty?).join(' ').presence
+      end
+
+      def fallback
+        I18n.t('permission_forge.shared.user_fallback', id: @user.id)
+      end
+
+      def raw_value(attr)
+        attr_name = attr.to_s
+        if readable_column?(attr_name)
+          value = @user.read_attribute_before_type_cast(attr_name)
+          return value if value.to_s.strip.present?
+        end
+        @user.try(attr)
+      end
+
+      # True when attr_name is a loaded column on an AR-like user (guards
+      # partial SELECTs from a custom user_list_resolver).
+      def readable_column?(attr_name)
+        klass = @user.class
+        klass.respond_to?(:column_names) && klass.column_names.include?(attr_name) &&
+          @user.respond_to?(:read_attribute_before_type_cast) &&
+          (!@user.respond_to?(:has_attribute?) || @user.has_attribute?(attr_name))
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/record_id.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # The id of a PermissionForge record, from a request value: an Integer, or
+    # nil for anything that is not one — blank, a Hash, an Array, text, or more
+    # digits than a bigint holds (the database would raise, or read '1abc' as 1).
+    module RecordId
+      FORMAT = /\A\d{1,18}\z/
+
+      # @param value [Object]
+      # @return [Integer, nil]
+      def self.cast(value)
+        text = value.to_s.strip if value.is_a?(String) || value.is_a?(Integer)
+        text.to_i if text&.match?(FORMAT)
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/rule_builder.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # What the rule builder page (permission_set_rules/_builder) decides beyond
+    # the RuleForm's own state: which notes show, which option is selected in
+    # each select, and how the "how to combine" choices read. The template only
+    # draws it.
+    #
+    # @example
+    #   builder = RuleBuilder.new(form: form, resource: resource, model_errors: [])
+    #   builder.ignored_warning?       # => false
+    #   builder.join_choices.map(&:join) # => ['auto', 'joins', 'left_joins']
+    class RuleBuilder
+      # join: the value; checked: the stored choice; auto: the one that is
+      # automatic (its title is named in the "auto" description).
+      JoinChoice = Struct.new(:join, :checked, :auto, keyword_init: true) do
+        def auto? = join == 'auto'
+      end
+
+      attr_reader :form, :resource, :model_errors
+
+      def initialize(form:, resource:, model_errors: [], configuration: PermissionForge.configuration)
+        @form = form
+        @resource = resource
+        @model_errors = Array(model_errors)
+        @configuration = configuration
+      end
+
+      def errors = form.errors
+      def error_codes = errors.values
+
+      def steps = form.path_steps
+      def target = form.target_model
+
+      # A Resource that sees everything makes every rule moot.
+      def ignored_warning? = resource.view_all ? true : false
+
+      # The "follow a relationship" select: only while the target has any.
+      def follow_options = target ? target.associations : []
+      def follow? = follow_options.any?
+
+      def model_missing? = target.nil?
+
+      # Open the advanced panel when the join is not the automatic one.
+      def advanced_open? = form.join != 'auto'
+
+      def join_choices
+        RuleForm::JOINS.map { |join| JoinChoice.new(join: join, checked: form.join == join, auto: form.auto_join) }
+      end
+
+      def scoping_on? = @configuration.auto_query_scoping.to_s == 'filter_only'
+
+      def field_selected?(column) = column.name == form.field_name
+      def operator_selected?(operator) = operator == form.operator
+    end
+  end
+end

data/lib/permission_forge/admin/rule_form.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Form object behind the rule builder: turns the sentence-style inputs
+    # (relationship path, field, operator, adaptive value, "the current user",
+    # include empty, join choice) into PermissionSetRule attributes, and lists
+    # the choices offered at each step from model reflection.
+    class RuleForm
+      ARITY = {
+        'equal' => :one, 'not_equal' => :one, 'less_than' => :one, 'greater_than' => :one,
+        'less_than_or_equal' => :one, 'greater_than_or_equal' => :one, 'in' => :list, 'not_in' => :list,
+        'contains' => :one, 'not_contains' => :one, 'starts_with' => :one, 'ends_with' => :one,
+        'between' => :range, 'is_null' => :none, 'is_not_null' => :none
+      }.freeze
+      USER_OPERATORS = %w[equal not_equal in not_in is_null is_not_null].freeze
+      NULLABLE = %w[equal not_equal in not_in].freeze
+      JOINS = %w[auto joins left_joins].freeze
+      CURRENT_USER = 'current_user'
+      VALUE_ERRORS = { one: :value, list: :list, range: :range }.freeze
+
+      attr_reader :name, :path, :field_name, :operator, :value, :values, :value_from, :value_to,
+                  :current_user, :include_nulls, :failure_message, :join, :is_active, :errors
+
+      def initialize(resource:, params: nil, rule: nil, catalog: ModelCatalog.new)
+        @resource = resource
+        @catalog = catalog
+        @errors = {}
+        if params
+          assign_inputs(RuleFormInput.from_params(normalize(params)))
+          @operator = 'equal' unless operators.include?(@operator)
+        else
+          assign_inputs(RuleFormInput.from_rule(rule))
+        end
+      end
+
+      # --- choices ----------------------------------------------------------------
+
+      def root_model
+        @root_model ||= @catalog.find(@resource.name)
+      end
+
+      # [[ModelInfo, Association selected or nil], ...] for each path step, plus
+      # the model the field is read from.
+      def path_steps
+        model = root_model
+        steps = []
+        @path.each do |assoc_name|
+          break unless model
+
+          assoc = model.association(assoc_name)
+          steps << [model, assoc]
+          model = assoc && @catalog.find(assoc.class_name)
+        end
+        @target_model = model
+        steps
+      end
+
+      def target_model
+        path_steps unless defined?(@target_model)
+        @target_model
+      end
+
+      def field_options
+        target_model ? target_model.columns.reject(&:virtual?) : []
+      end
+
+      def column
+        field_options.find { |option| option.name == @field_name }
+      end
+
+      def operators
+        column&.user_reference? ? USER_OPERATORS : ARITY.keys
+      end
+
+      def arity
+        ARITY.fetch(@operator, :one)
+      end
+
+      def nullable?
+        NULLABLE.include?(@operator)
+      end
+
+      def user_field?
+        column&.user_reference? || false
+      end
+
+      def enum_values
+        column&.enum_values
+      end
+
+      def input_type
+        case column&.type
+        when :integer, :decimal, :float, :bigint then 'number'
+        when :date then 'date'
+        when :datetime, :timestamp then 'datetime-local'
+        else 'text'
+        end
+      end
+
+      def follows_relationship?
+        @path.any?
+      end
+
+      # --- persistence --------------------------------------------------------------
+
+      def valid?
+        @errors = {}
+        @errors[:name] = :name_blank if @name.blank?
+        @errors[:field] = :field if column.nil?
+        validate_value
+        @errors.empty?
+      end
+
+      def attributes
+        {
+          name: @name, field_name: @field_name, operator: @operator, field_value: field_value,
+          field_accessor_path: @path.any? ? @path.join('.') : nil, join_type: join_type,
+          include_nulls: nullable? && @include_nulls, failure_message: @failure_message.presence,
+          is_active: @is_active
+        }
+      end
+
+      def field_value
+        case arity
+        when :none then nil
+        when :list then @values.join(',')
+        when :range then [@value_from, @value_to].join(',')
+        else @current_user ? CURRENT_USER : @value
+        end
+      end
+
+      # Rules without a relationship are filter rules (join_type nil).
+      def join_type
+        return nil if @path.empty?
+        return @join if %w[joins left_joins].include?(@join)
+
+        @include_nulls ? 'left_joins' : 'joins'
+      end
+
+      def auto_join
+        @include_nulls ? 'left_joins' : 'joins'
+      end
+
+      # Unsaved rule for previews.
+      def preview_rule
+        PermissionForge::PermissionSetRule.new(attributes.merge(resource: @resource))
+      end
+
+      private
+
+      def normalize(params)
+        (params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h).deep_stringify_keys
+      end
+
+      # Sets the reader ivars (@name, @path, ...) from RuleFormInput.
+      def assign_inputs(inputs)
+        inputs.each { |key, value| instance_variable_set(:"@#{key}", value) }
+      end
+
+      def validate_value
+        @errors[:value] = VALUE_ERRORS[arity] if value_missing?
+      end
+
+      def value_missing?
+        case arity
+        when :one then !@current_user && @value.blank?
+        when :list then @values.empty?
+        when :range then @value_from.blank? || @value_to.blank?
+        else false
+        end
+      end
+    end
+  end
+end