permission_forge 0.14.1

data/lib/permission_forge/services/gdpr_field_auditor.rb

@@ -0,0 +1,223 @@
+require_relative 'gdpr_field_auditor/text_report'
+
+module PermissionForge
+  module Services
+    # Reports fields that look like personal data and are neither masked nor mapped. It reports and never changes anything.
+    #
+    # @api public
+    class GdprFieldAuditor
+      # @param configuration [Configuration]
+      # @return [Array<Hash>] one entry per finding
+      def self.call(configuration: PermissionForge.configuration)
+        new(configuration: configuration).call
+      end
+
+      def initialize(configuration: PermissionForge.configuration)
+        @configuration = configuration
+      end
+
+      # @return [Array<Hash>] one entry per finding
+      def call
+        report = []
+        audit_unmasked_fields(report)
+        audit_unmapped_columns(report)
+        audit_implicit_virtual_grants(report)
+        audit_view_all_on_pii_resources(report)
+        audit_cross_set_unmasking(report)
+        report
+      end
+
+      private
+
+      # Field rows that reach someone's permission hash: in effect, in a
+      # granting Permission Set. Every check reads rows through here, so a row
+      # the engine skips (switched off, or in a switched-off resource or set,
+      # or in a muting set) is never reported as both "unmasked" and "unmapped".
+      def granting_fields
+        PermissionForge::ResourceField.in_effect.merge(PermissionForge::PermissionSet.granting)
+      end
+
+      def audit_unmasked_fields(report)
+        granting_fields.where(mask_access: false).preload(resource: :permission_set).find_each do |field|
+          report << unmasked_finding(field) if gdpr_field?(field.name)
+        end
+      end
+
+      def unmasked_finding(field)
+        resource = field.resource
+        { type: :unmasked_field, resource_field_id: field.id, field_name: field.name, resource_name: resource.name,
+          suggested_strategy: gdpr_strategy(field.name), permission_set: resource.permission_set.name }
+      end
+
+      def audit_unmapped_columns(report)
+        PermissionForge::Resource.distinct.pluck(:name).each do |resource_name|
+          audit_unmapped_for_resource(report, resource_name)
+        end
+      rescue ActiveRecord::StatementInvalid
+        # Tables don't exist yet (pre-migration)
+      end
+
+      def audit_unmapped_for_resource(report, resource_name)
+        columns = model_columns_for(resource_name)
+        return unless columns
+
+        virtual = unmapped_virtual_names_for(resource_name)
+        mapped_names = mapped_field_names_for(resource_name)
+        (columns + virtual - mapped_names).each do |column_name|
+          match = gdpr_patterns.find { |regex, _| column_name.match?(regex) }
+          next unless match
+
+          finding = { type: :unmapped_column, resource: resource_name, column: column_name, pattern_matched: match[1] }
+          report << (virtual.include?(column_name) ? finding.merge(virtual: true) : finding)
+        end
+      end
+
+      # Virtual fields that follow unconfigured_field_strategy when nobody
+      # configured them. Implicitly granted ones are reported per Permission
+      # Set by audit_implicit_virtual_grants instead.
+      def unmapped_virtual_names_for(resource_name)
+        fields = virtual_fields(resource_name)
+        return [] unless fields
+
+        fields.names.reject { |name| fields.implicit_grant?(name) }
+      end
+
+      # Declared virtual fields that look like personal data and have no active
+      # field row in a granting resource: under extra_fields_default_access =
+      # :grant that set gives its people read and edit on them, unmasked.
+      def audit_implicit_virtual_grants(report)
+        return unless @configuration.grant_extra_fields_by_default?
+
+        granting_resources.each { |resource| report.concat(implicit_virtual_grants_in(resource)) }
+      rescue ActiveRecord::StatementInvalid
+        # Tables don't exist yet (pre-migration)
+      end
+
+      # A switched-off row counts as no row, because the engine skips it.
+      def implicit_virtual_grants_in(resource)
+        configured = resource.resource_fields.select(&:is_active).map(&:name)
+        implicit_pii_fields(resource.name).filter_map do |name, strategy|
+          next if configured.include?(name)
+
+          { type: :implicit_virtual_grant, resource_name: resource.name, field_name: name,
+            suggested_strategy: strategy, permission_set: resource.permission_set.name }
+        end
+      end
+
+      def granting_resources
+        granting_sets = PermissionForge::PermissionSet.active.granting.select(:id)
+        PermissionForge::Resource.active.where(read_access: true, permission_set_id: granting_sets)
+                                 .includes(:permission_set, :resource_fields)
+      end
+
+      # [[name, suggested strategy]] for the model's implicitly granted names
+      # that match a GDPR pattern. Names in ignored_fields are left out: the
+      # admin does not manage those.
+      def implicit_pii_fields(resource_name)
+        @implicit_pii_fields ||= {}
+        @implicit_pii_fields[resource_name] ||= begin
+          names = Array(virtual_fields(resource_name)&.implicit).uniq - Array(@configuration.ignored_fields).map(&:to_s)
+          names.filter_map { |name| [name, gdpr_strategy(name)] if gdpr_field?(name) }
+        end
+      end
+
+      # @return [PermissionForge::VirtualFields, nil] nil when the resource
+      #   names no model whose columns can be read.
+      def virtual_fields(resource_name)
+        @virtual_fields ||= {}
+        @virtual_fields.fetch(resource_name) do
+          @virtual_fields[resource_name] = build_virtual_fields(resource_name)
+        end
+      end
+
+      def build_virtual_fields(resource_name)
+        return unless model_columns_for(resource_name)
+
+        PermissionForge::VirtualFields.new(resource_name.safe_constantize, @configuration)
+      end
+
+      def model_columns_for(resource_name)
+        model_class = resource_name.safe_constantize
+        return unless model_class
+        return unless model_class.respond_to?(:column_names)
+
+        model_class.column_names
+      rescue ActiveRecord::StatementInvalid
+        nil
+      end
+
+      # Names with a field row in effect in any granting Permission Set. A row
+      # the engine skips counts as no row.
+      def mapped_field_names_for(resource_name)
+        granting_fields.merge(PermissionForge::Resource.where(name: resource_name)).distinct.pluck(:name)
+      end
+
+      def audit_view_all_on_pii_resources(report)
+        resources_with_bypass.find_each do |resource|
+          pii_fields = resource.resource_fields.select { |field| gdpr_field?(field.name) }
+          next if pii_fields.empty?
+
+          report << build_view_all_finding(resource, pii_fields)
+        end
+      rescue ActiveRecord::StatementInvalid
+        # Tables don't exist yet (pre-migration)
+      end
+
+      # Resources in effect in a granting Permission Set. In a muting set
+      # view_all takes the bypass away, and a switched-off row gives nothing.
+      def resources_with_bypass
+        resources = PermissionForge::Resource.arel_table
+        PermissionForge::Resource.in_effect.merge(PermissionForge::PermissionSet.granting)
+                                 .where(resources[:view_all].eq(true).or(resources[:modify_all].eq(true)))
+      end
+
+      def build_view_all_finding(resource, pii_fields)
+        bypasses = []
+        bypasses << 'view_all' if resource.view_all
+        bypasses << 'modify_all' if resource.modify_all
+
+        { type: :view_all_on_pii_resource, resource_name: resource.name,
+          permission_set: resource.permission_set.name, bypasses: bypasses,
+          pii_fields: pii_fields.map(&:name) }
+      end
+
+      # Masks combine with AND, so an unmasked row wins over a masked row of
+      # the same field of the same resource in another Permission Set.
+      def audit_cross_set_unmasking(report)
+        masking_sets = sets_masking_pii_fields
+        granting_fields.where(mask_access: false).preload(resource: :permission_set).find_each do |field|
+          resource = field.resource
+          masked_elsewhere = masking_sets.fetch([resource.name, field.name], []) - [resource.permission_set_id]
+          report << cross_set_finding(resource, field.name) if masked_elsewhere.any?
+        end
+      rescue ActiveRecord::StatementInvalid
+        # Tables don't exist yet (pre-migration)
+      end
+
+      def cross_set_finding(resource, field_name)
+        { type: :cross_set_unmasking, field_name: field_name, resource_name: resource.name,
+          permission_set: resource.permission_set.name }
+      end
+
+      # { [resource name, field name] => ids of the granting sets that mask it }
+      def sets_masking_pii_fields
+        masked = granting_fields.where(mask_access: true).preload(:resource).select { |field| gdpr_field?(field.name) }
+        masked.each_with_object({}) do |field, sets|
+          (sets[[field.resource.name, field.name]] ||= []) << field.resource.permission_set_id
+        end
+      end
+
+      def gdpr_field?(name)
+        gdpr_patterns.any? { |regex, _| name.match?(regex) }
+      end
+
+      def gdpr_strategy(name)
+        gdpr_patterns.find { |regex, _| name.match?(regex) }&.last
+      end
+
+      def gdpr_patterns
+        @configuration.gdpr_field_patterns
+      end
+    end
+  end
+end

data/lib/permission_forge/services/host_key_guard.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    # Refuses to read permissions or write assignments when a column that
+    # stores a host primary key cannot hold it.
+    #
+    # An integer column silently truncates a UUID or string key to its leading
+    # digits ('1aaa…' and '1bbb…' both become 1), so different users would
+    # share permission sets and different tenants would share permission data.
+    # The install generator types these columns from the host models; this
+    # guard covers installs where it could not, or that predate it.
+    #
+    # Checked lazily where the truncation would bite (PermissionCacheAccessor,
+    # the two assignment models) rather than at boot, so `db:migrate` can still
+    # run to repair an affected schema. A passing check is remembered until the
+    # configuration it depends on changes.
+    #
+    # @api private
+    class HostKeyGuard
+      Mismatch = Struct.new(:table, :column, :column_type, :host, :key_type) do
+        def to_s
+          "#{table}.#{column} is #{column_type} but #{host}'s primary key is #{key_type}"
+        end
+      end
+
+      class << self
+        # @return [true]
+        # @raise [PermissionForge::ConfigurationError] when a host key would be truncated
+        def verify!
+          signature = configuration_signature
+          return true if @verified == signature
+
+          found = mismatches
+          raise PermissionForge::ConfigurationError, message(found) if found.any?
+
+          @verified = signature
+          true
+        rescue ActiveRecord::StatementInvalid, ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished
+          true # schema not readable yet (before the install migration); not remembered
+        end
+
+        def reset!
+          @verified = nil
+        end
+
+        # @return [Array<Mismatch>] columns that would truncate the key they store
+        def mismatches
+          key_columns.filter_map { |model, column, host_name| mismatch(model, column, host_name) }
+        end
+
+        private
+
+        def configuration_signature
+          config = PermissionForge.configuration
+          [config.user_class, config.table_name_prefix, config.tenant_model, config.tenant_column]
+        end
+
+        # [model, column, host class name] for every column holding a host key
+        # that an authorization decision depends on.
+        def key_columns
+          config = PermissionForge.configuration
+          user_class = config.user_class
+          columns = [[PermissionForge::PermissionSetUser, 'user_id', user_class],
+                     [PermissionForge::PermissionSetGroupUser, 'user_id', user_class]]
+          return columns unless config.tenant_enabled?
+
+          tenant_column = config.resolved_tenant_column.to_s
+          columns + tenant_scoped_models.map { |model| [model, tenant_column, config.tenant_model] }
+        end
+
+        # The audit log is tenant-scoped as well (a truncated tenant id would
+        # show one tenant another's events); it is checked only once its table
+        # exists, so an install that has not run the upgrade yet keeps the
+        # rest of the check.
+        def tenant_scoped_models
+          models = [PermissionForge::PermissionSet, PermissionForge::PermissionSetUser,
+                    PermissionForge::PermissionSetGroup, PermissionForge::PermissionSetGroupUser,
+                    PermissionForge::Resource, PermissionForge::ResourceField,
+                    PermissionForge::ResourceAction, PermissionForge::PermissionSetRule]
+          PermissionForge::AuditEvent.table_exists? ? models + [PermissionForge::AuditEvent] : models
+        end
+
+        def mismatch(model, column, host_name)
+          host = host_name.to_s.safe_constantize
+          key_type = primary_key_type(host)
+          column_type = model.columns_hash[column]&.type
+          return unless column_type == :integer && key_type && key_type != :integer
+
+          Mismatch.new(model.table_name, column, column_type, host.name, key_type)
+        end
+
+        # nil for a missing model or a composite primary key (not checked).
+        def primary_key_type(host)
+          return unless host.respond_to?(:columns_hash)
+
+          key = host.primary_key
+          host.columns_hash[key]&.type if key.is_a?(String)
+        end
+
+        def message(found)
+          "PermissionForge columns cannot hold the host primary keys they store: #{found.join('; ')}. " \
+            'An integer column truncates a UUID or string key to its leading digits, so different users ' \
+            '(or tenants) would share permission data. Change these columns to the type of the key and ' \
+            're-create the affected rows; see "UUID or string keys" in docs/migration-guide.md.'
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/services/mask_value.rb

@@ -0,0 +1,93 @@
+module PermissionForge
+  # The service objects hosts call (`Service.call(...)`): assignment, erasure, filtering, auditing and cloning.
+  # Each public service documents its arguments and result; helpers under this namespace are `@api private`.
+  #
+  # @api public
+  module Services
+    # WARNING: These strategies provide display-level obfuscation only.
+    # They do NOT constitute GDPR-compliant anonymization or pseudonymization.
+    # See docs/gdpr_masking_disclaimer.md for details.
+    #
+    # @api public
+    class MaskValue
+      BUILT_IN_STRATEGIES = {
+        'full' => :mask_full,
+        'email' => :mask_email,
+        'last4' => :mask_last4,
+        'first1_last4' => :mask_first1_last4
+      }.freeze
+
+      STRATEGIES = BUILT_IN_STRATEGIES.keys.freeze
+      MASK_CHAR = '*'.freeze
+
+      # @return [Hash{String => #call}] the built-in strategies merged with `config.custom_mask_strategies`
+      def self.strategies
+        custom = PermissionForge.configuration.custom_mask_strategies
+        return BUILT_IN_STRATEGIES if custom.blank?
+
+        BUILT_IN_STRATEGIES.merge(custom)
+      end
+
+      # Masks a value with a built-in or custom strategy.
+      # @param value [Object]
+      # @param strategy [String] `full`, `email`, `last4`, `first1_last4` or a custom one
+      # @return [Object] the masked value (nil stays nil)
+      def self.call(value, strategy: 'full')
+        return value if value.nil?
+
+        str = value.to_s
+        return str if str.empty?
+
+        new(str, strategy).call
+      end
+
+      def initialize(value, strategy)
+        @value = value
+        @strategy = strategy
+        all_strategies = self.class.strategies
+        return if all_strategies.key?(@strategy)
+
+        raise ArgumentError,
+              "Unknown mask strategy: #{strategy.inspect}. Valid strategies: #{all_strategies.keys.join(', ')}"
+      end
+
+      # @return [Object] the masked value
+      def call
+        all_strategies = self.class.strategies
+        strategy_ref = all_strategies[@strategy]
+
+        if strategy_ref.is_a?(Symbol)
+          send(strategy_ref)
+        else
+          strategy_ref.call(@value)
+        end
+      end
+
+      private
+
+      def mask_full
+        MASK_CHAR * 8
+      end
+
+      def mask_email
+        return mask_full unless @value.include?('@')
+
+        local, domain = @value.split('@', 2)
+        masked_local = local.length > 1 ? "#{local[0]}#{MASK_CHAR * 3}" : MASK_CHAR
+        "#{masked_local}@#{domain}"
+      end
+
+      def mask_last4
+        return mask_full if @value.length <= 4
+
+        "#{MASK_CHAR * (@value.length - 4)}#{@value[-4..]}"
+      end
+
+      def mask_first1_last4
+        return mask_full if @value.length <= 5
+
+        "#{@value[0]}#{MASK_CHAR * (@value.length - 5)}#{@value[-4..]}"
+      end
+    end
+  end
+end

data/lib/permission_forge/services/permission_cache_clearer.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    # Removes every cached permission hash — this version's entries, the
+    # previous versions' (Cache::UserKeys.namespaces), and the per-context
+    # variants — for every user, in every tenant. The step to run once the
+    # last process of the previous release is gone (0.14: an invalidation
+    # made by 0.13 cannot reach this version's entries, and one made after
+    # the clear would miss them again), and the way to revoke everything
+    # cached at once. Every user then rebuilds on their next request: a cold
+    # cache, one rebuild each. Two strategies, the first that works:
+    #
+    #   :pattern — the store removes keys by pattern (Redis, memory and file
+    #     stores: Cache::Base#clear_entries): one call per namespace, nothing
+    #     enumerated. How many users or tenants that reached is not known
+    #     (the result and the events say so). On a Redis store the
+    #     invalidation stamps go with the bare keys — a rebuild writes a new
+    #     one, one in flight is not kept.
+    #   :enumerated — otherwise (Memcached, Solid Cache): every id of the
+    #     user model, in slices of Cache::HolderInvalidation::SLICE, through
+    #     the bulk invalidation (one stamp write and one removal per slice),
+    #     or through each user's own invalidate_permissions where the bulk
+    #     path must not be used (HolderInvalidation.by_id?: a host override,
+    #     a listener, a snapshot transaction); then the per-context variants
+    #     an invalidation leaves (Cache::VariantRemoval: one read of the
+    #     slice's index entries, and a stamp write and a removal for the
+    #     users who had a variant stored). With tenancy on: once per tenant of the
+    #     tenant model, the users as the host scopes them under that tenant
+    #     (a user model that is not tenant-scoped is visited under every
+    #     tenant: users × tenants), and once more without a tenant for the
+    #     tenant-agnostic keys and users of no tenant. A user a host default
+    #     scope hides under a tenant keeps that tenant's key until cache_ttl.
+    #
+    # @example
+    #   result = PermissionCacheClearer.call(actor: 'ops: TCK-12', reason: 'deploy 0.14')
+    #   # => { strategy: :enumerated, users: 240, tenants: 2, unconfirmed: 0 }
+    #   # => { strategy: :pattern, users: nil, tenants: 2, unconfirmed: 0 }
+    #
+    # `users` counts visits (a user once per tenant); `unconfirmed` the ones
+    # the cache store did not confirm (each also reported through
+    # `config.on_cache_failure`, and owed). The audit log: one `cache.cleared`
+    # event per tenant, in that tenant with that tenant's counts, plus one
+    # without a tenant with the totals (`across_tenants`); under :pattern
+    # the counts are not known and the events say `counted: false`.
+    # `actor:` and `reason:` as the other housekeeping services (rake:
+    # ACTOR=, REASON=).
+    #
+    # @api public
+    class PermissionCacheClearer
+      include Concerns::AuditedOperation
+
+      EVENT = 'cache.cleared'
+      SLICE = Cache::HolderInvalidation::SLICE
+
+      # Clears every cached permission hash (see the class comment).
+      #
+      # @param actor [Object, nil] who runs it, for the cache.cleared events
+      # @param reason [String, nil] why
+      # @return [Hash] strategy:, users:, tenants:, unconfirmed:
+      def self.call(...) = new(...).call
+
+      def initialize(actor: nil, reason: nil)
+        @actor = actor
+        @reason = reason
+      end
+
+      # @return [Hash] strategy:, users:, tenants:, unconfirmed:
+      def call
+        audited(actor: @actor, reason: @reason) { clear }
+      end
+
+      private
+
+      def clear
+        result = clear_by_pattern || clear_by_enumeration
+        # retire every memo in this process, as an invalidation does
+        PermissionForge.bump_permissions_cache_version!
+        result
+      end
+
+      # @return [Hash, nil] nil when the store cannot remove by pattern
+      def clear_by_pattern
+        cache = PermissionForge.cache
+        return unless Cache::UserKeys.namespaces.all? { |namespace| cache.clear_entries(namespace) }
+
+        tenant_ids = tenants.map(&:id)
+        tenant_ids.each { |tenant_id| record(tenant_id, strategy: :pattern, counted: false, unconfirmed: 0) }
+        record_without_tenant(strategy: :pattern, counted: false, unconfirmed: 0, tenants: tenant_ids.size)
+        { strategy: :pattern, users: nil, tenants: tenant_ids.size, unconfirmed: 0 }
+      end
+
+      def clear_by_enumeration
+        totals = { strategy: :enumerated, users: 0, tenants: 0, unconfirmed: 0 }
+        tenants.each { |tenant| add_counts(totals, clear_tenant(tenant), tenants: 1) }
+        add_counts(totals, without_tenant { invalidate_everyone(nil) })
+        record_without_tenant(**totals)
+        totals
+      end
+
+      # One tenant's users, under that tenant, and its event.
+      def clear_tenant(tenant)
+        counts = PermissionForge.with_ambient_tenant(tenant) { invalidate_everyone(tenant.id) }
+        record(tenant.id, strategy: :enumerated, **counts)
+        counts
+      end
+
+      def add_counts(totals, counts, **more)
+        totals.merge!(counts, more) { |_key, total, count| total + count }
+      end
+
+      # Every user the model lists here, in slices, by id where that is
+      # allowed and through each user's invalidate_permissions where not.
+      #
+      # @return [Hash] users:, unconfirmed:
+      def invalidate_everyone(tenant_id)
+        model = PermissionForge.configuration.user_model
+        by_id = Cache::HolderInvalidation.by_id?(model)
+        counts = { users: 0, unconfirmed: 0 }
+        users_scope(model, tenant_id).in_batches(of: SLICE) do |batch|
+          ids = batch.pluck(model.primary_key)
+          counts[:users] += ids.size
+          counts[:unconfirmed] += by_id ? by_id(ids, tenant_id).size : one_by_one(batch, tenant_id)
+        end
+        counts
+      end
+
+      # The invalidation leaves the variants to their TTL; they hold the
+      # profile, so the clear removes them too.
+      #
+      # @return [Array] the ids the store did not confirm
+      def by_id(ids, tenant_id)
+        Cache::HolderInvalidation.call(user_ids: ids, tenant_id: tenant_id) | Cache::VariantRemoval.call(user_ids: ids, tenant_id: tenant_id)
+      end
+
+      # @return [Integer] how many the store did not confirm
+      def one_by_one(batch, tenant_id)
+        batch.reject do |user|
+          Cache::Failure.none? do
+            user.invalidate_permissions(tenant_id: tenant_id)
+            Cache::VariantRemoval.call(user_ids: [user.id], tenant_id: tenant_id, ambient_key: user.permission_cache_key)
+          end
+        end.size
+      end
+
+      # Under a tenant: the users as the host scopes them (a tenant-scoped
+      # user model lists that tenant's). Without one: everyone.
+      def users_scope(model, tenant_id)
+        PermissionForge::Concerns::AutoPermissionScoping.internally_suspended { tenant_id ? model.all : model.unscoped }
+      end
+
+      # The tenants of the tenant model, when tenancy is on; none otherwise.
+      def tenants
+        return [] unless PermissionForge.configuration.tenant_enabled?
+
+        @tenants ||= PermissionForge.configuration.tenant_model.constantize.unscoped.to_a
+      end
+
+      def without_tenant(&)
+        defined?(ActsAsTenant) ? ActsAsTenant.without_tenant(&) : yield
+      end
+
+      def record(tenant_id, **data)
+        PermissionForge::Audit.record(EVENT, tenant_id: tenant_id,
+                                             data: data.transform_keys(&:to_s).merge('operation' => 'cache_clear'))
+      end
+
+      # The event without a tenant — recorded with none ambient, so it is one.
+      def record_without_tenant(**data)
+        without_tenant { record(nil, **data, across_tenants: true) }
+      end
+    end
+  end
+end