parse-stack-next 5.2.1 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02b1de621aaff6ee9a80804b8cb961f18887ef1f6b0a45a38d4c7baa1861f9f7
-  data.tar.gz: d4ae4c20a3e7694d7162e091f5ec3a7dcff05399e352eceecb8dae2dc214c274
+  metadata.gz: 90a966c230e0a0e2e6fd814170726e3af713dae06c0341a00cd7581eecbe53ee
+  data.tar.gz: b171ed432c7ea7806ec07653b47122bd6102a16046c980d915fe45f98ffbca32
 SHA512:
-  metadata.gz: 0cfcf6a2d6472788bc88b000acf11e81fd87b2cead5cae3f7b8e0021ad94172a1051d62cfc3e16fe3dd40086a2dd55f2a4aafa3b4abfdd443a9f4eec273b5656
-  data.tar.gz: 0bf1c5f83855416fd99473e69876c1f6906f2d6cefcc4891f1a67ab60ce92154483c0a49a31a0b0cbed2891a2cd976b0d7f7436f308633272ed2fc0c75dd0871
+  metadata.gz: 510f3f2deb860cedc73f11455fb5d4789c327923abebad4e26b223ae9c385374ffa23bc9564561e7d4dddb31b0c1a015b7e7222dacd7c0b18bdb01199580d7a0
+  data.tar.gz: cd0fb4c706b3c33f12059c7431cf75abd792cbd5ba8b193dd43256aaa70c8fcdd3f86e10b3ad8ffb25c8e9ccc3f985a61bcaa8b49d24badf6f8358cec2b16f3d

data/.bundle/config

@@ -1,4 +1,5 @@
 ---
 BUNDLE_FORCE_RUBY_PLATFORM: "true"
+BUNDLE_FROZEN: "false"
 BUNDLE_PATH: "/home/runner/work/parse-stack-next/parse-stack-next/vendor/bundle"
 BUNDLE_DEPLOYMENT: "true"

data/CHANGELOG.md

@@ -1,5 +1,160 @@
 ## parse-stack-next Changelog
 
+### 5.3.0
+
+#### Run webhook handlers 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. A handler can now opt in to
+acting on the server *as that user* — with full ACL, CLP, and `protectedFields`
+enforcement — instead of reaching for the application master key.
+
+- **NEW**: `Parse::Webhooks::Payload#session_token` exposes the caller's session
+  token, captured from the incoming payload. It is `nil` for a master-key
+  request (which carries no user). 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` or the request log.
+- **NEW**: `Parse::Webhooks::Payload#user_agent` returns a non-master
+  `Parse::Agent` bound to the caller's session token, so it runs in client mode
+  and every query is authorized as the user. Returns `nil` when there is no
+  token.
+- **NEW**: `Parse::Webhooks::Payload#user_client` returns a non-master
+  `Parse::Client` that binds the caller's session token, so even raw REST calls
+  through it are authorized as the user with no further ceremony. Returns `nil`
+  when there is no token.
+- **NEW**: `Parse::Client.new` accepts a `session_token:` option that binds a
+  token to the client. It is applied as the lowest-priority auth fallback on
+  every request (explicit per-call `session_token:` and `Parse.with_session`
+  still take precedence, and an explicit `use_master_key: true` skips it).
+  Pair it with `master_key: nil` to build a user-scoped client.
+- **NEW**: `Parse::Client#become(session_token)` returns a new non-master client
+  that mirrors the receiver's connection settings (`server_url`/`app_id`/
+  `api_key`) but binds the given token — the primitive behind `payload.user_client`
+  and `Parse::User#session_client`. `Parse::Client#anonymous` returns the same
+  shape with no token (unauthenticated REST) to drop a bound identity.
+- **NEW**: `Parse::User#session_client` returns a non-master `Parse::Client`
+  bound to a logged-in user's session token — the client-side counterpart of
+  `payload.user_client` (e.g. `Parse::User.login(u, p).session_client`).
+- **NEW**: `Parse::Client#with_session { ... }` runs a block with the client's
+  bound session token active as the ambient session, so REST-routed operations
+  (`find`/`get`/`count`/`save`) inside it are authorized as the user without
+  passing `session_token:` per call (the client-receiver flavor of
+  `Parse.with_session` / `Parse::User#with_session`). Mongo-direct queries
+  (`results_direct`, `aggregate`, Atlas search) are unaffected and still require
+  explicit per-query scoping.
+- **NEW**: `rake client:console` opens an interactive console 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 /
+  `protectedFields` rather than the master key.
+- **FIXED**: `Parse::Client#inspect` and `Parse::Webhooks::Payload#inspect` no
+  longer print the master key or session token (and, for the payload, the
+  pre-scrub raw credentials) in cleartext — they are redacted, so an error
+  reporter or stray `inspect` cannot leak them.
+- **FIXED**: a whitespace-only `Parse::Client` `session_token:` is now treated
+  as no token, so it can never silently fall through to the master key.
+
+#### Pluralized class-name aliases
+
+Referencing the plural form of a model constant now resolves to that class, so
+the plural reads naturally as a query entry point — `Posts.where(...).count`
+works for a class `Post`.
+
+- **NEW**: The plural alias is created lazily on first reference and is the
+  *same class object* as the singular (`Posts.equal?(Post)` is `true`), so every
+  class method works through it (`query`/`where`, `count`, `find`, `all`, and any
+  `scope`) 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.
+- **NEW**: `pluralized_alias!` class macro for explicit opt-in — use it for a
+  custom plural, a class whose name ends in `s`, or a namespaced model (the alias
+  is defined on the enclosing module). It ignores the global flag and raises
+  `ArgumentError` rather than clobbering an existing unrelated constant.
+- **NEW**: `Parse.pluralized_aliases` configuration (default `true`; opt out with
+  `Parse.pluralized_aliases = false` or `PARSE_PLURALIZED_ALIASES=false`).
+- **CHANGED**: The automatic path is conservative — a class whose name already
+  ends in `s` is skipped, and a plural that does not singularize to a known
+  `Parse::Object` subclass falls through to a normal `NameError`.
+
+#### Pointer associations declared with `property … as:` — BREAKING: now serialize as Pointers
+
+Declaring a pointer with `property` instead of `belongs_to` used to fail
+silently: the `as:` option was dropped and the field became a plain `:string`
+column, so an assigned object was stored as a String and never serialized as a
+Parse pointer. `property … as:` now resolves to the same pointer association as
+`belongs_to`.
+
+- **BREAKING**: a field declared with `property … as:` now serializes as a
+  Pointer (`{__type: "Pointer", …}`) instead of a String. If a deployed app
+  previously used `property … as:` and saved records, Parse Server pinned that
+  column as `String` on first write, and a Pointer write against it is rejected
+  with error 111 (schema type mismatch). Drop or migrate that column to a
+  Pointer type before deploying. Apps that never used `property … as:` are
+  unaffected — the option was a silent no-op, so no working pointer behavior
+  depended on it.
+- **FIXED**: `property <name>, as: <class>` and `property <name>, :pointer` now
+  declare a pointer association identical to the equivalent `belongs_to` — same
+  `:pointer` field type, remote column, target-class reference, getter/setter,
+  dirty tracking, and `{__type: "Pointer", …}` wire form. Previously `as:` was
+  ignored and the field defaulted to `:string`, with no warning.
+- **NEW**: `belongs_to` (and the delegating `property … as:`) raise an
+  `ArgumentError` at declaration time when `as:` names a scalar data type such
+  as `as: :string` — a scalar cannot be a pointer target. The message points to
+  the intended `property <name>, :<type>` form. The guard fires only on an
+  explicit `as:`, so existing `belongs_to :field` declarations are unaffected.
+- **NEW**: `Parse.validate_associations!` verifies that every `belongs_to` /
+  `property … as:` pointer target and every `has_many` target — relation-,
+  array-, and query-backed — resolves to a known Parse class, reporting any
+  unresolved target as a `Class#field -> "Target"` offender. The query- and
+  array-backed `has_many` targets are the bucket where an `as:` typo otherwise
+  stays latent until the association is first traversed. Forward references are
+  legal at
+  declaration time and indistinguishable from typos there, so this cross-class
+  check is meant to run once after all models load (boot, CI, or a rake task).
+- **IMPROVED**: `belongs_to` now stores `_description:` and `_enum:` agent
+  metadata, which previously only `property` retained. A documented pointer
+  association keeps its semantic description, including when declared through
+  `property … as:`.
+
+#### afterSave create reports changed fields; file equality is force_ssl-consistent
+
+A trigger handler that keys off dirty tracking (`*_changed?` / `changes`) now
+sees every field an object was created with on an `afterSave` create, symmetric
+with the existing `afterSave` update behavior, and two `Parse::File` values that
+point at the same location compare equal regardless of `force_ssl`.
+
+- **NEW**: On an `afterSave` trigger for a newly created object (no prior
+  persisted state), the built `Parse::Object` now marks every populated data
+  property as changed, so a handler can use `*_changed?` / `changes` / `changed`
+  uniformly across create and update. Previously the create object
+  was pristine, so `*_changed?` returned `false` for every field and a handler
+  that builds a payload from changed fields would see nothing on creates. A
+  property whose create value equals its declared `default:` (e.g.
+  `status: "draft"`, `count: 0`, `archived: false`) is correctly reported as
+  changed. System fields (`createdAt` / `updatedAt` / `ACL` / `objectId`) stay
+  clean — they are not reported as changed — and object readability, `new?`, and
+  `existed?` are unchanged. Credential and row-permission fields remain filtered
+  from the built object. The `afterSave` update path is unchanged.
+- **CHANGED**: As a result of the above, model `after_save` / `after_create`
+  callbacks fired through the webhook dispatcher now observe an `afterSave`-create
+  object whose data fields are dirty (rather than pristine). A handler that
+  branched on dirty state for a created object should review that expectation;
+  the values themselves are unchanged.
+- **FIXED**: `Parse::File#==` now compares both files through the canonical
+  `url` reader rather than the raw stored URL on one side, so the comparison is
+  symmetric (`a == b` matches `b == a`) and consistent when
+  `Parse::File.force_ssl` coerces a stored `http://` URL to `https://`. Two
+  files at the same location previously read as unequal under `force_ssl`, which
+  could spuriously mark a file property as changed during dirty tracking.
+  Signed-URL query parameters are still stripped before comparison, so a
+  re-signed URL for the same object compares equal while a different underlying
+  location does not.
+- **NEW**: `Parse::File#content_signature` is the overridable seam that `==`
+  uses to decide whether two files refer to the same underlying file. It returns
+  the canonical `url` today (Parse Server's S3 files adapter exposes no content
+  digest); a files-adapter shim or `Parse::File` subclass can override it to key
+  equality off a content hash (S3 ETag / sha256) in the future without touching
+  dirty tracking.
+
 ### 5.2.1
 
 #### Webhook trigger handlers now receive the full Parse object

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    parse-stack-next (5.2.1)
+    parse-stack-next (5.3.0)
       activemodel (>= 6.1, < 9)
       activesupport (>= 6.1, < 9)
       connection_pool (>= 2.2, < 4)

data/README.md

@@ -4,6 +4,12 @@
 
 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.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)
@@ -296,6 +302,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)
@@ -1622,6 +1629,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.
 
@@ -4930,6 +4992,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

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