standard_audit 0.12.1 → 0.13.1

data/lib/standard_audit/checksum.rb

@@ -0,0 +1,208 @@
+require "json"
+require "openssl"
+
+module StandardAudit
+  # The row digest. There are two algorithms; which one a row uses is decided
+  # by its `created_at` against `config.canonical_checksum_since` (default
+  # StandardAudit::CANONICAL_CHECKSUM_CUTOVER), at write time and again at
+  # verification, from the same stored timestamp. Nothing extra is stored.
+  #
+  # == Legacy (rows created before the cutover)
+  #
+  # `SHA256("<parent>|field=value|field=value|…")`, where a Hash value was
+  # serialised with `to_json` in whatever key order the Ruby hash had. That is
+  # the bug in fundbright/delivery-ops#689: at write time the hash is the one
+  # the caller built (insertion order), but PostgreSQL `jsonb` — and MySQL
+  # `JSON` — store object keys in their own order (shortest first, then
+  # bytewise), so the value read back serialises differently and the digest
+  # cannot be reproduced. SQLite keeps JSON as text, so the gem's own suite
+  # never saw it. Kept byte-for-byte so legacy rows are verified exactly as
+  # they were signed.
+  #
+  # == Canonical (rows created at or after the cutover)
+  #
+  # `SHA256(canonical_json({"fields" => {…}, "previous_checksum" => …, "v" => 2}))`.
+  # Every input is reduced to a form the database cannot change:
+  #
+  # * Hash / Array values (the `metadata` jsonb column, or any other JSON
+  #   column a host adds to the hashed set) are first round-tripped through
+  #   `ActiveSupport::JSON.encode` + `JSON.parse` — the same encoding the
+  #   column type applies on write — so symbol keys, Time values, BigDecimals
+  #   and the like hash as the JSON the database actually stores. Object keys
+  #   are then sorted bytewise at every depth; array order is kept (arrays are
+  #   ordered in every JSON store).
+  # * Integral floats hash as integers (`1.0` → `1`, `1e20` →
+  #   `100000000000000000000`), because a JSON store is free to hand back
+  #   either spelling of the same number.
+  # * Times hash as UTC ISO 8601 with microseconds, as in the legacy digest.
+  # * Strings are escaped at the byte level (`"`, `\` and C0 controls only),
+  #   so the output does not depend on the json gem's escaping options.
+  # * nil stays `null`, distinct from `""` — the legacy digest conflated them.
+  # * Fields are encoded as a JSON object rather than joined with `|`, so a
+  #   value containing `|field=` can no longer move content between adjacent
+  #   fields without changing the digest.
+  #
+  # Known limit: a host with `ActiveSupport.parse_json_times = true` reads
+  # ISO 8601 strings in JSON back as Time objects, which re-encode at
+  # millisecond precision in the app's zone. A metadata string that was not
+  # already in that exact form would then hash differently on read. The
+  # setting is off by default.
+  module Checksum
+    LEGACY = 1
+    CANONICAL = 2
+    ALGORITHMS = [LEGACY, CANONICAL].freeze
+
+    TIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%6NZ".freeze
+    ESCAPE = /["\\\x00-\x1f]/n
+
+    module_function
+
+    # The algorithm for a row created at `created_at`: canonical at or after
+    # `config.canonical_checksum_since`, legacy before it. A row not yet
+    # timestamped is judged by the current time — what a write now would use.
+    def algorithm_for(created_at)
+      created_at ||= Time.current
+      created_at >= StandardAudit.config.canonical_checksum_since ? CANONICAL : LEGACY
+    end
+
+    def digest(attrs, fields:, previous_checksum: nil, version:)
+      digester(attrs, fields: fields, version: version).call(previous_checksum)
+    end
+
+    # A callable `parent -> digest` for one row. The row's own serialisation
+    # is built once, so trying many candidate parents (the recovery search)
+    # costs one SHA-256 each.
+    def digester(attrs, fields:, version:)
+      case version
+      when LEGACY then legacy_digester(attrs, fields: fields)
+      when CANONICAL then canonical_digester(attrs, fields: fields)
+      else raise ArgumentError, "unknown checksum algorithm #{version.inspect} (known: #{ALGORITHMS.join(", ")})"
+      end
+    end
+
+    # The legacy digest, unchanged since 0.3. Do not "fix" this: it is how
+    # every pre-cutover row is signed, and it must keep reproducing them.
+    def legacy_digest(attrs, fields:, previous_checksum: nil)
+      legacy_digester(attrs, fields: fields).call(previous_checksum)
+    end
+
+    def legacy_digester(attrs, fields:)
+      canonical = fields.map { |f|
+        value = attrs[f]
+        value = value.to_json if value.is_a?(Hash)
+        value = value.utc.strftime(TIME_FORMAT) if time_like?(value)
+        "#{f}=#{value}"
+      }.join("|")
+
+      lambda do |previous_checksum|
+        input = previous_checksum.present? ? "#{previous_checksum}|#{canonical}" : canonical
+        OpenSSL::Digest::SHA256.hexdigest(input)
+      end
+    end
+
+    def canonical_digest(attrs, fields:, previous_checksum: nil)
+      canonical_digester(attrs, fields: fields).call(previous_checksum)
+    end
+
+    # SHA-256 of canonical_json(canonical_payload(...)). The payload's keys
+    # sort as "fields" < "previous_checksum" < "v", so the row's part is
+    # serialised once and only the parent is spliced in per call — the
+    # result is byte-identical to serialising the whole payload.
+    def canonical_digester(attrs, fields:)
+      head = String.new("{\"fields\":", encoding: Encoding::BINARY)
+      canonical_json(fields.to_h { |f| [f, canonical_value(attrs[f])] }, head)
+      head << ",\"previous_checksum\":"
+      tail = ",\"v\":#{CANONICAL}}"
+
+      lambda do |previous_checksum|
+        parent = previous_checksum.presence
+        OpenSSL::Digest::SHA256.hexdigest(head + (parent ? json_string(parent.to_s, String.new(encoding: Encoding::BINARY)) : "null") + tail)
+      end
+    end
+
+    # The documented canonical payload for a row ("v" => 2 names the format), as a plain Hash.
+    def canonical_payload(attrs, fields:, previous_checksum: nil)
+      {
+        "fields" => fields.to_h { |f| [f, canonical_value(attrs[f])] },
+        "previous_checksum" => previous_checksum.presence,
+        "v" => CANONICAL
+      }
+    end
+
+    # The stored-form value of one field, before canonical encoding.
+    def canonical_value(value)
+      case value
+      when nil, String, Integer, Float, true, false then value
+      when Hash, Array then json_round_trip(value)
+      else time_like?(value) ? value.utc.strftime(TIME_FORMAT) : value.to_s
+      end
+    end
+
+    # What a JSON column hands back for `value`: encoded exactly as
+    # ActiveRecord's JSON type encodes on write, then parsed. Key ORDER is
+    # the one thing this does not settle — canonical_json does.
+    def json_round_trip(value)
+      JSON.parse(ActiveSupport::JSON.encode(value), max_nesting: false, create_additions: false)
+    end
+
+    # Deterministic JSON: object keys sorted bytewise at every depth, no
+    # whitespace, integral floats as integers, byte-level string escaping.
+    # Returns a binary String.
+    def canonical_json(value, out = String.new(encoding: Encoding::BINARY))
+      case value
+      when Hash
+        out << "{"
+        value.map { |k, v| [k.to_s.b, v] }.sort_by(&:first).each_with_index do |(k, v), i|
+          out << "," if i.positive?
+          json_string(k, out)
+          out << ":"
+          canonical_json(v, out)
+        end
+        out << "}"
+      when Array
+        out << "["
+        value.each_with_index do |v, i|
+          out << "," if i.positive?
+          canonical_json(v, out)
+        end
+        out << "]"
+      when nil then out << "null"
+      when true then out << "true"
+      when false then out << "false"
+      when Integer then out << value.to_s
+      when Float then out << (value.finite? && value == value.floor ? value.to_i.to_s : value.to_s)
+      else json_string(value.to_s, out)
+      end
+      out
+    end
+
+    def json_string(string, out)
+      out << '"'
+      out << string.b.gsub(ESCAPE) do |c|
+        case c
+        when '"' then '\\"'
+        when "\\" then "\\\\"
+        else format("\\u%04x", c.ord)
+        end
+      end
+      out << '"'
+    end
+
+    def time_like?(value)
+      value.respond_to?(:strftime) && value.respond_to?(:utc)
+    end
+
+    # True when some JSON object inside `value` has more than one key, i.e.
+    # a store that reorders keys could have changed how the legacy digest serialised
+    # it. A row with no such object cannot fail the legacy digest because of key order.
+    def key_order_ambiguous?(value)
+      case value
+      when Hash then value.size > 1 || value.each_value.any? { |v| key_order_ambiguous?(v) }
+      when Array then value.any? { |v| key_order_ambiguous?(v) }
+      else false
+      end
+    end
+  end
+end
+
+require "standard_audit/checksum/key_order_search"

data/lib/standard_audit/configuration.rb

@@ -13,7 +13,8 @@ module StandardAudit
                   :anonymizable_metadata_keys, :retention_days,
                   :audit_catalogue, :verify_audit_declarations,
                   :raise_on_audit_write_error, :audit_write_error_handler,
-                  :audit_error_context_key
+                  :audit_error_context_key, :error_reporter,
+                  :canonical_checksum_since
 
     def initialize
       @subscriptions = []
@@ -128,6 +129,16 @@ module StandardAudit
       # computed. See Configuration#before_checksum.
       @before_checksum_hooks = []
 
+      # Rows whose `created_at` is at or after this time are signed with the
+      # canonical checksum (object keys sorted, independent of how jsonb
+      # stores them) and verified strictly with it; earlier rows keep the
+      # legacy algorithm. Defaults to StandardAudit::CANONICAL_CHECKSUM_CUTOVER.
+      # Override only if your rollout of this release slips past that date,
+      # set it BEFORE the new time arrives, and never change it afterwards:
+      # verification recomputes the same decision from each row's stored
+      # created_at, so moving it re-judges rows under the other algorithm.
+      @canonical_checksum_since = StandardAudit::CANONICAL_CHECKSUM_CUTOVER
+
       @anonymizable_metadata_keys = %i[email name ip_address]
 
       # ── StandardAudit::Operation (the operation-audit DSL) ────────────────
@@ -191,6 +202,27 @@ module StandardAudit
       # improvement to the built-in reporter. Default keeps existing behaviour.
       @audit_error_context_key = :audit_action
 
+      # Where the gem sends the errors it swallows: a failed subscriber write,
+      # a failed `record(raise: false)`, a raising `before_checksum` hook, and
+      # a failed `audit!` write under the default report-and-swallow policy.
+      # A callable taking `(error, context)`, where context is a Hash such as
+      # `{ audit_action: "orders.created", subscriber: "StandardAudit::Subscriber" }`
+      # (keyed by `audit_error_context_key`).
+      #
+      # nil (the default) means `Rails.error.report(error, handled: true,
+      # context: context)`. That reaches Sentry only when a `Rails.error`
+      # subscriber is registered (sentry-rails registers one); a host that
+      # never forwards `Rails.error` can point this straight at its tracker:
+      #
+      #   config.error_reporter = ->(error, context) { Sentry.capture_exception(error, extra: context) }
+      #
+      # It replaces the built-in `Rails.error` call; call `Rails.error.report`
+      # from it too if you want both. A reporter that raises is logged and
+      # ignored, so it can never turn a swallowed audit failure into a raised
+      # one. `audit_write_error_handler`, when set, still takes precedence for
+      # `audit!` write failures.
+      @error_reporter = nil
+
       # Retention defaults from ENV so it can be set per-environment without a
       # code change. Unset/blank/non-positive => nil (infinite retention, the
       # compliance-safe default that never auto-deletes). A host app can still

data/lib/standard_audit/engine.rb

@@ -1,7 +1,10 @@
 module StandardAudit
+  # A plain (non-isolated) engine: it contributes the AuditLog model, the two
+  # jobs and the subscriber wiring, and has no routes, controllers or views.
+  # 0.13.0 dropped `isolate_namespace` and the empty `config/routes.rb` it
+  # carried. Nothing depended on them: AuditLog sets its own `table_name`, and
+  # no host mounted the engine.
   class Engine < ::Rails::Engine
-    isolate_namespace StandardAudit
-
     initializer "standard_audit.subscriber" do
       ActiveSupport.on_load(:active_record) do
         StandardAudit.subscriber.setup!

data/lib/standard_audit/event_subscriber.rb

@@ -47,7 +47,8 @@ module StandardAudit
           ip_address: context[:ip_address] || payload[:ip_address],
           user_agent: context[:user_agent] || payload[:user_agent],
           session_id: context[:session_id] || payload[:session_id]
-        }
+        },
+        via: :rails_event
       )
     rescue => e
       StandardAudit.report_write_error(e, name, subscriber: self.class.name)

data/lib/standard_audit/operation/audit.rb

@@ -282,13 +282,9 @@ module StandardAudit
           message = "[StandardAudit] Failed to record #{action}: #{error.class} #{error.message}"
           Rails.logger&.error(message) if defined?(Rails) && Rails.respond_to?(:logger)
 
-          return unless defined?(Rails) && Rails.respond_to?(:error) && Rails.error
-
-          Rails.error.report(
+          StandardAudit.report_error(
             error,
-            handled: true,
-            context: { StandardAudit.config.audit_error_context_key => action,
-                       operation: operation.class.name }
+            { StandardAudit.config.audit_error_context_key => action, operation: operation.class.name }
           )
         end
       end

data/lib/standard_audit/rspec/baseline.rb

@@ -18,12 +18,19 @@ require "standard_audit"
 #       catalogue: -> { AuditCatalogue::ACTIONS },
 #       sensitive_keys: %i[source_payload],
 #       sensitive_key_patterns: [/secret/i],
-#       present: %i[metadata_builder before_write current_scope_resolver]
+#       present: %i[metadata_builder before_write current_scope_resolver],
+#       hooks: 2   # or %i[backfill_scope classify_actor]
 #   end
 #
 # Every option is optional. Behaviour held in lambdas (resolvers, builders)
 # can't be compared by value, so list them under `present:` to assert they
 # survive a reset, and keep an app-specific example for what they return.
+#
+# `hooks:` covers `before_checksum` hooks, which live in a list rather than a
+# named setting. Pass an Integer to assert exactly that many are registered,
+# or an Array of the Symbol hook names (`config.before_checksum :name`) to
+# assert each is registered. The mutation example also clears the hooks
+# before the reset, so it fails if the baseline block doesn't re-add them.
 RSpec.shared_examples "a standard_audit baseline" do |options = {}|
   subscriptions          = Array(options[:subscriptions])
   settings               = options.fetch(:settings, {})
@@ -31,9 +38,14 @@ RSpec.shared_examples "a standard_audit baseline" do |options = {}|
   sensitive_keys         = Array(options[:sensitive_keys])
   sensitive_key_patterns = Array(options[:sensitive_key_patterns])
   present                = Array(options[:present])
+  hooks                  = options[:hooks]
+
+  unless hooks.nil? || hooks.is_a?(Integer) || (hooks.is_a?(Array) && hooks.all? { |h| h.is_a?(Symbol) || h.is_a?(String) })
+    raise ArgumentError, "hooks: must be an Integer (hook count) or an Array of Symbol hook names; got #{hooks.inspect}"
+  end
 
   def standard_audit_baseline_assertions(subscriptions:, settings:, catalogue:, sensitive_keys:,
-    sensitive_key_patterns:, present:)
+    sensitive_key_patterns:, present:, hooks:)
     config = StandardAudit.config
 
     expect(config.subscriptions).to include(*subscriptions) if subscriptions.any?
@@ -49,11 +61,22 @@ RSpec.shared_examples "a standard_audit baseline" do |options = {}|
     present.each do |name|
       expect(config.public_send(name)).not_to be_nil, "expected config.#{name} to survive a reset"
     end
+    case hooks
+    when Integer
+      expect(config.before_checksum_hooks.size).to eq(hooks),
+        "expected #{hooks} before_checksum hook(s) after a reset, found #{config.before_checksum_hooks.size}"
+    when Array
+      registered = config.before_checksum_hooks.select { |h| h.is_a?(Symbol) || h.is_a?(String) }.map(&:to_sym)
+      hooks.map(&:to_sym).each do |name|
+        expect(registered).to include(name), "expected before_checksum :#{name} to survive a reset"
+      end
+    end
   end
 
   let(:standard_audit_baseline_options) do
     { subscriptions: subscriptions, settings: settings, catalogue: catalogue,
-      sensitive_keys: sensitive_keys, sensitive_key_patterns: sensitive_key_patterns, present: present }
+      sensitive_keys: sensitive_keys, sensitive_key_patterns: sensitive_key_patterns, present: present,
+      hooks: hooks }
   end
 
   it "is registered with configure(baseline: true)" do
@@ -71,6 +94,7 @@ RSpec.shared_examples "a standard_audit baseline" do |options = {}|
     StandardAudit.config.subscribe_to "standard_audit.isolation_canary"
     settings.each_key { |name| StandardAudit.config.public_send(:"#{name}=", nil) }
     present.each { |name| StandardAudit.config.public_send(:"#{name}=", nil) }
+    StandardAudit.config.before_checksum_hooks = [] unless hooks.nil?
 
     StandardAudit.reset_configuration!
 

data/lib/standard_audit/subscriber.rb

@@ -46,7 +46,8 @@ module StandardAudit
         target: config.target_extractor.call(payload),
         scope: config.scope_extractor.call(payload),
         metadata: payload.except(*EXCLUDED_PAYLOAD_KEYS),
-        context: payload.slice(:request_id, :ip_address, :user_agent, :session_id)
+        context: payload.slice(:request_id, :ip_address, :user_agent, :session_id),
+        via: :notification
       )
     rescue => e
       StandardAudit.report_write_error(e, event.name, subscriber: self.class.name)

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.12.1"
+  VERSION = "0.13.1"
 end

data/lib/standard_audit.rb

@@ -1,6 +1,17 @@
 require "standard_audit/version"
+
+module StandardAudit
+  # From this instant (by each row's `created_at`) new rows get the canonical
+  # checksum and are verified strictly with it; earlier rows are legacy. See
+  # StandardAudit::Checksum and fundbright/delivery-ops#689. Every host must
+  # run 0.13.1+ BEFORE this time: an older gem still writing after it produces
+  # legacy-hashed rows that fail strict canonical verification.
+  # Overridable per host via `config.canonical_checksum_since`.
+  CANONICAL_CHECKSUM_CUTOVER = Time.utc(2026, 10, 1, 0, 0, 0).freeze
+end
 require "standard_audit/engine"
 require "standard_audit/configuration"
+require "standard_audit/checksum"
 require "standard_audit/metadata_filter"
 require "standard_audit/record_reference"
 require "standard_audit/sensitive_keys_dry_run"
@@ -17,6 +28,16 @@ module StandardAudit
   # `sensitive_keys` even if a user adds them there.
   RESERVED_METADATA_KEYS = %w[_tags _source].freeze
 
+  # Values of `entry[:via]` as `before_write` sees it:
+  #
+  # * `:direct` — `StandardAudit.record` without a block, and therefore
+  #   `Auditable#record_audit` and `Operation#audit!`.
+  # * `:notification` — the ActiveSupport::Notifications subscriber
+  #   (`subscribe_to` patterns, and `StandardAudit.record` WITH a block, which
+  #   instruments the event and lets this subscriber write it).
+  # * `:rails_event` — the `Rails.event` subscriber (Rails 8.1+).
+  VIA = %i[direct notification rails_event].freeze
+
   class << self
     # Applies configuration to the single mutable Configuration instance.
     #
@@ -58,7 +79,8 @@ module StandardAudit
     # here), so it records only when the event is subscribed to.
     #
     # `raise: false` makes a failed write non-fatal: the error is logged and
-    # reported to `Rails.error` as handled, and nil is returned. For call
+    # reported through `config.error_reporter` (default: `Rails.error`, as
+    # handled), and nil is returned. For call
     # sites where a missing audit row must never break the request (auth
     # failure logging, say). It governs only the audit write — in block form
     # the subscriber already rescues, and the block's own errors always
@@ -80,7 +102,7 @@ module StandardAudit
 
       begin
         write_entry(event_type, actor: actor, target: target, scope: scope,
-          metadata: metadata, context: options)
+          metadata: metadata, context: options, via: :direct)
       rescue => e
         raise if raise_errors
 
@@ -96,7 +118,11 @@ module StandardAudit
     # values; nil entries fall back to the Current resolvers. `reserved` is
     # merged into metadata AFTER `metadata_builder` (the Rails.event subscriber
     # uses it for `_tags` / `_source`, which a builder never saw before 0.12).
-    def write_entry(event_type, actor:, target:, scope:, metadata:, context: {}, reserved: {})
+    # `via` names the entry point (see VIA) and is handed to `before_write`
+    # as `entry[:via]`; it is not persisted.
+    def write_entry(event_type, actor:, target:, scope:, metadata:, context: {}, reserved: {}, via: :direct)
+      raise ArgumentError, "via must be one of #{VIA.inspect}; got #{via.inspect}" unless VIA.include?(via)
+
       actor ||= config.current_actor_resolver.call
       scope ||= config.current_scope_resolver&.call
 
@@ -113,14 +139,16 @@ module StandardAudit
         request_id: context[:request_id] || config.current_request_id_resolver.call,
         ip_address: context[:ip_address] || config.current_ip_address_resolver.call,
         user_agent: context[:user_agent] || config.current_user_agent_resolver.call,
-        session_id: context[:session_id] || config.current_session_id_resolver.call
+        session_id: context[:session_id] || config.current_session_id_resolver.call,
+        via: via
       }
 
-      # Runs on EVERY path, before redaction, so anything it injects into
-      # metadata is still subject to `sensitive_keys` and dereferencing. It may
-      # mutate `entry` in place; its return value is ignored. It may raise —
-      # that is how a host guard rejects a write — and the error propagates
-      # exactly as a failed save would.
+      # Runs on EVERY path, AFTER `metadata_builder` and before redaction, so
+      # it sees the builder's output and anything it injects into metadata is
+      # still subject to `sensitive_keys` and dereferencing. It may mutate
+      # `entry` in place; its return value is ignored. It may raise — that is
+      # how a host guard rejects a write — and the error propagates exactly as
+      # a failed save would. `entry[:via]` says which entry point wrote it.
       config.before_write&.call(entry)
 
       persist(entry)
@@ -147,20 +175,29 @@ module StandardAudit
       Thread.current[:standard_audit_batch] = previous
     end
 
-    # @api private — logs a failed audit write and reports it to Rails.error
-    # as handled. Used by the subscribers, which must never let an audit
-    # failure break the instrumented code path.
+    # @api private — logs a failed audit write and reports it through
+    # `report_error`. Used by the subscribers, which must never let an audit
+    # failure break the instrumented code path, and by `record(raise: false)`.
     def report_write_error(error, event_type, **context)
       Rails.logger.error("[StandardAudit] Error creating audit log for #{event_type}: #{error.class}: #{error.message}")
-      return unless Rails.respond_to?(:error) && Rails.error
+      report_error(error, { config.audit_error_context_key => event_type, **context })
+    end
 
-      Rails.error.report(
-        error,
-        handled: true,
-        context: { config.audit_error_context_key => event_type, **context }
-      )
+    # @api private — the one place the gem reports an error it swallows.
+    # Calls `config.error_reporter` when set, otherwise
+    # `Rails.error.report(error, handled: true, context:)`. A reporter that
+    # raises is logged and ignored.
+    def report_error(error, context)
+      if config.error_reporter
+        config.error_reporter.call(error, context)
+      elsif defined?(Rails) && Rails.respond_to?(:error) && Rails.error
+        Rails.error.report(error, handled: true, context: context)
+      end
+      nil
     rescue => report_failure
-      Rails.logger.error("[StandardAudit] Error reporting audit failure: #{report_failure.class}: #{report_failure.message}")
+      message = "[StandardAudit] Error reporting audit failure: #{report_failure.class}: #{report_failure.message}"
+      Rails.logger&.error(message) if defined?(Rails) && Rails.respond_to?(:logger)
+      nil
     end
 
     def subscriber
@@ -260,6 +297,8 @@ module StandardAudit
           created_at: now,
           updated_at: now
         ))
+        # created_at is set above, so the algorithm is decided by the same
+        # stored timestamp verification will read.
         checksum = StandardAudit::AuditLog.compute_checksum_value(
           row.stringify_keys,
           previous_checksum: previous_checksum

data/lib/tasks/standard_audit_tasks.rake

@@ -85,17 +85,34 @@ namespace :standard_audit do
 
   desc "Verify audit log chain integrity (tamper detection)"
   task verify: :environment do
-    result = StandardAudit::AuditLog.verify_chain
+    # FAIL_ON_LEGACY_UNVERIFIABLE=1 — treat pre-cutover rows whose metadata
+    # key order cannot be reconstructed as failures (see
+    # AuditLog.verify_chain). KEY_ORDER_SEARCH_LIMIT=5040 — orderings tried
+    # per legacy row.
+    options = {}
+    options[:fail_on_legacy_unverifiable] = true if %w[1 true].include?(ENV["FAIL_ON_LEGACY_UNVERIFIABLE"])
+    if (limit = ENV["KEY_ORDER_SEARCH_LIMIT"].presence)
+      options[:key_order_search_limit] = Integer(limit, 10)
+    end
+
+    result = StandardAudit::AuditLog.verify_chain(**options)
 
     puts "Audit Log Chain Verification"
     puts "============================="
+    puts "Canonical checksums since: #{StandardAudit.config.canonical_checksum_since.utc.iso8601}"
     puts "Records verified: #{result[:verified]}"
     puts "Chain valid: #{result[:valid]}"
     puts "Forked links recovered: #{result[:recovered]}"
+    puts "Legacy rows verified by key-order reconstruction: #{result[:reordered]}" if result[:reordered].to_i.positive?
     puts "Anonymized (redacted) records: #{result[:redacted]}" if result[:redacted].to_i.positive?
+    if result[:legacy_unverifiable].to_i.positive?
+      puts "Legacy rows unverifiable (metadata key order lost): #{result[:legacy_unverifiable]} " \
+           "— cannot be proven either way; this count must not grow after the cutover"
+    end
 
     if result[:failures].any?
       puts "\nUnverifiable records detected: #{result[:failures].size}"
+      result[:failures].map { |failure| failure[:reason] }.tally.each { |reason, n| puts "  #{reason}: #{n}" }
       result[:failures].each do |failure|
         puts "  #{failure[:id]} (#{failure[:event_type]}) at #{failure[:created_at]} — #{failure[:reason]}"
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.1
 platform: ruby
 authors:
 - Jaryl Sim
@@ -15,42 +15,42 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: activejob
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: globalid
   requirement: !ruby/object:Gem::Requirement
@@ -96,20 +96,20 @@ files:
 - 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/add_anonymized_at/add_anonymized_at_generator.rb
 - lib/generators/standard_audit/add_anonymized_at/templates/add_anonymized_at_to_audit_logs.rb.erb
-- 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
+- lib/generators/standard_audit/migration_number.rb
 - lib/standard_audit.rb
 - lib/standard_audit/audit_scope.rb
 - lib/standard_audit/auditable.rb
 - lib/standard_audit/checks/retention.rb
+- lib/standard_audit/checksum.rb
+- lib/standard_audit/checksum/key_order_search.rb
 - lib/standard_audit/configuration.rb
 - lib/standard_audit/engine.rb
 - lib/standard_audit/event_subscriber.rb
@@ -148,7 +148,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Database-backed audit logging for Rails via Rails.event and ActiveSupport::Notifications.
 test_files: []

data/config/routes.rb

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