parse-stack-next 5.7.6 → 5.8.1

data/docs/webhooks_guide.md

@@ -87,10 +87,18 @@ one-to-one — the SDK maps between them.
 - **`beforeFind` / `afterFind` are result-side, not object-side.** Unlike the
   save/delete triggers, a find payload carries no single `object` — `beforeFind`
   exposes the incoming `query` (via `payload.query`) and `afterFind` exposes the
-  matched rows (via `payload.objects`). And unlike `afterSave` (whose return
-  value Parse Server ignores), **`afterFind` is result-rewriting**: whatever the
-  handler returns *replaces* the rows sent to the client, so it can filter or
-  redact results. It also adds a webhook round-trip to every matching query, so
+  matched rows (via `payload.objects`). **Over an HTTP webhook, `afterFind` can
+  observe the rows or deny the query, but it cannot rewrite them.** Parse Server
+  passes every row a webhook returns through `toJSONwithObjects`, which turns
+  any plain JSON object into `{}`, so returned rows would reach the client
+  blank. The SDK therefore always replies "keep the rows" (`{}`, with no
+  `success` key). Returning `nil`, `true`, or the unchanged `payload.objects`
+  all pass the rows through. Returning a different set of rows (dropping or
+  adding some) denies the query with an error instead, so rows a handler meant
+  to hide are never returned. To restrict rows, constrain the query in
+  `beforeFind` or with ACLs/CLPs; to block a query, call `error!` or return
+  `false`. (In-process `Parse.Cloud.afterFind` cloud code is not subject to this
+  limit.) It also adds a webhook round-trip to every matching query, so
   register it deliberately.
 
   One non-obvious detail the SDK handles for you: **Parse Server does not put the
@@ -104,11 +112,9 @@ one-to-one — the SDK maps between them.
   Because the class is resolved from the route, declared `:vector` columns are
   stripped from `afterFind` `payload.objects` by default, exactly as they are
   from `object`/`original`/`update` on the other triggers (a
-  `vector_visibility :public` class keeps them). One consequence to keep in
-  mind: an `afterFind` handler that returns `payload.objects` to pass results
-  through passes the *vector-scrubbed* rows on to the client — which matches the
-  `as_json` default (an `owner_only` class never exposes vectors anyway). Return
-  your own array if you need different columns.
+  `vector_visibility :public` class keeps them). This affects only what the
+  handler sees. The rows the client receives are the ones Parse Server matched,
+  unchanged by the webhook.
 
 - **Auth triggers (`beforeLogin` / `afterLogin` / `afterLogout` /
   `beforePasswordResetRequest`) and LiveQuery triggers (`beforeConnect` /
@@ -259,10 +265,102 @@ abort "Webhook coverage gaps detected" if inert.positive?
 ## Returning a value from a handler
 
 A handler block runs with `self` bound to the `Parse::Webhooks::Payload`, so
-inside it you can call `parse_object`, `params`, `error!`, etc. directly. The
-value the handler produces is what Parse Server receives: for `before_save`,
-return the (possibly mutated) `parse_object` to allow the write, or `false` /
-`error!` to reject it.
+inside it you can call `parse_object`, `params`, `error!`, etc. directly. What
+the handler returns decides the reply Parse Server receives:
+
+| Trigger | Allow | Change | Reject |
+|---------|-------|--------|--------|
+| `before_save` | `true`, `nil`, or an unchanged `parse_object` | the mutated `parse_object`, or a Hash of field overrides | `false` or `error!` |
+| `before_delete` | anything else | n/a | `false`, `error!`, or a `before_destroy` callback that returns `false` |
+| `after_find` | `nil`, `true`, or the unchanged `payload.objects` | not possible over HTTP (see above) | `false` or `error!` |
+| function | the return value is the function result | | `error!` |
+
+How a `before_save` change reaches Parse Server: Parse Server *replaces* the
+pending write with the object a beforeSave webhook returns. The SDK therefore
+never replies with only your changes. When nothing changed, it replies "keep
+the write as sent", so the client's atomic operators (`Increment`, `Add`,
+`Remove`, `Delete`, relation operators) and any undeclared fields reach the
+database untouched. When the handler changed fields, the reply is the client's
+full write with your changes layered on top: operators on fields you did not
+touch are passed through as operators, fields the model does not declare (and
+`_User` signup fields such as `password` and `authData`) are kept, and a field
+you set back to its stored value is dropped from the write. A field you
+rewrite is written as an absolute value. Edits made in place on `parse_object`
+count even if the handler returns `true`.
+
+An operator on a dotted sub-key (`"meta.count"`) arrives only as its resulting
+sub-document, so on an update the SDK writes back just the sub-keys that
+changed, as dotted paths, and a removed sub-key as a `Delete`. The split is one
+level deep: a changed sub-key is written whole at `field.sub`, nested objects
+included, because Parse Server rebuilds the afterSave object from a dotted key
+only one level deep. Concurrent writes to other sub-keys of the field survive.
+Some limits remain:
+
+- Two concurrent writes inside the same sub-key can still overwrite each
+  other, including two operators on deeper paths under it
+  (`meta.count.value` and `meta.count.other`).
+- An array is written whole, so a concurrent `Add` to an array inside a
+  sub-document is lost.
+- When a changed sub-key would carry a typed value (a Date, Bytes, Pointer, or
+  other `__type` value), the whole field is written instead, because Parse
+  Server stores a dotted typed value without converting it. Unchanged typed
+  values and deletes do not trigger this.
+- A client that replaces a whole sub-document gets a merge: the changed
+  sub-keys are written and the sub-keys it knew about and removed are
+  deleted, so a sub-key another request added in the meantime survives.
+- Parse Server reports the reply's dotted keys back to the client in the save
+  response. The JavaScript SDK applies them; other clients may need to fetch
+  the object to see the merged value.
+- A dotted key in a Hash the handler returns (`{ "meta.y" => 5 }`) is folded
+  into the parent path the reply writes whole. A key deeper than one level
+  (`"meta.count.value"`) is folded into a `meta.count` write built from the
+  pending object, and on a create every dotted key folds into its whole
+  field. An operator folded this way (`{"__op" => "Increment"}`, `Add`,
+  `AddUnique`, `Remove`, `Delete`) is applied to the value it replaces; an
+  operator that cannot be applied there, or two of your own keys that
+  conflict (`"meta.a" => 5` with `"meta.a.b" => 6`), fails the save with an
+  error. Hash keys may use Ruby names (`acl:`); they are mapped to the
+  stored field names.
+
+On a create, returning `parse_object` also writes the model's declared
+defaults for fields the client did not send, including its ACL policy. Parse
+Server stores a create without an `ACL` as public read and write, so the reply
+always carries the ACL your policy resolves, exactly as an SDK-side create
+would. Owner-based policies (`:owner_else_private`, the default, as well as
+`:owner_else_public` and `:owner_but_public_read`) take the owner from the
+declared `owner:` field and, when that is empty, from the user who made the
+request, so a signed-in client owns what it creates. A request without a user
+gets the policy's fallback (master-key only under `:owner_else_private`), and so
+does a master-key request. A `_User` class declared with `owner: :self` is
+owned by the new user, never by the requester: the reply carries the policy's
+ACL without an owner entry and Parse Server adds the new user's own read and
+write. An ACL the client sent is kept, and an ACL the handler sets always
+wins, whether through `acl=` or mass assignment. A `guard :acl, :master_only`
+revert on a create returns the ACL to the class policy rather than to `{}`.
+Built-in classes such as `_User` that have no policy of their own keep Parse
+Server's defaults. A handler that returns `true`, `nil`, or a Hash keeps the client's
+write as sent, so a create without an ACL stays public; return
+`parse_object` to apply the policy. An ACL the handler assigns on
+`parse_object` (`parse_object.acl = Parse::ACL.new`) is written whatever the
+handler returns, unless a returned Hash sets `ACL` itself.
+
+`after_destroy` callbacks run in the `after_delete` handler (once per delivery,
+skipped for deletes the SDK itself made, whose callbacks already ran locally).
+`before_destroy` callbacks run in `before_delete` when the handler returns
+`parse_object`.
+
+`error!(message, code: 137)` attaches a Parse error code to the error reply
+and to the raised `Parse::Webhooks::ResponseError#code`. Parse Server's HTTP
+webhook adapter currently reports every webhook error to the client as code
+141 (`SCRIPT_FAILED`), so the code is mainly useful to in-process callers such
+as `Parse::Webhooks.run_function`. Any other exception a handler raises is
+answered with a generic `{"error": "Webhook handler failed."}` reply (the
+exception class and a redacted message are logged), so internal details never
+reach the client.
+
+A request for a function with no registered handler is answered with an
+error. A trigger with no registered handler passes the operation through
+unchanged.
 
 You can set that value either with an explicit `return` or by letting it be the
 block's last expression — both work:
@@ -396,10 +494,14 @@ usual.
 This protects the webhook endpoint against **replayed inbound POSTs** —
 `lib/parse/webhooks/replay_protection.rb`:
 
-- **Always-on body + request-id dedup.** A bounded LRU records a digest of each
-  `(request_id, body)`; a duplicate seen within `replay_window_seconds` is
-  rejected with `"Webhook replay detected."`. No cooperation from Parse Server is
-  required; this stops in-window replays.
+- **Nonce-keyed dedup.** When a delivery carries an `X-Parse-Request-Id` or
+  `X-Parse-Webhook-Nonce` header, a bounded LRU records a digest of
+  `(nonce, body)`; a duplicate seen within `replay_window_seconds` is rejected
+  with `"Webhook replay detected."`. Parse Server sends neither header on its
+  own deliveries, so add one in the proxy or wrapper that delivers webhooks if
+  you want dedup. Without a nonce the SDK does not dedup on the body alone:
+  two legitimate identical requests (the same function called twice with the
+  same params) cannot be told apart from a replay that way.
 - **Opt-in HMAC freshness verification.** Set a `signing_secret` and the receiver
   verifies two headers:
   - `X-Parse-Webhook-Timestamp` — Unix epoch seconds; requests outside
@@ -407,6 +509,13 @@ This protects the webhook endpoint against **replayed inbound POSTs** —
   - `X-Parse-Webhook-Signature` — hex HMAC-SHA256 of `"#{timestamp}.#{body}"`
     keyed with the signing secret.
 
+  A signed delivery is deduplicated on its signature, so a captured request
+  cannot be replayed inside the skew window, even with an altered or missing
+  nonce. To send identical bodies more than once in the same second, include
+  an `X-Parse-Webhook-Nonce` header and sign
+  `"#{timestamp}.#{nonce}.#{body}"` instead; each delivery then has its own
+  signature, and a signature cannot be reused under another nonce.
+
 ```ruby
 Parse::Webhooks::ReplayProtection.signing_secret = ENV["PARSE_WEBHOOK_SIGNING_SECRET"]
 Parse::Webhooks::ReplayProtection.replay_window_seconds = 120

data/lib/parse/acl_scope.rb

@@ -74,13 +74,32 @@ module Parse
     #     agree; see {Parse::MongoDB.verify_client!}. Per-client
     #     authorization plus a process-global MongoDB connection is safe only
     #     when they belong to the same application.
-    Resolution = Struct.new(:mode, :permission_strings, :user_id, :session, :strict_role, :client, keyword_init: true) do
+    # @!attribute master_dropped
+    #   @return [Boolean, nil] `true` when the caller asked for `master: true`
+    #     inside {Parse.without_master_key} and the call was downgraded to
+    #     the public scope. Reported on the `parse.mongodb.aggregate`
+    #     notification so a master-key caller that sees only public rows
+    #     inside the block can be diagnosed.
+    Resolution = Struct.new(:mode, :permission_strings, :user_id, :session, :strict_role, :client,
+                            :master_dropped, keyword_init: true) do
       def master?; mode == :master; end
       def session?; mode == :session; end
       def public?; mode == :public; end
       def strict_role?; strict_role == true; end
+      def master_dropped?; master_dropped == true; end
     end
 
+    # SDK-internal value for `master:` on calls that read metadata, not rows
+    # (index statistics, the Atlas Search index listing). It resolves to
+    # master mode even inside {Parse.without_master_key}, which governs row
+    # access. Unlike wrapping the call in {Parse.with_master_key}, it changes
+    # no fiber state, so notification subscribers and threads started during
+    # the call still see the caller's block.
+    # @!visibility private
+    METADATA_MASTER = Object.new.tap do |o|
+      def o.inspect = "#<Parse::ACLScope::METADATA_MASTER>"
+    end.freeze
+
     # The client a resolution was produced by, or nil when it cannot say.
     #
     # Deliberately tolerant of objects that are resolution-shaped without
@@ -125,6 +144,12 @@ module Parse
       #   `master: true` are supplied — they are mutually exclusive.
       # @raise [ACLRequired] when neither is supplied and
       #   {.require_session_token} is `true`.
+      #
+      # Inside a {Parse.without_master_key} block an explicit `master: true`
+      # is dropped and the call runs in the public scope, as a REST request
+      # does once the block strips its master key. With
+      # {.require_session_token} set, the dropped call raises {ACLRequired}
+      # instead. A nested {Parse.with_master_key} block restores master mode.
       def resolve!(options, method_name:)
         session_token = options.delete(:session_token)
         master = options.delete(:master)
@@ -140,6 +165,10 @@ module Parse
         # the legacy behavior.
         strict_role = options.delete(:strict_role) == true
 
+        # SDK metadata reads keep master mode whatever the block says.
+        metadata_master = master.equal?(METADATA_MASTER)
+        master = true if metadata_master
+
         provided = [session_token, master == true ? master : nil, acl_user, acl_role].compact
         if provided.length > 1
           raise ArgumentError,
@@ -147,6 +176,12 @@ module Parse
                 "session_token:, master: true, acl_user:, or acl_role:. Pick one."
         end
 
+        # `Parse.without_master_key` strips the master key from every REST
+        # request in the block, an explicit `use_master_key: true` included.
+        # A direct read must not keep master authority the REST call loses.
+        master_dropped = master == true && !metadata_master && master_key_suppressed?
+        master = nil if master_dropped
+
         if acl_user
           # Pre-resolved User-pointer path used by
           # Parse::Query#scope_to_user. Mirrors the session-token path
@@ -186,6 +221,18 @@ module Parse
                                 client: authorization_client(options))
         end
 
+        if master_dropped
+          if @require_session_token == true
+            raise ACLRequired,
+                  "Parse::#{method_name} was called with master: true inside " \
+                  "Parse.without_master_key, which drops master mode, and " \
+                  "Parse::ACLScope.require_session_token refuses the public " \
+                  "fallback. Pass session_token:, or run the call inside " \
+                  "Parse.with_master_key if it needs master authority."
+          end
+          return public_resolution(options, master_dropped: true)
+        end
+
         if @require_session_token == true
           raise ACLRequired,
                 "Parse::#{method_name} requires session_token: or master: true. " \
@@ -196,14 +243,7 @@ module Parse
         end
 
         warn_no_acl_context_once!(method_name)
-        anonymous = Parse::Authorization::Resolved.new(nil, Set.new)
-        Resolution.new(
-          mode: :public,
-          permission_strings: anonymous.permission_strings,
-          user_id: nil,
-          session: anonymous,
-          client: authorization_client(options),
-        )
+        public_resolution(options)
       end
 
       # Compile the `_rperm` `$match` stage to prepend to a mongo-direct
@@ -266,6 +306,27 @@ module Parse
       #   * **`$facet`** — recursive: each facet branch is itself a
       #     pipeline; rewrite every branch independently.
       #
+      # Each joined class is also held to its own Class-Level Permissions,
+      # the way Parse Server's include sub-query would be:
+      #
+      #   * its `find` CLP is evaluated with Parse Server's branch
+      #     semantics ({Parse::CLPScope.row_constraint_for!}). A denial
+      #     refuses the whole join (fail closed). A grant that rests only
+      #     on `readUserFields` / `pointerFields` adds the "row points at
+      #     the requesting user" predicate to the join's leading `$match`
+      #     (or to `restrictSearchWithMatch` for `$graphLookup`);
+      #   * its protectedFields for the scope are removed by a
+      #     {Parse::CLPScope.protected_strip_stage} placed right after that
+      #     `$match`, before any caller stage of the sub-pipeline. Joined
+      #     rows therefore never carry a protected field into the outer
+      #     pipeline, whatever later stages reshape them, and a `_User`
+      #     row keeps its own `email` only when its STORED `_id` is the
+      #     requesting user.
+      #
+      # When `class_name:` names the queried class, each top-level `$facet`
+      # branch also starts with that class's strip stage: a branch nests the
+      # documents one level down, out of reach of the top-level strip.
+      #
       # Returns a NEW Array; the input pipeline is not mutated.
       # Master and nil-resolution pass through unchanged. Legacy
       # (non-strict-role) empty-perms resolutions also pass through.
@@ -275,8 +336,12 @@ module Parse
       #
       # @param pipeline [Array<Hash>] the aggregation pipeline.
       # @param resolution [Resolution, nil]
+      # @param class_name [String, nil] the queried class, for `$facet`
+      #   branch stripping.
       # @return [Array<Hash>] the rewritten pipeline.
-      def rewrite_pipeline(pipeline, resolution)
+      # @raise [Parse::CLPScope::Denied] when a joined class refuses `find`
+      #   for the scope.
+      def rewrite_pipeline(pipeline, resolution, class_name: nil)
         return pipeline if pipeline.nil? || pipeline.empty?
         return pipeline if resolution.nil? || resolution.master?
         perms = resolution.permission_strings
@@ -301,7 +366,25 @@ module Parse
         # this gate; the rewriter is the shared SDK-level layer so the
         # mongo-direct path enforces it independent of whether an agent
         # made the call.
-        pipeline.map { |stage| rewrite_stage(stage, acl_match, perms) }
+        ctx = JoinContext.new(acl_match, perms, resolution, clp_client_for(resolution))
+        pipeline.each_with_index.map do |stage, idx|
+          rewritten = rewrite_stage(stage, ctx)
+          next rewritten if class_name.nil?
+          strip_facet_branches(rewritten, class_name.to_s, ctx, pipeline[0...idx])
+        end
+      end
+
+      # Whether {.rewrite_pipeline} rewrites join stages for this
+      # resolution (and so places the protected-field strip at the head of
+      # every join). False for master, nil, and legacy empty-perms scopes.
+      #
+      # @param resolution [Resolution, nil]
+      # @return [Boolean]
+      def rewrites_joins?(resolution)
+        return false if resolution.nil? || resolution.master?
+        perms = resolution.permission_strings
+        strict = resolution.respond_to?(:strict_role?) && resolution.strict_role?
+        strict || !(perms.nil? || perms.empty?)
       end
 
       # Walk the result documents and redact every embedded sub-document
@@ -336,34 +419,70 @@ module Parse
 
       private
 
+      # Per-call state shared by the join rewriters.
+      JoinContext = Struct.new(:acl_match, :perms, :resolution, :client)
+
+      # The client whose schema decides CLP for a resolution. A user-scoped
+      # client (from `become` / `session_client`) holds no master key and
+      # cannot read `/schemas`, so it falls back to the default client (nil).
+      # Mirrors {Parse::MongoDB.clp_client_for}.
+      def clp_client_for(resolution)
+        c = client_of(resolution)
+        return nil if c.nil?
+        return nil unless c.respond_to?(:master_key) && !c.master_key.to_s.empty?
+        c
+      end
+
       # Apply the rewriter to a single pipeline stage. Operator-aware:
       # only join-style stages are touched. Everything else passes
-      # through verbatim. `perms` is threaded down so the cross-class
-      # CLP gate (Wave-3 TRACK-ACL-3) can challenge each joined class.
-      def rewrite_stage(stage, acl_match, perms)
+      # through verbatim. The context is threaded down so the
+      # cross-class CLP gate (Wave-3 TRACK-ACL-3) can challenge each
+      # joined class.
+      def rewrite_stage(stage, ctx)
         return stage unless stage.is_a?(Hash)
         op_key, op_val = stage.first
         case op_key.to_s
         when "$lookup"
-          { op_key => rewrite_lookup(op_val, acl_match, perms) }
+          { op_key => rewrite_lookup(op_val, ctx) }
         when "$unionWith"
-          { op_key => rewrite_union_with(op_val, acl_match, perms) }
+          { op_key => rewrite_union_with(op_val, ctx) }
         when "$graphLookup"
-          { op_key => rewrite_graph_lookup(op_val, acl_match, perms) }
+          { op_key => rewrite_graph_lookup(op_val, ctx) }
         when "$facet"
-          { op_key => rewrite_facet(op_val, acl_match, perms) }
+          { op_key => rewrite_facet(op_val, ctx) }
         else
           stage
         end
       end
 
-      # Cross-class CLP gate. Raises {Parse::CLPScope::Denied} when
-      # the current scope cannot `find` rows of `target_class`. Master
-      # mode is already short-circuited in {.rewrite_pipeline} (it
-      # never reaches the rewriters), so reaching this helper means
-      # `perms` is a real claim set. Centralized here to avoid drift
-      # between the three join-style rewriters.
-      def assert_join_target_permitted!(target, perms)
+      # Cross-class CLP gate for a joined class. Applies the hard
+      # internal-collection floor, then evaluates the joined class's `find`
+      # CLP with Parse Server's branch semantics. Raises
+      # {Parse::CLPScope::Denied} when the scope cannot `find` rows of
+      # `target` (including an unresolvable CLP: fail closed). Returns the
+      # `$match` predicate the joined rows must satisfy: the ACL predicate,
+      # ANDed with the pointer-ownership predicate when the grant rests on
+      # `readUserFields` / `pointerFields`.
+      #
+      # Master mode is short-circuited in {.rewrite_pipeline}, so reaching
+      # this helper means `perms` is a real claim set.
+      def join_predicate!(target, ctx)
+        acl_predicate = ctx.acl_match["$match"]
+        return acl_predicate if target.nil? || target.to_s.empty?
+        target_str = target.to_s
+        assert_join_target_permitted!(target_str, ctx.perms, client: ctx.client)
+        pointer_fields = Parse::CLPScope.row_constraint_for!(
+          target_str, :find, ctx.resolution, client: ctx.client,
+        )
+        return acl_predicate if pointer_fields.nil?
+        ownership = Parse::CLPScope.pointer_fields_predicate(pointer_fields, ctx.resolution.user_id)
+        { "$and" => [acl_predicate, ownership] }
+      end
+
+      # Internal-collection floor plus the `permits?` CLP gate for a joined
+      # class. Raises {Parse::PipelineSecurity::Error} for an internal
+      # collection and {Parse::CLPScope::Denied} when CLP refuses `find`.
+      def assert_join_target_permitted!(target, perms, client: nil)
         return if target.nil?
         target_str = target.to_s
         return if target_str.empty?
@@ -378,22 +497,53 @@ module Parse
         # admitting the SDK data classes (`_User`/`_Role`/`_Installation`/
         # `_Session`), which then face the per-scope CLP `find` gate.
         Parse::PipelineSecurity.assert_collection_allowed!(target_str)
-        return if Parse::CLPScope.permits?(target_str, :find, perms)
+        return if Parse::CLPScope.permits?(target_str, :find, perms, client: client)
         raise Parse::CLPScope::Denied.new(
           target_str, :find,
           "Joined class '#{target_str}' refuses :find for current scope.",
         )
       end
 
-      def rewrite_lookup(spec, acl_match, perms)
+      # The stages that lead a join's sub-pipeline: the row filter, then
+      # the joined class's protected-field strip (when it has any).
+      def join_head_stages!(target, ctx)
+        head = [{ "$match" => join_predicate!(target, ctx) }]
+        strip = strip_stage_for(target, ctx)
+        head << strip if strip
+        head
+      end
+
+      def strip_stage_for(target, ctx, user_id: ctx.resolution.user_id)
+        return nil if target.nil? || target.to_s.empty?
+        set = Parse::CLPScope.protected_fields_for(target.to_s, ctx.perms, client: ctx.client)
+        Parse::CLPScope.protected_strip_stage(set, class_name: target.to_s, user_id: user_id)
+      end
+
+      # Prepend the queried class's strip stage to every branch of a
+      # top-level `$facet`. The `_User` self exemption is kept only when no
+      # earlier stage can have rewritten `_id`.
+      def strip_facet_branches(stage, class_name, ctx, preceding)
+        return stage unless stage.is_a?(Hash)
+        op_key, op_val = stage.first
+        return stage unless op_key.to_s == "$facet" && op_val.is_a?(Hash)
+        stable = Parse::PipelineSecurity.identity_preserving?(preceding)
+        strip = strip_stage_for(class_name, ctx, user_id: stable ? ctx.resolution.user_id : nil)
+        return stage if strip.nil?
+        branches = op_val.each_with_object({}) do |(name, branch), out|
+          out[name] = branch.is_a?(Array) ? [strip] + branch : branch
+        end
+        { op_key => branches }
+      end
+
+      def rewrite_lookup(spec, ctx)
         # String shorthand `{$lookup: "Collection"}` is not a real
         # Mongo form; defensively leave it alone.
         return spec unless spec.is_a?(Hash)
         # Gate FIRST so a CLP-denied join is refused before the
         # rewriter spends work rebuilding the sub-pipeline. `from`
-        # accepts string or symbol — normalize via the gate.
+        # accepts string or symbol; the gate normalizes it.
         target = spec["from"] || spec[:from]
-        assert_join_target_permitted!(target, perms)
+        head = join_head_stages!(target, ctx)
         spec = spec.dup
         existing_pipeline = spec["pipeline"] || spec[:pipeline] || []
         # Walk the sub-pipeline recursively so nested $lookup /
@@ -402,69 +552,77 @@ module Parse
         # `perms` set. (Mongo evaluates the sub-pipeline in the
         # joined collection's context, but the requesting session is
         # unchanged; permissions don't elevate by traversing a join.)
-        rewritten_inner = existing_pipeline.map { |s| rewrite_stage(s, acl_match, perms) }
-        new_pipeline = [acl_match] + rewritten_inner
-        spec["pipeline"] = new_pipeline
+        rewritten_inner = existing_pipeline.map { |s| rewrite_stage(s, ctx) }
+        spec["pipeline"] = head + rewritten_inner
         spec.delete(:pipeline) # symbol form was promoted to string form
         spec
       end
 
-      def rewrite_union_with(spec, acl_match, perms)
+      def rewrite_union_with(spec, ctx)
         # `$unionWith` accepts either a String (collection name only)
-        # or a Hash `{coll:, pipeline:}`. Post the target from
-        # either shape so the CLP gate fires before the String→Hash
-        # upgrade — denying access to the joined class BEFORE we go
+        # or a Hash `{coll:, pipeline:}`. Resolve the target from
+        # either shape so the CLP gate fires before the String to Hash
+        # upgrade, denying access to the joined class BEFORE we go
         # to the trouble of building out an upgraded sub-pipeline.
         target = if spec.is_a?(String)
             spec
           elsif spec.is_a?(Hash)
             spec["coll"] || spec[:coll]
           end
-        assert_join_target_permitted!(target, perms)
+        return spec unless spec.is_a?(String) || spec.is_a?(Hash)
+        head = join_head_stages!(target, ctx)
 
         if spec.is_a?(String)
-          return { "coll" => spec, "pipeline" => [acl_match] }
+          return { "coll" => spec, "pipeline" => head }
         end
-        return spec unless spec.is_a?(Hash)
         spec = spec.dup
         existing_pipeline = spec["pipeline"] || spec[:pipeline] || []
-        rewritten_inner = existing_pipeline.map { |s| rewrite_stage(s, acl_match, perms) }
-        spec["pipeline"] = [acl_match] + rewritten_inner
+        rewritten_inner = existing_pipeline.map { |s| rewrite_stage(s, ctx) }
+        spec["pipeline"] = head + rewritten_inner
         spec.delete(:pipeline)
         spec
       end
 
-      def rewrite_graph_lookup(spec, acl_match, perms)
+      def rewrite_graph_lookup(spec, ctx)
         return spec unless spec.is_a?(Hash)
-        # Same CLP gate, same reasoning — $graphLookup reads from a
+        # Same CLP gate, same reasoning: $graphLookup reads from a
         # different collection in the same session's authority.
         target = spec["from"] || spec[:from]
-        assert_join_target_permitted!(target, perms)
+        predicate = join_predicate!(target, ctx)
+        # `$graphLookup` returns whole joined documents and has no
+        # sub-pipeline to strip protected fields in. Refuse it when the
+        # joined class has any for this scope.
+        if strip_stage_for(target, ctx)
+          raise Parse::CLPScope::Denied.new(
+            target.to_s, :find,
+            "$graphLookup into '#{target}' would return protected fields for the " \
+            "current scope; use $lookup, which strips them.",
+          )
+        end
         spec = spec.dup
         # `$graphLookup` doesn't accept a sub-pipeline. Its filter hook
         # is `restrictSearchWithMatch`, which is a $match-predicate (no
         # `$match` wrapper). Combine with any existing restriction via
         # `$and`.
-        acl_predicate = acl_match["$match"]
         existing = spec["restrictSearchWithMatch"] || spec[:restrictSearchWithMatch]
         combined = if existing.nil? || (existing.respond_to?(:empty?) && existing.empty?)
-            acl_predicate
+            predicate
           else
-            { "$and" => [existing, acl_predicate] }
+            { "$and" => [existing, predicate] }
           end
         spec["restrictSearchWithMatch"] = combined
         spec.delete(:restrictSearchWithMatch)
         spec
       end
 
-      def rewrite_facet(spec, acl_match, perms)
+      def rewrite_facet(spec, ctx)
         return spec unless spec.is_a?(Hash)
         spec.each_with_object({}) do |(branch_name, branch_pipeline), out|
           out[branch_name] = if branch_pipeline.is_a?(Array)
-              # Recurse with the same perms — facet branches are
+              # Recurse with the same perms: facet branches are
               # evaluated in the requesting session's authority, not
               # elevated.
-              branch_pipeline.map { |s| rewrite_stage(s, acl_match, perms) }
+              branch_pipeline.map { |s| rewrite_stage(s, ctx) }
             else
               branch_pipeline
             end
@@ -727,8 +885,30 @@ module Parse
         @warned_malformed_rperm_classes = Set.new
       end
 
+      # Whether an explicit `master: true` must be dropped: true inside a
+      # {Parse.without_master_key} block that no nested
+      # {Parse.with_master_key} has re-enabled.
+      # @!visibility private
+      # @return [Boolean]
+      def master_key_suppressed?
+        Parse.respond_to?(:master_key_disabled?) && Parse.master_key_disabled?
+      end
+
       private
 
+      # The anonymous public-scope resolution: `"*"` grants only.
+      def public_resolution(options, master_dropped: nil)
+        anonymous = Parse::Authorization::Resolved.new(nil, Set.new)
+        Resolution.new(
+          mode: :public,
+          permission_strings: anonymous.permission_strings,
+          user_id: nil,
+          session: anonymous,
+          client: authorization_client(options),
+          master_dropped: master_dropped,
+        )
+      end
+
       # Emit the once-per-process security banner the first time a
       # mongo-direct path runs without `session_token:` and without
       # `master: true`. Mirrors {Parse::AtlasSearch}'s warned-once