beskar 0.1.0 → 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.1.0"
+  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,6 +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"
@@ -10,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

@@ -1,25 +1,16 @@
 # frozen_string_literal: true
 
-require 'rails/generators'
-require 'rails/generators/migration'
+require "rails/generators"
+require "rails/generators/active_record/migration"
 
 module Beskar
   module Generators
     class InstallGenerator < Rails::Generators::Base
-      include Rails::Generators::Migration
+      include ActiveRecord::Generators::Migration
 
-      source_root File.expand_path('templates', __dir__)
+      source_root File.expand_path("templates", __dir__)
 
-      desc "Creates a Beskar initializer and runs migrations"
-
-      def self.next_migration_number(path)
-        if @prev_migration_nr
-          @prev_migration_nr += 1
-        else
-          @prev_migration_nr = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
-        end
-        @prev_migration_nr.to_s
-      end
+      desc "Creates a Beskar initializer, mounts the dashboard, and copies migrations"
 
       def copy_initializer
         template "initializer.rb.tt", "config/initializers/beskar.rb"
@@ -29,7 +20,10 @@ module Beskar
         route_text = "mount Beskar::Engine => '/beskar'"
 
         # Check if the route already exists
-        if File.read("config/routes.rb").include?(route_text)
+        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
@@ -39,11 +33,11 @@ module Beskar
 
       def copy_migrations
         # Copy migrations from the engine to the host app
-        migration_source = File.expand_path("../../../../../db/migrate", __dir__)
+        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+_/, '')
+            migration_name = File.basename(migration).sub(/^\d+_/, "")
 
             # Check if migration already exists
             if migration_already_exists?(migration_name)
@@ -76,22 +70,28 @@ module Beskar
 
           2. Configure authentication for the dashboard in config/initializers/beskar.rb
 
-             For Devise users:
-             config.authenticate_admin = proc do
-               authenticate_admin!
-             end
+             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.
 
-             For custom authentication:
-             config.authenticate_admin = proc do
-               redirect_to main_app.root_path unless current_user&.admin?
-             end
+             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::SecurityTrackable
+               include Beskar::Models::SecurityTrackableAuthenticable
+             end
+             Also integrate login admission and session guards from docs/guides/authentication.md.
 
-               # For Devise users, also add:
+             For Devise:
+             class User < ApplicationRecord
+               include Beskar::Models::SecurityTrackable
                include Beskar::Models::SecurityTrackableDevise
              end
 
@@ -109,8 +109,9 @@ module Beskar
           📚 Documentation
           ===============================================================================
 
-          Dashboard Guide: https://github.com/humadroid-io/beskar/blob/main/DASHBOARD.md
-          Configuration: https://github.com/humadroid-io/beskar/blob/main/README.md
+          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
@@ -119,10 +120,8 @@ module Beskar
           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. Set up database indexes for large-scale deployments:
-
-             $ rails generate beskar:indexes
-             $ rails db:migrate
+          4. Run the copied migrations; required indexes are included.
+          5. Schedule Beskar::SecurityState.cleanup_expired! to reclaim expired state.
 
           ===============================================================================
           💡 Quick Tips
@@ -144,12 +143,13 @@ module Beskar
       private
 
       def migration_already_exists?(migration_name)
-        Dir.glob("db/migrate/*_#{migration_name}").any?
+        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(nil)
-        file_name = "#{migration_number}_#{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

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

@@ -12,51 +12,108 @@ Beskar.configure do |config|
   # (cookies, session, authenticate_or_request_with_http_basic, etc.).
   # The block should return truthy value to allow access, falsey to deny.
 
-  # Option 1: Using Devise with admin role (recommended for production)
+  # 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 2: HTTP Basic Authentication (uses controller method)
+  # Option 3: HTTP Basic Authentication (uses controller method)
   # config.authenticate_admin = ->(request) do
   #   authenticate_or_request_with_http_basic("Beskar Admin") do |username, password|
-  #     username == ENV['BESKAR_ADMIN_USERNAME'] &&
-  #     password == ENV['BESKAR_ADMIN_PASSWORD']
+  #     Beskar::Services::RequestContext.secure_match?(username, ENV['BESKAR_ADMIN_USERNAME']) &&
+  #       Beskar::Services::RequestContext.secure_match?(password, ENV['BESKAR_ADMIN_PASSWORD'])
   #   end
   # end
 
-  # Option 3: Token-based authentication
+  # Option 4: Token-based authentication
   # config.authenticate_admin = ->(request) do
-  #   request.headers['Authorization'] == "Bearer #{ENV['BESKAR_ADMIN_TOKEN']}"
+  #   token = ENV['BESKAR_ADMIN_TOKEN']
+  #   token.present? && Beskar::Services::RequestContext.secure_match?(request.headers['Authorization'], "Bearer #{token}")
   # end
 
-  # Option 4: Cookie-based authentication (uses controller cookies)
+  # Option 5: Cookie-based authentication (uses controller cookies)
   # config.authenticate_admin = ->(request) do
-  #   cookies.signed[:admin_token] == ENV['BESKAR_ADMIN_TOKEN']
+  #   Beskar::Services::RequestContext.secure_match?(cookies.signed[:admin_token], ENV['BESKAR_ADMIN_TOKEN'])
   # end
 
-  # Option 5: Using CanCanCan (uses controller method)
+  # Option 6: Using CanCanCan (requires policy helpers on Beskar's controller)
   # config.authenticate_admin = ->(request) do
   #   authorize! :manage, :beskar_dashboard
   # end
 
-  # Option 6: Using Pundit (uses controller method)
+  # Option 7: Using Pundit (requires policy helpers on Beskar's controller)
   # config.authenticate_admin = ->(request) do
   #   authorize :beskar_dashboard, :access?
   # end
 
-  # Option 7: For development/testing ONLY (NOT for production!)
+  # 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 = <%= Rails.env.development? ? 'true' : 'false' %>
+  config.monitor_only = true
 
   # ============================================================================
   # IP WHITELIST
@@ -71,7 +128,7 @@ Beskar.configure do |config|
   # ============================================================================
   # WAF (WEB APPLICATION FIREWALL) - Score-Based Blocking
   # ============================================================================
-  # Enable WAF to protect against common attacks and vulnerability scans.
+  # 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
 
@@ -82,6 +139,12 @@ Beskar.configure do |config|
   # 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)
@@ -102,8 +165,8 @@ Beskar.configure do |config|
   #   %r{/public/.*}              # Public content
   # ]
   #
-  # === Pre-configured Profiles ===
-  # See WAF_CONFIGURATION_PROFILES.md for complete profile examples:
+  # === 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)
@@ -115,7 +178,11 @@ Beskar.configure do |config|
   # 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
@@ -129,6 +196,8 @@ Beskar.configure do |config|
   # 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
@@ -137,17 +206,22 @@ Beskar.configure do |config|
   # 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
-  # config.risk_based_locking[:immediate_signout] = false  # Sign out users immediately when locked
+  # 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[:auto_unlock_time] = 1.hour  # How long to lock the account
-  # config.risk_based_locking[:notify_user] = true         # Notify user on lock
+  # 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:
@@ -171,7 +245,17 @@ Beskar.configure do |config|
   # 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
-  # config.emergency_password_reset[:notify_security_team] = true
+  # 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

data/lib/tasks/beskar_tasks.rake

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 namespace :beskar do
+  desc "Remove expired coordination state (does not remove audit events or active bans)"
+  task cleanup_security_state: :environment do
+    Beskar::SecurityState.cleanup_expired!
+  end
+
   desc "Install Beskar: copy migrations and create initializer"
   task install: :environment do
     puts "=" * 80
@@ -10,25 +15,19 @@ namespace :beskar do
 
     # Copy migrations
     puts "📦 Copying migrations..."
-    begin
-      Rake::Task["beskar:install:migrations"].invoke
-    rescue RuntimeError
-      # In development/test within the gem, this task might not exist
-      # In a real app using the gem, it will work fine
-      puts "   (Skipping migration copy in gem development mode)"
-    end
+    Rake::Task["beskar:install:migrations"].invoke
     puts "✓ Migrations ready"
     puts
 
     # Create initializer
     initializer_path = Rails.root.join("config/initializers/beskar.rb")
-    
+
     if File.exist?(initializer_path)
       puts "⚠️  Initializer already exists at config/initializers/beskar.rb"
       print "   Overwrite? (y/N): "
-      response = $stdin.gets.chomp.downcase
-      
-      unless response == 'y' || response == 'yes'
+      response = $stdin.gets.to_s.strip.downcase
+
+      unless response == "y" || response == "yes"
         puts "   Skipping initializer creation"
         puts
         next_steps
@@ -41,7 +40,7 @@ namespace :beskar do
 
     # Read the template and process ERB (Rails will be available in the rake task context)
     template_content = File.read(template_path)
-    erb = ERB.new(template_content, trim_mode: '-')
+    erb = ERB.new(template_content, trim_mode: "-")
 
     # Evaluate the ERB template in a context where Rails is available
     processed_content = erb.result(binding)
@@ -69,7 +68,7 @@ namespace :beskar do
     puts
     puts "   # app/models/user.rb"
     puts "   class User < ApplicationRecord"
-    puts "     include Beskar::SecurityTrackable"
+    puts "     include Beskar::Models::SecurityTrackable"
     puts "     "
     puts "     devise :database_authenticatable, :registerable,"
     puts "            :recoverable, :rememberable, :validatable"
@@ -98,11 +97,8 @@ namespace :beskar do
     puts "5. When ready to enable blocking:"
     puts
     puts "   # config/initializers/beskar.rb"
-    puts "   config.waf = {"
-    puts "     enabled: true,"
-    puts "     monitor_only: false,  # <-- Change this to false"
-    puts "     # ... rest of config"
-    puts "   }"
+    puts "   config.waf[:enabled] = true"
+    puts "   config.monitor_only = false"
     puts
     puts "6. Optional: Add IP whitelist for trusted sources:"
     puts
@@ -115,7 +111,7 @@ namespace :beskar do
     puts "=" * 80
     puts "Documentation:"
     puts "  - README: https://github.com/humadroid-io/beskar"
-    puts "  - WAF Monitor Mode: See MONITOR_ONLY_MODE.md"
+    puts "  - WAF Monitor Mode: See docs/operations/monitor-only-mode.md"
     puts "=" * 80
   end
 end