standard_audit 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b89dc74bd119d2e0f1ff5080cef706439e68b61c79d2a6b653fcd5a74e265ae1
-  data.tar.gz: 86686ea3bb611a13e8c8947ef3e0b63aad63eb47bfa1e48b16abba377a426f7f
+  metadata.gz: 80719c54fd8a1d3859f52741cfc4a478ec670114ad5ab025b1b9b14a10a80625
+  data.tar.gz: d5baa91d4e29844e0e0c375e0ef6c9b3cd4f2d6eba0284696911891270f3befa
 SHA512:
-  metadata.gz: b06e7ee9a3b5d79191cb47a532cf81efb95e3bb722015540be79ce4bb9412ab13b8e69985a66d368c8dcdfb099f34f1ca1d3f0d894bfc90cc409615782dde921
-  data.tar.gz: bb1e9316eba648a8d238becb75d33f705b82f509310e8c3e0d562656accac2b44339e49551e026ae0357bf57dda8fe8251f6f1d6c7df655777d5b157c3d17b0a
+  metadata.gz: 3fc6d5267408dd0858b0cecac9e449c00b6ef6e75b12cb9cb74167634769cd09f95fa51805a948f9a20e100b7bbd43237f473f4508d211a8c66293c0af2bbe3f
+  data.tar.gz: cdb5c7130f54d124da4e2b02586e510b5a75693c729d30d495403d4e948b7d6fcc81b640cb241a138292d452ebb5a52f0d84a6a0f178e8ecb982d7a209c179ea

data/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`rake standard_audit:anonymize_actor[gid]` and `standard_audit:export_actor[gid]` no longer raise `NoMethodError`.** The tasks passed the GlobalID string straight into `AuditLog.anonymize_actor!` / `export_for_actor`, which called `to_global_id` on it. Both methods now accept a record, a `GlobalID`, or a GlobalID string. A string is parsed, not located, so erasure works after the subject's row has been deleted; an invalid string raises `ArgumentError`. What gets anonymized is unchanged.
+- **`rake standard_audit:cleanup` no longer deletes logs older than 90 days when `retention_days` is nil.** nil means keep forever, but the task fell back to a hard-coded 90. `cleanup` and `archive` (which always defaulted to 90) now take the days argument, else `config.retention_days`, else abort with a message saying how to set one.
+- **`cleanup`/`archive` reject a days value that is not a positive integer.** `cleanup[abc]` used to become `0` days, i.e. delete every row. `0`, negatives and non-numeric values now abort. `StandardAudit::CleanupJob` is unchanged.
+- **`StandardAudit::Subscriber` and `StandardAudit::EventSubscriber` report swallowed errors to `Rails.error`.** A failed audit write was only logged, so it never reached error tracking. It is now also reported with `handled: true` and context `{ <config.audit_error_context_key> => event_name, subscriber: <class name> }`. The log line is kept.
+
 ## [0.11.0] - 2026-07-31
 
 ### Security

data/README.md

@@ -96,7 +96,32 @@ 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.
+
+**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 +150,46 @@ 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.
+
+**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 +349,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 +437,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 +469,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 +491,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 +524,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 +628,28 @@ 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`.
+
+**Replace your host code with** the one line above. 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, move the `Current` fallback here;
+- a `before_checksum` hook that back-fills `log.scope` from `Current`
+  (sidekick-web), which before 0.12.0 never ran on the batched path.
+
 ## Async Processing
 
 For high-throughput applications, offload audit log creation to a background job:
@@ -499,6 +678,47 @@ This:
 - Clears `ip_address`, `user_agent`, and `session_id`
 - Removes metadata keys listed in `anonymizable_metadata_keys`
 
+Both `anonymize_actor!` and `export_for_actor` accept the subject as a record,
+a `GlobalID`, or a GlobalID string (`"gid://myapp/User/123"`). A string is
+parsed, never located, so erasure still works after the user's own row has been
+deleted — the usual order for an erasure request. Anything that is not a valid
+GlobalID raises `ArgumentError`.
+
+```ruby
+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:
@@ -525,7 +745,9 @@ STANDARD_AUDIT_RETENTION_DAYS=365   # keep 365 days
 ```
 
 Infinite retention (the default) is the compliance-safe behavior: nothing is
-ever auto-deleted. For financial/legal domains that is usually what you want;
+ever auto-deleted. The `standard_audit:cleanup` and `standard_audit:archive`
+rake tasks respect this: with no days argument and a nil `retention_days` they
+abort rather than fall back to a default window. For financial/legal domains that is usually what you want;
 enabling a finite window is a deliberate decision.
 
 ### Production retention warning (StandardHealth)
@@ -572,9 +794,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`:
@@ -626,6 +851,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
@@ -635,10 +869,12 @@ rake standard_audit:verify
 # Record the parent digest each existing row was signed against
 rake standard_audit:relink_checksums
 
-# Delete logs older than N days (default: retention_days config or 90)
+# Delete logs older than N days
 rake standard_audit:cleanup[180]
+# ...or older than config.retention_days
+rake standard_audit:cleanup
 
-# Archive old logs to a JSON file before deleting
+# Archive old logs to a JSON file before deleting (same days rules)
 rake standard_audit:archive[90,audit_backup.json]
 
 # Show statistics
@@ -651,6 +887,15 @@ rake "standard_audit:anonymize_actor[gid://myapp/User/123]"
 rake "standard_audit:export_actor[gid://myapp/User/123,export.json]"
 ```
 
+`cleanup` and `archive` take the window from the days argument, else
+`config.retention_days`; if neither is set they abort (a nil `retention_days`
+means keep forever, so there is no implicit 90-day default). Days must be a
+positive integer — `0`, negatives and non-numeric values abort instead of
+deleting everything.
+
+`anonymize_actor` and `export_actor` take a GlobalID string and work even after
+the user record has been deleted.
+
 ## Database Support
 
 The migration uses `json` column type by default, which works across:
@@ -717,10 +962,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

@@ -92,12 +92,24 @@ module StandardAudit
 
     # -- GDPR methods --
 
-    def self.anonymize_actor!(record)
-      gid = record.to_global_id.to_s
+    # `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 = {
@@ -116,14 +128,28 @@ module StandardAudit
           attrs[:metadata] = cleaned_metadata
         end
 
+        attrs[:anonymized_at] = log.anonymized_at || stamp if stamp
+
         log.update_columns(attrs)
       end
 
       count
     end
 
-    def self.export_for_actor(record)
-      gid = record.to_global_id.to_s
+    # 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
 
       records = logs.map do |log|
@@ -149,6 +175,22 @@ module StandardAudit
       }
     end
 
+    # Normalises a GDPR subject to its GlobalID string. Parses rather than
+    # locates, so it works when the subject's row no longer exists.
+    def self.subject_gid_for(subject)
+      gid =
+        case subject
+        when GlobalID then subject
+        when String then GlobalID.parse(subject)
+        else subject.respond_to?(:to_global_id) ? subject.to_global_id : nil
+        end
+
+      raise ArgumentError, "expected a record, a GlobalID, or a GlobalID string (gid://app/Model/id), got #{subject.inspect}" unless gid
+
+      gid.to_s
+    end
+    private_class_method :subject_gid_for
+
     # Recomputes the checksum from the record's current field values and the
     # given previous checksum. Useful for verification without saving.
     def compute_checksum_value(previous_checksum: nil)
@@ -171,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)
@@ -185,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
@@ -234,6 +299,7 @@ module StandardAudit
       previous_checksum = nil
       verified = 0
       recovered = 0
+      redacted = 0
       failures = []
       window = []
       first_row = true
@@ -246,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
@@ -267,6 +343,7 @@ module StandardAudit
             end
           end
         else
+          verified += 1
           expected = record.compute_checksum_value(previous_checksum: previous_checksum)
 
           if record.checksum == expected
@@ -284,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

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,15 @@
+class AddAnonymizedAtToAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    # 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: ...)`).
+    return if column_exists?(:audit_logs, :anonymized_at)
+
+    add_column :audit_logs, :anonymized_at, :datetime
+  end
+end