parse-stack-next 5.1.1 → 5.2.0

data/lib/parse/agent/constraint_translator.rb

@@ -170,7 +170,11 @@ module Parse
           # These enable bcrypt-hash and session-token oracle attacks via
           # count deltas even when operators are otherwise clean.
           assert_where_key_permitted!(key)
-          result[columnize(key)] = translate_value(value, depth: 0, agent: agent)
+          result[columnize(key)] = if key == "$relatedTo"
+                                     translate_related_to_value(value, depth: 0, agent: agent)
+                                   else
+                                     translate_value(value, depth: 0, agent: agent)
+                                   end
         end
       end
 
@@ -213,30 +217,48 @@ module Parse
         # Check if it's a Parse type (Pointer, Date, File, GeoPoint)
         return hash if parse_type?(hash)
 
-        # Check if all keys are operators
-        if hash.keys.all? { |k| k.to_s.start_with?("$") }
-          hash.transform_keys(&:to_s).each_with_object({}) do |(op, val), result|
-            validate_operator!(op)
-            # NEW-TOOLS-7: validate $regex / $options operands before
-            # forwarding to MongoDB.
-            assert_regex_operand_safe!(op, val) if op == "$regex" || op == "$options"
-            result[op] = if CROSS_CLASS_OPERATORS.include?(op)
-                           translate_cross_class_value(op, val, depth: depth + 1, agent: agent)
-                         else
-                           translate_value(val, depth: depth + 1, agent: agent)
-                         end
-          end
-        else
-          # Regular nested object - translate keys to columnized format.
-          # Apply the internal-field key denylist at every nesting level so
-          # a key nested inside $and/$or/$nor cannot bypass the top-level check.
-          hash.transform_keys(&:to_s).each_with_object({}) do |(k, v), result|
+        # Classify each key INDEPENDENTLY rather than branching on whether
+        # *every* key is an operator. A hash that mixes an operator key with a
+        # non-operator (field) sibling — reachable as a `$or`/`$and`/`$nor`
+        # array element — must still validate and dispatch the operator. The
+        # previous all-or-nothing `keys.all?(operator)` gate routed any mixed
+        # hash to the field branch, which skipped `validate_operator!` AND the
+        # cross-class / `$relatedTo` accessibility checks: a blocked operator
+        # (`$where`) or an off-allowlist cross-class / relation reference could
+        # smuggle through alongside a throwaway field key. Per-key dispatch
+        # closes that hole while preserving behavior for pure-operator and
+        # pure-field hashes.
+        hash.transform_keys(&:to_s).each_with_object({}) do |(k, v), result|
+          if k.start_with?("$")
+            result[k] = translate_operator_value(k, v, depth: depth, agent: agent)
+          else
+            # Field-name key: enforce the internal-field denylist at every
+            # nesting level (so a key nested inside `$and`/`$or`/`$nor` cannot
+            # bypass the top-level check), then columnize and recurse.
             assert_where_key_permitted!(k)
             result[columnize(k)] = translate_value(v, depth: depth + 1, agent: agent)
           end
         end
       end
 
+      # Validate and translate a single operator (`$`-prefixed) key/value pair.
+      # Centralized so the operator denylist/whitelist and the cross-class /
+      # `$relatedTo` accessibility checks run for operators in pure-operator
+      # hashes AND for operators mixed with field-key siblings.
+      def translate_operator_value(op, val, depth:, agent: nil)
+        validate_operator!(op)
+        # NEW-TOOLS-7: validate $regex / $options operands before
+        # forwarding to MongoDB.
+        assert_regex_operand_safe!(op, val) if op == "$regex" || op == "$options"
+        if CROSS_CLASS_OPERATORS.include?(op)
+          translate_cross_class_value(op, val, depth: depth + 1, agent: agent)
+        elsif op == "$relatedTo"
+          translate_related_to_value(val, depth: depth + 1, agent: agent)
+        else
+          translate_value(val, depth: depth + 1, agent: agent)
+        end
+      end
+
       # Translate the value of a cross-class operator
       # (+$inQuery+/+$notInQuery+/+$select+/+$dontSelect+). The value
       # carries an embedded +className+ that must be validated against
@@ -299,6 +321,55 @@ module Parse
         translate_value(val, depth: depth, agent: agent)
       end
 
+      # Validate the owning-object class named by a +$relatedTo+ constraint.
+      #
+      # +$relatedTo+ has the shape +{ object: <Pointer>, key: <relation field> }+.
+      # Unlike +$inQuery+ / +$select+ it carries no +className+ / inner +where+,
+      # so it is NOT a {CROSS_CLASS_OPERATORS} entry — but it DOES reach across
+      # to a second class: the owning object whose relation is being read. Left
+      # unvalidated, an agent narrowed to one class (or with a class globally
+      # +agent_hidden+) could still name a relation anchored on an off-allowlist
+      # class via the +object+ pointer. That is the SDK-surface analog of
+      # GHSA-wmwx-jr2p-4j4r, where Parse Server's own +$relatedTo+ bypassed the
+      # owning object's ACL. Run the owning class through the same accessibility
+      # policy as every other cross-class hop, then translate the value normally.
+      #
+      # Fails closed when the owning class cannot be resolved from +object+: an
+      # unresolvable pointer is exactly the shape that would otherwise slip the
+      # check, so refuse the constraint rather than skip it.
+      def translate_related_to_value(val, depth:, agent: nil)
+        owning_class = related_to_owning_class(val)
+        if owning_class.nil? || owning_class.to_s.empty?
+          raise ConstraintSecurityError.new(
+            "SECURITY: $relatedTo requires a resolvable owning-object class; " \
+            "none could be determined from its `object` pointer.",
+            operator: "$relatedTo",
+            reason: :cross_class_denied,
+          )
+        end
+        assert_embedded_class_accessible!("$relatedTo", owning_class, agent: agent)
+        translate_value(val, depth: depth, agent: agent)
+      end
+
+      # Extract the Parse class name of a +$relatedTo+ constraint's owning
+      # object from its +object+ slot, which may be a Parse::Pointer, a Parse
+      # pointer/relation hash (+{__type:, className:, objectId:}+, string or
+      # symbol keys), or a storage-form string (+"ClassName$objectId"+).
+      # Returns nil when no class can be resolved so the caller can fail closed.
+      def related_to_owning_class(val)
+        return nil unless val.is_a?(Hash)
+        obj = val["object"] || val[:object]
+        return obj.parse_class if obj.respond_to?(:parse_class)
+        case obj
+        when Hash
+          o = obj.transform_keys(&:to_s)
+          cn = o["className"]
+          cn.nil? || cn.to_s.empty? ? nil : cn
+        when String
+          obj.include?("$") ? obj.split("$", 2).first : nil
+        end
+      end
+
       # Hook into the agent-side accessibility check when the agent
       # module is loaded; in pure-unit contexts where +Parse::Agent::Tools+
       # has not been loaded, default to a no-op rather than raising —

data/lib/parse/agent/describe.rb

@@ -185,6 +185,7 @@ module Parse
             class_filter: strict_class_filter?,
           },
           correlation_id: @correlation_id,
+          prompt:         { version: Parse::Agent::PROMPT_VERSION },
         }
       end
 

data/lib/parse/agent/errors.rb

@@ -129,5 +129,21 @@ module Parse
     # agent-callable" (a Parse::Error) or "the tier doesn't allow it"
     # (a +:permission_denied+).
     class MethodFiltered < AgentError; end
+
+    # Raised at semantic-search dispatch time when at least one class in
+    # the model registry declares +agent_tenant_scope+ but the class
+    # being searched does not. In a tenant-aware deployment an
+    # un-scoped searchable surface would let an agent retrieve across
+    # tenant boundaries, so the gate is a hard refusal, not a warning.
+    # Enforced at dispatch (when all classes are loaded) rather than at
+    # +agent_searchable+ declaration time so class-load order can't
+    # produce a false negative.
+    class MissingTenantScope < AgentError; end
+
+    # Raised when a tool result contains an operator-registered
+    # prompt-injection canary phrase AND `Parse::Agent.canary_action` is
+    # `:refuse`. A SecurityError subclass so it routes through execute's
+    # security rescue and is never swallowed.
+    class PromptInjectionDetected < SecurityError; end
   end
 end

data/lib/parse/agent/mcp_client.rb

@@ -528,7 +528,16 @@ module Parse
       # @api private
       def wrap_tool_content_for_llm(content)
         s = content.to_s
+        # Idempotency first: our own already-wrapped output (marker at the
+        # head) passes through untouched, so re-wrapping across turns does
+        # not grow or mangle the marker.
         return s if s.start_with?(UNTRUSTED_TOOL_RESULT_MARKER)
+        # Fresh content: neutralize any embedded wrapper/marker strings
+        # (e.g. a stored `</schema_description>` or a forged marker) BEFORE
+        # prepending the real marker, so a stored value can't impersonate or
+        # close the wrapper. The prefix we add afterward is therefore never
+        # seen as embedded by the scrub.
+        s = Parse::Agent::PromptHardening.scrub_marker_injection(s)
         "#{UNTRUSTED_TOOL_RESULT_MARKER}\n#{s}"
       end
 

data/lib/parse/agent/mcp_dispatcher.rb

@@ -132,7 +132,16 @@ module Parse
       #   are translated into a JSON-RPC `isError` content envelope by
       #   {#handle_tools_call}. Cleared from the agent in an ensure block
       #   before this method returns.
-      def self.call(body:, agent:, logger: nil, progress_callback: nil, cancellation_token: nil)
+      # @param subscription_manager [Parse::Agent::MCPSubscriptions::Manager, nil]
+      #   the per-transport resource-subscription coordinator. When present and
+      #   {Parse::Agent::MCPSubscriptions::Manager#supported? supported}, the
+      #   `initialize` handshake advertises the `resources.subscribe` capability
+      #   and `resources/subscribe` / `resources/unsubscribe` are routed to it.
+      #   nil (the default, and the only option on non-streaming transports like
+      #   the WEBrick MCPServer) leaves the capability unadvertised and those
+      #   methods returning a "not supported" error.
+      def self.call(body:, agent:, logger: nil, progress_callback: nil, cancellation_token: nil,
+                    subscription_manager: nil, approval_gate: nil)
         # Snapshot any prior callback/token already on the agent (e.g. a
         # token a parent dispatcher installed before a tool handler
         # invoked us recursively, or values pre-set by the application).
@@ -143,6 +152,7 @@ module Parse
         # token.
         prev_progress_callback   = agent.progress_callback   if agent.respond_to?(:progress_callback)
         prev_cancellation_token  = agent.cancellation_token  if agent.respond_to?(:cancellation_token)
+        prev_approval_gate       = agent.approval_gate        if agent.respond_to?(:approval_gate)
 
         # Install the progress callback and cancellation token on the
         # agent for the duration of the dispatch. Cleared in the ensure
@@ -156,6 +166,10 @@ module Parse
         # is documented to return a fresh agent per request.
         agent.progress_callback   = progress_callback   if progress_callback   && agent.respond_to?(:progress_callback=)
         agent.cancellation_token  = cancellation_token  if cancellation_token  && agent.respond_to?(:cancellation_token=)
+        # Install the per-session approval gate (MCP elicitation) so
+        # agent.execute can request human approval for destructive tools.
+        # Restored in the ensure block like the other per-request state.
+        agent.approval_gate       = approval_gate        if approval_gate       && agent.respond_to?(:approval_gate=)
 
         # Guard: body must be a Hash with a "method" key.
         unless body.is_a?(Hash) && body.key?("method")
@@ -175,7 +189,7 @@ module Parse
           return { status: 200, body: jsonrpc_error(id, -32600, "Invalid Request: notifications must not carry an id") }
         end
 
-        result_hash = dispatch(method, params, agent, id, logger)
+        result_hash = dispatch(method, params, agent, id, logger, subscription_manager)
         { status: result_hash[:status], body: result_hash[:body] }
 
       rescue Parse::Agent::Unauthorized => e
@@ -197,6 +211,9 @@ module Parse
         if agent.respond_to?(:cancellation_token=)
           agent.cancellation_token = prev_cancellation_token
         end
+        if agent.respond_to?(:approval_gate=)
+          agent.approval_gate = prev_approval_gate
+        end
       end
 
       # Emit an internal-error diagnostic. The class+message are operator-only;
@@ -219,10 +236,10 @@ module Parse
       # envelope, and return { status:, body: }.
       #
       # @api private
-      def self.dispatch(method, params, agent, id, logger = nil)
+      def self.dispatch(method, params, agent, id, logger = nil, subscription_manager = nil)
         result = case method
           when "initialize"
-            handle_initialize(params)
+            handle_initialize(params, subscription_manager)
           when "tools/list"
             handle_tools_list(params, agent)
           when "tools/call"
@@ -233,6 +250,10 @@ module Parse
             handle_resources_templates_list(params, agent)
           when "resources/read"
             handle_resources_read(params, agent)
+          when "resources/subscribe"
+            handle_resources_subscribe(params, agent, subscription_manager)
+          when "resources/unsubscribe"
+            handle_resources_unsubscribe(params, agent, subscription_manager)
           when "prompts/list"
             handle_prompts_list(params)
           when "prompts/get"
@@ -278,6 +299,12 @@ module Parse
 
       rescue Parse::Agent::Unauthorized => e
         { status: 401, body: jsonrpc_error(id, -32001, "Unauthorized") }
+      rescue Parse::Agent::AccessDenied
+        # Class-authorization denial (agent_hidden / classes: allowlist), e.g.
+        # from the resources/subscribe gate. Map to -32602 with a generic
+        # message — do NOT echo the class name, so a denied subscribe can't be
+        # used to probe which hidden classes exist.
+        { status: 200, body: jsonrpc_error(id, -32602, "Invalid params") }
       rescue Parse::Agent::SecurityError
         { status: 200, body: jsonrpc_error(id, -32602, "Invalid params") }
       rescue Parse::Agent::ValidationError => e
@@ -307,8 +334,11 @@ module Parse
       # returning the server's preferred version locks those clients
       # out.
       #
+      # @param subscription_manager [Parse::Agent::MCPSubscriptions::Manager, nil]
+      #   when supported, flips the advertised `resources.subscribe` capability
+      #   to true. See {#capabilities_for}.
       # @return [Hash] protocol version, capabilities, and server info.
-      def self.handle_initialize(params)
+      def self.handle_initialize(params, subscription_manager = nil)
         requested = params.is_a?(Hash) ? params["protocolVersion"] : nil
         negotiated =
           if requested.is_a?(String) && SUPPORTED_PROTOCOL_VERSIONS.include?(requested)
@@ -318,7 +348,7 @@ module Parse
           end
         {
           "protocolVersion" => negotiated,
-          "capabilities"    => CAPABILITIES,
+          "capabilities"    => capabilities_for(subscription_manager),
           "serverInfo"      => {
             "name"    => "parse-stack-mcp",
             "version" => Parse::Stack::VERSION,
@@ -327,6 +357,27 @@ module Parse
       end
       private_class_method :handle_initialize
 
+      # Compute the advertised capability object for this transport.
+      #
+      # `resources.subscribe` is advertised as `true` ONLY when a subscription
+      # manager is wired AND reports itself supported (LiveQuery enabled +
+      # available, on a streaming transport that can hold a listening channel).
+      # Advertising a capability is a contract: we never claim `subscribe: true`
+      # unless the server can actually deliver `notifications/resources/updated`.
+      # On the WEBrick MCPServer (no streaming) and on the Rack app when
+      # subscriptions are disabled, this falls back to the base CAPABILITIES
+      # with `subscribe: false`.
+      #
+      # @param manager [Parse::Agent::MCPSubscriptions::Manager, nil]
+      # @return [Hash]
+      def self.capabilities_for(manager)
+        return CAPABILITIES unless manager.respond_to?(:supported?) && manager.supported?
+        CAPABILITIES.merge(
+          "resources" => CAPABILITIES["resources"].merge("subscribe" => true),
+        )
+      end
+      private_class_method :capabilities_for
+
       # Handle `tools/list`.
       #
       # Accepts an optional non-standard `category` param (Parse Stack
@@ -438,12 +489,24 @@ module Parse
             envelope
           end
         else
-          {
+          # Forward the structured error metadata the agent already computed
+          # (error_code, retry_after, details such as suggested_rewrite /
+          # allowed_fields) so a client can branch deterministically and
+          # honor retry_after — instead of re-parsing the prose message. Goes
+          # in `_meta` (spec-allowed arbitrary metadata) under a `parse.`
+          # prefix; the human-readable text content is unchanged.
+          envelope = {
             "content" => [
               { "type" => "text", "text" => result[:error].to_s },
             ],
             "isError" => true,
           }
+          meta = {}
+          meta["parse.error_code"]  = result[:error_code].to_s if result[:error_code]
+          meta["parse.retry_after"] = result[:retry_after]     if result[:retry_after]
+          meta["parse.details"]     = result[:details]         if result[:details].is_a?(Hash) && result[:details].any?
+          envelope["_meta"] = meta unless meta.empty?
+          envelope
         end
       end
       private_class_method :handle_tools_call
@@ -938,6 +1001,75 @@ module Parse
       end
       private_class_method :handle_resources_read
 
+      # Handle `resources/subscribe` (MCP 2025-06-18).
+      #
+      # Registers a LiveQuery-backed subscription for `params["uri"]` keyed by
+      # the agent's session identity (`correlation_id`, sourced from the
+      # `Mcp-Session-Id` header by the transport). Subsequent data changes are
+      # debounced and delivered as `notifications/resources/updated` over the
+      # session's GET listening stream.
+      #
+      # Per the MCP spec a successful subscribe returns an empty result. Errors
+      # propagate as JSON-RPC errors:
+      #   - manager absent / unsupported  → -32601 (capability not offered)
+      #   - malformed or non-subscribable URI → -32602 (ValidationError)
+      #   - agent scope with no LiveQuery equivalent → -32602 (SecurityError)
+      #
+      # @param manager [Parse::Agent::MCPSubscriptions::Manager, nil]
+      # @return [Hash] empty result, or an `:error` hash when unsupported.
+      def self.handle_resources_subscribe(params, agent, manager)
+        return subscriptions_unsupported_error unless manager.respond_to?(:supported?) && manager.supported?
+        ok = manager.subscribe(
+          session_id: agent_session_id(agent),
+          uri:        params["uri"].to_s,
+          agent:      agent,
+        )
+        return {} if ok
+        # subscribe returned false: the session's listening stream was torn down
+        # (detach_listener) while the network subscribe was in flight, so no
+        # subscription exists and no notifications/resources/updated will arrive.
+        # Surface an error rather than a false empty-success ack (per the MCP
+        # contract an empty result == subscribed) so the client reopens its GET
+        # stream and retries instead of waiting forever for updates.
+        { error: { "code" => -32602,
+                   "message" => "resources/subscribe: the session no longer has an open " \
+                                "listening stream; reopen the GET stream and retry" } }
+      end
+      private_class_method :handle_resources_subscribe
+
+      # Handle `resources/unsubscribe` (MCP 2025-06-18). Idempotent — stops the
+      # LiveQuery subscription for the URI if one exists, returns an empty
+      # result regardless.
+      #
+      # @param manager [Parse::Agent::MCPSubscriptions::Manager, nil]
+      # @return [Hash] empty result, or an `:error` hash when unsupported.
+      def self.handle_resources_unsubscribe(params, agent, manager)
+        return subscriptions_unsupported_error unless manager.respond_to?(:supported?) && manager.supported?
+        manager.unsubscribe(
+          session_id: agent_session_id(agent),
+          uri:        params["uri"].to_s,
+        )
+        {}
+      end
+      private_class_method :handle_resources_unsubscribe
+
+      # The session identity used to key resource subscriptions. The transport
+      # populates `agent.correlation_id` from `Mcp-Session-Id`.
+      # @return [String, nil]
+      def self.agent_session_id(agent)
+        agent.respond_to?(:correlation_id) ? agent.correlation_id : nil
+      end
+      private_class_method :agent_session_id
+
+      # Error hash returned when a subscribe/unsubscribe arrives but this
+      # transport does not offer the capability. -32601 (method not found) is
+      # the correct code per JSON-RPC for an unoffered method.
+      # @return [Hash]
+      def self.subscriptions_unsupported_error
+        { error: { "code" => -32601, "message" => "Resource subscriptions are not supported by this server" } }
+      end
+      private_class_method :subscriptions_unsupported_error
+
       # Handle `prompts/list`.
       #
       # Delegates to `Parse::Agent::Prompts.list`, which returns an Array of