provenance 1.0.0

data/lib/provenance/trackers/auditable.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "action_controller"
+require "active_record"
+
+module Provenance
+  # Controller-side concern. Wraps each action, opens a journal, collects model
+  # changes for the request and delivers the assembled audit event to the
+  # configured hooks once all transactions have completed.
+  module Auditable
+    extend ActiveSupport::Concern
+    include Provenance::Trackers::Providers
+
+    included do
+      around_action :track_model_changes
+    end
+
+    private
+
+    def track_model_changes
+      return yield if skip_model_change_tracking? || !Provenance.config.enabled
+
+      Provenance::Context.journal = Provenance::Journal.new
+
+      Provenance::Context.pending_audit_log = -> do
+        next unless Provenance::Context.request_completed?
+
+        status = Provenance::Context.response_status
+        next if status && status >= 400
+
+        log_audit_event_and_clear_journal
+      end
+
+      request_obj = request
+      if request_obj.respond_to?(:uuid)
+        uuid_value = request_obj.uuid
+        Provenance::Context.request_id = uuid_value.to_s if uuid_value && !uuid_value.to_s.strip.empty?
+      end
+
+      Thread.current[:provenance_send_scheduled] = nil
+
+      yield
+
+      Provenance::Context.response_status = if response.respond_to?(:status)
+                                              response.status
+                                            else
+                                              200
+                                            end
+
+      send_audit_after_all_commits
+    end
+
+    def send_audit_after_all_commits
+      return unless Provenance.config.enabled
+
+      journal = Provenance::Context.journal
+      return unless journal
+
+      active_transactions = journal.instance_variable_get(:@active_transactions)
+
+      return if active_transactions.any?
+
+      send_audit_if_ready
+    end
+
+    def send_audit_if_ready
+      return unless Provenance.config.enabled
+
+      journal = Provenance::Context.journal
+
+      if request.respond_to?(:get?) && (request.get? || request.head?)
+        log_audit_event_and_clear_journal
+        return
+      end
+
+      return unless journal&.all_transactions_completed?
+
+      log_audit_event_and_clear_journal
+    end
+
+    def log_audit_event_and_clear_journal
+      return if skip_audit_logging? || !Provenance.config.enabled
+
+      journal = Provenance::Context.journal
+      return unless journal
+
+      begin
+        audit_data = audit_log_data
+
+        Provenance.config.audit_hooks.each do |hook|
+          hook.call(audit_data)
+        end
+      ensure
+        Provenance::Context.cleanup
+      end
+    end
+
+    def audit_log_data
+      journal_data = Provenance::Context.journal&.to_h
+
+      response_status = response.respond_to?(:status) ? response.status : 200
+
+      message_data = if response_status < 400
+                       (journal_data || {}).merge(params: filter_sensitive_params(params.to_unsafe_h))
+                     else
+                       filter_sensitive_params(params.to_unsafe_h)
+                     end
+
+      {
+        timestamp: Time.current.utc.iso8601(3),
+        event_type: generate_event_type,
+        status: response_status,
+        message: stringify_hash_values(message_data),
+        username: username_from_provider || "unauthenticated",
+        remote_ip: remote_ip_from_provider || "unknown",
+        origin_ip: origin_ip_from_provider || "unknown",
+        session_id: session_id_from_provider || "unauthenticated",
+        roles: roles_from_provider || [],
+        request_id: Provenance::Context.request_id,
+        source: Provenance.config.source_name
+      }.compact
+    end
+  end
+end

data/lib/provenance/trackers/bulk_operations.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module Provenance
+  module Trackers
+    # Intercepts bulk operations (`update_all`/`delete_all`) which bypass
+    # ActiveRecord callbacks and therefore never reach the regular Trackable
+    # path. Captures the ids of the affected rows before execution and records
+    # the change in the journal.
+    module BulkOperations
+      def update_all(*args)
+        Provenance::Trackers::BulkOperations.track(self, :bulk_update, args.first) { super }
+      end
+
+      def delete_all(*args)
+        Provenance::Trackers::BulkOperations.track(self, :bulk_delete, nil) { super }
+      end
+
+      class << self
+        def track(relation, action, updates)
+          journal = Provenance::Context.journal
+          klass = relation.klass
+
+          return yield unless trackable?(journal, klass)
+
+          ids, truncated = safe_collect_ids(relation, klass)
+          transaction_id = safe_transaction_id(klass)
+
+          result = yield
+
+          begin
+            journal.add_bulk_change(klass, action, ids, updates,
+              truncated: truncated, transaction_id: transaction_id)
+          rescue StandardError
+            # Auditing must never break the underlying operation.
+          end
+
+          result
+        end
+
+        private
+
+        def trackable?(journal, klass)
+          journal &&
+            Provenance.config.track_bulk_operations &&
+            klass.respond_to?(:include?) &&
+            klass.include?(Provenance::Trackable)
+        end
+
+        def safe_collect_ids(relation, klass)
+          pk = klass.primary_key
+          return [[], false] unless pk
+
+          max = Provenance.config.bulk_operations_max_ids.to_i
+          ids = relation.unscope(:select).limit(max + 1).pluck(pk)
+          [ids.first(max), ids.size > max]
+        rescue StandardError
+          [[], false]
+        end
+
+        def safe_transaction_id(klass)
+          Provenance::TransactionKey.for_connection(klass.connection)
+        rescue StandardError
+          Provenance::Context.request_id
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Relation.prepend(Provenance::Trackers::BulkOperations) if defined?(ActiveRecord::Relation)

data/lib/provenance/trackers/error_reporting.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/inflector"
+
+module Provenance
+  # Controller-side concern that emits a dedicated audit event for failed
+  # requests. Call `audit_error(error, status)` from your error handlers.
+  module ErrorReporting
+    extend ActiveSupport::Concern
+    include Provenance::Trackers::Providers
+
+    STATUS_CODES = {
+      not_found: 404,
+      unauthorized: 401,
+      forbidden: 403,
+      unprocessable_entity: 422,
+      conflict: 409
+    }.freeze
+
+    def audit_error(error_message, status)
+      return if skip_audit_logging? || !Provenance.config.enabled
+
+      numeric_status = status.is_a?(Symbol) ? STATUS_CODES[status] || 500 : status
+
+      audit_data = {
+        timestamp: Time.current.utc.iso8601(3),
+        event_type: generate_event_type,
+        status: numeric_status.to_s,
+        message: stringify_hash_values({
+          error_type: error_message.class.name,
+          error_message: error_message.is_a?(Exception) ? error_message.message : error_message.to_s,
+          params: filter_sensitive_params(params.to_unsafe_h)
+        }),
+        username: username_from_provider || "unauthenticated",
+        remote_ip: remote_ip_from_provider || "unknown",
+        origin_ip: origin_ip_from_provider || "unknown",
+        session_id: session_id_from_provider || "unauthenticated",
+        roles: roles_from_provider || [],
+        source: Provenance.config.source_name
+      }.compact
+
+      Provenance.config.audit_hooks.each do |hook|
+        hook.call(audit_data)
+      end
+    end
+  end
+end

data/lib/provenance/trackers/providers.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/inflector"
+
+module Provenance
+  module Trackers
+    # Shared controller-side helpers: per-action opt-outs, custom event types,
+    # value providers and the recursive sanitizers used when serializing audit
+    # payloads.
+    module Providers
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def skip_model_change_tracking(*actions)
+          @skip_model_change_tracking_actions ||= []
+          @skip_model_change_tracking_actions += actions.map(&:to_s)
+        end
+
+        def skip_model_change_tracking_actions
+          @skip_model_change_tracking_actions || []
+        end
+
+        def custom_audit_event_type(action, event_type)
+          @custom_audit_event_types ||= {}
+          @custom_audit_event_types[action] = event_type
+        end
+
+        def skip_audit_logging(*actions)
+          @skip_audit_logging_actions ||= []
+          @skip_audit_logging_actions += actions.map(&:to_s)
+        end
+
+        def skip_audit_logging_actions
+          @skip_audit_logging_actions || []
+        end
+      end
+
+      private
+
+      def username_from_provider
+        return nil unless Provenance.config.username_provider
+
+        call_provider(Provenance.config.username_provider)
+      end
+
+      def roles_from_provider
+        return [] unless Provenance.config.roles_provider
+
+        call_provider(Provenance.config.roles_provider)
+      end
+
+      def remote_ip_from_provider
+        return nil unless Provenance.config.remote_ip_provider
+
+        call_provider(Provenance.config.remote_ip_provider)
+      end
+
+      def session_id_from_provider
+        return nil unless Provenance.config.session_id_provider
+
+        call_provider(Provenance.config.session_id_provider)
+      end
+
+      def origin_ip_from_provider
+        return nil unless Provenance.config.origin_ip_provider
+
+        call_provider(Provenance.config.origin_ip_provider)
+      end
+
+      def call_provider(provider)
+        if provider.respond_to?(:call) || provider.is_a?(Proc)
+          provider.call(self)
+        else
+          provider
+        end
+      end
+
+      def filter_sensitive_params(params)
+        sensitive_attrs = Provenance.config.sensitive_attributes
+        return params if sensitive_attrs.empty?
+
+        case params
+        when Hash
+          filtered_data = {}
+          params.each do |key, value|
+            filtered_data[key] = if sensitive_attrs.include?(key.to_s)
+                                   "[FILTERED]"
+                                 else
+                                   filter_sensitive_params(value)
+                                 end
+          end
+          filtered_data
+        when Array
+          params.map { |item| filter_sensitive_params(item) }
+        else
+          params
+        end
+      end
+
+      def generate_event_type
+        controller_path = params[:controller].to_s.tr("/", "_")
+        action = action_name
+
+        custom_event_type = self.class.instance_variable_get(:@custom_audit_event_types)&.[](action.to_sym)
+        return custom_event_type if custom_event_type
+
+        singular_path = ActiveSupport::Inflector.singularize(controller_path)
+
+        case action.to_sym
+        when :index
+          "read_#{controller_path}"
+        when :show
+          "show_#{singular_path}"
+        when :create
+          "create_#{controller_path}"
+        when :update
+          "update_#{singular_path}"
+        when :destroy
+          "destroy_#{singular_path}"
+        else
+          "#{action}_#{controller_path}"
+        end
+      end
+
+      def skip_model_change_tracking?
+        self.class.skip_model_change_tracking_actions.include?(action_name) ||
+          (respond_to?(:skip_audit_logging?) && skip_audit_logging?)
+      end
+
+      def skip_audit_logging?
+        self.class.skip_audit_logging_actions.include?(action_name)
+      end
+
+      def stringify_hash_values(data, seen = Set.new)
+        case data
+        when Hash
+          return data if seen.include?(data.object_id)
+
+          seen.add(data.object_id)
+          data.transform_values { |value| stringify_hash_values(value, seen) }
+        when Array
+          return data if seen.include?(data.object_id)
+
+          seen.add(data.object_id)
+          data.map { |item| stringify_hash_values(item, seen) }
+        when Numeric, TrueClass, FalseClass
+          data.to_s
+        when Date, Time, DateTime
+          data.iso8601
+        when NilClass, String
+          data
+        else
+          begin
+            stringify_hash_values(data.as_json, seen)
+          rescue StandardError
+            data.to_s
+          end
+        end
+      end
+    end
+  end
+end