permission_forge 0.14.1

data/lib/permission_forge/rls.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # Level 3 — Postgres Row-Level Security runtime plumbing.
+  #
+  # Policies are generated by {Services::RlsPolicyGenerator} and installed via
+  # `rails generate permission_forge:rls` (initial migration) or
+  # `rake permission_forge:rls:sync` (after rule edits). This module executes
+  # that DDL and manages the per-request session variable the policies read.
+  #
+  # Setting the user:
+  #
+  #   # Block form — transaction-scoped (SET LOCAL), ideal for jobs/services:
+  #   PermissionForge::RLS.with_user(user) { Customer.where(...) }
+  #
+  #   # Controller form — session-scoped, cleared in ensure:
+  #   around_action do |_controller, action|
+  #     PermissionForge::RLS.set_user!(current_user)
+  #     action.call
+  #   ensure
+  #     PermissionForge::RLS.clear_user!
+  #   end
+  #
+  # Enforcement caveats (documented in docs/query-scoping.md): a superuser or
+  # BYPASSRLS role bypasses policies entirely — the app must connect as a
+  # regular role. Under RLS a denied row is invisible, so find_by reports
+  # missing (nil / RecordNotFound) rather than NotAuthorizedError.
+  #
+  # @api public
+  module RLS
+    module_function
+
+    def postgres?
+      with_connection { |connection| connection.adapter_name.match?(/postgresql/i) }
+    rescue ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished
+      false
+    end
+
+    def ensure_postgres!
+      return if postgres?
+
+      raise PermissionForge::ConfigurationError,
+            I18n.t('permission_forge.errors.rls_requires_postgres',
+                   default: 'PermissionForge RLS requires PostgreSQL — the current database ' \
+                            'adapter does not support row-level security policies.')
+    end
+
+    # Runs the block with the RLS session variable set transaction-locally
+    # (set_config(..., true) — automatically cleared when the transaction
+    # ends, so no reset bookkeeping and no leakage across pooled connections).
+    #
+    # The block runs on the connection the variable is set on: one the
+    # calling thread already holds, or one taken for the block and given
+    # back to the pool after it.
+    def with_user(user_or_id)
+      ensure_postgres!
+      with_connection do |connection|
+        connection.transaction do
+          apply_user(user_or_id, local: true, connection: connection)
+          yield
+        end
+      end
+    end
+
+    # Session-scoped variant for around_action use. MUST be paired with
+    # clear_user! in an ensure block — the setting survives on the pooled
+    # connection otherwise. Set on the connection the calling thread keeps
+    # (leased to it until the request ends), so the request's queries see it.
+    def set_user!(user_or_id)
+      ensure_postgres!
+      apply_user(user_or_id, local: false)
+    end
+
+    # Clears the database session variable that carries the current user (PostgreSQL only).
+    # @return [void]
+    def clear_user!
+      return unless postgres?
+
+      run_set_config('', local: false)
+    end
+
+    # Generates and executes RLS DDL for every protected model (enable/force +
+    # four policies + digest comment), one transaction per table.
+    #
+    # @return [Array<Hash>] per-table { table:, digest:, skipped_rules: }
+    def sync!
+      ensure_postgres!
+      protected_model_classes.map do |model_class|
+        result = Services::RlsPolicyGenerator.call(model_class: model_class)
+        with_connection { |connection| execute_in_transaction(connection, result[:statements]) }
+        log_skipped_rules(result)
+        result.slice(:table, :digest, :skipped_rules)
+      end
+    end
+
+    # Drops PermissionForge policies and disables RLS on every protected table
+    # (used by the generated migration's `down`).
+    #
+    # @return [Array<String>] the table names cleaned up
+    def remove!
+      ensure_postgres!
+      protected_model_classes.map do |model_class|
+        with_connection { |connection| drop_policies(connection, model_class.table_name) }
+        model_class.table_name
+      end
+    end
+
+    # Compares each protected table's live policy digest with the digest the
+    # current rule state would produce. A missing policy reports out-of-sync
+    # (stored: nil) — enabling Level 3 without installing policies is itself
+    # a misconfiguration worth surfacing.
+    #
+    # @return [Array<Hash>] { table:, expected:, stored:, in_sync: }
+    def drift_report
+      protected_model_classes.map do |model_class|
+        expected = Services::RlsPolicyGenerator.new(model_class: model_class).digest
+        stored = stored_digest(model_class.table_name)
+        { table: model_class.table_name, expected: expected, stored: stored, in_sync: expected == stored }
+      end
+    end
+
+    # @param table_name [String]
+    # @return [String, nil] the digest of the policy installed on the table
+    # @api private
+    def stored_digest(table_name)
+      row = with_connection do |connection|
+        connection.select_value(<<~SQL)
+          SELECT d.description
+          FROM pg_policy pol
+          JOIN pg_class c ON c.oid = pol.polrelid
+          JOIN pg_description d ON d.objoid = pol.oid
+          WHERE c.relname = #{connection.quote(table_name)}
+            AND pol.polname = #{connection.quote(Services::RlsPolicyGenerator::POLICY_NAMES[:select])}
+        SQL
+      end
+      row&.delete_prefix(Services::RlsPolicyGenerator::DIGEST_COMMENT_PREFIX)
+    end
+
+    # @return [Array<Class>] the models that include PermissionScopedFindable
+    # @api private
+    def protected_model_classes
+      Concerns::PermissionScopedFindable.protected_model_names.filter_map(&:safe_constantize)
+    end
+
+    # A connection for one unit of work: the one the calling thread holds,
+    # else one from the pool that goes back to it when the block ends.
+    # (`ActiveRecord::Base.connection` is soft-deprecated from Rails 7.2 and
+    # would keep a connection leased to the thread.)
+    def with_connection(&)
+      ActiveRecord::Base.connection_pool.with_connection(&)
+    end
+
+    # The connection the calling thread keeps until it is released (the end
+    # of the request, or of the job): where a session-scoped setting has to
+    # live. `lease_connection` from Rails 7.2; on 7.1 that is `connection`.
+    def leased_connection
+      pool = ActiveRecord::Base.connection_pool
+      pool.respond_to?(:lease_connection) ? pool.lease_connection : pool.connection
+    end
+
+    def execute_in_transaction(connection, statements)
+      connection.transaction do
+        statements.each { |statement| connection.execute(statement) }
+      end
+    end
+
+    def drop_policies(connection, table_name)
+      table = connection.quote_table_name(table_name)
+      connection.transaction do
+        Services::RlsPolicyGenerator::POLICY_NAMES.each_value do |name|
+          connection.execute("DROP POLICY IF EXISTS #{name} ON #{table}")
+        end
+        connection.execute("ALTER TABLE #{table} NO FORCE ROW LEVEL SECURITY")
+        connection.execute("ALTER TABLE #{table} DISABLE ROW LEVEL SECURITY")
+      end
+    end
+
+    # `connection` defaults to the one the calling thread keeps (set_user!).
+    def apply_user(user_or_id, local:, connection: leased_connection)
+      id = user_or_id.respond_to?(:id) ? user_or_id.id : user_or_id
+      run_set_config(id.to_s, local: local, connection: connection)
+    end
+
+    # set_config avoids interpolating the setting name as an identifier —
+    # both the name and value travel as quoted literals.
+    def run_set_config(value, local:, connection: leased_connection)
+      var = PermissionForge.configuration.rls_session_variable
+      connection.execute(
+        "SELECT set_config(#{connection.quote(var)}, #{connection.quote(value)}, #{local})"
+      )
+    end
+
+    # Logs the rules a policy sync left out because they cannot be expressed in SQL.
+    # @param result [Hash] the sync result
+    # @api private
+    def log_skipped_rules(result)
+      return if result[:skipped_rules].empty?
+
+      Rails.logger&.warn(
+        "[PermissionForge] RLS sync for '#{result[:table]}' skipped " \
+        "#{result[:skipped_rules].size} untranslatable rule(s) " \
+        "(#{result[:skipped_rules].map { |r| "#{r[:rule]}: #{r[:reason]}" }.join(', ')}) — " \
+        'join-type rules, dotted field names and rules on an STI subclass resource are enforced at the application layer only.'
+      )
+    end
+
+    private_class_method :with_connection, :leased_connection, :execute_in_transaction, :drop_policies
+  end
+end

data/lib/permission_forge/services/attribute_access_guard.rb

@@ -0,0 +1,138 @@
+module PermissionForge
+  module Services
+    # Decides what value an attribute reader should return for a given user, based on
+    # the user's field permissions. Used by {PermissionForge::Concerns::MaskedAttributes}.
+    #
+    # Returns a `[include?, value]` tuple so callers can distinguish "omit this key from
+    # the hash" from "substitute this value in place." This mirrors the asymmetry between
+    # Salesforce's `Security.stripInaccessible()` (omits the field) and a direct getter
+    # call (which has to return *something*).
+    #
+    # @example Single attribute
+    #   include?, value = AttributeAccessGuard.call(
+    #     resource_name: :Customer, attribute: :email, raw_value: 'a@b.com', user: current_user
+    #   )
+    #
+    # Every decision is reported for the field.access audit event
+    # (Audit::FieldAccess), which also calls the legacy on_field_filtered hook:
+    # to `observer:` — the frame of the record read in progress, or nil when
+    # nobody listens (MaskedAttributes) — or, by default, to whatever read is
+    # in progress on this thread (a call of its own is a read of its own).
+    #
+    # `resource_name:` is one Resource name, or the chain of names the
+    # record's class answers to (ResourceChain: its own and its STI
+    # ancestors', nearest first). The field is looked up along the chain; the
+    # decision is reported under the first name, the record's own.
+    #
+    # @api private
+    class AttributeAccessGuard
+      ACTIONS = %i[hidden masked passed bypassed unconfigured].freeze
+
+      # The default observer: Audit::FieldAccess.note.
+      STANDALONE = Object.new.freeze
+
+      # Called on every guarded read: the instance is set up without passing
+      # the keywords on a second time (half the cost of `new(...).call`).
+      # rubocop:disable Metrics/ParameterLists -- model: the record's class, so a read with no user looks up no constant
+      def self.call(resource_name:, attribute:, raw_value:, user: nil, observer: STANDALONE, model: nil)
+        allocate.decide(resource_name, attribute, raw_value, user, observer, model)
+      end
+
+      # @param resource_name [Symbol, String, Array<Symbol>] a name, or the chain
+      # @param observer [Audit::FieldAccess::Frame, nil] where decisions go
+      # @param model [Class, nil] the record's class (default: the class the
+      #   first name names)
+      def initialize(resource_name:, attribute:, raw_value:, user: nil, observer: STANDALONE, model: nil)
+        assign(resource_name, attribute, raw_value, user, observer)
+        @model = model
+      end
+
+      # .call on an allocated instance. @api private
+      def decide(resource_name, attribute, raw_value, user, observer, model = nil)
+        assign(resource_name, attribute, raw_value, user, observer)
+        @model = model
+        call
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # @return [Array(Boolean, Object)] tuple of (include_in_hash?, value_to_return)
+      def call
+        return without_user unless @user
+        return unconfigured unless field
+
+        return hidden unless field[:read_access]
+        return masked if field[:mask_access]
+
+        passed
+      end
+
+      private
+
+      def assign(resource_name, attribute, raw_value, user, observer)
+        @resource_names = resource_name.is_a?(Array) ? resource_name : resource_name.to_sym
+        @resource_name = resource_name.is_a?(Array) ? resource_name.first : @resource_names
+        @attribute = attribute.to_sym
+        @raw_value = raw_value
+        @user = user || PermissionForge.current_user
+        @observer = observer
+      end
+
+      def field
+        return @field if defined?(@field)
+
+        @field = PermissionForge::ResourceChain.field_permissions(@user, @resource_names, @attribute)
+      end
+
+      # Without a user there is no entry to decide by:
+      # config.masked_attributes_nil_user_strategy says whether every
+      # attribute passes (:bypass, the default) or is hidden (:hide) — except
+      # on the user model, which sign-in reads before anyone is signed in.
+      # The model is the record's class, or else the one the first name of the
+      # chain names (an anonymous subclass answers as its base).
+      def without_user
+        model = @model || @resource_name.to_s.safe_constantize
+        PermissionForge.configuration.hide_masked_attributes_without_user_for?(model) ? hidden : bypass
+      end
+
+      def bypass
+        notify(:bypassed)
+        [true, @raw_value]
+      end
+
+      def hidden
+        notify(:hidden)
+        [false, PermissionForge.configuration.hidden_attribute_value]
+      end
+
+      def masked
+        notify(:masked)
+        strategy = field[:mask_strategy] || 'full'
+        [true, MaskValue.call(@raw_value, strategy: strategy)]
+      end
+
+      def passed
+        notify(:passed)
+        [true, @raw_value]
+      end
+
+      def unconfigured
+        strategy_key = PermissionForge.configuration.unconfigured_field_strategy
+        # Unknown strategy keys fall back to :block (fail closed), never pass-through.
+        strategy = FiltersResponseAttributes::UNCONFIGURED_FIELD_STRATEGIES.fetch(
+          strategy_key,
+          FiltersResponseAttributes::UNCONFIGURED_FIELD_STRATEGIES[:block]
+        )
+        include_field, value = strategy.call(@resource_name.to_s, @attribute, @raw_value)
+        notify(:unconfigured)
+        [include_field, value]
+      end
+
+      def notify(action)
+        return if @observer.nil?
+        return PermissionForge::Audit::FieldAccess.note(@resource_name, @attribute, action, @user) if @observer.equal?(STANDALONE)
+
+        @observer.add(@resource_name, @attribute, action, @user)
+      end
+    end
+  end
+end

data/lib/permission_forge/services/audit_event_purger.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    # Retention: deletes audit events older than the retention period and
+    # records that it did (`audit.purged`: count, cutoff, period, batch).
+    #
+    #   AuditEventPurger.call                         # config.audit_retention_period
+    #   AuditEventPurger.call(older_than: 400.days, actor: 'nightly job')
+    #   AuditEventPurger.call(dry_run: true)          # counts, writes nothing
+    #
+    # Only events whose `occurred_at` is before now - period are deleted — an
+    # event inside the period is never touched, and neither is an
+    # `audit.purged` event (the record of purges outlives them). A Duration
+    # is subtracted by the calendar (30.days across a DST change, 1.year),
+    # a number is seconds. No period (nil: the default) deletes nothing and
+    # says so. With auditing off (nothing could record the purge) a real run
+    # raises ConfigurationError.
+    #
+    # Each batch is `delete_all` plus its own `audit.purged` event in ONE
+    # transaction: a batch whose event cannot be written is not deleted,
+    # under every audit_change_failure_strategy (a purge is always fail-closed),
+    # so no deletion is ever unrecorded. In a tenant context only that tenant's events are
+    # purged; with none, all of them. A run that finds nothing records nothing.
+    #
+    # A purge with no tenant (the rake task, a platform job) records one
+    # `audit.purged` per tenant whose events the batch deleted, in that
+    # tenant and with that tenant's count (`across_tenants: true`), plus one
+    # without a tenant for the events that had none: a tenant's auditors
+    # never see an event without a tenant, and must still see that their
+    # log was purged. Other tenants' counts are not in it.
+    #
+    # Reached only from Ruby and `rake permission_forge:audit_events:purge`:
+    # there is deliberately no controller, route or API for it.
+    #
+    # @api public
+    class AuditEventPurger
+      include Concerns::AuditedOperation
+
+      BATCH_SIZE = 1000
+      EVENT = 'audit.purged'
+
+      # Deletes audit events past the retention period.
+      # @return [Hash] the counts of the run
+      def self.call(...) = new(...).call
+
+      # @param older_than [ActiveSupport::Duration, Numeric, nil] the retention period
+      # @param actor [Object, nil] a user, an Audit::Actor or a label String
+      # @param batch_size [Integer] rows deleted per statement (>= 1)
+      # @param now [Time] the clock (tests)
+      # @raise [PermissionForge::ConfigurationError] for a period that is not valid
+      # @raise [ArgumentError] for a batch_size below 1
+      # rubocop:disable-next Metrics/ParameterLists
+      def initialize(older_than: PermissionForge.configuration.audit_retention_period, actor: nil, reason: nil,
+                     dry_run: false, batch_size: BATCH_SIZE, now: Time.current)
+        raise ArgumentError, "batch_size must be at least 1 (got #{batch_size.inspect})" unless batch_size.is_a?(Integer) && batch_size >= 1
+
+        @period = PermissionForge::Configuration::AuditSettings.retention_period(older_than)
+        @actor = actor
+        @reason = reason
+        @dry_run = dry_run
+        @batch_size = batch_size
+        @now = now
+      end
+
+      # @return [Hash] { purged:, retention_configured:, cutoff:, period:, dry_run: } (+ message: when not configured)
+      def call
+        return not_configured_result if @period.nil?
+
+        cutoff = @now - @period
+        return dry_run_result(cutoff) if @dry_run
+
+        refuse_without_auditing!
+        audited(actor: @actor, reason: @reason) { purge(cutoff) }
+      end
+
+      private
+
+      def dry_run_result(cutoff)
+        { purged: expired(cutoff).count, retention_configured: true, cutoff: cutoff, period: @period.to_i, dry_run: true }
+      end
+
+      def not_configured_result
+        { purged: 0, retention_configured: false, dry_run: @dry_run, message: 'retention not configured' }
+      end
+
+      def refuse_without_auditing!
+        return if PermissionForge::Audit.enabled?
+
+        raise PermissionForge::ConfigurationError,
+              'audit events are switched off (or their table is missing): a purge would be unrecorded, so it is refused'
+      end
+
+      def expired(cutoff)
+        PermissionForge::AuditEvent.unscoped.in_tenant(PermissionForge.ambient_tenant_id)
+                                   .where(PermissionForge::AuditEvent.arel_table[:occurred_at].lt(cutoff))
+                                   .where.not(event: EVENT)
+      end
+
+      def purge(cutoff)
+        purged = 0
+        batch = 0
+        loop do
+          ids = expired(cutoff).order(:id).limit(@batch_size).pluck(:id)
+          break if ids.empty?
+
+          batch += 1
+          purged += purge_batch(ids, cutoff, batch)
+        end
+
+        { purged: purged, retention_configured: true, cutoff: cutoff, period: @period.to_i, dry_run: false }
+      end
+
+      # The deletion and its records commit together.
+      def purge_batch(ids, cutoff, batch)
+        PermissionForge::AuditEvent.transaction do
+          per_tenant = counts_by_tenant(ids)
+          deleted = PermissionForge::AuditEvent.unscoped.where(id: ids).delete_all
+          record_batch(per_tenant || { nil => deleted }, summary_data(cutoff, batch, across_tenants: !per_tenant.nil?))
+          deleted
+        end
+      end
+
+      def record_batch(per_tenant, data)
+        per_tenant.each do |tenant_id, count|
+          # fail closed whatever audit_change_failure_strategy says: a nil
+          # (:report / :log swallowed a failed write) rolls the batch back
+          recorded = PermissionForge::Audit.record(EVENT, tenant_id: tenant_id, data: data.merge('count' => count))
+          raise PermissionForge::Audit::EventNotRecordedError.new(event: EVENT) if recorded.nil?
+        end
+      end
+
+      # { tenant id => events of the batch } for a purge with no tenant
+      # ambient; nil (one record, in the ambient tenant) otherwise.
+      def counts_by_tenant(ids)
+        column = PermissionForge::AuditEvent.tenant_column
+        return if column.nil? || PermissionForge.ambient_tenant_id
+
+        PermissionForge::AuditEvent.unscoped.where(id: ids).group(column).count
+      end
+
+      def summary_data(cutoff, batch, across_tenants:)
+        data = { 'operation' => 'audit_events_purge', 'count' => 0, 'batch' => batch,
+                 'cutoff' => cutoff.utc.iso8601(6), 'period_seconds' => @period.to_i, 'dry_run' => false }
+        data['across_tenants'] = true if across_tenants
+        data
+      end
+    end
+  end
+end

data/lib/permission_forge/services/bulk_permission_set_assignment.rb

@@ -0,0 +1,108 @@
+module PermissionForge
+  module Services
+    # Assigns or revokes a permission set for multiple users in a single
+    # transaction. Each assignment created or destroyed invalidates its
+    # user's cached permissions after the commit (PermissionSetUser's own
+    # after_commit), once per user; each user's hash is rebuilt read-through
+    # on their next request, in their own context.
+    #
+    # @example Bulk assign
+    #   result = BulkPermissionSetAssignment.call(
+    #     permission_set: ps, user_ids: [1, 2, 3], action: :assign
+    #   )
+    #   # => { assigned: 3, revoked: 0, invalidated: 3 }
+    #
+    # `invalidated` counts the users assigned or revoked whose invalidation
+    # the cache store confirmed. Fewer means the store failed for the rest
+    # (reported through `config.on_cache_failure`): their cached permissions
+    # may live until cache_ttl. A user who already held the set (assign) or
+    # never did (revoke) changed nothing and is not invalidated. Inside a
+    # transaction of the caller the invalidations happen at its commit, after
+    # this returns: `invalidated` is then nil (not known).
+    #
+    # Every row is created or destroyed through its callbacks, so each person
+    # gets an assignment.granted / assignment.revoked audit event, all with
+    # one correlation id (the transaction's). The reason (a ticket, free
+    # text) comes from the surrounding Audit::Context.
+    #
+    # @api public
+    class BulkPermissionSetAssignment
+      ACTION_STRATEGIES = {
+        assign: :assign_users,
+        revoke: :revoke_users
+      }.freeze
+
+      VALID_ACTIONS = ACTION_STRATEGIES.keys.freeze
+
+      # Assigns or revokes a Permission Set for many users in one transaction.
+      # @return [Hash] `{ assigned:, revoked:, invalidated: }`
+      def self.call(...) = new(...).call
+
+      # @raise [ArgumentError] unless `action` is one of VALID_ACTIONS
+      def self.validate_action!(action)
+        action = action.presence&.to_sym
+        return action if VALID_ACTIONS.include?(action)
+
+        raise ArgumentError, "Invalid action: #{action}. Must be one of: #{VALID_ACTIONS.join(', ')}"
+      end
+
+      def initialize(permission_set:, user_ids:, action:, created_by: nil, expires_at: nil)
+        @permission_set = permission_set
+        # Host keys as given: `to_i` would turn a UUID into its leading digits
+        # and assign whoever owns that number.
+        @user_ids = Array(user_ids).compact_blank.map(&:to_s).uniq
+        @action = action&.to_sym
+        @created_by = created_by
+        @expires_at = expires_at
+        @assigned_count = 0
+        @revoked_count = 0
+        @changed_user_ids = []
+      end
+
+      # @return [Hash] `{ assigned:, revoked:, invalidated: }`
+      def call
+        validate_action!
+
+        deferred = PermissionForge::OpenTransaction.current
+        failures = PermissionForge::Cache::Failure.collect do
+          ActiveRecord::Base.transaction { send(ACTION_STRATEGIES.fetch(@action)) }
+        end
+
+        # what the store confirmed (Cache::Failure) — not what a host's override of invalidate_permissions returns
+        { assigned: @assigned_count, revoked: @revoked_count, invalidated: deferred ? nil : failures.confirmed(@changed_user_ids).size }
+      end
+
+      private
+
+      def validate_action!
+        self.class.validate_action!(@action)
+      end
+
+      def assign_users
+        users = PermissionForge.configuration.user_model.where(id: @user_ids)
+        existing_user_ids = @permission_set.permission_set_users.where(user_id: @user_ids).pluck(:user_id)
+
+        users.each do |user|
+          next if existing_user_ids.include?(user.id)
+
+          @permission_set.permission_set_users.create!(
+            user: user,
+            expires_at: @expires_at,
+            created_by_id: @created_by&.id,
+            updated_by_id: @created_by&.id
+          )
+          @assigned_count += 1
+          @changed_user_ids << user.id
+        end
+      end
+
+      # Through callbacks, as destroy_all; a row a callback refuses to
+      # destroy (destroy answers false) is neither revoked nor counted.
+      def revoke_users
+        revoked = @permission_set.permission_set_users.where(user_id: @user_ids).to_a.select(&:destroy)
+        @revoked_count = revoked.size
+        @changed_user_ids = revoked.map(&:user_id).uniq
+      end
+    end
+  end
+end

data/lib/permission_forge/services/concerns/across_tenants.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    # @api private
+    module Concerns
+      # A housekeeping service run with no tenant ambient (a rake task, a
+      # console, a platform job) works on every tenant's rows; with a tenant
+      # ambient, on that tenant's only.
+      #
+      # #across_tenants lifts acts_as_tenant's scope for the tenant-less run,
+      # as PermissionedUser's destroy and PermissionCacheClearer do, so
+      # `require_tenant = true` does not refuse it with NoTenantSet; with a
+      # tenant ambient, or tenancy off, the block runs as it is. No hard
+      # dependency on acts_as_tenant: without it there is nothing to lift.
+      #
+      # #record_per_tenant writes a run's summary event the way audit.purged
+      # and cache.cleared are written: with a tenant ambient, once (in it);
+      # tenant-less, once in each tenant the run touched, with that tenant's
+      # rows, plus the total without a tenant — each marked across_tenants —
+      # so every tenant's auditors see what was done in their tenant.
+      module AcrossTenants
+        # One summary event of a run over `rows`; `data` builds the event's
+        # data from the rows it covers.
+        Summary = Struct.new(:event, :rows, :payload, :data) do
+          def record(covered = rows, tenant_id: nil, more: {})
+            PermissionForge::Audit.record(event, **payload, tenant_id: tenant_id, data: data.call(covered).merge(more))
+          end
+
+          # In each tenant with its rows, then the total without a tenant.
+          def record_per_tenant(column)
+            by_tenant = rows.select { |row| row.has_attribute?(column) && !row[column].nil? }.group_by { |row| row[column] }
+            by_tenant.each { |tenant_id, tenant_rows| record(tenant_rows, tenant_id: tenant_id, more: { 'across_tenants' => true }) }
+            record(more: { 'across_tenants' => true, 'tenants' => by_tenant.size })
+          end
+        end
+
+        private
+
+        def across_tenants(&)
+          return yield unless tenantless_run?
+
+          ::ActsAsTenant.without_tenant(&)
+        end
+
+        # Tenancy is on and no tenant is ambient.
+        def tenantless_run?
+          PermissionForge.configuration.tenant_enabled? && defined?(::ActsAsTenant) && PermissionForge.ambient_tenant.nil?
+        end
+
+        # @param event [String] the summary event
+        # @param rows [Array<ActiveRecord::Base>] the rows the run changed
+        # @param payload [Hash] more of Audit.record's payload (subject_user_id: …)
+        # @yieldparam rows [Array<ActiveRecord::Base>] the rows of one tenant, or all of them
+        # @yieldreturn [Hash] the event's data for those rows
+        def record_per_tenant(event, rows, **payload, &data)
+          summary = Summary.new(event, rows, payload, data)
+          return summary.record unless tenantless_run?
+
+          summary.record_per_tenant(tenant_column)
+        end
+
+        def tenant_column
+          PermissionForge.configuration.resolved_tenant_column.to_s
+        end
+      end
+    end
+  end
+end