parse-stack-next 5.8.0 → 5.8.1

data/docs/webhooks_guide.md

@@ -284,13 +284,65 @@ database untouched. When the handler changed fields, the reply is the client's
 full write with your changes layered on top: operators on fields you did not
 touch are passed through as operators, fields the model does not declare (and
 `_User` signup fields such as `password` and `authData`) are kept, and a field
-you set back to its stored value is dropped from the write. Two limits come
-from what Parse Server sends the webhook: a field you rewrite is written as an
-absolute value, and an operator on a dotted sub-key (`"meta.count"`) arrives
-only as its resulting sub-document and is written back that way. Edits made
-in place on `parse_object` count even if the handler returns `true`. On a
-create, returning `parse_object` also writes the model's declared defaults
-(including its default ACL) for fields the client did not send.
+you set back to its stored value is dropped from the write. A field you
+rewrite is written as an absolute value. Edits made in place on `parse_object`
+count even if the handler returns `true`.
+
+An operator on a dotted sub-key (`"meta.count"`) arrives only as its resulting
+sub-document, so on an update the SDK writes back just the sub-keys that
+changed, as dotted paths, and a removed sub-key as a `Delete`. The split is one
+level deep: a changed sub-key is written whole at `field.sub`, nested objects
+included, because Parse Server rebuilds the afterSave object from a dotted key
+only one level deep. Concurrent writes to other sub-keys of the field survive.
+Some limits remain:
+
+- Two concurrent writes inside the same sub-key can still overwrite each
+  other, including two operators on deeper paths under it
+  (`meta.count.value` and `meta.count.other`).
+- An array is written whole, so a concurrent `Add` to an array inside a
+  sub-document is lost.
+- When a changed sub-key would carry a typed value (a Date, Bytes, Pointer, or
+  other `__type` value), the whole field is written instead, because Parse
+  Server stores a dotted typed value without converting it. Unchanged typed
+  values and deletes do not trigger this.
+- A client that replaces a whole sub-document gets a merge: the changed
+  sub-keys are written and the sub-keys it knew about and removed are
+  deleted, so a sub-key another request added in the meantime survives.
+- Parse Server reports the reply's dotted keys back to the client in the save
+  response. The JavaScript SDK applies them; other clients may need to fetch
+  the object to see the merged value.
+- A dotted key in a Hash the handler returns (`{ "meta.y" => 5 }`) is folded
+  into the parent path the reply writes whole. A key deeper than one level
+  (`"meta.count.value"`) is folded into a `meta.count` write built from the
+  pending object, and on a create every dotted key folds into its whole
+  field. An operator folded this way (`{"__op" => "Increment"}`, `Add`,
+  `AddUnique`, `Remove`, `Delete`) is applied to the value it replaces; an
+  operator that cannot be applied there, or two of your own keys that
+  conflict (`"meta.a" => 5` with `"meta.a.b" => 6`), fails the save with an
+  error. Hash keys may use Ruby names (`acl:`); they are mapped to the
+  stored field names.
+
+On a create, returning `parse_object` also writes the model's declared
+defaults for fields the client did not send, including its ACL policy. Parse
+Server stores a create without an `ACL` as public read and write, so the reply
+always carries the ACL your policy resolves, exactly as an SDK-side create
+would. Owner-based policies (`:owner_else_private`, the default, as well as
+`:owner_else_public` and `:owner_but_public_read`) take the owner from the
+declared `owner:` field and, when that is empty, from the user who made the
+request, so a signed-in client owns what it creates. A request without a user
+gets the policy's fallback (master-key only under `:owner_else_private`), and so
+does a master-key request. A `_User` class declared with `owner: :self` is
+owned by the new user, never by the requester: the reply carries the policy's
+ACL without an owner entry and Parse Server adds the new user's own read and
+write. An ACL the client sent is kept, and an ACL the handler sets always
+wins, whether through `acl=` or mass assignment. A `guard :acl, :master_only`
+revert on a create returns the ACL to the class policy rather than to `{}`.
+Built-in classes such as `_User` that have no policy of their own keep Parse
+Server's defaults. A handler that returns `true`, `nil`, or a Hash keeps the client's
+write as sent, so a create without an ACL stays public; return
+`parse_object` to apply the policy. An ACL the handler assigns on
+`parse_object` (`parse_object.acl = Parse::ACL.new`) is written whatever the
+handler returns, unless a returned Hash sets `ACL` itself.
 
 `after_destroy` callbacks run in the `after_delete` handler (once per delivery,
 skipped for deletes the SDK itself made, whose callbacks already ran locally).

data/lib/parse/acl_scope.rb

@@ -74,13 +74,32 @@ module Parse
     #     agree; see {Parse::MongoDB.verify_client!}. Per-client
     #     authorization plus a process-global MongoDB connection is safe only
     #     when they belong to the same application.
-    Resolution = Struct.new(:mode, :permission_strings, :user_id, :session, :strict_role, :client, keyword_init: true) do
+    # @!attribute master_dropped
+    #   @return [Boolean, nil] `true` when the caller asked for `master: true`
+    #     inside {Parse.without_master_key} and the call was downgraded to
+    #     the public scope. Reported on the `parse.mongodb.aggregate`
+    #     notification so a master-key caller that sees only public rows
+    #     inside the block can be diagnosed.
+    Resolution = Struct.new(:mode, :permission_strings, :user_id, :session, :strict_role, :client,
+                            :master_dropped, keyword_init: true) do
       def master?; mode == :master; end
       def session?; mode == :session; end
       def public?; mode == :public; end
       def strict_role?; strict_role == true; end
+      def master_dropped?; master_dropped == true; end
     end
 
+    # SDK-internal value for `master:` on calls that read metadata, not rows
+    # (index statistics, the Atlas Search index listing). It resolves to
+    # master mode even inside {Parse.without_master_key}, which governs row
+    # access. Unlike wrapping the call in {Parse.with_master_key}, it changes
+    # no fiber state, so notification subscribers and threads started during
+    # the call still see the caller's block.
+    # @!visibility private
+    METADATA_MASTER = Object.new.tap do |o|
+      def o.inspect = "#<Parse::ACLScope::METADATA_MASTER>"
+    end.freeze
+
     # The client a resolution was produced by, or nil when it cannot say.
     #
     # Deliberately tolerant of objects that are resolution-shaped without
@@ -125,6 +144,12 @@ module Parse
       #   `master: true` are supplied — they are mutually exclusive.
       # @raise [ACLRequired] when neither is supplied and
       #   {.require_session_token} is `true`.
+      #
+      # Inside a {Parse.without_master_key} block an explicit `master: true`
+      # is dropped and the call runs in the public scope, as a REST request
+      # does once the block strips its master key. With
+      # {.require_session_token} set, the dropped call raises {ACLRequired}
+      # instead. A nested {Parse.with_master_key} block restores master mode.
       def resolve!(options, method_name:)
         session_token = options.delete(:session_token)
         master = options.delete(:master)
@@ -140,6 +165,10 @@ module Parse
         # the legacy behavior.
         strict_role = options.delete(:strict_role) == true
 
+        # SDK metadata reads keep master mode whatever the block says.
+        metadata_master = master.equal?(METADATA_MASTER)
+        master = true if metadata_master
+
         provided = [session_token, master == true ? master : nil, acl_user, acl_role].compact
         if provided.length > 1
           raise ArgumentError,
@@ -147,6 +176,12 @@ module Parse
                 "session_token:, master: true, acl_user:, or acl_role:. Pick one."
         end
 
+        # `Parse.without_master_key` strips the master key from every REST
+        # request in the block, an explicit `use_master_key: true` included.
+        # A direct read must not keep master authority the REST call loses.
+        master_dropped = master == true && !metadata_master && master_key_suppressed?
+        master = nil if master_dropped
+
         if acl_user
           # Pre-resolved User-pointer path used by
           # Parse::Query#scope_to_user. Mirrors the session-token path
@@ -186,6 +221,18 @@ module Parse
                                 client: authorization_client(options))
         end
 
+        if master_dropped
+          if @require_session_token == true
+            raise ACLRequired,
+                  "Parse::#{method_name} was called with master: true inside " \
+                  "Parse.without_master_key, which drops master mode, and " \
+                  "Parse::ACLScope.require_session_token refuses the public " \
+                  "fallback. Pass session_token:, or run the call inside " \
+                  "Parse.with_master_key if it needs master authority."
+          end
+          return public_resolution(options, master_dropped: true)
+        end
+
         if @require_session_token == true
           raise ACLRequired,
                 "Parse::#{method_name} requires session_token: or master: true. " \
@@ -196,14 +243,7 @@ module Parse
         end
 
         warn_no_acl_context_once!(method_name)
-        anonymous = Parse::Authorization::Resolved.new(nil, Set.new)
-        Resolution.new(
-          mode: :public,
-          permission_strings: anonymous.permission_strings,
-          user_id: nil,
-          session: anonymous,
-          client: authorization_client(options),
-        )
+        public_resolution(options)
       end
 
       # Compile the `_rperm` `$match` stage to prepend to a mongo-direct
@@ -845,8 +885,30 @@ module Parse
         @warned_malformed_rperm_classes = Set.new
       end
 
+      # Whether an explicit `master: true` must be dropped: true inside a
+      # {Parse.without_master_key} block that no nested
+      # {Parse.with_master_key} has re-enabled.
+      # @!visibility private
+      # @return [Boolean]
+      def master_key_suppressed?
+        Parse.respond_to?(:master_key_disabled?) && Parse.master_key_disabled?
+      end
+
       private
 
+      # The anonymous public-scope resolution: `"*"` grants only.
+      def public_resolution(options, master_dropped: nil)
+        anonymous = Parse::Authorization::Resolved.new(nil, Set.new)
+        Resolution.new(
+          mode: :public,
+          permission_strings: anonymous.permission_strings,
+          user_id: nil,
+          session: anonymous,
+          client: authorization_client(options),
+          master_dropped: master_dropped,
+        )
+      end
+
       # Emit the once-per-process security banner the first time a
       # mongo-direct path runs without `session_token:` and without
       # `master: true`. Mirrors {Parse::AtlasSearch}'s warned-once

data/lib/parse/agent/describe.rb

@@ -176,7 +176,8 @@ module Parse
           tenant_id: tenant_id,
           classes: filter_descriptor(@class_filter_only, @class_filter_except),
           tools: tools_descriptor,
-          methods: filter_descriptor(@method_filter_only, @method_filter_except, transform: ->(s) { s.to_s }),
+          methods: filter_descriptor(@method_filter_only, @method_filter_except, transform: ->(s) { s.to_s })
+            .merge(layers: method_filter_layers_descriptor),
           filters: per_agent_filters_summary,
           hidden_classes: Parse::Agent::MetadataRegistry.hidden_class_names,
           per_class: per_class_descriptor,
@@ -383,10 +384,15 @@ module Parse
         lines << "    except:    #{data[:tools][:except].inspect}" if data[:tools][:except]
         lines << "    effective: #{data[:tools][:effective].inspect}"
 
-        if data[:methods][:only] || data[:methods][:except]
+        inherited_layers = Array(data[:methods][:layers])[0...-1] if data[:methods][:only] || data[:methods][:except]
+        inherited_layers ||= Array(data[:methods][:layers])
+        if data[:methods][:only] || data[:methods][:except] || inherited_layers.any?
           lines << "  methods:"
           lines << "    only:    #{data[:methods][:only].inspect}" if data[:methods][:only]
           lines << "    except:  #{data[:methods][:except].inspect}" if data[:methods][:except]
+          inherited_layers.each do |layer|
+            lines << "    inherited: #{layer.compact.inspect}"
+          end
         end
 
         if data[:filters]

data/lib/parse/agent/mcp_dispatcher.rb

@@ -229,7 +229,14 @@ module Parse
         # token.
         prev_progress_callback = agent.progress_callback if agent.respond_to?(:progress_callback)
         prev_cancellation_token = agent.cancellation_token if agent.respond_to?(:cancellation_token)
-        prev_approval_gate = agent.approval_gate if agent.respond_to?(:approval_gate)
+        # Snapshot the agent's OWN gate, not the effective one: a sub-agent
+        # with no gate of its own reads its parent's, and restoring that
+        # copy would pin it and stop the delegation.
+        prev_approval_gate = if agent.respond_to?(:approval_gate_override)
+            agent.approval_gate_override
+          elsif agent.respond_to?(:approval_gate)
+            agent.approval_gate
+          end
         prev_log_callback = agent.log_callback if agent.respond_to?(:log_callback)
 
         # Install the progress callback and cancellation token on the

data/lib/parse/agent.rb

@@ -1035,11 +1035,35 @@ module Parse
     #   `progress_callback` / `cancellation_token` are threaded. An
     #   embedder on the non-MCP path may assign any object responding to
     #   `#review`.
+    #
+    #   A sub-agent built with `parent:` and no gate of its own uses its
+    #   parent's gate, read at call time: the dispatcher swaps the
+    #   parent's gate per request, so a copy taken at construction would
+    #   go stale. Without this a sub-agent fell back to {NullGate} and
+    #   ran tools in `require_approval_for` tiers with no approval.
     def approval_gate
-      @approval_gate ||= Parse::Agent::NullGate.new
+      return @approval_gate if @approval_gate
+      return @approval_parent.approval_gate if @approval_parent
+      @approval_gate_defaulted = true
+      @approval_gate = Parse::Agent::NullGate.new
+    end
+
+    # Assign this agent's own approval gate. Assigning nil removes it, so
+    # a sub-agent goes back to using its parent's gate.
+    def approval_gate=(gate)
+      @approval_gate_defaulted = false
+      @approval_gate = gate
     end
 
-    attr_writer :approval_gate
+    # @return [Parse::Agent::ApprovalGate, nil] the gate assigned on this
+    #   agent itself, or nil when it uses its parent's (or the default).
+    #   The MCP dispatcher snapshots and restores this rather than
+    #   {#approval_gate}, so restoring never pins a parent's gate.
+    # @api private
+    def approval_gate_override
+      gate = @approval_gate
+      gate.is_a?(Parse::Agent::NullGate) && @approval_gate_defaulted ? nil : gate
+    end
 
     # @return [Boolean] true if the active cancellation token has been
     #   tripped; false otherwise. Returns false when no token is
@@ -1736,8 +1760,10 @@ module Parse
         #
         #   * nil    — inherit from parent (the common case; the
         #              child wants whatever the parent had).
-        #   * true   — explicit opt-in (caller wants faceted_search
-        #              authority regardless of parent).
+        #   * true:  keep faceted_search authority. Allowed only when
+        #              the parent has it: a child cannot turn on
+        #              master-key faceting under a scoped parent, which
+        #              would return every row's buckets and results.
         #   * false  — explicit opt-OUT: the sub-agent should DROP
         #              faceted_search authority even if the parent
         #              had it. Previously `false` was the default
@@ -1753,6 +1779,13 @@ module Parse
         # per-row ACL via Parse::ACLScope's `_rperm` match and do
         # NOT consult master_atlas.
         master_atlas = parent.master_atlas if master_atlas.nil?
+        if master_atlas == true && !parent.master_atlas
+          raise ArgumentError,
+                "sub-agent master_atlas: true exceeds parent's master_atlas: false. " \
+                "A sub-agent cannot turn on master-key Atlas faceting its parent " \
+                "was not given. Omit master_atlas to inherit the parent's setting, " \
+                "or pass master_atlas: false."
+        end
 
         # Inherit cooperative cancellation surface. Without this, a
         # delegating tool that constructs a sub-agent and drives it
@@ -1764,6 +1797,9 @@ module Parse
         @cancellation_token = parent.cancellation_token
         @progress_callback = parent.progress_callback
         @log_callback = parent.log_callback
+        # Approval gate: delegate to the parent's current gate (see
+        # {#approval_gate}).
+        @approval_parent = parent
 
         # Clamp the sub-agent's permission tier at the parent's. The
         # default :readonly is always ≤ any parent tier, so this fires
@@ -2054,8 +2090,63 @@ module Parse
           Parse::AggregationResult.normalize_field_names!(field_names)
         end
 
-      # Sub-agent class-filter inheritance. Unlike `tools:` (which overrides
-      # outright), `classes:` clamps to the parent's effective set so a
+      # Sub-agent `tools:` inheritance: narrow only, same rule as `classes:`
+      # below. Intersect onlies, union excepts. A child `only:` that leaves
+      # nothing once the parent's allowlist and excepts apply raises; an
+      # explicitly empty `only: []` is the strictest narrowing and is kept.
+      if parent
+        parent_tools_only = parent.instance_variable_get(:@tool_filter_only)
+        parent_tools_except = parent.instance_variable_get(:@tool_filter_except)
+        requested_tools = @tool_filter_only
+        if parent_tools_only && @tool_filter_only
+          @tool_filter_only = (@tool_filter_only & parent_tools_only).freeze
+        elsif parent_tools_only
+          @tool_filter_only = parent_tools_only
+        end
+        if parent_tools_except
+          @tool_filter_except = (@tool_filter_except ? (@tool_filter_except | parent_tools_except) : parent_tools_except).freeze
+        end
+        if requested_tools && !requested_tools.empty? &&
+           (parent_tools_only || parent_tools_except)
+          reachable = @tool_filter_only - (@tool_filter_except || Set.new)
+          if reachable.empty?
+            raise ArgumentError,
+                  "sub-agent tools: { only: } would have no overlap with the parent's " \
+                  "tools: filter (parent only: #{parent_tools_only&.to_a&.sort.inspect}, " \
+                  "except: #{parent_tools_except&.to_a&.sort.inspect}; the child requested " \
+                  "#{requested_tools.to_a.sort.inspect}). A sub-agent cannot enable tools its " \
+                  "parent was not given. Pass a subset of the parent's tools, or omit tools: " \
+                  "to inherit the parent's filter."
+          end
+        end
+      end
+
+      # Sub-agent `methods:` inheritance. Entries can be bare (`:archive`) or
+      # qualified (`"Post.archive"`), so plain set intersection would get the
+      # matching wrong. Instead the parent's filters are kept as layers and
+      # {#method_filtered?} refuses a call any layer refuses. A child
+      # `only:` that no parent layer could permit raises; an explicitly
+      # empty `only: []` is kept.
+      @method_filter_layers = (parent ? parent.method_filter_layers : []).dup
+      if parent && @method_filter_only && !@method_filter_only.empty? && !@method_filter_layers.empty?
+        reachable = @method_filter_only.any? do |entry|
+          @method_filter_layers.all? { |layer_only, layer_except| method_entry_reachable?(entry, layer_only, layer_except) }
+        end
+        unless reachable
+          raise ArgumentError,
+                "sub-agent methods: { only: } would have no overlap with the parent's " \
+                "methods: filter (child requested #{@method_filter_only.to_a.map(&:to_s).sort.inspect}). " \
+                "A sub-agent cannot call agent methods its parent was not given. Pass a " \
+                "subset of the parent's methods, or omit methods: to inherit them."
+        end
+      end
+      if @method_filter_only || @method_filter_except
+        @method_filter_layers << [@method_filter_only, @method_filter_except].freeze
+      end
+      @method_filter_layers.freeze
+
+      # Sub-agent class-filter inheritance. Like `tools:` above,
+      # `classes:` clamps to the parent's effective set so a
       # sub-agent can NEVER widen its parent's data-reach. Intersect onlies,
       # union excepts. A child `only:` that would have no overlap with the
       # parent's effective set raises at construction — empty-onlyset means
@@ -2253,29 +2344,77 @@ module Parse
     #
     # An entry matches the invocation if it equals either the bare
     # method name (`:archive`) or the qualified form (`"Class.archive"`).
+    # The class part is compared by its Parse class name on both sides, so
+    # `"User.reset"` and `"_User.reset"` name the same method whichever
+    # spelling the entry or the caller used.
     #
     # @param method_name [Symbol, String]
     # @param class_name  [String]
     # @return [Boolean] true if filtered (refuse), false if permitted
     def method_filtered?(method_name, class_name:)
-      return false if @method_filter_only.nil? && @method_filter_except.nil?
-
       method_sym = method_name.to_sym
-      qualified = "#{class_name}.#{method_name}"
+      parse_class = Parse::Agent.canonical_method_class(class_name)
 
-      if @method_filter_only
-        permitted = @method_filter_only.include?(method_sym) ||
-                    @method_filter_only.include?(qualified)
-        return true unless permitted
+      # A sub-agent carries its parent's filters as earlier layers; its own
+      # filter is the last layer. Any layer can refuse.
+      method_filter_layers.any? do |only, except|
+        (only && !method_entry_matches?(only, method_sym, parse_class)) ||
+          (except && method_entry_matches?(except, method_sym, parse_class))
       end
+    end
 
-      if @method_filter_except
-        excluded = @method_filter_except.include?(method_sym) ||
-                   @method_filter_except.include?(qualified)
-        return true if excluded
-      end
+    # The Parse class name for the class part of a qualified `methods:`
+    # entry or a `call_method` class argument: `"User"` and `"_User"`
+    # both give `"_User"`. A name that resolves to no model is returned
+    # unchanged.
+    # @api private
+    # @param name [String, Class]
+    # @return [String]
+    def self.canonical_method_class(name)
+      return name.parse_class if name.is_a?(Class) && name.respond_to?(:parse_class)
+      str = name.to_s
+      klass = resolve_method_filter_class(str)
+      klass ? klass.parse_class : str
+    end
 
-      false
+    # Ruby constant names a `methods:` entry may use for a model whose Parse
+    # class name differs (`class Artist < Parse::Object; parse_class
+    # "Musician"; end`).
+    RUBY_CONSTANT_NAME_RE = /\A[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*\z/
+
+    # @!visibility private
+    # The Parse::Object subclass a `methods:` class name refers to, by
+    # Parse class name first and then by Ruby constant name, or nil.
+    def self.resolve_method_filter_class(str)
+      klass = begin
+          Parse::Model.find_class(str)
+        rescue StandardError
+          nil
+        end
+      return klass if klass.is_a?(Class) && klass < Parse::Object
+      return nil unless str.match?(RUBY_CONSTANT_NAME_RE)
+      klass = begin
+          Object.const_get(str)
+        rescue StandardError, LoadError
+          nil
+        end
+      klass.is_a?(Class) && klass < Parse::Object ? klass : nil
+    end
+
+    # @return [Array<Array(Set, Set)>] the `methods:` filters in effect as
+    #   `[only, except]` pairs, own filter last; a sub-agent carries its
+    #   parent's layers first.
+    def method_filter_layers
+      @method_filter_layers || []
+    end
+
+    # @return [Array<Hash>] {#method_filter_layers} as `{only:, except:}`
+    #   hashes of sorted name strings (nil when a layer has no such list),
+    #   parent layers first. Used by the audit payload and {#describe}.
+    def method_filter_layers_descriptor
+      method_filter_layers.map do |only, except|
+        { only: only && only.to_a.map(&:to_s).sort, except: except && except.to_a.map(&:to_s).sort }
+      end
     end
 
     # @return [Boolean] whether unknown names in tools: raise vs. warn at
@@ -2507,6 +2646,15 @@ module Parse
       payload[:tools_except] = @tool_filter_except.to_a.sort if @tool_filter_except
       payload[:methods_only] = @method_filter_only.to_a.map(&:to_s).sort if @method_filter_only
       payload[:methods_except] = @method_filter_except.to_a.map(&:to_s).sort if @method_filter_except
+      # `methods_only` / `methods_except` are this agent's own filter. A
+      # sub-agent is also bound by its parent's filters, so the full set in
+      # force is emitted as layers (parent first) whenever any layer was
+      # inherited, including a single parent layer on a child with no
+      # filter of its own.
+      own_method_layers = (@method_filter_only || @method_filter_except) ? 1 : 0
+      if method_filter_layers.size > own_method_layers
+        payload[:methods_layers] = method_filter_layers_descriptor
+      end
       # Per-agent per-class filters — emit class-name → field-name list,
       # NOT the constraint values. Filter values can contain user-identifying
       # data (`{ user_id: "abc123" }`, `{ org_id: tenant_uuid }`) that
@@ -3393,7 +3541,44 @@ module Parse
     # strings (qualified-class.method match).
     def normalize_method_filter_entry(value)
       str = value.to_s
-      str.include?(".") ? str : str.to_sym
+      return str.to_sym unless str.include?(".")
+      class_part, method_part = str.split(".", 2)
+      if Parse::Agent.resolve_method_filter_class(class_part).nil?
+        warn "[Parse::Agent] methods: entry #{str.inspect} names a class that does not " \
+             "resolve to a loaded Parse::Object model (by Parse class name or Ruby " \
+             "constant). It is matched by its class part as written; check the spelling."
+      end
+      "#{Parse::Agent.canonical_method_class(class_part)}.#{method_part}"
+    end
+
+    # Whether a `methods:` filter set names this invocation, either bare or
+    # qualified. Qualified entries are compared by Parse class name, which
+    # also covers an entry whose class was not loaded at construction.
+    def method_entry_matches?(set, method_sym, parse_class)
+      return true if set.include?(method_sym) || set.include?("#{parse_class}.#{method_sym}")
+      set.any? do |entry|
+        next false unless entry.is_a?(String)
+        class_part, method_part = entry.split(".", 2)
+        method_part == method_sym.to_s && Parse::Agent.canonical_method_class(class_part) == parse_class
+      end
+    end
+
+    # Whether a child `methods:` only-entry could pass one parent layer.
+    # A qualified entry ("Post.archive") passes when the layer names it or
+    # its bare method. A bare entry (:archive) passes when the layer names
+    # it bare or qualified on any class.
+    def method_entry_reachable?(entry, layer_only, layer_except)
+      if entry.is_a?(String)
+        bare = entry.split(".", 2).last.to_sym
+        return false if layer_except && (layer_except.include?(entry) || layer_except.include?(bare))
+        return true unless layer_only
+        layer_only.include?(entry) || layer_only.include?(bare)
+      else
+        return false if layer_except&.include?(entry)
+        return true unless layer_only
+        layer_only.include?(entry) ||
+          layer_only.any? { |e| e.is_a?(String) && e.split(".", 2).last == entry.to_s }
+      end
     end
 
     # Normalize the constructor's `classes:` kwarg into a [only_set,

data/lib/parse/atlas_search/index_manager.rb

@@ -65,7 +65,11 @@ module Parse
             # `master: true` so the SDK's CLP layer skips this metadata
             # pipeline. The mongo-side privilege check still applies
             # (the underlying connection must hold `listSearchIndexes`).
-            results = Parse::MongoDB.aggregate(collection_name, pipeline, master: true)
+            # The metadata sentinel keeps that master mode inside a
+            # `Parse.without_master_key` block, which governs row access,
+            # without re-enabling the master key for anything else.
+            results = Parse::MongoDB.aggregate(collection_name, pipeline,
+                                               master: Parse::ACLScope::METADATA_MASTER)
             cache_mutex.synchronize { cache_indexes(collection_name, results) }
             results
           rescue => e

data/lib/parse/atlas_search.rb

@@ -559,6 +559,7 @@ module Parse
         unless resolution.master?
           acl_match = Parse::ACLScope.match_stage_for(resolution)
           pipeline << acl_match if acl_match
+          pipeline << pointer_fields_match_stage(pointer_fields, resolution) if pointer_fields
         end
 
         # Add filter if provided
@@ -660,6 +661,17 @@ module Parse
                 "accept that bucket counts include all rows, or use " \
                 "#search for ACL-scoped results without facets."
         end
+        # Inside Parse.without_master_key the only scope left is public,
+        # and $searchMeta bucket counts are not ACL-filtered there either,
+        # so they would count rows the block is meant to hide. Fail closed.
+        if Parse::ACLScope.master_key_suppressed?
+          raise FacetedSearchNotACLSafe,
+                "Parse::AtlasSearch.faceted_search cannot run inside " \
+                "Parse.without_master_key: $searchMeta bucket counts include " \
+                "rows the caller cannot read. Wrap the call in " \
+                "Parse.with_master_key to accept master-key counts, or use " \
+                "#search for ACL-scoped results without facets."
+        end
         # Wave-3b READPREF-4: see #search for rationale. Captured
         # before resolve_scope! pops the auth kwargs so the recursive
         # search() call below can re-thread it explicitly (resolve!
@@ -815,6 +827,7 @@ module Parse
         unless resolution.master?
           acl_match = Parse::ACLScope.match_stage_for(resolution)
           pipeline << acl_match if acl_match
+          pipeline << pointer_fields_match_stage(pointer_fields, resolution) if pointer_fields
         end
 
         # Caller-supplied filter, sanitized against operator injection
@@ -851,6 +864,8 @@ module Parse
         unless resolution.master?
           Parse::ACLScope.redact_results!(raw_results, resolution)
           Parse::CLPScope.redact_protected_fields!(raw_results, protected_fields) if protected_fields.any?
+          # The pointerFields `$match` above already ran before `$limit`;
+          # this re-check is defense in depth and should drop nothing.
           if pointer_fields
             raw_results = Parse::CLPScope.filter_by_pointer_fields(
               raw_results, pointer_fields, resolution.user_id,
@@ -972,13 +987,37 @@ module Parse
           return Parse::ACLScope.resolve_for_role(acl_role, client: auth_client)
         end
 
-        if master == true
+        if master == true && !Parse::ACLScope.master_key_suppressed?
           return Parse::ACLScope::Resolution.new(
                    mode: :master, permission_strings: nil, user_id: nil, session: nil,
                    client: auth_client,
                  )
         end
 
+        # Inside `Parse.without_master_key` an explicit master request runs
+        # in the public scope, as Parse::ACLScope.resolve! does: no
+        # no-ACL banner (the caller did pass a scope), and either strict
+        # flag refuses the fallback.
+        if master == true
+          if @require_session_token == true || Parse::ACLScope.require_session_token == true
+            raise ACLRequired,
+                  "Parse::AtlasSearch.#{method_name} was called with master: true " \
+                  "inside Parse.without_master_key, which drops master mode, and " \
+                  "require_session_token refuses the public fallback. Pass " \
+                  "session_token:, or run the call inside Parse.with_master_key " \
+                  "if it needs master authority."
+          end
+          anonymous = Session::Resolved.new(nil, Set.new)
+          return Parse::ACLScope::Resolution.new(
+                   mode: :public,
+                   permission_strings: anonymous.permission_strings,
+                   user_id: nil,
+                   session: anonymous,
+                   client: auth_client,
+                   master_dropped: true,
+                 )
+        end
+
         if @require_session_token == true
           raise ACLRequired,
                 "Parse::AtlasSearch.#{method_name} requires session_token: or " \
@@ -1037,6 +1076,15 @@ module Parse
                                             label: "Atlas Search")
       end
 
+      # The pointerFields / readUserFields ownership constraint as a
+      # `$match` stage, placed after the ACL `$match` and before `$sort` /
+      # `$limit`. Filtering the fetched rows afterwards returned short or
+      # empty pages whenever the top-ranked hits belonged to other users,
+      # even though eligible matches ranked below them.
+      def pointer_fields_match_stage(pointer_fields, resolution)
+        { "$match" => Parse::CLPScope.pointer_fields_predicate(pointer_fields, resolution.user_id) }
+      end
+
       # ATLAS-4: refuse `highlight_field:` when the field is in the
       # resolved protectedFields set. searchHighlights returns the
       # matched token plus surrounding chars verbatim; running it on