standard_audit 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dff9827071db99dfcb9dc184f3cc20d0bcfd208de8f5d41c86efff0f7e4c2be
-  data.tar.gz: 979f93e8ed8d293695337e453ade9926b553be7904617d7c61d653ef5997a3ea
+  metadata.gz: 84f59bffd4df4a9174ba0a88645a4c7d5818eddf862b5badfb55c3880fb5849d
+  data.tar.gz: 7747fdff93658f34f3ba3a9bfa70ca40fdc581125d182c996319a161f5c30809
 SHA512:
-  metadata.gz: 98bf60f4d4d40d46ff28d9203c8686a5c57765a86c4c3ef1db97c59d32b27e355ac7b585730cd69865e54cf8540109c87546259ea19e4afdfa9a3510b5b52e1f
-  data.tar.gz: dda3b2376d9afcd2a61808fc79025e246365302f7b097c17a801bf47cc6a8f3e26a3e11b411dc19b31f6ebac32dc44107e92582e02813a22476be2fa1eaca32a
+  metadata.gz: 03f2f84e0418106b8899b9aaff009e95fdbb116f9eb98c37308d2b4ae41df3cfbfe9d9b1615bdd4beb4391d983989cb658e4195451cb56214a75e4cf46ba4375
+  data.tar.gz: 6b2e84e5bcd6e6e933535a6ae9e654deb3502e69b575d613044c7b02de843e2a8886c43a0c82bd8cb6313ff012510d36a52f290ca36dd778634c4b3c70cefb80

data/CHANGELOG.md

@@ -7,6 +7,17 @@ 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

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

@@ -209,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
 ```
@@ -339,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/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

@@ -45,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)

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.5.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.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -89,7 +89,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- MIT-LICENSE
+- LICENSE
 - README.md
 - Rakefile
 - app/jobs/standard_audit/cleanup_job.rb
@@ -105,6 +105,7 @@ 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