permission_forge 0.14.1

data/lib/permission_forge/services/permission_set_group_cloner.rb

@@ -0,0 +1,52 @@
+module PermissionForge
+  module Services
+    # Deep-copies a Permission Set Group with all its Permission Sets (each
+    # through PermissionSetCloner) — never its members. The group's copy
+    # records `permission_set_group.cloned`, each set's copy
+    # `permission_set.cloned`; every event of the copy shares one correlation id.
+    #
+    # @api public
+    class PermissionSetGroupCloner
+      include Clonable
+
+      # @param unlock [Boolean] copy the group's sets (and their rows)
+      #   editable (`is_editable: true`) instead of keeping their locks
+      def self.call(permission_set_group:, attrs: {}, unlock: false)
+        new(permission_set_group, attrs, unlock: unlock).call
+      end
+
+      def initialize(permission_set_group, attrs, unlock: false)
+        @group = permission_set_group
+        @attrs = attrs
+        @unlock = unlock
+      end
+
+      # @return [PermissionSetGroup] the copy
+      def call
+        PermissionForge::Audit.correlate do
+          @group.class.transaction do
+            cloned = duplicate_record(@group, **@attrs)
+            clone_permission_sets(cloned)
+            record_clone(cloned)
+            cloned
+          end
+        end
+      end
+
+      private
+
+      def clone_permission_sets(cloned_group)
+        @group.permission_sets.each do |ps|
+          attrs = { name: ps.name, permission_set_group: cloned_group }
+          attrs[:is_editable] = true if @unlock
+          PermissionSetCloner.call(permission_set: ps, attrs: attrs, unlock: @unlock)
+        end
+      end
+
+      def record_clone(cloned)
+        PermissionForge::Audit.record('permission_set_group.cloned', record: cloned,
+                                                                     data: { 'source_uuid' => @group.uuid, 'source_name' => @group.name })
+      end
+    end
+  end
+end

data/lib/permission_forge/services/permits_attributes/nested_records.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    class PermitsAttributes
+      # Which nested records name a row the current user may reach.
+      #
+      # A nested record keeps its `id` (without one a payload can only
+      # create), and Rails refuses the id of another parent's row — but it
+      # loads the rows of the SAME parent through the association, which is
+      # not rule-scoped. So a record with an id survives only when the child
+      # model has no row-level rules to ask (no PermissionScopedFindable:
+      # left to Rails) or the id is inside `permission_scoped` for the current
+      # user, checked in one query per payload. Otherwise the whole record
+      # goes: dropping the id alone would turn an update into a create. A
+      # blank id is a new record, as Rails reads it: nothing to check.
+      #
+      # @api private
+      class NestedRecords
+        # One id per record. A plain Hash may carry both 'id' and :id; Rails
+        # reads the record with indifferent access (the last key wins), and
+        # the guard must not check one id while Rails applies the other. The
+        # same id under both keys is kept under one; two ids drop the record.
+        #
+        # @param record [Hash] a filtered record
+        # @return [Hash, nil]
+        def self.with_one_id(record)
+          return record unless record.key?('id') && record.key?(:id)
+
+          ids = [record['id'], record[:id]].map { |id| id.to_s.presence }.uniq
+          record.except(:id) if ids.size == 1
+        end
+
+        # @param collection [Boolean] whether the association is a collection
+        #   (has_many); a has_one / belongs_to payload is one record
+        def initialize(child, collection:)
+          @child = child
+          @collection = collection
+        end
+
+        # @param payload [Array<Hash>, Hash] the filtered payload: an Array of
+        #   records, Rails' index Hash, or one record
+        # @yield once for every record of a collection that is dropped
+        # @return [Array<Hash>, Hash, nil] the payload without the denied
+        #   records; nil when its one record is denied
+        def admit(payload, &)
+          return payload unless @child.respond_to?(:permission_scoped)
+          return admit_one(payload) unless @collection
+
+          case payload
+          when Array then admit_each(payload, &)
+          when Hash then id_key?(payload) ? admit_one(payload) : admit_indexed(payload, &)
+          else payload
+          end
+        end
+
+        private
+
+        def admit_each(records, &)
+          denied = denied_ids(records)
+          records.select { |record| admitted?(record, denied, &) }
+        end
+
+        def admit_indexed(records, &)
+          denied = denied_ids(records.values)
+          records.select { |_, record| admitted?(record, denied, &) }
+        end
+
+        def admit_one(record)
+          record if denied_ids([record]).empty?
+        end
+
+        def admitted?(record, denied)
+          return true unless denied.include?(id_of(record))
+
+          yield if block_given?
+          false
+        end
+
+        # The ids among the records that permission_scoped does not reach,
+        # as Strings, in one query. An id that names no row is denied too.
+        def denied_ids(records)
+          ids = records.filter_map { |record| id_of(record) }
+          return [] if ids.empty?
+
+          key = @child.primary_key
+          ids - @child.permission_scoped.where(key => ids).pluck(key).map(&:to_s)
+        end
+
+        # As Rails tells one record of a collection from the index form: by
+        # the key, whatever it holds.
+        def id_key?(record)
+          record.key?('id') || record.key?(:id)
+        end
+
+        # The record's id as a String; nil for none or a blank one.
+        def id_of(record)
+          return unless record.respond_to?(:key?)
+
+          id = record.key?('id') ? record['id'] : record[:id]
+          id.to_s.presence
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/services/permits_attributes.rb

@@ -0,0 +1,270 @@
+module PermissionForge
+  module Services
+    # Filters permitted params by the current user's field-level EDIT permissions.
+    #
+    # A key is kept when the user may edit that field on the resource, whatever
+    # its value: a Hash or an Array is a value like any other (a json column),
+    # never a payload to look into. A key the user may not edit is dropped,
+    # whatever its value (fail closed).
+    #
+    # The one exception is a nested payload: `<assoc>_attributes` for an
+    # association the model accepts nested attributes for. It is filtered
+    # record by record against the ASSOCIATION MODEL's own resource entry — an
+    # Array per element, Rails' index Hash per value, a has_one / belongs_to
+    # Hash as one record; an element that is not a record is dropped. A
+    # record keeps its `id` only when it names a row the user may reach
+    # ({NestedRecords}: inside the child model's `permission_scoped`, or the
+    # child has no row rules to ask); a denied record is dropped whole. A
+    # record keeps its `_destroy` only when the user may delete the model
+    # the payload is filtered for (its entry's `delete_access`; Rails would
+    # otherwise destroy the row on the strength of an edit grant). When
+    # the user's hash has no entry for that model the payload is dropped;
+    # config.nested_attributes_parent_fallback = true filters it against the
+    # parent's fields and delete access instead (the id check still applies).
+    #
+    # Non-mutating: the caller's params object is never modified; a new plain Hash
+    # is returned.
+    #
+    # The keys that were dropped are published as params.filtered (when it is
+    # stored or heard; nothing is collected otherwise): their paths —
+    # `secret`, `supplier_attributes.secret`, `lines_attributes.*.price`,
+    # `lines_attributes.*` for an element that is no record — never their
+    # values. Without a user every key is dropped (reason nil_user).
+    #
+    # @example
+    #   filtered = PermitsAttributes.call(resource: customer, permitted_params: params)
+    #
+    # @api public
+    class PermitsAttributes
+      EVENT = 'params.filtered'.freeze
+      NESTED_SUFFIX = '_attributes'.freeze
+      # The path segment of a record inside a collection payload.
+      EACH = '*'.freeze
+      # The keys of a nested record that name it rather than set a field.
+      RECORD_KEYS = %w[id].freeze
+      # The key of a nested record that asks for its destruction.
+      DESTROY_KEY = '_destroy'.freeze
+
+      # Filters incoming params by the user's field-level edit access (does not mutate them).
+      # @param resource [String] the model name
+      # @param permitted_params [Hash]
+      # @return [Hash]
+      def self.call(resource:, permitted_params:)
+        new(resource: resource, permitted_params: permitted_params).call
+      end
+
+      def initialize(resource:, permitted_params:)
+        @user = PermissionForge.current_user
+        @resource = resource
+        @permitted_params = permitted_params
+      end
+
+      # @return [Hash] a new hash holding only the fields the user may edit
+      def call
+        if @user.blank?
+          report_dropped('nil_user') { each_pair(@permitted_params) { |key, _| dropped(key) } } if nil_user_report?
+          return {}
+        end
+        return {} if resource_class.nil?
+        return {} if @permitted_params.blank?
+
+        report_dropped('field_access') { filter_for(resource_class, @permitted_params) }
+      end
+
+      private
+
+      # Runs the filter, collecting the dropped paths in @dropped only when
+      # params.filtered is stored or heard, and publishes them.
+      def report_dropped(reason)
+        return yield unless PermissionForge::Audit.instrument?(EVENT)
+
+        @dropped = []
+        @path = []
+        result = yield
+        publish_dropped(reason) unless @dropped.empty?
+        result
+      end
+
+      def nil_user_report?
+        !resource_class.nil? && @permitted_params.present? && PermissionForge::Audit.instrument?(EVENT)
+      end
+
+      def publish_dropped(reason)
+        dropped = @dropped.uniq
+        record = @resource.is_a?(Class) ? nil : @resource
+        PermissionForge::Audit.instrument(EVENT) do
+          reference = record ? { record: record } : { record_type: PermissionForge::Audit::Runtime.record_type(resource_class) }
+          reference.merge(subject_user_id: PermissionForge::Audit::Runtime.user_id(@user),
+                          data: { 'model' => resource_class.name, 'reason' => reason, 'dropped' => dropped },
+                          objects: { user: @user, record: record })
+        end
+      end
+
+      # Records the dropped key's path, when dropped keys are collected. Nil,
+      # so that a dropped element leaves nothing in a filter_map.
+      def dropped(key)
+        @dropped&.push((@path + [key.to_s]).join('.'))
+        nil
+      end
+
+      def within(segment)
+        return yield unless @dropped
+
+        @path.push(segment.to_s)
+        begin
+          yield
+        ensure
+          @path.pop
+        end
+      end
+
+      def resource_class
+        return nil if @resource.nil?
+
+        @resource.is_a?(Class) ? @resource : @resource.class
+      end
+
+      # A NEW hash with the keys editable on `klass`, each nested payload
+      # filtered for its own model. Everything else is dropped (fail closed).
+      def filter_for(klass, params, record: false)
+        fields = editable_fields_for(klass)
+        result = {}
+
+        each_pair(params) do |key, value|
+          if (association = nested_association(klass, key))
+            filtered = within(key) { filter_nested(klass, association, value) }
+            filtered.nil? ? dropped(key) : result[key] = filtered
+          elsif fields.key?(key.to_sym) || (record && record_key?(klass, key))
+            result[key] = value
+          else
+            dropped(key)
+          end
+        end
+
+        result
+      end
+
+      # A key of a nested record that names it rather than sets a field —
+      # or its `_destroy`, when the user may delete records of `klass`.
+      def record_key?(klass, key)
+        name = key.to_s
+        RECORD_KEYS.include?(name) || (name == DESTROY_KEY && deletable?(klass))
+      end
+
+      # Whether the user may delete records of `klass`: the delete_access of
+      # the entry the class answers to (ResourceChain.grants?). Once per
+      # class and call.
+      def deletable?(klass)
+        @deletable ||= {}
+        @deletable.fetch(klass) do
+          @deletable[klass] = @user.respond_to?(:permissions_hash) &&
+                              PermissionForge::ResourceChain.grants?(@user, resource_names(klass), :delete_access)
+        end
+      end
+
+      # The association behind a `<assoc>_attributes` key, when `klass`
+      # accepts nested attributes for it. Any other key is a field.
+      def nested_association(klass, key)
+        name = key.to_s
+        return unless name.end_with?(NESTED_SUFFIX) && klass.respond_to?(:nested_attributes_options)
+
+        assoc_name = name.delete_suffix(NESTED_SUFFIX).to_sym
+        klass.reflect_on_association(assoc_name) if klass.nested_attributes_options.key?(assoc_name)
+      end
+
+      # The payload filtered for the model it is for, minus the records whose
+      # id names a row the child's row rules deny (NestedRecords) — or nil,
+      # the key dropped as a whole: no entry for that model, not a payload,
+      # or its one record denied.
+      def filter_nested(parent_klass, association, value)
+        child = association_class(association)
+        target = nested_target(parent_klass, child)
+        return unless target
+
+        filtered = filter_payload(target, association, value)
+        NestedRecords.new(child, collection: association.collection?).admit(filtered) { dropped(EACH) } unless filtered.nil?
+      end
+
+      # The model a nested payload is filtered for: the association's own,
+      # when the user's hash has an entry for it; the parent, only under
+      # config.nested_attributes_parent_fallback (a key editable on the
+      # parent then admits the same key on a child the user was never
+      # granted); nothing otherwise.
+      def nested_target(parent_klass, child)
+        return child if child && configured_resource?(child)
+
+        parent_klass if PermissionForge.configuration.nested_attributes_parent_fallback
+      end
+
+      # nil for a polymorphic association (no one model) or one whose model
+      # does not load: such a payload is dropped.
+      def association_class(association)
+        association.klass unless association.polymorphic?
+      rescue NameError
+        nil
+      end
+
+      def filter_payload(target, association, value)
+        return filter_record(target, value) unless association.collection?
+        return filter_each(target, value) if value.is_a?(Array)
+        return unless each_pair?(value)
+
+        # As Rails reads a collection Hash: one record when it has an id,
+        # otherwise the index form, whose values are the records.
+        record_with_id?(value) ? within(EACH) { filter_record(target, value) } : filter_indexed(target, value)
+      end
+
+      # One record (a has_one / belongs_to payload, or one of a collection),
+      # with one id (NestedRecords.with_one_id); nil when it is no record or
+      # names two ids.
+      def filter_record(target, value)
+        NestedRecords.with_one_id(filter_for(target, value, record: true)) if each_pair?(value)
+      end
+
+      def filter_each(target, records)
+        records.filter_map do |record|
+          filtered = within(EACH) { filter_record(target, record) }
+          filtered.nil? ? dropped(EACH) : filtered
+        end
+      end
+
+      def filter_indexed(target, records)
+        result = {}
+        each_pair(records) do |index, record|
+          filtered = within(EACH) { filter_record(target, record) }
+          filtered.nil? ? dropped(EACH) : result[index] = filtered
+        end
+        result
+      end
+
+      def record_with_id?(value)
+        value.key?('id') || value.key?(:id)
+      end
+
+      # The Resource names a model answers to: its own and its STI
+      # ancestors' (ResourceChain).
+      def resource_names(klass)
+        PermissionForge::ResourceChain.names(klass)
+      end
+
+      def configured_resource?(klass)
+        @user.respond_to?(:permissions_hash) && PermissionForge::ResourceChain.entries(@user, resource_names(klass)).any?
+      end
+
+      def editable_fields_for(klass)
+        return {} unless @user.respond_to?(:permissions_hash)
+
+        PermissionForge::ResourceChain.fields(@user, resource_names(klass)).select { |_, access| access[:edit_access] }
+      end
+
+      # Iterates key/value pairs of an ActionController::Parameters or a Hash.
+      def each_pair(params, &)
+        params.each_pair(&)
+      end
+
+      def each_pair?(value)
+        value.respond_to?(:each_pair)
+      end
+    end
+  end
+end

data/lib/permission_forge/services/resource_field_generator.rb

@@ -0,0 +1,93 @@
+module PermissionForge
+  module Services
+    # Creates a ResourceField for every column of a resource's model (and declared virtual fields
+    # under `extra_fields_default_access = :unconfigured`).
+    #
+    # @api public
+    class ResourceFieldGenerator
+      # @param resource [Resource]
+      # @param grant_all [Boolean] grant read and edit on the generated fields
+      # @return [Array<ResourceField>] the fields created
+      def self.call(resource:, grant_all: false)
+        new(resource: resource, grant_all: grant_all).call
+      end
+
+      def initialize(resource:, grant_all: false)
+        @resource = resource
+        @grant_all = grant_all
+      end
+
+      # All or nothing, under one audit correlation id (an enclosing block's,
+      # if any): a field that cannot be saved leaves no field and no event.
+      def call
+        model_class = @resource.name.safe_constantize
+        return [] unless model_class
+
+        fields = PermissionForge::Audit.correlate { PermissionForge::ResourceField.transaction { generate_fields(model_class) } }
+        PermissionForge.configuration.record_gdpr_pattern_checksum
+        fields
+      end
+
+      # A field needs a name: a blank one declared by the model is skipped
+      # (and logged) rather than failing "Add resource" / "Sync fields".
+      def self.without_blank_names(model_class, names)
+        usable = names.reject { |name| name.to_s.strip.empty? }
+        skipped = names.size - usable.size
+        if skipped.positive?
+          Rails.logger&.warn("[PermissionForge] skipped #{skipped} blank field name(s) declared by " \
+                             "#{model_class.name}.#{PermissionForge.configuration.extra_fields_method}")
+        end
+        usable
+      end
+
+      private
+
+      def generate_fields(model_class)
+        existing_names = @resource.resource_fields.pluck(:name)
+        columns = model_class.column_names - ignored_fields + virtual_field_names(model_class) - existing_names
+
+        columns.map do |column_name|
+          attrs = build_field_attrs(column_name)
+          apply_gdpr_defaults(attrs, column_name) if PermissionForge.configuration.gdpr_defaults
+          PermissionForge::ResourceField.create!(attrs)
+        end
+      end
+
+      def build_field_attrs(column_name)
+        {
+          resource: @resource,
+          name: column_name,
+          label: column_name.humanize,
+          is_active: true,
+          is_editable: true,
+          read_access: @grant_all,
+          edit_access: @grant_all
+        }
+      end
+
+      def ignored_fields
+        PermissionForge.configuration.ignored_fields
+      end
+
+      # Virtual fields get rows only under extra_fields_default_access =
+      # :unconfigured. Under :grant ExtraFieldDefaults already gives declared
+      # names read + edit, and a generated row (no access unless grant_all)
+      # would take that away from callers that rely on it.
+      def virtual_field_names(model_class)
+        configuration = PermissionForge.configuration
+        return [] if configuration.grant_extra_fields_by_default?
+
+        self.class.without_blank_names(model_class, PermissionForge::VirtualFields.new(model_class, configuration).names)
+      end
+
+      def apply_gdpr_defaults(attrs, column_name)
+        _pattern, strategy = PermissionForge.configuration.gdpr_field_patterns.find { |regex, _| column_name.match?(regex) }
+        return unless strategy
+
+        attrs[:read_access] = true
+        attrs[:mask_access] = true
+        attrs[:mask_strategy] = strategy
+      end
+    end
+  end
+end

data/lib/permission_forge/services/resource_with_fields_builder.rb

@@ -0,0 +1,47 @@
+module PermissionForge
+  module Services
+    # Creates a Resource with full CRUD access and its generated fields, all or nothing.
+    #
+    # @api public
+    class ResourceWithFieldsBuilder
+      # @param permission_set [PermissionSet]
+      # @param resource_name [String] the model name
+      # @return [Resource]
+      def self.call(permission_set:, resource_name:)
+        new(permission_set, resource_name).call
+      end
+
+      def initialize(permission_set, resource_name)
+        @permission_set = permission_set
+        @resource_name = resource_name
+      end
+
+      # The resource and its fields are created all or nothing, under one
+      # audit correlation id (an enclosing block's, if any).
+      def call
+        PermissionForge::Audit.correlate do
+          PermissionForge::Resource.transaction do
+            resource = create_resource
+            ResourceFieldGenerator.call(resource: resource, grant_all: true)
+            resource
+          end
+        end
+      end
+
+      private
+
+      def create_resource
+        PermissionForge::Resource.create!(
+          name: @resource_name,
+          permission_set: @permission_set,
+          read_access: true,
+          create_access: true,
+          edit_access: true,
+          delete_access: true,
+          is_active: true,
+          is_editable: true
+        )
+      end
+    end
+  end
+end