standard_audit 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dff9827071db99dfcb9dc184f3cc20d0bcfd208de8f5d41c86efff0f7e4c2be
-  data.tar.gz: 979f93e8ed8d293695337e453ade9926b553be7904617d7c61d653ef5997a3ea
+  metadata.gz: 1ab5fcec99d13f0796742d817c1dd42e45c0e8518f8967033a67194c3179ae6e
+  data.tar.gz: b0f6272a600a665615cc533b439ad2b654d54c025bd7bc2b378b5c2eac7e850d
 SHA512:
-  metadata.gz: 98bf60f4d4d40d46ff28d9203c8686a5c57765a86c4c3ef1db97c59d32b27e355ac7b585730cd69865e54cf8540109c87546259ea19e4afdfa9a3510b5b52e1f
-  data.tar.gz: dda3b2376d9afcd2a61808fc79025e246365302f7b097c17a801bf47cc6a8f3e26a3e11b411dc19b31f6ebac32dc44107e92582e02813a22476be2fa1eaca32a
+  metadata.gz: 1ab1f514a13f1b03501cfdf18b3c2afcf8ff214a36992edb3e00f052384826c56bf09a35c4d7c4b8f92a4f28513cd8fe5534d946622112bb27bb6f8bfd8826c7
+  data.tar.gz: 7f9fc2acdb292b06f72b2323ac0c5c780348da8d1b91e9850ae73a61eba2361fb21b3aa431888de9d0003dc2934c0ba1b2a9a060bd4bd3b2a6a1bfb71eea5680

data/CHANGELOG.md

@@ -7,6 +7,63 @@ 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
+
+- `config.retention_days` now defaults from the `STANDARD_AUDIT_RETENTION_DAYS` environment variable, so a deployment can opt into a retention window without a code change. Unset/blank/zero/negative/non-numeric resolves to `nil` (infinite retention — the compliance-safe default that never auto-deletes). Host apps can still override `config.retention_days` in their initializer.
+- `StandardAudit::Checks::Retention` — a StandardHealth-compatible (duck-typed, no hard dependency) readiness check that flags unbounded retention on **production** deployments. Register it non-critical in `config/initializers/standard_health.rb`:
+  ```ruby
+  c.register_check :audit_retention, StandardAudit::Checks::Retention, critical: false
+  ```
+  When `APP_ENVIRONMENT == "production"` (falling back to `Rails.env.production?` so staging is not flagged) and `retention_days` is nil, it returns `:warn`, rolling `GET /health/ready` to `:degraded` — still HTTP 200, so it surfaces the advisory without failing the probe or blocking a deploy.
+
 ## [0.5.0] - 2026-04-29
 
 ### Changed

data/{MIT-LICENSE → LICENSE}

@@ -1,4 +1,6 @@
-Copyright (c) 2026 Jaryl Sim
+The MIT License (MIT)
+
+Copyright (c) 2026 Rarebit One
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

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) }
@@ -209,6 +235,8 @@ StandardAudit.configure do |config|
   config.anonymizable_metadata_keys = %i[email name ip_address]
 
   # -- Retention (schedule StandardAudit::CleanupJob to enforce) --
+  # Defaults from STANDARD_AUDIT_RETENTION_DAYS (see Retention below); set here
+  # to override per app. Leave unset for infinite retention.
   config.retention_days = 90
 end
 ```
@@ -339,6 +367,45 @@ File.write("export.json", JSON.pretty_generate(data))
 
 Returns a hash with `subject`, `exported_at`, `total_records`, and a `records` array.
 
+## Retention
+
+`config.retention_days` controls how long audit logs are kept. It is only
+enforced when you actually run cleanup (the `StandardAudit::CleanupJob` or the
+`standard_audit:cleanup` rake task) — setting it alone deletes nothing.
+
+It defaults from the `STANDARD_AUDIT_RETENTION_DAYS` environment variable, so a
+deployment can opt into a retention window without a code change:
+
+```bash
+STANDARD_AUDIT_RETENTION_DAYS=365   # keep 365 days
+# unset / blank / 0 / negative / non-numeric => nil => infinite retention
+```
+
+Infinite retention (the default) is the compliance-safe behavior: nothing is
+ever auto-deleted. For financial/legal domains that is usually what you want;
+enabling a finite window is a deliberate decision.
+
+### Production retention warning (StandardHealth)
+
+`StandardAudit::Checks::Retention` is a [StandardHealth](https://github.com/rarebit-one/standard_health)-compatible
+check that flags unbounded retention **on production deployments** as an
+advisory. Register it (non-critical) in `config/initializers/standard_health.rb`:
+
+```ruby
+StandardHealth.configure do |c|
+  c.register_check :audit_retention,
+                   StandardAudit::Checks::Retention,
+                   critical: false
+end
+```
+
+When `APP_ENVIRONMENT == "production"` (falling back to `Rails.env.production?`
+when that var is unset — so staging is not flagged) and `retention_days` is nil,
+the check returns `:warn`. That rolls `GET /health/ready` up to `:degraded`,
+which is **still HTTP 200** — it surfaces the advisory in the readiness JSON
+without failing the probe or blocking a deploy. The check is duck-typed and has
+no hard dependency on `standard_health`.
+
 ## Rake Tasks
 
 ```bash
@@ -382,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/checks/retention.rb

@@ -0,0 +1,58 @@
+module StandardAudit
+  module Checks
+    # A StandardHealth-compatible readiness check that warns when audit_logs
+    # retention is unbounded on a production deployment.
+    #
+    # It is intentionally duck-typed (no hard dependency on standard_health):
+    # it exposes the `#initialize(name:, critical:)` + `#run` contract the
+    # StandardHealth aggregator calls, so it loads even where standard_health
+    # is absent.
+    #
+    # Register it (NON-critical) in config/initializers/standard_health.rb:
+    #
+    #   c.register_check :audit_retention,
+    #                    StandardAudit::Checks::Retention,
+    #                    critical: false
+    #
+    # A :warn result rolls /health/ready up to :degraded, which is still
+    # HTTP 200 — it surfaces the advisory in the readiness JSON WITHOUT failing
+    # the probe or blocking a deploy. Only a *critical* check failure returns
+    # 503, and this check is never critical.
+    #
+    # "Production" is ENV["APP_ENVIRONMENT"] == "production" when that var is
+    # set (so staging — which also runs RAILS_ENV=production — is not flagged);
+    # otherwise it falls back to Rails.env.production?.
+    class Retention
+      def initialize(name: :audit_retention, critical: false)
+        @name = name
+        @critical = critical
+      end
+
+      def run
+        unless production?
+          return { status: :ok, detail: "retention advisory only runs on production deployments" }
+        end
+
+        days = StandardAudit.config.retention_days
+        return { status: :ok, retention_days: days } if days
+
+        {
+          status: :warn,
+          message: "audit_logs retention is unbounded on production. Set " \
+                   "STANDARD_AUDIT_RETENTION_DAYS (or config.retention_days) and schedule " \
+                   "StandardAudit::CleanupJob, or treat indefinite retention as a deliberate " \
+                   "compliance decision."
+        }
+      end
+
+      private
+
+      def production?
+        app_env = ENV["APP_ENVIRONMENT"].to_s
+        return app_env == "production" unless app_env.empty?
+
+        defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+      end
+    end
+  end
+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,9 +45,85 @@ 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_days = nil
+
+      # Retention defaults from ENV so it can be set per-environment without a
+      # code change. Unset/blank/non-positive => nil (infinite retention, the
+      # compliance-safe default that never auto-deletes). A host app can still
+      # override with `config.retention_days = N` in its initializer.
+      @retention_days = self.class.retention_days_from_env
+    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
+      raw = ENV["STANDARD_AUDIT_RETENTION_DAYS"]
+      return nil if raw.nil? || raw.strip.empty?
+
+      days = Integer(raw, exception: false)
+      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)