parse-stack-next 5.4.1 → 5.5.1

data/lib/parse/agent/mcp_rack_app.rb

@@ -4,6 +4,7 @@
 require "json"
 require "securerandom"
 require "digest"
+require "uri"
 require_relative "errors"
 require_relative "mcp_dispatcher"
 require_relative "mcp_subscriptions"
@@ -320,6 +321,7 @@ module Parse
                      pre_auth_rate_limiter: nil,
                      allowed_origins: nil,
                      require_custom_header: nil,
+                     loopback_csrf_default: false,
                      resource_subscriptions: false,
                      subscription_manager: nil,
                      notifications: nil,
@@ -376,6 +378,16 @@ module Parse
         @pre_auth_rate_limiter      = pre_auth_rate_limiter
         @allowed_origins            = normalize_allowed_origins(allowed_origins)
         @required_custom_header     = normalize_required_custom_header(require_custom_header)
+        # NEW-9: when no explicit allowed_origins / require_custom_header CSRF
+        # gate is configured but the server was started on an unauthenticated
+        # loopback bind, default to a loopback-only Origin policy. A browser
+        # DNS-rebinding attack against 127.0.0.1 always carries an `Origin`
+        # header (the attacker page's origin), so refusing any present
+        # non-loopback Origin closes that vector — while native clients (curl,
+        # SDK-to-SDK) send NO Origin and stay allowed, and a legitimate local
+        # browser UI sends a loopback Origin and is allowed. Ignored when an
+        # explicit allowlist is configured (operator owns the policy then).
+        @loopback_csrf_default      = loopback_csrf_default && @allowed_origins.nil?
         @health_path                = health_path.is_a?(String) && !health_path.empty? ? health_path : nil
         # Per-app registry of in-flight cancellable requests. Keyed by
         # [correlation_id, request_id]. A `notifications/cancelled` POST
@@ -660,12 +672,9 @@ module Parse
         #     Missing/empty `Origin` is allowed regardless — native
         #     clients (curl, SDK-to-SDK) shouldn't be broken by a
         #     CSRF defense aimed at browsers.
-        if @allowed_origins
-          origin = env["HTTP_ORIGIN"].to_s.strip
-          unless origin.empty? || origin_allowed?(origin)
-            @logger&.warn("[Parse::Agent::MCPRackApp] Origin refused: #{origin.inspect}")
-            return [403, json_headers, [json_rpc_error(-32_700, "Origin not allowed")]]
-          end
+        if origin_refused?(env)
+          @logger&.warn("[Parse::Agent::MCPRackApp] Origin refused: #{env["HTTP_ORIGIN"].to_s.strip.inspect}")
+          return [403, json_headers, [json_rpc_error(-32_700, "Origin not allowed")]]
         end
 
         # 2c. Required custom header (CSRF defense-in-depth). A header
@@ -1051,14 +1060,11 @@ module Parse
           return [400, json_headers, [json_rpc_error(-32_600, "Missing or invalid Mcp-Session-Id")]]
         end
 
-        # The origin allowlist (when configured) guards the listening stream
-        # the same way it guards POST — a browser-driven cross-origin GET to
-        # an SSE endpoint is the analogous CSRF surface.
-        if @allowed_origins
-          origin = env["HTTP_ORIGIN"].to_s.strip
-          unless origin.empty? || origin_allowed?(origin)
-            return [403, json_headers, [json_rpc_error(-32_700, "Origin not allowed")]]
-          end
+        # The origin policy (when configured, or the loopback default) guards
+        # the listening stream the same way it guards POST — a browser-driven
+        # cross-origin GET to an SSE endpoint is the analogous CSRF surface.
+        if origin_refused?(env)
+          return [403, json_headers, [json_rpc_error(-32_700, "Origin not allowed")]]
         end
 
         # Owner-binding: only the principal that established this session (or,
@@ -2119,6 +2125,39 @@ module Parse
       # `@allowed_origins`. Comparison is case-insensitive on host and
       # scheme. Wildcard via leading `.` matches subdomains:
       # `.example.com` matches `app.example.com` and `example.com`.
+      # Single chokepoint for the Origin CSRF gate, shared by the POST and
+      # listening-stream paths. A missing/empty Origin (native clients: curl,
+      # SDK-to-SDK) is always allowed — the CSRF surface is browser-only, and
+      # browsers always send an Origin on cross-origin requests. When an
+      # explicit allowlist is configured it wins; otherwise the loopback
+      # default (NEW-9) refuses any present non-loopback Origin.
+      def origin_refused?(env)
+        origin = env["HTTP_ORIGIN"].to_s.strip
+        return false if origin.empty?
+        if @allowed_origins
+          !origin_allowed?(origin)
+        elsif @loopback_csrf_default
+          !origin_is_loopback?(origin)
+        else
+          false
+        end
+      end
+
+      # True when `origin`'s host is a loopback address (any scheme/port).
+      # Closes browser DNS-rebinding on an unauthenticated loopback bind: the
+      # attacker page's Origin (e.g. http://evil.example) is not loopback and
+      # is refused, while a real local UI on http://localhost:<port> passes.
+      def origin_is_loopback?(origin)
+        host = begin
+          URI.parse(origin).host
+        rescue URI::InvalidURIError, StandardError
+          nil
+        end
+        return false if host.nil?
+        host = host.downcase.delete_prefix("[").delete_suffix("]") # unwrap IPv6 brackets
+        host == "localhost" || host == "127.0.0.1" || host == "::1"
+      end
+
       def origin_allowed?(origin)
         return false unless @allowed_origins
         normalized = origin.downcase

data/lib/parse/agent/mcp_server.rb

@@ -162,11 +162,30 @@ module Parse
         # pre_auth_rate_limiter: closes NEW-MCP-6 — runs before the factory
         # is invoked so an empty or malformed body can't amplify into a
         # Parse Server round-trip.
+        # NEW-9: on an unauthenticated loopback dev bind with no explicit CSRF
+        # gate configured, enable a loopback-only Origin policy by default to
+        # mitigate browser DNS-rebinding (a malicious page resolving a hostname
+        # to 127.0.0.1 and POSTing to the agent). The attacker page always
+        # carries a non-loopback Origin and is refused; native (no-Origin)
+        # clients and real local browser UIs are unaffected. Skipped when an
+        # API key is set (auth already gates) or the operator configured the
+        # Origin/custom-header gates themselves.
+        loopback_csrf_default =
+          LOOPBACK_HOSTS.include?(host.to_s) && @api_key.to_s.empty? &&
+          allowed_origins.nil? && require_custom_header.nil?
+        if loopback_csrf_default
+          warn "[Parse::Agent::MCPServer] Binding #{host}:#{port} without an API key. " \
+               "Enabling a loopback-only Origin policy to mitigate browser DNS-rebinding. " \
+               "For anything beyond local single-user dev set MCP_API_KEY (or pass api_key:), " \
+               "and/or configure allowed_origins:/require_custom_header:."
+        end
+
         @rack_app = MCPRackApp.new(
           agent_factory: method(:agent_factory),
           pre_auth_rate_limiter: pre_auth_rate_limiter,
           allowed_origins: allowed_origins,
           require_custom_header: require_custom_header,
+          loopback_csrf_default: loopback_csrf_default,
         )
       end
 

data/lib/parse/api/path_segment.rb

@@ -45,6 +45,37 @@ module Parse
         s
       end
 
+      # Parse objectId pattern: 1–40 alphanumerics. Parse Server generates
+      # 10-char alphanumeric ids; the cap is generous to allow custom ids
+      # while still refusing path-traversal (`/`, `.`, `..`) and query
+      # injection (`?`, `&`, `=`). Mirrors Parse::API::Objects::OBJECT_ID_PATTERN.
+      OBJECT_ID_PATTERN = /\A[A-Za-z0-9]{1,40}\z/.freeze
+
+      # Validate a Parse objectId used in a REST path (`users/<id>`,
+      # `classes/<Class>/<id>`) and return it unchanged. Refuses anything that
+      # could traverse to a different endpoint or smuggle a query string when
+      # interpolated raw — e.g. a hostile/compromised Parse Server returning a
+      # crafted `objectId` like `../classes/_User?where=...` on a prior
+      # response that then rides the next fetch/update/delete with whatever
+      # credentials the call is authorized to send.
+      #
+      # @param value the objectId to validate (anything responding to `to_s`).
+      # @param kind [String] human-readable name for error messages.
+      # @return [String] the validated objectId.
+      # @raise [ArgumentError] if blank or it fails the pattern.
+      def object_id!(value, kind: "objectId")
+        s = value.to_s
+        if s.empty?
+          raise ArgumentError, "#{kind} must not be empty"
+        end
+        unless OBJECT_ID_PATTERN.match?(s)
+          raise ArgumentError,
+            "#{kind} #{s.inspect} contains characters not allowed in a Parse " \
+            "objectId. Must match /\\A[A-Za-z0-9]{1,40}\\z/."
+        end
+        s
+      end
+
       # Parse trigger className pattern: a normal identifier, OR one of Parse
       # Server's `@`-prefixed pseudo-classes (`@File` for file triggers,
       # `@Connect` for the connection-global LiveQuery trigger). The optional

data/lib/parse/api/users.rb

@@ -26,6 +26,7 @@ module Parse
       # @param headers [Hash] additional HTTP headers to send with the request.
       # @return [Parse::Response]
       def fetch_user(id, headers: {}, **opts)
+        id = Parse::API::PathSegment.object_id!(id)
         request :get, "#{USER_PATH_PREFIX}/#{id}", headers: headers, opts: opts
       end
 
@@ -74,6 +75,7 @@ module Parse
       # @param headers [Hash] additional HTTP headers to send with the request.
       # @return [Parse::Response]
       def update_user(id, body = {}, headers: {}, **opts)
+        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
         response
@@ -98,6 +100,7 @@ module Parse
       # @param headers [Hash] additional HTTP headers to send with the request.
       # @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
       end
 
@@ -223,15 +226,25 @@ module Parse
       # - code 205 (+ERROR_EMAIL_NOT_FOUND+) when +preventLoginWithUnverifiedEmail+
       #   is enabled and the account's email has not been verified.
       #
+      # Client-side rate limited per username using the SAME bucket as {#login}
+      # (bare username, no namespace) — failures across both credential oracles
+      # accumulate, so an attacker cannot bypass a +login+ lockout by pivoting to
+      # this endpoint. The trade-off: a run of failed step-up re-auth calls counts
+      # toward (and can trigger) the primary login lockout for that username.
+      # Client-side limiting is a convenience, not a boundary — the server is the
+      # real control.
+      #
       # @param username [String] the Parse user username.
       # @param password [String] the Parse user's associated password.
       # @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]
       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.parse_class = Parse::Model::CLASS_USER
+        track_login_attempt(username, response.success?)
         response
       end
 

data/lib/parse/cache/redis.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "moneta"
+require "json"
 require_relative "pool"
 
 module Parse
@@ -82,6 +83,20 @@ module Parse
         # session-scoped REST responses outlive their token's
         # validity. Callers can still pass `expires: false` to opt out.
         merged_options = { expires: true }.merge(moneta_options)
+        # SECURITY: disable Moneta's value serializer so cached values are NOT
+        # Marshal-encoded. We JSON-(de)serialize values ourselves in #store /
+        # #[] (see #encode_value / #decode_value). The default Moneta-Redis
+        # value serializer is Marshal, which would `Marshal.load` whatever
+        # bytes come back from Redis on every cache hit — an arbitrary-code-
+        # execution primitive if the Redis cache is shared, unauthenticated,
+        # or reachable through a plaintext `redis://` MITM. Forcing nil here
+        # (overriding any caller-supplied `value_serializer:`/`serializer:`)
+        # keeps that gadget-deserialization vector closed regardless of how
+        # the wrapper is configured. Keys keep the default (:marshal) encoding:
+        # they are only ever written and SCAN/DEL-compared as opaque strings,
+        # never `Marshal.load`ed from Redis content, so they are not a
+        # deserialization vector.
+        merged_options = merged_options.merge(value_serializer: nil)
         @moneta_options = merged_options
         @closed = false
         @pool = Pool.new(size: pool_size, timeout: pool_timeout) do
@@ -90,7 +105,7 @@ module Parse
       end
 
       def [](key)
-        @pool[key]
+        decode_value(@pool[key])
       end
 
       def key?(key)
@@ -102,15 +117,18 @@ module Parse
       end
 
       def store(key, value, options = {})
-        @pool.store(key, value, options)
+        @pool.store(key, encode_value(value), options)
       end
 
       # Atomic SETNX. Required so `Parse::CreateLock` can acquire
       # cross-process locks when this wrapper is the configured cache /
       # `synchronize_create_store`. Returns `true` only when the key did
-      # not already exist.
+      # not already exist. The value goes through the same JSON encoding
+      # as {#store} so a later {#[]} read round-trips instead of decoding
+      # to nil. (Parse::LockBackend never hits this path on this wrapper —
+      # it prefers the raw-Redis {#lock_acquire}/{#lock_release} pair.)
       def create(key, value, options = {})
-        @pool.create(key, value, options)
+        @pool.create(key, encode_value(value), options)
       end
 
       # Atomic counter increment. Forwarded for Moneta surface parity.
@@ -135,14 +153,14 @@ module Parse
       # Atomically acquire a lock: SET key=owner only if absent, with a
       # native expiry. Used by {Parse::LockBackend} for {Parse::Lock} and
       # {Parse::CreateLock}. Deliberately bypasses Moneta's `create` —
-      # `Moneta.new(:Redis)` marshals BOTH keys and values, so a raw-Redis
-      # compare-and-delete on the marshaled blob would be fragile and
-      # coupled to Moneta's serializer config. Routing acquire AND release
-      # through plain-string raw Redis here keeps one consistent encoding
-      # across both ends of the lock and makes the keys human-inspectable
-      # in Redis (`parse-stack:lock:v1:<digest>`). Lock keys are
+      # `Moneta.new(:Redis)` marshals keys (and, by default, values), so a
+      # raw-Redis compare-and-delete on a Moneta-encoded blob would be
+      # fragile and coupled to Moneta's serializer config. Routing acquire
+      # AND release through plain-string raw Redis here keeps one consistent
+      # encoding across both ends of the lock and makes the keys human-
+      # inspectable in Redis (`parse-stack:lock:v1:<digest>`). Lock keys are
       # short-lived (TTL ≤ 30s) so there is no migration concern when a
-      # deploy flips between the Moneta-encoded and raw-encoded paths.
+      # deploy flips encodings.
       #
       # @param key [String] plain-string lock key.
       # @param owner [String] unique-per-acquisition owner token.
@@ -222,6 +240,32 @@ module Parse
 
       private
 
+      # Serialize a cache value to a JSON String before handing it to Moneta
+      # (which stores it raw, since the value serializer is disabled — see the
+      # constructor). JSON is used instead of Marshal so the read side never
+      # `Marshal.load`s attacker-influenced Redis bytes. Cache values written
+      # by the caching middleware are `{ "headers" => ..., "body" => ... }`
+      # hashes of strings, which round-trip losslessly through JSON.
+      def encode_value(value)
+        JSON.generate(value)
+      end
+
+      # Decode a JSON String read back from Moneta/Redis. Returns nil on a
+      # miss or on any value that is not valid JSON — most importantly, legacy
+      # Marshal-encoded entries written before this wrapper switched to JSON.
+      # Treating an undecodable value as a miss makes the caller refetch and
+      # re-store it in the JSON format, and ensures a hostile non-JSON blob can
+      # at worst yield a cache miss, never a deserialized Ruby object graph.
+      def decode_value(raw)
+        return nil if raw.nil?
+        JSON.parse(raw)
+      rescue JSON::ParserError, EncodingError, TypeError
+        # ParserError covers malformed and hostile-depth JSON
+        # (JSON::NestingError subclasses it); TypeError covers a
+        # non-String blob from a misconfigured store. All are misses.
+        nil
+      end
+
       def delete_keys_matching!(pattern)
         @pool.pool.with do |store|
           redis = backend_client(store)

data/lib/parse/client/caching.rb

@@ -190,8 +190,13 @@ module Parse
               body = cache_data.respond_to?(:body) ? cache_data.body : nil
               response_headers = cache_data.response_headers || {}
             elsif cache_data.is_a?(Hash)
-              body = cache_data[:body]
-              response_headers = cache_data[:headers] || {}
+              # New entries are stored with string keys so they survive a
+              # JSON round-trip (the Redis cache wrapper serializes values as
+              # JSON, not Marshal — see Parse::Cache::Redis). Fall back to
+              # symbol keys for legacy in-memory / Marshal-backed entries
+              # written before that switch.
+              body = cache_data["body"] || cache_data[:body]
+              response_headers = cache_data["headers"] || cache_data[:headers] || {}
             end
 
             if cache_data.present? && body.present?
@@ -244,8 +249,12 @@ module Parse
              response_env.body.present? && response_env.response_headers[CONTENT_LENGTH_KEY].to_i.between?(20, 1_250_000)
             store_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
             begin
+              # Store with string keys (and a plain Hash of headers) so the
+              # value round-trips losslessly through the Redis cache wrapper's
+              # JSON serialization. The read path above reads string keys first
+              # with a symbol-key fallback for legacy entries.
               @store.store(@cache_key,
-                           { headers: response_env.response_headers, body: response_env.body },
+                           { "headers" => response_env.response_headers.to_h, "body" => response_env.body },
                            expires: @expires)
               duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - store_start) * 1000.0).round(3)
               instrument_cache(:store, method: method, url_path: url_path, duration_ms: duration_ms)

data/lib/parse/client/logging.rb

@@ -186,6 +186,15 @@ module Parse
             end
           end
 
+        # Scrub credentials before logging. At :debug level this method emits
+        # both the request body (login/signup carries a cleartext `password`)
+        # and the response body (auth responses carry a fresh `sessionToken`,
+        # `authData`, and MFA secrets). `log_headers` already redacts headers;
+        # the body path must use the same canonical scrubber or it leaks live
+        # credentials to anyone with log access. Redact BEFORE the length cap
+        # so truncation can't split a token across the boundary and slip past.
+        content = Parse::Middleware::BodyBuilder.redact(content)
+
         if content.length > max_length
           logger.debug "  [#{prefix} Body] #{content[0...max_length]}... (truncated, #{content.length} total)"
         elsif content.length > 0

data/lib/parse/client.rb

@@ -716,10 +716,26 @@ module Parse
             warn "[Parse::Client] Cache store provided but :expires is not set or is 0. " \
                  "Caching will be disabled. Set :expires to enable caching (e.g., expires: 10)."
           else
-            # advanced: provide a REDIS url, we'll configure a Moneta Redis store.
+            # advanced: provide a REDIS url, we'll configure a Redis store.
             if opts[:cache].is_a?(String) && opts[:cache].starts_with?("redis://")
               begin
-                opts[:cache] = Moneta.new(:Redis, url: opts[:cache])
+                # Eagerly load the redis adapter so a missing `redis` gem
+                # fails fast here (at setup) with the friendly hint below,
+                # rather than deferring to the first cache access — the
+                # Parse::Cache::Redis pool builds its Moneta-Redis backends
+                # lazily, so without this the LoadError would surface later.
+                require "moneta/adapters/redis"
+                # Route through Parse::Cache::Redis rather than a bare
+                # `Moneta.new(:Redis, ...)`. SECURITY: the Moneta-Redis store
+                # Marshals values by default, so every cache hit would
+                # `Marshal.load` whatever bytes come back from Redis — an
+                # arbitrary-code-execution primitive if the cache is shared,
+                # unauthenticated, or reachable over a plaintext `redis://`
+                # MITM. The wrapper forces `value_serializer: nil` and
+                # JSON-(de)serializes cached values itself, closing that
+                # deserialization vector on this shorthand the same way an
+                # explicitly-constructed wrapper does.
+                opts[:cache] = Parse::Cache::Redis.new(url: opts[:cache])
               rescue LoadError
                 puts "[Parse::Middleware::Caching] Did you forget to load the redis gem (Gemfile)?"
                 raise
@@ -1425,6 +1441,22 @@ module Parse
   # Object/Pointer envelope is converted, and an Object of an UNregistered class
   # is left as a raw Hash (building it would degrade to a field-less Pointer).
   # Plain Hashes and arbitrary `__type` app data pass through untouched.
+  #
+  # SECURITY — cloud results are treated as server-authoritative. The
+  # `__type:"Object"` decode in {._decode_cloud_value} routes through
+  # +Parse::Object.build+, which hydrates with trusted-init — the SAME path
+  # used to decode every query / +.fetch+ result. Trusted-init skips the
+  # +PROTECTED_INITIALIZE_KEYS+ filter, so credential-shaped keys
+  # (+sessionToken+, +authData+, +_rperm+, +_wperm+, +roles+, …) present in a
+  # cloud function's return value populate the in-memory object, exactly as they
+  # do for any other server response. This is by design: the payload is authored
+  # by your Cloud Code and the request is caller-authenticated, and making cloud
+  # results filter these keys would make them inconsistent with (and stricter
+  # than) query/+.fetch+ hydration — e.g. a cloud function returning
+  # +request.user+ would come back missing its +sessionToken+. If a cloud
+  # function is expected to echo back third-party-influenced data, call it with
+  # +raw: true+ (+Parse.call_function(name, body, raw: true)+) to receive the
+  # undecoded response and sanitize it yourself before building objects.
   def self._extract_cloud_result(response)
     r = response.result
     value = r.is_a?(Hash) ? r["result"] : r
@@ -1568,7 +1600,9 @@ module Parse
   # specific {Parse::Error} subclasses as the underlying client does.
   # @param name (see Parse.call_function)
   # @param body (see Parse.call_function)
-  # @param opts (see Parse.call_function) — :raw is ignored.
+  # @param opts (see Parse.call_function) — +:raw+ has no effect; this method
+  #   always decodes the result. Use {Parse.call_function} with +raw: true+ if
+  #   you need the undecoded response.
   # @raise [Parse::Error::CloudCodeError] when the response indicates a cloud-code error.
   # @return [Object] the result data of the response.
   def self.call_function!(name, body = {}, **opts)

data/lib/parse/embeddings/batch_embedder.rb

@@ -0,0 +1,188 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module Embeddings
+    # Batch-level orchestration for bulk embedding jobs.
+    #
+    # {Provider#embed_text_batched} only slices input into
+    # provider-sized chunks; any retry/backoff lives inside each
+    # provider's single HTTP call. That is the wrong layer for bulk
+    # work: a 50k-document backfill needs *batch-level* pacing (stay
+    # under the provider's requests-per-minute budget across calls) and
+    # *batch-level* backoff (a 429 after the provider's internal retries
+    # are exhausted should pause the whole job, not kill it).
+    # {BatchEmbedder} wraps any registered provider with both.
+    #
+    # @example Backfill with pacing and backoff
+    #   embedder = Parse::Embeddings::BatchEmbedder.new(
+    #     Parse::Embeddings.provider(:openai),
+    #     requests_per_minute: 60,
+    #     max_attempts: 5,
+    #   )
+    #   vectors = embedder.embed_text(texts, input_type: :search_document)
+    #
+    # @example Progress reporting
+    #   embedder = Parse::Embeddings::BatchEmbedder.new(provider,
+    #     on_progress: ->(done:, total:, batch_index:, batch_count:) {
+    #       puts "#{done}/#{total}"
+    #     })
+    #
+    # == Retry classification
+    #
+    # By default a batch is retried when the provider raises a
+    # {Parse::Embeddings::Error} subclass whose class name ends in
+    # `RateLimitError` or `TransientError` — the convention every
+    # bundled provider follows (`OpenAI::RateLimitError`,
+    # `Voyage::TransientError`, …). Pass `retry_on:` with explicit
+    # exception classes to override. Non-retryable errors (auth,
+    # bad-request, response-contract violations) propagate immediately.
+    #
+    # Vectors are returned aligned 1:1 with the input, identical to
+    # `embed_text` on the wrapped provider.
+    class BatchEmbedder
+      # Raised when a batch still fails after `max_attempts` retryable
+      # failures. Wraps the final provider error in `#cause` and carries
+      # the index of the failing batch so a resumable job knows where to
+      # pick up.
+      class BatchFailed < Parse::Embeddings::Error
+        # @return [Integer] zero-based index of the failing batch.
+        attr_reader :batch_index
+        # @return [Integer] number of inputs successfully embedded before the failure.
+        attr_reader :completed_count
+
+        def initialize(message, batch_index:, completed_count:)
+          @batch_index = batch_index
+          @completed_count = completed_count
+          super(message)
+        end
+      end
+
+      RETRYABLE_NAME_SUFFIXES = %w[RateLimitError TransientError].freeze
+
+      # @return [Provider] the wrapped provider.
+      attr_reader :provider
+
+      # @param provider [Provider] any registered embedding provider.
+      # @param batch_size [Integer, nil] inputs per provider call.
+      #   Defaults to the provider's own {Provider#embed_batch_size}
+      #   hint, falling back to 64 when the provider has none.
+      # @param requests_per_minute [Numeric, nil] batch-level pacing
+      #   budget. When set, consecutive provider calls are spaced at
+      #   least `60.0 / requests_per_minute` seconds apart. nil disables
+      #   pacing.
+      # @param max_attempts [Integer] attempts per batch (1 = no retry).
+      # @param base_delay [Numeric] first backoff delay in seconds;
+      #   doubles per attempt.
+      # @param max_delay [Numeric] backoff ceiling in seconds.
+      # @param jitter [Numeric] random multiplier range added to each
+      #   delay (`delay * (1 + rand * jitter)`); spreads thundering
+      #   herds when several workers back off together.
+      # @param retry_on [Array<Class>, nil] explicit retryable exception
+      #   classes; nil uses the name-suffix convention described above.
+      # @param on_progress [#call, nil] callable invoked after each
+      #   successful batch with `done:, total:, batch_index:, batch_count:`.
+      def initialize(provider, batch_size: nil, requests_per_minute: nil,
+                     max_attempts: 5, base_delay: 2.0, max_delay: 60.0,
+                     jitter: 0.25, retry_on: nil, on_progress: nil)
+        unless provider.is_a?(Provider)
+          raise ArgumentError,
+                "Parse::Embeddings::BatchEmbedder expects a Parse::Embeddings::Provider " \
+                "(got #{provider.class})."
+        end
+        @provider = provider
+        @batch_size = batch_size ? Integer(batch_size) : nil
+        raise ArgumentError, "batch_size must be positive" if @batch_size && @batch_size <= 0
+        @min_interval = requests_per_minute ? (60.0 / Float(requests_per_minute)) : nil
+        @max_attempts = Integer(max_attempts)
+        raise ArgumentError, "max_attempts must be >= 1" if @max_attempts < 1
+        @base_delay = Float(base_delay)
+        @max_delay = Float(max_delay)
+        @jitter = Float(jitter)
+        @retry_on = retry_on && Array(retry_on)
+        @on_progress = on_progress
+        @last_call_at = nil
+      end
+
+      # Embed `strings` through the wrapped provider with pacing and
+      # batch-level backoff.
+      #
+      # @param strings [Array<String>]
+      # @param input_type [Symbol]
+      # @return [Array<Array<Float>>] aligned 1:1 with `strings`.
+      # @raise [BatchFailed] when a batch exhausts its attempts.
+      def embed_text(strings, input_type: :search_document)
+        unless strings.is_a?(Array)
+          raise ArgumentError,
+                "Parse::Embeddings::BatchEmbedder#embed_text expects Array<String> " \
+                "(got #{strings.class})."
+        end
+        return [] if strings.empty?
+
+        size = @batch_size || @provider.embed_batch_size || 64
+        batches = strings.each_slice(size).to_a
+        out = []
+        batches.each_with_index do |batch, idx|
+          out.concat(run_batch(batch, input_type, idx, out.length))
+          if @on_progress
+            @on_progress.call(done: out.length, total: strings.length,
+                              batch_index: idx, batch_count: batches.length)
+          end
+        end
+        out
+      end
+
+      private
+
+      def run_batch(batch, input_type, batch_index, completed_count)
+        attempts = 0
+        begin
+          attempts += 1
+          pace!
+          @provider.embed_text(batch, input_type: input_type)
+        rescue StandardError => e
+          raise unless retryable?(e)
+          if attempts >= @max_attempts
+            raise BatchFailed.new(
+              "Parse::Embeddings::BatchEmbedder: batch #{batch_index} failed after " \
+              "#{attempts} attempt(s) — #{e.class}: #{e.message}",
+              batch_index: batch_index, completed_count: completed_count,
+            )
+          end
+          sleep(backoff_delay(attempts))
+          retry
+        end
+      end
+
+      def retryable?(error)
+        if @retry_on
+          return @retry_on.any? { |klass| error.is_a?(klass) }
+        end
+        return false unless error.is_a?(Parse::Embeddings::Error)
+        name = error.class.name.to_s
+        RETRYABLE_NAME_SUFFIXES.any? { |suffix| name.end_with?(suffix) }
+      end
+
+      def backoff_delay(attempt)
+        delay = [@base_delay * (2**(attempt - 1)), @max_delay].min
+        delay * (1.0 + rand * @jitter)
+      end
+
+      # Enforce the inter-call interval. Measured from the START of the
+      # previous call so a slow provider response counts toward the
+      # interval rather than stacking on top of it.
+      def pace!
+        return if @min_interval.nil?
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        if @last_call_at
+          wait = (@last_call_at + @min_interval) - now
+          if wait > 0
+            sleep(wait)
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          end
+        end
+        @last_call_at = now
+      end
+    end
+  end
+end