standard_audit 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c400c65330d8896079475becca2eedc20481027bd23a9e6c35d1aa6011e46762
-  data.tar.gz: e5757a3734ccecaa266b0e17f537f53c51d26cebd6b6fdcc0022db758d31935e
+  metadata.gz: ae2015728333aa6f6549bf138de8c27017c78c23f0d930ab3df9cf73c99b14cf
+  data.tar.gz: 6e479ec25dcb88c2538a23efbec0796762b4274fd0baa2c5ad6707f57e90b65d
 SHA512:
-  metadata.gz: f03510f5f6f9c6ba1e47e189da9d29e9c1a6d720886fb149c4938f4612581bd4049b87e61d1a67a36c7a27cb4ca1a147c3f9984c17ee090980d236fa632531c3
-  data.tar.gz: faf25861c62875fb9e89b97c938a5ed1730982f3f8a48b40c694a3ee26f9941c9832085a1dc75420d4a7085c0cb03aff0b1474ea59e3a29a4386297d9fb6c879
+  metadata.gz: d3ec930cf81109adf17c563d15dba60a0e82ab33bcb0cb6ce422009f5b157b8d1335c46da73269053ed3e09e8169bbada9c548409080871d6dd9e3c928b65ce8
+  data.tar.gz: 64906fb08b3d97c7e25626790c32fcf6eb08885cd4c0d5f7cf22a6acf9bd2516101f768fe90d93bfd3db4a3120f726b1e63eaa49036beffcf513d139f68d58f8

data/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/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/version.rb

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

data/lib/standard_audit.rb

@@ -102,12 +102,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.3.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -82,6 +82,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