beskar 0.1.0 → 0.2.1

data/lib/beskar/services/location_assessment.rb

@@ -0,0 +1,109 @@
+require "time"
+
+module Beskar
+  module Services
+    # Observations pair a location with its own occurred_at and event_id. Never
+    # apply one timestamp to a collection of unrelated historical locations.
+    class LocationAssessment
+      MAX_SPEED_KMH = 1000
+
+      def self.normalize(location)
+        location = location.is_a?(Hash) ? location.deep_symbolize_keys : {}
+        lat, lon = number(location[:latitude]), number(location[:longitude])
+        if lat && lon && lat.between?(-90, 90) && lon.between?(-180, 180)
+          location.merge(latitude: lat, longitude: lon)
+        else
+          location.merge(latitude: nil, longitude: nil)
+        end
+      end
+
+      def self.number(value)
+        number = Float(value, exception: false)
+        number if number&.finite?
+      end
+
+      def self.timestamp(value)
+        value = Time.iso8601(value) if value.is_a?(String)
+        value = value.to_time.to_f if value.respond_to?(:to_time)
+        number(value)
+      rescue ArgumentError
+        nil
+      end
+
+      def self.coordinates(location)
+        location = normalize(location)
+        return if location[:private_ip] == true || %w[Private Unknown].include?(location[:country])
+        return if location[:provider].to_s == "mock"
+        lat, lon = number(location[:latitude]), number(location[:longitude])
+        [lat, lon] if lat && lon && lat.between?(-90, 90) && lon.between?(-180, 180)
+      end
+
+      def initialize(location, observations: [], at: Time.current)
+        @location = self.class.normalize(location)
+        @at = self.class.timestamp(at)
+        @observations = observations.filter_map do |observation|
+          next unless observation.is_a?(Hash)
+          observation = observation.symbolize_keys
+          time = self.class.timestamp(observation[:occurred_at])
+          next unless @at && time && time < @at
+          {location: self.class.normalize(observation[:location]), occurred_at: time, event_id: observation[:event_id]}
+        end.sort_by { |observation| [observation[:occurred_at], observation[:event_id].to_i] }.reverse
+      end
+
+      def call
+        factors = []
+        location = @location.merge(impossible_travel: false, country_change: false)
+        status = if @location[:private_ip] == true || @location[:country] == "Private"
+          "private"
+        elsif @location[:provider].to_s == "mock"
+          "synthetic"
+        elsif self.class.coordinates(@location) || known_country?(@location)
+          "available"
+        else
+          "unknown"
+        end
+        if %w[private unknown].include?(status)
+          factors << {name: "location_unavailable", points: 10, evidence: {status: status}}
+        elsif status == "available"
+          previous = @observations.find { |entry| self.class.coordinates(entry[:location]) }
+          if previous && (current_coordinates = self.class.coordinates(@location))
+            elapsed = @at - previous[:occurred_at]
+            distance = GeolocationService.calculate_distance(*current_coordinates, *self.class.coordinates(previous[:location]))
+            evidence = {previous_event_id: previous[:event_id], previous_at: Time.at(previous[:occurred_at]).utc.iso8601(6),
+                        elapsed_seconds: elapsed, distance_km: distance.round(3), max_speed_kmh: MAX_SPEED_KMH}
+            location[:travel] = evidence
+            if distance > MAX_SPEED_KMH * elapsed / 3600.0
+              location[:impossible_travel] = true
+              factors << {name: "impossible_travel", points: 25, evidence: evidence}
+            end
+          end
+          previous_country = @observations.find { |entry| known_country?(entry[:location]) }
+          if known_country?(@location) && previous_country && country_changed?(previous_country[:location])
+            location[:country_change] = true
+            factors << {name: "country_change", points: 10,
+                        evidence: {previous_event_id: previous_country[:event_id], previous_country: previous_country[:location][:country],
+                                   current_country: @location[:country]}}
+          end
+        end
+        total = factors.sum { |factor| factor[:points] }
+        factors << {name: "geolocation_cap", points: 30 - total, evidence: {cap: 30}} if total > 30
+        {location: location.merge(assessment_status: status), score: [total, 30].min, factors: factors}
+      end
+
+      private
+
+      def known_country?(location)
+        location[:provider].to_s != "mock" && location[:private_ip] != true &&
+          location[:country].present? && !%w[Unknown Private].include?(location[:country])
+      end
+
+      def country_changed?(previous)
+        if previous[:country_code].present? && @location[:country_code].present?
+          previous[:country_code].to_s.upcase != @location[:country_code].to_s.upcase
+        else
+          previous[:country].to_s.downcase != @location[:country].to_s.downcase
+        end
+      end
+    end
+  end
+end

data/lib/beskar/services/native_account_lock.rb

@@ -0,0 +1,82 @@
+module Beskar
+  module Services
+    # Persistent Rails-native locks and session creation serialize on one row.
+    # unlock_at lives in data: merely checking/creating a session must never
+    # prolong a finite lock, and manual locks must not expire through cleanup.
+    class NativeAccountLock
+      def self.key(user)
+        raise ArgumentError, "Account must be persisted" unless user.persisted?
+        "account_lock:#{user.class.base_class.name}:#{user.id}"
+      end
+
+      def self.locked_data?(data)
+        data["locked"] && (!data["unlock_at"] || data["unlock_at"] > Time.current.to_f)
+      end
+
+      def self.locked?(user)
+        SecurityState.uncached { !!locked_data?(SecurityState.read(key(user))) }
+      end
+
+      def self.lock!(user, duration:, metadata: {})
+        return false unless RequestContext.enforce?(metadata[:ip_address] || metadata["ip_address"])
+        raise ArgumentError, "Unlock duration must be positive or nil" if duration && !duration.to_f.positive?
+        cleanup_error = nil
+        result = SecurityState.mutate(key(user), ttl: nil) do |state|
+          cleanup_error = nil
+          data = state.fetch(key(user))
+          next false if locked_data?(data)
+          data.replace("locked" => true, "locked_at" => Time.current.iso8601,
+            "unlock_at" => duration && Time.current.to_f + duration.to_f, "context" => AuditData.metadata(metadata))
+          SessionRevocation.rotate!(data)
+          # Every database session, including the current one, is revoked.
+          begin
+            user.class.transaction(requires_new: true) { revoke_sessions!(user) }
+          rescue => error
+            # A host callback must not prevent the authoritative lock. Session
+            # readers deny access until cleanup succeeds during explicit unlock;
+            # automatic expiry must never reactivate unrevoked old sessions.
+            cleanup_error = error
+            data.merge!("session_cleanup_pending" => true, "unlock_at" => nil)
+          end
+          true
+        end
+        Beskar::Logger.error("Locked account; session cleanup failed (#{cleanup_error.class})") if cleanup_error
+        result
+      end
+
+      def self.require_manual_unlock!(user)
+        SecurityState.mutate(key(user), ttl: nil) do |state|
+          state.fetch(key(user)).merge!("locked" => true, "unlock_at" => nil, "locked_at" => Time.current.iso8601)
+        end
+      end
+
+      def self.unlock!(user)
+        SecurityState.mutate(key(user), ttl: nil) do |state|
+          data = state.fetch(key(user))
+          revoke_sessions!(user) if data["session_cleanup_pending"]
+          data.replace(data.slice("generation"))
+        end
+        true
+      end
+
+      def self.revoke_sessions!(user)
+        sessions = user.sessions
+        # Bypass both a loaded association and MySQL's earlier transaction
+        # snapshot. Keep association removal and model destruction callbacks.
+        sessions.destroy(sessions.lock.to_a)
+        sessions.reset
+        # A host callback can abort removal. Verify against a current read too.
+        raise ActiveRecord::RecordNotDestroyed, "Account sessions could not be revoked" if sessions.lock.exists?
+      end
+
+      def self.with_session(user, request, generation: nil)
+        SecurityState.mutate(key(user), ttl: nil) do |state|
+          next false if generation && generation != state.fetch(key(user)).fetch("generation", "0")
+          next false if RequestContext.enforce?(RequestContext.ip(request)) && locked_data?(state.fetch(key(user)))
+          yield
+          true
+        end
+      end
+    end
+  end
+end

data/lib/beskar/services/notifications.rb

@@ -0,0 +1,46 @@
+module Beskar
+  module Services
+    # Optional delivery, separate from the synchronous security decision. No
+    # password, token, email address, request metadata, or model is serialized.
+    class Notifications
+      class DeliveryError < StandardError; end
+
+      def self.enabled?(kind)
+        case kind
+        when "account_locked" then Beskar.configuration.notify_user_on_lock?
+        when "emergency_password_reset" then Beskar.configuration.emergency_password_reset[:send_notification] == true
+        when "security_team_reset" then Beskar.configuration.emergency_password_reset[:notify_security_team] == true
+        else raise Configuration::Error, "Unsupported notification kind"
+        end
+      end
+
+      def self.enqueue(user, kind)
+        return unless enabled?(kind)
+        raise ArgumentError, "Notification account must be persisted" unless user.persisted?
+        arguments = {user_type: user.class.base_class.name, user_id: user.id, kind: kind}
+        after_commit do
+          ConfigurationValidator.new(Beskar.configuration).validate_notifications!
+          # Indices keep addresses out of queue arguments. A separate job per
+          # recipient prevents one failed address from retrying all recipients.
+          indices = (kind == "security_team_reset") ? Beskar.configuration.notifications[:security_team_recipients].each_index.to_a : [nil]
+          indices.each do |index|
+            job = Beskar::NotificationJob.perform_later(**arguments, recipient_index: index)
+            Beskar::Logger.warn("Security notification was not enqueued") unless job
+          rescue => error
+            Beskar::Logger.warn("Security notification enqueue failed (#{error.class})")
+          end
+        end
+      rescue => error
+        Beskar::Logger.warn("Security notification preparation failed (#{error.class})")
+      end
+
+      def self.after_commit(&block)
+        ActiveRecord.after_all_transactions_commit do
+          block.call
+        rescue => error
+          Beskar::Logger.warn("Security notification dispatch failed (#{error.class})")
+        end
+      end
+    end
+  end
+end

data/lib/beskar/services/rate_limiter.rb

@@ -13,175 +13,150 @@ module Beskar
           exponential_backoff: true
         },
         global_attempts: {
+          enabled: false,
           limit: 100,
           period: 1.minute
         }
       }.freeze
 
-      class << self
-        def check_authentication_attempt(request, result, user = nil)
-          ip_address = request.ip
-
-          # Check IP-based rate limiting
-          ip_result = check_ip_rate_limit(ip_address)
-
-          # Check account-based rate limiting if we have a user
-          account_result = user ? check_account_rate_limit(user) : {allowed: true}
-
-          # Check global rate limiting to prevent system overload
-          global_result = check_global_rate_limit
+      BACKOFF_DELAYS = [60, 300, 900, 3600, 14400, 86400].freeze
 
-          # Record the attempt
-          record_attempt(ip_address, result, user)
+      class << self
+        # Atomically reserve capacity across every applicable tier. :check is a
+        # read-only preview: it never counts an attempt or escalates backoff.
+        def check_authentication_attempt(request, result, user = nil, account_key: nil)
+          keys = keys_for(RequestContext.ip(request), user, account_key: account_key)
+          return preview(keys) if result == :check
 
-          # Return most restrictive result
-          most_restrictive_result([ip_result, account_result, global_result])
+          reserve(keys)
         end
 
         def check_ip_rate_limit(ip_address)
-          config = Beskar.configuration.rate_limiting&.dig(:ip_attempts) || DEFAULT_CONFIG[:ip_attempts]
-          cache_key = "beskar:ip_attempts:#{ip_address}"
-          check_rate_limit(cache_key, config)
+          preview(keys_for(ip_address).slice(:ip_attempts))
         end
 
         def check_account_rate_limit(user)
-          config = Beskar.configuration.rate_limiting&.dig(:account_attempts) || DEFAULT_CONFIG[:account_attempts]
-          cache_key = "beskar:account_attempts:#{user.class.name}:#{user.id}"
-          check_rate_limit(cache_key, config)
+          preview(keys_for(nil, user).slice(:account_attempts))
+        end
+
+        def reserve_account(user, ip_address: nil, account_key: nil)
+          reserve(keys_for(ip_address, user, account_key: account_key).slice(:account_attempts))
         end
 
         def check_global_rate_limit
-          config = Beskar.configuration.rate_limiting&.dig(:global_attempts) || DEFAULT_CONFIG[:global_attempts]
-          cache_key = "beskar:global_attempts"
-          check_rate_limit(cache_key, config)
+          preview(keys_for(nil).slice(:global_attempts))
         end
 
         def is_rate_limited?(request, user = nil)
-          result = check_authentication_attempt(request, :check, user)
-          !result[:allowed]
+          !check_authentication_attempt(request, :check, user)[:allowed]
         end
 
         def time_until_allowed(request, user = nil)
-          result = check_authentication_attempt(request, :check, user)
-          result[:retry_after] || 0
+          check_authentication_attempt(request, :check, user)[:retry_after] || 0
         end
 
-        def reset_rate_limit(ip_address: nil, user: nil)
+        def reset_rate_limit(ip_address: nil, user: nil, global: false)
+          keys = keys_for(ip_address, user)
+          keys.delete(:global_attempts) unless global
           if ip_address
-            Rails.cache.delete("beskar:ip_attempts:#{ip_address}")
-            Rails.cache.delete("beskar:ip_backoff:#{ip_address}")
+            mode = Beskar.configuration.monitor_only? ? "observe" : "enforce"
+            keys[:denials] = "rate_denials:#{mode}:#{IPAddr.new(ip_address.to_s)}"
           end
+          return if keys.empty?
 
-          if user
-            cache_key = "beskar:account_attempts:#{user.class.name}:#{user.id}"
-            Rails.cache.delete(cache_key)
-            Rails.cache.delete("beskar:account_backoff:#{user.class.name}:#{user.id}")
-          end
+          SecurityState.mutate(keys.values, ttl: 1.second) { |state| state.each_value(&:clear) }
         end
 
         private
 
-        def check_rate_limit(cache_key, config)
-          now = Time.current.to_i
-          period = config[:period].to_i
-          limit = config[:limit]
-          window_start = now - period
-
-          # Get current window data
-          window_data = Rails.cache.read(cache_key) || {}
-
-          # Clean old entries
-          cleaned_data = window_data.select { |timestamp, _| timestamp.to_i > window_start }
+        def keys_for(ip_address, user = nil, account_key: nil)
+          keys = {}
+          mode = (Beskar.configuration.monitor_only? || IpWhitelist.whitelisted?(ip_address)) ? "observe" : "enforce"
+          keys[:ip_attempts] = "rate:#{mode}:ip:#{IPAddr.new(ip_address.to_s)}" if ip_address
+          keys[:account_attempts] = "rate:#{mode}:account:#{user.class.name}:#{user.id}" if user
+          keys[:account_attempts] ||= "rate:#{mode}:account:#{account_key}" if account_key
+          keys[:global_attempts] = "rate:#{mode}:global" if config_for(:global_attempts)[:enabled]
+          keys
+        end
 
-          # Update cache with cleaned data if it changed
-          if cleaned_data != window_data
-            if cleaned_data.empty?
-              Rails.cache.delete(cache_key)
-            else
-              Rails.cache.write(cache_key, cleaned_data, expires_in: period + 60)
-            end
+        def config_for(tier)
+          config = DEFAULT_CONFIG.fetch(tier).merge(Beskar.configuration.rate_limiting&.dig(tier) || {})
+          unless config[:limit].is_a?(Integer) && config[:limit].positive? && config[:period].to_f.positive?
+            raise ArgumentError, "Rate limits require a positive integer limit and positive period (#{tier})"
           end
+          config
+        end
 
-          current_count = cleaned_data.values.sum
-
-          # Check if we're over the limit
-          if current_count >= limit
-            # Calculate retry after time with exponential backoff if configured
-            retry_after = calculate_retry_after(cache_key, config, current_count, limit)
+        def preview(keys)
+          now = Time.current.to_f
+          most_restrictive_result(keys.map do |tier, key|
+            evaluate(SecurityState.read(key), config_for(tier), now).merge(tier: tier)
+          end)
+        end
 
-            reset_time = if cleaned_data.empty?
-              Time.at(now + period)
-            else
-              Time.at(cleaned_data.keys.map(&:to_i).min + period)
+        def reserve(keys)
+          # No applicable tier (for example an addressless request with global
+          # limiting disabled): nothing to count, so admission is a no-op.
+          return most_restrictive_result([]) if keys.empty?
+
+          configs = keys.to_h { |tier, _| [tier, config_for(tier)] }
+          ttl = [configs.values.map { |config| config[:period].to_f }.max, BACKOFF_DELAYS.last].max + 60
+          SecurityState.mutate(keys.values, ttl: ttl) do |state|
+            now = Time.current.to_f
+            results = keys.map do |tier, key|
+              config = configs.fetch(tier)
+              data = state.fetch(key)
+              data["attempts"] = recent_attempts(data, config, now)
+              result = evaluate(data, config, now)
+              if result[:allowed]
+                data.delete("denials")
+                data.delete("blocked_until")
+                # Bounded to the configured limit: denied traffic never grows the
+                # sliding window indefinitely or resets its expiration.
+                data["attempts"] << now
+              elsif config[:exponential_backoff]
+                index = [data.fetch("denials", 0), BACKOFF_DELAYS.length - 1].min
+                data["denials"] = [index + 1, BACKOFF_DELAYS.length].min
+                data["blocked_until"] = [data.fetch("blocked_until", 0), now + BACKOFF_DELAYS[index]].max
+                result = evaluate(data, config, now)
+              end
+              result.merge(tier: tier)
             end
-
-            {
-              allowed: false,
-              count: current_count,
-              limit: limit,
-              reset_time: reset_time,
-              retry_after: retry_after,
-              reason: "rate_limit_exceeded"
-            }
-          else
-            {
-              allowed: true,
-              count: current_count,
-              limit: limit,
-              remaining: limit - current_count
-            }
+            most_restrictive_result(results)
           end
         end
 
-        def record_attempt(ip_address, result, user)
-          return if result == :check # Don't record check operations
-
-          now = Time.current.to_i
-
-          # Record IP attempt
-          ip_cache_key = "beskar:ip_attempts:#{ip_address}"
-          record_attempt_in_cache(ip_cache_key, now)
-
-          # Record account attempt if user exists
-          if user
-            account_cache_key = "beskar:account_attempts:#{user.class.name}:#{user.id}"
-            record_attempt_in_cache(account_cache_key, now)
-          end
-
-          # Record global attempt
-          global_cache_key = "beskar:global_attempts"
-          record_attempt_in_cache(global_cache_key, now, 1.minute)
+        def recent_attempts(data, config, now)
+          Array(data["attempts"]).select { |timestamp| timestamp > now - config[:period].to_f }
         end
 
-        def record_attempt_in_cache(cache_key, timestamp, expiry = 1.hour)
-          window_data = Rails.cache.read(cache_key) || {}
-          window_data[timestamp] = (window_data[timestamp] || 0) + 1
-          Rails.cache.write(cache_key, window_data, expires_in: expiry + 60)
+        def evaluate(data, config, now)
+          attempts = recent_attempts(data, config, now)
+          count = attempts.size
+          deadline = data.fetch("blocked_until", 0)
+          if count >= config[:limit]
+            # Enough entries must expire to bring the count below the limit.
+            deadline = [deadline, attempts.sort[count - config[:limit]] + config[:period].to_f].max
+          end
+          if deadline > now
+            {allowed: false, count: count, limit: config[:limit], remaining: 0,
+             reset_time: Time.at(deadline), retry_after: (deadline - now).ceil, reason: "rate_limit_exceeded"}
+          else
+            {allowed: true, count: count, limit: config[:limit], remaining: config[:limit] - count}
+          end
         end
 
-        def calculate_retry_after(cache_key, config, current_count, limit)
-          return 0 unless config[:exponential_backoff]
-
-          backoff_key = cache_key.gsub("_attempts:", "_backoff:")
-          failure_count = Rails.cache.read(backoff_key) || 0
-
-          # Increment failure count
-          Rails.cache.write(backoff_key, failure_count + 1, expires_in: 1.hour)
-
-          # Exponential backoff: 1min, 5min, 15min, 1hour, 4hours, 24hours
-          base_delays = [60, 300, 900, 3600, 14400, 86400] # in seconds
-          delay_index = [failure_count, base_delays.length - 1].min
-
-          base_delays[delay_index]
+        # Compatibility for callers that record an outcome directly.
+        def record_attempt(ip_address, result, user)
+          reserve(keys_for(ip_address, user)) unless result == :check
         end
 
         def most_restrictive_result(results)
-          # Find the most restrictive (not allowed) result
-          restricted = results.find { |r| !r[:allowed] }
-          return restricted if restricted
+          return {allowed: true, count: 0, remaining: Float::INFINITY, disabled: true} if results.empty?
+          denied = results.reject { |result| result[:allowed] }
+          return denied.max_by { |result| result[:retry_after] } if denied.any?
 
-          # If all are allowed, return the one with the lowest remaining count
-          results.min_by { |r| r[:remaining] || Float::INFINITY }
+          results.min_by { |result| result[:remaining] }
         end
       end
 
@@ -193,21 +168,24 @@ module Beskar
 
       def allowed?
         self.class.check_ip_rate_limit(@ip_address)[:allowed] &&
-          (@user.nil? || self.class.check_account_rate_limit(@user)[:allowed])
+          (@user.nil? || self.class.check_account_rate_limit(@user)[:allowed]) &&
+          self.class.check_global_rate_limit[:allowed]
       end
 
       def attempts_remaining
         ip_result = self.class.check_ip_rate_limit(@ip_address)
         account_result = @user ? self.class.check_account_rate_limit(@user) : {remaining: Float::INFINITY}
 
-        [ip_result[:remaining] || 0, account_result[:remaining] || 0].min
+        global_result = self.class.check_global_rate_limit
+        [ip_result[:remaining] || 0, account_result[:remaining] || 0, global_result[:remaining] || 0].min
       end
 
       def time_until_reset
         ip_result = self.class.check_ip_rate_limit(@ip_address)
         account_result = @user ? self.class.check_account_rate_limit(@user) : {retry_after: 0}
 
-        [ip_result[:retry_after] || 0, account_result[:retry_after] || 0].max
+        global_result = self.class.check_global_rate_limit
+        [ip_result[:retry_after] || 0, account_result[:retry_after] || 0, global_result[:retry_after] || 0].max
       end
 
       def reset!

data/lib/beskar/services/request_context.rb

@@ -0,0 +1,69 @@
+require "ipaddr"
+require "uri"
+
+module Beskar
+  module Services
+    module RequestContext
+      module_function
+
+      # Nil when the request has no usable address, for example an in-process Rack
+      # client with a blank REMOTE_ADDR. Rails falls back to REMOTE_ADDR when
+      # forwarded headers are invalid, so a remote client cannot cause this.
+      def ip(request)
+        value = if request.respond_to?(:remote_ip)
+          request.remote_ip
+        elsif request.respond_to?(:env) && request.env && request.env["action_dispatch.remote_ip"]
+          request.env["action_dispatch.remote_ip"]
+        else
+          request.ip
+        end
+        IPAddr.new(value.to_s).to_s
+      rescue IPAddr::Error
+        nil
+      end
+
+      def text(value, limit: 500)
+        value&.to_s&.encode("UTF-8", invalid: :replace, undef: :replace)&.gsub(/[[:cntrl:]]/, " ")&.truncate(limit)
+      end
+
+      # Query strings and referrer queries may carry secrets even when their keys
+      # are unknown to the host application's parameter filter.
+      def path(request)
+        text(request.path, limit: 2048)
+      end
+
+      def security_metadata(request, enrich: true)
+        metadata = {
+          timestamp: Time.current.iso8601,
+          request_id: request.respond_to?(:request_id) ? request.request_id : nil,
+          request_path: path(request),
+          referer: safe_referer(request.referer)
+        }
+        if enrich
+          metadata[:device_info] = DeviceDetector.detect(text(request.user_agent))
+          metadata[:geolocation] = GeolocationService.locate(ip(request))
+        end
+        metadata
+      end
+
+      def safe_referer(value)
+        return if value.blank?
+        uri = URI.parse(text(value, limit: 2048))
+        return unless uri.is_a?(URI::HTTP)
+        uri.query = uri.fragment = nil
+        uri.user = uri.password = nil
+        uri.to_s
+      rescue URI::Error
+        nil
+      end
+
+      def secure_match?(supplied, expected)
+        supplied.present? && expected.present? && ActiveSupport::SecurityUtils.secure_compare(supplied.to_s, expected.to_s)
+      end
+
+      def enforce?(ip_address = nil)
+        !Beskar.configuration.monitor_only? && !IpWhitelist.whitelisted?(ip_address)
+      end
+    end
+  end
+end

data/lib/beskar/services/risk_assessment.rb

@@ -0,0 +1,58 @@
+module Beskar
+  module Services
+    # A single snapshot supplies both the numeric decision and its audit evidence.
+    # IP repetition and lock/unlock records are not verified device/recovery trust.
+    class RiskAssessment
+      HISTORY_LIMIT = 20
+      attr_reader :score, :metadata
+
+      def self.observations(user, at: Time.current, mode: "enforce")
+        return [] unless user
+        user.security_events.where(event_type: "login_success", created_at: (at - 4.hours)...at)
+          .order(created_at: :desc, id: :desc).limit(HISTORY_LIMIT).pluck(:id, :created_at, :metadata)
+          .filter_map do |id, created_at, metadata|
+            next unless metadata.is_a?(Hash)
+            admission = metadata["authentication"]
+            next unless admission.is_a?(Hash) && admission["allowed"] == true && admission["locked_now"] != true
+            next unless usable_history?(metadata, mode)
+            {event_id: id, occurred_at: created_at, location: metadata["geolocation"]}
+          end
+      end
+
+      def self.usable_history?(metadata, mode)
+        return false unless metadata.is_a?(Hash)
+        assessment = metadata["risk_assessment"]
+        return false if assessment && !assessment.is_a?(Hash)
+        mode != "enforce" || assessment&.fetch("mode", nil) != "observe"
+      end
+
+      def initialize(request, user: nil, result: :success, at: Time.current)
+        ip = RequestContext.ip(request)
+        mode = RequestContext.enforce?(ip) ? "enforce" : "observe"
+        device = DeviceDetector.new.assess(request.user_agent)
+        geography = GeolocationService.new.assess_location(ip, observations: self.class.observations(user, at: at, mode: mode), at: at)
+        factors = [{name: (result == :success) ? "credential_success" : "credential_failure", points: (result == :success) ? 1 : 10, evidence: {}}]
+        factors.concat(device[:factors]).concat(geography[:factors])
+        if device[:device_info][:mobile] && (at.hour >= 22 || at.hour < 6)
+          factors << {name: "mobile_late_hours", points: 5, evidence: {hour: at.hour, timezone: at.zone}}
+        end
+        failures = if user
+          user.security_events.where(event_type: "login_failure", created_at: (at - 10.minutes)..at)
+            .order(created_at: :desc, id: :desc).limit(HISTORY_LIMIT).pluck(:metadata)
+            .count { |metadata| self.class.usable_history?(metadata, mode) }
+        else
+          0
+        end
+        factors << {name: "recent_failures", points: 20, evidence: {at_least: 2, window_seconds: 600}} if failures >= 2
+        total = factors.sum { |factor| factor[:points] }
+        factors << {name: "total_cap", points: 100 - total, evidence: {cap: 100}} if total > 100
+        @score = [total, 100].min
+        @metadata = {
+          device_info: device[:device_info], geolocation: geography[:location],
+          risk_assessment: {version: 1, assessed_at: at.iso8601(6), mode: mode, score: score,
+                            factors: factors, trust_discount: 0, history_limit: HISTORY_LIMIT}
+        }
+      end
+    end
+  end
+end