parse-stack-next 5.3.0 → 5.4.0

data/lib/parse/embeddings/spend_cap.rb

@@ -0,0 +1,255 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "thread"
+
+module Parse
+  module Embeddings
+    # Per-tenant cumulative embedding spend cap.
+    #
+    # The agent `semantic_search` tool embeds attacker-controlled text
+    # (chat queries) on every call. Without a cap, a tenant — or an
+    # adversary driving an agent — can run up unbounded embedding-provider
+    # cost. {SpendCap} tracks the cumulative number of *tokens* embedded
+    # per tenant inside a sliding time window and HARD-REFUSES (raises
+    # {Exceeded}) once a tenant would exceed its limit. This is distinct
+    # from {Parse::Agent::RateLimiter}, which bounds request *count* per
+    # window; the spend cap bounds embedding *volume* (a proxy for cost).
+    #
+    # == Disabled by default
+    #
+    # With no configured limit the cap is a no-op — {.charge!} records
+    # nothing and never raises. Operators opt in:
+    #
+    #   Parse::Embeddings::SpendCap.configure(limit_tokens: 1_000_000, window: 3600)
+    #   Parse::Embeddings::SpendCap.configure(:acme_tenant, limit_tokens: 50_000)
+    #
+    # A per-tenant limit (second form) overrides the default for that
+    # tenant. The reserved key {DEFAULT_KEY} sets the fallback applied to
+    # every tenant without an explicit limit.
+    #
+    # == Token estimation
+    #
+    # Callers pass an explicit token count, or use {.estimate_tokens} (a
+    # chars/4 heuristic — the same approximation the agent layer uses for
+    # its context-token budgets). The cap is intentionally an estimate: it
+    # exists to bound runaway cost, not to bill precisely.
+    #
+    # Thread-safe: all state lives behind a single mutex.
+    module SpendCap
+      # Raised when a tenant would exceed its token cap. Carries the
+      # limit, the already-used count (within the window), and a
+      # `retry_after` hint (seconds until enough of the window rolls off
+      # to admit the rejected charge — `nil` if the charge can never fit).
+      class Exceeded < StandardError
+        attr_reader :tenant_id, :limit, :used, :requested, :window, :retry_after
+
+        def initialize(tenant_id:, limit:, used:, requested:, window:, retry_after:)
+          @tenant_id = tenant_id
+          @limit = limit
+          @used = used
+          @requested = requested
+          @window = window
+          @retry_after = retry_after
+          super(
+            "Embedding spend cap exceeded for tenant #{tenant_id.inspect}: " \
+            "#{used}+#{requested} tokens would exceed #{limit}/#{window}s." \
+            "#{retry_after ? " Retry after #{retry_after.round(1)}s." : " Request exceeds the cap outright."}"
+          )
+        end
+      end
+
+      # Fallback bucket key for charges with no tenant identity, and the
+      # key under which {.configure} (with no explicit tenant) sets the
+      # default limit applied to every tenant lacking an override.
+      DEFAULT_KEY = :__default__
+
+      # Default sliding window (seconds) when none is configured.
+      DEFAULT_WINDOW = 3600
+
+      class << self
+        # Configure the cap. Two forms:
+        #
+        #   configure(limit_tokens:, window:)            # default for all tenants
+        #   configure(tenant_id, limit_tokens:, window:) # override one tenant
+        #
+        # `limit_tokens: nil` disables the cap for that scope (the default
+        # scope when no tenant is given).
+        #
+        # @param tenant_id [Object, nil] tenant to override, or nil for
+        #   the global default.
+        # @param limit_tokens [Integer, nil] token ceiling per window.
+        # @param window [Integer] sliding window length in seconds.
+        # @return [void]
+        def configure(tenant_id = nil, limit_tokens:, window: DEFAULT_WINDOW)
+          key = tenant_id.nil? ? DEFAULT_KEY : tenant_id
+          unless limit_tokens.nil?
+            li = Integer(limit_tokens)
+            raise ArgumentError, "SpendCap: limit_tokens must be positive (got #{li})." if li <= 0
+          end
+          w = Integer(window)
+          raise ArgumentError, "SpendCap: window must be positive (got #{w})." if w <= 0
+          mutex.synchronize do
+            limits[key] = limit_tokens.nil? ? nil : { limit: Integer(limit_tokens), window: w }
+          end
+          nil
+        end
+
+        # Charge `tokens` against `tenant_id`'s budget. HARD-REFUSES by
+        # raising {Exceeded} when the charge would push the tenant over
+        # its limit within the window; otherwise records the charge and
+        # returns the new in-window total.
+        #
+        # No-op (returns nil) when no limit applies to the tenant.
+        #
+        # @param tenant_id [Object, nil] tenant identity (nil → {DEFAULT_KEY}).
+        # @param tokens [Integer] tokens to charge (>= 0).
+        # @return [Integer, nil] new in-window total, or nil if uncapped.
+        # @raise [Exceeded]
+        def charge!(tenant_id:, tokens:)
+          t = Integer(tokens)
+          raise ArgumentError, "SpendCap: tokens must be >= 0 (got #{t})." if t.negative?
+          key = tenant_id.nil? ? DEFAULT_KEY : tenant_id
+
+          mutex.synchronize do
+            cfg = limit_for(key)
+            return nil if cfg.nil? # uncapped
+
+            window = cfg[:window]
+            limit = cfg[:limit]
+            now = monotonic
+            entries = prune(key, now, window)
+            used = entries.sum { |e| e[1] }
+
+            if used + t > limit
+              raise Exceeded.new(
+                tenant_id: key, limit: limit, used: used, requested: t,
+                window: window, retry_after: retry_after_for(entries, t, limit, window, now),
+              )
+            end
+            entries << [now, t] if t.positive?
+            used + t
+          end
+        end
+
+        # Current in-window token usage for a tenant (0 when uncapped or
+        # idle). Does not mutate.
+        #
+        # @param tenant_id [Object, nil]
+        # @return [Integer]
+        def usage(tenant_id: nil)
+          key = tenant_id.nil? ? DEFAULT_KEY : tenant_id
+          mutex.synchronize do
+            cfg = limit_for(key)
+            return 0 if cfg.nil?
+            prune(key, monotonic, cfg[:window]).sum { |e| e[1] }
+          end
+        end
+
+        # Estimate token count from a String.
+        #
+        # The familiar "~4 characters per token" ratio only holds for
+        # ASCII. CJK, emoji, and other multibyte text run closer to one
+        # token per codepoint in a real tokenizer, so a pure
+        # `chars / 4` estimate undercounts such input by up to ~4x — and
+        # since this estimate is the sole basis for the hard-refuse
+        # decision, that lets a caller feeding multibyte text reach ~4x
+        # the real embedding volume before the cap trips. Take the larger
+        # of the char-based and byte-based estimates so multibyte input
+        # bills at least as much as its UTF-8 byte length implies.
+        #
+        # @param text [String]
+        # @return [Integer]
+        def estimate_tokens(text)
+          str = text.to_s
+          chars = (str.length / 4.0).ceil
+          bytes = (str.bytesize / 4.0).ceil
+          [chars, bytes].max
+        end
+
+        # Clear recorded usage (all tenants, or one). Limits are retained.
+        #
+        # @param tenant_id [Object, nil]
+        def reset!(tenant_id = nil)
+          mutex.synchronize do
+            if tenant_id.nil?
+              @buckets = {}
+            else
+              buckets.delete(tenant_id)
+            end
+          end
+          nil
+        end
+
+        # Remove all configured limits AND recorded usage. Mainly for
+        # tests — returns the cap to its disabled-by-default state.
+        def reset_all!
+          mutex.synchronize do
+            @limits = {}
+            @buckets = {}
+          end
+          nil
+        end
+
+        private
+
+        MUTEX_INIT = Mutex.new
+        private_constant :MUTEX_INIT
+
+        def mutex
+          @mutex ||= MUTEX_INIT.synchronize { @mutex ||= Mutex.new }
+        end
+
+        def limits
+          @limits ||= {}
+        end
+
+        def buckets
+          @buckets ||= {}
+        end
+
+        # Resolve the effective limit config for a key: an explicit
+        # per-tenant entry wins; otherwise the DEFAULT_KEY entry; nil when
+        # neither is set (uncapped). A key explicitly set to nil disables
+        # the cap for that tenant even if a default exists.
+        def limit_for(key)
+          if limits.key?(key)
+            limits[key]
+          else
+            limits[DEFAULT_KEY]
+          end
+        end
+
+        # Drop entries older than the window; returns the (mutated) live
+        # entry list for the key.
+        def prune(key, now, window)
+          entries = (buckets[key] ||= [])
+          cutoff = now - window
+          entries.reject! { |e| e[0] <= cutoff }
+          entries
+        end
+
+        # Seconds until enough in-window tokens roll off to admit a charge
+        # of `requested` tokens. nil when the request alone exceeds the
+        # limit (it can never fit).
+        def retry_after_for(entries, requested, limit, window, now)
+          return nil if requested > limit
+          need_to_free = (entries.sum { |e| e[1] } + requested) - limit
+          return 0.0 if need_to_free <= 0
+          freed = 0
+          entries.sort_by { |e| e[0] }.each do |ts, tok|
+            freed += tok
+            if freed >= need_to_free
+              return [(ts + window) - now, 0.0].max
+            end
+          end
+          nil
+        end
+
+        def monotonic
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/lib/parse/embeddings.rb

@@ -554,3 +554,4 @@ require_relative "embeddings/voyage"
 require_relative "embeddings/jina"
 require_relative "embeddings/qwen"
 require_relative "embeddings/local_http"
+require_relative "embeddings/spend_cap"

data/lib/parse/live_query/client.rb

@@ -363,7 +363,7 @@ module Parse
       #   events can arrive. Optional — callers may still capture the
       #   returned subscription and register callbacks later.
       # @return [Subscription]
-      def subscribe(class_name, where: {}, fields: nil, session_token: nil,
+      def subscribe(class_name, where: {}, fields: nil, keys: nil, watch: nil, session_token: nil,
                     use_master_key: false, &block)
         # Handle Parse::Object subclass
         if class_name.is_a?(Class) && class_name < Parse::Object
@@ -396,6 +396,8 @@ module Parse
           class_name: class_name,
           query: where,
           fields: fields,
+          keys: keys,
+          watch: watch,
           session_token: session_token,
           use_master_key: use_master_key,
         )

data/lib/parse/live_query/subscription.rb

@@ -62,12 +62,22 @@ module Parse
       # @return [Parse::LiveQuery::Client] the LiveQuery client
       attr_reader :client
 
-      # @return [Array<String>] fields to watch for changes (nil = all fields)
+      # @return [Array<String>] field projection for returned events
+      #   (nil = all fields). Parse Server 7.0 renamed this subscription
+      #   option from `fields` to `keys`; {#keys} is the canonical alias.
       attr_reader :fields
+      # @return [Array<String>] alias for {#fields} under Parse Server's
+      #   post-7.0 `keys` name.
+      alias_method :keys, :fields
 
       # @return [String, nil] session token for ACL-aware subscriptions
       attr_reader :session_token
 
+      # @return [Array<String>, nil] field names that trigger update events when
+      #   changed (PS 7.0+ `watch` option). +nil+ means all field changes trigger
+      #   update events.
+      attr_reader :watch
+
       # Create a new subscription
       # @param client [Parse::LiveQuery::Client] the LiveQuery client
       # @param class_name [String] Parse class name
@@ -85,13 +95,16 @@ module Parse
       #   elevated; on a non-admin connection the client warns and the
       #   subscription stays ACL-scoped. For mixed scoped + admin needs,
       #   use two separate clients. Defaults to false.
-      def initialize(client:, class_name:, query: {}, fields: nil,
-                     session_token: nil, use_master_key: false)
+      def initialize(client:, class_name:, query: {}, fields: nil, keys: nil,
+                     session_token: nil, use_master_key: false, watch: nil)
         @monitor = Monitor.new
         @client = client
         @class_name = class_name
         @query = query
-        @fields = fields
+        # `keys` is the post-7.0 name; accept either and prefer the explicit
+        # `keys:` when both are supplied.
+        @fields = keys.nil? ? fields : keys
+        @watch = watch
         @session_token = session_token
         @use_master_key = use_master_key == true
         @request_id = generate_request_id
@@ -239,7 +252,21 @@ module Parse
           },
         }
 
-        msg[:query][:fields] = fields if fields&.any?
+        if fields&.any?
+          # Parse Server 7.0 (DEPPS9 / #8852) renamed the subscription field-
+          # projection option from `fields` to `keys`. PS 7+ reads `keys` and
+          # ignores `fields`; PS < 7 reads `fields`. Emit BOTH so projection is
+          # honored on every supported server — sending an extra key the server
+          # ignores is harmless, while sending only `fields` silently disables
+          # projection (events return all columns) on PS 7+.
+          msg[:query][:keys] = fields
+          msg[:query][:fields] = fields
+        end
+        # PS 7.0 (#8028) `watch`: fire update events only when the named fields
+        # change. Distinct from field projection (`keys`/`fields`): `watch`
+        # controls which field mutations generate an update event; `keys` controls
+        # which fields are returned in the event payload.
+        msg[:query][:watch] = watch if watch&.any?
         msg[:sessionToken] = session_token if session_token
         # The subscribe frame deliberately NEVER carries `masterKey`.
         # Parse Server's `_handleSubscribe` does not read it — master-key

data/lib/parse/model/acl.rb

@@ -91,8 +91,10 @@ module Parse
   #  artist.save
   #
   # You may also set default ACLs for your subclasses by using {Parse::Object.set_default_acl}.
-  # These will be get applied for newly created instances. All subclasses have
-  # public read and write enabled by default.
+  # These will get applied for newly created instances. Unless overridden, subclasses
+  # inherit the shipped `:owner_else_private` policy — records are private
+  # (master-only) until an owner is resolved at save time. Use {Parse::Object.set_default_acl}
+  # or {Parse::Object.acl_policy} to grant broader access.
   #
   #  class AdminData < Parse::Object
   #

data/lib/parse/model/classes/audience.rb

@@ -155,12 +155,60 @@ module Parse
     property :name
 
     # @!attribute query
-    # The query constraints that define which installations belong to this audience.
-    # This is stored as a hash matching the Installation query format.
-    # @return [Hash] The query constraint hash.
+    # The query constraints that define which installations belong to this
+    # audience, as a Hash matching the Installation query format.
+    #
+    # On the wire this is persisted as a JSON **string**, matching Parse
+    # Server's built-in `_Audience.query` column (typed `String`, not Object).
+    # Assigning a Hash and reading a Hash back is handled transparently. The
+    # previous `property :query, :object` emitted a JSON object, so every save
+    # of a hash query was rejected by the server with a schema mismatch
+    # ("expected String but got Object").
+    # @return [ActiveSupport::HashWithIndifferentAccess, nil] the query hash.
     # @example
     #   audience.query = { "deviceType" => "ios", "appVersion" => { "$gte" => "2.0" } }
-    property :query, :object
+    property :query_json, :string, field: :query
+
+    # JSON-encode a Hash/Array assigned to the query field before the `:string`
+    # property coercion runs. Every assignment path — `query=`,
+    # `query_constraint=`, mass-assignment via `new(query:)`, and server
+    # hydration — funnels through `format_value`, so intercepting here (rather
+    # than the public setter, which mass-assignment bypasses) is the single
+    # reliable place to keep the wire value valid JSON (`{"k":"v"}`) instead of
+    # Ruby's `Hash#to_s` (`{"k"=>"v"}`). A String passed in (e.g. a row loaded
+    # from the server) falls through to the normal string coercion untouched.
+    def format_value(key, val, data_type = nil)
+      if key == :query_json && (val.is_a?(Hash) || val.is_a?(Array))
+        return val.to_json
+      end
+      super
+    end
+
+    # The query constraints as a Hash (decoded from the stored JSON string).
+    # @return [ActiveSupport::HashWithIndifferentAccess, nil]
+    def query
+      raw = query_json
+      case raw
+      when nil, "" then nil
+      when Hash then raw.with_indifferent_access
+      when String
+        decoded = begin
+            JSON.parse(raw)
+          rescue JSON::ParserError
+            nil
+          end
+        decoded.is_a?(Hash) ? decoded.with_indifferent_access : decoded
+      else
+        raw
+      end
+    end
+
+    # Assign the audience query. Accepts a Hash (preferred) or a pre-encoded
+    # JSON String; either form is persisted as a JSON string.
+    # @param value [Hash, String, nil]
+    def query=(value)
+      self.query_json = value
+    end
 
     # Alias for query to match Parse Server naming conventions.
     # @return [Hash] The query constraint hash.

data/lib/parse/model/classes/user.rb

@@ -28,6 +28,59 @@ module Parse
 
     # 125	Error code indicating that the email address was invalid.
     class InvalidEmailAddress < Error; end
+
+    # Error code 205 (Parse::Response::ERROR_EMAIL_NOT_FOUND) raised by
+    # {Parse::User.login!} and {Parse::User#verify_password} when Parse Server
+    # returns code 205 because +preventLoginWithUnverifiedEmail+ is enabled and
+    # the account's email address has not been verified.
+    #
+    # It is a SUBCLASS of {AuthenticationError} on purpose: before this typed
+    # error existed, the unverified-email rejection raised a plain
+    # +AuthenticationError+, so existing callers wrapping {Parse::User.login!}
+    # in +rescue AuthenticationError+ must keep catching it (subclassing keeps
+    # that contract — making it a sibling would be a silent breaking change).
+    # Callers who want to special-case the unverified-email path just rescue
+    # this narrower subclass FIRST.
+    #
+    # @example
+    #   begin
+    #     Parse::User.login!(username, password)
+    #   rescue Parse::Error::EmailNotVerifiedError
+    #     # Prompt user to check their inbox and verify their email
+    #   rescue Parse::Error::AuthenticationError
+    #     # Wrong credentials or other login failure (still catches the above
+    #     # too, if no narrower rescue precedes it)
+    #   end
+    class EmailNotVerifiedError < AuthenticationError; end
+
+    # Raised by {Parse::Client} when the SDK's client-side login rate-limit
+    # guard fires — i.e. the same username has failed
+    # {Parse::API::Users::LOGIN_MAX_FAILURES} or more times and the exponential
+    # back-off window has not yet elapsed.
+    #
+    # The class is a subclass of {AuthenticationError} so that a single
+    # <tt>rescue Parse::Error::AuthenticationError</tt> handler covers both
+    # wrong-credential failures and lockout situations. Callers that need to
+    # distinguish the lockout case just rescue this narrower subclass first.
+    # Because the previous implementation raised a plain +RuntimeError+, there
+    # is no prior +AuthenticationError+ rescue contract to preserve — this is
+    # a new typed entry in the login-failure taxonomy.
+    #
+    # Note that +Parse::Error < StandardError+, so a bare +rescue+ or
+    # +rescue StandardError+ still catches this error.
+    #
+    # @example
+    #   begin
+    #     Parse::User.login!(username, password)
+    #   rescue Parse::Error::AccountLockoutError => e
+    #     # Too many failed attempts — tell the user how long to wait
+    #     retry_in = e.message[/\d+/]
+    #     render_lockout_page(retry_in: retry_in)
+    #   rescue Parse::Error::AuthenticationError
+    #     # Wrong credentials (or other login failure — also catches lockout
+    #     # if no narrower rescue precedes it)
+    #   end
+    class AccountLockoutError < AuthenticationError; end
   end
 
   # The main class representing the _User table in Parse. A user can either be signed up or anonymous.
@@ -504,15 +557,55 @@ module Parse
         if hash.key?(:authData) || hash.key?("authData") ||
            hash.key?(:auth_data) || hash.key?("auth_data")
           hash = hash.dup
+          raw_auth = hash[:authData] || hash["authData"] ||
+                     hash[:auth_data] || hash["auth_data"]
           hash.delete(:authData)
           hash.delete("authData")
           hash.delete(:auth_data)
           hash.delete("auth_data")
+          # Preserve ONLY a non-sensitive MFA status derived from the stripped
+          # authData, so #mfa_enabled? / #mfa_status (and the #disable_mfa!
+          # guard) work after an ordinary fetch without retaining the TOTP
+          # secret, recovery codes, mobile number, or any OAuth provider token.
+          # Non-MFA authData still strips to nil exactly as before.
+          safe = sanitized_mfa_authdata(raw_auth)
+          hash["authData"] = safe if safe
         end
       end
       super(hash, dirty_track: dirty_track, filter_protected: filter_protected, protected_set: protected_set)
     end
 
+    # @!visibility private
+    # Reduce a server-returned +authData+ hash to a leak-safe MFA status.
+    # Parse Server returns +authData.mfa+ as +{ "secret" => ..., "recovery" =>
+    # [...] }+ (the raw TOTP secret and one-time recovery codes) even on a
+    # user's own session-token read, so the value itself must never be retained.
+    # This keeps only +{ "mfa" => { "status" => "enabled" } }+ when MFA is
+    # configured, and returns +nil+ otherwise (preserving the prior
+    # strip-to-nil behavior for OAuth-only / non-MFA authData).
+    # @return [Hash, nil]
+    def sanitized_mfa_authdata(raw)
+      return nil unless raw.is_a?(Hash)
+      mfa = raw["mfa"] || raw[:mfa]
+      return nil unless mfa.is_a?(Hash)
+
+      status = mfa["status"] || mfa[:status]
+      # An EXPLICIT non-"enabled" status is authoritative: treat the user
+      # as disabled even if a stale `secret`/`recovery` lingers in the
+      # blob. Without this, a residual credential would override an
+      # explicit `status: "disabled"` and make `mfa_enabled?` report true
+      # for a user who has turned MFA off.
+      return nil if status.is_a?(String) && status != "enabled"
+
+      recovery = mfa["recovery"] || mfa[:recovery]
+      enabled = status == "enabled" ||
+                (mfa["secret"] || mfa[:secret]).present? ||
+                (recovery.is_a?(Array) ? recovery.any? : recovery.present?) ||
+                (mfa["mobile"] || mfa[:mobile]).present?
+
+      enabled ? { "mfa" => { "status" => "enabled" } } : nil
+    end
+
     # @return [Boolean] true if this user is anonymous (i.e. created
     #   via the +authData.anonymous+ provider rather than via signup
     #   with a username/password or a real OAuth provider).
@@ -664,6 +757,17 @@ module Parse
       Parse::User.request_password_reset(email)
     end
 
+    # Request that Parse Server (re)send this user's email-address verification
+    # email. The server must have an email adapter and `verifyUserEmails` enabled.
+    # @return [Boolean] true if the request was accepted, false otherwise.
+    # @raise [Parse::Error::ServiceUnavailableError] if Parse Server returns a
+    #   500/503 (e.g. no emailAdapter / `verifyUserEmails` disabled).
+    # @see Parse::User.request_email_verification
+    def request_email_verification
+      return false if email.nil?
+      Parse::User.request_email_verification(email)
+    end
+
     # You may set a password for this user when you are creating them. Parse never returns a
     # @param passwd The user's password to be used for signing up.
     # @raise [Parse::Error::UsernameMissingError] If username is missing.
@@ -1069,9 +1173,21 @@ module Parse
         # Self-fetch trust: see {.login}.
         with_authdata_trust { Parse::User.build(response.result) }
       else
-        raise Parse::Error::AuthenticationError,
-              "Parse::User.login! failed for #{username.inspect}: " \
-              "#{response.error || "HTTP #{response.http_status}"} (code=#{response.code.inspect})"
+        case response.code
+        when Parse::Response::ERROR_EMAIL_NOT_FOUND
+          # Parse Server throws code 205 (EMAIL_NOT_FOUND) when
+          # +preventLoginWithUnverifiedEmail+ is set and the account's email
+          # address has not yet been verified. Raise the typed error so callers
+          # can direct the user to verify their inbox without catching every
+          # AuthenticationError.
+          raise Parse::Error::EmailNotVerifiedError,
+                "Parse::User.login! failed for #{username.inspect}: " \
+                "email address is not verified (code=205)"
+        else
+          raise Parse::Error::AuthenticationError,
+                "Parse::User.login! failed for #{username.inspect}: " \
+                "#{response.error || "HTTP #{response.http_status}"} (code=#{response.code.inspect})"
+        end
       end
     end
 
@@ -1096,6 +1212,26 @@ module Parse
       response.success?
     end
 
+    # Request that Parse Server (re)send the email-address verification email for
+    # a registered, not-yet-verified user. The server must have an email adapter
+    # and `verifyUserEmails` enabled.
+    # @example
+    #  # pass a user object
+    #  Parse::User.request_email_verification(user)
+    #  # or an email
+    #  Parse::User.request_email_verification("user@example.com")
+    # @param email [String] The user's email address (or a {Parse::User}).
+    # @return [Boolean] True/false if the request was accepted.
+    # @raise [Parse::Error::ServiceUnavailableError] if Parse Server returns a
+    #   500/503 (e.g. no emailAdapter / `verifyUserEmails` disabled). Callers that
+    #   branch on the Boolean should rescue this.
+    def self.request_email_verification(email)
+      email = email.email if email.is_a?(Parse::User)
+      return false if email.blank?
+      response = client.request_email_verification(email)
+      response.success?
+    end
+
     # Same as `session!` but returns nil if a user was not found or sesion token was invalid.
     # @return [User] the user matching this active token, otherwise nil.
     # @see #session!
@@ -1260,6 +1396,47 @@ module Parse
       active_session_count > 1
     end
 
+    # Verify this user's password without minting a session token.
+    #
+    # Delegates to the +GET /parse/verifyPassword+ endpoint (Parse Server
+    # 7.1.0+) using this user's +username+ and the supplied +password+. The
+    # check is purely credential validation — no session is created on
+    # success, and the user's existing sessions are unaffected.
+    #
+    # Use this as a step-up authentication gate: before allowing a sensitive
+    # action (e.g. changing an email address or deleting an account), call
+    # +verify_password+ to confirm the caller still knows the password.
+    #
+    # @param password [String] the password to verify.
+    # @return [Boolean] +true+ if the credentials are valid.
+    # @raise [Parse::Error::EmailNotVerifiedError] when the account exists but
+    #   +preventLoginWithUnverifiedEmail+ is enabled and the email has not been
+    #   verified (Parse Server error code 205). The caller may want to prompt
+    #   the user to check their inbox rather than treating this as a wrong-
+    #   password failure.
+    # @raise [Parse::Error::AuthenticationError] when the username does not
+    #   exist or the password is wrong (code 101, +OBJECT_NOT_FOUND+).
+    # @return [Boolean]
+    # @example
+    #   # Step-up check before a destructive action
+    #   if user.verify_password(params[:current_password])
+    #     user.destroy
+    #   end
+    def verify_password(password)
+      response = client.verify_password(username.to_s, password.to_s)
+      return true if response.success?
+
+      case response.code
+      when Parse::Response::ERROR_EMAIL_NOT_FOUND
+        raise Parse::Error::EmailNotVerifiedError,
+              "verify_password failed: email address is not verified (code=205)"
+      else
+        raise Parse::Error::AuthenticationError,
+              "verify_password failed: " \
+              "#{response.error || "HTTP #{response.http_status}"} (code=#{response.code.inspect})"
+      end
+    end
+
     # Return the transitive upward closure of role names this user
     # inherits permissions from.
     #