standard_audit 0.11.1 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 697434bf73f4588971d9fda7503f13f53a848ab4fe058fbc05be5b567a186d6f
-  data.tar.gz: e5bad881dc6a5ab13ae22d13777176120967161f40356dcd6522ab4616492c1f
+  metadata.gz: a6da3bdedaecde5d44a57afe47372bf419b9290ace08a2312d1c522df5a67561
+  data.tar.gz: 283e8c2839ddce46fa2ec6468423c75380256f51f05a0a52844763d5454b7da3
 SHA512:
-  metadata.gz: feb2b3354808c948aff042e0a3354ac2344c3e4ac1b03f0c375645ff7b1aaf1ec27253e87e764652ee7d52710a4c7aecd7748ba13475afa001a0c27f55a2ca79
-  data.tar.gz: a83422f4ef6b6ca319c29c450ae7cf82457cc5ad342345947a867e2243ef701c2bb0310a5b1d99f5cbf9c322b756f5094c42e77e53eb6ea3b828a834f94bfacc
+  metadata.gz: 96cd2995bbaaab665bc485770604f37b0b4188cf052a30639b804882a70cc276fad7e10b7ee21c65fa0294018687e06cea921ae7e387f4666a3f7298d29bbd09
+  data.tar.gz: 810d2becd35d3e0a5325786b86415c48318b4c23d7c8df46742916053cff6eaf5f97e3cba1e94b8ab479437751ba94177c28b05bc4c12837208a975698788aa0

data/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.1] - 2026-09-24
+
+### Upgrade steps
+
+1. **If you installed the 0.12.0 `add_anonymized_at` migration, check your copy.** The 0.12.0 template put `return if column_exists?(:audit_logs, :anonymized_at)` inside `change`. That early return also runs on rollback, so `db:rollback` deleted the `schema_migrations` row and silently left the column in place. Replace the body with `add_column :audit_logs, :anonymized_at, :datetime, if_not_exists: true` (in `change`), or copy the new up/down template. Nothing to do if your copy already uses `if_not_exists:` (sidekick-web, jumpdrive-web) or if you never ran the generator.
+2. If an error-tracker search or alert matches `before_checksum` hook failures on the `audit_event` context key, see Fixed.
+
+### Fixed
+
+- **The `add_anonymized_at` migration is reversible.** The template now uses explicit `up` / `down` with `add_column ..., if_not_exists: true` and `remove_column ..., if_exists: true`. It is still idempotent, and rollback now removes the column. A new generator spec runs the generated migration up, down and up.
+- **`before_checksum` hook failures use `config.audit_error_context_key`.** The hook's `Rails.error.report` hard-coded `audit_event:` as its context key. Every other audit-error report site uses the configured key (default `:audit_action`). Apps that set `audit_error_context_key = :audit_event` see no change. Apps on the default now get `audit_action:` for hook failures too, matching every other audit error.
+
+### Documentation
+
+- `current_scope_resolver` is for scope derived from `Current`. Scope derived from the row (e.g. the target's organisation) belongs in a `before_checksum` or `before_write` hook. The README no longer describes sidekick-web's target-derived hook as a `Current` back-fill.
+- New note: `before_write` / `before_checksum` run once per row, batched writes included. Memoize per-actor lookups (e.g. in a `CurrentAttributes` cache) to avoid an N+1 on a batch flush.
+- `record(raise: false)` reports through `Rails.error`, so failures reach Sentry only if a `Rails.error` subscriber is registered (`sentry-rails` registers one).
+
+## [0.12.0] - 2026-09-24
+
+### Upgrade steps
+
+1. Bump the gem and run `rails generate standard_audit:add_anonymized_at && rails db:migrate` (new nullable `audit_logs.anonymized_at`; idempotent, no table rewrite, strong_migrations-safe). Optional — without it everything works as in 0.11, and anonymized rows keep failing `verify_chain`.
+2. StandardId apps: delete `config.current_actor_resolver = -> { Current.account }` and `config.current_session_id_resolver = -> { Current.session&.id }` — they are now the defaults.
+3. If your `metadata_builder` must NOT run on direct `StandardAudit.record` / `audit!` writes, make it idempotent or move that logic (see Changed).
+4. Optionally adopt `current_scope_resolver`, `before_write`, `raise: false` and `require "standard_audit/rspec"`'s `have_audited` / baseline shared example — each README section says which host code it replaces.
+
+### Added
+
+- **`config.before_write = ->(entry) { … }`** — runs on every write path (direct `record`, block form, `Auditable#record_audit`, `Operation#audit!`, both subscribers; sync, async and batched), after the Current resolvers and `metadata_builder` and before dereferencing/redaction. Mutate the entry in place; raising aborts the write (direct callers see the error; subscribers rescue and report it). Replaces host wrappers such as fundbright's `AuditWriting#record_audit!` and its `audit!` PII-guard/`surface` override.
+- **`config.current_scope_resolver`** (default `nil`) — fallback audit scope when a write names none. Explicit `scope:` and `scope_extractor` results always win. Applied on every write path.
+- **`StandardAudit.record(..., raise: false)`** — a failed write is logged, reported to `Rails.error` as handled, and returns nil. Replaces the `AuditAuthFailure` rescue-and-report wrappers.
+- **`audit_logs.anonymized_at`** and the `standard_audit:add_anonymized_at` generator; the install migration now includes the column. `AuditLog#anonymized?` and `AuditLog.anonymization_column?`.
+- **`verify_chain` result gains `redacted:`** — rows stamped `anonymized_at` are counted there instead of as `digest_mismatch` failures. Their stored checksum is kept, so the chain still links through them, and their declared parent is still checked for `missing_parent`. `rake standard_audit:verify` prints the count when nonzero.
+- **RSpec support:** `have_audited("event").by(actor).on(target).within(scope).with_metadata(...).once` block matcher, and the `"a standard_audit baseline"` shared example. Loaded by `require "standard_audit/rspec"`, or individually from `standard_audit/rspec/matchers` and `standard_audit/rspec/baseline`.
+
+### Changed
+
+- **One write path.** Every entry point now ends in `StandardAudit.write_entry`. `StandardAudit::Subscriber` no longer re-implements the write, which has three visible effects:
+  - **`metadata_builder` now runs on direct `StandardAudit.record` calls** (and therefore `audit!` / `record_audit`), not only on the subscriber paths. Builders that inject context (`engine_scope`) now reach direct writes, closing the gap fundbright-web's initializer documents. A builder that is not idempotent would now see operation metadata too — review before upgrading.
+  - **Events handled by the ActiveSupport::Notifications subscriber inside `StandardAudit.batch` are now buffered** and flushed with the batch, like the `Rails.event` subscriber and direct calls already were. `before_checksum` hooks run for them (see Fixed).
+  - Subscriber failures are logged as `[StandardAudit] Error creating audit log for <event>: …` and reported with the same context as 0.11.1.
+- **Default resolvers match StandardId.** `current_actor_resolver` tries `Current.account`, then `Current.user`; `current_session_id_resolver` tries `Current.session&.id`, then `Current.session_id`. Each is `respond_to?`-guarded, so `Current.user` apps are unaffected. The README's zero-config claim for StandardId is now true.
+- `Rails.event` reserved metadata (`_tags`, `_source`) is still merged after `metadata_builder`, so builders never see it.
+
+### Fixed
+
+- **`before_checksum` hooks now run on batched writes.** `StandardAudit.batch` flushes with `insert_all!`, which never built a model, so hooks silently skipped every batched row. The flush now runs each buffered row through the hooks (per-hook isolation included) before checksumming, so batched rows get the same derived columns as `save!` and still verify.
+
+### Deprecated
+
+- **`standard_audit:add_checksums` generator** — the 0.2 → 0.3 upgrade path. It still works but warns; removal is planned.
+
 ## [0.11.1] - 2026-09-24
 
 ### Fixed

data/README.md

@@ -96,7 +96,38 @@ StandardAudit.record("orders.created",
 )
 ```
 
-When `actor` is omitted, it falls back to the configured `current_actor_resolver` (which reads from `Current.user` by default).
+When `actor` is omitted, it falls back to the configured `current_actor_resolver` (which reads `Current.account`, then `Current.user`, by default).
+
+#### Non-fatal writes: `raise: false`
+
+Where a missing audit row must never break the request — logging an
+authentication failure, say — pass `raise: false`. A failed write is logged,
+reported to `Rails.error` as handled (context
+`{ <audit_error_context_key> => event_type, source: "StandardAudit.record" }`),
+and `record` returns nil:
+
+```ruby
+StandardAudit.record("auth.token_invalid",
+  actor: token,
+  metadata: { error_code: "AUTH_001", path: request.path },
+  raise: false)
+```
+
+The default is `raise: true` (unchanged). In block form the option only
+governs the audit write; errors from your block always propagate.
+
+`raise: false` does not talk to Sentry (or any other tracker) itself. It calls
+`Rails.error.report`, so a swallowed failure reaches your error tracker only if
+something subscribes to `Rails.error`. `sentry-rails` registers that subscriber
+for you. With a hand-rolled Sentry setup, register one
+(`Rails.error.subscribe(...)`), or these failures show up only in the log.
+
+**Replace your host code with** `raise: false`. It supersedes the
+`AuditAuthFailure#record_auth_failure` rescue-and-report wrapper
+(sidekick-web, luminality-web, nutripod-web
+`app/controllers/concerns/audit_auth_failure.rb`); set
+`config.audit_error_context_key = :audit_event` to keep those apps' Sentry
+grouping key.
 
 ### ActiveSupport::Notifications
 
@@ -125,6 +156,67 @@ end
 
 This uses `ActiveSupport::Notifications.instrument` under the hood.
 
+### One write path, and `before_write`
+
+Every entry point — `StandardAudit.record` (plain and block form),
+`Auditable#record_audit`, `Operation#audit!`, the ActiveSupport::Notifications
+subscriber and the `Rails.event` subscriber — ends in the same write path.
+Actor/session/scope resolution, `metadata_builder`, `before_write`, record
+dereferencing, redaction, `StandardAudit.batch` and `async` therefore behave
+identically whichever way a row is written. (Before 0.12.0 the notifications
+subscriber carried its own copy: it ignored `batch`, and `metadata_builder`
+never ran on direct `record` calls.)
+
+`config.before_write` is the seam for host policy that must apply to every row:
+
+```ruby
+config.before_write = ->(entry) {
+  # entry: { event_type:, actor:, target:, scope:, metadata:,
+  #          request_id:, ip_address:, user_agent:, session_id: }
+  AuditMetadataPii.verify!(entry[:metadata]) if StandardAudit::Operation::Audit.verify?
+  if (surface = Current.audit_surface).present?
+    entry[:metadata] = entry[:metadata].merge(surface: surface)
+  end
+}
+```
+
+It runs after the `Current` resolvers and `metadata_builder`, and **before**
+dereferencing and `sensitive_keys` redaction, so anything it injects is still
+filtered. Mutate `entry` in place; the return value is ignored. Raising aborts
+the write: direct callers see the error, the subscribers rescue and report it.
+
+**Hooks run once per row, batched writes included.** `before_write` and
+`before_checksum` run for every row inside `StandardAudit.batch` too (at flush
+time for `before_checksum`). A hook that looks something up per actor (a role,
+a membership, a tenant) therefore runs one query per row and turns a batch into
+an N+1. Memoize those lookups for the unit of work, for example in a
+`CurrentAttributes` cache that resets with the request or job:
+
+```ruby
+class Current < ActiveSupport::CurrentAttributes
+  attribute :audit_actor_roles
+
+  def self.audit_role_for(actor)
+    self.audit_actor_roles ||= {}
+    audit_actor_roles[actor.to_global_id.to_s] ||= actor.audit_role
+  end
+end
+
+# actor_role: a column your app added to audit_logs
+config.before_checksum { |log| log.actor_role = Current.audit_role_for(log.actor) if log.actor }
+```
+
+**Replace your host code with** a `before_write`. It supersedes:
+
+- a hand-built job-side wrapper that runs a guard before `StandardAudit.record`
+  (fundbright-web `AuditWriting#record_audit!`);
+- an `audit!` override that runs a PII guard and injects metadata
+  (fundbright-web `ApplicationOperation#audit!`);
+- a `metadata_builder` whose injection (`engine_scope`) is documented as
+  missing direct writes (fundbright-web / luminality-web initializers) —
+  `metadata_builder` now applies to direct writes too, so no change is needed
+  beyond deleting the caveat.
+
 ## Model Concerns
 
 ### Auditable
@@ -284,6 +376,69 @@ outside `app/operations/`, which would otherwise always look orphaned.
 The registry can only see loaded classes, so the shared example calls
 `Rails.application.eager_load!` by default (`eager_load: false` to opt out).
 
+## Testing
+
+```ruby
+# spec/rails_helper.rb
+require "standard_audit/rspec"
+```
+
+This resets StandardAudit state before every example (so declare your
+configuration with `configure(baseline: true)`), and loads two helpers. Each is
+also loadable on its own: `standard_audit/rspec/matchers`,
+`standard_audit/rspec/baseline`.
+
+### `have_audited`
+
+```ruby
+expect { Orders::Create.call(order) }
+  .to have_audited("order.created")
+  .by(account)                    # a record, an RSpec matcher, or no arg = "any resolvable actor"
+  .on(order)                      # target, same forms
+  .within(organisation)           # scope, same forms
+  .with_metadata(total: 100, tags: include("vip"))  # subset; values may be matchers
+  .once                           # or .times(n); default "at least one"
+
+expect { noop }.not_to have_audited("order.created")
+```
+
+Only rows persisted during the block count. On failure it lists the rows that
+were written, so a wrong actor or metadata shows up directly.
+
+**Replace your host code with** `have_audited`. It supersedes hand-rolled
+helpers such as `expect_well_formed_audit(action)` (sidekick-web
+`spec/support/audit_log_coverage.rb`) — the equivalent is
+`have_audited(action).by.on` — and the
+`change(StandardAudit::AuditLog, :count)` + `AuditLog.last` pairs across the
+five apps' coverage specs.
+
+### `"a standard_audit baseline"`
+
+Guards that your configuration survives the per-example reset:
+
+```ruby
+RSpec.describe "StandardAudit configuration baseline" do
+  it_behaves_like "a standard_audit baseline",
+    subscriptions: [/\Astandard_id\./, /\Aauthorization\./],
+    settings: { retention_days: 1826, raise_on_audit_write_error: true, filter_nested_metadata: true },
+    catalogue: -> { AuditCatalogue::ACTIONS },
+    sensitive_keys: %i[source_payload],
+    sensitive_key_patterns: [/secret/i],
+    present: %i[metadata_builder before_write current_scope_resolver]
+end
+```
+
+It checks the baseline is registered, that each value holds, and that it is
+restored after a mutation plus `reset_configuration!`. Behaviour held in
+lambdas can only be checked for presence; keep an app-specific example for
+anything whose *result* matters.
+
+**Replace your host code with** the shared example. It supersedes the bulk of
+each app's `spec/initializers/standard_audit_baseline_spec.rb` (or
+`spec/config/…`). The `Current.account` / `Current.session&.id` resolver
+examples can go too once those overrides are deleted (they are the 0.12.0
+defaults).
+
 ## Configuration Reference
 
 Use `configure(baseline: true)` in your initializer. It remembers the block so
@@ -309,11 +464,12 @@ StandardAudit.configure(baseline: true) do |config|
   # -- Current Attribute Resolvers --
   # Fallbacks used when payload values are nil.
   # Designed to work with Rails Current attributes.
-  config.current_actor_resolver      = -> { Current.user }
+  # (Defaults shown in simplified form — each is respond_to?-guarded.)
+  config.current_actor_resolver      = -> { Current.account || Current.user }
   config.current_request_id_resolver = -> { Current.request_id }
   config.current_ip_address_resolver = -> { Current.ip_address }
   config.current_user_agent_resolver = -> { Current.user_agent }
-  config.current_session_id_resolver = -> { Current.session_id }
+  config.current_session_id_resolver = -> { Current.session&.id || Current.session_id }
 
   # -- Sensitive Data --
   # Keys automatically stripped from metadata. Matching is EXACT on the key
@@ -340,7 +496,7 @@ StandardAudit.configure(baseline: true) do |config|
   # 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.
+  # the audit write. Also run on batched writes, at flush time (since 0.12.0).
   config.before_checksum { |log| log.scope = MyApp.derive_scope(log) }
   config.before_checksum :backfill_scope   # an AuditLog instance method
 
@@ -362,9 +518,18 @@ StandardAudit.configure(baseline: true) do |config|
   }
 
   # -- Metadata Builder --
-  # Optional proc to transform metadata before storage.
+  # Optional proc to transform metadata before storage. Runs on EVERY write
+  # path (since 0.12.0 — previously only the two subscribers).
   config.metadata_builder = ->(metadata) { metadata.slice(:relevant_key) }
 
+  # -- Ambient scope --
+  # Fallback tenant when a write names none. See "Multi-Tenancy".
+  config.current_scope_resolver = -> { Current.organisation }
+
+  # -- before_write --
+  # Runs on every write path, before redaction. See "One write path".
+  config.before_write = ->(entry) { entry[:metadata] = entry[:metadata].merge("surface" => Current.surface) }
+
   # -- Async Processing --
   # Offload audit log creation to ActiveJob.
   config.async = false
@@ -386,7 +551,26 @@ end
 
 ### Default Current Attribute Resolvers
 
-Out of the box, StandardAudit reads from `Current` if it responds to the relevant method. This means if your app (or an auth library like StandardId) populates `Current.user`, `Current.request_id`, etc., audit logs automatically capture request context with zero configuration.
+Out of the box, StandardAudit reads from a top-level `Current` if it responds to the relevant method:
+
+| Column       | Default resolution (first non-nil wins)          |
+|--------------|--------------------------------------------------|
+| actor        | `Current.account`, then `Current.user`           |
+| session_id   | `Current.session&.id`, then `Current.session_id` |
+| request_id   | `Current.request_id`                             |
+| ip_address   | `Current.ip_address`                             |
+| user_agent   | `Current.user_agent`                             |
+
+The `account`/`session` pair is what StandardId's `Current` exposes, so a StandardId app gets actor and session attribution with zero configuration (since 0.12.0 — earlier versions read only `Current.user`/`Current.session_id`, which StandardId does not define). Apps following the Rails generator convention (`Current.user`) keep working unchanged.
+
+**Replace your host code with:** nothing. If your initializer carries
+
+```ruby
+config.current_actor_resolver = -> { Current.account }
+config.current_session_id_resolver = -> { Current.session&.id }
+```
+
+both lines are now the defaults and can be deleted.
 
 ## Query Interface
 
@@ -471,6 +655,39 @@ StandardAudit::AuditLog.for_scope(current_organisation)
 
 The scope is stored as a GlobalID string, so it works with any model class.
 
+### Ambient scope: `current_scope_resolver`
+
+When most writes happen inside a tenant-scoped request, resolve the scope from
+`Current` instead of threading it through every call:
+
+```ruby
+config.current_scope_resolver = -> { Current.channel || Current.organisation }
+```
+
+It is a *fallback*: an explicit `scope:` and a scope found by `scope_extractor`
+always win. It applies on every write path (direct `record`, `audit!`,
+`record_audit`, both subscribers; sync, async and batched). Default `nil`.
+
+`current_scope_resolver` is for scope that comes from **ambient request
+state** (`Current`). It takes no arguments and never sees the row. Scope that
+derives from the **row itself**, such as the organisation that owns the
+target, belongs in a `before_checksum` hook (or `before_write`), which receives
+the record or entry:
+
+```ruby
+config.before_checksum do |log|
+  log.scope ||= log.target.organisation if log.target.respond_to?(:organisation)
+end
+```
+
+**Replace your host code with** the one line above when your fallback reads
+`Current`. It supersedes a `scope_extractor` that falls back to `Current`
+(nutripod-web:
+`->(payload) { payload[:scope] || Current.channel || Current.organisation }`),
+which only ever covered the subscriber path. Keep `scope_extractor` for reading
+the payload and move the `Current` fallback here. Target-derived scope hooks
+stay as they are; since 0.12.0 they also run on the batched path.
+
 ## Async Processing
 
 For high-throughput applications, offload audit log creation to a background job:
@@ -509,6 +726,37 @@ GlobalID raises `ArgumentError`.
 StandardAudit::AuditLog.anonymize_actor!("gid://myapp/User/123")
 ```
 
+#### Anonymization and the checksum chain
+
+Anonymizing rewrites checksummed columns, so an anonymized row can no longer
+reproduce its own digest. Since 0.12.0 its stored `checksum` is left untouched
+(the rows after it still link to it) and, when the table has an
+`anonymized_at` column, the row is stamped. `verify_chain` then counts it under
+`redacted` instead of reporting a `digest_mismatch`:
+
+```ruby
+StandardAudit::AuditLog.verify_chain
+# => { valid: true, verified: 5576, recovered: 0, redacted: 1, failures: [] }
+```
+
+A redacted row's declared parent is still checked, so deleting the row before
+it is still reported as `missing_parent`. Reconcile a nonzero `redacted`
+against your erasure records: anyone who can write `anonymized_at` can hide an
+edit behind it.
+
+Existing installs add the column with:
+
+```bash
+rails generate standard_audit:add_anonymized_at
+rails db:migrate
+```
+
+(nullable, no default, idempotent; safe under strong_migrations). Without it,
+`anonymize_actor!` works exactly as before and anonymized rows keep failing
+`verify_chain` as `digest_mismatch`. Rows anonymized before the migration are
+not stamped retroactively — they are indistinguishable from tampered rows after
+the fact; stamp them by hand if your erasure log identifies them.
+
 ### Right to Access (Export)
 
 Export all audit data for a specific user:
@@ -584,9 +832,12 @@ own digest, so editing it invalidates the row.
 
 ```ruby
 result = StandardAudit::AuditLog.verify_chain
-# => { valid: true, verified: 5577, recovered: 0, failures: [] }
+# => { valid: true, verified: 5577, recovered: 0, redacted: 0, failures: [] }
 ```
 
+`redacted` counts rows anonymized by `anonymize_actor!` — see "Anonymization
+and the checksum chain".
+
 - `failures` carries `reason: :digest_mismatch` (the row's fields no longer
   produce its digest) or `reason: :missing_parent` (the row it was appended to
   is no longer in the log). Retention pruning does not trip `:missing_parent`:
@@ -638,6 +889,15 @@ verification — which is the point.
 re-signs rows from their current contents, so it attests only that a script ran.
 It is for rows that never had a checksum at all (pre-feature data).
 
+## Generators
+
+| Generator | Purpose |
+|-----------|---------|
+| `standard_audit:install` | `audit_logs` migration + initializer (new installs) |
+| `standard_audit:add_previous_checksum` | Adds `previous_checksum` (upgrading from < 0.8) |
+| `standard_audit:add_anonymized_at` | Adds `anonymized_at` (upgrading from < 0.12) |
+| `standard_audit:add_checksums` | **Deprecated** (0.12.0; to be removed). The 0.2 → 0.3 upgrade path; warns when run |
+
 ## Rake Tasks
 
 ```bash
@@ -740,10 +1000,10 @@ key you want on an audit row, while the value serialises with
 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):
+Records are dereferenced **after** `metadata_builder` (and `before_write`)
+run, so a builder that needs real attributes still gets the record. Since
+0.12.0 this holds on every write path, including direct `StandardAudit.record`
+calls:
 
 ```ruby
 config.metadata_builder = ->(metadata) {

data/app/models/standard_audit/audit_log.rb

@@ -95,12 +95,21 @@ module StandardAudit
     # `subject` may be a record, a GlobalID, or a GlobalID string
     # ("gid://app/User/1"). A string is parsed, never located, so erasure and
     # export still work after the subject's own row has been deleted.
+    #
+    # Anonymization rewrites CHECKSUM_FIELDS, so an anonymized row can no
+    # longer reproduce its own digest. Its stored `checksum` is deliberately
+    # left untouched, so the rows after it still link to it. When the host has
+    # the `anonymized_at` column (`standard_audit:add_anonymized_at`), the row
+    # is stamped and `verify_chain` counts it as `redacted` rather than as a
+    # `digest_mismatch` failure. Without the column, anonymization works
+    # exactly as before and such rows still fail verification.
     def self.anonymize_actor!(subject)
       gid = subject_gid_for(subject)
       logs = where("actor_gid = ? OR target_gid = ?", gid, gid)
       count = logs.count
 
       anonymizable_keys = StandardAudit.config.anonymizable_metadata_keys.map(&:to_s)
+      stamp = anonymization_column? ? Time.current : nil
 
       logs.find_each do |log|
         attrs = {
@@ -119,12 +128,26 @@ module StandardAudit
           attrs[:metadata] = cleaned_metadata
         end
 
+        attrs[:anonymized_at] = log.anonymized_at || stamp if stamp
+
         log.update_columns(attrs)
       end
 
       count
     end
 
+    # True when the table carries `anonymized_at` (the
+    # `standard_audit:add_anonymized_at` migration, or a 0.12+ install).
+    def self.anonymization_column?
+      column_names.include?("anonymized_at")
+    end
+
+    # True when this row's checksummed fields were rewritten by
+    # `anonymize_actor!`, so its digest is unverifiable by construction.
+    def anonymized?
+      has_attribute?(:anonymized_at) && anonymized_at.present?
+    end
+
     def self.export_for_actor(subject)
       gid = subject_gid_for(subject)
       logs = where("actor_gid = ? OR target_gid = ?", gid, gid).chronological
@@ -190,6 +213,20 @@ module StandardAudit
       OpenSSL::Digest::SHA256.hexdigest(canonical)
     end
 
+    # Runs the configured `before_checksum` hooks against a row that will be
+    # written by `insert_all!` (the `StandardAudit.batch` flush), so batched
+    # writes get the same derived columns as a `save!`. The row is loaded into
+    # an unsaved instance, the hooks run exactly as on `before_create`, and the
+    # resulting attributes are returned for checksumming. With no hooks
+    # registered the row is returned untouched and no model is built.
+    def self.apply_before_checksum_hooks(row)
+      return row if StandardAudit.config.before_checksum_hooks.blank?
+
+      log = new(row)
+      log.send(:run_before_checksum_hooks)
+      log.attributes.symbolize_keys.except(:checksum, :previous_checksum)
+    end
+
     # The checksum of the most recent row — the node a new row links to.
     def self.chain_tip_checksum
       order(created_at: :desc, id: :desc).limit(1).pick(:checksum)
@@ -204,9 +241,18 @@ module StandardAudit
     end
 
     # Verifies the integrity of the audit log. Returns a result hash with
-    # :valid (boolean), :verified (count), :recovered (count) and :failures
-    # (array of hashes carrying :id, :event_type, :created_at, :expected,
-    # :actual and :reason).
+    # :valid (boolean), :verified (count), :recovered (count), :redacted
+    # (count) and :failures (array of hashes carrying :id, :event_type,
+    # :created_at, :expected, :actual and :reason).
+    #
+    # A row stamped `anonymized_at` (GDPR erasure via `anonymize_actor!`) is
+    # counted in :redacted instead of being digest-checked: its checksummed
+    # fields were rewritten on purpose, so its digest cannot reproduce. Its
+    # stored checksum is unchanged, so the rest of the chain still links
+    # through it, and a declared parent is still checked for presence. Treat a
+    # nonzero :redacted as something to reconcile against your erasure
+    # records — anyone able to write `anonymized_at` can also hide an edit
+    # behind it.
     #
     # Records are processed in (created_at, id) order. Records without a
     # checksum (pre-feature data) reset the walk — the next checksummed record
@@ -253,6 +299,7 @@ module StandardAudit
       previous_checksum = nil
       verified = 0
       recovered = 0
+      redacted = 0
       failures = []
       window = []
       first_row = true
@@ -265,10 +312,20 @@ module StandardAudit
           next
         end
 
-        verified += 1
         declared = record.previous_checksum if declared_parents
 
-        if declared.present?
+        if record.anonymized?
+          redacted += 1
+          # The digest cannot be checked, but the parent it declares can.
+          if declared.present? && check_parents && !parent_present?(declared, window, relation)
+            if first_row
+              pruned_parents << declared
+            elsif !pruned_parents.include?(declared)
+              failures << chain_failure(record, expected: nil, reason: :missing_parent)
+            end
+          end
+        elsif declared.present?
+          verified += 1
           expected = record.compute_checksum_value(previous_checksum: declared)
 
           if record.checksum != expected
@@ -286,6 +343,7 @@ module StandardAudit
             end
           end
         else
+          verified += 1
           expected = record.compute_checksum_value(previous_checksum: previous_checksum)
 
           if record.checksum == expected
@@ -303,7 +361,7 @@ module StandardAudit
         window.shift if window.size > recovery_window
       end
 
-      { valid: failures.empty?, verified: verified, recovered: recovered, failures: failures }
+      { valid: failures.empty?, verified: verified, recovered: recovered, redacted: redacted, failures: failures }
     end
 
     # Records, for every row that does not already carry one, the parent digest
@@ -539,7 +597,13 @@ module StandardAudit
         # 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)
+        if Rails.respond_to?(:error) && Rails.error
+          Rails.error.report(
+            e,
+            handled: true,
+            context: { StandardAudit.config.audit_error_context_key => event_type }
+          )
+        end
         nil
       end
     end

data/lib/generators/standard_audit/add_anonymized_at/add_anonymized_at_generator.rb

@@ -0,0 +1,20 @@
+module StandardAudit
+  module Generators
+    # Adds `audit_logs.anonymized_at` (0.12.0). With it, rows erased by
+    # `AuditLog.anonymize_actor!` are reported by `verify_chain` as `redacted`
+    # rather than as `digest_mismatch` failures.
+    class AddAnonymizedAtGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def copy_migration
+        migration_template "add_anonymized_at_to_audit_logs.rb.erb",
+          "db/migrate/add_anonymized_at_to_audit_logs.rb"
+      end
+    end
+  end
+end

data/lib/generators/standard_audit/add_anonymized_at/templates/add_anonymized_at_to_audit_logs.rb.erb

@@ -0,0 +1,25 @@
+class AddAnonymizedAtToAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  # A nullable column with no default: a metadata-only change on PostgreSQL,
+  # no table rewrite, nothing for StrongMigrations to object to. Idempotent,
+  # so it is safe on a host that already has the column (a 0.12+ install).
+  #
+  # Rows anonymized BEFORE this migration keep a NULL stamp and still fail
+  # `verify_chain` as `digest_mismatch`; there is no way to tell them apart
+  # from tampered rows after the fact. If your erasure records identify them,
+  # stamp them by hand (`update_columns(anonymized_at: ...)`).
+  #
+  # Explicit up/down with `if_not_exists:` / `if_exists:` rather than an early
+  # `return if column_exists?` inside `change`: that return also runs on
+  # rollback, which then deletes the schema_migrations row and silently leaves
+  # the column behind.
+  #
+  # Rolling back drops the column even if it came from your create_audit_logs
+  # migration (0.12+ installs). Those installs do not need this migration.
+  def up
+    add_column :audit_logs, :anonymized_at, :datetime, if_not_exists: true
+  end
+
+  def down
+    remove_column :audit_logs, :anonymized_at, if_exists: true
+  end
+end

data/lib/generators/standard_audit/add_checksums/add_checksums_generator.rb

@@ -1,13 +1,27 @@
 module StandardAudit
   module Generators
+    # DEPRECATED (0.12.0); scheduled for removal. This is the 0.2 -> 0.3
+    # upgrade path that added the `checksum` column. Every install since 0.3
+    # creates the column via `standard_audit:install`, and no known host still
+    # needs it. Run `standard_audit:add_previous_checksum` on hosts that
+    # predate 0.8 instead.
     class AddChecksumsGenerator < Rails::Generators::Base
       include Rails::Generators::Migration
       source_root File.expand_path("templates", __dir__)
 
+      DEPRECATION_MESSAGE = "standard_audit:add_checksums is deprecated and will be removed in a " \
+                            "future release. It only upgrades pre-0.3 installs; the install " \
+                            "generator has created the checksum column since 0.3.".freeze
+
       def self.next_migration_number(dirname)
         Time.now.utc.strftime("%Y%m%d%H%M%S")
       end
 
+      def warn_deprecated
+        say_status :deprecated, DEPRECATION_MESSAGE, :yellow
+        warn "[StandardAudit] DEPRECATION: #{DEPRECATION_MESSAGE}"
+      end
+
       def copy_migration
         migration_template "add_checksum_to_audit_logs.rb.erb", "db/migrate/add_checksum_to_audit_logs.rb"
       end