permission_forge 0.14.1

data/lib/permission_forge/services/expired_assignment_cleaner.rb

@@ -0,0 +1,152 @@
+module PermissionForge
+  module Services
+    # Removes expired PermissionSetUser records and invalidates the cached
+    # permissions of all affected users (rebuilt read-through on next access).
+    #
+    # @example
+    #   result = ExpiredAssignmentCleaner.call
+    #   # => { removed: 5, invalidated: 3 }
+    #
+    # `invalidated` counts the users whose invalidation the cache store
+    # confirmed; a failure is reported through `config.on_cache_failure`.
+    #
+    # @example Dry run (inspect without removing)
+    #   result = ExpiredAssignmentCleaner.call(dry_run: true)
+    #   # => { removed: 0, invalidated: 0, expired_count: 5, affected_user_ids: [1, 2, 3] }
+    #
+    # Each assignment is re-read, locked, when it is destroyed: one that was
+    # renewed (or removed) since the run selected it is left alone, and its
+    # `assignment.revoked` snapshot is the row as it was at that moment.
+    #
+    # The audit log: assignments are destroyed through their callbacks (one
+    # `assignment.revoked` each), then ONE `cleanup.expired_assignments` event
+    # names the sets and the counts — only when something was removed, so a
+    # nightly run over nothing leaves no noise. Its data holds the number of
+    # affected users and at most AFFECTED_USER_IDS_LIMIT of their ids
+    # (`affected_user_ids_truncated` says when there were more; each
+    # `assignment.revoked` names its own user). `actor:` (a user, an
+    # Audit::Actor or a label String) and `reason:` say who ran it and why;
+    # without a reason (none given, none in the context) the events carry
+    # DEFAULT_REASON. A dry run writes nothing.
+    #
+    # Tenants: with a tenant ambient, that tenant's assignments. With none
+    # (the rake task) every tenant's — also under acts_as_tenant's
+    # require_tenant — and the summary is written in each tenant that lost
+    # assignments (its counts) plus once without a tenant (the totals), each
+    # with `across_tenants: true` (Concerns::AcrossTenants).
+    #
+    # @api public
+    class ExpiredAssignmentCleaner
+      include Concerns::AuditedOperation
+      include Concerns::AcrossTenants
+
+      DEFAULT_REASON = 'expired'.freeze
+
+      # The most user ids the summary event stores: the event's data must
+      # stay well inside a MySQL TEXT column (64 KB) whatever the run's size.
+      AFFECTED_USER_IDS_LIMIT = 100
+
+      # Removes expired assignments and invalidates the affected users' cached permissions.
+      # @return [Hash] see {#call}
+      def self.call(...) = new(...).call
+
+      def initialize(dry_run: false, actor: nil, reason: nil)
+        @dry_run = dry_run
+        @actor = actor
+        @reason = reason
+        @removed_count = 0
+        @invalidated_count = 0
+      end
+
+      # @return [Hash] `{ removed:, invalidated: }` (plus `expired_count:` and `affected_user_ids:` for a dry run)
+      def call
+        across_tenants do
+          expired_records = PermissionForge::PermissionSetUser.expired
+          next dry_run_result(expired_records.count, expired_records.distinct.pluck(:user_id)) if @dry_run
+
+          audited(actor: @actor, reason: reason) { clean(expired_records.order(:id).pluck(:id)) }
+        end
+      end
+
+      private
+
+      def reason
+        return @reason if @reason.present? || PermissionForge::Audit::Context[:reason].present?
+
+        DEFAULT_REASON
+      end
+
+      def clean(candidate_ids)
+        removed = candidate_ids.filter_map { |id| destroy_if_still_expired(id) }
+        @removed_count = removed.size
+
+        confirmed = invalidate_users(removed.map(&:user_id).uniq)
+        @invalidated_count = confirmed.size
+        record_summary(removed, confirmed) if @removed_count.positive?
+
+        { removed: @removed_count, invalidated: @invalidated_count }
+      end
+
+      # The row as it is now, locked until it is gone; nil when it is no
+      # longer expired (renewed) or no longer there.
+      def destroy_if_still_expired(id)
+        PermissionForge::PermissionSetUser.transaction do
+          record = PermissionForge::PermissionSetUser.expired.lock.find_by(id: id)
+          record&.destroy
+        end
+      end
+
+      # One event, or one per tenant plus the totals (record_per_tenant),
+      # each with the counts of its own rows.
+      def record_summary(records, confirmed_user_ids)
+        sets = PermissionForge::PermissionSet.where(id: records.map(&:permission_set_id).uniq).index_by(&:id)
+        record_per_tenant('cleanup.expired_assignments', records) do |rows|
+          SummaryData.new(rows, sets, confirmed_user_ids).to_h
+        end
+      end
+
+      # The data of one cleanup.expired_assignments event, for the removed
+      # rows it covers.
+      #
+      # @api private
+      SummaryData = Struct.new(:rows, :sets_by_id, :confirmed_user_ids) do
+        def to_h
+          { 'operation' => 'cleanup_expired_assignments', 'removed' => rows.size,
+            'invalidated' => (user_ids & confirmed_user_ids).size, **bounded_user_ids,
+            'set_uuids' => sets.map(&:uuid).uniq, 'set_names' => sets.map(&:name).uniq, 'dry_run' => false }
+        end
+
+        private
+
+        def user_ids
+          @user_ids ||= rows.map(&:user_id).uniq
+        end
+
+        def sets
+          sets_by_id.values_at(*rows.map(&:permission_set_id).uniq.sort).compact
+        end
+
+        def bounded_user_ids
+          { 'affected_user_count' => user_ids.size,
+            'affected_user_ids' => user_ids.first(AFFECTED_USER_IDS_LIMIT).map(&:to_s),
+            'affected_user_ids_truncated' => user_ids.size > AFFECTED_USER_IDS_LIMIT }
+        end
+      end
+      private_constant :SummaryData
+
+      def dry_run_result(expired_count, affected_user_ids)
+        { removed: 0, invalidated: 0, expired_count: expired_count, affected_user_ids: affected_user_ids }
+      end
+
+      # @return [Array] the ids of the users whose invalidation the store
+      #   confirmed — not what a host's override of the method returns
+      def invalidate_users(user_ids)
+        confirmed = []
+        PermissionForge.configuration.user_model.where(id: user_ids).find_each do |user|
+          confirmed << user.id if PermissionForge::Cache::Failure.none? { user.invalidate_permissions }
+        end
+        confirmed
+      end
+    end
+  end
+end

data/lib/permission_forge/services/extra_field_defaults.rb

@@ -0,0 +1,71 @@
+module PermissionForge
+  module Services
+    # Gives a model's declared extra (virtual) fields their implicit entry when
+    # nothing configured them: readable when the resource grants read,
+    # editable when it grants edit, never masked.
+    #
+    # Strictly ADDITIVE: a name that already has an entry (a ResourceField row,
+    # or a variant of one) is left untouched, so an extra field can never
+    # unmask or grant edit on a field an admin configured. PermissionHashBuilder
+    # calls this once per resource, after every granting set is merged, so a
+    # row in ANY of the user's sets wins whatever order the sets are in, and
+    # the resource flags it follows are the merged ones (edit from any set).
+    #
+    # Only names the model declares through extra_fields_method are read, and
+    # only under extra_fields_default_access = :grant. Under :unconfigured
+    # nothing is added: the field follows unconfigured_field_strategy, like a
+    # column. Names the admin merely discovers never get an entry here.
+    #
+    # An error raised by the host's extra_fields_method is not rescued: a
+    # broken method must fail the build of the hash, not quietly change it.
+    #
+    # @api private
+    class ExtraFieldDefaults
+      # The entry's mask part: an implicit entry is never masked.
+      UNMASKED = { mask_access: false, mask_strategy: 'full' }.freeze
+
+      # @param entry [Hash] the resource's entry in the hash being built:
+      #   its :fields (written in place) and its merged :permissions
+      # @return [Hash] the fields, with implicit entries added
+      def self.call(entry:, resource_name:, configuration: PermissionForge.configuration)
+        new(entry:, resource_name:, configuration:).call
+      end
+
+      # The implicit entry for a resource with the given merged permissions.
+      # Only an exact `true` grants: the entry used to be read + edit for
+      # everyone who could read the resource, so a read-only user could write
+      # a declared virtual field (before 0.14).
+      #
+      # @param permissions [Hash] the resource's merged :permissions
+      # @return [Hash] a new entry
+      def self.implicit_entry(permissions)
+        { read_access: permissions[:read_access] == true, edit_access: permissions[:edit_access] == true, **UNMASKED }
+      end
+
+      def initialize(entry:, resource_name:, configuration:)
+        @fields = entry.fetch(:fields)
+        @permissions = entry.fetch(:permissions)
+        @resource_name = resource_name.to_s
+        @configuration = configuration
+      end
+
+      # @return [Hash] the fields hash, with implicit entries added
+      def call
+        declared_names.each { |name| @fields[name] ||= self.class.implicit_entry(@permissions) }
+        @fields
+      end
+
+      private
+
+      # @fields is String-keyed until the cache symbolizes it. A Symbol name
+      # would miss the collision check, sit beside the configured String key,
+      # and replace it once both become Symbols — so VirtualFields.extra_names
+      # returns Strings.
+      def declared_names
+        return [] unless @configuration.grant_extra_fields_by_default?
+
+        PermissionForge::VirtualFields.extra_names(@resource_name.safe_constantize, @configuration)
+      end
+    end
+  end
+end

data/lib/permission_forge/services/field_permission_merger.rb

@@ -0,0 +1,83 @@
+module PermissionForge
+  module Services
+    # Merges the active ResourceField rows of one resource into a fields hash.
+    # Extracted from PermissionHashBuilder for SRP, which calls it once per
+    # granting set.
+    #
+    # Rows only: the implicit entries for a model's extra (virtual) fields are
+    # added by ExtraFieldDefaults, once per resource, after every set is merged.
+    #
+    # {.merge_row} is the one definition of merging a row into an entry; the
+    # admin's Admin::EffectiveFields explains fields with it.
+    #
+    # @api private
+    class FieldPermissionMerger
+      FIELD_PERMISSION_OPTIONS = %i[read_access edit_access].freeze
+      FIELD_MASK_OPTIONS = %i[mask_access mask_strategy].freeze
+      # The mask of an entry no row that grants read has decided yet.
+      DEFAULT_MASK_STRATEGY = 'full'.freeze
+
+      def self.call(...) = new(...).call
+
+      # Merges one row into one entry, across granting sets:
+      # - read and edit are OR-ed (any set that grants wins);
+      # - the mask is decided by the rows that GRANT READ alone: AND-ed (any
+      #   such set that unmasks wins), with the first such row's strategy.
+      #   A row that grants no read (the admin UI's Hidden: read=f, mask=f)
+      #   never votes — it used to take part in the AND, so Masked in one set
+      #   plus Hidden in another read as plaintext, in either order.
+      # The four keys are always present (the hash format is a contract).
+      #
+      # @param entry [Hash] the field's entry so far, written in place
+      # @param field [ResourceField, #read_access] the row
+      # @return [Hash] the entry
+      def self.merge_row(entry, field)
+        # A row that granted read has merged the mask already: read_access is
+        # OR-ed, so it is true from that row on and never before.
+        decided = entry[:read_access] == true
+        FIELD_PERMISSION_OPTIONS.each { |action| entry[action] ||= field.public_send(action) }
+        merge_mask(entry, field, decided)
+        entry
+      end
+
+      def self.merge_mask(entry, field, decided)
+        unless field.read_access
+          entry[:mask_access] = false unless entry.key?(:mask_access)
+          entry[:mask_strategy] ||= DEFAULT_MASK_STRATEGY
+          return
+        end
+
+        entry[:mask_access] = decided ? entry[:mask_access] && field.mask_access : field.mask_access
+        entry[:mask_strategy] = field.mask_strategy unless decided
+      end
+      private_class_method :merge_mask
+
+      def initialize(fields:, resource:, configuration: PermissionForge.configuration)
+        @fields = fields
+        @resource = resource
+        @configuration = configuration
+      end
+
+      def call
+        @resource.resource_fields.select(&:is_active).each do |field|
+          next unless field.is_active
+
+          compute_field_variants(field.name).each { |variant| set_field_permissions(variant, field) }
+          set_field_permissions(field.name, field)
+        end
+
+        @fields
+      end
+
+      private
+
+      def compute_field_variants(field_name)
+        @configuration.field_variants_for(field_name)
+      end
+
+      def set_field_permissions(field_name, field)
+        self.class.merge_row(@fields[field_name] ||= {}, field)
+      end
+    end
+  end
+end

data/lib/permission_forge/services/filters_response_attributes.rb

@@ -0,0 +1,144 @@
+module PermissionForge
+  module Services
+    # Filters and masks response attributes based on the current user's field permissions.
+    # Fields without read access are removed; fields with mask_access are masked using MaskValue.
+    #
+    # Fail-closed posture: when a user is present but has NO field permissions for
+    # the resource (unmapped resource, cache re-entrancy), every attribute is treated
+    # as unconfigured and routed through `unconfigured_field_strategy` (default :block),
+    # so an authenticated user never receives raw fields for a resource they lack
+    # configured access to. The nil-user case follows `response_filter_nil_user_strategy`.
+    #
+    # Each call is one read for the field.access audit event
+    # (Audit::FieldAccess): the record is named by the resource and the hash's
+    # `id`, the hidden, masked and unconfigured keys are listed, and the
+    # legacy on_field_filtered hook is called for every configured key, as
+    # before.
+    #
+    # @example
+    #   filtered = FiltersResponseAttributes.call(
+    #     attributes: { name: 'John', email: 'john@example.com' },
+    #     resource_name: 'Customer'
+    #   )
+    #
+    # @api public
+    class FiltersResponseAttributes
+      # Filters a response hash by the user's field-level read access (does not mutate it).
+      # @param attributes [Hash]
+      # @param resource_name [String] the model name the fields belong to
+      # @param user [Object, nil] defaults to the current user
+      # @return [Hash]
+      def self.call(attributes:, resource_name:, user: nil)
+        new(attributes: attributes, resource_name: resource_name, user: user).call
+      end
+
+      def initialize(attributes:, resource_name:, user: nil)
+        @attributes = attributes
+        @resource_name = resource_name.to_s
+        @user = user || PermissionForge.current_user
+      end
+
+      # @return [Hash] a new hash without the fields the user may not read, masked where required
+      def call
+        PermissionForge::Audit::FieldAccess.read(@attributes, @resource_name, record_id: record_id) do |frame|
+          @frame = frame
+          next handle_nil_user if @user.blank?
+
+          # No early return on blank field_permissions: an authenticated user with no
+          # configured access to the resource must still be filtered (fail closed),
+          # not handed the raw attributes.
+          filter_and_mask
+        end
+      end
+
+      UNCONFIGURED_FIELD_STRATEGIES = {
+        pass_through: ->(_resource_name, _key, value) { [true, value] },
+        warn: lambda { |resource_name, key, value|
+          Rails.logger.warn("PermissionForge: unconfigured field '#{key}' on #{resource_name} passed through unmasked")
+          [true, value]
+        },
+        mask_all: ->(_resource_name, _key, value) { [true, MaskValue.call(value, strategy: 'full')] },
+        block: ->(_resource_name, _key, _value) { [false, nil] }
+      }.freeze
+
+      private
+
+      # When there is no current user we cannot evaluate permissions. The behavior
+      # is explicit and configurable via `response_filter_nil_user_strategy`:
+      #   :bypass — return raw attributes (system/console context; default, backward-compatible)
+      #   :block  — return {} (strict fail-closed)
+      def handle_nil_user
+        if PermissionForge.configuration.response_filter_nil_user_strategy == :block
+          note_all(:hidden)
+          {}
+        else
+          note_all(:bypassed)
+          @attributes
+        end
+      end
+
+      # Without a user every key is decided the same way (the hook was never
+      # called for these).
+      def note_all(action)
+        @attributes.each_key { |key| @frame.add(@resource_name, key, action, nil, hook: false) } if @frame
+      end
+
+      # The id in the hash, when it has one (the hash's own key, not a reader).
+      def record_id
+        return unless @attributes.respond_to?(:key?)
+
+        @attributes.key?(:id) ? @attributes[:id] : @attributes['id']
+      end
+
+      def filter_and_mask
+        @result = {}
+        @attributes.each { |key, value| process_field(key, value) }
+        @result
+      end
+
+      def process_field(key, value)
+        field = field_permissions[key.to_sym]
+
+        if field.nil?
+          include_field, masked_value = handle_unconfigured_field(key, value)
+          @result[key] = masked_value if include_field
+          @frame&.add(@resource_name, key, :unconfigured, @user, hook: false)
+        else
+          apply_configured_field(key, value, field)
+        end
+      end
+
+      def apply_configured_field(key, value, field)
+        unless field[:read_access]
+          notify_field_filtered(key, :hidden)
+          return
+        end
+
+        if field[:mask_access]
+          @result[key] = MaskValue.call(value, strategy: field[:mask_strategy] || 'full')
+          notify_field_filtered(key, :masked)
+        else
+          @result[key] = value
+          notify_field_filtered(key, :passed)
+        end
+      end
+
+      def notify_field_filtered(field_name, action)
+        @frame&.add(@resource_name, field_name, action, @user)
+      end
+
+      def handle_unconfigured_field(key, value)
+        strategy_key = PermissionForge.configuration.unconfigured_field_strategy
+        # Unknown strategy keys fall back to :block (fail closed), never pass-through.
+        strategy = UNCONFIGURED_FIELD_STRATEGIES.fetch(strategy_key, UNCONFIGURED_FIELD_STRATEGIES[:block])
+        strategy.call(@resource_name, key, value)
+      end
+
+      # The user's field entries for the resource: those of the model the
+      # name names and of its STI ancestors (ResourceChain); {} without any.
+      def field_permissions
+        @field_permissions ||= PermissionForge::ResourceChain.fields(@user, PermissionForge::ResourceChain.names_for(@resource_name))
+      end
+    end
+  end
+end

data/lib/permission_forge/services/gdpr_field_auditor/text_report.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    class GdprFieldAuditor
+      # Plain-text rendering of a GdprFieldAuditor report for terminals and
+      # logs. One line per finding, whatever its type, so the count in the
+      # header is the number of lines below it.
+      #
+      # @api private
+      class TextReport
+        CLEAN = 'All GDPR-sensitive fields are properly masked.'
+
+        LINES = {
+          unmasked_field: lambda { |finding|
+            "[UNMASKED] #{finding[:resource_name]}.#{finding[:field_name]} " \
+              "— matches pattern '#{finding[:suggested_strategy]}'"
+          },
+          unmapped_column: lambda { |finding|
+            "[UNMAPPED] #{finding[:resource]}.#{finding[:column]} " \
+              "— matches pattern '#{finding[:pattern_matched]}', no active ResourceField"
+          },
+          implicit_virtual_grant: lambda { |finding|
+            "[VIRTUAL] #{finding[:permission_set]} › #{finding[:resource_name]}.#{finding[:field_name]} " \
+              "— matches a GDPR pattern (suggested mask: '#{finding[:suggested_strategy]}'), " \
+              'no active ResourceField, readable and editable by default'
+          },
+          view_all_on_pii_resource: lambda { |finding|
+            "[VIEW ALL] #{finding[:permission_set]} › #{finding[:resource_name]} " \
+              "— #{finding[:bypasses].join(' + ')} skips row-level rules; GDPR-sensitive fields " \
+              "on this resource: #{finding[:pii_fields].join(', ')}"
+          },
+          cross_set_unmasking: lambda { |finding|
+            "[OVERRIDES MASK] #{finding[:permission_set]} › #{finding[:resource_name]}.#{finding[:field_name]} " \
+              '— unmasked here, masked in another Permission Set; a person in both sees the full value'
+          }
+        }.freeze
+
+        # A finding type added to the auditor without a line here still prints.
+        FALLBACK = lambda { |finding|
+          "[#{finding[:type].to_s.upcase.tr('_', ' ')}] " \
+            "#{finding.except(:type).map { |key, value| "#{key}: #{value}" }.join(', ')}"
+        }
+
+        def initialize(report)
+          @report = report
+        end
+
+        def to_s
+          return CLEAN if @report.empty?
+
+          ["GDPR audit found #{@report.size} issue(s):", *@report.map { |finding| "  #{line(finding)}" }].join("\n")
+        end
+
+        private
+
+        def line(finding)
+          LINES.fetch(finding[:type], FALLBACK).call(finding)
+        end
+      end
+    end
+  end
+end