parse-stack-next 5.2.1 → 5.4.0

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.
@@ -835,6 +939,26 @@ module Parse
       @session
     end
 
+    # A non-master {Parse::Client} bound to this user's session token, for
+    # acting on the server *as this user* with full ACL / CLP / +protectedFields+
+    # enforcement and no master-key fallback. It mirrors the connection settings
+    # of +base+ (the configured client by default) but carries no master key and
+    # binds {#session_token}, so even raw REST calls through it are authorized as
+    # the user with no per-call ceremony. The web-counterpart of
+    # {Parse::Webhooks::Payload#user_client}; the typical client-side entry point
+    # is right after a login:
+    #
+    #   client = Parse::User.login(username, password).session_client
+    #   Parse::Query.new("Post", client: client).results   # scoped to the user
+    #
+    # @param base [Parse::Client] the client whose connection settings to mirror.
+    # @return [Parse::Client, nil] +nil+ when the user has no session token
+    #   (e.g. fetched/saved under the master key rather than logged in).
+    def session_client(base = self.client)
+      return nil if @session_token.nil? || @session_token.to_s.strip.empty?
+      base.become(@session_token)
+    end
+
     # @!visibility private
     # Keys that must never flow through +Parse::User.create+ from a
     # mass-assigned hash. +authData+ on the user-signup endpoint causes
@@ -1049,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
 
@@ -1076,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!
@@ -1240,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.
     #

data/lib/parse/model/core/embed_managed.rb

@@ -128,6 +128,39 @@ module Parse
         base.extend(ClassMethods)
       end
 
+      # Recompute this record's managed embedding(s) in-place, NOW,
+      # without a save. Runs the same digest-tracked recompute the
+      # `before_save` callback runs: a provider call happens only when the
+      # source text/URL changed since the last embed (digest miss). Useful
+      # to populate the vector before inspecting it, or to force a refresh
+      # in a console.
+      #
+      # @param field [Symbol, nil] limit to one embed target; nil
+      #   recomputes every declared directive.
+      # @return [self]
+      # @raise [ArgumentError] when `field:` names no embed target, or the
+      #   class declares no `embed` directives.
+      def compute_embedding!(field: nil)
+        directives = self.class.embed_directives
+        if directives.empty?
+          raise ArgumentError, "#{self.class}#compute_embedding!: no `embed` directives declared."
+        end
+        selected =
+          if field
+            d = directives[field.to_sym]
+            unless d
+              raise ArgumentError,
+                    "#{self.class}#compute_embedding!: :#{field} is not an embed target " \
+                    "(have #{directives.keys.inspect})."
+            end
+            [d]
+          else
+            directives.values
+          end
+        selected.each { |directive| Parse::Core::EmbedManaged.recompute_embedding!(self, directive) }
+        self
+      end
+
       module ClassMethods
         # Per-class registry of {EmbedDirective}s keyed by target vector
         # property symbol. Read by tests and tooling; written only by
@@ -300,6 +333,86 @@ module Parse
           into
         end
 
+        # Backfill embeddings for records whose managed vector field is
+        # still null — the bulk counterpart to the per-save embed path.
+        # Walks the class with objectId-cursor pagination (robust to the
+        # result set shrinking as records are embedded; terminates even
+        # when a record has no source text and stays null), saving each
+        # pending record so its `before_save` embed callback runs.
+        #
+        # Intended as an admin / maintenance operation: it reads and
+        # writes through the default client, so run it with a master-key
+        # client (or pass `save_opts:` carrying a `session_token:` that can
+        # write every row).
+        #
+        # @param field [Symbol, nil] limit the backfill to one embed
+        #   target; nil processes every declared directive.
+        # @param batch_size [Integer] rows fetched per round (default 100).
+        # @param limit [Integer, nil] stop after embedding at most this
+        #   many records across all directives; nil = no cap.
+        # @param where [Hash, nil] extra query constraints AND-ed with the
+        #   null-target filter (e.g. `{ published: true }`).
+        # @param save_opts [Hash] options forwarded to each `record.save`
+        #   (e.g. `session_token:`).
+        # @return [Integer] number of records saved (embedded).
+        # @raise [ArgumentError] when `field:` names no embed target, or
+        #   the class declares no `embed` directives.
+        def embed_pending!(field: nil, batch_size: 100, limit: nil, where: nil, save_opts: {})
+          bs = Integer(batch_size)
+          raise ArgumentError, "#{self}.embed_pending!: batch_size must be positive." if bs <= 0
+          directives = resolve_embed_directives_for_backfill(field)
+
+          processed = 0
+          directives.each do |directive|
+            remaining = limit ? (limit - processed) : nil
+            break if remaining && remaining <= 0
+            processed += backfill_embed_directive!(directive, bs, where, remaining, save_opts)
+          end
+          processed
+        end
+
+        # @!visibility private
+        def resolve_embed_directives_for_backfill(field)
+          if field
+            d = embed_directives[field.to_sym]
+            unless d
+              raise ArgumentError,
+                    "#{self}.embed_pending!: :#{field} is not an embed target " \
+                    "(have #{embed_directives.keys.inspect})."
+            end
+            [d]
+          else
+            ds = embed_directives.values
+            raise ArgumentError, "#{self}.embed_pending!: no `embed` directives declared." if ds.empty?
+            ds
+          end
+        end
+
+        # @!visibility private
+        # objectId-cursor walk over rows where `directive.into` is null.
+        def backfill_embed_directive!(directive, batch_size, where, remaining, save_opts)
+          count = 0
+          cursor = nil
+          loop do
+            q = query(directive.into.null => true)
+            q = q.where(where) if where.is_a?(Hash) && !where.empty?
+            q = q.where(:objectId.gt => cursor) if cursor
+            q.order(:objectId.asc)
+            q.limit(batch_size)
+            batch = q.results
+            break if batch.nil? || batch.empty?
+
+            batch.each do |record|
+              cursor = record.id
+              record.save(**save_opts)
+              count += 1
+              return count if remaining && count >= remaining
+            end
+            break if batch.length < batch_size
+          end
+          count
+        end
+
         # @!visibility private
         # Prepend a module that intercepts the public `<into>=` setter
         # and raises {ProtectedFieldError} unless the current thread has

data/lib/parse/model/core/pluralized_aliases.rb

@@ -0,0 +1,30 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  # Global `const_missing` hook that lazily resolves the plural form of a
+  # {Parse::Object} subclass constant to that class. Referencing `Posts`
+  # when a class `Post` exists installs `Posts` as an alias for `Post` on
+  # the referencing module and returns it, so query entry points like
+  # `Posts.where(...).count` work without any per-model boilerplate.
+  #
+  # The hook is prepended onto `Module` so it applies to constant lookups
+  # in any namespace (top-level and nested). It is tightly guarded: every
+  # path that is not a plural-of-a-Parse-class falls through to `super`,
+  # preserving normal `NameError` and autoloader (Zeitwerk/classic)
+  # behavior. The whole feature is gated on {Parse.pluralized_aliases?} so
+  # opting out (`Parse.pluralized_aliases = false`) makes this a near-zero
+  # cost pass-through.
+  #
+  # @see Parse.pluralized_aliases
+  # @see Parse.__pluralized_alias_for
+  module PluralizedAliases
+    def const_missing(name)
+      klass = Parse.__pluralized_alias_for(self, name) if defined?(Parse)
+      return klass unless klass.nil?
+      super
+    end
+  end
+end
+
+Module.prepend(Parse::PluralizedAliases)

data/lib/parse/model/core/properties.rb

@@ -197,6 +197,33 @@ module Parse
           # data_type = :timezone if key == :time_zone || key == :timezone
         end
 
+        # A property that names a pointer target — via `as:`/`class_name:` or an
+        # explicit :pointer data type — is really a belongs_to association, not a
+        # scalar column. Delegate so `property :rejected_by, as: :user` behaves
+        # identically to `belongs_to :rejected_by, as: :user` instead of silently
+        # storing a String (the `as:` option was previously dropped, leaving the
+        # field as the default :string type). Reusing belongs_to keeps the
+        # className-trust guard and autofetch/dirty-tracking in one place rather
+        # than duplicating pointer handling here. `opts` is still raw user input
+        # at this point (the defaults merge happens further down), so only an
+        # explicitly-passed :field is forwarded and belongs_to defaults the rest.
+        if opts.key?(:as) || opts.key?(:class_name) || data_type == :pointer
+          forwarded = %i[as class_name field required _description _enum]
+          bt_opts = {}
+          forwarded.each { |o| bt_opts[o] = opts[o] if opts.key?(o) }
+          # belongs_to has no scalar-property machinery (defaults, symbolize,
+          # enum validation, alias toggles, scope generation). Surface — rather
+          # than silently drop — any such option so a `default:`/`symbolize:` on
+          # a pointer property isn't quietly ignored.
+          dropped = opts.keys.map(&:to_sym) - forwarded
+          unless dropped.empty?
+            warn "[#{self}] property #{key.inspect} resolves to a pointer association; " \
+                 "ignoring unsupported option(s) #{dropped.map(&:inspect).join(', ')} " \
+                 "(not available on belongs_to)."
+          end
+          return belongs_to(key, bt_opts)
+        end
+
         data_type = :timezone if data_type == :string && (key == :time_zone || key == :timezone)
 
         # allow :bool for :boolean

data/lib/parse/model/core/querying.rb

@@ -120,6 +120,76 @@ module Parse
 
       alias_method :where, :query
 
+      # Define a pluralized constant alias for this class so the plural form
+      # can be used as a query entry point — e.g. `Posts.where(...).count`
+      # for a class `Post`. The alias is the same class object, so every
+      # class method (`where`, `query`, `count`, `find`, `all`, scopes)
+      # works through it and `Posts.parse_class` still returns `"Post"`.
+      #
+      # This is the explicit counterpart to the automatic
+      # {Parse.pluralized_aliases} behavior. Use it when automatic aliasing
+      # is disabled, when the class name ends in `s` (which the automatic
+      # path skips), when you want a custom plural, or for namespaced models
+      # (the alias is defined on the enclosing module, not at top level).
+      #
+      # @example default plural
+      #   class Post < Parse::Object
+      #     pluralized_alias!          # defines ::Posts => Post
+      #   end
+      #
+      # @example custom plural for a name ending in `s`
+      #   class Status < Parse::Object
+      #     pluralized_alias! :Statuses
+      #   end
+      #
+      # @example namespaced model
+      #   module Blog
+      #     class Post < Parse::Object
+      #       pluralized_alias!        # defines Blog::Posts => Blog::Post
+      #     end
+      #   end
+      #
+      # @param constant_name [Symbol, String, nil] the plural constant to
+      #   define; defaults to the ActiveSupport pluralization of the class's
+      #   demodulized name.
+      # @raise [ArgumentError] if the target constant already exists and is
+      #   not this class.
+      # @return [self, nil] self when an alias exists/was created; nil if the
+      #   class is anonymous or the plural matches the singular name.
+      def pluralized_alias!(constant_name = nil)
+        base = name
+        return nil if base.nil?
+        parts = base.split("::")
+        short = parts.last
+        plural = (constant_name && constant_name.to_s) || short.pluralize
+        return nil if plural == short
+        # NOTE: bare `Object` here would lexically resolve to `Parse::Object`
+        # (we are inside module Parse::Core::Querying), so the alias must be
+        # anchored at the true top level with `::Object`.
+        parent = parts.length > 1 ? parts[0..-2].join("::").constantize : ::Object
+        if parent.const_defined?(plural.to_sym, false)
+          existing = parent.const_get(plural.to_sym)
+          return self if existing.equal?(self)
+          # A code reloader (Zeitwerk in development) swaps `self` for a fresh
+          # class object but does not clean up the alias constant we set — it
+          # owns no autoload entry for it. On re-run of the class body the
+          # plural still points at the now-orphaned previous class. Re-point it
+          # to the current class instead of raising on every reload. Only a
+          # genuinely foreign constant (not a Parse model mapping to the same
+          # remote class) is treated as a conflict.
+          stale_reload = existing.is_a?(Class) && existing < Parse::Object &&
+                         existing.parse_class == parse_class
+          unless stale_reload
+            raise ArgumentError,
+                  "Cannot define pluralized alias #{plural} for #{base}: " \
+                  "constant already defined as #{existing}."
+          end
+          parent.send(:remove_const, plural.to_sym)
+        end
+        parent.const_set(plural.to_sym, self)
+        self
+      end
+
       # @param conditions (see Parse::Query#where)
       # @return (see Parse::Query#where)
       # @see Parse::Query#where
@@ -484,7 +554,7 @@ module Parse
       # @return [Parse::LiveQuery::Subscription] the subscription object
       # @see Parse::LiveQuery::Subscription
       # @see Parse::Query#subscribe
-      def subscribe(where: {}, fields: nil, session_token: nil, client: nil,
+      def subscribe(where: {}, fields: nil, keys: nil, watch: nil, session_token: nil, client: nil,
                     use_master_key: false, &block)
         # Fall through to the ambient set by `Parse.with_session` / `Parse.login`
         # so a caller wrapping a region with `with_session(user) { Klass.subscribe ... }`
@@ -495,6 +565,8 @@ module Parse
         end
         query(where).subscribe(
           fields: fields,
+          keys: keys,
+          watch: watch,
           session_token: session_token,
           client: client,
           use_master_key: use_master_key,