provenance 2.0.0

data/lib/provenance/actor.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Provenance
+  # Who performed an action.
+  class Actor
+    # @return [String, nil]
+    attr_reader :id
+    # @return [String, nil]
+    attr_reader :type
+    # @return [String, nil]
+    attr_reader :display
+    # @return [Array<String>]
+    attr_reader :roles
+    # @return [Actor, nil] the real user behind a "login as" session
+    attr_reader :impersonator
+
+    # Builds an actor from a user-like object, a Hash, an {Actor} or nil.
+    #
+    # Objects are read through +provenance_actor+ (returning a Hash) when defined,
+    # otherwise through +id+, +provenance_display+/+email+/+name+ and +provenance_roles+.
+    #
+    # @param value [Object, Hash, Actor, nil]
+    # @return [Actor, nil]
+    def self.wrap(value)
+      case value
+      when nil then nil
+      when Actor then value
+      when Hash then new(**value.symbolize_keys.slice(:id, :type, :display, :roles, :impersonator))
+      else
+        return wrap(value.provenance_actor) if value.respond_to?(:provenance_actor)
+
+        new(
+          id: value.respond_to?(:id) ? value.id : nil,
+          type: value.class.name,
+          display: display_for(value),
+          roles: value.respond_to?(:provenance_roles) ? value.provenance_roles : []
+        )
+      end
+    end
+
+    # @api private
+    def self.display_for(value)
+      %i[provenance_display email name].each do |m|
+        return value.public_send(m) if value.respond_to?(m)
+      end
+      nil
+    end
+
+    # @param id [Object]
+    # @param type [String, nil]
+    # @param display [String, nil]
+    # @param roles [Array]
+    # @param impersonator [Object, nil] anything {wrap} accepts
+    def initialize(id:, type: nil, display: nil, roles: [], impersonator: nil)
+      @id = id&.to_s
+      @type = type&.to_s
+      @display = display&.to_s
+      @roles = Array(roles).map(&:to_s)
+      @impersonator = Actor.wrap(impersonator)
+      freeze
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      {
+        "id" => id,
+        "type" => type,
+        "display" => display,
+        "roles" => roles,
+        "impersonator" => impersonator&.to_h
+      }
+    end
+
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(Actor) && other.to_h == to_h
+    end
+    alias_method :eql?, :==
+
+    # @return [Integer]
+    def hash
+      to_h.hash
+    end
+  end
+end

data/lib/provenance/configuration.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Provenance
+  # Global settings, see {Provenance.configure}.
+  class Configuration
+    # Accepted values for {#format}.
+    FORMATS = %i[native ocsf cloudevents].freeze
+
+    # Settings for tamper evidence (section 7 of the specification).
+    class Integrity
+      # @return [String, nil] HMAC-SHA256 key; +nil+ disables integrity
+      attr_accessor :key
+
+      # @return [Boolean]
+      def enabled?
+        key.present?
+      end
+    end
+
+    # @return [Boolean] master switch; default +true+
+    attr_accessor :enabled
+    # @return [Array<Symbol, String, Regexp>] extra attributes to redact, merged with Rails filter_parameters
+    attr_accessor :redact_attributes
+    # @return [Array<String>] attributes never recorded in diffs; default +created_at+, +updated_at+
+    attr_accessor :ignored_attributes
+    # @return [Symbol] :native, :ocsf or :cloudevents
+    attr_accessor :format
+    # @return [Boolean] write events to the outbox table instead of delivering inline
+    attr_accessor :outbox
+    # @return [ActiveSupport::Duration] how long delivered outbox rows are kept
+    attr_accessor :outbox_retention
+    # @return [Integer] rows per relay batch
+    attr_accessor :outbox_batch_size
+    # @return [Boolean] enqueue {RelayJob} after each outbox write
+    attr_accessor :outbox_enqueue_relay
+    # @return [Boolean] emit successful GET/HEAD actions without changes
+    attr_accessor :audit_reads
+    # @return [Array<String>] exception class names that produce a +denied+ outcome
+    attr_accessor :denied_exceptions
+    # @return [Integer] maximum number of ids recorded for a bulk change
+    attr_accessor :bulk_ids_limit
+    # @return [Array<#deliver>] configured sinks
+    attr_reader :sinks
+    # @return [Integrity]
+    attr_reader :integrity
+    # @return [Proc, nil] actor resolver set with {#actor}
+    attr_reader :actor_resolver
+    # @return [Proc, nil] error handler set with {#on_error}
+    attr_reader :error_handler
+    # @return [Logger, nil] logger for diagnostics; defaults to Rails.logger
+    attr_writer :logger
+    # @return [String] application name
+    attr_writer :app_name
+
+    def initialize
+      @enabled = true
+      @redact_attributes = []
+      @ignored_attributes = %w[created_at updated_at]
+      @format = :native
+      @sinks = []
+      @outbox = false
+      @outbox_retention = 7.days
+      @outbox_batch_size = 100
+      @outbox_enqueue_relay = true
+      @integrity = Integrity.new
+      @audit_reads = false
+      @denied_exceptions = ["CanCan::AccessDenied", "Pundit::NotAuthorizedError"]
+      @bulk_ids_limit = 500
+    end
+
+    # Application name used as the event +app+ and CloudEvents +source+. Defaults to
+    # the Rails application module name, underscored.
+    #
+    # @return [String]
+    def app_name
+      @app_name ||= if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+        Rails.application.class.module_parent_name.underscore
+      else
+        "app"
+      end
+    end
+
+    # @return [Logger]
+    def logger
+      @logger || (defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger) || Logger.new($stderr)
+    end
+
+    # Sets the actor resolver. The block receives a {Context} and returns a user-like
+    # object, a Hash or an {Actor}.
+    #
+    # @yieldparam ctx [Context]
+    # @return [void]
+    def actor(&block)
+      @actor_resolver = block
+    end
+
+    # Sets the handler for sink and emission failures.
+    #
+    # @yieldparam exception [Exception]
+    # @yieldparam event [Hash, nil]
+    # @return [void]
+    def on_error(&block)
+      @error_handler = block
+    end
+
+    # Adds a sink. Accepts a built-in type (:logger, :io, :http, :proc, :memory,
+    # :kafka) with its options, or any object responding to +#deliver(batch)+.
+    #
+    # @param type [Symbol, #deliver]
+    # @return [#deliver] the sink instance
+    def sink(type, *args, **options, &block)
+      Sinks.build(type, *args, **options, &block).tap { |s| @sinks << s }
+    end
+
+    # Reports an error through the configured handler, falling back to the logger.
+    #
+    # @param exception [Exception]
+    # @param event [Hash, nil]
+    # @return [void]
+    def report_error(exception, event = nil)
+      if error_handler
+        error_handler.call(exception, event)
+      else
+        logger.error("[provenance] #{exception.class}: #{exception.message}")
+      end
+    rescue => e
+      logger.error("[provenance] error handler failed: #{e.class}: #{e.message}")
+    end
+
+    # @param exception [Exception]
+    # @return [Boolean] whether the exception produces a +denied+ outcome
+    def denied?(exception)
+      names = Array(denied_exceptions).map(&:to_s)
+      exception.class.ancestors.any? { |mod| names.include?(mod.name) }
+    end
+
+    # @raise [ConfigurationError]
+    # @return [true]
+    def validate!
+      unless FORMATS.include?(format)
+        raise ConfigurationError, "format must be one of #{FORMATS.join(", ")}, got #{format.inspect}"
+      end
+      if integrity.enabled? && !outbox
+        raise ConfigurationError, "integrity requires the outbox (set c.outbox = true)"
+      end
+      unless bulk_ids_limit.is_a?(Integer) && bulk_ids_limit >= 0
+        raise ConfigurationError, "bulk_ids_limit must be a non-negative Integer"
+      end
+      true
+    end
+  end
+end

data/lib/provenance/context.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Provenance
+  # What the actor resolver sees: whichever of controller, job, request and Rack env
+  # are available for the current action.
+  class Context
+    # @return [ActionController::Metal, nil]
+    attr_accessor :controller
+    # @return [ActiveJob::Base, nil]
+    attr_accessor :job
+    # @return [Hash, nil] the Rack env
+    attr_accessor :env
+
+    # @param controller [ActionController::Metal, nil]
+    # @param job [ActiveJob::Base, nil]
+    # @param request [ActionDispatch::Request, nil]
+    # @param env [Hash, nil]
+    def initialize(controller: nil, job: nil, request: nil, env: nil)
+      @controller = controller
+      @job = job
+      @request = request
+      @env = env
+    end
+
+    # @return [ActionDispatch::Request, nil]
+    def request
+      @request ||= controller&.request || (env && ActionDispatch::Request.new(env))
+    end
+  end
+end

data/lib/provenance/controller.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Provenance
+  # Controller integration, included into ActionController::Base and ::API.
+  #
+  # @example
+  #   class InvoicesController < ApplicationController
+  #     provenance_action_name ->(controller) { "billing.#{controller.action_name}" }
+  #     skip_provenance only: :preview
+  #   end
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_provenance_action_name, instance_accessor: false, default: nil
+      class_attribute :_provenance_skip, instance_accessor: false, default: nil
+    end
+
+    class_methods do
+      # Overrides the action name for this controller.
+      #
+      # @param callable [#call] receives the controller, returns the name
+      # @return [void]
+      def provenance_action_name(callable = nil, &block)
+        self._provenance_action_name = callable || block
+      end
+
+      # Excludes actions of this controller from auditing.
+      #
+      # @param only [Array<Symbol>, Symbol, nil]
+      # @param except [Array<Symbol>, Symbol, nil]
+      # @return [void]
+      def skip_provenance(only: nil, except: nil)
+        self._provenance_skip = {only: only && Array(only).map(&:to_s), except: Array(except).map(&:to_s)}
+      end
+    end
+
+    # @api private
+    def process_action(*)
+      Provenance.current&.context&.controller ||= self
+      super
+    end
+
+    # Name of the current action for Provenance.
+    #
+    # @return [String]
+    def provenance_action_name
+      custom = self.class._provenance_action_name
+      custom ? custom.call(self).to_s : "#{controller_path}##{action_name}"
+    end
+
+    # @return [Boolean] whether this controller action is excluded
+    def skip_provenance?
+      rule = self.class._provenance_skip
+      return false unless rule
+      return false if rule[:except].include?(action_name.to_s)
+
+      rule[:only].nil? || rule[:only].include?(action_name.to_s)
+    end
+
+    private
+
+    def append_info_to_payload(payload)
+      super
+      payload[:provenance_action_name] = provenance_action_name
+      payload[:provenance_skip] = skip_provenance?
+    rescue => e
+      Provenance.config.report_error(e)
+    end
+
+    # Applies the process_action.action_controller payload to the current action.
+    #
+    # @api private
+    module Subscriber
+      module_function
+
+      # @param payload [Hash]
+      # @return [void]
+      def call(payload)
+        action = Provenance.current
+        return unless action&.kind == "http"
+
+        if payload[:provenance_skip]
+          action.skip!
+          return
+        end
+        action.name = payload[:provenance_action_name] || "#{payload[:controller]}##{payload[:action]}"
+        action.request["status"] = payload[:status] if payload[:status]
+        action.fail!(payload[:exception_object]) if payload[:exception_object]
+      end
+    end
+  end
+end

data/lib/provenance/emitter.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Provenance
+  # Turns closed actions into events and hands them to the outbox or the sinks.
+  # Never raises: failures are reported through +on_error+.
+  module Emitter
+    module_function
+
+    # Schedules emission of a closed action once every open transaction has committed.
+    #
+    # @param action [Action]
+    # @return [void]
+    def finish(action)
+      return if action.skipped? || !Provenance.enabled?
+
+      ActiveRecord.after_all_transactions_commit { emit(action) }
+    rescue => e
+      Provenance.config.report_error(e)
+    end
+
+    # Builds and dispatches the event for an action if it is auditable.
+    #
+    # @param action [Action]
+    # @return [Hash, nil] the native event
+    def emit(action)
+      return unless action.auditable?
+
+      event = Event.build(action)
+      dispatch(event)
+      event
+    rescue => e
+      Provenance.config.report_error(e, event)
+      nil
+    end
+
+    # @param event [Hash] native event
+    # @return [void]
+    def dispatch(event)
+      if Testing.capturing?
+        Testing.record(event)
+      elsif Provenance.config.outbox
+        Outbox.write(event)
+      else
+        deliver([event])
+      end
+    end
+
+    # Serializes native events in the configured format and delivers them to every
+    # sink. A failing sink does not prevent delivery to the others.
+    #
+    # @param events [Array<Hash>] native events
+    # @param raise_errors [Boolean] re-raise the first sink failure after trying all sinks
+    # @return [void]
+    def deliver(events, raise_errors: false)
+      batch = Serializers.serialize_all(events, Provenance.config.format)
+      failure = nil
+      Provenance.config.sinks.each do |sink|
+        sink.deliver(batch)
+      rescue => e
+        failure ||= e
+        events.each { |event| Provenance.config.report_error(e, event) } unless raise_errors
+      end
+      raise failure if failure && raise_errors
+    end
+  end
+end

data/lib/provenance/entity_change.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Provenance
+  # One record-level change attached to an action.
+  class EntityChange
+    # Accepted operations.
+    OPERATIONS = %w[create update destroy link unlink bulk_update bulk_delete bulk_insert].freeze
+
+    # @return [String]
+    attr_reader :entity
+    # @return [String]
+    attr_reader :operation
+    # @return [Hash, nil] {attr => [before, after]}; create holds after values, destroy before values
+    attr_reader :diff
+    # @return [String, nil] association name for link/unlink
+    attr_reader :association
+    # @return [Hash, nil] {"type", "id"} of the linked record for link/unlink
+    attr_reader :target
+    # @return [Integer, nil] affected rows for bulk operations
+    attr_reader :count
+    # @return [String, nil] fingerprint of the WHERE clause for bulk operations
+    attr_reader :where
+    # @return [Array<String>, nil] affected ids for bulk operations
+    attr_reader :ids
+    # @return [Boolean, nil] whether {#ids} was cut at +bulk_ids_limit+
+    attr_reader :truncated
+
+    # @param entity [String]
+    # @param operation [String, Symbol]
+    # @param entity_id [Object, Proc] a Proc is evaluated when the event is built
+    def initialize(entity:, operation:, entity_id: nil, diff: nil, association: nil, target: nil,
+      count: nil, where: nil, ids: nil, truncated: nil)
+      @entity = entity.to_s
+      @operation = operation.to_s
+      raise ArgumentError, "unknown operation #{operation.inspect}" unless OPERATIONS.include?(@operation)
+
+      @entity_id = entity_id
+      @diff = diff
+      @association = association&.to_s
+      @target = target
+      @count = count
+      @where = where
+      @ids = ids
+      @truncated = truncated
+    end
+
+    # @return [String, nil]
+    def entity_id
+      value = @entity_id.is_a?(Proc) ? @entity_id.call : @entity_id
+      value&.to_s
+    end
+
+    # @return [Hash, nil] {#target} with lazily computed ids evaluated
+    def resolved_target
+      target&.transform_values { |v| v.is_a?(Proc) ? v.call&.to_s : v }
+    end
+
+    # @return [Boolean]
+    def bulk?
+      operation.start_with?("bulk_")
+    end
+
+    # @return [Hash{String => Object}] JSON-safe representation
+    def to_h
+      h = {"entity" => entity, "entity_id" => entity_id, "operation" => operation, "diff" => JsonSafe.call(diff)}
+      h.merge!("association" => association, "target" => JsonSafe.call(resolved_target)) if association
+      if bulk?
+        h.merge!("count" => count, "where" => where, "ids" => Array(ids).map(&:to_s), "truncated" => truncated ? true : false)
+      end
+      h
+    end
+  end
+end

data/lib/provenance/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Provenance
+  # Base class for all Provenance errors.
+  class Error < StandardError; end
+
+  # Raised when {Configuration#validate!} finds an invalid setting.
+  class ConfigurationError < Error; end
+
+  # Raised by sinks when an event batch could not be delivered.
+  class DeliveryError < Error; end
+end

data/lib/provenance/event.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Provenance
+  # Builds the immutable native event (schema "provenance/event@2") for an action.
+  module Event
+    # Value of the +schema+ field.
+    SCHEMA = "provenance/event@2"
+
+    module_function
+
+    # @param action [Action]
+    # @return [Hash{String => Object}] deeply frozen, JSON-safe event
+    def build(action)
+      event = {
+        "schema" => SCHEMA,
+        "id" => action.id,
+        "occurred_at" => action.started_at.utc.iso8601(3),
+        "app" => Provenance.config.app_name,
+        "action" => {"kind" => action.kind, "name" => action.name.to_s, "caused_by" => action.caused_by},
+        "actor" => action.actor&.to_h,
+        "request" => (action.kind == "http") ? JsonSafe.call(action.request) : nil,
+        "outcome" => {"result" => action.result, "error" => action.error},
+        "changes" => action.changes.map(&:to_h),
+        "metadata" => JsonSafe.call(Redactor.deep(action.metadata))
+      }
+      deep_freeze(event)
+    end
+
+    # Returns a frozen deep copy of a JSON-like structure.
+    #
+    # @param value [Object]
+    # @return [Object]
+    def deep_freeze(value)
+      case value
+      when Hash then value.to_h { |k, v| [k.to_s.freeze, deep_freeze(v)] }.freeze
+      when Array then value.map { |v| deep_freeze(v) }.freeze
+      when String then value.frozen? ? value : value.dup.freeze
+      else value
+      end
+    end
+  end
+end

data/lib/provenance/integrity.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Provenance
+  # Tamper evidence: a per-app HMAC-SHA256 chain over canonical JSON.
+  #
+  #   mac = HMAC-SHA256(key, prev + canonical_json(event without "integrity"))
+  module Integrity
+    module_function
+
+    # Canonical JSON: object keys sorted, no insignificant whitespace.
+    #
+    # @param value [Object] JSON-like structure
+    # @return [String]
+    def canonical(value)
+      JSON.generate(sort(value))
+    end
+
+    # @param key [String]
+    # @param prev [String, nil] mac of the previous event
+    # @param event [Hash] native event; an "integrity" member is ignored
+    # @return [String] lowercase hex HMAC-SHA256
+    def mac(key, prev, event)
+      payload = stringify(event).except("integrity")
+      OpenSSL::HMAC.hexdigest("SHA256", key.to_s, "#{prev}#{canonical(payload)}")
+    end
+
+    # Verifies a contiguous, seq-ordered list of events from one app. The +prev+ of
+    # the first event is taken as given, so a pruned outbox still verifies.
+    #
+    # @param events [Array<Hash>] native events with an "integrity" member
+    # @param key [String]
+    # @return [Integer, nil] the first broken seq, or nil when the chain is intact
+    def verify(events, key:)
+      previous = nil
+      events.each do |raw|
+        event = stringify(raw)
+        integrity = event["integrity"]
+        expected_seq = previous ? previous["seq"] + 1 : nil
+        return expected_seq || 0 unless integrity.is_a?(Hash) && integrity["seq"].is_a?(Integer)
+
+        seq = integrity["seq"]
+        return seq if previous && (seq != expected_seq || integrity["prev"] != previous["mac"])
+        return seq unless secure_compare(mac(key, integrity["prev"], event), integrity["mac"].to_s)
+
+        previous = integrity
+      end
+      nil
+    end
+
+    # @api private
+    def secure_compare(a, b)
+      a.bytesize == b.bytesize && OpenSSL.fixed_length_secure_compare(a, b)
+    end
+
+    # @api private
+    def sort(value)
+      case value
+      when Hash then value.keys.map(&:to_s).sort.to_h { |k| [k, sort(value[k] || value[k.to_sym])] }
+      when Array then value.map { |v| sort(v) }
+      else value
+      end
+    end
+
+    # @api private
+    def stringify(value)
+      case value
+      when Hash then value.to_h { |k, v| [k.to_s, stringify(v)] }
+      when Array then value.map { |v| stringify(v) }
+      else value
+      end
+    end
+  end
+end

data/lib/provenance/job.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Provenance
+  # ActiveJob integration, included into ActiveJob::Base. Each performed job is a
+  # +job+ action; the enqueuing action's id and actor travel in the job payload
+  # under the "provenance" key.
+  module Job
+    extend ActiveSupport::Concern
+
+    # Job payload key.
+    KEY = "provenance"
+
+    included do
+      class_attribute :_provenance_skip, instance_accessor: false, default: false
+      around_perform { |job, block| Provenance::Job.perform(job, &block) }
+    end
+
+    class_methods do
+      # Excludes this job class from auditing.
+      #
+      # @return [void]
+      def skip_provenance
+        self._provenance_skip = true
+      end
+    end
+
+    # @return [Hash, nil] the deserialized "provenance" payload
+    attr_reader :provenance_parent
+
+    # @api private
+    def serialize
+      data = super
+      action = Provenance.current
+      if action && Provenance.enabled?
+        data[KEY] = {"action_id" => action.id, "actor" => action.actor&.to_h}
+      end
+      data
+    end
+
+    # @api private
+    def deserialize(job_data)
+      super
+      @provenance_parent = job_data[KEY]
+    end
+
+    # Runs a job inside a +job+ action.
+    #
+    # @param job [ActiveJob::Base]
+    # @return [Object]
+    def self.perform(job, &block)
+      return Provenance.without(&block) if job.class._provenance_skip
+      return block.call unless Provenance.enabled?
+
+      parent = job.provenance_parent || {}
+      actor = parent["actor"] && Actor.wrap(parent["actor"])
+      Provenance.track(
+        kind: :job, name: job.class.name, actor: actor, caused_by: parent["action_id"],
+        context: Context.new(job: job)
+      ) { block.call }
+    end
+  end
+end