permission_forge 0.14.1 → 0.15.0

data/app/controllers/concerns/permission_forge/change_review.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # For the "Review and save" step of a batched edit (Admin::ChangeSet): what
+  # to say when there is nothing to save, and once the edit is applied.
+  #
+  # @api private
+  module ChangeReview
+    extend ActiveSupport::Concern
+
+    private
+
+    # A plain notice, or — when the request turned on flags their
+    # dependencies keep off (ChangeSet#refused: Edit with Read off, ...) — an
+    # alert that says which and why, instead of a bare "No changes to save."
+    #
+    # @return [Hash] for redirect_to
+    def pf_nothing_to_save_flash(change_set)
+      refused = change_set.refused
+      return { notice: pf_no_changes_text } if refused.empty?
+
+      reasons = refused.map { |refusal| helpers.pf_refusal_description(refusal) }
+      { alert: t('permission_forge.flash.permission_sets.nothing_applied', reasons: reasons.join('; ')) }
+    end
+
+    # The flash of an applied batched edit: how many changes, for whom, and
+    # what the cache store confirmed (CacheConfirmation) — or, when it
+    # applied none, what the review step says (#pf_nothing_to_save_flash:
+    # "No changes to save.", or why each requested change was refused).
+    #
+    # @param change_set [PermissionForge::Admin::ChangeSet] after #apply!
+    # @param outcome [PermissionForge::Cache::Outcome]
+    # @return [Hash] for redirect_to
+    def pf_applied_flash(change_set, outcome)
+      changes = change_set.changes
+      return pf_nothing_to_save_flash(change_set) if changes.empty?
+
+      people = helpers.pf_people_text(pf_people_count(@permission_set))
+      cache_flash_text(outcome, t('permission_forge.flash.permission_sets.saved', count: changes.size, people: people))
+    end
+  end
+end

data/app/controllers/concerns/permission_forge/copy_refusal.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # What the admin says when a copy (Duplicate, "Start from") is refused:
+  # the row the validations refused and why, instead of a 500. A copy keeps
+  # its original's stored values (Concerns::KeepsCopiedValues), so this is
+  # left for a row no copy can hold (Modify All without View All, say); the
+  # copy is made whole or not at all (one transaction).
+  #
+  # @api private
+  module CopyRefusal
+    # The record kinds a copy is made of, by class.
+    KINDS = {
+      'PermissionForge::PermissionSet' => :permission_set, 'PermissionForge::PermissionSetGroup' => :permission_set_group,
+      'PermissionForge::Resource' => :resource, 'PermissionForge::ResourceField' => :resource_field,
+      'PermissionForge::ResourceAction' => :resource_action, 'PermissionForge::PermissionSetRule' => :permission_set_rule
+    }.freeze
+
+    private
+
+    # @param error [ActiveRecord::RecordInvalid]
+    # @param name [String] the name of what was being copied
+    # @return [String]
+    def pf_copy_refused_message(error, name)
+      record = error.record
+      t('permission_forge.flash.copy_refused.message', name: name, record: pf_copy_refused_record(record),
+                                                       errors: pf_copy_refused_errors(record.errors))
+    end
+
+    # "Resource “Customer”"
+    def pf_copy_refused_record(record)
+      t("permission_forge.flash.copy_refused.kinds.#{KINDS.fetch(record.class.name, :record)}", name: record.try(:name).to_s)
+    end
+
+    def pf_copy_refused_errors(errors)
+      PermissionForge::Admin::ListSentence.call(PermissionForge::Admin::ErrorSentence.all(errors))
+    end
+  end
+end

data/app/controllers/concerns/permission_forge/param_shapes.rb

@@ -18,6 +18,107 @@ module PermissionForge
       value.is_a?(String) ? value.delete("\0").strip : ''
     end
 
+    # A request value that cannot be read, naming the parameter: a 400 in
+    # the admin, a 422 in the API keyed by the parameter like a validation
+    # error (`{ "expires_at": ["is not an ISO 8601 date or time"] }`).
+    #
+    # @api private
+    class InvalidParam < ActionController::BadRequest
+      # @return [String] the parameter, e.g. "expires_at"
+      attr_reader :param
+      # @return [String] what is wrong with it, without its name
+      attr_reader :detail
+
+      def initialize(param, detail)
+        @param = param.to_s
+        @detail = detail
+        super("#{@param} #{detail}")
+      end
+
+      # The field-keyed messages of the API's 422 (`{ "expires_at" => [...] }`).
+      #
+      # @return [Hash{String => Array<String>}]
+      def messages = { param => [detail] }
+    end
+
+    # A flag that is not true or false (ParamShapes.boolean): the API
+    # answers it like any InvalidParam (422 keyed by it); the admin, whose
+    # forms post "0" and "1", goes back with a flash and changes nothing
+    # (ApplicationController).
+    #
+    # @api private
+    class InvalidFlag < InvalidParam
+      # @param param [String, Symbol] the flag, e.g. "is_active"
+      def initialize(param)
+        super(param, I18n.t('permission_forge.api.errors.boolean_invalid'))
+      end
+    end
+
+    # What a boolean parameter is read as: JSON's true and false, their
+    # strings, and 1 / 0 as a number or a string (see .boolean).
+    BOOLEANS = { true => true, 'true' => true, 1 => true, '1' => true,
+                 false => false, 'false' => false, 0 => false, '0' => false }.freeze
+
+    # The words a boolean is also sent as, in any case: what a form posts
+    # (`on` for a checkbox without a value; `off`) and the letters
+    # PostgreSQL and ActiveModel write (`t`, `f`).
+    BOOLEAN_WORDS = { 'true' => true, 't' => true, 'on' => true, '1' => true,
+                      'false' => false, 'f' => false, 'off' => false, '0' => false }.freeze
+
+    # The one reading of a boolean the admin and the API take: BOOLEANS,
+    # or a String that is one of BOOLEAN_WORDS in any case. Anything else
+    # ("yes", "nope", "", 2, 1.5, a list) is no boolean: a reader refuses
+    # it (InvalidParam), never takes it for true as ActiveModel's cast does.
+    #
+    # @return [Boolean, nil] nil when the value is no boolean
+    def self.boolean(value)
+      return BOOLEANS[value] if BOOLEANS.key?(value)
+
+      BOOLEAN_WORDS[value.downcase] if value.is_a?(String)
+    end
+
+    # A flag `key` as true or false (.boolean).
+    #
+    # @raise [InvalidFlag] for anything else
+    # @return [Boolean]
+    def self.flag(key, value)
+      read = boolean(value)
+      read.nil? ? raise(InvalidFlag, key) : read
+    end
+
+    # `attrs` with each of `keys` it has read as a flag (.flag), in place.
+    #
+    # @raise [InvalidFlag] keyed by the first flag that is no boolean
+    # @return [Hash, ActionController::Parameters] attrs
+    def self.flags(attrs, keys)
+      keys.map(&:to_s).select { |key| attrs.key?(key) }.each { |key| attrs[key] = flag(key, attrs[key]) }
+      attrs
+    end
+
+    # The time an ISO 8601 String names, in Time.zone: see IsoTime.
+    #
+    # @return [ActiveSupport::TimeWithZone, nil] nil for anything else
+    def self.time(value) = IsoTime.parse(value)
+
+    # What a whole-number parameter is read from: digits with an optional
+    # minus sign, as a String or a JSON number. "2abc", "1.5", "+7" and ""
+    # are not one.
+    WHOLE_NUMBER = /\A-?\d+\z/
+
+    # The whole number `value` holds when it is inside `range`, else
+    # `default`: see #pf_integer_param.
+    #
+    # @param range [Range] of Integers, endless for an upper bound the
+    #   caller clamps itself (`1..`)
+    # @return [Integer, Object] the number, or `default`
+    def self.integer(value, default:, range:)
+      text = value.to_s.strip if value.is_a?(String) || value.is_a?(Integer)
+      return default unless text&.match?(WHOLE_NUMBER)
+
+      number = Integer(text, 10)
+      range.cover?(number) ? number : default
+    end
+
     # `value` with NUL bytes removed from every String in it, however deep.
     #
     # @return [Object] a new Parameters / Array, or the value itself
@@ -64,24 +165,123 @@ module PermissionForge
       tab if tabs.include?(tab)
     end
 
+    # params[key] when it is a whole number (digits, or a JSON number)
+    # inside `range`, else `default`. For a page, a page size, a count: a
+    # value that cannot be read is the default (`per_page=abc` lists the
+    # default page size), never 0, 1 or a 500 — a typo in a paging
+    # parameter must not refuse the page. A parameter whose misreading must
+    # refuse the request is read by a strict reader (pf_boolean_param,
+    # pf_time_param: InvalidParam).
+    #
+    #   pf_integer_param(:per_page, default: 25, range: 1..)
+    #   pf_integer_param(:hour, default: nil, range: 0..23)
+    def pf_integer_param(key, default:, range:)
+      ParamShapes.integer(params[key], default: default, range: range)
+    end
+
     # The Integer ids in params[key] (one value or a list); anything that is
     # not digits is dropped.
     def pf_id_list(key)
       Array.wrap(params[key]).filter_map { |value| PermissionForge::Admin::RecordId.cast(value) }
     end
 
-    # The time params[key] names, nil when it is blank.
+    # params[key] as true or false (ParamShapes.boolean); false when it is
+    # absent or null.
+    #
+    # @raise [InvalidFlag] for anything else ("yes", "", 2, a list): a value
+    #   that cannot be read must never be taken for false
+    def pf_boolean_param(key)
+      value = params[key]
+      return false if value.nil?
+
+      ParamShapes.flag(key, value)
+    end
+
+    # `attrs` (an attribute hash of a form) with each of `keys` it has read
+    # as true or false (ParamShapes.flags): the admin's flags. ActiveModel
+    # would read "nope" as true.
     #
-    # @raise [ActionController::BadRequest] for a value that is no time:
-    #   a date that cannot be read must never become "no end date"
+    # @raise [InvalidFlag] keyed by the attribute for anything else (the
+    #   admin answers it with a flash: nothing is changed)
+    def pf_boolean_attributes(attrs, *keys)
+      ParamShapes.flags(attrs, keys)
+    end
+
+    # The time params[key] names (an ISO 8601 date or date-time, IsoTime),
+    # nil when it is blank.
+    #
+    # @raise [InvalidParam] for anything else ("tuesday", "2026-13-45"): a
+    #   date that cannot be read must never become "no end date", nor a time
+    #   somebody did not mean
     def pf_time_param(key)
       value = params[key]
       return nil if value.blank?
 
-      time = Time.zone.parse(value.to_s) if value.is_a?(String)
-      time || raise(ActionController::BadRequest, "#{key} is not a time")
-    rescue ArgumentError
-      raise ActionController::BadRequest, "#{key} is not a time"
+      ParamShapes.time(value) || raise(InvalidParam.new(key, I18n.t('permission_forge.api.errors.not_iso8601_time')))
+    end
+
+    # The ISO 8601 forms a time parameter is read in, and nothing else
+    # (Time.zone.parse reads "tuesday" as today 00:00):
+    #
+    # - a date, `2026-10-22`: the end of that day in Time.zone
+    #   (23:59:59.999999999), as the admin's end-date presets: an assignment
+    #   that ends on a date lasts through it;
+    # - a date and a time of day, `2026-10-22T10:00`, with optional seconds
+    #   and fraction (`10:00:00`, `10:00:00.5`), `T` or one space between
+    #   them, and an optional offset, `Z` or `+02:00`; without one the time
+    #   is read in Time.zone.
+    #
+    # Every field must exist on the calendar and the clock (no 2026-02-30,
+    # no 24:00, no leap second).
+    #
+    # @api private
+    module IsoTime
+      FORMAT = /\A(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})
+                (?:[T\x20](?<hour>\d{2}):(?<minute>\d{2})(?::(?<second>\d{2})(?:\.(?<fraction>\d{1,9}))?)?
+                   (?<offset>Z|[+-]\d{2}:\d{2})?)?\z/x
+
+      # @return [ActiveSupport::TimeWithZone, nil] nil for a value that is not
+      #   one of the forms above
+      def self.parse(value)
+        match = FORMAT.match(value.strip) if value.is_a?(String)
+        fields = match && fields_of(match)
+        offset = match && match[:offset]
+        return unless fields && valid_offset?(offset)
+
+        match[:hour] ? at(fields, offset) : Time.zone.local(*fields.first(3)).end_of_day
+      end
+
+      # [year, month, day, hour, minute, seconds with fraction], nil when a
+      # field is off the calendar or the clock.
+      def self.fields_of(match)
+        date = match.values_at(:year, :month, :day).map(&:to_i)
+        clock = match.values_at(:hour, :minute, :second).map(&:to_i)
+        return unless Date.valid_date?(*date) && valid_clock?(*clock)
+
+        [*date, *clock.first(2), clock.last + fraction_of(match[:fraction])]
+      end
+
+      def self.valid_clock?(hour, minute, second)
+        hour < 24 && minute < 60 && second < 60
+      end
+
+      # nil (no offset) and Z are valid; ±HH:MM within a day.
+      def self.valid_offset?(offset)
+        return true if offset.nil? || offset == 'Z'
+
+        offset[1, 2].to_i < 24 && offset[4, 2].to_i < 60
+      end
+
+      def self.fraction_of(digits)
+        digits ? Rational(digits.to_i, 10**digits.size) : 0
+      end
+
+      def self.at(fields, offset)
+        return Time.zone.local(*fields) unless offset
+
+        Time.new(*fields, offset == 'Z' ? '+00:00' : offset).in_time_zone
+      end
+      private_class_method :fields_of, :valid_clock?, :valid_offset?, :fraction_of, :at
     end
   end
 end

data/app/controllers/concerns/permission_forge/save_notice.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # An admin save that changes nothing: not written, and said so. One
+  # definition for every form that saves a record (the field drawer, the
+  # action form, the rule builder, the group page, the Conditions tab, an
+  # end date, the set and Resource pages):
+  #
+  # - a record is saved only when it holds a change an audit event records
+  #   (#pf_save_changed, RecordsAuditEvents#audited_changes_pending?: a blank
+  #   posted over generated text is no change either, Admin::Prefill.posted;
+  #   a stamp of updated_by alone is none) — an unchanged record is not
+  #   saved, so no commit callback invalidates its holders' cached
+  #   permissions. A batched edit with no change (Admin::ChangeSet) saves
+  #   nothing either;
+  # - such a save says flash.no_changes (#pf_save_flash) — never the form's
+  #   "Saved …", and with no cache note: no cache work was done.
+  #
+  # Field test round 8 (B#70).
+  #
+  # @api private
+  module SaveNotice
+    extend ActiveSupport::Concern
+
+    # @param saved [ActiveRecord::Base, Boolean] the record just saved (or
+    #   left unsaved by #pf_save_changed), or whether a batched edit applied
+    #   any change
+    # @return [Boolean] whether the save changed anything
+    def self.saved_anything?(saved)
+      return saved if [true, false].include?(saved)
+
+      saved.saved_audited_changes?
+    end
+
+    private
+
+    # Assigns `attrs` to `record`, then runs the block (the save: save,
+    # save!) only when the record holds a change an audit event records.
+    #
+    # @param record [ActiveRecord::Base] one of the gem's models
+    # @param attrs [Hash] the attributes the form posted
+    # @yieldparam record [ActiveRecord::Base]
+    # @return the block's value, or true when there was nothing to save
+    def pf_save_changed(record, attrs = {})
+      record.assign_attributes(attrs)
+      return true unless record.audited_changes_pending?
+
+      yield record
+    end
+
+    # The flash of a save: { notice: "No changes to save." } when it changed
+    # nothing (SaveNotice.saved_anything?), else what the block answers — a
+    # flash Hash (CacheConfirmation#cache_flash_text), or a String, the notice.
+    #
+    # @param saved [ActiveRecord::Base, Boolean]
+    # @return [Hash] for redirect_to
+    def pf_save_flash(saved)
+      return { notice: pf_no_changes_text } unless SaveNotice.saved_anything?(saved)
+
+      flash = yield
+      flash.is_a?(Hash) ? flash : { notice: flash }
+    end
+
+    # "No changes to save." in the page's language.
+    def pf_no_changes_text
+      t('permission_forge.flash.no_changes')
+    end
+  end
+end

data/app/controllers/permission_forge/api/audit_events_controller.rb

@@ -9,7 +9,7 @@ module PermissionForge
       before_action :authorize_audit_log!
 
       rescue_from PermissionForge::Audit::EventQuery::Invalid do |error|
-        render json: { error: { status: 422, messages: error.errors } }, status: :unprocessable_entity
+        render_unprocessable(error.errors)
       end
 
       def index

data/app/controllers/permission_forge/api/base_controller.rb

@@ -30,6 +30,11 @@ module PermissionForge
       AUDIT_SOURCE = 'api'
       # Largest id a bigint column holds; past it PostgreSQL raises instead of matching nothing.
       MAX_RECORD_ID = (2**63) - 1
+      # Body attributes that refer to another record (#with_reference_id),
+      # with the message of a reference that names none.
+      REFERENCES = {
+        permission_set_group_id: 'permission_forge.validations.permission_set.group_missing'
+      }.freeze
 
       before_action :set_api_locale
       before_action :pf_require_tenant
@@ -41,15 +46,68 @@ module PermissionForge
       end
 
       rescue_from ActiveRecord::RecordInvalid do |e|
-        render json: { error: { status: 422, messages: e.record.errors.messages } }, status: :unprocessable_entity
+        render_validation_errors(e.record)
       end
 
+      # The uniqueness race: two requests passed the uniqueness validation
+      # together and the unique index refused this one's INSERT. The
+      # validation's own 422, keyed by the attribute, from the index the
+      # error names (UniqueConflict); `base` when it names none. Through
+      # 0.14.1 a 500.
+      rescue_from ActiveRecord::RecordNotUnique do |e|
+        render_unprocessable(PermissionForge::UniqueConflict.messages(e) ||
+                             { 'base' => [I18n.t('permission_forge.api.errors.record_not_unique')] })
+      end
+
+      # A NOT NULL column no validation foresaw (ValidatesRequiredColumns
+      # refuses nil in the gem's own columns, keyed by the attribute): a
+      # host column, a trigger. The 422 envelope, never a 500.
+      rescue_from ActiveRecord::NotNullViolation do
+        render_unprocessable({ 'base' => [I18n.t('permission_forge.api.errors.not_null')] })
+      end
+
+      # Field-keyed like a validation error (ResponseRenderer#render_input_error).
       rescue_from ActionController::ParameterMissing, ActionController::BadRequest do |e|
-        render json: { error: { status: 422, messages: e.message } }, status: :unprocessable_entity
+        render_input_error(e)
+      end
+
+      # A body Rails cannot parse (invalid JSON sent as application/json)
+      # raises when params are first read — in the forgery check, before
+      # api_auth — so the 400 is answered in the API's envelope instead of
+      # Rails' own. A disabled API stays a 404. params[:locale] cannot be
+      # read: the header decides.
+      rescue_from ActionDispatch::Http::Parameters::ParseError do
+        render_body_unreadable
+      end
+
+      # A form or multipart body Rack cannot parse (`a[=1&%%%`, a multipart
+      # body without its end) raises ActionController::BadRequest while
+      # Rails reads the parameters for its instrumentation, before
+      # rescue_from applies: answered here like an unreadable JSON body, the
+      # 400 envelope (through 0.15.0-rc Rails' own 400 page).
+      # AbstractController documents process_action as the method to
+      # override around an action.
+      def process_action(...)
+        super
+      rescue ActionController::BadRequest => e
+        raise if performed? || e.is_a?(ParamShapes::InvalidParam)
+
+        render_body_unreadable
       end
 
       private
 
+      # The 400 envelope of a body that cannot be read; a disabled API stays
+      # a 404. params[:locale] cannot be read: the header decides.
+      def render_body_unreadable
+        verify_api_enabled!
+        return if performed?
+
+        assign_api_locale(extract_locale_from_accept_language)
+        render json: { error: { status: 400, messages: I18n.t('permission_forge.api.errors.body_unreadable') } },
+               status: :bad_request
+      end
+
       # Who acts (Audit::ActorResolver: audit_actor_resolver, the signed-in
       # user, else an anonymous API client), request id, IP, the `reason`
       # body key and one correlation id per mutating request.
@@ -63,9 +121,12 @@ module PermissionForge
       end
 
       def set_api_locale
-        locale = params[:locale] || extract_locale_from_accept_language
-        # Always assign a locale (default when none/invalid) so a locale set by
-        # one request can never leak into the next on a reused thread.
+        assign_api_locale(params[:locale] || extract_locale_from_accept_language)
+      end
+
+      # Always assign a locale (default when none/invalid) so a locale set by
+      # one request can never leak into the next on a reused thread.
+      def assign_api_locale(locale)
         I18n.locale = if locale.present? && api_available_locale?(locale)
                         locale
                       else
@@ -104,6 +165,64 @@ module PermissionForge
         scope.find_by!(identifier => value)
       end
 
+      # The attributes of the body section `section` an endpoint writes to
+      # `model`: those of `keys` it has, each in its shape (Api::InputShapes,
+      # the one shape table). The other keys of the section go through
+      # strong parameters' own handling of keys an action does not take
+      # (logged, or raised under action_on_unpermitted_parameters = :raise).
+      #
+      # @param record [ActiveRecord::Base, nil] the record an update changes
+      # @return [ActiveSupport::HashWithIndifferentAccess]
+      # @raise [ActionController::ParameterMissing] the section is missing,
+      #   empty or not an object (a 422 keyed by it)
+      # @raise [InputShapes::Refused] a value of the wrong shape (a 422 keyed
+      #   by each such attribute)
+      def pf_record_attributes(section, model, *keys, record: nil)
+        attrs = pf_require_hash(section)
+        attrs.except(*keys.map(&:to_s)).permit
+        InputShapes.call(attrs, model, keys, record: record)
+      end
+
+      # The `name` of a copy: text without NUL bytes and surrounding white
+      # space, '' when absent or null (the caller's default name).
+      #
+      # @raise [InputShapes::Refused] for anything else (true, a number, a
+      #   list, an object), keyed by name: never silently the default name
+      def pf_copy_name
+        InputShapes.check!(:name, params[:name], :text)
+        pf_text_param(:name)
+      end
+
+      # `attrs` with the reference `key` (e.g. permission_set_group_id)
+      # replaced by the id of the record it names in `scope`, looked up like
+      # every identifier (tenant-scoped): its numeric id, or — under
+      # api_record_identifier = :uuid — its uuid, the identifier the API
+      # answers with. A blank value (null, "") is no reference (nil). Anything
+      # else that names no record of the scope is a 422 keyed by `key`; a
+      # uuid that starts with digits is never read as an id (the integer
+      # column would cast "12ab…" to 12).
+      #
+      # @raise [ParamShapes::InvalidParam]
+      def with_reference_id(attrs, key, scope)
+        return attrs unless attrs.key?(key)
+
+        value = attrs[key]
+        return attrs.merge(key => nil) if value.nil? || value == ''
+
+        attrs.merge(key => referenced_record(scope, value)&.id ||
+                           raise(ParamShapes::InvalidParam.new(key, I18n.t(REFERENCES.fetch(key)))))
+      end
+
+      def referenced_record(scope, value)
+        text = value.to_s if value.is_a?(String) || value.is_a?(Integer)
+        return unless text
+
+        if identifier_value?('id', text) then scope.find_by(id: text.to_i)
+        elsif PermissionForge.configuration.api_record_identifier.to_s == 'uuid' && identifier_value?('uuid', text)
+          scope.find_by(uuid: text)
+        end
+      end
+
       def identifier_value?(identifier, value)
         return false if value.empty? || value.include?("\0")
         return true unless identifier.to_s == 'id'
@@ -121,11 +240,43 @@ module PermissionForge
         user
       end
 
+      # The person params[key] names, for a new assignment or membership,
+      # within config.user_list_resolver (Admin::PeopleDirectory#find). Every
+      # refusal is a 422 keyed by the parameter, so it never reads as the
+      # Permission Set or the Group in the path being wrong (a 404):
+      #
+      # - missing, null or blank: "is missing";
+      # - not one id (a list, an object, a number with a fraction, text that
+      #   is not a key of the user model: "abc" for an integer key): "is not
+      #   a user id";
+      # - an id that names nobody the resolver lists: "names nobody who can
+      #   be assigned". An unknown id and someone the resolver leaves out read
+      #   the same, as in a bulk request's `skipped`.
+      #
+      # @raise [ParamShapes::InvalidParam]
+      def requested_user(key = :user_id)
+        value = params[key]
+        problem = user_id_problem(value)
+        user = PermissionForge::Admin::PeopleDirectory.new.find(value) unless problem
+        problem ||= I18n.t('permission_forge.api.errors.user_not_found') unless user
+        raise ParamShapes::InvalidParam.new(key, problem) if problem
+
+        user
+      end
+
+      # What is wrong with a user_id before anybody is looked up, nil when
+      # it is one id of the user model's key type.
+      def user_id_problem(value)
+        return I18n.t('permission_forge.api.errors.user_id_missing') if value.blank?
+        return if (value.is_a?(String) || value.is_a?(Integer)) && PermissionForge::Admin::PeopleDirectory::Ids.cast(value).any?
+
+        I18n.t('permission_forge.api.errors.user_id_invalid')
+      end
+
       def authorize_action!(action, record)
         authorizer = PermissionForge.configuration.api_action_authorization
-        message = I18n.t('permission_forge.api.errors.action_not_authorized')
         unless authorizer
-          return deny_when_authorization_required(message) do
+          return deny_when_authorization_required(I18n.t('permission_forge.api.errors.action_authorization_missing')) do
             audit_action_refused(action, record, hook: 'api_require_authorization')
           end
         end
@@ -133,7 +284,7 @@ module PermissionForge
         return if authorizer.call(self, action, record)
 
         audit_action_refused(action, record, hook: 'api_action_authorization')
-        render_not_authorized(message)
+        render_not_authorized(I18n.t('permission_forge.api.errors.action_not_authorized'))
       end
 
       # Runs the mutation authorization hook and the is_editable lock for a
@@ -174,9 +325,8 @@ module PermissionForge
       # A refusal records the ids as requested (bounded, Audit::Refusals).
       def authorize_assignment!(permission_set, user_ids)
         authorizer = PermissionForge.configuration.api_assignment_authorization
-        message = I18n.t('permission_forge.api.errors.assignment_not_authorized')
         unless authorizer
-          return deny_when_authorization_required(message) do
+          return deny_when_authorization_required(I18n.t('permission_forge.api.errors.assignment_authorization_missing')) do
             audit_assignment_refused(permission_set, user_ids, hook: 'api_require_authorization')
           end
         end
@@ -184,14 +334,15 @@ module PermissionForge
         return if authorizer.call(self, permission_set, PermissionForge::Admin::PeopleDirectory::Ids.cast(user_ids))
 
         audit_assignment_refused(permission_set, user_ids, hook: 'api_assignment_authorization')
-        render_not_authorized(message)
+        render_not_authorized(I18n.t('permission_forge.api.errors.assignment_not_authorized'))
       end
 
       # When config.api_require_authorization is on, a missing authorization lambda
       # means DENY (403) rather than the backward-compatible silent allow. This
       # prevents "authenticated == full admin" when the host wired api_auth but not
       # the per-action / assignment authorization hooks. The block records the
-      # refusal.
+      # refusal. The message names the missing option (the integrator's fix),
+      # unlike a lambda's denial; it carries nothing from the request.
       def deny_when_authorization_required(message)
         return unless PermissionForge.configuration.api_require_authorization