parse-stack-next 5.7.6 → 5.8.1

data/lib/parse/agent.rb

@@ -23,6 +23,8 @@ require_relative "agent/rate_limiter"
 require_relative "agent/cancellation_token"
 require_relative "agent/log_levels"
 require_relative "agent/approval_gate"
+require_relative "agent/field_policy"
+require_relative "agent/field_names"
 require_relative "agent/prompt_hardening"
 require_relative "agent/describe"
 
@@ -592,8 +594,10 @@ module Parse
         # Use provided port, or configured port, or default
         port ||= Parse.mcp_server_port || 3001
 
-        @mcp_enabled = true
+        # Load the server before flagging MCP as enabled, so a failed load
+        # does not leave mcp_enabled? reporting true.
         require_relative "agent/mcp_server"
+        @mcp_enabled = true
         MCPServer.default_port = port
 
         # Pass remote API config if available
@@ -1031,11 +1035,35 @@ module Parse
     #   `progress_callback` / `cancellation_token` are threaded. An
     #   embedder on the non-MCP path may assign any object responding to
     #   `#review`.
+    #
+    #   A sub-agent built with `parent:` and no gate of its own uses its
+    #   parent's gate, read at call time: the dispatcher swaps the
+    #   parent's gate per request, so a copy taken at construction would
+    #   go stale. Without this a sub-agent fell back to {NullGate} and
+    #   ran tools in `require_approval_for` tiers with no approval.
     def approval_gate
-      @approval_gate ||= Parse::Agent::NullGate.new
+      return @approval_gate if @approval_gate
+      return @approval_parent.approval_gate if @approval_parent
+      @approval_gate_defaulted = true
+      @approval_gate = Parse::Agent::NullGate.new
     end
 
-    attr_writer :approval_gate
+    # Assign this agent's own approval gate. Assigning nil removes it, so
+    # a sub-agent goes back to using its parent's gate.
+    def approval_gate=(gate)
+      @approval_gate_defaulted = false
+      @approval_gate = gate
+    end
+
+    # @return [Parse::Agent::ApprovalGate, nil] the gate assigned on this
+    #   agent itself, or nil when it uses its parent's (or the default).
+    #   The MCP dispatcher snapshots and restores this rather than
+    #   {#approval_gate}, so restoring never pins a parent's gate.
+    # @api private
+    def approval_gate_override
+      gate = @approval_gate
+      gate.is_a?(Parse::Agent::NullGate) && @approval_gate_defaulted ? nil : gate
+    end
 
     # @return [Boolean] true if the active cancellation token has been
     #   tripped; false otherwise. Returns false when no token is
@@ -1559,6 +1587,7 @@ module Parse
                    max_log_size: DEFAULT_MAX_LOG_SIZE,
                    system_prompt: nil, system_prompt_suffix: nil, pricing: nil,
                    tools: nil, methods: nil, classes: nil, filters: nil,
+                   fields: nil, field_names: nil,
                    parent: nil, recursion_depth: nil,
                    strict_tool_filter: nil, strict_class_filter: nil,
                    master_atlas: nil,
@@ -1731,8 +1760,10 @@ module Parse
         #
         #   * nil    — inherit from parent (the common case; the
         #              child wants whatever the parent had).
-        #   * true   — explicit opt-in (caller wants faceted_search
-        #              authority regardless of parent).
+        #   * true:  keep faceted_search authority. Allowed only when
+        #              the parent has it: a child cannot turn on
+        #              master-key faceting under a scoped parent, which
+        #              would return every row's buckets and results.
         #   * false  — explicit opt-OUT: the sub-agent should DROP
         #              faceted_search authority even if the parent
         #              had it. Previously `false` was the default
@@ -1748,6 +1779,13 @@ module Parse
         # per-row ACL via Parse::ACLScope's `_rperm` match and do
         # NOT consult master_atlas.
         master_atlas = parent.master_atlas if master_atlas.nil?
+        if master_atlas == true && !parent.master_atlas
+          raise ArgumentError,
+                "sub-agent master_atlas: true exceeds parent's master_atlas: false. " \
+                "A sub-agent cannot turn on master-key Atlas faceting its parent " \
+                "was not given. Omit master_atlas to inherit the parent's setting, " \
+                "or pass master_atlas: false."
+        end
 
         # Inherit cooperative cancellation surface. Without this, a
         # delegating tool that constructs a sub-agent and drives it
@@ -1759,6 +1797,9 @@ module Parse
         @cancellation_token = parent.cancellation_token
         @progress_callback = parent.progress_callback
         @log_callback = parent.log_callback
+        # Approval gate: delegate to the parent's current gate (see
+        # {#approval_gate}).
+        @approval_parent = parent
 
         # Clamp the sub-agent's permission tier at the parent's. The
         # default :readonly is always ≤ any parent tier, so this fires
@@ -2033,9 +2074,79 @@ module Parse
       @method_filter_only, @method_filter_except = normalize_method_filter(methods)
       @class_filter_only, @class_filter_except = normalize_class_filter(classes)
       @filters = normalize_query_filters(filters)
+      # Per-agent field narrowing (see Parse::Agent::FieldPolicy). Stored as
+      # layers so a sub-agent's policy INTERSECTS its parent's: every layer
+      # that names a class must permit a field for the agent to see it.
+      own_field_policy = normalize_field_policy(fields)
+      @field_policy_layers = (parent ? parent.field_policy_layers : []) +
+                             (own_field_policy ? [own_field_policy] : [])
+      @field_policy_layers.freeze
+      # Data-field naming mode (see Parse::Agent::FieldNames). A sub-agent
+      # inherits its parent's mode unless it sets one; naming never affects
+      # the access restrictions inherited above.
+      @field_names_mode = if field_names.nil?
+          parent ? parent.field_names_mode : :default
+        else
+          Parse::AggregationResult.normalize_field_names!(field_names)
+        end
+
+      # Sub-agent `tools:` inheritance: narrow only, same rule as `classes:`
+      # below. Intersect onlies, union excepts. A child `only:` that leaves
+      # nothing once the parent's allowlist and excepts apply raises; an
+      # explicitly empty `only: []` is the strictest narrowing and is kept.
+      if parent
+        parent_tools_only = parent.instance_variable_get(:@tool_filter_only)
+        parent_tools_except = parent.instance_variable_get(:@tool_filter_except)
+        requested_tools = @tool_filter_only
+        if parent_tools_only && @tool_filter_only
+          @tool_filter_only = (@tool_filter_only & parent_tools_only).freeze
+        elsif parent_tools_only
+          @tool_filter_only = parent_tools_only
+        end
+        if parent_tools_except
+          @tool_filter_except = (@tool_filter_except ? (@tool_filter_except | parent_tools_except) : parent_tools_except).freeze
+        end
+        if requested_tools && !requested_tools.empty? &&
+           (parent_tools_only || parent_tools_except)
+          reachable = @tool_filter_only - (@tool_filter_except || Set.new)
+          if reachable.empty?
+            raise ArgumentError,
+                  "sub-agent tools: { only: } would have no overlap with the parent's " \
+                  "tools: filter (parent only: #{parent_tools_only&.to_a&.sort.inspect}, " \
+                  "except: #{parent_tools_except&.to_a&.sort.inspect}; the child requested " \
+                  "#{requested_tools.to_a.sort.inspect}). A sub-agent cannot enable tools its " \
+                  "parent was not given. Pass a subset of the parent's tools, or omit tools: " \
+                  "to inherit the parent's filter."
+          end
+        end
+      end
 
-      # Sub-agent class-filter inheritance. Unlike `tools:` (which overrides
-      # outright), `classes:` clamps to the parent's effective set so a
+      # Sub-agent `methods:` inheritance. Entries can be bare (`:archive`) or
+      # qualified (`"Post.archive"`), so plain set intersection would get the
+      # matching wrong. Instead the parent's filters are kept as layers and
+      # {#method_filtered?} refuses a call any layer refuses. A child
+      # `only:` that no parent layer could permit raises; an explicitly
+      # empty `only: []` is kept.
+      @method_filter_layers = (parent ? parent.method_filter_layers : []).dup
+      if parent && @method_filter_only && !@method_filter_only.empty? && !@method_filter_layers.empty?
+        reachable = @method_filter_only.any? do |entry|
+          @method_filter_layers.all? { |layer_only, layer_except| method_entry_reachable?(entry, layer_only, layer_except) }
+        end
+        unless reachable
+          raise ArgumentError,
+                "sub-agent methods: { only: } would have no overlap with the parent's " \
+                "methods: filter (child requested #{@method_filter_only.to_a.map(&:to_s).sort.inspect}). " \
+                "A sub-agent cannot call agent methods its parent was not given. Pass a " \
+                "subset of the parent's methods, or omit methods: to inherit them."
+        end
+      end
+      if @method_filter_only || @method_filter_except
+        @method_filter_layers << [@method_filter_only, @method_filter_except].freeze
+      end
+      @method_filter_layers.freeze
+
+      # Sub-agent class-filter inheritance. Like `tools:` above,
+      # `classes:` clamps to the parent's effective set so a
       # sub-agent can NEVER widen its parent's data-reach. Intersect onlies,
       # union excepts. A child `only:` that would have no overlap with the
       # parent's effective set raises at construction — empty-onlyset means
@@ -2233,29 +2344,77 @@ module Parse
     #
     # An entry matches the invocation if it equals either the bare
     # method name (`:archive`) or the qualified form (`"Class.archive"`).
+    # The class part is compared by its Parse class name on both sides, so
+    # `"User.reset"` and `"_User.reset"` name the same method whichever
+    # spelling the entry or the caller used.
     #
     # @param method_name [Symbol, String]
     # @param class_name  [String]
     # @return [Boolean] true if filtered (refuse), false if permitted
     def method_filtered?(method_name, class_name:)
-      return false if @method_filter_only.nil? && @method_filter_except.nil?
-
       method_sym = method_name.to_sym
-      qualified = "#{class_name}.#{method_name}"
+      parse_class = Parse::Agent.canonical_method_class(class_name)
 
-      if @method_filter_only
-        permitted = @method_filter_only.include?(method_sym) ||
-                    @method_filter_only.include?(qualified)
-        return true unless permitted
+      # A sub-agent carries its parent's filters as earlier layers; its own
+      # filter is the last layer. Any layer can refuse.
+      method_filter_layers.any? do |only, except|
+        (only && !method_entry_matches?(only, method_sym, parse_class)) ||
+          (except && method_entry_matches?(except, method_sym, parse_class))
       end
+    end
 
-      if @method_filter_except
-        excluded = @method_filter_except.include?(method_sym) ||
-                   @method_filter_except.include?(qualified)
-        return true if excluded
-      end
+    # The Parse class name for the class part of a qualified `methods:`
+    # entry or a `call_method` class argument: `"User"` and `"_User"`
+    # both give `"_User"`. A name that resolves to no model is returned
+    # unchanged.
+    # @api private
+    # @param name [String, Class]
+    # @return [String]
+    def self.canonical_method_class(name)
+      return name.parse_class if name.is_a?(Class) && name.respond_to?(:parse_class)
+      str = name.to_s
+      klass = resolve_method_filter_class(str)
+      klass ? klass.parse_class : str
+    end
 
-      false
+    # Ruby constant names a `methods:` entry may use for a model whose Parse
+    # class name differs (`class Artist < Parse::Object; parse_class
+    # "Musician"; end`).
+    RUBY_CONSTANT_NAME_RE = /\A[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*\z/
+
+    # @!visibility private
+    # The Parse::Object subclass a `methods:` class name refers to, by
+    # Parse class name first and then by Ruby constant name, or nil.
+    def self.resolve_method_filter_class(str)
+      klass = begin
+          Parse::Model.find_class(str)
+        rescue StandardError
+          nil
+        end
+      return klass if klass.is_a?(Class) && klass < Parse::Object
+      return nil unless str.match?(RUBY_CONSTANT_NAME_RE)
+      klass = begin
+          Object.const_get(str)
+        rescue StandardError, LoadError
+          nil
+        end
+      klass.is_a?(Class) && klass < Parse::Object ? klass : nil
+    end
+
+    # @return [Array<Array(Set, Set)>] the `methods:` filters in effect as
+    #   `[only, except]` pairs, own filter last; a sub-agent carries its
+    #   parent's layers first.
+    def method_filter_layers
+      @method_filter_layers || []
+    end
+
+    # @return [Array<Hash>] {#method_filter_layers} as `{only:, except:}`
+    #   hashes of sorted name strings (nil when a layer has no such list),
+    #   parent layers first. Used by the audit payload and {#describe}.
+    def method_filter_layers_descriptor
+      method_filter_layers.map do |only, except|
+        { only: only && only.to_a.map(&:to_s).sort, except: except && except.to_a.map(&:to_s).sort }
+      end
     end
 
     # @return [Boolean] whether unknown names in tools: raise vs. warn at
@@ -2487,6 +2646,15 @@ module Parse
       payload[:tools_except] = @tool_filter_except.to_a.sort if @tool_filter_except
       payload[:methods_only] = @method_filter_only.to_a.map(&:to_s).sort if @method_filter_only
       payload[:methods_except] = @method_filter_except.to_a.map(&:to_s).sort if @method_filter_except
+      # `methods_only` / `methods_except` are this agent's own filter. A
+      # sub-agent is also bound by its parent's filters, so the full set in
+      # force is emitted as layers (parent first) whenever any layer was
+      # inherited, including a single parent layer on a child with no
+      # filter of its own.
+      own_method_layers = (@method_filter_only || @method_filter_except) ? 1 : 0
+      if method_filter_layers.size > own_method_layers
+        payload[:methods_layers] = method_filter_layers_descriptor
+      end
       # Per-agent per-class filters — emit class-name → field-name list,
       # NOT the constraint values. Filter values can contain user-identifying
       # data (`{ user_id: "abc123" }`, `{ org_id: tenant_uuid }`) that
@@ -3373,7 +3541,44 @@ module Parse
     # strings (qualified-class.method match).
     def normalize_method_filter_entry(value)
       str = value.to_s
-      str.include?(".") ? str : str.to_sym
+      return str.to_sym unless str.include?(".")
+      class_part, method_part = str.split(".", 2)
+      if Parse::Agent.resolve_method_filter_class(class_part).nil?
+        warn "[Parse::Agent] methods: entry #{str.inspect} names a class that does not " \
+             "resolve to a loaded Parse::Object model (by Parse class name or Ruby " \
+             "constant). It is matched by its class part as written; check the spelling."
+      end
+      "#{Parse::Agent.canonical_method_class(class_part)}.#{method_part}"
+    end
+
+    # Whether a `methods:` filter set names this invocation, either bare or
+    # qualified. Qualified entries are compared by Parse class name, which
+    # also covers an entry whose class was not loaded at construction.
+    def method_entry_matches?(set, method_sym, parse_class)
+      return true if set.include?(method_sym) || set.include?("#{parse_class}.#{method_sym}")
+      set.any? do |entry|
+        next false unless entry.is_a?(String)
+        class_part, method_part = entry.split(".", 2)
+        method_part == method_sym.to_s && Parse::Agent.canonical_method_class(class_part) == parse_class
+      end
+    end
+
+    # Whether a child `methods:` only-entry could pass one parent layer.
+    # A qualified entry ("Post.archive") passes when the layer names it or
+    # its bare method. A bare entry (:archive) passes when the layer names
+    # it bare or qualified on any class.
+    def method_entry_reachable?(entry, layer_only, layer_except)
+      if entry.is_a?(String)
+        bare = entry.split(".", 2).last.to_sym
+        return false if layer_except && (layer_except.include?(entry) || layer_except.include?(bare))
+        return true unless layer_only
+        layer_only.include?(entry) || layer_only.include?(bare)
+      else
+        return false if layer_except&.include?(entry)
+        return true unless layer_only
+        layer_only.include?(entry) ||
+          layer_only.any? { |e| e.is_a?(String) && e.split(".", 2).last == entry.to_s }
+      end
     end
 
     # Normalize the constructor's `classes:` kwarg into a [only_set,
@@ -3428,6 +3633,49 @@ module Parse
     # lookup re-expands the variants and accepts both forms symmetrically.
     #
     # @return [Hash, nil] frozen Hash or nil when no filters declared
+    # Normalize the constructor's `fields:` kwarg: a Hash mapping class
+    # identifiers (Class, String, Symbol, or :default) to an Array of field
+    # names. Keys canonicalize like `filters:` so `Parse::User` matches both
+    # "_User" and "User". Field names may be Ruby property names or wire
+    # names; they are translated to wire form at lookup time.
+    def normalize_field_policy(fields)
+      return nil if fields.nil?
+      unless fields.is_a?(Hash)
+        raise ArgumentError,
+              "fields: must be a Hash mapping class identifiers (or :default) " \
+              "to Arrays of field names, got #{fields.class}"
+      end
+      result = {}
+      fields.each do |key, names|
+        unless names.is_a?(Array) && names.all? { |n| n.is_a?(String) || n.is_a?(Symbol) }
+          raise ArgumentError,
+                "fields[#{key.inspect}]: value must be an Array of field names, got #{names.inspect}"
+        end
+        field_policy_keys(key).each { |canon| result[canon] = names.map(&:to_s).freeze }
+      end
+      result.freeze
+    end
+
+    # Canonical lookup names for a `fields:` key. Tools look policies up by
+    # the class's Parse name (`_User`, or a custom `parse_class`), so a
+    # String or Symbol key is resolved through Parse::Model.find_class to
+    # that name as well as kept verbatim; otherwise `fields: { "User" => ... }`
+    # would silently fail to narrow `_User`.
+    def field_policy_keys(key)
+      keys = canonical_filter_key(key)
+      if key.is_a?(String) || key.is_a?(Symbol)
+        klass = (Parse::Model.find_class(key.to_s) rescue nil)
+        if klass.respond_to?(:parse_class)
+          keys |= [klass.parse_class.to_s]
+          if defined?(Parse::Agent::MetadataRegistry) &&
+             Parse::Agent::MetadataRegistry.respond_to?(:hidden_name_variants_for)
+            keys |= Parse::Agent::MetadataRegistry.hidden_name_variants_for(klass)
+          end
+        end
+      end
+      keys
+    end
+
     def normalize_query_filters(filters)
       return nil if filters.nil?
       unless filters.is_a?(Hash)
@@ -3567,6 +3815,35 @@ module Parse
     #
     # @param class_name [String, Symbol, Class]
     # @return [Boolean]
+    # @return [Array<Hash>] the per-agent `fields:` policies in effect, own
+    #   policy last; a sub-agent carries its parent's layers first. Each
+    #   layer maps a canonical class name (or :default) to raw field names.
+    attr_reader :field_policy_layers
+
+    # @return [Symbol] `:default` or `:server`; see {Parse::Agent::FieldNames}.
+    attr_reader :field_names_mode
+
+    # Wire-format field names this agent narrows `class_name` to, or nil when
+    # no `fields:` layer names the class (or a :default). Every layer that
+    # applies must permit a field, so a sub-agent can never widen its
+    # parent. The result is intersected with the class's `agent_fields`
+    # ceiling by {Parse::Agent::MetadataRegistry.field_allowlist}.
+    #
+    # @param class_name [String, Class]
+    # @return [Array<String>, nil]
+    def field_narrowing_for(class_name)
+      return nil if @field_policy_layers.nil? || @field_policy_layers.empty?
+      cn = class_name.respond_to?(:parse_class) ? class_name.parse_class.to_s : class_name.to_s
+      result = nil
+      @field_policy_layers.each do |layer|
+        names = layer[cn] || layer[:default]
+        next if names.nil?
+        wire = Parse::Agent::MetadataRegistry.wire_field_names(cn, names)
+        result = result ? (result & wire) : wire
+      end
+      result
+    end
+
     def class_filter_permits?(class_name)
       return true if @class_filter_only.nil? && @class_filter_except.nil?
       candidates = class_name_variants_for(class_name)

data/lib/parse/api/batch.rb

@@ -26,7 +26,16 @@ module Parse
           batch_operations = Parse::BatchOperation.new batch_operations
         end
         response = request(:post, "batch", body: batch_operations.as_json)
-        response.success? && response.batch? ? response.batch_responses : response
+        return response.batch_responses if response.success? && response.batch?
+        return response if response.error?
+        # A successful HTTP response whose body is not an array of results
+        # cannot be matched to the submitted requests. Report it as a failure
+        # rather than as a batch where every write landed.
+        Parse::Response.error_response(
+          Parse::Response::ERROR_INTERNAL,
+          "Malformed batch response: expected an array of results",
+          http_status: response.http_status,
+        ).tap { |r| r.request = response.request }
       end
     end
   end

data/lib/parse/api/schema.rb

@@ -8,11 +8,19 @@ module Parse
       # @!visibility private
       SCHEMAS_PATH = "schemas"
 
+      # Parse Server serves `/schemas` to the master key only. Every call
+      # here therefore asks for the master key explicitly (outside client
+      # mode), which also stops an ambient `Parse.with_session` token or a
+      # client-bound token from being attached in its place. With a session token attached the request was
+      # refused with 403, and callers that cache the class permissions (the
+      # CLP scope used by mongo-direct queries) then denied a direct query
+      # that the master-keyed client was entitled to run.
+
       # Get all the schemas for the application.
       # @param opts [Hash] additional options for the request.
       # @return [Parse::Response]
       def schemas(opts = {})
-        request_opts = { cache: false }.merge(opts)
+        request_opts = { cache: false }.merge(schema_auth_opts).merge(opts)
         request :get, SCHEMAS_PATH, opts: request_opts
       end
 
@@ -21,7 +29,7 @@ module Parse
       # @return [Parse::Response]
       def schema(className)
         safe = Parse::API::PathSegment.identifier!(className, kind: "class name")
-        opts = { cache: false }
+        opts = { cache: false }.merge(schema_auth_opts)
         request :get, "#{SCHEMAS_PATH}/#{safe}", opts: opts
       end
 
@@ -32,7 +40,7 @@ module Parse
       # @return [Parse::Response]
       def create_schema(className, schema)
         safe = Parse::API::PathSegment.identifier!(className, kind: "class name")
-        request :post, "#{SCHEMAS_PATH}/#{safe}", body: schema
+        request :post, "#{SCHEMAS_PATH}/#{safe}", body: schema, opts: schema_auth_opts
       end
 
       # Update the schema for a collection.
@@ -42,7 +50,18 @@ module Parse
       # @return [Parse::Response]
       def update_schema(className, schema)
         safe = Parse::API::PathSegment.identifier!(className, kind: "class name")
-        request :put, "#{SCHEMAS_PATH}/#{safe}", body: schema
+        request :put, "#{SCHEMAS_PATH}/#{safe}", body: schema, opts: schema_auth_opts
+      end
+
+      private
+
+      # Ask for the master key explicitly, except under `Parse.client_mode`,
+      # whose contract is that the SDK never sends the master key on its own
+      # initiative. A client with no master key configured sends none either
+      # way.
+      # @!visibility private
+      def schema_auth_opts
+        { use_master_key: !Parse.client_mode }
       end
     end #Schema
   end #API

data/lib/parse/api/sessions.rb

@@ -13,8 +13,12 @@ module Parse
       # @param opts [Hash] additional options to pass to the {Parse::Client} request.
       # @return [Parse::Response]
       def fetch_session(session_token, **opts)
-        opts.merge!({ use_master_key: false, cache: false })
-        headers = { Parse::Protocol::SESSION_TOKEN => session_token }
+        # The positional token is passed as the explicit per-call token so an
+        # ambient `Parse.with_session` token or a client-bound token cannot
+        # replace it and return another user's session.
+        session_token = session_token.session_token if session_token.respond_to?(:session_token)
+        opts = opts.merge({ use_master_key: false, cache: false, session_token: session_token.to_s })
+        headers = { Parse::Protocol::SESSION_TOKEN => session_token.to_s }
         response = request :get, "#{SESSION_PATH_PREFIX}/me", headers: headers, opts: opts
         response.parse_class = Parse::Model::CLASS_SESSION
         response