parse-stack-next 5.2.1 → 5.4.0

data/Gemfile

@@ -32,5 +32,12 @@ group :test, :development do
   gem "puma"
   gem "sinatra"
   gem "rack-test"
+  # MFA / TOTP test infrastructure (Parse::MFA, two_factor_auth).
+  # rotp:    generates TOTP secrets and time-based codes so the MFA unit and
+  #          integration tests can enroll and log in against Parse Server's
+  #          TOTP adapter (SHA1 / 6 digits / 30s — rotp's defaults match).
+  # rqrcode: renders the provisioning QR code exercised by Parse::MFA.qr_code.
+  gem "rotp"
+  gem "rqrcode"
   # gem "thin" # for yard server - disabled due to eventmachine compilation issues
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    parse-stack-next (5.2.1)
+    parse-stack-next (5.4.0)
       activemodel (>= 6.1, < 9)
       activesupport (>= 6.1, < 9)
       connection_pool (>= 2.2, < 4)
@@ -39,6 +39,7 @@ GEM
     bundler-audit (0.9.3)
       bundler (>= 1.2.0)
       thor (~> 1.0)
+    chunky_png (1.4.0)
     coderay (1.1.3)
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
@@ -54,7 +55,7 @@ GEM
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-net_http (3.4.3)
+    faraday-net_http (3.4.4)
       net-http (~> 0.5)
     faraday-net_http_persistent (2.3.1)
       faraday (~> 2.5)
@@ -72,7 +73,7 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.19.5)
+    json (2.19.8)
     logger (1.7.0)
     method_source (1.1.0)
     minitest (6.0.6)
@@ -104,7 +105,7 @@ GEM
       coderay (~> 1.1)
       method_source (~> 1.0)
       reline (>= 0.6.0)
-    psych (5.3.1)
+    psych (5.4.0)
       date
       stringio
     puma (8.0.2)
@@ -133,6 +134,11 @@ GEM
       connection_pool
     reline (0.6.3)
       io-console (~> 0.5)
+    rotp (6.3.0)
+    rqrcode (3.2.0)
+      chunky_png (~> 1.0)
+      rqrcode_core (~> 2.0)
+    rqrcode_core (2.1.0)
     ruby-progressbar (1.13.0)
     rufo (0.18.2)
     securerandom (0.4.1)
@@ -181,6 +187,8 @@ DEPENDENCIES
   rake
   redcarpet
   redis
+  rotp
+  rqrcode
   rufo
   sinatra
   webrick

data/README.md

@@ -4,6 +4,21 @@
 
 A full-featured Ruby client SDK for [Parse Server](http://parseplatform.org/). [parse-stack-next](https://github.com/neurosynq/parse-stack-next) is a Ruby client SDK, REST client, and Active Model ORM for [Parse Server](http://parseplatform.org/), combining a low-level API client, a query engine, an object-relational mapper (ORM), and a Cloud Code Webhooks rack application in a single gem.
 
+### What's new in 5.4
+
+- **5.4.0 — Hybrid search + reranking for RAG** — `Class.hybrid_search(text:, lexical:, vector:, k:, fusion:)` fuses a lexical Atlas Search branch with a `$vectorSearch` branch using reciprocal-rank fusion (RRF): lexical search nails exact tokens (codes, proper nouns), vector search nails paraphrase, and fusing the two beats either alone. Each branch enforces ACL/CLP independently before fusion (no separate hydration fetch to secure); results carry `#hybrid_score` / `#hybrid_ranks`. `Parse::VectorSearch::Hybrid.rank_fusion_supported?` detects Atlas 8.0+ native `$rankFusion` by a cached behavioural probe (native execution is opt-in; client-side RRF is the always-enforced default). `Parse::Retrieval::Reranker` adds cross-encoder reranking (`Reranker::Cohere` over `/v2/rerank`, plus a deterministic `Reranker::Fixture`), wired into `Parse::Retrieval.retrieve(hybrid:, rerank:)`. `Parse::Embeddings::SpendCap` adds an opt-in per-tenant embedding token cap (hard-refuse) at the `semantic_search` agent-tool boundary. See [CHANGELOG.md](./CHANGELOG.md) and [`docs/atlas_vector_search_guide.md`](./docs/atlas_vector_search_guide.md)
+- **5.4.0 — Vector backfill, visibility, and webhook redaction** — `Class.embed_pending!` backfills embeddings for records whose managed `:vector` field is null (objectId-cursor pagination); `Parse::Object#compute_embedding!` forces an in-place recompute without a save; `vector_visibility :owner_only | :public` controls whether a class's vectors appear in `as_json` by default; and webhook trigger payloads now strip declared `:vector` columns by default (a `:public` class keeps them). See [CHANGELOG.md](./CHANGELOG.md)
+- **5.4.0 — TOTP multi-factor auth works end to end** — the `Parse::User` MFA lifecycle is now fully functional and exercised against a real MFA-enabled Parse Server. `setup_mfa!(secret:, token:)` enrolls TOTP and returns recovery codes; `Parse::User.login_with_mfa(user, pass, code)` completes a second-factor login; `mfa_enabled?` / `mfa_status` report enrollment after an ordinary fetch — the SDK strips the raw TOTP secret and recovery codes that Parse Server returns in `authData` but preserves a leak-safe `{status: "enabled"}` projection so the status reads correctly without exposing the secret; `disable_mfa!(current_token:)` turns MFA off after re-validating the current code (a wrong code raises `Parse::MFA::VerificationError`), and `disable_mfa_master_key!(authorized_by:)` is the operator override. Each MFA write also no longer raises an internal argument error before reaching the server. Interactively, `rake client:console` now prompts for a TOTP / recovery code (or reads `PARSE_LOGIN_MFA`) when logging into an enrolled account. See [CHANGELOG.md](./CHANGELOG.md)
+- **5.4.0 — Request email-address verification** — `Parse::User.request_email_verification(email)` and the instance `Parse::User#request_email_verification` ask Parse Server to (re)send the verification email for a registered, not-yet-verified user, mirroring `request_password_reset` (per-email rate limiting, Boolean return). Requires a server email adapter with `verifyUserEmails` enabled. See [CHANGELOG.md](./CHANGELOG.md)
+- **5.4.0 — Audience hash queries persist correctly** — `Parse::Audience#query` is now stored as a JSON string on the wire to match Parse Server's `_Audience.query` column type, so saving an audience with a `Hash` query no longer fails the server schema check. The public API is unchanged — assign a `Hash`, read a `Hash` back. See [CHANGELOG.md](./CHANGELOG.md)
+- **5.4.0 — Faster AtlasSearch role-cache expiry** — `Parse::AtlasSearch` `role_cache_ttl` now defaults to 30 seconds (was 120) so a role grant or revoke is reflected in `$search` ACL decisions sooner, at the cost of slightly more frequent role lookups. See [CHANGELOG.md](./CHANGELOG.md)
+
+### What's new in 5.3
+
+- **5.3.0 — Run webhook handlers (and clients) as the calling user** — Parse Server embeds the caller's live session token in every trigger webhook fired by a logged-in user. A handler can now opt in to acting on the server *as that user* — full ACL/CLP/`protectedFields` enforcement, no master key. `payload.session_token` exposes the captured token (`nil` for master-key requests; still scrubbed from `payload.user`/`payload.object`/`as_json`/logs); `payload.user_agent` returns a client-mode `Parse::Agent`, and `payload.user_client` a non-master `Parse::Client` with the token **bound** so even raw REST calls authorize as the user. The same user-scoped client is available client-side via `Parse::User#session_client` and the `Parse::Client#become(token)` primitive, with `Parse::Client#with_session { … }` for block scoping. Backed by a new `Parse::Client.new(session_token:)` option. See [Acting as the calling user](#acting-as-the-calling-user)
+- **5.3.0 — Pluralized class-name aliases** — referencing the plural form of a model constant now resolves to that class, so `Posts.where(:author.eq => user).count` works for a class `Post`. The alias is created lazily on first reference and is the *same class object*, so every class method (`query`/`where`, `count`, `find`, `all`, scopes) works through it and `Posts.parse_class` still returns `"Post"`. Because it is the same class it adds no `Parse::Object.descendants` entry and never registers a separate Parse schema class. Classes whose name already ends in `s` are skipped by the automatic path; non-Parse plurals and typos fall through to a normal `NameError`. On by default — opt out with `Parse.pluralized_aliases = false` (or `PARSE_PLURALIZED_ALIASES=false`). For a custom plural, an `s`-ending class, or a namespaced model, call `pluralized_alias!` in the class body. See [Pluralized class-name aliases](#pluralized-class-name-aliases)
+- **5.3.0 — afterSave create reports changed fields; force_ssl-consistent file equality** — a trigger handler that keys off dirty tracking now sees every field on an `afterSave` *create*, symmetric with `afterSave` updates: the built object marks each populated data property changed (from `nil`) while `createdAt`/`updatedAt`/`ACL`/`objectId` stay clean and object readability, `new?`, and `existed?` are unchanged — so a handler that builds a payload from `*_changed?` / `changes` works uniformly across create and update. Separately, `Parse::File#==` now compares both files through the canonical `url` reader, so two files at the same location compare equal regardless of `Parse::File.force_ssl` (and `a == b` matches `b == a`), and a re-signed URL for the same object no longer reads as a change. See [Cloud Code Triggers](#cloud-code-triggers)
+
 ### What's new in 5.2
 
 - **5.2.1 — Webhook triggers receive the full Parse object** — trigger handlers (`beforeSave`/`afterSave`/…) now get the complete server object (`createdAt`/`updatedAt`, `ACL`, internal fields); only live credentials (session tokens, password hashes) are stripped. `Parse::Object#existed?` / `#new?` are reliable in `afterSave`, `afterSave` updates carry dirty tracking, and the model lifecycle runs in ActiveModel order — `before_save → before_create` then `after_create → after_save` — so `before_create` now fires for REST/JS/Auth0 creates (and `after_save` no longer double-fires). See [Cloud Code Triggers](#cloud-code-triggers)
@@ -203,9 +218,20 @@ result = Parse.call_function :myFunctionName, {param: value}
 
 ```
 
+## Examples
+
+Runnable, self-contained scripts live in [`examples/`](examples/) — see
+[`examples/README.md`](examples/README.md) for the full index. Highlights:
+
+- [`basic_server.rb`](examples/basic_server.rb) — master-key setup: models, schema, CRUD + queries.
+- [`basic_client.rb`](examples/basic_client.rb) — unprivileged client with row-level ACL enforcement.
+- [`live_query_listener.rb`](examples/live_query_listener.rb) — interactive LiveQuery console scoped to a user's session.
+- [`rag_chatbot.rb`](examples/rag_chatbot.rb) — retrieval-augmented generation with `semantic_search` + an OpenAI/Anthropic add-in.
+- [`transaction_example.rb`](examples/transaction_example.rb) — atomic multi-object transactions.
+
 ## Release History
 
-**Current version: 5.0.1** | **Ruby 3.2+ required**
+**Current version: 5.4.0** | **Ruby 3.2+ required**
 
 The 5.0 highlights (vector search / RAG, pooled Redis cache, AS::N instrumentation, MCP transport hardening, GraphQL type generation) are summarized in the [What's new in 5.0](#whats-new-in-50) section above. Earlier releases are recorded below.
 
@@ -296,6 +322,7 @@ The 1.x line is the original [`modernistik/parse-stack`](https://github.com/mode
     - [Linking and Unlinking](#linking-and-unlinking)
     - [Request Password Reset](#request-password-reset)
 - [Modeling and Subclassing](#modeling-and-subclassing)
+  - [Pluralized class-name aliases](#pluralized-class-name-aliases)
   - [Defining Properties](#defining-properties)
     - [Accessor Aliasing](#accessor-aliasing)
     - [Property Options](#property-options)
@@ -1579,8 +1606,11 @@ user.mfa_status    # => :enabled, :disabled, or :unknown
 # Disable MFA (requires current token)
 user.disable_mfa!(current_token: "123456")
 
-# Admin reset (master key) — authorized_by must be a Parse::User
-user.disable_mfa_master_key!(authorized_by: admin_user)
+# Admin reset (master key) — fails closed: pass either an admin_role:
+# for the library to verify, or allow_unverified: true to assert that
+# you have already authorized the operator out-of-band.
+user.disable_mfa_master_key!(authorized_by: admin_user, admin_role: "Admin")
+# or: user.disable_mfa_master_key!(authorized_by: admin_user, allow_unverified: true)
 ```
 
 **SMS MFA (requires Parse Server SMS callback):**
@@ -1622,6 +1652,61 @@ class Commentary < Parse::Object
 end
 ```
 
+### Pluralized class-name aliases
+
+As a convenience, the plural form of a model constant resolves to that class, so the plural reads naturally at a query call site:
+
+```ruby
+class Post < Parse::Object
+  property :title, :string
+  belongs_to :author, as: :user
+end
+
+# `Posts` resolves to `Post` on first reference:
+Posts.where(:author.eq => current_user).count
+Posts.query(:title.exists => true).results
+Posts.find("abc123")
+```
+
+The alias is created lazily (via `const_missing`) the first time the plural constant is referenced, and it is the **same class object** as the singular — `Posts.equal?(Post)` is `true`. As a result:
+
+- Every class method works through it for free: `query`/`where`, `count`, `find`, `all`, and any `scope` you define.
+- `Posts.parse_class` still returns `"Post"`. The alias is purely a Ruby-constant convenience.
+- It adds no `Parse::Object.descendants` entry and **never registers a separate Parse schema class** — schema introspection and `Parse.auto_upgrade!` see exactly one class.
+
+The automatic path is deliberately conservative:
+
+- A class whose name already ends in `s` (for example `Status`, `Series`) is **skipped**, since its plural is ambiguous.
+- A plural that does not singularize to a known `Parse::Object` subclass (a typo, or `Strings` → `String`) falls through to a normal `NameError` — the SDK does not change Ruby's behavior for non-model constants.
+
+The feature is enabled by default. Opt out globally:
+
+```ruby
+Parse.pluralized_aliases = false      # programmatic
+# or
+# PARSE_PLURALIZED_ALIASES=false      # environment
+```
+
+For a custom plural, a class whose name ends in `s` that you *do* want aliased, or a namespaced model (where the alias should live on the enclosing module rather than at the top level), declare it explicitly with the `pluralized_alias!` macro. The explicit macro ignores the global flag and the `s`-ending guard:
+
+```ruby
+class Status < Parse::Object
+  pluralized_alias! :Statuses          # defines ::Statuses => Status
+end
+
+module Blog
+  class Article < Parse::Object
+    pluralized_alias!                   # defines Blog::Articles => Blog::Article
+  end
+end
+```
+
+If the target constant already exists and is not the class itself, `pluralized_alias!` raises `ArgumentError` rather than clobbering it (a code reloader swapping the class object is detected and the alias is re-pointed instead).
+
+The automatic path and the macro differ in *where* the alias constant is installed. The macro always anchors it on the class's own parent — top level for `Post`, the enclosing module for a namespaced model. The automatic path installs it on the module where the plural was first referenced (Ruby's `const_missing` fires on the referencing lexical scope), so a bare `Posts` written inside `module Blog` defines `Blog::Posts`. Both resolve to the same class; if you want a single, predictable top-level constant, prefer the macro.
+
+> **Note on reloading:** under a code reloader (for example Zeitwerk in Rails development), a model class is swapped for a fresh object on reload, but the alias constant the SDK created is not tracked by the reloader and is therefore not removed. The `pluralized_alias!` macro detects this on the next run of the class body and re-points the alias to the current class. An *automatically*-created alias, however, stays bound to the previous class object until the process restarts (`const_missing` cannot re-fire for a constant that is still defined). If you depend on the plural during development and want fully deterministic reload behavior, declare it explicitly with `pluralized_alias!`, or disable the feature with `Parse.pluralized_aliases = false`.
+
 ### Defining Properties
 Properties are considered a literal-type of association. This means that a defined local property maps directly to a column name for that remote Parse class which contain the value. **All properties are implicitly formatted to map to a lower-first camelcase version in Parse (remote).** Therefore a local property defined as `like_count`, would be mapped to the remote column of `likeCount` automatically. The only special behavior to this rule is the `:id` property which maps to `objectId` in Parse. This implicit conversion mapping is the default behavior, but can be changed on a per-property basis. All Parse data types are supported and all Parse::Object subclasses already provide definitions for `:id` (objectId), `:created_at` (createdAt), `:updated_at` (updatedAt) and `:acl` (ACL) properties.
 
@@ -4855,6 +4940,32 @@ The `parse_object` handed to your handler is the **full object as Parse Server s
 
 For any `after_*` hook, return values are not needed since Parse does not utilize them. You may also register as many `after_save` or `after_delete` handlers as you prefer, all of them will be called.
 
+For `before_save` (and functions), the handler's value **is** the response Parse Server acts on — return the (possibly mutated) `parse_object` to allow the write, or `false` / `error!` to reject it. You can set that value with an explicit `return` or as the block's last expression; both work, as do the proc idioms `next value` / `break value`:
+
+```ruby
+Parse::Webhooks.route :before_save, :Artist do
+  artist = parse_object
+  return artist if artist.name.present?   # explicit early return
+  error! "name is required"               # raise to reject the save
+end
+```
+
+`self` inside the block is the `Parse::Webhooks::Payload`, so `parse_object`, `params`, and `error!` are available directly. As anywhere in Ruby, `return` ends the handler immediately — to run work *after* the response is sent, use `after_response` (below) rather than code after the `return`.
+
+#### Deferring work until after the response
+
+`payload.after_response { … }` (alias `defer`) registers work to run **after** the webhook response has been sent, off the critical path of the save or function the client is waiting on. The handler returns its value synchronously; the deferred block runs afterward — ideal for search indexing, cache warming, or fan-out that should not add latency.
+
+```ruby
+Parse::Webhooks.route :after_save, :Post do
+  post = parse_object
+  after_response { SearchIndex.reindex(post.id) }   # runs after the reply is sent
+  post
+end
+```
+
+Under Puma or Unicorn the block runs via `rack.after_reply` once the response is flushed (same worker thread, zero added round-trip latency); on a server without it (e.g. WEBrick) it falls back to a detached thread. Multiple blocks run in order and are isolated — one raising affects neither the response nor the others. Notes: deferred blocks run **only on the success path** (a rejected `before_save` runs none), "after the response" is **not** "after the row commits" (don't rely on the persisted row inside the block), and the work is **in-process and best-effort** — it dies with the worker, so for anything that *must* happen use a durable job queue (Sidekiq / ActiveJob). Blocks are drained only when the payload runs through the mounted `Parse::Webhooks` Rack app (a no-op under direct `run_function` / `call_route`). See the [Cloud Code Webhooks Guide](docs/webhooks_guide.md#deferring-work-until-after-the-response).
+
 > **Your model's `after_save` callbacks run here too.** When an `after_save` /
 > `after_create` trigger fires, the webhook rebuilds the `Parse::Object` from the
 > payload and runs that model's ActiveModel `after_save` / `after_create`
@@ -4866,6 +4977,57 @@ For any `after_*` hook, return values are not needed since Parse does not utiliz
 > for saves from other clients (JS / iOS / REST), the webhook runs them, since
 > the SDK never had the chance.
 
+#### ActiveModel callbacks vs. Parse Server triggers
+
+The SDK exposes the full ActiveModel lifecycle on every model
+(`before_validation`, `before_save`/`after_save`, `before_create`/`after_create`,
+`before_update`/`after_update`, `before_destroy`/`after_destroy`). Parse Server,
+separately, exposes a fixed set of **webhook trigger types**. They are not
+one-to-one — the SDK maps between them, and a webhook must be **registered** for
+your ActiveModel logic to run server-side for non-Ruby clients (JS / iOS / REST /
+Dashboard). Without a registered webhook, that logic runs only in the Ruby
+process that initiated the save.
+
+Supported Parse Server trigger types: `beforeSave`/`afterSave`,
+`beforeDelete`/`afterDelete`, `beforeFind`/`afterFind`, `beforeLogin`/`afterLogin`,
+`afterLogout`, `beforePasswordResetRequest`, `beforeConnect`,
+`beforeSubscribe`/`afterEvent`, and file triggers on the `@File` pseudo-class.
+
+The **authentication** triggers (`beforeLogin`/`afterLogin`/`afterLogout`/
+`beforePasswordResetRequest`) and **LiveQuery** triggers (`beforeConnect`/
+`beforeSubscribe`/`afterEvent`) route as first-class shapes — predicates
+(`before_login?` … `after_event?`, `auth_trigger?`/`live_query_trigger?`), an
+`event` accessor, and top-level `sessionToken` capture into `payload.session_token`.
+None of them run ActiveModel `save`/`create`/`destroy` callbacks, even though the
+auth triggers carry a `_User`/`_Session`. Parse Server **ignores the response body**
+for all of them, so the only signal that affects the operation is rejection, and
+only on the `before*` variants: returning `false` (or calling `error!`) from a
+`before_login`/`before_connect`/`before_subscribe`/`before_password_reset_request`
+handler denies the operation, while anything else is a success no-op. (LiveQuery
+triggers are delivered over HTTP only in a co-located single-process setup;
+`beforeConnect` is effectively in-process-only.)
+
+Key relationship — **`beforeSave`/`afterSave` carry the create variants**. Parse
+Server has **no `beforeCreate`/`afterCreate` trigger** (it rejects them). The SDK
+runs your `before_create`/`after_create` callbacks *inside* the
+`beforeSave`/`afterSave` handler for new objects, in ActiveModel order
+(`before_save → before_create`, `after_create → after_save`). So **registering a
+`beforeSave` webhook enables both `before_save` and `before_create`**, and
+`afterSave` enables both `after_save` and `after_create`. Requesting a create
+webhook raises with guidance pointing you at the save trigger.
+
+> **`after_save` is synchronous and on the critical path.** Parse Server waits
+> for the webhook to return before completing the client's write — even on
+> `afterSave`, whose return value is a no-op. Treat `after_save` as a place to
+> **enqueue** background work, not to run long logic inline, and avoid saving
+> other objects inside it (each cascading save fires more webhooks). `beforeSave`
+> can mutate or reject the write, so it is necessarily inline — keep it lean.
+
+For the full picture — trigger types, registration, the synchronous-latency
+model, the Ruby-initiated dedup, and inbound replay/freshness protection — see
+the [Cloud Code Webhooks Guide](docs/webhooks_guide.md) and
+[`examples/webhook_server.rb`](examples/webhook_server.rb).
+
 #### Trigger object state
 
 Because the trigger payload is server-authoritative, the `parse_object` your
@@ -4930,6 +5092,80 @@ double-firing. `:if`/`:unless` conditions on these callbacks are honored.
 > most for client-initiated saves, where the callback runs inside the webhook —
 > Ruby-SDK saves run it in-process after their own REST response instead.
 
+#### Acting as the calling user
+
+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). A handler can opt in to acting on the server **as that user** —
+authorized by Parse Server with full ACL, CLP, and `protectedFields`
+enforcement — instead of reaching for the application master key. Three opt-in
+handles are available on the `payload`:
+
+| Handle | Returns | `nil` when |
+|---|---|---|
+| `payload.session_token` | the caller's raw token (`String`) | master-key request (no user) |
+| `payload.user_agent(**opts)` | a non-master `Parse::Agent` in **client mode**, token bound | no token |
+| `payload.user_client` | a non-master `Parse::Client` with the token **bound** | no token |
+
+```ruby
+Parse::Webhooks.route :after_save, :Post do
+  next true unless session_token?            # master-key save → no caller token
+
+  # A client-mode Parse::Agent scoped to the caller (read tools only unless
+  # you pass allow_mutations: true). ACL/CLP enforced; no master-key fallback.
+  visible = user_agent.execute(:query_class, class_name: "Post", limit: 20)
+
+  # …or a raw user-scoped Parse::Client. The token is BOUND, so plain REST
+  # calls authorize as the user with no per-call session_token: argument:
+  mine = user_client.request(:get, "classes/Post").result
+  true
+end
+```
+
+The token is captured before the payload's credential scrubbing runs, so it is
+still removed from `payload.user` / `payload.object` and never appears in
+`payload.as_json`, `payload.inspect`, or the request log. `user_client` binds it
+via the `Parse::Client.new(session_token:)` option, applied as the
+lowest-priority auth fallback — an explicit per-call `session_token:`, a
+`Parse.with_session` block, or an explicit `use_master_key: true` all still take
+precedence. This applies to **webhook-delivered** triggers (including the model
+`webhook :before_save` DSL, which is HTTP-delivered); a genuine in-process
+ActiveModel `before_save :method` callback has no incoming request and therefore
+no caller token.
+
+The same user-scoped client is available on the **client side**. Two shapes:
+
+```ruby
+# 1. A client object you can pass around (carries the user's token + the
+#    server connection, no master key):
+client = Parse::User.login(username, password).session_client
+Parse::Query.new("Post", client: client).results        # runs as the user
+# (Parse.client.become(token) builds the same thing from any token.)
+
+# 2. A block that runs ordinary model operations as the user, without
+#    threading session_token: through each call:
+Parse::User.login(username, password).with_session do
+  Post.query.count            # counts only the user's readable Posts
+  Post.create(title: "Hi")    # created under the user's permissions
+end
+```
+
+`with_session` (on a `Parse::User`, a `Parse::Client`, or `Parse.with_session`)
+scopes by binding the token as the ambient session — it authorizes
+**REST-routed** operations (`find` / `get` / `count` / `save`) as the user. 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 otherwise run in **master** mode, so scope them explicitly with a per-query
+`session_token:` or a scoped `Parse::Agent`. (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)`.) `Parse::Client#anonymous` builds the same
+non-master client with no token, for an explicitly unauthenticated request.
+
+To explore a server as a specific user from this repo, `rake client:console`
+opens an IRB session whose default client is a non-master client bound to a user
+(session token, login, or anonymous), so every query in the session runs with
+that user's ACL/CLP — with `whoami` and `as_master { … }` helpers.
+
 `before_save` and `before_delete` hooks have special functionality and multiple ways to halt operations:
 
 1. **Using `error!` method**: Calling `error!` will return an error response to Parse Server
@@ -5628,6 +5864,13 @@ The integration tests use Docker Compose to spin up a Parse Server instance with
 - Docker and Docker Compose installed
 - Ruby environment with bundler
 
+> **Always run the suite with `bundle exec`.** Newer `minitest` (6.0+) moved
+> `minitest/mock` out into a separate gem, so a bare `ruby`/`rake` invocation
+> activates minitest 6 and then fails to load `minitest/mock`, aborting every
+> test at load time with `cannot load such file -- minitest/mock (LoadError)`.
+> Running through bundler pins the locked versions and avoids this. If you hit
+> that LoadError, prefix the command with `bundle exec`.
+
 #### Setup and Running Tests
 
 1. **Enable Docker Tests**: Set the environment variable to enable Docker-based tests:
@@ -5712,6 +5955,56 @@ docker compose -f scripts/docker/docker-compose.test.yml up -d
 curl -s http://localhost:29337/parse/health   # -> {"status":"ok"}
 ```
 
+#### Network Exposure and the Preflight Guard
+
+Every service binds to loopback (`127.0.0.1`) by default, and the default
+credentials above are committed to this repository — safe in combination,
+since nothing off the host can reach them. Each bind is overridable
+(`PARSE_BIND`, `MONGO_BIND`, `REDIS_BIND`, `DASHBOARD_BIND`) for the
+occasional need to attach a remote client while debugging.
+
+That override is a footgun: pointing a bind at `0.0.0.0` while the default
+credentials are still in force would publish an admin-credentialed stack
+(Mongo `admin:password`, master key `psnextItMasterKey`) onto your LAN. A
+`preflight` service runs before anything else and **refuses to start the
+stack** in exactly that case. To proceed, do one of:
+
+```bash
+# 1. Keep it loopback (the default) — just omit the *_BIND override.
+
+# 2. Supply real credentials instead of the committed test defaults.
+PARSE_MASTER_KEY="$(openssl rand -hex 24)" \
+MONGO_ROOT_PASSWORD="$(openssl rand -hex 24)" \
+MONGO_BIND=0.0.0.0 \
+  docker compose -f scripts/docker/docker-compose.test.yml up -d
+
+# 3. Acknowledge the exposure on a trusted, isolated network.
+ALLOW_INSECURE_BIND=1 MONGO_BIND=0.0.0.0 \
+  docker compose -f scripts/docker/docker-compose.test.yml up -d
+```
+
+#### Secret Injection (real credentials)
+
+The committed defaults are deliberately non-secret, so the loopback stack
+needs no secrets manager. If you point the stack at *real or shared*
+credentials (option 2 above, or a staging Mongo), keep them out of your
+shell history and the compose file by injecting them at launch. The stack
+reads plain environment variables, so any injector works:
+
+```bash
+# 1Password CLI — secrets resolved from an op:// .env reference file.
+op run --env-file=.env.secrets -- \
+  docker compose -f scripts/docker/docker-compose.test.yml up -d
+
+# Doppler — secrets pulled from a configured project/config.
+doppler run -- \
+  docker compose -f scripts/docker/docker-compose.test.yml up -d
+```
+
+Use the committed `.env.sample` as the reference for which variables each
+side expects; copy it to a gitignored `.env` (or an `op://`-referenced
+`.env.secrets`) and fill in real values there.
+
 #### Environment Variables
 
 The defaults above are baked into the Compose file and the test helpers, so the