beskar 0.0.2 → 0.2.0

data/lib/beskar/services/waf_request.rb

@@ -0,0 +1,60 @@
+require "uri"
+
+module Beskar
+  module Services
+    # Matching input only. Never copy these raw/canonical paths or query values
+    # into audit records, state, or logs; those contain rule identifiers instead.
+    class WafRequest
+      MAX_BYTES = 8192
+      attr_reader :path, :problem, :method, :decoding_passes
+
+      def initialize(request)
+        @request = request
+        @method = request.respond_to?(:request_method) ? request.request_method.to_s.upcase : "GET"
+        @method = "OTHER" unless %w[GET HEAD POST PUT PATCH DELETE OPTIONS CONNECT TRACE].include?(@method)
+        raw = request.path.to_s
+        @decoding_passes = 0
+        if raw.bytesize > MAX_BYTES
+          @path, @problem = "", :oversized_path
+          return
+        end
+        @path = raw.b
+        @problem = :invalid_encoding if @path.match?(/%(?![0-9a-f]{2})/i)
+        2.times do
+          break unless @path.match?(/%[0-9a-f]{2}/i)
+          @path = @path.gsub(/%([0-9a-f]{2})/i) { [$1.to_i(16)].pack("C") }
+          @decoding_passes += 1
+        end
+        @problem ||= :excessive_encoding if @path.match?(/%[0-9a-f]{2}/i)
+        @path = @path.tr("\\", "/").force_encoding(Encoding::UTF_8)
+        if !@path.valid_encoding? || @path.match?(/[[:cntrl:]]/)
+          @problem = :invalid_encoding
+          @path = ""
+        end
+      end
+
+      def suspicious_format?
+        return false unless @request.respond_to?(:query_string)
+        query = @request.query_string.to_s
+        return false if query.bytesize > MAX_BYTES
+        URI.decode_www_form(query).any? do |key, value|
+          key == "format" && value.match?(/\A(?:exe|bat|cmd|com|scr|vbs|jar|asp|aspx|jsp|php)\z/i)
+        end
+      rescue ArgumentError
+        false
+      end
+
+      def excluded?(category)
+        Array((Beskar.configuration.waf || {})[:request_exclusions]).any? do |rule|
+          next false unless rule.is_a?(Hash)
+          rule = rule.symbolize_keys
+          next false unless rule[:path].is_a?(Regexp)
+          methods = Array(rule[:methods]).map { |value| value.to_s.upcase }
+          categories = Array(rule[:categories]).map(&:to_s)
+          (methods.empty? || methods.include?(method)) &&
+            (categories.empty? || categories.include?(category.to_s)) && rule[:path].match?(path)
+        end
+      end
+    end
+  end
+end

data/lib/beskar/version.rb

@@ -1,3 +1,3 @@
 module Beskar
-  VERSION = "0.0.2"
+  VERSION = "0.2.0"
 end

data/lib/beskar/warden_authentication.rb

@@ -0,0 +1,53 @@
+module Beskar
+  # Wrap strategy execution, not before_failure (which also runs on anonymous
+  # page visits). Database passwords retain their identity-aware admission hook.
+  module WardenStrategyAdmission
+    def _run!
+      return super if defined?(Devise::Strategies::DatabaseAuthenticatable) && is_a?(Devise::Strategies::DatabaseAuthenticatable)
+      model = Beskar.configuration.model_class_for_scope(scope)
+      return super unless model&.respond_to?(:track_failed_authentication)
+
+      request = ActionDispatch::Request.new(env)
+      attempt = Services::AuthenticationAttempt.reserve(request, model: model, scope: scope, cache: true)
+      unless attempt.allowed?
+        model.track_failed_authentication(request, scope, attempt: attempt)
+        custom!(attempt.response)
+        return self
+      end
+      super
+    rescue Services::AuthenticationAttempt::Unavailable, ActiveRecord::ActiveRecordError
+      custom!(Services::AuthenticationAttempt.unavailable_response)
+      self
+    end
+  end
+
+  # Enforce even if a host uses set_user(..., run_callbacks: false). Includes
+  # OAuth sign_in, non-password strategies, stateless Warden and session fetch.
+  module WardenSessionAdmission
+    def set_user(user, opts = {})
+      return super unless user.respond_to?(:track_authentication_event)
+      scope = opts[:scope] || config.default_scope
+      request = ActionDispatch::Request.new(env)
+      if opts[:event] == :fetch
+        allowed = Services::SessionRevocation.allowed?(user, request: request,
+          token: Services::SessionRevocation.token(user))
+      else
+        attempt = Services::AuthenticationAttempt.current(request, scope)
+        attempt ||= Services::AuthenticationAttempt.reserve(request, model: user.class,
+          scope: scope, user: user, cache: true)
+        user.track_authentication_event(request, :success, attempt: attempt, persist: false)
+        attempt.verify_generation!
+        attempt.persist_outcome!
+        allowed = attempt.allowed?
+      end
+      unless allowed
+        logout(scope)
+        throw :warden, scope: scope, message: :authentication_denied
+      end
+      super
+    rescue Services::AuthenticationAttempt::Unavailable, ActiveRecord::ActiveRecordError
+      logout(scope)
+      raise Services::AuthenticationAttempt::Unavailable, "Authentication temporarily unavailable"
+    end
+  end
+end

data/lib/beskar.rb

@@ -1,5 +1,8 @@
 require "beskar/version"
 require "beskar/configuration"
+require "beskar/configuration_validator"
+require "beskar/logger"
+require "beskar/risk_level"
 require "beskar/middleware"
 require "beskar/middleware/request_analyzer"
 require "beskar/models/security_trackable_generic"
@@ -9,19 +12,66 @@ require "beskar/models/security_trackable"
 require "beskar/services/rate_limiter"
 require "beskar/services/device_detector"
 require "beskar/services/geolocation_service"
+require "beskar/services/location_assessment"
+require "beskar/services/risk_assessment"
 require "beskar/services/account_locker"
 require "beskar/services/ip_whitelist"
 require "beskar/services/waf"
+require "beskar/services/waf_request"
+require "beskar/services/audit_data"
+require "beskar/services/event_search"
+require "beskar/services/request_context"
+require "beskar/services/authentication_attempt"
+require "beskar/services/authentication"
+require "beskar/services/native_account_lock"
+require "beskar/services/session_revocation"
+require "beskar/services/notifications"
+require "beskar/services/administrative_bans"
+require "beskar/services/administrative_audit"
+require "beskar/services/ban_expiry"
+require "beskar/devise_authentication"
+require "beskar/warden_authentication"
 require "beskar/engine"
 
 module Beskar
   class << self
-    attr_accessor :configuration
+    def configuration=(value)
+      raise Configuration::Error, "Use audited Beskar.configure for runtime changes" if configuration.frozen?
+      @configuration = value
+    end
   end
 
-  def self.configure
-    self.configuration ||= Configuration.new
-    yield(configuration)
+  CONFIGURATION_MUTEX = Mutex.new
+
+  def self.configure(actor: nil, reason: nil, request_id: nil)
+    CONFIGURATION_MUTEX.synchronize do
+      original = configuration
+      if original.frozen?
+        allowed = original.authorize_configuration&.call(actor) == true
+        raise Configuration::Error, "Runtime configuration change is not authorized" unless allowed
+        raise Configuration::Error, "Runtime configuration cannot run in a database transaction" if AdministrativeAction.connection.transaction_open?
+      end
+      candidate = original.dup
+      yield(candidate)
+      candidate.validate!(resolve_jobs: !!Rails.application&.initialized?)
+      published = candidate.dup
+      if original.frozen?
+        published.seal!
+        Services::AdministrativeAudit.record!(actor: actor, reason: reason, request_id: request_id,
+          action: "configuration_changed", target_type: "Configuration",
+          before_state: Services::AdministrativeAudit.configuration_snapshot(original),
+          after_state: Services::AdministrativeAudit.configuration_snapshot(published).merge(
+            "changed_settings" => original.instance_variables.filter_map do |name|
+              name.to_s.delete_prefix("@") unless original.instance_variable_get(name) == published.instance_variable_get(name)
+            end, "process_id" => Process.pid
+          ))
+      end
+      @configuration = published
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
   end
 
   # Convenience method to access the rate limiter

data/lib/generators/beskar/install/install_generator.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record/migration"
+
+module Beskar
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Beskar initializer, mounts the dashboard, and copies migrations"
+
+      def copy_initializer
+        template "initializer.rb.tt", "config/initializers/beskar.rb"
+      end
+
+      def mount_engine
+        route_text = "mount Beskar::Engine => '/beskar'"
+
+        # Check if the route already exists
+        routes_path = File.join(destination_root, "config/routes.rb")
+        if !File.exist?(routes_path)
+          say "No config/routes.rb found; mount Beskar::Engine manually at /beskar.", :yellow
+        elsif File.read(routes_path).match?(/\bmount\s+Beskar::Engine\b/)
+          say "Route already mounted, skipping...", :yellow
+        else
+          route route_text
+          say "Mounted Beskar engine at /beskar", :green
+        end
+      end
+
+      def copy_migrations
+        # Copy migrations from the engine to the host app
+        migration_source = File.expand_path("../../../../db/migrate", __dir__)
+
+        if Dir.exist?(migration_source)
+          Dir.glob("#{migration_source}/*.rb").each do |migration|
+            migration_name = File.basename(migration).sub(/^\d+_/, "")
+
+            # Check if migration already exists
+            if migration_already_exists?(migration_name)
+              say "Migration #{migration_name} already exists, skipping...", :yellow
+            else
+              migration_template migration, "db/migrate/#{migration_name}"
+            end
+          end
+        end
+
+        say "Migrations copied. Run 'rails db:migrate' to create the tables.", :green
+      end
+
+      # CSS Zero is no longer required - styles are embedded in the dashboard
+      # def install_css_zero
+      #   # Removed - dashboard now uses embedded styles
+      # end
+
+      def show_readme
+        readme_content = <<~README
+
+          ===============================================================================
+          🛡️  Beskar Installation Complete!
+          ===============================================================================
+
+          Next steps:
+
+          1. Run migrations to create the security tables:
+             $ rails db:migrate
+
+          2. Configure authentication for the dashboard in config/initializers/beskar.rb
+
+             Uncomment one complete example in the generated initializer:
+             - Rails built-in authentication: signed session_id cookie and Session model.
+             - Devise: Warden authentication with your app's Devise mapping scope.
+
+             Each example includes authenticate_admin, authorize_admin, and audit_actor.
+             Adapt admin? and beskar_permissions to your application's roles/policies.
+             Permissions: read, manage_bans, export, read_audit. Missing grants deny access.
+             Beskar's controller does not inherit your host authentication helpers.
+             See docs/guides/authentication.md and docs/guides/audit-lifecycle.md.
+             Without audit_actor, separately authorized reads work but writes/exports return 503.
+
+          3. Add Beskar concerns to your User model (or authentication model):
+
+             For Rails built-in authentication:
+             class User < ApplicationRecord
+               include Beskar::Models::SecurityTrackableAuthenticable
+             end
+             Also integrate login admission and session guards from docs/guides/authentication.md.
+
+             For Devise:
+             class User < ApplicationRecord
+               include Beskar::Models::SecurityTrackable
+               include Beskar::Models::SecurityTrackableDevise
+             end
+
+          4. Access the security dashboard at:
+             http://localhost:3000/beskar
+
+          5. Optional: Configure additional settings in config/initializers/beskar.rb
+             - IP whitelist
+             - WAF rules
+             - Rate limiting
+             - Geolocation
+             - Risk-based locking
+
+          ===============================================================================
+          📚 Documentation
+          ===============================================================================
+
+          Documentation: https://github.com/humadroid-io/beskar/blob/master/docs/README.md
+          Dashboard Guide: https://github.com/humadroid-io/beskar/blob/master/docs/guides/dashboard-and-search.md
+          Configuration: https://github.com/humadroid-io/beskar/blob/master/docs/guides/configuration.md
+
+          ===============================================================================
+          ⚠️  Important for Production
+          ===============================================================================
+
+          1. ALWAYS configure authentication for the dashboard
+          2. Set monitor_only = false when ready to block threats
+          3. Configure your IP whitelist to prevent locking yourself out
+          4. Run the copied migrations; required indexes are included.
+          5. Schedule Beskar::SecurityState.cleanup_expired! to reclaim expired state.
+
+          ===============================================================================
+          💡 Quick Tips
+          ===============================================================================
+
+          - Start with monitor_only = true to observe without blocking
+          - Use the dashboard to review security events before enabling blocking
+          - Configure email notifications for high-risk events
+          - Export security data regularly for analysis
+          - Consider implementing custom risk scoring for your use case
+
+          ===============================================================================
+
+        README
+
+        say readme_content, :green
+      end
+
+      private
+
+      def migration_already_exists?(migration_name)
+        basename = migration_name.delete_suffix(".rb")
+        Dir.glob(File.join(destination_root, "db/migrate/*_#{basename}{,.beskar}.rb")).any?
+      end
+
+      def migration_template(source, destination)
+        migration_number = self.class.next_migration_number(File.join(destination_root, File.dirname(destination)))
+        file_name = File.join(File.dirname(destination), "#{migration_number}_#{File.basename(destination)}")
+
+        copy_file source, file_name
+      end
+    end
+  end
+end

data/lib/generators/beskar/install/templates/initializer.rb.tt

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+Beskar.configure do |config|
+  # ============================================================================
+  # DASHBOARD AUTHENTICATION (REQUIRED)
+  # ============================================================================
+  # Configure how to authenticate access to the Beskar security dashboard.
+  # This is REQUIRED for all environments.
+  #
+  # The authenticate_admin callback receives the request object and is executed
+  # in the controller context, giving you access to all controller methods
+  # (cookies, session, authenticate_or_request_with_http_basic, etc.).
+  # The block should return truthy value to allow access, falsey to deny.
+
+  # Choose one authentication option below. Options 1 and 2 include all three
+  # callbacks: authentication, permissions, and the operator recorded in audits.
+  # admin? and beskar_permissions are application-defined methods, not Rails or
+  # Devise defaults. Adapt them to your roles/policies. Permission names are:
+  # read, manage_bans, export, read_audit (beskar_permissions returns strings).
+  #
+  # Option 1: Rails built-in authentication (Rails 8 authentication generator)
+  # Beskar does not inherit your ApplicationController or Authentication concern,
+  # so Current.session/current_user may not be populated on dashboard requests.
+  # Resolve the host's Session from its signed cookie instead. Adapt the model
+  # and cookie name if you customized Rails' generated authentication.
+  # First add this to app/models/user.rb (not inside this initializer):
+  #   include Beskar::Models::SecurityTrackableAuthenticable
+  # This supplies beskar_access_allowed? for the revocation guard below.
+  # Beskar::Models::SecurityTrackable is Devise-specific and is not a substitute;
+  # without the native concern, the guard raises NoMethodError on the user.
+  # See docs/guides/authentication.md for the full integration.
+  # config.authenticate_admin = ->(request) do
+  #   @beskar_admin_user = nil
+  #   session_id = cookies.signed[:session_id]
+  #   auth_session = ::Session.find_by(id: session_id) if session_id
+  #   if Beskar::Services::SessionRevocation.native_session_allowed?(auth_session, request: request)
+  #     @beskar_admin_user = auth_session.user
+  #   end
+  #   @beskar_admin_user&.admin?
+  # end
+  # config.authorize_admin = ->(_request, permission) do
+  #   @beskar_admin_user&.admin? && @beskar_admin_user.beskar_permissions.include?(permission.to_s)
+  # end
+  # config.audit_actor = ->(_request) do
+  #   "User:#{@beskar_admin_user.id}" if @beskar_admin_user&.admin?
+  # end
+
+  # Option 2: Devise (Warden-backed; does not use the Rails Session model)
+  # :user is the Devise mapping scope, not a role. Change it to :admin only if
+  # your app has a separate Devise Admin model/mapping.
+  # authenticate resumes the Warden session or tries configured strategies
+  # (including remember-me); user reads the resulting authenticated identity.
+  # config.authenticate_admin = ->(request) do
+  #   user = request.env['warden']&.authenticate(scope: :user)
+  #   user&.admin?
+  # end
+  # config.authorize_admin = ->(request, permission) do
+  #   user = request.env['warden']&.user(scope: :user)
+  #   user&.admin? && user.beskar_permissions.include?(permission.to_s)
+  # end
+  # config.audit_actor = ->(request) do
+  #   user = request.env['warden']&.user(scope: :user)
+  #   "User:#{user.id}" if user&.admin?
+  # end
+
+  # Option 3: HTTP Basic Authentication (uses controller method)
+  # config.authenticate_admin = ->(request) do
+  #   authenticate_or_request_with_http_basic("Beskar Admin") do |username, password|
+  #     Beskar::Services::RequestContext.secure_match?(username, ENV['BESKAR_ADMIN_USERNAME']) &&
+  #       Beskar::Services::RequestContext.secure_match?(password, ENV['BESKAR_ADMIN_PASSWORD'])
+  #   end
+  # end
+
+  # Option 4: Token-based authentication
+  # config.authenticate_admin = ->(request) do
+  #   token = ENV['BESKAR_ADMIN_TOKEN']
+  #   token.present? && Beskar::Services::RequestContext.secure_match?(request.headers['Authorization'], "Bearer #{token}")
+  # end
+
+  # Option 5: Cookie-based authentication (uses controller cookies)
+  # config.authenticate_admin = ->(request) do
+  #   Beskar::Services::RequestContext.secure_match?(cookies.signed[:admin_token], ENV['BESKAR_ADMIN_TOKEN'])
+  # end
+
+  # Option 6: Using CanCanCan (requires policy helpers on Beskar's controller)
+  # config.authenticate_admin = ->(request) do
+  #   authorize! :manage, :beskar_dashboard
+  # end
+
+  # Option 7: Using Pundit (requires policy helpers on Beskar's controller)
+  # config.authenticate_admin = ->(request) do
+  #   authorize :beskar_dashboard, :access?
+  # end
+
+  # Option 8: For development/testing ONLY (NOT for production!)
+  # config.authenticate_admin = ->(request) do
+  #   Rails.env.development? || Rails.env.test?
+  # end
+
+  # REQUIRED: grant permissions separately from authentication (nil denies all).
+  # Options 1 and 2 show complete examples. For other options, supply your own
+  # authorize_admin callback returning true for each permitted operation.
+
+  # REQUIRED FOR DASHBOARD WRITES AND EXPORTS: resolve an authenticated operator.
+  # Use the same trusted identity used by authenticate_admin (as above).
+  # Never derive this from request params, emails, passwords, or tokens.
+  # Without audit_actor, separately authorized reads work; writes/exports return 503.
+  # Forms require a reason and changes require transactional history.
+  # Apply the administrative-action migration; see docs/guides/audit-lifecycle.md.
+
+  # ============================================================================
+  # MONITOR-ONLY MODE
+  # ============================================================================
+  # When enabled, Beskar will log all security events but won't actually block
+  # any requests. Useful for testing or initial deployment.
+  config.monitor_only = true
+
+  # ============================================================================
+  # IP WHITELIST
+  # ============================================================================
+  # IPs that should never be blocked (your office, monitoring services, etc.)
+  config.ip_whitelist = [
+    # '192.168.1.0/24',  # Local network
+    # '10.0.0.0/8',      # Private network
+    # '127.0.0.1',       # Localhost
+  ]
+
+  # ============================================================================
+  # WAF (WEB APPLICATION FIREWALL) - Score-Based Blocking
+  # ============================================================================
+  # Enable scanner-path detection (not general SQL injection/XSS filtering).
+  # Uses score-based blocking with exponential decay for intelligent threat detection.
+  config.waf[:enabled] = true
+
+  # Optionally customize WAF settings (these are the defaults):
+  # config.waf[:auto_block] = true                 # Automatically block IPs after threshold
+  # config.waf[:score_threshold] = 150             # Cumulative risk score before blocking
+  # config.waf[:violation_window] = 6.hours        # Maximum time window to track violations
+  # config.waf[:block_durations] = [1.hour, 6.hours, 24.hours, 7.days] # Escalating durations
+  # config.waf[:permanent_block_after] = 500       # Permanent block when cumulative score reaches this
+  # config.waf[:create_security_events] = true     # Create SecurityEvent records
+  # config.waf[:exception_detection] = :suspicious # Ordinary Rails errors need scanner evidence
+  # config.waf[:request_exclusions] = [
+  #   {path: %r{\A/wp-content/}, methods: ["GET", "HEAD"], categories: [:wordpress_static]}
+  # ]
+  # WAF evidence excludes raw URLs and exception messages. Audit fields honor
+  # Rails filter_parameters. See docs/guides/audit-and-waf.md before opting into :all errors.
+  #
+  # === Exponential Decay Configuration ===
+  # Violations decay over time based on severity (reduces false positives)
+  # config.waf[:decay_enabled] = true
+  # config.waf[:decay_rates] = {                   # Half-life in minutes
+  #   critical: 360,  # 6 hour half-life (config files, path traversal)
+  #   high: 120,      # 2 hour half-life (WordPress, PHP admin scans)
+  #   medium: 45,     # 45 minute half-life (unknown formats)
+  #   low: 15         # 15 minute half-life (RecordNotFound/404s)
+  # }
+  # config.waf[:max_violations_tracked] = 50       # Maximum violations to track per IP
+  #
+  # === RecordNotFound Exclusions ===
+  # Exclude legitimate 404-prone paths from triggering violations
+  # config.waf[:record_not_found_exclusions] = [
+  #   %r{/posts/.*},              # Blog posts with slugs
+  #   %r{/products/[\w-]+},       # Product URLs with slugs
+  #   %r{/public/.*}              # Public content
+  # ]
+  #
+  # === Illustrative thresholds ===
+  # See docs/guides/audit-and-waf.md for matching rules and tuning limitations:
+  # - STRICT: score_threshold = 100 (high-security)
+  # - BALANCED: score_threshold = 150 (recommended default)
+  # - PERMISSIVE: score_threshold = 200 (high-traffic sites)
+
+  # ============================================================================
+  # SECURITY TRACKING
+  # ============================================================================
+  # Security tracking is enabled by default. To disable or customize:
+  # config.security_tracking[:enabled] = false
+  # config.security_tracking[:track_successful_logins] = true
+  # config.security_tracking[:track_failed_logins] = true
+  # No background analyzer is built in. Opt in with your own Active Job:
+  # config.security_tracking[:analysis_job] = "SecurityReviewJob"
+  # config.security_tracking[:auto_analyze_patterns] = true
+  # The job receives user_type:, user_id:, event_type: after the outer commit.
+  # See docs/guides/configuration.md for the contract and queue/delivery limitations.
+
+  # ============================================================================
+  # RATE LIMITING
+  # ============================================================================
+  # Rate limiting is configured by default. To customize:
+  # config.rate_limiting[:ip_attempts][:limit] = 10
+  # config.rate_limiting[:ip_attempts][:period] = 1.hour
+  # config.rate_limiting[:ip_attempts][:exponential_backoff] = true
+  #
+  # config.rate_limiting[:account_attempts][:limit] = 5
+  # config.rate_limiting[:account_attempts][:period] = 15.minutes
+  # config.rate_limiting[:account_attempts][:exponential_backoff] = true
+  #
+  # config.rate_limiting[:global_attempts][:enabled] = false # Shared budget is opt-in
+  # config.rate_limiting[:ip_attempts][:block_requests] = false # Keep login quotas off unrelated requests
+  # config.rate_limiting[:global_attempts][:limit] = 100
+  # config.rate_limiting[:global_attempts][:period] = 1.minute
+  # config.rate_limiting[:global_attempts][:exponential_backoff] = false
+
+  # ============================================================================
+  # RISK-BASED ACCOUNT LOCKING
+  # ============================================================================
+  # Risk-based locking is disabled by default. To enable:
+  # Review docs/guides/risk-scoring.md: factors are heuristics; repeated IPs do not establish trust.
+  # config.risk_based_locking[:enabled] = true
+  # Confirmed locks always reject sign-in and revoke old sessions, including with legacy immediate_signout: false.
+  # config.risk_based_locking[:risk_threshold] = 75        # Risk score threshold for locking
+  # config.risk_based_locking[:lock_strategy] = :devise_lockable # :rails_auth or :none also supported; :custom is rejected
+  # config.risk_based_locking[:auto_unlock_time] = 1.hour  # Native locks only; nil requires manual unlock
+  # Devise owns unlock_strategy/unlock_in. Configure those through Devise.
+  # Rails-native controllers/session readers need the guards in docs/guides/authentication.md.
+  # config.risk_based_locking[:notify_user] = true         # Opt-in email; configure notifications below first
+  # config.risk_based_locking[:log_lock_events] = true     # Log lock events
+
+  # ============================================================================
+  # GEOLOCATION
+  # ============================================================================
+  # Geolocation uses a mock provider by default. To use MaxMind:
+  # Mock locations are synthetic and never trigger travel/country risk.
+  # 1. Download GeoLite2-City database from maxmind.com
+  # 2. Place it in config/GeoLite2-City.mmdb
+  # 3. Configure:
+  # config.geolocation[:provider] = :maxmind
+  # config.geolocation[:maxmind_city_db_path] = Rails.root.join('config', 'GeoLite2-City.mmdb').to_s
+  # config.geolocation[:cache_ttl] = 4.hours
+
+  # ============================================================================
+  # AUTHENTICATION MODELS
+  # ============================================================================
+  # Authentication models are auto-detected by default. To customize:
+  # config.authentication_models[:auto_detect] = false  # Disable auto-detection
+  # config.authentication_models[:devise] = [:user, :admin]
+  # config.authentication_models[:rails_auth] = [:customer]
+
+  # ============================================================================
+  # EMERGENCY PASSWORD RESET
+  # ============================================================================
+  # Emergency password reset is disabled by default. To enable:
+  # config.emergency_password_reset[:enabled] = true
+  # config.emergency_password_reset[:impossible_travel_threshold] = 3
+  # config.emergency_password_reset[:suspicious_device_threshold] = 5
+  # config.emergency_password_reset[:total_locks_threshold] = 5
+  # config.emergency_password_reset[:send_notification] = true # Default false; requires notification settings
+  # config.emergency_password_reset[:notify_security_team] = true # Default false; requires team recipients
+  # config.emergency_password_reset[:require_manual_unlock] = false
+
+  # ============================================================================
+  # NOTIFICATIONS (OPT-IN)
+  # ============================================================================
+  # config.notifications[:from] = "security@your-domain.example"
+  # config.notifications[:recovery_url] = "https://your-domain.example/account-recovery"
+  # config.notifications[:security_team_recipients] = ["security-team@your-domain.example"]
+  # Replace these values, configure Action Mailer, and run an Active Job worker
+  # consuming beskar_notifications. Recovery URLs are entry pages, never tokens.
+  # See docs/guides/notifications-and-recovery.md for retries and host recovery requirements.
+end