standard_audit 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c400c65330d8896079475becca2eedc20481027bd23a9e6c35d1aa6011e46762
-  data.tar.gz: e5757a3734ccecaa266b0e17f537f53c51d26cebd6b6fdcc0022db758d31935e
+  metadata.gz: 6a9a29ab9754c6dbc24134d000864e8d99f60966227691ee782b782423ac7dc7
+  data.tar.gz: 0ee9864f7b073c3376041facfafe575006179b443937883377a5bdda605bc81a
 SHA512:
-  metadata.gz: f03510f5f6f9c6ba1e47e189da9d29e9c1a6d720886fb149c4938f4612581bd4049b87e61d1a67a36c7a27cb4ca1a147c3f9984c17ee090980d236fa632531c3
-  data.tar.gz: faf25861c62875fb9e89b97c938a5ed1730982f3f8a48b40c694a3ee26f9941c9832085a1dc75420d4a7085c0cb03aff0b1474ea59e3a29a4386297d9fb6c879
+  metadata.gz: e156d464655ca40f791b064e264b18ac587b63819f454d8bc98b9b7a9168cbd02519795c14d0333cd148be191715d29498244d1218f505365a1ef669c6f591fe
+  data.tar.gz: 2816bb0d249b20d8464cde9655b5799d8b7525cba615b9a97528bd9ef78ca1b1254fd528bca77ac3390001bdf34adc384add86c5b924d43a2e93bf695620ae89

data/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-19
+
+### Added
+
+- Rails 8.1+ structured event reporter (`Rails.event`) integration. A new `StandardAudit::EventSubscriber` is registered automatically when `Rails.event` is available, so `Rails.event.notify("myapp.orders.created", actor: user, target: order)` persists an `AuditLog` the same way an `ActiveSupport::Notifications.instrument` call does. Event name is matched against the existing `subscribe_to` patterns (supports `*`, `**`, and `Regexp`). `Rails.event.set_context(...)` values take precedence over the `Current.*` resolvers for `request_id`, `ip_address`, `user_agent`, and `session_id`. `Rails.event.tagged(...)` and `source_location` are captured under the reserved metadata keys `_tags` and `_source`.
+
+## [0.3.0] - 2026-03-31
+
+### Added
+
+- Tamper detection via chained SHA-256 checksums — each record's `checksum` column hashes its content plus the previous record's checksum
+- `AuditLog.verify_chain` to walk the chain and detect modified records
+- `AuditLog.backfill_checksums!` to retroactively checksum pre-existing records
+- Rake tasks: `standard_audit:verify` (exits non-zero on failure) and `standard_audit:backfill_checksums`
+- Upgrade generator: `rails g standard_audit:add_checksums` adds the checksum column and created_at index
+
+### Changed
+
+- Primary keys now use UUIDv7 (time-ordered) instead of UUIDv4 for deterministic chain ordering
+- Batch inserts (`StandardAudit.batch`) now compute chained checksums
+
+### Upgrade
+
+Run the upgrade generator to add the checksum column:
+
+```bash
+rails generate standard_audit:add_checksums
+rails db:migrate
+```
+
+Optionally backfill checksums for existing records:
+
+```bash
+rake standard_audit:backfill_checksums
+```
+
 ## [0.2.0] - 2026-03-25
 
 ### Added

data/README.md

@@ -52,11 +52,38 @@ StandardAudit::AuditLog.for_actor(current_user).this_week
 
 ## Recording Events
 
-StandardAudit provides three ways to record audit events.
+StandardAudit provides four ways to record audit events. On Rails 8.1+, prefer `Rails.event` — it is the standard Rails interface for structured events.
+
+### Rails.event (Rails 8.1+)
+
+StandardAudit registers a `Rails.event` subscriber at boot, so any `notify` call whose name matches a configured `subscribe_to` pattern is persisted automatically:
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action do
+    Rails.event.set_context(
+      request_id: request.request_id,
+      ip_address: request.remote_ip,
+      user_agent: request.user_agent
+    )
+  end
+end
+
+Rails.event.tagged("checkout") do
+  Rails.event.notify("myapp.orders.created",
+    actor: current_user,
+    target: @order,
+    scope: current_organisation,
+    total: @order.total
+  )
+end
+```
+
+`Rails.event.set_context` values override the `Current.*` resolvers for `request_id`, `ip_address`, `user_agent`, and `session_id`. Tags and `source_location` are captured as metadata under the reserved keys `_tags` and `_source`.
 
 ### Convenience API
 
-The simplest approach — call `StandardAudit.record` directly:
+Call `StandardAudit.record` directly:
 
 ```ruby
 StandardAudit.record("orders.created",
@@ -71,7 +98,7 @@ When `actor` is omitted, it falls back to the configured `current_actor_resolver
 
 ### ActiveSupport::Notifications
 
-Instrument events and let the subscriber handle persistence:
+For Rails < 8.1, or when `Rails.event` is unavailable, instrument events via `ActiveSupport::Notifications`:
 
 ```ruby
 ActiveSupport::Notifications.instrument("myapp.orders.created", {

data/app/models/standard_audit/audit_log.rb

@@ -1,8 +1,17 @@
+require "openssl"
+
 module StandardAudit
   class AuditLog < ApplicationRecord
     self.table_name = "audit_logs"
 
+    CHECKSUM_FIELDS = %w[
+      id event_type actor_gid actor_type target_gid target_type
+      scope_gid scope_type metadata request_id ip_address
+      user_agent session_id occurred_at
+    ].freeze
+
     before_create :assign_uuid, if: -> { id.blank? }
+    before_create :compute_checksum, if: -> { checksum.blank? }
     after_create_commit :emit_created_event
 
     # Audit logs are append-only. Use update_columns for privileged
@@ -156,6 +165,95 @@ module StandardAudit
       }
     end
 
+    # 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)
+      self.class.compute_checksum_value(
+        attributes.slice(*CHECKSUM_FIELDS),
+        previous_checksum: previous_checksum
+      )
+    end
+
+    def self.compute_checksum_value(attrs, previous_checksum: nil)
+      canonical = CHECKSUM_FIELDS.map { |f|
+        value = attrs[f]
+        value = value.to_json if value.is_a?(Hash)
+        value = value.utc.strftime("%Y-%m-%dT%H:%M:%S.%6NZ") if value.respond_to?(:strftime) && value.respond_to?(:utc)
+        "#{f}=#{value}"
+      }.join("|")
+
+      canonical = "#{previous_checksum}|#{canonical}" if previous_checksum.present?
+
+      OpenSSL::Digest::SHA256.hexdigest(canonical)
+    end
+
+    # Verifies the integrity of the audit log chain. Returns a result hash with
+    # :valid (boolean), :verified (count), and :failures (array of hashes).
+    #
+    # Records are processed in (created_at, id) order. Records without a
+    # checksum (pre-feature data) reset the chain — the next checksummed
+    # record starts a new independent chain segment.
+    def self.verify_chain(scope: nil, batch_size: 1000)
+      relation = scope ? where(scope_gid: scope.to_global_id.to_s) : all
+
+      previous_checksum = nil
+      verified = 0
+      failures = []
+
+      relation.in_batches(of: batch_size) do |batch|
+        batch.order(created_at: :asc, id: :asc).each do |record|
+          if record.checksum.blank?
+            previous_checksum = nil
+            next
+          end
+
+          expected = record.compute_checksum_value(previous_checksum: previous_checksum)
+
+          if record.checksum != expected
+            failures << {
+              id: record.id,
+              event_type: record.event_type,
+              created_at: record.created_at,
+              expected: expected,
+              actual: record.checksum
+            }
+          end
+
+          verified += 1
+          previous_checksum = record.checksum
+        end
+      end
+
+      { valid: failures.empty?, verified: verified, failures: failures }
+    end
+
+    # Backfills checksums for records that don't have them (e.g. pre-existing
+    # records before the checksum feature was added).
+    def self.backfill_checksums!(batch_size: 1000)
+      previous_checksum = nil
+      count = 0
+
+      in_batches(of: batch_size) do |batch|
+        batch.order(created_at: :asc, id: :asc).each do |record|
+          if record.checksum.present?
+            previous_checksum = record.checksum
+            next
+          end
+
+          new_checksum = compute_checksum_value(
+            record.attributes.slice(*CHECKSUM_FIELDS),
+            previous_checksum: previous_checksum
+          )
+          record.update_columns(checksum: new_checksum)
+
+          previous_checksum = new_checksum
+          count += 1
+        end
+      end
+
+      count
+    end
+
     private
 
     def emit_created_event
@@ -170,8 +268,17 @@ module StandardAudit
       Rails.logger.warn("[StandardAudit] Failed to emit event: #{e.class}: #{e.message}")
     end
 
+    # Fetches the most recent record's checksum and chains the new record to it.
+    # Note: concurrent inserts can read the same "previous" record, forking
+    # the chain. Use database-level advisory locks if you need serializable
+    # chain integrity under concurrent writes.
+    def compute_checksum
+      previous = self.class.order(created_at: :desc, id: :desc).limit(1).pick(:checksum)
+      self.checksum = compute_checksum_value(previous_checksum: previous)
+    end
+
     def assign_uuid
-      self.id = SecureRandom.uuid
+      self.id = SecureRandom.uuid_v7
     end
   end
 end

data/lib/generators/standard_audit/add_checksums/add_checksums_generator.rb

@@ -0,0 +1,16 @@
+module StandardAudit
+  module Generators
+    class AddChecksumsGenerator < 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 "add_checksum_to_audit_logs.rb.erb", "db/migrate/add_checksum_to_audit_logs.rb"
+      end
+    end
+  end
+end

data/lib/generators/standard_audit/add_checksums/templates/add_checksum_to_audit_logs.rb.erb

@@ -0,0 +1,6 @@
+class AddChecksumToAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :audit_logs, :checksum, :string, limit: 64
+    add_index :audit_logs, :created_at
+  end
+end

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

@@ -16,6 +16,7 @@ class CreateAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.curr
       t.string :session_id
       t.jsonb :metadata, default: {}
       t.datetime :occurred_at, null: false
+      t.string :checksum, limit: 64
       t.timestamps
     end
 
@@ -25,6 +26,7 @@ class CreateAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.curr
     add_index :audit_logs, [:scope_type, :scope_gid]
     add_index :audit_logs, :request_id
     add_index :audit_logs, [:occurred_at, :created_at]
+    add_index :audit_logs, :created_at
     add_index :audit_logs, :session_id
     # GIN index requires PostgreSQL; remove if using another database
     add_index :audit_logs, :metadata, using: :gin

data/lib/standard_audit/engine.rb

@@ -5,6 +5,12 @@ module StandardAudit
     initializer "standard_audit.subscriber" do
       ActiveSupport.on_load(:active_record) do
         StandardAudit.subscriber.setup!
+
+        # Rails 8.1+ structured event reporter. Feature-detected so the gem
+        # still works on older Rails versions that only have AS::Notifications.
+        if Rails.respond_to?(:event) && Rails.event.respond_to?(:subscribe)
+          Rails.event.subscribe(StandardAudit.event_subscriber)
+        end
       end
     end
   end

data/lib/standard_audit/event_subscriber.rb

@@ -0,0 +1,101 @@
+module StandardAudit
+  # Subscriber for Rails 8.1+ structured event reporting (`Rails.event`).
+  #
+  # Registered with `Rails.event.subscribe(...)` so that every `Rails.event.notify`
+  # call flows through StandardAudit for persistence. Events whose name does not
+  # match any configured `subscribe_to` pattern are ignored.
+  #
+  # Payload is extracted with the same extractors used by the
+  # ActiveSupport::Notifications subscriber. Rails.event `context` supplies
+  # request_id/ip_address/user_agent/session_id and takes precedence over the
+  # Current.* resolvers. Tags and source_location are captured as metadata
+  # under the reserved keys `_tags` and `_source`.
+  class EventSubscriber
+    RESERVED_PAYLOAD_KEYS = %i[actor target scope request_id ip_address user_agent session_id].freeze
+
+    def initialize
+      @pattern_cache = {}
+      @pattern_cache_mutex = Mutex.new
+    end
+
+    def emit(event)
+      return unless StandardAudit.config.enabled
+
+      name = event[:name]
+      return if name.nil?
+      return unless matches_subscription?(name)
+
+      config  = StandardAudit.config
+      payload = event[:payload] || {}
+      context = event[:context] || {}
+
+      actor  = config.actor_extractor.call(payload)
+      target = config.target_extractor.call(payload)
+      scope  = config.scope_extractor.call(payload)
+
+      metadata = build_metadata(payload, event[:tags], event[:source_location], config)
+
+      StandardAudit.record(
+        name,
+        actor: actor,
+        target: target,
+        scope: scope,
+        metadata: metadata,
+        request_id: context[:request_id] || payload[:request_id],
+        ip_address: context[:ip_address] || payload[:ip_address],
+        user_agent: context[:user_agent] || payload[:user_agent],
+        session_id: context[:session_id] || payload[:session_id]
+      )
+    rescue => e
+      Rails.logger.error("[StandardAudit] Error handling Rails.event: #{e.class}: #{e.message}")
+    end
+
+    private
+
+    def matches_subscription?(name)
+      StandardAudit.config.subscriptions.any? { |pattern| pattern_match?(pattern, name) }
+    end
+
+    # Supports the same pattern shapes as ActiveSupport::Notifications.subscribe:
+    # a Regexp, or a String with `*` matching a single segment and `**` matching
+    # the remainder.
+    def pattern_match?(pattern, name)
+      case pattern
+      when Regexp
+        pattern.match?(name)
+      when String
+        compiled_pattern_for(pattern).match?(name)
+      else
+        false
+      end
+    end
+
+    def compiled_pattern_for(pattern)
+      cached = @pattern_cache[pattern]
+      return cached if cached
+
+      @pattern_cache_mutex.synchronize do
+        @pattern_cache[pattern] ||= Regexp.new(
+          "\\A" + Regexp.escape(pattern).gsub('\\*\\*', ".*").gsub('\\*', "[^.]*") + "\\z"
+        )
+      end
+    end
+
+    # `_tags` and `_source` are reserved metadata keys owned by this
+    # subscriber. Sensitive-key filtering is handled downstream by
+    # `StandardAudit.record`, so we don't re-run it here.
+    def build_metadata(payload, tags, source_location, config)
+      reserved = RESERVED_PAYLOAD_KEYS.map(&:to_s)
+      raw = payload.reject { |k, _| reserved.include?(k.to_s) }
+      raw = config.metadata_builder.call(raw) if config.metadata_builder
+
+      if tags.is_a?(Hash) && tags.any?
+        raw[:_tags] = tags
+      elsif tags && !tags.is_a?(Hash)
+        Rails.logger.warn("[StandardAudit] Dropping Rails.event tags of unexpected type: #{tags.class}")
+      end
+      raw[:_source] = source_location if source_location
+      raw
+    end
+  end
+end

data/lib/standard_audit/subscriber.rb

@@ -67,7 +67,7 @@ module StandardAudit
         log.save!
       end
     rescue => e
-      Rails.logger.error("[StandardAudit] Error creating audit log: #{e.message}")
+      Rails.logger.error("[StandardAudit] Error creating audit log: #{e.class}: #{e.message}")
     end
 
     def extract_metadata(payload, config)

data/lib/standard_audit/version.rb

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

data/lib/standard_audit.rb

@@ -2,10 +2,15 @@ require "standard_audit/version"
 require "standard_audit/engine"
 require "standard_audit/configuration"
 require "standard_audit/subscriber"
+require "standard_audit/event_subscriber"
 require "standard_audit/auditable"
 require "standard_audit/audit_scope"
 
 module StandardAudit
+  # Metadata keys owned internally by StandardAudit. Never filtered by
+  # `sensitive_keys` even if a user adds them there.
+  RESERVED_METADATA_KEYS = %w[_tags _source].freeze
+
   class << self
     def configure
       yield(config) if block_given?
@@ -20,8 +25,9 @@ module StandardAudit
 
       actor ||= config.current_actor_resolver.call
 
-      # Filter sensitive keys
-      sensitive = config.sensitive_keys.map(&:to_s)
+      # Filter sensitive keys. `_tags` and `_source` are reserved internal
+      # metadata keys owned by EventSubscriber and are never stripped.
+      sensitive = config.sensitive_keys.map(&:to_s) - RESERVED_METADATA_KEYS
       filtered_metadata = metadata.reject { |k, _| sensitive.include?(k.to_s) }
 
       attrs = {
@@ -90,6 +96,10 @@ module StandardAudit
       @subscriber ||= Subscriber.new
     end
 
+    def event_subscriber
+      @event_subscriber ||= EventSubscriber.new
+    end
+
     def reset_configuration!
       @configuration = nil
     end
@@ -102,12 +112,31 @@ module StandardAudit
 
     def flush_batch(buffer)
       now = Time.current
-      rows = buffer.map do |attrs|
-        attrs.merge(
-          id: SecureRandom.uuid,
+      previous_checksum = StandardAudit::AuditLog
+        .order(created_at: :desc, id: :desc)
+        .limit(1)
+        .pick(:checksum)
+
+      # Generate sorted UUIDs to ensure batch ordering matches id ordering.
+      # UUIDv7 within the same millisecond can have non-monotonic lower bits;
+      # sorting guarantees the chain order matches the id order used by
+      # verify_chain. Under very high throughput this is a best-effort
+      # guarantee — see compute_checksum's concurrency note.
+      ids = buffer.size.times.map { SecureRandom.uuid_v7 }.sort
+
+      rows = buffer.each_with_index.map do |attrs, i|
+        row = attrs.merge(
+          id: ids[i],
           created_at: now,
           updated_at: now
         )
+        checksum = StandardAudit::AuditLog.compute_checksum_value(
+          row.stringify_keys,
+          previous_checksum: previous_checksum
+        )
+        row[:checksum] = checksum
+        previous_checksum = checksum
+        row
       end
 
       StandardAudit::AuditLog.insert_all!(rows)

data/lib/tasks/standard_audit_tasks.rake

@@ -55,6 +55,30 @@ namespace :standard_audit do
     puts "Anonymized #{count} audit logs for #{args[:actor_gid]}"
   end
 
+  desc "Verify audit log chain integrity (tamper detection)"
+  task verify: :environment do
+    result = StandardAudit::AuditLog.verify_chain
+
+    puts "Audit Log Chain Verification"
+    puts "============================="
+    puts "Records verified: #{result[:verified]}"
+    puts "Chain valid: #{result[:valid]}"
+
+    if result[:failures].any?
+      puts "\nTampered records detected: #{result[:failures].size}"
+      result[:failures].each do |failure|
+        puts "  #{failure[:id]} (#{failure[:event_type]}) at #{failure[:created_at]}"
+      end
+      abort "Chain verification failed"
+    end
+  end
+
+  desc "Backfill checksums for records that don't have them"
+  task backfill_checksums: :environment do
+    count = StandardAudit::AuditLog.backfill_checksums!
+    puts "Backfilled checksums for #{count} audit log records"
+  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?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -65,8 +65,9 @@ dependencies:
     - - ">="
       - !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.
+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.
 email:
 - code@jaryl.dev
 executables: []
@@ -82,6 +83,8 @@ files:
 - app/models/standard_audit/application_record.rb
 - app/models/standard_audit/audit_log.rb
 - config/routes.rb
+- lib/generators/standard_audit/add_checksums/add_checksums_generator.rb
+- lib/generators/standard_audit/add_checksums/templates/add_checksum_to_audit_logs.rb.erb
 - 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
@@ -90,6 +93,7 @@ files:
 - lib/standard_audit/auditable.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/subscriber.rb
 - lib/standard_audit/version.rb
@@ -118,5 +122,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Database-backed audit logging for Rails via ActiveSupport::Notifications.
+summary: Database-backed audit logging for Rails via Rails.event and ActiveSupport::Notifications.
 test_files: []