standard_audit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 44b12d653a138dc099f16e659e14cd139b612369f2279859b9fcae7eff57827c
+  data.tar.gz: f36ceca0425ba35b8ad73c1ac91cf63e82eb6da21fdaf7f7117c73f9c09ecc4e
+SHA512:
+  metadata.gz: e10c0a45d0941ab4284f3f1fd0a8bd25b5b9c83b0052a1e354d3acb43be984eb1997e934ff8ea45beb9df772e12420300f41403bd018d3a75e2080b32df05cd0
+  data.tar.gz: c0fcae8a3eee766f6a2caf7f01323788e4eeadf3de73ff3b37a7258e3a037b2771e557a7865adf559ebd98afc3d975b2e92bbdfc0b2735b1819fffaef80511e8

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (2026-03-03)
+
+Initial release.
+
+- Core audit log model with UUID primary keys and GlobalID-based polymorphic references
+- Convenience API: `StandardAudit.record` with sync, async, and block forms
+- ActiveSupport::Notifications subscriber for automatic event capture
+- Configurable Current attribute resolvers for request context
+- Multi-tenancy support via scope column
+- 20+ composable query scopes (by actor, target, scope, event type, time, request context)
+- Async processing via ActiveJob with configurable queue
+- Sensitive key filtering for metadata
+- GDPR compliance: `anonymize_actor!` (right to erasure) and `export_for_actor` (right to access)
+- Model concerns: `Auditable` for actors/targets, `AuditScope` for tenant models
+- Install generator with migration and initializer templates
+- Rake tasks for cleanup, archival, statistics, and GDPR operations

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,365 @@
+# StandardAudit
+
+Database-backed audit logging for Rails via ActiveSupport::Notifications.
+
+StandardAudit is a standalone Rails engine that captures audit events into a dedicated `audit_logs` table. It uses [GlobalID](https://github.com/rails/globalid) for polymorphic references, making it work with any ActiveRecord model without foreign keys or tight coupling.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "standard_audit"
+```
+
+Run the install generator:
+
+```bash
+rails generate standard_audit:install
+rails db:migrate
+```
+
+This creates:
+- A migration for the `audit_logs` table (UUID primary keys, JSON metadata)
+- An initializer at `config/initializers/standard_audit.rb`
+
+## Quick Start
+
+### 1. Subscribe to events
+
+```ruby
+# config/initializers/standard_audit.rb
+StandardAudit.configure do |config|
+  config.subscribe_to "myapp.*"
+end
+```
+
+### 2. Instrument events in your code
+
+```ruby
+ActiveSupport::Notifications.instrument("myapp.orders.created", {
+  actor: current_user,
+  target: @order,
+  scope: current_organisation
+})
+```
+
+### 3. Query the logs
+
+```ruby
+StandardAudit::AuditLog.for_actor(current_user).this_week
+```
+
+## Recording Events
+
+StandardAudit provides three ways to record audit events.
+
+### Convenience API
+
+The simplest approach — call `StandardAudit.record` directly:
+
+```ruby
+StandardAudit.record("orders.created",
+  actor: current_user,
+  target: @order,
+  scope: current_organisation,
+  metadata: { total: @order.total }
+)
+```
+
+When `actor` is omitted, it falls back to the configured `current_actor_resolver` (which reads from `Current.user` by default).
+
+### ActiveSupport::Notifications
+
+Instrument events and let the subscriber handle persistence:
+
+```ruby
+ActiveSupport::Notifications.instrument("myapp.orders.created", {
+  actor: current_user,
+  target: @order,
+  scope: current_organisation,
+  total: 99.99
+})
+```
+
+Any payload keys not in the reserved set (`actor`, `target`, `scope`, `request_id`, `ip_address`, `user_agent`, `session_id`) are stored as metadata.
+
+### Block form
+
+Wrap an operation so the event is only recorded if the block succeeds:
+
+```ruby
+StandardAudit.record("orders.created", actor: current_user, target: @order) do
+  @order.process!
+end
+```
+
+This uses `ActiveSupport::Notifications.instrument` under the hood.
+
+## Model Concerns
+
+### Auditable
+
+Include `StandardAudit::Auditable` in models that act as actors or targets:
+
+```ruby
+class User < ApplicationRecord
+  include StandardAudit::Auditable
+end
+```
+
+This provides:
+
+```ruby
+user.audit_logs_as_actor   # logs where this user is the actor
+user.audit_logs_as_target  # logs where this user is the target
+user.audit_logs            # logs where this user is either
+user.record_audit("users.updated", target: @profile)
+```
+
+### AuditScope
+
+Include `StandardAudit::AuditScope` in tenant/organisation models:
+
+```ruby
+class Organisation < ApplicationRecord
+  include StandardAudit::AuditScope
+end
+```
+
+This provides:
+
+```ruby
+organisation.scoped_audit_logs  # all logs scoped to this organisation
+```
+
+## Configuration Reference
+
+```ruby
+StandardAudit.configure do |config|
+  # -- Subscriptions --
+  # Subscribe to ActiveSupport::Notifications patterns.
+  # Supports wildcards.
+  config.subscribe_to "myapp.*"
+  config.subscribe_to "auth.*"
+
+  # -- Extractors --
+  # How to pull actor/target/scope from notification payloads.
+  # Defaults shown below.
+  config.actor_extractor  = ->(payload) { payload[:actor] }
+  config.target_extractor = ->(payload) { payload[:target] }
+  config.scope_extractor  = ->(payload) { payload[:scope] }
+
+  # -- Current Attribute Resolvers --
+  # Fallbacks used when payload values are nil.
+  # Designed to work with Rails Current attributes.
+  config.current_actor_resolver      = -> { Current.user }
+  config.current_request_id_resolver = -> { Current.request_id }
+  config.current_ip_address_resolver = -> { Current.ip_address }
+  config.current_user_agent_resolver = -> { Current.user_agent }
+  config.current_session_id_resolver = -> { Current.session_id }
+
+  # -- Sensitive Data --
+  # Keys automatically stripped from metadata.
+  config.sensitive_keys = %i[password password_confirmation token secret]
+
+  # -- Metadata Builder --
+  # Optional proc to transform metadata before storage.
+  config.metadata_builder = ->(metadata) { metadata.slice(:relevant_key) }
+
+  # -- Async Processing --
+  # Offload audit log creation to ActiveJob.
+  config.async = false
+  config.queue_name = :default
+
+  # -- Feature Toggle --
+  config.enabled = true
+
+  # -- GDPR --
+  # Metadata keys to strip during anonymization.
+  config.anonymizable_metadata_keys = %i[email name ip_address]
+
+  # -- Retention --
+  config.retention_days = 90
+  config.auto_cleanup = false
+end
+```
+
+### Default Current Attribute Resolvers
+
+Out of the box, StandardAudit reads from `Current` if it responds to the relevant method. This means if your app (or an auth library like StandardId) populates `Current.user`, `Current.request_id`, etc., audit logs automatically capture request context with zero configuration.
+
+## Query Interface
+
+`StandardAudit::AuditLog` ships with composable scopes:
+
+### By association
+
+```ruby
+AuditLog.for_actor(user)          # logs for a specific actor
+AuditLog.for_target(order)        # logs for a specific target
+AuditLog.for_scope(organisation)  # logs within a scope/tenant
+AuditLog.by_actor_type("User")    # logs by actor class name
+AuditLog.by_target_type("Order")  # logs by target class name
+AuditLog.by_scope_type("Organisation")
+```
+
+### By event
+
+```ruby
+AuditLog.by_event_type("orders.created")   # exact match
+AuditLog.matching_event("orders.%")        # SQL LIKE pattern
+```
+
+### By time
+
+```ruby
+AuditLog.today
+AuditLog.yesterday
+AuditLog.this_week
+AuditLog.this_month
+AuditLog.last_n_days(30)
+AuditLog.since(1.hour.ago)
+AuditLog.before(1.day.ago)
+AuditLog.between(start_time, end_time)
+```
+
+### By request context
+
+```ruby
+AuditLog.for_request("req-abc-123")
+AuditLog.from_ip("192.168.1.1")
+AuditLog.for_session("session-xyz")
+```
+
+### Ordering
+
+```ruby
+AuditLog.chronological           # oldest first
+AuditLog.reverse_chronological   # newest first
+AuditLog.recent(20)              # newest 20 records
+```
+
+### Composing queries
+
+All scopes are chainable:
+
+```ruby
+AuditLog
+  .for_scope(current_organisation)
+  .by_event_type("orders.created")
+  .this_month
+  .reverse_chronological
+```
+
+## Multi-Tenancy
+
+StandardAudit supports multi-tenancy through the `scope` column. Pass any ActiveRecord model as the scope — typically an Organisation or Account:
+
+```ruby
+StandardAudit.record("orders.created",
+  actor: current_user,
+  target: @order,
+  scope: current_organisation
+)
+```
+
+Then query all audit activity within that tenant:
+
+```ruby
+StandardAudit::AuditLog.for_scope(current_organisation)
+```
+
+The scope is stored as a GlobalID string, so it works with any model class.
+
+## Async Processing
+
+For high-throughput applications, offload audit log creation to a background job:
+
+```ruby
+StandardAudit.configure do |config|
+  config.async = true
+  config.queue_name = :audit  # default: :default
+end
+```
+
+When async is enabled, `StandardAudit::CreateAuditLogJob` serialises actor, target, and scope as GlobalID strings and resolves them back when the job runs. If a referenced record has been deleted between event capture and job execution, the GID string and type are preserved on the audit log (the record just won't be resolvable).
+
+## GDPR Compliance
+
+### Right to Erasure (Anonymization)
+
+Strip personally identifiable information from audit logs while preserving the event timeline:
+
+```ruby
+StandardAudit::AuditLog.anonymize_actor!(user)
+```
+
+This:
+- Replaces `actor_gid` / `target_gid` with `[anonymized]` where the user appears
+- Clears `ip_address`, `user_agent`, and `session_id`
+- Removes metadata keys listed in `anonymizable_metadata_keys`
+
+### Right to Access (Export)
+
+Export all audit data for a specific user:
+
+```ruby
+data = StandardAudit::AuditLog.export_for_actor(user)
+File.write("export.json", JSON.pretty_generate(data))
+```
+
+Returns a hash with `subject`, `exported_at`, `total_records`, and a `records` array.
+
+## Rake Tasks
+
+```bash
+# Delete logs older than N days (default: retention_days config or 90)
+rake standard_audit:cleanup[180]
+
+# Archive old logs to a JSON file before deleting
+rake standard_audit:archive[90,audit_backup.json]
+
+# Show statistics
+rake standard_audit:stats
+
+# GDPR: anonymize all logs for an actor
+rake "standard_audit:anonymize_actor[gid://myapp/User/123]"
+
+# GDPR: export all logs for an actor
+rake "standard_audit:export_actor[gid://myapp/User/123,export.json]"
+```
+
+## Database Support
+
+The migration uses `json` column type by default, which works across:
+
+| Database   | Column Type | Notes |
+|------------|-------------|-------|
+| PostgreSQL | `jsonb`     | Consider changing `json` to `jsonb` in the migration for better query performance |
+| MySQL      | `json`      | Native JSON support |
+| SQLite     | `json`      | Stored as text; suitable for development and testing |
+
+For PostgreSQL, edit the generated migration to use `jsonb` instead of `json`:
+
+```ruby
+t.jsonb :metadata, default: {}
+```
+
+## Best Practices
+
+**What to audit**: Authentication events, data mutations, permission changes, financial transactions, admin actions, data exports, and API access from external services.
+
+**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]
+```
+
+**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.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/jobs/standard_audit/create_audit_log_job.rb

@@ -0,0 +1,47 @@
+module StandardAudit
+  class CreateAuditLogJob < ActiveJob::Base
+    queue_as { StandardAudit.config.queue_name }
+
+    def perform(attrs)
+      attrs = attrs.symbolize_keys
+
+      actor_gid = attrs.delete(:actor_gid)
+      target_gid = attrs.delete(:target_gid)
+      scope_gid = attrs.delete(:scope_gid)
+      actor_type = attrs.delete(:actor_type)
+      target_type = attrs.delete(:target_type)
+      scope_type = attrs.delete(:scope_type)
+
+      log = StandardAudit::AuditLog.new(attrs)
+
+      if actor_gid.present?
+        begin
+          log.actor = GlobalID::Locator.locate(actor_gid)
+        rescue ActiveRecord::RecordNotFound
+          log.actor_gid = actor_gid
+          log.actor_type = actor_type
+        end
+      end
+
+      if target_gid.present?
+        begin
+          log.target = GlobalID::Locator.locate(target_gid)
+        rescue ActiveRecord::RecordNotFound
+          log.target_gid = target_gid
+          log.target_type = target_type
+        end
+      end
+
+      if scope_gid.present?
+        begin
+          log.scope = GlobalID::Locator.locate(scope_gid)
+        rescue ActiveRecord::RecordNotFound
+          log.scope_gid = scope_gid
+          log.scope_type = scope_type
+        end
+      end
+
+      log.save!
+    end
+  end
+end

data/app/models/standard_audit/application_record.rb

@@ -0,0 +1,5 @@
+module StandardAudit
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/standard_audit/audit_log.rb

@@ -0,0 +1,157 @@
+module StandardAudit
+  class AuditLog < ApplicationRecord
+    self.table_name = "audit_logs"
+
+    before_create :assign_uuid, if: -> { id.blank? }
+
+    validates :event_type, presence: true
+    validates :occurred_at, presence: true
+
+    # -- Actor assignment via GlobalID --
+
+    def actor=(record)
+      if record.nil?
+        self.actor_gid = nil
+        self.actor_type = nil
+      else
+        self.actor_gid = record.to_global_id.to_s
+        self.actor_type = record.class.name
+      end
+    end
+
+    def actor
+      return nil if actor_gid.blank?
+      GlobalID::Locator.locate(actor_gid)
+    rescue ActiveRecord::RecordNotFound
+      nil
+    end
+
+    # -- Target assignment via GlobalID --
+
+    def target=(record)
+      if record.nil?
+        self.target_gid = nil
+        self.target_type = nil
+      else
+        self.target_gid = record.to_global_id.to_s
+        self.target_type = record.class.name
+      end
+    end
+
+    def target
+      return nil if target_gid.blank?
+      GlobalID::Locator.locate(target_gid)
+    rescue ActiveRecord::RecordNotFound
+      nil
+    end
+
+    # -- Scope assignment via GlobalID --
+
+    def scope=(record)
+      if record.nil?
+        self.scope_gid = nil
+        self.scope_type = nil
+      else
+        self.scope_gid = record.to_global_id.to_s
+        self.scope_type = record.class.name
+      end
+    end
+
+    def scope
+      return nil if scope_gid.blank?
+      GlobalID::Locator.locate(scope_gid)
+    rescue ActiveRecord::RecordNotFound
+      nil
+    end
+
+    # -- Query scopes --
+
+    scope :for_actor, ->(record) { where(actor_gid: record.to_global_id.to_s) }
+    scope :by_actor_type, ->(type) { where(actor_type: type.is_a?(Class) ? type.name : type.to_s) }
+    scope :for_target, ->(record) { where(target_gid: record.to_global_id.to_s) }
+    scope :by_target_type, ->(type) { where(target_type: type.is_a?(Class) ? type.name : type.to_s) }
+    scope :for_scope, ->(record) { where(scope_gid: record.to_global_id.to_s) }
+    scope :by_scope_type, ->(type) { where(scope_type: type.is_a?(Class) ? type.name : type.to_s) }
+    scope :by_event_type, ->(event_type) { where(event_type: event_type) }
+    scope :matching_event, ->(pattern) { where("event_type LIKE ?", pattern) }
+    scope :between, ->(start_time, end_time) { where(occurred_at: start_time..end_time) }
+    scope :since, ->(time) { where("occurred_at >= ?", time) }
+    scope :before, ->(time) { where("occurred_at < ?", time) }
+    scope :today, -> { where(occurred_at: Time.current.beginning_of_day..Time.current.end_of_day) }
+    scope :yesterday, -> { where(occurred_at: 1.day.ago.beginning_of_day..1.day.ago.end_of_day) }
+    scope :this_week, -> { where(occurred_at: Time.current.beginning_of_week..Time.current.end_of_week) }
+    scope :this_month, -> { where(occurred_at: Time.current.beginning_of_month..Time.current.end_of_month) }
+    scope :last_n_days, ->(n) { where("occurred_at >= ?", n.days.ago.beginning_of_day) }
+    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 :recent, ->(n = 10) { reverse_chronological.limit(n) }
+
+    # -- GDPR methods --
+
+    def self.anonymize_actor!(record)
+      gid = record.to_global_id.to_s
+      logs = where("actor_gid = ? OR target_gid = ?", gid, gid)
+      count = logs.count
+
+      anonymizable_keys = StandardAudit.config.anonymizable_metadata_keys.map(&:to_s)
+
+      logs.find_each do |log|
+        attrs = {
+          ip_address: nil,
+          user_agent: nil,
+          session_id: nil
+        }
+
+        attrs[:actor_gid] = "[anonymized]" if log.actor_gid == gid
+        attrs[:actor_type] = "[anonymized]" if log.actor_gid == gid
+        attrs[:target_gid] = "[anonymized]" if log.target_gid == gid
+        attrs[:target_type] = "[anonymized]" if log.target_gid == gid
+
+        if log.metadata.present? && anonymizable_keys.any?
+          cleaned_metadata = log.metadata.reject { |k, _| anonymizable_keys.include?(k.to_s) }
+          attrs[:metadata] = cleaned_metadata
+        end
+
+        log.update_columns(attrs)
+      end
+
+      count
+    end
+
+    def self.export_for_actor(record)
+      gid = record.to_global_id.to_s
+      logs = where("actor_gid = ? OR target_gid = ?", gid, gid).chronological
+
+      records = logs.map do |log|
+        {
+          id: log.id,
+          event_type: log.event_type,
+          actor_gid: log.actor_gid,
+          target_gid: log.target_gid,
+          scope_gid: log.scope_gid,
+          metadata: log.metadata,
+          occurred_at: log.occurred_at.iso8601,
+          ip_address: log.ip_address,
+          user_agent: log.user_agent,
+          request_id: log.request_id
+        }
+      end
+
+      {
+        subject: gid,
+        exported_at: Time.current.iso8601,
+        total_records: records.size,
+        records: records
+      }
+    end
+
+    private
+
+    def assign_uuid
+      self.id = SecureRandom.uuid
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+StandardAudit::Engine.routes.draw do
+end

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

@@ -0,0 +1,20 @@
+module StandardAudit
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def copy_migration
+        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"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+class CreateAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :audit_logs, id: :uuid do |t|
+      t.string :actor_gid
+      t.string :actor_type
+      t.string :target_gid
+      t.string :target_type
+      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.string :session_id
+      t.json :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, [: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, :session_id
+  end
+end

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

@@ -0,0 +1,37 @@
+StandardAudit.configure do |config|
+  # Subscribe to ActiveSupport::Notifications patterns
+  # config.subscribe_to "audit.**"
+
+  # Actor extractor from notification payload
+  # config.actor_extractor = ->(payload) { payload[:actor] }
+
+  # Target extractor from notification payload
+  # config.target_extractor = ->(payload) { payload[:target] }
+
+  # Scope extractor from notification payload
+  # config.scope_extractor = ->(payload) { payload[:scope] }
+
+  # Fallback resolvers (used when payload values are nil)
+  # config.current_actor_resolver = -> { Current.user }
+  # config.current_request_id_resolver = -> { Current.request_id }
+  # config.current_ip_address_resolver = -> { Current.ip_address }
+  # 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]
+
+  # Run audit log creation in background job
+  # config.async = false
+  # config.queue_name = :default
+
+  # Enable/disable audit logging
+  # config.enabled = true
+
+  # GDPR: metadata keys to strip on anonymization
+  # config.anonymizable_metadata_keys = %i[email name ip_address]
+
+  # Data retention
+  # config.retention_days = nil
+  # config.auto_cleanup = false
+end

data/lib/standard_audit/audit_scope.rb

@@ -0,0 +1,9 @@
+module StandardAudit
+  module AuditScope
+    extend ActiveSupport::Concern
+
+    def scoped_audit_logs
+      StandardAudit::AuditLog.for_scope(self)
+    end
+  end
+end

data/lib/standard_audit/auditable.rb

@@ -0,0 +1,29 @@
+module StandardAudit
+  module Auditable
+    extend ActiveSupport::Concern
+
+    def audit_logs_as_actor
+      StandardAudit::AuditLog.for_actor(self)
+    end
+
+    def audit_logs_as_target
+      StandardAudit::AuditLog.for_target(self)
+    end
+
+    def audit_logs
+      gid = to_global_id.to_s
+      StandardAudit::AuditLog.where("actor_gid = ? OR target_gid = ?", gid, gid)
+    end
+
+    def record_audit(event_type, target: nil, scope: nil, metadata: {}, **options)
+      StandardAudit.record(
+        event_type,
+        actor: self,
+        target: target,
+        scope: scope,
+        metadata: metadata,
+        **options
+      )
+    end
+  end
+end

data/lib/standard_audit/configuration.rb

@@ -0,0 +1,52 @@
+module StandardAudit
+  class Configuration
+    attr_accessor :async, :queue_name, :enabled,
+                  :actor_extractor, :target_extractor, :scope_extractor,
+                  :current_actor_resolver, :current_request_id_resolver,
+                  :current_ip_address_resolver, :current_user_agent_resolver,
+                  :current_session_id_resolver,
+                  :sensitive_keys, :metadata_builder,
+                  :anonymizable_metadata_keys, :retention_days, :auto_cleanup
+
+    def initialize
+      @subscriptions = []
+      @async = false
+      @queue_name = :default
+      @enabled = true
+
+      @actor_extractor = ->(payload) { payload[:actor] }
+      @target_extractor = ->(payload) { payload[:target] }
+      @scope_extractor = ->(payload) { payload[:scope] }
+
+      @current_actor_resolver = -> {
+        defined?(Current) && Current.respond_to?(:user) ? Current.user : nil
+      }
+      @current_request_id_resolver = -> {
+        defined?(Current) && Current.respond_to?(:request_id) ? Current.request_id : nil
+      }
+      @current_ip_address_resolver = -> {
+        defined?(Current) && Current.respond_to?(:ip_address) ? Current.ip_address : nil
+      }
+      @current_user_agent_resolver = -> {
+        defined?(Current) && Current.respond_to?(:user_agent) ? Current.user_agent : nil
+      }
+      @current_session_id_resolver = -> {
+        defined?(Current) && Current.respond_to?(:session_id) ? Current.session_id : nil
+      }
+
+      @sensitive_keys = %i[password password_confirmation token secret]
+      @metadata_builder = nil
+      @anonymizable_metadata_keys = %i[email name ip_address]
+      @retention_days = nil
+      @auto_cleanup = false
+    end
+
+    def subscribe_to(pattern)
+      @subscriptions << pattern
+    end
+
+    def subscriptions
+      @subscriptions.dup.freeze
+    end
+  end
+end

data/lib/standard_audit/engine.rb

@@ -0,0 +1,11 @@
+module StandardAudit
+  class Engine < ::Rails::Engine
+    isolate_namespace StandardAudit
+
+    initializer "standard_audit.subscriber" do
+      ActiveSupport.on_load(:active_record) do
+        StandardAudit.subscriber.setup!
+      end
+    end
+  end
+end

data/lib/standard_audit/subscriber.rb

@@ -0,0 +1,87 @@
+module StandardAudit
+  class Subscriber
+    attr_reader :subscriptions
+
+    def initialize
+      @subscriptions = []
+    end
+
+    def setup!
+      config = StandardAudit.config
+      config.subscriptions.each do |pattern|
+        subscriber = ActiveSupport::Notifications.subscribe(pattern) do |event|
+          handle_event(event)
+        end
+        @subscriptions << subscriber
+      end
+    end
+
+    def teardown!
+      @subscriptions.each do |subscriber|
+        ActiveSupport::Notifications.unsubscribe(subscriber)
+      end
+      @subscriptions.clear
+    end
+
+    private
+
+    def handle_event(event)
+      return unless StandardAudit.config.enabled
+
+      config = StandardAudit.config
+      payload = event.payload
+
+      actor = config.actor_extractor.call(payload)
+      target = config.target_extractor.call(payload)
+      scope = config.scope_extractor.call(payload)
+
+      # Fall back to Current attributes when payload values are nil
+      actor ||= config.current_actor_resolver.call
+
+      metadata = extract_metadata(payload, config)
+
+      attrs = {
+        event_type: event.name,
+        occurred_at: Time.current,
+        request_id: payload[:request_id] || config.current_request_id_resolver.call,
+        ip_address: payload[:ip_address] || config.current_ip_address_resolver.call,
+        user_agent: payload[:user_agent] || config.current_user_agent_resolver.call,
+        session_id: payload[:session_id] || config.current_session_id_resolver.call,
+        metadata: metadata
+      }
+
+      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)
+      else
+        log = StandardAudit::AuditLog.new(attrs)
+        log.actor = actor
+        log.target = target
+        log.scope = scope
+        log.save!
+      end
+    rescue => e
+      Rails.logger.error("[StandardAudit] Error creating audit log: #{e.message}")
+    end
+
+    def extract_metadata(payload, config)
+      # Remove known non-metadata keys
+      excluded_keys = %i[actor target scope request_id ip_address user_agent session_id]
+      raw_metadata = payload.except(*excluded_keys)
+
+      if config.metadata_builder
+        raw_metadata = config.metadata_builder.call(raw_metadata)
+      end
+
+      # Filter sensitive keys
+      sensitive = config.sensitive_keys.map(&:to_s)
+      raw_metadata.reject { |k, _| sensitive.include?(k.to_s) }
+    end
+  end
+end

data/lib/standard_audit/version.rb

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

data/lib/standard_audit.rb

@@ -0,0 +1,74 @@
+require "standard_audit/version"
+require "standard_audit/engine"
+require "standard_audit/configuration"
+require "standard_audit/subscriber"
+require "standard_audit/auditable"
+require "standard_audit/audit_scope"
+
+module StandardAudit
+  class << self
+    def configure
+      yield(config) if block_given?
+    end
+
+    def config
+      @configuration ||= Configuration.new
+    end
+
+    def record(event_type, actor: nil, target: nil, scope: nil, metadata: {}, **options)
+      return unless config.enabled
+
+      actor ||= config.current_actor_resolver.call
+
+      # Filter sensitive keys
+      sensitive = config.sensitive_keys.map(&:to_s)
+      filtered_metadata = metadata.reject { |k, _| sensitive.include?(k.to_s) }
+
+      attrs = {
+        event_type: event_type,
+        occurred_at: Time.current,
+        request_id: options[:request_id] || config.current_request_id_resolver.call,
+        ip_address: options[:ip_address] || config.current_ip_address_resolver.call,
+        user_agent: options[:user_agent] || config.current_user_agent_resolver.call,
+        session_id: options[:session_id] || config.current_session_id_resolver.call,
+        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
+
+      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)
+      else
+        log = StandardAudit::AuditLog.new(attrs)
+        log.actor = actor
+        log.target = target
+        log.scope = scope
+        log.save!
+        log
+      end
+    end
+
+    def subscriber
+      @subscriber ||= Subscriber.new
+    end
+
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+end

data/lib/tasks/standard_audit_tasks.rake

@@ -0,0 +1,71 @@
+namespace :standard_audit do
+  desc "Delete audit logs older than specified days (default: 90)"
+  task :cleanup, [:days] => :environment do |_t, args|
+    days = (args[:days] || StandardAudit.config.retention_days || 90).to_i
+    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"
+  task :archive, [:days, :output] => :environment do |_t, args|
+    days = (args[:days] || 90).to_i
+    output = args[:output] || "audit_logs_archive_#{Date.current}.json"
+    cutoff = days.days.ago
+
+    logs = StandardAudit::AuditLog.where("occurred_at < ?", cutoff)
+
+    File.open(output, "w") do |f|
+      logs.find_each do |log|
+        f.puts log.attributes.to_json
+      end
+    end
+
+    puts "Archived #{logs.count} logs to #{output}"
+  end
+
+  desc "Show audit log statistics"
+  task stats: :environment do
+    total = StandardAudit::AuditLog.count
+    today = StandardAudit::AuditLog.today.count
+    this_week = StandardAudit::AuditLog.this_week.count
+
+    by_type = StandardAudit::AuditLog
+      .group(:event_type)
+      .order(count_all: :desc)
+      .limit(10)
+      .count
+
+    puts "Audit Log Statistics"
+    puts "===================="
+    puts "Total: #{total}"
+    puts "Today: #{today}"
+    puts "This week: #{this_week}"
+    puts ""
+    puts "Top 10 Event Types:"
+    by_type.each { |type, count| puts "  #{type}: #{count}" }
+  end
+
+  desc "Anonymize audit logs for a specific actor (GDPR right to erasure)"
+  task :anonymize_actor, [:actor_gid] => :environment do |_t, args|
+    raise "actor_gid is required" unless args[:actor_gid].present?
+
+    count = StandardAudit::AuditLog.anonymize_actor!(args[:actor_gid])
+    puts "Anonymized #{count} audit logs for #{args[:actor_gid]}"
+  end
+
+  desc "Export audit logs for a specific actor (GDPR right to access)"
+  task :export_actor, [:actor_gid, :output] => :environment do |_t, args|
+    raise "actor_gid is required" unless args[:actor_gid].present?
+    output = args[:output] || "audit_export_#{Date.current}.json"
+
+    data = StandardAudit::AuditLog.export_for_actor(args[:actor_gid])
+
+    File.open(output, "w") do |f|
+      f.puts JSON.pretty_generate(data)
+    end
+
+    puts "Exported #{data[:total_records]} audit logs to #{output}"
+  end
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: standard_audit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jaryl Sim
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: globalid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: StandardAudit is a standalone Rails gem for database-backed audit logging
+  via ActiveSupport::Notifications. Generic, flexible, and works with any Rails application.
+email:
+- code@jaryl.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/jobs/standard_audit/create_audit_log_job.rb
+- app/models/standard_audit/application_record.rb
+- app/models/standard_audit/audit_log.rb
+- config/routes.rb
+- lib/generators/standard_audit/install/install_generator.rb
+- lib/generators/standard_audit/install/templates/create_audit_logs.rb.erb
+- lib/generators/standard_audit/install/templates/initializer.rb.erb
+- lib/standard_audit.rb
+- lib/standard_audit/audit_scope.rb
+- lib/standard_audit/auditable.rb
+- lib/standard_audit/configuration.rb
+- lib/standard_audit/engine.rb
+- lib/standard_audit/subscriber.rb
+- lib/standard_audit/version.rb
+- lib/tasks/standard_audit_tasks.rake
+homepage: https://github.com/rarebit-one/standard_audit
+licenses:
+- MIT
+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
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Database-backed audit logging for Rails via ActiveSupport::Notifications.
+test_files: []