standard_audit 0.7.0 → 0.9.0

data/lib/standard_audit/rspec/operation.rb

@@ -0,0 +1,136 @@
+require "standard_audit"
+
+# RSpec shared examples for the operation-audit contract.
+#
+# A THIN layer over StandardAudit::Operation::Audit — every example below is a
+# one-line call to a plain-Ruby predicate plus a failure message. If the shape
+# of these examples doesn't fit your app, call the predicates directly from a
+# bespoke spec and skip this file; nothing here is load-bearing.
+#
+#   require "standard_audit/rspec/operation"
+#
+#   RSpec.describe "Operation audit declarations" do
+#     it_behaves_like "standard_audit operation declarations",
+#       source:         "/app/operations/",
+#       minimum:        100,
+#       orphans_within: -> { AuditCatalogue::OPERATION_ACTIONS }
+#   end
+#
+# Options (all optional):
+#
+#   source:         path fragment scoping the check to your own operations.
+#                   Strongly recommended — without it, any class anywhere that
+#                   includes the module is held to the contract.
+#   minimum:        registry floor. THE MOST IMPORTANT OPTION. Without it, an
+#                   app where someone stopped including the module — or where
+#                   eager loading silently stopped reaching `app/operations/` —
+#                   passes every other example vacuously against an empty set.
+#                   Set it just below your real count.
+#   expected:       Array of class names that must be registered. A second,
+#                   sharper form of the same protection.
+#   orphans_within: the catalogue slice operations are responsible for, as an
+#                   Array or a callable. Use it when your catalogue also covers
+#                   writers outside `app/operations/` (a controller concern, a
+#                   tool server, a notification-bus name), which would otherwise
+#                   always look orphaned. Omit to skip the orphan check;
+#                   pass `:catalogue` to check the whole catalogue.
+#   eager_load:     force `Rails.application.eager_load!` first so the registry
+#                   is complete regardless of the test env's setting.
+#                   Defaults to true.
+RSpec.shared_examples "standard_audit operation declarations" do |options = {}|
+  source         = options[:source]
+  minimum        = options[:minimum]
+  expected       = Array(options[:expected])
+  orphans_within = options[:orphans_within]
+  eager_load     = options.fetch(:eager_load, true)
+
+  audit = StandardAudit::Operation::Audit
+
+  before(:all) do
+    Rails.application.eager_load! if eager_load && defined?(Rails) && Rails.application
+  end
+
+  let(:operations) { audit.operations(source: source) }
+
+  it "sees the operations it is supposed to check" do
+    if expected.any?
+      expect(operations.map(&:name)).to include(*expected)
+    end
+
+    if minimum
+      expect(operations.size).to be >= minimum,
+        "Expected at least #{minimum} registered operations#{source ? " under #{source}" : ""}, " \
+        "found #{operations.size}. Every other example in this group passes vacuously against " \
+        "an empty set, so this is almost certainly a wiring failure — an operation that stopped " \
+        "including StandardAudit::Operation, or eager loading no longer reaching them."
+    end
+
+    skip("no `minimum:` or `expected:` given — nothing to assert") if minimum.nil? && expected.empty?
+  end
+
+  it "requires every operation to declare `audits` or `audit_none!`" do
+    undeclared = audit.undeclared(operations: operations)
+
+    expect(undeclared).to be_empty,
+      "These operations declare neither `audits` nor `audit_none!`:\n  " \
+      "#{undeclared.map(&:name).sort.join("\n  ")}\n" \
+      "Add `audits \"some.action\"` if it records an audit, or `audit_none!` " \
+      "(with the reason in a comment) if it deliberately doesn't."
+  end
+
+  it "only declares actions present in the audit catalogue" do
+    unknown = audit.unknown_actions(operations: operations)
+
+    skip("no `config.audit_catalogue` configured") if audit.catalogue.nil?
+
+    expect(unknown).to be_empty,
+      "These operations declare audit actions missing from the catalogue " \
+      "(add them to it):\n  " \
+      "#{unknown.map { |klass, actions| "#{klass.name}: #{actions.inspect}" }.join("\n  ")}"
+  end
+
+  it "has no duplicate catalogue entries" do
+    skip("no `config.audit_catalogue` configured") if audit.catalogue.nil?
+
+    dupes = audit.duplicate_catalogue_entries
+
+    expect(dupes).to be_empty, "duplicate audit catalogue entries: #{dupes.inspect}"
+  end
+
+  it "operations that declare `audits` call `audit!`" do
+    missing = audit.missing_write_sites(operations: operations)
+
+    expect(missing).to be_empty,
+      "These operations declare `audits` but never call `audit!`:\n  " \
+      "#{missing.map(&:name).sort.join("\n  ")}"
+  end
+
+  it "operations that declare `audit_none!` do not call `audit!`" do
+    writing = audit.unexpected_write_sites(operations: operations)
+
+    expect(writing).to be_empty,
+      "These operations declare `audit_none!` but call `audit!`:\n  " \
+      "#{writing.map(&:name).sort.join("\n  ")}"
+  end
+
+  it "has no catalogued action that no operation writes" do
+    skip("no `orphans_within:` given") if orphans_within.nil?
+
+    within =
+      if orphans_within == :catalogue
+        nil
+      elsif orphans_within.respond_to?(:call)
+        orphans_within.call
+      else
+        orphans_within
+      end
+
+    skip("no `config.audit_catalogue` configured") if within.nil? && audit.catalogue.nil?
+
+    orphans = audit.orphan_actions(operations: operations, within: within)
+
+    expect(orphans).to be_empty,
+      "These catalogued actions are declared by no operation — wire them or " \
+      "drop them: #{orphans.inspect}"
+  end
+end

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.7.0"
+  VERSION = "0.9.0"
 end

data/lib/standard_audit.rb

@@ -6,6 +6,7 @@ require "standard_audit/sensitive_keys_dry_run"
 require "standard_audit/subscriber"
 require "standard_audit/event_subscriber"
 require "standard_audit/reference_preloading"
+require "standard_audit/operation"
 require "standard_audit/auditable"
 require "standard_audit/audit_scope"
 require "standard_audit/checks/retention"
@@ -153,10 +154,8 @@ module StandardAudit
 
     def flush_batch(buffer)
       now = Time.current
-      previous_checksum = StandardAudit::AuditLog
-        .order(created_at: :desc, id: :desc)
-        .limit(1)
-        .pick(:checksum)
+      records_parent = StandardAudit::AuditLog.chain_parent_column?
+      previous_checksum = StandardAudit::AuditLog.chain_tip_checksum
 
       # Generate sorted UUIDs to ensure batch ordering matches id ordering.
       # UUIDv7 within the same millisecond can have non-monotonic lower bits;
@@ -175,6 +174,7 @@ module StandardAudit
           row.stringify_keys,
           previous_checksum: previous_checksum
         )
+        row[:previous_checksum] = previous_checksum if records_parent
         row[:checksum] = checksum
         previous_checksum = checksum
         row

data/lib/tasks/standard_audit_tasks.rake

@@ -63,16 +63,34 @@ namespace :standard_audit do
     puts "============================="
     puts "Records verified: #{result[:verified]}"
     puts "Chain valid: #{result[:valid]}"
+    puts "Forked links recovered: #{result[:recovered]}"
 
     if result[:failures].any?
-      puts "\nTampered records detected: #{result[:failures].size}"
+      puts "\nUnverifiable records detected: #{result[:failures].size}"
       result[:failures].each do |failure|
-        puts "  #{failure[:id]} (#{failure[:event_type]}) at #{failure[:created_at]}"
+        puts "  #{failure[:id]} (#{failure[:event_type]}) at #{failure[:created_at]} — #{failure[:reason]}"
       end
       abort "Chain verification failed"
     end
   end
 
+  desc "Record the parent digest each existing row was signed against (never re-signs)"
+  task relink_checksums: :environment do
+    unless StandardAudit::AuditLog.chain_parent_column?
+      abort "audit_logs has no previous_checksum column — run `rails generate standard_audit:add_previous_checksum` first"
+    end
+
+    result = StandardAudit::AuditLog.relink_checksums!
+
+    puts "Relinked: #{result[:relinked]}"
+    puts "Left as-is (already linked, or a segment root): #{result[:skipped]}"
+    puts "Unresolved: #{result[:unresolved]}"
+    puts ""
+    puts "No checksum was rewritten. A parent is recorded only when it reproduces"
+    puts "the digest the row has held since it was written; unresolved rows keep"
+    puts "failing verification, which is the point."
+  end
+
   desc "Backfill checksums for records that don't have them"
   task backfill_checksums: :environment do
     count = StandardAudit::AuditLog.backfill_checksums!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -99,6 +99,8 @@ files:
 - 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/add_previous_checksum/add_previous_checksum_generator.rb
+- lib/generators/standard_audit/add_previous_checksum/templates/add_previous_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
@@ -110,8 +112,11 @@ files:
 - lib/standard_audit/engine.rb
 - lib/standard_audit/event_subscriber.rb
 - lib/standard_audit/metadata_filter.rb
+- lib/standard_audit/operation.rb
+- lib/standard_audit/operation/audit.rb
 - lib/standard_audit/reference_preloading.rb
 - lib/standard_audit/rspec.rb
+- lib/standard_audit/rspec/operation.rb
 - lib/standard_audit/sensitive_keys_dry_run.rb
 - lib/standard_audit/subscriber.rb
 - lib/standard_audit/version.rb