parse-stack-next 4.5.0 → 5.0.1

data/lib/parse/agent.rb

@@ -455,6 +455,37 @@ module Parse
     WRITE_GATED_TOOLS  = %i[create_object update_object delete_object].freeze
     SCHEMA_GATED_TOOLS = %i[create_class delete_class].freeze
 
+    # Built-in tools that are safe to dispatch when the agent runs on a
+    # client (no master_key) with a session_token. Parse Server natively
+    # enforces ACL + CLP + protectedFields on these REST endpoints, so the
+    # SDK does not need to add an enforcement layer for them.
+    #
+    # The list is the MODE CEILING in client mode: an operator's `tools:`
+    # filter may narrow further, but cannot widen past this set. Anything
+    # not in CLIENT_SAFE_READ_TOOLS or CLIENT_SAFE_MUTATION_TOOLS is
+    # refused at dispatch when @client_mode is true, including custom
+    # registered tools (which must opt in explicitly via
+    # `Parse::Agent::Tools.register(client_safe: true, ...)`).
+    CLIENT_SAFE_READ_TOOLS = %i[
+      list_tools
+      get_object
+      get_objects
+      query_class
+      count_objects
+      get_sample_objects
+    ].freeze
+
+    # Built-in mutation tools that route through session-token REST and
+    # are therefore enforceable by Parse Server's native ACL/CLP. Gated
+    # additionally by the per-agent +allow_mutations:+ kwarg in client
+    # mode (default false) and by the existing process-level env vars
+    # (PARSE_AGENT_ALLOW_WRITE_TOOLS + PARSE_AGENT_ALLOW_RAW_CRUD).
+    CLIENT_SAFE_MUTATION_TOOLS = %i[
+      create_object
+      update_object
+      delete_object
+    ].freeze
+
     # Truthy ENV-var values. Anything else (including unset) means disabled.
     ENV_TRUTHY_RE = /\A(1|true|yes|on)\z/i.freeze
 
@@ -590,6 +621,24 @@ module Parse
     # @return [Parse::Client] the Parse client instance to use
     attr_reader :client
 
+    # @return [Boolean] whether the agent runs in client mode (its
+    #   Parse::Client has no master_key). In client mode the dispatchable
+    #   tool set is restricted to {CLIENT_SAFE_READ_TOOLS},
+    #   {CLIENT_SAFE_MUTATION_TOOLS} (gated on {#allow_mutations?}), and
+    #   any registered tool declared +client_safe: true+.
+    def client_mode?
+      @client_mode == true
+    end
+
+    # @return [Boolean] whether this agent may dispatch raw mutation
+    #   tools (create_object/update_object/delete_object). Layered with
+    #   the process-level PARSE_AGENT_ALLOW_WRITE_TOOLS +
+    #   PARSE_AGENT_ALLOW_RAW_CRUD env vars (all three must be true).
+    #   Default: +false+ in client mode, +true+ in master-key mode.
+    def allow_mutations?
+      @allow_mutations == true
+    end
+
     # @return [Array<Hash>] log of operations performed in this session
     attr_reader :operation_log
 
@@ -604,7 +653,7 @@ module Parse
 
     # @return [String, nil] caller-supplied identifier that ties multiple
     #   tool calls into a single logical conversation. Set by the transport
-    #   layer (MCPRackApp reads X-MCP-Session-Id) or directly by an
+    #   layer (MCPRackApp reads Mcp-Session-Id) or directly by an
     #   embedder. Included in every `parse.agent.tool_call` notification
     #   payload as `:correlation_id` when present. Sanitized to a max of
     #   128 characters from the set `[A-Za-z0-9._-]` to prevent log
@@ -1068,7 +1117,8 @@ module Parse
                    tools: nil, methods: nil, classes: nil, filters: nil,
                    parent: nil, recursion_depth: nil,
                    strict_tool_filter: nil, strict_class_filter: nil,
-                   master_atlas: nil)
+                   master_atlas: nil,
+                   allow_mutations: nil)
       # SECURITY: Mutually exclusive identity inputs. `acl_user:` and
       # `acl_role:` are unverified constructor assertions (the SDK does
       # not round-trip them to Parse Server for validation the way
@@ -1271,6 +1321,78 @@ module Parse
       @tenant_id       = tenant_id
       @master_atlas    = master_atlas == true
 
+      # Client-mode detection. An agent runs in CLIENT MODE when its
+      # underlying Parse::Client has no master_key AND it was constructed
+      # with a non-empty session_token. This is the explicit
+      # "session-token-on-a-public-client" posture: every tool call must
+      # route through a REST endpoint Parse Server natively authorizes
+      # (ACL + CLP + protectedFields) because the SDK has no master-key
+      # fallback to lean on.
+      #
+      # The "no master_key, no session_token" case is NOT treated as
+      # client mode — that's a misconfigured master-key-posture agent
+      # whose REST calls will fail with 401 at dispatch. The existing
+      # one-time master-key warning surfaces this; refusing here would
+      # break compatibility with test harnesses and bootstrap factories
+      # that construct agents before identity is threaded in.
+      #
+      # acl_user / acl_role on a no-master-key client are refused
+      # regardless of session_token presence: they are unverified
+      # constructor assertions with no REST equivalent — Parse Server's
+      # REST surface offers no "act as user-pointer" affordance, so the
+      # SDK cannot honor them without a master key.
+      no_master_key = @client.respond_to?(:master_key) && @client.master_key.nil?
+      session_token_present = !@session_token.nil? && !@session_token.to_s.empty?
+      @client_mode = no_master_key && session_token_present
+
+      if no_master_key && (@acl_user_scope || @acl_role_scope)
+        raise ArgumentError,
+              "Parse::Agent: acl_user: and acl_role: require a Parse::Client " \
+              "with a master_key (they are unverified constructor assertions " \
+              "the SDK can only honor via master-key REST). The supplied " \
+              "client has no master_key. Use session_token: instead, or " \
+              "switch to a master-key client."
+      end
+
+      # Per-agent mutation gate. Layered ON TOP of the process-level
+      # PARSE_AGENT_ALLOW_WRITE_TOOLS / PARSE_AGENT_ALLOW_RAW_CRUD env
+      # vars — BOTH must be true for raw create/update/delete to
+      # dispatch. Defaults:
+      #   * Client mode  → false (default-deny; opt in per agent)
+      #   * Master-key   → true  (back-compat; existing operators have
+      #                           only the env vars today, and adding a
+      #                           false default would silently disable
+      #                           writes for every existing master-key
+      #                           agent).
+      # When +parent:+ is supplied, the child cannot widen the parent's
+      # gate: if parent.allow_mutations? is false, child must also be
+      # false. Default-on-nil inherits the parent's value verbatim so
+      # the safe path (omit kwarg) is trivially correct.
+      if parent
+        parent_allows = parent.respond_to?(:allow_mutations?) ? parent.allow_mutations? : true
+        resolved_allow_mutations =
+          if allow_mutations.nil?
+            parent_allows
+          else
+            allow_mutations == true
+          end
+        if resolved_allow_mutations && !parent_allows
+          raise ArgumentError,
+                "sub-agent allow_mutations: true exceeds parent's " \
+                "allow_mutations: false. A sub-agent cannot widen the " \
+                "parent's mutation gate — drop the override (omit to inherit) " \
+                "or pass allow_mutations: false explicitly."
+        end
+        @allow_mutations = resolved_allow_mutations
+      else
+        @allow_mutations =
+          if allow_mutations.nil?
+            !@client_mode
+          else
+            allow_mutations == true
+          end
+      end
+
       # Resolve the ACL scope ONCE at construction into a frozen
       # Parse::ACLScope::Resolution. Three modes:
       #
@@ -1561,12 +1683,24 @@ module Parse
     #
     # Resolution order is strict: builtin permission-tier tools are unioned
     # with registered tools whose declared permission is <= the agent's
-    # tier, then the per-instance filter narrows that set. The filter
-    # cannot elevate above the permission-tier output — `tools: { only:
+    # tier, then the per-instance filter narrows that set, then in client
+    # mode the client-safe ceiling narrows it further. None of these
+    # steps can elevate above its input — `tools: { only:
     # [:delete_object] }` on a `:readonly` agent still excludes
-    # `delete_object`. This invariant is the structural correctness of
-    # the layered design (env-gates ▷ permission tier ▷ per-instance
-    # filter) and must not be violated by future changes.
+    # `delete_object`, and `tools: { only: [:aggregate] }` on a
+    # client-mode agent still excludes `aggregate`. This invariant is
+    # the structural correctness of the layered design (mode ceiling ▷
+    # env-gates ▷ permission tier ▷ per-instance filter) and must not
+    # be violated by future changes.
+    #
+    # The client-mode intersection here is what makes the advertised
+    # catalog (MCP `tools/list`, OpenAI function definitions, the
+    # describe output) match the set the dispatch path will actually
+    # dispatch. Without it, an LLM would see a refused tool in its
+    # catalog, attempt it, and learn about the refusal only via an
+    # access-denied error — wasting turns on tools it never could have
+    # called. The dispatch-path gate in {#execute} remains as the
+    # belt-and-suspenders enforcement point.
     #
     # @return [Array<Symbol>] list of allowed tool names
     def allowed_tools
@@ -1575,6 +1709,14 @@ module Parse
 
       permitted = permitted & @tool_filter_only.to_a   if @tool_filter_only
       permitted = permitted - @tool_filter_except.to_a if @tool_filter_except
+
+      if @client_mode
+        permitted = permitted.select { |sym| Parse::Agent::Tools.client_safe?(sym) }
+        unless @allow_mutations
+          permitted -= Parse::Agent::CLIENT_SAFE_MUTATION_TOOLS
+        end
+      end
+
       permitted
     end
 
@@ -1692,10 +1834,64 @@ module Parse
       end
 
       unless tool_allowed?(tool_name)
-        # Distinguish "filter excluded it" (tier permits, instance filter
-        # narrowed it away) from "tier never allowed it" so consumers see
-        # the meaningful diagnostic. Same denial outcome either way — only
-        # the error_code + message differ.
+        # Distinguish refusal reasons so the LLM (and SOC tooling) see
+        # the meaningful diagnostic. Resolution order matters — the
+        # client-mode ceiling and the per-agent mutation gate emit
+        # specific :access_denied messages so an operator can tell
+        # which knob refused the call. The generic "filter excluded
+        # it" / "tier never allowed it" branches catch what's left.
+
+        # Operator-filter precedence: when the per-instance `tools:`
+        # filter is the binding gate, prefer the filter message even
+        # if the client-mode ceiling or mutation gate would also have
+        # refused. Otherwise an operator who set
+        # `tools: { except: [:create_object] }` AND `allow_mutations:
+        # false` is told "set allow_mutations: true", which won't
+        # actually help — the filter is the real blocker.
+        operator_filter_excludes =
+          (@tool_filter_except && @tool_filter_except.include?(tool_name)) ||
+          (@tool_filter_only && !@tool_filter_only.include?(tool_name))
+        if operator_filter_excludes && tier_permits_tool?(tool_name)
+          return error_response(
+                   "Tool '#{tool_name}' is not enabled for this agent instance " \
+                   "(excluded by the configured tools: filter).",
+                   error_code: :tool_filtered,
+                 )
+        end
+
+        if @client_mode &&
+           Parse::Agent::CLIENT_SAFE_MUTATION_TOOLS.include?(tool_name) &&
+           !@allow_mutations &&
+           Parse::Agent::Tools.client_safe?(tool_name)
+          # The tool is REST-safe (the mode ceiling would let it
+          # through) but the per-agent mutation gate is closed.
+          # Naming the gate specifically avoids sending operators to
+          # the env-var rabbit hole when the real fix is the
+          # constructor kwarg.
+          return error_response(
+                   "Raw mutation tool '#{tool_name}' is disabled for this " \
+                   "client-mode agent. Construct the agent with " \
+                   "allow_mutations: true to enable write/delete dispatch. " \
+                   "The process-level PARSE_AGENT_ALLOW_WRITE_TOOLS / " \
+                   "PARSE_AGENT_ALLOW_RAW_CRUD env vars must additionally " \
+                   "be set on the deployment.",
+                   error_code: :access_denied,
+                 )
+        end
+        if @client_mode && !Parse::Agent::Tools.client_safe?(tool_name)
+          # Mode ceiling. Tool requires either master-key REST or
+          # mongo-direct, neither of which a client-mode agent has.
+          # Refuse with a specific message so the LLM doesn't retry.
+          return error_response(
+                   "Tool '#{tool_name}' is not available to client-mode agents. " \
+                   "Client mode (no master_key on the underlying Parse::Client) " \
+                   "restricts dispatch to session-token-authorized REST tools: " \
+                   "#{(CLIENT_SAFE_READ_TOOLS + CLIENT_SAFE_MUTATION_TOOLS).sort.join(", ")}, " \
+                   "plus any custom tool registered with client_safe: true. " \
+                   "Refused at the mode ceiling.",
+                   error_code: :access_denied,
+                 )
+        end
         if tier_permits_tool?(tool_name)
           return error_response(
                    "Tool '#{tool_name}' is not enabled for this agent instance " \
@@ -1724,10 +1920,11 @@ module Parse
       # also re-opening the generic create_object/update_object surface
       # (which additionally requires RAW_CRUD=true).
       if WRITE_GATED_TOOLS.include?(tool_name) &&
-         !(Parse::Agent.write_tools_enabled? && Parse::Agent.raw_crud_enabled?)
+         !(Parse::Agent.write_tools_enabled? && Parse::Agent.raw_crud_enabled? && @allow_mutations)
         missing = []
         missing << "PARSE_AGENT_ALLOW_WRITE_TOOLS=true" unless Parse::Agent.write_tools_enabled?
         missing << "PARSE_AGENT_ALLOW_RAW_CRUD=true"    unless Parse::Agent.raw_crud_enabled?
+        missing << "allow_mutations: true (per-agent kwarg)" unless @allow_mutations
         return error_response(
                  "Raw CRUD tool '#{tool_name}' is disabled. Required: #{missing.join(' AND ')}. " \
                  "Prefer declaring an agent_method on the target class for an intent-based " \

data/lib/parse/api/analytics.rb

@@ -6,12 +6,34 @@ module Parse
     # Defines the Analytics interface for the Parse REST API
     module Analytics
 
-      # Send analytics data.
-      # @param event_name [String] the name of the event.
-      # @param metrics [Hash] the metrics to attach to event.
+      # Send analytics data. Parse Server's default `analyticsAdapter`
+      # is a no-op: events POSTed here are accepted but not persisted
+      # and cannot be read back through Parse Server. Operators who wire
+      # in a custom adapter decide what (if anything) to do with each
+      # event, including whether to cap dimension count — the legacy
+      # parse.com eight-pair cap does NOT apply to Parse Server out of
+      # the box. If you need to read events back, persist them to a
+      # regular `Parse::Object` subclass instead.
+      #
+      # @param event_name [String] the name of the event. Restricted to
+      #   word characters, hyphens, and dots so the value cannot escape
+      #   the `/events/` path segment.
+      # @param metrics [Hash] dimension pairs to attach to the event.
+      # @param opts [Hash] additional options forwarded to {Parse::Client#request}
+      #   (e.g. :session_token, :use_master_key). Analytics events are
+      #   typically public-writable, but a session token can be threaded
+      #   through for installations that require authentication on /events.
+      # @raise [ArgumentError] when `event_name` is empty or contains
+      #   characters outside `[\w\-\.]`.
       # @see http://docs.parseplatform.org/rest/guide/#analytics Parse Analytics
-      def send_analytics(event_name, metrics = {})
-        request :post, "events/#{event_name}", body: metrics
+      def send_analytics(event_name, metrics = {}, **opts)
+        safe = event_name.to_s
+        unless safe.match?(/\A[\w\-\.]+\z/)
+          raise ArgumentError,
+                "Parse::API::Analytics#send_analytics: event_name must contain only " \
+                "word characters, hyphens, or dots (got #{event_name.inspect})"
+        end
+        request :post, "events/#{safe}", body: metrics, opts: opts
       end
     end
   end

data/lib/parse/api/files.rb

@@ -15,12 +15,16 @@ module Parse
       # @param fileName [String] the basename of the file.
       # @param data [Hash] the data related to this file.
       # @param content_type [String] the mime-type of the file.
+      # @param opts [Hash] additional options forwarded to {Parse::Client#request}
+      #   (e.g. :session_token, :use_master_key). When the SDK is running in
+      #   client mode against a Parse Server with `fileUpload.enableForAuthenticatedUser`
+      #   on, a session_token is required for the upload to be accepted.
       # @return [Parse::Response]
-      def create_file(fileName, data = {}, content_type = nil)
+      def create_file(fileName, data = {}, content_type = nil, **opts)
         safe = Parse::API::PathSegment.file!(fileName, kind: "file name")
         headers = {}
         headers.merge!({ Parse::Protocol::CONTENT_TYPE => content_type.to_s }) if content_type.present?
-        response = request :post, "#{FILES_PATH}/#{safe}", body: data, headers: headers
+        response = request :post, "#{FILES_PATH}/#{safe}", body: data, headers: headers, opts: opts
         response.parse_class = Parse::Model::TYPE_FILE
         response
       end

data/lib/parse/api/push.rb

@@ -8,12 +8,29 @@ module Parse
       # @!visibility private
       PUSH_PATH = "push"
 
-      # Update the schema for a collection.
-      # @param payload [Hash] the paylod for the Push notification.
+      # Send a Push notification.
+      #
+      # Parse Server's `POST /parse/push` endpoint is master-key-only —
+      # there is no session-token authorization model for sending pushes,
+      # and a no-master-key client cannot use this method. Calling it
+      # without master-key credentials returns HTTP 403 from the server;
+      # this guard fails closed in the SDK so the deployment's
+      # configuration isn't the only line of defense.
+      #
+      # @param payload [Hash] the payload for the Push notification.
+      # @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]
+      # @raise [Parse::Error::AuthenticationError] when the client has no master key configured.
       # @see http://docs.parseplatform.org/rest/guide/#sending-pushes Sending Pushes
-      def push(payload = {})
-        request :post, PUSH_PATH, body: payload.as_json
+      def push(payload = {}, headers: {}, **opts)
+        unless master_key.is_a?(String) && !master_key.empty?
+          raise Parse::Error::AuthenticationError,
+                "Parse::API::Push#push requires a master key — push notifications " \
+                "have no session-token authorization model in Parse Server"
+        end
+        opts[:use_master_key] = true unless opts.key?(:use_master_key)
+        request :post, PUSH_PATH, body: payload.as_json, headers: headers, opts: opts
       end
     end
   end

data/lib/parse/api/server.rb

@@ -14,6 +14,16 @@ module Parse
       SERVER_INFO_PATH = "serverInfo"
       # @!visibility private
       SERVER_HEALTH_PATH = "health"
+
+      # Minimum supported Parse Server major version. Below this floor the
+      # SDK emits a one-shot deprecation warning per client instance the
+      # first time `server_info` resolves. The threshold tracks "current
+      # major minus two" against Parse Server's release cadence — Parse
+      # Server 9.x is current in 2026, so anything below 7.0 is flagged.
+      # Override with `PARSE_DEPRECATED_SERVER_VERSION_BELOW=6.0` or
+      # silence entirely with `PARSE_SUPPRESS_SERVER_VERSION_WARNING=true`.
+      DEPRECATED_SERVER_VERSION_BELOW = "7.0.0"
+
       # Fetch and cache information about the Parse server configuration. This
       # hash contains information specifically to the configuration of the running
       # parse server.
@@ -23,6 +33,8 @@ module Parse
         response = request :get, SERVER_INFO_PATH
         @server_info = response.error? ? nil :
           response.result.with_indifferent_access
+        warn_if_deprecated_server_version! if @server_info
+        @server_info
       end
 
       # Fetches the status of the server based on the health check.
@@ -37,6 +49,7 @@ module Parse
       # @return [Hash] a hash containing server configuration if available.
       def server_info!
         @server_info = nil
+        @server_version_warned = false
         server_info
       end
 
@@ -45,6 +58,52 @@ module Parse
       def server_version
         server_info.present? ? @server_info[:parseServerVersion] : nil
       end
+
+      private
+
+      # One-shot deprecation warning. The check runs once per client
+      # instance (`@server_version_warned` latches), after `server_info`
+      # has actually resolved against the wire — so unit tests that
+      # never reach a real server don't pay the cost. Silenceable via
+      # ENV so operators on a known-old Parse Server pinned for an
+      # explicit reason can suppress the noise.
+      def warn_if_deprecated_server_version!
+        return if @server_version_warned
+        return if ENV["PARSE_SUPPRESS_SERVER_VERSION_WARNING"] == "true"
+        return unless defined?(Parse) && (!Parse.respond_to?(:suppress_server_version_warning?) || !Parse.suppress_server_version_warning?)
+        version_string = @server_info[:parseServerVersion].to_s
+        return if version_string.empty?
+        floor = ENV["PARSE_DEPRECATED_SERVER_VERSION_BELOW"].to_s
+        floor = DEPRECATED_SERVER_VERSION_BELOW if floor.empty?
+        return unless server_version_below?(version_string, floor)
+        @server_version_warned = true
+        message = "[Parse::Client] DEPRECATION: connected Parse Server version #{version_string} " \
+                  "is below the supported floor #{floor}. Newer Parse Stack releases assume " \
+                  "behaviors (CLP shape, aggregate envelope, $vectorSearch, schema endpoints) " \
+                  "that may not be present on this server. Upgrade Parse Server, or silence " \
+                  "with Parse.suppress_server_version_warning = true / " \
+                  "PARSE_SUPPRESS_SERVER_VERSION_WARNING=true. Override the floor with " \
+                  "PARSE_DEPRECATED_SERVER_VERSION_BELOW=#{floor.sub(/\.0\.0\z/, ".0")}."
+        if defined?(Parse) && Parse.respond_to?(:logger) && Parse.logger
+          Parse.logger.warn(message)
+        else
+          warn message
+        end
+      end
+
+      # Loose semver compare on major.minor. Parse Server publishes
+      # `parseServerVersion` as `"9.0.0"`, `"6.5.7"`, `"8.0.0-alpha.1"`,
+      # etc. We only care about the major (and minor as a tiebreak) for
+      # the deprecation gate. Falls back to "not below" on any
+      # unparseable input so a wire-format surprise never raises.
+      def server_version_below?(actual, floor)
+        actual_parts = actual.scan(/\d+/).first(2).map(&:to_i)
+        floor_parts  = floor.scan(/\d+/).first(2).map(&:to_i)
+        return false if actual_parts.empty? || floor_parts.empty?
+        actual_parts << 0 while actual_parts.length < 2
+        floor_parts  << 0 while floor_parts.length  < 2
+        (actual_parts <=> floor_parts) < 0
+      end
     end
   end
 end

data/lib/parse/api/users.rb

@@ -37,6 +37,7 @@ module Parse
       end
 
       # Find user matching this active session token.
+      # @param session_token [String] the Parse user session token to look up.
       # @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]
@@ -69,7 +70,7 @@ module Parse
       # @param headers [Hash] additional HTTP headers to send with the request.
       # @return [Parse::Response]
       def update_user(id, body = {}, headers: {}, **opts)
-        response = request :put, "#{USER_PATH_PREFIX}/#{id}", body: body, opts: opts
+        response = request :put, "#{USER_PATH_PREFIX}/#{id}", body: body, headers: headers, opts: opts
         response.parse_class = Parse::Model::CLASS_USER
         response
       end
@@ -97,13 +98,36 @@ module Parse
       end
 
       # Request a password reset for a registered email.
+      #
+      # Client-side rate limited on a per-email basis using the same
+      # tracker that backs {#login} (entries are namespaced under a
+      # +pwreset:+ prefix so the two limiters don't collide on usernames
+      # that happen to equal an email). Every request counts toward the
+      # backoff — Parse Server's +requestPasswordReset+ response does
+      # not differentiate "email exists" from "email does not exist"
+      # (and rightly so, to avoid account enumeration), so the SDK
+      # cannot distinguish a legitimate retry from an attacker probing
+      # for valid emails. The cap mirrors {LOGIN_MAX_FAILURES}: 5
+      # requests within the rolling window before exponential backoff
+      # kicks in and the limit clears via the same TTL-based cleanup.
+      #
       # @param email [String] the Parse user email.
       # @param opts [Hash] additional options to pass to the {Parse::Client} request.
       # @param headers [Hash] additional HTTP headers to send with the request.
+      # @raise [RuntimeError] when the per-email request rate is exceeded.
       # @return [Parse::Response]
       def request_password_reset(email, headers: {}, **opts)
+        rate_key = "pwreset:#{email}"
+        check_login_rate_limit!(rate_key)
         body = { email: email }
-        request :post, REQUEST_PASSWORD_RESET, body: body, opts: opts, headers: headers
+        response = request :post, REQUEST_PASSWORD_RESET, body: body, 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
+        # "success" without leaking that distinction to an attacker who
+        # is probing.
+        track_login_attempt(rate_key, false)
+        response
       end
 
       # Login a user. Implements client-side rate limiting with exponential

data/lib/parse/atlas_search/index_manager.rb

@@ -101,6 +101,74 @@ module Parse
           indexes.find { |idx| idx["name"] == index_name }
         end
 
+        # List only `type: "search"` indexes (lexical / BM25). Filters the
+        # raw {.list_indexes} output. `$listSearchIndexes` returns both
+        # search and vectorSearch index types on the same collection;
+        # callers building lexical pipelines should consume this view.
+        # Indexes with an absent `type` field default to `"search"` for
+        # compatibility with older Atlas Search releases that pre-date the
+        # vector-search index type.
+        #
+        # @param collection_name [String] the Parse collection name
+        # @return [Array<Hash>] search indexes only
+        def list_search_indexes(collection_name)
+          list_indexes(collection_name).select do |idx|
+            type = (idx["type"] || idx[:type] || "search").to_s
+            type == "search"
+          end
+        end
+
+        # List only `type: "vectorSearch"` indexes. Filters the raw
+        # {.list_indexes} output. Vector-search indexes are the only ones
+        # eligible for the `$vectorSearch` aggregation stage; routing a
+        # lexical-index name into vector search (or vice versa) fails at
+        # the Atlas Search node with a non-obvious error, so the SDK
+        # filters at lookup time.
+        #
+        # @param collection_name [String] the Parse collection name
+        # @return [Array<Hash>] vector-search indexes only
+        def list_vector_indexes(collection_name)
+          list_indexes(collection_name).select do |idx|
+            (idx["type"] || idx[:type]).to_s == "vectorSearch"
+          end
+        end
+
+        # Find the vector-search index that covers a given field path on a
+        # collection. Walks `latestDefinition.fields[]` looking for an
+        # entry whose `type` is `"vector"` and whose `path` matches
+        # `field`. Returns the first matching index, or nil if none.
+        #
+        # The shape this matches is the documented Atlas vectorSearch
+        # index definition:
+        #
+        #   {
+        #     "name" => "Movie_embedding_..._idx",
+        #     "type" => "vectorSearch",
+        #     "latestDefinition" => {
+        #       "fields" => [
+        #         { "type" => "vector", "path" => "embedding",
+        #           "numDimensions" => 1536, "similarity" => "cosine" },
+        #         { "type" => "filter", "path" => "wiki_id" }
+        #       ]
+        #     }
+        #   }
+        #
+        # @param collection_name [String]
+        # @param field [String, Symbol] the vector field path
+        # @return [Hash, nil] the index definition or nil
+        def find_vector_index(collection_name, field:)
+          field_str = field.to_s
+          list_vector_indexes(collection_name).find do |idx|
+            defn = idx["latestDefinition"] || idx[:latestDefinition] || {}
+            fields = defn["fields"] || defn[:fields] || []
+            fields.any? do |f|
+              type = (f["type"] || f[:type]).to_s
+              path = (f["path"] || f[:path]).to_s
+              type == "vector" && path == field_str
+            end
+          end
+        end
+
         # Validate that an index exists and is ready
         # @param collection_name [String] the Parse collection name
         # @param index_name [String] the index name to validate
@@ -349,5 +417,21 @@ module Parse
         end
       end
     end
+
+    # Alias for {IndexManager} exposing the type-aware lookup surface
+    # ({IndexManager.list_search_indexes},
+    # {IndexManager.list_vector_indexes},
+    # {IndexManager.find_vector_index}). Backed by the same module, so
+    # the cache, mutex, and TTL are shared across both names — calling
+    # `IndexCatalog.clear_cache` and `IndexManager.clear_cache`
+    # invalidates the same store.
+    #
+    # @example Discover the vector index covering Movie.embedding
+    #   idx = Parse::AtlasSearch::IndexCatalog.find_vector_index(
+    #     "Movie", field: "embedding"
+    #   )
+    #   idx&.dig("name")
+    #   # => "Movie_embedding_openai_text_embedding_ada_002_1536_idx"
+    IndexCatalog = IndexManager
   end
 end