permission_forge 0.14.1

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

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    class BaseController < PermissionForge.configuration.api_base_controller_class.constantize
+      include PermissionForge::ApiAuthentication
+      include PermissionForge::TenantRequired
+      include PermissionForge::ParamShapes
+      include PermissionForge::Api::ResponseRenderer
+      include PermissionForge::Api::Pagination
+      include PermissionForge::Api::SerializerResolver
+
+      # API-safe CSRF posture. A mutating request without a valid CSRF token
+      # gets an empty session and an empty cookie jar (`:null_session`), so a
+      # cross-site form post from a signed-in admin's browser reaches api_auth
+      # (and any host `current_user`) with no session: a session- or
+      # cookie-based api_auth refuses it. Clients that authenticate with a
+      # header (a token, an API key) are unaffected. `prepend: true` puts the
+      # check first in the chain, before verify_api_enabled! /
+      # authenticate_api_request! (ApiAuthentication) and before the host
+      # base controller's own callbacks — registered after them it would
+      # only empty the session once api_auth had already let the request in.
+      # ActionController::API bases have no forgery protection (and no
+      # cookies), so this is a no-op there.
+      # Verified like the admin screens (ForgeryProtection).
+      include PermissionForge::ForgeryProtection
+
+      protect_from_forgery with: :null_session, prepend: true, **pf_forgery_strategy if respond_to?(:protect_from_forgery)
+
+      AUDIT_SOURCE = 'api'
+      # Largest id a bigint column holds; past it PostgreSQL raises instead of matching nothing.
+      MAX_RECORD_ID = (2**63) - 1
+
+      before_action :set_api_locale
+      before_action :pf_require_tenant
+      # After api_auth (a refused request records its own event).
+      around_action :pf_audit_request
+
+      rescue_from ActiveRecord::RecordNotFound do
+        render json: { error: { status: 404, messages: I18n.t('permission_forge.api.errors.not_found') } }, status: :not_found
+      end
+
+      rescue_from ActiveRecord::RecordInvalid do |e|
+        render json: { error: { status: 422, messages: e.record.errors.messages } }, status: :unprocessable_entity
+      end
+
+      rescue_from ActionController::ParameterMissing, ActionController::BadRequest do |e|
+        render json: { error: { status: 422, messages: e.message } }, status: :unprocessable_entity
+      end
+
+      private
+
+      # 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.
+      def pf_audit_request(&)
+        PermissionForge::Audit::RequestContext.wrap(self, source: AUDIT_SOURCE, &)
+      end
+
+      # Records a refused request so that no rollback takes it along.
+      def pf_audit_refused(event, **payload)
+        PermissionForge::Audit::RequestContext.refused(self, event, source: AUDIT_SOURCE, **payload)
+      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.
+        I18n.locale = if locale.present? && api_available_locale?(locale)
+                        locale
+                      else
+                        I18n.default_locale
+                      end
+      end
+
+      def extract_locale_from_accept_language
+        header = request.env['HTTP_ACCEPT_LANGUAGE']
+        return nil if header.blank?
+
+        # Split on commas, drop q-weights, take the primary subtag of each tag.
+        # Matches bare tags ("en") as well as region/quality forms ("en-US;q=0.8").
+        header.split(',').filter_map do |part|
+          tag = part.split(';').first.to_s.strip
+          primary = tag.split('-').first&.downcase
+          primary if primary && api_available_locale?(primary)
+        end.first
+      end
+
+      def api_available_locale?(locale)
+        allowed = PermissionForge.configuration.available_locales || PermissionForge::BUNDLED_LOCALES
+        Array(allowed).map(&:to_s).include?(locale.to_s)
+      end
+
+      # The record `params[param_key]` names in `scope` — the one lookup every
+      # API endpoint uses. Under api_record_identifier = :id only digits name a
+      # record: the database would cast '1abc', or a uuid that starts with
+      # digits, to 1 and answer for another record. A NUL byte names nothing
+      # (PostgreSQL raises on it). Raises RecordNotFound, rendered as a 404.
+      def find_record(scope, param_key = :identifier)
+        identifier = PermissionForge.configuration.api_record_identifier
+        value = params[param_key].to_s
+        raise ActiveRecord::RecordNotFound unless identifier_value?(identifier, value)
+
+        scope.find_by!(identifier => value)
+      end
+
+      def identifier_value?(identifier, value)
+        return false if value.empty? || value.include?("\0")
+        return true unless identifier.to_s == 'id'
+
+        value.match?(/\A[1-9]\d{0,18}\z/) && value.to_i <= MAX_RECORD_ID
+      end
+
+      # Looks up a host user by id within config.user_list_resolver
+      # (Admin::PeopleDirectory#find), rendering a 404 (and returning nil)
+      # when the id names nobody there — a missing user, someone the
+      # resolver leaves out, or a value that is not a key.
+      def find_host_user(user_id)
+        user = PermissionForge::Admin::PeopleDirectory.new.find(user_id)
+        render_not_found unless user
+        user
+      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
+            audit_action_refused(action, record, hook: 'api_require_authorization')
+          end
+        end
+
+        return if authorizer.call(self, action, record)
+
+        audit_action_refused(action, record, hook: 'api_action_authorization')
+        render_not_authorized(message)
+      end
+
+      # Runs the mutation authorization hook and the is_editable lock for a
+      # create/update/destroy. May render a 403; callers follow with
+      # `return if performed?`. Used by CrudActions and the bespoke controllers
+      # so every mutation path is guarded consistently.
+      # A destroy also asks the record's container (EditableLock.container_of):
+      # a set in a locked group is not deleted.
+      def guard_mutation!(action, record)
+        authorize_action!(action, record)
+        return if performed?
+
+        enforce_editable!(record, (PermissionForge::Admin::EditableLock.container_of(record) if action == :destroy))
+      end
+
+      # Blocks a change when a record, or what it belongs to (its Resource,
+      # Permission Set, or the Group of a membership — Admin::EditableLock),
+      # is flagged is_editable: false: a new child of a locked parent is
+      # refused like a change to the parent. Records with a nil/true flag are
+      # unaffected. The refusal names the locked record.
+      def enforce_editable!(*records)
+        reject_locked!(PermissionForge::Admin::EditableLock.locked_record(*records))
+      end
+
+      def reject_locked!(locked)
+        return unless locked
+
+        pf_audit_refused('admin.lock_refused', record: locked)
+        render json: {
+          error: { status: 403, messages: I18n.t('permission_forge.api.errors.not_editable') }
+        }, status: :forbidden
+      end
+
+      # config.api_assignment_authorization receives (controller, target,
+      # user_ids): the Permission Set (or the Group of a membership) and an
+      # Array of the people concerned cast to the user model's primary-key
+      # type (Integers for integer keys) — whatever shape the request sent.
+      # 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
+            audit_assignment_refused(permission_set, user_ids, hook: 'api_require_authorization')
+          end
+        end
+
+        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)
+      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.
+      def deny_when_authorization_required(message)
+        return unless PermissionForge.configuration.api_require_authorization
+
+        yield
+        render_not_authorized(message)
+      end
+
+      # api.auth_failed for a mutation the authorization refused. A record
+      # not saved yet (create) is named by its class only.
+      def audit_action_refused(action, record, hook:)
+        reference = if record.respond_to?(:persisted?) && record.persisted? then { record: record }
+                    elsif record then { record_type: record.class.name }
+                    else {}
+                    end
+        pf_audit_refused('api.auth_failed', data: { 'reason' => 'action_not_authorized', 'hook' => hook, 'action' => action.to_s },
+                                            **reference)
+      end
+
+      # `target` is the Permission Set, or the Permission Set Group of a
+      # membership; the user ids are bounded (Audit::Refusals).
+      def audit_assignment_refused(target, user_ids, hook:)
+        pf_audit_refused('api.auth_failed', **PermissionForge::Audit::Refusals.assignment(target, user_ids, hook: hook))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    class DashboardController < BaseController
+      before_action :require_admin!, only: :show
+
+      def show
+        render json: {
+          data: {
+            permission_sets_count: PermissionForge::PermissionSet.count,
+            active_sets_count: PermissionForge::PermissionSet.active.count,
+            resources_count: PermissionForge::Resource.count,
+            rules_count: PermissionForge::PermissionSetRule.count,
+            groups_count: PermissionForge::PermissionSetGroup.count,
+            users_count: PermissionForge::PermissionSetUser.select(:user_id).distinct.count
+          }
+        }, status: :ok
+      end
+
+      private
+
+      def require_admin!
+        return unless PermissionForge.configuration.api_stats_require_admin
+
+        head :forbidden unless @admin
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    # Members of one Permission Set Group. Adding and removing run through
+    # the model callbacks (group_membership.* audit events), after
+    # api_assignment_authorization and then config.admin_assignment_authorization.
+    class PermissionSetGroupUsersController < BaseController
+      include PermissionForge::AssignmentAuthorization
+
+      before_action :set_group
+
+      def index
+        scope = @group.permission_set_group_users.includes(:user)
+        render_collection(scope, serializer_for(:permission_set_group_user))
+      end
+
+      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)
+
+        gu = @group.permission_set_group_users.build(user: user)
+        save_and_render(gu, :permission_set_group_user)
+      end
+
+      # The member must be somebody config.user_list_resolver lists (404 otherwise).
+      def destroy
+        gu = find_record(@group.permission_set_group_users)
+        return unless find_host_user(gu.user_id)
+
+        authorize_assignment!(@group, [gu.user_id])
+        enforce_editable!(gu) unless performed?
+        return if performed? || pf_assignment_refused_api?(@group, gu.user_id, :remove_member)
+
+        gu.destroy!
+        head :no_content
+      end
+
+      private
+
+      def set_group
+        @group = find_record(PermissionForge::PermissionSetGroup, :permission_set_group_identifier)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    class PermissionSetGroupsController < BaseController
+      before_action :set_group, only: %i[show update destroy clone]
+
+      def index
+        scope = PermissionForge::PermissionSetGroup.order(:name)
+        render_collection(scope, serializer_for(:permission_set_group))
+      end
+
+      def show
+        render_record(@group, serializer_for(:permission_set_group))
+      end
+
+      def create
+        group = PermissionForge::PermissionSetGroup.new(group_params)
+        guard_mutation!(:create, group)
+        return if performed?
+
+        if group.save
+          render_created(group, serializer_for(:permission_set_group))
+        else
+          render_validation_errors(group)
+        end
+      end
+
+      def update
+        guard_mutation!(:update, @group)
+        return if performed?
+
+        if @group.update(group_params)
+          render_record(@group, serializer_for(:permission_set_group))
+        else
+          render_validation_errors(@group)
+        end
+      end
+
+      def destroy
+        guard_mutation!(:destroy, @group)
+        return if performed?
+
+        @group.destroy!
+        head :no_content
+      end
+
+      def clone
+        authorize_action!(:clone, @group)
+        return if performed?
+
+        # As the admin's Duplicate: the copy of the group and of its sets is editable.
+        cloned = PermissionForge::Services::PermissionSetGroupCloner.call(
+          permission_set_group: @group, attrs: { name: pf_text_param(:name).presence || "#{@group.name} (Copy)", is_editable: true },
+          unlock: true
+        )
+        render_created(cloned, serializer_for(:permission_set_group))
+      end
+
+      private
+
+      def set_group
+        @group = find_record(PermissionForge::PermissionSetGroup)
+      end
+
+      def group_params
+        pf_require_hash(:permission_set_group).permit(:name, :description, :is_active, :is_editable)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    class PermissionSetRulesController < BaseController
+      include CrudActions
+      include NestedResourceLookup
+
+      before_action :set_resource
+      before_action :set_rule, only: %i[show update destroy]
+
+      private
+
+      def collection_scope = @resource.permission_set_rules
+      def current_record = @rule
+      def serializer_type = :permission_set_rule
+
+      def build_record
+        record = collection_scope.build(record_params)
+        record.permission_set = @permission_set
+        record
+      end
+
+      def set_rule
+        @rule = find_nested_record(@resource.permission_set_rules)
+      end
+
+      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
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    # Assignments of one Permission Set. Every grant and revocation runs
+    # through the model callbacks (assignment.* audit events), after
+    # api_assignment_authorization and then config.admin_assignment_authorization.
+    class PermissionSetUsersController < BaseController
+      include PermissionForge::AssignmentAuthorization
+
+      # bulk_action → AssignmentAuthorization action; the keys are the
+      # service's VALID_ACTIONS, anything else is a 422 before the service runs.
+      BULK_ACTIONS = { 'assign' => :grant, 'revoke' => :revoke }.freeze
+
+      before_action :set_permission_set
+
+      def index
+        scope = @permission_set.permission_set_users.includes(:user)
+        render_collection(scope, serializer_for(:permission_set_user))
+      end
+
+      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)
+
+        create_assignment(user)
+      end
+
+      # The holder must be somebody config.user_list_resolver lists (404
+      # otherwise). Revoking narrows access for a granting set, also a locked
+      # one; on a locked Muting Permission Set it widens and is refused.
+      def destroy
+        psu = find_record(@permission_set.permission_set_users)
+        return unless find_host_user(psu.user_id)
+
+        authorize_assignment!(@permission_set, [psu.user_id])
+        reject_widening!(:revoke) unless performed?
+        return if performed? || pf_assignment_refused_api?(@permission_set, psu.user_id, :revoke)
+
+        psu.destroy!
+        head :no_content
+      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?
+        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
+
+      # 403 when the change would widen access on a locked set
+      # (Admin::EditableLock.widening_lock: which way depends on is_muting).
+      def reject_widening!(change)
+        reject_locked!(pf_widening_lock(@permission_set, change))
+      end
+
+      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)
+      end
+
+      # An unknown bulk_action raises ArgumentError (422, rescued in #bulk)
+      # before anything is authorized or changed.
+      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
+        end
+        pf_assignment_refused_api?(@permission_set, params[:user_ids], action)
+      end
+
+      def bulk_assignment
+        PermissionForge::Services::BulkPermissionSetAssignment.call(
+          permission_set: @permission_set,
+          user_ids: bulk_user_ids,
+          action: params[:bulk_action],
+          created_by: PermissionForge.current_user,
+          expires_at: pf_time_param(:expires_at)
+        )
+      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.
+      def bulk_user_ids
+        PermissionForge::Admin::PeopleDirectory.new.find_all(params[:user_ids]).map(&:id)
+      end
+
+      def set_permission_set
+        @permission_set = find_record(PermissionForge::PermissionSet, :permission_set_identifier)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    class PermissionSetsController < BaseController
+      before_action :set_permission_set, only: %i[show update destroy clone]
+
+      def index
+        scope = PermissionForge::PermissionSet.order(created_at: :desc)
+        render_collection(scope, serializer_for(:permission_set))
+      end
+
+      def show
+        render_record(@permission_set, serializer_for(:permission_set))
+      end
+
+      def create
+        ps = PermissionForge::PermissionSet.new(permission_set_params)
+        guard_mutation!(:create, ps)
+        return if performed?
+
+        save_set(ps) { render_created(ps, serializer_for(:permission_set)) }
+      end
+
+      # The lock is checked on the stored set, before the request's
+      # attributes (is_editable among them) are assigned.
+      def update
+        guard_mutation!(:update, @permission_set)
+        return if performed?
+
+        @permission_set.assign_attributes(permission_set_params)
+        save_set(@permission_set) { render_record(@permission_set, serializer_for(:permission_set)) }
+      end
+
+      def destroy
+        guard_mutation!(:destroy, @permission_set)
+        return if performed?
+
+        @permission_set.destroy!
+        head :no_content
+      end
+
+      def clone
+        authorize_action!(:clone, @permission_set)
+        return if performed?
+
+        # As the admin's Duplicate: an editable copy, outside a locked group.
+        cloned = PermissionForge::Admin::PermissionSetFactory.duplicate(
+          @permission_set, name: pf_text_param(:name).presence || "#{@permission_set.name} (Copy)"
+        )
+        render_created(cloned, serializer_for(:permission_set))
+      end
+
+      private
+
+      # Saves a set whose attributes are assigned, unless it would enter or
+      # leave a locked Permission Set Group (as the admin's group page
+      # refuses); yields to render on success.
+      def save_set(permission_set)
+        locked = locked_group_for_move(permission_set)
+        return reject_locked!(locked) if locked
+
+        permission_set.save ? yield : render_validation_errors(permission_set)
+      end
+
+      def locked_group_for_move(permission_set)
+        return unless permission_set.permission_set_group_id_changed?
+
+        PermissionForge::Admin::EditableLock.locked_group_for_move(
+          from: permission_set.permission_set_group_id_was, to: permission_set.permission_set_group_id
+        )
+      end
+
+      def set_permission_set
+        @permission_set = find_record(PermissionForge::PermissionSet)
+      end
+
+      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
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    class ResourceActionsController < BaseController
+      include CrudActions
+      include NestedResourceLookup
+
+      before_action :set_resource
+      before_action :set_action, only: %i[show update destroy]
+
+      private
+
+      def collection_scope = @resource.resource_actions
+      def current_record = @action
+      def serializer_type = :resource_action
+
+      def set_action
+        @action = find_nested_record(@resource.resource_actions)
+      end
+
+      def record_params
+        pf_require_hash(:resource_action).permit(:name, :label, :description, :is_permitted, :is_active)
+      end
+
+      # A create or a rename must also name a valid action key. Checked after
+      # the base checks (authorization, editable lock), so a caller who may
+      # not change the record gets its 403 first.
+      def guard_mutation!(action, record)
+        super
+        reject_invalid_key!(record) unless performed? || action == :destroy
+      end
+
+      # Action keys follow ControllerActions::KEY_FORMAT: the admin form, the
+      # controller catalog and permission_forge_actions accept nothing else.
+      # A row named "Export" or "archive " is not the key of `export` or
+      # `archive`: it would read as a restriction in the admin while that
+      # controller action stays unmanaged. Checked here rather than in a model
+      # validation, so rows that already carry such a name can still be edited
+      # and cloned.
+      def reject_invalid_key!(record)
+        name = requested_name
+        return if name.nil? || name.match?(PermissionForge::ControllerActions::KEY_FORMAT)
+
+        record.errors.add(:name, I18n.t('permission_forge.errors.admin.action_format'))
+        render_validation_errors(record)
+      end
+
+      # The name a create or a rename asks for; nil when an update keeps the
+      # name the row has.
+      def requested_name
+        current = current_record&.name
+        name = record_params.fetch(:name, current).to_s
+        name unless name == current
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    class ResourceFieldsController < BaseController
+      include CrudActions
+      include NestedResourceLookup
+
+      before_action :set_resource
+      before_action :set_field, only: %i[show update destroy]
+
+      private
+
+      def collection_scope = @resource.resource_fields
+      def current_record = @field
+      def serializer_type = :resource_field
+
+      def set_field
+        @field = find_nested_record(@resource.resource_fields)
+      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
+        )
+      end
+    end
+  end
+end