parse-stack-next 5.8.2 → 5.8.4

data/lib/parse/live_query/client.rb

@@ -599,7 +599,7 @@ module Parse
           else
             raise ArgumentError,
               "[Parse::LiveQuery] Refusing to derive insecure ws:// URL from " \
-              "http:// server URL (#{server_url.inspect}). The LiveQuery " \
+              "http:// server URL (#{Parse::Client.redact_url_userinfo(server_url).inspect}). The LiveQuery " \
               "connect frame carries the master key and any session token " \
               "in plaintext on this socket. Use an https:// Parse server URL " \
               "(so wss:// is derived) or pass an explicit wss:// `url:` to " \
@@ -785,8 +785,10 @@ module Parse
 
       # Start background thread for reading messages
       def start_reader_thread
+        # Long-lived: started without the caller's ambient identity, so frame
+        # handling and the threads it starts do not inherit a session token.
         @reader_thread = Thread.new do
-          read_loop
+          Parse.without_ambient_identity(keep_restrictions: true) { read_loop }
         end
         @reader_thread.abort_on_exception = false
       end
@@ -962,9 +964,15 @@ module Parse
         subscription = @subscriptions[request_id]
         return unless subscription
 
+        class_name = message.dig("object", "className") || subscription.class_name
+        # Remove `_User` / `_Session` credential fields (sessionToken,
+        # authData) before anything else sees the payload. The payload's own
+        # className is checked as well as the subscription's class.
+        message = Event.scrub_message(message, subscription.class_name)
+
         event = Event.new(
           type: op.to_sym,
-          class_name: message.dig("object", "className") || subscription.class_name,
+          class_name: class_name,
           object_data: message["object"],
           original_data: message["original"],
           request_id: request_id,
@@ -1051,14 +1059,24 @@ module Parse
 
         Logging.info("Scheduling reconnect", delay: delay.round(2))
 
+        # The reconnect thread runs without the caller's ambient identity. A
+        # reconnect scheduled inside Parse.without_master_key on an admin
+        # client therefore latches the master-key withhold here, before the
+        # thread drops the block state, so the reconnect cannot elevate.
+        if admin_connection? && Parse.respond_to?(:master_key_disabled?) && Parse.master_key_disabled?
+          @master_key_withheld = true
+        end
+
         @reconnect_thread = Thread.new do
-          sleep delay
-          @monitor.synchronize do
-            @reconnect_thread = nil
+          Parse.without_ambient_identity do
+            sleep delay
+            @monitor.synchronize do
+              @reconnect_thread = nil
+            end
+            @reconnect_interval = [@reconnect_interval * cfg.reconnect_multiplier,
+                                   cfg.max_reconnect_interval].min
+            connect
           end
-          @reconnect_interval = [@reconnect_interval * cfg.reconnect_multiplier,
-                                 cfg.max_reconnect_interval].min
-          connect
         end
       end
 

data/lib/parse/live_query/event.rb

@@ -36,6 +36,55 @@ module Parse
       # @return [Hash] raw payload from the server
       attr_reader :raw
 
+      # Classes whose LiveQuery payloads have credential fields removed.
+      CREDENTIAL_CLASSES = %w[_User _Session].freeze
+
+      # Payload keys removed from `_User` / `_Session` objects. Parse Server
+      # releases without the fix for GHSA-349r could deliver another user's
+      # `_User` / `_Session` events, `sessionToken` included, to an `$or`
+      # subscription. Removing these before hydration keeps a bearer token
+      # (or a linked-account credential) out of callbacks, logs, and
+      # {#raw} even against such a server.
+      CREDENTIAL_KEYS = %w[sessionToken authData _session_token _hashed_password _auth_data].freeze
+
+      # Prefix for per-provider auth-data storage columns.
+      CREDENTIAL_KEY_PREFIX = "_auth_data_"
+
+      class << self
+        # Remove credential keys from an object payload when it belongs to
+        # `_User` or `_Session` (by its own `className` or by `class_name`).
+        # Returns a copy; other payloads are returned unchanged.
+        #
+        # @param data [Hash, Object] object payload from the server.
+        # @param class_name [String, nil] the subscription's class.
+        # @return [Hash, Object]
+        def scrub_credentials(data, class_name = nil)
+          return data unless data.is_a?(Hash)
+          own = data["className"] || data[:className]
+          return data unless CREDENTIAL_CLASSES.include?(own.to_s) || CREDENTIAL_CLASSES.include?(class_name.to_s)
+          data.reject do |key, _|
+            k = key.to_s
+            CREDENTIAL_KEYS.include?(k) || k.start_with?(CREDENTIAL_KEY_PREFIX)
+          end
+        end
+
+        # Scrub the `object` and `original` payloads of a whole server
+        # message. Returns a copy when anything changed.
+        #
+        # @param message [Hash]
+        # @param class_name [String, nil]
+        # @return [Hash]
+        def scrub_message(message, class_name = nil)
+          return message unless message.is_a?(Hash)
+          scrubbed = message.dup
+          %w[object original].each do |key|
+            next unless scrubbed.key?(key)
+            scrubbed[key] = scrub_credentials(scrubbed[key], class_name)
+          end
+          scrubbed
+        end
+      end
+
       # Create a new Event from a LiveQuery server message
       # @param type [Symbol] event type
       # @param class_name [String] Parse class name
@@ -48,7 +97,12 @@ module Parse
         @class_name = class_name
         @request_id = request_id
         @received_at = Time.now
-        @raw = raw
+        @raw = self.class.scrub_message(raw, class_name)
+
+        # Credential fields of `_User` / `_Session` objects are removed
+        # before hydration (see {CREDENTIAL_KEYS}).
+        object_data = self.class.scrub_credentials(object_data, class_name)
+        original_data = self.class.scrub_credentials(original_data, class_name)
 
         # Convert object data to Parse::Object instances
         @object = build_object(class_name, object_data) if object_data

data/lib/parse/live_query/event_queue.rb

@@ -87,7 +87,12 @@ module Parse
           return if @running
 
           @running = true
-          @processor_thread = Thread.new { process_loop(&processor) }
+          # Long-lived: started without the ambient identity of the caller
+          # (see Parse.without_ambient_identity), so callbacks dispatched on
+          # it never run with an inherited with_session token. A restricted
+          # caller's thread keeps the master key suppressed instead of
+          # gaining it.
+          @processor_thread = Thread.new { Parse.without_ambient_identity(keep_restrictions: true) { process_loop(&processor) } }
           @processor_thread.abort_on_exception = false
 
           Logging.debug("Event queue started", max_size: @max_size, strategy: @strategy)

data/lib/parse/live_query/health_monitor.rb

@@ -69,7 +69,7 @@ module Parse
           @last_pong_at = Time.now
           @awaiting_pong = false
 
-          @ping_thread = Thread.new { ping_loop }
+          @ping_thread = Thread.new { Parse.without_ambient_identity(keep_restrictions: true) { ping_loop } }
           @ping_thread.abort_on_exception = false
 
           Logging.debug("Health monitor started", ping_interval: @ping_interval, pong_timeout: @pong_timeout)

data/lib/parse/model/file.rb

@@ -86,6 +86,11 @@ module Parse
       # cloud-metadata endpoint that must not be reachable from SDK fetches).
       "100.100.100.200/32",
       "::/128", "::1/128", "fc00::/7", "fe80::/10", "ff00::/8", "::ffff:0:0/96",
+      # NAT64 (RFC 6052) and 6to4 (RFC 3056) embed an IPv4 address, which on
+      # a NAT64 or 6to4 network can be an internal or metadata address.
+      "64:ff9b::/96", "64:ff9b:1::/48", "2002::/16",
+      # Deprecated IPv4-compatible IPv6 (RFC 4291 2.5.5.1), e.g. ::127.0.0.1.
+      "::/96",
     ].map { |c| IPAddr.new(c) }.freeze
     # Restrictive port allowlist for Parse::File URL fetches. By default
     # only the standard HTTP/HTTPS ports are permitted. Operators may
@@ -543,8 +548,12 @@ module Parse
       end
 
       # @!visibility private
-      # Fetches a remote URL with strict SSRF defenses. Refuses non-HTTP
-      # schemes, RFC1918 / loopback / cloud-metadata addresses, oversized
+      # Fetches a remote URL with strict SSRF defenses. The returned object's
+      # `content_type` is the remote server's `Content-Type` header, which is
+      # controlled by whoever controls the URL; callers must not trust it as
+      # the file's real type (see {Parse::File#initialize}).
+      #
+      # Refuses non-HTTP schemes, RFC1918 / loopback / cloud-metadata addresses, oversized
       # bodies, and slow upstreams. Returns the open-uri Tempfile/StringIO
       # the caller can read from.
       #
@@ -716,6 +725,29 @@ module Parse
     # If the first parameter is a hash, we assume it might be the Parse File hash format which contains url and name fields only.
     # If the first paramter is a Parse::File, then we copy fields over
     # Otherwise, creating a new file requires a name, the actual contents (usually from a File.open("local.jpg").read ) and the mime-type
+    #
+    # == Remote URL content type is untrusted
+    #
+    # Passing a URL String here, or assigning a URL String to a `:file`
+    # property (which calls this initializer), downloads the URL and records
+    # the remote server's `Content-Type` header as {#mime_type}. No content
+    # sniffing is performed. When the URL comes from a request, the server
+    # behind it is chosen by the requester, and so is the recorded type.
+    #
+    # - Do not assign request strings to file properties or pass them here.
+    #   Build files from bytes your application received
+    #   (`Parse::File.new(name, bytes, type)`) and determine `type`
+    #   server-side from the content.
+    # - Any consumer that decodes stored files (image processing such as
+    #   libvips or ImageMagick, Active Storage variants, document parsers)
+    #   should treat the stored mime type as untrusted, sniff the content
+    #   before choosing a decoder, and disable decoders for untrusted formats.
+    #   For libvips 8.13 and later, set `VIPS_BLOCK_UNTRUSTED` in the
+    #   environment or call `Vips.block_untrusted(true)` (ruby-vips 2.2.1 and
+    #   later).
+    # - Keep {Parse::File.allowed_remote_hosts} restricted to the hosts the
+    #   application expects to fetch from.
+    #
     # @param name [String]
     # @param contents [Object]
     # @param mime_type [String] Default see default_mime_type
@@ -761,7 +793,9 @@ module Parse
       @mime_type ||= mime_type
     end
 
-    # This creates a new Parse File Object with from a URL, saves it and returns it
+    # This creates a new Parse File Object with from a URL, saves it and returns it.
+    # The saved mime type is the remote server's `Content-Type` header and is
+    # untrusted when the URL is (see {#initialize}).
     # @param url [String] A url which will be used to create the file and automatically save it.
     # @return [Parse::File] A newly saved file based on contents of _url_
     def self.create(url)

data/lib/parse/mongodb.rb

@@ -1777,6 +1777,11 @@ module Parse
           scope: nil,
           result_count: nil,
         }
+        # One schema entry per class for the whole request: the protected-
+        # field scanner, the CLP row gate, the join gate, and the protected-
+        # field strip below all read the same snapshot, so a cache expiry
+        # and refetch between them cannot change the decision.
+        Parse::CLPScope.with_snapshot do
         ActiveSupport::Notifications.instrument("parse.mongodb.aggregate", instrument_payload) do |payload|
           # Resolve auth kwargs into a Parse::ACLScope::Resolution. The
           # call MUTATES the temporary kwargs hash (popping the auth
@@ -1943,6 +1948,7 @@ module Parse
           payload[:result_count] = results.size
           results
         end
+        end
       rescue => e
         raise_if_timeout!(e, collection_name, max_time_ms)
         raise
@@ -2200,6 +2206,19 @@ module Parse
                 "with session_token:, or Parse::Query#results_direct), or run the call inside " \
                 "Parse.with_master_key."
         end
+        if (Parse.current_session_token || Parse.anonymous_session?) &&
+           Fiber[Parse::INNERMOST_AUTH_BLOCK_KEY] != :master
+          # Inside Parse.with_session the caller expects that user's (or
+          # the anonymous) authority. `find` cannot apply it, so refuse
+          # instead of returning every row. A Parse.with_master_key block
+          # entered inside the session block states the master authority
+          # explicitly and is allowed; one wrapped around it is not.
+          raise Parse::ACLScope::ACLRequired,
+                "Parse::MongoDB.find runs unscoped (master authority) and is refused " \
+                "inside Parse.with_session. Use Parse::Query#results_direct, which applies " \
+                "the ambient session, or Parse::MongoDB.aggregate with session_token:, or " \
+                "run the call inside a Parse.with_master_key block nested in the session block."
+        end
         max_time_ms = options.delete(:max_time_ms)
         # A regex that is not escaped literal text gets a default time limit.
         max_time_ms ||= Parse::PipelineSecurity.regex_time_budget(filter)

data/lib/parse/pipeline_security.rb

@@ -86,10 +86,15 @@ module Parse
     # execute server-side JavaScript (`$where`, `$function`,
     # `$accumulator`) or mutate the database (`$out`, `$merge`) or the
     # server itself (`$collMod`, `$createIndex`, `$dropIndex`,
-    # `$planCacheSetFilter`, `$planCacheClear`). None of them are needed
-    # for read queries.
+    # `$planCacheSetFilter`, `$planCacheClear`). `$jsonSchema` is refused
+    # because its `properties` name fields inside a value, out of reach of
+    # the key-based protectedFields checks, and its `pattern` runs a regex
+    # that skips {Parse::RegexSecurity} and the regex time limit; a
+    # `{ $jsonSchema: { properties: { email: { pattern: "^a" } } } }` match
+    # reads a protected field one character at a time. None of them are
+    # needed for read queries.
     DENIED_OPERATORS = %w[
-      $where $function $accumulator
+      $where $function $accumulator $jsonSchema
       $out $merge
       $collMod $createIndex $dropIndex
       $planCacheSetFilter $planCacheClear
@@ -441,19 +446,72 @@ module Parse
 
       require_relative "atlas_search/protected_paths" unless defined?(Parse::AtlasSearch::ProtectedPaths)
 
-      protected_set = Parse::CLPScope.protected_fields_for(collection_name, perms)
+      # Read the schema the CLP gate reads: the resolution's client, not the
+      # default one, so a multi-app setup scans the right application's
+      # protectedFields. `strict:` fails closed when the schema is
+      # unresolvable; an empty set would let a `$match` on a protected
+      # field through as a value oracle.
+      client = schema_client_for(resolution)
+      protected_set = Parse::CLPScope.protected_fields_for(collection_name, perms, client: client, strict: true)
+      # A joined class whose schema is unresolvable is refused after the
+      # walk, so a denial that names a protected field of the queried class
+      # is reported first.
+      unresolved = nil
       sets = Hash.new do |memo, klass|
-        memo[klass] = Parse::CLPScope.protected_fields_for(klass, perms)
+        memo[klass] = begin
+            Parse::CLPScope.protected_fields_for(klass, perms, client: client, strict: true)
+          rescue Parse::CLPScope::Denied => e
+            unresolved ||= e
+            Set.new
+          end
       end
       sets[collection_name.to_s] = protected_set || Set.new
 
       pipeline.each_with_index do |stage, idx|
+        refuse_internal_search_paths!(stage, collection_name.to_s, resolution)
         walk_stage_refs!(stage, collection_name.to_s, sets, "pipeline[#{idx}]")
         refuse_protected_stage_keys!(stage, collection_name.to_s, sets, "pipeline[#{idx}]")
       end
+      raise unresolved if unresolved
+      nil
+    end
+
+    # The client whose schema decides CLP for a resolution, matching
+    # {Parse::MongoDB.clp_client_for}: the resolution's client when it holds
+    # a master key (it can read `/schemas`), otherwise nil (the default).
+    #
+    # @!visibility private
+    def schema_client_for(resolution)
+      return nil unless defined?(Parse::ACLScope) && Parse::ACLScope.respond_to?(:client_of)
+      c = Parse::ACLScope.client_of(resolution)
+      return nil if c.nil?
+      return nil unless c.respond_to?(:master_key) && !c.master_key.to_s.empty?
+      c
+    end
+
+    private_class_method :schema_client_for
+
+    # Refuse a top-level `$search` / `$searchMeta` stage whose paths name a
+    # Parse Server internal column, or (on `_User` / `_Session`, for a
+    # non-master scope) reach every field through a wildcard or queryString.
+    # {walk_for_denied!} refuses internal names for every caller; this adds
+    # the collection-aware wildcard rule.
+    #
+    # @!visibility private
+    def refuse_internal_search_paths!(stage, collection_name, resolution)
+      return unless stage.is_a?(Hash)
+      stage.each do |op, body|
+        next unless %w[$search $searchMeta].include?(op.to_s)
+        Parse::AtlasSearch::ProtectedPaths.assert_no_internal_paths!(
+          stage: body, collection_name: collection_name, resolution: resolution,
+          method_name: "Parse::MongoDB.aggregate", what: "#{op} path",
+        )
+      end
       nil
     end
 
+    private_class_method :refuse_internal_search_paths!
+
     # Whether no stage of `pipeline` can change a row's identity
     # (`_id` / `objectId`).
     #
@@ -630,6 +688,10 @@ module Parse
     #   sub-pipeline (the joined class, with ITS protected set), and the
     #   same for `$unionWith` and `$graphLookup`, so an `$inQuery` style
     #   join cannot probe the joined class's protected fields either.
+    # * `$setWindowFields`, `$densify`, and `$fill` partition, sort, and
+    #   output fields (see {refuse_protected_window_keys!});
+    # * `$bucket` / `$bucketAuto` `groupBy` and `$sortByCount` references;
+    # * `$search` / `$searchMeta` paths, sort keys, and queryString texts.
     #
     # @!visibility private
     def refuse_protected_stage_keys!(stage, class_name, sets, path)
@@ -665,6 +727,35 @@ module Parse
           end
         when "$lookup", "$graphLookup", "$unionWith"
           refuse_protected_join_keys!(op.to_s, body, class_name, sets, path)
+        when "$setWindowFields", "$densify", "$fill"
+          refuse_protected_window_keys!(op.to_s, body, class_name, own, path)
+        when "$bucket", "$bucketAuto"
+          next unless body.is_a?(Hash)
+          group_by = body["groupBy"] || body[:groupBy]
+          paths.each_expr_reference(group_by) do |ref|
+            raise_protected_key!(class_name, ref, "#{path}.#{op}.groupBy") if paths.touches?(ref, own)
+          end
+        when "$sortByCount"
+          paths.each_expr_reference(body) do |ref|
+            raise_protected_key!(class_name, ref, "#{path}.$sortByCount") if paths.touches?(ref, own)
+          end
+        when "$search", "$searchMeta"
+          next if own.nil? || own.empty?
+          paths.each_search_reference(body) do |ref|
+            if ref != paths::ALL_FIELDS && (ref.is_a?(String) || ref.is_a?(Symbol))
+              raise_protected_key!(class_name, ref, "#{path}.#{op}") if paths.touches?(ref, own)
+            elsif ref == paths::ALL_FIELDS || paths.touches?(ref, own)
+              # A wildcard path, an Array or path object naming a protected
+              # field, or a queryString text (which can name any field).
+              raise Parse::CLPScope::Denied.new(
+                class_name, :find,
+                "This user is not allowed to query protected fields on class #{class_name}: " \
+                "#{path}.#{op} uses a path that reaches every field or a protected one " \
+                "(#{ref == paths::ALL_FIELDS ? "queryString or wildcard" : ref.inspect}). " \
+                "Name the fields to search explicitly.",
+              )
+            end
+          end
         end
       end
       nil
@@ -672,6 +763,62 @@ module Parse
 
     private_class_method :refuse_protected_stage_keys!
 
+    # Refuse a `$setWindowFields`, `$densify`, or `$fill` stage that
+    # partitions, sorts, or fills on a protected field. Each decides row
+    # order or the values written into neighbouring rows from the field it
+    # names, so the output reveals the field even after the strip:
+    #
+    # * `$setWindowFields`: `partitionBy` expression references, `sortBy`
+    #   keys, and field references inside each `output` window (including
+    #   `window.documents` / `window.range` bounds);
+    # * `$densify`: `field` and `partitionByFields` (bare field names);
+    # * `$fill`: `sortBy` keys, `partitionBy` expression references,
+    #   `partitionByFields`, and `output` keys (the fields being filled).
+    #
+    # @!visibility private
+    def refuse_protected_window_keys!(op, body, class_name, own, path)
+      return unless body.is_a?(Hash)
+      return if own.nil? || own.empty?
+      paths = Parse::AtlasSearch::ProtectedPaths
+      fetch = ->(key) { body.key?(key) ? body[key] : body[key.to_sym] }
+
+      sort_by = fetch.call("sortBy")
+      if sort_by.is_a?(Hash)
+        sort_by.each_key do |key|
+          raise_protected_key!(class_name, key, "#{path}.#{op}.sortBy") if paths.touches?(key.to_s, own)
+        end
+      end
+
+      paths.each_expr_reference(fetch.call("partitionBy")) do |ref|
+        raise_protected_key!(class_name, ref, "#{path}.#{op}.partitionBy") if paths.touches?(ref, own)
+      end
+
+      Array(fetch.call("partitionByFields")).each do |name|
+        next unless name.is_a?(String) || name.is_a?(Symbol)
+        raise_protected_key!(class_name, name, "#{path}.#{op}.partitionByFields") if paths.touches?(name.to_s, own)
+      end
+
+      if op == "$densify"
+        field = fetch.call("field")
+        raise_protected_key!(class_name, field, "#{path}.$densify.field") if
+          (field.is_a?(String) || field.is_a?(Symbol)) && paths.touches?(field.to_s, own)
+      end
+
+      output = fetch.call("output")
+      return unless output.is_a?(Hash)
+      output.each do |name, spec|
+        if op == "$fill" && paths.touches?(name.to_s, own)
+          raise_protected_key!(class_name, name, "#{path}.$fill.output")
+        end
+        paths.each_expr_reference(spec) do |ref|
+          raise_protected_key!(class_name, ref, "#{path}.#{op}.output.#{name}") if paths.touches?(ref, own)
+        end
+      end
+      nil
+    end
+
+    private_class_method :refuse_protected_window_keys!
+
     # @!visibility private
     def refuse_protected_join_keys!(op, body, class_name, sets, path)
       paths = Parse::AtlasSearch::ProtectedPaths
@@ -983,6 +1130,17 @@ module Parse
               )
             end
           end
+          # Stages that name fields by BARE string value rather than by key
+          # or `$<field>` reference (`$densify.field`, `$fill`
+          # `partitionByFields`, `$search` paths, join fields). The key and
+          # reference screens above and below do not see these, so they are
+          # held to the same credential / internal rule here.
+          if BARE_FIELD_NAME_STAGES.include?(key_str)
+            refuse_internal_bare_field_names!(
+              key_str, value, depth: depth, stage_idx: stage_idx,
+              allow_internal_fields: allow_internal_fields,
+            )
+          end
           # Caller-supplied regex patterns. Catches the two shapes Mongo
           # accepts: the find-form `{ field: { $regex: "..." } }` (key ==
           # "$regex", value a String or a Regexp) and the aggregation-form
@@ -1079,6 +1237,85 @@ module Parse
 
     private_class_method :walk_for_denied!
 
+    # Stages whose arguments name a field by bare string value.
+    # @!visibility private
+    BARE_FIELD_NAME_STAGES = %w[
+      $densify $fill $setWindowFields $search $searchMeta
+      $geoNear $lookup $graphLookup
+    ].freeze
+
+    # Refuse a bare field name in a stage argument that names an internal
+    # Parse Server column. Credential columns are refused for every caller;
+    # `_rperm` / `_wperm` / `_tombstone` only when `allow_internal_fields`
+    # is false, matching the `$match` key rule in {walk_for_denied!}.
+    # @!visibility private
+    def refuse_internal_bare_field_names!(op, body, depth:, stage_idx:, allow_internal_fields:)
+      return unless body.is_a?(Hash)
+      fetch = ->(key) { body.key?(key) ? body[key] : body[key.to_sym] }
+      names = case op
+        when "$densify" then [fetch.call("field"), *Array(fetch.call("partitionByFields"))]
+        when "$fill", "$setWindowFields" then Array(fetch.call("partitionByFields"))
+        when "$geoNear" then [fetch.call("key"), fetch.call("distanceField"), fetch.call("includeLocs")]
+        when "$lookup" then [fetch.call("localField"), fetch.call("foreignField")]
+        when "$graphLookup"
+          [fetch.call("connectFromField"), fetch.call("connectToField"), fetch.call("depthField")]
+        when "$search", "$searchMeta"
+          require_relative "atlas_search/protected_paths" unless defined?(Parse::AtlasSearch::ProtectedPaths)
+          paths = Parse::AtlasSearch::ProtectedPaths
+          refs = []
+          paths.each_search_reference(body) { |ref| refs << ref }
+          paths.each_query_string_field(body) do |field|
+            refs << (field.match?(/[*?]/) ? { "wildcard" => field } : field)
+          end
+          refs
+        else []
+        end
+      names.each do |name|
+        next unless internal_field_name?(name, allow_internal_fields)
+        raise Error.new(
+          "SECURITY: #{op} at nesting depth #{depth}" \
+          "#{stage_idx ? " inside stage #{stage_idx}" : ""} names internal Parse Server " \
+          "field #{name.inspect}. This column (password hash, session token, auth data, " \
+          "or ACL pointer) must not appear in a user-influenced pipeline; partitioning, " \
+          "sorting, or matching on it reveals its value.",
+          stage: stage_idx,
+          operator: op,
+          reason: :denied_internal_field,
+        )
+      end
+      nil
+    end
+
+    private_class_method :refuse_internal_bare_field_names!
+
+    # Whether a bare field name (a String, an Array of names, or an Atlas
+    # `{ value: }` / `{ wildcard: }` path object) names an internal column.
+    # @!visibility private
+    def internal_field_name?(name, allow_internal_fields)
+      case name
+      when String, Symbol
+        head = name.to_s.split(".").first.to_s
+        return false if head.empty?
+        credential = CREDENTIAL_FIELDS_DENYLIST.include?(head) ||
+                     INTERNAL_FIELDS_PREFIX_DENYLIST.any? { |prefix| head.start_with?(prefix) }
+        credential || (!allow_internal_fields && INTERNAL_FIELDS_DENYLIST.include?(head))
+      when Array
+        name.any? { |n| internal_field_name?(n, allow_internal_fields) }
+      when Hash
+        value = name.key?("value") ? name["value"] : name[:value]
+        glob = name.key?("wildcard") ? name["wildcard"] : name[:wildcard]
+        return true if !value.nil? && internal_field_name?(value, allow_internal_fields)
+        require_relative "atlas_search/protected_paths" unless defined?(Parse::AtlasSearch::ProtectedPaths)
+        # The collection is not known here, so the credential columns count
+        # (the conservative answer).
+        Parse::AtlasSearch::ProtectedPaths.internal_glob?(glob, include_acl: !allow_internal_fields)
+      else
+        false
+      end
+    end
+
+    private_class_method :internal_field_name?
+
     # @!visibility private
     # Run a caller-supplied regex pattern (String, Regexp, or
     # BSON::Regexp::Raw) through Parse::RegexSecurity with this module's