standard_audit 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a9a29ab9754c6dbc24134d000864e8d99f60966227691ee782b782423ac7dc7
-  data.tar.gz: 0ee9864f7b073c3376041facfafe575006179b443937883377a5bdda605bc81a
+  metadata.gz: 84f59bffd4df4a9174ba0a88645a4c7d5818eddf862b5badfb55c3880fb5849d
+  data.tar.gz: 7747fdff93658f34f3ba3a9bfa70ca40fdc581125d182c996319a161f5c30809
 SHA512:
-  metadata.gz: e156d464655ca40f791b064e264b18ac587b63819f454d8bc98b9b7a9168cbd02519795c14d0333cd148be191715d29498244d1218f505365a1ef669c6f591fe
-  data.tar.gz: 2816bb0d249b20d8464cde9655b5799d8b7525cba615b9a97528bd9ef78ca1b1254fd528bca77ac3390001bdf34adc384add86c5b924d43a2e93bf695620ae89
+  metadata.gz: 03f2f84e0418106b8899b9aaff009e95fdbb116f9eb98c37308d2b4ae41df3cfbfe9d9b1615bdd4beb4391d983989cb658e4195451cb56214a75e4cf46ba4375
+  data.tar.gz: 6b2e84e5bcd6e6e933535a6ae9e654deb3502e69b575d613044c7b02de843e2a8886c43a0c82bd8cb6313ff012510d36a52f290ca36dd778634c4b3c70cefb80

data/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-06-24
+
+### Added
+
+- `config.retention_days` now defaults from the `STANDARD_AUDIT_RETENTION_DAYS` environment variable, so a deployment can opt into a retention window without a code change. Unset/blank/zero/negative/non-numeric resolves to `nil` (infinite retention — the compliance-safe default that never auto-deletes). Host apps can still override `config.retention_days` in their initializer.
+- `StandardAudit::Checks::Retention` — a StandardHealth-compatible (duck-typed, no hard dependency) readiness check that flags unbounded retention on **production** deployments. Register it non-critical in `config/initializers/standard_health.rb`:
+  ```ruby
+  c.register_check :audit_retention, StandardAudit::Checks::Retention, critical: false
+  ```
+  When `APP_ENVIRONMENT == "production"` (falling back to `Rails.env.production?` so staging is not flagged) and `retention_days` is nil, it returns `:warn`, rolling `GET /health/ready` to `:degraded` — still HTTP 200, so it surfaces the advisory without failing the probe or blocking a deploy.
+
+## [0.5.0] - 2026-04-29
+
+### Changed
+
+- CI and release workflows migrated to the shared `rarebit-one/.github` reusable workflows (`reusable-gem-ci.yml@v1`, `reusable-gem-release.yml@v1`); `.github/workflows/ci.yml` and `release.yml` are now thin shims.
+- The `standard_audit:install` generator is now idempotent. Re-running it skips the migration when a `*_create_audit_logs.rb` file already exists in `db/migrate/`, and skips the initializer when `config/initializers/standard_audit.rb` already exists. New flags: `--skip-migration`, `--skip-initializer`, and `--force` (overwrite the existing initializer; defaults to skip without an interactive prompt).
+
+### Removed
+
+- **BREAKING:** Removed `Configuration#use_preset` and the `lib/standard_audit/presets/` directory. The preset pattern (`config.use_preset(:standard_id)`) created a direct dependency from `standard_audit` on a specific publisher gem, which inverted the intended dependency direction — `standard_audit` should be a generic event consumer with no knowledge of any particular publisher. Host apps should subscribe to event patterns directly:
+  ```ruby
+  StandardAudit.configure do |c|
+    c.subscribe_to "standard_id.authentication.*"
+    c.subscribe_to "standard_id.session.created"
+    c.subscribe_to "standard_id.session.revoked"
+    c.subscribe_to "standard_id.session.expired"
+    c.subscribe_to "standard_id.account.*"
+  end
+  ```
+  Each publisher gem documents its event namespace.
+- **BREAKING:** Dropped support for Ruby < 4.0. `required_ruby_version` is now `>= 4.0`. Hosts must upgrade to Ruby 4.0+ before bundling this version. CI tests all four published 4.0.x patches.
+- **BREAKING:** Dropped support for Rails < 8.0. `activerecord`, `activejob`, and `activesupport` constraints are now `>= 8.0` (was `>= 7.1`). Hosts on Rails 7.x must upgrade to Rails 8.0+ before bundling this version. Aligns with the org-wide policy of supporting Rails 8 and up.
+
 ## [0.4.0] - 2026-04-19
 
 ### Added

data/{MIT-LICENSE → LICENSE}

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

data/README.md

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

data/lib/generators/standard_audit/install/install_generator.rb

@@ -1,19 +1,85 @@
+require "rails/generators"
+
 module StandardAudit
   module Generators
+    # Installs StandardAudit in a host Rails application.
+    #
+    # Creates the migration for the `audit_logs` table and writes the
+    # initializer at `config/initializers/standard_audit.rb`.
+    #
+    # Idempotent: re-running the generator will skip pieces it has already
+    # installed. Pass `--skip-*` flags to opt out of individual steps and
+    # `--force` to overwrite an existing initializer.
     class InstallGenerator < Rails::Generators::Base
       include Rails::Generators::Migration
       source_root File.expand_path("templates", __dir__)
 
+      desc <<~DESC
+        Installs StandardAudit. By default this:
+          * copies a CreateAuditLogs migration into db/migrate/
+          * writes config/initializers/standard_audit.rb
+
+        Use --skip-* flags to opt out of individual steps when re-running on an
+        existing install. The generator is idempotent — already-installed
+        pieces are skipped with a clear message. Pass --force to overwrite an
+        existing initializer.
+      DESC
+
+      class_option :skip_migration, type: :boolean, default: false,
+        desc: "Do not copy the CreateAuditLogs migration into db/migrate"
+      class_option :skip_initializer, type: :boolean, default: false,
+        desc: "Do not write config/initializers/standard_audit.rb"
+      class_option :force, type: :boolean, default: false,
+        desc: "Overwrite config/initializers/standard_audit.rb if it already exists"
+
       def self.next_migration_number(dirname)
         Time.now.utc.strftime("%Y%m%d%H%M%S")
       end
 
       def copy_migration
+        if options[:skip_migration]
+          say_status("skip", "db/migrate/*_create_audit_logs.rb (--skip-migration)", :yellow)
+          return
+        end
+
+        if existing_migration
+          say_status(
+            "identical",
+            "AuditLog migration already present (#{relative_migration_path(existing_migration)}), skipping",
+            :blue
+          )
+          return
+        end
+
         migration_template "create_audit_logs.rb.erb", "db/migrate/create_audit_logs.rb"
       end
 
       def copy_initializer
-        template "initializer.rb.erb", "config/initializers/standard_audit.rb"
+        initializer_path = "config/initializers/standard_audit.rb"
+
+        if options[:skip_initializer]
+          say_status("skip", "#{initializer_path} (--skip-initializer)", :yellow)
+          return
+        end
+
+        if File.exist?(File.join(destination_root, initializer_path)) && !options[:force]
+          say_status("identical", "#{initializer_path} (already exists; pass --force to overwrite)", :blue)
+          return
+        end
+
+        template "initializer.rb.erb", initializer_path, force: options[:force]
+      end
+
+      no_commands do
+        def existing_migration
+          Dir.glob(File.join(destination_root, "db/migrate/*_create_audit_logs.rb")).first
+        end
+
+        def relative_migration_path(absolute_path)
+          Pathname.new(absolute_path).relative_path_from(Pathname.new(destination_root)).to_s
+        rescue ArgumentError
+          absolute_path
+        end
       end
     end
   end

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

@@ -1,8 +1,11 @@
 StandardAudit.configure do |config|
-  # Use a preset to subscribe to common event patterns
-  # config.use_preset(:standard_id)
-
-  # Or subscribe to ActiveSupport::Notifications patterns manually
+  # Subscribe to ActiveSupport::Notifications / Rails.event patterns.
+  # Each gem documents its own event namespace; subscribe to whichever
+  # patterns you want audited:
+  # config.subscribe_to "standard_id.authentication.*"
+  # config.subscribe_to "standard_id.session.created"
+  # config.subscribe_to "standard_id.session.revoked"
+  # config.subscribe_to "standard_circuit.circuit.*"
   # config.subscribe_to "audit.**"
 
   # Actor extractor from notification payload

data/lib/standard_audit/checks/retention.rb

@@ -0,0 +1,58 @@
+module StandardAudit
+  module Checks
+    # A StandardHealth-compatible readiness check that warns when audit_logs
+    # retention is unbounded on a production deployment.
+    #
+    # It is intentionally duck-typed (no hard dependency on standard_health):
+    # it exposes the `#initialize(name:, critical:)` + `#run` contract the
+    # StandardHealth aggregator calls, so it loads even where standard_health
+    # is absent.
+    #
+    # Register it (NON-critical) in config/initializers/standard_health.rb:
+    #
+    #   c.register_check :audit_retention,
+    #                    StandardAudit::Checks::Retention,
+    #                    critical: false
+    #
+    # A :warn result rolls /health/ready up to :degraded, which is still
+    # HTTP 200 — it surfaces the advisory in the readiness JSON WITHOUT failing
+    # the probe or blocking a deploy. Only a *critical* check failure returns
+    # 503, and this check is never critical.
+    #
+    # "Production" is ENV["APP_ENVIRONMENT"] == "production" when that var is
+    # set (so staging — which also runs RAILS_ENV=production — is not flagged);
+    # otherwise it falls back to Rails.env.production?.
+    class Retention
+      def initialize(name: :audit_retention, critical: false)
+        @name = name
+        @critical = critical
+      end
+
+      def run
+        unless production?
+          return { status: :ok, detail: "retention advisory only runs on production deployments" }
+        end
+
+        days = StandardAudit.config.retention_days
+        return { status: :ok, retention_days: days } if days
+
+        {
+          status: :warn,
+          message: "audit_logs retention is unbounded on production. Set " \
+                   "STANDARD_AUDIT_RETENTION_DAYS (or config.retention_days) and schedule " \
+                   "StandardAudit::CleanupJob, or treat indefinite retention as a deliberate " \
+                   "compliance decision."
+        }
+      end
+
+      private
+
+      def production?
+        app_env = ENV["APP_ENVIRONMENT"].to_s
+        return app_env == "production" unless app_env.empty?
+
+        defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+      end
+    end
+  end
+end

data/lib/standard_audit/configuration.rb

@@ -10,7 +10,6 @@ module StandardAudit
 
     def initialize
       @subscriptions = []
-      @applied_presets = []
       @async = false
       @queue_name = :default
       @enabled = true
@@ -46,7 +45,22 @@ module StandardAudit
       ]
       @metadata_builder = nil
       @anonymizable_metadata_keys = %i[email name ip_address]
-      @retention_days = nil
+
+      # Retention defaults from ENV so it can be set per-environment without a
+      # code change. Unset/blank/non-positive => nil (infinite retention, the
+      # compliance-safe default that never auto-deletes). A host app can still
+      # override with `config.retention_days = N` in its initializer.
+      @retention_days = self.class.retention_days_from_env
+    end
+
+    # Parses STANDARD_AUDIT_RETENTION_DAYS into a positive Integer, or nil when
+    # unset/blank/zero/negative/non-numeric (=> infinite retention).
+    def self.retention_days_from_env
+      raw = ENV["STANDARD_AUDIT_RETENTION_DAYS"]
+      return nil if raw.nil? || raw.strip.empty?
+
+      days = Integer(raw, exception: false)
+      days&.positive? ? days : nil
     end
 
     def subscribe_to(pattern)
@@ -56,22 +70,5 @@ module StandardAudit
     def subscriptions
       @subscriptions.dup.freeze
     end
-
-    def use_preset(name)
-      key = name.to_sym
-      return self if @applied_presets.include?(key)
-
-      preset = case key
-      when :standard_id
-        require "standard_audit/presets/standard_id"
-        StandardAudit::Presets::StandardId
-      else
-        raise ArgumentError, "Unknown preset: #{name}. Available presets: :standard_id"
-      end
-
-      preset.apply(self)
-      @applied_presets << key
-      self
-    end
   end
 end

data/lib/standard_audit/rspec.rb

@@ -0,0 +1,29 @@
+require "standard_audit"
+
+# StandardAudit state reset between examples.
+#
+# - Clears the thread-local batch buffer so a spec that exits inside a
+#   `StandardAudit.batch { ... }` block (e.g. via an unhandled error or
+#   abort) cannot leak buffered records into the next example.
+# - Resets the Configuration via `StandardAudit.reset_configuration!` so
+#   that mutations to `StandardAudit.config` (subscriptions, sensitive
+#   keys, async flag, custom resolvers, etc.) do not bleed across specs.
+#   Consumers that customise configuration must re-call
+#   `StandardAudit.configure { |c| ... }` from a `before` hook in their
+#   own suite if they need a non-default baseline.
+#
+# The memoized `Subscriber` and `EventSubscriber` instances are *not*
+# torn down here — they are wired up at engine boot via initializers and
+# rebuilding them per-example would unsubscribe from
+# `ActiveSupport::Notifications` / `Rails.event` for the rest of the run.
+# Specs that need to assert on subscriber behaviour should manage that
+# locally.
+#
+# Intentionally `before(:example)` rather than `after(:example)` so the
+# reset always runs even when a previous example aborted in an after hook.
+RSpec.configure do |config|
+  config.before(:example) do
+    Thread.current[:standard_audit_batch] = nil
+    StandardAudit.reset_configuration!
+  end
+end

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

data/lib/standard_audit.rb

@@ -5,6 +5,7 @@ require "standard_audit/subscriber"
 require "standard_audit/event_subscriber"
 require "standard_audit/auditable"
 require "standard_audit/audit_scope"
+require "standard_audit/checks/retention"
 
 module StandardAudit
   # Metadata keys owned internally by StandardAudit. Never filtered by

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -15,42 +15,42 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: activejob
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: globalid
   requirement: !ruby/object:Gem::Requirement
@@ -65,9 +65,23 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
 description: StandardAudit is a standalone Rails gem for database-backed audit logging.
-  On Rails 8.1+ it subscribes to Rails.event; on earlier versions it subscribes to
-  ActiveSupport::Notifications. Generic, flexible, and works with any Rails application.
+  On Rails 8.1+ it subscribes to Rails.event; on Rails 8.0 it falls back to ActiveSupport::Notifications.
+  Generic, flexible, and works with any Rails application.
 email:
 - code@jaryl.dev
 executables: []
@@ -75,7 +89,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- MIT-LICENSE
+- LICENSE
 - README.md
 - Rakefile
 - app/jobs/standard_audit/cleanup_job.rb
@@ -91,10 +105,11 @@ files:
 - lib/standard_audit.rb
 - lib/standard_audit/audit_scope.rb
 - lib/standard_audit/auditable.rb
+- lib/standard_audit/checks/retention.rb
 - lib/standard_audit/configuration.rb
 - lib/standard_audit/engine.rb
 - lib/standard_audit/event_subscriber.rb
-- lib/standard_audit/presets/standard_id.rb
+- lib/standard_audit/rspec.rb
 - lib/standard_audit/subscriber.rb
 - lib/standard_audit/version.rb
 - lib/tasks/standard_audit_tasks.rake
@@ -113,7 +128,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/standard_audit/presets/standard_id.rb

@@ -1,22 +0,0 @@
-module StandardAudit
-  module Presets
-    module StandardId
-      # Regex wildcards capture all events in a namespace. Session uses
-      # explicit strings to exclude noisy events like session.validated
-      # that fire on every authenticated request.
-      SUBSCRIPTIONS = [
-        /\Astandard_id\.authentication\./,
-        "standard_id.session.created",
-        "standard_id.session.revoked",
-        "standard_id.session.expired",
-        /\Astandard_id\.account\./,
-        /\Astandard_id\.social\./,
-        /\Astandard_id\.passwordless\./
-      ].freeze
-
-      def self.apply(config)
-        SUBSCRIPTIONS.each { |pattern| config.subscribe_to(pattern) }
-      end
-    end
-  end
-end