standard_audit 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84f59bffd4df4a9174ba0a88645a4c7d5818eddf862b5badfb55c3880fb5849d
-  data.tar.gz: 7747fdff93658f34f3ba3a9bfa70ca40fdc581125d182c996319a161f5c30809
+  metadata.gz: 1ab5fcec99d13f0796742d817c1dd42e45c0e8518f8967033a67194c3179ae6e
+  data.tar.gz: b0f6272a600a665615cc533b439ad2b654d54c025bd7bc2b378b5c2eac7e850d
 SHA512:
-  metadata.gz: 03f2f84e0418106b8899b9aaff009e95fdbb116f9eb98c37308d2b4ae41df3cfbfe9d9b1615bdd4beb4391d983989cb658e4195451cb56214a75e4cf46ba4375
-  data.tar.gz: 6b2e84e5bcd6e6e933535a6ae9e654deb3502e69b575d613044c7b02de843e2a8886c43a0c82bd8cb6313ff012510d36a52f290ca36dd778634c4b3c70cefb80
+  metadata.gz: 1ab1f514a13f1b03501cfdf18b3c2afcf8ff214a36992edb3e00f052384826c56bf09a35c4d7c4b8f92a4f28513cd8fe5534d946622112bb27bb6f8bfd8826c7
+  data.tar.gz: 7f9fc2acdb292b06f72b2323ac0c5c780348da8d1b91e9850ae73a61eba2361fb21b3aa431888de9d0003dc2934c0ba1b2a9a060bd4bd3b2a6a1bfb71eea5680

data/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-07-30
+
+### Added
+
+- **Batch actor/target/scope preloading.** `AuditLog#actor` / `#target` / `#scope` resolved their GlobalID one row at a time, so every audit list N+1'd. Two consuming apps had already fixed this locally, both by reaching into private ivars (`instance_variable_set(:@preloaded_actor, …)`) because the gem exposed no setter. The gem now owns it:
+  - `AuditLog.preload_references(logs, refs: %i[actor target], only: [...], includes: {...})` resolves a page in one query per distinct stored `*_type`, built on `GlobalID::Locator.locate_many` with `ignore_missing: true`.
+  - `preloaded_actor=` / `preloaded_target=` / `preloaded_scope=` public writers, plus `actor_preloaded?` predicates.
+  - The memo is a Hash consulted with `key?`, so *preloaded-but-deleted* memoizes `nil` and reads back without a query — distinct from *not preloaded*. `actor=` / `target=` / `scope=` populate the memo (they already hold the record); `reload` clears it.
+  - `only:` is matched against the **stored type string by class name**. `GlobalID::Locator`'s own `:only` is evaluated as `gid.model_class <= klass`, which constantizes the historical type string *before* deciding whether it was permitted — so a renamed or deleted class raises `NameError` rather than being denied. Consequence: `only:` does not expand to subclasses or modules; list every concrete class. A non-whitelisted reference memoizes `nil`.
+  - `includes:` is treated as a per-type map when every key is a String or Class (`{ "Order" => [:user] }`), and as a uniform Active Record includes spec otherwise (so `{ account: :identifiers }` still works as you'd expect).
+  - A type string that no longer constantizes — or a blank `*_type` on a row that still carries a `*_gid` — is left *unmemoized*, so the per-row reader behaves exactly as it did before preloading was attempted. Preloading can never turn a resolvable reference into a permanent `nil`.
+- `AuditLog#actor_model_id` / `#target_model_id` / `#scope_model_id` (and `AuditLog.reference_model_id(gid)`) — the model id extracted straight from the gid string, a helper three separate consumer call sites had hand-rolled. Deliberately **not** `GlobalID.parse(gid)&.model_id`: audit rows are historical and append-only, so a gid whose app segment differs from the current `GlobalID.app` is a real row that must still yield its id. Mirrors `URI::GID`'s own decoding (drops `?params`, `CGI.unescape`s each segment, returns an Array for a composite primary key) while ignoring the app name, so it agrees with `GlobalID#model_id` wherever that works and keeps working where it doesn't.
+
+
+- **`config.before_checksum`** — registers a hook that runs on `before_create` **between `assign_uuid` and `compute_checksum`**. Definition order is execution order, so a hook may set a `CHECKSUM_FIELDS` member (back-fill `scope`, derive a column, rewrite `metadata`) and the row still passes `AuditLog.verify_chain`. Hosts previously had to register their own `before_create ..., prepend: true` to beat the gem's checksum callback — fragile ordering knowledge no host should need.
+  ```ruby
+  config.before_checksum { |log| log.scope = MyApp.derive_scope(log) }
+  config.before_checksum :backfill_scope   # an AuditLog instance method
+  ```
+  Hooks accumulate and run in registration order. **Each is rescued individually** — a failing hook logs (and reports to `Rails.error`), is **rolled back to the attributes it started from**, and is skipped; the remaining hooks still run and the audit write never fails. The rollback is what makes "skipped" true: without it, a hook that assigns `scope_gid` and then fails a later lookup would leave a half-applied row for the following callbacks to checksum and persist. If a row is created with an explicit `checksum`, hooks still run (most derived columns are not checksummed) but the supplied digest is dropped and re-derived when a hook changed a `CHECKSUM_FIELDS` member. Hooks do not run on the batched `insert_all!` path, which never instantiates a model.
+- **`StandardAudit.configure(baseline: true)`** — remembers the block so `reset_configuration!` replays it onto the fresh Configuration. **Required companion to the `before_checksum` hooks, not optional.** The config object holds *behaviour*, not just data, so a suite that installs `standard_audit/rspec` (whose per-example `reset_configuration!` restores gem defaults) would silently lose its write-time hooks after the first example — and the specs that would have caught it pass vacuously. The install template now uses `configure(baseline: true)`, and the `lib/standard_audit/rspec.rb` docstring no longer instructs hosts to re-apply configuration by hand. `reset_configuration!(replay_baseline: false)`, `clear_baseline_configuration!` and `baseline_configured?` round it out. A plain `configure` is unchanged and registers nothing.
+
+
+- **`config.sensitive_key_patterns`** (Array of Regexp, always applied, default `[]`) — the supported way to catch a family of keys. Stripe's `client_secret` slipping past the exact-match `:secret` is solved by `/secret/i`.
+
+  **There is deliberately no substring matching mode**, and one should not be added. Against the current default key list, substring matching strips real audit content across the estate: `input_tokens` / `output_tokens` (live LLM cost accounting in luminality and sidekick), `token_digest` (rendered in luminality's staff audit UI), `password_reset_sent_at`, `authorization_endpoint`, even `onepassword`. Audit rows are append-only, so it cannot be undone — the content is simply never written from then on. Patterns are opt-in, per-app, and checkable in advance.
+- **`config.sensitive_key_exceptions`** (Array of exact names or Regexps, default `[]`) — never redacted, even when `sensitive_keys` or a pattern matches. Lets an app adopt `[/token/i]` while keeping `input_tokens` / `output_tokens`.
+- **`rake standard_audit:sensitive_keys:dry_run`** — read-only. Reports, per metadata key, what a candidate rule *would* have stripped from the rows you already have, what it would keep, and any nested matches that survive because `filter_nested_metadata` is off. Turns "is this rule safe for my app?" into a command rather than a guess, which matters precisely because the rows are append-only.
+  ```bash
+  bin/rails standard_audit:sensitive_keys:dry_run                 # current config
+  bin/rails "standard_audit:sensitive_keys:dry_run[secret]"       # candidate pattern
+  NESTED=1 bin/rails "standard_audit:sensitive_keys:dry_run[secret|token]"
+  ```
+  Backed by `StandardAudit::SensitiveKeysDryRun.call(...)`, which extracts keys **in Ruby** rather than with `jsonb_object_keys` so it stays backend-neutral.
+- `StandardAudit::MetadataFilter` — `MetadataFilter.call(metadata, config:)` filters metadata; `MetadataFilter.new.filter?(key)` answers the same question for a single key without writing a row. Matching stays **exact on the key name** (string/symbol insensitive), unchanged from 0.6.0. Anything hash-like is filtered (so `ActionController::Parameters` is redacted, not waved through because it isn't a `Hash`); `nil` passes; anything else raises `MetadataFilter::UnfilterableMetadataError` rather than writing unfiltered content to an append-only row.
+
+### Fixed
+
+- **Nested metadata was never redacted on either write path.** `metadata: { stripe: { client_secret: … } }` was written intact even under exact matching — a larger real leak than the top-level case. Opt in with `config.filter_nested_metadata = true` (default `false`, so 0.6.0 behaviour is preserved); redaction then descends into nested Hashes and Hashes inside Arrays. `RESERVED_METADATA_KEYS` (`_tags`, `_source`) are preserved *and their subtree is never descended into, at every depth* — they are gem-owned, and `event_subscriber.rb` sets them after building metadata.
+- **The two write paths applied different sensitive-key filters.** `StandardAudit.record` and `StandardAudit::Subscriber#extract_metadata` each carried an independent copy of the redaction logic, and they had already diverged: the subscriber copy did not subtract `RESERVED_METADATA_KEYS`, so an app that added `:_tags` or `:_source` to `sensitive_keys` had the reserved key preserved on the `record` path and stripped on the `ActiveSupport::Notifications` path. Both now call the single `StandardAudit::MetadataFilter`, and the divergence is resolved in favour of `record`'s behaviour — reserved keys can never be filtered on either path. Parity is driven from one shared example (`spec/support/shared_examples/metadata_filtering.rb`), so a future divergence fails the suite rather than shipping.
+
+### Notes
+
+- `StandardAudit.batch { ... }` flushes via `insert_all!` and never instantiates a model, so none of the above runs on the batched write path — the memo is a no-op there by construction.
+- Minor behaviour change on a single instance: `log.actor = user; user.destroy!; log.actor` now returns the (destroyed) in-memory record instead of `nil`, because the writer memoizes. Reading the row fresh (or calling `reload`) is unchanged and still returns `nil`. This matches how Active Record association writers behave.
+
 ## [0.6.0] - 2026-06-24
 
 ### Added

data/README.md

@@ -164,8 +164,13 @@ organisation.scoped_audit_logs  # all logs scoped to this organisation
 
 ## Configuration Reference
 
+Use `configure(baseline: true)` in your initializer. It remembers the block so
+`StandardAudit.reset_configuration!` replays it — required if your suite loads
+`standard_audit/rspec`, because the config object holds behaviour (`before_checksum`
+hooks) as well as data, and a per-example reset would otherwise drop it.
+
 ```ruby
-StandardAudit.configure do |config|
+StandardAudit.configure(baseline: true) do |config|
   # -- Subscriptions --
   # Subscribe to ActiveSupport::Notifications patterns.
   # Supports wildcards.
@@ -189,9 +194,30 @@ StandardAudit.configure do |config|
   config.current_session_id_resolver = -> { Current.session_id }
 
   # -- Sensitive Data --
-  # Keys automatically stripped from metadata.
+  # Keys automatically stripped from metadata. Matching is EXACT on the key
+  # name; there is deliberately no substring mode (see below).
   config.sensitive_keys += %i[my_custom_secret]  # added to built-in defaults
 
+  # Regexps matched against every key name, in addition to the exact list.
+  # Solves e.g. Stripe's `client_secret`, which does not equal `:secret`.
+  config.sensitive_key_patterns = [/secret/i]
+
+  # Keys (exact names or Regexps) that are never redacted, so a broad pattern
+  # can keep the real audit keys it would otherwise swallow.
+  config.sensitive_key_exceptions = %i[input_tokens output_tokens]
+
+  # Descend into nested Hashes when redacting. OFF by default — without it,
+  # `metadata: { stripe: { client_secret: ... } }` is written intact.
+  config.filter_nested_metadata = true
+
+  # -- Write-time hooks --
+  # Run between the UUID assignment and the checksum computation, so a hook MAY
+  # set a checksummed column and the row still passes `verify_chain`. No
+  # `prepend: true` needed. Each hook is rescued individually and can never fail
+  # the audit write. Not run on the batched `insert_all!` path.
+  config.before_checksum { |log| log.scope = MyApp.derive_scope(log) }
+  config.before_checksum :backfill_scope   # an AuditLog instance method
+
   # -- Metadata Builder --
   # Optional proc to transform metadata before storage.
   config.metadata_builder = ->(metadata) { metadata.slice(:relevant_key) }
@@ -423,8 +449,30 @@ t.jsonb :metadata, default: {}
 
 ```ruby
 config.sensitive_keys += %i[medical_record_number]  # extend the built-in defaults
+config.sensitive_key_patterns = [/secret/i]         # catch a whole family
+config.sensitive_key_exceptions = %i[input_tokens]  # ...minus the real ones
+config.filter_nested_metadata = true                # redact nested Hashes too
 ```
 
+`sensitive_keys` matches **exactly** on the key name. There is deliberately no
+substring mode: against the default list it would strip real audit content —
+`input_tokens` / `output_tokens`, `token_digest`, `password_reset_sent_at`,
+`authorization_endpoint`, `onepassword`. Audit rows are append-only, so that
+cannot be undone. Use `sensitive_key_patterns` and check any rule against your
+own data first:
+
+```bash
+bin/rails "standard_audit:sensitive_keys:dry_run[secret]"   # NESTED=1 to model nesting
+```
+
+The dry run writes nothing. It reports per key what would be stripped, what
+would be kept, and nested matches that survive because
+`filter_nested_metadata` is off.
+
+Nested metadata is **not** redacted unless `filter_nested_metadata` is enabled
+— `metadata: { stripe: { client_secret: ... } }` passes both write paths under
+exact matching by default.
+
 **Performance**: For high-volume applications, enable async processing and ensure your `audit_logs` table has appropriate indexes (the install generator adds them by default). Consider partitioning by `occurred_at` for very large tables.
 
 **Retention**: Set `retention_days` in your configuration and run `rake standard_audit:cleanup` via a scheduled job (e.g., cron or SolidQueue recurring). Archive before deleting if you need long-term storage.

data/app/models/standard_audit/audit_log.rb

@@ -2,6 +2,8 @@ require "openssl"
 
 module StandardAudit
   class AuditLog < ApplicationRecord
+    include StandardAudit::ReferencePreloading
+
     self.table_name = "audit_logs"
 
     CHECKSUM_FIELDS = %w[
@@ -10,7 +12,15 @@ module StandardAudit
       user_agent session_id occurred_at
     ].freeze
 
+    # Callback ORDER IS THE CONTRACT here. Definition order is execution
+    # order, so registering the host hook list between assign_uuid and
+    # compute_checksum means a hook can set a CHECKSUM_FIELDS member (e.g.
+    # back-fill `scope`) and the row still verifies. Hosts previously had to
+    # register `before_create ..., prepend: true` themselves to beat
+    # compute_checksum — fragile ordering knowledge no host should need.
+    # Do not reorder these three lines.
     before_create :assign_uuid, if: -> { id.blank? }
+    before_create :run_before_checksum_hooks
     before_create :compute_checksum, if: -> { checksum.blank? }
     after_create_commit :emit_created_event
 
@@ -24,61 +34,35 @@ module StandardAudit
     validates :event_type, presence: true
     validates :occurred_at, presence: true
 
-    # -- Actor assignment via GlobalID --
+    # -- actor / target / scope assignment via GlobalID --
+    #
+    # Reads consult the preload memo first (see ReferencePreloading), then fall
+    # back to a single `GlobalID::Locator.locate`. Writers populate the memo,
+    # since they already hold the record. If the underlying record was deleted
+    # the reader returns nil while the gid and type stay on the row.
 
     def actor=(record)
-      if record.nil?
-        self.actor_gid = nil
-        self.actor_type = nil
-      else
-        self.actor_gid = record.to_global_id.to_s
-        self.actor_type = record.class.name
-      end
+      assign_reference(:actor, record)
     end
 
     def actor
-      return nil if actor_gid.blank?
-      GlobalID::Locator.locate(actor_gid)
-    rescue ActiveRecord::RecordNotFound
-      nil
+      read_reference(:actor)
     end
 
-    # -- Target assignment via GlobalID --
-
     def target=(record)
-      if record.nil?
-        self.target_gid = nil
-        self.target_type = nil
-      else
-        self.target_gid = record.to_global_id.to_s
-        self.target_type = record.class.name
-      end
+      assign_reference(:target, record)
     end
 
     def target
-      return nil if target_gid.blank?
-      GlobalID::Locator.locate(target_gid)
-    rescue ActiveRecord::RecordNotFound
-      nil
+      read_reference(:target)
     end
 
-    # -- Scope assignment via GlobalID --
-
     def scope=(record)
-      if record.nil?
-        self.scope_gid = nil
-        self.scope_type = nil
-      else
-        self.scope_gid = record.to_global_id.to_s
-        self.scope_type = record.class.name
-      end
+      assign_reference(:scope, record)
     end
 
     def scope
-      return nil if scope_gid.blank?
-      GlobalID::Locator.locate(scope_gid)
-    rescue ActiveRecord::RecordNotFound
-      nil
+      read_reference(:scope)
     end
 
     # -- Query scopes --
@@ -280,5 +264,60 @@ module StandardAudit
     def assign_uuid
       self.id = SecureRandom.uuid_v7
     end
+
+    # Runs config.before_checksum_hooks in registration order. Each hook is
+    # rescued individually: an audit write must never fail because a host's
+    # derived-column logic did. A hook that raises is rolled back to the
+    # attributes it started from and skipped; the remaining hooks still run.
+    def run_before_checksum_hooks
+      hooks = StandardAudit.config.before_checksum_hooks
+      return if hooks.blank?
+
+      # Only relevant when a checksum was supplied explicitly (the normal path
+      # has none yet, and compute_checksum runs next).
+      checksummed_before = checksum.present? ? attributes.slice(*CHECKSUM_FIELDS) : nil
+
+      hooks.each { |hook| run_before_checksum_hook(hook) }
+
+      # A caller-supplied checksum stops describing the row the moment a hook
+      # changes a checksummed field. Dropping it lets compute_checksum
+      # re-derive one, rather than persisting a row that fails verify_chain
+      # immediately. Hooks still run for such rows, because most derived
+      # columns (actor_role and friends) are not checksummed at all.
+      self.checksum = nil if checksummed_before && attributes.slice(*CHECKSUM_FIELDS) != checksummed_before
+    end
+
+    def run_before_checksum_hook(hook)
+      snapshot = attributes.deep_dup
+
+      begin
+        case hook
+        when Symbol, String then send(hook)
+        else hook.call(self)
+        end
+      rescue StandardError => e
+        # Roll the record back to where the hook found it. Without this a hook
+        # that assigns scope_gid and then fails a later lookup leaves a
+        # half-applied row that the following callbacks happily checksum and
+        # persist — so the hook would not actually be "skipped".
+        restore_attributes_from(snapshot)
+        Rails.logger.warn("[StandardAudit] before_checksum hook failed: #{e.class}: #{e.message}")
+        Rails.error.report(e, handled: true, context: { audit_event: event_type }) if Rails.respond_to?(:error)
+        nil
+      end
+    end
+
+    def restore_attributes_from(snapshot)
+      snapshot.each do |name, value|
+        write_attribute(name, value) unless read_attribute(name) == value
+      end
+
+      # The reference memo may hold a record the hook assigned; drop it so the
+      # restored gid columns are the source of truth again.
+      @preloaded_references = nil
+    rescue StandardError => e
+      Rails.logger.warn("[StandardAudit] could not roll back a failed before_checksum hook: #{e.class}: #{e.message}")
+      nil
+    end
   end
 end

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

@@ -1,4 +1,8 @@
-StandardAudit.configure do |config|
+# `baseline: true` remembers this block so `StandardAudit.reset_configuration!`
+# replays it. Required if you `require "standard_audit/rspec"` in your suite:
+# without it, every example resets to gem defaults and loses the configuration
+# below — including any `before_checksum` hooks, which are behaviour, not data.
+StandardAudit.configure(baseline: true) do |config|
   # Subscribe to ActiveSupport::Notifications / Rails.event patterns.
   # Each gem documents its own event namespace; subscribe to whichever
   # patterns you want audited:
@@ -27,10 +31,35 @@ StandardAudit.configure do |config|
   # config.current_user_agent_resolver = -> { Current.user_agent }
   # config.current_session_id_resolver = -> { Current.session_id }
 
-  # Keys to strip from metadata (defaults include: password, password_confirmation,
-  # token, secret, api_key, access_token, refresh_token, private_key,
-  # certificate_chain, ssn, credit_card, authorization)
+  # -- Metadata redaction ----------------------------------------------------
+  #
+  # Keys to strip from metadata. Matching is EXACT on the key name (defaults
+  # include: password, password_confirmation, token, secret, api_key,
+  # access_token, refresh_token, private_key, certificate_chain, ssn,
+  # credit_card, authorization).
   # config.sensitive_keys += %i[my_custom_secret]
+  #
+  # Regexps matched against every key name, in addition to the exact list.
+  # This is the supported way to catch a family of keys — e.g. Stripe's
+  # `client_secret`, which does not equal the default `:secret`:
+  # config.sensitive_key_patterns = [/secret/i]
+  #
+  # There is deliberately no "substring" matching mode. Against the default
+  # key list it would strip real audit content: input_tokens/output_tokens,
+  # token_digest, password_reset_sent_at, authorization_endpoint, onepassword.
+  # Audit rows are append-only, so that cannot be undone. Check any rule
+  # against your own data first:
+  #
+  #   bin/rails "standard_audit:sensitive_keys:dry_run[secret]"
+  #
+  # Keys (exact names or Regexps) that are never redacted, so a broad pattern
+  # can keep the handful of real audit keys it would otherwise swallow:
+  # config.sensitive_key_exceptions = %i[input_tokens output_tokens]
+  #
+  # Descend into nested Hashes when redacting. Off by default because it
+  # changes what gets written; `metadata: { stripe: { client_secret: ... } }`
+  # is NOT redacted unless you turn this on. Run the dry run first.
+  # config.filter_nested_metadata = true
 
   # Run audit log creation in background job
   # config.async = false
@@ -44,4 +73,17 @@ StandardAudit.configure do |config|
 
   # Data retention (schedule StandardAudit::CleanupJob to enforce)
   # config.retention_days = nil
+
+  # -- Write-time hooks -------------------------------------------------------
+  #
+  # Run between the UUID assignment and the checksum computation, so a hook MAY
+  # set a checksummed column (scope_gid, metadata, ...) and the row still passes
+  # `AuditLog.verify_chain`. No `prepend: true` needed.
+  #
+  # Each hook is rescued individually — a failing hook is logged and skipped and
+  # never fails the audit write. Batched writes (StandardAudit.batch, which uses
+  # insert_all!) never instantiate a model, so hooks do not run there.
+  #
+  # config.before_checksum { |log| log.scope = MyApp.derive_scope(log) }
+  # config.before_checksum :backfill_scope   # an AuditLog instance method
 end

data/lib/standard_audit/configuration.rb

@@ -5,7 +5,9 @@ module StandardAudit
                   :current_actor_resolver, :current_request_id_resolver,
                   :current_ip_address_resolver, :current_user_agent_resolver,
                   :current_session_id_resolver,
-                  :sensitive_keys, :metadata_builder,
+                  :sensitive_keys, :sensitive_key_patterns,
+                  :sensitive_key_exceptions, :filter_nested_metadata,
+                  :metadata_builder, :before_checksum_hooks,
                   :anonymizable_metadata_keys, :retention_days
 
     def initialize
@@ -43,7 +45,37 @@ module StandardAudit
         private_key certificate_chain
         ssn credit_card authorization
       ]
+      # Regexps matched against every metadata key name, in addition to the
+      # exact-match `sensitive_keys` list. This is the supported way to catch a
+      # family of keys: `/secret/i` redacts `client_secret`, `webhook_secret`,
+      # and `secret` alike.
+      #
+      # There is deliberately NO substring *mode* for `sensitive_keys` — see
+      # the note in MetadataFilter. Patterns are opt-in and per-app, which is
+      # the only safe shape for a rule applied to append-only rows.
+      @sensitive_key_patterns = []
+
+      # Key names (String/Symbol, exact) or Regexps that are never redacted,
+      # even when `sensitive_keys` or `sensitive_key_patterns` matches. Lets an
+      # app adopt a broad pattern while keeping the handful of real audit keys
+      # it would otherwise swallow, e.g.
+      # `sensitive_key_patterns = [/token/i]` with
+      # `sensitive_key_exceptions = %i[input_tokens output_tokens]`.
+      @sensitive_key_exceptions = []
+
+      # When true, redaction descends into nested Hashes (and Hashes inside
+      # Arrays), so `metadata: { stripe: { client_secret: … } }` is caught.
+      # Defaults to false: it changes what gets written, and audit rows are
+      # append-only. Reserved keys are never descended into.
+      @filter_nested_metadata = false
+
       @metadata_builder = nil
+
+      # Callables (or Symbols naming an AuditLog instance method) run on
+      # `before_create` AFTER the UUID is assigned and BEFORE the checksum is
+      # computed. See Configuration#before_checksum.
+      @before_checksum_hooks = []
+
       @anonymizable_metadata_keys = %i[email name ip_address]
 
       # Retention defaults from ENV so it can be set per-environment without a
@@ -63,6 +95,37 @@ module StandardAudit
       days&.positive? ? days : nil
     end
 
+    # Registers a hook to run between `assign_uuid` and `compute_checksum` on
+    # every audit write that instantiates a model.
+    #
+    #   config.before_checksum { |log| log.scope = derive_scope(log) }
+    #   config.before_checksum :backfill_organization_scope
+    #
+    # A hook may set a `CHECKSUM_FIELDS` member (`scope_gid`, `metadata`, …) and
+    # the row will still verify, because the checksum is computed afterwards.
+    # That is the whole point: before this existed, hosts had to register their
+    # own `before_create ..., prepend: true` to beat the gem's checksum
+    # callback, which is fragile ordering knowledge no host should need.
+    #
+    # Hooks accumulate and run in registration order. Each is rescued
+    # individually — a failing hook logs and is skipped; it never fails the
+    # audit write.
+    #
+    # A Symbol/String is sent to the AuditLog instance (use this for methods
+    # 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.
+    def before_checksum(hook = nil, &block)
+      hook ||= block
+      raise ArgumentError, "before_checksum needs a callable, a Symbol, or a block" if hook.nil?
+
+      @before_checksum_hooks << hook
+      hook
+    end
+
     def subscribe_to(pattern)
       @subscriptions << pattern
     end

data/lib/standard_audit/metadata_filter.rb

@@ -0,0 +1,155 @@
+module StandardAudit
+  # The single implementation of sensitive-key redaction for audit metadata.
+  #
+  # There used to be two: one in `StandardAudit.record` and one in
+  # `Subscriber#extract_metadata`. They had already diverged — the subscriber
+  # copy did not subtract `RESERVED_METADATA_KEYS`, so an app that (reasonably)
+  # added `:_tags` to `sensitive_keys` got the reserved key preserved on the
+  # `record` path and stripped on the `ActiveSupport::Notifications` path. Two
+  # copies of a security filter drifting apart is exactly the failure mode
+  # worth designing out, so both paths now call here.
+  #
+  # The divergence is resolved in favour of `record`'s behaviour: reserved keys
+  # are subtracted from the sensitive set and can never be filtered.
+  #
+  # == Matching
+  #
+  # A key is redacted when it matches `config.sensitive_keys` **exactly** (by
+  # name, string/symbol insensitive) or matches one of
+  # `config.sensitive_key_patterns` (Regexps, always applied), unless it is
+  # listed in `config.sensitive_key_exceptions` or is a reserved key.
+  #
+  # == Why there is no substring mode
+  #
+  # Matching `sensitive_keys` by substring instead of exactly is the obvious
+  # "fix" for `client_secret` not matching `:secret`, and it is a trap. Against
+  # the current default key list it would strip real audit content across the
+  # estate:
+  #
+  #   :token   => input_tokens, output_tokens (live LLM cost accounting),
+  #              token_digest (rendered in a staff audit UI)
+  #   :password => password_reset_sent_at, onepassword
+  #   :authorization => authorization_endpoint
+  #
+  # Audit rows are append-only, so a bad default cannot be undone — the content
+  # is simply never written. `sensitive_key_patterns` is the supported tool
+  # instead: `/secret/i` solves the motivating `client_secret` case exactly,
+  # opt-in and per-app, and `rake standard_audit:sensitive_keys:dry_run` turns
+  # "is this rule safe for my data?" into a command rather than a guess.
+  class MetadataFilter
+    # Raised when metadata is neither nil nor hash-like. Deliberately a raise
+    # rather than a pass-through: this filter **fails closed**. An
+    # `ActionController::Parameters` is not a `Hash`, and letting an unrecognised
+    # object through unfiltered would write raw params — passwords included —
+    # into an append-only row. Pre-0.7.0 the same input blew up with
+    # `NoMethodError` on `#reject`, so raising preserves the outcome while
+    # naming the cause.
+    class UnfilterableMetadataError < ArgumentError; end
+
+    class << self
+      def call(metadata, config: StandardAudit.config)
+        new(config: config).call(metadata)
+      end
+    end
+
+    def initialize(config: StandardAudit.config)
+      @config = config
+    end
+
+    # Filters anything hash-like, not just `Hash` — `ActionController::Parameters`
+    # and other `each_pair`-able wrappers are filtered rather than waved
+    # through. `nil` passes (there is nothing to leak); anything else raises.
+    #
+    # Descends into nested Hashes (and Hashes inside Arrays) only when
+    # `config.filter_nested_metadata` is true. Reserved keys are preserved and
+    # their values are left entirely alone, **at every depth** — `_tags` and
+    # `_source` are gem-owned, not host payload, and immunity that held only at
+    # the top level would be a confusing half-guarantee.
+    def call(metadata)
+      return nil if metadata.nil?
+
+      unless hash_like?(metadata)
+        raise UnfilterableMetadataError,
+          "audit metadata must be nil or hash-like (got #{metadata.class}); " \
+          "refusing to write it unfiltered"
+      end
+
+      filtered = metadata.reject { |key, _| filter?(key) }
+      return filtered unless @config.filter_nested_metadata
+
+      filter_values(filtered)
+    end
+
+    # True when `key` would be redacted from metadata. Public so hosts (and the
+    # dry-run tooling) can ask the question without writing a row.
+    def filter?(key)
+      key = key.to_s
+
+      # `_tags` and `_source` are owned by EventSubscriber and are never
+      # stripped, even if a consumer lists them in `sensitive_keys`.
+      return false if StandardAudit::RESERVED_METADATA_KEYS.include?(key)
+      return false if exception?(key)
+
+      sensitive_keys.include?(key) || sensitive_key_patterns.any? { |pattern| pattern.match?(key) }
+    end
+
+    private
+
+    def hash_like?(value)
+      value.respond_to?(:each_pair) && value.respond_to?(:reject)
+    end
+
+    # Rewrites each value in place on the already-rejected copy. In place
+    # because `transform_values` is not guaranteed across every hash-like
+    # wrapper, whereas `[]=` is.
+    def filter_values(hash)
+      hash.each_pair do |key, value|
+        # Reserved subtree: immune at every depth, never descended into.
+        next if StandardAudit::RESERVED_METADATA_KEYS.include?(key.to_s)
+
+        replacement = filter_descendant(value)
+        hash[key] = replacement unless replacement.equal?(value)
+      end
+
+      hash
+    end
+
+    def filter_descendant(value)
+      if hash_like?(value)
+        filter_values(value.reject { |key, _| filter?(key) })
+      elsif value.is_a?(Array)
+        value.map { |element| filter_descendant(element) }
+      else
+        value
+      end
+    end
+
+    def sensitive_keys
+      @sensitive_keys ||= @config.sensitive_keys.map(&:to_s) - StandardAudit::RESERVED_METADATA_KEYS
+    end
+
+    # A String entry is read as a Regexp source, so the rake task (and a
+    # `SENSITIVE_KEY_PATTERNS` env var) can pass one through without eval.
+    def sensitive_key_patterns
+      @sensitive_key_patterns ||= Array(@config.sensitive_key_patterns).map do |pattern|
+        pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern.to_s)
+      end
+    end
+
+    def exception?(key)
+      exact_exceptions.include?(key) || pattern_exceptions.any? { |pattern| pattern.match?(key) }
+    end
+
+    def exceptions
+      @exceptions ||= Array(@config.sensitive_key_exceptions).partition { |entry| entry.is_a?(Regexp) }
+    end
+
+    def pattern_exceptions
+      exceptions.first
+    end
+
+    def exact_exceptions
+      @exact_exceptions ||= exceptions.last.map(&:to_s)
+    end
+  end
+end

data/lib/standard_audit/reference_preloading.rb

@@ -0,0 +1,298 @@
+require "cgi"
+require "active_support/concern"
+
+module StandardAudit
+  # Batch resolution of the GlobalID-backed `actor` / `target` / `scope`
+  # references on a page of audit rows, plus the per-row memo the readers
+  # consult.
+  #
+  # Why this exists: `AuditLog#actor` resolves `actor_gid` through
+  # `GlobalID::Locator.locate`, which is one query per row. Rendering N rows
+  # that each read `actor` and `target` issues O(N) lookups — an N+1 that
+  # Prosopite fails in every consuming app. Before this concern existed, apps
+  # worked around it by defining their own `preloaded_actor=` writer (or
+  # reaching into `@preloaded_actor` with `instance_variable_set`) and
+  # hand-rolling a per-type whitelist loader.
+  #
+  # == Memo semantics
+  #
+  # The memo is a Hash consulted with `key?`, not a pair of ivars checked with
+  # `defined?`. That distinction matters: a reference that was preloaded but
+  # whose record has since been deleted memoizes `nil`, and reads back as
+  # `nil` *without* falling through to a query. "Preloaded, and the answer is
+  # nothing" is therefore distinct from "not preloaded".
+  #
+  # `actor=` / `target=` / `scope=` populate the memo too, since the writer
+  # already holds the record. `reload` clears it.
+  #
+  # == Batched writes
+  #
+  # `StandardAudit.batch { ... }` flushes through `insert_all!` and never
+  # instantiates an AuditLog, so nothing in this concern runs on that path —
+  # neither the memo nor the writers. It is a no-op for batched writes by
+  # construction, not by accident.
+  module ReferencePreloading
+    extend ActiveSupport::Concern
+
+    # The GlobalID-backed reference columns. `scope` is preloadable but not in
+    # the default `refs:` set, since most read surfaces render actor/target
+    # only.
+    REFERENCES = %i[actor target scope].freeze
+
+    DEFAULT_REFS = %i[actor target].freeze
+
+    class_methods do
+      # Resolves the given references for a whole collection of audit logs in a
+      # fixed number of queries (one per distinct stored `*_type`), then
+      # memoizes the result on each row.
+      #
+      #   AuditLog.preload_references(
+      #     logs,
+      #     refs: %i[actor target],
+      #     only: [Account, Profile, Order],
+      #     includes: { "Profile" => [:account], "Order" => [:user] }
+      #   )
+      #
+      # [refs:]     Which references to resolve. Defaults to `%i[actor target]`.
+      # [only:]     Optional whitelist of permitted classes. See the note below —
+      #             this is matched against the *stored type string*, so it is
+      #             a stricter gate than `GlobalID::Locator`'s own `:only`.
+      # [includes:] Either a uniform Active Record `includes` spec applied to
+      #             every type, or a per-type Hash keyed by class name String
+      #             or Class constant (e.g. `{ "Profile" => [:account] }`).
+      #             A Hash counts as per-type only when *every* key is a String
+      #             or a Module; `{ account: :identifiers }` is therefore read
+      #             as a uniform nested-includes spec, as you would expect.
+      #
+      # == Why `only:` is matched on the stored string
+      #
+      # `GlobalID::Locator`'s `:only` option is evaluated as
+      # `gid.model_class <= klass`, which means it *constantizes the stored
+      # type string before deciding whether it was allowed*. That is the wrong
+      # order for audit rows, whose type strings are historical: a class that
+      # has since been renamed or removed raises `NameError` rather than being
+      # filtered out. So this method filters on the stored `*_type` string
+      # first, by class name, and only then hands the surviving gids to
+      # `locate_many` (still passing `only:` as a second gate).
+      #
+      # The consequence is that `only:` does **not** expand to subclasses or
+      # to modules the way GlobalID's does — list every concrete class whose
+      # name you expect to see in `actor_type` / `target_type`. Deny-by-default
+      # is the safe direction for a whitelist.
+      #
+      # A reference whose type is not in `only:` memoizes `nil`, so it reads
+      # back as nil without a query rather than silently re-N+1ing.
+      #
+      # Returns the logs as an Array.
+      def preload_references(logs, refs: DEFAULT_REFS, only: nil, includes: nil)
+        logs = logs.to_a
+        return logs if logs.empty?
+
+        Array(refs).each do |ref|
+          ref = ref.to_sym
+          unless REFERENCES.include?(ref)
+            raise ArgumentError, "unknown audit reference #{ref.inspect} (expected one of #{REFERENCES.inspect})"
+          end
+
+          preload_one_reference(logs, ref, only: only, includes: includes)
+        end
+
+        logs
+      end
+
+      # Extracts the model id from a GlobalID string without resolving it:
+      # "gid://some-app/Account/123" => "123".
+      #
+      # Deliberately *not* `GlobalID.parse(gid)&.model_id`. Audit gids are
+      # historical and the rows are append-only, so a gid written by another
+      # app — or before this app was renamed — is a real, permanent row whose
+      # id must still be readable. Parsing it back through the locator
+      # machinery resolves against the *current* `GlobalID.app`, which is not
+      # what these rows are keyed on.
+      #
+      # This mirrors `URI::GID#set_model_components` exactly, minus the app
+      # check and the validations: drop any `?params` query, take everything
+      # after the model-name segment, split composite ids on "/", and
+      # `CGI.unescape` each part (`URI::GID.build` `CGI.escape`s them). Returns
+      # a String for a single-column primary key and an Array of Strings for a
+      # composite one, matching `GlobalID#model_id`.
+      def reference_model_id(gid)
+        return nil if gid.blank?
+
+        # "gid:" , "" , app , ModelName , <id segment(s)>
+        segment = gid.to_s.split("?", 2).first.to_s.split("/", 5)[4]
+        return nil if segment.blank?
+
+        parts = segment.split("/").reject(&:blank?).map { |part| CGI.unescape(part) }
+        return nil if parts.empty?
+
+        parts.length == 1 ? parts.first : parts
+      end
+
+      private
+
+      def preload_one_reference(logs, ref, only:, includes:)
+        gid_attr = :"#{ref}_gid"
+        type_attr = :"#{ref}_type"
+        allowed_names = only && Array(only).map { |klass| klass.is_a?(Module) ? klass.name : klass.to_s }
+
+        index = {}
+        unresolvable_types = []
+
+        logs.group_by { |log| log.public_send(type_attr) }.each do |type, type_logs|
+          # A blank `*_type` with a populated `*_gid` happens on historical and
+          # partially-backfilled rows. The per-row reader can still resolve
+          # those (the gid carries the model name), so mark the group
+          # unresolvable rather than memoizing nil — batching must never make a
+          # resolvable reference read back as nothing.
+          if type.blank?
+            unresolvable_types << type
+            next
+          end
+
+          # Not whitelisted: intentionally left out of the index so it memoizes
+          # nil (no query, now or later).
+          next if allowed_names && !allowed_names.include?(type)
+
+          gids = type_logs.filter_map { |log| log.public_send(gid_attr).presence }.uniq
+          next if gids.empty?
+
+          begin
+            locate_reference_records(gids, only: only, includes: includes_for(includes, type)).each do |record|
+              index[[type, normalized_record_key(record.id)]] = record
+            end
+          rescue NameError, ActiveRecord::StatementInvalid => e
+            # A historical type string that no longer constantizes, or a
+            # relation the current schema can't satisfy. Leave these rows
+            # *unmemoized* so the per-row reader behaves exactly as it did
+            # before preloading was attempted — memoizing nil here would
+            # silently rewrite behaviour on a bad `includes:`.
+            unresolvable_types << type
+            Rails.logger.warn("[StandardAudit] Could not preload #{ref} for type #{type.inspect}: #{e.class}: #{e.message}")
+          end
+        end
+
+        logs.each do |log|
+          type = log.public_send(type_attr)
+          next if unresolvable_types.include?(type)
+
+          log.write_preloaded_reference(
+            ref,
+            index[[type, reference_model_id(log.public_send(gid_attr))]]
+          )
+        end
+      end
+
+      # `ignore_missing: true` makes this a `where(id: ids)` instead of
+      # `find(ids)`, so a deleted record is simply absent from the result
+      # rather than raising — which is what lets a deleted reference memoize
+      # nil.
+      def locate_reference_records(gids, only:, includes:)
+        options = { ignore_missing: true }
+        options[:only] = only if only
+        options[:includes] = includes if includes
+
+        GlobalID::Locator.locate_many(gids, options)
+      end
+
+      # Mirrors how `GlobalID::Locator::BaseLocator#locate_many` keys its own
+      # result index, so composite primary keys line up with
+      # `reference_model_id`.
+      def normalized_record_key(id)
+        id.is_a?(Array) ? id.map(&:to_s) : id.to_s
+      end
+
+      def includes_for(includes, type)
+        return nil if includes.nil?
+        return includes unless per_type_includes?(includes)
+
+        entry = includes.find { |key, _| (key.is_a?(Module) ? key.name : key.to_s) == type }
+        entry&.last
+      end
+
+      # A Hash counts as a per-type mapping only when every key names a class.
+      # Symbol keys mean the caller passed an Active Record includes spec such
+      # as `{ account: :identifiers }`, which must be applied uniformly.
+      def per_type_includes?(includes)
+        includes.is_a?(Hash) &&
+          includes.any? &&
+          includes.keys.all? { |key| key.is_a?(String) || key.is_a?(Module) }
+      end
+    end
+
+    # Writers. `preloaded_actor = record_or_nil` is the supported way to hand a
+    # separately-resolved record to a log; `nil` means "resolved to nothing",
+    # not "clear the memo".
+    REFERENCES.each do |ref|
+      define_method(:"preloaded_#{ref}=") do |record|
+        write_preloaded_reference(ref, record)
+      end
+
+      define_method(:"#{ref}_preloaded?") do
+        reference_preloaded?(ref)
+      end
+
+      # `actor_model_id` / `target_model_id` / `scope_model_id` — the trailing
+      # gid segment, without needing the record.
+      define_method(:"#{ref}_model_id") do
+        self.class.reference_model_id(public_send(:"#{ref}_gid"))
+      end
+    end
+
+    # The memo itself. Public because `preload_references` writes through it
+    # from the class side; treat it as gem-internal — `preloaded_actor=` and
+    # `actor_preloaded?` are the supported surface.
+    def preloaded_references
+      @preloaded_references ||= {}
+    end
+
+    def reference_preloaded?(ref)
+      preloaded_references.key?(ref.to_sym)
+    end
+
+    # See `preloaded_references` — gem-internal, but public so the class-level
+    # preloader can reach it.
+    def write_preloaded_reference(ref, record)
+      preloaded_references[ref.to_sym] = record
+    end
+
+    # Drops the memo so the next read re-resolves from the (possibly changed)
+    # gid columns.
+    def reload(...)
+      @preloaded_references = nil
+      super
+    end
+
+    private
+
+    # The single-row fallback: identical to the pre-0.7.0 reader behaviour.
+    def locate_reference(ref)
+      gid = public_send(:"#{ref}_gid")
+      return nil if gid.blank?
+
+      GlobalID::Locator.locate(gid)
+    rescue ActiveRecord::RecordNotFound
+      nil
+    end
+
+    def read_reference(ref)
+      ref = ref.to_sym
+      return preloaded_references[ref] if preloaded_references.key?(ref)
+
+      locate_reference(ref)
+    end
+
+    def assign_reference(ref, record)
+      if record.nil?
+        public_send(:"#{ref}_gid=", nil)
+        public_send(:"#{ref}_type=", nil)
+      else
+        public_send(:"#{ref}_gid=", record.to_global_id.to_s)
+        public_send(:"#{ref}_type=", record.class.name)
+      end
+
+      write_preloaded_reference(ref, record)
+      record
+    end
+  end
+end

data/lib/standard_audit/rspec.rb

@@ -8,9 +8,23 @@ require "standard_audit"
 # - Resets the Configuration via `StandardAudit.reset_configuration!` so
 #   that mutations to `StandardAudit.config` (subscriptions, sensitive
 #   keys, async flag, custom resolvers, etc.) do not bleed across specs.
-#   Consumers that customise configuration must re-call
-#   `StandardAudit.configure { |c| ... }` from a `before` hook in their
-#   own suite if they need a non-default baseline.
+#
+# IMPORTANT — declare your configuration as a baseline. The reset restores
+# gem defaults, and the config object holds *behaviour*, not just data:
+# `before_checksum_hooks` live there. A suite that installs this plugin
+# without a baseline silently loses its write-time hooks after the first
+# example, and the specs that would have caught it pass vacuously.
+#
+# So in `config/initializers/standard_audit.rb`, use:
+#
+#   StandardAudit.configure(baseline: true) do |config|
+#     config.subscribe_to "myapp.**"
+#     config.before_checksum :backfill_scope
+#   end
+#
+# `reset_configuration!` replays that block onto the fresh Configuration,
+# so every example starts from your app's real configuration. There is
+# nothing to re-apply by hand in a `before` hook.
 #
 # The memoized `Subscriber` and `EventSubscriber` instances are *not*
 # torn down here — they are wired up at engine boot via initializers and

data/lib/standard_audit/sensitive_keys_dry_run.rb

@@ -0,0 +1,177 @@
+require "set"
+
+module StandardAudit
+  # Answers "is this redaction rule safe for MY data?" against the rows an app
+  # already has, before the rule is switched on.
+  #
+  # This matters more here than in most gems: audit rows are append-only, so a
+  # rule that swallows real audit content cannot be undone after the fact — the
+  # content is simply never written from then on. Reading the historical rows
+  # first turns the judgement call into a command.
+  #
+  # Keys are extracted **in Ruby**, not with `jsonb_object_keys`, so this works
+  # against SQLite (the dummy app), MySQL, and Postgres alike. The install
+  # template's migration uses jsonb + GIN, but the gem itself stays
+  # backend-neutral.
+  #
+  #   StandardAudit::SensitiveKeysDryRun.call(sensitive_key_patterns: [/secret/i])
+  #   # => #<Report rows_scanned=1204 stripped={"client_secret"=>18, ...} ...>
+  #
+  class SensitiveKeysDryRun
+    # [rows_scanned]        how many audit rows were read
+    # [stripped]            key path => row count, for keys the candidate rule
+    #                       would redact
+    # [kept]                key path => row count, for keys it would keep
+    # [nested_unfiltered]   key path => row count, for *nested* keys the rule
+    #                       matches but which are NOT redacted because
+    #                       `filter_nested_metadata` is off. This is the
+    #                       exposure `filter_nested_metadata` exists to close;
+    #                       empty when nested filtering is enabled.
+    Report = Struct.new(:rows_scanned, :stripped, :kept, :nested_unfiltered, :nested, keyword_init: true) do
+      def any_stripped?
+        stripped.any?
+      end
+
+      def to_s
+        lines = []
+        lines << "Rows scanned: #{rows_scanned}"
+        lines << "Nested filtering: #{nested ? 'on' : 'off'}"
+        lines << ""
+
+        lines << section("WOULD BE STRIPPED", stripped, "Nothing would be stripped.")
+        lines << ""
+        lines << section("KEPT", kept, "No metadata keys found.")
+
+        if nested_unfiltered.any?
+          lines << ""
+          lines << section(
+            "MATCHES BUT NOT STRIPPED (nested; set config.filter_nested_metadata = true to redact)",
+            nested_unfiltered,
+            nil
+          )
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def section(title, counts, empty_message)
+        out = [title, "=" * title.length]
+
+        if counts.empty?
+          out << (empty_message || "None.")
+        else
+          width = counts.keys.map(&:length).max
+          counts.sort_by { |key, count| [-count, key] }.each do |key, count|
+            out << format("  %-#{width}s  %d row(s)", key, count)
+          end
+        end
+
+        out.join("\n")
+      end
+    end
+
+    class << self
+      # Every keyword defaults to the app's live configuration, so calling it
+      # with no arguments reports what the *current* config does.
+      def call(sensitive_keys: nil, sensitive_key_patterns: nil, sensitive_key_exceptions: nil,
+               nested: nil, relation: nil, batch_size: 1000)
+        new(
+          sensitive_keys: sensitive_keys,
+          sensitive_key_patterns: sensitive_key_patterns,
+          sensitive_key_exceptions: sensitive_key_exceptions,
+          nested: nested
+        ).call(relation: relation, batch_size: batch_size)
+      end
+    end
+
+    def initialize(sensitive_keys: nil, sensitive_key_patterns: nil, sensitive_key_exceptions: nil, nested: nil)
+      live = StandardAudit.config
+
+      candidate = Configuration.new
+      candidate.sensitive_keys = sensitive_keys || live.sensitive_keys
+      candidate.sensitive_key_patterns = sensitive_key_patterns || live.sensitive_key_patterns
+      candidate.sensitive_key_exceptions = sensitive_key_exceptions || live.sensitive_key_exceptions
+
+      @nested = nested.nil? ? live.filter_nested_metadata : nested
+      @filter = MetadataFilter.new(config: candidate)
+    end
+
+    def call(relation: nil, batch_size: 1000)
+      relation ||= StandardAudit::AuditLog.all
+
+      rows = 0
+      stripped = Hash.new(0)
+      kept = Hash.new(0)
+      nested_unfiltered = Hash.new(0)
+
+      relation.select(:id, :metadata).find_each(batch_size: batch_size) do |log|
+        rows += 1
+        metadata = log.metadata
+        next unless metadata.respond_to?(:each_pair)
+
+        # Collect distinct paths per row first, then increment once each. A row
+        # whose `charges[]` array holds two matching hashes is ONE affected row,
+        # not two — the counts are documented as row counts.
+        row = { stripped: Set.new, kept: Set.new, nested_unfiltered: Set.new }
+        walk(metadata, nil, row, top_level: true)
+
+        row[:stripped].each { |path| stripped[path] += 1 }
+        row[:kept].each { |path| kept[path] += 1 }
+        row[:nested_unfiltered].each { |path| nested_unfiltered[path] += 1 }
+      end
+
+      Report.new(
+        rows_scanned: rows,
+        stripped: stripped,
+        kept: kept,
+        nested_unfiltered: nested_unfiltered,
+        nested: @nested
+      )
+    end
+
+    private
+
+    def walk(hash, prefix, row, top_level:)
+      hash.each_pair do |key, value|
+        name = key.to_s
+        path = prefix ? "#{prefix}.#{name}" : name
+
+        # Reserved keys are immune at every depth, and their subtree is
+        # gem-owned — never descended into. Mirrors MetadataFilter exactly, so
+        # the dry run cannot misrepresent the rule it is modelling.
+        if StandardAudit::RESERVED_METADATA_KEYS.include?(name)
+          row[:kept] << path
+          next
+        end
+
+        matches = @filter.filter?(name)
+
+        if matches && (top_level || @nested)
+          row[:stripped] << path
+          next
+        end
+
+        # A nested match that survives because nested filtering is off. Reported
+        # separately rather than silently counted as "kept" — this is exactly
+        # the leak `filter_nested_metadata` closes.
+        if matches
+          row[:nested_unfiltered] << path
+        else
+          row[:kept] << path
+        end
+
+        descend(value, path, row)
+      end
+    end
+
+    def descend(value, path, row)
+      if value.respond_to?(:each_pair)
+        walk(value, path, row, top_level: false)
+      elsif value.is_a?(Array)
+        value.each { |element| descend(element, "#{path}[]", row) }
+      end
+    end
+  end
+end

data/lib/standard_audit/subscriber.rb

@@ -79,9 +79,11 @@ module StandardAudit
         raw_metadata = config.metadata_builder.call(raw_metadata)
       end
 
-      # Filter sensitive keys
-      sensitive = config.sensitive_keys.map(&:to_s)
-      raw_metadata.reject { |k, _| sensitive.include?(k.to_s) }
+      # 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
   end
 end

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/standard_audit.rb

@@ -1,8 +1,11 @@
 require "standard_audit/version"
 require "standard_audit/engine"
 require "standard_audit/configuration"
+require "standard_audit/metadata_filter"
+require "standard_audit/sensitive_keys_dry_run"
 require "standard_audit/subscriber"
 require "standard_audit/event_subscriber"
+require "standard_audit/reference_preloading"
 require "standard_audit/auditable"
 require "standard_audit/audit_scope"
 require "standard_audit/checks/retention"
@@ -13,8 +16,30 @@ module StandardAudit
   RESERVED_METADATA_KEYS = %w[_tags _source].freeze
 
   class << self
-    def configure
-      yield(config) if block_given?
+    # Applies configuration to the single mutable Configuration instance.
+    #
+    # `baseline: true` also *remembers* the block, so `reset_configuration!`
+    # replays it. That matters because the config object holds behaviour, not
+    # just data — `before_checksum_hooks` in particular. Without a baseline, a
+    # suite that installs the rspec plugin (which calls `reset_configuration!`
+    # before every example) silently loses write-time hooks after the first
+    # example, and the specs that would notice pass vacuously.
+    #
+    # Idiomatic host usage, in config/initializers/standard_audit.rb:
+    #
+    #   StandardAudit.configure(baseline: true) do |config|
+    #     config.subscribe_to "myapp.**"
+    #     config.before_checksum :backfill_scope
+    #   end
+    #
+    # Only the most recent `baseline: true` block is remembered; call it once,
+    # from the initializer.
+    def configure(baseline: false, &block)
+      return config unless block
+
+      @baseline_configuration = block if baseline
+      block.call(config)
+      config
     end
 
     def config
@@ -26,10 +51,9 @@ module StandardAudit
 
       actor ||= config.current_actor_resolver.call
 
-      # Filter sensitive keys. `_tags` and `_source` are reserved internal
-      # metadata keys owned by EventSubscriber and are never stripped.
-      sensitive = config.sensitive_keys.map(&:to_s) - RESERVED_METADATA_KEYS
-      filtered_metadata = metadata.reject { |k, _| sensitive.include?(k.to_s) }
+      # Redaction lives in MetadataFilter, shared with Subscriber, so the two
+      # write paths cannot drift apart.
+      filtered_metadata = MetadataFilter.call(metadata, config: config)
 
       attrs = {
         event_type: event_type,
@@ -101,8 +125,24 @@ module StandardAudit
       @event_subscriber ||= EventSubscriber.new
     end
 
-    def reset_configuration!
+    # Drops the memoized Configuration. Any block registered with
+    # `configure(baseline: true)` is replayed onto the fresh instance, so a
+    # per-example reset restores the app's real configuration rather than the
+    # gem defaults.
+    def reset_configuration!(replay_baseline: true)
       @configuration = nil
+      @baseline_configuration&.call(config) if replay_baseline
+      config
+    end
+
+    # Forgets the `configure(baseline: true)` block. Mainly for the gem's own
+    # specs and for a host that needs a genuinely pristine configuration.
+    def clear_baseline_configuration!
+      @baseline_configuration = nil
+    end
+
+    def baseline_configured?
+      !@baseline_configuration.nil?
     end
 
     private

data/lib/tasks/standard_audit_tasks.rake

@@ -79,6 +79,47 @@ namespace :standard_audit do
     puts "Backfilled checksums for #{count} audit log records"
   end
 
+  namespace :sensitive_keys do
+    desc "Report which historical metadata keys a redaction rule would strip (read-only)"
+    task :dry_run, [:pattern] => :environment do |_t, args|
+      # Audit rows are append-only, so a redaction rule that swallows real
+      # content cannot be undone. This reads the rows you already have and
+      # reports, per key, what the rule would have stripped.
+      #
+      #   rake standard_audit:sensitive_keys:dry_run
+      #   rake "standard_audit:sensitive_keys:dry_run[secret]"
+      #   NESTED=1 rake "standard_audit:sensitive_keys:dry_run[secret|token]"
+      #
+      # The argument is a Regexp source, matched case-insensitively, and is
+      # applied *in addition to* the app's configured sensitive_keys.
+      # NESTED=1/0 overrides config.filter_nested_metadata for the run.
+      pattern = args[:pattern].presence || ENV["PATTERN"].presence
+      patterns = StandardAudit.config.sensitive_key_patterns.dup
+      patterns << Regexp.new(pattern, Regexp::IGNORECASE) if pattern
+
+      nested =
+        case ENV["NESTED"]
+        when nil, "" then nil
+        when "0", "false" then false
+        else true
+        end
+
+      report = StandardAudit::SensitiveKeysDryRun.call(
+        sensitive_key_patterns: patterns,
+        nested: nested,
+        batch_size: (ENV["BATCH_SIZE"] || 1000).to_i
+      )
+
+      puts "StandardAudit sensitive-key dry run"
+      puts "==================================="
+      puts "Candidate pattern: #{pattern ? Regexp.new(pattern, Regexp::IGNORECASE).inspect : '(none — reporting current config)'}"
+      puts ""
+      puts report
+      puts ""
+      puts "Nothing was written. Rows are append-only; a rule you enable applies only to future writes."
+    end
+  end
+
   desc "Export audit logs for a specific actor (GDPR right to access)"
   task :export_actor, [:actor_gid, :output] => :environment do |_t, args|
     raise "actor_gid is required" unless args[:actor_gid].present?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -109,7 +109,10 @@ files:
 - lib/standard_audit/configuration.rb
 - lib/standard_audit/engine.rb
 - lib/standard_audit/event_subscriber.rb
+- lib/standard_audit/metadata_filter.rb
+- lib/standard_audit/reference_preloading.rb
 - lib/standard_audit/rspec.rb
+- lib/standard_audit/sensitive_keys_dry_run.rb
 - lib/standard_audit/subscriber.rb
 - lib/standard_audit/version.rb
 - lib/tasks/standard_audit_tasks.rake