parse-stack-next 5.7.6 → 5.8.0

data/lib/parse/stack.rb

@@ -115,9 +115,12 @@ module Parse
   #
   # The `token` argument may be a String, a {Parse::User} (its
   # `session_token` is read), a {Parse::Session} (its `session_token` is
-  # read), or `nil`. Passing `nil` clears the ambient inside the block —
-  # useful for performing one anonymous call inside an otherwise
-  # session-scoped region.
+  # read), or `nil`. Passing `nil`, or a user or session that carries no
+  # token, runs the block ANONYMOUSLY: requests inside it send neither a
+  # session token nor the master key, and a client's bound token is not
+  # used either. This is useful for performing one anonymous call inside an
+  # otherwise session-scoped region. A call inside the block can still opt
+  # out with an explicit `session_token:` or `use_master_key: true`.
   #
   # Fiber-local, not thread-local: concurrent fibers (and threads, since
   # each thread starts with its own root fiber) do not share state.
@@ -156,17 +159,37 @@ module Parse
         "token is refused so the block cannot silently execute with master-key " \
         "authority — pass a valid session token, or `nil` for no ambient session."
     end
-    Fiber[SESSION_TOKEN_STATE_KEY] = resolved
+    # `nil` (no token, or a user/session without one) installs the
+    # anonymous sentinel rather than clearing the slot. A cleared slot meant
+    # "no ambient", which the request layer resolves to the master key on a
+    # master-keyed client: the opposite of the documented anonymous block.
+    Fiber[SESSION_TOKEN_STATE_KEY] = resolved.nil? ? ANONYMOUS_SESSION : resolved
     yield
   ensure
     Fiber[SESSION_TOKEN_STATE_KEY] = previous
   end
 
+  # Fiber-state sentinel installed by `Parse.with_session(nil)`. The request
+  # layer treats it as "anonymous": no session token and no master key.
+  # @!visibility private
+  ANONYMOUS_SESSION = :__parse_anonymous_session__
+
   # The ambient session token set by {.with_session} for the current
-  # fiber, or `nil` when not inside such a block.
+  # fiber, or `nil` when not inside such a block or inside an anonymous
+  # `with_session(nil)` block (see {.anonymous_session?}).
   # @return [String, nil]
   def self.current_session_token
-    Fiber[SESSION_TOKEN_STATE_KEY]
+    value = Fiber[SESSION_TOKEN_STATE_KEY]
+    value == ANONYMOUS_SESSION ? nil : value
+  end
+
+  # Whether the current fiber is inside an anonymous `Parse.with_session(nil)`
+  # block (directly, or nested without a token-bearing block inside it).
+  # Requests there carry no session token and no master key unless the call
+  # passes `session_token:` or `use_master_key: true` explicitly.
+  # @return [Boolean]
+  def self.anonymous_session?
+    Fiber[SESSION_TOKEN_STATE_KEY] == ANONYMOUS_SESSION
   end
 
   # @!visibility private
@@ -776,10 +799,17 @@ module Parse
     #   - the name singularizes to a *different* string (i.e. looks plural),
     #   - the singular form does NOT already end in `s` (per design: classes
     #     whose name ends in `s` are not auto-aliased),
-    #   - the singular constant is defined (searching ancestors so a
-    #     top-level model is visible from a nested reference) and is a
-    #     `Parse::Object` subclass,
-    #   - the plural is not already defined on the referencing module.
+    #   - the singular constant resolves from the referencing module and
+    #     is a `Parse::Object` subclass,
+    #   - the plural is not already defined in the singular class's own
+    #     namespace.
+    #
+    # The alias is installed in the namespace that defines the singular
+    # class (`Object` for a top-level `Post`, `Blog` for `Blog::Post`), never
+    # on the module where the lookup happened. A reference to `Posts` from
+    # inside an unrelated class or module therefore resolves, but does not
+    # add a `Posts` constant to that module. A frozen namespace is left
+    # alone (no `FrozenError`).
     #
     # @param mod [Module] the module/class on which `const_missing` fired.
     # @param name [Symbol] the missing constant name.
@@ -795,15 +825,40 @@ module Parse
       return nil unless mod.const_defined?(sym, true)
       klass = mod.const_get(sym)
       return nil unless klass.is_a?(Class) && klass < Parse::Object
-      return nil if mod.const_defined?(name, false)
-      mod.const_set(name, klass)
+      home = __pluralized_alias_home(klass, sym)
+      return nil if home.nil?
+      if home.const_defined?(name, false)
+        existing = home.const_get(name, false)
+        return existing.equal?(klass) ? klass : nil
+      end
+      return nil if home.frozen?
+      home.const_set(name, klass)
       klass
-    rescue NameError, LoadError
+    rescue NameError, LoadError, FrozenError
       # const_get/const_defined? can raise on malformed names or autoload
       # failures; never let alias resolution mask the original lookup.
       nil
     end
 
+    # @!visibility private
+    # The namespace that directly defines `klass` under the name `singular`,
+    # which is where its pluralized alias belongs. nil when it cannot be
+    # determined (anonymous class, or a constant that only resolves through
+    # an ancestor).
+    # @param klass [Class]
+    # @param singular [Symbol]
+    # @return [Module, nil]
+    def __pluralized_alias_home(klass, singular)
+      name = klass.name
+      return nil if name.nil?
+      parent_name = name.rpartition("::").first
+      home = parent_name.empty? ? ::Object : ::Object.const_get(parent_name, false)
+      return nil unless home.is_a?(Module) && home.const_defined?(singular, false)
+      home.const_get(singular, false).equal?(klass) ? home : nil
+    rescue NameError
+      nil
+    end
+
     # Verify that every association target across the loaded {Parse::Object}
     # subclasses resolves to a known Parse class. Covers `belongs_to` and
     # `property … as:` pointer targets (via each class's `references`),
@@ -1048,4 +1103,7 @@ Parse._attach_slow_query_subscriber! if Parse.slow_query_threshold_ms
 # already defined. Gated at runtime on Parse.pluralized_aliases?.
 require_relative "model/core/pluralized_aliases"
 
-require_relative "stack/railtie" if defined?(::Rails)
+# Only hook into Rails when railties is loaded. A bare `Rails` module (for
+# example the one rails-html-sanitizer defines) has no `Rails::Railtie`, and
+# subclassing it would abort loading the gem.
+require_relative "stack/railtie" if defined?(::Rails::Railtie)

data/lib/parse/two_factor_auth/user_extension.rb

@@ -50,8 +50,14 @@ module Parse
         def login_with_mfa(username, password, mfa_token)
           raise MFA::RequiredError, "MFA token is required" if mfa_token.blank?
 
+          # `client.login_with_mfa` always goes out without the master key
+          # (see Parse::API::Users#login_with_mfa): with it, Parse Server
+          # would skip this verification and overwrite the enrolled secret.
           response = client.login_with_mfa(username, password, mfa_token)
-          return nil unless response.success?
+          unless response.success?
+            raise MFA::VerificationError, response.error.to_s if MFA.invalid_token_response?(response)
+            return nil
+          end
 
           # Self-fetch trust: an MFA login returns the authenticating
           # user's own row, so authData here is legitimately theirs.
@@ -447,8 +453,14 @@ module Parse
       #   user = Parse::User.first
       #   user.login_with_mfa!("password123", "123456")
       def login_with_mfa!(password, mfa_token = nil)
+        raise MFA::RequiredError, "MFA token is required for this account" if mfa_token.blank?
         response = client.login_with_mfa(username.to_s, password.to_s, mfa_token)
-        apply_attributes!(response.result)
+        unless response.success?
+          raise MFA::VerificationError, response.error.to_s if MFA.invalid_token_response?(response)
+          return false
+        end
+        # Self-fetch trust: the login response is this user's own row.
+        self.class.with_authdata_trust { apply_attributes!(response.result) }
         session_token.present?
       rescue Parse::Client::ResponseError => e
         if e.message.include?("Missing additional authData")

data/lib/parse/two_factor_auth.rb

@@ -62,6 +62,17 @@ module Parse
       end
     end
 
+    # Whether a failed login response is Parse Server rejecting the MFA code
+    # (as opposed to wrong credentials). Parse Server's MFA adapter throws a
+    # bare string, which reaches the client as code 141 with the adapter's
+    # message, e.g. "Invalid MFA token".
+    # @!visibility private
+    # @param response [Parse::Response]
+    # @return [Boolean]
+    def self.invalid_token_response?(response)
+      response.respond_to?(:error) && response.error.to_s.start_with?("Invalid MFA token", "Please enter the token")
+    end
+
     # Error raised when MFA is required but not provided
     class RequiredError < Parse::Error
       def initialize(message = "MFA token is required for this account")

data/lib/parse/vector_search/hybrid.rb

@@ -463,10 +463,33 @@ module Parse
           protected_fields = Parse::CLPScope.protected_fields_for(
             collection_name, resolution.permission_strings,
           )
+          # Unconditional: `Parse::AtlasSearch` may already be partially
+          # defined by a submodule (session, protected_paths) without the
+          # main file loaded. `require_relative` is idempotent.
+          require_relative "../atlas_search"
+          Parse::AtlasSearch.send(:assert_search_fields_allowed!,
+                                  Array(lex[:fields]).map(&:to_s), protected_fields, resolution)
           Parse::VectorSearch.validate_query_vector!(vec[:query_vector])
           Parse::PipelineSecurity.validate_filter!(vec[:vector_filter]) if vec[:vector_filter]
           Parse::PipelineSecurity.validate_filter!(vec[:filter]) if vec[:filter]
           Parse::PipelineSecurity.validate_filter!(lex[:filter]) if lex[:filter]
+          # The client path gets these refusals from AtlasSearch.search and
+          # VectorSearch.search. The native path builds its own pipeline,
+          # so apply the same protected-field refusals here: the vector
+          # field, every filter's predicate keys, and `$expr` references.
+          Parse::VectorSearch.send(:assert_protected_fields_untouched!,
+                                   collection_name, vec[:field].to_s, vec[:filter],
+                                   vec[:vector_filter], protected_fields, resolution)
+          if lex[:filter] && !lex[:filter].empty? && !resolution.master?
+            Parse::PipelineSecurity.refuse_protected_field_references!(
+              [{ "$match" => lex[:filter] }], collection_name, resolution,
+            )
+            Parse::AtlasSearch::ProtectedPaths.assert_filter_allowed!(
+              lex[:filter], protected_fields, resolution,
+              collection_name: collection_name,
+              method_name: "Parse::VectorSearch::Hybrid.search",
+            )
+          end
 
           pipeline = native_pipeline_for(lex, vec, oversample, resolution,
                                          k_constant: k_constant, weights: weights, limit: oversample)
@@ -672,27 +695,22 @@ module Parse
         end
 
         def assert_clp_find!(collection_name, resolution)
-          return if resolution.nil? || resolution.master?
-          unless Parse::CLPScope.permits?(collection_name, :find, resolution.permission_strings)
-            raise Parse::CLPScope::Denied.new(
-              collection_name, :find,
-              "CLP refuses find on '#{collection_name}' for the current hybrid-search scope.",
-            )
-          end
+          # Same CLP branch evaluation as Parse::MongoDB.aggregate (public,
+          # user, and role grants first; then pointerFields / readUserFields).
+          # Raises Parse::CLPScope::Denied when the scope cannot find at all.
+          Parse::CLPScope.row_constraint_for!(collection_name, :find, resolution,
+                                              label: "hybrid-search")
+          nil
         end
 
         def resolve_pointer_fields!(collection_name, resolution)
-          return nil if resolution.nil? || resolution.master?
-          pointer_fields = Parse::CLPScope.pointer_fields_for(collection_name, :find)
-          return nil if pointer_fields.nil?
-          if resolution.user_id.nil?
-            raise Parse::CLPScope::Denied.new(
-              collection_name, :find,
-              "CLP requires user identity (pointerFields=#{pointer_fields.inspect}) " \
-              "but the current hybrid-search scope has no user_id.",
-            )
-          end
-          pointer_fields
+          # nil when a public, user, or role grant already permits every row
+          # (Parse Server ignores pointer permissions then); otherwise the
+          # pointerFields plus readUserFields the rows must match. The older
+          # permits? / pointer_fields_for pair missed readUserFields entirely
+          # and over-restricted a public grant that also listed pointerFields.
+          Parse::CLPScope.row_constraint_for!(collection_name, :find, resolution,
+                                              label: "hybrid-search")
         end
 
         def validate_weights!(weights)

data/lib/parse/vector_search/index_definition.rb

@@ -0,0 +1,237 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module VectorSearch
+    # Derives an Atlas `vectorSearch` index definition from a model's
+    # declarations, so the index an operator deploys matches what the SDK
+    # will query instead of being written by hand.
+    #
+    # Sources, all read from the model:
+    #
+    # * the `:vector` property: path, `numDimensions` (`dimensions:`),
+    #   `similarity` (`similarity:`, default `cosine`), and the optional
+    #   index-side `quantization:` (`:scalar` / `:binary`);
+    # * `agent_searchable filter_fields:`, the fields the agent tool lets a
+    #   caller pass as `vector_filter:` (pointer fields map to their
+    #   `_p_<column>` storage path, matching the pointer translation
+    #   {Parse::Retrieval.retrieve} applies);
+    # * the `agent_tenant_scope` field, which retrieval folds into
+    #   `$vectorSearch.filter` on every scoped query.
+    #
+    # Output is deterministic: the vector entry first, then filter entries
+    # sorted by path, keys in a fixed order. Generating is side-effect free;
+    # applying an index stays explicit through
+    # {Parse::Schema::SearchIndexMigrator} (declare it with the
+    # `vector_search_index` model macro and run `apply_search_indexes!`).
+    #
+    # @example
+    #   class Article < Parse::Object
+    #     property :embedding, :vector, dimensions: 1024, similarity: :dotProduct,
+    #                                   quantization: :scalar
+    #     agent_searchable field: :embedding, filter_fields: %i[category]
+    #     vector_search_index "article_vec"   # generated; applied explicitly
+    #   end
+    #
+    #   Parse::VectorSearch::IndexDefinition.build(Article)
+    #   # => { "fields" => [
+    #   #      { "type" => "vector", "path" => "embedding", "numDimensions" => 1024,
+    #   #        "similarity" => "dotProduct", "quantization" => "scalar" },
+    #   #      { "type" => "filter", "path" => "category" } ] }
+    module IndexDefinition
+      # Similarity emitted when the property declares none. Atlas requires
+      # one; cosine is the safe choice for unit-normalized embeddings.
+      DEFAULT_SIMILARITY = "cosine"
+
+      # Index-side quantization values accepted on a `:vector` property.
+      QUANTIZATIONS = %w[scalar binary].freeze
+
+      # Key order for each field entry, so serialized output is stable.
+      VECTOR_KEY_ORDER = %w[type path numDimensions similarity quantization].freeze
+
+      module_function
+
+      # Build the definition for one `:vector` field of `model_class`.
+      #
+      # @param model_class [Class] a Parse::Object subclass.
+      # @param field [Symbol, String, nil] the `:vector` property; may be
+      #   omitted when the class declares exactly one searchable vector.
+      # @return [Hash] a string-keyed `{ "fields" => [...] }` definition.
+      # @raise [ArgumentError] when the field cannot be resolved.
+      def build(model_class, field: nil)
+        field_sym = resolve_field!(model_class, field)
+        meta = model_class.vector_properties.fetch(field_sym)
+
+        vector = {
+          "type" => "vector",
+          # The stored column (field_map), which is what $vectorSearch
+          # queries: `body_embedding` is saved as `bodyEmbedding`.
+          "path" => (model_class.respond_to?(:vector_storage_path) ? model_class.vector_storage_path(field_sym) : field_sym.to_s),
+          "numDimensions" => meta[:dimensions],
+          "similarity" => (meta[:similarity] || DEFAULT_SIMILARITY).to_s,
+        }
+        vector["quantization"] = meta[:quantization].to_s if meta[:quantization]
+
+        filters = filter_paths(model_class).map { |path| { "type" => "filter", "path" => path } }
+        { "fields" => [order_keys(vector)] + filters }
+      end
+
+      # Preview the declaration a `vector_search_index` macro would apply.
+      #
+      # @return [Hash] `{ name:, type: "vectorSearch", definition: }`.
+      def preview(model_class, name:, field: nil)
+        { name: name.to_s, type: "vectorSearch", definition: build(model_class, field: field) }
+      end
+
+      # Structured, deterministic comparison of a declared definition with a
+      # live one. Accepts either definitions or index documents carrying
+      # `latestDefinition` (the shape `$listSearchIndexes` returns).
+      #
+      # @param declared [Hash] the generated (or declared) definition.
+      # @param live [Hash, nil] the live definition or index document.
+      # @return [Hash] `{ in_sync:, vector: { key => { declared:, live: } },
+      #   filters_missing: [...], filters_extra: [...] }`. `vector` lists
+      #   only differing keys; `filters_missing` are declared filter paths
+      #   absent from the live index (scoped queries on them fail
+      #   Atlas-side), `filters_extra` are live paths not declared.
+      def diff(declared, live)
+        declared_defn = definition_of(declared)
+        live_defn = definition_of(live)
+
+        d_vec = vector_entry(declared_defn)
+        # Compare against the live vector entry for the SAME path, so an
+        # index with several vector fields does not report false drift.
+        l_vec = vector_entry(live_defn, path: d_vec["path"])
+        vector_changes = {}
+        (VECTOR_KEY_ORDER - %w[type]).each do |key|
+          dv = normalize_vector_value(key, d_vec[key])
+          lv = normalize_vector_value(key, l_vec[key])
+          vector_changes[key] = { declared: dv, live: lv } unless dv == lv
+        end
+
+        d_filters = filter_paths_of(declared_defn)
+        l_filters = filter_paths_of(live_defn)
+        missing = (d_filters - l_filters).sort
+        extra = (l_filters - d_filters).sort
+
+        {
+          in_sync: vector_changes.empty? && missing.empty? && extra.empty?,
+          vector: vector_changes,
+          filters_missing: missing,
+          filters_extra: extra,
+        }
+      end
+
+      # @!visibility private
+      def resolve_field!(model_class, field)
+        unless model_class.respond_to?(:vector_properties)
+          raise ArgumentError, "#{model_class.inspect} declares no :vector properties."
+        end
+        props = model_class.vector_properties
+        searchable = props.keys.reject { |k| props[k][:searchable] == false }
+        if field
+          sym = field.to_sym
+          unless searchable.include?(sym)
+            raise ArgumentError,
+                  "#{model_class}: :#{sym} is not a searchable :vector property " \
+                  "(searchable: #{searchable.inspect})."
+          end
+          return sym
+        end
+        return searchable.first if searchable.length == 1
+        raise ArgumentError,
+              "#{model_class}: cannot infer the vector field (searchable: #{searchable.inspect}); " \
+              "pass field:."
+      end
+
+      # @!visibility private
+      # Filter paths the SDK pre-filters on for this class, deduplicated and
+      # sorted. Tenant path matches the resolution the migrator's
+      # augmentation and first-query drift check use.
+      def filter_paths(model_class)
+        paths = []
+        class_name = model_class.parse_class
+        if defined?(Parse::Agent::MetadataRegistry)
+          Parse::Agent::MetadataRegistry.searchable_filter_fields(class_name).each do |f|
+            paths << storage_path(model_class, f)
+          end
+          rule = Parse::Agent::MetadataRegistry.tenant_scope_rule(class_name)
+          paths << wire_name(model_class, rule[:field]) if rule
+        end
+        paths.compact.uniq.sort
+      end
+
+      # @!visibility private
+      def storage_path(model_class, field)
+        wire = wire_name(model_class, field)
+        type = model_class.respond_to?(:fields) ? model_class.fields[field.to_sym] : nil
+        type == :pointer ? "_p_#{wire}" : wire
+      end
+
+      # @!visibility private
+      def wire_name(model_class, field)
+        sym = field.to_sym
+        fmap = model_class.respond_to?(:field_map) ? model_class.field_map : {}
+        (fmap[sym] || sym.to_s.columnize).to_s
+      end
+
+      # @!visibility private
+      def order_keys(entry)
+        VECTOR_KEY_ORDER.each_with_object({}) { |k, h| h[k] = entry[k] if entry.key?(k) }
+      end
+
+      # @!visibility private
+      def definition_of(value)
+        return {} unless value.is_a?(Hash)
+        inner = value["latestDefinition"] || value[:latestDefinition] ||
+                value[:definition] || value["definition"]
+        inner.is_a?(Hash) ? inner : value
+      end
+
+      # @!visibility private
+      def fields_of(defn)
+        Array(defn["fields"] || defn[:fields]).select { |f| f.is_a?(Hash) }
+      end
+
+      # @!visibility private
+      def vector_entry(defn, path: nil)
+        vectors = fields_of(defn).select { |f| (f["type"] || f[:type]).to_s == "vector" }
+        entry = (path && vectors.find { |f| (f["path"] || f[:path]).to_s == path.to_s }) || vectors.first || {}
+        entry.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+      end
+
+      # @!visibility private
+      def filter_paths_of(defn)
+        fields_of(defn).select { |f| (f["type"] || f[:type]).to_s == "filter" }
+                       .map { |f| (f["path"] || f[:path]).to_s }.uniq.sort
+      end
+
+      # @!visibility private
+      # An absent `quantization` means none on both sides; numbers compare
+      # as integers; everything else as strings.
+      def normalize_vector_value(key, value)
+        case key
+        when "quantization"
+          value.nil? || value.to_s.empty? ? "none" : value.to_s
+        when "numDimensions"
+          # A malformed live value is reported as drift, not raised.
+          value.nil? ? nil : (Integer(value) rescue value.to_s)
+        else
+          value&.to_s
+        end
+      end
+    end
+  end
+
+  module Schema
+    class << self
+      # Generate the Atlas `vectorSearch` index definition for a model's
+      # `:vector` field. See {Parse::VectorSearch::IndexDefinition.build}.
+      #
+      # @return [Hash]
+      def vector_index_definition(model_class, field: nil)
+        Parse::VectorSearch::IndexDefinition.build(model_class, field: field)
+      end
+    end
+  end
+end

data/lib/parse/vector_search.rb

@@ -5,6 +5,7 @@ require_relative "pipeline_security"
 require_relative "acl_scope"
 require_relative "clp_scope"
 require_relative "mongodb"
+require_relative "atlas_search/protected_paths"
 
 module Parse
   # Atlas Vector Search entry point. Routes through `Parse::MongoDB`
@@ -306,6 +307,8 @@ module Parse
         protected_fields = Parse::CLPScope.protected_fields_for(
           collection_name, resolution.permission_strings,
         )
+        assert_protected_fields_untouched!(collection_name, path, filter, vector_filter,
+                                           protected_fields, resolution)
 
         vs_stage = {
           "index" => index_name.to_s,
@@ -453,31 +456,55 @@ module Parse
       # scope, refuse the call when the resolved claim set can't
       # `find` on the collection. Mirrors `Parse::AtlasSearch.search`.
       def assert_clp_find!(collection_name, resolution)
-        return if resolution.nil? || resolution.master?
-        unless Parse::CLPScope.permits?(collection_name, :find, resolution.permission_strings)
-          raise Parse::CLPScope::Denied.new(
-            collection_name, :find,
-            "CLP refuses find on '#{collection_name}' for the current VectorSearch scope.",
+        # Same CLP branch evaluation as Parse::MongoDB.aggregate (public,
+        # user, and role grants first; then pointerFields / readUserFields).
+        # Raises Parse::CLPScope::Denied when the scope cannot find at all.
+        Parse::CLPScope.row_constraint_for!(collection_name, :find, resolution,
+                                            label: "VectorSearch")
+        nil
+      end
+
+      # Resolve and return pointerFields for `find` on the collection.
+      # Refuse a scoped vector search that lets a protected field decide
+      # which rows match or how they rank: a protected vector `field:`, a
+      # `filter:` / `vector_filter:` predicate keyed on a protected field
+      # (top level or under $and/$or/$nor/$not, dotted or `_p_` form), or
+      # an `$expr` reference to one. The output strip alone does not close
+      # that oracle. Master scopes and classes with nothing protected are
+      # unaffected.
+      #
+      # @raise [Parse::CLPScope::Denied]
+      def assert_protected_fields_untouched!(collection_name, path, filter, vector_filter,
+                                             protected_fields, resolution)
+        paths = Parse::AtlasSearch::ProtectedPaths
+        return unless paths.enforce?(resolution, protected_fields)
+        paths.assert_paths_allowed!(path, protected_fields, resolution,
+                                    collection_name: collection_name,
+                                    method_name: "Parse::VectorSearch.search",
+                                    what: "vector field")
+        [filter, vector_filter].each do |f|
+          next if f.nil? || f.empty?
+          Parse::PipelineSecurity.refuse_protected_field_references!(
+            [{ "$match" => f }], collection_name, resolution,
           )
+          paths.assert_filter_allowed!(f, protected_fields, resolution,
+                                       collection_name: collection_name,
+                                       method_name: "Parse::VectorSearch.search")
         end
+        nil
       end
 
-      # Resolve and return pointerFields for `find` on the collection.
       # Raises CLPScope::Denied when pointerFields is set but the
       # current scope has no user_id (acl_role-only / public agents).
       # Returns nil when master-mode or no pointerFields entry exists.
       def resolve_pointer_fields!(collection_name, resolution)
-        return nil if resolution.nil? || resolution.master?
-        pointer_fields = Parse::CLPScope.pointer_fields_for(collection_name, :find)
-        return nil if pointer_fields.nil?
-        if resolution.user_id.nil?
-          raise Parse::CLPScope::Denied.new(
-            collection_name, :find,
-            "CLP requires user identity (pointerFields=#{pointer_fields.inspect}) " \
-            "but the current VectorSearch scope has no user_id.",
-          )
-        end
-        pointer_fields
+        # nil when a public, user, or role grant already permits every row
+        # (Parse Server ignores pointer permissions then); otherwise the
+        # pointerFields plus readUserFields the rows must match. The older
+        # permits? / pointer_fields_for pair missed readUserFields entirely
+        # and over-restricted a public grant that also listed pointerFields.
+        Parse::CLPScope.row_constraint_for!(collection_name, :find, resolution,
+                                            label: "VectorSearch")
       end
 
       # Execute the pipeline directly against the MongoDB collection.
@@ -501,3 +528,5 @@ module Parse
     @default_index = nil
   end
 end
+
+require_relative "vector_search/index_definition"