rsb-admin 0.9.1

data/app/controllers/rsb/admin/settings_controller.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    class SettingsController < AdminController
+      before_action :authorize_settings
+
+      # GET /admin/settings?tab=auth
+      #
+      # Renders the settings page with tabbed navigation.
+      # Loads settings for the active tab category only.
+      # Resolves current values, locked status, and depends_on states
+      # for each setting in the active category.
+      #
+      # @return [void]
+      def index
+        @rsb_page_title = I18n.t('rsb.admin.settings.page_title', default: 'Settings')
+        @categories = RSB::Settings.registry.categories
+        @active_tab = resolve_active_tab
+
+        if @active_tab
+          @groups = RSB::Settings.registry.grouped_definitions(@active_tab)
+          @field_states = build_field_states(@active_tab, @groups)
+          @current_values = build_current_values(@active_tab, @groups)
+        else
+          @groups = {}
+          @field_states = {}
+          @current_values = {}
+        end
+      end
+
+      # PATCH /admin/settings
+      #
+      # Batch update settings for a single category.
+      # Receives all field values for the category, diffs against current values,
+      # and only persists changed values. Skips locked settings and settings
+      # disabled by depends_on.
+      #
+      # @return [void] redirects to settings page with tab preserved
+      def batch_update
+        category = params.dig(:settings, :category)
+        tab = params.dig(:settings, :tab) || category
+
+        schema = RSB::Settings.registry.for(category)
+        unless schema
+          redirect_to rsb_admin.settings_path, alert: 'Unknown settings category.'
+          return
+        end
+
+        submitted = params.dig(:settings, :values)&.to_unsafe_h || {}
+
+        begin
+          ActiveRecord::Base.transaction do
+            schema.definitions.each do |defn|
+              key_str = defn.key.to_s
+              next unless submitted.key?(key_str)
+
+              full_key = "#{category}.#{key_str}"
+
+              # Skip locked settings (defense-in-depth)
+              next if RSB::Settings.configuration.locked?(full_key)
+
+              # Skip depends_on disabled settings (defense-in-depth)
+              if defn.depends_on.present?
+                parent_value = RSB::Settings.get(defn.depends_on)
+                next unless parent_truthy?(parent_value)
+              end
+
+              # Compare with current value (cast submitted string for fair comparison)
+              current = RSB::Settings.get(full_key)
+              submitted_val = submitted[key_str]
+
+              RSB::Settings.set(full_key, submitted_val) unless values_equal?(current, submitted_val, defn.type)
+            end
+          end
+        rescue RSB::Settings::ValidationError => e
+          RSB::Settings.invalidate_cache!
+          redirect_to rsb_admin.settings_path(tab: tab), alert: e.message
+          return
+        end
+
+        redirect_to rsb_admin.settings_path(tab: tab), notice: 'Settings updated successfully.'
+      end
+
+      # Existing single-setting update (kept for backward compatibility)
+      def update
+        key = "#{params[:category]}.#{params[:key]}"
+
+        if RSB::Settings.configuration.locked?(key)
+          redirect_to rsb_admin.settings_path, alert: 'Setting is locked.'
+          return
+        end
+
+        RSB::Settings.set(key, params[:value])
+        redirect_to rsb_admin.settings_path, notice: 'Setting updated.'
+      end
+
+      private
+
+      # Resolve the active tab from params, falling back to the first category.
+      #
+      # @return [String, nil] the active category name, or nil if no categories exist
+      def resolve_active_tab
+        categories = RSB::Settings.registry.categories
+        return nil if categories.empty?
+
+        tab = params[:tab]
+        categories.include?(tab) ? tab : categories.first
+      end
+
+      # Build a hash of setting key -> field state for the active category.
+      # States: :editable, :locked, :disabled_by_dependency
+      #
+      # @param category [String]
+      # @param groups [Hash<String, Array<SettingDefinition>>]
+      # @return [Hash<Symbol, Symbol>] setting key -> state
+      def build_field_states(category, groups)
+        states = {}
+        locked_keys = RSB::Settings.configuration.locked_keys
+
+        groups.each_value do |definitions|
+          definitions.each do |defn|
+            full_key = "#{category}.#{defn.key}"
+
+            if locked_keys.include?(full_key)
+              states[defn.key] = :locked
+            elsif defn.depends_on.present?
+              parent_value = RSB::Settings.get(defn.depends_on)
+              states[defn.key] = parent_truthy?(parent_value) ? :editable : :disabled_by_dependency
+            else
+              states[defn.key] = :editable
+            end
+          end
+        end
+
+        states
+      end
+
+      # Build a hash of setting key -> current resolved value for the active category.
+      #
+      # @param category [String]
+      # @param groups [Hash<String, Array<SettingDefinition>>]
+      # @return [Hash<Symbol, Object>] setting key -> current value
+      def build_current_values(category, groups)
+        values = {}
+        groups.each_value do |definitions|
+          definitions.each do |defn|
+            values[defn.key] = RSB::Settings.get("#{category}.#{defn.key}")
+          end
+        end
+        values
+      end
+
+      # Check if a parent setting value is truthy for depends_on resolution.
+      # Falsy: false, nil, 0, "", "false", "0"
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      def parent_truthy?(value)
+        return false if value.nil?
+        return false if value == false
+        return false if value == 0
+        return false if value.is_a?(String) && value.blank?
+        return false if value.to_s.downcase == 'false'
+        return false if value.to_s == '0'
+
+        true
+      end
+
+      # Compare current value to submitted value with type-appropriate casting.
+      # Submitted values come as strings from HTML forms.
+      #
+      # @param current [Object] the current resolved value
+      # @param submitted [String] the submitted form value
+      # @param type [Symbol] the setting type
+      # @return [Boolean] true if values are equal
+      def values_equal?(current, submitted, type)
+        case type
+        when :boolean
+          current_bool = ActiveModel::Type::Boolean.new.cast(current)
+          submitted_bool = ActiveModel::Type::Boolean.new.cast(submitted)
+          current_bool == submitted_bool
+        when :integer
+          current.to_i == submitted.to_i
+        when :float
+          current.to_f == submitted.to_f
+        else
+          current.to_s == submitted.to_s
+        end
+      end
+
+      def build_breadcrumbs
+        super
+        add_breadcrumb(I18n.t('rsb.admin.shared.system'))
+        add_breadcrumb(I18n.t('rsb.admin.settings.title'))
+      end
+
+      def authorize_settings
+        authorize_admin_action!(resource: 'settings', action: action_name)
+      end
+    end
+  end
+end

data/app/controllers/rsb/admin/two_factor_controller.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Handles TOTP 2FA enrollment, backup codes display, and disable.
+    # All actions require admin authentication (inherited from AdminController).
+    class TwoFactorController < AdminController
+      skip_before_action :enforce_two_factor_enrollment
+
+      # GET /admin/profile/two_factor/new
+      # Renders the enrollment page with QR code and manual entry key.
+      def new
+        @admin_user = current_admin_user
+        @otp_secret = @admin_user.generate_otp_secret!
+        session[:rsb_admin_otp_provisional_secret] = @otp_secret
+
+        issuer = begin
+          RSB::Settings.get('admin.app_name')
+        rescue StandardError
+          'RSB Admin'
+        end
+        @otp_uri = @admin_user.otp_provisioning_uri(@otp_secret, issuer: issuer)
+        @qr_svg = RQRCode::QRCode.new(@otp_uri).as_svg(
+          module_size: 4,
+          standalone: true,
+          use_path: true
+        )
+      end
+
+      # POST /admin/profile/two_factor
+      # Confirms enrollment by verifying the TOTP code against the provisional secret.
+      def create
+        @admin_user = current_admin_user
+        @otp_secret = session[:rsb_admin_otp_provisional_secret]
+
+        unless @otp_secret
+          redirect_to rsb_admin.new_profile_two_factor_path, alert: 'Enrollment session expired. Please try again.'
+          return
+        end
+
+        totp = ROTP::TOTP.new(@otp_secret)
+        if totp.verify(params[:otp_code].to_s, drift_behind: 30, drift_ahead: 30)
+          # Persist OTP secret and enable 2FA
+          @admin_user.update!(otp_secret: @otp_secret, otp_required: true)
+
+          # Generate backup codes
+          codes = @admin_user.generate_backup_codes!
+          session[:rsb_admin_backup_codes] = codes
+          session.delete(:rsb_admin_otp_provisional_secret)
+          session.delete(:rsb_admin_force_2fa_enrollment)
+
+          redirect_to rsb_admin.profile_two_factor_backup_codes_path
+        else
+          # Re-render enrollment page with error
+          issuer = begin
+            RSB::Settings.get('admin.app_name')
+          rescue StandardError
+            'RSB Admin'
+          end
+          @otp_uri = @admin_user.otp_provisioning_uri(@otp_secret, issuer: issuer)
+          @qr_svg = RQRCode::QRCode.new(@otp_uri).as_svg(
+            module_size: 4,
+            standalone: true,
+            use_path: true
+          )
+          flash.now[:alert] = 'Invalid verification code. Please try again.'
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      # GET /admin/profile/two_factor/backup_codes
+      # Displays backup codes one time after enrollment.
+      def backup_codes
+        @backup_codes = session.delete(:rsb_admin_backup_codes)
+        return if @backup_codes
+
+        redirect_to rsb_admin.profile_path, alert: 'Backup codes are only shown once after enrollment.'
+        nil
+      end
+
+      # DELETE /admin/profile/two_factor
+      # Disables 2FA with current password confirmation.
+      def destroy
+        admin = current_admin_user
+
+        unless admin.authenticate(params[:current_password].to_s)
+          redirect_to rsb_admin.profile_path, alert: 'Incorrect password.'
+          return
+        end
+
+        admin.disable_otp!
+        redirect_to rsb_admin.profile_path, notice: 'Two-factor authentication disabled.'
+      end
+
+      private
+
+      # Override breadcrumbs for 2FA pages
+      def build_breadcrumbs
+        super
+        add_breadcrumb(I18n.t('rsb.admin.profile.title', default: 'Profile'), rsb_admin.profile_path)
+        add_breadcrumb('Two-Factor Authentication')
+      end
+    end
+  end
+end

data/app/helpers/rsb/admin/authorization_helper.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # View helper for permission-aware rendering in admin views.
+    #
+    # Provides a convenience method to check if the current admin user
+    # has permission to access a given resource and action. Used in views
+    # to conditionally render or disable UI elements based on RBAC permissions.
+    # This helper is automatically included in all RSB::Admin controllers
+    # via the AdminController base class.
+    #
+    # @example Check permission in a view
+    #   <% if rsb_admin_can?("identities", "index") %>
+    #     <a href="/admin/identities">Identities</a>
+    #   <% end %>
+    #
+    # @example Conditionally render action button
+    #   <% if rsb_admin_can?("articles", "edit") %>
+    #     <%= link_to "Edit", edit_admin_article_path(@article) %>
+    #   <% end %>
+    module AuthorizationHelper
+      # Check if the current admin user has permission for a resource action.
+      #
+      # Delegates to `current_admin_user.can?` for the actual permission check.
+      # Returns false if there is no current admin user (safety fallback).
+      #
+      # @param resource [String] the resource key (e.g., "identities", "dashboard")
+      # @param action [String] the action name (e.g., "index", "show", "edit")
+      #
+      # @return [Boolean] true if the user has permission, false otherwise
+      #
+      # @example Check dashboard access
+      #   rsb_admin_can?("dashboard", "index") #=> true/false
+      #
+      # @example Check resource edit permission
+      #   rsb_admin_can?("identities", "edit") #=> true/false
+      #
+      # @example No current user returns false
+      #   # When current_admin_user is nil
+      #   rsb_admin_can?("roles", "index") #=> false
+      def rsb_admin_can?(resource, action)
+        return false unless respond_to?(:current_admin_user) && current_admin_user
+
+        current_admin_user.can?(resource, action)
+      end
+    end
+  end
+end

data/app/helpers/rsb/admin/branding_helper.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    module BrandingHelper
+      # Returns the resolved app name from settings.
+      #
+      # @return [String] the admin panel title
+      def rsb_admin_app_name
+        RSB::Settings.get('admin.app_name').to_s.presence || 'Admin'
+      end
+
+      # Returns the resolved logo URL from settings.
+      # Empty string means "not set."
+      #
+      # @return [String] the logo URL or empty string
+      def rsb_admin_logo_url
+        RSB::Settings.get('admin.logo_url').to_s
+      end
+
+      # Returns the resolved company name from settings.
+      # Empty string means "not set."
+      #
+      # @return [String] the company name or empty string
+      def rsb_admin_company_name
+        RSB::Settings.get('admin.company_name').to_s
+      end
+
+      # Returns the resolved footer text from settings.
+      # Empty string means "not set."
+      #
+      # @return [String] the footer text or empty string
+      def rsb_admin_footer_text
+        RSB::Settings.get('admin.footer_text').to_s
+      end
+    end
+  end
+end

data/app/helpers/rsb/admin/formatting_helper.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # View helper methods for formatting values and rendering badges in admin panel views.
+    #
+    # This helper provides value formatting utilities for displaying data in tables,
+    # forms, and detail views. It includes badge rendering with auto-detected variants
+    # and support for multiple formatter types (datetime, json, truncate, custom procs).
+    # The helper is automatically included in all RSB::Admin controllers via the
+    # AdminController base class.
+    #
+    # @example Badge rendering
+    #   <%= rsb_admin_badge("Active", variant: :success) %>
+    #   <%= rsb_admin_badge(user.status, variant: :info) %>
+    #
+    # @example Value formatting
+    #   <%= rsb_admin_format_value(user.status, :badge) %>
+    #   <%= rsb_admin_format_value(user.created_at, :datetime) %>
+    #   <%= rsb_admin_format_value(user.metadata, :json) %>
+    module FormattingHelper
+      # Render a badge span with auto-detected or explicit variant.
+      #
+      # Badges are styled spans with background and text colors corresponding to
+      # semantic variants (success, warning, danger, info). The badge uses Tailwind
+      # CSS utility classes with rsb-* prefixed custom color tokens.
+      #
+      # @param text [String, #to_s] The badge text content
+      # @param variant [Symbol] The badge variant (:success, :warning, :danger, :info)
+      #   Defaults to :info
+      #
+      # @return [ActiveSupport::SafeBuffer] HTML-safe badge span element
+      #
+      # @example Success badge
+      #   rsb_admin_badge("Active", variant: :success)
+      #   # => '<span class="inline-block px-2 py-0.5 rounded-full text-xs font-medium bg-rsb-success-bg text-rsb-success-text">Active</span>'
+      #
+      # @example Warning badge
+      #   rsb_admin_badge("Pending", variant: :warning)
+      #   # => '<span class="inline-block px-2 py-0.5 rounded-full text-xs font-medium bg-rsb-warning-bg text-rsb-warning-text">Pending</span>'
+      #
+      # @example Danger badge
+      #   rsb_admin_badge("Expired", variant: :danger)
+      #   # => '<span class="inline-block px-2 py-0.5 rounded-full text-xs font-medium bg-rsb-danger-bg text-rsb-danger-text">Expired</span>'
+      #
+      # @example Info badge (default)
+      #   rsb_admin_badge("Unknown")
+      #   # => '<span class="inline-block px-2 py-0.5 rounded-full text-xs font-medium bg-rsb-info-bg text-rsb-info-text">Unknown</span>'
+      def rsb_admin_badge(text, variant: :info)
+        variant_class = case variant.to_s
+                        when 'success' then 'bg-rsb-success-bg text-rsb-success-text'
+                        when 'warning' then 'bg-rsb-warning-bg text-rsb-warning-text'
+                        when 'danger'  then 'bg-rsb-danger-bg text-rsb-danger-text'
+                        else 'bg-rsb-info-bg text-rsb-info-text'
+                        end
+        content_tag(:span, text, class: "inline-block px-2 py-0.5 rounded-full text-xs font-medium #{variant_class}")
+      end
+
+      # Format a value using a formatter strategy.
+      #
+      # This method provides a unified interface for formatting values in admin views.
+      # It supports built-in formatters (:badge, :datetime, :truncate, :json), custom
+      # proc formatters, and intelligent defaults when no formatter is specified.
+      # Returns HTML-safe strings suitable for direct rendering in views.
+      #
+      # @param value [Object] The value to format (can be nil, String, Time, Hash, Array, etc.)
+      # @param formatter [Symbol, Proc, nil] The formatter to use:
+      #   - :badge — renders as badge with auto-detected variant (rule #4)
+      #   - :datetime — formats Time values as "Month DD, YYYY at HH:MM PM"
+      #   - :truncate — truncates to 50 chars with ellipsis
+      #   - :json — pretty-prints Hash/Array as <pre> block
+      #   - Proc — calls proc with (value) or (value, record) based on arity
+      #   - nil — auto-formats based on value type
+      # @param record [Object, nil] Optional record passed to proc formatters with arity 2
+      #
+      # @return [ActiveSupport::SafeBuffer, String] HTML-safe formatted value
+      #
+      # @example Badge with auto-detection (rule #4)
+      #   rsb_admin_format_value("active", :badge)
+      #   # => '<span class="...bg-rsb-success-bg...">Active</span>'
+      #   rsb_admin_format_value("suspended", :badge)
+      #   # => '<span class="...bg-rsb-warning-bg...">Suspended</span>'
+      #
+      # @example Datetime formatting
+      #   rsb_admin_format_value(Time.new(2024, 6, 15, 14, 30), :datetime)
+      #   # => "June 15, 2024 at 02:30 PM"
+      #
+      # @example Truncate long text
+      #   rsb_admin_format_value("a" * 100, :truncate)
+      #   # => "aaaaaaaaaa... (truncated)"
+      #
+      # @example JSON formatting
+      #   rsb_admin_format_value({ foo: "bar", baz: 123 }, :json)
+      #   # => '<pre class="...">{\n  "foo": "bar",\n  "baz": 123\n}</pre>'
+      #
+      # @example Empty JSON
+      #   rsb_admin_format_value({}, :json)
+      #   # => '<span class="text-rsb-muted">Empty</span>'
+      #
+      # @example Custom proc formatter
+      #   formatter = ->(val) { "USD #{val}" }
+      #   rsb_admin_format_value(100, formatter)
+      #   # => "USD 100"
+      #
+      # @example Proc with record
+      #   formatter = ->(val, rec) { "#{val} for #{rec.name}" }
+      #   rsb_admin_format_value("admin", formatter, user)
+      #   # => "admin for John Doe"
+      #
+      # @example Nil value
+      #   rsb_admin_format_value(nil, nil)
+      #   # => '<span class="text-rsb-muted">-</span>'
+      #
+      # @example XSS prevention
+      #   rsb_admin_format_value("<script>alert('xss')</script>", nil)
+      #   # => "&lt;script&gt;alert('xss')&lt;/script&gt;"
+      def rsb_admin_format_value(value, formatter, record = nil)
+        return content_tag(:span, '-', class: 'text-rsb-muted') if value.nil?
+
+        case formatter
+        when :badge
+          variant = auto_badge_variant(value)
+          rsb_admin_badge(value.to_s.titleize, variant: variant)
+        when :datetime
+          if value.respond_to?(:strftime)
+            value.strftime('%B %d, %Y at %I:%M %p')
+          else
+            value.to_s
+          end
+        when :truncate
+          truncate(value.to_s, length: 50)
+        when :json
+          if value.is_a?(Hash) || value.is_a?(Array)
+            if value.empty?
+              content_tag(:span, 'Empty', class: 'text-rsb-muted')
+            else
+              content_tag(:pre, JSON.pretty_generate(value),
+                          class: 'mt-1 p-3 bg-rsb-bg rounded-rsb text-xs font-mono overflow-x-auto whitespace-pre')
+            end
+          else
+            value.to_s
+          end
+        when Proc
+          result = formatter.arity == 2 ? formatter.call(value, record) : formatter.call(value)
+          result.to_s
+        when nil
+          # No formatter — render as-is, with special handling for known types
+          if (value.is_a?(Hash) || value.is_a?(Array)) && value.any?
+            content_tag(:pre, JSON.pretty_generate(value),
+                        class: 'mt-1 p-3 bg-rsb-bg rounded-rsb text-xs font-mono overflow-x-auto whitespace-pre')
+          elsif value.is_a?(Time)
+            value.strftime('%B %d, %Y at %I:%M %p')
+          else
+            ERB::Util.html_escape(value.to_s)
+          end
+        else
+          ERB::Util.html_escape(value.to_s)
+        end
+      end
+
+      private
+
+      # Auto-detect badge variant from status-like values (rule #4).
+      #
+      # This method implements the badge auto-detection logic for common status
+      # strings. It performs case-insensitive matching against predefined status
+      # categories and returns the corresponding semantic variant.
+      #
+      # @param value [#to_s] The value to analyze (typically a status string)
+      #
+      # @return [Symbol] The detected variant (:success, :warning, :danger, or :info)
+      #
+      # @example Success states
+      #   auto_badge_variant("active")     # => :success
+      #   auto_badge_variant("ENABLED")    # => :success
+      #   auto_badge_variant("confirmed")  # => :success
+      #
+      # @example Warning states
+      #   auto_badge_variant("pending")    # => :warning
+      #   auto_badge_variant("SUSPENDED")  # => :warning
+      #   auto_badge_variant("invited")    # => :warning
+      #
+      # @example Danger states
+      #   auto_badge_variant("expired")    # => :danger
+      #   auto_badge_variant("DELETED")    # => :danger
+      #   auto_badge_variant("banned")     # => :danger
+      #
+      # @example Unknown states (fallback)
+      #   auto_badge_variant("unknown")    # => :info
+      #   auto_badge_variant("custom")     # => :info
+      def auto_badge_variant(value)
+        case value.to_s.downcase
+        when 'active', 'enabled', 'confirmed', 'accepted'
+          :success
+        when 'suspended', 'pending', 'invited', 'expiring'
+          :warning
+        when 'deactivated', 'disabled', 'expired', 'revoked', 'banned', 'deleted'
+          :danger
+        else
+          :info
+        end
+      end
+    end
+  end
+end