lesli_audit 1.1.0 → 1.1.2

data/app/models/concerns/lesli_audit/append_only.rb

@@ -0,0 +1,12 @@
+module LesliAudit
+    module AppendOnly
+        extend ActiveSupport::Concern
+
+        # New records remain writable until their first INSERT. Once persisted,
+        # Active Record blocks ordinary updates and destroys. Retention cleanup
+        # and tenant hard-purge foreign keys intentionally operate below models.
+        def readonly?
+            persisted? || super
+        end
+    end
+end

data/app/models/lesli_audit/account.rb

@@ -1,19 +1,35 @@
 module LesliAudit
     class Account < ApplicationRecord
-        belongs_to :account, class_name: "Lesli::Account"
+        belongs_to :account,
+            class_name: "Lesli::Account",
+            inverse_of: :audit
+
+        validates :account_id, uniqueness: true
+
         has_many :dashboards
 
-        has_many :account_logs
-        has_many :account_devices
-        has_many :account_requests
+        has_many :account_logs,
+            inverse_of: :account,
+            dependent: :delete_all
+
+        has_many :account_devices,
+            inverse_of: :account,
+            dependent: :delete_all
+
+        has_many :account_requests,
+            inverse_of: :account,
+            dependent: :delete_all
 
-        has_many :user_logs
-        has_many :user_journals
-        has_many :user_requests
+        has_many :user_logs,
+            inverse_of: :account,
+            dependent: :delete_all
 
-        after_create :initialize_account
+        has_many :user_journals,
+            inverse_of: :account,
+            dependent: :delete_all
 
-        def initialize_account
-        end
+        has_many :user_requests,
+            inverse_of: :account,
+            dependent: :delete_all
     end
 end

data/app/models/lesli_audit/account_device.rb

@@ -1,5 +1,7 @@
 module LesliAudit
     class AccountDevice < ApplicationRecord
-        belongs_to :account, class_name: 'Lesli::Account'
+        belongs_to :account,
+            class_name: "LesliAudit::Account",
+            inverse_of: :account_devices
     end
 end

data/app/models/lesli_audit/account_log.rb

@@ -1,11 +1,16 @@
 module LesliAudit
     class AccountLog < ApplicationRecord
-        belongs_to :account, optional: true
-        belongs_to :user, class_name: "Lesli::User", optional: true
-        
-        enum :operation, { 
-            :account_creation => 'account_creation',
-            :account_initialization => 'account_initialization'
-        }
+        include LesliAudit::AppendOnly
+
+        belongs_to :account,
+            class_name: "LesliAudit::Account",
+            inverse_of: :account_logs
+
+        belongs_to :user,
+            class_name: "Lesli::User",
+            inverse_of: :account_logs,
+            optional: true
+
+        validates :operation, presence: true
     end
 end

data/app/models/lesli_audit/account_request.rb

@@ -1,5 +1,7 @@
 module LesliAudit
     class AccountRequest < ApplicationRecord
-        belongs_to :account
+        belongs_to :account,
+            class_name: "LesliAudit::Account",
+            inverse_of: :account_requests
     end
 end

data/app/models/lesli_audit/user_journal.rb

@@ -1,7 +1,20 @@
 module LesliAudit
     class UserJournal < ApplicationRecord
-        belongs_to :account
-        belongs_to :user, class_name: "Lesli::User"
-        belongs_to :session, class_name: "LesliShield::User::Session"
+        belongs_to :account,
+            class_name: "LesliAudit::Account",
+            inverse_of: :user_journals
+
+        belongs_to :user,
+            class_name: "Lesli::User",
+            inverse_of: :journals,
+            optional: true
+
+        validates :event_uid, presence: true
+        validates :request_controller, :request_action, presence: true, if: :retain?
+
+        scope :pending, -> { where(processed_at: nil) }
+        scope :processed, -> { where.not(processed_at: nil) }
+        scope :retained, -> { where(retain: true) }
+        scope :transient, -> { where(retain: false) }
     end
 end

data/app/models/lesli_audit/user_log.rb

@@ -1,7 +1,16 @@
 module LesliAudit
     class UserLog < ApplicationRecord
-        belongs_to :account, optional: true
-        belongs_to :user, class_name: "Lesli::User"
-        belongs_to :session, class_name: "LesliShield::User::Session", optional: true
+        include LesliAudit::AppendOnly
+
+        belongs_to :account,
+            class_name: "LesliAudit::Account",
+            inverse_of: :user_logs
+
+        belongs_to :user,
+            class_name: "Lesli::User",
+            inverse_of: :logs,
+            optional: true
+
+        validates :operation, presence: true
     end
 end

data/app/models/lesli_audit/user_request.rb

@@ -1,7 +1,11 @@
 module LesliAudit
     class UserRequest < ApplicationRecord
-        belongs_to :account
-        belongs_to :user, class_name: "Lesli::User"
-        belongs_to :session, class_name: "LesliShield::User::Session"
+        belongs_to :account,
+            class_name: "LesliAudit::Account",
+            inverse_of: :user_requests
+
+        belongs_to :user,
+            class_name: "Lesli::User",
+            inverse_of: :requests
     end
 end

data/app/services/lesli_audit/activity_audit.rb

@@ -0,0 +1,130 @@
+=begin
+
+Lesli
+
+Copyright (c) 2026, Lesli Technologies, S. A.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see http://www.gnu.org/licenses/.
+
+Lesli · Ruby on Rails SaaS Development Framework.
+
+Made with ♥ by LesliTech
+Building a better future, one line of code at a time.
+
+@contact  hello@lesli.tech
+@website  https://www.lesli.tech
+@license  GPLv3 http://www.gnu.org/licenses/gpl-3.0.en.html
+
+// · ~·~     ~·~     ~·~     ~·~     ~·~     ~·~     ~·~     ~·~     ~·~
+// ·
+=end
+
+module LesliAudit
+    # Writes durable business and security events. Unlike request analytics,
+    # this entry point never rescues persistence errors: an auditable operation
+    # must fail when its event cannot be stored.
+    class ActivityAudit
+        class MissingAccount < StandardError; end
+
+        def self.record_account!(account:, actor: nil, **attributes)
+            return unless enabled?
+
+            new(account: account, actor: actor, **attributes).record_account!
+        end
+
+        def self.record_user!(user:, **attributes)
+            return unless enabled?
+
+            new(account: user&.account, actor: user, **attributes).record_user!
+        end
+
+        def self.enabled?
+            Lesli.config.audit&.dig(:enable_logs) == true
+        end
+
+        def initialize(
+            account:,
+            actor: nil,
+            engine: nil,
+            source: nil,
+            action: nil,
+            operation: nil,
+            description: nil,
+            session_id: nil,
+            subject: nil
+        )
+            @audit_account = resolve_audit_account(account)
+            @actor = actor
+            @engine = identifier(engine)
+            @source = identifier(source)
+            @action = identifier(action)
+            @operation = identifier(operation.presence || action.presence)
+            @description = description
+            @session_id = session_id.presence
+            @subject = subject
+
+            raise ArgumentError, "operation is required" if @operation.blank?
+        end
+
+        def record_account!
+            audit_account.account_logs.create!(event_attributes.merge(user: actor))
+        end
+
+        def record_user!
+            raise ArgumentError, "user is required" unless actor
+
+            audit_account.user_logs.create!(event_attributes.merge(user: actor))
+        end
+
+        private
+
+        attr_reader :actor, :audit_account, :subject
+
+        def resolve_audit_account(account)
+            resolved = account if account.is_a?(LesliAudit::Account)
+            resolved ||= account&.audit if account&.respond_to?(:audit)
+
+            return resolved if resolved
+
+            raise MissingAccount, "LesliAudit account is required"
+        end
+
+        # Keep event metadata deliberately small. Request parameters and other
+        # unfiltered payloads are not accepted by this API.
+        def event_attributes
+            {
+                engine: @engine,
+                source: @source,
+                action: @action,
+                operation: @operation,
+                description: @description,
+                session_id: @session_id,
+                actor_uid: actor_uid,
+                subject_type: subject&.class&.name,
+                subject_id: subject&.id
+            }
+        end
+
+        def actor_uid
+            actor.uid if actor&.respond_to?(:uid)
+        end
+
+        def identifier(value)
+            return if value.nil?
+            return value.name if value.respond_to?(:name) && value.name.present?
+
+            value.to_s
+        end
+    end
+end

data/app/services/lesli_audit/request_service.rb

@@ -38,44 +38,11 @@ module LesliAudit
         # @param {query} Has of the formated queries/filters that will be applied to filter data
         # @description
         # @example
-        def index 
-
-
-            requests = current_user.requests
+        def index
+            current_user.requests
             .order(created_at: :desc)
             .page(query[:pagination][:page])
             .per(query[:pagination][:perPage])
-
-            return requests
-
-
-            search_string = nil # query[:search].downcase.gsub(" ","%") unless query[:search].blank?
-            order_string = "user_requests.created_at" 
-            
-            user_requests = current_user.account.users.joins(:requests)
-            #user_requests = user_requests.where("users.email = ?", query[:filters][:user]) unless query[:filters][:user].blank?
-
-            if !search_string.blank?
-                # user_requests = user_requests.where([
-                #     "lower(users.email) like :search_string",
-                #     "lower(request_controller) like :search_string",
-                #     "lower(request_action) like :search_string"
-                # ].join(" or "), { 
-                #     search_string: "%#{search_string}%"
-                # }) 
-            end
-
-            user_requests.select(
-                :id,
-                "users.id as user_id",
-                "users.email",
-                :request_controller,
-                :request_action,
-                :request_method,
-                :user_session_id,
-                Date2.new.date_time.db_timestamps("user_requests")
-            ).page(query[:pagination][:page])
-            .per(query[:pagination][:perPage])
         end
     end
 end

data/app/services/lesli_audit/retention_cleanup.rb

@@ -0,0 +1,146 @@
+=begin
+
+Lesli
+
+Copyright (c) 2026, Lesli Technologies, S. A.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see http://www.gnu.org/licenses/.
+
+Lesli · Ruby on Rails SaaS Development Framework.
+
+Made with ♥ by LesliTech
+Building a better future, one line of code at a time.
+
+@contact  hello@lesli.tech
+@website  https://www.lesli.tech
+@license  GPLv3 http://www.gnu.org/licenses/gpl-3.0.en.html
+
+// · ~·~     ~·~     ~·~     ~·~     ~·~     ~·~     ~·~     ~·~     ~·~
+// ·
+=end
+
+module LesliAudit
+    # Applies the retention policy configured by the host application.
+    #
+    # Cleanup uses delete_all deliberately: analytics has no destroy callbacks,
+    # while activity events are append-only during their retained lifetime. Each
+    # relation is deleted in bounded primary-key batches and can be retried safely.
+    class RetentionCleanup
+        DEFAULT_BATCH_SIZE = 1_000
+
+        ANALYTICS_MODELS = [
+            LesliAudit::AccountDevice,
+            LesliAudit::AccountRequest,
+            LesliAudit::UserRequest
+        ].freeze
+
+        ACTIVITY_MODELS = [
+            LesliAudit::AccountLog,
+            LesliAudit::UserLog
+        ].freeze
+
+        def self.call(batch_size: DEFAULT_BATCH_SIZE, today: Date.current, now: Time.current)
+            new(batch_size: batch_size, today: today, now: now).call
+        end
+
+        def initialize(batch_size:, today:, now:)
+            @batch_size = positive_integer!(batch_size, :batch_size)
+            @today = today.to_date
+            @now = now
+        end
+
+        def call
+            deleted = {}
+
+            cleanup_journals(deleted)
+            cleanup_group(
+                deleted,
+                ANALYTICS_MODELS,
+                column: :date,
+                cutoff: date_cutoff(:analytics_retention_days)
+            )
+            cleanup_group(
+                deleted,
+                ACTIVITY_MODELS,
+                column: :created_at,
+                cutoff: time_cutoff(:audit_retention_days)
+            )
+
+            deleted
+        end
+
+        private
+
+        attr_reader :batch_size, :now, :today
+
+        def cleanup_journals(deleted)
+            retained_count = delete_with_cutoff(
+                LesliAudit::UserJournal.retained.processed,
+                :date,
+                date_cutoff(:journal_retention_days)
+            )
+            transient_count = delete_with_cutoff(
+                LesliAudit::UserJournal.transient.processed,
+                :date,
+                date_cutoff(:analytics_retention_days)
+            )
+
+            deleted[LesliAudit::UserJournal.table_name] = retained_count + transient_count
+        end
+
+        def cleanup_group(deleted, models, column:, cutoff:)
+            models.each do |model|
+                deleted[model.table_name] = delete_with_cutoff(model.all, column, cutoff)
+            end
+        end
+
+        def delete_with_cutoff(relation, column, cutoff)
+            return 0 unless cutoff
+
+            relation
+                .where(relation.klass.arel_table[column].lt(cutoff))
+                .in_batches(of: batch_size)
+                .delete_all
+        end
+
+        def date_cutoff(setting)
+            days = retention_days(setting)
+            today - days if days
+        end
+
+        def time_cutoff(setting)
+            days = retention_days(setting)
+            now - days.days if days
+        end
+
+        def retention_days(setting)
+            value = Lesli.config.audit&.dig(setting)
+            return if value.nil?
+
+            positive_integer!(value, setting)
+        end
+
+        def positive_integer!(value, setting)
+            valid_value = value.is_a?(Integer) || (value.is_a?(String) && value.match?(/\A[1-9]\d*\z/))
+            raise ArgumentError unless valid_value
+
+            integer = value.to_i
+            return integer if integer.positive?
+
+            raise ArgumentError, "#{setting} must be a positive integer or nil"
+        rescue ArgumentError, TypeError
+            raise ArgumentError, "#{setting} must be a positive integer or nil"
+        end
+    end
+end

data/app/services/lesli_audit/user_agent_parser.rb

@@ -0,0 +1,51 @@
+=begin
+
+Lesli
+
+Copyright (c) 2026, Lesli Technologies, S. A.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see http://www.gnu.org/licenses/.
+
+Lesli · Ruby on Rails SaaS Development Framework.
+
+Made with ♥ by LesliTech
+Building a better future, one line of code at a time.
+
+@contact  hello@lesli.tech
+@website  https://www.lesli.tech
+@license  GPLv3 http://www.gnu.org/licenses/gpl-3.0.en.html
+
+// · ~·~     ~·~     ~·~     ~·~     ~·~     ~·~     ~·~     ~·~     ~·~
+// ·
+=end
+
+require "device_detector"
+
+module LesliAudit
+    # Provides one normalized user-agent contract for the engines that need to
+    # persist browser and operating-system metadata.
+    class UserAgentParser
+        def self.parse(user_agent)
+            detector = DeviceDetector.new(user_agent.to_s)
+
+            {
+                platform: detector.os_name,
+                os: detector.os_full_version,
+                browser: detector.name,
+                version: detector.full_version,
+                device: detector.device_type
+            }
+        end
+    end
+end

data/app/services/lesli_audit/user_service.rb

@@ -35,22 +35,24 @@ module LesliAudit
 
         def users
             users = current_user.account.users
+            users = users.with_deleted if users.respond_to?(:with_deleted)
 
             now = Time.current
             last_30_days = 30.days.ago
+            quoted_false = ActiveRecord::Base.connection.quote(false)
 
             stats = users.pick(
                 # total users 
                 Arel.sql("COUNT(*)"),
 
                 # total deactivated users 
-                Arel.sql("SUM(CASE WHEN active = 0 AND deleted_at IS NULL THEN 1 ELSE 0 END)"),
+                Arel.sql("SUM(CASE WHEN active = #{quoted_false} AND deleted_at IS NULL THEN 1 ELSE 0 END)"),
 
                 # total locked users 
                 Arel.sql(
                     "SUM(CASE WHEN (
                         locked_at IS NOT NULL
-                        OR locked_until > #{ActiveRecord::Base.connection.quote(Time.current)}
+                        OR locked_until > #{ActiveRecord::Base.connection.quote(now)}
                     ) AND deleted_at IS NULL THEN 1 ELSE 0 END)"
                 ),
 
@@ -137,37 +139,37 @@ module LesliAudit
 
             group = 'day' 
 
-            group_by = "DATE_TRUNC('month', lesli_audit_user_requests.date)" if group == 'month'
-            group_by = "DATE_TRUNC('week', lesli_audit_user_requests.date)" if group == 'week'
-            group_by = "DATE_TRUNC('day', lesli_audit_user_requests.date)" if group == 'day'
+            group_by = "DATE_TRUNC('month', lesli_audit_user_journals.date)" if group == 'month'
+            group_by = "DATE_TRUNC('week', lesli_audit_user_journals.date)" if group == 'week'
+            group_by = "DATE_TRUNC('day', lesli_audit_user_journals.date)" if group == 'day'
 
             # compatibility for SQLite
             if ActiveRecord::Base.connection.adapter_name == "SQLite"
-                group_by = "strftime('%Y-%m-%d', lesli_audit_user_requests.date)"
+                group_by = "strftime('%Y-%m-%d', lesli_audit_user_journals.date)"
             end
 
-            user_requests = current_user.account.users.joins(:requests)
+            user_journals = current_user.account.users
+            .joins(:journals)
+            .merge(LesliAudit::UserJournal.retained.processed)
 
-            user_requests = user_requests.select(
-                :id,
+            user_journals = user_journals.select(
                 "lesli_users.id as user_id",
                 "lesli_users.email as user_email",
                 "#{group_by} date",
-                "min(lesli_audit_user_requests.created_at) as first_activity", 
-                "max(lesli_audit_user_requests.updated_at) as last_activity",
-                "count(lesli_audit_user_requests.id) resources", 
-                "sum(lesli_audit_user_requests.request_count) requests"
+                "min(lesli_audit_user_journals.created_at) as first_activity",
+                "max(lesli_audit_user_journals.created_at) as last_activity",
+                "count(lesli_audit_user_journals.id) requests"
             )
            
-            user_requests = user_requests.group(:user_id, group_by)
+            user_journals = user_journals.group("lesli_users.id", group_by)
 
-            user_requests.map do |request|
+            user_journals.map do |request|
                 request[:first_activity] = Date2.new(request[:first_activity]).time
                 request[:last_activity] = Date2.new(request[:last_activity]).time
                 request
             end
             
-            user_requests.reverse
+            user_journals.reverse
         end
 
         def registrations