permission_forge 0.14.1 → 0.15.0

data/config/routes.rb

@@ -85,6 +85,7 @@ PermissionForge::Engine.routes.draw do
       resources :rules, controller: 'permission_set_rules', only: %i[new create edit update destroy] do
         collection do
           post :refresh
+          get :preview
         end
         member do
           patch :toggle
@@ -107,37 +108,51 @@ PermissionForge::Engine.routes.draw do
   # JSON Admin API — routes are always drawn; access is guarded at runtime
   # by BaseController checking api_enabled + api_auth configuration.
   namespace :api, defaults: { format: :json } do
-    resource :stats, only: [:show], controller: 'dashboard'
-
-    # The audit log is read-only over the API: no write route exists.
-    resources :audit_events, only: %i[index show], param: :identifier
+    # JSON only: `.json` or no extension. Any other extension
+    # (`/permission_sets.xml`) matches no endpoint and reaches the catch-all
+    # below: the JSON 404 envelope, never a JSON 200 under another format.
+    constraints(format: /json/) do
+      resource :stats, only: [:show], controller: 'dashboard'
+
+      # The audit log is read-only over the API: no write route exists.
+      resources :audit_events, only: %i[index show], param: :identifier
+
+      # No new/edit: a JSON API has no forms. Without them `…/new` reads as
+      # an identifier (404 unknown record) and `…/:identifier/edit` reaches
+      # the catch-all (404), both in the envelope; through 0.14.1 they raised
+      # AbstractController::ActionNotFound (Rails' own 404 page).
+      resources :permission_sets, param: :identifier, except: %i[new edit] do
+        member do
+          post :clone
+        end
 
-    resources :permission_sets, param: :identifier do
-      member do
-        post :clone
-      end
+        resources :resources, param: :identifier, except: %i[new edit] do
+          member do
+            post :generate_fields
+          end
+          resources :fields, param: :identifier, controller: 'resource_fields', except: %i[new edit]
+          resources :actions, param: :identifier, controller: 'resource_actions', except: %i[new edit]
+          resources :rules, param: :identifier, controller: 'permission_set_rules', except: %i[new edit]
+        end
 
-      resources :resources, param: :identifier do
-        member do
-          post :generate_fields
+        resources :users, param: :identifier, controller: 'permission_set_users', only: %i[index create destroy] do
+          collection do
+            post :bulk
+          end
         end
-        resources :fields, param: :identifier, controller: 'resource_fields'
-        resources :actions, param: :identifier, controller: 'resource_actions'
-        resources :rules, param: :identifier, controller: 'permission_set_rules'
       end
 
-      resources :users, param: :identifier, controller: 'permission_set_users', only: %i[index create destroy] do
-        collection do
-          post :bulk
+      resources :permission_set_groups, param: :identifier, except: %i[new edit] do
+        member do
+          post :clone
         end
+        resources :users, param: :identifier, controller: 'permission_set_group_users', only: %i[index create destroy]
       end
     end
 
-    resources :permission_set_groups, param: :identifier do
-      member do
-        post :clone
-      end
-      resources :users, param: :identifier, controller: 'permission_set_group_users', only: %i[index create destroy]
-    end
+    # Last: any other path or method under /api answers the JSON 404
+    # envelope, not Rails' HTML page (Api::UnmatchedRoutesController) —
+    # OPTIONS and TRACE included (through 0.15.0-rc a RoutingError).
+    match '(*path)', to: 'unmatched_routes#show', via: %i[get post put patch delete options trace], format: false
   end
 end

data/lib/generators/permission_forge/install/install_generator.rb

@@ -23,6 +23,16 @@ module PermissionForge
 
       KEY_TYPES = %w[bigint integer uuid string].freeze
       DETECTED_KEY_TYPES = { integer: 'bigint', uuid: 'uuid', string: 'string' }.freeze
+      # Printed after an install (#print_next_steps).
+      NEXT_STEPS = [
+        'bin/rails db:migrate',
+        'In your User model: include PermissionForge::Concerns::PermissionedUser (can_read?, permissions_hash)',
+        'Mount the admin in config/routes.rb: mount PermissionForge::Engine, at: "/permissions"',
+        "Admin credentials: uncomment Option A in config/initializers/permission_forge.rb\n     " \
+        '(PF_ADMIN_USER, PF_ADMIN_PASSWORD), or use your own admin controller (Option B)',
+        'bin/rails permission_forge:audit lists what is still open before production'
+      ].freeze
+      QUICK_START_URL = 'https://github.com/fetijashari/permission_forge#quick-start'.freeze
 
       def copy_initializer
         template 'initializer.rb.tt', 'config/initializers/permission_forge.rb'
@@ -34,6 +44,17 @@ module PermissionForge
         migration_template 'migration.rb.tt', 'db/migrate/create_permission_forge_tables.rb'
       end
 
+      # What the files alone do not do: without a mount and credentials there
+      # is no admin to open. Not printed by `rails destroy`.
+      def print_next_steps
+        return unless behavior == :invoke
+
+        steps = NEXT_STEPS.drop(options[:skip_migration] ? 1 : 0)
+        say "\nPermissionForge is installed. Next steps:"
+        steps.each.with_index(1) { |step, number| say "  #{number}. #{step}" }
+        say "  Quick Start: #{QUICK_START_URL}"
+      end
+
       private
 
       def table_prefix

data/lib/generators/permission_forge/install/templates/initializer.rb.tt

@@ -10,23 +10,23 @@ PermissionForge.configure do |config|
   # ---------------------------------------------------------------------------
   # A guarded controller action (ControllerActionGuard) with nobody signed in is refused.
   config.action_guard_nil_user_strategy = :deny
+  # So, by default, is any guarded action no Permission Set manages (opt out: config.unconfigured_action_strategy = :allow).
   # Conditional Permission Sets fail closed without a request context (see below).
   config.conditional_sets_strict_mode = true
-  # The cache is Rails.cache: use a shared store in production (Redis, Solid Cache, Memcached).
+  # Rails.cache, shared by every process: Redis or Solid Cache in production, :file_store (not :memory_store) in development.
   config.cache_backend = :rails_cache
 
-  # config.preset = :strict closes every fail-open default at once
-  # (docs/configuration.md#presets; a setting you make here still wins):
-  #   nil_user_strategy = :deny, auto_query_scoping = :filter_only,
-  #   response_filter_nil_user_strategy = :block, unconfigured_action_strategy = :block,
-  #   mask_virtual_attributes = :auto, extra_fields_default_access = :unconfigured,
-  #   and the three settings above.
+  # config.preset = :strict closes the fail-open defaults a setting can close (masking with
+  # nobody signed in too: :hide_in_requests, set in its own section below):
+  #   nil_user_strategy = :deny, auto_query_scoping = :filter_only, no_read_access_strategy = :deny,
+  #   response_filter_nil_user_strategy = :block, mask_virtual_attributes = :auto,
+  #   extra_fields_default_access = :unconfigured, and the three settings above. A setting you make here still wins (docs/configuration.md#presets).
   # What it costs: with nil_user_strategy :deny and auto_query_scoping :filter_only,
-  # code that runs with no current user (jobs, mailers, seeds, webhooks, the
-  # console, sign-in lookups on a user model that includes PermissionScopedFindable)
-  # sees no protected rows, and a belongs_to presence check on a protected parent
-  # fails ("must exist"). Run such code with a user, or inside
-  # PermissionForge.without_permission_scope { }, where nobody signed in gets no rules:
+  # code that runs with no current user (jobs, mailers, seeds, webhooks, the console,
+  # sign-in lookups on a user model that includes PermissionScopedFindable) sees no
+  # protected rows (a seed's find_or_create_by! adds a duplicate on every run), and a
+  # belongs_to presence check on a protected parent fails ("must exist"). Run such code
+  # with a user, or inside PermissionForge.without_permission_scope { }, where nobody signed in gets no rules:
   # never around code an anonymous request reaches. Never include PermissionScopedFindable in the user model.
   # config.preset = :strict
 
@@ -48,10 +48,9 @@ PermissionForge.configure do |config|
   # reports the assignments still held by users it calls inactive.
   config.user_active_check = ->(user) { user.respond_to?(:active_for_authentication?) ? user.active_for_authentication? : true }
 
-  # The profile cached with each user's permissions (uuid: nil when users have none).
-  config.profile_builder = ->(user) {
-    { id: user.id, uuid: user.try(:uuid), name: user.try(:name), email: user.try(:email) }
-  }
+  # The profile cached with each user's permissions. The default is like this example but leaves an encrypted
+  # attribute out (nil); this lambda calls the public readers, which decrypt (and may be masked):
+  # config.profile_builder = ->(user) { { id: user.id, uuid: user.try(:uuid), name: user.try(:name), email: user.try(:email).presence || user.try(:email_address) } }
 
   # Prefix of the PermissionForge tables ('' for none).
   config.table_name_prefix = '<%= table_prefix %>'
@@ -85,14 +84,15 @@ PermissionForge.configure do |config|
   # keep it cheap, never read permissions inside it, return {} with no request.
 
   # ---------------------------------------------------------------------------
-  # Masked attributes with nobody signed in (not part of the preset)
+  # Masked attributes with nobody signed in
   # ---------------------------------------------------------------------------
-  # :bypass (default) returns the stored values; :hide hides every guarded
-  # attribute. Trade-off: jobs, mailers and console code that read masked
-  # models with no user then see hidden values: set the current user there.
-  # The user model (user_class and its subclasses) stays readable for sign-in,
-  # and validations always read the stored values.
-  # config.masked_attributes_nil_user_strategy = :hide
+  # Hidden in a web request with nobody signed in (a public page, a forgotten
+  # sign-in, a before_action before it, a mail sent with deliver_now); jobs, rake
+  # and the console keep stored values. :hide hides in jobs too; :bypass nowhere.
+  # Webhooks that normalize records: sign a system user in (a value derived from
+  # a hidden read can still be saved into another column).
+  # The user model stays readable for sign-in; validations read stored values.
+  config.masked_attributes_nil_user_strategy = :hide_in_requests
 
   # ---------------------------------------------------------------------------
   # Admin screens
@@ -108,15 +108,15 @@ PermissionForge.configure do |config|
   # config.http_basic_auth_enabled = false
   # config.base_controller_class   = '::Admin::BaseController'  # must authenticate admins
   #
-  # Who may grant, revoke, extend or review an assignment, or change a group's
-  # members (admin screens and API). Example: no self-assignment.
+  # Who may grant, revoke, extend or review an assignment, or change a group's members
+  # (admin screens and API). Example: no self-assignment. PermissionForge.current_user is
+  # current_user_resolver's user; under Option A your app's sign-in does not run (nil).
   # config.admin_assignment_authorization = ->(controller, target, user_ids, action) {
-  #   admin = controller.current_user
+  #   admin = PermissionForge.current_user
   #   admin&.admin? && !user_ids.include?(admin.id)
   # }
-  #
   # Who may read the audit log pages, exports and API (nil: anyone with admin access).
-  # config.audit_log_authorization = ->(controller) { controller.current_user&.auditor? }
+  # config.audit_log_authorization = ->(controller) { PermissionForge.current_user&.auditor? }
 
   # ---------------------------------------------------------------------------
   # Audit log (docs/audit-log.md)
@@ -124,7 +124,8 @@ PermissionForge.configure do |config|
   # Every permission change is recorded in the audit_events table, inside the
   # change's own transaction. Each option with its default (an example where that is nil):
   # config.audit_events = :auto                    # true: always; false: never (events are still published)
-  # config.audit_actor_resolver = ->(controller) { controller.current_user }  # nil: current_user_resolver
+  # config.audit_actor_resolver = ->(controller) { Session.find_by(id: controller.request.cookie_jar.signed[:session_id])&.user }
+  #   nil: current_user_resolver, then the Basic auth login; the example names a Rails 8 sign-in under Option A
   # config.audit_request_context = ->(controller) { { request_id: controller.request.request_id, ip: controller.request.remote_ip } }
   # config.audit_change_failure_strategy = :raise  # the change rolls back; or :report, :log
   # config.audit_hook_failure_strategy = :report   # or :log, :raise
@@ -138,11 +139,11 @@ PermissionForge.configure do |config|
   # ---------------------------------------------------------------------------
   # config.api_enabled = true
   # config.api_base_controller_class = '::Api::BaseController'  # your auth chain
-  # config.api_auth = ->(controller) { controller.current_user&.admin? }
-  # config.api_action_authorization = ->(controller, action, record) { controller.current_user&.admin? }
-  # config.api_assignment_authorization = ->(controller, permission_set, user_ids) { controller.current_user&.admin? }
+  # config.api_auth = ->(controller) { PermissionForge.current_user&.admin? }
+  # config.api_action_authorization = ->(controller, action, record) { PermissionForge.current_user&.admin? }
+  # config.api_assignment_authorization = ->(controller, permission_set, user_ids) { PermissionForge.current_user&.admin? }
   #
-  # api_auth proves identity only: until both authorization lambdas are set,
-  # every API change and assignment is refused (403).
+  # config.api_stats_authorization = ->(controller) { PermissionForge.current_user&.admin? }  # GET /api/stats
+  # api_auth proves identity only: until each lambda above is set, what it guards is refused (403).
   # config.api_require_authorization = true  # default
 end

data/lib/generators/permission_forge/install/templates/migration.rb.tt

@@ -2,7 +2,7 @@ class CreatePermissionForgeTables < ActiveRecord::Migration<%= migration_version
   def change
     create_table :<%= table_prefix %>permission_set_groups do |t|
       t.string  :uuid, null: false
-      t.string  :name, null: false, default: 'Untitled Permission Set Group'
+      t.string  :name, null: false
       t.string  :description
       t.boolean :is_active, null: false, default: true
       t.boolean :is_editable, null: false, default: true
@@ -18,7 +18,7 @@ class CreatePermissionForgeTables < ActiveRecord::Migration<%= migration_version
     create_table :<%= table_prefix %>permission_sets do |t|
       t.string     :uuid, null: false
       t.references :permission_set_group, foreign_key: { to_table: :<%= table_prefix %>permission_set_groups }, null: true
-      t.string     :name, null: false, default: 'Untitled Permission Set'
+      t.string     :name, null: false
       t.string     :description
       t.boolean    :is_active, null: false, default: true
       t.boolean    :is_editable, null: false, default: true
@@ -106,14 +106,14 @@ class CreatePermissionForgeTables < ActiveRecord::Migration<%= migration_version
       t.string     :uuid, null: false
       t.references :permission_set, foreign_key: { to_table: :<%= table_prefix %>permission_sets }, null: false
       t.references :resource, foreign_key: { to_table: :<%= table_prefix %>resources }, null: false
-      t.string     :name, null: false, default: 'Untitled Rule'
-      t.string     :failure_message, default: 'You do not have permission to perform this action.'
+      t.string     :name, null: false
+      t.string     :failure_message
       t.string     :join_type
       t.string     :field_name, null: false
       t.string     :field_value, null: false
       t.string     :field_accessor_path
       t.string     :operator, null: false, default: 'equal'
-      t.boolean    :include_nulls, null: false, default: true
+      t.boolean    :include_nulls, null: false, default: false
       t.boolean    :is_active, null: false, default: true
       t.boolean    :is_editable, null: false, default: true
 <% if tenant_column %>      t.<%= tenant_id_type %>     :<%= tenant_column %>

data/lib/permission_forge/activation_conditions.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+module PermissionForge
+  # The activation conditions of a Permission Set as its row holds them: the
+  # one reading of `allowed_ips` (a list of IP addresses or CIDR ranges
+  # written with commas, newlines or spaces between them) and of the hour
+  # window (`allowed_hours_start`, `allowed_hours_end`). Included in
+  # PermissionSet (the row) and in ConditionalSets::Member (what the cache
+  # keeps of a conditional set); anything else that answers the three
+  # readers is read through {.of}.
+  #
+  # Who reads it: Services::PermissionSetConditionEvaluator (every
+  # per-request selection), the PermissionSet validations (a new row, or a
+  # changed condition, is refused when it cannot be judged — the stored text
+  # is normalised to commas), Admin::ConditionsForm, SentencesHelper, the
+  # API serializer and the `conditions` security-audit check.
+  #
+  # A condition nobody can judge — an entry that is not an address, a list
+  # of separators alone, one hour of the two, the same hour twice, an hour
+  # outside 0..23 — is *broken* (#conditions_broken?): a granting set never
+  # passes on it, with or without a request context, and a muting set always
+  # applies (ConditionalSets::Member), in every mode. The condition can only be written past the model.
+  #
+  # @api private
+  module ActivationConditions
+    # What separates two entries of an IP list.
+    SEPARATORS = /[,\s]+/
+    # The hours of a day.
+    HOURS = (0..23)
+
+    # The hour window of a set: none (#set? false), a window from `from`
+    # (inclusive) to `to` (exclusive) that may wrap midnight (#wraps?), or a
+    # broken one (#broken?: one hour missing, an hour outside HOURS, or
+    # `from == to`) that includes no hour.
+    #
+    # @api private
+    HoursWindow = Data.define(:from, :to) do
+      def set? = !(from.nil? && to.nil?)
+      def complete? = !from.nil? && !to.nil?
+      def in_range? = [from, to].compact.all? { |hour| HOURS.cover?(hour) }
+      def broken? = set? && !problem.nil?
+      def wraps? = complete? && from > to
+
+      # Why the window cannot be judged: :hours_incomplete, :hours_range,
+      # :hours_equal — nil for a window that can be (or none at all).
+      #
+      # @return [Symbol, nil]
+      def problem
+        return unless set?
+        return :hours_incomplete unless complete?
+        return :hours_range unless in_range?
+
+        :hours_equal if from == to
+      end
+
+      # @param hour [Integer] 0..23
+      # @return [Boolean] whether the window includes the hour; never for a
+      #   broken window or none at all
+      def include?(hour)
+        return false unless set? && !broken?
+
+        wraps? ? hour >= from || hour < to : hour >= from && hour < to
+      end
+    end
+
+    # The conditions of an object that answers the three readers (a host's
+    # own object, a Struct) without including the module.
+    #
+    # @api private
+    Reading = Data.define(:allowed_ips, :allowed_hours_start, :allowed_hours_end) { include ActivationConditions }
+
+    class << self
+      # @param object [#allowed_ips, #allowed_hours_start, #allowed_hours_end]
+      # @return [ActivationConditions]
+      def of(object)
+        return object if object.is_a?(ActivationConditions)
+
+        Reading.new(allowed_ips: object.allowed_ips, allowed_hours_start: object.allowed_hours_start,
+                    allowed_hours_end: object.allowed_hours_end)
+      end
+
+      # The entries of an IP list as written: a String with commas, newlines
+      # or spaces between the entries, or an Array of such Strings (the API
+      # takes both). Blanks are dropped; the entries are not checked.
+      #
+      # @param value [String, Array<String>, nil]
+      # @return [Array<String>]
+      def entries(value)
+        Array(value).flat_map { |part| part.to_s.split(SEPARATORS) }.reject(&:empty?)
+      end
+
+      # A condition text as a row stores it: nil for text of whitespace
+      # alone — any Unicode space, which Ruby reads as blank while SQL's TRIM
+      # takes spaces only — so #conditional? and the SQL scopes read it the
+      # same. A row stored before keeps its text; SQL reads it as a
+      # condition (narrower: the set is selected per request and passes).
+      #
+      # @param value [String, nil]
+      # @return [String, nil]
+      def condition_text(value)
+        value.is_a?(String) && value.match?(/\A[[:space:]]*\z/) ? nil : value
+      end
+
+      # The address of a request, as the IP list is compared with it: an
+      # IPv4-mapped IPv6 address (`::ffff:10.0.0.5`, what a dual-stack
+      # server reports for an IPv4 client) as the IPv4 address it holds.
+      #
+      # @param value [String, IPAddr, nil]
+      # @return [IPAddr, nil] nil for anything that is not an address
+      def request_address(value)
+        return if value.blank?
+
+        address = value.is_a?(IPAddr) ? value : IPAddr.new(value.to_s)
+        address.ipv4_mapped? ? address.native : address
+      rescue IPAddr::Error
+        nil
+      end
+
+      # @param entry [String]
+      # @return [IPAddr, nil] nil for an entry that is not an IP address or a CIDR range
+      def ip_range(entry)
+        IPAddr.new(entry)
+      rescue IPAddr::Error
+        nil
+      end
+    end
+
+    # @return [Array<String>] the entries of `allowed_ips` as written (.entries)
+    def allowed_ip_list
+      ActivationConditions.entries(allowed_ips)
+    end
+
+    # @return [Array<IPAddr>] the ranges of the entries that are addresses
+    def allowed_ip_ranges
+      allowed_ip_list.filter_map { |entry| ActivationConditions.ip_range(entry) }
+    end
+
+    # @return [Array<String>] the entries of `allowed_ips` that are no address
+    def invalid_ip_entries
+      allowed_ip_list.reject { |entry| ActivationConditions.ip_range(entry) }
+    end
+
+    # Whether the IP list cannot be judged: text that holds no entry, or an
+    # entry that is not an address. A blank list is no condition.
+    #
+    # @return [Boolean]
+    def ip_list_broken?
+      return false if allowed_ips.blank?
+
+      allowed_ip_list.empty? || invalid_ip_entries.any?
+    end
+
+    # @return [HoursWindow]
+    def hours_window
+      HoursWindow.new(from: allowed_hours_start, to: allowed_hours_end)
+    end
+
+    # Whether a condition of the row cannot be judged (see the module).
+    #
+    # @return [Boolean]
+    def conditions_broken?
+      ip_list_broken? || hours_window.broken? || session_flag_broken?
+    end
+
+    # A session flag no request can carry: its name holds a control
+    # character (a NUL byte, a newline, a tab). The validation refuses one.
+    #
+    # @return [Boolean]
+    def session_flag_broken?
+      requires_session_flag.to_s.match?(/[[:cntrl:]]/)
+    end
+
+    # A granting set whose condition nobody can judge: it never applies, with
+    # a request context or without one (ConditionalSets, Admin::EffectiveAccess).
+    # For an includer that answers `muting?` (PermissionSet, ConditionalSets::Member).
+    #
+    # @return [Boolean]
+    def never_grants?
+      !muting? && conditions_broken?
+    end
+
+    # What the validations refuse about the row's conditions, for a stored
+    # row too: `[:ip_entry, entry]` per entry that is no address, `[:ip_empty,
+    # text]` for a list of separators, `[:flag_unusable, flag]` for a session
+    # flag no request can carry, and the window's problem with the window
+    # (:hours_incomplete, :hours_range, :hours_equal).
+    #
+    # @return [Array<Array(Symbol, Object)>]
+    def condition_problems
+      problems = invalid_ip_entries.map { |entry| [:ip_entry, entry] }
+      problems << [:flag_unusable, requires_session_flag] if session_flag_broken?
+      problems << [:ip_empty, allowed_ips] if allowed_ips.present? && allowed_ip_list.empty?
+      window = hours_window
+      problems << [window.problem, window] if window.problem
+      problems
+    end
+  end
+end

data/lib/permission_forge/admin/action_label.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # The one definition of the label the admin shows for an action: the
+    # label an admin wrote on the ResourceAction row — one the gem generated
+    # (PermissionForge::GeneratedText.label?: blank, the key, the key
+    # humanized) is none — else, on an English page, Rails' English for the
+    # key ("Export csv", what an English host saw before 0.15:
+    # FieldLabel.english), else the key verbatim ("export_csv"; `verbatim?`:
+    # the view draws it in <code>). An action with a row and one without
+    # read the same.
+    #
+    # @example
+    #   ActionLabel.for(action).text           # => "Export to CSV" (the admin's label); "export_csv" on sq, "Export csv" on en
+    #   ActionLabel.for(nil, 'sync').verbatim?  # => true on a page that is not English
+    #
+    # @api private
+    module ActionLabel
+      # @param action [ResourceAction, #label, nil] the row, when there is one
+      # @param key [String, Symbol] the action key (the row's name by default)
+      # @return [FieldLabel::Label]
+      def self.for(action, key = action&.name)
+        key = key.to_s
+        label = FieldLabel.written_label(action, key)
+        return FieldLabel::Label.new(text: label, verbatim: false) if label
+
+        english = FieldLabel.english(key)
+        english ? FieldLabel::Label.new(text: english, verbatim: false) : FieldLabel::Label.new(text: key, verbatim: true)
+      end
+    end
+  end
+end

data/lib/permission_forge/admin/action_rows.rb

@@ -24,6 +24,8 @@ module PermissionForge
         delegate :effect, :permitted_by, to: :standing
 
         def configured? = !action.nil?
+        # The label is the key itself (ActionLabel): drawn once, in <code>.
+        def verbatim? = label == name
       end
 
       # What one action means right now for people with this set, and which
@@ -147,7 +149,7 @@ module PermissionForge
 
       def build_row(key, action)
         endpoints = endpoints_by_key.fetch(key, [])
-        Row.new(name: key, label: action&.display_name || key.humanize, action: action, endpoints: endpoints,
+        Row.new(name: key, label: ActionLabel.for(action, key).text, action: action, endpoints: endpoints,
                 unlinked: discovery? && endpoints.empty?,
                 standing: Standing.new(key, action, across: @across, configuration: @configuration))
       end

data/lib/permission_forge/admin/actor_label.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # How the admin names who made a change — the one definition the record
+    # footers, the event page, the audit tabs and their CSV, "Assigned by" and
+    # the event sentences use: a label the gem stored as a code
+    # (Audit::ActorCodes: an API client nobody named, the boot) in the
+    # page's language, else the event's actor label (with its kind where
+    # it is not a person: "admin (password prompt)"), else "Person #<id>",
+    # else the actor kind's word (StateLabel kind :actor: "System",
+    # "Unknown"). A record with no event and no created_by / updated_by is
+    # "System" (#system).
+    #
+    # @api private
+    module ActorLabel
+      module_function
+
+      # @param event [PermissionForge::AuditEvent]
+      # @return [String]
+      def for(event)
+        type = event.actor_type.to_s
+        label = event.actor_label.presence
+        code = PermissionForge::Audit::ActorCodes.code(type, label)
+        return I18n.t("permission_forge.audit_log.actor_codes.#{code}") if code
+        return I18n.t("permission_forge.audit_log.actor_named.#{type}", name: label, default: label) if label
+        return I18n.t('permission_forge.audit_log.person_id', id: event.actor_id) if type == 'user' && event.actor_id.present?
+
+        type_label(type)
+      end
+
+      # The word of an actor kind; a kind outside the catalogue as stored.
+      #
+      # @param type [String, Symbol]
+      # @return [String]
+      def type_label(type) = StateLabel.word(:actor, type, default: type.to_s)
+
+      # Whether the event names nobody: its actor kind is unknown and it has no label.
+      #
+      # @param event [PermissionForge::AuditEvent, nil]
+      # @return [Boolean]
+      def unknown?(event)
+        !event.nil? && event.actor_type.to_s == 'unknown' && event.actor_label.blank?
+      end
+
+      # Who a record with no event and no person stamped on it was changed by.
+      #
+      # @return [String]
+      def system = StateLabel.word(:actor, :system)
+    end
+  end
+end