parse-stack-next 5.5.3 → 5.5.5

data/lib/parse/query.rb

@@ -19,7 +19,7 @@ module Parse
   # your Parse collections by utilizing the {http://docs.parseplatform.org/rest/guide/#queries
   # REST Querying interface}. This is the main engine behind making Parse queries
   # on remote collections. It takes a set of constraints and generates the
-  # proper hash parameters that are passed to an API request in order to retrive
+  # proper hash parameters that are passed to an API request in order to retrieve
   # matching results. The querying design pattern is inspired from
   # {http://datamapper.org/ DataMapper} where symbols are overloaded with
   # specific methods with attached values.
@@ -44,19 +44,19 @@ module Parse
   # names when compiling the query. This feature can be overridden by changing the
   # value of {Parse::Query.field_formatter}.
   #
-  #  # default uses :columnize
-  #  query = Parse::User.query :field_one => 1, :FieldTwo => 2, :Field_Three => 3
-  #  query.compile_where # => {"fieldOne"=>1, "fieldTwo"=>2, "fieldThree"=>3}
+  #     # default uses :columnize
+  #     query = Parse::User.query :field_one => 1, :FieldTwo => 2, :Field_Three => 3
+  #     query.compile_where # => {"fieldOne"=>1, "fieldTwo"=>2, "fieldThree"=>3}
   #
-  #  # turn off
-  #  Parse::Query.field_formatter = nil
-  #  query = Parse::User.query :field_one => 1, :FieldTwo => 2, :Field_Three => 3
-  #  query.compile_where # => {"field_one"=>1, "FieldTwo"=>2, "Field_Three"=>3}
+  #     # turn off
+  #     Parse::Query.field_formatter = nil
+  #     query = Parse::User.query :field_one => 1, :FieldTwo => 2, :Field_Three => 3
+  #     query.compile_where # => {"field_one"=>1, "FieldTwo"=>2, "Field_Three"=>3}
   #
-  #  # force everything camel case
-  #  Parse::Query.field_formatter = :camelize
-  #  query = Parse::User.query :field_one => 1, :FieldTwo => 2, :Field_Three => 3
-  #  query.compile_where # => {"FieldOne"=>1, "FieldTwo"=>2, "FieldThree"=>3}
+  #     # force everything camel case
+  #     Parse::Query.field_formatter = :camelize
+  #     query = Parse::User.query :field_one => 1, :FieldTwo => 2, :Field_Three => 3
+  #     query.compile_where # => {"FieldOne"=>1, "FieldTwo"=>2, "FieldThree"=>3}
   #
   # Most of the constraints supported by Parse are available to `Parse::Query`.
   # Assuming you have a column named `field`, here are some examples. For an
@@ -524,6 +524,25 @@ module Parse
         # Normalize to symbol for comparison (handles both string and symbol keys)
         expr_sym = expression.respond_to?(:to_sym) ? expression.to_sym : expression
 
+        # SEC-06: privilege/auth control options must NOT be settable from an
+        # untrusted, string-keyed conditions hash. `use_master_key` via a
+        # forwarded params hash (e.g. `Query.new(Cls, {"use_master_key" =>
+        # true, "ownerId" => "victim"})`) is an ACL/CLP-bypass mass-
+        # assignment; `session` swaps the query's auth principal. Honor these
+        # two ONLY when the caller passed a Symbol key (code-authored). A
+        # string form is treated as an ordinary field constraint — fail-safe:
+        # it matches a literal field of that name and never elevates.
+        if !expression.is_a?(Symbol) && (expr_sym == :use_master_key || expr_sym == :session)
+          warn "[Parse::Query] Ignoring string-keyed control option " \
+               "#{expression.inspect}; auth/privilege options (:use_master_key, " \
+               ":session) are honored only as symbol keys to prevent " \
+               "mass-assignment from untrusted params. Treating it as a field " \
+               "constraint. Set it via the query method (e.g. `use_master_key: " \
+               "true` as a symbol) if you intended to control authentication."
+          add_constraint(expression, value)
+          next
+        end
+
         if expr_sym == :order
           order value
         elsif expr_sym == :keys
@@ -635,23 +654,23 @@ module Parse
     # When set, Parse Server excludes the named fields from each returned
     # object, complementing the {#keys} allowlist. The two options can be
     # combined: Parse Server first applies the {#keys} allowlist, then
-    # strips any field names listed in +excludeKeys+.
+    # strips any field names listed in `excludeKeys`.
     #
-    # @note On the REST query path (+encode: true+ in {#compile}) this maps to
-    #   Parse Server's path-scoped +excludeKeys+. On the mongo-direct path
-    #   (explicit +.results_direct+, an auto-route, or an aggregation that
-    #   auto-promotes — e.g. an +$inQuery+ pointer constraint that rewrites to
-    #   a +$lookup+) the pipeline can only project the {#keys} allowlist, so
+    # @note On the REST query path (`encode: true` in {#compile}) this maps to
+    #   Parse Server's path-scoped `excludeKeys`. On the mongo-direct path
+    #   (explicit `.results_direct`, an auto-route, or an aggregation that
+    #   auto-promotes — e.g. an `$inQuery` pointer constraint that rewrites to
+    #   a `$lookup`) the pipeline can only project the {#keys} allowlist, so
     #   the SDK honors the denylist as a post-fetch sanitize over the returned
     #   results instead. That mongo-direct sanitize is recursive by name: it
     #   strips EVERY key with a matching name at any depth, so excluding a
     #   field also removes a same-named field inside included/nested objects —
     #   broader than the REST path's top-level/dotted scoping. Reserved
-    #   envelope fields (+objectId+, +className+, +__type+, +createdAt+,
-    #   +updatedAt+, +ACL+ and their Mongo storage-form names) are never
+    #   envelope fields (`objectId`, `className`, `__type`, `createdAt`,
+    #   `updatedAt`, `ACL` and their Mongo storage-form names) are never
     #   stripped, so object reconstruction is unaffected. The raw aggregation
     #   accessor (`aggregate(...).raw`) returns unredacted documents — the
-    #   sanitize applies to the object/decoded result paths. +excludeKeys+ is a
+    #   sanitize applies to the object/decoded result paths. `excludeKeys` is a
     #   projection convenience, not an ACL/CLP boundary, so it does not affect
     #   access control.
     #
@@ -731,7 +750,7 @@ module Parse
     #  Song.all :order => { :like_count => :desc, :name => :asc }
     # @param ordering [Parse::Order, Symbol, String, Hash] one or more
     #   ordering directives. A Hash maps field => direction. Unsupported
-    #   argument types raise +ArgumentError+ rather than being silently
+    #   argument types raise `ArgumentError` rather than being silently
     #   dropped.
     # @return [self]
     def order(*ordering)
@@ -808,9 +827,9 @@ module Parse
     #  Song.all :limit => 2025 # large limits supported.
     #  Song.all :limit => :max # as many records as possible.
     # @param count [Integer,Symbol,String,nil] The number of records to return.
-    #  Pass +:max+ to fetch as many records as possible (Parse-Server dependent).
-    #  Numeric strings (e.g. +"50"+) are coerced to Integer. Pass +nil+ to
-    #  explicitly clear the limit. Any other value raises +ArgumentError+
+    #  Pass `:max` to fetch as many records as possible (Parse-Server dependent).
+    #  Numeric strings (e.g. `"50"`) are coerced to Integer. Pass `nil` to
+    #  explicitly clear the limit. Any other value raises `ArgumentError`
     #  rather than silently disabling the limit.
     # @return [self]
     def limit(count)
@@ -855,18 +874,18 @@ module Parse
     # Forces Parse Server (and the underlying MongoDB driver) to use the
     # named index instead of the query planner's choice. Useful for
     # benchmarking or for working around sub-optimal plan selection.
-    # The hint is emitted in the compiled REST query body as the +hint+
+    # The hint is emitted in the compiled REST query body as the `hint`
     # parameter (supported by Parse Server 7.4.0+) AND forwarded to the
-    # mongo-direct path — +results_direct+ / +count_direct+ / +distinct_direct+
+    # mongo-direct path — `results_direct` / `count_direct` / `distinct_direct`
     # pass it to {Parse::MongoDB.aggregate}/{Parse::MongoDB.find} as the Mongo
-    # +hint+ option, so a plan diagnosed with {#explain} can be corrected on
+    # `hint` option, so a plan diagnosed with {#explain} can be corrected on
     # either path.
     #
     # @example Force a specific index
     #   Post.query(:status => "published").hint("status_1_created_at_-1").results
     #
     # @param index_name [String, nil, :_read_] the index name or key pattern to use,
-    #   or +nil+ to clear a previously set hint. Called with no arguments acts as a
+    #   or `nil` to clear a previously set hint. Called with no arguments acts as a
     #   reader and returns the current hint value.
     # @return [String, nil, self]
     HINT_UNSET = :_hint_unset_ # @!visibility private
@@ -1029,7 +1048,7 @@ module Parse
     #  # parts of a single where constraint
     #  { :column.constraint => value }
     # @see Parse::Constraint
-    # @param conditions [Hash] a set of constraints for this query.
+    # @param expressions [Hash] a set of constraints for this query.
     # @param opts [Hash] a set of options when adding the constraints. This is
     #  specific for each Parse::Constraint.
     # @return [self]
@@ -1669,7 +1688,7 @@ module Parse
       _id _created_at _updated_at _acl
     ].freeze
 
-    # Recursively delete every key named in +names+ from a nested
+    # Recursively delete every key named in `names` from a nested
     # Hash/Array structure, in place. Symbol and string keys both match.
     # @param value [Object] a Hash, Array, or scalar
     # @param names [Set<String>] the key names to drop
@@ -2079,6 +2098,39 @@ module Parse
       end
     end
 
+    # Auth kwargs for the Atlas Search bridge (`#atlas_search` builder
+    # block). Explicit `atlas_search(...)` auth kwargs win; otherwise
+    # derive from the query's own scope (`#scope_to_user`, an explicit
+    # `session_token`, an ambient `Parse.with_session`, or `use_master_key`).
+    #
+    # Unlike {#mongo_direct_auth_kwargs} there is deliberately NO silent
+    # `{ master: true }` fallback for an unscoped query — we return `{}`
+    # so `Parse::AtlasSearch.search_with_stage` applies Atlas Search's own
+    # policy (`resolve_scope!`): public-only fallback, or `ACLRequired`
+    # when `Parse::AtlasSearch.require_session_token` is on. That keeps the
+    # search bridge fail-closed rather than defaulting an unscoped block
+    # search to a master-key ACL bypass.
+    # @return [Hash] zero-or-one-of { session_token:/master:/acl_user:/acl_role: }
+    # @!visibility private
+    def atlas_search_auth_kwargs(options)
+      explicit = %i[session_token master acl_user acl_role].select { |k| options.key?(k) }
+      return explicit.to_h { |k| [k, options[k]] } if explicit.any?
+
+      if @acl_user
+        { acl_user: @acl_user }
+      elsif @acl_role
+        { acl_role: @acl_role }
+      elsif @session_token.is_a?(String) && !@session_token.empty?
+        { session_token: @session_token }
+      elsif use_master_key == true
+        { master: true }
+      elsif (ambient = ambient_session_token)
+        { session_token: ambient }
+      else
+        {}
+      end
+    end
+
     # The fiber-local ambient session token set by `Parse.with_session`,
     # or nil. A whitespace-only ambient is treated as absent so it cannot
     # block the master fallback and then fail a later presence check —
@@ -2140,7 +2192,7 @@ module Parse
     #   instead of Parse::Object instances (default: false)
     # @param max_time_ms [Integer, nil] optional server-side time limit in milliseconds.
     #   When provided, MongoDB will cancel the aggregation if it exceeds this budget and
-    #   {Parse::MongoDB::ExecutionTimeout} is raised. Pass +nil+ (the default) for no cap.
+    #   {Parse::MongoDB::ExecutionTimeout} is raised. Pass `nil` (the default) for no cap.
     # @yield a block to iterate for each object that matched the query
     # @return [Array<Parse::Object>] if raw is false, a list of Parse::Object subclasses
     # @return [Array<Hash>] if raw is true, Parse-formatted JSON hashes
@@ -2180,7 +2232,7 @@ module Parse
 
       # Execute the aggregation directly on MongoDB. The pipeline was built
       # entirely from SDK constraint translation (no user-supplied stages),
-      # so legitimate +_rperm+/+_wperm+ references emitted by
+      # so legitimate `_rperm`/`_wperm` references emitted by
       # {#readable_by_role} and friends are sanctioned. The DENIED_OPERATORS
       # walk still runs at the MongoDB layer. When `session_token:` or
       # `master:` is supplied, Parse::MongoDB.aggregate adds the
@@ -2491,55 +2543,73 @@ module Parse
       skip_val = options[:skip] || (@skip > 0 ? @skip : 0)
 
       if block_given?
-        # Builder block mode
+        # Builder-block mode: the caller configures the $search stage
+        # directly via the yielded SearchBuilder. Route through
+        # Parse::AtlasSearch.search_with_stage so the SAME SDK-side
+        # enforcement chain as the options API runs — scope resolution,
+        # CLP `find`, the ACL $match placed AFTER $search (not prepended
+        # to stage 0), protectedFields/pointerFields redaction, and the
+        # $expr protected-field oracle guard on the caller filter.
+        #
+        # The previous implementation called Parse::MongoDB.aggregate
+        # with `allow_internal_fields: true` and NO auth forwarding: it
+        # both ran unscoped (resolved to :public / master, no ACL) and,
+        # because that helper prepends the ACL $match at position 0, was
+        # rejected outright by Atlas (which requires $search at stage 0).
+        # It was non-functional under both supported security configs.
         index_name = options[:index] || Parse::AtlasSearch.default_index
         builder = Parse::AtlasSearch::SearchBuilder.new(index_name: index_name)
         yield builder
 
-        # Build pipeline: $search must be first
-        pipeline = [builder.build]
-
-        # Add score projection
-        pipeline << { "$addFields" => { "_score" => { "$meta" => "searchScore" } } }
-
-        # Add existing query constraints as $match
+        # Carry the query's existing constraints as the caller filter,
+        # interpolated into a post-$search $match. The constraints MUST be
+        # converted to Mongo storage form first: `compile_where` yields the
+        # Parse REST shape (pointer keys like `owner`, values that are live
+        # Parse::Pointer objects / Parse date dicts). Fed to a `$match`
+        # verbatim, a Parse::Pointer fails BSON serialization and dates/ids
+        # target the wrong field (`owner` vs `_p_owner`). `convert_-
+        # constraints_for_direct_mongodb` rewrites keys/values to storage
+        # form — the same conversion the mongo-direct path applies, and the
+        # one the pre-5.5.5 block path used before this branch was rewritten.
+        filter = options[:filter]
         compiled_where = compile_where
         if compiled_where.present?
           regular_constraints = compiled_where.reject { |f, _| f == "__aggregation_pipeline" }
           if regular_constraints.any?
             mongo_constraints = convert_constraints_for_direct_mongodb(regular_constraints)
-            pipeline << { "$match" => mongo_constraints }
+            filter = (filter || {}).merge(mongo_constraints)
           end
         end
 
-        # Add sort, skip, limit
-        pipeline << { "$sort" => { "_score" => -1 } }
-        pipeline << { "$skip" => skip_val } if skip_val > 0
-        pipeline << { "$limit" => limit }
-
-        # SDK-built pipeline only — see results_direct for rationale.
-        raw_results = Parse::MongoDB.aggregate(@table, pipeline,
-                                               allow_internal_fields: true,
-                                               read_preference: @read_preference,
-                                             hint: @hint)
+        search_opts = {
+          filter: filter,
+          limit: limit,
+          skip: skip_val,
+          class_name: @table,
+          raw: options[:raw],
+          **atlas_search_auth_kwargs(options),
+        }
+        rp = options.key?(:read_preference) ? options[:read_preference] : @read_preference
+        search_opts[:read_preference] = rp unless rp.nil?
+        search_opts[:max_time_ms] = options[:max_time_ms] if options.key?(:max_time_ms)
 
-        # Convert results
-        if options[:raw]
-          Parse::AtlasSearch::SearchResult.new(results: raw_results, raw_results: raw_results)
-        else
-          parse_results = Parse::MongoDB.convert_documents_to_parse(raw_results, @table)
-          objects = parse_results.map { |doc| Parse.decode(doc) }.compact
-          Parse::AtlasSearch::SearchResult.new(results: objects, raw_results: raw_results)
-        end
+        Parse::AtlasSearch.search_with_stage(@table, builder.build, **search_opts)
       else
         # Simple options API - delegate to AtlasSearch module
         raise ArgumentError, "query string is required when not using a block" if query.nil?
 
-        # Merge query constraints as filter
+        # Merge query constraints as filter. Convert to Mongo storage form
+        # first (same reasoning as the block branch above): compile_where
+        # yields the Parse REST shape (live Parse::Pointer objects, Parse
+        # date dicts, un-prefixed pointer field names) which a raw $match
+        # cannot serialize / would target the wrong column.
         compiled_where = compile_where
         if compiled_where.present?
           regular_constraints = compiled_where.reject { |f, _| f == "__aggregation_pipeline" }
-          options[:filter] = (options[:filter] || {}).merge(regular_constraints) if regular_constraints.any?
+          if regular_constraints.any?
+            mongo_constraints = convert_constraints_for_direct_mongodb(regular_constraints)
+            options[:filter] = (options[:filter] || {}).merge(mongo_constraints)
+          end
         end
 
         options[:class_name] = @table
@@ -2596,11 +2666,17 @@ module Parse
           "Call Parse::AtlasSearch.configure(enabled: true) after configuring Parse::MongoDB."
       end
 
-      # Merge query constraints as filter
+      # Merge query constraints as filter, converted to Mongo storage form
+      # first (see #atlas_search for the reasoning — a raw Parse::Pointer
+      # fails BSON serialization and un-prefixed pointer fields target the
+      # wrong column).
       compiled_where = compile_where
       if compiled_where.present?
         regular_constraints = compiled_where.reject { |f, _| f == "__aggregation_pipeline" }
-        options[:filter] = (options[:filter] || {}).merge(regular_constraints) if regular_constraints.any?
+        if regular_constraints.any?
+          mongo_constraints = convert_constraints_for_direct_mongodb(regular_constraints)
+          options[:filter] = (options[:filter] || {}).merge(mongo_constraints)
+        end
       end
 
       # Use query limit if set and no explicit limit provided
@@ -5964,22 +6040,22 @@ module Parse
     # @param verbose [Boolean, nil] whether to print verbose output (nil means use query's setting)
     # @param mongo_direct [Boolean] if true, uses MongoDB directly bypassing Parse Server (required for $literal)
     # @param max_time_ms [Integer, nil] optional server-side time limit in milliseconds passed to
-    #   {Parse::MongoDB.aggregate} when mongo_direct is true. Pass +nil+ (the default) for no cap.
-    # @param raw_values [Boolean] when true, passes +rawValues: true+ to the Parse Server REST
+    #   {Parse::MongoDB.aggregate} when mongo_direct is true. Pass `nil` (the default) for no cap.
+    # @param raw_values [Boolean] when true, passes `rawValues: true` to the Parse Server REST
     #   aggregate endpoint (PS 9.9.0+). Has no effect on the mongo-direct path.
-    # @param raw_field_names [Boolean] when true, passes +rawFieldNames: true+ to the Parse Server
+    # @param raw_field_names [Boolean] when true, passes `rawFieldNames: true` to the Parse Server
     #   REST aggregate endpoint (PS 9.9.0+). Has no effect on the mongo-direct path.
     # @param allow_internal_fields [Boolean] when true, the mongo-direct path
-    #   forwards +allow_internal_fields: true+ to {Parse::MongoDB.aggregate} so
-    #   SDK-built ACL `$match` stages that legitimately reference +_rperm+ /
-    #   +_wperm+ (emitted by {Parse::Query#readable_by}, +#publicly_readable+,
+    #   forwards `allow_internal_fields: true` to {Parse::MongoDB.aggregate} so
+    #   SDK-built ACL `$match` stages that legitimately reference `_rperm` /
+    #   `_wperm` (emitted by {Parse::Query#readable_by}, `#publicly_readable`,
     #   and friends) pass the pipeline-security internal-fields denylist —
-    #   matching the parity already held by +results_direct+ / +count_direct+ /
-    #   +distinct_direct+. Set +true+ ONLY when this Aggregation's pipeline was
+    #   matching the parity already held by `results_direct` / `count_direct` /
+    #   `distinct_direct`. Set `true` ONLY when this Aggregation's pipeline was
     #   built entirely from SDK constraint translation (no caller-supplied
     #   stages); the credential-field guard (`_hashed_password`, session tokens,
-    #   auth data) is what +allow_internal_fields+ relaxes, so it must never be
-    #   set on a pipeline that interpolates user input. Defaults to +false+.
+    #   auth data) is what `allow_internal_fields` relaxes, so it must never be
+    #   set on a pipeline that interpolates user input. Defaults to `false`.
     def initialize(query, pipeline, verbose: nil, mongo_direct: false, max_time_ms: nil,
                    raw_values: false, raw_field_names: false, allow_internal_fields: false)
       @query = query
@@ -6041,7 +6117,7 @@ module Parse
 
     # Execute aggregation directly on MongoDB
     # @param max_time_ms [Integer, nil] optional server-side time limit (milliseconds).
-    #   Defaults to the value passed to {#initialize} via the +max_time_ms:+ keyword.
+    #   Defaults to the value passed to {#initialize} via the `max_time_ms:` keyword.
     # @return [Array<Hash>] raw MongoDB results
     def execute_direct!(max_time_ms: @max_time_ms)
       table = @query.instance_variable_get(:@table)

data/lib/parse/retrieval/reranker/cohere.rb

@@ -3,6 +3,7 @@
 
 require "json"
 require "uri"
+require "ipaddr"
 require_relative "../reranker"
 
 module Parse
@@ -197,10 +198,39 @@ module Parse
           unless uri.is_a?(URI::HTTPS) || uri.is_a?(URI::HTTP)
             raise ArgumentError, "Reranker::Cohere: base_url must be http(s) (got #{base_url.inspect})."
           end
+          # Never accept credentials embedded in the URL. They leak into
+          # logs / error messages / the Faraday connection, and userinfo
+          # can mask the real host (`https://evil@api.cohere.com/`).
+          unless uri.userinfo.nil?
+            raise ArgumentError,
+                  "Reranker::Cohere: base_url must not embed userinfo (credentials in the URL)."
+          end
+          # Plaintext http:// would send the Cohere API key in the clear.
+          # Permit it ONLY for loopback hosts (a local dev proxy / sidecar);
+          # require https:// for anything that leaves the machine. NB:
+          # URI::HTTPS is a subclass of URI::HTTP, so match on the scheme
+          # string, not `is_a?`.
+          if uri.scheme == "http" && !loopback_host?(uri.host)
+            raise ArgumentError,
+                  "Reranker::Cohere: base_url must be https:// for non-loopback hosts " \
+                  "(refusing to send the API key over plaintext http to #{uri.host.inspect})."
+          end
         rescue URI::InvalidURIError => e
           raise ArgumentError, "Reranker::Cohere: invalid base_url #{base_url.inspect} (#{e.message})."
         end
 
+        # @return [Boolean] true for localhost / 127.0.0.0/8 / ::1 etc.
+        def loopback_host?(host)
+          return false if host.nil? || host.empty?
+          h = host.downcase.sub(/\A\[/, "").sub(/\]\z/, "") # strip IPv6 brackets
+          return true if h == "localhost"
+          begin
+            IPAddr.new(h).loopback?
+          rescue IPAddr::Error
+            false
+          end
+        end
+
         def safe_base_host
           URI.parse(@base_url).host
         rescue StandardError

data/lib/parse/schema.rb

@@ -523,7 +523,7 @@ module Parse
       #   via the conventional accessor names some Parse-Stack models
       #   ship with), OR
       # - {Parse::Schema.default_class_level_permissions} if set, OR
-      # - +nil+ to leave `classLevelPermissions` off the schema body so
+      # - `nil` to leave `classLevelPermissions` off the schema body so
       #   Parse Server uses its built-in defaults.
       def model_class_level_permissions
         %i[class_level_permissions classLevelPermissions clp].each do |reader|

data/lib/parse/stack/version.rb

@@ -6,6 +6,6 @@ module Parse
   # The Parse Server SDK for Ruby
   module Stack
     # The current version.
-    VERSION = "5.5.3"
+    VERSION = "5.5.5"
   end
 end

data/lib/parse/stack.rb

@@ -44,14 +44,14 @@ module Parse
 
   # Fiber-local key consulted by the authentication middleware. A truthy
   # entry suppresses the master-key header for the duration of the block
-  # set by {Parse.without_master_key}; a +:enabled+ entry forces the
+  # set by {Parse.without_master_key}; a `:enabled` entry forces the
   # master-key header back on inside a nested {Parse.with_master_key}
   # block.
   MASTER_KEY_STATE_KEY = :__parse_master_key_state__
 
-  # Run +block+ with the master key suppressed for every Parse request
+  # Run `block` with the master key suppressed for every Parse request
   # originating in the current fiber. Equivalent to setting the
-  # +X-Disable-Parse-Master-Key+ header on each request, but block-scoped
+  # `X-Disable-Parse-Master-Key` header on each request, but block-scoped
   # so callers can wrap a unit of work — e.g. running an action "as if
   # the configured master key were not available" — without threading
   # the header through every intermediate call.
@@ -105,7 +105,7 @@ module Parse
   # the previous value on exit.
   SESSION_TOKEN_STATE_KEY = :__parse_session_token__
 
-  # Run +block+ with an ambient session token set for the current fiber.
+  # Run `block` with an ambient session token set for the current fiber.
   # Inside the block, every Parse request that doesn't explicitly pass
   # `session_token:` *and* doesn't explicitly request `use_master_key:
   # true` will be sent with this token. Equivalent to threading
@@ -140,8 +140,21 @@ module Parse
   def self.with_session(token)
     resolved = token.respond_to?(:session_token) ? token.session_token : token
     resolved = resolved.to_s if resolved
+    # Capture BEFORE any raise so the `ensure` always restores the real
+    # previous ambient (never clobbers an enclosing with_session).
     previous = Fiber[SESSION_TOKEN_STATE_KEY]
-    Fiber[SESSION_TOKEN_STATE_KEY] = (resolved && !resolved.empty?) ? resolved : nil
+    # SEC-02: a present-but-blank (empty or whitespace) token is an unusable
+    # credential. The prior behavior stored a whitespace token as the ambient
+    # (only an exactly-empty string was treated as absent), and the request
+    # layer would then drop it and silently send the master key. Reject blank
+    # tokens loudly at the source instead. `nil` still means "no ambient".
+    if resolved.is_a?(String) && resolved.strip.empty?
+      raise ArgumentError,
+        "Parse.with_session was given a blank session token. A present-but-empty " \
+        "token is refused so the block cannot silently execute with master-key " \
+        "authority — pass a valid session token, or `nil` for no ambient session."
+    end
+    Fiber[SESSION_TOKEN_STATE_KEY] = resolved
     yield
   ensure
     Fiber[SESSION_TOKEN_STATE_KEY] = previous
@@ -584,11 +597,11 @@ module Parse
   # nil, falls back to {Parse.cache}.
   #
   # SECURITY: if you pass a raw Moneta-Redis store, build it with
-  # +value_serializer: nil+. The lock release path reads the stored owner
-  # token back (+store[key]+) to compare-and-delete; with Moneta's default
-  # Marshal value serializer that read +Marshal.load+s bytes from Redis — an
+  # `value_serializer: nil`. The lock release path reads the stored owner
+  # token back (`store[key]`) to compare-and-delete; with Moneta's default
+  # Marshal value serializer that read `Marshal.load`s bytes from Redis — an
   # RCE vector on a shared/untrusted/MITM'd lock store. With
-  # +value_serializer: nil+ the owner token is a plain string and is never
+  # `value_serializer: nil` the owner token is a plain string and is never
   # deserialized. Alternatively pass a {Parse::Cache::Redis} instance, which
   # uses a raw-string acquire/release path and avoids Marshal entirely.
   # @example
@@ -600,7 +613,7 @@ module Parse
   # Optional allowlist of {Parse::Object} subclasses that may use the
   # synchronize-create lock. When set, calls from any other class raise
   # {Parse::CreateLockUnavailableError}. When nil (default) with the global
-  # default enabled, a one-time +[Parse::Stack:SECURITY]+ warning is emitted
+  # default enabled, a one-time `[Parse::Stack:SECURITY]` warning is emitted
   # noting the unbounded surface; the lock still applies to every class.
   #
   # **Inheritance behavior:** The allowlist check in

data/lib/parse/two_factor_auth/user_extension.rb

@@ -318,12 +318,12 @@ module Parse
         # CONFIRM the disable took effect from the SERVER's own view — a
         # positive post-condition rather than trusting the unlink response
         # alone. We must read the server directly here, NOT lean on the
-        # in-memory #mfa_enabled? projection: Parse Server omits +authData+
+        # in-memory #mfa_enabled? projection: Parse Server omits `authData`
         # entirely for a user with no providers, so once MFA is unlinked an
-        # ordinary fetch carries no +authData+ key at all and therefore can
-        # never clear the +{ mfa: { status: "enabled" } }+ value pinned at
+        # ordinary fetch carries no `authData` key at all and therefore can
+        # never clear the `{ mfa: { status: "enabled" } }` value pinned at
         # enrollment. An enabled account's own (session-token) read returns
-        # +authData.mfa+; a disabled one omits it — so an absent/mfa-less
+        # `authData.mfa`; a disabled one omits it — so an absent/mfa-less
         # authData on this trusted self-read is the authoritative signal.
         if mfa_enabled_on_server?
           raise MFA::VerificationError, "MFA disable did not take effect (still enabled after unlink)"
@@ -337,27 +337,27 @@ module Parse
       # verification entirely, so the caller must prove (out-of-band) that
       # the operator initiating the disable is authorized to do so.
       #
-      # The +authorized_by:+ keyword is required and must be a
+      # The `authorized_by:` keyword is required and must be a
       # {Parse::User} (or {Parse::Pointer} to a User) representing the
       # operator performing the override. The caller is responsible for
       # verifying that operator's privileges (e.g. via a role check). An
-      # optional +admin_role:+ argument lets this method enforce a role
+      # optional `admin_role:` argument lets this method enforce a role
       # membership check on the operator using the existing role-hierarchy
       # support; when given, the operator must belong to the role (or any
-      # of its child roles) or +ForbiddenError+ is raised.
+      # of its child roles) or `ForbiddenError` is raised.
       #
       # @param authorized_by [Parse::User, Parse::Pointer] the operator
       #   performing the override. Required.
       # @param admin_role [Parse::Role, String, nil] role (or role name)
-      #   that +authorized_by+ must belong to. Library-enforced. Either
-      #   this or +allow_unverified: true+ is REQUIRED (fail-closed).
+      #   that `authorized_by` must belong to. Library-enforced. Either
+      #   this or `allow_unverified: true` is REQUIRED (fail-closed).
       # @param allow_unverified [Boolean] explicitly accept caller-side
-      #   authorization without a library role check. Defaults to +false+;
-      #   must be set deliberately to bypass MFA without an +admin_role+.
+      #   authorization without a library role check. Defaults to `false`;
+      #   must be set deliberately to bypass MFA without an `admin_role`.
       # @return [Boolean] True if disabled successfully.
-      # @raise [ArgumentError] when +authorized_by:+ is missing or not a User.
-      # @raise [Parse::MFA::ForbiddenError] when neither +admin_role+ nor
-      #   +allow_unverified:+ is supplied, or when +admin_role+ is supplied
+      # @raise [ArgumentError] when `authorized_by:` is missing or not a User.
+      # @raise [Parse::MFA::ForbiddenError] when neither `admin_role` nor
+      #   `allow_unverified:` is supplied, or when `admin_role` is supplied
       #   and the operator is not a member.
       #
       # @example Library-enforced role check (preferred)
@@ -415,8 +415,8 @@ module Parse
         end
 
         # Refresh auth_data, then drop the in-memory MFA projection. As in
-        # #disable_mfa!, a disabled user's read omits +authData+, so the
-        # +{ mfa: { status: "enabled" } }+ value pinned at enrollment won't
+        # #disable_mfa!, a disabled user's read omits `authData`, so the
+        # `{ mfa: { status: "enabled" } }` value pinned at enrollment won't
         # self-clear on fetch — clear it explicitly so #mfa_enabled? reports
         # the truth after a master-key disable.
         fetch
@@ -426,7 +426,7 @@ module Parse
       end
 
       # @deprecated Use {#disable_mfa_master_key!} with an explicit
-      #   +authorized_by:+ argument. The old name had no authorization gate
+      #   `authorized_by:` argument. The old name had no authorization gate
       #   and acted as a one-call IDOR primitive when invoked on an
       #   attacker-controlled user instance.
       def disable_mfa_admin!(*args, **kwargs)
@@ -496,10 +496,10 @@ module Parse
 
       # @!visibility private
       # Authoritative server-side MFA check via a trusted self-read.
-      # Reads +authData.mfa+ straight from a fresh session-token fetch
+      # Reads `authData.mfa` straight from a fresh session-token fetch
       # rather than the (possibly stale) in-memory projection. An enabled
-      # account returns +authData.mfa+ with a +status+/+secret+; a disabled
-      # one omits +authData+ — so absence (or an mfa-less authData) means
+      # account returns `authData.mfa` with a `status`/`secret`; a disabled
+      # one omits `authData` — so absence (or an mfa-less authData) means
       # disabled.
       # @return [Boolean]
       def mfa_enabled_on_server?
@@ -512,13 +512,13 @@ module Parse
 
       # @!visibility private
       # Drop the in-memory MFA projection after a disable. A disabled user's
-      # server read omits +authData+ entirely, so an ordinary fetch can
-      # never clear the +{ mfa: { status: "enabled" } }+ value pinned at
-      # enrollment; do it explicitly here. Only the +mfa+ subkey is removed
+      # server read omits `authData` entirely, so an ordinary fetch can
+      # never clear the `{ mfa: { status: "enabled" } }` value pinned at
+      # enrollment; do it explicitly here. Only the `mfa` subkey is removed
       # (any anonymous/OAuth authData is preserved), and the assignment runs
-      # through the non-dirtying hydration path inside a +with_authdata_trust+
+      # through the non-dirtying hydration path inside a `with_authdata_trust`
       # scope so it is neither stripped nor marked dirty — a later #save will
-      # not resend +authData+.
+      # not resend `authData`.
       def clear_local_mfa_projection!
         cleared = auth_data.is_a?(Hash) ? auth_data.dup : {}
         cleared.delete("mfa")