beskar 0.0.2 → 0.2.0

data/docs/operations/state-storage.md

@@ -0,0 +1,144 @@
+# Coordinated security state
+
+Beskar supports any `Rails.cache` backend, including a process-local MemoryStore,
+FileStore, RedisCacheStore, MemCacheStore, Solid Cache, or NullStore. Enforcement
+does not depend on cache increment, compare-and-swap, distributed locks, or cache
+persistence. A custom store does not need any Beskar-specific operations.
+
+## Authority and trade-offs
+
+`beskar_security_states` is the shared authority for rate-limit windows, backoff
+deadlines, middleware denial counts, and WAF violation history. Transactions lock
+rows in deterministic order. Unique keys prevent duplicate state; optimistic
+locking and bounded retries handle concurrent-update conflicts, including SQLite
+write-lock contention. Retryable blocks must contain only database work.
+
+Ban mutation reads also lock the ban row. Under MySQL's default `REPEATABLE READ`,
+an earlier coordination lookup can establish a snapshot before another worker
+commits. Locking the coordination row does not refresh ordinary snapshot reads
+of other tables; [locking reads](https://dev.mysql.com/doc/refman/8.4/en/innodb-locking-reads.html)
+are required to preserve the latest violation count and expiry when extending a ban.
+Native session revocation likewise locks the current session rows and checks for
+remaining rows with a locking read, ignoring stale loaded associations while
+preserving host removal/destruction callbacks.
+
+`beskar_banned_ips` is authoritative for ban decisions. Each decision uses an
+indexed database query. Stale positive/negative cache entries, cache eviction,
+process restarts, and rolled-back ban writes do not change the result.
+`BannedIp.preload_cache!` remains a compatibility no-op.
+
+All application workers must use the same authoritative database. Separate SQLite
+files in different containers are not shared coordination. Run security reads and
+writes against the writer, not an asynchronously replicated read-only database.
+Cache independence is **not** database-outage independence: database failures may
+fail the request, rather than silently discard enforcement state.
+Windows and deadlines use application time, so worker clocks must be synchronized.
+
+This design adds database work: normal requests read bans; authentication attempts
+update IP and optional account state; detected WAF violations update per-IP state.
+The shared global counter is disabled by default, avoiding an application-wide
+login-denial budget and lock hot spot. Explicitly enabling
+`rate_limiting[:global_attempts][:enabled]` restores it and its availability risk.
+Session resumption/generation checks add uncached database reads; locks revoke
+generations transactionally. Benchmark with the host application's traffic and pool
+size. No fixed throughput or latency guarantee is asserted.
+
+Concurrency regressions exercise separate database connections. The PostgreSQL 17
+and MySQL 8.4 full-suite jobs passed in
+[CI run 35353219531](https://github.com/AuditBadger-com/beskar/actions/runs/35353219531).
+The preceding run confirmed the MySQL schema repairs, then exposed stale ban reads and two
+test SQL-quoting assumptions. These failures were reproduced against an isolated
+local MySQL 8.4.11 server; repeated concurrency runs also exposed stale session
+cleanup during native account locking. After repair, the full MySQL and SQLite
+suites each pass 849 tests / 4,619 assertions with three existing MaxMind-data
+skips (Ruby 4.0.7, seed `20260918`). The MySQL concurrency suite also passes ten
+seeds (`101` through `1010`, in increments of `101`). New instance-extension and
+stale-session-association regressions fail before their fixes and pass after them.
+Production-load validation remains open.
+Local Docker access was denied, so MySQL ran with a project-local data directory
+and Unix socket, with TCP networking disabled; no system service was installed.
+`BESKAR_TEST_DATABASE_URL` selects an isolated test database; never
+point it at a production database (Rails test tasks can rebuild it).
+
+JSON columns use `default: -> { "('{}')" }`: MySQL requires a parenthesized
+expression for [JSON defaults](https://dev.mysql.com/doc/refman/8.4/en/data-type-defaults.html).
+SQLite and PostgreSQL accept this expression too. Model attributes also supply
+independent empty hashes because MySQL reports these defaults as SQL functions.
+When regenerating the dummy schema from SQLite, preserve these expressions and
+the `sessions.user_id` bigint type needed to match MySQL's default primary keys.
+Regression tests check both migrations and the checked-in schema's MySQL SQL,
+plus actual default values on the active test database.
+
+## Rate-limit semantics
+
+All recorded authentication attempts count, whether credentials succeed or fail.
+Each tier retains at most its configured limit of admitted timestamps; denied
+attempts do not grow that tier's sliding window. Other tiers still count the
+attempt while they have capacity. Results combine tiers using the latest retry
+deadline. Exponential backoff is an enforced deadline, not just a response hint.
+
+`:check`, `is_rate_limited?`, and `time_until_allowed` are read-only and do not
+escalate backoff. Backoff grows on denied calls that record attempts. Middleware
+previews do not grow authentication backoff. By default an authentication quota
+does not block unrelated page/API traffic from the same shared IP. Opting into
+`rate_limiting[:ip_attempts][:block_requests] = true` enables request-wide blocking
+and the five-denials/hour automatic ban. IP login quotas still affect shared-NAT
+users: size them for actual shared egress, and retain account limits. No default
+can distinguish every legitimate user from an attacker sharing an IP.
+
+`reset_rate_limit(ip_address:, user:, global: false)` clears the selected IP,
+account, and IP denial/backoff state in the current mode. Pass `global: true` to
+also reset the global counter. It does not remove bans. Monitor and enforcement
+state are separate; see [monitor mode](monitor-only-mode.md).
+
+The Devise database-password adapter now reserves and enforces all applicable
+limits before verifying credentials. Rails-native controllers must adopt the
+[explicit admission/session guards](../guides/authentication.md). Outcomes reuse the same
+request-local attempt, independently of optional audit persistence. Whitelisted
+requests record observation-only counters without consuming enforced capacity.
+
+Native account locks also use this table, with an internal automatic-unlock
+deadline or manual-only state. Their rows are retained for the account lifetime;
+expired-counter cleanup does not delete native lock authority.
+
+## Upgrade
+
+1. Copy the new migration with `bin/rails beskar:install:migrations`, then run
+   `bin/rails db:migrate` before starting the new application workers. Fresh installs
+   can use `bin/rails generate beskar:install`.
+2. Drain old workers during rollout. Old cache-based workers and new database-based
+   workers do not coordinate. Existing cache counters are not imported, so counting
+   windows restart; existing database bans remain in force.
+3. Review legacy bans. A temporary ban must have an expiry; a permanent ban is
+   active regardless of a legacy expiry timestamp. Permanent rows are never removed
+   by expired-ban cleanup. New saves normalize permanent expiry to nil. Inspect
+   malformed/CIDR IPs, alternate IPv6 spellings, and duplicate canonical addresses
+   in older data before rollout; new writes require canonical individual IPs.
+4. Review bans created by older monitor-mode versions before enabling enforcement.
+   Those rows are not automatically deleted or reclassified.
+5. Schedule `bin/rails beskar:cleanup_security_state` periodically (for example,
+   hourly). Expired rows are ignored immediately; cleanup only reclaims storage.
+   Audit events and active bans are not deleted by this task. Security-event
+   retention is separate: account deletion now retains events unchanged, with
+   no automatic expiry/purge. See [Audit lifecycle](../guides/audit-lifecycle.md).
+6. Upgrade Rails-native login controllers and existing-session readers using
+   [Authentication](../guides/authentication.md). The former logging-only calls cannot
+   prevent session creation. No additional migration beyond the shared-state
+   migration is needed for these native locks.
+7. For batch eight, also apply the administrative-action migration and configure
+   a trusted `audit_actor` for dashboard writes. See [Audit lifecycle](../guides/audit-lifecycle.md)
+   for required reasons, transactional history, and the old-worker drain requirement.
+
+## Verification
+
+Run with the project's current mise default Ruby:
+
+```sh
+mise exec -- env PARALLEL_WORKERS=1 bin/rails test
+mise exec -- bundle exec standardrb
+```
+
+Regression coverage includes null/unavailable caches, distinct IP/account keys,
+global coordination, atomic concurrent updates, long windows, backoff expiry,
+read-only checks, rollback, stale ban caches, canonical IPv6, permanent bans,
+monitor isolation, trusted proxy attribution, Rack headers, and migration copying.

data/docs/research/rust-performance-assessment.md

@@ -0,0 +1,69 @@
+# Rust performance assessment
+
+Assessed on 2026-09-11 against the current working tree, including uncommitted remediation changes. This records an exploratory assessment for future consideration; no Rust implementation was built or benchmarked.
+
+**There is room for a small Rust component, especially WAF matching and large IP/CIDR lists. Current evidence favors reducing database work before introducing Rust.** A broad rewrite is not justified by the measurements below.
+
+The intended constraints are performance improvements only, no Rust toolchain requirement for applications installing Beskar, precompiled binaries for supported platforms and architectures, and no net increase in request overhead.
+
+[Original project review](../audits/project-review.md) and [Archived project overview](../archive/project-documentation.md) describe an older architecture in several places. The current implementation and [State storage](../operations/state-storage.md) establish that ordinary requests query both bans and rate-limit state. Authentication attempts and WAF violations also perform transactional state updates. Translating their calculations to Rust would leave database round trips and lock contention in place.
+
+**Local measurements**
+
+A read-only diagnostic used Ruby 4.0.6 with YJIT, Rails 8.0.2.1, and local SQLite on Linux x86-64. It measured a single thread with warm code and database state, SQL query caching disabled, and logging suppressed. SQLite query-only mode prevented writes during the measurements.
+
+The clean request was `/products/42?sort=recent`, with an unbanned, unrestricted IP and two nonmatching whitelist CIDRs. The downstream endpoint returned a trivial HTTP 200 response. Each operation received 2,000 warmup iterations, followed by three timed batches of 10,000 iterations; the larger whitelist cases used batches of 1,000. Garbage collection ran before each batch and remained enabled during timing.
+
+| Operation | Approximate average time per operation |
+| --- | ---: |
+| WAF analysis, clean URL, all 55 patterns | 2.4 µs |
+| Whitelist lookup, 2 CIDRs | 1.2 µs |
+| Whitelist lookup, 100 CIDRs, no match | 5.1–5.2 µs |
+| Whitelist lookup, 1,000 CIDRs, no match | 40–41 µs |
+| Ban lookup | 26–29 µs |
+| IP rate-limit preview | 14–16 µs |
+| Complete clean middleware call, 2 CIDRs | 52–59 µs |
+| Device detection for one browser user agent | 7.8 µs |
+
+Ranges summarize batch averages across the diagnostic runs, not latency percentiles. The complete clean middleware call allocated approximately 310 Ruby objects, while its isolated WAF analysis allocated one. Instrumentation confirmed two SELECTs per clean middleware call: one for bans and one for IP rate-limit state.
+
+These measurements exclude the host application's real work, a full HTTP server stack, concurrent traffic, remote database latency, populated authentication history, and attack-path persistence. They are not production throughput or latency guarantees and do not establish a Rust speedup.
+
+Even eliminating the WAF computation entirely would save only about **4–5% of Beskar's measured clean-request overhead** in this setup. Its share of the full host request would be smaller. Large whitelist configurations present a more substantial CPU cost.
+
+**Candidates worth considering**
+
+| Component | Possible Rust implementation | Assessment |
+| --- | --- | --- |
+| [WAF matcher](../../lib/beskar/services/waf.rb) | Compile the rule set once, match through one native call, and return compact rule IDs | Best initial experiment, particularly as rule counts or input lengths grow; current short clean-path cost is already small |
+| [IP whitelist](../../lib/beskar/services/ip_whitelist.rb) | Compiled IPv4/IPv6 prefix tree, with exact-address lookup where appropriate | Promising for large lists; replacing linear scanning is the principal opportunity in either language |
+| [Device detection](../../lib/beskar/services/device_detector.rb) | Combine classification and extraction in one native operation | Secondary candidate because it mainly affects authentication rather than every ordinary request |
+| [Rate limiting](../../lib/beskar/services/rate_limiter.rb), [bans](../../app/models/beskar/banned_ip.rb), and audit persistence | Translate existing calculations and orchestration | Low priority: database round trips, transactions, and contention remain |
+| Risk arithmetic and geographic distance | Native numeric calculations | Small workloads; optimize history retrieval and repeated enrichment first |
+
+Rust's [RegexSet](https://docs.rs/regex/latest/regex/struct.RegexSet.html) can identify matching expressions in one pass, which fits the WAF's need to report matching rules without extracting captures. A performance-only port must preserve all matching rules, result ordering, case handling, encoding behavior, and path/query interpretation. Ruby and Rust regex semantics differ, and Rust's [regex crate](https://docs.rs/regex/latest/regex/) does not support arbitrary look-around or backreferences. Differential tests against the Ruby implementation are necessary; a literal pattern translation is insufficient.
+
+For IP lookup, native acceleration would also need to avoid rebuilding configuration or comparing the entire source list on each request. Configuration updates must preserve the existing invalidation contract. Process-local native counters or ban snapshots would require a separate coordination design to preserve cross-worker enforcement correctness.
+
+**Distribution without a Rust installation requirement**
+
+A Ruby native extension built with [Magnus](https://github.com/matsadler/magnus) and the [rb-sys distribution tooling](https://oxidize-rb.org/docs/deployment/) is a suitable approach. Rust would be a maintainer/CI build dependency; consuming applications would load the compiled library.
+
+- Publish platform-specific gems containing release binaries, allowing RubyGems/Bundler to select the applicable artifact.
+- Define and test the supported matrix explicitly: Linux x86-64 and ARM64 with glibc and musl, macOS Intel and Apple Silicon, and Windows if included in Beskar's supported platforms.
+- Cover supported Ruby ABIs as well as OS and CPU architecture. At assessment time, this repository's main CI matrix uses Ruby 3.4 and 4.0.6. Do not assume one extension binary covers all Ruby versions.
+- Account for minimum OS/libc versions and CPU instruction compatibility when building distributable binaries.
+- Keep a pure Ruby gem variant for unsupported combinations, without automatically requiring Rust compilation during installation. Verify its detection behavior matches the native implementation.
+- Test installation and execution of published artifacts in environments without a Rust toolchain.
+
+RubyGems supports platform-specific binary gems through the [platform attribute](https://guides.rubygems.org/specification-reference/#platform). Platform support would be an explicit release commitment, not a promise that one universal binary works everywhere.
+
+**Keeping request overhead small**
+
+Load the extension and compile its rule configuration once at boot. Select the native or Ruby implementation at boot as well. Use one native call per analysis, pass existing strings with minimal copying, and return a compact result. Construct detailed Ruby metadata only when a match needs it. Keep database access and enforcement decisions coordinated through the established authority.
+
+The Ruby/native boundary has a cost. Releasing the Ruby GVL, copying strings, or converting nested Ruby structures may cost more than a small calculation saves. The requirement should therefore be a measured net improvement, including allocations and tail latency, rather than a claim of zero overhead.
+
+Before implementing Rust, investigate repeated IP parsing and whitelist checks, eager debug-message construction, repeated configuration processing, and database access. Reducing database work must preserve the consistency guarantees introduced by the remediation; reinstating stale process-local enforcement caches would change behavior.
+
+If revisited, first establish representative benchmarks for clean requests, already-blocked requests, authentication attempts, large whitelists, long inputs, and WAF violations under concurrency. Measure p50/p95/p99 latency, CPU, allocations, database queries, and lock waits with the intended production backend. Then prototype only the WAF matcher and, if large lists are expected, the CIDR matcher. Retain Rust only if equivalent behavior and meaningful end-to-end gains justify maintaining the binary matrix.

data/lib/beskar/configuration.rb

@@ -1,10 +1,22 @@
 module Beskar
   class Configuration
-    attr_accessor :rate_limiting, :security_tracking, :risk_based_locking, :geolocation, :ip_whitelist, :waf, :authentication_models, :emergency_password_reset
+    class Error < ArgumentError; end
+    SECTIONS = %i[rate_limiting security_tracking risk_based_locking geolocation waf authentication_models emergency_password_reset notifications].freeze
+    LOCK_STRATEGIES = %i[devise_lockable rails_auth none].freeze
+    GEOLOCATION_PROVIDERS = %i[mock maxmind].freeze
+    attr_accessor :rate_limiting, :security_tracking, :risk_based_locking, :geolocation, :ip_whitelist, :waf, :authentication_models, :emergency_password_reset, :notifications, :monitor_only, :authenticate_admin, :audit_actor, :authorize_admin, :authorize_configuration
 
     def initialize
+      @monitor_only = false # Global monitor-only mode - logs everything but doesn't block
       @ip_whitelist = [] # Array of IP addresses or CIDR ranges
 
+      # Dashboard authentication - configure this to restrict access to the dashboard
+      # Example: config.authenticate_admin = proc { |request| request.env["warden"]&.authenticate(scope: :admin).present? }
+      @authenticate_admin = nil
+      @audit_actor = nil # Proc returning a stable opaque actor ID; required for dashboard writes
+      @authorize_admin = nil # (request, permission), controller context; nil denies every dashboard action
+      @authorize_configuration = nil # (opaque_actor), trusted host code; nil denies runtime changes
+
       # Authentication models configuration
       # Auto-detect by default, or can be explicitly configured
       @authentication_models = {
@@ -16,21 +28,33 @@ module Beskar
       @waf = {
         enabled: false,                  # Master switch for WAF
         auto_block: true,                # Automatically block IPs after threshold
-        block_threshold: 3,              # Number of violations before blocking
-        violation_window: 1.hour,        # Time window to count violations
-        block_durations: [ 1.hour, 6.hours, 24.hours, 7.days ], # Escalating block durations
-        permanent_block_after: 5,        # Permanent block after N violations (nil = never)
+        score_threshold: 150,            # Cumulative risk score before blocking (replaces block_threshold)
+        violation_window: 6.hours,       # Maximum time window to track violations
+        block_durations: [1.hour, 6.hours, 24.hours, 7.days], # Escalating block durations
+        permanent_block_after: 500,      # Permanent block after cumulative score reaches this (nil = never)
         create_security_events: true,    # Create SecurityEvent records
-        monitor_only: false              # If true, log but don't block (even if auto_block is true)
+        exception_detection: :suspicious, # :suspicious, :all (opt-in broad scoring), or :none
+        request_exclusions: [],          # {path: Regexp, methods: [...], categories: [...]}
+        record_not_found_exclusions: [], # Regex patterns to exclude from RecordNotFound detection
+        decay_enabled: true,             # Enable exponential decay of violation scores over time
+        decay_rates: {                   # Decay rates by severity (half-life in minutes)
+          critical: 360,                 # Critical violations: 6 hour half-life
+          high: 120,                     # High violations: 2 hour half-life
+          medium: 45,                    # Medium violations: 45 minute half-life
+          low: 15                        # Low violations: 15 minute half-life
+        },
+        max_violations_tracked: 50       # Maximum number of violations to track per IP (oldest pruned)
       }
       @security_tracking = {
         enabled: true,
         track_successful_logins: true,
         track_failed_logins: true,
-        auto_analyze_patterns: true
+        auto_analyze_patterns: false, # No built-in background analyzer. Opt in with a host Active Job.
+        analysis_job: nil
       }
       @rate_limiting = {
         ip_attempts: {
+          block_requests: false, # Authentication quotas do not block unrelated traffic behind a shared NAT
           limit: 10,
           period: 1.hour,
           exponential_backoff: true
@@ -41,6 +65,7 @@ module Beskar
           exponential_backoff: true
         },
         global_attempts: {
+          enabled: false, # Opt-in availability tradeoff: a distributed attacker can consume this shared budget
           limit: 100,
           period: 1.minute,
           exponential_backoff: false
@@ -49,11 +74,11 @@ module Beskar
       @risk_based_locking = {
         enabled: false,                    # Master switch for risk-based locking
         risk_threshold: 75,                # Lock account if risk score >= this value
-        lock_strategy: :devise_lockable,   # Strategy: :devise_lockable, :custom, :none
-        auto_unlock_time: 1.hour,          # Time until automatic unlock (if supported by strategy)
-        notify_user: true,                 # Send notification on lock
+        lock_strategy: :devise_lockable,   # Strategy: :devise_lockable, :rails_auth, :none
+        auto_unlock_time: 1.hour,          # Native lock duration; nil for manual unlock. Devise owns unlock_in.
+        notify_user: false,                # Opt-in email; configure notifications first
         log_lock_events: true,             # Create security event for locks
-        immediate_signout: false           # Sign out user immediately via Warden callback (requires :lockable)
+        immediate_signout: true            # Locked attempts are always denied; retained for compatibility
       }
       @geolocation = {
         provider: :mock,                   # Provider: :maxmind, :mock
@@ -65,10 +90,66 @@ module Beskar
         impossible_travel_threshold: 3,    # Reset after N impossible travel events in 24h
         suspicious_device_threshold: 5,    # Reset after N suspicious device events in 24h
         total_locks_threshold: 5,          # Reset after N total locks in 24h (any reason)
-        send_notification: true,           # Send email to user about reset
-        notify_security_team: true,        # Alert security team about automatic resets
+        send_notification: false,          # Opt-in recovery instructions via Action Mailer
+        notify_security_team: false,        # Opt-in security-team email
         require_manual_unlock: false       # Require manual admin unlock after reset
       }
+      @notifications = {
+        from: nil,                        # One sender mailbox; no example-address fallback
+        recovery_url: nil,                # HTTPS recovery entry page, not a token-bearing URL
+        security_team_recipients: []       # Separate message/job for each configured mailbox
+      }
+    end
+
+    # Section assignment overlays library defaults, not the previous section.
+    # Nested edits in a configure block instead retain the current settings.
+    SECTIONS.each do |section|
+      define_method(:"#{section}=") do |value|
+        raise Error, "#{section} must be a hash with symbol keys" unless value.is_a?(Hash)
+        defaults = Configuration.new.public_send(section)
+        instance_variable_set(:"@#{section}", defaults.deep_merge(value.deep_dup))
+      end
+    end
+
+    def initialize_copy(other)
+      super
+      SECTIONS.each { |section| instance_variable_set(:"@#{section}", other.public_send(section).deep_dup) }
+      @ip_whitelist = other.ip_whitelist.deep_dup
+    end
+
+    def validate!(resolve_jobs: true)
+      ConfigurationValidator.new(self).validate!(resolve_jobs: resolve_jobs)
+      self
+    end
+
+    def seal!
+      freeze_value = lambda do |value|
+        case value
+        when Hash
+          value.each { |key, item|
+            freeze_value.call(key)
+            freeze_value.call(item)
+          }
+          value.freeze
+        when Array
+          value.each { |item| freeze_value.call(item) }
+          value.freeze
+        when String, Regexp then value.freeze
+        end
+      end
+      (SECTIONS + [:ip_whitelist]).each { |name| freeze_value.call(public_send(name)) }
+      freeze
+    end
+
+    def analysis_job_class
+      configured = @security_tracking[:analysis_job]
+      job = configured.is_a?(String) ? configured.safe_constantize : configured
+      unless job.is_a?(Class) && job < ActiveJob::Base
+        raise Error, "security_tracking.analysis_job must identify a host ActiveJob::Base subclass"
+      end
+      job
+    rescue NameError
+      raise Error, "security_tracking.analysis_job could not be loaded"
     end
 
     def security_tracking_enabled?
@@ -97,15 +178,17 @@ module Beskar
     end
 
     def lock_strategy
-      @risk_based_locking[:lock_strategy] || :devise_lockable
+      strategy = @risk_based_locking[:lock_strategy]
+      raise Error, "risk_based_locking.lock_strategy must be devise_lockable, rails_auth, or none" unless LOCK_STRATEGIES.include?(strategy)
+      strategy
     end
 
     def auto_unlock_time
-      @risk_based_locking[:auto_unlock_time] || 1.hour
+      @risk_based_locking.fetch(:auto_unlock_time, 1.hour)
     end
 
     def notify_user_on_lock?
-      @risk_based_locking[:notify_user] != false
+      @risk_based_locking[:notify_user] == true
     end
 
     def log_lock_events?
@@ -135,11 +218,12 @@ module Beskar
     end
 
     def waf_auto_block?
-      waf_enabled? && @waf[:auto_block] && !@waf[:monitor_only]
+      waf_enabled? && @waf[:auto_block] && !@monitor_only
     end
 
-    def waf_monitor_only?
-      @waf[:monitor_only] == true
+    # General monitor-only mode check (affects all blocking)
+    def monitor_only?
+      @monitor_only == true
     end
 
     # IP Whitelist configuration helpers
@@ -179,7 +263,7 @@ module Beskar
           end
         rescue => e
           # Ignore errors during detection
-          Rails.logger.debug "[Beskar] Error detecting Rails auth model #{model.name}: #{e.message}"
+          Beskar::Logger.debug("Error detecting Rails auth model #{model.name}: #{e.class}")
         end
       end
 
@@ -192,6 +276,7 @@ module Beskar
     end
 
     def model_class_for_scope(scope)
+      return Devise.mappings[scope.to_sym].to if defined?(Devise) && scope && Devise.mappings.key?(scope.to_sym)
       scope.to_s.camelize.constantize
     rescue NameError
       nil

data/lib/beskar/configuration_validator.rb

@@ -0,0 +1,188 @@
+require "ipaddr"
+require "uri"
+require "mail"
+
+module Beskar
+  # Validation errors name known setting paths, never supplied values/secrets.
+  # Pure configuration checks do not query application models or Rails.cache.
+  class ConfigurationValidator
+    def initialize(configuration)
+      @config = configuration
+    end
+
+    def validate!(resolve_jobs: true)
+      defaults = Configuration.new
+      Configuration::SECTIONS.each do |section|
+        shape(@config.public_send(section), defaults.public_send(section), section.to_s)
+      end
+      boolean(@config.monitor_only, "monitor_only")
+      invalid!("authenticate_admin", "must be a Proc or nil") unless @config.authenticate_admin.nil? || @config.authenticate_admin.is_a?(Proc)
+      invalid!("audit_actor", "must be a Proc or nil") unless @config.audit_actor.nil? || @config.audit_actor.is_a?(Proc)
+      %i[authorize_admin authorize_configuration].each do |name|
+        value = @config.public_send(name)
+        invalid!(name.to_s, "must be a Proc or nil") unless value.nil? || value.is_a?(Proc)
+      end
+      whitelist
+      waf
+      locking
+      geolocation
+      auth_models
+      analysis_job(resolve_jobs)
+      validate_notifications!
+      true
+    end
+
+    # Also checked by delivery workers, since low-level configuration is mutable.
+    def validate_notifications!
+      settings = @config.notifications
+      shape(settings, Configuration.new.notifications, "notifications")
+      sender = settings[:from]
+      invalid!("notifications.from", "must be one email address") unless sender.nil? || self.class.mailbox?(sender)
+      recipients = settings[:security_team_recipients]
+      unless recipients.size <= 20 && recipients.all? { |item| self.class.mailbox?(item) }
+        invalid!("notifications.security_team_recipients", "must contain at most 20 email addresses")
+      end
+      url = settings[:recovery_url]
+      invalid!("notifications.recovery_url", "must be an HTTPS entry-page URL without credentials, query, or fragment") unless url.nil? || self.class.recovery_url?(url)
+
+      user_delivery = @config.notify_user_on_lock? || @config.emergency_password_reset[:send_notification] == true
+      team_delivery = @config.emergency_password_reset[:notify_security_team] == true
+      invalid!("notifications.from", "is required when notifications are enabled") if (user_delivery || team_delivery) && sender.nil?
+      invalid!("notifications.recovery_url", "is required for user notifications") if user_delivery && url.nil?
+      invalid!("notifications.security_team_recipients", "must not be empty when team notifications are enabled") if team_delivery && recipients.empty?
+      true
+    end
+
+    def self.mailbox?(value)
+      return false unless value.is_a?(String) && value.bytesize <= 254 && value.match?(/\A[^\s<>@,;]+@[^\s<>@,;]+\z/)
+      parsed = Mail::Address.new(value)
+      parsed.address == value && parsed.domain.present?
+    rescue Mail::Field::ParseError
+      false
+    end
+
+    def self.recovery_url?(value)
+      return false unless value.is_a?(String) && value.bytesize <= 2048 && !value.match?(/[[:cntrl:]]/)
+      uri = URI.parse(value)
+      uri.is_a?(URI::HTTPS) && uri.host.present? && uri.userinfo.nil? && uri.query.nil? && uri.fragment.nil?
+    rescue URI::InvalidURIError
+      false
+    end
+
+    private
+
+    def invalid!(path, message)
+      raise Configuration::Error, "#{path} #{message}"
+    end
+
+    def shape(value, defaults, path)
+      invalid!(path, "must be a hash with symbol keys") unless value.is_a?(Hash)
+      invalid!(path, "contains unknown or non-symbol keys") unless (value.keys - defaults.keys).empty?
+      defaults.each do |key, default|
+        child = "#{path}.#{key}"
+        invalid!(child, "is missing") unless value.key?(key)
+        item = value[key]
+        case default
+        when Hash then shape(item, default, child)
+        when TrueClass, FalseClass then boolean(item, child)
+        when ActiveSupport::Duration then positive(item, child, optional: key == :auto_unlock_time)
+        when Numeric
+          if child == "risk_based_locking.risk_threshold"
+            invalid!(child, "must be a finite number between 0 and 100") unless number?(item) && (0..100).cover?(item)
+          else
+            positive(item, child, optional: key == :permanent_block_after)
+            if [:limit, :max_violations_tracked, :impossible_travel_threshold, :suspicious_device_threshold, :total_locks_threshold].include?(key)
+              invalid!(child, "must be an integer") unless item.is_a?(Integer)
+            end
+          end
+        when Array then invalid!(child, "must be an array") unless item.is_a?(Array)
+        end
+      end
+    end
+
+    def number?(value)
+      value.is_a?(Numeric) && value.real? && value.finite?
+    end
+
+    def positive(value, path, optional: false)
+      return if optional && value.nil?
+      numeric = value.is_a?(ActiveSupport::Duration) ? value.to_f : value
+      invalid!(path, "must be finite and positive#{" or nil" if optional}") unless number?(numeric) && numeric.positive?
+    end
+
+    def boolean(value, path)
+      invalid!(path, "must be true or false") unless value == true || value == false
+    end
+
+    def whitelist
+      invalid!("ip_whitelist", "must be an array") unless @config.ip_whitelist.is_a?(Array)
+      @config.ip_whitelist.each_with_index do |entry, index|
+        path = "ip_whitelist[#{index}]"
+        invalid!(path, "must be an IP address or CIDR string") unless entry.is_a?(String) && entry.present?
+        begin
+          IPAddr.new(entry.strip)
+        rescue IPAddr::Error
+          invalid!(path, "must be a valid IP address or CIDR")
+        end
+      end
+    end
+
+    def waf
+      settings = @config.waf
+      invalid!("waf.exception_detection", "must be suspicious, all, or none") unless %i[suspicious all none].include?(settings[:exception_detection])
+      invalid!("waf.block_durations", "must not be empty") if settings[:block_durations].empty?
+      settings[:block_durations].each_with_index { |value, index| positive(value, "waf.block_durations[#{index}]") }
+      regexps(settings[:record_not_found_exclusions], "waf.record_not_found_exclusions")
+      categories = Services::Waf::VULNERABILITY_PATTERNS.keys + Services::Waf::EXCEPTION_RULES.values.map(&:first) + [:malformed_path]
+      settings[:request_exclusions].each_with_index do |rule, index|
+        path = "waf.request_exclusions[#{index}]"
+        invalid!(path, "must be a hash with path, methods, and/or categories") unless rule.is_a?(Hash) && (rule.keys - %i[path methods categories]).empty?
+        invalid!("#{path}.path", "must be a Regexp") unless rule[:path].is_a?(Regexp)
+        if rule.key?(:methods)
+          valid = rule[:methods].is_a?(Array) && rule[:methods].all? do |item|
+            (item.is_a?(String) || item.is_a?(Symbol)) && %w[GET HEAD POST PUT PATCH DELETE OPTIONS CONNECT TRACE OTHER].include?(item.to_s.upcase)
+          end
+          invalid!("#{path}.methods", "must contain HTTP method names") unless valid
+        end
+        if rule.key?(:categories)
+          invalid!("#{path}.categories", "must contain known WAF categories") unless rule[:categories].is_a?(Array) && rule[:categories].all? { |item| categories.any? { |category| category.to_s == item.to_s } }
+        end
+      end
+    end
+
+    def regexps(values, path)
+      invalid!(path, "must contain only Regexp entries") unless values.all? { |value| value.is_a?(Regexp) }
+    end
+
+    def locking
+      @config.lock_strategy
+    end
+
+    def geolocation
+      settings = @config.geolocation
+      invalid!("geolocation.provider", "must be mock or maxmind") unless Configuration::GEOLOCATION_PROVIDERS.include?(settings[:provider])
+      path = settings[:maxmind_city_db_path]
+      invalid!("geolocation.maxmind_city_db_path", "must be a path string or nil") unless path.nil? || path.is_a?(String)
+      if settings[:provider] == :maxmind
+        readable = path.present? && !path.include?("\0") && File.file?(path) && File.readable?(path)
+        invalid!("geolocation.maxmind_city_db_path", "must identify a readable database file") unless readable
+      end
+    end
+
+    def auth_models
+      %i[devise rails_auth].each do |kind|
+        names = @config.authentication_models[kind]
+        invalid!("authentication_models.#{kind}", "must contain scope names") unless names.all? { |name| (name.is_a?(String) || name.is_a?(Symbol)) && name.to_s.match?(/\A[a-zA-Z]\w*(?:(?:::|\/)\w+)*\z/) }
+      end
+    end
+
+    def analysis_job(resolve)
+      job = @config.security_tracking[:analysis_job]
+      valid = job.nil? || job.is_a?(Class) || (job.is_a?(String) && job.match?(/\A[A-Z]\w*(?:::[A-Z]\w*)*\z/))
+      invalid!("security_tracking.analysis_job", "must be a job class, class name, or nil") unless valid
+      return unless @config.auto_analyze_patterns?
+      invalid!("security_tracking.analysis_job", "is required when automatic analysis is enabled") unless job
+      @config.analysis_job_class if resolve || job.is_a?(Class)
+    end
+  end
+end

data/lib/beskar/devise_authentication.rb

@@ -0,0 +1,24 @@
+module Beskar
+  # Only the password strategy is intercepted. Warden's before_failure callback
+  # also runs for protected-page visits without credentials, so it cannot safely
+  # serve as an admission hook.
+  module DeviseAuthentication
+    def authenticate!
+      model = mapping.to
+      return super unless model.respond_to?(:track_failed_authentication)
+
+      resource = model.find_for_database_authentication(authentication_hash)
+      attempt = Services::AuthenticationAttempt.reserve(request, model: model, scope: scope,
+        user: resource, credentials: authentication_hash, cache: true)
+      resource ? attempt.bind_user!(resource) : attempt.bind_identity!(model, authentication_hash)
+      unless attempt.allowed?
+        model.track_failed_authentication(request, scope, attempt: attempt)
+        return custom!(attempt.response)
+      end
+      super
+    rescue Services::AuthenticationAttempt::Unavailable, ActiveRecord::ActiveRecordError => error
+      Beskar::Logger.error("Authentication admission unavailable (#{error.class})")
+      custom!(Services::AuthenticationAttempt.unavailable_response)
+    end
+  end
+end