parse-stack-next 5.4.1 → 5.5.1

data/lib/parse/query.rb

@@ -1252,14 +1252,32 @@ module Parse
         pipeline, has_lookup_stages = build_aggregation_pipeline
         pipeline << { "$count" => "count" }
 
-        # Auto-detect if MongoDB direct is needed
+        # Auto-detect if MongoDB direct is needed. Mirror the routing in
+        # #execute_aggregation_pipeline: a pipeline that references internal
+        # ACL columns (_rperm/_wperm via readable_by/publicly_readable and
+        # friends) MUST run mongo-direct — Parse Server's REST aggregate
+        # endpoint cannot express a $match on those columns — and the
+        # mongo-direct sink must be told the references are sanctioned so
+        # the PipelineSecurity internal-fields denylist lets them through.
+        uses_internal_fields = pipeline_uses_internal_fields?(pipeline)
+        scoped = distinct_query_is_scoped?
         use_mongo_direct = false
-        if has_lookup_stages && defined?(Parse::MongoDB) && Parse::MongoDB.enabled?
+        if defined?(@acl_query_mongo_direct) && !@acl_query_mongo_direct.nil?
+          use_mongo_direct = @acl_query_mongo_direct
+        elsif (scoped || has_lookup_stages || uses_internal_fields) &&
+              defined?(Parse::MongoDB) && Parse::MongoDB.enabled?
           use_mongo_direct = true
+        elsif scoped
+          # Same fail-closed contract as #aggregate / #aggregate_from_query:
+          # a scoped count must not fall back to REST /aggregate, which
+          # would drop the scope and count rows the caller cannot read.
+          raise_scoped_aggregation_requires_mongo_direct!
         end
 
         # Execute aggregation
-        aggregation = Aggregation.new(self, pipeline, verbose: @verbose_aggregate, mongo_direct: use_mongo_direct)
+        aggregation = Aggregation.new(self, pipeline, verbose: @verbose_aggregate,
+                                      mongo_direct: use_mongo_direct,
+                                      allow_internal_fields: uses_internal_fields)
         response = aggregation.execute!
 
         # Extract count from aggregation result
@@ -1803,6 +1821,25 @@ module Parse
       false
     end
 
+    # Fail closed for a scoped aggregation that would otherwise fall back
+    # to REST /aggregate. That endpoint is master-key-only and enforces
+    # neither ACL nor CLP, so letting a scoped query through would silently
+    # run it unscoped as the master key. Every aggregation terminal that
+    # routes a scoped query (aggregate, aggregate_from_query, count,
+    # execute_aggregation_pipeline) raises through here.
+    # @raise [MongoDirectRequired]
+    # @api private
+    def raise_scoped_aggregation_requires_mongo_direct!
+      raise MongoDirectRequired,
+        "[Parse::Query] This scoped aggregation (session_token / " \
+        "scope_to_user / scope_to_role) requires mongo-direct so the " \
+        "SDK can enforce ACL/CLP. Parse Server's REST /aggregate " \
+        "endpoint is master-key-only and enforces neither, so routing " \
+        "it there would silently run unscoped as the master key. " \
+        "Enable mongo-direct via Parse::MongoDB.configure(...), or " \
+        "rewrite without the aggregation terminal."
+    end
+
     # Scope a query to a specific user's row-level ACL when it auto-routes
     # through mongo-direct. The SDK records the user, computes the
     # effective `_rperm` allow-set (user objectId + `"*"` + every role
@@ -1928,11 +1965,21 @@ module Parse
     #     roles, injects the three-layer ACL simulation
     #     (top-level `$match`, `$lookup` rewriter, post-fetch
     #     redactor) via {Parse::MongoDB.aggregate}.
+    #   * an active `Parse.with_session` block — the fiber-local ambient
+    #     session token scopes the read the same way an explicit
+    #     `session_token=` would (see {#mongo_direct_auth_kwargs}).
     #
     # Raises a clear {MongoDirectRequired} otherwise.
     # @!visibility private
     def assert_mongo_direct_routable!
       has_session = @session_token.is_a?(String) && !@session_token.empty?
+      # An active `Parse.with_session` block scopes the read even on a
+      # non-master client (client_mode, or a user-scoped client with no
+      # master key), where `server_mode_master` is false. Without this the
+      # query would raise instead of running scoped — and on a master
+      # client the ambient is what `mongo_direct_auth_kwargs` forwards so
+      # the read is scoped rather than silently master.
+      has_ambient_session = !ambient_session_token.nil?
       # Mirror the request-layer auth resolution in Parse::Client#request:
       # when the process is in "server mode" — Parse.client_mode == false
       # AND the resolved Parse::Client has a master_key — and the caller
@@ -1948,7 +1995,7 @@ module Parse
         false
       end
       server_mode_master = (use_master_key != false) && !Parse.client_mode && client_has_master_key
-      unless use_master_key || server_mode_master || @acl_user || @acl_role || has_session
+      unless use_master_key || server_mode_master || @acl_user || @acl_role || has_session || has_ambient_session
         raise MongoDirectRequired,
           "[Parse::Query] This query uses a constraint that can only run " \
           "via mongo-direct. Mongo-direct bypasses Parse Server's enforcement, " \
@@ -1982,6 +2029,12 @@ module Parse
     #     double-inject).
     #   * `session_token` is set → forward `session_token:` so
     #     Parse::ACLScope runs the full three-layer simulation.
+    #   * Otherwise, the fiber-local ambient session set by
+    #     `Parse.with_session` is forwarded as `session_token:` (unless
+    #     the caller explicitly requested `use_master_key: true`), so a
+    #     query that auto-routes to mongo-direct inside a `with_session`
+    #     block is scoped to that user — matching what the REST path does
+    #     in {Parse::Client#request}.
     #   * Otherwise (master-key path) → forward `master: true`.
     # @!visibility private
     def mongo_direct_auth_kwargs
@@ -1999,11 +2052,32 @@ module Parse
         { acl_role: @acl_role }
       elsif @session_token.is_a?(String) && !@session_token.empty?
         { session_token: @session_token }
+      elsif use_master_key != true && (ambient = ambient_session_token)
+        # No explicit per-query scope, but a `Parse.with_session` block is
+        # active. Mirror Parse::Client#request's precedence (ambient
+        # session wins over the server-mode master default) so the read is
+        # scoped to that user instead of silently running as master with
+        # no ACL/CLP enforcement. An explicit `use_master_key: true` is a
+        # deliberate admin call and skips the ambient, exactly as the REST
+        # path does.
+        { session_token: ambient }
       else
         { master: true }
       end
     end
 
+    # The fiber-local ambient session token set by `Parse.with_session`,
+    # or nil. A whitespace-only ambient is treated as absent so it cannot
+    # block the master fallback and then fail a later presence check —
+    # the same guard {Parse::Client#request} applies.
+    # @return [String, nil]
+    # @!visibility private
+    def ambient_session_token
+      return nil unless Parse.respond_to?(:current_session_token)
+      ambient = Parse.current_session_token
+      ambient if ambient.is_a?(String) && !ambient.strip.empty?
+    end
+
     # Check if this query contains constraints that require aggregation pipeline processing
     # @return [Boolean] true if aggregation pipeline is required
     def requires_aggregation_pipeline?
@@ -3464,15 +3538,60 @@ module Parse
         complete_pipeline << { "$limit" => @limit }
       end
 
-      # Auto-detect if mongo_direct is needed (when $inQuery constraints are present and MongoDB is available)
-      use_mongo_direct = mongo_direct
-      if use_mongo_direct.nil? && lookup_stages && lookup_stages.any? && defined?(Parse::MongoDB) && Parse::MongoDB.enabled?
-        use_mongo_direct = true
-      end
-
       # Optimize pipeline by merging consecutive $match stages
       complete_pipeline = deduplicate_consecutive_match_stages(complete_pipeline)
 
+      # Auto-detect whether this aggregation must run via the direct-MongoDB
+      # path instead of Parse Server's REST /aggregate endpoint. Three
+      # independent triggers, each of which REST /aggregate cannot serve:
+      #
+      #   * $inQuery / $notInQuery → $lookup stages (the original trigger).
+      #   * An SDK-injected ACL $match on the internal _rperm / _wperm columns
+      #     (readable_by / publicly_readable / writable_by and friends). Parse
+      #     Server's REST aggregate rejects a $match on those columns.
+      #   * A scoped query (session_token / scope_to_user / scope_to_role).
+      #     REST /aggregate is master-key-only and enforces NEITHER ACL NOR
+      #     CLP, so a scoped aggregate sent over REST silently runs unscoped
+      #     as the master key — leaking sums/min/max/distinct over rows the
+      #     caller cannot read. This is the same enforcement asymmetry the
+      #     #distinct / #count / #results auto-routes already guard against;
+      #     the scalar terminals (sum/average/min/max/count_distinct) all
+      #     funnel through here, so routing them here fixes every one.
+      #
+      # `allow_internal_fields` is forwarded for internal-field pipelines: the
+      # caller-supplied `pipeline` arg was validated above (line ~3343) with
+      # the internal-fields denylist active, so any _rperm/_wperm reference in
+      # the merged pipeline is provably SDK-injected, never user input.
+      uses_internal_fields = pipeline_uses_internal_fields?(complete_pipeline)
+      scoped = distinct_query_is_scoped?
+      mongo_ready = defined?(Parse::MongoDB) && Parse::MongoDB.enabled?
+      use_mongo_direct = mongo_direct
+
+      if scoped
+        # A scoped aggregation (session_token / scope_to_user / scope_to_role)
+        # must NEVER reach Parse Server's REST /aggregate endpoint — it is
+        # master-key-only and enforces NEITHER ACL NOR CLP, so it would run
+        # unscoped as the master key. This holds even when the caller
+        # explicitly passes `mongo_direct: false`: an explicit false cannot
+        # opt a scoped query out of ACL/CLP enforcement. Promote to mongo-
+        # direct, or fail closed when direct Mongo is unavailable (refuse
+        # rather than leak unscoped rows).
+        if mongo_ready
+          use_mongo_direct = true
+        else
+          raise_scoped_aggregation_requires_mongo_direct!
+        end
+      elsif use_mongo_direct.nil?
+        # Unscoped auto-routing: $inQuery/$notInQuery → $lookup pipelines and
+        # SDK-injected internal-field ($rperm/_wperm) pipelines can't be served
+        # by REST /aggregate, so prefer mongo-direct when available. An unscoped
+        # internal-field pipeline keeps the REST fallback (a master-key
+        # correctness edge, not an enforcement bypass).
+        if (lookup_stages && lookup_stages.any?) || uses_internal_fields
+          use_mongo_direct = true if mongo_ready
+        end
+      end
+
       # When the pipeline is bound for direct MongoDB, translate every stage
       # through the direct-MongoDB field rewriter so user-supplied stages
       # (which use logical Parse field names like `$author`) reach the
@@ -3484,6 +3603,7 @@ module Parse
       end
 
       Aggregation.new(self, complete_pipeline, verbose: verbose, mongo_direct: use_mongo_direct || false,
+                      allow_internal_fields: uses_internal_fields,
                       raw_values: raw_values, raw_field_names: raw_field_names)
     end
 
@@ -3550,17 +3670,44 @@ module Parse
       # Build pipeline from current query constraints
       pipeline, has_lookup_stages = build_query_aggregate_pipeline
 
+      # `allow_internal_fields` is computed from the SDK-built portion ONLY
+      # (before appending caller stages): build_query_aggregate_pipeline emits
+      # the _rperm/_wperm $match for readable_by/etc., but `additional_stages`
+      # is caller-supplied and NOT validated here, so we must not sanction an
+      # internal-field reference the caller smuggled in. A scoped query still
+      # routes to mongo-direct regardless (so ACL/CLP enforcement runs).
+      uses_internal_fields = pipeline_uses_internal_fields?(pipeline)
+
       # Append any additional stages
       pipeline.concat(additional_stages) if additional_stages.any?
 
-      # Auto-detect if mongo_direct is needed (when $inQuery constraints are present and MongoDB is available)
+      # Same routing contract as #aggregate: $lookup subqueries, an SDK ACL
+      # $match, or a scoped query each require the direct-MongoDB path (REST
+      # /aggregate cannot express _rperm/_wperm and is master-key-only/
+      # unenforced). A scoped query fails closed when mongo-direct is
+      # unavailable rather than silently running unscoped as master.
+      scoped = distinct_query_is_scoped?
+      mongo_ready = defined?(Parse::MongoDB) && Parse::MongoDB.enabled?
       use_mongo_direct = mongo_direct
-      if use_mongo_direct.nil? && has_lookup_stages && defined?(Parse::MongoDB) && Parse::MongoDB.enabled?
-        use_mongo_direct = true
+
+      if scoped
+        # A scoped aggregation must never reach REST /aggregate (master-key-
+        # only, unenforced) — not even when the caller explicitly passes
+        # mongo_direct: false. Promote to mongo-direct, or fail closed.
+        if mongo_ready
+          use_mongo_direct = true
+        else
+          raise_scoped_aggregation_requires_mongo_direct!
+        end
+      elsif use_mongo_direct.nil?
+        if has_lookup_stages || uses_internal_fields
+          use_mongo_direct = true if mongo_ready
+        end
       end
 
       # Create Aggregation directly to avoid double-applying constraints
-      Aggregation.new(self, pipeline, verbose: verbose, mongo_direct: use_mongo_direct || false)
+      Aggregation.new(self, pipeline, verbose: verbose, mongo_direct: use_mongo_direct || false,
+                      allow_internal_fields: uses_internal_fields)
     end
 
     private
@@ -3607,6 +3754,16 @@ module Parse
         end
       end
 
+      # Fold in SDK-built aggregation-pipeline marker stages (the _rperm/_wperm
+      # $match emitted by readable_by/publicly_readable/etc., plus set-equality
+      # and empty_or_nil markers). `compile_where` strips these markers, so
+      # without this extraction an ACL filter on `aggregate_from_query` would
+      # be silently dropped — the same omission that affected `Query#count`.
+      markers = compile_markers
+      if markers.key?("__aggregation_pipeline")
+        markers["__aggregation_pipeline"].each { |stage| pipeline << stage }
+      end
+
       # Add $sort stage from order constraints
       unless @order.empty?
         sort_stage = {}
@@ -3702,19 +3859,35 @@ module Parse
       #    Parse Server blocks these for security - must use MongoDB direct
       use_mongo_direct = false
 
+      # When the SDK-built pipeline references internal ACL columns
+      # (_rperm/_wperm via readable_by/writable_by/publicly_readable and
+      # friends, or _acl), the mongo-direct sink must be told these
+      # references are sanctioned so the PipelineSecurity internal-fields
+      # denylist lets them through. The pipeline here is built entirely
+      # from SDK constraint translation (no caller-supplied stages), so
+      # this is safe — same posture as results_direct/count_direct.
+      uses_internal_fields = pipeline_uses_internal_fields?(pipeline)
+      scoped = distinct_query_is_scoped?
+
       # Check for explicit mongo_direct preference first
       if defined?(@acl_query_mongo_direct) && !@acl_query_mongo_direct.nil?
         use_mongo_direct = @acl_query_mongo_direct
       elsif defined?(Parse::MongoDB) && Parse::MongoDB.enabled?
-        # Auto-detect based on pipeline contents
-        if has_lookup_stages || pipeline_uses_internal_fields?(pipeline)
+        # Auto-detect based on pipeline contents and query scope
+        if scoped || has_lookup_stages || uses_internal_fields
           use_mongo_direct = true
         end
+      elsif scoped
+        # Same fail-closed contract as #aggregate / #aggregate_from_query:
+        # a scoped pipeline must not fall back to REST /aggregate, which
+        # would drop the scope and return rows the caller cannot read.
+        raise_scoped_aggregation_requires_mongo_direct!
       end
 
       # Create Aggregation directly to avoid double-applying constraints
       # The aggregate() method would redundantly add where constraints again
-      Aggregation.new(self, pipeline, verbose: @verbose_aggregate, mongo_direct: use_mongo_direct)
+      Aggregation.new(self, pipeline, verbose: @verbose_aggregate, mongo_direct: use_mongo_direct,
+                      allow_internal_fields: uses_internal_fields)
     end
 
     # Check if the pipeline references internal Parse fields that require MongoDB direct access
@@ -5454,23 +5627,38 @@ module Parse
     # Strings are used as-is (user IDs or "role:RoleName" format).
     # Use "public" for public access, "none" or [] for no read permissions.
     #
-    # @param permission [Parse::User, Parse::Role, String, Array] the permission to check
+    # @param permission [Parse::User, Parse::Role, Parse::Pointer, String, Symbol, Array]
+    #   the permission to check. A `Parse::User` (or User pointer) expands to
+    #   the user's objectId plus every role they inherit; a `Parse::Role` (or
+    #   role name String / `:ACL.readable_by_role` form) expands up the role
+    #   hierarchy. `"public"` / `:public` / `:everyone` / `:world` map to the
+    #   `"*"` wildcard. `"none"` / `:none` / `[]` / `nil` match objects with no
+    #   read permissions (explicit empty `_rperm`).
     # @param mongo_direct [Boolean] if true, forces MongoDB direct query. If nil (default),
     #   auto-detects based on query complexity. Set to false to force Parse Server aggregation.
+    # @param strict [Boolean] when false (default), the match is **inclusive**:
+    #   it ALSO returns publicly-readable rows (`_rperm` contains `"*"`) and
+    #   rows with a missing `_rperm` (public by absence), because those are
+    #   genuinely readable by the principal. This is access-simulation
+    #   semantics ("what can this principal read"). Pass `strict: true` for an
+    #   **exact** match — only rows whose `_rperm` literally contains one of
+    #   the resolved permissions, with no public/missing rows — which is what
+    #   an ownership or security audit wants ("which rows explicitly grant
+    #   this principal"). Equivalent to the `:ACL.readable_by_exact` operator.
     # @return [Parse::Query] returns self for method chaining
     # @note This uses MongoDB aggregation pipeline because Parse Server restricts
     #   direct queries on internal ACL fields (_rperm/_wperm).
     # @example
-    #   Song.query.readable_by("user123")           # Objects readable by user ID
-    #   Song.query.readable_by("role:Admin")        # Objects readable by Admin role
-    #   Song.query.readable_by(current_user)        # Objects readable by user object
-    #   Song.query.readable_by("public")            # Publicly readable objects
-    #   Song.query.readable_by("none")              # Objects with no read permissions
-    #   Song.query.readable_by([])                  # Objects with no read permissions (empty ACL)
-    #   Song.query.readable_by([], mongo_direct: true)  # Force MongoDB direct query
-    def readable_by(permission, mongo_direct: nil)
+    #   Song.query.readable_by("user123")               # readable by user ID (+ public)
+    #   Song.query.readable_by("role:Admin")            # readable by Admin role (+ public)
+    #   Song.query.readable_by(current_user)            # by user object, roles expanded (+ public)
+    #   Song.query.readable_by(:public)                 # publicly readable objects
+    #   Song.query.readable_by("none")                  # objects with no read permissions
+    #   Song.query.readable_by([])                      # objects with no read permissions (empty ACL)
+    #   Song.query.readable_by("role:Admin", strict: true)  # ONLY rows that explicitly grant Admin
+    def readable_by(permission, mongo_direct: nil, strict: false)
       @acl_query_mongo_direct = mongo_direct unless mongo_direct.nil?
-      where(:ACL.readable_by => permission)
+      where((strict ? :ACL.readable_by_exact : :ACL.readable_by) => permission)
       self
     end
 
@@ -5478,14 +5666,16 @@ module Parse
     #
     # @param role_name [Parse::Role, String, Array] the role name(s) to check
     # @param mongo_direct [Boolean] if true, forces MongoDB direct query.
+    # @param strict [Boolean] when true, exact match only — no implicit public
+    #   `"*"` and no missing-`_rperm` rows. See {#readable_by}.
     # @return [Parse::Query] returns self for method chaining
     # @example
     #   Song.query.readable_by_role("Admin")              # Objects readable by Admin role
     #   Song.query.readable_by_role(["Admin", "Editor"])  # Objects readable by Admin or Editor
     #   Song.query.readable_by_role(admin_role)           # Objects readable by Role object
-    def readable_by_role(role_name, mongo_direct: nil)
+    def readable_by_role(role_name, mongo_direct: nil, strict: false)
       @acl_query_mongo_direct = mongo_direct unless mongo_direct.nil?
-      where(:ACL.readable_by_role => role_name)
+      where((strict ? :ACL.readable_by_role_exact : :ACL.readable_by_role) => role_name)
       self
     end
 
@@ -5493,23 +5683,27 @@ module Parse
     # Strings are used as-is (user IDs or "role:RoleName" format).
     # Use "public" for public access, "none" or [] for no write permissions.
     #
-    # @param permission [Parse::User, Parse::Role, String, Array] the permission to check
+    # @param permission [Parse::User, Parse::Role, Parse::Pointer, String, Symbol, Array]
+    #   the permission to check. See {#readable_by} for value coercion and
+    #   role expansion.
     # @param mongo_direct [Boolean] if true, forces MongoDB direct query. If nil (default),
     #   auto-detects based on query complexity. Set to false to force Parse Server aggregation.
+    # @param strict [Boolean] when true, exact match only — no implicit public
+    #   `"*"` and no missing-`_wperm` rows. See {#readable_by}.
     # @return [Parse::Query] returns self for method chaining
     # @note This uses MongoDB aggregation pipeline because Parse Server restricts
     #   direct queries on internal ACL fields (_rperm/_wperm).
     # @example
-    #   Song.query.writable_by("user123")           # Objects writable by user ID
-    #   Song.query.writable_by("role:Admin")        # Objects writable by Admin role
-    #   Song.query.writable_by(current_user)        # Objects writable by user object
-    #   Song.query.writable_by("public")            # Publicly writable objects
-    #   Song.query.writable_by("none")              # Objects with no write permissions
-    #   Song.query.writable_by([])                  # Objects with no write permissions (empty ACL)
-    #   Song.query.writable_by([], mongo_direct: true)  # Force MongoDB direct query
-    def writable_by(permission, mongo_direct: nil)
+    #   Song.query.writable_by("user123")               # writable by user ID (+ public)
+    #   Song.query.writable_by("role:Admin")            # writable by Admin role (+ public)
+    #   Song.query.writable_by(current_user)            # by user object, roles expanded (+ public)
+    #   Song.query.writable_by(:public)                 # Publicly writable objects
+    #   Song.query.writable_by("none")                  # objects with no write permissions
+    #   Song.query.writable_by([])                      # objects with no write permissions (empty ACL)
+    #   Song.query.writable_by("role:Admin", strict: true)  # ONLY rows that explicitly grant Admin
+    def writable_by(permission, mongo_direct: nil, strict: false)
       @acl_query_mongo_direct = mongo_direct unless mongo_direct.nil?
-      where(:ACL.writable_by => permission)
+      where((strict ? :ACL.writable_by_exact : :ACL.writable_by) => permission)
       self
     end
 
@@ -5517,14 +5711,16 @@ module Parse
     #
     # @param role_name [Parse::Role, String, Array] the role name(s) to check
     # @param mongo_direct [Boolean] if true, forces MongoDB direct query.
+    # @param strict [Boolean] when true, exact match only — no implicit public
+    #   `"*"` and no missing-`_wperm` rows. See {#readable_by}.
     # @return [Parse::Query] returns self for method chaining
     # @example
     #   Song.query.writable_by_role("Admin")              # Objects writable by Admin role
     #   Song.query.writable_by_role(["Admin", "Editor"])  # Objects writable by Admin or Editor
     #   Song.query.writable_by_role(admin_role)           # Objects writable by Role object
-    def writable_by_role(role_name, mongo_direct: nil)
+    def writable_by_role(role_name, mongo_direct: nil, strict: false)
       @acl_query_mongo_direct = mongo_direct unless mongo_direct.nil?
-      where(:ACL.writable_by_role => role_name)
+      where((strict ? :ACL.writable_by_role_exact : :ACL.writable_by_role) => role_name)
       self
     end
 
@@ -5599,6 +5795,38 @@ module Parse
 
     alias_method :master_key_only, :private_acl
 
+    # Find objects that are NOT readable by the given principal — i.e. hidden
+    # from them. Excludes rows readable by the principal directly, via any role
+    # they inherit, OR publicly (a public row is readable by everyone), and
+    # excludes rows with a missing `_rperm` (public by absence).
+    #
+    # @param permission [Parse::User, Parse::Role, Parse::Pointer, String, Symbol, Array]
+    #   the principal to hide from. See {#readable_by} for value coercion.
+    # @param mongo_direct [Boolean] if true, forces MongoDB direct query.
+    # @return [Parse::Query] returns self for method chaining
+    # @example
+    #   Song.query.not_readable_by(current_user).results   # hidden from this user
+    def not_readable_by(permission, mongo_direct: nil)
+      @acl_query_mongo_direct = mongo_direct unless mongo_direct.nil?
+      where(:ACL.not_readable_by => permission)
+      self
+    end
+
+    # Find objects that are NOT writable by the given principal. See
+    # {#not_readable_by} for the exclusion semantics (direct, role, public).
+    #
+    # @param permission [Parse::User, Parse::Role, Parse::Pointer, String, Symbol, Array]
+    #   the principal to exclude. See {#readable_by} for value coercion.
+    # @param mongo_direct [Boolean] if true, forces MongoDB direct query.
+    # @return [Parse::Query] returns self for method chaining
+    # @example
+    #   Song.query.not_writable_by("role:Admin").results
+    def not_writable_by(permission, mongo_direct: nil)
+      @acl_query_mongo_direct = mongo_direct unless mongo_direct.nil?
+      where(:ACL.not_writable_by => permission)
+      self
+    end
+
     # Find objects that are NOT publicly readable.
     # Matches objects where _rperm does NOT contain "*".
     #
@@ -5728,8 +5956,19 @@ module Parse
     #   aggregate endpoint (PS 9.9.0+). Has no effect on the mongo-direct path.
     # @param raw_field_names [Boolean] when true, passes +rawFieldNames: true+ to the Parse Server
     #   REST aggregate endpoint (PS 9.9.0+). Has no effect on the mongo-direct path.
+    # @param allow_internal_fields [Boolean] when true, the mongo-direct path
+    #   forwards +allow_internal_fields: true+ to {Parse::MongoDB.aggregate} so
+    #   SDK-built ACL `$match` stages that legitimately reference +_rperm+ /
+    #   +_wperm+ (emitted by {Parse::Query#readable_by}, +#publicly_readable+,
+    #   and friends) pass the pipeline-security internal-fields denylist —
+    #   matching the parity already held by +results_direct+ / +count_direct+ /
+    #   +distinct_direct+. Set +true+ ONLY when this Aggregation's pipeline was
+    #   built entirely from SDK constraint translation (no caller-supplied
+    #   stages); the credential-field guard (`_hashed_password`, session tokens,
+    #   auth data) is what +allow_internal_fields+ relaxes, so it must never be
+    #   set on a pipeline that interpolates user input. Defaults to +false+.
     def initialize(query, pipeline, verbose: nil, mongo_direct: false, max_time_ms: nil,
-                   raw_values: false, raw_field_names: false)
+                   raw_values: false, raw_field_names: false, allow_internal_fields: false)
       @query = query
       @pipeline = pipeline
       @cached_response = nil
@@ -5737,6 +5976,7 @@ module Parse
       @max_time_ms = max_time_ms
       @raw_values = raw_values
       @raw_field_names = raw_field_names
+      @allow_internal_fields = allow_internal_fields
       # Use provided verbose setting, or fall back to query's verbose_aggregate setting
       @verbose = verbose.nil? ? @query.instance_variable_get(:@verbose_aggregate) : verbose
     end
@@ -5789,7 +6029,8 @@ module Parse
       # honors it on the mongo-direct path too (parity with results_direct /
       # count_direct / distinct_direct).
       hint = @query.instance_variable_get(:@hint)
-      Parse::MongoDB.aggregate(table, @pipeline, max_time_ms: max_time_ms, hint: hint, **auth_kwargs)
+      Parse::MongoDB.aggregate(table, @pipeline, max_time_ms: max_time_ms, hint: hint,
+                               allow_internal_fields: @allow_internal_fields, **auth_kwargs)
     end
 
     # Returns processed results from the aggregation.

data/lib/parse/retrieval/agent_tool.rb

@@ -108,20 +108,27 @@ module Parse
         score_quantize = (agent.permissions != :admin)
         vector_field = Parse::Agent::MetadataRegistry.searchable_field(cname)
 
-        chunks = Parse::Retrieval.retrieve(
-          query: query,
-          klass: klass,
-          field: vector_field,
-          text_field: resolved_text_field,
-          k: clamp_k(k),
-          filter: filter,
-          vector_filter: vector_filter,
-          chunker: build_chunker(chunk_size, chunk_overlap, chunk_by, max_chunks_per_document),
-          tenant_scope: scope,
-          score_quantize: score_quantize,
-          source_transform: source_projector(agent, cname, scope),
-          **agent.acl_scope_kwargs,
-        )
+        # with_precharged: the cap was charged above with per-tenant
+        # identity (or deliberately skipped for trusted admin agents) —
+        # suppress the generic query-embed charge inside
+        # find_similar/embed_query_text! so the query isn't double-billed
+        # (or admin queries billed to the shared default bucket).
+        chunks = Parse::Embeddings::SpendCap.with_precharged do
+          Parse::Retrieval.retrieve(
+            query: query,
+            klass: klass,
+            field: vector_field,
+            text_field: resolved_text_field,
+            k: clamp_k(k),
+            filter: filter,
+            vector_filter: vector_filter,
+            chunker: build_chunker(chunk_size, chunk_overlap, chunk_by, max_chunks_per_document),
+            tenant_scope: scope,
+            score_quantize: score_quantize,
+            source_transform: source_projector(agent, cname, scope),
+            **agent.acl_scope_kwargs,
+          )
+        end
 
         # Token budget (B4): trim the score-ordered chunk list before
         # building the envelope so `documents` only carries parents whose

data/lib/parse/retrieval/retriever.rb

@@ -70,6 +70,84 @@ module Parse
       obj
     end
 
+    # Translate Parse pointer VALUES in a caller-supplied filter into
+    # their MongoDB storage form so they actually match raw documents.
+    # `{ owner: <Parse::Pointer User/abc> }` becomes
+    # `{ "_p_owner" => "_User$abc" }` — pointer columns are stored under
+    # a `_p_` prefix with `"<className>$<objectId>"` string values, so a
+    # Parse-side pointer (a `{__type: "Pointer", ...}` hash on the wire,
+    # or a `Parse::Pointer` / `Parse::Object` instance from Ruby
+    # callers) in a `$match` / `$vectorSearch.filter` would otherwise
+    # never match anything.
+    #
+    # Recognized pointer values:
+    # * `Parse::Pointer` / `Parse::Object` instances,
+    # * `{ "__type" => "Pointer", "className" => ..., "objectId" => ... }`
+    #   hashes (symbol or string keys).
+    #
+    # Translation applies to direct values, and to pointer values inside
+    # one level of operator hashes (`{ owner: { "$in" => [ptr, ptr] } }`,
+    # `$eq` / `$ne` / `$nin`). Non-pointer values and unrecognized keys
+    # pass through untouched, so the call is idempotent.
+    #
+    # SECURITY ORDERING: run this AFTER {.assert_no_underscore_keys!} /
+    # the agent filter-field allowlist (callers may not name `_p_*`
+    # columns directly) and BEFORE the tenant-scope fold.
+    #
+    # @param klass [Class] the Parse::Object subclass (for field_map
+    #   wire-name resolution).
+    # @param filter [Hash, nil] caller filter.
+    # @return [Hash, nil] translated copy (or the input when nothing
+    #   needed translation / input was nil).
+    def translate_pointer_filter_values(klass, filter)
+      return filter unless filter.is_a?(Hash)
+      out = {}
+      filter.each do |key, value|
+        if (storage = pointer_storage_value(value))
+          out["_p_#{wire_name(klass, key)}"] = storage
+        elsif value.is_a?(Hash) && value.keys.any? { |op| op.to_s.start_with?("$") }
+          translated = value.transform_values do |opval|
+            if (s = pointer_storage_value(opval))
+              s
+            elsif opval.is_a?(Array)
+              opval.map { |el| pointer_storage_value(el) || el }
+            else
+              opval
+            end
+          end
+          if translated == value
+            out[key] = value
+          else
+            out["_p_#{wire_name(klass, key)}"] = translated
+          end
+        else
+          out[key] = value
+        end
+      end
+      out
+    end
+
+    # @!visibility private
+    # `"<className>$<objectId>"` storage string for a pointer-shaped
+    # value, or nil when the value is not a pointer.
+    def pointer_storage_value(value)
+      if defined?(Parse::Pointer) && value.is_a?(Parse::Pointer)
+        cname = value.parse_class
+        oid = value.id
+        return nil if cname.to_s.empty? || oid.to_s.empty?
+        return "#{cname}$#{oid}"
+      end
+      if value.is_a?(Hash)
+        type = value["__type"] || value[:__type]
+        return nil unless type.to_s == "Pointer"
+        cname = value["className"] || value[:className]
+        oid = value["objectId"] || value[:objectId]
+        return nil if cname.to_s.empty? || oid.to_s.empty?
+        return "#{cname}$#{oid}"
+      end
+      nil
+    end
+
     # Retrieve and chunk documents semantically similar to `query`.
     #
     # @param query [String] natural-language query.
@@ -136,6 +214,12 @@ module Parse
       end
 
       resolved_text_field = (text_field || infer_text_field!(klass)).to_sym
+      # Pointer-value translation runs BEFORE the tenant-scope fold (the
+      # fold's conflict check must see final storage-form keys) and after
+      # any caller-side underscore-key gate (the agent tool walks the raw
+      # filter before calling retrieve).
+      filter = translate_pointer_filter_values(klass, filter)
+      vector_filter = translate_pointer_filter_values(klass, vector_filter)
       merged_vector_filter = fold_tenant_scope(klass, vector_filter, tenant_scope)
       chunker ||= default_chunker
       text_wire = wire_name(klass, resolved_text_field)