parse-stack-next 5.2.0 → 5.3.0

data/Rakefile

@@ -35,6 +35,54 @@ def mcp_credentials_or_abort!
   [server_url, app_id, rest_api_key, master_key]
 end
 
+# Resolve the identity for `rake client:console`. Returns a session-token String,
+# or nil to mean "anonymous" (no token, no master). Order: PARSE_SESSION_TOKEN,
+# PARSE_CLIENT_ANONYMOUS=true, PARSE_LOGIN_USER (+PARSE_LOGIN_PASSWORD), else
+# prompt for login / token / anon. The login path uses the configured default
+# client (the master client set up just before this is called).
+def client_console_token!
+  token = ENV["PARSE_SESSION_TOKEN"].to_s.strip
+  return token unless token.empty?
+  return nil if ENV["PARSE_CLIENT_ANONYMOUS"].to_s == "true"
+
+  user = ENV["PARSE_LOGIN_USER"].to_s.strip
+  if user.empty?
+    print "Identity? [login/token/anon] (login): "
+    case $stdin.gets.to_s.strip.downcase
+    when "anon", "anonymous" then return nil
+    when "token"
+      print "Session token (r:...): "
+      t = $stdin.gets.to_s.strip
+      return t.empty? ? nil : t
+    else
+      print "Username (blank for anonymous): "
+      user = $stdin.gets.to_s.strip
+      return nil if user.empty?
+    end
+  end
+
+  pwd = ENV["PARSE_LOGIN_PASSWORD"].to_s
+  if pwd.empty?
+    begin
+      require "io/console"
+      print "Password for #{user}: "
+      pwd = $stdin.noecho(&:gets).to_s
+      puts
+    rescue LoadError, IOError, SystemCallError
+      # io/console missing, or stdin is not a TTY (piped input raises
+      # Errno::ENOTTY, a SystemCallError — not an IOError). Fall back to a
+      # plain read; warn that it will echo.
+      warn "[client:console] WARNING: cannot disable echo; password will be visible."
+      print "Password for #{user}: "
+      pwd = $stdin.gets.to_s
+    end
+  end
+  u = Parse::User.login(user, pwd.chomp)
+  abort "[client:console] login failed for #{user.inspect}" if u.nil? || u.session_token.to_s.empty?
+  puts "Logged in as #{u.username} (#{u.id})."
+  u.session_token
+end
+
 # Default test task runs all tests with Docker enabled.
 #
 # `*disruptive*` tests are EXCLUDED here: they stop/restart the shared
@@ -48,55 +96,92 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
+# Shared runner for the file-per-process test tasks. Each test file runs in its
+# own Ruby process (isolation against the shared Parse Server); output streams
+# live, and — for trackability — a PASS/FAIL + duration line per file is printed
+# to STDOUT *and* appended to a progress log you can `tail -f` from another
+# shell while the run is in flight (works even when the run is backgrounded or
+# piped, where STDOUT would otherwise buffer until completion).
+#
+# Env knobs:
+#   TEST_PATTERN=<substr>       run only files whose path includes <substr>
+#                               (e.g. TEST_PATTERN=webhook)
+#   CONTINUE_ON_FAILURE=false   stop at the first failing file
+#                               (default: run them all, then list every failure)
+#
+# Exits non-zero if any file failed.
+def run_test_files!(label, files, log:)
+  $stdout.sync = true
+  require "fileutils"
+  if (pattern = ENV["TEST_PATTERN"].to_s).length.positive?
+    files = files.select { |f| f.include?(pattern) }
+    puts "TEST_PATTERN=#{pattern} -> #{files.length} matching file(s)"
+  end
+  continue = ENV.fetch("CONTINUE_ON_FAILURE", "true") != "false"
+  FileUtils.mkdir_p(File.dirname(log))
+  total = files.length
+  started = Time.now
+  results = []
+  File.write(log, "#{label}: #{total} files, started #{started}\n")
+  puts "\n>> #{label}: #{total} files (progress log: #{log})"
+
+  files.each_with_index do |file, i|
+    n = i + 1
+    puts "\n" + "=" * 80
+    puts "[#{n}/#{total}] #{file}"
+    puts "=" * 80
+    t0 = Time.now
+    ok = system("PARSE_TEST_USE_DOCKER=true ruby -Ilib:test #{file}")
+    dt = Time.now - t0
+    results << [file, ok, dt]
+    summary = format("[%d/%d] %-4s %7.1fs  %s", n, total, ok ? "PASS" : "FAIL", dt, file)
+    puts summary
+    File.open(log, "a") { |f| f.puts summary }
+    if !ok && !continue
+      File.open(log, "a") { |f| f.puts "STOPPED at first failure (CONTINUE_ON_FAILURE=false)" }
+      break
+    end
+  end
+
+  elapsed = Time.now - started
+  passed = results.count { |_, ok, _| ok }
+  failed = results.reject { |_, ok, _| ok }
+  footer = format("%s: %d/%d passed in %.1fs (%.1f min)",
+                  label, passed, results.length, elapsed, elapsed / 60.0)
+  puts "\n" + "=" * 80
+  puts footer
+  unless failed.empty?
+    puts "Failed (#{failed.length}):"
+    failed.each { |f, _, d| puts format("  FAIL %7.1fs  %s", d, f) }
+  end
+  puts "=" * 80
+  File.open(log, "a") do |f|
+    f.puts footer
+    failed.each { |ff, _, d| f.puts format("  FAIL %7.1fs  %s", d, ff) }
+  end
+  exit(1) unless failed.empty?
+end
+
 # Integration tests require Docker
 namespace :test do
-  desc "Run all integration tests (requires Docker)"
+  desc "Run all integration tests (requires Docker). " \
+       "Knobs: TEST_PATTERN=<substr>, CONTINUE_ON_FAILURE=false."
   task :integration do
     # Disruptive tests (server stop/restart) are run separately via
     # `test:integration:disruptive` so they never interleave with — and
     # flake — the rest of the integration suite against the shared server.
-    integration_files = FileList["test/lib/**/*integration_test.rb"]
-                          .exclude("test/lib/**/*disruptive*")
-
-    puts "Running #{integration_files.length} integration test files..."
-    integration_files.each_with_index do |file, index|
-      puts "Running integration test #{index + 1}/#{integration_files.length}: #{file}"
-
-      # 10: docker integration test fails for cloud functions
-      skip_till = 0
-      if (index + 1) <= skip_till
-        puts "Skipping test #{index + 1} as per configuration\n"
-        next
-      end
-
-      puts "\n" + "="*80
-      puts "Running: #{file}"
-      puts "="*80
-      system("PARSE_TEST_USE_DOCKER=true ruby -Ilib:test #{file}") || exit(1)
-    end
-    puts "\n✅ All integration tests completed successfully!"
+    files = FileList["test/lib/**/*integration_test.rb"]
+              .exclude("test/lib/**/*disruptive*")
+    run_test_files!("Integration tests", files, log: "tmp/integration-progress.log")
   end
 
-  desc "Run unit tests only (no Docker required)"
+  desc "Run unit tests only (no Docker required). " \
+       "Knobs: TEST_PATTERN=<substr>, CONTINUE_ON_FAILURE=false."
   task :unit do
-    unit_files = FileList["test/lib/**/*_test.rb"]
-                   .exclude("test/lib/**/*integration_test.rb")
-                   .exclude("test/lib/**/*disruptive*")
-
-    puts "Running #{unit_files.length} unit test files (no Docker)..."
-    unit_files.each_with_index do |file, index|
-      puts "Running unit test #{index + 1}/#{unit_files.length}: #{file}"
-
-      # 73 is problematic Testing Contains and Nin with Parse Objects with contains and nin 
-      skip_till = 0
-      if (index + 1) <= skip_till
-        puts "Skipping test #{index + 1} as per configuration"
-        next
-      end
-
-      system("PARSE_TEST_USE_DOCKER=true ruby -Ilib:test #{file}") || exit(1)
-    end
-    puts "\n✅ All unit tests completed successfully!"
+    files = FileList["test/lib/**/*_test.rb"]
+              .exclude("test/lib/**/*integration_test.rb")
+              .exclude("test/lib/**/*disruptive*")
+    run_test_files!("Unit tests", files, log: "tmp/unit-progress.log")
   end
 
   namespace :integration do
@@ -602,6 +687,74 @@ namespace :mcp do
   end
 end
 
+# rake client:console — IRB whose DEFAULT client is a non-master client bound to
+# a user's session, so every model query runs as that user (ACL/CLP enforced).
+# Identity: PARSE_SESSION_TOKEN, or PARSE_LOGIN_USER/PARSE_LOGIN_PASSWORD, else
+# prompt. Connection env matches the other tasks; the master key is used only to
+# log in. Helpers in the REPL: client, whoami, as_master { … }.
+namespace :client do
+  desc "Interactive console authenticated as a Parse user (session token or login), not master"
+  task :console do
+    require "irb"
+    begin; require "dotenv/load"; rescue LoadError; end
+    $LOAD_PATH.unshift(File.expand_path("lib", __dir__))
+    require "parse-stack"
+
+    server_url, app_id, rest_api_key, master_key = mcp_credentials_or_abort!
+    Parse.setup(server_url: server_url, application_id: app_id, api_key: rest_api_key, master_key: master_key)
+    master_client = Parse.client
+    token = client_console_token! # String, or nil for anonymous
+
+    # Models memoize their resolved client at the class level (`@client ||=`),
+    # so swapping clients[:default] alone is NOT enough — every swap must also
+    # drop those cached ivars or already-touched classes keep the old client.
+    reset_client_caches = lambda do
+      next unless defined?(Parse::Object)
+      [Parse::Object, *Parse::Object.descendants, Parse::Query].each do |k|
+        k.remove_instance_variable(:@client) if k.instance_variable_defined?(:@client)
+      end
+    end
+
+    # Make a non-master client (session-bound, or anonymous) the default so
+    # every model query runs as the user.
+    user_client = token ? master_client.become(token) : master_client.anonymous
+    Parse::Client.clients[:default] = user_client
+    reset_client_caches.call
+
+    Object.send(:define_method, :client) { user_client }
+    # Redacted: GET /users/me returns a Parse::User carrying the live
+    # sessionToken, and Parse::Object has no redacted #inspect, so returning the
+    # raw object would print the token in the REPL. Hand back a safe summary.
+    Object.send(:define_method, :whoami) do
+      next "anonymous (no session)" unless token
+      r = user_client.current_user(token)
+      next "whoami failed: #{r.error}" unless r.success?
+      u = r.result
+      { "username" => u["username"], "objectId" => u["objectId"], "session_token" => "[FILTERED]" }
+    rescue StandardError => e
+      "whoami failed: #{e.message}"
+    end
+    # Escalate to the master key for the block, then restore the user client.
+    # Both swaps must reset the class client caches (see reset_client_caches),
+    # otherwise a class touched inside the block keeps master afterward, or a
+    # previously-touched class never escalates. Already-instantiated Parse::Query
+    # objects held in REPL locals keep their own client and are not reset.
+    Object.send(:define_method, :as_master) do |&blk|
+      Parse::Client.clients[:default] = master_client
+      reset_client_caches.call
+      blk.call
+    ensure
+      Parse::Client.clients[:default] = user_client
+      reset_client_caches.call
+    end
+
+    mode = token ? "a USER" : "ANONYMOUS"
+    puts "parse-stack-next client console — as #{mode} (no master key). Helpers: client, whoami, as_master { }."
+    ARGV.clear
+    IRB.start
+  end
+end
+
 desc "List undocumented methods"
 task "yard:stats" do
   exec "yard stats --list-undoc"

data/docs/client_sdk_guide.md

@@ -180,6 +180,39 @@ This duality is intentional. The high-level convenience method matches
 what mobile SDKs do; the raw client preserves the response so you can
 log or reroute.
 
+#### A user-scoped client straight from login
+
+`Parse::User#session_client` turns a logged-in user into a **non-master client
+with that user's token bound**, so you don't thread `session_token:` through
+every call. (`Parse.client.become(token)` builds the same thing from any token.)
+`Parse::User#with_session` runs a block as the user:
+
+```ruby
+client = Parse::User.login("ada", "p4ssw0rd!").session_client
+Parse::Query.new("Post", client: client).results     # runs as Ada
+
+# Or a block — every REST-routed op inside is authorized as Ada:
+Parse::User.login("ada", "p4ssw0rd!").with_session do
+  Post.query.count
+  Post.create(title: "Hello")
+end
+```
+
+`session_client` returns `nil` if the user has no session token (e.g. it was
+fetched/saved under the master key rather than logged in). The bound token is
+applied as the lowest-priority auth fallback, so an explicit per-call
+`session_token:`, a `Parse.with_session` block, or `use_master_key: true` all
+still take precedence.
+
+> **Scope boundary.** `with_session` (and `Parse.with_session`) authorize
+> **REST-routed** operations (`find` / `get` / `count` / `save`) as the user.
+> Mongo-direct queries (`results_direct`, `aggregate`, Atlas search) do **not**
+> pick up the ambient session — scope them explicitly with a per-query
+> `session_token:` or a scoped `Parse::Agent`. A no-master client like this one
+> has no mongo-direct path anyway. To run a query as a user *without* a token —
+> via the master key and SDK-side ACL simulation — use
+> `Parse::Query#scope_to_user(user)`.
+
 ### 2.3 Validate / refresh a session
 
 ```ruby

data/docs/mcp_guide.md

@@ -515,10 +515,14 @@ Parse Server version and its `masterKeyIps` configuration.)
 - **Subscriptions do not survive a listening-stream reconnect.** Closing the
   `GET` stream tears down the session's LiveQuery subscriptions; a client that
   reconnects must re-issue its `resources/subscribe` calls.
-- **Session id is a bearer capability.** The listening stream authenticates via
-  the agent factory and keys delivery off the server-issued `Mcp-Session-Id`,
-  which the client must keep secret — possession of a valid session id (plus a
-  valid agent) is sufficient to attach. This matches the cancellation model.
+- **Listening streams are owner-bound (not a bare bearer capability).** The
+  stream authenticates via the agent factory *and* the server-issued
+  `Mcp-Session-Id` is bound to the principal that established it, so another
+  authenticated caller who knows or guesses the id is refused with `403`. The
+  `Mcp-Session-Id` is still secret-bearing and should be kept confidential, but
+  possession alone is no longer sufficient — see **Listening-stream ownership**
+  below for the binding model, its limits, and the `principal_resolver:` knob
+  master-key deployments need to make it effective.
 - **Per-session and global caps.** A client that subscribes but never opens (or
   later drops) its listening stream leaves LiveQuery subscriptions running until
   the session is torn down. A per-session ceiling (default 100,
@@ -538,6 +542,73 @@ Parse Server version and its `masterKeyIps` configuration.)
   one-time warning at construction when a streaming or subscription/notification
   surface is enabled without a cap.
 
+### Listening-stream ownership
+
+The GET listening stream is the single server→client bus shared by resource
+subscriptions, [server-initiated notifications](#server-initiated-notifications-general-purpose),
+and [approval elicitation](#approval-workflows-mcp-elicitation). Whoever holds
+that stream receives everything pushed to its `Mcp-Session-Id` — another
+session's `notifications/resources/updated`, `elicitation/create` approval
+prompts, and arbitrary `notify` payloads. So the stream is **owner-bound**: a
+session is tied to the principal that established it, and only the same
+principal may later open (or re-open) its stream.
+
+How the binding is established and checked:
+
+- **Initialize-bound.** A session created through an `initialize` POST is bound
+  authoritatively to that caller's principal. A later `GET` carrying the same
+  `Mcp-Session-Id` from a *different* principal is refused with HTTP `403`
+  (`-32600`, "Mcp-Session-Id is owned by another principal"). A re-`initialize`
+  by the same caller refreshes the binding.
+- **Trust-on-first-use (TOFU) for the decoupled bus.** A session id that
+  `initialize` never saw — the `notifications: true` bus, where application code
+  pushes to ids it chose itself — is claimed by the first principal to attach a
+  listener; a different principal attaching afterward is refused. TOFU closes
+  the prior model's eviction-after-claim hole (a second caller could overwrite
+  or shadow an existing listener), but a first-mover attacker can still claim an
+  *unused* id, so **notification-bus session ids must be high-entropy**.
+- **Stream close keeps the claim.** The binding is dropped only on an explicit
+  `DELETE` termination, not on mere stream close — a reconnecting owner keeps
+  its claim, and an attacker cannot grab the id during a brief disconnect.
+
+The principal fingerprint is derived, in order, from: an operator-supplied
+`principal_resolver:`, then the agent's `session_token` (hashed), then
+`acl_user`, then `acl_role`. With none of these the agent falls back to a shared
+`"mk"` (master-key) principal:
+
+- **A master-key-everywhere factory makes owner-binding a no-op.** If every
+  request builds a bare master-key agent (no `session_token:` / `acl_user:` /
+  `acl_role:`), all agents share the `"mk"` fingerprint and are
+  indistinguishable, so the `403` never fires among them. Deployments that
+  authenticate users upstream and run master-key agents should supply a
+  `principal_resolver:` to restore a real per-user identity:
+
+  ```ruby
+  app = Parse::Agent::MCPRackApp.new(
+    streaming: true,
+    notifications: true,                 # or resource_subscriptions: true
+    principal_resolver: ->(agent, env) {
+      # Return a stable per-user id (String). nil/empty falls through to the
+      # agent's own scope, then to the shared "mk" principal.
+      env["myapp.authenticated_user_id"]
+    },
+    agent_factory: ->(env) { ... },
+  )
+  ```
+
+  The resolver must respond to `#call`; an invalid one raises `ArgumentError` at
+  construction. Per-user impersonation (binding a real `session_token` per
+  request) achieves the same effect without a resolver.
+
+**Limits (same scope as the cancellation registry):** the owner registry is
+per-`MCPRackApp` instance and **single-process** — it does not span Puma workers
+or survive a restart. In a clustered deployment the `initialize` POST and the
+`GET` stream may land on different workers, so the initialize-binding degrades
+to TOFU there. The registry is LRU-bounded (default 10,000 sessions) so a stream
+of `initialize`-without-`DELETE` sessions cannot grow it without limit; evicting
+an active owner just downgrades that id to TOFU on its next attach. Blank
+session ids or blank fingerprints fail closed.
+
 ---
 
 ## Approval Workflows (MCP elicitation)
@@ -3035,6 +3106,66 @@ Four different refusal reasons each produce a distinct `:error_code` and message
 
 **Resolution order at dispatch:** operator filter ▷ mutation gate ▷ mode ceiling ▷ in-tool class gate. Operator-filter precedence is deliberate — when a tool is excluded by both the operator's `tools: { except: [...] }` AND the mutation gate (or the mode ceiling), the operator-filter message wins so the operator looks at the right knob first. The mode-ceiling message names the tool, not the class — even when the request would have hit an `agent_hidden` class, the ceiling fires first for a refused tool, so the LLM does not learn anything about the class. For tools that pass the ceiling (e.g. `query_class`) the in-tool `assert_class_accessible!` runs next and the `agent_hidden` message echoes the class name supplied by the caller.
 
+### Client mode from a webhook — run a handler as the calling user (v5.3.0)
+
+Parse Server includes the caller's live session token (`user.sessionToken`) in
+every trigger webhook fired by a logged-in user (it is absent for a master-key
+request). `Parse::Webhooks::Payload` captures that token before scrubbing it out
+of `payload.user` / `payload.object` (so it never lands in `payload.as_json` or
+the request log) and exposes two opt-in, user-scoped handles — the webhook
+counterpart of constructing a client-mode agent by hand:
+
+```ruby
+Parse::Webhooks.route(:after_save, "Post") do
+  # self is the Parse::Webhooks::Payload.
+  next true unless session_token?            # master-key save → no caller token
+
+  # A client-mode Parse::Agent bound to the caller — ACL/CLP enforced, no
+  # master-key fallback. Same posture as Parse::Agent.new(session_token:, client: <no master_key>).
+  visible = user_agent.execute(:query_class, class_name: "Post", limit: 20)
+
+  # …or a raw user-scoped Parse::Client (token is BOUND, so plain REST calls
+  # are authorized as the user with no per-call session_token: needed):
+  mine = user_client.request(:get, "classes/Post").result
+  true
+end
+```
+
+| Payload handle | Returns | `nil` when |
+|----------------|---------|-----------|
+| `payload.session_token` | the caller's raw token (`String`) | master-key request (no user) |
+| `payload.user_agent(**opts)` | non-master `Parse::Agent` in **client mode**, token bound | no token |
+| `payload.user_client` | non-master `Parse::Client` with the token **bound** | no token |
+
+`user_client` binds the token via the new `Parse::Client.new(session_token:)`
+option, applied as the lowest-priority auth fallback on every request — an
+explicit per-call `session_token:`, a `Parse.with_session` block, or an explicit
+`use_master_key: true` all still take precedence. Everything the Client Mode
+ceiling above says about a hand-built client-mode agent applies verbatim to
+`payload.user_agent`: read tools only unless `allow_mutations: true`, and
+`acl_user:` / `acl_role:` are not available on a no-master client.
+
+The same user-scoped client is available client-side from a login
+(`Parse::User#session_client`, or `Parse.client.become(token)` from any token),
+and `Parse::User#with_session` / `Parse::Client#with_session` run a block as the
+user so ordinary model operations are implicitly scoped:
+
+```ruby
+client = Parse::User.login(username, password).session_client   # non-master, token bound
+Parse::Query.new("Post", client: client).results                # query as the user
+Parse::User.login(username, password).with_session { Post.query.count }
+```
+
+`with_session` (and `Parse.with_session`) authorize **REST-routed** operations
+(`find` / `get` / `count` / `save`) as the user. Mongo-direct queries
+(`results_direct`, `aggregate`, Atlas search) do NOT pick up the ambient
+session — they resolve auth from the query's own `session_token:` / `acl_user:`
+and otherwise run in **master** mode (a full master read, not anonymous), so
+scope them explicitly with a per-query `session_token:` or a scoped
+`Parse::Agent`. This is deliberate: mongo-direct scoping is always explicit in
+this SDK, so the ambient fiber state can never silently flip a mongo-direct
+query into user scope (or be mistaken for it).
+
 ---
 
 ## `agent_hidden` — Per-Class Agent-Surface Denial

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)