standard_audit 0.11.1 → 0.12.1

data/lib/generators/standard_audit/install/templates/create_audit_logs.rb.erb

@@ -21,6 +21,9 @@ class CreateAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.curr
       # share a parent, so the log is a DAG rather than a strict line; storing
       # the parent is what keeps every row verifiable when it forks.
       t.string :previous_checksum, limit: 64
+      # Set by AuditLog.anonymize_actor! (GDPR erasure). verify_chain counts a
+      # stamped row as `redacted` instead of a digest failure.
+      t.datetime :anonymized_at
       t.timestamps
     end
 

data/lib/standard_audit/configuration.rb

@@ -4,7 +4,8 @@ module StandardAudit
                   :actor_extractor, :target_extractor, :scope_extractor,
                   :current_actor_resolver, :current_request_id_resolver,
                   :current_ip_address_resolver, :current_user_agent_resolver,
-                  :current_session_id_resolver,
+                  :current_session_id_resolver, :current_scope_resolver,
+                  :before_write,
                   :sensitive_keys, :sensitive_key_patterns,
                   :sensitive_key_exceptions, :filter_nested_metadata,
                   :dereference_record_metadata,
@@ -24,8 +25,11 @@ module StandardAudit
       @target_extractor = ->(payload) { payload[:target] }
       @scope_extractor = ->(payload) { payload[:scope] }
 
+      # Tries StandardId's `Current.account` first, then the Rails-generator
+      # convention `Current.user`. Each is respond_to?-guarded, so an app that
+      # defines only one of them (or no `Current` at all) resolves cleanly.
       @current_actor_resolver = -> {
-        defined?(Current) && Current.respond_to?(:user) ? Current.user : nil
+        Configuration.current_attribute(:account) || Configuration.current_attribute(:user)
       }
       @current_request_id_resolver = -> {
         defined?(Current) && Current.respond_to?(:request_id) ? Current.request_id : nil
@@ -36,10 +40,35 @@ module StandardAudit
       @current_user_agent_resolver = -> {
         defined?(Current) && Current.respond_to?(:user_agent) ? Current.user_agent : nil
       }
+      # Tries StandardId's `Current.session&.id` first, then a plain
+      # `Current.session_id` attribute.
       @current_session_id_resolver = -> {
-        defined?(Current) && Current.respond_to?(:session_id) ? Current.session_id : nil
+        session = Configuration.current_attribute(:session)
+        session_id = session.id if session.respond_to?(:id)
+        session_id || Configuration.current_attribute(:session_id)
       }
 
+      # Fallback for the audit scope (tenant) when a write names none —
+      # explicit `scope:` and `scope_extractor` results always win. Applied on
+      # every write path. nil (the default) leaves unscoped writes unscoped.
+      #
+      #   config.current_scope_resolver = -> { Current.organisation }
+      @current_scope_resolver = nil
+
+      # A callable run on EVERY write path (direct `record`, `audit!`,
+      # `record_audit`, both subscribers; sync, async and batched) after the
+      # Current resolvers and `metadata_builder`, and BEFORE redaction. It
+      # receives the mutable entry Hash — :event_type, :actor, :target, :scope,
+      # :metadata, :request_id, :ip_address, :user_agent, :session_id — and may
+      # change it in place; the return value is ignored. Raising aborts the
+      # write (the subscribers rescue and report; direct callers see the error).
+      #
+      #   config.before_write = ->(entry) {
+      #     AuditMetadataPii.verify!(entry[:metadata]) if Rails.env.local?
+      #     entry[:metadata] = entry[:metadata].merge("surface" => Current.surface) if Current.surface
+      #   }
+      @before_write = nil
+
       # Note: :authorization filters the HTTP Authorization header value.
       # If you use "authorization" as a metadata key for policy decisions,
       # rename it (e.g. :authorization_policy) to avoid accidental filtering.
@@ -169,6 +198,14 @@ module StandardAudit
       @retention_days = self.class.retention_days_from_env
     end
 
+    # Reads `::Current.<name>` when a top-level `Current` exists and responds
+    # to it; nil otherwise. The building block of the default resolvers.
+    def self.current_attribute(name)
+      return nil unless defined?(::Current) && ::Current.respond_to?(name)
+
+      ::Current.public_send(name)
+    end
+
     # Parses STANDARD_AUDIT_RETENTION_DAYS into a positive Integer, or nil when
     # unset/blank/zero/negative/non-numeric (=> infinite retention).
     def self.retention_days_from_env
@@ -199,9 +236,9 @@ module StandardAudit
     # supplied by a concern mixed into the model). A callable is passed the
     # instance.
     #
-    # NOTE: batched writes (`StandardAudit.batch { … }` → `insert_all!`) never
-    # instantiate a model, so hooks do not run there. A batched writer that
-    # needs a derived column has to set it on the buffered attrs.
+    # Batched writes (`StandardAudit.batch { … }` → `insert_all!`) run the same
+    # hooks at flush time, against an unsaved instance built from each
+    # buffered row, before that row's checksum is computed (since 0.12.0).
     def before_checksum(hook = nil, &block)
       hook ||= block
       raise ArgumentError, "before_checksum needs a callable, a Symbol, or a block" if hook.nil?

data/lib/standard_audit/event_subscriber.rb

@@ -33,42 +33,28 @@ module StandardAudit
       target = config.target_extractor.call(payload)
       scope  = config.scope_extractor.call(payload)
 
-      metadata = build_metadata(payload, event[:tags], event[:source_location], config)
+      reserved = RESERVED_PAYLOAD_KEYS.map(&:to_s)
 
-      StandardAudit.record(
+      StandardAudit.write_entry(
         name,
         actor: actor,
         target: target,
         scope: scope,
-        metadata: metadata,
-        request_id: context[:request_id] || payload[:request_id],
-        ip_address: context[:ip_address] || payload[:ip_address],
-        user_agent: context[:user_agent] || payload[:user_agent],
-        session_id: context[:session_id] || payload[:session_id]
+        metadata: payload.reject { |k, _| reserved.include?(k.to_s) },
+        reserved: reserved_metadata(event[:tags], event[:source_location]),
+        context: {
+          request_id: context[:request_id] || payload[:request_id],
+          ip_address: context[:ip_address] || payload[:ip_address],
+          user_agent: context[:user_agent] || payload[:user_agent],
+          session_id: context[:session_id] || payload[:session_id]
+        }
       )
     rescue => e
-      Rails.logger.error("[StandardAudit] Error handling Rails.event: #{e.class}: #{e.message}")
-      report_error(e, name)
+      StandardAudit.report_write_error(e, name, subscriber: self.class.name)
     end
 
     private
 
-    # The event handler rescues so a failed audit write cannot break the
-    # instrumented code path, but a log line alone is invisible to error
-    # tracking — so report it as handled too.
-    def report_error(error, event_name)
-      return unless Rails.respond_to?(:error) && Rails.error
-
-      Rails.error.report(
-        error,
-        handled: true,
-        context: { StandardAudit.config.audit_error_context_key => event_name,
-                   subscriber: self.class.name }
-      )
-    rescue => report_failure
-      Rails.logger.error("[StandardAudit] Error reporting audit failure: #{report_failure.class}: #{report_failure.message}")
-    end
-
     def matches_subscription?(name)
       StandardAudit.config.subscriptions.any? { |pattern| pattern_match?(pattern, name) }
     end
@@ -99,20 +85,18 @@ module StandardAudit
     end
 
     # `_tags` and `_source` are reserved metadata keys owned by this
-    # subscriber. Sensitive-key filtering is handled downstream by
-    # `StandardAudit.record`, so we don't re-run it here.
-    def build_metadata(payload, tags, source_location, config)
-      reserved = RESERVED_PAYLOAD_KEYS.map(&:to_s)
-      raw = payload.reject { |k, _| reserved.include?(k.to_s) }
-      raw = config.metadata_builder.call(raw) if config.metadata_builder
+    # subscriber. They are merged in AFTER `metadata_builder` runs (see
+    # StandardAudit.write_entry), so a builder never sees or strips them.
+    def reserved_metadata(tags, source_location)
+      reserved = {}
 
       if tags.is_a?(Hash) && tags.any?
-        raw[:_tags] = tags
+        reserved[:_tags] = tags
       elsif tags && !tags.is_a?(Hash)
         Rails.logger.warn("[StandardAudit] Dropping Rails.event tags of unexpected type: #{tags.class}")
       end
-      raw[:_source] = source_location if source_location
-      raw
+      reserved[:_source] = source_location if source_location
+      reserved
     end
   end
 end

data/lib/standard_audit/rspec/baseline.rb

@@ -0,0 +1,81 @@
+require "standard_audit"
+
+# Shared example guarding the `configure(baseline: true)` contract: that the
+# app's StandardAudit configuration survives `StandardAudit.reset_configuration!`
+# (which `require "standard_audit/rspec"` runs before every example).
+#
+#   require "standard_audit/rspec/baseline"   # or "standard_audit/rspec"
+#
+#   RSpec.describe "StandardAudit configuration baseline" do
+#     it_behaves_like "a standard_audit baseline",
+#       subscriptions: [/\Astandard_id\./, /\Aauthorization\./],
+#       settings: {
+#         retention_days: 1826,
+#         raise_on_audit_write_error: true,
+#         filter_nested_metadata: true,
+#         queue_name: :maintenance
+#       },
+#       catalogue: -> { AuditCatalogue::ACTIONS },
+#       sensitive_keys: %i[source_payload],
+#       sensitive_key_patterns: [/secret/i],
+#       present: %i[metadata_builder before_write current_scope_resolver]
+#   end
+#
+# Every option is optional. Behaviour held in lambdas (resolvers, builders)
+# can't be compared by value, so list them under `present:` to assert they
+# survive a reset, and keep an app-specific example for what they return.
+RSpec.shared_examples "a standard_audit baseline" do |options = {}|
+  subscriptions          = Array(options[:subscriptions])
+  settings               = options.fetch(:settings, {})
+  catalogue              = options[:catalogue]
+  sensitive_keys         = Array(options[:sensitive_keys])
+  sensitive_key_patterns = Array(options[:sensitive_key_patterns])
+  present                = Array(options[:present])
+
+  def standard_audit_baseline_assertions(subscriptions:, settings:, catalogue:, sensitive_keys:,
+    sensitive_key_patterns:, present:)
+    config = StandardAudit.config
+
+    expect(config.subscriptions).to include(*subscriptions) if subscriptions.any?
+    settings.each do |name, value|
+      expect(config.public_send(name)).to eq(value), "expected config.#{name} to be #{value.inspect} after a reset"
+    end
+    if catalogue
+      resolved = config.audit_catalogue.respond_to?(:call) ? config.audit_catalogue.call : config.audit_catalogue
+      expect(Array(resolved).map(&:to_s)).to match_array(Array(catalogue.call).map(&:to_s))
+    end
+    expect(config.sensitive_keys).to include(*sensitive_keys) if sensitive_keys.any?
+    expect(config.sensitive_key_patterns).to include(*sensitive_key_patterns) if sensitive_key_patterns.any?
+    present.each do |name|
+      expect(config.public_send(name)).not_to be_nil, "expected config.#{name} to survive a reset"
+    end
+  end
+
+  let(:standard_audit_baseline_options) do
+    { subscriptions: subscriptions, settings: settings, catalogue: catalogue,
+      sensitive_keys: sensitive_keys, sensitive_key_patterns: sensitive_key_patterns, present: present }
+  end
+
+  it "is registered with configure(baseline: true)" do
+    expect(StandardAudit.baseline_configured?).to be(true),
+      "config/initializers/standard_audit.rb must call StandardAudit.configure(baseline: true), " \
+      "or reset_configuration! silently reverts every example to gem defaults"
+  end
+
+  it "carries the app's configuration" do
+    standard_audit_baseline_assertions(**standard_audit_baseline_options)
+  end
+
+  it "restores it after a mutation and a reset" do
+    StandardAudit.config.sensitive_keys += %i[standard_audit_isolation_canary]
+    StandardAudit.config.subscribe_to "standard_audit.isolation_canary"
+    settings.each_key { |name| StandardAudit.config.public_send(:"#{name}=", nil) }
+    present.each { |name| StandardAudit.config.public_send(:"#{name}=", nil) }
+
+    StandardAudit.reset_configuration!
+
+    expect(StandardAudit.config.sensitive_keys).not_to include(:standard_audit_isolation_canary)
+    expect(StandardAudit.config.subscriptions).not_to include("standard_audit.isolation_canary")
+    standard_audit_baseline_assertions(**standard_audit_baseline_options)
+  end
+end

data/lib/standard_audit/rspec/matchers.rb

@@ -0,0 +1,187 @@
+require "standard_audit"
+
+# Block matcher asserting that a block wrote an audit row.
+#
+#   require "standard_audit/rspec/matchers"   # or "standard_audit/rspec"
+#
+#   expect { operation.call }
+#     .to have_audited("order.created")
+#     .by(account)                  # actor: a record, an RSpec matcher, or no arg for "any actor"
+#     .on(order)                    # target: same forms
+#     .within(organisation)         # scope: same forms
+#     .with_metadata(total: 100)    # subset match; values may be RSpec matchers
+#     .once                         # or .times(n); default is "at least one"
+#
+#   expect { noop }.not_to have_audited("order.created")
+#
+# Only rows written DURING the block are considered, and only persisted ones:
+# under `config.async = true` run jobs inline (or use `perform_enqueued_jobs`),
+# and a `StandardAudit.batch` must be flushed inside the block.
+#
+# `.by` / `.on` / `.within` with no argument assert presence — a well-formed
+# row with a resolvable GlobalID — which is what per-app helpers such as
+# `expect_well_formed_audit` checked by hand.
+module StandardAudit
+  module RSpec
+    module Matchers
+      class HaveAudited
+        include ::RSpec::Matchers::Composable
+
+        ANY = Object.new.freeze
+        private_constant :ANY
+
+        def initialize(event_type)
+          @event_type = event_type.to_s
+          @references = {}
+          @metadata = nil
+          @count = nil
+        end
+
+        def by(actor = ANY)
+          @references[:actor] = actor
+          self
+        end
+
+        def on(target = ANY)
+          @references[:target] = target
+          self
+        end
+
+        def within(scope = ANY)
+          @references[:scope] = scope
+          self
+        end
+        alias_method :scoped_to, :within
+
+        def with_metadata(expected)
+          @metadata = expected.to_h.deep_stringify_keys
+          self
+        end
+
+        def once
+          times(1)
+        end
+
+        def times(count)
+          @count = count
+          self
+        end
+        alias_method :exactly, :times
+
+        def supports_block_expectations?
+          true
+        end
+
+        def supports_value_expectations?
+          false
+        end
+
+        def matches?(block)
+          capture(block)
+          @count ? matching.size == @count : matching.any?
+        end
+
+        def does_not_match?(block)
+          raise ArgumentError, "have_audited(...).times/once is not supported with not_to" if @count
+
+          capture(block)
+          matching.empty?
+        end
+
+        def description
+          parts = ["have audited #{@event_type.inspect}"]
+          @references.each { |role, value| parts << "#{preposition(role)} #{describe_value(value)}" }
+          parts << "with metadata including #{@metadata.inspect}" if @metadata
+          parts << (@count == 1 ? "once" : "#{@count} times") if @count
+          parts.join(" ")
+        end
+
+        def failure_message
+          "expected block to #{description}, but #{found_summary}"
+        end
+
+        def failure_message_when_negated
+          "expected block not to #{description}, but it wrote:\n#{format_rows(matching)}"
+        end
+
+        private
+
+        def capture(block)
+          before_ids = StandardAudit::AuditLog.pluck(:id)
+          block.call
+          @written = StandardAudit::AuditLog.where.not(id: before_ids).order(:created_at, :id).to_a
+          @candidates = @written.select { |log| log.event_type == @event_type }
+        end
+
+        def matching
+          @matching ||= @candidates.select { |log| row_matches?(log) }
+        end
+
+        def row_matches?(log)
+          @references.all? { |role, expected| reference_matches?(log, role, expected) } &&
+            metadata_matches?(log.metadata || {})
+        end
+
+        def metadata_matches?(actual)
+          return true if @metadata.nil?
+
+          @metadata.all? { |key, value| actual.key?(key) && values_match?(value, actual[key]) }
+        end
+
+        def reference_matches?(log, role, expected)
+          gid = log.public_send(:"#{role}_gid")
+
+          if expected.equal?(ANY)
+            gid.present? && GlobalID.parse(gid)&.model_id.present?
+          elsif expected.respond_to?(:to_global_id) && !matcher?(expected)
+            gid == expected.to_global_id.to_s
+          else
+            values_match?(expected, log.public_send(role))
+          end
+        end
+
+        def matcher?(object)
+          ::RSpec::Matchers.is_a_matcher?(object)
+        end
+
+        def preposition(role)
+          { actor: "by", target: "on", scope: "within" }.fetch(role)
+        end
+
+        def describe_value(value)
+          return "any record" if value.equal?(ANY)
+          return value.description if matcher?(value) && value.respond_to?(:description)
+          return value.to_global_id.to_s if value.respond_to?(:to_global_id)
+
+          value.inspect
+        end
+
+        def found_summary
+          if @candidates.empty?
+            others = @written.map(&:event_type).uniq
+            others.empty? ? "no audit rows were written" : "it wrote only: #{others.join(", ")}"
+          elsif @count
+            "#{matching.size} matching row(s) were written:\n#{format_rows(@candidates)}"
+          else
+            "no #{@event_type.inspect} row matched. Rows written:\n#{format_rows(@candidates)}"
+          end
+        end
+
+        def format_rows(rows)
+          rows.map { |log|
+            "  #{log.event_type} actor=#{log.actor_gid.inspect} target=#{log.target_gid.inspect} " \
+              "scope=#{log.scope_gid.inspect} metadata=#{log.metadata.inspect}"
+          }.join("\n")
+        end
+      end
+
+      def have_audited(event_type)
+        HaveAudited.new(event_type)
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include StandardAudit::RSpec::Matchers
+end

data/lib/standard_audit/rspec.rb

@@ -1,5 +1,12 @@
 require "standard_audit"
+require "standard_audit/rspec/matchers"
+require "standard_audit/rspec/baseline"
 
+# StandardAudit test support. Loads the `have_audited` matcher
+# (standard_audit/rspec/matchers) and the "a standard_audit baseline" shared
+# example (standard_audit/rspec/baseline), and resets StandardAudit state
+# between examples.
+#
 # StandardAudit state reset between examples.
 #
 # - Clears the thread-local batch buffer so a spec that exits inside a

data/lib/standard_audit/subscriber.rb

@@ -27,90 +27,32 @@ module StandardAudit
 
     # The event handler rescues so a failed audit write cannot break the
     # instrumented code path, but a log line alone is invisible to error
-    # tracking — so report it as handled too.
-    def report_error(error, event_name)
-      return unless Rails.respond_to?(:error) && Rails.error
-
-      Rails.error.report(
-        error,
-        handled: true,
-        context: { StandardAudit.config.audit_error_context_key => event_name,
-                   subscriber: self.class.name }
-      )
-    rescue => report_failure
-      Rails.logger.error("[StandardAudit] Error reporting audit failure: #{report_failure.class}: #{report_failure.message}")
-    end
-
+    # tracking — so it is reported as handled too.
+    #
+    # The write itself goes through StandardAudit.write_entry, the same path
+    # `StandardAudit.record` uses, so batching, `current_scope_resolver`,
+    # `metadata_builder` and `before_write` behave identically here. Until
+    # 0.12.0 this method carried its own copy of the write logic, which ignored
+    # `StandardAudit.batch`.
     def handle_event(event)
-      return unless StandardAudit.config.enabled
-
       config = StandardAudit.config
-      payload = event.payload
-
-      actor = config.actor_extractor.call(payload)
-      target = config.target_extractor.call(payload)
-      scope = config.scope_extractor.call(payload)
-
-      # Fall back to Current attributes when payload values are nil
-      actor ||= config.current_actor_resolver.call
-
-      metadata = extract_metadata(payload, config)
+      return unless config.enabled
 
-      attrs = {
-        event_type: event.name,
-        occurred_at: Time.current,
-        request_id: payload[:request_id] || config.current_request_id_resolver.call,
-        ip_address: payload[:ip_address] || config.current_ip_address_resolver.call,
-        user_agent: payload[:user_agent] || config.current_user_agent_resolver.call,
-        session_id: payload[:session_id] || config.current_session_id_resolver.call,
-        metadata: metadata
-      }
+      payload = event.payload
 
-      if config.async
-        job_attrs = attrs.dup
-        job_attrs[:actor_gid] = actor&.to_global_id&.to_s
-        job_attrs[:target_gid] = target&.to_global_id&.to_s
-        job_attrs[:scope_gid] = scope&.to_global_id&.to_s
-        job_attrs[:actor_type] = actor&.class&.name
-        job_attrs[:target_type] = target&.class&.name
-        job_attrs[:scope_type] = scope&.class&.name
-        StandardAudit::CreateAuditLogJob.perform_later(job_attrs.stringify_keys)
-      else
-        log = StandardAudit::AuditLog.new(attrs)
-        log.actor = actor
-        log.target = target
-        log.scope = scope
-        log.save!
-      end
+      StandardAudit.write_entry(
+        event.name,
+        actor: config.actor_extractor.call(payload),
+        target: config.target_extractor.call(payload),
+        scope: config.scope_extractor.call(payload),
+        metadata: payload.except(*EXCLUDED_PAYLOAD_KEYS),
+        context: payload.slice(:request_id, :ip_address, :user_agent, :session_id)
+      )
     rescue => e
-      Rails.logger.error("[StandardAudit] Error creating audit log: #{e.class}: #{e.message}")
-      report_error(e, event.name)
+      StandardAudit.report_write_error(e, event.name, subscriber: self.class.name)
     end
 
-    def extract_metadata(payload, config)
-      # Remove known non-metadata keys
-      excluded_keys = %i[actor target scope request_id ip_address user_agent session_id]
-      raw_metadata = payload.except(*excluded_keys)
-
-      if config.metadata_builder
-        raw_metadata = config.metadata_builder.call(raw_metadata)
-      end
-
-      # ActiveRecord objects in the payload are replaced by a reference BEFORE
-      # any key-based redaction, because the leak they cause is not a
-      # sensitive *key* — it is a value that serialises as an entire database
-      # row (rarebit-one/rarebit-ops#296). Runs after `metadata_builder` so a
-      # host that derives fields from a record (`payload[:account].email`)
-      # still sees the record.
-      if config.dereference_record_metadata
-        raw_metadata = StandardAudit::RecordReference.call(raw_metadata)
-      end
-
-      # Redaction lives in MetadataFilter, shared with StandardAudit.record.
-      # This path previously carried its own copy that did *not* subtract
-      # RESERVED_METADATA_KEYS, so `_tags`/`_source` were strippable here and
-      # not there.
-      StandardAudit::MetadataFilter.call(raw_metadata, config: config)
-    end
+    EXCLUDED_PAYLOAD_KEYS = %i[actor target scope request_id ip_address user_agent session_id].freeze
+    private_constant :EXCLUDED_PAYLOAD_KEYS
   end
 end

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.11.1"
+  VERSION = "0.12.1"
 end