permission_forge 0.14.1

data/lib/permission_forge/admin/effective_access.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # "What can this person do right now, and why?"
+    #
+    # Mirrors PermissionHashBuilder + FieldPermissionMerger exactly (same set
+    # selection order, same ||= / AND / muting semantics, same variants and
+    # extra fields) but keeps provenance: which Permission Set granted or muted
+    # every flag, field and action. Parity with the engine is covered by tests.
+    #
+    # Differences from a live request, by design:
+    # - Activation conditions are not evaluated (the admin's IP/time says
+    #   nothing about the person's). Conditional sets count, and are reported in
+    #   #conditional_sets so the UI can say "only while conditions are true".
+    class EffectiveAccess
+      CRUD = %i[read_access create_access edit_access delete_access].freeze
+      RESOURCE_FLAGS = (CRUD + %i[view_all modify_all]).freeze
+
+      # A permission outcome with the sets that caused it.
+      Outcome = Struct.new(:state, :granted_by, :blocked_by, keyword_init: true) do
+        def granted? = state == :granted
+        def blocked? = state == :blocked
+      end
+
+      # `implicit` — no set configures the field for this outcome: it is a
+      # declared virtual field on the implicit read + edit grant
+      # (extra_fields_default_access = :grant).
+      FieldOutcome = Struct.new(:name, :level, :mask_strategy, :granted_by, :blocked_by, :blocked_level,
+                                :capped, :unconfigured, :virtual, :variant_of, :implicit, keyword_init: true) do
+        def visible? = level != 'hidden'
+      end
+
+      RuleSource = Struct.new(:rule, :permission_set, keyword_init: true)
+
+      ResourceOutcome = Struct.new(:name, :flags, :records, :rules, :fields, :actions, keyword_init: true) do
+        def op(flag) = flags.fetch(flag)
+        def visible_field_count = fields.count(&:visible?)
+      end
+
+      # One resource name with its [permission_set, resource] pairs from the
+      # granting and muting sets, and the resulting resource flag outcomes.
+      ResourceSources = Struct.new(:name, :grants, :mutes, :flags, keyword_init: true)
+
+      attr_reader :live_sets, :conditional_sets
+
+      def self.call(...) = new(...).call
+
+      def initialize(user:, configuration: PermissionForge.configuration, catalog: ModelCatalog.new)
+        @user = user
+        @configuration = configuration
+        @catalog = catalog
+      end
+
+      # @return [Array<ResourceOutcome>]
+      def call
+        @live_sets = select_live_sets
+        @conditional_sets = @live_sets.select(&:conditional?)
+        granting, muting = @live_sets.partition(&:granting?)
+
+        names = granting.flat_map { |ps| active_resources(ps).map(&:name) }.uniq
+        names.map { |name| build_resource(sources_for(name, granting, muting)) }
+      end
+
+      private
+
+      # Same selection as PermissionCacheAccessor#active_non_expired_permission_sets
+      # minus the request-context filter.
+      def select_live_sets
+        ids = PermissionForge::PermissionSetUser.where(user_id: @user.id).active_assignments.select(:permission_set_id)
+        sets = PermissionForge::PermissionSet.active.where(id: ids).order(:created_at, :id)
+                                             .includes(resources: %i[resource_fields resource_actions permission_set_rules]).to_a
+        # Same row order as the hash builder (a variant tie goes to the older row).
+        sets.each { |permission_set| PermissionForge::Services::PermissionHashBuilder.sort_rows(permission_set) }
+      end
+
+      def active_resources(permission_set)
+        permission_set.resources.select(&:is_active)
+      end
+
+      # [permission_set, resource] for every active row of the sets named by
+      # one of `names`, in set order then row order.
+      def pairs_for(permission_sets, names)
+        permission_sets.flat_map do |ps|
+          active_resources(ps).select { |r| names.include?(r.name) }.map { |resource| [ps, resource] }
+        end
+      end
+
+      # A granting set's row for the resource; a muting set's rows for the
+      # resource and for the STI bases of the model it names — the engine's
+      # cascade (PermissionHashBuilder#apply_muting_permission_set): a muted
+      # base reaches the subclass entry, a muted subclass only itself.
+      def sources_for(name, granting, muting)
+        grants = pairs_for(granting, [name])
+        mutes = pairs_for(muting, PermissionForge::ResourceChain.names_for(name).map(&:to_s))
+        flags = RESOURCE_FLAGS.index_with { |flag| outcome_for(grants, mutes) { |r| r.public_send(flag) } }
+        ResourceSources.new(name: name, grants: grants, mutes: mutes, flags: flags)
+      end
+
+      def build_resource(sources)
+        grants = sources.grants
+        ResourceOutcome.new(
+          name: sources.name, flags: sources.flags,
+          records: records_state(sources.flags),
+          rules: rules_for(grants),
+          fields: EffectiveFields.new(sources, configuration: @configuration, catalog: @catalog).call,
+          actions: action_outcomes(grants, sources.mutes)
+        )
+      end
+
+      # Granted by every granting set whose resource matches; muting sets only
+      # block what some set granted.
+      def outcome_for(grants, mutes, &)
+        granted_by = sets_matching(grants, &)
+        blocked_by = granted_by.any? ? sets_matching(mutes, &) : []
+        Outcome.new(state: outcome_state(granted_by, blocked_by), granted_by: granted_by, blocked_by: blocked_by)
+      end
+
+      # Each set once: a muting set may reach an entry through two rows.
+      def sets_matching(pairs)
+        pairs.select { |_, resource| yield resource }.map(&:first).uniq
+      end
+
+      def outcome_state(granted_by, blocked_by)
+        return :none if granted_by.empty?
+
+        blocked_by.any? ? :blocked : :granted
+      end
+
+      def records_state(flags)
+        return :none unless flags[:read_access].granted?
+
+        flags[:view_all].granted? ? :all : :rules
+      end
+
+      def rules_for(grants)
+        grants.flat_map do |ps, resource|
+          resource.permission_set_rules.select(&:is_active).map { |rule| RuleSource.new(rule: rule, permission_set: ps) }
+        end
+      end
+
+      # --- Actions ----------------------------------------------------------
+
+      def action_outcomes(grants, mutes)
+        names = grants.flat_map { |_, r| active_actions(r).map(&:name) }.uniq
+        names.map { |action| [action, outcome_for(grants, mutes) { |r| permitted?(r, action) }] }
+      end
+
+      def active_actions(resource)
+        resource.resource_actions.select(&:is_active)
+      end
+
+      def permitted?(resource, action)
+        active_actions(resource).select(&:is_permitted).map(&:name).include?(action)
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/effective_fields.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Field half of EffectiveAccess for one resource: mirrors what
+    # PermissionHashBuilder does with fields (FieldPermissionMerger's ||=
+    # read/edit, AND-merged mask and variants, then extra fields, then muting)
+    # while keeping which sets granted or muted each field.
+    #
+    # Extra fields follow the engine: after every granting set is merged, each
+    # declared name that nothing configured gets the implicit entry
+    # (ExtraFieldDefaults). A row in any set wins, whatever the set order.
+    class EffectiveFields
+      FieldOutcome = EffectiveAccess::FieldOutcome
+
+      # What FiltersResponseAttributes does with a column no set mentions
+      # (any other strategy hides it).
+      UNCONFIGURED_LEVELS = { 'pass_through' => 'read', 'warn' => 'read', 'mask_all' => 'masked' }.freeze
+
+      # @param sources [EffectiveAccess::ResourceSources]
+      def initialize(sources, configuration:, catalog:)
+        @sources = sources
+        @configuration = configuration
+        @catalog = catalog
+        # entry: { read_access:, edit_access:, mask_access:, mask_strategy:, sources: [[set, level]], variant_of: }
+        @entries = {}
+      end
+
+      # @return [Array<EffectiveAccess::FieldOutcome>]
+      def call
+        merge_granting_fields
+        apply_muting_fields
+
+        model = @catalog.find(@sources.name)
+        (@entries.keys + Array(model&.managed_field_names)).uniq.map do |field|
+          field_outcome(field, model.present? && model.virtual_field?(field))
+        end
+      end
+
+      private
+
+      def active_fields(resource)
+        resource.resource_fields.select(&:is_active)
+      end
+
+      def variants_of(name)
+        @configuration.field_variants_for(name)
+      end
+
+      def merge_granting_fields
+        @sources.grants.each do |ps, resource|
+          active_fields(resource).each { |field| merge_granting_field(ps, field) }
+        end
+        implicit_names.each { |name| @entries[name] ||= implicit_entry }
+      end
+
+      def merge_granting_field(permission_set, field)
+        name = field.name
+        variants_of(name).each { |variant| merge_into(entry_for(variant, name), field, permission_set) }
+        merge_into(entry_for(name, nil), field, permission_set)
+      end
+
+      def entry_for(key, variant_of)
+        @entries[key] ||= { sources: [], variant_of: variant_of }
+      end
+
+      # The engine's own merge (FieldPermissionMerger.merge_row), plus provenance.
+      def merge_into(entry, field, permission_set)
+        Services::FieldPermissionMerger.merge_row(entry, field)
+        entry[:sources] << [permission_set, FieldLevel.level_of(field, muting: false), field.mask_strategy]
+      end
+
+      # Declared names that get the implicit read + edit entry; none under
+      # extra_fields_default_access = :unconfigured (they are then listed as
+      # unconfigured virtual fields instead). Read for any constant, like the
+      # engine does, not only for the models the catalog lists.
+      def implicit_names
+        PermissionForge::VirtualFields.new(@sources.name.to_s.safe_constantize, @configuration).implicit
+      end
+
+      # The engine's entry for the resource flags as the granting sets merged
+      # them (what some granting set grants, blocked later or not).
+      def implicit_entry
+        granted = @sources.flags.transform_values { |outcome| !outcome.granted_by.empty? }
+        Services::ExtraFieldDefaults.implicit_entry(granted).merge(sources: [], extra: true)
+      end
+
+      def apply_muting_fields
+        @sources.mutes.each do |ps, resource|
+          active_fields(resource).each { |field| apply_muting_field(ps, field) }
+          hide_every_field(ps) if resource.read_access
+        end
+      end
+
+      # A muting set that revokes the resource's read hides every field, as
+      # the engine does (PermissionHashBuilder#mute_fields_of_resource). One
+      # that revokes its edit caps every field to read: level_attrs does that
+      # from the resource's edit outcome.
+      def hide_every_field(permission_set)
+        @entries.each_value { |entry| hide_entry(entry, permission_set) }
+      end
+
+      def hide_entry(entry, permission_set)
+        entry[:read_access] = false
+        entry[:edit_access] = false
+        (entry[:mutes] ||= []) << [permission_set, 'hide']
+      end
+
+      def apply_muting_field(permission_set, field)
+        name = field.name
+        ([name] + variants_of(name)).each do |key|
+          entry = @entries[key]
+          mute_field(entry, field, permission_set) if entry
+        end
+      end
+
+      # The engine's own muting of a row (PermissionHashBuilder
+      # #mute_single_field: a row that mutes read mutes edit too), plus
+      # provenance.
+      def mute_field(entry, field, permission_set)
+        level = FieldLevel.level_of(field, muting: true)
+        return if level == 'leave'
+
+        entry[:read_access] = false if field.read_access
+        entry[:edit_access] = false if field.read_access || field.edit_access
+        entry[:mask_access] = true if field.mask_access
+        (entry[:mutes] ||= []) << [permission_set, level]
+      end
+
+      def field_outcome(name, virtual)
+        entry = @entries[name]
+        return unconfigured_outcome(name, virtual) if entry.nil?
+
+        implicit = entry[:extra].present?
+        FieldOutcome.new(
+          name: name, mask_strategy: entry[:mask_strategy], granted_by: granting_sources(entry),
+          unconfigured: false, virtual: virtual || implicit, implicit: implicit, variant_of: entry[:variant_of],
+          **level_attrs(entry), **muting_attrs(entry)
+        )
+      end
+
+      # Editable fields are capped to Read when the resource's Edit is not granted.
+      def level_attrs(entry)
+        level = FieldLevel.effective_level(entry)
+        capped = level == 'edit' && !@sources.flags[:edit_access].granted?
+        { level: capped ? 'read' : level, capped: capped }
+      end
+
+      def muting_attrs(entry)
+        mutes = entry[:mutes] || []
+        { blocked_by: mutes.map(&:first).uniq, blocked_level: mutes.last&.last }
+      end
+
+      # Sets that make the field readable, most open first. A set that lists
+      # the field as Hidden grants nothing and, like the engine, has no say in
+      # the mask. An implicit entry exists only when no set configured the
+      # field, so no set is credited for it: the level comes from the
+      # virtual-field default.
+      def granting_sources(entry)
+        return [] if entry[:extra]
+
+        entry[:sources].select { |_, lvl, _| FieldLevel.rank(lvl) >= 1 }
+                       .sort_by { |_, lvl, _| -FieldLevel.rank(lvl) }.map(&:first).uniq
+      end
+
+      def unconfigured_outcome(name, virtual)
+        FieldOutcome.new(name: name, level: unconfigured_level, mask_strategy: 'full', granted_by: [],
+                         blocked_by: [], capped: false, unconfigured: true, virtual: virtual, implicit: false)
+      end
+
+      def unconfigured_level
+        UNCONFIGURED_LEVELS.fetch(@configuration.unconfigured_field_strategy.to_s, 'hidden')
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/expiry_presets.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Assignment end-date presets. Calendar-day maths (date + n days), never
+    # seconds, so DST changes don't shift labels. An assignment ending on a
+    # date stays valid through the end of that day.
+    module ExpiryPresets
+      DAYS = { '1d' => 1, '1w' => 7, '30d' => 30 }.freeze
+      KEYS = %w[1d 1w 30d eom custom never].freeze
+      CHANGE_KEYS = %w[1w 30d eom never].freeze
+
+      class InvalidDate < StandardError; end
+
+      module_function
+
+      # @return [Date, nil] nil for "never"/"custom" without a date
+      def date_for(key, today: Time.zone.today, custom: nil)
+        case key.to_s
+        when *DAYS.keys then today + DAYS.fetch(key.to_s)
+        when 'eom' then today.end_of_month
+        when 'custom' then parse_custom(custom, today)
+        end
+      end
+
+      # The expires_at timestamp for a preset (end of the chosen day), or nil.
+      def expires_at_for(key, today: Time.zone.today, custom: nil)
+        date_for(key, today: today, custom: custom)&.in_time_zone&.end_of_day
+      end
+
+      def parse_custom(value, today)
+        raise InvalidDate, :missing if value.blank?
+
+        date = Date.iso8601(value.to_s)
+        raise InvalidDate, :not_future unless date > today
+
+        date
+      rescue Date::Error
+        raise InvalidDate, :missing
+      end
+
+      # Days until the assignment ends (0 = today, negative = ended), nil when
+      # it never ends.
+      def days_left(expires_at, today: Time.zone.today)
+        return nil if expires_at.nil?
+
+        (expires_at.to_date - today).to_i
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/exports/document.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module Exports
+      # A file the admin hands over (CSV or JSON): a metadata block — what was
+      # exported, when, by whom, with which filters, how many rows — then
+      # every row. Rows are produced lazily, one batch at a time, so a large
+      # export is written as it is read and nothing is cut off.
+      #
+      # CSV layout:
+      #   export,<kind>
+      #   exported_at,<ISO 8601>
+      #   exported_by,<label>          (and exported_by_type / exported_by_id)
+      #   filters,<JSON>
+      #   row_count,<n>
+      #   <empty line>
+      #   <column names>
+      #   <rows>
+      #
+      # JSON layout: { "meta": {...}, "columns": [...], "data": [ {...}, ... ] }
+      class Document
+        attr_reader :columns, :meta
+
+        # @param columns [Array<String>] the row keys, in order
+        # @param meta [Hash{String => Object}] export, exported_at, exported_by, filters, row_count …
+        # @param rows [#call] callable taking a block; yields each row as a Hash{String => Object}
+        def initialize(columns:, meta:, rows:)
+          @columns = columns
+          @meta = meta
+          @rows = rows
+        end
+
+        # @return [Enumerator<String>] the CSV, chunk by chunk
+        def csv
+          Enumerator.new do |out|
+            out << csv_head
+            @rows.call { |row| out << csv_row(row) }
+          end
+        end
+
+        # The metadata block, an empty line, the column names.
+        def csv_head
+          Csv.document(meta.map { |key, value| [key, flat(value)] }) + Csv::LINE_END + Csv.line(columns)
+        end
+
+        # @return [Enumerator<String>] the JSON, chunk by chunk
+        def json
+          Enumerator.new do |out|
+            out << %({"meta":#{ActiveSupport::JSON.encode(meta)},"columns":#{ActiveSupport::JSON.encode(columns)},"data":[)
+            first = true
+            @rows.call do |row|
+              out << (first ? '' : ',') << ActiveSupport::JSON.encode(row.slice(*columns))
+              first = false
+            end
+            out << "]}\n"
+          end
+        end
+
+        # @param format [Symbol, String] :csv or :json
+        # @return [Enumerator<String>]
+        def chunks(format)
+          format.to_s == 'json' ? json : csv
+        end
+
+        # The whole file as one String (tests, small exports).
+        def render(format)
+          chunks(format).to_a.join
+        end
+
+        private
+
+        # One row as a CSV line, in column order.
+        def csv_row(row)
+          Csv.line(columns.map { |column| flat(row[column]) })
+        end
+
+        # A cell: Hashes and Arrays as JSON, times in ISO 8601, the rest as text.
+        def flat(value)
+          case value
+          when Hash, Array then ActiveSupport::JSON.encode(value)
+          when Time, DateTime, ActiveSupport::TimeWithZone then value.utc.iso8601(6)
+          else value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/exports/events.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module Exports
+      # The audit log export: every event the filter matches (views of the
+      # log included, whatever the page hid), oldest first,
+      # with every column (the JSON API's, from AuditEventSerializer) and
+      # `data` as JSON. The rows are fixed when the export starts — the
+      # events up to the newest one then — so the row count in the metadata
+      # is the number of rows that follow, even while new events (this
+      # export's own audit.exported, for one) are being written.
+      class Events
+        BATCH_SIZE = 1000
+        KIND = 'audit_events'
+
+        def self.columns
+          PermissionForge::Api::Serializers::AuditEventSerializer.attribute_names.map(&:to_s)
+        end
+
+        # @param relation [ActiveRecord::Relation] the filtered events, in any order
+        # @param filters [Hash] the filters, as written in the metadata
+        # @param exported_by [Audit::Actor]
+        # @param batch_size [Integer] events read per query
+        # @param time_zone [String] the zone date-only filters were read in
+        # @return [Document]
+        def self.call(relation, filters:, exported_by: PermissionForge::Audit::Actor.current, now: Time.current, # rubocop:disable Metrics/ParameterLists
+                      batch_size: BATCH_SIZE, time_zone: AuditLogDays.zone_name)
+          events = snapshot(relation.unscope(:order))
+          # An export is evidence: views of the log are always in it, and it says so.
+          meta = Exports.meta(KIND, exported_by: exported_by, filters: filters.to_h.merge('include_views' => true),
+                                    row_count: events.count, now: now, time_zone: time_zone)
+          Document.new(columns: columns, meta: meta, rows: lambda { |&row|
+            events.find_each(batch_size: batch_size) { |event| row.call(serialize(event)) }
+          })
+        end
+
+        def self.snapshot(events)
+          newest = events.maximum(:id)
+          newest ? events.where(id: ..newest) : events.none
+        end
+
+        def self.serialize(event)
+          PermissionForge::Api::Serializers::AuditEventSerializer.new(event).as_json.transform_keys(&:to_s)
+        end
+
+        private_class_method :snapshot, :serialize
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/exports/holdings.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    module Exports
+      # "Who holds what": every assignment as it stands — the person, the
+      # Permission Set, when and by whom it was granted, when it ends, when
+      # and by whom it was last reviewed, and the reason of its last change.
+      # Granted by is the actor of the assignment.granted event when the
+      # audit log has one, else the created_by column.
+      #
+      # The rows are read while the file is written (batches of BATCH_SIZE,
+      # the way the events export does), never all at once. `row_count` in the
+      # metadata is a COUNT taken when the export starts, on the assignments up
+      # to the newest id then. Assignments are changed and removed, not only
+      # added: one removed while the file is written is missing from it
+      # (`row_count` can then exceed the rows), and each row shows its
+      # assignment as it was when its batch was read. The person lookups run
+      # per batch, in the tenant and with the record rules suspended as in the
+      # action (AuditEventsController#pf_stream).
+      class Holdings
+        BATCH_SIZE = 500
+        KIND = 'holdings'
+        COLUMNS = %w[assignment_id assignment_uuid person_id person permission_set_id permission_set_uuid permission_set
+                     muting set_active granted_at granted_by_type granted_by_id granted_by expires_at expired
+                     reviewed_at reviewed_by_id reviewed_by reason].freeze
+
+        # @param exported_by [Audit::Actor]
+        # @param batch_size [Integer] assignments read per query
+        # @return [Document]
+        def self.call(exported_by: PermissionForge::Audit::Actor.current, now: Time.current, batch_size: BATCH_SIZE)
+          new(now, batch_size).document(exported_by)
+        end
+
+        def initialize(now, batch_size = BATCH_SIZE)
+          @now = now
+          @batch_size = batch_size
+        end
+
+        def document(exported_by)
+          assignments = snapshot
+          meta = Exports.meta(KIND, exported_by: exported_by, filters: {}, row_count: assignments.count, now: @now)
+          Document.new(columns: COLUMNS, meta: meta, rows: ->(&row) { each_row(assignments, &row) })
+        end
+
+        private
+
+        # The assignments as they stand now: up to the newest id.
+        def snapshot
+          assignments = PermissionForge::PermissionSetUser.includes(:permission_set, :user)
+          newest = assignments.maximum(:id)
+          newest ? assignments.where(id: ..newest) : assignments.none
+        end
+
+        # Outside the query cache: it would keep every batch's results for the request.
+        def each_row(assignments, &)
+          ActiveRecord::Base.uncached { each_batch(assignments, &) }
+        end
+
+        def each_batch(assignments)
+          assignments.find_in_batches(batch_size: @batch_size) do |batch|
+            granted = LastChanges.new(batch, events: %w[assignment.granted])
+            people = people_by_id(batch)
+            batch.each { |assignment| yield row(assignment, granted[assignment], people) }
+          end
+        end
+
+        def row(assignment, grant_event, people)
+          set = assignment.permission_set
+          person(assignment).merge(permission_set_columns(set)).merge(
+            'granted_at' => assignment.created_at, **granted_by(assignment, grant_event, people),
+            'expires_at' => assignment.expires_at, 'expired' => assignment.expired?,
+            **reviewed(assignment, people), 'reason' => assignment.try(:reason)
+          )
+        end
+
+        def person(assignment)
+          { 'assignment_id' => assignment.id, 'assignment_uuid' => assignment.try(:uuid), 'person_id' => assignment.user_id,
+            'person' => label(assignment.user) }
+        end
+
+        def permission_set_columns(set)
+          { 'permission_set_id' => set&.id, 'permission_set_uuid' => set&.uuid, 'permission_set' => set&.name,
+            'muting' => set&.is_muting, 'set_active' => set&.is_active }
+        end
+
+        def granted_by(assignment, event, people)
+          if event
+            return { 'granted_by_type' => event.actor_type, 'granted_by_id' => event.actor_id,
+                     'granted_by' => event.actor_label }
+          end
+
+          id = assignment.try(:created_by_id)
+          { 'granted_by_type' => (id ? 'user' : nil), 'granted_by_id' => id, 'granted_by' => label(people[id.to_s]) }
+        end
+
+        def reviewed(assignment, people)
+          id = assignment.try(:reviewed_by_id)
+          { 'reviewed_at' => assignment.try(:reviewed_at), 'reviewed_by_id' => id, 'reviewed_by' => label(people[id.to_s]) }
+        end
+
+        # The creators and reviewers of a batch, by id (String).
+        def people_by_id(batch)
+          ids = batch.flat_map { |assignment| [assignment.try(:created_by_id), assignment.try(:reviewed_by_id)] }.compact.uniq
+          return {} if ids.empty?
+
+          PermissionForge.configuration.user_model.where(id: ids).index_by { |user| user.id.to_s }
+        rescue StandardError
+          {}
+        end
+
+        def label(user)
+          PersonLabel.new(user).name if user
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/exports.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # Files the admin hands over: the audit log (Exports::Events) and who
+    # holds what (Exports::Holdings), written by Exports::Document.
+    module Exports
+      module_function
+
+      # The metadata block every export starts with.
+      #
+      # @param kind [String] what was exported
+      # @param exported_by [Audit::Actor]
+      # @param filters [Hash]
+      # @param row_count [Integer]
+      # @param time_zone [String] the zone date-only filters were read in
+      # @return [Hash{String => Object}]
+      def meta(kind, exported_by:, filters:, row_count:, now: Time.current, time_zone: AuditLogDays.zone_name) # rubocop:disable Metrics/ParameterLists
+        {
+          'export' => kind,
+          'exported_at' => now.utc.iso8601,
+          'time_zone' => time_zone,
+          'exported_by' => exported_by.label || exported_by.type,
+          'exported_by_type' => exported_by.type,
+          'exported_by_id' => exported_by.id,
+          'filters' => filters.to_h.transform_keys(&:to_s),
+          'row_count' => row_count
+        }
+      end
+
+      # A file name: permission-forge-<kind>-<UTC timestamp>.<format>
+      def filename(kind, format, now: Time.current)
+        "permission-forge-#{kind.to_s.tr('_', '-')}-#{now.utc.strftime('%Y%m%dT%H%M%SZ')}.#{format}"
+      end
+    end
+  end
+end