super_admin 0.2.0

data/app/services/super_admin/resources/association_inspector.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  module Resources
+    # Provides helpers around ActiveRecord associations for SuperAdmin screens.
+    class AssociationInspector
+      class << self
+        def preloadable_names(model_class)
+          model_class.reflect_on_all_associations.filter_map do |association|
+            next unless %i[belongs_to has_one].include?(association.macro)
+            options = association.options || {}
+            next if options[:polymorphic] || options[:through]
+
+            association.name
+          end
+        end
+      end
+
+      def initialize(resource)
+        @resource = resource
+      end
+
+      def has_many_counts(associations)
+        has_many_assocs = associations.select { |assoc| assoc.macro == :has_many }
+        return {} if has_many_assocs.empty?
+
+        # Optimize: use counter_cache when available, batch count for others
+        counts = {}
+        to_query = []
+
+        has_many_assocs.each do |association|
+          counter_method = "#{association.name}_count"
+          if @resource.respond_to?(counter_method)
+            # Use counter_cache column if available (no query)
+            counts[association.name] = @resource.public_send(counter_method)
+          else
+            to_query << association
+          end
+        end
+
+        # Batch count remaining associations to reduce queries
+        if to_query.any?
+          batch_counts = batch_count_associations(to_query)
+          counts.merge!(batch_counts)
+        end
+
+        counts
+      rescue StandardError => error
+        Rails.logger.warn(
+          "[SuperAdmin::Resources::AssociationInspector] Failed to count associations for #{@resource.class}##{@resource.id}: #{error.class} - #{error.message}"
+        )
+        has_many_assocs.each_with_object({}) { |assoc, h| h[assoc.name] = 0 }
+      end
+
+      private
+
+      # Batch count multiple associations in parallel to reduce total queries
+      # Falls back to individual counts if batch counting fails
+      def batch_count_associations(associations)
+        # For small numbers of associations (1-2), individual queries are fine
+        return individual_counts(associations) if associations.size <= 2
+
+        # Try batch counting with concurrent queries
+        results = {}
+        threads = associations.map do |association|
+          Thread.new do
+            begin
+              count = count_for(association)
+              [ association.name, count ]
+            rescue StandardError => error
+              Rails.logger.debug(
+                "[SuperAdmin::AssociationInspector] Failed to count #{association.name}: #{error.message}"
+              )
+              [ association.name, 0 ]
+            end
+          end
+        end
+
+        threads.each do |thread|
+          name, count = thread.value
+          results[name] = count
+        end
+
+        results
+      rescue StandardError
+        # Fallback to individual counts if threading fails
+        individual_counts(associations)
+      end
+
+      def individual_counts(associations)
+        associations.each_with_object({}) do |association, counts|
+          counts[association.name] = count_for(association)
+        rescue StandardError
+          counts[association.name] = 0
+        end
+      end
+
+      def count_for(association)
+        association_proxy = @resource.association(association.name)
+        scope = association_proxy.scope
+
+        # Clean up scope to get a simple count
+        scope = scope.except(:select) if scope.respond_to?(:except)
+        scope = scope.unscope(:order) if scope.respond_to?(:unscope)
+        scope = scope.limit(nil) if scope.respond_to?(:limit)
+        scope = scope.offset(nil) if scope.respond_to?(:offset)
+
+        scope.count
+      end
+    end
+  end
+end

data/app/services/super_admin/resources/collection_presenter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  module Resources
+    # Provides helper methods to work with resource collections (filtering, exports, pagination state).
+    class CollectionPresenter
+      attr_reader :context, :params
+
+      delegate :model_class, :resource_param, to: :context
+
+      def initialize(context:, params:)
+        @context = context
+        @params = params
+      end
+
+      def filter_definitions
+        SuperAdmin::FilterBuilder.definitions_for(model_class)
+      end
+
+      def filter_params
+        @filter_params ||= FilterParams.new(model_class, params[:filters]).to_h
+      end
+
+      def scope
+        @scope ||= begin
+          base_scope = SuperAdmin::ResourceQuery.filtered_scope(
+            model_class,
+            search: params[:search],
+            sort: params[:sort],
+            direction: params[:direction],
+            filters: filter_params
+          )
+
+          # Apply eager loading to avoid N+1 queries
+          includes = SuperAdmin::DashboardResolver.collection_includes_for(model_class)
+          includes.any? ? base_scope.includes(includes) : base_scope
+        end
+      end
+
+      def preserved_params
+        {}.tap do |hash|
+          hash[:search] = params[:search] if params[:search].present?
+          hash[:sort] = params[:sort] if params[:sort].present?
+          hash[:direction] = params[:direction] if params[:direction].present?
+          hash[:filters] = filter_params if filter_params.present?
+        end
+      end
+
+      def queue_export!(user, attributes)
+        SuperAdmin::CsvExportCreator.call(
+          user: user,
+          model_class: model_class,
+          resource: resource_param,
+          search: params[:search],
+          sort: params[:sort],
+          direction: params[:direction],
+          filters: filter_params,
+          attributes: attributes
+        )
+      end
+    end
+  end
+end

data/app/services/super_admin/resources/context.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  module Resources
+    # Wraps information about the requested resource to avoid leaking controller logic.
+    class Context
+      attr_reader :resource_param
+
+      def initialize(resource_param)
+        @resource_param = resource_param.to_s
+      end
+
+      def valid?
+        SuperAdmin::ModelInspector.find_model(resource_param).present?
+      end
+
+      def resource_name
+        resource_param
+      end
+
+      def singular_name
+        resource_name.singularize
+      end
+
+      def plural_name
+        resource_name.pluralize
+      end
+
+      def model_class
+        @model_class ||= begin
+          klass = SuperAdmin::ModelInspector.find_model(resource_param)
+          raise NameError, "Unrecognized resource '#{resource_param}'" unless klass
+
+          klass
+        end
+      end
+
+      def dashboard
+        SuperAdmin::DashboardResolver.dashboard_for(model_class)
+      end
+
+      def displayable_attributes
+        SuperAdmin::DashboardResolver.collection_attributes_for(model_class)
+      end
+
+      def show_attributes
+        SuperAdmin::DashboardResolver.show_attributes_for(model_class)
+      end
+
+      def editable_attributes
+        SuperAdmin::DashboardResolver.form_attributes_for(model_class)
+      end
+
+      def human_model_name(count: 1)
+        model_class.model_name.human(count: count)
+      end
+
+      def param_key
+        model_class.model_name.param_key
+      end
+    end
+  end
+end

data/app/services/super_admin/resources/filter_params.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  module Resources
+    # Sanitizes filter parameters for a resource collection.
+    class FilterParams
+      def initialize(model_class, raw_filters)
+        @model_class = model_class
+        @raw_filters = raw_filters
+      end
+
+      def to_h
+        return {} if @raw_filters.blank?
+
+        parameters = ensure_parameters(@raw_filters)
+        permitted_keys = SuperAdmin::FilterBuilder.permitted_param_keys(@model_class)
+        parameters.permit(*permitted_keys).to_h
+      end
+
+      private
+
+      def ensure_parameters(filters)
+        return filters if filters.is_a?(ActionController::Parameters)
+
+        ActionController::Parameters.new(filters)
+      end
+    end
+  end
+end

data/app/services/super_admin/resources/permitted_attributes.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "set"
+
+module SuperAdmin
+  module Resources
+    # Computes the strong parameters list for a given resource, including nested attributes.
+    class PermittedAttributes
+      attr_reader :model_class
+
+      def initialize(model_class)
+        @model_class = model_class
+      end
+
+      # Make the class callable, returning the list of permitted attribute names
+      def call
+        attribute_names
+      end
+
+      def permit(params)
+        params.require(param_key).permit(*attribute_names)
+      end
+
+      def attribute_names
+        @attribute_names ||= begin
+          dashboard_form_attrs = SuperAdmin::DashboardResolver.form_attributes_for(model_class)
+
+          direct_attributes = SuperAdmin::ResourceConfiguration
+            .editable_attributes(model_class)
+            .reject { |attr| attr.to_s.end_with?("_attributes") }
+            .map(&:to_sym)
+
+          allowed_direct = if dashboard_form_attrs.present?
+            dashboard_form_attrs
+              .reject { |attr| attr.to_s.end_with?("_attributes") }
+              .map(&:to_sym)
+          else
+            []
+          end
+
+          if allowed_direct.present?
+            direct_attributes &= allowed_direct
+          end
+
+          # Filter out sensitive attributes for security (defense-in-depth)
+          direct_attributes = SuperAdmin::SensitiveAttributes.filter(
+            direct_attributes,
+            model_class: model_class,
+            allowlist: allowed_direct
+          )
+
+          direct_attributes + nested_attribute_definitions(dashboard_form_attrs)
+        end
+      end
+
+      private
+
+      def param_key
+        model_class.model_name.param_key
+      end
+
+      def nested_attribute_definitions(dashboard_form_attrs)
+        allowlist = if dashboard_form_attrs.present?
+          dashboard_form_attrs.select { |attr| attr.to_s.end_with?("_attributes") }.map do |attr|
+            attr.to_s.delete_suffix("_attributes").to_sym
+          end.to_set
+        end
+
+        allowlist = nil if allowlist&.empty?
+
+        Array(model_class.nested_attributes_options).filter_map do |association_name, options|
+          if allowlist && !allowlist.include?(association_name.to_sym)
+            next
+          end
+
+          reflection = model_class.reflect_on_association(association_name)
+          next unless reflection
+
+          nested_keys = SuperAdmin::ResourceConfiguration
+            .editable_attributes(reflection.klass)
+            .reject { |attr| attr.to_s.end_with?("_attributes") }
+            .map(&:to_sym)
+
+          # Filter out sensitive attributes from nested attributes too
+          nested_keys = SuperAdmin::SensitiveAttributes.filter(
+            nested_keys,
+            model_class: reflection.klass
+          )
+
+          nested_keys -= [ reflection.foreign_key.to_sym ] if reflection.respond_to?(:foreign_key)
+          nested_keys << :id unless nested_keys.include?(:id)
+
+          # Always permit `_destroy` so nested forms can request deletions, even
+          # when the association does not explicitly enable allow_destroy. Rails
+          # will ignore the flag if the association disallows it, but permitting
+          # the parameter keeps the API consistent across nested resources.
+          nested_keys << :_destroy unless nested_keys.include?(:_destroy)
+
+          { "#{association_name}_attributes".to_sym => nested_keys }
+        end
+      end
+    end
+  end
+end

data/app/services/super_admin/resources/value_normalizer.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module SuperAdmin
+  module Resources
+    # Normalizes permitted attribute values before assignment, applying
+    # lightweight casting for data types that HTML forms cannot express directly.
+    class ValueNormalizer
+      ARRAY_DELIMITER_REGEX = /[,\n]/.freeze
+
+      def initialize(model_class, params)
+        @model_class = model_class
+        @params = params
+      end
+
+      # Returns a normalized copy of the permitted parameters.
+      def normalize
+        return params unless params.is_a?(ActionController::Parameters) && params.permitted?
+
+        normalize_params_for(model_class, params)
+        params
+      end
+
+      private
+
+      attr_reader :model_class, :params
+
+      def normalize_params_for(current_model, current_params)
+        current_params.keys.each do |key|
+          string_key = key.to_s
+          value = current_params[key]
+
+          if nested_attribute?(string_key)
+            normalize_nested_attribute(current_model, string_key, value)
+            next
+          end
+
+          column = current_model.columns_hash[string_key]
+          next unless column
+
+          if array_column?(column)
+            current_params[key] = normalize_array_value(column, value)
+          end
+        end
+      end
+
+      def nested_attribute?(key)
+        key.end_with?("_attributes")
+      end
+
+      def normalize_nested_attribute(current_model, key, value)
+        association_name = key.delete_suffix("_attributes")
+        reflection = current_model.reflect_on_association(association_name)
+        return unless reflection
+
+        case value
+        when ActionController::Parameters
+          normalize_params_for(reflection.klass, value)
+        when Array
+          value.each do |entry|
+            next unless entry.is_a?(ActionController::Parameters)
+
+            normalize_params_for(reflection.klass, entry)
+          end
+        end
+      end
+
+      def array_column?(column)
+        column.respond_to?(:array) && column.array
+      end
+
+      def normalize_array_value(column, value)
+        array = case value
+        when String
+          parse_array_string(value)
+        when Array
+          value.compact
+        else
+          Array(value)
+        end
+
+        cast_array_elements(array, column)
+      end
+
+      def parse_array_string(value)
+        value.to_s.split(ARRAY_DELIMITER_REGEX).map(&:strip).reject(&:blank?)
+      end
+
+      def cast_array_elements(array, column)
+        array.filter_map do |element|
+          next if element.blank?
+
+          cast_element(element, column)
+        end
+      end
+
+      def cast_element(element, column)
+        return element unless element.is_a?(String)
+
+        stripped = element.strip
+        return nil if stripped.blank?
+
+        case column.type
+        when :integer, :bigint
+          Integer(stripped, exception: false) || stripped
+        when :float
+          Float(stripped, exception: false) || stripped
+        when :decimal
+          BigDecimal(stripped)
+        when :boolean
+          ActiveModel::Type::Boolean.new.cast(stripped) || stripped
+        else
+          stripped
+        end
+      rescue ArgumentError, TypeError
+        stripped
+      end
+    end
+  end
+end

data/app/services/super_admin/sensitive_attributes.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  module SensitiveAttributes
+    DEFAULT_SENSITIVE_PATTERNS = %w[
+      password
+      password_digest
+      password_confirmation
+      encrypted_password
+      reset_password_token
+      reset_password_sent_at
+      remember_token
+      remember_created_at
+      authentication_token
+      access_token
+      refresh_token
+      api_key
+      api_secret
+  token
+      secret
+      secret_key
+      secret_token
+      private_key
+      otp_secret
+      otp_secret_key
+      encrypted_otp_secret
+      encrypted_otp_secret_iv
+      encrypted_otp_secret_salt
+      confirmation_token
+      confirmed_at
+      confirmation_sent_at
+      unconfirmed_email
+      unlock_token
+      locked_at
+      failed_attempts
+      encrypted_
+      crypted_
+      cipher_
+    ].freeze
+
+    DEFAULT_ROLE_PATTERNS = %w[
+      admin
+      superadmin
+      super_admin
+      role
+      roles
+      permission
+      permissions
+      can_
+      is_admin
+      is_superadmin
+    ].freeze
+
+    DEFAULT_SYSTEM_PATTERNS = %w[
+      created_at
+      updated_at
+      deleted_at
+      discarded_at
+      lock_version
+    ].freeze
+
+    class << self
+      def default_patterns
+        @default_patterns ||= (
+          DEFAULT_SENSITIVE_PATTERNS +
+          DEFAULT_ROLE_PATTERNS +
+          DEFAULT_SYSTEM_PATTERNS
+        ).map { |pattern| pattern.to_s.downcase }.freeze
+      end
+
+      def configured_patterns
+        @configured_patterns ||= begin
+          custom = Array(SuperAdmin.configuration.additional_sensitive_attributes)
+                    .map { |pattern| pattern.to_s.downcase }
+
+          (default_patterns + custom).uniq.freeze
+        end
+      end
+
+      def sensitive?(attribute_name)
+        attr_str = attribute_name.to_s.downcase
+
+        configured_patterns.any? do |pattern|
+          if pattern.end_with?("_")
+            attr_str.start_with?(pattern)
+          else
+            attr_str == pattern ||
+              attr_str.start_with?("#{pattern}_") ||
+              attr_str.end_with?("_#{pattern}") ||
+              attr_str.include?("_#{pattern}_")
+          end
+        end
+      end
+
+      def filter(attributes, model_class: nil, allowlist: [])
+        case attributes
+        when Hash
+          filter_hash(attributes)
+        when Array
+          filter_attribute_array(attributes, model_class: model_class, allowlist: allowlist)
+        else
+          filter_attribute_array(Array(attributes), model_class: model_class, allowlist: allowlist)
+        end
+      end
+
+      def reset!
+        @default_patterns = nil
+        @configured_patterns = nil
+      end
+
+      private
+
+      def filter_hash(payload)
+        payload.each_with_object({}) do |(key, value), result|
+          result_key = preserve_key_type(key)
+
+          result[result_key] = case value
+          when Hash
+                                 filter_hash(value)
+          when Array
+                                 value.map { |entry| entry.is_a?(Hash) ? filter_hash(entry) : filtered_value(result_key, entry) }
+          else
+                                 filtered_value(result_key, value)
+          end
+        end
+      end
+
+      def filter_attribute_array(attributes, model_class:, allowlist: [])
+        allowed = Array(allowlist).map { |attr| to_symbol(attr) }.compact
+
+        attributes.each_with_object([]) do |attr, result|
+          case attr
+          when Hash
+            filtered_hash = attr.each_with_object({}) do |(key, value), memo|
+              memo[to_symbol(key)] = filter_attribute_array(Array(value), model_class: model_class, allowlist: [])
+            end
+            result << filtered_hash
+          else
+            attr_sym = to_symbol(attr)
+            next if attr_sym.nil?
+
+            if allowed.include?(attr_sym) || !sensitive?(attr_sym)
+              result << attr_sym
+            elsif model_class
+              Rails.logger.debug(
+                "[SuperAdmin::SensitiveAttributes] Filtered sensitive attribute '#{attr_sym}' from #{model_class.name} permitted parameters"
+              )
+            end
+          end
+        end
+      end
+
+      def filtered_value(key, value)
+        sensitive?(key) ? "[FILTERED]" : value
+      end
+
+      def preserve_key_type(key)
+        key.is_a?(String) ? key : to_symbol(key)
+      end
+
+      def to_symbol(key)
+        key.to_sym if key.respond_to?(:to_sym)
+      end
+    end
+  end
+end