permission_forge 0.14.1

data/lib/permission_forge/concerns/field_mask_checker.rb

@@ -0,0 +1,45 @@
+module PermissionForge
+  module Concerns
+    # Field-level mask checks.
+    # Depends on PermissionCacheAccessor for pf_resource_name_permissions.
+    #
+    # @api public
+    module FieldMaskChecker
+      extend ActiveSupport::Concern
+
+      # @param resource [Symbol, String] resource name
+      # @param field_name [Symbol, String] field name
+      # @return [Boolean] true if the field should be masked
+      #
+      # Fail-closed for unconfigured fields: when the field has no entry in the
+      # permission hash, the answer follows `unconfigured_field_strategy` — a
+      # blocking or mask-all strategy reports the field as masked rather than
+      # defaulting to "not masked" (which would leak plaintext).
+      def masked_field?(resource, field_name)
+        field = field_permissions(resource, field_name)
+        return field[:mask_access] == true if field
+
+        %i[block mask_all].include?(PermissionForge.configuration.unconfigured_field_strategy)
+      end
+
+      # @param resource [Symbol, String] resource name
+      # @param field_name [Symbol, String] field name
+      # @return [String] mask strategy (e.g., 'full', 'email', 'last4')
+      def mask_strategy_for(resource, field_name)
+        field = field_permissions(resource, field_name)
+        field&.dig(:mask_strategy) || 'full'
+      end
+
+      # @param resource [Symbol, String] resource name
+      # @param field_name [Symbol, String] field name
+      # @return [Hash, nil] field permission hash with :read_access, :edit_access, :mask_access, :mask_strategy
+      def field_permissions(resource, field_name)
+        entry = pf_resource_name_permissions(resource)
+        return if entry.blank?
+
+        field_name = field_name.to_sym
+        entry.dig(:fields, field_name)
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/has_active_scope.rb

@@ -0,0 +1,12 @@
+module PermissionForge
+  module Concerns
+    # @api private
+    module HasActiveScope
+      extend ActiveSupport::Concern
+
+      included do
+        scope :active, -> { where(is_active: true) }
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/has_audit_trail.rb

@@ -0,0 +1,59 @@
+module PermissionForge
+  module Concerns
+    # @api private
+    module HasAuditTrail
+      extend ActiveSupport::Concern
+
+      included do
+        # class_name is config.audit_user_class as the model loads — after the
+        # host's config/initializers, since the models are autoloaded by the
+        # application (app/models). The callbacks are always registered but
+        # no-op at runtime when audit_trail_enabled is false — so
+        # config.audit_trail_enabled = false is a real toggle, not a
+        # load-time-frozen one.
+        belongs_to :created_by,
+                   class_name: PermissionForge.configuration.audit_user_class,
+                   optional: true
+
+        belongs_to :updated_by,
+                   class_name: PermissionForge.configuration.audit_user_class,
+                   optional: true
+
+        before_create :set_created_by
+        before_update :set_updated_by
+      end
+
+      private
+
+      # created_by is kept when given (a clone, an import); updated_by starts
+      # as whoever created the row.
+      def set_created_by
+        return unless PermissionForge.configuration.audit_trail_enabled
+
+        acting = audit_trail_user_id
+        self.created_by_id ||= acting
+        self.updated_by_id ||= acting || created_by_id
+      end
+
+      # Moves only to someone known: an edit by nobody (a job, a Basic-auth
+      # login, an API client) keeps the previous editor instead of blanking it.
+      def set_updated_by
+        return unless PermissionForge.configuration.audit_trail_enabled
+
+        acting = audit_trail_user_id
+        self.updated_by_id = acting if acting
+      end
+
+      # The id of the acting user: the audit actor (an explicit
+      # with_audit_actor block, the request's actor, else
+      # PermissionForge.current_user) when it was made from a record of
+      # config.audit_user_class — the class the two columns point at. An
+      # admin of another model, or an actor given as a Hash, stamps nothing:
+      # its id would name somebody else.
+      def audit_trail_user_id
+        actor = PermissionForge::Audit::Actor.current
+        actor.id if actor.user_of?(PermissionForge.configuration.audit_user_class.to_s.safe_constantize)
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/has_permission_set_users.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    # Provides `users_on_permission_set` required by {PermissionsRegenerator},
+    # and `user_ids_on_permission_set`, the ids of their users, plucked
+    # without loading a row (what the invalidation uses).
+    #
+    # Include this concern and declare the lookup strategy based on how the model
+    # relates to a permission set:
+    #
+    #   permission_set_user_lookup :self         # PermissionSet (has permission_set_users directly)
+    #   permission_set_user_lookup :direct       # Has permission_set_id column
+    #   permission_set_user_lookup :via_resource # Has resource_id -> resource -> permission_set
+    #
+    # Inside after_commit the queries go through the commit's InvalidationBatch
+    # (InvalidatesInBatch), so the records of one Permission Set written in one
+    # transaction look its assignments up once. Anywhere else every call
+    # queries afresh. Every lookup follows the record's tenant, not the
+    # ambient one.
+    #
+    # @api private
+    module HasPermissionSetUsers
+      extend ActiveSupport::Concern
+      include InvalidatesInBatch
+
+      # Which Permission Sets the record's change affects, by strategy.
+      LOOKUPS = {
+        self: :self_permission_set_ids,
+        direct: :direct_permission_set_ids,
+        via_resource: :via_resource_permission_set_ids
+      }.freeze
+
+      included do
+        # a record moved to another set or resource: see #direct_permission_set_ids
+        after_save { %w[permission_set_id resource_id].each { |column| note_previous_value(column) } }
+      end
+
+      class_methods do
+        # @param strategy [:self, :direct, :via_resource]
+        def permission_set_user_lookup(strategy)
+          lookup = LOOKUPS.fetch(strategy) do
+            raise ArgumentError, "Unknown strategy: #{strategy}. Use :self, :direct, or :via_resource"
+          end
+
+          # on the class itself: these win over PermissionsRegenerator's defaults
+          define_method(:affected_permission_set_ids) { send(lookup) }
+          define_method(:users_on_permission_set) { assignments_of_affected_sets }
+          define_method(:user_ids_on_permission_set) { holder_ids_of_affected_sets }
+          private :affected_permission_set_ids, :users_on_permission_set, :user_ids_on_permission_set
+        end
+      end
+
+      private
+
+      # @return [Array<PermissionForge::PermissionSetUser>]
+      def assignments_of_affected_sets
+        affected_permission_set_ids.flat_map { |set_id| permission_set_assignments(set_id).to_a }
+      end
+
+      # @return [Array] the holders' user ids, without duplicates
+      def holder_ids_of_affected_sets
+        affected_permission_set_ids.flat_map { |set_id| permission_set_user_ids(set_id) }.uniq
+      end
+
+      def self_permission_set_ids
+        [id]
+      end
+
+      # A record moved to another Permission Set (or resource) changes what
+      # both grant, so the users of both are affected — every set it left
+      # since the last commit (InvalidatesInBatch#note_previous_value).
+      def direct_permission_set_ids
+        [permission_set_id, *previous_values('permission_set_id')].compact_blank.uniq.reject do |set_id|
+          shared_lookup(:inactive_permission_set, set_id) { permission_set_exists?(set_id, active: false) }
+        end
+      end
+
+      def via_resource_permission_set_ids
+        [resource_id, *previous_values('resource_id')].compact_blank.uniq.filter_map do |parent_id|
+          set_id = shared_lookup(:permission_set_of_resource, parent_id) do
+            in_record_tenant(PermissionForge::Resource).where(id: parent_id).pick(:permission_set_id)
+          end
+          next if set_id.blank?
+
+          set_id if shared_lookup(:active_permission_set, set_id) { permission_set_exists?(set_id, active: true) }
+        end
+      end
+
+      # The assignments of a Permission Set in this record's tenant (see
+      # InvalidatesInBatch#in_record_tenant).
+      def permission_set_assignments(set_id)
+        shared_lookup(:assignments, set_id) do
+          in_record_tenant(PermissionForge::PermissionSetUser).where(permission_set_id: set_id)
+        end
+      end
+
+      # Their user ids, plucked: a set may have thousands of holders, and
+      # nothing but the id is needed to invalidate them.
+      def permission_set_user_ids(set_id)
+        shared_lookup(:assignment_user_ids, set_id) { permission_set_assignments(set_id).distinct.pluck(:user_id) }
+      end
+
+      def permission_set_exists?(set_id, active:)
+        in_record_tenant(PermissionForge::PermissionSet).where(id: set_id, is_active: active).exists?
+      end
+
+      # The lookups depend on the record's tenant, so it is part of every key:
+      # records of two tenants in one commit do not share an answer.
+      def shared_lookup(*key, &)
+        invalidation_batch.fetch([permission_record_tenant_id, *key], &)
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/has_tenant_scoping.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    # Conditionally includes acts_as_tenant on PermissionForge models
+    # when `config.tenant_model` is set and the acts_as_tenant gem is available.
+    #
+    # All permission data is strictly scoped to the current tenant.
+    # Cross-tenant user sharing is supported: the same user can be assigned
+    # to permission sets in multiple tenants, each producing a separate cached hash.
+    #
+    # @example Enable in initializer
+    #   config.tenant_model = 'Account'  # enables multi-tenancy
+    #   config.tenant_column = :account_id  # optional, inferred from model
+    #
+    # @api private
+    module HasTenantScoping
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Declares the tenant association and default scope on the including
+        # model, on the configured column. Each model calls it as its class
+        # body loads — after the host's config/initializers (the models are
+        # autoloaded), and after its own macros, so acts_as_tenant's callbacks
+        # keep running after the model's own; a code reload declares it again.
+        # Idempotent: acts_as_tenant adds a default_scope on every call, so
+        # applying twice (the class body plus a host, or the test suite,
+        # calling it by hand) would filter the tenant twice.
+        def apply_tenant_scoping!
+          config = PermissionForge.configuration
+          return unless config.tenant_enabled? && defined?(ActsAsTenant)
+          return if tenant_scoping_applied?
+
+          acts_as_tenant config.tenant_association_name,
+                         foreign_key: config.resolved_tenant_column,
+                         class_name: config.tenant_model,
+                         **tenant_scoping_options
+          @pf_tenant_model = config.tenant_model.to_s
+        end
+
+        # Extra acts_as_tenant options of the including model. A permission
+        # row needs a tenant whatever the host's belongs_to_required_by_default
+        # says (the models load after the host's initializers, where that
+        # setting may be anything); a model whose rows may belong to none (an
+        # audit event of a cross-tenant task) overrides this with
+        # `{ optional: true }`.
+        def tenant_scoping_options
+          { optional: false }
+        end
+
+        # The tenant model this class was scoped on as it loaded; nil while
+        # it is not scoped (ModelBindings compares it with the configuration).
+        #
+        # @return [String, nil]
+        def tenant_scoping_model
+          @pf_tenant_model if tenant_scoping_applied?
+        end
+
+        # acts_as_tenant defines scoped_by_tenant? on the class once applied.
+        def tenant_scoping_applied?
+          respond_to?(:scoped_by_tenant?)
+        end
+
+        # The rows of one tenant whatever tenant is ambient, together with the
+        # rows that have no tenant (written before tenancy was switched on).
+        # No tenant id means every row — and so does a table that has no
+        # tenant column (an install that predates it): its rows cannot be told
+        # apart, and a lookup that raised would invalidate nobody.
+        # Built without ActsAsTenant.with_tenant, which writes the tenant it
+        # resolved back into the request-level one.
+        #
+        # @param tenant_id [Object, nil]
+        # @return [ActiveRecord::Relation]
+        def of_tenant(tenant_id)
+          config = PermissionForge.configuration
+          return all unless config.tenant_enabled? && tenant_scoping_applied?
+
+          column = config.resolved_tenant_column
+          return unscoped if tenant_id.nil? || !column_names.include?(column.to_s)
+
+          unscoped.where(column => [tenant_id, nil])
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/has_uuid.rb

@@ -0,0 +1,24 @@
+module PermissionForge
+  # The concerns a host includes in its own classes (`PermissionedUser`, `PermissionScopedFindable`,
+  # `MaskedAttributes`, `ControllerActionGuard`, ...); the ones the gem uses on its own models are `@api private`.
+  #
+  # @api public
+  module Concerns
+    # @api private
+    module HasUuid
+      extend ActiveSupport::Concern
+
+      included do
+        before_create :generate_uuid, if: -> { respond_to?(:uuid) && uuid.blank? }
+
+        validates :uuid, uniqueness: true, allow_nil: true
+      end
+
+      private
+
+      def generate_uuid
+        self.uuid = PermissionForge.configuration.uuid_generator.call
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/invalidates_in_batch.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    # Runs a permission record's cache invalidation after commit, through the
+    # InvalidationBatch shared by the records written in the same transaction,
+    # so what one of them invalidated is not invalidated again by the next.
+    #
+    # The including concern or model says what to invalidate by overriding
+    # `invalidate_committed_caches` (calling super) and doing the work through
+    # `invalidation_batch`:
+    #
+    #   def invalidate_committed_caches
+    #     super
+    #     invalidation_batch.once([:my_cache, id]) { MyCache.drop(id) }
+    #   end
+    #
+    # The rule this concern keeps: a record's after_commit reuses a batch only
+    # when the record joined it for the write being reported.
+    #   - Every write that can lead to after_commit sets the reference first:
+    #     save and destroy join the open batch in a before callback (it runs
+    #     before the row is written, whatever other callbacks do); touch, which
+    #     has no before callback, drops the reference and so invalidates on its
+    #     own.
+    #   - Every such write also tells the batches of this process to forget
+    #     what they remember (InvalidationBatch.note_write): it may be a write
+    #     made by a callback between two after_commits of one commit.
+    #   - after_commit takes the reference (it is used once) and claims the
+    #     batch; a refused claim, or no reference, means a batch of its own.
+    #   - Outside after_commit there is no batch to reuse: calling an
+    #     invalidation method by hand always invalidates.
+    #
+    # Two more things hold for every invalidation made here:
+    #   - It follows the RECORD's tenant, not the ambient one. A record of
+    #     tenant A saved while tenant B (or none) is ambient still finds the
+    #     assignments of tenant A (`in_record_tenant`), and their users
+    #     whatever default scope the host's user model has.
+    #   - Nothing is raised out of after_commit: Rails would skip the commit
+    #     callbacks of the remaining records. A failure is reported through
+    #     Cache::Failure instead.
+    #
+    # @api private
+    module InvalidatesInBatch
+      extend ActiveSupport::Concern
+
+      included do
+        before_save :join_invalidation_batch
+        before_destroy :join_invalidation_batch
+        after_commit :invalidate_after_commit, on: %i[create update destroy]
+      end
+
+      def touch(*, **)
+        PermissionForge::InvalidationBatch.note_write
+        @pf_joined_invalidation_batch = nil
+        super
+      end
+
+      private
+
+      def join_invalidation_batch
+        self.class.connection_pool.with_connection do |connection|
+          @pf_joined_invalidation_batch = PermissionForge::InvalidationBatch.join(connection)
+        end
+      end
+
+      def invalidate_after_commit
+        outer = @pf_invalidation_batch
+        joined = @pf_joined_invalidation_batch
+        @pf_joined_invalidation_batch = nil
+        @pf_invalidation_batch = joined&.claim
+        invalidate_committed_caches
+      rescue StandardError => e
+        PermissionForge::Cache::Failure.report(operation: :after_commit, error: e, record: "#{self.class.name}##{id}")
+      ensure
+        # nil, unless an invalidation wrote this very record again and its
+        # commit ran inside this one.
+        @pf_invalidation_batch = outer
+      end
+
+      # Leaves a note in the batch this record joined for the write in
+      # progress, next to the note the record keeps for itself (see
+      # InvalidationBatch#note).
+      def note_in_invalidation_batch(kind, value)
+        @pf_joined_invalidation_batch&.note(kind, value)
+      end
+
+      # A record moved by a save (another user, Permission Set or resource)
+      # changes what the previous one grants too. Call from after_save: the
+      # value `column` had before the save just made is noted when it
+      # changed — at every save, since after_commit only sees the last save
+      # of a transaction. Like InvalidatesManagedActions' note it is only ever
+      # consumed by a commit (#previous_values), never forgotten on rollback
+      # (a later save rolled back to a savepoint must not take an earlier
+      # move with it; an extra invalidation costs a rebuild), and it is also
+      # left in the batch, under the row it belongs to: of two instances of
+      # one row written in a transaction, Rails runs the commit callbacks of
+      # one.
+      def note_previous_value(column)
+        return unless has_attribute?(column) && saved_change_to_attribute?(column)
+
+        previous = attribute_before_last_save(column)
+        return if previous.nil?
+
+        ((@pf_previous_values ||= {})[column] ||= []) << previous
+        note_in_invalidation_batch(:"previous_#{column}", [invalidation_row, previous])
+      end
+
+      # The values `column` had before the saves this commit reports — this
+      # instance's, and those the batch holds for this row (another instance
+      # of it) — consumed: the next commit starts from nothing.
+      def previous_values(column)
+        own = @pf_previous_values&.delete(column) || []
+        row = invalidation_row
+        noted = invalidation_batch.noted(:"previous_#{column}").filter_map { |noted_row, value| value if noted_row == row }
+        (own + noted).uniq
+      end
+
+      # Which row a note in the batch belongs to.
+      def invalidation_row
+        [self.class.base_class.name, id]
+      end
+
+      # What to invalidate once the record's transaction has committed.
+      # Override, call super, and work through `invalidation_batch`.
+      def invalidate_committed_caches; end
+
+      # The batch of the commit being reported, inside after_commit; anywhere
+      # else a batch of its own each time, which remembers nothing.
+      def invalidation_batch
+        @pf_invalidation_batch || PermissionForge::InvalidationBatch.new
+      end
+
+      # Invalidates the cached hash of the users who hold the assignments —
+      # once per user and tenant in `batch`. By id, in slices, when nothing
+      # but the store calls of User#invalidate_permissions would happen
+      # (Cache::HolderInvalidation.by_id?); else through the public
+      # User#invalidate_permissions of each loaded user (host apps override
+      # it). A user whose invalidation raises is reported and counts as
+      # done: the others still get theirs, and the next record of the commit
+      # does not try again.
+      #
+      # @param user_ids [Array] the holders' user ids
+      def invalidate_assigned_users(user_ids, batch, tenant_id)
+        pending = user_ids.compact.uniq
+        pending.reject! { |user_id| batch.done?([:user, user_id, tenant_id]) }
+        return if pending.empty?
+
+        if PermissionForge::Cache::HolderInvalidation.by_id?(PermissionForge.configuration.user_model)
+          invalidate_user_ids(pending, batch, tenant_id)
+        else
+          assigned_users(pending).each do |user|
+            batch.once([:user, user.id, tenant_id]) { invalidate_user(user, tenant_id) }
+          end
+        end
+      end
+
+      # What the store did not confirm was reported and owed by
+      # HolderInvalidation, and counts as done like a user whose
+      # invalidate_permissions failed.
+      def invalidate_user_ids(user_ids, batch, tenant_id)
+        begin
+          PermissionForge::Cache::HolderInvalidation.call(user_ids: user_ids, tenant_id: tenant_id)
+        rescue StandardError => e
+          PermissionForge::Cache::Failure.report(operation: :invalidate, error: e, record: "#{self.class.name}##{id}")
+        end
+        user_ids.each { |user_id| batch.done!([:user, user_id, tenant_id]) }
+      end
+
+      def invalidate_user(user, tenant_id)
+        user.invalidate_permissions(tenant_id: tenant_id)
+      rescue StandardError => e
+        PermissionForge::Cache::Failure.report(operation: :invalidate, user_id: user.id, error: e)
+      end
+
+      # Loaded past the default scopes of the host's user model: an ambient
+      # tenant, a soft-delete or a permission scope there must not hide the
+      # holder of an assignment from an invalidation.
+      def assigned_users(user_ids)
+        return [] if user_ids.empty?
+
+        model = PermissionForge.configuration.user_model
+        PermissionForge::Concerns::AutoPermissionScoping.internally_suspended { model.unscoped.where(model.primary_key => user_ids).to_a }
+      end
+
+      # A relation over a permission model that follows this record's tenant
+      # instead of the ambient one (HasTenantScoping.of_tenant). The ambient
+      # default scope would find nothing for a record of tenant A saved under
+      # tenant B, and under no tenant it would also match another tenant's
+      # rows that merely share an id. A record without a tenant looks
+      # everywhere.
+      def in_record_tenant(model)
+        model.of_tenant(permission_record_tenant_id)
+      end
+
+      # Tenant id of the changed record, so invalidation reaches the
+      # tenant-scoped cache key even when no ambient tenant is set
+      # (e.g., callbacks fired from a background job).
+      def permission_record_tenant_id
+        config = PermissionForge.configuration
+        return nil unless config.tenant_enabled?
+
+        column = config.resolved_tenant_column
+        respond_to?(column) ? public_send(column) : nil
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/invalidates_managed_actions.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    # Drops ControllerActions::ManagedIndex when a record that defines it
+    # changes: a row that counts being created, destroyed or renamed, or a row
+    # or Permission Set being switched on or off. Flag edits (CRUD toggles,
+    # is_permitted) leave the index alone — they change who is granted, not
+    # what is managed.
+    #
+    # The change is noted at each save and consumed at commit. after_commit on
+    # its own sees only the LAST save of a transaction: a row created (or
+    # switched on) and then saved again would look unchanged there, and the
+    # guard would keep treating its action as unmanaged.
+    #
+    # A note is only ever consumed by a commit, never forgotten: a later save
+    # rolled back to a savepoint must not take the note of an earlier save
+    # with it. After a rollback the note stays, and the record's next commit
+    # drops the index once more than needed — which costs one rebuild, where a
+    # missed drop lets requests through for as long as the index lives.
+    #
+    # The note is also left in the transaction's InvalidationBatch: of two
+    # instances of one row written in a transaction, Rails runs the commit
+    # callbacks of one, which may not be the one that changed what is managed.
+    #
+    # The index is dropped after commit through InvalidatesInBatch: once per
+    # transaction (and tenant), however many of its records changed what is
+    # managed.
+    #
+    # @api private
+    module InvalidatesManagedActions
+      extend ActiveSupport::Concern
+      include InvalidatesInBatch
+
+      NOTE = :managed_actions
+
+      included do
+        after_save :note_managed_actions_change
+      end
+
+      private
+
+      def note_managed_actions_change
+        return unless managed_actions_changed?
+
+        @pf_managed_actions_changed = true
+        note_in_invalidation_batch(NOTE, permission_record_tenant_id)
+      end
+
+      # The index first, and each of the two even when the other raises.
+      def invalidate_committed_caches
+        invalidate_managed_actions
+      ensure
+        super
+      end
+
+      def invalidate_managed_actions
+        batch = invalidation_batch
+        tenant_ids = batch.noted(NOTE)
+        tenant_ids |= [permission_record_tenant_id] if destroyed? ? is_active : @pf_managed_actions_changed
+
+        tenant_ids.each do |tenant_id|
+          batch.once([NOTE, tenant_id]) do
+            PermissionForge::ControllerActions::ManagedIndex.invalidate!(tenant_id: tenant_id)
+          end
+        end
+        @pf_managed_actions_changed = false
+      end
+
+      # Whether the save just made changed what is managed. For a Resource or
+      # ResourceAction: a new row that counts, a row switched on or off, or a
+      # rename of a row that counts. PermissionSet overrides this.
+      def managed_actions_changed?
+        return is_active if previously_new_record?
+
+        saved_change_to_is_active? || (is_active && saved_change_to_name?)
+      end
+    end
+  end
+end