parse-stack-next 5.2.1 → 5.4.0

data/lib/parse/api/hooks.rb

@@ -7,15 +7,52 @@ module Parse
     module Hooks
       # @!visibility private
       HOOKS_PREFIX = "hooks/"
-      # The allowed set of Parse triggers.
-      TRIGGER_NAMES = [:afterCreate, :afterDelete, :afterFind, :afterSave, :beforeDelete, :beforeFind, :beforeSave].freeze
+      # The allowed set of Parse webhook triggers. Mirrors Parse Server's
+      # `triggers.Types` so registration of the auth / LiveQuery / password-
+      # reset hooks is no longer pre-rejected by the SDK.
+      #
+      # NOTE: this allowlist gates *registration* only. The webhook router in
+      # {Parse::Webhooks} currently shapes payloads for the object triggers
+      # (before/after save/delete/find); the login / connect / subscribe /
+      # password-reset payloads carry a different shape (no `object`) and
+      # their first-class routing is a follow-up. `beforeConnect` is a
+      # connection-global trigger whose Parse-canonical className is the
+      # `@Connect` sentinel; file triggers use `@File`. Both are accepted by
+      # the trigger-className validator ({Parse::API::PathSegment.trigger_class_name!}).
+      TRIGGER_NAMES = [
+        :afterDelete, :afterFind, :afterSave,
+        :beforeDelete, :beforeFind, :beforeSave,
+        :beforeLogin, :afterLogin, :afterLogout, :beforePasswordResetRequest,
+        :beforeConnect, :beforeSubscribe, :afterEvent,
+      ].freeze
       # @!visibility private
-      TRIGGER_NAMES_LOCAL = [:after_create, :after_delete, :after_find, :after_save, :before_delete, :before_find, :before_save].freeze
+      TRIGGER_NAMES_LOCAL = [
+        :after_delete, :after_find, :after_save,
+        :before_delete, :before_find, :before_save,
+        :before_login, :after_login, :after_logout, :before_password_reset_request,
+        :before_connect, :before_subscribe, :after_event,
+      ].freeze
+
+      # `beforeCreate` / `afterCreate` are NOT Parse Server trigger types —
+      # Parse Server rejects them ("invalid hook declaration"). They exist only
+      # as Parse-Stack ActiveModel callbacks (`before_create` / `after_create`),
+      # which the webhook router runs INSIDE the `beforeSave` / `afterSave`
+      # handler for new objects (gated on `original.nil?`). So there is nothing
+      # to register for them — register `beforeSave` / `afterSave` instead and
+      # the create callbacks fire within it.
       # @!visibility private
       def _verify_trigger(triggerName)
-        triggerName = triggerName.to_s.camelize(:lower).to_sym
-        raise ArgumentError, "Invalid trigger name #{triggerName}" unless TRIGGER_NAMES.include?(triggerName)
-        triggerName
+        camel = triggerName.to_s.camelize(:lower).to_sym
+        if %i[beforeCreate afterCreate].include?(camel)
+          save     = camel == :beforeCreate ? "beforeSave" : "afterSave"
+          callback = camel == :beforeCreate ? "before_create" : "after_create"
+          raise ArgumentError,
+                "Parse Server has no #{camel} webhook trigger. Register a " \
+                "#{save} webhook instead — Parse Stack runs your #{callback} " \
+                "ActiveModel callbacks within the #{save} handler for new objects."
+        end
+        raise ArgumentError, "Invalid trigger name #{camel}" unless TRIGGER_NAMES.include?(camel)
+        camel
       end
 
       # Fetch all defined cloud code functions.
@@ -74,7 +111,7 @@ module Parse
       # @see TRIGGER_NAMES
       def fetch_trigger(triggerName, className)
         triggerName = _verify_trigger(triggerName)
-        safe_class = Parse::API::PathSegment.identifier!(className, kind: "class name")
+        safe_class = Parse::API::PathSegment.trigger_class_name!(className, kind: "class name")
         request :get, "#{HOOKS_PREFIX}triggers/#{safe_class}/#{triggerName}"
       end
 
@@ -98,7 +135,7 @@ module Parse
       # @see Parse::API::Hooks::TRIGGER_NAMES
       def update_trigger(triggerName, className, url)
         triggerName = _verify_trigger(triggerName)
-        safe_class = Parse::API::PathSegment.identifier!(className, kind: "class name")
+        safe_class = Parse::API::PathSegment.trigger_class_name!(className, kind: "class name")
         request :put, "#{HOOKS_PREFIX}triggers/#{safe_class}/#{triggerName}", body: { url: url }
       end
 
@@ -109,7 +146,7 @@ module Parse
       # @see Parse::API::Hooks::TRIGGER_NAMES
       def delete_trigger(triggerName, className)
         triggerName = _verify_trigger(triggerName)
-        safe_class = Parse::API::PathSegment.identifier!(className, kind: "class name")
+        safe_class = Parse::API::PathSegment.trigger_class_name!(className, kind: "class name")
         request :put, "#{HOOKS_PREFIX}triggers/#{safe_class}/#{triggerName}", body: { __op: "Delete" }
       end
     end

data/lib/parse/api/objects.rb

@@ -84,8 +84,15 @@ module Parse
       # @param body [Hash] the body of the request.
       # @param opts [Hash] additional options to pass to the {Parse::Client} request.
       # @param headers [Hash] additional HTTP headers to send with the request.
+      # @param context [Hash, nil] an optional caller context forwarded as the
+      #   +X-Parse-Cloud-Context+ header. Parse Server maps it to
+      #   +req.info.context+ inside beforeSave/afterSave cloud triggers.
+      #   Omit or pass +nil+ to leave behavior unchanged.
       # @return [Parse::Response]
-      def create_object(className, body = {}, headers: {}, **opts)
+      def create_object(className, body = {}, headers: {}, context: nil, **opts)
+        unless context.nil?
+          headers = headers.merge(Parse::Protocol::CLOUD_CONTEXT => context.to_json)
+        end
         response = request :post, uri_path(className), body: body, headers: headers, opts: opts
         response.parse_class = className if response.present?
         response
@@ -135,8 +142,15 @@ module Parse
       # @param body [Hash] The key value pairs to update.
       # @param opts [Hash] additional options to pass to the {Parse::Client} request.
       # @param headers [Hash] additional HTTP headers to send with the request.
+      # @param context [Hash, nil] an optional caller context forwarded as the
+      #   +X-Parse-Cloud-Context+ header. Parse Server maps it to
+      #   +req.info.context+ inside beforeSave/afterSave cloud triggers.
+      #   Omit or pass +nil+ to leave behavior unchanged.
       # @return [Parse::Response]
-      def update_object(className, id, body = {}, headers: {}, **opts)
+      def update_object(className, id, body = {}, headers: {}, context: nil, **opts)
+        unless context.nil?
+          headers = headers.merge(Parse::Protocol::CLOUD_CONTEXT => context.to_json)
+        end
         response = request :put, uri_path(className, id), body: body, headers: headers, opts: opts
         response.parse_class = className if response.present?
         response

data/lib/parse/api/path_segment.rb

@@ -45,6 +45,39 @@ module Parse
         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
+      # leading `@` is the only relaxation; the rest stays path-safe (no `/`,
+      # `.`, or `..`).
+      TRIGGER_CLASS_PATTERN = /\A@?[A-Za-z_][A-Za-z0-9_]*\z/.freeze
+
+      # Validate a className used in a webhook-trigger path
+      # (`hooks/triggers/<className>/<trigger>`). Same as {.identifier!} but
+      # additionally accepts the `@File` / `@Connect` pseudo-classes that Parse
+      # Server uses for file and connection triggers. `create_trigger` carries
+      # the className in the request BODY (not the path), so it already accepts
+      # these; this keeps fetch / update / delete symmetric with create.
+      #
+      # @param value the className to validate.
+      # @param kind [String] human-readable name for error messages.
+      # @return [String] the validated className.
+      # @raise [ArgumentError] if blank or otherwise fails the pattern.
+      def trigger_class_name!(value, kind: "class name")
+        s = value.to_s
+        if s.empty?
+          raise ArgumentError, "#{kind} must not be empty"
+        end
+        unless TRIGGER_CLASS_PATTERN.match?(s)
+          raise ArgumentError,
+            "#{kind} #{s.inspect} contains characters that are not allowed in " \
+            "a Parse trigger class name. Names must match " \
+            "/\\A@?[A-Za-z_][A-Za-z0-9_]*\\z/ (an identifier, optionally an " \
+            "@-prefixed pseudo-class such as @File or @Connect)."
+        end
+        s
+      end
+
       # Validate and percent-encode a less-restrictive path segment, used
       # for file names which can contain hyphens, periods, and other
       # filename-safe characters but must never contain a literal `/`,

data/lib/parse/api/server.rb

@@ -59,6 +59,100 @@ module Parse
         server_info.present? ? @server_info[:parseServerVersion] : nil
       end
 
+      # The `features` block advertised by `GET /serverInfo`. Parse Server
+      # surfaces coarse capability groups here (`globalConfig`, `hooks`,
+      # `cloudCode`, `logs`, `push`, `schemas`), each a Hash of booleans.
+      # This is authoritative where present but intentionally coarse — it
+      # does NOT carry fine-grained behavior flags like "public explain" or
+      # the LiveQuery `keys` rename. Those are resolved by version inference
+      # in {#server_supports?}.
+      # @return [Hash] the advertised features block, or `{}` if unavailable.
+      def server_features
+        info = server_info
+        return {} unless info.is_a?(Hash)
+        feats = info[:features]
+        feats.is_a?(Hash) ? feats : {}
+      end
+
+      # Capability table consumed by {#server_supports?}. Each entry is
+      # version-inferred (we cannot read these off the coarse `features`
+      # block) with one of two predicates:
+      #
+      # - `since:` — the capability EXISTS on this version and newer. An
+      #   unknown/unparseable server version resolves to `true`
+      #   (fail-open-to-modern: assume the current server line, matching the
+      #   deprecation gate's posture).
+      # - `until:` — the capability existed BELOW this version and was
+      #   removed/restricted at it. Unknown version resolves to `false`
+      #   (the modern server no longer offers it).
+      #
+      # `feature:` (a `[group, flag]` pair) lets a future capability prefer
+      # the advertised `features` block when Parse Server genuinely surfaces
+      # it there; absent that, the version predicate decides.
+      # @!visibility private
+      CAPABILITIES = {
+        # LiveQuery subscription field projection: the `fields` option was
+        # renamed `keys` in Parse Server 7.0.0 (DEPPS9 / #8852). The SDK
+        # emits both, so this is informational rather than gating.
+        livequery_keys_option: { since: "7.0.0" },
+        # Cloud functions encode returned Parse.Object values as `__type`
+        # dictionaries: default flipped to `true` in 8.0.0, made
+        # unconditional (option removed) in 9.0.0.
+        cloud_object_encoding: { since: "8.0.0" },
+        # Non-master `explain` on a query: `allowPublicExplain` defaulted to
+        # `false` in 9.0.0, so a session-scoped explain that worked on 8.x
+        # is rejected on 9.x unless the operator re-enables it.
+        public_explain: { until: "9.0.0" },
+        # Aggregation `rawValues` / `rawFieldNames` options added in 9.9.0
+        # (#10438).
+        aggregate_raw_values: { since: "9.9.0" },
+      }.freeze
+
+      # Capability probe against the connected Parse Server. Builds on the
+      # already-memoized {#server_info} (no extra round-trip beyond the one
+      # `serverInfo` fetch) and the coarse `features` block, falling back to
+      # version inference for behavior flags the `features` block does not
+      # carry.
+      #
+      # Fails OPEN to the modern server line: when the server version cannot
+      # be determined (offline unit tests, a `serverInfo` outage, a wire
+      # surprise), a `since:` capability resolves `true` and an `until:`
+      # capability resolves `false` — i.e. "assume the current server",
+      # mirroring {#warn_if_deprecated_server_version!}.
+      #
+      # @example
+      #   client.server_supports?(:public_explain)   # => false on PS 9.x
+      #   client.server_supports?(:aggregate_raw_values)
+      # @param feature [Symbol] a key of {CAPABILITIES}.
+      # @return [Boolean] whether the connected server supports the feature.
+      # @raise [ArgumentError] for an unknown capability key (typo guard).
+      def server_supports?(feature)
+        spec = CAPABILITIES[feature]
+        raise ArgumentError, "Unknown Parse Server capability #{feature.inspect}" if spec.nil?
+
+        # Prefer the advertised features block when a capability declares a
+        # `[group, flag]` path AND the server actually surfaces it.
+        if (path = spec[:feature])
+          group, flag = path
+          advertised = server_features.dig(group.to_s, flag.to_s)
+          advertised = server_features.dig(group, flag) if advertised.nil?
+          return advertised == true unless advertised.nil?
+        end
+
+        version = server_version.to_s
+        if (floor = spec[:since])
+          # Supported on `floor` and newer. Unknown version => assume modern => true.
+          return true if version.empty?
+          !server_version_below?(version, floor)
+        elsif (ceiling = spec[:until])
+          # Supported strictly below `ceiling`. Unknown version => assume modern => false.
+          return false if version.empty?
+          server_version_below?(version, ceiling)
+        else
+          false
+        end
+      end
+
       private
 
       # One-shot deprecation warning. The check runs once per client

data/lib/parse/api/users.rb

@@ -14,7 +14,11 @@ module Parse
       # @!visibility private
       LOGIN_PATH = "login"
       # @!visibility private
+      VERIFY_PASSWORD_PATH = "verifyPassword"
+      # @!visibility private
       REQUEST_PASSWORD_RESET = "requestPasswordReset"
+      # @!visibility private
+      VERIFICATION_EMAIL_REQUEST = "verificationEmailRequest"
 
       # Fetch a {Parse::User} for a given objectId.
       # @param id [String] the user objectid
@@ -130,6 +134,26 @@ module Parse
         response
       end
 
+      # Request that Parse Server (re)send the email-address verification email
+      # for a registered, not-yet-verified user. Requires the server to have an
+      # email adapter and `verifyUserEmails` enabled; otherwise Parse Server
+      # responds with an error. Rate-limited per email like password reset.
+      #
+      # @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.
+      # @return [Parse::Response]
+      def request_email_verification(email, headers: {}, **opts)
+        rate_key = "emailverify:#{email}"
+        check_login_rate_limit!(rate_key)
+        body = { email: email }
+        response = request :post, VERIFICATION_EMAIL_REQUEST, body: body, opts: opts, headers: headers
+        # Indistinguishable found/not-found response, like password reset — count
+        # every attempt toward backoff so probing can't reset the counter.
+        track_login_attempt(rate_key, false)
+        response
+      end
+
       # Login a user. Implements client-side rate limiting with exponential
       # backoff after repeated failures to mitigate brute force attacks.
       # @param username [String] the Parse user username.
@@ -180,6 +204,37 @@ module Parse
         response
       end
 
+      # Verify a user's credentials against Parse Server without minting a session.
+      # This is the canonical step-up / re-authentication primitive: it confirms
+      # that the username + password combination is correct without producing a
+      # new session token on success.
+      #
+      # Uses the +POST /parse/verifyPassword+ endpoint (credentials in the request
+      # BODY, mirroring +login+) rather than the +GET+ form. Parse Server accepts
+      # both (same handler, neither master-key gated; the POST variant landed in
+      # 7.1.0), but POST keeps the plaintext password out of the URL — and
+      # therefore out of server access logs, reverse-proxy logs, the +Referer+
+      # header, and the SDK's URL-keyed response cache.
+      #
+      # On success Parse Server returns the user object (HTTP 200) with the same
+      # shape as a login response (minus +sessionToken+). On failure it returns a
+      # 4xx with an error body, most commonly:
+      # - code 101 (+ERROR_OBJECT_NOT_FOUND+) for an unknown username or wrong password.
+      # - code 205 (+ERROR_EMAIL_NOT_FOUND+) when +preventLoginWithUnverifiedEmail+
+      #   is enabled and the account's email has not been verified.
+      #
+      # @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)
+        body = { username: username, password: password }
+        response = request :post, VERIFY_PASSWORD_PATH, body: body, headers: headers, opts: opts
+        response.parse_class = Parse::Model::CLASS_USER
+        response
+      end
+
       # Logout a user by deleting the associated session.
       # @param session_token [String] the Parse user session token to delete.
       # @param headers [Hash] additional HTTP headers to send with the request.
@@ -223,7 +278,7 @@ module Parse
       LOGIN_RATE_LIMIT_TTL = 600
 
       # Checks if a login attempt is allowed for the given username.
-      # @raise [RuntimeError] if the account is temporarily locked out.
+      # @raise [Parse::Error::AccountLockoutError] if the account is temporarily locked out.
       def check_login_rate_limit!(username)
         @login_rate_limit_mutex ||= Mutex.new
         @login_rate_limit_mutex.synchronize do
@@ -231,7 +286,8 @@ module Parse
           return unless entry
           if entry[:locked_until] && Time.now < entry[:locked_until]
             wait = (entry[:locked_until] - Time.now).ceil
-            raise "Login rate limited for '#{username}'. Try again in #{wait} seconds."
+            raise Parse::Error::AccountLockoutError,
+                  "Login rate limited for '#{username}'. Try again in #{wait} seconds."
           end
         end
       end

data/lib/parse/atlas_search.rb

@@ -105,10 +105,10 @@ module Parse
 
       # @!attribute [rw] role_cache_ttl
       #   TTL (seconds) for {Session}'s user-id → role-name cache.
-      #   Default: 120 (2 minutes). Short on purpose: stale role
-      #   data yields incorrect ACL decisions, so the cache is sized
-      #   to amortize within a single request/turn but expire well
-      #   inside the response time the operator notices a role grant.
+      #   Default: 30. Short on purpose: stale role data yields
+      #   incorrect ACL decisions, so the cache is sized to amortize
+      #   within a single request/turn but expire well inside the
+      #   response time the operator notices a role grant or revoke.
       #   @return [Integer]
       attr_accessor :role_cache_ttl
 
@@ -141,7 +141,7 @@ module Parse
       # @param session_cache_ttl [Integer] session-token cache TTL
       #   (seconds). Default: 3600.
       # @param role_cache_ttl [Integer] role-name cache TTL (seconds).
-      #   Default: 120.
+      #   Default: 30.
       # @example
       #   Parse::AtlasSearch.configure(enabled: true, default_index: "default")
       def configure(enabled: true,
@@ -195,7 +195,7 @@ module Parse
         @allow_raw = default_allow_raw
         @require_session_token = false
         @session_cache_ttl = 3600
-        @role_cache_ttl = 120
+        @role_cache_ttl = 30
         @session_cache = Session::MemoryCache.new
         @role_cache = Session::MemoryCache.new
         @master_warned = false
@@ -1015,7 +1015,7 @@ module Parse
     @allow_raw = nil
     @require_session_token = false
     @session_cache_ttl = 3600
-    @role_cache_ttl = 120
+    @role_cache_ttl = 30
     @session_cache = Session::MemoryCache.new
     @role_cache = Session::MemoryCache.new
     @master_warned = false

data/lib/parse/client/body_builder.rb

@@ -74,6 +74,11 @@ module Parse
         Parse::Protocol::MASTER_KEY,
         Parse::Protocol::API_KEY,
         Parse::Protocol::SESSION_TOKEN,
+        # Caller-supplied Cloud Code context (X-Parse-Cloud-Context) carries
+        # `context.to_json`, which may hold PII / request metadata. Redact it in
+        # the header log; the body/as_json log path scrubs sensitive sub-values
+        # of context separately.
+        Parse::Protocol::CLOUD_CONTEXT,
         "X-Parse-JavaScript-Key",
         "Authorization",
         "Cookie",

data/lib/parse/client/protocol.rb

@@ -31,6 +31,10 @@ module Parse
     # The request header field for MongoDB read preference.
     # Supported values: PRIMARY, PRIMARY_PREFERRED, SECONDARY, SECONDARY_PREFERRED, NEAREST
     READ_PREFERENCE = "X-Parse-Read-Preference"
+    # The request header field for threading a caller-supplied context object
+    # through a write or cloud-function call. Parse Server maps this header to
+    # +req.info.context+ and flows it through beforeSave/afterSave triggers.
+    CLOUD_CONTEXT = "X-Parse-Cloud-Context"
 
     # Valid read preference values for MongoDB
     READ_PREFERENCES = %w[PRIMARY PRIMARY_PREFERRED SECONDARY SECONDARY_PREFERRED NEAREST].freeze

data/lib/parse/client.rb

@@ -331,7 +331,86 @@ module Parse
     attr_accessor :cache
     attr_writer :retry_limit
     attr_reader :application_id, :api_key, :master_key, :server_url
+    # @return [String, nil] the session token bound to this client, if any
+    #   (see the `:session_token` constructor option). Applied as the
+    #   lowest-priority auth fallback on every request.
+    attr_reader :session_token
     alias_method :app_id, :application_id
+
+    # Redacted inspection. The default Ruby `#inspect` would dump every ivar,
+    # exposing the master key and any bound session token in cleartext wherever
+    # a client is logged or surfaced in an error reporter. Show only the
+    # connection identity and a boolean for each credential's presence.
+    def inspect
+      "#<#{self.class.name} server_url=#{@server_url.inspect} " \
+      "app_id=#{@application_id.inspect} master_key=#{@master_key ? "[FILTERED]" : "nil"} " \
+      "session_token=#{@session_token ? "[FILTERED]" : "nil"}>"
+    end
+
+    # A NEW non-master {Parse::Client} that mirrors THIS client's connection
+    # settings (`server_url` / `application_id` / `api_key`) but carries no
+    # master key and binds +session_token+, so it acts on the server as that
+    # user (ACL / CLP / `protectedFields` enforced, no master-key fallback).
+    # This is the general primitive behind {Parse::Webhooks::Payload#user_client}
+    # and {Parse::User#session_client}: derive a user-scoped client from a
+    # configured (e.g. master) client without re-specifying the connection.
+    #
+    #   user_client = Parse.client.become(user.session_token)
+    #   Parse::Query.new("Post", client: user_client).results   # as the user
+    #
+    # @param session_token [String, #session_token] the token to bind. A blank
+    #   token yields a tokenless non-master client (anonymous REST).
+    # @return [Parse::Client]
+    def become(session_token)
+      Parse::Client.new(
+        server_url: @server_url,
+        app_id: @application_id,
+        api_key: @api_key,
+        master_key: nil,
+        session_token: session_token,
+      )
+    end
+
+    # A NEW anonymous client that mirrors THIS client's connection but carries
+    # neither a master key nor a session token — every request it makes is
+    # unauthenticated (app-id + REST key only). Use it to drop the bound user
+    # identity for a one-off public read without mutating a shared client.
+    # Equivalent to {#become} with no token.
+    # @return [Parse::Client]
+    def anonymous
+      become(nil)
+    end
+
+    # Run a block with this client's bound {#session_token} active as the
+    # ambient session, so every query / object operation inside it that resolves
+    # the default client (e.g. `Post.count`, `Post.all`, `obj.save`) is
+    # authorized by Parse Server as that user — ACL and CLP enforced, master key
+    # suppressed — without threading `session_token:` through each call.
+    #
+    # This is the client-receiver flavor of {Parse.with_session} (and mirrors
+    # {Parse::User#with_session}); it scopes by binding the token as the AMBIENT
+    # session — it does not re-route operations through this client object, so
+    # the connection used inside the block is still the resolved default client.
+    # If you need operations to run against a different client, pass that client
+    # explicitly (e.g. `Parse::Query.new("Post", client: #{become}(...))`).
+    #
+    #   total = Parse::User.login(u, p).with_session { Post.count }   # readable Posts only
+    #
+    # Scopes REST-routed operations (`find` / `get` / `count` / `save`). It does
+    # NOT scope mongo-direct queries (`results_direct`, `aggregate`, Atlas
+    # search): those resolve auth from the query's own `session_token:` /
+    # `acl_user:` and, absent that, run in MASTER mode — so a mongo-direct read
+    # inside this block is a full master read, not anonymous. Scope mongo-direct
+    # explicitly with a per-query `session_token:` or a scoped {Parse::Agent}.
+    #
+    # @raise [ArgumentError] if this client has no bound session token (scoping
+    #   would be a no-op and almost certainly a mistake).
+    # @return the value of the block.
+    def with_session(&block)
+      raise ArgumentError, "Parse::Client#with_session requires a block" unless block_given?
+      raise ArgumentError, "Parse::Client#with_session requires a client with a bound session_token" if @session_token.nil?
+      Parse.with_session(@session_token, &block)
+    end
     # The client can support multiple sessions. The first session created, will be placed
     # under the default session tag. The :default session will be the default client to be used
     # by the other classes including Parse::Query and Parse::Objects
@@ -415,6 +494,14 @@ module Parse
     # @option opts [String] :master_key The Parse application master key (optional).
     #    If this key is set, it will be sent on every request sent by the client
     #    and your models. Defaults to ENV['PARSE_SERVER_MASTER_KEY'].
+    # @option opts [String] :session_token An optional session token bound to
+    #    this client. When set, every request that does not pass an explicit
+    #    `session_token:` / `use_master_key: true` and is not inside a
+    #    `Parse.with_session` block sends this token (and suppresses the master
+    #    key), so the client transparently acts as that user. Precedence is
+    #    explicit per-call > `Parse.with_session` ambient > this bound token.
+    #    Typically paired with `master_key: nil` to build a user-scoped client
+    #    (see {Parse::Webhooks::Payload#user_client}).
     # @option opts [Boolean, Symbol] :logging Controls request/response logging.
     #    - `true` - Enable logging at :info level
     #    - `:debug` - Enable verbose logging with headers and body content
@@ -492,7 +579,26 @@ module Parse
       @server_url = opts[:server_url] || ENV["PARSE_SERVER_URL"] || Parse::Protocol::SERVER_URL
       @application_id = opts[:application_id] || opts[:app_id] || ENV["PARSE_SERVER_APPLICATION_ID"] || ENV["PARSE_APP_ID"]
       @api_key = opts[:api_key] || opts[:rest_api_key] || ENV["PARSE_SERVER_REST_API_KEY"] || ENV["PARSE_API_KEY"]
-      @master_key = opts[:master_key] || ENV["PARSE_SERVER_MASTER_KEY"] || ENV["PARSE_MASTER_KEY"]
+      # Distinguish an explicit `master_key: nil` (deliberately a non-master
+      # client — what user_client / session_client / user_agent rely on) from
+      # an omitted key (fall back to ENV). The previous `opts[:master_key] ||
+      # ENV[...]` form silently re-inherited the process master key for the
+      # explicit-nil case, putting a "non-master" client back into master mode
+      # in any deployment that exports PARSE_SERVER_MASTER_KEY / PARSE_MASTER_KEY.
+      @master_key = if opts.key?(:master_key)
+                      opts[:master_key]
+                    else
+                      ENV["PARSE_SERVER_MASTER_KEY"] || ENV["PARSE_MASTER_KEY"]
+                    end
+      # Optional token bound to this client; applied per request as the
+      # lowest-priority auth fallback (see #request). Normalize blank/whitespace
+      # to nil so it never trips the "token present" branch at request time
+      # (where `present?` is false for whitespace) and silently fall back to the
+      # master key on a master-configured client.
+      bound_token = opts[:session_token]
+      bound_token = bound_token.session_token if bound_token.respond_to?(:session_token)
+      bound_token = bound_token.to_s.strip
+      @session_token = bound_token.empty? ? nil : bound_token
 
       @require_https = opts.fetch(:require_https, ENV["PARSE_REQUIRE_HTTPS"] == "true")
       @allow_faraday_proxy = opts.fetch(:allow_faraday_proxy, false)
@@ -1016,14 +1122,20 @@ module Parse
 
       token = opts[:session_token]
       # When no explicit token was passed AND the caller didn't ask to send
-      # the master key, fall through to the fiber-local ambient set by
-      # `Parse.with_session`. Explicit `use_master_key: true` is treated as
-      # a deliberate admin call and skips the ambient — otherwise an
-      # `admin.do_thing(use_master_key: true)` nested inside a
-      # `with_session(user)` block would silently downgrade.
+      # the master key, fall through to (in order) the fiber-local ambient set
+      # by `Parse.with_session`, then this client's own bound `@session_token`.
+      # Explicit `use_master_key: true` is treated as a deliberate admin call
+      # and skips both — otherwise an `admin.do_thing(use_master_key: true)`
+      # nested inside a `with_session(user)` block (or on a token-bound client)
+      # would silently downgrade. The ambient wins over the bound token so a
+      # `with_session` override inside a user-scoped client still takes effect.
       if token.nil? && !(explicit_master && opts[:use_master_key] == true)
         ambient = Parse.current_session_token
-        token = ambient if ambient.is_a?(String) && !ambient.empty?
+        # A whitespace-only ambient must not count as present: otherwise it
+        # blocks the bound-token fallback below and then fails the later
+        # `token.present?` check, silently sending the master key instead.
+        token = ambient if ambient.is_a?(String) && !ambient.strip.empty?
+        token = @session_token if (token.nil? || token.to_s.strip.empty?) && @session_token
       end
       if token.present?
         token = token.session_token if token.respond_to?(:session_token)
@@ -1302,9 +1414,53 @@ module Parse
   # Unwrap the `{ "result" => ... }` envelope from a successful cloud-code response.
   # Guards against unusual server payloads (non-Hash bodies) by returning the raw
   # result rather than raising TypeError on `String#[]`/`Integer#[]`.
+  #
+  # Parse Server 8.0 flipped `encodeParseObjectInCloudFunction` to true and 9.0
+  # removed the opt-out, so a cloud function that returns a Parse object now
+  # yields a `__type`-encoded dictionary (`{"__type":"Object","className":...}`)
+  # where a pre-8.x caller received a plain attribute Hash. We decode those
+  # self-describing envelopes back into `Parse::Object` / `Parse::Pointer` so the
+  # value a caller sees is consistent across server versions and matches what
+  # every other Parse SDK returns. Decoding is conservative: only a fully-shaped
+  # 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.
   def self._extract_cloud_result(response)
     r = response.result
-    r.is_a?(Hash) ? r["result"] : r
+    value = r.is_a?(Hash) ? r["result"] : r
+    _decode_cloud_value(value)
+  end
+
+  # @!visibility private
+  # Recursively decode Parse-encoded values in a cloud-code result. See
+  # {._extract_cloud_result} for the rationale and the conservatism rules.
+  def self._decode_cloud_value(value)
+    case value
+    when Array
+      value.map { |v| _decode_cloud_value(v) }
+    when Hash
+      type = value["__type"] || value[:__type]
+      class_name = value["className"] || value[:className]
+      object_id  = value["objectId"] || value[:objectId]
+      if type == Parse::Model::TYPE_POINTER && class_name && object_id
+        # Pointers carry no attributes, so building one is lossless even for
+        # an unregistered class (yields a Parse::Pointer).
+        Parse::Object.build(value)
+      elsif type == Parse::Model::TYPE_OBJECT && class_name && object_id &&
+            Parse::Model.find_class(class_name)
+        # Only build a full object when the class is registered; otherwise
+        # Parse::Object.build collapses to a field-less Pointer and we'd lose
+        # the attributes — better to hand back the raw Hash.
+        Parse::Object.build(value)
+      else
+        # Plain Hash, partial envelope, or non-object `__type` (Date/GeoPoint/
+        # File/Bytes, or literal app data): leave the node shape intact and
+        # only recurse into nested values so embedded objects still decode.
+        value.transform_values { |v| _decode_cloud_value(v) }
+      end
+    else
+      value
+    end
   end
 
   # Helper method to trigger cloud jobs and get results.
@@ -1379,6 +1535,9 @@ module Parse
   # @option opts [Symbol] :client The client connection to use.
   # @option opts [Boolean] :raw Whether to return the raw response object.
   # @option opts [Boolean] :master_key Whether to use the master key for this request.
+  # @option opts [Hash, nil] :context An optional caller context forwarded as the
+  #   +X-Parse-Cloud-Context+ header. Parse Server maps it to +req.info.context+
+  #   in the function handler and flows it through beforeSave/afterSave triggers.
   # @return [Object] the result data of the response. nil if there was an error.
   def self.call_function(name, body = {}, **opts)
     conn = opts[:session] || opts[:client] || :default
@@ -1388,7 +1547,13 @@ module Parse
     request_opts[:session_token] = opts[:session_token] if opts[:session_token]
     request_opts[:master_key] = opts[:master_key] if opts[:master_key]
 
-    response = Parse::Client.client(conn).call_function(name, body, opts: request_opts)
+    # Build call kwargs; only forward context: when explicitly supplied so
+    # call sites that do not use context produce the same opts hash that
+    # existing mock expectations match against.
+    call_kwargs = { opts: request_opts }
+    call_kwargs[:context] = opts[:context] unless opts[:context].nil?
+
+    response = Parse::Client.client(conn).call_function(name, body, **call_kwargs)
     return response if opts[:raw].present?
     if response.error?
       Parse::Client._safe_warn("CloudCodeError", response, name: name)