standard_audit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44b12d653a138dc099f16e659e14cd139b612369f2279859b9fcae7eff57827c
-  data.tar.gz: f36ceca0425ba35b8ad73c1ac91cf63e82eb6da21fdaf7f7117c73f9c09ecc4e
+  metadata.gz: c400c65330d8896079475becca2eedc20481027bd23a9e6c35d1aa6011e46762
+  data.tar.gz: e5757a3734ccecaa266b0e17f537f53c51d26cebd6b6fdcc0022db758d31935e
 SHA512:
-  metadata.gz: e10c0a45d0941ab4284f3f1fd0a8bd25b5b9c83b0052a1e354d3acb43be984eb1997e934ff8ea45beb9df772e12420300f41403bd018d3a75e2080b32df05cd0
-  data.tar.gz: c0fcae8a3eee766f6a2caf7f01323788e4eeadf3de73ff3b37a7258e3a037b2771e557a7865adf559ebd98afc3d975b2e92bbdfc0b2735b1819fffaef80511e8
+  metadata.gz: f03510f5f6f9c6ba1e47e189da9d29e9c1a6d720886fb149c4938f4612581bd4049b87e61d1a67a36c7a27cb4ca1a147c3f9984c17ee090980d236fa632531c3
+  data.tar.gz: faf25861c62875fb9e89b97c938a5ed1730982f3f8a48b40c694a3ee26f9941c9832085a1dc75420d4a7085c0cb03aff0b1474ea59e3a29a4386297d9fb6c879

data/CHANGELOG.md

@@ -1,8 +1,35 @@
 # Changelog
 
-## 0.1.0 (2026-03-03)
+All notable changes to this project will be documented in this file.
 
-Initial release.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-03-25
+
+### Added
+
+- Batch insert mode via `StandardAudit.batch { }` for high-volume audit logging
+- `StandardAudit::CleanupJob` for automated retention enforcement
+- `config.use_preset(:standard_id)` to subscribe to StandardId auth events in one call
+- GIN index on metadata JSONB column in install generator (PostgreSQL)
+- CI-driven gem publishing via GitHub Actions trusted publisher
+
+### Changed
+
+- Migration template uses `jsonb` instead of `json` for metadata column
+- Expanded default `sensitive_keys` to include `api_key`, `access_token`, `refresh_token`, `private_key`, `certificate_chain`, `ssn`, `credit_card`, `authorization`
+
+### Breaking Changes
+
+- AuditLog records are now immutable — `update`/`destroy` raises `ActiveRecord::ReadOnlyRecord`. Use `update_columns` for privileged operations like GDPR anonymization. `delete`/`delete_all` still work for bulk cleanup.
+- Removed `auto_cleanup` config attribute. Schedule `StandardAudit::CleanupJob` directly instead.
+
+## [0.1.0] - 2026-03-03
+
+### Added
 
 - Core audit log model with UUID primary keys and GlobalID-based polymorphic references
 - Convenience API: `StandardAudit.record` with sync, async, and block forms

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright TODO: Write your name
+Copyright (c) 2026 Jaryl Sim
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -161,7 +161,7 @@ StandardAudit.configure do |config|
 
   # -- Sensitive Data --
   # Keys automatically stripped from metadata.
-  config.sensitive_keys = %i[password password_confirmation token secret]
+  config.sensitive_keys += %i[my_custom_secret]  # added to built-in defaults
 
   # -- Metadata Builder --
   # Optional proc to transform metadata before storage.
@@ -179,9 +179,8 @@ StandardAudit.configure do |config|
   # Metadata keys to strip during anonymization.
   config.anonymizable_metadata_keys = %i[email name ip_address]
 
-  # -- Retention --
+  # -- Retention (schedule StandardAudit::CleanupJob to enforce) --
   config.retention_days = 90
-  config.auto_cleanup = false
 end
 ```
 
@@ -353,7 +352,7 @@ t.jsonb :metadata, default: {}
 **Sensitive data**: Configure `sensitive_keys` to automatically strip passwords, tokens, and secrets from metadata. Add domain-specific keys as needed:
 
 ```ruby
-config.sensitive_keys = %i[password token secret ssn credit_card_number]
+config.sensitive_keys += %i[medical_record_number]  # extend the built-in defaults
 ```
 
 **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.

data/app/jobs/standard_audit/cleanup_job.rb

@@ -0,0 +1,14 @@
+module StandardAudit
+  class CleanupJob < ActiveJob::Base
+    queue_as { StandardAudit.config.queue_name }
+
+    def perform
+      days = StandardAudit.config.retention_days
+      return unless days
+
+      cutoff = days.days.ago
+      deleted = StandardAudit::AuditLog.before(cutoff).in_batches(of: 10_000).delete_all
+      Rails.logger.info("[StandardAudit] CleanupJob deleted #{deleted} audit logs older than #{days} days")
+    end
+  end
+end

data/app/models/standard_audit/audit_log.rb

@@ -3,6 +3,14 @@ module StandardAudit
     self.table_name = "audit_logs"
 
     before_create :assign_uuid, if: -> { id.blank? }
+    after_create_commit :emit_created_event
+
+    # Audit logs are append-only. Use update_columns for privileged
+    # operations like GDPR anonymization that must bypass this guard.
+    # Note: delete/delete_all bypass callbacks and are permitted for
+    # bulk cleanup operations (see CleanupJob, rake standard_audit:cleanup).
+    before_update { raise ActiveRecord::ReadOnlyRecord }
+    before_destroy { raise ActiveRecord::ReadOnlyRecord }
 
     validates :event_type, presence: true
     validates :occurred_at, presence: true
@@ -85,8 +93,8 @@ module StandardAudit
     scope :for_request, ->(request_id) { where(request_id: request_id) }
     scope :from_ip, ->(ip_address) { where(ip_address: ip_address) }
     scope :for_session, ->(session_id) { where(session_id: session_id) }
-    scope :chronological, -> { order(occurred_at: :asc) }
-    scope :reverse_chronological, -> { order(occurred_at: :desc) }
+    scope :chronological, -> { order(occurred_at: :asc, created_at: :asc) }
+    scope :reverse_chronological, -> { order(occurred_at: :desc, created_at: :desc) }
     scope :recent, ->(n = 10) { reverse_chronological.limit(n) }
 
     # -- GDPR methods --
@@ -150,6 +158,18 @@ module StandardAudit
 
     private
 
+    def emit_created_event
+      ActiveSupport::Notifications.instrument("standard_audit.audit_log.created", {
+        id: id,
+        event_type: event_type,
+        actor_type: actor_type,
+        target_type: target_type,
+        scope_type: scope_type
+      })
+    rescue StandardError => e
+      Rails.logger.warn("[StandardAudit] Failed to emit event: #{e.class}: #{e.message}")
+    end
+
     def assign_uuid
       self.id = SecureRandom.uuid
     end

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

@@ -5,26 +5,28 @@ class CreateAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.curr
       t.string :actor_type
       t.string :target_gid
       t.string :target_type
+      # Multi-tenancy: include StandardAudit::AuditScope in your tenant model
+      # (e.g., Organisation) to scope audit logs. Leave nil for single-tenant apps.
       t.string :scope_gid
       t.string :scope_type
       t.string :event_type, null: false
       t.string :request_id
       t.string :ip_address
-      t.string :user_agent
+      t.text :user_agent
       t.string :session_id
-      t.json :metadata, default: {}
+      t.jsonb :metadata, default: {}
       t.datetime :occurred_at, null: false
       t.timestamps
     end
 
     add_index :audit_logs, :event_type
-    add_index :audit_logs, :actor_type
-    add_index :audit_logs, :target_type
+    add_index :audit_logs, [:actor_gid, :occurred_at]
+    add_index :audit_logs, [:target_gid, :occurred_at]
     add_index :audit_logs, [:scope_type, :scope_gid]
-    add_index :audit_logs, :scope_type
     add_index :audit_logs, :request_id
-    add_index :audit_logs, :occurred_at
-    add_index :audit_logs, :ip_address
+    add_index :audit_logs, [:occurred_at, :created_at]
     add_index :audit_logs, :session_id
+    # GIN index requires PostgreSQL; remove if using another database
+    add_index :audit_logs, :metadata, using: :gin
   end
 end

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

@@ -1,5 +1,8 @@
 StandardAudit.configure do |config|
-  # Subscribe to ActiveSupport::Notifications patterns
+  # Use a preset to subscribe to common event patterns
+  # config.use_preset(:standard_id)
+
+  # Or subscribe to ActiveSupport::Notifications patterns manually
   # config.subscribe_to "audit.**"
 
   # Actor extractor from notification payload
@@ -11,6 +14,9 @@ StandardAudit.configure do |config|
   # Scope extractor from notification payload
   # config.scope_extractor = ->(payload) { payload[:scope] }
 
+  # Multi-tenancy: include StandardAudit::AuditScope in your tenant model
+  # to add a scoped_audit_logs association.
+
   # Fallback resolvers (used when payload values are nil)
   # config.current_actor_resolver = -> { Current.user }
   # config.current_request_id_resolver = -> { Current.request_id }
@@ -18,8 +24,10 @@ StandardAudit.configure do |config|
   # config.current_user_agent_resolver = -> { Current.user_agent }
   # config.current_session_id_resolver = -> { Current.session_id }
 
-  # Keys to strip from metadata
-  # config.sensitive_keys = %i[password password_confirmation token secret]
+  # Keys to strip from metadata (defaults include: password, password_confirmation,
+  # token, secret, api_key, access_token, refresh_token, private_key,
+  # certificate_chain, ssn, credit_card, authorization)
+  # config.sensitive_keys += %i[my_custom_secret]
 
   # Run audit log creation in background job
   # config.async = false
@@ -31,7 +39,6 @@ StandardAudit.configure do |config|
   # GDPR: metadata keys to strip on anonymization
   # config.anonymizable_metadata_keys = %i[email name ip_address]
 
-  # Data retention
+  # Data retention (schedule StandardAudit::CleanupJob to enforce)
   # config.retention_days = nil
-  # config.auto_cleanup = false
 end

data/lib/standard_audit/configuration.rb

@@ -6,10 +6,11 @@ module StandardAudit
                   :current_ip_address_resolver, :current_user_agent_resolver,
                   :current_session_id_resolver,
                   :sensitive_keys, :metadata_builder,
-                  :anonymizable_metadata_keys, :retention_days, :auto_cleanup
+                  :anonymizable_metadata_keys, :retention_days
 
     def initialize
       @subscriptions = []
+      @applied_presets = []
       @async = false
       @queue_name = :default
       @enabled = true
@@ -34,11 +35,18 @@ module StandardAudit
         defined?(Current) && Current.respond_to?(:session_id) ? Current.session_id : nil
       }
 
-      @sensitive_keys = %i[password password_confirmation token secret]
+      # Note: :authorization filters the HTTP Authorization header value.
+      # If you use "authorization" as a metadata key for policy decisions,
+      # rename it (e.g. :authorization_policy) to avoid accidental filtering.
+      @sensitive_keys = %i[
+        password password_confirmation token secret
+        api_key access_token refresh_token
+        private_key certificate_chain
+        ssn credit_card authorization
+      ]
       @metadata_builder = nil
       @anonymizable_metadata_keys = %i[email name ip_address]
       @retention_days = nil
-      @auto_cleanup = false
     end
 
     def subscribe_to(pattern)
@@ -48,5 +56,22 @@ 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/presets/standard_id.rb

@@ -0,0 +1,22 @@
+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

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/standard_audit.rb

@@ -44,15 +44,20 @@ module StandardAudit
         return
       end
 
-      if config.async
-        job_attrs = attrs.dup
-        job_attrs[:actor_gid] = actor&.to_global_id&.to_s
-        job_attrs[:target_gid] = target&.to_global_id&.to_s
-        job_attrs[:scope_gid] = scope&.to_global_id&.to_s
-        job_attrs[:actor_type] = actor&.class&.name
-        job_attrs[:target_type] = target&.class&.name
-        job_attrs[:scope_type] = scope&.class&.name
-        StandardAudit::CreateAuditLogJob.perform_later(job_attrs.stringify_keys)
+      gid_attrs = {
+        actor_gid: actor&.to_global_id&.to_s,
+        actor_type: actor&.class&.name,
+        target_gid: target&.to_global_id&.to_s,
+        target_type: target&.class&.name,
+        scope_gid: scope&.to_global_id&.to_s,
+        scope_type: scope&.class&.name
+      }
+
+      if batching?
+        Thread.current[:standard_audit_batch] << attrs.merge(gid_attrs)
+        nil
+      elsif config.async
+        StandardAudit::CreateAuditLogJob.perform_later(attrs.merge(gid_attrs).stringify_keys)
       else
         log = StandardAudit::AuditLog.new(attrs)
         log.actor = actor
@@ -63,6 +68,24 @@ module StandardAudit
       end
     end
 
+    # Buffers record calls and flushes them via insert_all! on block exit.
+    # If the block raises, buffered records are dropped — only successful
+    # batches are persisted. Nested batches flush independently.
+    # Block-form record calls (with AS::Notifications) bypass the buffer
+    # and are processed normally since they don't persist records directly.
+    # Note: uses Thread.current for storage, which is not fiber-safe.
+    # Apps using async adapters (Falcon) should avoid concurrent batches.
+    def batch
+      previous = Thread.current[:standard_audit_batch]
+      buffer = Thread.current[:standard_audit_batch] = []
+
+      yield
+
+      flush_batch(buffer) if buffer.any?
+    ensure
+      Thread.current[:standard_audit_batch] = previous
+    end
+
     def subscriber
       @subscriber ||= Subscriber.new
     end
@@ -70,5 +93,24 @@ module StandardAudit
     def reset_configuration!
       @configuration = nil
     end
+
+    private
+
+    def batching?
+      Thread.current[:standard_audit_batch].is_a?(Array)
+    end
+
+    def flush_batch(buffer)
+      now = Time.current
+      rows = buffer.map do |attrs|
+        attrs.merge(
+          id: SecureRandom.uuid,
+          created_at: now,
+          updated_at: now
+        )
+      end
+
+      StandardAudit::AuditLog.insert_all!(rows)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -77,6 +77,7 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- app/jobs/standard_audit/cleanup_job.rb
 - app/jobs/standard_audit/create_audit_log_job.rb
 - app/models/standard_audit/application_record.rb
 - app/models/standard_audit/audit_log.rb
@@ -89,6 +90,7 @@ files:
 - lib/standard_audit/auditable.rb
 - lib/standard_audit/configuration.rb
 - lib/standard_audit/engine.rb
+- lib/standard_audit/presets/standard_id.rb
 - lib/standard_audit/subscriber.rb
 - lib/standard_audit/version.rb
 - lib/tasks/standard_audit_tasks.rake
@@ -99,6 +101,7 @@ metadata:
   homepage_uri: https://github.com/rarebit-one/standard_audit
   source_code_uri: https://github.com/rarebit-one/standard_audit
   changelog_uri: https://github.com/rarebit-one/standard_audit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/rarebit-one/standard_audit/issues
 rdoc_options: []
 require_paths:
 - lib