permission_forge 0.14.1 → 0.15.0

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

@@ -3,7 +3,7 @@
 module PermissionForge
   module Api
     class DashboardController < BaseController
-      before_action :require_admin!, only: :show
+      before_action :authorize_stats!, only: :show
 
       def show
         render json: {
@@ -20,10 +20,35 @@ module PermissionForge
 
       private
 
-      def require_admin!
-        return unless PermissionForge.configuration.api_stats_require_admin
+      # While config.api_stats_require_admin is on (the default), only a
+      # caller config.api_stats_authorization allows reads the stats; a
+      # refusal is a 403 recorded as api.auth_failed (stats_not_authorized).
+      # Without the lambda the 403 names it, as for the other lambdas.
+      def authorize_stats!
+        configuration = PermissionForge.configuration
+        return unless configuration.api_stats_require_admin
 
-        head :forbidden unless @admin
+        authorizer = configuration.api_stats_authorization
+        return if authorizer ? authorizer.call(self) : legacy_admin_flag?
+
+        pf_audit_refused('api.auth_failed', data: { 'reason' => 'stats_not_authorized',
+                                                    'hook' => authorizer ? 'api_stats_authorization' : 'api_stats_require_admin' })
+        render_not_authorized(authorizer ? nil : I18n.t('permission_forge.api.errors.stats_authorization_missing'))
+      end
+
+      # Through 0.15 the stats endpoint read an @admin = true that api_auth
+      # set on the controller (documented in 0.14). Still honoured when
+      # api_stats_authorization is not set, with a deprecation warning;
+      # removed in 0.16.
+      def legacy_admin_flag?
+        return false unless @admin
+
+        PermissionForge::Deprecation.warn(
+          'Setting @admin on the API controller (in api_auth) to allow GET /api/stats is deprecated; ' \
+          'set config.api_stats_authorization = ->(controller) { ... } instead',
+          key: :api_stats_admin_ivar
+        )
+        true
       end
     end
   end

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

@@ -15,14 +15,17 @@ module PermissionForge
         render_collection(scope, serializer_for(:permission_set_group_user))
       end
 
+      # A user_id that is missing, not an id, or names nobody
+      # config.user_list_resolver lists is a 422 keyed by user_id
+      # (BaseController#requested_user), after the authorization hooks.
       def create
         user_id = params[:user_id]
         authorize_assignment!(@group, [user_id])
         enforce_editable!(@group) unless performed?
         return if performed?
 
-        user = find_host_user(user_id)
-        return if performed? || pf_assignment_refused_api?(@group, user.id, :add_member)
+        user = requested_user
+        return if pf_assignment_refused_api?(@group, user.id, :add_member)
 
         gu = @group.permission_set_group_users.build(user: user)
         save_and_render(gu, :permission_set_group_user)

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

@@ -49,10 +49,11 @@ module PermissionForge
         authorize_action!(:clone, @group)
         return if performed?
 
-        # As the admin's Duplicate: the copy of the group and of its sets is editable.
+        # As the admin's Duplicate: the copy of the group and of its sets is
+        # editable, and named "<name> (copy)" in the request's locale.
+        name = pf_copy_name.presence || I18n.t('permission_forge.permission_sets.copy_name', name: @group.name)
         cloned = PermissionForge::Services::PermissionSetGroupCloner.call(
-          permission_set_group: @group, attrs: { name: pf_text_param(:name).presence || "#{@group.name} (Copy)", is_editable: true },
-          unlock: true
+          permission_set_group: @group, attrs: { name: name, is_editable: true }, unlock: true
         )
         render_created(cloned, serializer_for(:permission_set_group))
       end
@@ -64,7 +65,7 @@ module PermissionForge
       end
 
       def group_params
-        pf_require_hash(:permission_set_group).permit(:name, :description, :is_active, :is_editable)
+        pf_record_attributes(:permission_set_group, PermissionForge::PermissionSetGroup, :name, :description, :is_active, :is_editable)
       end
     end
   end

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

@@ -25,12 +25,14 @@ module PermissionForge
         @rule = find_nested_record(@resource.permission_set_rules)
       end
 
+      # A list for field_value under in / not_in / between is joined with
+      # commas; the stored rule's operator decides on an update that sends
+      # none (Api::InputShapes).
       def record_params
-        pf_require_hash(:permission_set_rule).permit(
-          :name, :field_name, :field_value, :operator,
-          :join_type, :field_accessor_path, :include_nulls,
-          :is_active, :is_editable, :failure_message
-        )
+        pf_record_attributes(:permission_set_rule, PermissionForge::PermissionSetRule,
+                             :name, :field_name, :field_value, :operator,
+                             :join_type, :field_accessor_path, :include_nulls,
+                             :is_active, :is_editable, :failure_message, record: current_record)
       end
     end
   end

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

@@ -19,13 +19,16 @@ module PermissionForge
         render_collection(scope, serializer_for(:permission_set_user))
       end
 
+      # A user_id that is missing, not an id, or names nobody
+      # config.user_list_resolver lists is a 422 keyed by user_id
+      # (BaseController#requested_user), after the authorization hooks.
       def create
         authorize_assignment!(@permission_set, [params[:user_id]])
         reject_widening!(:grant) unless performed?
         return if performed?
 
-        user = find_host_user(params[:user_id])
-        return if performed? || pf_assignment_refused_api?(@permission_set, user.id, :grant)
+        user = requested_user
+        return if pf_assignment_refused_api?(@permission_set, user.id, :grant)
 
         create_assignment(user)
       end
@@ -41,20 +44,20 @@ module PermissionForge
         reject_widening!(:revoke) unless performed?
         return if performed? || pf_assignment_refused_api?(@permission_set, psu.user_id, :revoke)
 
-        psu.destroy!
-        head :no_content
+        # The revoked assignment and what the cache store confirmed
+        # (meta.cache, as the bulk endpoint answers it); through 0.14.x a 204.
+        outcome = PermissionForge::Cache::Report.of { psu.destroy! }
+        render_record_with_cache(psu, outcome, status: :ok)
       end
 
       def bulk
         authorize_assignment!(@permission_set, params[:user_ids])
         # On a locked set only what narrows access passes (an unknown
         # bulk_action is judged as a grant, then refused as a 422).
-        reject_widening!(BULK_ACTIONS.fetch(params[:bulk_action].to_s, :grant)) unless performed?
+        reject_widening!(BULK_ACTIONS.fetch(bulk_action_param, :grant)) unless performed?
         return if performed? || bulk_refused?
 
         render json: { data: bulk_assignment }, status: :ok
-      rescue ArgumentError => e
-        render json: { error: { status: 422, messages: e.message } }, status: :unprocessable_entity
       end
 
       private
@@ -65,34 +68,92 @@ module PermissionForge
         reject_locked!(pf_widening_lock(@permission_set, change))
       end
 
+      # The new assignment and what the cache store confirmed (meta.cache).
       def create_assignment(user)
-        psu = @permission_set.permission_set_users.build(user: user, expires_at: pf_time_param(:expires_at))
-        psu.save ? render_created(psu, serializer_for(:permission_set_user)) : render_validation_errors(psu)
+        psu = @permission_set.permission_set_users.build(user: user, expires_at: future_expires_at)
+        saved = false
+        outcome = PermissionForge::Cache::Report.of { saved = psu.save }
+        return render_validation_errors(psu) unless saved
+
+        render_record_with_cache(psu, outcome, status: :created)
       end
 
-      # An unknown bulk_action raises ArgumentError (422, rescued in #bulk)
-      # before anything is authorized or changed.
+      # params[:expires_at] (ParamShapes#pf_time_param) for a new
+      # assignment. An end that is not after now would create an assignment
+      # that grants nothing: refused (422) before anybody is assigned. The
+      # admin's Undo restores a removed assignment with the end it had, also
+      # one that has passed, and does not come through here.
+      def future_expires_at
+        expires_at = pf_time_param(:expires_at)
+        return expires_at if expires_at.nil? || expires_at > Time.current
+
+        raise ParamShapes::InvalidParam.new(:expires_at, I18n.t('permission_forge.api.errors.expires_at_past'))
+      end
+
+      # An unknown bulk_action, and a request that names nobody, are a 422
+      # ({ "bulk_action": [...] }, { "user_ids": [...] }) before anything is
+      # changed: a 200 that did nothing would hide a broken payload.
       def bulk_refused?
-        action = BULK_ACTIONS.fetch(params[:bulk_action].to_s) do |name|
-          PermissionForge::Services::BulkPermissionSetAssignment.validate_action!(name)
-          raise ArgumentError, "Invalid action: #{name}" # a service action this controller does not map
+        action = BULK_ACTIONS.fetch(bulk_action_param) do
+          raise ParamShapes::InvalidParam.new(:bulk_action, I18n.t('permission_forge.api.errors.bulk_action_invalid'))
         end
+        require_user_ids!
         pf_assignment_refused_api?(@permission_set, params[:user_ids], action)
       end
 
+      # params[:bulk_action] when it is text ('' otherwise: a list or an
+      # object is no action, never its #to_s).
+      def bulk_action_param
+        action = params[:bulk_action]
+        action.is_a?(String) ? action : ''
+      end
+
+      # user_ids missing, [], "" or only blanks: "must name at least one
+      # user". Anything else that is not a list of ids — one string such as
+      # "1,3", a number, an object, a list holding an object, a list, a
+      # fraction or a boolean —: "must be a list" — through 0.14.1 "1,3" was
+      # read as one id and answered 200 with nobody assigned, and an element
+      # that was no id was left out without a word. A blank string beside an
+      # id is ignored, as Rails' own `collection_singular_ids=` ignores it
+      # (`collection_check_boxes` sends one with every form); Ids.cast leaves
+      # it out. Ids that name nobody are not refused: they are reported as
+      # `skipped`. (A JSON null among them never gets here: Rails' deep_munge
+      # removes it from the parameters.)
+      def require_user_ids!
+        user_ids = params[:user_ids]
+        message = if Array.wrap(user_ids).all?(&:blank?) then I18n.t('permission_forge.api.errors.user_ids_missing')
+                  elsif !user_id_list?(user_ids) then I18n.t('permission_forge.api.errors.user_ids_not_list')
+                  end
+        raise ParamShapes::InvalidParam.new(:user_ids, message) if message
+      end
+
+      def user_id_list?(user_ids)
+        user_ids.is_a?(Array) && user_ids.all? { |id| id.is_a?(String) || id.is_a?(Integer) }
+      end
+
+      # The service's counts and its cache outcome (`cache`: `confirmed`,
+      # `process_local`, `unconfirmed` — Cache::Outcome, as every
+      # cache-touching operation answers it) plus `skipped`: the ids of the
+      # request that name nobody config.user_list_resolver lists. A revoke
+      # ignores expires_at (it removes the assignments whatever their end),
+      # also one that cannot be read.
       def bulk_assignment
-        PermissionForge::Services::BulkPermissionSetAssignment.call(
+        user_ids = bulk_user_ids
+        result = PermissionForge::Services::BulkPermissionSetAssignment.call(
           permission_set: @permission_set,
-          user_ids: bulk_user_ids,
-          action: params[:bulk_action],
+          user_ids: user_ids,
+          action: bulk_action_param,
           created_by: PermissionForge.current_user,
-          expires_at: pf_time_param(:expires_at)
+          expires_at: (future_expires_at if bulk_action_param == 'assign')
         )
+        # Someone outside user_list_resolver and an id that names no user
+        # read the same: the answer says nothing about who exists.
+        result.merge(skipped: PermissionForge::Admin::PeopleDirectory::Ids.unmatched(params[:user_ids], user_ids))
       end
 
       # The people of the request within config.user_list_resolver
       # (Admin::PeopleDirectory#find_all); an id naming nobody there is
-      # skipped, as an unknown id always was.
+      # skipped (and reported).
       def bulk_user_ids
         PermissionForge::Admin::PeopleDirectory.new.find_all(params[:user_ids]).map(&:id)
       end

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

@@ -45,8 +45,10 @@ module PermissionForge
         return if performed?
 
         # As the admin's Duplicate: an editable copy, outside a locked group.
+        # Names are unique per tenant: the default one is the admin's
+        # "<name> (copy)" in the request's locale, numbered when taken.
         cloned = PermissionForge::Admin::PermissionSetFactory.duplicate(
-          @permission_set, name: pf_text_param(:name).presence || "#{@permission_set.name} (Copy)"
+          @permission_set, name: pf_copy_name.presence || PermissionForge::PermissionSet.copy_name(@permission_set.name)
         )
         render_created(cloned, serializer_for(:permission_set))
       end
@@ -75,12 +77,16 @@ module PermissionForge
         @permission_set = find_record(PermissionForge::PermissionSet)
       end
 
+      # The activation conditions take their shapes from Api::InputShapes
+      # (allowed_ips a String or a list of Strings, an hour digits, a flag
+      # text; null or "" clears); permission_set_group_id takes the group's
+      # id or, under api_record_identifier = :uuid, its uuid
+      # (BaseController#with_reference_id).
       def permission_set_params
-        pf_require_hash(:permission_set).permit(
-          :name, :description, :is_active, :is_editable, :is_muting,
-          :requires_session_flag, :allowed_ips, :allowed_hours_start, :allowed_hours_end,
-          :permission_set_group_id
-        )
+        attrs = pf_record_attributes(:permission_set, PermissionForge::PermissionSet,
+                                     :name, :description, :is_active, :is_editable, :is_muting, :permission_set_group_id,
+                                     :requires_session_flag, :allowed_hours_start, :allowed_hours_end, :allowed_ips)
+        with_reference_id(attrs, :permission_set_group_id, PermissionForge::PermissionSetGroup)
       end
     end
   end

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

@@ -20,7 +20,7 @@ module PermissionForge
       end
 
       def record_params
-        pf_require_hash(:resource_action).permit(:name, :label, :description, :is_permitted, :is_active)
+        pf_record_attributes(:resource_action, PermissionForge::ResourceAction, :name, :label, :description, :is_permitted, :is_active)
       end
 
       # A create or a rename must also name a valid action key. Checked after

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

@@ -20,10 +20,9 @@ module PermissionForge
       end
 
       def record_params
-        pf_require_hash(:resource_field).permit(
-          :name, :label, :description, :is_active, :is_editable,
-          :read_access, :edit_access, :mask_access, :mask_strategy
-        )
+        pf_record_attributes(:resource_field, PermissionForge::ResourceField,
+                             :name, :label, :description, :is_active, :is_editable,
+                             :read_access, :edit_access, :mask_access, :mask_strategy)
       end
     end
   end

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

@@ -8,26 +8,34 @@ module PermissionForge
       before_action :set_permission_set
       before_action :set_resource, only: %i[show update destroy generate_fields]
 
-      # Grants read (and, with grant_all, edit) on every unconfigured column,
-      # so it passes the same gates as the admin UI's "Sync fields": the
-      # authorization hook, then the lock on the resource and its set.
+      # Creates a field row for every unconfigured column: with grant_all,
+      # readable and editable, unmasked; without it, no access (under
+      # gdpr_defaults, personal-data columns readable and masked). It passes
+      # the same gates as the admin UI's "Sync fields": the authorization
+      # hook, then the lock on the resource and its set. grant_all is read
+      # by ParamShapes#pf_boolean_param (true, "true", 1, "1"; absent, false,
+      # "false", 0, "0"): anything else is a 422 keyed by grant_all, never
+      # fields without edit. A Resource named after no model this app can
+      # load (PermissionForge::ModelLookup: `Kernel`, a model without its
+      # table) has no columns: a 422 keyed by name.
       def generate_fields
         guard_mutation!(:generate_fields, @resource)
+        refuse_no_model unless performed?
         return if performed?
 
         fields = PermissionForge::Services::ResourceFieldGenerator.call(
           resource: @resource,
-          grant_all: %w[true 1].include?(params[:grant_all])
+          grant_all: pf_boolean_param(:grant_all)
         )
         data = PermissionForge::Api::Serializers::ResourceFieldSerializer.collection(fields)
         render json: { data: data }, status: :created
+      rescue ParamShapes::InvalidParam
+        raise # rendered by BaseController like every input error
       rescue StandardError => e
         # Log the internal detail; return a generic message so model/column names
         # and adapter errors are not leaked to API clients.
         Rails.logger.error("[PermissionForge] generate_fields failed for #{@resource&.name}: #{e.class}: #{e.message}")
-        render json: {
-          error: { status: 422, messages: I18n.t('permission_forge.api.errors.field_generation_failed') }
-        }, status: :unprocessable_entity
+        render_unprocessable('base' => [I18n.t('permission_forge.api.errors.field_generation_failed')])
       end
 
       private
@@ -36,6 +44,13 @@ module PermissionForge
       def current_record = @resource
       def serializer_type = :resource
 
+      # 422 on name for a Resource named after no model this app can load.
+      def refuse_no_model
+        return if PermissionForge::ModelLookup.model?(@resource.name)
+
+        render_unprocessable('name' => [I18n.t('permission_forge.api.errors.resource_names_no_model')])
+      end
+
       def set_permission_set
         @permission_set = find_record(PermissionForge::PermissionSet, :permission_set_identifier)
       end
@@ -45,11 +60,10 @@ module PermissionForge
       end
 
       def record_params
-        pf_require_hash(:resource).permit(
-          :name, :description, :is_active, :is_editable,
-          :read_access, :create_access, :edit_access, :delete_access,
-          :view_all, :modify_all
-        )
+        pf_record_attributes(:resource, PermissionForge::Resource,
+                             :name, :description, :is_active, :is_editable,
+                             :read_access, :create_access, :edit_access, :delete_access,
+                             :view_all, :modify_all)
       end
     end
   end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    # Any path and method under the API mount that no endpoint answers
+    # (`GET /api/unknown`, `POST /api/audit_events`): a 404 in the API's JSON
+    # envelope instead of Rails' HTML page. Drawn after every API route, and
+    # only under /api. It runs the API's guards first: while api_enabled is
+    # off it is the same bodiless 404 as every API route; a caller api_auth
+    # refuses gets the 401 and a request with no tenant the 403, each
+    # recorded as api.auth_failed like on any endpoint.
+    #
+    # @api private
+    class UnmatchedRoutesController < BaseController
+      def show
+        render_not_found(I18n.t('permission_forge.api.errors.route_not_found'))
+      end
+    end
+  end
+end

data/app/controllers/permission_forge/application_controller.rb

@@ -26,6 +26,7 @@ module PermissionForge
     include PermissionForge::TenantRequired
     include PermissionForge::ParamShapes
     include PermissionForge::HtmlFormat
+    include PermissionForge::SaveNotice
 
     THEMES = %w[auto light dark].freeze
     FRAGMENT_HEADER = 'X-PF-Fragment'.freeze
@@ -38,19 +39,56 @@ module PermissionForge
     # inside the scope suspension (an actor resolver may query).
     around_action :pf_audit_request
 
+    # The uniqueness race (two requests passed the uniqueness validation
+    # together; the unique index refused this one's INSERT): back to the
+    # page the form was on (the admin's home without a Referer, never
+    # another host) with the validation's message for the index the error
+    # names (UniqueConflict), or the generic one. 303: the browser follows
+    # with a GET whatever the form's method was. Through 0.14.1 a 500.
+    rescue_from ActiveRecord::RecordNotUnique do |error|
+      detail = PermissionForge::UniqueConflict.sentence(error)
+      alert = detail ? t('permission_forge.flash.record_not_unique_detail', detail: detail) : t('permission_forge.flash.record_not_unique')
+      redirect_back_or_to permission_forge.root_path, alert: alert, allow_other_host: false, status: :see_other
+    end
+
+    # A NOT NULL column no validation foresaw (ValidatesRequiredColumns
+    # covers the gem's own columns): back to the page like the uniqueness
+    # race, never a 500.
+    rescue_from ActiveRecord::NotNullViolation do
+      redirect_back_or_to permission_forge.root_path, alert: t('permission_forge.flash.not_null'), allow_other_host: false,
+                                                      status: :see_other
+    end
+
+    # A flag the admin cannot read (ParamShapes::InvalidFlag: not true or
+    # false, where the forms post "0" and "1"): back to the page like the
+    # uniqueness race, saying which flag, nothing changed. ActiveModel's
+    # cast read any other word as true; this is never that, nor a 500. (Any
+    # other InvalidParam, a date the admin cannot read, stays a 400.)
+    rescue_from PermissionForge::ParamShapes::InvalidFlag do |error|
+      redirect_back_or_to permission_forge.root_path,
+                          alert: t('permission_forge.flash.invalid_param', param: error.param, detail: error.detail),
+                          allow_other_host: false, status: :see_other
+    end
+
     helper PermissionForge::ApplicationHelper unless self < PermissionForge::ApplicationHelper
     helper_method :pf_fragment?, :pf_theme, :pf_help_visible?, :pf_current_admin,
                   :pf_attention, :pf_settings_catalog, :pf_back_or
 
     private
 
+    # A Permission Set's, group's or rule's name for a flash (Admin::RecordName:
+    # an install-default English name in the request's language).
+    def pf_record_name(record)
+      PermissionForge::Admin::RecordName.for(record)
+    end
+
     # Memoized per request: drives the Home badge and the home page.
     def pf_attention
       @pf_attention ||= PermissionForge::Admin::AttentionItems.new
     end
 
     def pf_settings_catalog
-      @pf_settings_catalog ||= PermissionForge::Admin::SettingsCatalog.new
+      @pf_settings_catalog ||= PermissionForge::Admin::SettingsCatalog.new(attention: pf_attention)
     end
 
     def set_locale
@@ -178,10 +216,6 @@ module PermissionForge
       raise ActionController::RoutingError, 'Not Found'
     end
 
-    def pf_locked?(record)
-      PermissionForge::Admin::EditableLock.locked?(record)
-    end
-
     # Redirects with an alert when the record (or any of `records`), or what
     # it belongs to (Admin::EditableLock: its Resource, Permission Set, the
     # Group of a membership), is locked, and records the refusal