standard_audit 0.10.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fca49bbca23bc24c89aa7249f0ea4718c2f4fa6bae03748ec93a45df17c4bd0
-  data.tar.gz: 7920932fea8af270498c7620d7cb4e18e0cfaab1c0deb7f299715ce578882dd2
+  metadata.gz: 697434bf73f4588971d9fda7503f13f53a848ab4fe058fbc05be5b567a186d6f
+  data.tar.gz: e5bad881dc6a5ab13ae22d13777176120967161f40356dcd6522ab4616492c1f
 SHA512:
-  metadata.gz: 7117529ed69a81588ea18b081e3b8a8047dc9441fe116bef9e594beacc692108a1c8d625e2d4c1a959ac01a1d03857d9d94e91a4dfe65c52c35ce894b980e797
-  data.tar.gz: bdb36b281136e0928c4bac601bbee408de0cf040d70222c8d3339153c53312e1bd1820f136488086184426f68ce9f930b75d521b75fd25950f4f7b3bb232c66d
+  metadata.gz: feb2b3354808c948aff042e0a3354ac2344c3e4ac1b03f0c375645ff7b1aaf1ec27253e87e764652ee7d52710a4c7aecd7748ba13475afa001a0c27f55a2ca79
+  data.tar.gz: a83422f4ef6b6ca319c29c450ae7cf82457cc5ad342345947a867e2243ef701c2bb0310a5b1d99f5cbf9c322b756f5094c42e77e53eb6ea3b828a834f94bfacc

data/CHANGELOG.md

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

data/README.md

@@ -332,6 +332,10 @@ StandardAudit.configure(baseline: true) do |config|
   # `metadata: { stripe: { client_secret: ... } }` is written intact.
   config.filter_nested_metadata = true
 
+  # Replace ActiveRecord objects in metadata with a reference instead of
+  # serialising every attribute. ON by default; see "Records in metadata".
+  config.dereference_record_metadata = true
+
   # -- Write-time hooks --
   # Run between the UUID assignment and the checksum computation, so a hook MAY
   # set a checksummed column and the row still passes `verify_chain`. No
@@ -495,6 +499,16 @@ 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")
+```
+
 ### Right to Access (Export)
 
 Export all audit data for a specific user:
@@ -521,7 +535,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)
@@ -631,10 +647,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
@@ -647,6 +665,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:
@@ -695,6 +722,38 @@ Nested metadata is **not** redacted unless `filter_nested_metadata` is enabled
 — `metadata: { stripe: { client_secret: ... } }` passes both write paths under
 exact matching by default.
 
+### Records in metadata
+
+An ActiveRecord object appearing anywhere in metadata is replaced, by default,
+with a reference rather than a snapshot of the row:
+
+```ruby
+{ account: account }
+# => { account: { "gid" => "gid://myapp/Account/1", "type" => "Account", "id" => "1" } }
+```
+
+This applies at any depth, inside Arrays, Hashes and `ActiveRecord::Relation`s,
+on both write paths. It is on by default because key-based redaction cannot
+reach the problem: a payload key like `account:` looks like exactly the kind of
+key you want on an audit row, while the value serialises with
+`password_digest`, `token_digest`, `lookup_hash` and anything else the table
+happens to hold. Audit rows are append-only, so an unsafe default cannot be
+walked back.
+
+On the notifications path, records are dereferenced **after**
+`metadata_builder` runs, so a builder that needs real attributes still gets the
+record (`metadata_builder` has never applied to a direct `StandardAudit.record`
+call — pass the attributes you want in `metadata` there):
+
+```ruby
+config.metadata_builder = ->(metadata) {
+  metadata.merge(account_email: metadata[:account]&.email)
+}
+```
+
+`config.dereference_record_metadata = false` restores the pre-0.11.0 behaviour
+of writing full attributes. Prefer `metadata_builder` over turning it off.
+
 **Performance**: For high-volume applications, enable async processing and ensure your `audit_logs` table has appropriate indexes (the install generator adds them by default). Consider partitioning by `occurred_at` for very large tables.
 
 **Retention**: Set `retention_days` in your configuration and run `rake standard_audit:cleanup` via a scheduled job (e.g., cron or SolidQueue recurring). Archive before deleting if you need long-term storage.

data/app/models/standard_audit/audit_log.rb

@@ -92,8 +92,11 @@ 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.
+    def self.anonymize_actor!(subject)
+      gid = subject_gid_for(subject)
       logs = where("actor_gid = ? OR target_gid = ?", gid, gid)
       count = logs.count
 
@@ -122,8 +125,8 @@ module StandardAudit
       count
     end
 
-    def self.export_for_actor(record)
-      gid = record.to_global_id.to_s
+    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 +152,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)

data/lib/standard_audit/configuration.rb

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

data/lib/standard_audit/event_subscriber.rb

@@ -48,10 +48,27 @@ module StandardAudit
       )
     rescue => e
       Rails.logger.error("[StandardAudit] Error handling Rails.event: #{e.class}: #{e.message}")
+      report_error(e, name)
     end
 
     private
 
+    # The event handler rescues so a failed audit write cannot break the
+    # instrumented code path, but a log line alone is invisible to error
+    # tracking — so report it as handled too.
+    def report_error(error, event_name)
+      return unless Rails.respond_to?(:error) && Rails.error
+
+      Rails.error.report(
+        error,
+        handled: true,
+        context: { StandardAudit.config.audit_error_context_key => event_name,
+                   subscriber: self.class.name }
+      )
+    rescue => report_failure
+      Rails.logger.error("[StandardAudit] Error reporting audit failure: #{report_failure.class}: #{report_failure.message}")
+    end
+
     def matches_subscription?(name)
       StandardAudit.config.subscriptions.any? { |pattern| pattern_match?(pattern, name) }
     end

data/lib/standard_audit/record_reference.rb

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

data/lib/standard_audit/subscriber.rb

@@ -25,6 +25,22 @@ module StandardAudit
 
     private
 
+    # The event handler rescues so a failed audit write cannot break the
+    # instrumented code path, but a log line alone is invisible to error
+    # tracking — so report it as handled too.
+    def report_error(error, event_name)
+      return unless Rails.respond_to?(:error) && Rails.error
+
+      Rails.error.report(
+        error,
+        handled: true,
+        context: { StandardAudit.config.audit_error_context_key => event_name,
+                   subscriber: self.class.name }
+      )
+    rescue => report_failure
+      Rails.logger.error("[StandardAudit] Error reporting audit failure: #{report_failure.class}: #{report_failure.message}")
+    end
+
     def handle_event(event)
       return unless StandardAudit.config.enabled
 
@@ -68,6 +84,7 @@ module StandardAudit
       end
     rescue => e
       Rails.logger.error("[StandardAudit] Error creating audit log: #{e.class}: #{e.message}")
+      report_error(e, event.name)
     end
 
     def extract_metadata(payload, config)
@@ -79,6 +96,16 @@ module StandardAudit
         raw_metadata = config.metadata_builder.call(raw_metadata)
       end
 
+      # ActiveRecord objects in the payload are replaced by a reference BEFORE
+      # any key-based redaction, because the leak they cause is not a
+      # sensitive *key* — it is a value that serialises as an entire database
+      # row (rarebit-one/rarebit-ops#296). Runs after `metadata_builder` so a
+      # host that derives fields from a record (`payload[:account].email`)
+      # still sees the record.
+      if config.dereference_record_metadata
+        raw_metadata = StandardAudit::RecordReference.call(raw_metadata)
+      end
+
       # Redaction lives in MetadataFilter, shared with StandardAudit.record.
       # This path previously carried its own copy that did *not* subtract
       # RESERVED_METADATA_KEYS, so `_tags`/`_source` were strippable here and

data/lib/standard_audit/version.rb

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

data/lib/standard_audit.rb

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

data/lib/tasks/standard_audit_tasks.rake

@@ -1,16 +1,44 @@
+module StandardAudit
+  module RakeSupport
+    module_function
+
+    # Resolves the retention window for cleanup/archive: the task argument,
+    # else config.retention_days, else abort. nil retention means "keep
+    # forever", so there is deliberately no hard-coded fallback. Anything that
+    # is not a positive integer aborts — `cleanup[abc]` used to become 0 days,
+    # i.e. delete everything.
+    def resolve_days!(task_name, arg)
+      raw = arg.presence || StandardAudit.config.retention_days
+
+      if raw.nil?
+        abort "standard_audit:#{task_name}: no retention window. Pass days " \
+              "(rake \"standard_audit:#{task_name}[90]\") or set config.retention_days " \
+              "/ STANDARD_AUDIT_RETENTION_DAYS. A nil retention_days means keep forever."
+      end
+
+      days = Integer(raw.to_s.strip, 10, exception: false)
+      unless days&.positive?
+        abort "standard_audit:#{task_name}: days must be a positive integer, got #{raw.inspect}"
+      end
+
+      days
+    end
+  end
+end
+
 namespace :standard_audit do
-  desc "Delete audit logs older than specified days (default: 90)"
+  desc "Delete audit logs older than N days (default: config.retention_days; aborts if neither is set)"
   task :cleanup, [:days] => :environment do |_t, args|
-    days = (args[:days] || StandardAudit.config.retention_days || 90).to_i
+    days = StandardAudit::RakeSupport.resolve_days!("cleanup", args[:days])
     cutoff = days.days.ago
 
     deleted = StandardAudit::AuditLog.where("occurred_at < ?", cutoff).delete_all
     puts "Deleted #{deleted} audit logs older than #{days} days"
   end
 
-  desc "Archive audit logs to JSON file"
+  desc "Archive audit logs older than N days to a JSON file (default: config.retention_days; aborts if neither is set)"
   task :archive, [:days, :output] => :environment do |_t, args|
-    days = (args[:days] || 90).to_i
+    days = StandardAudit::RakeSupport.resolve_days!("archive", args[:days])
     output = args[:output] || "audit_logs_archive_#{Date.current}.json"
     cutoff = days.days.ago
 

metadata

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