standard_audit 0.7.0 → 0.9.0

data/lib/generators/standard_audit/add_previous_checksum/add_previous_checksum_generator.rb

@@ -0,0 +1,17 @@
+module StandardAudit
+  module Generators
+    class AddPreviousChecksumGenerator < 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_previous_checksum_to_audit_logs.rb.erb",
+          "db/migrate/add_previous_checksum_to_audit_logs.rb"
+      end
+    end
+  end
+end

data/lib/generators/standard_audit/add_previous_checksum/templates/add_previous_checksum_to_audit_logs.rb.erb

@@ -0,0 +1,23 @@
+class AddPreviousChecksumToAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    # On PostgreSQL with a large audit_logs table, add
+    # `disable_ddl_transaction!` above and pass `algorithm: :concurrently` to
+    # the add_index calls — StrongMigrations will ask for it.
+    #
+    # Nullable and index-only: no data is rewritten. Existing rows keep a NULL
+    # parent and are verified by position and parent recovery, exactly as they
+    # are today. Run `rake standard_audit:relink_checksums` afterwards to
+    # record the parent each existing row was actually signed against.
+    add_column :audit_logs, :previous_checksum, :string, limit: 64
+    # Not used by the gem itself: verification reads previous_checksum off rows
+    # it has already loaded. It is here for forensics — "what forked off this
+    # row?" — which is the question you ask once verification flags something.
+    add_index :audit_logs, :previous_checksum
+    # verify_chain / backfill_checksums! walk the table with a keyset cursor
+    # ordered by (created_at, id).
+    add_index :audit_logs, [:created_at, :id] unless index_exists?(:audit_logs, [:created_at, :id])
+    # verify_chain looks a declared parent up by digest when it falls outside
+    # the in-memory recovery window — the path that reports a removed row.
+    add_index :audit_logs, :checksum unless index_exists?(:audit_logs, :checksum)
+  end
+end

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

@@ -17,6 +17,10 @@ class CreateAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.curr
       t.jsonb :metadata, default: {}
       t.datetime :occurred_at, null: false
       t.string :checksum, limit: 64
+      # The digest of the row this one was chained to. Concurrent writers can
+      # share a parent, so the log is a DAG rather than a strict line; storing
+      # the parent is what keeps every row verifiable when it forks.
+      t.string :previous_checksum, limit: 64
       t.timestamps
     end
 
@@ -27,6 +31,17 @@ class CreateAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.curr
     add_index :audit_logs, :request_id
     add_index :audit_logs, [:occurred_at, :created_at]
     add_index :audit_logs, :created_at
+    # verify_chain / backfill_checksums! walk the table with a keyset cursor
+    # ordered by (created_at, id); the composite index makes each page an index
+    # range scan rather than a scan plus filter.
+    add_index :audit_logs, [:created_at, :id]
+    # verify_chain looks a declared parent up by digest when it falls outside
+    # the in-memory recovery window — the path that reports a removed row.
+    add_index :audit_logs, :checksum
+    # Not used by the gem itself: verification reads previous_checksum off rows
+    # it has already loaded. It is here for forensics — "what forked off this
+    # row?" — which is the question you ask once verification flags something.
+    add_index :audit_logs, :previous_checksum
     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/configuration.rb

@@ -8,7 +8,9 @@ module StandardAudit
                   :sensitive_keys, :sensitive_key_patterns,
                   :sensitive_key_exceptions, :filter_nested_metadata,
                   :metadata_builder, :before_checksum_hooks,
-                  :anonymizable_metadata_keys, :retention_days
+                  :anonymizable_metadata_keys, :retention_days,
+                  :audit_catalogue, :verify_audit_declarations,
+                  :raise_on_audit_write_error, :audit_write_error_handler
 
     def initialize
       @subscriptions = []
@@ -78,6 +80,50 @@ module StandardAudit
 
       @anonymizable_metadata_keys = %i[email name ip_address]
 
+      # ── StandardAudit::Operation (the operation-audit DSL) ────────────────
+
+      # The host's canonical action vocabulary, used by `audit!` to reject an
+      # action absent from it. Normally a CALLABLE, because referencing an
+      # autoloadable constant eagerly from an initializer pins the first-loaded
+      # copy and breaks Zeitwerk reloading:
+      #
+      #   config.audit_catalogue = -> { AuditCatalogue::ACTIONS }
+      #
+      # A plain Array is accepted when the vocabulary really is a frozen
+      # literal. `nil` (the default) skips the membership check entirely, so
+      # the DSL is adoptable before an app has a catalogue.
+      #
+      # Membership is the ONLY rule applied — see StandardAudit::Operation.
+      @audit_catalogue = nil
+
+      # Whether `audit!` verifies the declaration before writing. A callable
+      # (or a plain boolean). Defaults to local environments only: in
+      # production `audit!` just writes, because a developer's declaration
+      # mistake must not 500 a user — the host's meta-spec is the real gate.
+      @verify_audit_declarations = -> {
+        defined?(Rails) && Rails.respond_to?(:env) && Rails.env.respond_to?(:local?) && Rails.env.local?
+      }
+
+      # Whether a failed audit *write* aborts the operation. `false` (report
+      # and swallow) matches four of the five apps this DSL was extracted from.
+      # Set `true` where an unaudited state change is itself a compliance
+      # failure — one app deliberately does not rescue, and defaulting to
+      # swallow would have silently downgraded that posture.
+      #
+      # StandardAudit::Operation::DeclarationError is NEVER governed by this;
+      # it always propagates.
+      @raise_on_audit_write_error = false
+
+      # Optional callable invoked instead of the built-in logger/Rails.error
+      # reporting when an audit write fails:
+      #
+      #   config.audit_write_error_handler =
+      #     ->(error, action:, operation:) { ErrorReporting.notify(error, ...) }
+      #
+      # Runs before `raise_on_audit_write_error` is applied, so it sees every
+      # write failure under either policy.
+      @audit_write_error_handler = 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/operation/audit.rb

@@ -0,0 +1,253 @@
+module StandardAudit
+  module Operation
+    # The registry, the catalogue resolver, the write-error policy, and the
+    # analysis predicates behind the operation-audit meta-spec.
+    #
+    # Everything here is PLAIN RUBY that returns data — no RSpec, no
+    # assertions. A host can call these from a bespoke spec, a rake task, or a
+    # CI script. `standard_audit/rspec/operation` is a thin shared-example
+    # layer over exactly these methods and adds no logic of its own.
+    #
+    #   StandardAudit::Operation::Audit.undeclared           # => [Class, ...]
+    #   StandardAudit::Operation::Audit.unknown_actions      # => { Class => ["x.y"] }
+    #   StandardAudit::Operation::Audit.orphan_actions       # => ["x.y"]
+    #   StandardAudit::Operation::Audit.missing_write_sites  # => [Class, ...]
+    module Audit
+      # Heuristic used by the source-scanning predicates: a call to the private
+      # `audit!` helper, with or without parentheses, not preceded by a receiver
+      # (so `foo.audit!` and `Something::audit!` don't count).
+      #
+      # The scan is FILE-scoped, not class-scoped — two operations defined in
+      # one file share a verdict. Zeitwerk requires one class per file in a
+      # real app, so this only matters for fixtures. A commented-out or
+      # documented `audit!` in the same file also counts as a write site; the
+      # predicates deliberately err towards a false pass rather than a false
+      # failure, since the runtime guard is the authoritative check.
+      WRITE_SITE_PATTERN = /(?<![\w.:])audit!\s*(?:\(|["':@$\w])/
+
+      class << self
+        # ── Registry ────────────────────────────────────────────────────────
+
+        # Every class that has gained the contract, in registration order.
+        # Includes bases, intermediates, and anonymous classes — use
+        # {.operations} for the filtered view a meta-spec should assert on.
+        def registered
+          @registered ||= []
+        end
+
+        def register(klass)
+          registered << klass unless registered.include?(klass)
+          klass
+        end
+
+        # Empties the registry. For the gem's own specs and for hosts that
+        # rebuild the constant graph mid-suite; a normal suite never needs it.
+        def reset_registry!
+          @registered = []
+        end
+
+        # The real operations a meta-spec should hold to the contract.
+        #
+        # Excluded:
+        #   - anonymous classes (no name) — test doubles and `Class.new` fixtures
+        #   - classes that declared `audit_abstract!`
+        #   - classes that declare NOTHING and have subclasses — i.e. a shared
+        #     base such as `ApplicationOperation`. This is what lets an app
+        #     adopt the whole contract with one `include` on its base class and
+        #     no further configuration. A class that DID declare is never
+        #     excluded by this rule, even if it is subclassed, so subclassing a
+        #     real operation cannot quietly drop it from the check.
+        #
+        # @param source [String, nil] keep only classes whose defining file path
+        #   contains this fragment, e.g. `"/app/operations/"`. Recommended: it
+        #   scopes the check to the host's own operations and drops anything
+        #   defined in a spec file.
+        def operations(source: nil)
+          registered.select do |klass|
+            next false if klass.name.nil? || klass.name.empty?
+            next false if klass.audit_spec == :abstract
+            next false if klass.audit_spec.nil? && subclassed?(klass)
+            next true if source.nil?
+
+            source_path(klass)&.include?(source)
+          end
+        end
+
+        # Absolute path of the file that defines `klass`, or nil.
+        def source_path(klass)
+          return nil if klass.name.nil? || klass.name.empty?
+
+          Object.const_source_location(klass.name)&.first
+        rescue NameError
+          nil
+        end
+
+        # ── Catalogue ───────────────────────────────────────────────────────
+
+        # The host's action vocabulary as an Array of Strings, or nil when no
+        # catalogue is configured (in which case membership is not checked).
+        #
+        # `config.audit_catalogue` is normally a callable — see the note in
+        # StandardAudit::Operation on why an eagerly-referenced autoloadable
+        # constant breaks Zeitwerk reloading. A plain Array is accepted for the
+        # case where the vocabulary really is a frozen literal.
+        def catalogue
+          raw = StandardAudit.config.audit_catalogue
+          return nil if raw.nil?
+
+          resolved = raw.respond_to?(:call) ? raw.call : raw
+          return nil if resolved.nil?
+
+          Array(resolved).map(&:to_s)
+        end
+
+        # ── Policy ──────────────────────────────────────────────────────────
+
+        # Whether `audit!` verifies declarations before writing. Defaults to
+        # "local environments only" — production writes silently, because a
+        # developer's declaration mistake must not 500 a user.
+        def verify?
+          resolver = StandardAudit.config.verify_audit_declarations
+          resolver.respond_to?(:call) ? !!resolver.call : !!resolver
+        end
+
+        # Applies the configured policy to a failed audit *write* (never to a
+        # DeclarationError, which `audit!` re-raises first).
+        #
+        # @return [nil] when the error is swallowed
+        # @raise [StandardError] the original error when
+        #   `config.raise_on_audit_write_error` is true
+        def handle_write_error(error, action:, operation:)
+          handler = StandardAudit.config.audit_write_error_handler
+
+          if handler
+            handler.call(error, action: action, operation: operation)
+          else
+            report_write_error(error, action: action, operation: operation)
+          end
+
+          raise error if StandardAudit.config.raise_on_audit_write_error
+
+          nil
+        end
+
+        # ── Predicates ──────────────────────────────────────────────────────
+
+        # Operations that declare neither `audits` nor `audit_none!`. A new
+        # mutating operation shipping with no audit trail shows up here.
+        #
+        # @return [Array<Class>]
+        def undeclared(operations: self.operations)
+          operations.select { |klass| klass.audit_spec.nil? }
+        end
+
+        # Declared actions that are absent from the configured catalogue.
+        # Empty when no catalogue is configured.
+        #
+        # @return [Hash{Class => Array<String>}]
+        def unknown_actions(operations: self.operations, catalogue: self.catalogue)
+          return {} if catalogue.nil?
+
+          operations.each_with_object({}) do |klass, acc|
+            unknown = declared_for(klass) - catalogue
+            acc[klass] = unknown if unknown.any?
+          end
+        end
+
+        # Catalogue entries no operation declares — dead vocabulary, which makes
+        # the catalogue a wish rather than a record.
+        #
+        # @param within [Array<String>, nil] check only this slice. Hosts whose
+        #   catalogue also covers non-operation writers (a controller concern, a
+        #   tool server, a notification-bus name) pass the operation-only slice
+        #   here; the rest are written outside `app/operations/` and would
+        #   always look orphaned.
+        # @return [Array<String>]
+        def orphan_actions(operations: self.operations, catalogue: self.catalogue, within: nil)
+          pool = within ? Array(within).map(&:to_s) : catalogue
+          return [] if pool.nil?
+
+          pool - declared_actions(operations: operations)
+        end
+
+        # Every action declared across the given operations, de-duplicated.
+        #
+        # @return [Array<String>]
+        def declared_actions(operations: self.operations)
+          operations.flat_map { |klass| declared_for(klass) }.uniq
+        end
+
+        # Catalogue entries listed more than once.
+        #
+        # @return [Array<String>]
+        def duplicate_catalogue_entries(catalogue: self.catalogue)
+          return [] if catalogue.nil?
+
+          catalogue.tally.select { |_action, count| count > 1 }.keys
+        end
+
+        # Operations that declare `audits` but whose source contains no `audit!`
+        # call — the declaration is aspirational and nothing writes the row.
+        #
+        # Source-based, therefore a heuristic: a class whose defining file can't
+        # be read is skipped rather than reported.
+        #
+        # @return [Array<Class>]
+        def missing_write_sites(operations: self.operations)
+          operations.select do |klass|
+            spec = klass.audit_spec
+            next false unless spec.is_a?(Array)
+
+            src = source_for(klass)
+            src && !src.match?(WRITE_SITE_PATTERN)
+          end
+        end
+
+        # Operations that declare `audit_none!` but whose source calls `audit!`
+        # anyway. The runtime guard catches this too, but only if that code path
+        # is exercised; this catches it statically.
+        #
+        # @return [Array<Class>]
+        def unexpected_write_sites(operations: self.operations)
+          operations.select do |klass|
+            next false unless klass.audit_spec == :none
+
+            src = source_for(klass)
+            src&.match?(WRITE_SITE_PATTERN)
+          end
+        end
+
+        private
+
+        def declared_for(klass)
+          spec = klass.audit_spec
+          spec.is_a?(Array) ? spec : []
+        end
+
+        def source_for(klass)
+          path = source_path(klass)
+          return nil unless path && File.exist?(path)
+
+          File.read(path)
+        end
+
+        def subclassed?(klass)
+          klass.respond_to?(:subclasses) && klass.subclasses.any?
+        end
+
+        def report_write_error(error, action:, operation:)
+          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(
+            error,
+            handled: true,
+            context: { audit_action: action, operation: operation.class.name }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/standard_audit/operation.rb

@@ -0,0 +1,205 @@
+require "active_support/concern"
+require "standard_audit/operation/audit"
+
+module StandardAudit
+  # Operation-level audit contract, extracted from five independent copies of
+  # the same DSL (fundbright-web, jumpdrive-web, luminality-web, nutripod-web,
+  # sidekick-web).
+  #
+  # It is a MODULE, never a base class. The five host `ApplicationOperation`
+  # classes range from 61 to 303 lines and diverge deliberately — one of them
+  # explicitly refuses a `Result`/`execute` lifecycle, and one app has no shared
+  # operation base at all. This module contributes the audit contract and
+  # nothing else: no lifecycle, no `call`, no `Result`.
+  #
+  # It gives an including class:
+  #
+  #   - a class-level declaration of audit intent — `audits "x.y"` (it records
+  #     one or more audit events), `audit_none!` (it intentionally records
+  #     none), or `audit_abstract!` (it is a base/intermediate class, not a real
+  #     operation). The declaration is meant to be MANDATORY, enforced by the
+  #     host's meta-spec — see StandardAudit::Operation::Audit and
+  #     `standard_audit/rspec/operation`.
+  #
+  #   - a single private instance-level write path, `audit!(action, **attrs)`,
+  #     which verifies the declaration (dev/test only) and then writes through
+  #     StandardAudit.record.
+  #
+  # ── ADOPTION SHAPES ─────────────────────────────────────────────────────────
+  # Both shapes found in the estate work with no host configuration:
+  #
+  #   1. A shared base includes the module once, and the real operations are its
+  #      subclasses. `inherited` registers them. The base itself is excluded
+  #      from `Audit.operations` automatically because it declares nothing and
+  #      has subclasses.
+  #
+  #   2. Every operation is a leaf that includes the module directly (no shared
+  #      base). `included` registers each one.
+  #
+  # ── ERROR POLICY ────────────────────────────────────────────────────────────
+  # `DeclarationError` ALWAYS propagates — it is a developer mistake caught in
+  # dev/test, and letting it decay into a swallowed write or a failure Result
+  # would hide drift from CI.
+  #
+  # A genuine *write* failure is governed by `config.raise_on_audit_write_error`
+  # (default `false`, i.e. report and swallow). One of the five apps
+  # deliberately lets a failed audit write abort the operation, because for it
+  # an unaudited state change is a compliance failure; it sets the flag to
+  # `true`. A swallow-only module would have silently downgraded that posture,
+  # which is why this is configurable rather than fixed.
+  #
+  # ── CATALOGUE ───────────────────────────────────────────────────────────────
+  # The gem has no knowledge of any host's action vocabulary. The host declares
+  # it:
+  #
+  #   StandardAudit.configure(baseline: true) do |config|
+  #     config.audit_catalogue = -> { AuditCatalogue::ACTIONS }
+  #   end
+  #
+  # A CALLABLE, because referencing an autoloadable constant eagerly from an
+  # initializer pins the first-loaded copy and breaks Zeitwerk reloading. `nil`
+  # (the default) means the catalogue check is skipped entirely, so the DSL is
+  # adoptable before an app has a catalogue.
+  #
+  # Membership is the ONLY rule applied to an action string. There is
+  # deliberately no dot-count, case, prefix, or namespace validation: one app's
+  # catalogue carries notification-bus names verbatim
+  # (`jumpdrive-web.surface.audience_changed`) because the subscriber records
+  # the bus name as-is, and normalising them would orphan historical rows.
+  module Operation
+    extend ActiveSupport::Concern
+
+    # Raised when an operation writes an audit action it didn't declare, wrote
+    # despite `audit_none!`, or wrote an action absent from the configured
+    # catalogue. Raised in dev/test only (see `config.verify_audit_declarations`)
+    # and never rescued by this module.
+    class DeclarationError < StandardError; end
+
+    included do |base|
+      StandardAudit::Operation::Audit.register(base)
+    end
+
+    module ClassMethods
+      # Subclasses of an adopting base class are the real operations, so they
+      # register too — and they do NOT inherit `@audit_spec`, by design: each
+      # leaf states its own intent. A leaf reading `nil` through a declared
+      # parent would be the wrong (and silently passing) answer.
+      def inherited(subclass)
+        super
+        StandardAudit::Operation::Audit.register(subclass)
+      end
+
+      # The audit action(s) this operation is expected to emit.
+      #
+      # @return [nil, :none, :abstract, Array<String>]
+      #   `nil` — undeclared (the meta-spec forbids this)
+      #   `:none` — intentionally records no audit
+      #   `:abstract` — not a real operation; excluded from the meta-spec
+      #   Array — the catalogue action strings it may write
+      def audit_spec
+        @audit_spec
+      end
+
+      # Declare the audit action(s) this operation emits (primary first; an
+      # operation may emit several — conditional or per-item — and all must be
+      # listed). The matching write happens via #audit! inside the operation.
+      #
+      #   audits "order.created"
+      #   audits "order.created", "order.line_item_added"
+      #
+      # Values are coerced to Strings, so Symbols and frozen catalogue
+      # constants both work. Calling it twice REPLACES the declaration.
+      def audits(*actions)
+        actions = actions.flatten.map(&:to_s)
+        raise ArgumentError, "`audits` needs at least one action" if actions.empty?
+
+        @audit_spec = actions
+      end
+
+      # Declare that this operation mutates state but intentionally records no
+      # audit. The accepted reasons, all of which should be left as a comment
+      # on the call: delegators that audit downstream, projections/re-indexes
+      # derived from already-audited state, outcome-only writes on a record
+      # whose creation is already audited, and high-volume telemetry ingestion.
+      def audit_none!
+        @audit_spec = :none
+      end
+
+      # Declare that this class is a base or intermediate class rather than a
+      # real operation, so the meta-spec skips it.
+      #
+      # Usually unnecessary: a class that declares nothing and HAS subclasses is
+      # treated as a base automatically, which is what makes a one-line
+      # `include StandardAudit::Operation` on a shared `ApplicationOperation`
+      # work with no further configuration. Use this when the automatic rule is
+      # not enough — most often an intermediate class that has no subclasses
+      # *yet*, or one you want to state the intent of explicitly.
+      def audit_abstract!
+        @audit_spec = :abstract
+      end
+    end
+
+    private
+
+    # The single audit-write path for operations.
+    #
+    # Call it INSIDE the operation's own transaction where one is open, so the
+    # audit row commits atomically with the state change — this helper opens no
+    # transaction of its own. `action` is the StandardAudit `event_type`;
+    # keyword args are forwarded straight to StandardAudit.record, so `actor:` /
+    # `target:` / `scope:` must be model objects (the gem records their
+    # GlobalID), alongside `metadata:` and context overrides such as
+    # `ip_address:`.
+    #
+    # `actor:` defaults to whatever `config.current_actor_resolver` returns, so
+    # only operations acting on someone else's behalf need to pass it.
+    #
+    # In dev/test it raises DeclarationError on declaration↔write drift. In
+    # production it just writes: a developer mistake shouldn't 500 a user, and
+    # the meta-spec is the CI gate.
+    #
+    # @return [StandardAudit::AuditLog, nil]
+    def audit!(action, **attrs)
+      action = action.to_s
+      verify_audit_declared!(action) if StandardAudit::Operation::Audit.verify?
+
+      StandardAudit.record(action, **attrs)
+    rescue DeclarationError
+      # Always propagate a declaration mismatch, ahead of the generic rescue
+      # below and regardless of `raise_on_audit_write_error`. It can only be
+      # raised when verification is on (dev/test).
+      raise
+    rescue StandardError => e
+      StandardAudit::Operation::Audit.handle_write_error(e, action: action, operation: self)
+    end
+
+    # Raises DeclarationError when `action` contradicts the class's declaration
+    # or is absent from the configured catalogue. Public-ish by convention (it
+    # is private, like `audit!`) but documented because host meta-specs assert
+    # on its messages.
+    def verify_audit_declared!(action)
+      catalogue = StandardAudit::Operation::Audit.catalogue
+
+      case (spec = self.class.audit_spec)
+      when nil
+        raise DeclarationError,
+          "#{self.class} writes audit '#{action}' but declares neither `audits` nor `audit_none!`"
+      when :none
+        raise DeclarationError,
+          "#{self.class} declares `audit_none!` but writes audit '#{action}'"
+      when :abstract
+        raise DeclarationError,
+          "#{self.class} declares `audit_abstract!` but writes audit '#{action}'"
+      else
+        unless spec.include?(action)
+          raise DeclarationError,
+            "#{self.class} writes audit '#{action}' not in its declared actions #{spec.inspect}"
+        end
+        if catalogue && !catalogue.include?(action)
+          raise DeclarationError,
+            "audit action '#{action}' is not in the configured audit catalogue"
+        end
+      end
+    end
+  end
+end