parse-stack-next 5.8.1 → 5.8.2

data/lib/parse/client/batch.rb

@@ -1,10 +1,16 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require "openssl"
+require "securerandom"
 require_relative "request"
 require_relative "response"
 
 module Parse
+  # Declared here because this file loads before lib/parse/client.rb, which
+  # reopens it with the same superclass and defines its subclasses.
+  class Error < StandardError; end
+
   # Create a new batch operation.
   # @param reqs [Array<Parse::Request>] a set of requests to batch.
   # @return [BatchOperation] a new {BatchOperation} with the given change requests.
@@ -36,6 +42,50 @@ module Parse
   class BatchOperation
     include Enumerable
 
+    # Raised when a batch would send requests built for different
+    # credentials (a different client, an explicit session token, or an
+    # explicit `use_master_key:`) as one transaction. Parse Server runs every
+    # sub-request of a `POST /batch` under that call's own credentials, so a
+    # mixed transaction cannot honor each request's authority. Nothing is
+    # sent when this is raised.
+    class MixedAuthorityError < Parse::Error; end
+
+    # @!visibility private
+    # Per-process random key for {.credential_fingerprint}'s digests, so a
+    # fingerprint cannot be compared against a precomputed digest of a key.
+    FINGERPRINT_KEY = SecureRandom.bytes(32).freeze
+
+    # @!visibility private
+    # A comparable identity for the credentials a client sends: server URL,
+    # application id, and keyed digests (HMAC-SHA256 under a per-process
+    # random key) of the REST key, master key, and bound session token. Two
+    # client objects with the same configuration (for example a class client
+    # memoized before a second `Parse.setup`) have the same fingerprint and
+    # are batched together. The fingerprint never holds a secret.
+    #
+    # With `session_scoped: true` the master key and bound session token are
+    # left out: a request that names its own session token (or an explicit
+    # blank one) never sends the master key or the client's bound token, so
+    # those do not change its credentials.
+    # @note Only these settings are compared. Custom Faraday middleware or
+    #   headers added in a client's setup block are not part of the
+    #   fingerprint, so two clients that differ only there are treated as
+    #   the same credentials and their requests may be sent through either.
+    # @param c [Parse::Client]
+    # @param session_scoped [Boolean]
+    # @return [Array]
+    def self.credential_fingerprint(c, session_scoped: false)
+      return [:client, c.object_id] unless c.respond_to?(:application_id) && c.respond_to?(:server_url)
+      digest = lambda do |v|
+        v.nil? || v.to_s.empty? ? nil : OpenSSL::HMAC.hexdigest("SHA256", FINGERPRINT_KEY, v.to_s)
+      end
+      base = [c.server_url.to_s.sub(%r{/+\z}, ""), c.application_id.to_s,
+              digest.call(c.respond_to?(:api_key) ? c.api_key : nil)]
+      return base + [:session_scoped] if session_scoped
+      bound = c.respond_to?(:session_token) ? c.session_token : nil
+      base + [digest.call(c.respond_to?(:master_key) ? c.master_key : nil), digest.call(bound)]
+    end
+
     # Default number of threads used to dispatch batch segments concurrently.
     # Raise via `Parse::BatchOperation.parallelism = N` (or pass `parallelism:`
     # to `#submit`) for higher throughput on bulk writes; 2 is intentionally
@@ -60,11 +110,38 @@ module Parse
     #  @return [Boolean] whether this batch should be executed as a transaction.
     attr_accessor :requests, :responses, :transaction
 
-    # @return [Parse::Client] the client to be used for the request.
+    # @return [Parse::Client] the client used for requests that were not
+    #   built for a specific client. In a batch with no client set
+    #   explicitly, requests built from an object
+    #   ({Parse::Object#change_requests}, {Parse::Object#destroy_request})
+    #   carry their class's client and are sent through it.
     def client
       @client ||= Parse::Client.client
     end
 
+    # Set the client every request in this batch is sent through. An
+    # explicitly chosen client wins over the class client a request was
+    # built for, as {Parse::Client#request} ignores it for a single request;
+    # each request's own `session_token:` / `use_master_key:` options and
+    # headers still apply.
+    # @param c [Parse::Client]
+    def client=(c)
+      @client = c
+      @explicit_client = !c.nil?
+    end
+
+    # @!visibility private
+    # Credentials (`session_token:`, `use_master_key:`) applied to requests
+    # that name none of their own. Set by {Parse::API::Batch#batch_request}
+    # when it routes a mixed batch through {#submit}.
+    # @return [Hash]
+    def batch_defaults
+      @batch_defaults || {}
+    end
+
+    # @!visibility private
+    attr_writer :batch_defaults
+
     # @param reqs [Array<Parse::Request>] an array of requests.
     # @param transaction [Boolean] whether to execute as a transaction.
     def initialize(reqs = nil, transaction: false)
@@ -185,22 +262,48 @@ module Parse
       failure = nil
       return @responses if @requests.empty?
 
+      # Parse Server runs every sub-request under the credentials of the one
+      # `POST /batch` call, so requests built for different credentials are
+      # sent as separate calls, each with its own client and options. This
+      # is decided before anything is sent.
+      groups = authority_groups(client, batch_defaults, force_client: @explicit_client)
+
       if @transaction
+        if groups.size > 1
+          raise MixedAuthorityError,
+                "A transaction cannot mix requests built for different credentials " \
+                "(#{groups.size} distinct clients or session/master-key options). Parse Server " \
+                "runs a batch under one credential, so it cannot honor each request's own. " \
+                "Save these objects in separate transactions."
+        end
+        group = groups.first
         # One request, one transaction. Exceptions propagate unchanged so the
         # caller can roll back its local state.
-        @responses = align_responses(@requests, client.batch_request(self))
+        result = group[:client].batch_request(self, **group[:opts])
+        @responses = align_responses(@requests, result)
       else
         segment = 50 if segment.nil? || segment < 1
         parallelism = 1 if parallelism.nil? || parallelism < 1
-        slices = @requests.each_slice(segment).to_a
+        # Each slice holds requests of one authority group, with their
+        # positions in the batch, so responses go back in request order.
+        slices = groups.flat_map do |g|
+          g[:entries].each_slice(segment).map { |entries| [g, entries] }
+        end
         outcomes = slices.threaded_map(parallelism) do |slice|
+          g, entries = slice
+          reqs = entries.map(&:last)
           begin
-            [align_responses(slice, client.batch_request(BatchOperation.new(slice))), nil]
+            chunk = BatchOperation.new
+            chunk.requests = reqs
+            [entries, align_responses(reqs, g[:client].batch_request(chunk, **g[:opts])), nil]
           rescue StandardError => e
-            [Array.new(slice.size) { exception_response(e) }, e]
+            [entries, Array.new(reqs.size) { exception_response(e) }, e]
           end
         end
-        @responses = outcomes.flat_map(&:first)
+        @responses = Array.new(@requests.size)
+        outcomes.each do |entries, responses, _error|
+          entries.each_with_index { |(index, _req), i| @responses[index] = responses[i] }
+        end
         failure = outcomes.map(&:last).compact.first
       end
 
@@ -213,6 +316,93 @@ module Parse
 
     private
 
+    # Group the requests by the credentials they would have as single
+    # requests: the client (a request's own class client in an implicit
+    # batch, else this batch's), plus the request's session token,
+    # `use_master_key:`, and master-key suppression from
+    # {Parse::Request#explicit_authority}. Requests with no explicit
+    # authority on this batch's client form one group sent with no extra
+    # options, so an ambient `Parse.with_session`, `Parse.client_mode`, or
+    # `Parse.without_master_key` applies exactly as it does to a single
+    # request.
+    #
+    # `default_opts` (call options from {Parse::API::Batch#batch_request})
+    # apply to a request that names no credentials of its own. Narrowing
+    # call options always win: `use_master_key: false` and master-key
+    # suppression from the call override a request's own
+    # `use_master_key: true`. A call option never widens a request.
+    # @param default_client [Parse::Client] client for requests built for
+    #   none, and for every request when `force_client` is true.
+    # @param default_opts [Hash] `session_token:` / `use_master_key:` /
+    #   `suppress_master_key:` call options.
+    # @param force_client [Boolean] send every request through
+    #   `default_client` (the caller chose the client explicitly).
+    # @return [Array<Hash>] groups in first-appearance order, each with
+    #   `:client`, `:opts`, and `:entries` (`[index, request]` pairs).
+    # @!visibility private
+    def authority_groups(default_client = client, default_opts = batch_defaults, force_client: false)
+      defaults = default_opts.is_a?(Hash) ? default_opts : {}
+      default_token = self.class.resolve_session_option(defaults, :session_token)
+      fingerprints = {}
+      fingerprint = lambda do |c, scoped|
+        fingerprints[[c.object_id, scoped]] ||= self.class.credential_fingerprint(c, session_scoped: scoped)
+      end
+      groups = {}
+      @requests.each_with_index do |req, index|
+        target = if force_client
+            default_client
+          elsif req.respond_to?(:client) && req.client
+            req.client
+          else
+            default_client
+          end
+        # Credentials resolve as they do for a single request: options, then
+        # the session-token and master-key-suppression headers.
+        named = req.respond_to?(:explicit_authority) ? req.explicit_authority : {}
+        token = named.key?(:session_token) ? named[:session_token] : default_token
+        master = named.key?(:use_master_key) ? named[:use_master_key] : defaults[:use_master_key]
+        master = nil unless master == true || master == false
+        # Narrowing call options win over a request's own master opt-in.
+        master = false if defaults[:use_master_key] == false
+        suppress = named[:suppress_master_key] == true || defaults[:suppress_master_key] == true
+        key = [fingerprint.call(target, !token.nil?), token, master, suppress]
+        existing = groups[key]
+        if existing && !existing[:client].equal?(default_client) && target.equal?(default_client)
+          # Same credentials as an earlier client object: send through the
+          # batch's own client.
+          existing[:client] = default_client
+        end
+        group = groups[key] ||= begin
+            call_opts = {}
+            call_opts[:session_token] = token unless token.nil?
+            call_opts[:use_master_key] = master unless master.nil?
+            call_opts[:suppress_master_key] = true if suppress
+            { client: target, opts: call_opts, entries: [] }
+          end
+        group[:entries] << [index, req]
+      end
+      groups.values
+    end
+
+    # @!visibility private
+    # The session token named under `key` in `opts`, resolved the way
+    # {Parse::Client#request} resolves it: a user object yields its token,
+    # and a value that is present but resolves to nil or blank becomes `""`
+    # so the explicit-blank branch fails closed (no master key, no ambient
+    # or bound token). nil when the option is absent or literally nil.
+    # @param opts [Hash]
+    # @param key [Symbol]
+    # @return [String, nil]
+    def self.resolve_session_option(opts, key)
+      return nil unless opts.is_a?(Hash)
+      raw = opts[key]
+      return nil if raw.nil?
+      token = raw.respond_to?(:session_token) ? raw.session_token : raw
+      return "" if token.nil?
+      token = token.to_s
+      token.strip.empty? ? "" : token
+    end
+
     # Whether `req` repeats a request already in the batch for the same
     # tagged object.
     def duplicate_object_request?(req)
@@ -275,10 +465,15 @@ class Array
   #  author = Author.first
   #  posts = Post.all author: author
   #  posts.destroy # batch destroy request
+  # @param session [String, #session_token, nil] send every delete as this
+  #   user (ACL and CLP enforced) instead of each object's client default.
   # @return [Parse::BatchOperation] the batch operation performed.
   # @raise ArgumentError if the array is not empty and holds no Parse objects.
+  # @raise Parse::BatchOperation::MixedAuthorityError never for a destroy;
+  #   objects bound to different clients are deleted in separate calls.
   # @see Parse::BatchOperation
-  def destroy
+  def destroy(session: nil)
+    token = Parse::BatchOperation.session_token_for!(session)
     targets = select { |o| o.respond_to?(:destroy_request) }
     if targets.empty? && !empty?
       raise ArgumentError, "Array#destroy requires Parse::Object elements; " \
@@ -287,8 +482,8 @@ class Array
     # A session deleted from a pointer or a partial fetch carries no token or
     # owner to drop from the identity cache; look them up first, in one
     # query per client.
-    Parse::Session.send(:_preload_identity_for_destroy!, targets) if defined?(Parse::Session)
-    _destroy_batch(targets)
+    Parse::Session.send(:_preload_identity_for_destroy!, targets, session_token: token) if defined?(Parse::Session)
+    _destroy_batch(targets, token)
   ensure
     # A looked-up session token is a live credential; never leave it on an
     # object whose delete was skipped or whose batch raised.
@@ -296,13 +491,14 @@ class Array
   end
 
   # @!visibility private
-  def _destroy_batch(targets)
+  def _destroy_batch(targets, token = nil)
     batch = Parse::BatchOperation.new
     objects = {}
     targets.each do |o|
       next if objects.key?(o.object_id)
       r = o.destroy_request
       next if r.nil?
+      r.opts[:session_token] = token if token
       objects[o.object_id] = o
       batch.add(r)
     end
@@ -356,16 +552,22 @@ class Array
   #  objects back to the original ones submitted. If you don't need the original objects
   #  to be updated with the changes, set this to false for improved performance.
   # @param force [Boolean] Do not skip objects that do not have pending changes (dirty tracking).
+  # @param session [String, #session_token, nil] send every write as this
+  #   user (ACL and CLP enforced) instead of each object's client default.
   # @example
   #  # assume Post and Author are Parse models
   #  author = Author.first
   #  posts = Post.first 100
   #  posts.each { |post| post.author = author }
   #  posts.save # batch save
+  # @note Each write is sent with the credentials of its object's class
+  #  client, as a single {Parse::Object#save} is. Objects bound to different
+  #  clients are saved in separate batch calls.
   # @return [Parse::BatchOperation] the batch operation performed.
   # @raise ArgumentError if the array is not empty and holds no Parse objects.
   # @see Parse::BatchOperation
-  def save(merge: true, force: false)
+  def save(merge: true, force: false, session: nil)
+    token = Parse::BatchOperation.session_token_for!(session)
     targets = select { |o| o.is_a?(Parse::Object) }
     if targets.empty? && !empty?
       raise ArgumentError, "Array#save requires Parse::Object elements; " \
@@ -376,7 +578,9 @@ class Array
     targets.each do |o|
       next if objects.key?(o.object_id)
       objects[o.object_id] = o
-      batch.add o.change_requests(force)
+      reqs = o.change_requests(force)
+      reqs.each { |r| r.opts[:session_token] = token } if token
+      batch.add reqs
     end
     if merge == false
       batch.submit
@@ -400,6 +604,21 @@ end
 
 module Parse
   class BatchOperation
+    # @!visibility private
+    # The session token named by a `session:` argument, or nil when none was
+    # given. A blank token is refused rather than treated as "no session".
+    # @param session [String, #session_token, nil]
+    # @return [String, nil]
+    # @raise ArgumentError for a blank or unusable session.
+    def self.session_token_for!(session)
+      return nil if session.nil?
+      token = session.respond_to?(:session_token) ? session.session_token : session
+      unless token.is_a?(String) && !token.strip.empty?
+        raise ArgumentError, "session: must be a session token or a user with one"
+      end
+      token
+    end
+
     # @!visibility private
     # Apply the batch responses for one object's requests to that object.
     # @param obj [Parse::Object] the object that was saved.

data/lib/parse/client/body_builder.rb

@@ -36,12 +36,41 @@ module Parse
       # Maximum url length for most server requests before HTTP Method Override is used.
       MAX_URL_LENGTH = 2_000.freeze
       # Fields that should be redacted from log output.
+      #
+      # Covers MFA material (`recovery` codes and the `secret` returned by
+      # MFA enrollment, also under `authDataResponse`) and the storage-form
+      # credential columns a raw MongoDB document carries (`_session_token`,
+      # `_hashed_password`, and the reset/verify tokens). Keys starting with
+      # {SENSITIVE_KEY_PREFIXES} (per-provider `_auth_data_<provider>`
+      # columns) are redacted too.
       SENSITIVE_FIELDS = %w[
         password token sessionToken session_token access_token authData
         masterKey master_key apiKey api_key clientKey client_key
         javascriptKey javascript_key refreshToken refresh_token
+        recovery recoveryCodes recovery_codes authDataResponse secret
+        _session_token _hashed_password _email_verify_token
+        _perishable_token _password_history
+      ].freeze
+      # Key prefixes whose values are always redacted.
+      SENSITIVE_KEY_PREFIXES = %w[_auth_data_].freeze
+      # A credential value: a double- or single-quoted string (with escapes),
+      # taken whole so a quoted value with spaces is redacted entirely, or an
+      # unquoted run up to a delimiter.
+      SENSITIVE_VALUE = /(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^"'&\s,}\]]+)/
+      SENSITIVE_PATTERN = /(#{(SENSITIVE_FIELDS + SENSITIVE_KEY_PREFIXES.map { |p| "#{p}\\w+" }).join("|")})(["']?\s*[=:>]\s*)(#{SENSITIVE_VALUE.source})/i
+      # Credential header names whose value is redacted when they appear as
+      # text (`X-Parse-Master-Key: mk`, `Authorization: Bearer x`), for
+      # example in an error message or a pasted request. Real request
+      # headers are redacted through {REDACTED_HEADERS}.
+      SENSITIVE_HEADER_NAMES = %w[
+        X-Parse-Master-Key X-Parse-REST-API-Key X-Parse-Session-Token
+        X-Parse-Javascript-Key X-Parse-Client-Key X-Parse-Webhook-Key
+        Authorization
       ].freeze
-      SENSITIVE_PATTERN = /(#{SENSITIVE_FIELDS.join("|")})(["']?\s*[=:>]\s*["']?)([^"&\s,}\]]+)/i
+      # Header-shaped text: a credential header name, a `:` or `=`
+      # separator, an optional auth scheme (`Bearer`, `Basic`, `Token`),
+      # then the value.
+      SENSITIVE_HEADER_PATTERN = /(#{SENSITIVE_HEADER_NAMES.map { |n| Regexp.escape(n) }.join("|")})(["']?\s*[=:]\s*)((?:bearer|basic|token)\s+)?(#{SENSITIVE_VALUE.source})/i
       # Lookup set of sensitive field names for structural (JSON) redaction
       # — case-insensitive match on the key, not the value. Walks the parsed
       # structure so nested objects like {"password":{"nested":"value"}}
@@ -139,32 +168,81 @@ module Parse
       def self.redact(str)
         s = str.to_s
         return s if s.empty?
-        after_structural = s
         if (parsed = try_parse_json(s))
           scrubbed = scrub_sensitive!(parsed)
           compact_vectors!(scrubbed)
           begin
-            after_structural = scrubbed.to_json
+            # Text patterns run on each string value before encoding, never
+            # on the encoded JSON: escaped quotes inside a value
+            # (`password=\"x\"`) would defeat them and could corrupt the JSON.
+            return redact_string_values!(scrubbed).to_json
           rescue StandardError
-            after_structural = s
+            # Fall through to the text pass on the original string.
           end
         end
-        after_structural.gsub(SENSITIVE_PATTERN) do
+        redact_patterns(s)
+      end
+
+      # Apply {redact_patterns} to every String value in a parsed JSON
+      # structure, in place. Keys are left alone (the structural pass already
+      # replaced the values of sensitive keys).
+      # @param obj [Object] a parsed JSON value.
+      # @return [Object] obj.
+      def self.redact_string_values!(obj)
+        case obj
+        when Hash
+          obj.each { |k, v| obj[k] = v.is_a?(String) ? redact_patterns(v) : redact_string_values!(v) }
+        when Array
+          obj.map! { |v| v.is_a?(String) ? redact_patterns(v) : redact_string_values!(v) }
+        end
+        obj
+      end
+
+      # The regex pass of {redact} on its own: replaces values that follow
+      # a credential field name (`password=x`, `"sessionToken":"r:x"`) or a
+      # credential header name (`X-Parse-Master-Key: mk`,
+      # `Authorization: Bearer x`). Use it on text that is not JSON, or on
+      # JSON that has already been scrubbed structurally.
+      # @param str [String]
+      # @return [String]
+      def self.redact_patterns(str)
+        s = str.to_s
+        return s if s.empty?
+        s = s.gsub(SENSITIVE_PATTERN) do
           key_part = $1
           sep_part = $2
           val_part = $3
-          # Skip values that the structural pass already redacted —
-          # otherwise the regex value-class `[^"&\s,}\]]+` stops at the
-          # bracket and we end up with `[FILTERED]]` from the trailing
-          # close-bracket left over from `"[FILTERED]"`.
-          if val_part == "[FILTERED" || val_part == REDACTED_PLACEHOLDER
-            "#{key_part}#{sep_part}#{val_part}"
-          else
-            "#{key_part}#{sep_part}#{REDACTED_PLACEHOLDER}"
-          end
+          # Skip values that the structural pass already redacted. The
+          # value class `[^"&\s,}\]]+` stops at the bracket, so without
+          # this a second pass would turn `"[FILTERED]"` into
+          # `[FILTERED]]`.
+          "#{key_part}#{sep_part}#{redacted_value(val_part)}"
+        end
+        s.gsub(SENSITIVE_HEADER_PATTERN) do
+          name_part = $1
+          sep_part = $2
+          scheme_part = $3
+          val_part = $4
+          "#{name_part}#{sep_part}#{scheme_part}#{redacted_value(val_part)}"
         end
       end
 
+      # @!visibility private
+      def self.already_redacted?(value)
+        value == "[FILTERED" || value == REDACTED_PLACEHOLDER
+      end
+
+      # @!visibility private
+      # The placeholder for a matched value, keeping the value's own quotes
+      # so quoted text (and JSON) stays well formed. A value that is already
+      # the placeholder is left as is.
+      def self.redacted_value(value)
+        quote = value[0] if value.length >= 2 && (value[0] == '"' || value[0] == "'") && value[-1] == value[0]
+        inner = quote ? value[1..-2] : value
+        return value if already_redacted?(inner)
+        quote ? "#{quote}#{REDACTED_PLACEHOLDER}#{quote}" : REDACTED_PLACEHOLDER
+      end
+
       # @!visibility private
       def self.try_parse_json(str)
         # Find first non-whitespace byte; allow leading whitespace and BOM.
@@ -178,6 +256,13 @@ module Parse
         nil
       end
 
+      # Whether a JSON key names a credential whose value must be redacted.
+      # @!visibility private
+      def self.sensitive_key?(key)
+        k = key.to_s.downcase
+        SENSITIVE_FIELDS_SET.include?(k) || SENSITIVE_KEY_PREFIXES.any? { |p| k.start_with?(p) }
+      end
+
       # @!visibility private
       # Recursively walks a parsed JSON structure replacing values under any
       # sensitive key with the redaction placeholder. Returns the same node
@@ -190,7 +275,7 @@ module Parse
         case node
         when Hash
           node.each do |key, value|
-            if key.is_a?(String) && SENSITIVE_FIELDS_SET.include?(key.downcase)
+            if key.is_a?(String) && sensitive_key?(key)
               node[key] = REDACTED_PLACEHOLDER
             elsif value.is_a?(Hash) || value.is_a?(Array)
               scrub_sensitive!(value)

data/lib/parse/client/caching.rb

@@ -73,6 +73,31 @@ module Parse
         # @return [Boolean] whether the logging should be enabled.
         attr_accessor :logging
 
+        # @!attribute cache_session_requests
+        # Whether reads made with a session token are cached. Off by default.
+        #
+        # A cached session read is answered without contacting Parse Server,
+        # so it cannot notice that the session was revoked (logout,
+        # {Parse::Session#destroy}, `logout_all!`, a password change) or that
+        # the user lost a role or row access through a change the SDK did not
+        # make. With this off, every session read reaches Parse Server, which
+        # checks the token and the current ACLs and CLPs each time. Master-key
+        # and anonymous reads are cached as before. Turning this on trades that
+        # guarantee for speed: a revoked or narrowed session keeps reading its
+        # cached responses until they expire.
+        #
+        # Only `true` enables it; any other value (including the String
+        # `"true"` read from an environment variable) leaves session reads
+        # uncached. A client can override this default with
+        # `Parse.setup(cache_session_requests: true)` (the middleware option
+        # of the same name).
+        # @return [Boolean]
+        attr_writer :cache_session_requests
+
+        def cache_session_requests
+          @cache_session_requests == true
+        end
+
         def enabled
           @enabled = true if @enabled.nil?
           @enabled
@@ -107,6 +132,10 @@ module Parse
         @opts = { expires: 0 }
         @opts.merge!(opts) if opts.is_a?(Hash)
         @expires = @opts[:expires]
+        # Per-middleware override of {.cache_session_requests}; nil defers to
+        # the class-level default.
+        @cache_session_requests =
+          @opts.key?(:cache_session_requests) ? (@opts[:cache_session_requests] == true) : nil
         # Optional cache key namespace so two Parse apps sharing one Redis don't
         # collide (e.g. `mk:/classes/Song/abc` is the same path for both apps).
         # When set, keys become `<namespace>:<existing-prefix>:<url>`. Empty
@@ -186,6 +215,20 @@ module Parse
         # time a long query ran.
         return @app.call(env) if method != :get && @request_headers[METHOD_OVERRIDE].to_s.casecmp?("GET")
 
+        # A session read is never read from or stored in the cache unless the
+        # application opted in (see {.cache_session_requests}): a cached answer
+        # would keep serving a revoked or narrowed session until it expired.
+        # The token header is set by the request layer from the effective
+        # session (an explicit `session_token:`, `Parse.with_session`, or a
+        # session-bound client), so this one check covers all three. Writes
+        # made with a session still run the invalidation below.
+        # Read the ambient cache tenant first so the bypass event carries it.
+        @cache_tenant = Parse.respond_to?(:current_cache_tenant) ? Parse.current_cache_tenant : nil
+        if method == :get && @request_headers.key?(SESSION_TOKEN) && !cache_session_requests?
+          instrument_cache(:bypass, method: method, url_path: url.path, reason: :session)
+          return @app.call(env)
+        end
+
         @cache_key = url.to_s
 
         # Auth discriminator. A master-key request bypasses ACL, CLP and
@@ -232,7 +275,6 @@ module Parse
         # and from `mk:`, so legacy cache entries written before the
         # tenant feature don't accidentally re-hydrate into a tenanted
         # request and vice versa.
-        @cache_tenant = Parse.respond_to?(:current_cache_tenant) ? Parse.current_cache_tenant : nil
         if @cache_tenant
           @cache_key = "T:#{@cache_tenant}:#{@cache_key}"
           @old_shape_key = "T:#{@cache_tenant}:#{@old_shape_key}"
@@ -438,8 +480,9 @@ module Parse
       # Emit an ActiveSupport::Notifications event under the `parse.cache.*`
       # namespace.
       #
-      # **Payload shape (stable):** `{ event:, namespace:, method:, url_path:,
-      # [reason:], [duration_ms:], [error:] }`.
+      # **Payload shape (stable):** `{ event:, namespace:, cache_tenant:,
+      # method:, url_path:, [reason:], [duration_ms:], [error:] }`.
+      # `cache_tenant` is the active `Parse.with_cache_tenant` value, or nil.
       #
       # **Security invariants:**
       # - The cache key is NEVER emitted. The key contains a hashed
@@ -472,6 +515,13 @@ module Parse
         ActiveSupport::Notifications.instrument("parse.cache.#{event}", payload)
       end
 
+      # Whether this middleware caches session reads: its own
+      # `cache_session_requests:` option when given, else the class default.
+      # @!visibility private
+      def cache_session_requests?
+        @cache_session_requests.nil? ? self.class.cache_session_requests : @cache_session_requests
+      end
+
       # Delete the canonical cache_key plus its legacy un-namespaced and
       # master-key-prefixed variants. Called on both GET misses (defensive
       # cleanup of stale pre-namespace entries) and non-GET writes (cache

data/lib/parse/client/request.rb

@@ -41,6 +41,65 @@ module Parse
     # Used to correlate batching requests with their responses.
     attr_accessor :tag
 
+    # @!visibility private
+    # The client this request belongs to, when it was built for a specific
+    # one (an object's class client). A {Parse::BatchOperation} sends a
+    # request through this client, so a write built for a session-bound
+    # client is never batched through another client's credentials. nil
+    # means the batch's own client.
+    attr_accessor :client
+
+    # @!visibility private
+    # The credentials this request names explicitly, resolved the way
+    # {Parse::Client#request} resolves them for a single request: the
+    # `session_token:` option, else an `X-Parse-Session-Token` header; and
+    # the `use_master_key:` option; and `suppress_master_key: true` when the
+    # master-key suppression header is set. A key is absent when the request
+    # does not name it, so ambient context (`Parse.with_session`,
+    # `client_mode`, a bound client token) still applies.
+    #
+    # A `session_token:` option that is present but resolves to no token (a
+    # user object without one, or a blank string) is returned as `""`, so a
+    # batch fails closed the same way a single request does: no master key
+    # and no ambient or bound token. `use_master_key:` is returned only when
+    # it is exactly `true` or `false`; {Parse::Client#request} treats any
+    # other value as not set, and so does a batch.
+    # @return [Hash] with optional `:session_token` (String),
+    #   `:use_master_key` (Boolean), and `:suppress_master_key` (true) keys.
+    def explicit_authority
+      o = opts.is_a?(Hash) ? opts : {}
+      result = {}
+      token = Parse::BatchOperation.resolve_session_option(o, :session_token)
+      if token.nil?
+        header_token = self.class.header_value(headers, Parse::Protocol::SESSION_TOKEN)
+        if header_token.is_a?(String)
+          token = header_token.strip.empty? ? "" : header_token
+        end
+      end
+      result[:session_token] = token unless token.nil?
+      master = o[:use_master_key]
+      result[:use_master_key] = master if master == true || master == false
+      # The suppression header wins over `use_master_key: true` in the
+      # authentication middleware, so a batch must carry it as a header
+      # rather than fold it into `use_master_key:` (which would also change
+      # how the ambient and bound session tokens apply).
+      if self.class.header_value(headers, Parse::Middleware::Authentication::DISABLE_MASTER_KEY).present?
+        result[:suppress_master_key] = true
+      end
+      result
+    end
+
+    # @!visibility private
+    # Case-insensitive header lookup.
+    # @return [Object, nil]
+    def self.header_value(headers, name)
+      return nil unless headers.is_a?(Hash)
+      return headers[name] if headers.key?(name)
+      wanted = name.to_s.downcase
+      headers.each { |k, v| return v if k.to_s.downcase == wanted }
+      nil
+    end
+
     # @!attribute [rw] request_id
     #   @return [String] unique identifier for this request to enable idempotency
     attr_accessor :request_id