permission_forge 0.14.1

data/app/helpers/permission_forge/audit_helper.rb

@@ -0,0 +1,230 @@
+module PermissionForge
+  # Labels and links for audit rows (Person → Audit, Permission Set → Audit,
+  # CSV) and for audit events (the audit log, the timelines, an event).
+  #
+  # @api private
+  module AuditHelper
+    # Every category has a glyph and a word (never colour alone).
+    CATEGORY_GLYPHS = { 'change' => '✎', 'admin' => '⚑', 'system' => '⚙', 'access' => '◉' }.freeze
+    CATEGORY_VARIANTS = { 'change' => :changed, 'admin' => :warn, 'system' => :default, 'access' => :mask }.freeze
+    # The message Audit::EventQuery gives a filter that needs a value (Rails' own).
+    QUERY_BLANK_MESSAGE = 'errors.messages.blank'.freeze
+    # [record label, where] per audited type; evaluated in the view context.
+    AUDIT_LABELS = {
+      'permission_set' => ->(record) { [record.name, nil] },
+      'group' => ->(record) { [record.name, nil] },
+      'resource' => ->(record) { [pf_resource_label(record), record.permission_set&.name] },
+      'field' => ->(record) { [record.label.presence || record.name, pf_audit_resource_where(record.resource)] },
+      'action' => ->(record) { [record.label.presence || record.name, pf_audit_resource_where(record.resource)] },
+      'rule' => ->(record) { [record.name, pf_audit_resource_where(record.resource)] },
+      'assignment' => ->(record) { [pf_person_name(record.user), record.permission_set&.name] },
+      'group_membership' => ->(record) { [pf_person_name(record.user), record.permission_set_group&.name] }
+    }.freeze
+
+    # Link target per audited type; evaluated in the view context.
+    AUDIT_PATHS = {
+      'permission_set' => ->(record) { permission_forge.permission_set_path(record) },
+      'resource' => ->(record) { permission_forge.permission_set_resource_path(record.permission_set_id, record.name) },
+      'field' => ->(record) { pf_audit_nested_path(record.resource, :field, record.name) },
+      'action' => ->(record) { pf_audit_nested_path(record.resource, :action, record.id) },
+      'rule' => ->(record) { pf_audit_nested_path(record.resource, :rule, record.id) },
+      'assignment' => ->(record) { permission_forge.person_path(record.user_id) },
+      'group' => ->(record) { permission_forge.group_path(record) },
+      'group_membership' => ->(record) { permission_forge.group_path(record.permission_set_group_id) }
+    }.freeze
+
+    def pf_audit_type_label(type)
+      t("permission_forge.ui.audit.types.#{type}")
+    end
+
+    # [type label, record label, where] — also used for CSV export.
+    def pf_audit_describe(entry)
+      record = entry.record
+      label, where = pf_audit_label_and_where(entry.type, record)
+      [pf_audit_type_label(entry.type), label, where]
+    end
+
+    def pf_audit_label_and_where(type, record)
+      pf_audit_lookup(AUDIT_LABELS, type, record)
+    end
+
+    def pf_audit_resource_where(resource)
+      return nil unless resource
+
+      "#{resource.permission_set&.name} › #{pf_resource_label(resource)}"
+    end
+
+    def pf_audit_path(entry)
+      pf_audit_lookup(AUDIT_PATHS, entry.type, entry.record)
+    end
+
+    # Runs the registry entry for `type` in the view context; nil for unknown types.
+    def pf_audit_lookup(registry, type, record)
+      handler = registry[type]
+      instance_exec(record, &handler) if handler
+    end
+
+    def pf_audit_nested_path(resource, kind, key)
+      return nil unless resource
+
+      case kind
+      when :field then permission_forge.permission_set_resource_field_path(resource.permission_set_id, resource.name, key)
+      when :action then permission_forge.permission_set_resource_action_path(resource.permission_set_id, resource.name, key)
+      when :rule then permission_forge.edit_permission_set_resource_rule_path(resource.permission_set_id, resource.name, key)
+      end
+    end
+
+    def pf_audit_who_when(person, time, relative: false)
+      t('permission_forge.ui.audit.who_when', who: pf_person_name(person),
+                                              when: relative ? pf_relative(time) : pf_date(time))
+    end
+
+    # "Who · when" of an entry's last edit: the latest change event's actor
+    # and time when there is one, else updated_by / updated_at.
+    def pf_audit_edited(entry)
+      return pf_audit_who_when(entry.updated_by, entry.updated_at, relative: true) unless entry.last_event
+
+      t('permission_forge.ui.audit.who_when', who: pf_audit_actor_name(entry.last_event), when: pf_relative(entry.updated_at))
+    end
+
+    # The record's last edit as an event (who really made it), or nil when
+    # the audit log has none for it or the record was edited after it.
+    # Uses the page's preloaded lookup when it covers the record.
+    def pf_audit_last_change(record)
+      lookup = @pf_last_changes if @pf_last_changes&.covers?(record)
+      (lookup || PermissionForge::Admin::LastChanges.new([record])).last_edit(record)
+    end
+
+    # One lookup for every record whose footer the page shows (two queries
+    # per record type instead of two per footer). Nothing while the audit
+    # trail is off: the footers then say so and ask nothing.
+    def pf_audit_preload_last_changes(records)
+      return unless PermissionForge.configuration.audit_trail_enabled
+
+      @pf_last_changes = PermissionForge::Admin::LastChanges.new(records)
+      nil
+    end
+
+    # [created by, last edited by] names for the audit-trail CSV.
+    def pf_audit_people(entry)
+      edited_by = entry.last_event ? pf_audit_actor_name(entry.last_event) : pf_person_name(entry.updated_by)
+      [pf_person_name(entry.created_by), edited_by]
+    end
+
+    # --- audit events ---------------------------------------------------------
+
+    # Who acted, as recorded: the name snapshot, with what kind of actor it
+    # was when that is not a person ("ops (password prompt)", "API client").
+    def pf_audit_actor_name(event)
+      type = event.actor_type.to_s
+      label = event.actor_label.presence
+      return t("permission_forge.audit_log.actor_named.#{type}", name: label, default: label) if label
+      return t('permission_forge.audit_log.person_id', id: event.actor_id) if type == 'user' && event.actor_id.present?
+
+      pf_audit_actor_type_label(type)
+    end
+
+    def pf_audit_actor_type_label(type)
+      t("permission_forge.audit_log.actor_types.#{type}", default: type.to_s.humanize)
+    end
+
+    def pf_audit_category_label(category)
+      t("permission_forge.audit_log.categories.#{category}", default: category.to_s.humanize)
+    end
+
+    def pf_audit_source_label(source)
+      t("permission_forge.audit_log.sources.#{source}", default: source.to_s.humanize)
+    end
+
+    def pf_audit_category_badge(category)
+      pf_badge("#{CATEGORY_GLYPHS.fetch(category.to_s, '•')} #{pf_audit_category_label(category)}",
+               variant: CATEGORY_VARIANTS.fetch(category.to_s, :default))
+    end
+
+    def pf_audit_event_path(event, **)
+      permission_forge.audit_event_path(event.uuid, **)
+    end
+
+    # The audit log, filtered (only the filters given).
+    def pf_audit_log_path(**filters)
+      permission_forge.audit_events_path(filters.compact_blank)
+    end
+
+    # The person an event is about: the label an assignment's or a
+    # membership's event kept (their name then), else the user when they
+    # still exist, else their id.
+    def pf_audit_person_name(event, lookups)
+      id = event.subject_user_id
+      return nil if id.blank?
+
+      return event.record_label if pf_audit_person_record?(event) && event.record_label.present?
+
+      user = lookups.person(id)
+      return pf_person_name(user) if user
+
+      t('permission_forge.audit_log.person_id', id: id)
+    end
+
+    def pf_audit_person_record?(event)
+      %w[PermissionForge::PermissionSetUser PermissionForge::PermissionSetGroupUser].include?(event.record_type)
+    end
+
+    # The Permission Set's name when the event happened (AuditLookups), or
+    # what the event says about it.
+    def pf_audit_set_name(event, lookups)
+      return nil if event.permission_set_id.blank? && event.permission_set_uuid.blank?
+      return event.record_label if event.record_type == 'PermissionForge::PermissionSet' && event.record_label.present?
+
+      name = lookups.permission_set_name(event)
+      return name if name
+
+      t('permission_forge.audit_log.deleted_set', id: event.permission_set_id || event.permission_set_uuid)
+    end
+
+    def pf_audit_group_name(event, lookups)
+      name = lookups.group_name(event)
+      return name if name
+
+      id = PermissionForge::Admin::AuditLookups.group_id(event)
+      id ? t('permission_forge.audit_log.deleted_group', id: id) : t('permission_forge.audit_log.unknown_group')
+    end
+
+    # What the event is about: its label snapshot, else type and id.
+    def pf_audit_record_name(event)
+      return event.record_label if event.record_label.present?
+      return '' if event.record_type.blank?
+
+      [event.record_type.to_s.demodulize.titleize, event.record_id || event.record_uuid].compact.join(' #')
+    end
+
+    # A value of a before/after or snapshot table: text as it is, nothing as
+    # a dash-word, anything else as JSON.
+    def pf_audit_value(value)
+      case value
+      when nil then t('permission_forge.audit_log.no_value')
+      when String then value.empty? ? t('permission_forge.audit_log.empty_text') : value
+      when true, false then t("permission_forge.audit_log.boolean.#{value}")
+      when Numeric then value.to_s
+      else ActiveSupport::JSON.encode(value)
+      end
+    end
+
+    # One line per refused filter, in the admin's own words (EventQuery's
+    # messages are Rails' errors.messages, which a host may not translate):
+    # a value that is needed, or the value that is not valid.
+    def pf_audit_filter_error(name, messages, value)
+      field = t("permission_forge.audit_events.index.filters.#{name}", default: name.to_s.humanize)
+      scope = 'permission_forge.audit_events.index.invalid'
+      return t("#{scope}.blank", field: field) if Array(messages).include?(I18n.t(QUERY_BLANK_MESSAGE))
+      return t("#{scope}.invalid", field: field) if value.blank?
+
+      t("#{scope}.invalid_value", field: field, value: value.truncate(80))
+    end
+
+    # The first scalar of a filter parameter (a list or a hash shows nothing).
+    def pf_audit_filter_value(filters, key)
+      value = filters[key]
+      value.is_a?(String) ? value : nil
+    end
+  end
+end

data/app/helpers/permission_forge/audit_sentences_helper.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # One plain-language sentence per audit event ("Ana gave Bo the Permission
+  # Set Sales.").
+  #
+  # @api private
+  module AuditSentencesHelper
+    AUDIT_SENTENCES = 'permission_forge.audit_log.sentences'
+
+    # Events whose sentence depends on what they recorded: event name →
+    # a block (run in the view) that returns the sentence, or nil for the
+    # event's own one. Adding a variant is one entry here plus its key.
+    AUDIT_SENTENCE_VARIANTS = {
+      # Names the fields that were hidden or masked; a read with none of
+      # them is the plain "read X." sentence.
+      'field.access' => lambda { |event, parts|
+        fields = pf_audit_limited_fields(event)
+        next if fields.empty?
+
+        t('permission_forge.audit_log.sentence_variants.field_access_limited', **parts, fields: fields.join(', '))
+      },
+      # A revocation of an assignment that had already ended (the clean-up).
+      'assignment.revoked' => lambda { |event, parts|
+        ended = pf_audit_expired_at(event)
+        next unless ended
+
+        t('permission_forge.audit_log.sentence_variants.assignment_revoked_expired', **parts, date: pf_date(ended))
+      }
+    }.freeze
+
+    # One sentence per event, from the locale key named after the event
+    # (permission_forge.audit_log.sentences.<event>): a new event needs one
+    # key in each locale, and an event without one (a host's own) still reads
+    # as "<actor>: <event name>". Interpolations: actor, record, set, person,
+    # group, event, model (a runtime event's model).
+    def pf_audit_sentence(event, lookups)
+      parts = pf_audit_sentence_parts(event, lookups)
+      variant = AUDIT_SENTENCE_VARIANTS[event.event]
+      variant &&= instance_exec(event, parts, &variant)
+      return variant if variant
+
+      fallback = t("#{AUDIT_SENTENCES}.fallback", **parts)
+      sentence = t("#{AUDIT_SENTENCES}.#{event.event}", **parts, default: fallback)
+      sentence.is_a?(String) ? sentence : fallback
+    end
+
+    # The hidden and masked field names a field.access event lists.
+    def pf_audit_limited_fields(event)
+      data = event.data || {}
+      %w[hidden masked].flat_map { |key| Array(data[key]) }.map(&:to_s).uniq
+    end
+
+    # When the revoked assignment had ended, if it had ended before the
+    # revocation (its snapshot's expires_at).
+    def pf_audit_expired_at(event)
+      snapshot = event.data.is_a?(Hash) ? event.data['snapshot'] : nil
+      ended = pf_audit_time(snapshot['expires_at']) if snapshot.is_a?(Hash)
+      ended if ended && event.occurred_at && ended <= event.occurred_at
+    end
+
+    def pf_audit_time(value)
+      Time.zone.parse(value.to_s) if value.present?
+    rescue ArgumentError
+      nil
+    end
+
+    def pf_audit_sentence_parts(event, lookups)
+      unknown = t('permission_forge.audit_log.unknown')
+      {
+        actor: pf_audit_actor_name(event), record: pf_audit_record_name(event).presence || unknown,
+        set: pf_audit_set_name(event, lookups) || unknown, person: pf_audit_person_name(event, lookups) || unknown,
+        group: pf_audit_person_record?(event) ? pf_audit_group_name(event, lookups) : unknown, event: event.event,
+        model: pf_audit_model_name(event).presence || unknown
+      }
+    end
+
+    # The model a runtime event is about: data['model'], else the record type.
+    def pf_audit_model_name(event)
+      model = event.data.is_a?(Hash) ? event.data['model'] : nil
+      (model.is_a?(String) ? model : event.record_type).to_s.demodulize
+    end
+  end
+end

data/app/helpers/permission_forge/badges_helper.rb

@@ -0,0 +1,134 @@
+module PermissionForge
+  # Badges, Permission Set chips, field level badges and mask previews.
+  # Every class is pf- prefixed; no inline styles (strict-CSP friendly).
+  #
+  # @api private
+  module BadgesHelper
+    LEVEL_GLYPHS = { 'hidden' => '∅', 'masked' => '••', 'read' => '◉', 'edit' => '✎', 'leave' => '–',
+                     'mask' => '••', 'hide' => '⊘', 'muted' => '⊘', 'none' => '–' }.freeze
+
+    MASK_SAMPLES = [
+      [/email/, 'james.walker@acme.com'],
+      [/iban|bank|account|card/, 'DE89 3704 0044 0532 0130 00'],
+      [/phone|mobile|fax|tel/, '+383 44 123 456'],
+      [/cents|salary|amount|price|value/, '4 200,00 €'],
+      [/national|ssn|social/, '1234567890'],
+      [/birth|dob/, '1988-04-17'],
+      [/vat|tax/, 'XK810123456'],
+      [/address|street|city|zip|postal/, 'Rruga Agim Ramadani 15']
+    ].freeze
+    DEFAULT_MASK_SAMPLE = 'James Walker'.freeze
+
+    CHIP_PREFIXES = { muting: '⊘ ', inactive: '○ ' }.freeze
+    CHIP_SUFFIX_KEYS = { inactive: 'badges.off', expired: 'badges.expired' }.freeze
+
+    # --- badges ---------------------------------------------------------------
+
+    # Options: title:, href:, square: (bool), extra: (additional classes).
+    def pf_badge(text, variant: :default, **opts)
+      classes = ['pf-badge', ("pf-badge--#{variant}" unless variant.to_s == 'default'),
+                 ('pf-badge--square' if opts[:square]), opts[:extra]].compact.join(' ')
+      content = safe_join(Array(text))
+      href = opts[:href]
+      return link_to(content, href, class: classes, title: opts[:title]) if href
+
+      content_tag(:span, content, class: classes, title: opts[:title])
+    end
+
+    def pf_lock_badge(title: pf_ui('locked.title'))
+      pf_badge([pf_lock_icon, pf_ui('badges.locked')], title: title)
+    end
+
+    def pf_off_badge
+      content_tag(:span, "○ #{pf_ui('badges.off')}", class: 'pf-badge pf-badge--off')
+    end
+
+    def pf_fail_open?
+      !PermissionForge.configuration.conditional_sets_strict_mode
+    end
+
+    def pf_fail_open_badge(long: false)
+      text = long ? pf_ui('badges.fail_open_long') : pf_ui('badges.fail_open')
+      pf_badge("⚠ #{text}", variant: :failopen, href: pf_setting_path('conditional_sets_strict_mode'),
+                            title: pf_ui('badges.fail_open_title'))
+    end
+
+    def pf_set_badges(permission_set)
+      badges = []
+      badges << pf_badge("⊘ #{pf_ui('badges.muting')}", variant: :muting) if permission_set.is_muting
+      if permission_set.conditional?
+        badges << pf_badge("◷ #{pf_ui('badges.conditional')}", variant: :conditional,
+                                                               title: pf_condition_sentence(permission_set))
+        badges << pf_fail_open_badge if pf_fail_open?
+      end
+      badges << pf_lock_badge if pf_locked_record?(permission_set)
+      safe_join(badges, ' ')
+    end
+
+    def pf_locked_record?(record)
+      record.respond_to?(:is_editable) && record.is_editable == false
+    end
+
+    # Permission Set chip. state: :normal / :inactive / :expired (auto from set).
+    def pf_set_chip(permission_set, large: false, href: :auto, expired: false)
+      state = pf_set_chip_state(permission_set, expired)
+      classes = ['pf-chip', ('pf-chip--lg' if large), ("pf-chip--#{state}" unless state == :normal)].compact.join(' ')
+      body = pf_set_chip_body(permission_set, state)
+      href = permission_forge.permission_set_path(permission_set) if href == :auto
+      href ? link_to(body, href, class: classes) : content_tag(:span, body, class: classes)
+    end
+
+    def pf_set_chip_state(permission_set, expired)
+      return :expired if expired
+      return :inactive unless permission_set.is_active
+
+      permission_set.is_muting ? :muting : :normal
+    end
+
+    def pf_set_chip_body(permission_set, state)
+      suffix_key = CHIP_SUFFIX_KEYS[state]
+      safe_join([content_tag(:span, "#{CHIP_PREFIXES[state]}#{permission_set.name}"),
+                 (content_tag(:span, pf_ui(suffix_key), class: 'pf-chip__suffix') if suffix_key)].compact, ' ')
+    end
+
+    # Effective/configured field level badge ("•• Masked · j***@acme.com").
+    def pf_level_badge(level, strategy: nil, sample_for: nil, label: nil)
+      level = level.to_s
+      text = label || pf_level_label(level)
+      if %w[masked mask].include?(level) && strategy.present?
+        text = "#{text} (#{pf_mask_strategy_label(strategy)})"
+        text = "#{text} · #{pf_mask_preview(sample_for, strategy)}" if sample_for
+      end
+      content_tag(:span, "#{LEVEL_GLYPHS.fetch(level, '–')} #{text}", class: "pf-level-badge pf-level-badge--#{level}")
+    end
+
+    def pf_level_label(level)
+      pf_ui("levels.#{level}")
+    end
+
+    def pf_mask_strategy_label(strategy)
+      t("permission_forge.ui.mask_strategies.#{strategy}", default: strategy.to_s)
+    end
+
+    def pf_mask_strategies
+      PermissionForge::Services::MaskValue.strategies.keys.map(&:to_s)
+    end
+
+    def pf_custom_mask_strategy?(strategy)
+      !PermissionForge::Services::MaskValue::BUILT_IN_STRATEGIES.key?(strategy.to_s)
+    end
+
+    def pf_mask_sample(column)
+      name = column.to_s
+      MASK_SAMPLES.find { |pattern, _| name.match?(pattern) }&.last || DEFAULT_MASK_SAMPLE
+    end
+
+    # Runs the real MaskValue strategy on a sample value, so previews always
+    # match what people will see.
+    def pf_mask_preview(column, strategy)
+      PermissionForge::Services::MaskValue.call(pf_mask_sample(column), strategy: strategy.to_s)
+    rescue StandardError
+      '••••••••'
+    end
+  end
+end

data/app/helpers/permission_forge/changes_helper.rb

@@ -0,0 +1,117 @@
+module PermissionForge
+  # One plain-language line per ChangeSet change (the "Review and save" list).
+  #
+  # @api private
+  module ChangesHelper
+    # ChangeSet::Change#kind => the helper that words it. A new kind is one
+    # entry here plus its helper.
+    CHANGE_DESCRIBERS = {
+      set_attr: :pf_set_attr_change, resource_flag: :pf_resource_flag_change, resource_text: :pf_resource_text_change,
+      field_level: :pf_field_level_change, new_field: :pf_field_level_change, field_attr: :pf_field_attr_change,
+      action: :pf_action_change, new_action: :pf_new_action_change
+    }.freeze
+
+    def pf_change_description(change)
+      describer = CHANGE_DESCRIBERS[change.kind]
+      send(describer, change) if describer
+    end
+
+    def pf_resource_text_change(change)
+      pf_ui('changes.resource_text', resource: pf_resource_label(change.record),
+                                     attribute: pf_ui("changes.attributes.#{change.attribute}"))
+    end
+
+    def pf_action_change(change)
+      muting = change.resource&.permission_set&.is_muting
+      key = if muting then change.to ? 'changes.action_muted' : 'changes.action_unmuted'
+            else change.to ? 'changes.action_on' : 'changes.action_off'
+            end
+      pf_ui(key, resource: pf_resource_label(change.resource), action: change.record.display_name)
+    end
+
+    # A discovered controller action added to the set, followed by what that
+    # means for everyone: "Customer: Export added, permitted (this makes it
+    # managed: ...)".
+    def pf_new_action_change(change)
+      resource = change.resource
+      action = change.record
+      key = if resource.permission_set.is_muting then change.to ? 'changes.action_new_muted' : 'changes.action_new_unmuted'
+            else change.to ? 'changes.action_new_on' : 'changes.action_new_off'
+            end
+      text = pf_ui(key, resource: pf_resource_label(resource), action: action.display_name)
+      "#{text} #{pf_action_managed_note(resource, action.name)}"
+    end
+
+    # The first row for an action makes it managed for everyone; later rows
+    # join the sets that already manage it.
+    def pf_action_managed_note(resource, key)
+      return pf_ui('changes.action_managed_later') unless resource.in_effect?
+
+      across = pf_action_across(resource.name)
+      return pf_ui('changes.action_managed_first') unless across.managed?(key)
+
+      sets = across.permitting_sets(key).map(&:name)
+      sets.any? ? pf_ui('changes.action_managed_already', sets: sets.join(', ')) : pf_ui('changes.action_managed_nobody')
+    end
+
+    # One lookup per resource name per page.
+    def pf_action_across(resource_name)
+      (@pf_action_across ||= {})[resource_name] ||= PermissionForge::Admin::ActionAcrossSets.new(resource_name)
+    end
+
+    def pf_set_attr_change(change)
+      case change.attribute
+      when 'is_active' then pf_ui(change.to ? 'changes.set_on' : 'changes.set_off')
+      when 'permission_set_group_id'
+        group = change.to && PermissionForge::PermissionSetGroup.find_by(id: change.to)
+        group ? pf_ui('changes.set_group', group: group.name) : pf_ui('changes.set_no_group')
+      else pf_ui('changes.set_text', attribute: pf_ui("changes.attributes.#{change.attribute}"))
+      end
+    end
+
+    def pf_resource_flag_change(change)
+      key = change.to ? 'changes.flag_on' : 'changes.flag_off'
+      key = "#{key}_muting" if change.resource&.permission_set&.is_muting
+      text = pf_ui(key, resource: pf_resource_label(change.resource), flag: pf_flag_name(change.attribute))
+      change.cascaded ? "#{text} #{pf_ui('changes.cascaded')}" : text
+    end
+
+    def pf_flag_name(flag)
+      pf_ui("flags_short.#{flag}")
+    end
+
+    def pf_field_level_change(change)
+      from_level, = Array(change.from)
+      args = { resource: pf_resource_label(change.resource), field: pf_change_field_name(change.record),
+               to: pf_change_level_text(change.to) }
+      text = if from_level
+               pf_ui('changes.field_level', **args, from: pf_level_label(from_level))
+             else
+               pf_ui('changes.field_new', **args)
+             end
+      change.cascaded ? "#{text} #{pf_ui('changes.cascaded_field')}" : text
+    end
+
+    # "Masked (email)" for [level, strategy].
+    def pf_change_level_text(level_and_strategy)
+      level, strategy = Array(level_and_strategy)
+      text = pf_level_label(level)
+      %w[masked mask].include?(level) && strategy ? "#{text} (#{pf_mask_strategy_label(strategy)})" : text
+    end
+
+    def pf_change_field_name(field)
+      field.label.presence || field.name
+    end
+
+    def pf_field_attr_change(change)
+      field = change.record
+      if change.attribute == 'is_active'
+        return pf_ui(change.to ? 'changes.field_on' : 'changes.field_off', resource: pf_resource_label(change.resource),
+                                                                           field: field.label.presence || field.name)
+      end
+
+      pf_ui('changes.field_text', resource: pf_resource_label(change.resource), field: field.name,
+                                  attribute: pf_ui("changes.attributes.#{change.attribute}"))
+    end
+  end
+end

data/app/helpers/permission_forge/people_helper.rb

@@ -0,0 +1,118 @@
+module PermissionForge
+  # Person labels, avatars and assignment expiry/review cells.
+  #
+  # @api private
+  module PeopleHelper
+    def pf_person(user)
+      @pf_person_labels ||= {}
+      @pf_person_labels[[user.class.name, user.id]] ||= PermissionForge::Admin::PersonLabel.new(user)
+    end
+
+    def pf_person_name(user)
+      user ? pf_person(user).name : pf_ui('audit.system')
+    end
+
+    def pf_avatar(user, size: nil)
+      classes = ['pf-avatar', ("pf-avatar--#{size}" if size)].compact.join(' ')
+      content_tag(:span, pf_person(user).initials, class: classes, 'aria-hidden': true)
+    end
+
+    # Avatar + name + email block.
+    def pf_person_cell(user, href: nil)
+      label = pf_person(user)
+      body = safe_join([pf_avatar(user),
+                        content_tag(:span, class: 'pf-stack pf-stack--tight pf-ellipsis') do
+                          safe_join([content_tag(:span, label.name, class: 'pf-person-name pf-ellipsis'),
+                                     (content_tag(:span, label.secondary, class: 'pf-person-email pf-ellipsis') if label.secondary)].compact)
+                        end])
+      href ? link_to(body, href, class: 'pf-cell-person') : content_tag(:span, body, class: 'pf-cell-person')
+    end
+
+    # --- assignments --------------------------------------------------------
+
+    # [text, css tone class] for an assignment end date.
+    def pf_expiry(expires_at)
+      days = PermissionForge::Admin::ExpiryPresets.days_left(expires_at)
+      return [pf_ui('expiry.none'), 'pf-text-2'] if days.nil?
+      return [pf_ui('expiry.expired', date: pf_date(expires_at, year: false)), 'pf-text-3'] if expires_at < Time.current
+      return [pf_ui('expiry.today'), 'pf-text-warn'] if days.zero?
+      return [pf_ui('expiry.ends_in', count: days, date: pf_date(expires_at, year: false)), 'pf-text-warn'] if days <= 7
+
+      [pf_ui('expiry.until', date: pf_date(expires_at, year: false)), 'pf-text-2']
+    end
+
+    def pf_expiry_tag(expires_at)
+      text, tone = pf_expiry(expires_at)
+      content_tag(:span, text, class: tone)
+    end
+
+    # "✓ Reviewed by Ana on 3 Oct 2026" / "– Never reviewed"; a warning
+    # (⚠, warn tone) when the assignment is due for review (pf_stale?).
+    def pf_reviewed(assignment)
+      stale = pf_stale?(assignment)
+      reviewed = pf_review_known?(assignment) && assignment.reviewed_at.present?
+      glyph = content_tag(:span, pf_review_glyph(stale, reviewed), 'aria-hidden': true)
+      content_tag(:span, safe_join([glyph, pf_review_text(assignment)], ' '), class: "pf-fs-12 #{stale ? 'pf-text-warn' : 'pf-text-3'}")
+    end
+
+    def pf_review_glyph(stale, reviewed)
+      return '⚠' if stale
+
+      reviewed ? '✓' : '–'
+    end
+
+    # "Reviewed by <person> on <date>", "Reviewed on <date>" (no person
+    # recorded, e.g. a password-prompt login), or "Never reviewed". Without
+    # the review columns (upgrade not run) the last update counts, as before.
+    def pf_review_text(assignment)
+      return pf_ui('assignment.reviewed', when: pf_relative(assignment.last_reviewed_at)) unless pf_review_known?(assignment)
+
+      reviewed_at = assignment.reviewed_at
+      return pf_ui('assignment.never_reviewed') if reviewed_at.nil?
+
+      reviewer = pf_reviewer(assignment)
+      return pf_ui('assignment.reviewed_on', date: pf_date(reviewed_at)) unless reviewer
+
+      pf_ui('assignment.reviewed_by', who: pf_person_name(reviewer), date: pf_date(reviewed_at))
+    end
+
+    def pf_review_known?(assignment)
+      assignment.class.respond_to?(:review_supported?) && assignment.class.review_supported?
+    end
+
+    # The person who last reviewed the assignment (memoized per page), or nil.
+    def pf_reviewer(assignment)
+      id = assignment.try(:reviewed_by_id)
+      return nil if id.blank?
+
+      @pf_reviewers ||= {}
+      return @pf_reviewers[id.to_s] if @pf_reviewers.key?(id.to_s)
+
+      @pf_reviewers[id.to_s] = PermissionForge.configuration.user_model.find_by(id: id)
+    end
+
+    # Who granted an assignment: the actor of its assignment.granted event
+    # when the audit log has one (an HTTP Basic login or an API client stamps
+    # no created_by), else created_by. `granters` is an Admin::LastChanges
+    # over the assignments of the page (events: %w[assignment.granted]).
+    def pf_granted_by(assignment, granters = nil)
+      event = granters && granters[assignment]
+      event ? pf_audit_actor_name(event) : pf_person_name(assignment.try(:created_by))
+    end
+
+    def pf_granters(assignments)
+      PermissionForge::Admin::LastChanges.new(assignments, events: %w[assignment.granted])
+    end
+
+    def pf_stale?(assignment)
+      assignment.expires_at.nil? &&
+        assignment.last_reviewed_at < PermissionForge.configuration.admin_stale_assignment_days.to_i.days.ago
+    end
+
+    # Calendar date (not time) for each expiry preset, for labels.
+    def pf_expiry_preset_date(key)
+      date = PermissionForge::Admin::ExpiryPresets.date_for(key)
+      date ? pf_date(date) : nil
+    end
+  end
+end