standard_audit 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fca49bbca23bc24c89aa7249f0ea4718c2f4fa6bae03748ec93a45df17c4bd0
-  data.tar.gz: 7920932fea8af270498c7620d7cb4e18e0cfaab1c0deb7f299715ce578882dd2
+  metadata.gz: b89dc74bd119d2e0f1ff5080cef706439e68b61c79d2a6b653fcd5a74e265ae1
+  data.tar.gz: 86686ea3bb611a13e8c8947ef3e0b63aad63eb47bfa1e48b16abba377a426f7f
 SHA512:
-  metadata.gz: 7117529ed69a81588ea18b081e3b8a8047dc9441fe116bef9e594beacc692108a1c8d625e2d4c1a959ac01a1d03857d9d94e91a4dfe65c52c35ce894b980e797
-  data.tar.gz: bdb36b281136e0928c4bac601bbee408de0cf040d70222c8d3339153c53312e1bd1820f136488086184426f68ce9f930b75d521b75fd25950f4f7b3bb232c66d
+  metadata.gz: b06e7ee9a3b5d79191cb47a532cf81efb95e3bb722015540be79ce4bb9412ab13b8e69985a66d368c8dcdfb099f34f1ca1d3f0d894bfc90cc409615782dde921
+  data.tar.gz: bb1e9316eba648a8d238becb75d33f705b82f509310e8c3e0d562656accac2b44339e49551e026ae0357bf57dda8fe8251f6f1d6c7df655777d5b157c3d17b0a

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-07-31
+
+### Security
+
+- **ActiveRecord objects in audit metadata are no longer written with all of their attributes.** Any record found in metadata — at any depth, and inside Arrays, Hashes and `ActiveRecord::Relation`s — is now replaced with a reference: `{ "gid" => "gid://app/Account/1", "type" => "Account", "id" => "1" }`. Applies to both write paths (`ActiveSupport::Notifications` and `StandardAudit.record`).
+
+  `standard_id` publishes live records under payload keys like `account:`, `current_account:`, `session:` and `code_challenge:`, and `Subscriber#extract_metadata` excluded only `actor`/`target`/`scope`/`request_id`/`ip_address`/`user_agent`/`session_id` — every other key was written whole. Confirmed present in real `audit_logs` rows: `account.password_digest`, `account.password_reset_token_digest`, `session.token_digest`, `session.lookup_hash`, `code_challenge.code`.
+
+  All three existing defences missed, each for a different reason: `sensitive_keys` matches key names exactly and the secrets are attributes *underneath* `account:`; `filter_nested_metadata` is off by default so the filter never descended to them; and `account:` does not look sensitive at the top level. This is not a redaction bug — key-based redaction is the wrong tool for a value that is an entire database row — so the value is replaced by type, before any key filtering runs.
+
+  **This fix stops the bleeding; it does not clean up.** `audit_logs` is append-only by design (`before_update` and `before_destroy` raise `ReadOnlyRecord`), so every row already written keeps its digests, for the whole of a retention window that is intentionally long. Upgrading changes only what is written from now on. Assessing and remediating existing rows is a separate, host-side exercise.
+
+  `sensitive_keys` semantics are untouched: still exact-match, still no substring mode. See rarebit-one/rarebit-ops#296.
+
+### Added
+
+- **`config.dereference_record_metadata`** (default `true`) — the escape hatch for the above. It defaults to the SAFE behaviour, unlike `filter_nested_metadata`, because the values it catches are ones no host asked to record: they arrive as a side effect of a payload carrying `account:` or `session:`, and an append-only row cannot be walked back. Set it to `false` only if an app genuinely depends on record attributes in metadata and has satisfied itself no secret-bearing column can reach a row.
+
+### Changed
+
+- **Consumer-visible beyond the secrets disappearing:** any metadata key that used to hold a record's attribute hash now holds a three-key reference, so dashboards, reports or queries reading e.g. `metadata->'account'->>'email'` will read `NULL` on new rows (old rows are unchanged, which makes the change look like a data gap rather than a schema change). Recover the specific fields you need with `metadata_builder`, which runs BEFORE dereferencing and still receives the record: `->(metadata) { metadata.merge(account_email: metadata[:account]&.email) }`. `actor`/`target`/`scope` are unaffected — they were already stored as GlobalIDs.
+
 ## [0.10.0] - 2026-07-31
 
 ### Added

data/README.md

@@ -332,6 +332,10 @@ StandardAudit.configure(baseline: true) do |config|
   # `metadata: { stripe: { client_secret: ... } }` is written intact.
   config.filter_nested_metadata = true
 
+  # Replace ActiveRecord objects in metadata with a reference instead of
+  # serialising every attribute. ON by default; see "Records in metadata".
+  config.dereference_record_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
@@ -695,6 +699,38 @@ Nested metadata is **not** redacted unless `filter_nested_metadata` is enabled
 — `metadata: { stripe: { client_secret: ... } }` passes both write paths under
 exact matching by default.
 
+### Records in metadata
+
+An ActiveRecord object appearing anywhere in metadata is replaced, by default,
+with a reference rather than a snapshot of the row:
+
+```ruby
+{ account: account }
+# => { account: { "gid" => "gid://myapp/Account/1", "type" => "Account", "id" => "1" } }
+```
+
+This applies at any depth, inside Arrays, Hashes and `ActiveRecord::Relation`s,
+on both write paths. It is on by default because key-based redaction cannot
+reach the problem: a payload key like `account:` looks like exactly the kind of
+key you want on an audit row, while the value serialises with
+`password_digest`, `token_digest`, `lookup_hash` and anything else the table
+happens to hold. Audit rows are append-only, so an unsafe default cannot be
+walked back.
+
+On the notifications path, records are dereferenced **after**
+`metadata_builder` runs, so a builder that needs real attributes still gets the
+record (`metadata_builder` has never applied to a direct `StandardAudit.record`
+call — pass the attributes you want in `metadata` there):
+
+```ruby
+config.metadata_builder = ->(metadata) {
+  metadata.merge(account_email: metadata[:account]&.email)
+}
+```
+
+`config.dereference_record_metadata = false` restores the pre-0.11.0 behaviour
+of writing full attributes. Prefer `metadata_builder` over turning it off.
+
 **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/lib/standard_audit/configuration.rb

@@ -7,6 +7,7 @@ module StandardAudit
                   :current_session_id_resolver,
                   :sensitive_keys, :sensitive_key_patterns,
                   :sensitive_key_exceptions, :filter_nested_metadata,
+                  :dereference_record_metadata,
                   :metadata_builder, :before_checksum_hooks,
                   :anonymizable_metadata_keys, :retention_days,
                   :audit_catalogue, :verify_audit_declarations,
@@ -72,6 +73,25 @@ module StandardAudit
       # append-only. Reserved keys are never descended into.
       @filter_nested_metadata = false
 
+      # When true (the default), an ActiveRecord object appearing anywhere in
+      # audit metadata is replaced by a reference —
+      # `{ "gid" => …, "type" => …, "id" => … }` — instead of being serialised
+      # with all of its attributes. See StandardAudit::RecordReference.
+      #
+      # Defaults to the SAFE behaviour, unlike `filter_nested_metadata`,
+      # because the values this catches are ones no host asked to record:
+      # `password_digest`, `token_digest`, `lookup_hash` and PKCE verifiers
+      # arriving as a side effect of a payload carrying `account:` or
+      # `session:`. Audit rows are append-only, so an unsafe default cannot be
+      # walked back — the rows already written keep whatever was in them.
+      #
+      # Set to false ONLY if an app genuinely depends on record attributes in
+      # metadata and has satisfied itself that no secret-bearing column can
+      # reach a row. Preferred alternative: keep this on and use
+      # `metadata_builder` to pull the specific attributes you want, which runs
+      # BEFORE dereferencing and still sees the record.
+      @dereference_record_metadata = true
+
       @metadata_builder = nil
 
       # Callables (or Symbols naming an AuditLog instance method) run on

data/lib/standard_audit/record_reference.rb

@@ -0,0 +1,141 @@
+module StandardAudit
+  # Replaces ActiveRecord objects found in audit metadata with a stable
+  # *reference* instead of a snapshot of the record's whole attribute set.
+  #
+  # == Why this exists
+  #
+  # `ActiveSupport::Notifications` payloads routinely carry live records —
+  # `standard_id` publishes `account:`, `current_account:`, `session:` and
+  # `code_challenge:` — and an AR object serialises with every attribute it
+  # has. That put `account.password_digest`,
+  # `account.password_reset_token_digest`, `session.token_digest`,
+  # `session.lookup_hash` and `code_challenge.code` into `audit_logs` rows
+  # across the estate (rarebit-one/rarebit-ops#296).
+  #
+  # None of the three existing defences fired: `sensitive_keys` matches keys
+  # exactly and the secrets are attributes *underneath* `account:`;
+  # `filter_nested_metadata` is off by default so the filter never descended
+  # to them; and `account:` does not look sensitive at the top level.
+  #
+  # Key-based redaction is the wrong tool here — the leak is not "this key is
+  # sensitive", it is "this value is an entire database row". So the value is
+  # replaced wholesale, by type, before any key filtering happens.
+  #
+  # == What replaces a record
+  #
+  #   { "gid" => "gid://dummy/Account/1", "type" => "Account", "id" => "1" }
+  #
+  # A GlobalID string is the identifier this gem already uses for `actor`,
+  # `target` and `scope` (`actor_gid`), so an audit row stays resolvable with
+  # `GlobalID::Locator`. `type` and `id` ride along because they survive a
+  # record being deleted, an app whose GlobalID app name changes, and records
+  # that have no GlobalID at all (unpersisted ones): for those, `gid` is
+  # simply absent and the reference is still meaningful.
+  module RecordReference
+    # Written in place of a container that contains itself. Depth alone is NOT
+    # used as the guard: a plain depth cap would rewrite deeply-but-finitely
+    # nested metadata that holds no records at all, and permanently lose audit
+    # content in an append-only row to protect against a structure that is
+    # merely large. Only a genuine cycle — the one thing that cannot be
+    # serialised anyway — is replaced.
+    CIRCULAR = "[standard_audit: circular reference]".freeze
+
+    class << self
+      # Returns a copy of `value` with every ActiveRecord object — at any
+      # depth, inside Arrays, Hashes and Relations — replaced by a reference
+      # Hash. Structures containing no records are returned untouched (same
+      # object), so this is a no-op for ordinary metadata.
+      #
+      # Never mutates the input: notification payloads are shared with every
+      # other subscriber.
+      def call(value, ancestors = nil)
+        return reference_for(value) if record?(value)
+
+        container = relation?(value) || value.is_a?(Array) || hash_like?(value)
+        return value unless container
+
+        ancestors ||= {}.compare_by_identity
+        return CIRCULAR if ancestors.key?(value)
+
+        ancestors[value] = true
+        begin
+          if relation?(value)
+            map_collection(value.to_a, ancestors)
+          elsif value.is_a?(Array)
+            map_collection(value, ancestors)
+          else
+            map_hash(value, ancestors)
+          end
+        ensure
+          ancestors.delete(value)
+        end
+      end
+
+      # The reference written in place of a record.
+      def reference_for(record)
+        {
+          "gid" => global_id_for(record),
+          "type" => record.class.name,
+          "id" => record.id&.to_s
+        }.compact
+      end
+
+      private
+
+      def record?(value)
+        defined?(ActiveRecord::Base) && value.is_a?(ActiveRecord::Base)
+      end
+
+      def relation?(value)
+        defined?(ActiveRecord::Relation) && value.is_a?(ActiveRecord::Relation)
+      end
+
+      def hash_like?(value)
+        value.respond_to?(:each_pair) && value.respond_to?(:key?)
+      end
+
+      def map_collection(array, ancestors)
+        changed = false
+        mapped = array.map do |element|
+          replacement = call(element, ancestors)
+          changed ||= !replacement.equal?(element)
+          replacement
+        end
+
+        changed ? mapped : array
+      end
+
+      def map_hash(hash, ancestors)
+        changed = false
+        mapped = {}
+
+        hash.each_pair do |key, value|
+          # Reserved keys are gem-owned (`_tags`, `_source`) and are left
+          # exactly alone here, as they are in MetadataFilter.
+          if StandardAudit::RESERVED_METADATA_KEYS.include?(key.to_s)
+            mapped[key] = value
+            next
+          end
+
+          replacement = call(value, ancestors)
+          changed ||= !replacement.equal?(value)
+          mapped[key] = replacement
+        end
+
+        changed ? mapped : hash
+      end
+
+      # `to_global_id` raises for an unpersisted record and for a model that
+      # does not include GlobalID::Identification. Neither is a reason to fail
+      # an audit write, and neither is a reason to fall back to writing the
+      # attributes.
+      def global_id_for(record)
+        return nil unless record.respond_to?(:to_global_id)
+
+        record.to_global_id.to_s
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/standard_audit/subscriber.rb

@@ -79,6 +79,16 @@ module StandardAudit
         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

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

data/lib/standard_audit.rb

@@ -2,6 +2,7 @@ require "standard_audit/version"
 require "standard_audit/engine"
 require "standard_audit/configuration"
 require "standard_audit/metadata_filter"
+require "standard_audit/record_reference"
 require "standard_audit/sensitive_keys_dry_run"
 require "standard_audit/subscriber"
 require "standard_audit/event_subscriber"
@@ -52,9 +53,26 @@ module StandardAudit
 
       actor ||= config.current_actor_resolver.call
 
+      if block_given?
+        # Block form: instrument via ActiveSupport::Notifications and let the
+        # Subscriber write the row, which it does with its own dereferencing and
+        # filtering. Nothing built below would be used, so it is not built —
+        # dereferencing a Relation here would load it eagerly, before the block
+        # has run, purely to discard the result.
+        ActiveSupport::Notifications.instrument(event_type, metadata.merge(
+          actor: actor, target: target, scope: scope
+        )) do
+          yield
+        end
+        return
+      end
+
       # Redaction lives in MetadataFilter, shared with Subscriber, so the two
-      # write paths cannot drift apart.
-      filtered_metadata = MetadataFilter.call(metadata, config: config)
+      # write paths cannot drift apart. Record dereferencing is applied on both
+      # paths for the same reason: a snapshot of a whole row is as unrecoverable
+      # here as it is on the notifications path.
+      dereferenced = config.dereference_record_metadata ? RecordReference.call(metadata) : metadata
+      filtered_metadata = MetadataFilter.call(dereferenced, config: config)
 
       attrs = {
         event_type: event_type,
@@ -66,16 +84,6 @@ module StandardAudit
         metadata: filtered_metadata
       }
 
-      if block_given?
-        # Block form: instrument via ActiveSupport::Notifications
-        ActiveSupport::Notifications.instrument(event_type, metadata.merge(
-          actor: actor, target: target, scope: scope
-        )) do
-          yield
-        end
-        return
-      end
-
       gid_attrs = {
         actor_gid: actor&.to_global_id&.to_s,
         actor_type: actor&.class&.name,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -114,6 +114,7 @@ files:
 - lib/standard_audit/metadata_filter.rb
 - lib/standard_audit/operation.rb
 - lib/standard_audit/operation/audit.rb
+- lib/standard_audit/record_reference.rb
 - lib/standard_audit/reference_preloading.rb
 - lib/standard_audit/rspec.rb
 - lib/standard_audit/rspec/operation.rb