permission_forge 0.14.1 → 0.15.0

data/lib/permission_forge/concerns/masked_attributes.rb

@@ -27,7 +27,10 @@ module PermissionForge
     #
     # With no current user every value is returned as stored, unless
     # config.masked_attributes_nil_user_strategy = :hide, which hides every
-    # guarded attribute instead (the primary key and the raw paths excepted).
+    # guarded attribute instead (the primary key and the raw paths excepted),
+    # or :hide_in_requests, which does so inside a web request only
+    # (PermissionForge::WebRequest). Under :bypass a value returned as stored
+    # inside a web request is recorded (field.unmasked_without_user).
     #
     # @example Include in a model
     #   class Customer < ApplicationRecord
@@ -105,8 +108,10 @@ module PermissionForge
         # (`generated_attribute_methods`) and includes it in the model. Calling
         # `customer.email` hits that fast path, bypassing `read_attribute`. We
         # prepend an override module so direct getters (and setters, for the
-        # write-back guard) route through our logic. Captured at include time —
-        # column changes after this require a class reload to pick up.
+        # write-back guard) route through our logic: one per column the model
+        # has now, and one per column Rails finds each time it defines the
+        # attribute methods again (define_attribute_methods below: a column a
+        # migration added after the include, once the schema is read again).
         #
         # A getter raises ActiveModel::MissingAttributeError for a column that
         # was not loaded (`select(:id)`), as the getter Rails generates does.
@@ -116,16 +121,7 @@ module PermissionForge
         # the tenant model when computing cache keys). Masking `id` would create
         # a recursion: `id` → guard → `permissions_hash` → `current_tenant.id`.
         masked_attribute_module = ColumnAccessors.new
-        primary_key = self.primary_key&.to_s
-        columns_hash.each_key do |col_name|
-          next if col_name.to_s == primary_key
-
-          attr_sym = col_name.to_sym
-          masked_attribute_module.define_method(attr_sym) { read_attribute(attr_sym) { |name| missing_attribute(name, caller) } }
-          masked_attribute_module.define_method("#{attr_sym}=") do |value|
-            next super(value) unless pf_skip_masked_write?(attr_sym, value)
-          end
-        end
+        PermissionForge::Concerns::MaskedAttributes.define_column_accessors(self, masked_attribute_module)
         prepend(masked_attribute_module)
 
         const_set(:MaskedAttributeReaders, masked_attribute_module)
@@ -139,6 +135,50 @@ module PermissionForge
         @_pf_masked_attributes_applied = true
       end
 
+      class_methods do
+        # Rails defines a model's attribute methods lazily, and again after
+        # the schema is read again (reset_column_information — what
+        # PermissionForge::SchemaRead does when the database's columns
+        # changed): each time, a column the guarded module lacks gets its
+        # guarded getter and setter, so `record.new_column` answers what
+        # `record[:new_column]` and `as_json` answer. A subclass asks its
+        # parent first (Rails), whose module then has the method: Rails
+        # generates none of its own for the subclass.
+        def define_attribute_methods
+          super.tap { |generated| pf_define_late_column_accessors if generated }
+        end
+
+        private
+
+        def pf_define_late_column_accessors
+          return unless const_defined?(:MaskedAttributeReaders, false)
+
+          PermissionForge::Concerns::MaskedAttributes.define_column_accessors(self, const_get(:MaskedAttributeReaders, false))
+        end
+      end
+
+      # Defines on `accessors` a guarded getter and setter for every column
+      # of `klass` it does not have yet (the primary key never: it is used by
+      # routing, associations and tenant scoping). The columns are the ones
+      # Rails just loaded for the model (`columns_hash`, ignored columns
+      # excluded): those it generates methods for.
+      #
+      # @param klass [Class]
+      # @param accessors [ColumnAccessors]
+      # @return [void]
+      def self.define_column_accessors(klass, accessors)
+        primary_key = klass.primary_key&.to_s
+        klass.columns_hash.each_key do |col_name|
+          next if col_name.to_s == primary_key || accessors.method_defined?(col_name, false)
+
+          attr_sym = col_name.to_sym
+          accessors.define_method(attr_sym) { read_attribute(attr_sym) { |name| missing_attribute(name, caller) } }
+          accessors.define_method("#{attr_sym}=") do |value|
+            next super(value) unless pf_skip_masked_write?(attr_sym, value)
+          end
+        end
+      end
+
       # Whether MaskedAttributes has already been applied to a class. Used by the
       # engine's auto-apply to avoid re-prepending the readers module.
       def self.applied?(klass)
@@ -206,8 +246,7 @@ module PermissionForge
           masked_attributes_applied: applied_in_chain?(klass),
           primary_key: klass.primary_key,
           is_primary_key: klass.primary_key.to_s == attr_name.to_s,
-          current_user_present: !user.nil?,
-          masked_attributes_nil_user_strategy: config.masked_attributes_nil_user_strategy, user_model_exempt: config.user_model_class?(klass),
+          current_user_present: !user.nil?, **explain_without_user(config, klass),
           user_responds_to_field_permissions: user.respond_to?(:field_permissions),
           resource_in_permissions_hash: entries?(user, chain),
           field_configured: !field.nil?,
@@ -219,6 +258,13 @@ module PermissionForge
         }
       end
 
+      # What explain reports about reads with nobody signed in.
+      def self.explain_without_user(config, klass)
+        { masked_attributes_nil_user_strategy: config.masked_attributes_nil_user_strategy,
+          user_model_exempt: config.user_model_class?(klass), in_web_request: PermissionForge::WebRequest.active? }
+      end
+      private_class_method :explain_without_user
+
       # Whether the user's hash has a resource entry along the chain.
       def self.entries?(user, chain)
         user.respond_to?(:permissions_hash) && PermissionForge::ResourceChain.entries(user, chain).any?
@@ -280,12 +326,13 @@ module PermissionForge
       private_class_method :decide
 
       # What the guard does with no user (config.masked_attributes_nil_user_strategy;
-      # the user model is exempt from :hide).
+      # the user model is exempt from :hide and :hide_in_requests).
       def self.without_user_decision(klass)
         config = PermissionForge.configuration
-        return :no_user_bypassed unless config.hide_masked_attributes_without_user?
+        return :no_user_hidden if config.hide_masked_attributes_without_user_for?(klass)
+        return :no_user_user_model_exempt if config.hide_masked_attributes_without_user_in_requests? && config.user_model_class?(klass)
 
-        config.user_model_class?(klass) ? :no_user_user_model_exempt : :no_user_hidden
+        :no_user_bypassed
       end
       private_class_method :without_user_decision
 
@@ -304,6 +351,13 @@ module PermissionForge
       end
       private_class_method :print_explain_table
 
+      # Forgets the attributes read as hidden with nobody signed in
+      # (pf_hidden_without_user_reads): the record holds fresh values.
+      def reload(*)
+        pf_forget_hidden_without_user_reads
+        super
+      end
+
       # Reads an attribute through the field permissions of the current user.
       # @param attr_name [String, Symbol]
       def read_attribute(attr_name, &)
@@ -315,8 +369,12 @@ module PermissionForge
         attr_name = name = pf_alias_end(target) if target
         return raw if pf_read_as_stored?(name)
 
-        include_field, value = pf_guard(attr_name, raw)
-        value = PermissionForge.configuration.hidden_attribute_value unless include_field
+        user = pf_guarded_user
+        include_field, value = pf_guard(attr_name, raw, user)
+        unless include_field
+          value = PermissionForge.configuration.hidden_attribute_value
+          pf_note_hidden_without_user(name, raw) unless user
+        end
         # A returned value that differs from the raw column value was masked or
         # hidden; remember the exact sentinel so a write-back of it can be refused.
         pf_record_masked_read(name, value) unless include_field && value == raw
@@ -325,13 +383,15 @@ module PermissionForge
 
       # The user is resolved once for the whole hash. With no user every
       # value is returned as stored (or hidden, under
-      # config.masked_attributes_nil_user_strategy = :hide); the decisions
-      # (bypassed) are still published, as for a getter or as_json, but only
-      # when someone listens.
+      # config.masked_attributes_nil_user_strategy = :hide, and :hide_in_requests
+      # inside a web request); the decisions (bypassed) are still published,
+      # as for a getter or as_json, but only when someone listens, and each
+      # attribute returned as stored inside a web request is recorded
+      # (field.unmasked_without_user).
       def attributes
         raw = super
         user = pf_guarded_user
-        return raw unless user || pf_hide_without_user? || PermissionForge::Audit::FieldAccess::GATE.open?
+        return raw unless user || pf_guard_without_user? || PermissionForge::Audit::FieldAccess::GATE.open?
 
         PermissionForge::Audit::FieldAccess.read(self, self.class.name, record: self) do
           pf_guard_attributes_hash(raw, user)
@@ -440,14 +500,25 @@ module PermissionForge
         name == self.class.primary_key || pf_raw_store_column?(name) || name == pf_validation_read
       end
 
-      # config.masked_attributes_nil_user_strategy = :hide — with no user
-      # every guarded attribute is hidden (AttributeAccessGuard#without_user),
-      # except on the user model, which sign-in reads before anyone is
-      # signed in.
+      # config.masked_attributes_nil_user_strategy = :hide (and
+      # :hide_in_requests inside a web request) — with no user every guarded
+      # attribute is hidden (AttributeAccessGuard#without_user), except on
+      # the user model, which sign-in reads before anyone is signed in.
       def pf_hide_without_user?
         PermissionForge.configuration.hide_masked_attributes_without_user_for?(self.class)
       end
 
+      # Whether a read with no user goes through the guard attribute by
+      # attribute: it hides them, or records them (inside a web request
+      # under :bypass, while there is something left to record).
+      def pf_guard_without_user?
+        case PermissionForge.configuration.masked_attributes_without_user_for(self.class)
+        when :hide then true
+        when :record then PermissionForge::Audit::UnmaskedWithoutUser.pending?(self.class)
+        else false
+        end
+      end
+
       # Every guarded read of this record is one field.access read
       # (Audit::FieldAccess), joined by the reads made inside it. Nobody
       # listening (the gate is shut): one check, nothing collected.
@@ -491,12 +562,45 @@ module PermissionForge
         pf_masked_reads[attr_name.to_s] = sentinel
       end
 
+      # The attributes this instance read as hidden because nobody was signed
+      # in (masked_attributes_nil_user_strategy :hide, or :hide_in_requests in a
+      # web request) while they held a value. Whatever is written to one of
+      # them afterwards was worked out from the hidden value, or replaces a
+      # value nobody could see: pf_skip_masked_write? treats it as a
+      # write-back. Only something real counts: a value the record holds in
+      # memory, stored or assigned (an empty column, or an attribute of a new
+      # record nobody filled, hides nothing: a default or a fill-if-blank is
+      # written; a value submitted on a new record is kept from a normalizer
+      # that reads it). The value is the one just read, not
+      # attribute_in_database, which would build the record's mutation
+      # tracker on every hidden read. A debugging read (inspect) does not
+      # count. Forgotten on reload only: a save does not make the hidden read
+      # visible, so a value derived from it before the save is still refused
+      # after it.
+      def pf_hidden_without_user_reads
+        @pf_hidden_without_user_reads ||= Set.new
+      end
+
+      def pf_note_hidden_without_user(attr_name, value)
+        return if value.nil? || PermissionForge::ExecutionState[INSPECT_KEY]
+
+        pf_hidden_without_user_reads << attr_name.to_s
+      end
+
+      def pf_forget_hidden_without_user_reads
+        @pf_hidden_without_user_reads = nil
+      end
+
       # True when the guard should suppress this write because `value` is a masked/
       # hidden sentinel being written back over real data. Honors
       # config.masked_write_protection. Two detections:
       #   1. Ledger — this instance handed out that exact sentinel earlier (covers
       #      same-instance read-modify-write, e.g. a before_save callback).
-      #   2. Stateless — `value` equals what the mask would produce for the value
+      #   2. Hidden without a user — this instance read the attribute as hidden
+      #      because nobody was signed in: any value written to it was derived
+      #      from the hidden one (`self.name = name.to_s.strip` stores "") or
+      #      replaces a value nobody could see.
+      #   3. Stateless — `value` equals what the mask would produce for the value
       #      CURRENTLY persisted in the DB. This survives a request boundary: a form
       #      rendered "********" and submitted back onto a freshly-loaded record has
       #      no ledger entry, but still matches the persisted value's mask.
@@ -504,19 +608,29 @@ module PermissionForge
         protection = PermissionForge.configuration.masked_write_protection
         return false if protection == :off
 
-        ledger_hit = pf_masked_reads.key?(attr_name.to_s) && pf_masked_reads[attr_name.to_s] == value
-        return false unless ledger_hit || pf_matches_persisted_sentinel?(attr_name, value)
+        detected_by = pf_masked_write_detection(attr_name.to_s, value)
+        return false unless detected_by
 
-        pf_masked_write_refused(attr_name, protection, ledger_hit)
+        pf_masked_write_refused(attr_name, protection, detected_by)
+        PermissionForge::Audit::UnmaskedWithoutUser.write_refused(self.class, attr_name, protection) if detected_by == 'hidden_without_user'
         raise MaskedWriteError, attr_name if protection == :raise
 
         true # :skip — preserve the stored value by not calling super
       end
 
+      # How a write was recognised as a write-back (write.masked_skipped
+      # `detected_by`), nil for a write that is not one.
+      def pf_masked_write_detection(name, value)
+        return 'ledger' if pf_masked_reads.key?(name) && pf_masked_reads[name] == value
+        return 'hidden_without_user' if pf_hidden_without_user_reads.include?(name)
+
+        'persisted_value' if pf_matches_persisted_sentinel?(name, value)
+      end
+
       # write.masked_skipped: which attribute, how it was refused (:skip
       # keeps the stored value, :raise raised) and how the sentinel was
       # recognised. Never the value.
-      def pf_masked_write_refused(attr_name, protection, ledger_hit)
+      def pf_masked_write_refused(attr_name, protection, detected_by)
         event = 'write.masked_skipped'
         return unless PermissionForge::Audit.instrument?(event)
 
@@ -524,7 +638,7 @@ module PermissionForge
         PermissionForge::Audit.instrument(event) do
           { record: self, subject_user_id: PermissionForge::Audit::Runtime.user_id(user),
             data: { 'model' => self.class.name, 'attribute' => attr_name.to_s, 'protection' => protection.to_s,
-                    'detected_by' => ledger_hit ? 'ledger' : 'persisted_value' },
+                    'detected_by' => detected_by },
             objects: { user: user, record: self } }
         end
       end
@@ -562,6 +676,8 @@ module PermissionForge
 
           include_field, masked = pf_guard(key, value, user)
           next [key, masked] if include_field
+
+          pf_note_hidden_without_user(key, value) unless user
           next if omit_hidden
 
           [key, hidden_value]

data/lib/permission_forge/concerns/normalizes_label.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    # The one definition of what a blank label is stored as, for every model
+    # with a `label` column: a field row, an action row and a Resource. A
+    # label that is nil, empty or only whitespace is "no label", and so is
+    # the install migration's column default on a new row ('Untitled Field');
+    # such a label is stored as #generated_label — on create and on update,
+    # in code, through the JSON API and in the admin alike.
+    #
+    # A field or action row is labelled with its name (what the gem writes
+    # for a row it generates, and what PermissionForge::GeneratedText reads
+    # as no label); the field's column is NOT NULL, so nil cannot stand for
+    # "no label" there. A Resource stores nil (its label column is nullable
+    # and the admin names a model from the host's translation).
+    #
+    # A rename that leaves a label the gem would generate for the old name
+    # (the name or its humanized form: GeneratedText.label?) relabels the row
+    # with its new name: the old name would read as a label an admin wrote.
+    #
+    # Checked on create, when the label changes and on a rename only: a row
+    # stored with a blank label before keeps it through a save of its other
+    # attributes (no label change in that save's audit event).
+    #
+    # Field test round 8 (D#25): through the API a field label `null` was a
+    # 422 "can't be blank" while `""` was stored, and an action stored both
+    # as sent — the admin stored a blanked label as the name.
+    #
+    # @api private
+    module NormalizesLabel
+      extend ActiveSupport::Concern
+
+      included do
+        before_validation :normalize_label
+      end
+
+      # What a label `text` written to this row is stored as: a blank one
+      # (nil, empty, white space) as no label — the row's name (a
+      # Resource: nil) — anything else as written. The admin's review asks
+      # it for the value it shows.
+      #
+      # @param text [String, nil]
+      # @return [String, nil]
+      def label_to_store(text)
+        text.to_s.strip.empty? ? generated_label : text
+      end
+
+      private
+
+      # The label "no label" is stored as: the row's name.
+      #
+      # @return [String, nil]
+      def generated_label
+        name.to_s
+      end
+
+      def normalize_label
+        return unless has_attribute?(:label) && label_check_due?
+
+        self.label = unwritten_label? ? generated_label : label_to_store(label)
+      end
+
+      def label_check_due?
+        new_record? || will_save_change_to_label? || will_save_change_to_name?
+      end
+
+      # On a new row the column default; on a rename, a label generated for
+      # the old name that this save leaves as it is.
+      def unwritten_label?
+        return label == self.class.column_defaults['label'] if new_record?
+
+        will_save_change_to_name? && !will_save_change_to_label? && !generated_label.nil? &&
+          PermissionForge::GeneratedText.label?(label, name_in_database)
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/permission_cache_accessor.rb

@@ -389,9 +389,9 @@ module PermissionForge
       # @return [Array<PermissionForge::PermissionSet>]
       def pf_active_non_expired_permission_sets
         active_psu_ids = permission_set_users.active_assignments.select(:permission_set_id)
-        # Deterministic order so "first mask_strategy wins" in FieldPermissionMerger
-        # is stable across requests and DB adapters (was DB-insertion-order dependent).
-        PermissionForge::PermissionSet.active.where(id: active_psu_ids).order(:created_at, :id).to_a
+        # Deterministic order (PermissionSet.in_hash_order) so "first mask_strategy wins" in
+        # FieldPermissionMerger is stable across requests and DB adapters.
+        PermissionForge::PermissionSet.active.where(id: active_psu_ids).in_hash_order.to_a
       end
 
       # The 0.13 name of pf_active_non_expired_permission_sets, kept for host

data/lib/permission_forge/concerns/permission_scoped_findable.rb

@@ -8,7 +8,11 @@ module PermissionForge
     # `find_by!` apply the user's cached permission set rules before returning a
     # record, and `permission_scoped` returns a rule-constrained relation you can
     # chain (`.where`, `.first`, `.find`, `.count`, …). If view_all or modify_all
-    # is enabled for the resource, rules are bypassed entirely.
+    # is enabled for the resource, rules are bypassed entirely. A signed-in
+    # user the model's Resource chain grants no read_access gets the rules
+    # alone under config.no_read_access_strategy :rules_only (the default:
+    # no rules, every row) and no rows under :deny (PermissionForge::
+    # RecordReadAccess, asked before the rules).
     #
     # Level 1 — ENFORCE (config.auto_query_scoping = :filter_only): a
     # default_scope applies the current user's FILTER-type rules to every
@@ -87,14 +91,17 @@ module PermissionForge
         class << self
           # `find_by` constrained by the current user's row-level rules.
           # @return [ActiveRecord::Base, nil] nil for a missing record
-          # @raise [NotAuthorizedError] when a rule denies an existing record
+          # @raise [NotAuthorizedError] when a rule (or, under
+          #   no_read_access_strategy :deny, the missing read access) denies an
+          #   existing record
           def find_by(*args)
             find_by_with_permission(*args)
           end
 
           # `find_by!` constrained by the current user's row-level rules.
           # @raise [ActiveRecord::RecordNotFound] for a missing record
-          # @raise [NotAuthorizedError] when a rule denies an existing record
+          # @raise [NotAuthorizedError] when a rule (or the missing read access)
+          #   denies an existing record
           def find_by!(*args)
             find_by_with_permission(*args) || raise(ActiveRecord::RecordNotFound)
           end
@@ -102,13 +109,16 @@ module PermissionForge
       end
 
       # Raised when a row-level rule denies an existing record (find_by /
-      # find_by!) or there is no user under nil_user_strategy :raise.
+      # find_by!), when the user has no read access to the model under
+      # no_read_access_strategy :deny, or there is no user under
+      # nil_user_strategy :raise.
       #
       # `user` is the user the rules were applied for, `record_id` the id of
       # the record that was denied. `record` is nil when the gem raises: the
       # row the user may not see is not loaded to be handed out with the
-      # error. All three are optional keywords; `NotAuthorizedError.new(details)`
-      # and `raise NotAuthorizedError, details` work as before.
+      # error. They and `failure_messages` are optional keywords;
+      # `NotAuthorizedError.new(details)` and `raise NotAuthorizedError,
+      # details` work as before.
       #
       # `details` keeps whatever was raised with (the gem raises the Array of
       # rule failure messages; a Hash with :message for a missing user).
@@ -116,14 +126,43 @@ module PermissionForge
       # error reporter and `rescue_from` handler expects: the failure
       # messages joined, the :message of a Hash, or the class name.
       #
+      # `failure_messages` is what the denying rules say on their own (each
+      # rule's `failure_message`, as an admin wrote it, or the gem's default
+      # sentence for a rule without one), for a friendly 403 without parsing
+      # `message`.
+      #
+      # Unless the host rescues it, Rails answers this error with 403
+      # Forbidden (the engine registers it in
+      # `config.action_dispatch.rescue_responses`).
+      #
+      # @example A friendly 403
+      #   rescue_from PermissionForge::Concerns::PermissionScopedFindable::NotAuthorizedError do |error|
+      #     render json: { error: error.failure_messages.first || 'Forbidden' }, status: :forbidden
+      #   end
+      #
       # @api public
       class NotAuthorizedError < StandardError
         # Why the lookup was refused.
         # @return [Hash, nil]
         attr_reader :details, :user, :record, :record_id
 
+        # The `failure_message` of each rule that denied the record, in rule
+        # order, without repeats (two Permission Sets may carry the same
+        # rule); a rule left without one says the gem's own sentence in the
+        # current locale (`permission_forge.denials.rule_default`:
+        # `Services::PermissionRuleApplier.failure_message_for`). A user
+        # without read access under no_read_access_strategy :deny gets one
+        # sentence, `permission_forge.denials.no_read_access`. Empty when
+        # no rule denied: nobody signed in under `nil_user_strategy = :raise`,
+        # or an error the host raised without `failure_messages:`. Rule
+        # messages are written by admins: decide whether they belong in a
+        # response.
+        #
+        # @return [Array<String>] frozen
+        attr_reader :failure_messages
+
         NO_DETAILS = Object.new.freeze
-        READERS = %i[user record record_id].freeze
+        READERS = %i[user record record_id failure_messages].freeze
         private_constant :NO_DETAILS, :READERS
 
         # The String a details value reads as.
@@ -136,9 +175,9 @@ module PermissionForge
           end
         end
 
-        # The :message of a Hash, else the Hash without the user, record and
-        # record_id keywords (a user's inspect must not land in an error
-        # tracker), else nothing.
+        # The :message of a Hash, else the Hash without the user, record,
+        # record_id and failure_messages keywords (a user's inspect must not
+        # land in an error tracker), else nothing.
         def self.hash_text(details)
           text = text_for(details[:message] || details['message'])
           return text if text
@@ -148,12 +187,22 @@ module PermissionForge
         end
         private_class_method :hash_text
 
-        # Keywords other than user:, record: and record_id: are details, as
-        # they always were (`new(message: 'x')`); without a positional
+        # The failure_messages: keyword as a frozen Array of distinct,
+        # non-blank Strings.
+        #
+        # @api private
+        # @return [Array<String>]
+        def self.message_list(value)
+          Array(value).filter_map { |text| text.to_s.presence }.uniq.freeze
+        end
+
+        # Keywords other than user:, record:, record_id: and failure_messages:
+        # are details, as they always were (`new(message: 'x')`); without a positional
         # argument every keyword given stays in details too, so a host's
         # `new(record: r, message: 'x')` reads as before.
         def initialize(details = NO_DETAILS, **keywords)
           @user, @record, @record_id = keywords.values_at(:user, :record, :record_id)
+          @failure_messages = self.class.message_list(keywords[:failure_messages])
           if details.equal?(NO_DETAILS)
             details = keywords
           elsif !(extra = keywords.except(*READERS)).empty?
@@ -179,22 +228,15 @@ module PermissionForge
 
             next handle_nil_user(*args, host_suspended: host_suspended) unless current_user
 
-            rules = pf_applicable_rules(current_user, 'find_by')
-            next tenant_safe_find_by(*args) unless rules
-
-            query, failure_messages = PermissionForge::Services::PermissionRuleApplier.call(
-              model_class: self, rules: rules, args: args, current_user: current_user
-            )
-
-            next deny_or_missing(failure_messages, current_user, *args) if failure_messages.any?
-
-            query.where(*args).take
+            pf_find_by_as(current_user, *args)
           end
         end
 
         # Returns a relation constrained by the current user's row-level rules, so
         # any further chaining (`.where`, `.first`, `.find`, `.count`) stays scoped.
         # Honors nil_user_strategy: :bypass -> all, :deny -> none, :raise -> raises.
+        # A signed-in user the model's Resource chain grants no read_access gets
+        # none under no_read_access_strategy :deny (RecordReadAccess).
         # view_all/modify_all and the no-rules case return the unconstrained relation.
         #
         # Built with auto-scoping suspended (rules are applied here explicitly —
@@ -213,6 +255,22 @@ module PermissionForge
 
         private
 
+        # find_by for a signed-in user: the read access the model needs
+        # (RecordReadAccess), then the rules.
+        def pf_find_by_as(current_user, *args)
+          return deny_or_missing(pf_no_read_access_denial, current_user, *args) if pf_no_read_access?(current_user)
+
+          rules = pf_applicable_rules(current_user, 'find_by')
+          return tenant_safe_find_by(*args) unless rules
+
+          query, failure_messages, denying_rules = PermissionForge::Services::PermissionRuleApplier.call(
+            model_class: self, rules: rules, args: args, current_user: current_user
+          )
+          return deny_or_missing(pf_rule_denial(failure_messages, denying_rules), current_user, *args) if failure_messages.any?
+
+          query.where(*args).take
+        end
+
         # The gem's own suspension of Level 1 (the queries find_by and
         # permission_scoped make while they apply the rules themselves): not
         # reported as a scope_suspended bypass, which is about the host's
@@ -224,6 +282,7 @@ module PermissionForge
         def build_permission_scope(host_suspended)
           current_user = PermissionForge.current_user
           return permission_scoped_without_user(host_suspended) unless current_user
+          return pf_no_read_access_scope(current_user) if pf_no_read_access?(current_user)
 
           rules = pf_applicable_rules(current_user, 'permission_scoped')
           return all unless rules
@@ -233,20 +292,53 @@ module PermissionForge
           )
         end
 
-        # Distinguishes "denied by a rule" from "no such record". find_by must honor
-        # its nil contract for a genuinely missing record (matching stock Rails) and
-        # only raise NotAuthorizedError when the record exists but rules deny it.
-        def deny_or_missing(failure_messages, current_user, *args)
+        # Distinguishes "denied" from "no such record". find_by must honor its
+        # nil contract for a genuinely missing record (matching stock Rails)
+        # and only raise NotAuthorizedError when the record exists but the
+        # rules (or the missing read access) deny it.
+        #
+        # `denial` is [reason, messages, failure_messages]: pf_rule_denial or
+        # pf_no_read_access_denial.
+        def deny_or_missing(denial, current_user, *args)
           relation = tenant_safe_relation.where(*args)
           return nil unless relation.exists?
 
+          reason, messages, failure_messages = denial
           record_id = pf_denied_record_id(relation)
           PermissionForge::Audit::Runtime.denied(
-            PermissionForge::Audit::Runtime::DENIED, reason: :rule, model: self, via: 'find_by',
+            PermissionForge::Audit::Runtime::DENIED, reason: reason, model: self, via: 'find_by',
                                                      user: current_user, record_id: record_id,
-                                                     data: { 'messages' => failure_messages }
+                                                     data: { 'messages' => messages }
+          )
+          raise NotAuthorizedError.new(messages, user: current_user, record_id: record_id, failure_messages: failure_messages)
+        end
+
+        # What the applier answered: the failure messages and what each
+        # denying rule says on its own.
+        def pf_rule_denial(messages, denying_rules)
+          [:rule, messages, denying_rules.map { |rule| PermissionForge::Services::PermissionRuleApplier.failure_message_for(rule) }]
+        end
+
+        # The user's entries along the chain do not grant read_access, under
+        # no_read_access_strategy :deny: one message, from the locale.
+        def pf_no_read_access_denial
+          message = PermissionForge::RecordReadAccess.failure_message(self)
+          [PermissionForge::RecordReadAccess::REASON, [message], [message]]
+        end
+
+        # RecordReadAccess, the one definition.
+        def pf_no_read_access?(current_user)
+          PermissionForge::RecordReadAccess.denied?(current_user, self)
+        end
+
+        # permission_scoped for a user denied by RecordReadAccess: no rows,
+        # published as access.denied (no_read_access).
+        def pf_no_read_access_scope(current_user)
+          PermissionForge::Audit::Runtime.denied(
+            PermissionForge::Audit::Runtime::DENIED,
+            reason: PermissionForge::RecordReadAccess::REASON, model: self, via: 'permission_scoped', user: current_user
           )
-          raise NotAuthorizedError.new(failure_messages, user: current_user, record_id: record_id)
+          none
         end
 
         # The id of the row the rules denied, for access.denied and the error:

data/lib/permission_forge/concerns/permissioned_user.rb

@@ -57,7 +57,7 @@ module PermissionForge
       # With no tenant ambient the associations above reached every row.
       def pf_destroy_permission_rows_in_other_tenants
         config = PermissionForge.configuration
-        return unless config.tenant_enabled? && defined?(::ActsAsTenant) && ::ActsAsTenant.current_tenant
+        return unless PermissionForge.ambient_tenant
 
         [PermissionForge::PermissionSetUser, PermissionForge::PermissionSetGroupUser].each do |model|
           model.unscoped.where(user_id: id).find_each do |row|