permission_forge 0.14.1 → 0.15.0

data/lib/permission_forge.rb

@@ -258,6 +258,9 @@ module PermissionForge
 end
 
 require_relative 'permission_forge/execution_state'
+require_relative 'permission_forge/execution_state/restore'
+require_relative 'permission_forge/web_request'
+require_relative 'permission_forge/inspection_filters'
 require_relative 'permission_forge/model_bindings'
 require_relative 'permission_forge/cache/base'
 require_relative 'permission_forge/cache/memory_cache'
@@ -288,6 +291,7 @@ require_relative 'permission_forge/audit/subscribers'
 require_relative 'permission_forge/audit/log_access'
 require_relative 'permission_forge/audit/event_query'
 require_relative 'permission_forge/audit/runtime_emission'
+require_relative 'permission_forge/database_reach'
 require_relative 'permission_forge/audit'
 require_relative 'permission_forge/audit/gate'
 require_relative 'permission_forge/audit/runtime'
@@ -295,32 +299,53 @@ require_relative 'permission_forge/audit/field_access'
 require_relative 'permission_forge/audit/subscribers/base'
 require_relative 'permission_forge/audit/subscribers/legacy_hooks'
 require_relative 'permission_forge/audit/subscribers/log'
+require_relative 'permission_forge/audit/actor_codes'
+require_relative 'permission_forge/audit/reason_codes'
 require_relative 'permission_forge/audit/actor_resolver'
 require_relative 'permission_forge/audit/audited_views'
 require_relative 'permission_forge/audit/request_context'
+require_relative 'permission_forge/audit/unmasked_without_user'
 require_relative 'permission_forge/audit/detached'
 require_relative 'permission_forge/audit/refusals'
 require_relative 'permission_forge/audit/job_context'
 require_relative 'permission_forge/audit/settings_observer'
 require_relative 'permission_forge/audit/boot_warnings'
 
+require_relative 'permission_forge/schema_read'
+require_relative 'permission_forge/schema_read/ordered_types'
 require_relative 'permission_forge/resource_chain'
+require_relative 'permission_forge/record_read_access'
+require_relative 'permission_forge/unique_conflict'
 require_relative 'permission_forge/virtual_fields'
+require_relative 'permission_forge/managed_fields'
 require_relative 'permission_forge/virtual_fields/discovery'
+require_relative 'permission_forge/field_variants'
+require_relative 'permission_forge/field_names'
+require_relative 'permission_forge/timestamp_fields'
+require_relative 'permission_forge/field_level'
+require_relative 'permission_forge/sensitive_columns'
+require_relative 'permission_forge/secret_columns'
+require_relative 'permission_forge/encrypted_attributes'
+require_relative 'permission_forge/generated_text'
 
 require_relative 'permission_forge/concerns/has_active_scope'
 require_relative 'permission_forge/concerns/has_tenant_scoping'
 require_relative 'permission_forge/concerns/has_uuid'
+require_relative 'permission_forge/concerns/keeps_copied_values'
 require_relative 'permission_forge/concerns/has_audit_trail'
 require_relative 'permission_forge/invalidation_batch'
 require_relative 'permission_forge/concerns/invalidates_in_batch'
 require_relative 'permission_forge/concerns/has_permission_set_users'
 require_relative 'permission_forge/concerns/validates_dependency'
 require_relative 'permission_forge/concerns/validates_column_lengths'
+require_relative 'permission_forge/concerns/requires_name'
+require_relative 'permission_forge/concerns/normalizes_label'
+require_relative 'permission_forge/concerns/validates_required_columns'
 require_relative 'permission_forge/concerns/permissions_regenerator'
 require_relative 'permission_forge/concerns/invalidates_managed_actions'
 require_relative 'permission_forge/concerns/records_audit_events'
 require_relative 'permission_forge/concerns/audited_collection'
+require_relative 'permission_forge/activation_conditions'
 require_relative 'permission_forge/conditional_sets'
 require_relative 'permission_forge/concerns/permissions_memo'
 require_relative 'permission_forge/concerns/permissions_per_context'
@@ -335,7 +360,12 @@ require_relative 'permission_forge/concerns/masked_attributes'
 require_relative 'permission_forge/operators/constants'
 require_relative 'permission_forge/operators/validations'
 require_relative 'permission_forge/operators/value_casters'
+require_relative 'permission_forge/operators/rule_path'
+require_relative 'permission_forge/operators/rule_sources'
+require_relative 'permission_forge/model_lookup'
 require_relative 'permission_forge/operators/rule_column'
+require_relative 'permission_forge/operators/encrypted_alias'
+require_relative 'permission_forge/operators/rule_problem'
 require_relative 'permission_forge/operators/value_typing'
 require_relative 'permission_forge/services/mask_value'
 
@@ -361,9 +391,11 @@ require_relative 'permission_forge/api/serializers/permission_set_user_serialize
 require_relative 'permission_forge/api/serializers/audit_event_serializer'
 require_relative 'permission_forge/api/serializers/permission_set_group_serializer'
 require_relative 'permission_forge/api/serializers/permission_set_group_user_serializer'
+require_relative 'permission_forge/api/schema'
 
 require_relative 'permission_forge/services/concerns/clonable'
 require_relative 'permission_forge/services/concerns/audited_operation'
+require_relative 'permission_forge/services/concerns/settles_cache'
 require_relative 'permission_forge/services/concerns/across_tenants'
 require_relative 'permission_forge/services/bulk_permission_set_assignment'
 require_relative 'permission_forge/services/consent_withdrawal_handler'
@@ -383,14 +415,17 @@ require_relative 'permission_forge/services/gdpr_field_auditor'
 require_relative 'permission_forge/services/permission_hash_builder'
 require_relative 'permission_forge/services/permits_attributes'
 require_relative 'permission_forge/services/permits_attributes/nested_records'
+require_relative 'permission_forge/services/permits_attributes/result'
 require_relative 'permission_forge/services/data_subject_erasure'
 require_relative 'permission_forge/services/host_key_guard'
 require_relative 'permission_forge/services/stale_assignment_auditor'
 require_relative 'permission_forge/services/audit_event_purger'
 require_relative 'permission_forge/rake_audit'
+require_relative 'permission_forge/rake_dry_run'
 require_relative 'permission_forge/services/resource_field_generator'
 require_relative 'permission_forge/services/unscoped_query_detector'
 require_relative 'permission_forge/services/rls_operator_sql'
+require_relative 'permission_forge/services/rls_read_access_sql'
 require_relative 'permission_forge/services/rls_policy_generator'
 require_relative 'permission_forge/rls'
 
@@ -399,12 +434,17 @@ require_relative 'permission_forge/admin/field_level'
 require_relative 'permission_forge/admin/sensitive_columns'
 require_relative 'permission_forge/admin/model_catalog'
 require_relative 'permission_forge/admin/person_label'
+require_relative 'permission_forge/admin/state_label'
+require_relative 'permission_forge/admin/actor_label'
 require_relative 'permission_forge/admin/people_candidates'
 require_relative 'permission_forge/admin/people_directory'
+require_relative 'permission_forge/admin/list_sentence'
 require_relative 'permission_forge/admin/record_id'
 require_relative 'permission_forge/admin/editable_lock'
 require_relative 'permission_forge/admin/expiry_presets'
 require_relative 'permission_forge/admin/effective_access'
+require_relative 'permission_forge/admin/field_provenance'
+require_relative 'permission_forge/admin/field_chain'
 require_relative 'permission_forge/admin/effective_fields'
 require_relative 'permission_forge/admin/settings_values'
 require_relative 'permission_forge/admin/settings_catalog'
@@ -432,7 +472,15 @@ require_relative 'permission_forge/admin/change_set_parts/new_fields'
 require_relative 'permission_forge/admin/change_set_parts/actions'
 require_relative 'permission_forge/admin/change_set_parts/new_actions'
 require_relative 'permission_forge/admin/change_set'
+require_relative 'permission_forge/admin/field_label'
+require_relative 'permission_forge/admin/model_label'
+require_relative 'permission_forge/admin/action_label'
+require_relative 'permission_forge/admin/error_sentence'
+require_relative 'permission_forge/admin/prefill'
+require_relative 'permission_forge/admin/record_name'
+require_relative 'permission_forge/admin/chain_entries'
 require_relative 'permission_forge/admin/field_rows'
+require_relative 'permission_forge/admin/mask_strategy_choices'
 require_relative 'permission_forge/admin/field_detail'
 require_relative 'permission_forge/admin/audit_event_detail'
 require_relative 'permission_forge/admin/rule_builder'
@@ -445,17 +493,23 @@ require_relative 'permission_forge/admin/conditions_form'
 require_relative 'permission_forge/admin/permission_set_factory'
 require_relative 'permission_forge/admin/rule_form_input'
 require_relative 'permission_forge/admin/rule_form'
+require_relative 'permission_forge/admin/rule_notes'
+require_relative 'permission_forge/admin/rule_preview'
 require_relative 'permission_forge/admin/bulk_people_matcher'
 
 # Security review (rake permission_forge:audit)
+require_relative 'permission_forge/api_authorizations'
 require_relative 'permission_forge/services/security_audit'
 require_relative 'permission_forge/services/security_audit/base_check'
+require_relative 'permission_forge/services/security_audit/masking_without_user'
 require_relative 'permission_forge/services/security_audit/config_check'
 require_relative 'permission_forge/services/security_audit/privilege_check'
 require_relative 'permission_forge/services/security_audit/assignment_check'
 require_relative 'permission_forge/services/security_audit/rule_check'
 require_relative 'permission_forge/services/security_audit/integrity_check'
+require_relative 'permission_forge/services/security_audit/conditions_check'
 require_relative 'permission_forge/services/security_audit/personal_data_check'
+require_relative 'permission_forge/services/security_audit/unmanaged_actions'
 require_relative 'permission_forge/services/security_audit/action_check'
 require_relative 'permission_forge/services/security_audit/audit_trail_check'
 require_relative 'permission_forge/services/security_audit/user_model_check'

data/lib/tasks/permission_forge.rake

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 namespace :permission_forge do
-  desc 'Report fields that match the personal-data patterns but are not masked, and matching model columns with no ResourceField'
+  desc 'Report personal-data fields that are not masked, and matching model columns with no field row. ' \
+       'ACTOR= names who ran it, REASON= why (recorded as report.generated).'
   task audit_masks: :environment do
     report = PermissionForge::RakeAudit.reporting('permission_forge:audit_masks', counts: ->(r) { { findings: r.size } }) do
       PermissionForge::Services::GdprFieldAuditor.call
@@ -13,19 +14,38 @@ namespace :permission_forge do
 end
 
 namespace :permission_forge do
-  desc 'Read-only security review of the PermissionForge setup. FORMAT=json, FAIL_ON=critical|high|medium|low'
+  # Exits 1 when FAIL_ON is given and a finding of that severity or worse
+  # exists (saying so on stderr, so FORMAT=json output stays parseable), and 2
+  # when FAIL_ON names no severity (before the review runs).
+  # It changes no permission data; every run is recorded (report.generated)
+  # when the audit log is on.
+  desc 'Security review of the setup: changes no permission data, records the run in the audit log. ' \
+       'FORMAT=json, FAIL_ON=critical|high|medium|low|info; ACTOR= names who ran it, REASON= why.'
   task audit: :environment do
-    report = PermissionForge::RakeAudit.reporting('permission_forge:audit', counts: :counts.to_proc) do
-      PermissionForge::Services::SecurityAudit.call
+    audit = PermissionForge::Services::SecurityAudit
+    given = ENV.fetch('FAIL_ON', nil).presence
+    fail_on = given && audit.severity_named(given)
+    if given && fail_on.nil?
+      warn "FAIL_ON must be one of #{audit::SEVERITIES.join(', ')} (got #{given.inspect}). " \
+           'Usage: rake permission_forge:audit FAIL_ON=high'
+      exit 2
     end
 
+    # A rake task does not eager-load: the review must see every model (an
+    # STI subclass's `encrypts`, the models on a table a rule joins).
+    PermissionForge::Admin::ModelCatalog.eager_load_app_models
+    report = PermissionForge::RakeAudit.reporting('permission_forge:audit', counts: :counts.to_proc) { audit.call }
+
     if ENV['FORMAT'] == 'json'
       puts JSON.pretty_generate(report.to_h)
     else
       puts PermissionForge::Services::SecurityAuditChecks::TextReport.new(report)
     end
 
-    fail_on = ENV.fetch('FAIL_ON', nil).presence
-    exit 1 if fail_on && report.at_least(fail_on).any?
+    failing = fail_on ? report.at_least(fail_on).size : 0
+    if failing.positive?
+      warn "Failing: #{failing} finding(s) at or above #{fail_on} (FAIL_ON=#{given})."
+      exit 1
+    end
   end
 end

data/lib/tasks/permission_forge_audit_events.rake

@@ -2,10 +2,12 @@
 
 namespace :permission_forge do
   namespace :audit_events do
-    desc 'Delete audit events older than config.audit_retention_period (DRY_RUN=1 counts only). ACTOR= names who ran it.'
+    # Prints the result the audit.purged events record (RakeOutput).
+    desc 'Delete audit events older than config.audit_retention_period. Deletes when DRY_RUN is unset or ' \
+         'false (or 0, no); any other DRY_RUN value (1, true, yes) only counts. ACTOR= names who ran it, REASON= why.'
     task purge: :environment do
       task_name = 'permission_forge:audit_events:purge'
-      dry_run = %w[1 true].include?(ENV.fetch('DRY_RUN', nil))
+      dry_run = PermissionForge::RakeDryRun.dry_run?(ENV.fetch('DRY_RUN', nil), default: false)
       purge = -> { PermissionForge::Services::AuditEventPurger.call(dry_run: dry_run) }
       result = begin
         dry_run ? purge.call : PermissionForge::RakeAudit.changing(task_name, &purge)
@@ -19,9 +21,11 @@ namespace :permission_forge do
       if !result[:retention_configured]
         puts 'Retention is not configured (config.audit_retention_period is nil): nothing was deleted.'
       elsif dry_run
-        puts "Dry run — #{result[:purged]} audit event(s) older than #{result[:cutoff].iso8601} would be deleted."
+        PermissionForge::RakeOutput.report("Dry run — would delete #{result[:purged]} audit event(s) older than " \
+                                           "#{result[:cutoff].iso8601}:", result)
       else
-        puts "Deleted #{result[:purged]} audit event(s) older than #{result[:cutoff].iso8601}."
+        PermissionForge::RakeOutput.report("Deleted #{result[:purged]} audit event(s) older than #{result[:cutoff].iso8601}:",
+                                           result.except(:dry_run))
       end
     end
   end

data/lib/tasks/permission_forge_cache.rake

@@ -2,25 +2,25 @@
 
 namespace :permission_forge do
   namespace :cache do
-    desc 'Remove every cached permission hash of every user (by key pattern, or every user through the bulk ' \
-         'invalidation) — once the last process of the previous release is gone (0.14), or to revoke everything ' \
-         'cached at once; the cache is cold afterwards. ACTOR=, REASON='
+    # Upgrading from 0.13 or earlier: run it once the last process of the
+    # previous release is gone (it also removes the previous key namespace).
+    # What it prints is the result the cache.cleared event records
+    # (RakeOutput), the cache outcome included: on an in-memory store only
+    # this process's store is cleared, and the output says so.
+    desc "Remove every user's cached permissions at once; each user rebuilds on their next request. " \
+         'ACTOR=, REASON= (After an upgrade from 0.13: run it once the old processes are gone.)'
     task clear: :environment do
       task_name = 'permission_forge:cache:clear'
       result = PermissionForge::RakeAudit.changing(task_name) { PermissionForge::Services::PermissionCacheClearer.call }
       PermissionForge::RakeAudit.log(task_name, result.map { |key, value| "#{key}=#{value.inspect}" }.join(' '))
-      unconfirmed = result[:unconfirmed].positive? ? " (#{result[:unconfirmed]} not confirmed by the cache store)" : ''
+      # what it means for the users is the outcome's "Cache scope" line (a shared store: every user rebuilds on their
+      # next request; a per-process store: this process's only), never a second claim here
       done = if result[:strategy] == :pattern
-               'Removed every cached permission hash by key pattern (users not counted)'
+               'Removed every cached permission hash by key pattern:'
              else
-               "Invalidated the cached permissions of #{result[:users]} user visit(s) in #{result[:tenants]} tenant(s)"
+               'Invalidated the cached permissions of every user:'
              end
-      puts "#{done}#{unconfirmed}. The cache is cold: each user rebuilds on their next request."
-      if PermissionForge.cache.process_local?
-        puts 'Only the cache store of this rake process was cleared: an in-memory store (cache_backend :memory, or ' \
-             ':memory_store) lives in each process, so the web and job processes keep their entries until they ' \
-             'restart or the entries expire (cache_ttl). Invalidate the users from inside those processes, or restart them.'
-      end
+      PermissionForge::RakeOutput.report(done, result)
     end
   end
 end

data/lib/tasks/permission_forge_docs.rake

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# The gem's own documentation generators, run from the gem's Rakefile
+# (`bundle exec rake docs:configuration`, `docs:api`). They are defined only in a checkout
+# of the gem (where docs/ is) and never inside a Rails application — not in a
+# host's `rails -T` (the gem ships without docs/), not in the dummy app's.
+docs_root = File.expand_path('../../docs', __dir__)
+inside_rails = defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+if File.directory?(docs_root) && !inside_rails
+  namespace :docs do
+    desc 'Regenerate the Option reference of docs/configuration.md from SettingsCatalog and Configuration.new'
+    task :configuration do
+      lib = File.expand_path('../../lib', __dir__)
+      $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+      require 'permission_forge'
+      require 'permission_forge/docs/configuration_reference'
+
+      path = File.join(docs_root, 'configuration.md')
+      reference = PermissionForge::Docs::ConfigurationReference.new(document: File.read(path))
+      if reference.stale?
+        File.write(path, reference.render)
+        puts 'docs/configuration.md: Option reference regenerated'
+      else
+        puts 'docs/configuration.md: Option reference is up to date'
+      end
+    end
+
+    desc 'Regenerate the json sample blocks (sample=<name>) of docs/admin-api.md from Api::Schema and the serializers'
+    task :api do
+      lib = File.expand_path('../../lib', __dir__)
+      $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+      require 'permission_forge'
+      require 'permission_forge/docs/api_samples'
+      # The one parser of the docs' fenced blocks (a checkout has test/).
+      require File.expand_path('../../test/support/doc_blocks', __dir__)
+
+      path = File.join(docs_root, 'admin-api.md')
+      document = File.read(path)
+      samples = PermissionForge::Docs::ApiSamples.new(document: document, blocks: DocBlocks.parse(document, file: 'docs/admin-api.md'))
+      if samples.stale?
+        File.write(path, samples.render)
+        puts 'docs/admin-api.md: json samples regenerated'
+      else
+        puts 'docs/admin-api.md: json samples are up to date'
+      end
+    end
+  end
+end

data/lib/tasks/permission_forge_expiration.rake

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 namespace :permission_forge do
-  desc 'Remove expired permission set assignments and invalidate affected users\' cached permissions'
+  # Prints the result the cleanup.expired_assignments event records
+  # (RakeOutput): the people by name, the sets, the cache outcome.
+  desc "Remove expired permission set assignments and invalidate affected users' cached permissions. " \
+       'ACTOR= names who ran it, REASON= why.'
   task cleanup_expired_assignments: :environment do
     task_name = 'permission_forge:cleanup_expired_assignments'
     result = PermissionForge::RakeAudit.changing(task_name) { PermissionForge::Services::ExpiredAssignmentCleaner.call }
@@ -9,11 +12,12 @@ namespace :permission_forge do
     if result[:removed].zero?
       puts 'No expired assignments found.'
     else
-      puts "Removed #{result[:removed]} expired assignment(s), invalidated #{result[:invalidated]} user(s)."
+      PermissionForge::RakeOutput.report("Removed #{result[:removed]} expired assignment(s):", result)
     end
   end
 
-  desc 'Show expired permission set assignments without removing (dry run)'
+  desc 'List expired permission set assignments without removing them, as a dry run. ' \
+       'ACTOR= names who ran it, REASON= why (recorded as report.generated).'
   task expired_assignments: :environment do
     result = PermissionForge::RakeAudit.reporting(
       'permission_forge:expired_assignments',
@@ -22,8 +26,10 @@ namespace :permission_forge do
     if result[:expired_count].zero?
       puts 'No expired assignments found.'
     else
-      puts "Found #{result[:expired_count]} expired assignment(s) affecting #{result[:affected_user_ids].size} user(s)."
-      puts "User IDs: #{result[:affected_user_ids].join(', ')}"
+      PermissionForge::RakeOutput.report(
+        "Dry run — would remove #{result[:expired_count]} expired assignment(s) affecting #{result[:affected_user_ids].size} person(s):",
+        result.slice(:expired_count, :affected_user_ids, :cache).merge(dry_run: true)
+      )
       puts 'Run `rake permission_forge:cleanup_expired_assignments` to remove them.'
     end
   end

data/lib/tasks/permission_forge_gdpr.rake

@@ -1,20 +1,37 @@
 # frozen_string_literal: true
 
 namespace :permission_forge do
-  desc 'Find permanent permission assignments not reviewed within threshold (default: 90 days)'
+  # Exits 1 when it finds stale assignments, 2 when THRESHOLD_DAYS is not a
+  # number of days (rather than reading it as 0, which flags everything).
+  # People are named as the admin names them (RakeOutput.people).
+  desc 'Find permanent assignments not reviewed in THRESHOLD_DAYS, by default admin_stale_assignment_days. ' \
+       'Exits 1 when it finds any. ACTOR= names who ran it, REASON= why (recorded as report.generated).'
   task stale_assignments: :environment do
-    threshold = ENV.fetch('THRESHOLD_DAYS', 90).to_i
+    task_name = 'permission_forge:stale_assignments'
+    threshold = ENV.fetch('THRESHOLD_DAYS', nil)&.then do |given|
+      digits = given.strip
+      # ASCII digits only: Integer() would also take Ruby's underscores ("1_0").
+      days = Integer(digits, 10) if digits.match?(/\A[0-9]+\z/)
+      next days if days&.between?(1, 36_500)
+
+      message = "THRESHOLD_DAYS must be a whole number of days from 1 to 36500 (got #{given.inspect}). " \
+                "Usage: rake #{task_name} THRESHOLD_DAYS=90"
+      PermissionForge::RakeAudit.log(task_name, "refused: #{message}")
+      warn message
+      exit 2
+    end
     result = PermissionForge::RakeAudit.reporting(
-      'permission_forge:stale_assignments',
-      counts: ->(r) { { stale: r[:stale_count], users: r[:affected_user_ids].size, threshold_days: threshold } }
+      task_name,
+      counts: ->(r) { { stale: r[:stale_count], users: r[:affected_user_ids].size, threshold_days: r[:threshold_days] } }
     ) { PermissionForge::Services::StaleAssignmentAuditor.call(threshold_days: threshold) }
 
     if result[:stale_count].zero?
-      puts "No stale assignments found (threshold: #{threshold} days)."
+      puts "No stale assignments found (threshold: #{result[:threshold_days]} days)."
     else
-      puts "Found #{result[:stale_count]} stale assignment(s) affecting #{result[:affected_user_ids].size} user(s):"
+      puts "Found #{result[:stale_count]} stale assignment(s) affecting #{result[:affected_user_ids].size} person(s):"
+      names = PermissionForge::RakeOutput.people(result[:assignments].map { |a| a[:user_id] })
       result[:assignments].each do |a|
-        puts "  User #{a[:user_id]} — #{a[:permission_set] || '(set not found)'} (#{a[:days_stale]} days since last review or grant)"
+        puts "  #{names.fetch(a[:user_id].to_s)} — #{a[:permission_set] || '(set not found)'} (#{a[:days_stale]} days since last review or grant)"
       end
       puts "\nConsider reviewing these assignments or setting expires_at for time-bound access."
       exit 1
@@ -28,12 +45,16 @@ namespace :permission_forge do
   # request id, reason and data of every audit event, the *_by_id columns on
   # rows the person created, edited or reviewed, and the person's own record
   # in the app. Assignments in other tenants stay when a tenant is current.
-  desc "Remove a user's assignments, group memberships and cached permissions, and clear their name labels " \
-       'in the audit log (supports GDPR Art. 17). Ids and other event data stay. USER_ID required; DRY_RUN=true ' \
-       'by default.'
+  # rake -T shows a description up to its first full stop after a word: the
+  # first sentence carries no abbreviation ("Article 17", not "Art. 17") and
+  # ends on a word, not a parenthesis. What it prints is the result the
+  # erasure.performed event records (RakeOutput), the cache outcome included.
+  desc "Erase a person's permission data (assignments, cache, audit-log names) for a GDPR Article 17 request. " \
+       'Ids and other event data stay. USER_ID= required; a dry run unless DRY_RUN=false (or 0, no); ' \
+       'ACTOR= names who ran it, REASON= why.'
   task erasure: :environment do
     user_id = ENV.fetch('USER_ID', nil)
-    dry_run = ENV.fetch('DRY_RUN', 'true') == 'true'
+    dry_run = PermissionForge::RakeDryRun.dry_run?(ENV.fetch('DRY_RUN', nil), default: true)
 
     abort 'USER_ID is required. Usage: rake permission_forge:erasure USER_ID=123' if user_id.blank?
 
@@ -51,18 +72,13 @@ namespace :permission_forge do
              end
     PermissionForge::RakeAudit.log(task_name, "user #{user_id}, dry_run=#{dry_run}: #{result.except(:permission_sets).to_json}")
 
+    person = PermissionForge::RakeOutput.person(user)
     if dry_run
-      puts "Dry run — would remove for user #{user_id}:"
-      puts "  Permission set assignments: #{result[:assignments_count]}"
-      puts "  Group assignments: #{result[:group_assignments_count]}"
-      puts "  Permission sets: #{result[:permission_sets].join(', ')}" if result[:permission_sets].any?
+      PermissionForge::RakeOutput.report("Dry run — would erase for #{person}:", result)
+      puts '  (plus the name labels on the events the erasure itself writes)'
       puts "\nRun with DRY_RUN=false to execute."
     else
-      puts "Erasure complete for user #{user_id}:"
-      puts "  Assignments removed: #{result[:assignments_removed]}"
-      puts "  Group assignments removed: #{result[:group_assignments_removed]}"
-      puts "  Cache cleared: #{result[:cache_cleared]}"
-      puts "  Assignments remaining in other tenants: #{result[:assignments_remaining_elsewhere]}"
+      PermissionForge::RakeOutput.report("Erasure complete for #{person}:", result)
       puts '  Kept: audit event ids, ip, request id, reason and data; *_by_id columns; the user record itself.'
     end
   end