beskar 0.1.0 → 0.2.0

data/app/controllers/beskar/security_events_controller.rb

@@ -1,9 +1,11 @@
-require 'csv'
+require "csv"
 
 module Beskar
   class SecurityEventsController < ApplicationController
+    include Controllers::AuditExport
+
     def index
-      @events = Beskar::SecurityEvent.preload(:user).order(created_at: :desc)
+      @events = Beskar::SecurityEvent.preload(:user).order(created_at: :desc, id: :desc)
 
       # Apply filters
       apply_filters!
@@ -14,7 +16,7 @@ module Beskar
 
       # Get filter options for dropdowns
       @event_types = Beskar::SecurityEvent.distinct.pluck(:event_type).sort
-      @risk_levels = ['low', 'medium', 'high', 'critical']
+      @risk_levels = RiskLevel.filter_options
     end
 
     def show
@@ -22,9 +24,10 @@ module Beskar
 
       # Find related events
       @related_events = Beskar::SecurityEvent
+        .preload(:user)
         .where.not(id: @event.id)
         .where(ip_address: @event.ip_address)
-        .order(created_at: :desc)
+        .order(created_at: :desc, id: :desc)
         .limit(10)
 
       # Get user's recent events if user exists
@@ -44,24 +47,32 @@ module Beskar
 
       # Apply same filters as index
       apply_filters!
+      records = export_records(@events)
+      return if performed?
 
       respond_to do |format|
         format.csv do
-          send_data generate_csv(@events),
+          send_data generate_csv(records),
             filename: "security-events-#{Date.current}.csv",
-            type: 'text/csv'
+            type: "text/csv"
         end
         format.json do
-          render json: @events.as_json(
-            include: { user: { only: [:id, :email] } },
-            except: [:updated_at]
-          )
+          render json: records.map { |event| export_event(event) }
         end
       end
     end
 
     private
 
+    def export_event(event)
+      attributes = event.attributes.slice("id", "event_type", "ip_address", "user_id", "user_type",
+        "user_agent", "attempted_email", "risk_score", "metadata", "created_at")
+      if event.user
+        attributes["user"] = {id: event.user.id, email: Services::AuditData.user_email(event.user)}
+      end
+      attributes
+    end
+
     def apply_filters!
       # Filter by event type
       if params[:event_type].present?
@@ -70,18 +81,7 @@ module Beskar
 
       # Filter by risk level
       if params[:risk_level].present?
-        @events = case params[:risk_level]
-        when 'low'
-          @events.where("risk_score < 30")
-        when 'medium'
-          @events.where("risk_score BETWEEN 30 AND 60")
-        when 'high'
-          @events.where("risk_score BETWEEN 61 AND 85")
-        when 'critical'
-          @events.where("risk_score > 85")
-        else
-          @events
-        end
+        @events = @events.with_risk_level(params[:risk_level])
       end
 
       # Filter by IP address
@@ -91,9 +91,7 @@ module Beskar
 
       # Filter by user email (if attempted_email is stored)
       if params[:email].present?
-        # Search in attempted_email column and metadata (avoid joining polymorphic)
-        @events = @events.where("attempted_email LIKE ? OR metadata LIKE ?",
-                               "%#{params[:email]}%", "%#{params[:email]}%")
+        @events = Services::EventSearch.new(@events).email(params[:email])
       end
 
       # Filter by date range
@@ -118,63 +116,47 @@ module Beskar
       # Quick time range filters
       if params[:time_range].present?
         start_time = case params[:time_range]
-        when 'last_hour'
+        when "last_hour"
           1.hour.ago
-        when 'last_24h'
+        when "last_24h"
           24.hours.ago
-        when 'last_7d'
+        when "last_7d"
           7.days.ago
-        when 'last_30d'
+        when "last_30d"
           30.days.ago
-        else
-          nil
         end
 
         @events = @events.where("created_at >= ?", start_time) if start_time
       end
 
       # Filter by threat level
-      if params[:threats_only] == 'true'
+      if params[:threats_only] == "true"
         @events = @events.high_risk
       end
 
       # Search in metadata
       if params[:search].present?
-        search_term = "%#{params[:search]}%"
-        # Use database-agnostic approach for metadata search
-        if ActiveRecord::Base.connection.adapter_name == 'PostgreSQL'
-          @events = @events.where(
-            "ip_address LIKE ? OR user_agent LIKE ? OR attempted_email LIKE ? OR metadata::text LIKE ?",
-            search_term, search_term, search_term, search_term
-          )
-        else
-          # For SQLite and other databases, search in regular columns
-          # SQLite's JSON support varies by version, so we'll search in standard columns
-          @events = @events.where(
-            "ip_address LIKE ? OR user_agent LIKE ? OR attempted_email LIKE ? OR event_type LIKE ?",
-            search_term, search_term, search_term, search_term
-          )
-        end
+        @events = Services::EventSearch.new(@events).search(params[:search])
       end
     end
 
     def generate_csv(events)
-      require 'csv'
+      require "csv"
 
-      CSV.generate(headers: true) do |csv|
-        csv << ['ID', 'Date/Time', 'Event Type', 'IP Address', 'User', 'Risk Score', 'User Agent', 'Details']
+      CSV.generate(headers: true, force_quotes: true) do |csv|
+        csv << ["ID", "Date/Time", "Event Type", "IP Address", "User", "Risk Score", "User Agent", "Details"]
 
-        events.find_each do |event|
+        events.each do |event|
           csv << [
             event.id,
-            event.created_at.strftime('%Y-%m-%d %H:%M:%S'),
+            event.created_at.strftime("%Y-%m-%d %H:%M:%S"),
             event.event_type,
             event.ip_address,
-            event.user&.try(:email) || event.attempted_email || '-',
+            audit_user_label(event),
             event.risk_score,
             event.user_agent,
-            event.details || event.metadata&.dig("message") || '-'
-          ]
+            event.details || event.metadata&.dig("message") || "-"
+          ].map { |value| Services::AuditData.csv_cell(value) }
         end
       end
     end

data/app/controllers/concerns/beskar/controllers/audit_export.rb

@@ -0,0 +1,54 @@
+module Beskar
+  module Controllers
+    module AuditExport
+      extend ActiveSupport::Concern
+
+      LIMIT = 1000
+
+      included do
+        rescue_from Services::AdministrativeAudit::Unavailable, ActiveRecord::ActiveRecordError do |error|
+          raise error unless action_name == "export"
+          Beskar::Logger.warn("Audit export unavailable (#{error.class})")
+          render plain: "Audit export unavailable", status: :service_unavailable
+        end
+        rescue_from Services::AdministrativeBans::InvalidInput do |error|
+          render plain: error.message, status: :unprocessable_content
+        end
+      end
+
+      private
+
+      def export_records(relation)
+        response.set_header("Cache-Control", "private, no-store")
+        response.set_header("X-Content-Type-Options", "nosniff")
+        unless request.format.csv? || request.format.json?
+          head :not_acceptable
+          return
+        end
+        cursor = params[:before_id]
+        if cursor.present?
+          unless cursor.is_a?(String) && cursor.match?(/\A[1-9]\d{0,18}\z/) && cursor.to_i <= 9_223_372_036_854_775_807
+            render json: {error: "before_id must be a positive record ID"}, status: :unprocessable_content
+            return
+          end
+          relation = relation.where(id: ...cursor.to_i)
+        end
+        records = relation.reorder(id: :desc).limit(LIMIT + 1).to_a
+        truncated = records.length > LIMIT
+        records = records.first(LIMIT)
+        # Persist before disclosing any body. This records an authorized export
+        # preparation, not proof the client finished receiving the response.
+        Services::AdministrativeAudit.record!(actor: administrative_actor!,
+          reason: request.headers["X-Beskar-Audit-Reason"] || params[:audit_reason], request_id: request.request_id,
+          action: "audit_exported", target_type: relation.klass.name.demodulize,
+          after_state: {format: request.format.to_s, count: records.length, highest_id: records.first&.id,
+                        lowest_id: records.last&.id, before_id: cursor, truncated: truncated,
+                        filters: request.query_parameters.except("audit_reason", "controller", "action", "format")})
+        response.set_header("X-Beskar-Export-Limit", LIMIT.to_s)
+        response.set_header("X-Beskar-Export-Truncated", truncated.to_s)
+        response.set_header("X-Beskar-Next-Cursor", records.last.id.to_s) if truncated
+        records
+      end
+    end
+  end
+end

data/app/controllers/concerns/beskar/controllers/security_tracking.rb

@@ -1,69 +1,97 @@
 module Beskar
   module Controllers
-    # Controller concern for tracking Rails 8 authentication events
-    # 
-    # Usage in SessionsController:
-    #   class SessionsController < ApplicationController
-    #     include Beskar::Controllers::SecurityTracking
-    #     
-    #     def create
-    #       if user = User.authenticate_by(params.permit(:email_address, :password))
-    #         track_authentication_success(user)
-    #         start_new_session_for user
-    #         redirect_to after_authentication_url
-    #       else
-    #         track_authentication_failure(User, :user)
-    #         redirect_to new_session_path, alert: "Try another email address or password."
-    #       end
-    #     end
-    #   end
+    # Rails-native integration:
+    # before_action -> { admit_authentication_attempt(User, :user) }, only: :create
+    # After User.authenticate_by succeeds:
+    # return unless complete_authentication(user) { start_new_session_for(user) }
+    # Existing-session readers must also call user.beskar_access_allowed?(request).
     module SecurityTracking
       extend ActiveSupport::Concern
 
       private
 
-      # Track successful authentication for a user
-      # This should be called after verifying credentials but before creating session
+      # Run before password verification. Credentials are identity fields only;
+      # passwords must never be included in a persistent counter key.
+      def admit_authentication_attempt(model, scope = :user, credentials: nil)
+        values = params[scope].is_a?(ActionController::Parameters) ? params[scope] : params
+        key = model.attribute_names.include?("email_address") ? :email_address : :email
+        credentials ||= {key => values[key]}
+        user = model.find_by(credentials)
+        @beskar_authentication_attempt = Services::AuthenticationAttempt.reserve(request,
+          model: model, scope: scope, user: user, credentials: credentials, cache: true)
+        return true if @beskar_authentication_attempt.allowed?
+
+        model.track_failed_authentication(request, scope, attempt: @beskar_authentication_attempt)
+        render_authentication_response(@beskar_authentication_attempt.response)
+        false
+      rescue Services::AuthenticationAttempt::Unavailable, ActiveRecord::ActiveRecordError
+        render_authentication_response(Services::AuthenticationAttempt.unavailable_response)
+        false
+      end
+
+      # The preferred Rails-native API. Final audit persistence happens after the
+      # session guard, so a denied session is never learned as a successful login.
+      def complete_authentication(user)
+        return false unless user
+        attempt = native_authentication_attempt(user)
+        user.track_authentication_event(request, :success, attempt: attempt, persist: false)
+        if attempt.allowed?
+          admitted = user.with_beskar_session(request, generation: attempt.session_token) { yield }
+          attempt.deny!(:account_locked) unless admitted
+        end
+        if attempt.event
+          attempt.event.event_type = "authentication_blocked" unless attempt.allowed?
+          attempt.event.metadata = (attempt.event.metadata || {}).merge("authentication" => attempt.metadata)
+          if Beskar.configuration.track_successful_logins?
+            user.send(:persist_authentication_audit, attempt.event)
+            user.analyze_suspicious_patterns_async if attempt.allowed? && Beskar.configuration.auto_analyze_patterns?
+          end
+        end
+        render_authentication_response(attempt.response) unless attempt.allowed?
+        attempt.allowed?
+      rescue Services::AuthenticationAttempt::Unavailable, ActiveRecord::ActiveRecordError
+        render_authentication_response(Services::AuthenticationAttempt.unavailable_response)
+        false
+      end
+
+      # Compatibility API for custom integrations; callers must honor the boolean
+      # result and guard session creation. Prefer complete_authentication above.
       def track_authentication_success(user)
-        return unless user
-        return unless Beskar.configuration.track_successful_logins?
+        return false unless user
+        attempt = native_authentication_attempt(user)
+        user.track_authentication_event(request, :success, attempt: attempt)
+        render_authentication_response(attempt.response) unless attempt.allowed?
+        attempt.allowed?
+      rescue Services::AuthenticationAttempt::Unavailable
+        render_authentication_response(Services::AuthenticationAttempt.unavailable_response)
+        false
+      end
 
-        user.track_authentication_event(request, :success)
-        Beskar::Logger.info("Tracked successful authentication for user #{user.id}")
-      rescue => e
-        Beskar::Logger.error("Failed to track authentication success: #{e.message}")
+      def native_authentication_attempt(user)
+        @beskar_authentication_attempt ||= Services::AuthenticationAttempt.reserve(request,
+          model: user.class, scope: user.class.name.underscore, user: user, cache: true)
       end
 
-      # Track failed authentication attempt
-      # This should be called when authentication fails
       def track_authentication_failure(model_class, scope = :user)
-        return unless Beskar.configuration.track_failed_logins?
+        model_class.track_failed_authentication(request, scope, attempt: @beskar_authentication_attempt)
+      end
 
-        model_class.track_failed_authentication(request, scope)
-        Beskar::Logger.info("Tracked failed authentication for scope #{scope}")
-      rescue => e
-        Beskar::Logger.error("Failed to track authentication failure: #{e.message}")
+      def render_authentication_response(response)
+        return if performed?
+        status, headers, body = response
+        headers.each { |name, value| self.response.set_header(name, value) }
+        render body: body.join, status: status
       end
 
-      # Track logout event
       def track_logout(user)
-        return unless user
-        return unless Beskar.configuration.security_tracking_enabled?
-
+        return unless user && Beskar.configuration.security_tracking_enabled?
         user.security_events.create!(
-          event_type: "logout",
-          ip_address: request.ip,
-          user_agent: request.user_agent,
-          metadata: {
-            timestamp: Time.current.iso8601,
-            session_id: request.session.id,
-            request_path: request.path
-          },
-          risk_score: 0
+          event_type: "logout", ip_address: Services::RequestContext.ip(request),
+          user_agent: Services::RequestContext.text(request.user_agent), risk_score: 0,
+          metadata: {timestamp: Time.current.iso8601, request_path: Services::RequestContext.path(request)}
         )
-        Beskar::Logger.info("Tracked logout for user #{user.id}")
-      rescue => e
-        Beskar::Logger.error("Failed to track logout: #{e.message}")
+      rescue => error
+        Beskar::Logger.warn("Logout audit unavailable (#{error.class})")
       end
     end
   end

data/app/controllers/concerns/beskar/controllers/session_security.rb

@@ -0,0 +1,29 @@
+module Beskar
+  module Controllers
+    # Include in the host API base controller, after host credential resolution.
+    # The two readers are host methods; the generation must come from a verified
+    # credential, not a freshly queried value or an unsigned request parameter.
+    module SessionSecurity
+      extend ActiveSupport::Concern
+
+      included do
+        before_action :require_beskar_session!
+      end
+
+      private
+
+      def require_beskar_session!
+        unless respond_to?(:beskar_authenticated_user, true) && respond_to?(:beskar_authenticated_generation, true)
+          raise Services::AuthenticationAttempt::Unavailable, "Session adapter is not configured"
+        end
+        unless Services::SessionRevocation.allowed?(beskar_authenticated_user, request: request, token: beskar_authenticated_generation)
+          response.headers["Cache-Control"] = "no-store"
+          head :unauthorized
+        end
+      rescue Services::AuthenticationAttempt::Unavailable
+        response.headers["Cache-Control"] = "no-store"
+        head :service_unavailable
+      end
+    end
+  end
+end

data/app/jobs/beskar/notification_job.rb

@@ -0,0 +1,33 @@
+module Beskar
+  class NotificationJob < ApplicationJob
+    self.log_arguments = false
+    queue_as :beskar_notifications
+
+    retry_on Services::Notifications::DeliveryError, wait: :polynomially_longer, attempts: 5
+
+    def perform(user_type:, user_id:, kind:, recipient_index: nil)
+      return unless Services::Notifications.enabled?(kind)
+      ConfigurationValidator.new(Beskar.configuration).validate_notifications!
+      delivery = SecurityMailer.notification(user_type, user_id, kind, recipient_index)
+      message = delivery.message
+      # A deleted account or removed recipient has no message to deliver.
+      return unless message.to.present?
+      unless message.perform_deliveries && message.raise_delivery_errors
+        raise Services::Notifications::DeliveryError, "Security mail requires enabled deliveries and delivery errors"
+      end
+      raise Services::Notifications::DeliveryError, "Security mail delivery was aborted" unless delivery.deliver_now
+    rescue => error
+      # Prevent Active Job's failure/retry logs from dumping transport credentials
+      # or arbitrary host callback exception messages (including exception causes).
+      raise Services::Notifications::DeliveryError, "Security notification delivery failed (#{error.class})", cause: nil
+    end
+
+    def retry_job(options = {})
+      result = super
+      raise Services::Notifications::DeliveryError, "Security notification retry was not enqueued" unless result
+      result
+    rescue => error
+      raise Services::Notifications::DeliveryError, "Security notification retry failed (#{error.class})", cause: nil
+    end
+  end
+end

data/app/mailers/beskar/security_mailer.rb

@@ -0,0 +1,59 @@
+module Beskar
+  class SecurityMailer < ApplicationMailer
+    layout false
+
+    # Only scalar identity fields enter Action Mailer's process instrumentation.
+    def notification(user_type, user_id, kind, recipient_index = nil)
+      return unless Services::Notifications.enabled?(kind)
+      ConfigurationValidator.new(Beskar.configuration).validate_notifications!
+      model = user_type.safe_constantize if user_type.is_a?(String)
+      unless model.is_a?(Class) && model < ActiveRecord::Base && model.reflect_on_association(:security_events)
+        raise Configuration::Error, "Notification account model is unsupported"
+      end
+      user = model.find_by(id: user_id)
+      return unless user
+
+      settings = Beskar.configuration.notifications
+      if kind == "security_team_reset"
+        return unless recipient_index.is_a?(Integer) && recipient_index >= 0
+        recipient = settings[:security_team_recipients][recipient_index]
+        return unless recipient
+        subject = "Security notice: account password invalidated"
+        body = "A precautionary emergency password reset was performed for #{user.class.base_class.name} ID #{user.id}.\n" \
+          "Review the authenticated security dashboard and follow your incident response policy.\n" \
+          "This notification is not proof that the account was compromised.\n"
+      else
+        recipient = user.respond_to?(:email_address) ? user.email_address : user.email
+        unless ConfigurationValidator.mailbox?(recipient)
+          raise Configuration::Error, "Notification account requires one valid email address"
+        end
+        subject, explanation = if kind == "account_locked"
+          ["Security notice: account locked", "Your account was locked as a security precaution."]
+        else
+          ["Security notice: password reset required", "Your password was invalidated as a security precaution. Your previous password no longer works."]
+        end
+        body = "#{explanation}\n\nVisit the application's recovery page for help:\n#{settings[:recovery_url]}\n\n" \
+          "A password reset does not necessarily unlock your account. Contact your administrator if it remains locked.\n" \
+          "This notice does not contain a password or a sign-in link.\n"
+      end
+      mail(from: settings[:from], to: recipient, subject: subject, body: body, content_type: "text/plain")
+    rescue => error
+      raise Services::Notifications::DeliveryError, "Security mail preparation failed (#{error.class})", cause: nil
+    end
+
+    # Keep this mailer's delivery instrumentation free of addresses, message
+    # bodies, and raw transport errors. Do not change logging for host mailers.
+    def self.deliver_mail(message)
+      ActiveSupport::Notifications.instrument("deliver.beskar_notification", mailer: name) do
+        # Recheck after host interceptors; Mail otherwise silently skips delivery
+        # or swallows transport errors when these flags are disabled.
+        unless message.perform_deliveries && message.raise_delivery_errors
+          raise Services::Notifications::DeliveryError, "Security mail delivery is disabled"
+        end
+        yield
+      rescue => error
+        raise Services::Notifications::DeliveryError, "Security mail transport failed (#{error.class})", cause: nil
+      end
+    end
+  end
+end

data/app/models/beskar/administrative_action.rb

@@ -0,0 +1,41 @@
+module Beskar
+  class AdministrativeAction < ApplicationRecord
+    attribute :before_state, default: -> { {} }
+    attribute :after_state, default: -> { {} }
+
+    ACTIONS = %w[ban_created ban_updated ban_unbanned ban_extended ban_made_permanent audit_exported configuration_changed].freeze
+    before_validation :sanitize_audit_fields
+    after_find :sanitize_audit_fields
+
+    validates :actor, :operation_id, :request_id, :reason, presence: true
+    validates :actor, :request_id, length: {maximum: 200}
+    validates :reason, length: {maximum: 1000}
+    validates :action, inclusion: {in: ACTIONS}
+    validates :target_type, inclusion: {in: %w[BannedIp SecurityEvent Configuration]}
+    validates :target_id, numericality: {only_integer: true, greater_than: 0}, allow_nil: true
+    validates :target_id, presence: true, if: -> { action&.start_with?("ban_") }
+
+    # Reject ordinary instance saves/updates and destruction. Low-level counter,
+    # bulk and SQL APIs can bypass this; this is not tamper-proof storage.
+    def readonly?
+      persisted? || super
+    end
+
+    # Active Record deliberately bypasses readonly? in its instance delete API.
+    def delete
+      raise ActiveRecord::ReadOnlyRecord, "Administrative history is append-only" if persisted?
+      super
+    end
+
+    private
+
+    def sanitize_audit_fields
+      {actor: 200, request_id: 200, reason: 1000}.each do |field, limit|
+        self[field] = Services::AuditData.field(field, self[field], limit: limit) if has_attribute?(field)
+      end
+      %i[before_state after_state].each do |field|
+        self[field] = Services::AuditData.metadata(self[field]) if has_attribute?(field)
+      end
+    end
+  end
+end