standard_audit 0.13.3 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77f38f95622eab13dc70d4376ad9694a3bbb03d3d54f5f2c43f63012e041ea23
-  data.tar.gz: 5d68228d9da02a23808db8cc2588dc358df1dc7f7a82d86da4447d98038f6411
+  metadata.gz: 05062631e84ab99965b101b5381535c345929c0282cb4c0ca645f2636a5d42b3
+  data.tar.gz: 9acf2c4b4f8059ca4290655e065ce2e0fbd093a5747b87658ea426ec2b6d32f6
 SHA512:
-  metadata.gz: c5ca114c4894594f1e0de803d0d0e207bd308f887e130237af3d967a4ed33bc476ac72f28b1cff8b83af5f2d5c56e158542a917c560680c96e3f686ec339c6ec
-  data.tar.gz: 991e7cbfd6c21c73f54bc1bc1ed64aa1df8faaa2a6d44dfdf75222ab79911eb462de275ca086d74ef72108db70bad6df1f8c9f65fab9ec7ea115c0bb5bb99f1e
+  metadata.gz: 48c43519e8dfff7d04ea521ca6700cd85b3ac9096f89288b4c2bdc3a94a1b51d1c941fa6c9f7278e06672e9f1318805b0d0c34e0da282b65fcd85e67cf07ee0f
+  data.tar.gz: 59d4d4dbba01407436d16c6c6007b09b63ac0024f58c7f44d8880dac7f46f38baf279c5142264e2e03a150fec1ca1dcba0ce538d8105fa2c96a0c2fb29979cc2

data/CHANGELOG.md

@@ -7,6 +7,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-10-22
+
+### Added
+
+- **`config.retention_days = :indefinite`** (or
+  `STANDARD_AUDIT_RETENTION_DAYS=indefinite`) records keeping audit rows
+  forever as a decision. Rows are kept exactly as with `nil`, but the production
+  advisory `StandardAudit::Checks::Retention` reports `ok` with
+  `retention: "indefinite"` instead of warning. Hosts that set a huge day count
+  to quiet the advisory (nutripod-web uses 36,500) should switch: a day count is
+  a window, and `CleanupJob` acts on it. `CleanupJob` does nothing for
+  `:indefinite`, and `standard_audit:cleanup`/`:archive` abort unless given days.
+  New readers: `Configuration#retention_window_days`, `#retention_indefinite?`
+  and `#retention_misconfigured?`; `CleanupJob` warns and deletes nothing for a
+  value that is neither a positive Integer nor `:indefinite` (e.g. `"90"`).
+- **`standard_audit/rspec` fails loudly when configuration would be lost.**
+  A `before(:suite)` hook calls the new `StandardAudit.verify_baseline_configuration!`,
+  which raises `StandardAudit::BaselineConfigurationError`, naming each call
+  site, if any plain `StandardAudit.configure` (without `baseline: true`) ran
+  at boot. The per-example reset replays only the baseline block, so those
+  settings, `before_checksum` hooks included, disappeared from the second
+  example on, and the specs that would have noticed passed vacuously.
+  `configure` calls inside an example are unaffected. **Upgrading:** move any
+  boot-time plain `configure` into the single `configure(baseline: true)` block.
+- **`StandardAudit::AuthFailure`** records authentication failures: requests
+  refused before any operation runs. Include
+  `StandardAudit::AuthFailure::Controller` for a private
+  `record_auth_failure(event_type, error_code, actor: nil, **extra)`, or call
+  `StandardAudit::AuthFailure.record(..., request:/path:)` outside a controller.
+  It writes allow-listed metadata (`error_code`, `path`, `method`, plus the
+  caller's extras), the request id/IP/user agent as columns (user agent
+  truncated to 1024 characters), drops a non-GlobalID actor, and never raises,
+  including for a request whose forwarded-IP headers trip Rails' spoofing
+  check (it falls back to Rack's `request.ip`, which ignores `Client-IP`).
+  `config.log_auth_failures = true` (default `false`) adds a structured warn
+  line whose extras pass through `MetadataFilter` like the row's; if the log
+  line fails, the row is still written. It replaces the hand-copied
+  `AuditAuthFailure` concerns in nutripod-web, luminality-web and sidekick-web.
+- **`"standard_audit catalogue coverage"`** shared example
+  (`require "standard_audit/rspec/coverage"`): every catalogue action must be
+  asserted by a positive literal `have_audited("…")` somewhere in the suite,
+  apart from an explicit `pending:` list that may only shrink. It is a static
+  scan of the spec files, so it behaves the same under `parallel_rspec` and in
+  partial runs. Commented-out lines don't count. Predicates:
+  `StandardAudit::RSpec::Coverage.covered_actions` and `.report`.
+  It replaces the hand-synced `CATALOGUE_ACTIONS` copies in the
+  apps' `spec/support/audit_log_coverage.rb`.
+
+### Fixed
+
+- A logger that raises no longer turns a swallowed audit failure into a raised
+  one. `report_write_error` and `report_error`'s own fallback both guard their
+  `Rails.logger` call, so `record(raise: false)`, the subscribers and
+  `AuthFailure.record` keep their never-raise guarantee.
+
+### Changed
+
+- **`config.filter_nested_metadata` now defaults to `true`.** Redaction
+  descends into nested Hashes (and Hashes inside Arrays) unless a host turns it
+  off, so `metadata: { stripe: { client_secret: … } }` is no longer written
+  intact by default. Every rarebit-one consumer already set it to true, so for
+  them nothing changes. A host that relied on the old default will have nested
+  sensitive keys redacted from now on; to keep the old behaviour, set
+  `config.filter_nested_metadata = false` after a dry run
+  (`rake "standard_audit:sensitive_keys:dry_run[...]" NESTED=1`).
+  `raise_on_audit_write_error` keeps its `false` default: three of the five
+  consumers report and swallow failed audit writes on purpose.
+- The README configuration reference and the install generator's commented
+  `scope_extractor` example show the record guard the 0.13.3 default has, so a
+  host copying them no longer reintroduces FUNDBRIGHT-WEB-41.
+
 ## [0.13.3] - 2026-10-21
 
 ### Fixed

data/README.md

@@ -258,6 +258,43 @@ config.before_checksum { |log| log.actor_role = Current.audit_role_for(log.actor
   `metadata_builder` now applies to direct writes too, so no change is needed
   beyond deleting the caveat.
 
+## Authentication Failures
+
+A request refused before any operation runs (an invalid or revoked token, a
+missing scope, a locked account) never reaches the operation audit contract, so
+the controller records it. `StandardAudit::AuthFailure` is that recorder:
+
+```ruby
+class Api::BaseController < ActionController::API
+  include StandardAudit::AuthFailure::Controller
+
+  rescue_from InvalidToken do
+    record_auth_failure("auth.token_invalid", "AUTH_001")
+    render json: { error: "AUTH_001" }, status: :unauthorized
+  end
+end
+
+# Outside a controller, with or without a request:
+StandardAudit::AuthFailure.record("auth.social_denied", "AUTH_009", request: request)
+StandardAudit::AuthFailure.record("auth.social_denied", "AUTH_009", path: "/auth/callback", actor: account)
+```
+
+- **Metadata is an allow-list:** `error_code`, `path`, `method` (with a
+  request), plus exactly the extra keywords you pass. Nothing comes from params,
+  headers or the exception. The rejected credential is in scope on this path, so
+  never pass it; `sensitive_keys` is only the backstop.
+- **Request context goes in the columns:** with `request:`, the request id, IP
+  and user agent are written explicitly, and the user agent is truncated to
+  1024 characters so an over-long header can't cost you the row.
+- **The actor** is usually nil. A value that isn't GlobalID-able is dropped.
+- **It never raises** (`raise: false`), so an audit failure can't turn a 401
+  into a 500. Failures go to `config.error_reporter`.
+- **`config.log_auth_failures = true`** also emits one structured
+  `Rails.logger.warn` line per failure, for alerting off the log stream.
+
+These are not operation actions, so leave them out of an `orphans_within:
+:catalogue` check (or out of the catalogue).
+
 ## Model Concerns
 
 ### Auditable
@@ -488,6 +525,38 @@ each app's `spec/initializers/standard_audit_baseline_spec.rb` (or
 examples can go too once those overrides are deleted (they are the 0.12.0
 defaults).
 
+### `"standard_audit catalogue coverage"`
+
+Checks that every catalogue action is asserted by a positive
+`have_audited("…")` somewhere in the suite:
+
+```ruby
+require "standard_audit/rspec/coverage"
+
+RSpec.describe "Audit catalogue coverage" do
+  it_behaves_like "standard_audit catalogue coverage",
+    catalogue: -> { AuditCatalogue::OPERATION_ACTIONS },  # default: config.audit_catalogue
+    pending: %w[grant.pass_scheduled]                     # catalogued, no writer yet
+end
+```
+
+It fails on a catalogue action with no assertion, a `pending:` action that
+isn't in the catalogue, and a `pending:` action that has gained an assertion
+(so the list only shrinks).
+
+It scans the spec files' text rather than tallying matches at runtime, so it
+gives the same answer under `parallel_rspec`, in a single-file run and in the
+full suite. Only literal, positive assertions count: `.to have_audited("x")`,
+`.to(have_audited("x"))` and `.and have_audited("x")`. `not_to`, and names
+built at runtime, don't. Their example still has to pass, so in a green suite an
+assertion means the row was written.
+
+**Replace your host code with** the shared example: the hand-copied
+`CATALOGUE_ACTIONS` / `PENDING_FEATURE_ACTIONS` in
+`spec/support/audit_log_coverage.rb`, the spec that kept them in sync with the
+catalogue, and the `change(…).by(1)` + `expect_well_formed_log` pairs, which
+`have_audited("x").by.on.once` replaces.
+
 ## Configuration Reference
 
 Use `configure(baseline: true)` in your initializer. It remembers the block so
@@ -508,7 +577,13 @@ StandardAudit.configure(baseline: true) do |config|
   # Defaults shown below.
   config.actor_extractor  = ->(payload) { payload[:actor] }
   config.target_extractor = ->(payload) { payload[:target] }
-  config.scope_extractor  = ->(payload) { payload[:scope] } # default keeps it only if it responds to to_global_id
+  # Only a record can be a scope; the default drops anything else (e.g. the
+  # Symbol standard_id publishes as `scope:`) so it falls back to
+  # `current_scope_resolver`. Keep that guard in a custom extractor.
+  config.scope_extractor  = ->(payload) {
+    scope = payload[:scope]
+    scope if scope.respond_to?(:to_global_id)
+  }
 
   # -- Current Attribute Resolvers --
   # Fallbacks used when payload values are nil.
@@ -598,7 +673,8 @@ StandardAudit.configure(baseline: true) do |config|
 
   # -- 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.
+  # to override per app. Leave unset for infinite retention, or set
+  # :indefinite to record keeping rows forever as a decision.
   config.retention_days = 90
 
   # -- Checksum cutover --
@@ -840,10 +916,19 @@ 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
+STANDARD_AUDIT_RETENTION_DAYS=365          # keep 365 days
+STANDARD_AUDIT_RETENTION_DAYS=indefinite   # keep forever, on purpose
 # unset / blank / 0 / negative / non-numeric => nil => infinite retention
 ```
 
+`nil` and `:indefinite` both keep every row. The difference is intent: `nil`
+means nobody has decided, so the production advisory below warns, while
+`config.retention_days = :indefinite` records a deliberate keep-forever policy
+and the advisory reports ok. Don't set a huge day count (say 36,500) to silence
+the advisory; that is a window, so `CleanupJob` would one day act on it.
+`CleanupJob` does nothing for either, and the cleanup and archive rake tasks
+abort unless you pass days explicitly.
+
 Infinite retention (the default) is the compliance-safe behavior: nothing is
 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
@@ -866,7 +951,8 @@ 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`,
+the check returns `:warn`. With `:indefinite` it returns `:ok` with
+`retention: "indefinite"`. 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`.
@@ -1138,7 +1224,7 @@ canonical-checksum cutover do not depend on key order; earlier rows may — see
 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
+config.filter_nested_metadata = true                # the default since 0.14.0
 ```
 
 `sensitive_keys` matches **exactly** on the key name. There is deliberately no
@@ -1153,12 +1239,13 @@ bin/rails "standard_audit:sensitive_keys:dry_run[secret]"   # NESTED=1 to model
 ```
 
 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.
+would be kept, and nested matches that would survive if
+`filter_nested_metadata` were 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.
+Nested metadata is redacted by default (`filter_nested_metadata`, true since
+0.14.0): `metadata: { stripe: { client_secret: ... } }` has `client_secret`
+stripped on both write paths. Before 0.14.0 the default was false and such
+values were written intact.
 
 ### Records in metadata
 

data/app/jobs/standard_audit/cleanup_job.rb

@@ -3,7 +3,15 @@ module StandardAudit
     queue_as { StandardAudit.config.queue_name }
 
     def perform
-      days = StandardAudit.config.retention_days
+      config = StandardAudit.config
+      if config.retention_misconfigured?
+        Rails.logger.warn("[StandardAudit] CleanupJob skipped: retention_days is #{config.retention_days.inspect}, " \
+                          "not a positive Integer or :indefinite, so no audit logs were deleted")
+        return
+      end
+
+      # nil and :indefinite both mean keep forever.
+      days = config.retention_window_days
       return unless days
 
       cutoff = days.days.ago

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

@@ -19,7 +19,10 @@ StandardAudit.configure(baseline: true) do |config|
   # config.target_extractor = ->(payload) { payload[:target] }
 
   # Scope extractor from notification payload
-  # config.scope_extractor = ->(payload) { payload[:scope] }
+  # config.scope_extractor = ->(payload) {
+  #   scope = payload[:scope]
+  #   scope if scope.respond_to?(:to_global_id) # only a record can be a scope
+  # }
 
   # Multi-tenancy: include StandardAudit::AuditScope in your tenant model
   # to add a scoped_audit_logs association.
@@ -56,10 +59,10 @@ StandardAudit.configure(baseline: true) do |config|
   # 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
+  # Redaction descends into nested Hashes by default (since 0.14.0), so
+  # `metadata: { stripe: { client_secret: ... } }` is redacted. Turning it off
+  # writes nested secrets intact; run the dry run first if you do.
+  # config.filter_nested_metadata = false
 
   # Run audit log creation in background job
   # config.async = false
@@ -71,7 +74,9 @@ StandardAudit.configure(baseline: true) do |config|
   # GDPR: metadata keys to strip on anonymization
   # config.anonymizable_metadata_keys = %i[email name ip_address]
 
-  # Data retention (schedule StandardAudit::CleanupJob to enforce)
+  # Data retention (schedule StandardAudit::CleanupJob to enforce). nil keeps
+  # rows forever and the production health advisory warns; :indefinite keeps
+  # them forever as a recorded decision.
   # config.retention_days = nil
 
   # -- Write-time hooks -------------------------------------------------------

data/lib/standard_audit/auth_failure.rb

@@ -0,0 +1,136 @@
+module StandardAudit
+  # Records an authentication failure: a request refused before any operation
+  # runs (an invalid or revoked token, a missing scope, a locked account). No
+  # operation executes, so the operation audit contract (`audits` / `audit!`,
+  # the catalogue) never sees these. The controller records them directly.
+  # Extracted from three host copies (nutripod-web, luminality-web,
+  # sidekick-web) of the same concern.
+  #
+  # In a controller, include the concern and call the private helper from your
+  # `rescue_from` handlers:
+  #
+  #   class Api::BaseController < ActionController::API
+  #     include StandardAudit::AuthFailure::Controller
+  #   end
+  #
+  #   record_auth_failure("auth.token_invalid", "AUTH_001")
+  #   record_auth_failure("auth.token_revoked", "AUTH_003", actor: session)
+  #
+  # Outside a controller (a hook that has the request but no controller of
+  # yours), call the module directly:
+  #
+  #   StandardAudit::AuthFailure.record("auth.social_denied", "AUTH_009", request: request)
+  #   StandardAudit::AuthFailure.record("auth.social_denied", "AUTH_009", path: "/auth/callback")
+  #
+  # == What lands in the row
+  #
+  # Metadata is an allow-list: `error_code`, `path`, `method` (when a request
+  # is given), plus exactly the extra keywords the caller passes. Nothing is
+  # read from params, headers or the exception message. This is the one path
+  # where a live credential (the rejected token) is guaranteed to be in scope,
+  # and audit rows are append-only, so callers must never pass it.
+  # `sensitive_keys` redaction is the backstop, not the control.
+  #
+  # With a `request:`, the request id, IP and user agent go into the row's
+  # columns explicitly, rather than through the Current resolvers, and the user
+  # agent is truncated to USER_AGENT_LIMIT so an over-long header cannot make
+  # the insert fail and cost the row.
+  #
+  # The actor is usually nil (authentication failed). A value that is not
+  # GlobalID-able (a String, an id) is dropped rather than written.
+  #
+  # The write never raises (`raise: false`): the request is already being
+  # refused, and an audit failure must not turn a 401 into a 500. Failed writes
+  # go to `config.error_reporter` like any other non-raising record.
+  #
+  # With `config.log_auth_failures = true` each failure also emits one
+  # structured `Rails.logger.warn` line, for alerting off the log stream. Its
+  # extras pass through MetadataFilter like the row's.
+  module AuthFailure
+    # Hosts commonly cap `audit_logs.user_agent` at 1024 characters.
+    USER_AGENT_LIMIT = 1024
+
+    module_function
+
+    # @return [StandardAudit::AuditLog, nil] the row, or nil when the write
+    #   failed or auditing is disabled.
+    def record(event_type, error_code, actor: nil, request: nil, path: nil, **extra_metadata)
+      audit_actor = actor.respond_to?(:to_global_id) ? actor : nil
+      path ||= request&.path
+      ip = request && client_ip(request)
+
+      safely_log(event_type, error_code, actor, audit_actor, path, ip, extra_metadata) if StandardAudit.config.log_auth_failures
+
+      metadata = {
+        "error_code" => error_code,
+        "path" => path,
+        "method" => request&.request_method,
+        **extra_metadata.transform_keys(&:to_s)
+      }.compact
+
+      context = {}
+      if request
+        context[:request_id] = request.request_id
+        context[:ip_address] = ip
+        context[:user_agent] = request.user_agent&.slice(0, USER_AGENT_LIMIT)
+      end
+
+      StandardAudit.record(event_type, actor: audit_actor, metadata: metadata, raise: false, **context.compact)
+    rescue => e
+      # `raise: false` only covers the write. Building the row's inputs and the
+      # log line happens first, and must not turn the refusal into a 500 either.
+      StandardAudit.report_write_error(e, event_type, source: "StandardAudit::AuthFailure")
+      nil
+    end
+
+    # `request.remote_ip` raises ActionDispatch::RemoteIp::IpSpoofAttackError
+    # for a request whose Client-IP and X-Forwarded-For disagree (with
+    # `check_ip_spoofing`, the default). A client controls both headers, so
+    # fall back to Rack's `request.ip`, which ignores Client-IP, rather than
+    # fail.
+    def client_ip(request)
+      request.remote_ip
+    rescue => e
+      raise unless e.class.name == "ActionDispatch::RemoteIp::IpSpoofAttackError"
+
+      request.ip
+    end
+    private_class_method :client_ip
+
+    # The log line is secondary: if it fails, report that and still write the
+    # row, which is the record that matters.
+    def safely_log(event_type, *args)
+      log(event_type, *args)
+    rescue => e
+      StandardAudit.report_write_error(e, event_type, source: "StandardAudit::AuthFailure log line")
+    end
+    private_class_method :safely_log
+
+    # The extras pass through MetadataFilter first, so the log line gets the
+    # same `sensitive_keys` backstop as the row.
+    def log(event_type, error_code, actor, audit_actor, path, ip, extra_metadata)
+      return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      Rails.logger.warn({
+        event: event_type,
+        error_code: error_code,
+        path: path,
+        ip: ip,
+        actor: audit_actor ? audit_actor.to_global_id.to_s : actor&.to_s,
+        timestamp: Time.now.utc.iso8601,
+        **StandardAudit::MetadataFilter.call(extra_metadata).to_h.transform_keys(&:to_sym)
+      }.compact)
+    end
+    private_class_method :log
+
+    # The controller concern. `record_auth_failure` is private, so it never
+    # becomes an action.
+    module Controller
+      private
+
+      def record_auth_failure(event_type, error_code, actor: nil, **extra_metadata)
+        StandardAudit::AuthFailure.record(event_type, error_code, actor: actor, request: request, **extra_metadata)
+      end
+    end
+  end
+end

data/lib/standard_audit/checks/retention.rb

@@ -33,15 +33,18 @@ module StandardAudit
           return { status: :ok, detail: "retention advisory only runs on production deployments" }
         end
 
-        days = StandardAudit.config.retention_days
+        config = StandardAudit.config
+        return { status: :ok, retention: "indefinite" } if config.retention_indefinite?
+
+        days = config.retention_window_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."
+                   "StandardAudit::CleanupJob, or record indefinite retention as a deliberate " \
+                   "compliance decision with config.retention_days = :indefinite."
         }
       end
 

data/lib/standard_audit/configuration.rb

@@ -1,5 +1,8 @@
 module StandardAudit
   class Configuration
+    # `config.retention_days = :indefinite`: keep audit rows forever, on purpose.
+    INDEFINITE_RETENTION = :indefinite
+
     attr_accessor :async, :queue_name, :enabled,
                   :actor_extractor, :target_extractor, :scope_extractor,
                   :current_actor_resolver, :current_request_id_resolver,
@@ -7,7 +10,7 @@ module StandardAudit
                   :current_session_id_resolver, :current_scope_resolver,
                   :before_write,
                   :sensitive_keys, :sensitive_key_patterns,
-                  :sensitive_key_exceptions, :filter_nested_metadata,
+                  :sensitive_key_exceptions, :filter_nested_metadata, :log_auth_failures,
                   :dereference_record_metadata,
                   :metadata_builder, :before_checksum_hooks,
                   :anonymizable_metadata_keys, :retention_days,
@@ -105,18 +108,27 @@ module StandardAudit
       # `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
+      # When true (the default since 0.14.0), redaction descends into nested
+      # Hashes (and Hashes inside Arrays), so
+      # `metadata: { stripe: { client_secret: … } }` is caught. Reserved keys
+      # are never descended into. Before 0.14.0 it defaulted to false, which
+      # wrote nested secrets intact; every app in the estate had already
+      # turned it on. Set false only to keep pre-0.14.0 rows comparable, after
+      # a dry run (`rake standard_audit:sensitive_keys:dry_run`).
+      @filter_nested_metadata = true
+
+      # When true, StandardAudit::AuthFailure.record also emits one structured
+      # `Rails.logger.warn` line per failure (event, error_code, path, ip,
+      # actor, timestamp), for alerting off the log stream. The audit row is
+      # written either way.
+      @log_auth_failures = false
 
       # When true (the default), an ActiveRecord object appearing anywhere in
       # audit metadata is replaced by a reference —
       # `{ "gid" => …, "type" => …, "id" => … }` — instead of being serialised
       # with all of its attributes. See StandardAudit::RecordReference.
       #
-      # Defaults to the SAFE behaviour, unlike `filter_nested_metadata`,
+      # Defaults to the SAFE behaviour, like `filter_nested_metadata`,
       # because the values this catches are ones no host asked to record:
       # `password_digest`, `token_digest`, `lookup_hash` and PKCE verifiers
       # arriving as a side effect of a payload carrying `account:` or
@@ -235,9 +247,31 @@ module StandardAudit
       # 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.
+      #
+      # `:indefinite` (or STANDARD_AUDIT_RETENTION_DAYS=indefinite) also keeps
+      # rows forever, but records that as a decision: the production retention
+      # advisory (StandardAudit::Checks::Retention) only warns on nil, which
+      # means nobody chose.
       @retention_days = self.class.retention_days_from_env
     end
 
+    # The retention window as a positive Integer of days, or nil when rows are
+    # kept forever (`retention_days` nil or `:indefinite`). What cleanup reads.
+    def retention_window_days
+      retention_days.is_a?(Integer) && retention_days.positive? ? retention_days : nil
+    end
+
+    # True when the host chose to keep audit rows forever.
+    def retention_indefinite?
+      retention_days == INDEFINITE_RETENTION
+    end
+
+    # True for a `retention_days` that is neither a window nor keep-forever,
+    # e.g. a String "90" or 0. CleanupJob keeps every row then, and says so.
+    def retention_misconfigured?
+      !retention_days.nil? && !retention_indefinite? && retention_window_days.nil?
+    end
+
     # Reads `::Current.<name>` when a top-level `Current` exists and responds
     # to it; nil otherwise. The building block of the default resolvers.
     def self.current_attribute(name)
@@ -246,11 +280,13 @@ module StandardAudit
       ::Current.public_send(name)
     end
 
-    # Parses STANDARD_AUDIT_RETENTION_DAYS into a positive Integer, or nil when
-    # unset/blank/zero/negative/non-numeric (=> infinite retention).
+    # Parses STANDARD_AUDIT_RETENTION_DAYS into a positive Integer, `:indefinite`
+    # for the literal "indefinite", or nil when unset/blank/zero/negative/
+    # non-numeric (=> infinite retention, undecided).
     def self.retention_days_from_env
       raw = ENV["STANDARD_AUDIT_RETENTION_DAYS"]
       return nil if raw.nil? || raw.strip.empty?
+      return INDEFINITE_RETENTION if raw.strip.casecmp?(INDEFINITE_RETENTION.to_s)
 
       days = Integer(raw, exception: false)
       days&.positive? ? days : nil

data/lib/standard_audit/record_reference.rb

@@ -14,8 +14,8 @@ module StandardAudit
   #
   # None of the three existing defences fired: `sensitive_keys` matches keys
   # exactly and the secrets are attributes *underneath* `account:`;
-  # `filter_nested_metadata` is off by default so the filter never descended
-  # to them; and `account:` does not look sensitive at the top level.
+  # `filter_nested_metadata` was off by default (until 0.14.0) so the filter
+  # never descended to them; and `account:` does not look sensitive at the top level.
   #
   # Key-based redaction is the wrong tool here — the leak is not "this key is
   # sensitive", it is "this value is an entire database row". So the value is

data/lib/standard_audit/rspec/coverage.rb

@@ -0,0 +1,133 @@
+require "standard_audit"
+
+# Catalogue coverage: every catalogue action is asserted by a positive
+# `have_audited("…")` somewhere in the suite.
+#
+#   require "standard_audit/rspec/coverage"
+#
+#   RSpec.describe "Audit catalogue coverage" do
+#     it_behaves_like "standard_audit catalogue coverage",
+#       pending: %w[grant.pass_scheduled]   # catalogued, not written yet
+#   end
+#
+# It is a STATIC scan of the spec files, not a runtime tally. Four of the five
+# estate apps run their suites under parallel_rspec, where no single process
+# sees every example, and a partial run (one file) would always look
+# uncovered. A literal `expect { … }.to have_audited("order.created")` in a
+# green suite means that example wrote the row, which is what coverage needs.
+# Negated assertions (`not_to have_audited`) and commented-out lines do not
+# count, and neither do action names built at runtime (interpolated strings,
+# constants): list those under `pending:` with a comment, or assert them with
+# a literal. The scan is line-based, so an assertion inside a heredoc or string
+# would still count; don't keep one there.
+#
+# This replaces the hand-maintained `CATALOGUE_ACTIONS` copies in
+# `spec/support/audit_log_coverage.rb` and the specs that kept them in sync
+# with the real catalogue.
+#
+# Options (all optional):
+#
+#   catalogue: the actions that must be covered, as an Array or a callable.
+#              Defaults to `config.audit_catalogue`. Pass a slice (e.g.
+#              `-> { AuditCatalogue::OPERATION_ACTIONS }`) to scope it.
+#   pending:   catalogue actions allowed to have no assertion yet. Each must be
+#              in the catalogue, and one that gains an assertion must be
+#              removed, so the list only ever shrinks.
+#   specs:     glob(s) of spec files to scan, relative to Rails.root (or the
+#              working directory). Defaults to "spec/**/*_spec.rb".
+#   root:      the directory `specs:` is relative to. Defaults to Rails.root.
+module StandardAudit
+  module RSpec
+    module Coverage
+      # A positive have_audited with a literal action: `.to have_audited("x")`,
+      # `.to(have_audited("x"))`, or a compound `.and have_audited("x")`.
+      ASSERTION = /(?:\.to|\.and)\s*\(?\s*have_audited\(\s*(["'])([^"'#\\]+)\1/
+      DEFAULT_SPECS = "spec/**/*_spec.rb".freeze
+
+      Report = Struct.new(:catalogue, :covered, :uncovered, :unknown_pending, :stale_pending, keyword_init: true) do
+        def ok?
+          uncovered.empty? && unknown_pending.empty? && stale_pending.empty?
+        end
+      end
+
+      module_function
+
+      # action => ["path:line", ...] for every positive literal assertion.
+      def covered_actions(specs: DEFAULT_SPECS, root: default_root)
+        files = Array(specs).flat_map { |glob| Dir.glob(File.expand_path(glob, root)) }.uniq.sort
+        files.each_with_object(Hash.new { |h, k| h[k] = [] }) do |file, covered|
+          File.foreach(file).with_index(1) do |line, number|
+            next if line.lstrip.start_with?("#")
+
+            line.scan(ASSERTION) { |_quote, action| covered[action] << "#{relative(file, root)}:#{number}" }
+          end
+        end
+      end
+
+      def report(catalogue: nil, pending: [], specs: DEFAULT_SPECS, root: default_root)
+        catalogue = resolve(catalogue || StandardAudit.config.audit_catalogue).map(&:to_s).uniq
+        pending = resolve(pending).map(&:to_s)
+        covered = covered_actions(specs: specs, root: root)
+
+        Report.new(
+          catalogue: catalogue,
+          covered: covered,
+          uncovered: catalogue - pending - covered.keys,
+          unknown_pending: pending - catalogue,
+          stale_pending: pending & covered.keys
+        )
+      end
+
+      def resolve(value)
+        value = value.call if value.respond_to?(:call)
+        Array(value)
+      end
+
+      def default_root
+        defined?(Rails) && Rails.respond_to?(:root) && Rails.root ? Rails.root.to_s : Dir.pwd
+      end
+
+      def relative(file, root)
+        file.delete_prefix("#{root}/")
+      end
+    end
+  end
+end
+
+RSpec.shared_examples "standard_audit catalogue coverage" do |options = {}|
+  coverage = StandardAudit::RSpec::Coverage
+
+  let(:coverage_report) do
+    coverage.report(
+      catalogue: options[:catalogue],
+      pending: options.fetch(:pending, []),
+      specs: options.fetch(:specs, coverage::DEFAULT_SPECS),
+      root: options.fetch(:root) { coverage.default_root }
+    )
+  end
+
+  it "has a catalogue to check" do
+    expect(coverage_report.catalogue).not_to be_empty,
+      "No catalogue actions to check. Set config.audit_catalogue or pass `catalogue:`; " \
+      "otherwise every other example here passes against an empty set."
+  end
+
+  it "asserts every catalogue action with have_audited" do
+    expect(coverage_report.uncovered).to be_empty,
+      "These catalogue actions have no `expect { … }.to have_audited(\"…\")` in the suite:\n  " \
+      "#{coverage_report.uncovered.sort.join("\n  ")}\n" \
+      "Add an example that writes each one, or list it under `pending:` with the reason."
+  end
+
+  it "lists only catalogue actions as pending" do
+    expect(coverage_report.unknown_pending).to be_empty,
+      "These `pending:` actions are not in the catalogue: #{coverage_report.unknown_pending.sort.join(", ")}"
+  end
+
+  it "has no pending action that is already covered" do
+    stale = coverage_report.stale_pending.sort
+    expect(stale).to be_empty,
+      "These `pending:` actions now have an assertion, so remove them from `pending:`:\n  " \
+      "#{stale.map { |a| "#{a} (#{coverage_report.covered[a].first})" }.join("\n  ")}"
+  end
+end

data/lib/standard_audit/rspec.rb

@@ -42,7 +42,17 @@ require "standard_audit/rspec/baseline"
 #
 # Intentionally `before(:example)` rather than `after(:example)` so the
 # reset always runs even when a previous example aborted in an after hook.
+#
+# Before the first example, `before(:suite)` checks that no plain
+# `StandardAudit.configure` ran at boot (StandardAudit.verify_baseline_configuration!)
+# and raises StandardAudit::BaselineConfigurationError, naming the call
+# sites, if one did. Such a block is applied once and then silently dropped by
+# the first reset, which is exactly the failure described above.
 RSpec.configure do |config|
+  config.before(:suite) do
+    StandardAudit.verify_baseline_configuration!
+  end
+
   config.before(:example) do
     Thread.current[:standard_audit_batch] = nil
     StandardAudit.reset_configuration!

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.13.3"
+  VERSION = "0.14.0"
 end

data/lib/standard_audit.rb

@@ -1,6 +1,12 @@
 require "standard_audit/version"
 
 module StandardAudit
+  # Raised by `verify_baseline_configuration!` (see `configure`).
+  class BaselineConfigurationError < StandardError; end
+
+  # How many distinct plain `configure` call sites are remembered.
+  UNBASELINED_SITE_LIMIT = 20
+
   # From this instant (by each row's `created_at`) new rows get the canonical
   # checksum and are verified strictly with it; earlier rows are legacy. See
   # StandardAudit::Checksum and fundbright/delivery-ops#689. Every host must
@@ -22,6 +28,7 @@ require "standard_audit/operation"
 require "standard_audit/auditable"
 require "standard_audit/audit_scope"
 require "standard_audit/checks/retention"
+require "standard_audit/auth_failure"
 
 module StandardAudit
   # Metadata keys owned internally by StandardAudit. Never filtered by
@@ -60,11 +67,49 @@ module StandardAudit
     def configure(baseline: false, &block)
       return config unless block
 
-      @baseline_configuration = block if baseline
+      if baseline
+        @baseline_configuration = block
+      else
+        site = caller_locations(1, 1).first.to_s
+        # Bounded: only boot-time calls matter, but a suite that configures
+        # inside thousands of examples would otherwise grow this forever.
+        sites = unbaselined_configure_sites
+        sites << site unless sites.include?(site) || sites.size >= UNBASELINED_SITE_LIMIT
+      end
       block.call(config)
       config
     end
 
+    # Where a plain (non-baseline) `configure` block was applied, oldest first,
+    # each site once, at most UNBASELINED_SITE_LIMIT of them.
+    # `reset_configuration!` cannot replay these, so a plain block that runs at
+    # boot is lost after the rspec plugin's first per-example reset.
+    # `standard_audit/rspec` reads this when the suite starts (see
+    # `verify_baseline_configuration!`).
+    def unbaselined_configure_sites
+      @unbaselined_configure_sites ||= []
+    end
+
+    # Raises when configuration applied so far would not survive
+    # `reset_configuration!`: any plain `configure` block, whether or not a
+    # baseline exists too. `standard_audit/rspec` calls it from
+    # `before(:suite)`, after the app has booted and before the first reset, so
+    # the mistake fails the suite instead of quietly reverting to gem defaults
+    # (and dropping `before_checksum` hooks) from the second example on.
+    # Configuring inside an example is fine and isn't checked.
+    def verify_baseline_configuration!
+      sites = unbaselined_configure_sites
+      return true if sites.empty?
+
+      raise BaselineConfigurationError,
+        "StandardAudit.configure was called without `baseline: true` at:\n  " \
+        "#{sites.uniq.join("\n  ")}\n" \
+        "standard_audit/rspec resets the configuration before every example and " \
+        "replays only the `configure(baseline: true)` block, so these settings are " \
+        "lost after the first example. Move them into that one baseline block " \
+        "(config/initializers/standard_audit.rb)."
+    end
+
     def config
       @configuration ||= Configuration.new
     end
@@ -179,7 +224,12 @@ module StandardAudit
     # `report_error`. Used by the subscribers, which must never let an audit
     # failure break the instrumented code path, and by `record(raise: false)`.
     def report_write_error(error, event_type, **context)
-      Rails.logger.error("[StandardAudit] Error creating audit log for #{event_type}: #{error.class}: #{error.message}")
+      begin
+        Rails.logger.error("[StandardAudit] Error creating audit log for #{event_type}: #{error.class}: #{error.message}")
+      rescue StandardError
+        # A broken logger must not turn a swallowed failure into a raised one;
+        # the reporter below still runs.
+      end
       report_error(error, { config.audit_error_context_key => event_type, **context })
     end
 
@@ -196,7 +246,11 @@ module StandardAudit
       nil
     rescue => report_failure
       message = "[StandardAudit] Error reporting audit failure: #{report_failure.class}: #{report_failure.message}"
-      Rails.logger&.error(message) if defined?(Rails) && Rails.respond_to?(:logger)
+      begin
+        Rails.logger&.error(message) if defined?(Rails) && Rails.respond_to?(:logger)
+      rescue StandardError
+        # Nothing left to tell: the reporter and the logger both failed.
+      end
       nil
     end
 
@@ -222,6 +276,7 @@ module StandardAudit
     # specs and for a host that needs a genuinely pristine configuration.
     def clear_baseline_configuration!
       @baseline_configuration = nil
+      @unbaselined_configure_sites = nil
     end
 
     def baseline_configured?

data/lib/tasks/standard_audit_tasks.rake

@@ -10,6 +10,11 @@ module StandardAudit
     def resolve_days!(task_name, arg)
       raw = arg.presence || StandardAudit.config.retention_days
 
+      if raw == StandardAudit::Configuration::INDEFINITE_RETENTION
+        abort "standard_audit:#{task_name}: retention_days is :indefinite (keep forever). " \
+              "Pass days explicitly (rake \"standard_audit:#{task_name}[90]\") to run it anyway."
+      end
+
       if raw.nil?
         abort "standard_audit:#{task_name}: no retention window. Pass days " \
               "(rake \"standard_audit:#{task_name}[90]\") or set config.retention_days " \

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.13.3
+  version: 0.14.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -107,6 +107,7 @@ files:
 - lib/standard_audit.rb
 - lib/standard_audit/audit_scope.rb
 - lib/standard_audit/auditable.rb
+- lib/standard_audit/auth_failure.rb
 - lib/standard_audit/checks/retention.rb
 - lib/standard_audit/checksum.rb
 - lib/standard_audit/checksum/key_order_search.rb
@@ -120,6 +121,7 @@ files:
 - lib/standard_audit/reference_preloading.rb
 - lib/standard_audit/rspec.rb
 - lib/standard_audit/rspec/baseline.rb
+- lib/standard_audit/rspec/coverage.rb
 - lib/standard_audit/rspec/matchers.rb
 - lib/standard_audit/rspec/operation.rb
 - lib/standard_audit/sensitive_keys_dry_run.rb