parse-stack-next 5.7.6 → 5.8.0

data/lib/parse/agent.rb

@@ -23,6 +23,8 @@ require_relative "agent/rate_limiter"
 require_relative "agent/cancellation_token"
 require_relative "agent/log_levels"
 require_relative "agent/approval_gate"
+require_relative "agent/field_policy"
+require_relative "agent/field_names"
 require_relative "agent/prompt_hardening"
 require_relative "agent/describe"
 
@@ -592,8 +594,10 @@ module Parse
         # Use provided port, or configured port, or default
         port ||= Parse.mcp_server_port || 3001
 
-        @mcp_enabled = true
+        # Load the server before flagging MCP as enabled, so a failed load
+        # does not leave mcp_enabled? reporting true.
         require_relative "agent/mcp_server"
+        @mcp_enabled = true
         MCPServer.default_port = port
 
         # Pass remote API config if available
@@ -1559,6 +1563,7 @@ module Parse
                    max_log_size: DEFAULT_MAX_LOG_SIZE,
                    system_prompt: nil, system_prompt_suffix: nil, pricing: nil,
                    tools: nil, methods: nil, classes: nil, filters: nil,
+                   fields: nil, field_names: nil,
                    parent: nil, recursion_depth: nil,
                    strict_tool_filter: nil, strict_class_filter: nil,
                    master_atlas: nil,
@@ -2033,6 +2038,21 @@ module Parse
       @method_filter_only, @method_filter_except = normalize_method_filter(methods)
       @class_filter_only, @class_filter_except = normalize_class_filter(classes)
       @filters = normalize_query_filters(filters)
+      # Per-agent field narrowing (see Parse::Agent::FieldPolicy). Stored as
+      # layers so a sub-agent's policy INTERSECTS its parent's: every layer
+      # that names a class must permit a field for the agent to see it.
+      own_field_policy = normalize_field_policy(fields)
+      @field_policy_layers = (parent ? parent.field_policy_layers : []) +
+                             (own_field_policy ? [own_field_policy] : [])
+      @field_policy_layers.freeze
+      # Data-field naming mode (see Parse::Agent::FieldNames). A sub-agent
+      # inherits its parent's mode unless it sets one; naming never affects
+      # the access restrictions inherited above.
+      @field_names_mode = if field_names.nil?
+          parent ? parent.field_names_mode : :default
+        else
+          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
@@ -3428,6 +3448,49 @@ module Parse
     # lookup re-expands the variants and accepts both forms symmetrically.
     #
     # @return [Hash, nil] frozen Hash or nil when no filters declared
+    # Normalize the constructor's `fields:` kwarg: a Hash mapping class
+    # identifiers (Class, String, Symbol, or :default) to an Array of field
+    # names. Keys canonicalize like `filters:` so `Parse::User` matches both
+    # "_User" and "User". Field names may be Ruby property names or wire
+    # names; they are translated to wire form at lookup time.
+    def normalize_field_policy(fields)
+      return nil if fields.nil?
+      unless fields.is_a?(Hash)
+        raise ArgumentError,
+              "fields: must be a Hash mapping class identifiers (or :default) " \
+              "to Arrays of field names, got #{fields.class}"
+      end
+      result = {}
+      fields.each do |key, names|
+        unless names.is_a?(Array) && names.all? { |n| n.is_a?(String) || n.is_a?(Symbol) }
+          raise ArgumentError,
+                "fields[#{key.inspect}]: value must be an Array of field names, got #{names.inspect}"
+        end
+        field_policy_keys(key).each { |canon| result[canon] = names.map(&:to_s).freeze }
+      end
+      result.freeze
+    end
+
+    # Canonical lookup names for a `fields:` key. Tools look policies up by
+    # the class's Parse name (`_User`, or a custom `parse_class`), so a
+    # String or Symbol key is resolved through Parse::Model.find_class to
+    # that name as well as kept verbatim; otherwise `fields: { "User" => ... }`
+    # would silently fail to narrow `_User`.
+    def field_policy_keys(key)
+      keys = canonical_filter_key(key)
+      if key.is_a?(String) || key.is_a?(Symbol)
+        klass = (Parse::Model.find_class(key.to_s) rescue nil)
+        if klass.respond_to?(:parse_class)
+          keys |= [klass.parse_class.to_s]
+          if defined?(Parse::Agent::MetadataRegistry) &&
+             Parse::Agent::MetadataRegistry.respond_to?(:hidden_name_variants_for)
+            keys |= Parse::Agent::MetadataRegistry.hidden_name_variants_for(klass)
+          end
+        end
+      end
+      keys
+    end
+
     def normalize_query_filters(filters)
       return nil if filters.nil?
       unless filters.is_a?(Hash)
@@ -3567,6 +3630,35 @@ module Parse
     #
     # @param class_name [String, Symbol, Class]
     # @return [Boolean]
+    # @return [Array<Hash>] the per-agent `fields:` policies in effect, own
+    #   policy last; a sub-agent carries its parent's layers first. Each
+    #   layer maps a canonical class name (or :default) to raw field names.
+    attr_reader :field_policy_layers
+
+    # @return [Symbol] `:default` or `:server`; see {Parse::Agent::FieldNames}.
+    attr_reader :field_names_mode
+
+    # Wire-format field names this agent narrows `class_name` to, or nil when
+    # no `fields:` layer names the class (or a :default). Every layer that
+    # applies must permit a field, so a sub-agent can never widen its
+    # parent. The result is intersected with the class's `agent_fields`
+    # ceiling by {Parse::Agent::MetadataRegistry.field_allowlist}.
+    #
+    # @param class_name [String, Class]
+    # @return [Array<String>, nil]
+    def field_narrowing_for(class_name)
+      return nil if @field_policy_layers.nil? || @field_policy_layers.empty?
+      cn = class_name.respond_to?(:parse_class) ? class_name.parse_class.to_s : class_name.to_s
+      result = nil
+      @field_policy_layers.each do |layer|
+        names = layer[cn] || layer[:default]
+        next if names.nil?
+        wire = Parse::Agent::MetadataRegistry.wire_field_names(cn, names)
+        result = result ? (result & wire) : wire
+      end
+      result
+    end
+
     def class_filter_permits?(class_name)
       return true if @class_filter_only.nil? && @class_filter_except.nil?
       candidates = class_name_variants_for(class_name)

data/lib/parse/api/batch.rb

@@ -26,7 +26,16 @@ module Parse
           batch_operations = Parse::BatchOperation.new batch_operations
         end
         response = request(:post, "batch", body: batch_operations.as_json)
-        response.success? && response.batch? ? response.batch_responses : response
+        return response.batch_responses if response.success? && response.batch?
+        return response if response.error?
+        # A successful HTTP response whose body is not an array of results
+        # cannot be matched to the submitted requests. Report it as a failure
+        # rather than as a batch where every write landed.
+        Parse::Response.error_response(
+          Parse::Response::ERROR_INTERNAL,
+          "Malformed batch response: expected an array of results",
+          http_status: response.http_status,
+        ).tap { |r| r.request = response.request }
       end
     end
   end

data/lib/parse/api/schema.rb

@@ -8,11 +8,19 @@ module Parse
       # @!visibility private
       SCHEMAS_PATH = "schemas"
 
+      # Parse Server serves `/schemas` to the master key only. Every call
+      # here therefore asks for the master key explicitly (outside client
+      # mode), which also stops an ambient `Parse.with_session` token or a
+      # client-bound token from being attached in its place. With a session token attached the request was
+      # refused with 403, and callers that cache the class permissions (the
+      # CLP scope used by mongo-direct queries) then denied a direct query
+      # that the master-keyed client was entitled to run.
+
       # Get all the schemas for the application.
       # @param opts [Hash] additional options for the request.
       # @return [Parse::Response]
       def schemas(opts = {})
-        request_opts = { cache: false }.merge(opts)
+        request_opts = { cache: false }.merge(schema_auth_opts).merge(opts)
         request :get, SCHEMAS_PATH, opts: request_opts
       end
 
@@ -21,7 +29,7 @@ module Parse
       # @return [Parse::Response]
       def schema(className)
         safe = Parse::API::PathSegment.identifier!(className, kind: "class name")
-        opts = { cache: false }
+        opts = { cache: false }.merge(schema_auth_opts)
         request :get, "#{SCHEMAS_PATH}/#{safe}", opts: opts
       end
 
@@ -32,7 +40,7 @@ module Parse
       # @return [Parse::Response]
       def create_schema(className, schema)
         safe = Parse::API::PathSegment.identifier!(className, kind: "class name")
-        request :post, "#{SCHEMAS_PATH}/#{safe}", body: schema
+        request :post, "#{SCHEMAS_PATH}/#{safe}", body: schema, opts: schema_auth_opts
       end
 
       # Update the schema for a collection.
@@ -42,7 +50,18 @@ module Parse
       # @return [Parse::Response]
       def update_schema(className, schema)
         safe = Parse::API::PathSegment.identifier!(className, kind: "class name")
-        request :put, "#{SCHEMAS_PATH}/#{safe}", body: schema
+        request :put, "#{SCHEMAS_PATH}/#{safe}", body: schema, opts: schema_auth_opts
+      end
+
+      private
+
+      # Ask for the master key explicitly, except under `Parse.client_mode`,
+      # whose contract is that the SDK never sends the master key on its own
+      # initiative. A client with no master key configured sends none either
+      # way.
+      # @!visibility private
+      def schema_auth_opts
+        { use_master_key: !Parse.client_mode }
       end
     end #Schema
   end #API

data/lib/parse/api/sessions.rb

@@ -13,8 +13,12 @@ module Parse
       # @param opts [Hash] additional options to pass to the {Parse::Client} request.
       # @return [Parse::Response]
       def fetch_session(session_token, **opts)
-        opts.merge!({ use_master_key: false, cache: false })
-        headers = { Parse::Protocol::SESSION_TOKEN => session_token }
+        # The positional token is passed as the explicit per-call token so an
+        # ambient `Parse.with_session` token or a client-bound token cannot
+        # replace it and return another user's session.
+        session_token = session_token.session_token if session_token.respond_to?(:session_token)
+        opts = opts.merge({ use_master_key: false, cache: false, session_token: session_token.to_s })
+        headers = { Parse::Protocol::SESSION_TOKEN => session_token.to_s }
         response = request :get, "#{SESSION_PATH_PREFIX}/me", headers: headers, opts: opts
         response.parse_class = Parse::Model::CLASS_SESSION
         response

data/lib/parse/api/users.rb

@@ -47,7 +47,14 @@ module Parse
       # @param headers [Hash] additional HTTP headers to send with the request.
       # @return [Parse::Response]
       def current_user(session_token, headers: {}, **opts)
-        headers.merge!({ Parse::Protocol::SESSION_TOKEN => session_token })
+        # The token argument is the whole point of this call, so it is passed
+        # as the explicit per-call token: an ambient `Parse.with_session`
+        # token or a client-bound token must never replace it (that resolved
+        # the wrong user and poisoned the identity cache). A caller-supplied
+        # `session_token:` in opts is ignored for the same reason.
+        session_token = session_token.session_token if session_token.respond_to?(:session_token)
+        opts = opts.merge(session_token: session_token.to_s, use_master_key: false)
+        headers = headers.merge({ Parse::Protocol::SESSION_TOKEN => session_token.to_s })
         response = request :get, "#{USER_PATH_PREFIX}/me", headers: headers, opts: opts
         response.parse_class = Parse::Model::CLASS_USER
         response
@@ -58,10 +65,23 @@ module Parse
       # @param opts [Hash] additional options to pass to the {Parse::Client} request.
       # @param headers [Hash] additional HTTP headers to send with the request.
       # @return [Parse::Response]
+      #
+      # Sent WITHOUT the master key unless the caller passes
+      # `use_master_key: true`. Parse Server does not mint a session token for
+      # a master-key signup, so a master-keyed client used to get back a user
+      # with no `sessionToken` (and {Parse::User#upgrade_anonymous!} then
+      # failed). A master-key create also lets the request through `_User`
+      # create CLPs and authData checks that a real signup must pass.
       def create_user(body, headers: {}, **opts)
-        headers.merge!({ Parse::Protocol::REVOCABLE_SESSION => "1" })
+        opts = opts.merge(use_master_key: false) unless opts[:use_master_key] == true
+        headers = headers.merge({ Parse::Protocol::REVOCABLE_SESSION => "1" })
         if opts[:session_token].present?
-          headers.merge!({ Parse::Protocol::SESSION_TOKEN => opts[:session_token] })
+          headers = headers.merge({ Parse::Protocol::SESSION_TOKEN => opts[:session_token] })
+        elsif opts[:use_master_key] != true
+          # No token given: send none, rather than letting an ambient
+          # `with_session` token or a client-bound token make the caller the
+          # `request.user` of someone else's signup.
+          opts = opts.merge(session_token: "")
         end
         response = request :post, USER_PATH_PREFIX, body: body, headers: headers, opts: opts
         response.parse_class = Parse::Model::CLASS_USER
@@ -78,6 +98,10 @@ module Parse
         id = Parse::API::PathSegment.object_id!(id)
         response = request :put, "#{USER_PATH_PREFIX}/#{id}", body: body, headers: headers, opts: opts
         response.parse_class = Parse::Model::CLASS_USER
+        # A password change revokes the user's other sessions server-side.
+        if response.success? && body.is_a?(Hash) && (body.key?(:password) || body.key?("password"))
+          invalidate_user_identity(id)
+        end
         response
       end
 
@@ -101,7 +125,9 @@ module Parse
       # @return [Parse::Response]
       def delete_user(id, headers: {}, **opts)
         id = Parse::API::PathSegment.object_id!(id)
-        request :delete, "#{USER_PATH_PREFIX}/#{id}", headers: headers, opts: opts
+        response = request :delete, "#{USER_PATH_PREFIX}/#{id}", headers: headers, opts: opts
+        invalidate_user_identity(id) if response.success?
+        response
       end
 
       # Request a password reset for a registered email.
@@ -127,7 +153,7 @@ module Parse
         rate_key = "pwreset:#{email}"
         check_login_rate_limit!(rate_key)
         body = { email: email }
-        response = request :post, REQUEST_PASSWORD_RESET, body: body, opts: opts, headers: headers
+        response = request :post, REQUEST_PASSWORD_RESET, body: body, opts: unauthenticated_opts(opts), headers: headers
         # Always count the attempt as a "failure" for backoff purposes:
         # the response body is intentionally indistinguishable across
         # found/not-found emails, so we cannot reset the counter on
@@ -150,7 +176,7 @@ module Parse
         rate_key = "emailverify:#{email}"
         check_login_rate_limit!(rate_key)
         body = { email: email }
-        response = request :post, VERIFICATION_EMAIL_REQUEST, body: body, opts: opts, headers: headers
+        response = request :post, VERIFICATION_EMAIL_REQUEST, body: body, opts: unauthenticated_opts(opts), headers: headers
         # Indistinguishable found/not-found response, like password reset — count
         # every attempt toward backoff so probing can't reset the counter.
         track_login_attempt(rate_key, false)
@@ -164,11 +190,16 @@ module Parse
       # @param headers [Hash] additional HTTP headers to send with the request.
       # @param opts [Hash] additional options to pass to the {Parse::Client} request.
       # @return [Parse::Response]
+      #
+      # Always sent without the master key and without any ambient or bound
+      # session token (see {#unauthenticated_opts}). A master-key login makes
+      # Parse Server skip the additional MFA check and SAVE the submitted
+      # authData, so it must never be sent from a master-keyed client.
       def login(username, password, headers: {}, **opts)
         check_login_rate_limit!(username)
         body = { username: username, password: password }
-        headers.merge!({ Parse::Protocol::REVOCABLE_SESSION => "1" })
-        response = request :post, LOGIN_PATH, body: body, headers: headers, opts: opts
+        headers = headers.merge({ Parse::Protocol::REVOCABLE_SESSION => "1" })
+        response = request :post, LOGIN_PATH, body: body, headers: headers, opts: unauthenticated_opts(opts)
         response.parse_class = Parse::Model::CLASS_USER
         track_login_attempt(username, response.success?)
         response
@@ -200,8 +231,12 @@ module Parse
             },
           },
         }
-        headers.merge!({ Parse::Protocol::REVOCABLE_SESSION => "1" })
-        response = request :post, LOGIN_PATH, body: body, headers: headers, opts: opts
+        # Never with the master key: with it, Parse Server skips the MFA
+        # validation and stores the submitted `authData.mfa` over the
+        # account's enrolled TOTP secret, so any code "verifies" and MFA is
+        # silently broken for the account from then on.
+        headers = headers.merge({ Parse::Protocol::REVOCABLE_SESSION => "1" })
+        response = request :post, LOGIN_PATH, body: body, headers: headers, opts: unauthenticated_opts(opts)
         response.parse_class = Parse::Model::CLASS_USER
         track_login_attempt(username, response.success?)
         response
@@ -242,7 +277,7 @@ module Parse
       def verify_password(username, password, headers: {}, **opts)
         check_login_rate_limit!(username)
         body = { username: username, password: password }
-        response = request :post, VERIFY_PASSWORD_PATH, body: body, headers: headers, opts: opts
+        response = request :post, VERIFY_PASSWORD_PATH, body: body, headers: headers, opts: unauthenticated_opts(opts)
         response.parse_class = Parse::Model::CLASS_USER
         track_login_attempt(username, response.success?)
         response
@@ -254,9 +289,14 @@ module Parse
       # @param opts [Hash] additional options to pass to the {Parse::Client} request.
       # @return [Parse::Response]
       def logout(session_token, headers: {}, **opts)
-        headers.merge!({ Parse::Protocol::SESSION_TOKEN => session_token })
-        opts.merge!({ use_master_key: false, session_token: session_token })
-        request :post, LOGOUT_PATH, headers: headers, opts: opts
+        session_token = session_token.session_token if session_token.respond_to?(:session_token)
+        headers = headers.merge({ Parse::Protocol::SESSION_TOKEN => session_token })
+        opts = opts.merge({ use_master_key: false, session_token: session_token })
+        response = request :post, LOGOUT_PATH, headers: headers, opts: opts
+        # Forget the token in this client's identity plane so mongo-direct
+        # reads see the revocation now rather than when the entry expires.
+        invalidate_session_identity(session_token) if response.success?
+        response
       end
 
       # Signup a user given a username, password and, optionally, their email.
@@ -272,8 +312,42 @@ module Parse
         create_user(body, **opts)
       end
 
+      # Drop one session token from this client's identity plane.
+      # @!visibility private
+      # @param session_token [String]
+      def invalidate_session_identity(session_token)
+        return if session_token.nil? || session_token.to_s.empty?
+        authorization.invalidate(session_token) if respond_to?(:authorization)
+      rescue StandardError
+        nil
+      end
+
+      # Drop every identity entry that resolves to `user_id` from this
+      # client's identity plane, after an event that revokes the user's
+      # sessions (password change, account deletion, logout everywhere).
+      # @!visibility private
+      # @param user_id [String]
+      def invalidate_user_identity(user_id)
+        return if user_id.nil? || user_id.to_s.empty?
+        authorization.invalidate_user(user_id) if respond_to?(:authorization)
+      rescue StandardError
+        nil
+      end
+
       private
 
+      # Request options for an endpoint that authenticates by the request
+      # body itself (login, MFA login, verifyPassword, password reset,
+      # verification email). Forces the master key off, and passes an
+      # explicitly blank session token so neither the ambient
+      # `Parse.with_session` token nor a client-bound token is attached:
+      # {Parse::Client#request} treats an explicit blank token as "send no
+      # credential". A caller cannot opt back into the master key here.
+      # @!visibility private
+      def unauthenticated_opts(opts)
+        opts.merge(use_master_key: false, session_token: "")
+      end
+
       # @!visibility private
       # Thread-safe tracker for login rate limiting. Keys are usernames, values are
       # { failures: Integer, locked_until: Time }.

data/lib/parse/atlas_search/protected_paths.rb

@@ -0,0 +1,236 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "../clp_scope"
+
+module Parse
+  module AtlasSearch
+    # Shared "does this path touch a protected field" logic for every
+    # Atlas Search and vector search entry point.
+    #
+    # Stripping a protected field from the RESULT rows does not stop it
+    # from deciding which documents MATCH, how they RANK, or which rows a
+    # filter keeps. A scoped caller that can name a protected field in a
+    # `$search` path, a highlight, an autocomplete field, a sort, or a
+    # `$match` filter key can test guesses against its value. These
+    # helpers find every such reference so the entry points can refuse
+    # the call with {Parse::CLPScope::Denied}.
+    #
+    # Path comparison rules:
+    # * A String or Symbol path is reduced to its first dotted segment,
+    #   with a `_p_` storage prefix removed (`_p_owner` counts as `owner`,
+    #   `secret.sub` counts as `secret`). The storage columns
+    #   `_created_at` / `_updated_at` / `_id` map to `createdAt` /
+    #   `updatedAt` / `objectId`.
+    # * An Array path touches a protected field when any element does.
+    # * A `{ "value" => ..., "multi" => ... }` path object is judged by
+    #   its `value`.
+    # * A `{ "wildcard" => ... }` path object, or any other non-String
+    #   path, is treated as touching every field.
+    #
+    # Every check is a no-op for a master resolution, a nil resolution,
+    # or an empty protected set.
+    module ProtectedPaths
+      # Storage-form column names that differ from their Parse field name.
+      STORAGE_ALIASES = {
+        "_created_at" => "createdAt",
+        "_updated_at" => "updatedAt",
+        "_id" => "objectId",
+      }.freeze
+
+      # Query operators whose value is a list of sub-filters.
+      LOGICAL_OPERATORS = %w[$and $or $nor].freeze
+
+      # Sentinel yielded for a reference that reaches every field
+      # (a wildcard path, a queryString query).
+      ALL_FIELDS = :__all_fields__
+
+      module_function
+
+      # @return [Boolean] true when the scope is subject to protectedFields.
+      def enforce?(resolution, protected_fields)
+        return false if resolution.nil?
+        return false if resolution.respond_to?(:master?) && resolution.master?
+        !(protected_fields.nil? || protected_fields.empty?)
+      end
+
+      # The Parse field name a single String path addresses.
+      # @return [String, nil]
+      def root_field(path)
+        head = path.to_s.split(".").first.to_s
+        return nil if head.empty?
+        head = STORAGE_ALIASES.fetch(head, head)
+        head = head.delete_prefix("_p_") if head.start_with?("_p_") && head.length > 3
+        head
+      end
+
+      # Whether `path` touches a protected field.
+      #
+      # @param path [String, Symbol, Array, Hash, Object] an Atlas path.
+      # @param protected_fields [Set<String>, Array<String>]
+      # @return [Boolean]
+      def touches?(path, protected_fields)
+        return false if protected_fields.nil? || protected_fields.empty?
+        case path
+        when String, Symbol
+          protected_fields.include?(root_field(path))
+        when Array
+          path.any? { |p| touches?(p, protected_fields) }
+        when Hash
+          value = path.key?("value") ? path["value"] : path[:value]
+          has_wildcard = path.key?("wildcard") || path.key?(:wildcard)
+          return true if has_wildcard || value.nil?
+          touches?(value, protected_fields)
+        else
+          true
+        end
+      end
+
+      # Refuse when any of `paths` touches a protected field.
+      #
+      # @param paths [Object] a single path or an Array of paths.
+      # @param what [String] used in the error message ("search path",
+      #   "highlight path", ...).
+      # @raise [Parse::CLPScope::Denied]
+      def assert_paths_allowed!(paths, protected_fields, resolution, collection_name: nil,
+                                                                     method_name: "Parse::AtlasSearch.search",
+                                                                     what: "path")
+        return unless enforce?(resolution, protected_fields)
+        list = paths.is_a?(Array) ? paths : [paths]
+        hit = list.find { |p| touches?(p, protected_fields) }
+        return if hit.nil? && !list.empty?
+        raise_denied!(collection_name, method_name, what, hit.nil? ? ALL_FIELDS : hit)
+      end
+
+      # Walk a `$search` / `$searchMeta` body (or a whole stage) and
+      # refuse any path, sort key, or query-string reference that touches
+      # a protected field. Operators nest freely (compound
+      # must/should/filter/mustNot, embeddedDocument, facet operators,
+      # score functions), so every `path` / `defaultPath` value at any
+      # depth is checked.
+      #
+      # @raise [Parse::CLPScope::Denied]
+      def assert_search_stage_allowed!(stage, protected_fields, resolution, collection_name: nil,
+                                                                             method_name: "Parse::AtlasSearch.search_with_stage")
+        return unless enforce?(resolution, protected_fields)
+        each_search_reference(stage) do |ref|
+          next unless ref == ALL_FIELDS || touches?(ref, protected_fields)
+          raise_denied!(collection_name, method_name, "$search path", ref)
+        end
+        nil
+      end
+
+      # Yield every field reference in a `$search`-style body.
+      # @!visibility private
+      def each_search_reference(node, &block)
+        case node
+        when Array
+          node.each { |child| each_search_reference(child, &block) }
+        when Hash
+          node.each do |key, value|
+            case key.to_s
+            when "path", "defaultPath"
+              yield value
+            when "sort"
+              if value.is_a?(Hash)
+                value.each do |sort_key, dir|
+                  # `{ score: { $meta: "searchScore" } }` sorts by relevance,
+                  # not by a stored field.
+                  next if dir.is_a?(Hash) && (dir.key?("$meta") || dir.key?(:$meta))
+                  yield sort_key
+                end
+              else
+                each_search_reference(value, &block)
+              end
+            when "queryString"
+              # The Lucene query syntax can name any field (`ssn:123*`),
+              # so the query text reaches every field.
+              yield ALL_FIELDS
+              each_search_reference(value, &block)
+            when "moreLikeThis"
+              like = value.is_a?(Hash) ? (value["like"] || value[:like]) : nil
+              Array(like).each do |doc|
+                doc.is_a?(Hash) ? doc.each_key { |k| yield k } : yield(ALL_FIELDS)
+              end
+              each_search_reference(value, &block)
+            else
+              each_search_reference(value, &block)
+            end
+          end
+        end
+        nil
+      end
+
+      # Refuse a `$match` filter whose predicate KEYS (top level, and
+      # inside `$and` / `$or` / `$nor` / `$not`) or `$expr` field
+      # references touch a protected field. A filter decides which rows
+      # survive, so filtering on a protected field is an oracle on its
+      # value even when the field is stripped from the output.
+      #
+      # @raise [Parse::CLPScope::Denied]
+      def assert_filter_allowed!(filter, protected_fields, resolution, collection_name: nil,
+                                                                        method_name: "Parse::AtlasSearch.search")
+        return unless enforce?(resolution, protected_fields)
+        each_filter_reference(filter) do |ref|
+          next unless touches?(ref, protected_fields)
+          raise_denied!(collection_name, method_name, "filter field", ref)
+        end
+        nil
+      end
+
+      # Yield every field name a `$match` filter predicates on.
+      # @!visibility private
+      def each_filter_reference(node, &block)
+        case node
+        when Array
+          node.each { |child| each_filter_reference(child, &block) }
+        when Hash
+          node.each do |key, value|
+            k = key.to_s
+            if LOGICAL_OPERATORS.include?(k) || k == "$not"
+              each_filter_reference(value, &block)
+            elsif k == "$expr"
+              each_expr_reference(value, &block)
+            elsif k.start_with?("$")
+              # Other top-level operators ($text, $comment, ...) do not
+              # name a stored field by key.
+              next
+            else
+              yield k
+            end
+          end
+        end
+        nil
+      end
+
+      # Yield `$field` references inside an aggregation expression.
+      # `$$VAR` references are variables, not fields.
+      # @!visibility private
+      def each_expr_reference(node, &block)
+        case node
+        when String
+          yield node[1..] if node.start_with?("$") && !node.start_with?("$$") && node.length > 1
+        when Array
+          node.each { |child| each_expr_reference(child, &block) }
+        when Hash
+          node.each_value { |child| each_expr_reference(child, &block) }
+        end
+        nil
+      end
+
+      # @!visibility private
+      def raise_denied!(collection_name, method_name, what, ref)
+        detail = if ref == ALL_FIELDS
+            "a #{what} that reaches every field would match on protectedFields " \
+            "for the current scope; name the fields to search explicitly."
+          else
+            field = ref.is_a?(String) || ref.is_a?(Symbol) ? root_field(ref) : nil
+            label = field ? "'#{ref}' touches protected field '#{field}'" : "#{ref.inspect} reaches every field"
+            "#{what} #{label} for the current scope; matching, ranking, or " \
+            "filtering on it would reveal its value."
+          end
+        raise Parse::CLPScope::Denied.new(collection_name, :find, "#{method_name} refused: #{detail}")
+      end
+    end
+  end
+end