audit_log_rails 0.1.0 → 0.2.0

data/lib/audit_log_rails.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Mantem compatibilidade entre o nome publicado da gem e o namespace interno.
+require_relative "audit_logger"

data/lib/audit_logger/audit_log.rb

@@ -6,6 +6,18 @@ module AuditLogger
 
     JSON_FIELDS = %w[changed_by_other audited_changes audited_changes_humanize].freeze
 
+    # Historico de um agregado: tudo o que tem o registro como dono, do mais recente ao mais antigo.
+    scope :of_owner, lambda { |owner|
+      where(OwnerResolver.attributes_for(owner)).order(created_at: :desc, id: :desc)
+    }
+
+    # As colunas de dono chegaram na 0.2.0; a migration de upgrade cria as duas.
+    def self.owner_columns?
+      column_names.include?("owner_type") && column_names.include?("owner_id")
+    rescue ActiveRecord::StatementInvalid, ActiveRecord::NoDatabaseError
+      false
+    end
+
     # Mantem compatibilidade entre bancos nativos JSON/JSONB e colunas texto sem
     # depender de conexao ativa no carregamento da classe.
     JSON_FIELDS.each do |field_name|
@@ -39,7 +51,7 @@ module AuditLogger
 
     # A verificacao do tipo fica em runtime, quando a conexao ja deve estar disponivel.
     def json_like_column?(field_name)
-      self.class.type_for_attribute(field_name.to_s).type.in?([ :json, :jsonb ])
+      self.class.type_for_attribute(field_name.to_s).type.in?(%i[json jsonb])
     rescue ActiveRecord::ConnectionNotDefined, ActiveRecord::NoDatabaseError
       false
     end

data/lib/audit_logger/change_extractor.rb

@@ -38,21 +38,29 @@ module AuditLogger
     # Usa snapshot completo em create e destroy para preservar contexto.
     def snapshot_fields
       filtered_attributes.each_with_object({}) do |(attribute, value), result|
-        result[attribute] = { "value" => value }
+        result[attribute] = { "value" => mask(attribute, value) }
       end
     end
 
     # Em update salva apenas delta com old/new para reduzir ruido.
+    # Atributo mascarado entra no delta (a troca de senha fica registrada), mas sem os valores.
     def update_fields
       filtered_previous_changes.each_with_object({}) do |(attribute, values), result|
         old_value, new_value = values
         result[attribute] = {
-          "old_value" => old_value,
-          "new_value" => new_value
+          "old_value" => mask(attribute, old_value),
+          "new_value" => mask(attribute, new_value)
         }
       end
     end
 
+    # Valor nulo continua nulo: mostra que o campo estava vazio sem revelar nada.
+    def mask(attribute, value)
+      return value if value.nil? || !masked_attributes.include?(attribute)
+
+      configuration.mask_value
+    end
+
     # Remove do snapshot os atributos que nao devem ser auditados.
     def filtered_attributes
       record.attributes.reject do |attribute, _value|
@@ -71,5 +79,9 @@ module AuditLogger
     def ignored_attributes
       @ignored_attributes ||= model_config.effective_ignored_attributes(configuration)
     end
+
+    def masked_attributes
+      @masked_attributes ||= model_config.effective_masked_attributes(configuration)
+    end
   end
 end

data/lib/audit_logger/config_validator.rb

@@ -10,6 +10,7 @@ module AuditLogger
       uuid_resolver
       ip_resolver
       humanizer
+      error_handler
     ].freeze
 
     def self.validate!(configuration)
@@ -26,6 +27,8 @@ module AuditLogger
       validate_humanize_by_default!
       validate_i18n_scopes!
       validate_ignored_attributes!
+      validate_masked_attributes!
+      validate_booleans!
 
       configuration
     end
@@ -63,6 +66,25 @@ module AuditLogger
       end
     end
 
+    # Mesma regra dos ignorados: nomes de atributo como string ou symbol.
+    def validate_masked_attributes!
+      value = configuration.masked_attributes
+
+      unless value.is_a?(Array) && value.all? { |item| item.is_a?(String) || item.is_a?(Symbol) }
+        raise ConfigurationError,
+              "masked_attributes deve ser um Array de strings ou symbols"
+      end
+    end
+
+    # Flags simples nao aceitam valores "truthy" ambiguos.
+    def validate_booleans!
+      %i[resolve_associations raise_errors].each do |field_name|
+        next if [true, false].include?(configuration.public_send(field_name))
+
+        raise ConfigurationError, "#{field_name} deve ser true ou false"
+      end
+    end
+
     # Mantem a comparacao de atributos ignorados previsivel.
     def validate_ignored_attributes!
       value = configuration.ignored_attributes

data/lib/audit_logger/configuration.rb

@@ -11,7 +11,12 @@ module AuditLogger
                   :humanize_by_default,
                   :i18n_scopes,
                   :ignored_attributes,
-                  :humanizer
+                  :masked_attributes,
+                  :mask_value,
+                  :humanizer,
+                  :resolve_associations,
+                  :raise_errors,
+                  :error_handler
 
     def initialize
       reset!
@@ -28,7 +33,15 @@ module AuditLogger
       self.humanize_by_default = true
       self.i18n_scopes = default_i18n_scopes
       self.ignored_attributes = default_ignored_attributes
+      # Atributos sensiveis: a alteracao e registrada, mas o valor vira mask_value.
+      self.masked_attributes = default_masked_attributes
+      self.mask_value = "[FILTRADO]"
       self.humanizer = nil
+      # Troca o id de belongs_to pelo rotulo do registro associado no payload humanizado.
+      self.resolve_associations = true
+      # Por padrao a auditoria nunca derruba a operacao principal; nos testes vale ligar.
+      self.raise_errors = false
+      self.error_handler = nil
 
       self
     end
@@ -44,5 +57,10 @@ module AuditLogger
     def default_ignored_attributes
       %i[created_at updated_at lock_version]
     end
+
+    # Senhas e tokens comuns em apps Rails (Devise, has_secure_password, tokens de API).
+    def default_masked_attributes
+      %i[password password_digest encrypted_password reset_password_token confirmation_token unlock_token]
+    end
   end
 end

data/lib/audit_logger/humanizer.rb

@@ -65,6 +65,8 @@ module AuditLogger
     end
 
     # Mantem o label traduzido e preserva os dados do payload bruto.
+    # Em belongs_to, acrescenta o rotulo do registro associado: "r_cargo_id: 3 -> 7" vira
+    # old_value_label "PROFESSOR" e new_value_label "ASSESSOR".
     def default_field_payload(attribute, values)
       result = { "label" => translate_attribute(attribute) }
 
@@ -72,7 +74,51 @@ module AuditLogger
         result[key] = value
       end
 
-      result
+      result.merge(association_labels(attribute, values))
+    end
+
+    VALUE_KEYS = %w[old_value new_value value].freeze
+
+    def association_labels(attribute, values)
+      return {} unless configuration.resolve_associations
+
+      reflection = belongs_to_reflection(attribute)
+      return {} unless reflection
+
+      values.each_with_object({}) do |(key, value), labels|
+        next unless VALUE_KEYS.include?(key) && !value.nil?
+
+        label = association_label(reflection, value)
+        labels["#{key}_label"] = label unless label.nil?
+      end
+    rescue StandardError => e
+      log_warning(attribute, e)
+      {}
+    end
+
+    def belongs_to_reflection(attribute)
+      record.class.reflect_on_all_associations(:belongs_to).find do |reflection|
+        !reflection.polymorphic? && reflection.foreign_key.to_s == attribute.to_s
+      end
+    end
+
+    # Procura tambem registros excluidos (soft delete): o historico precisa do nome antigo.
+    def association_label(reflection, id)
+      klass = reflection.klass
+      scope = klass.respond_to?(:with_deleted) ? klass.with_deleted : klass.unscoped
+      associated = scope.find_by(reflection.association_primary_key => id)
+      associated && display_label(associated)
+    end
+
+    LABEL_METHODS = %i[display_name descricao nome name title].freeze
+
+    # Prefere um to_s definido na propria model; depois metodos comuns de rotulo.
+    def display_label(associated)
+      owner = associated.class.instance_method(:to_s).owner
+      return associated.to_s if owner.is_a?(Class) && owner < ActiveRecord::Base
+
+      method_name = LABEL_METHODS.find { |name| associated.respond_to?(name) }
+      method_name && associated.public_send(method_name)&.to_s
     end
 
     # Faz o fallback de traducao por escopo ate encontrar um label valido.

data/lib/audit_logger/model_config.rb

@@ -3,13 +3,19 @@
 module AuditLogger
   class ModelConfig
     # Guarda apenas a configuracao local da model, sem misturar com a global.
-    attr_reader :humanize, :i18n_scopes, :humanizer, :ignored_attributes
+    attr_reader :humanize, :i18n_scopes, :humanizer, :ignored_attributes, :masked_attributes, :owner
 
-    def initialize(humanize: nil, i18n_scopes: nil, humanizer: nil, ignored_attributes: [])
+    # owner: nome da associacao (Symbol) ou Proc(record) que devolve o registro "dono" do log,
+    # para consultar num lugar so o historico de um agregado (ex.: pessoa + contratos).
+    # Sem owner, o dono e o proprio registro.
+    def initialize(humanize: nil, i18n_scopes: nil, humanizer: nil, ignored_attributes: [], masked_attributes: [],
+                   owner: nil)
       @humanize = humanize
       @i18n_scopes = i18n_scopes
       @humanizer = humanizer
       @ignored_attributes = Array(ignored_attributes)
+      @masked_attributes = Array(masked_attributes)
+      @owner = owner
 
       validate!
     end
@@ -38,6 +44,11 @@ module AuditLogger
       (global_configuration.ignored_attributes + ignored_attributes).map(&:to_s).uniq
     end
 
+    # Combina masked attributes globais e locais em uma lista unica.
+    def effective_masked_attributes(global_configuration)
+      (global_configuration.masked_attributes + masked_attributes).map(&:to_s).uniq
+    end
+
     private
 
     # Concentra as validacoes do contrato aceito pela DSL `auditable`.
@@ -46,6 +57,8 @@ module AuditLogger
       validate_i18n_scopes!
       validate_humanizer!
       validate_ignored_attributes!
+      validate_masked_attributes!
+      validate_owner!
     end
 
     # Limita o override de humanizacao a valores simples e previsiveis.
@@ -70,6 +83,18 @@ module AuditLogger
       raise ConfigurationError, "humanizer da model deve ser um Proc/Lambda ou nil"
     end
 
+    def validate_masked_attributes!
+      return if masked_attributes.all? { |item| item.is_a?(String) || item.is_a?(Symbol) }
+
+      raise ConfigurationError, "masked_attributes da model deve ser um Array de strings ou symbols"
+    end
+
+    def validate_owner!
+      return if owner.nil? || owner.is_a?(Symbol) || owner.is_a?(Proc)
+
+      raise ConfigurationError, "owner da model deve ser um Symbol (associacao), um Proc ou nil"
+    end
+
     # Normaliza a entrada para facilitar o filtro de atributos depois.
     def validate_ignored_attributes!
       return if ignored_attributes.all? { |item| item.is_a?(String) || item.is_a?(Symbol) }

data/lib/audit_logger/owner_resolver.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  # Descobre o registro "dono" do log, para consultar o historico de um agregado num lugar so
+  # (ex.: alteracoes da pessoa, dos contratos e dos dependentes dela).
+  class OwnerResolver
+    def self.call(record, model_config)
+      new(record, model_config).call
+    end
+
+    def initialize(record, model_config)
+      @record = record
+      @model_config = model_config
+    end
+
+    # Sem owner configurado, ou com associacao vazia, o dono e o proprio registro.
+    def call
+      attributes_for(resolve_owner || record)
+    end
+
+    # Atributos owner_type/owner_id de um registro qualquer (tambem usado por record_event).
+    def self.attributes_for(owner)
+      return {} if owner.nil?
+
+      klass = owner.class
+      type = klass.respond_to?(:base_class) ? klass.base_class.name : klass.name
+      { owner_type: type, owner_id: owner.id.to_s }
+    end
+
+    private
+
+    attr_reader :record, :model_config
+
+    def resolve_owner
+      case model_config.owner
+      when Symbol then record.public_send(model_config.owner)
+      when Proc then model_config.owner.call(record)
+      end
+    end
+
+    def attributes_for(owner)
+      self.class.attributes_for(owner)
+    end
+  end
+end

data/lib/audit_logger/persistence.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  # Grava uma linha em audit_logs com o contexto do ator (usuario, uuid, ip).
+  # Compartilhado pelo log automatico (auditable) e pelos eventos manuais (record_event).
+  module Persistence
+    def self.create!(model_class_name:, id_object:, action:, audited_changes:, audited_changes_humanize:, owner: {})
+      actor_context = ActorContextResolver.call(AuditLogger.configuration)
+      now = Time.current
+      attributes = {
+        model_class_name: model_class_name,
+        id_object: id_object.to_s,
+        action: action.to_s,
+        uuid: actor_context[:uuid].to_s,
+        changed_by_id: actor_context[:changed_by_id],
+        changed_by_type: actor_context[:changed_by_type],
+        changed_by_other: actor_context[:changed_by_other],
+        audited_changes: audited_changes,
+        audited_changes_humanize: audited_changes_humanize,
+        ip_remote: actor_context[:ip_remote],
+        created_at: now,
+        updated_at: now
+      }
+      # Instalacoes da 0.1.x ainda sem as colunas de dono continuam funcionando.
+      attributes.merge!(owner) if AuditLog.owner_columns?
+
+      AuditLog.create!(attributes)
+    end
+  end
+end

data/lib/audit_logger/railtie.rb

@@ -12,6 +12,7 @@ module AuditLogger
 
     generators do
       require_relative "../generators/audit_logger/install_generator"
+      require_relative "../generators/audit_logger/upgrade_generator"
     end
   end
 end

data/lib/audit_logger/record_audit_entry.rb

@@ -14,7 +14,16 @@ module AuditLogger
     end
 
     # Orquestra toda a montagem do log e persiste o resultado final.
+    # Roda depois do commit: uma falha aqui nao pode virar erro da requisicao que ja gravou.
     def call
+      AuditLogger.safely(record: record, action: action) { persist }
+    end
+
+    private
+
+    attr_reader :record, :action, :configuration, :model_config
+
+    def persist
       payload = ChangeExtractor.new(
         record: record,
         action: action,
@@ -24,8 +33,7 @@ module AuditLogger
 
       return if payload.fetch("fields", {}).empty?
 
-      # Resolve o contexto do ator e gera a versao amigavel do payload antes de persistir.
-      actor_context = ActorContextResolver.call(configuration)
+      # Gera a versao amigavel do payload antes de persistir.
       humanized_payload = Humanizer.new(
         record: record,
         payload: payload,
@@ -33,29 +41,14 @@ module AuditLogger
         configuration: configuration
       ).call
 
-      AuditLog.create!(
+      AuditLogger::Persistence.create!(
         model_class_name: record.class.name,
-        id_object: resolve_record_id,
+        id_object: record.id.to_s,
         action: action,
-        uuid: actor_context[:uuid].to_s,
-        changed_by_id: actor_context[:changed_by_id],
-        changed_by_type: actor_context[:changed_by_type],
-        changed_by_other: actor_context[:changed_by_other],
         audited_changes: payload,
         audited_changes_humanize: humanized_payload,
-        ip_remote: actor_context[:ip_remote],
-        created_at: Time.current,
-        updated_at: Time.current
+        owner: OwnerResolver.call(record, model_config)
       )
     end
-
-    private
-
-    attr_reader :record, :action, :configuration, :model_config
-
-    # Normaliza o id como string para manter consistencia entre tipos de PK.
-    def resolve_record_id
-      record.id.to_s
-    end
   end
 end

data/lib/audit_logger/record_event.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  # Evento registrado a mao, para o que nao passa pelos callbacks do model:
+  # pedido de reset de senha, login, alteracao em massa (update_all) etc.
+  class RecordEvent
+    def self.call(**options)
+      new(**options).call
+    end
+
+    # fields usa o mesmo formato do log automatico: { "campo" => { "old_value" =>, "new_value" => } }
+    # ou { "campo" => { "value" => } }. metadata guarda contexto livre (origem, quantidade...).
+    def initialize(action:, record: nil, model_class_name: nil, id_object: nil, owner: nil, fields: {}, metadata: {})
+      @action = action.to_s
+      @record = record
+      @model_class_name = model_class_name
+      @id_object = id_object
+      @owner = owner
+      @fields = stringify(fields)
+      @metadata = metadata || {}
+    end
+
+    def call
+      AuditLogger.safely(record: record, action: action) { persist }
+    end
+
+    private
+
+    attr_reader :action, :record, :model_class_name, :id_object, :owner, :fields, :metadata
+
+    def persist
+      payload = { "type" => action, "fields" => fields }
+      payload["metadata"] = stringify(metadata) unless metadata.empty?
+
+      AuditLogger::Persistence.create!(
+        model_class_name: model_class_name || record&.class&.name || "AuditLogger::Event",
+        id_object: id_object || record&.id,
+        action: action,
+        audited_changes: payload,
+        audited_changes_humanize: humanize(payload),
+        owner: owner_attributes
+      )
+    end
+
+    # Com registro, reaproveita a humanizacao (labels e associacoes) da model dele.
+    def humanize(payload)
+      return payload unless record
+
+      humanized = Humanizer.new(
+        record: record, payload: payload, model_config: model_config, configuration: AuditLogger.configuration
+      ).call
+      humanized.merge(payload.slice("metadata"))
+    end
+
+    def owner_attributes
+      return OwnerResolver.attributes_for(owner) if owner
+      return OwnerResolver.call(record, model_config) if record
+
+      {}
+    end
+
+    def model_config
+      klass = record.class
+      klass.respond_to?(:audit_logger_model_config) ? klass.audit_logger_model_config : ModelConfig.new
+    end
+
+    def stringify(hash)
+      hash.to_h.each_with_object({}) do |(key, value), result|
+        result[key.to_s] = value.is_a?(Hash) ? stringify(value) : value
+      end
+    end
+  end
+end

data/lib/audit_logger/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AuditLogger
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/audit_logger.rb

@@ -14,7 +14,10 @@ require_relative "audit_logger/audit_log"
 require_relative "audit_logger/actor_context_resolver"
 require_relative "audit_logger/change_extractor"
 require_relative "audit_logger/humanizer"
+require_relative "audit_logger/owner_resolver"
+require_relative "audit_logger/persistence"
 require_relative "audit_logger/record_audit_entry"
+require_relative "audit_logger/record_event"
 require_relative "audit_logger/auditable"
 
 module AuditLogger
@@ -38,6 +41,38 @@ module AuditLogger
     def reset_configuration!
       @configuration = Configuration.new
     end
+
+    # Registra um evento que nao passa pelos callbacks (reset de senha, login, update_all).
+    # Ver AuditLogger::RecordEvent para as opcoes.
+    def record_event(**options)
+      RecordEvent.call(**options)
+    end
+
+    # A auditoria nunca derruba a operacao principal: registra o erro, chama o error_handler
+    # e segue. Com raise_errors = true (util em teste) o erro sobe.
+    def safely(record: nil, action: nil)
+      yield
+    rescue StandardError => e
+      raise if configuration.raise_errors
+
+      report_error(e, record, action)
+      nil
+    end
+
+    private
+
+    def report_error(error, record, action)
+      alvo = record ? " de #{record.class.name}##{record.id}" : ""
+      message = "[AuditLogger] Falha ao registrar #{action}#{alvo}: #{error.class} - #{error.message}"
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error(message)
+      else
+        warn(message)
+      end
+      configuration.error_handler&.call(error, record, action)
+    rescue StandardError
+      nil
+    end
   end
 end
 

data/lib/generators/audit_logger/templates/add_owner_to_audit_logs.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Upgrade da 0.1.x: colunas do registro "dono", para consultar o historico de um agregado.
+class AddOwnerToAuditLogs < ActiveRecord::Migration<%= migration_version %>
+  def up
+    add_column :audit_logs, :owner_type, :string unless column_exists?(:audit_logs, :owner_type)
+    add_column :audit_logs, :owner_id, :string unless column_exists?(:audit_logs, :owner_id)
+    return if index_exists?(:audit_logs, [:owner_type, :owner_id, :created_at])
+
+    add_index :audit_logs, [:owner_type, :owner_id, :created_at]
+  end
+
+  def down
+    remove_index :audit_logs, [:owner_type, :owner_id, :created_at] if index_exists?(:audit_logs, [:owner_type, :owner_id, :created_at])
+    remove_column :audit_logs, :owner_id if column_exists?(:audit_logs, :owner_id)
+    remove_column :audit_logs, :owner_type if column_exists?(:audit_logs, :owner_type)
+  end
+end

data/lib/generators/audit_logger/templates/audit_logger_initializer.rb.tt

@@ -42,6 +42,19 @@ AuditLogger.configure do |config|
   # Campos que normalmente nao agregam valor na auditoria.
   config.ignored_attributes = [:created_at, :updated_at, :lock_version]
 
+  # Campos sensiveis: a alteracao e registrada (ex.: "senha alterada"), mas o valor vira mask_value.
+  # Acrescente tokens proprios do projeto. Por model: auditable masked_attributes: [:token]
+  config.masked_attributes = [:password, :password_digest, :encrypted_password, :reset_password_token, :confirmation_token, :unlock_token]
+  config.mask_value = "[FILTRADO]"
+
+  # Em belongs_to, grava no payload humanizado o rotulo do registro associado (old_value_label/new_value_label).
+  config.resolve_associations = true
+
+  # A auditoria roda depois do commit e nunca derruba a requisicao: falha vira log de erro.
+  # Ligue raise_errors no ambiente de teste para enxergar problemas.
+  config.raise_errors = false
+  # config.error_handler = ->(error, record, action) { Sentry.capture_exception(error) }
+
   # Humanizer opcional.
   # Se retornar nil, a gem usa o fallback padrao baseado em I18n.
   config.humanizer = ->(_model_klass, _attribute, _old_value, _new_value) { nil }

data/lib/generators/audit_logger/templates/create_audit_logs.rb.tt

@@ -14,6 +14,8 @@ class CreateAuditLogs < ActiveRecord::Migration<%= migration_version %>
         t.jsonb :audited_changes, null: false, default: {}
         t.jsonb :audited_changes_humanize, null: false, default: {}
         t.string :ip_remote
+        t.string :owner_type
+        t.string :owner_id
         t.datetime :deleted_at
         t.timestamps
       end
@@ -21,6 +23,7 @@ class CreateAuditLogs < ActiveRecord::Migration<%= migration_version %>
       add_index :audit_logs, [:model_class_name, :id_object]
       add_index :audit_logs, :action
       add_index :audit_logs, [:changed_by_type, :changed_by_id]
+      add_index :audit_logs, [:owner_type, :owner_id, :created_at]
       add_index :audit_logs, :created_at
       add_index :audit_logs, :deleted_at
     end

data/lib/generators/audit_logger/upgrade_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module AuditLogger
+  module Generators
+    # Para quem instalou a 0.1.x: cria a migration das colunas owner_type/owner_id.
+    class UpgradeGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Cria a migration que acrescenta owner_type/owner_id em audit_logs (upgrade da 0.1.x)."
+
+      def copy_migration
+        migration_template "add_owner_to_audit_logs.rb.tt", "db/migrate/add_owner_to_audit_logs.rb"
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+
+      def self.next_migration_number(path)
+        ActiveRecord::Generators::Base.next_migration_number(path)
+      end
+    end
+  end
+end