super_admin 0.2.0

data/app/models/super_admin/audit_log.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  # Persists a trace of meaningful operations executed through SuperAdmin.
+  class AuditLog < ApplicationRecord
+    self.table_name = "super_admin_audit_logs"
+
+    belongs_to :user,
+               class_name: SuperAdmin.configuration.user_class_constant.name,
+               optional: true
+
+  validates :resource_type, :action, :performed_at, presence: true
+
+    scope :recent, -> { order(performed_at: :desc) }
+
+    before_validation :default_performed_at
+    before_validation :default_payloads
+
+    private
+
+    def default_performed_at
+      return if performed_at.present?
+
+      # When required attributes are missing, keep the field blank so validation errors surface.
+      return if resource_type.blank? || action.blank?
+
+      self.performed_at = Time.current
+    end
+
+    def default_payloads
+      self.changes_snapshot ||= {}
+      self.context ||= {}
+    end
+  end
+end

data/app/models/super_admin/csv_export.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  class CsvExport < ApplicationRecord
+    self.table_name = "super_admin_csv_exports"
+
+    RETENTION_PERIOD = 7.days unless const_defined?(:RETENTION_PERIOD)
+
+    belongs_to :user
+
+    has_one_attached :file
+
+    enum :status, {
+      pending: "pending",
+      processing: "processing",
+      ready: "ready",
+      failed: "failed"
+    }, suffix: true
+
+    validates :resource_name, :model_class_name, :status, :token, presence: true
+    validates :token, uniqueness: true
+
+    before_validation :generate_token, on: :create
+
+    scope :recent_first, -> { order(created_at: :desc) }
+    scope :active, -> { where("expires_at IS NULL OR expires_at > ?", Time.current) }
+
+    def ready_for_download?
+      ready_status? && file.attached?
+    rescue NoMethodError, ActiveRecord::StatementInvalid
+      # Handle cases where ActiveStorage is unavailable or not initialized
+      false
+    end
+
+    def mark_processing!
+      update!(status: :processing, started_at: Time.current)
+    end
+
+    def mark_ready!(records_count:)
+      update!(
+        status: :ready,
+        records_count: records_count,
+        completed_at: Time.current,
+        expires_at: RETENTION_PERIOD.from_now
+      )
+    end
+
+    def mark_failed!(error_message)
+      update!(
+        status: :failed,
+        error_message: error_message.to_s.truncate(500),
+        completed_at: Time.current
+      )
+    end
+
+    private
+
+    # Generate a secure random token. The uniqueness validation and database unique index
+    # will prevent race conditions. With 24 bytes (192 bits), the collision probability
+    # is astronomically low (~1 in 10^57 for billions of records).
+    def generate_token
+      return if token.present?
+
+      self.token = SecureRandom.urlsafe_base64(24)
+    end
+  end
+end

data/app/services/super_admin/auditing.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  # Lightweight helper that records meaningful user actions inside SuperAdmin.
+  module Auditing
+    module_function
+
+    def log!(user:, resource: nil, resource_type: nil, resource_id: nil, action:, changes: nil, context: {})
+      resource_type ||= resource&.class&.name
+      resource_id ||= resource&.try(:id)&.to_s
+
+  return if resource_type.blank? || resource_type == "SuperAdmin::AuditLog"
+
+      SuperAdmin::AuditLog.create(
+        user: compatible_user(user),
+        user_email: safe_user_email(user),
+        resource_type: resource_type,
+        resource_id: resource_id,
+        action: action.to_s,
+  changes_snapshot: prepare_changes(resource, action, changes),
+        context: context.presence || {},
+        performed_at: Time.current
+      )
+    rescue StandardError => error
+      Rails.logger.error(
+        "[SuperAdmin::Auditing] Failed to log action #{action} on #{resource.class.name}: #{error.class} - #{error.message}"
+      )
+      nil
+    end
+
+    def compatible_user(user)
+      return nil unless user
+
+      user_class = SuperAdmin.configuration.user_class_constant
+      return user if user.is_a?(user_class)
+
+      nil
+    rescue SuperAdmin::ConfigurationError
+      nil
+    end
+
+    def safe_user_email(user)
+      user.respond_to?(:email) ? user.email : nil
+    end
+
+    def prepare_changes(resource, action, changes)
+      payload = if changes.present?
+        sanitize_changes(changes)
+      else
+        resource ? default_changes(resource, action) : {}
+      end
+      payload.presence || {}
+    end
+
+    def default_changes(resource, action)
+      case action.to_s
+      when "create"
+        { "after" => resource.attributes }
+      when "update"
+        sanitize_changes(resource.previous_changes)
+      when "destroy"
+        { "before" => resource.attributes }
+      else
+        {}
+      end
+    end
+
+    def sanitize_changes(changes)
+      return {} unless changes
+
+      changes.except("updated_at")
+    end
+  end
+end

data/app/services/super_admin/authorization.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  # Authorization orchestrator. Selects the appropriate adapter and executes it.
+  class Authorization
+    class NotAuthorizedError < StandardError; end
+
+    class << self
+      def call(controller)
+        adapter = build_adapter(controller)
+        return true if adapter.authorized?
+
+        handle_unauthorized(controller, adapter)
+        false
+      end
+
+      def build_adapter(controller)
+        resolve_adapter(controller).new(controller)
+      end
+
+      private
+
+      def resolve_adapter(controller)
+        adapter_option = SuperAdmin.configuration.authorization_adapter
+
+        case adapter_option
+        when nil, :auto
+          auto_detect_adapter(controller)
+        when :default
+          config = SuperAdmin.configuration
+          config.authorize_with.present? ? AuthorizationAdapters::ProcAdapter : AuthorizationAdapters::DefaultAdapter
+        when Symbol, String
+          adapter_from_name(adapter_option)
+        when Class
+          adapter_option
+        else
+          AuthorizationAdapters::DefaultAdapter
+        end
+      rescue NameError => e
+        Rails.logger.error("[SuperAdmin] Authorization adapter resolution failed: #{e.message}")
+        AuthorizationAdapters::DefaultAdapter
+      end
+
+      def auto_detect_adapter(controller)
+        config = SuperAdmin.configuration
+
+        return AuthorizationAdapters::ProcAdapter if config.authorize_with.present?
+
+        if defined?(::Pundit) && controller.respond_to?(:authorize, true)
+          return AuthorizationAdapters::PunditAdapter
+        end
+
+        if defined?(::CanCan::Ability) && controller.respond_to?(:authorize!, true)
+          return AuthorizationAdapters::CancanAdapter
+        end
+
+        AuthorizationAdapters::DefaultAdapter
+      end
+
+      def adapter_from_name(name)
+        key = name.to_sym
+
+        case key
+        when :pundit
+          AuthorizationAdapters::PunditAdapter
+        when :cancan, :cancancan
+          AuthorizationAdapters::CancanAdapter
+        when :proc
+          AuthorizationAdapters::ProcAdapter
+        when :default
+          AuthorizationAdapters::DefaultAdapter
+        else
+          "SuperAdmin::AuthorizationAdapters::#{key.to_s.camelize}Adapter".constantize
+        end
+      end
+
+      def handle_unauthorized(controller, adapter)
+        handler = SuperAdmin.configuration.on_unauthorized
+        error = adapter.build_error
+
+        if handler
+          invoke_handler(controller, error, handler)
+        else
+          adapter.handle_unauthorized!(error)
+        end
+
+        error
+      end
+
+      def invoke_handler(controller, error, handler)
+        case handler
+        when Proc
+          args = case handler.arity
+          when 0
+            []
+          when 1
+            [ error ]
+          else
+            [ controller, error ]
+          end
+
+          controller.instance_exec(*args, &handler)
+        else
+          if controller.respond_to?(handler)
+            controller.public_send(handler, error)
+          else
+            raise ConfigurationError, "Unauthorized handler '#{handler}' is not defined"
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/super_admin/authorization_adapters/base_adapter.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  module AuthorizationAdapters
+    # Base class for authorization adapters. Provides helpers shared by all adapters.
+    class BaseAdapter
+      attr_reader :controller, :last_exception
+
+      def initialize(controller)
+        @controller = controller
+        @last_exception = nil
+      end
+
+      def authorized?(resource = nil)
+        raise NotImplementedError, "Adapters must implement #authorized?"
+      end
+
+      def authorize(resource = nil)
+        @last_exception = nil
+
+        result = invoke_authorized_check(resource)
+        !!result
+      rescue SuperAdmin::Authorization::NotAuthorizedError => error
+        remember_failure(error)
+        false
+      rescue StandardError => error
+        remember_failure(error)
+        raise
+      end
+
+      def authorized_scope(scope)
+        scope
+      end
+
+      # Default unauthorized handler simply raises the provided error. Adapters can override.
+      def handle_unauthorized!(error)
+        raise(error)
+      end
+
+      def build_error
+        SuperAdmin::Authorization::NotAuthorizedError.new(default_error_message)
+      end
+
+      protected
+
+      def remember_failure(exception = nil)
+        @last_exception = exception
+        false
+      end
+
+      def invoke_authorized_check(resource)
+        method = method(:authorized?)
+
+        if method.arity.zero?
+          authorized?
+        else
+          authorized?(resource)
+        end
+      end
+
+      def current_user
+        strategy = SuperAdmin.configuration.current_user_method || :current_user
+
+        case strategy
+        when Proc
+          controller.instance_exec(&strategy)
+        when Symbol, String
+          method_name = strategy.to_sym
+          return unless controller.respond_to?(method_name, true)
+
+          controller.__send__(method_name)
+        else
+          nil
+        end
+      rescue NoMethodError
+        nil
+      end
+
+      def default_error_message
+        I18n.t("super_admin.flash.access_denied", default: "You do not have permission to access this section.")
+      end
+
+      def redirect_with_alert!(message)
+        return unless controller.respond_to?(:redirect_to)
+
+        if controller.respond_to?(:flash)
+          controller.flash[:alert] ||= message
+        end
+
+        target = if controller.respond_to?(:main_app) && controller.main_app.respond_to?(:root_path)
+          controller.main_app.root_path
+        else
+          "/"
+        end
+
+        controller.redirect_to(target)
+      end
+    end
+  end
+end

data/app/services/super_admin/authorization_adapters/default_adapter.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  module AuthorizationAdapters
+    # Fallback authorization strategy relying on configured super admin predicate.
+    class DefaultAdapter < BaseAdapter
+      def authorized?(resource = nil)
+        checker = SuperAdmin.configuration.super_admin_check
+
+        if checker
+          user = current_user || resource
+          raise SuperAdmin::ConfigurationError, "Configure a #current_user method or provide a user resource" unless user
+
+          !!evaluate_custom_check(user, resource)
+        else
+          user = current_user || resource
+
+          if user && (user.respond_to?(:super_admin?) || user.respond_to?(:admin?))
+            !!evaluate_standard_predicate(user)
+          else
+            true
+          end
+        end
+      rescue SuperAdmin::ConfigurationError => error
+        raise error
+      rescue StandardError => error
+        raise SuperAdmin::ConfigurationError, "SuperAdmin authorization failed: #{error.message}"
+      end
+
+      def handle_unauthorized!(error)
+        redirect_with_alert!(error.message)
+      end
+
+      private
+
+      def evaluate_custom_check(user, resource)
+        checker = SuperAdmin.configuration.super_admin_check
+
+        case checker
+        when Proc
+          case checker.arity
+          when 0
+            controller.instance_exec(&checker)
+          when 1
+            controller.instance_exec(user, &checker)
+          when 2
+            controller.instance_exec(controller, user, &checker)
+          else
+            controller.instance_exec(controller, user, resource, &checker)
+          end
+        when Symbol, String
+          predicate = checker.to_sym
+
+          if user.respond_to?(predicate)
+            user.public_send(predicate)
+          elsif controller.respond_to?(predicate, true)
+            controller.__send__(predicate, user)
+          else
+            raise SuperAdmin::ConfigurationError, "SuperAdmin predicate '#{predicate}' is not defined"
+          end
+        else
+          raise SuperAdmin::ConfigurationError, "Unsupported super_admin_check: #{checker.inspect}"
+        end
+      end
+
+      def evaluate_standard_predicate(user)
+        if user.respond_to?(:super_admin?)
+          user.super_admin?
+        elsif user.respond_to?(:admin?)
+          user.admin?
+        else
+          raise SuperAdmin::ConfigurationError, "Define SuperAdmin.super_admin_check or add #super_admin?/#admin? predicate to the user"
+        end
+      end
+    end
+  end
+end

data/app/services/super_admin/authorization_adapters/proc_adapter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  module AuthorizationAdapters
+    # Adapter executing a custom callable configured via SuperAdmin.configure { |c| c.authorize_with = ... }.
+    class ProcAdapter < BaseAdapter
+      def authorized?(resource = nil)
+        callable = SuperAdmin.configuration.authorize_with
+        raise SuperAdmin::ConfigurationError, "authorize_with must be a callable or method name" if callable.blank?
+
+        result = case callable
+        when Proc
+          invoke_proc(callable, resource)
+        when Symbol, String
+          invoke_method(callable.to_sym)
+        else
+          raise SuperAdmin::ConfigurationError, "Unsupported authorize_with value: #{callable.inspect}"
+        end
+
+        !!result
+      rescue SuperAdmin::ConfigurationError
+        raise
+      rescue StandardError => exception
+        remember_failure(exception)
+      end
+
+      def build_error
+        message = if last_exception&.respond_to?(:message) && last_exception.message.present?
+          last_exception.message
+        else
+          default_error_message
+        end
+
+        SuperAdmin::Authorization::NotAuthorizedError.new(message)
+      end
+
+      def handle_unauthorized!(error)
+        redirect_with_alert!(error.message)
+      end
+
+      private
+
+      def invoke_proc(callable, resource)
+        positional_count = callable.parameters.count { |type, _| %i[req opt].include?(type) }
+        rest_parameter = callable.parameters.any? { |type, _| type == :rest }
+
+        base_arguments = [ controller, resource, current_user ]
+        args = base_arguments.first(positional_count)
+        args += base_arguments.drop(positional_count) if rest_parameter
+
+        controller.instance_exec(*args, &callable)
+      end
+
+      def invoke_method(method_name)
+        if controller.respond_to?(method_name, true)
+          controller.__send__(method_name)
+        elsif current_user&.respond_to?(method_name)
+          current_user.public_send(method_name)
+        else
+          raise SuperAdmin::ConfigurationError, "authorize_with method '#{method_name}' is not defined"
+        end
+      end
+    end
+  end
+end

data/app/services/super_admin/authorization_adapters/pundit_adapter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  module AuthorizationAdapters
+    # Adapter delegating authorization to Pundit.
+    class PunditAdapter < BaseAdapter
+      def authorized?(resource = nil)
+        ensure_pundit_available!
+        subject = resource || :super_admin
+        controller.__send__(:authorize, subject, :access?)
+        true
+      rescue LoadError => exception
+        raise SuperAdmin::ConfigurationError, missing_policy_message(exception)
+      rescue StandardError => exception
+        if pundit_not_authorized?(exception)
+          return remember_failure(exception)
+        end
+
+        if policy_missing?(exception)
+          raise SuperAdmin::ConfigurationError, missing_policy_message(exception)
+        end
+
+        raise
+      end
+
+      def authorized_scope(scope)
+        ensure_pundit_available!
+        return scope unless controller.respond_to?(:policy_scope)
+
+        controller.policy_scope(scope)
+      rescue LoadError => exception
+        raise SuperAdmin::ConfigurationError, missing_policy_message(exception)
+      rescue StandardError => exception
+        if policy_missing?(exception)
+          raise SuperAdmin::ConfigurationError, missing_policy_message(exception)
+        end
+
+        raise
+      end
+
+      def build_error
+        error = SuperAdmin::Authorization::NotAuthorizedError.new(default_error_message)
+        attach_cause(error)
+        error
+      end
+
+      def handle_unauthorized!(error)
+        redirect_with_alert!(error.message)
+      end
+
+      private
+
+      def ensure_pundit_available!
+        return if defined?(::Pundit)
+        return if controller.respond_to?(:authorize)
+
+        raise SuperAdmin::ConfigurationError, "Pundit adapter selected but Pundit is not loaded"
+      end
+
+      def pundit_not_authorized?(exception)
+        defined?(::Pundit::NotAuthorizedError) && exception.is_a?(::Pundit::NotAuthorizedError)
+      end
+
+      def attach_cause(error)
+        return unless last_exception
+
+        cause = last_exception
+        error.define_singleton_method(:cause) { cause }
+        error.set_backtrace(cause.backtrace) if cause.backtrace
+      end
+
+      def missing_policy_message(exception)
+        "SuperAdminPolicy with #access? must exist when using the Pundit adapter. #{exception.message}"
+      end
+
+      def policy_missing?(exception)
+        defined?(::Pundit::NotDefinedError) && exception.is_a?(::Pundit::NotDefinedError)
+      end
+    end
+  end
+end

data/app/services/super_admin/csv_export_creator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  # Encapsulates CSV export creation logic and enqueues it in Solid Queue.
+  class CsvExportCreator
+    DEFAULT_RETENTION = 7.days
+
+    def self.call(**kwargs)
+      new(**kwargs).call
+    end
+
+    def initialize(user:, model_class:, resource_name: nil, resource: nil, scope: nil, search: nil, sort: nil, direction: nil, filters: {}, attributes: [])
+      @user = user
+      @model_class = model_class
+      @resource_name = (resource || resource_name || model_class.model_name.plural).to_s
+      @scope = scope || model_class.all
+      @search = search
+      @sort = sort
+      @direction = direction
+      @filters = filters || {}
+      @attributes = Array(attributes).map(&:to_s)
+    end
+
+    def call
+      export = @user.csv_exports.create!(
+        model_class_name: @model_class.name,
+        resource_name: @resource_name,
+        search: @search,
+        sort: @sort,
+        direction: @direction,
+        filters: @filters,
+        selected_attributes: @attributes,
+        expires_at: DEFAULT_RETENTION.from_now
+      )
+
+      SuperAdmin::GenerateSuperAdminCsvExportJob.perform_later(
+        export_id: export.id,
+        model_class_name: @model_class.name,
+        attributes: @attributes
+      )
+
+      export
+    end
+  end
+end