parse-stack-next 5.8.0 → 5.8.2

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
@@ -845,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

data/lib/parse/agent/constraint_translator.rb

@@ -117,17 +117,16 @@ module Parse
       # worst-case backtracking cost on any one pattern bounded.
       MAX_REGEX_PATTERN_LENGTH = 256
 
-      # Allowed $options flag characters. MongoDB accepts i (case
-      # insensitive), m (multi-line), x (extended/whitespace-ignored),
-      # s (dot-all). The dot-all `s` flag is intentionally omitted: it
-      # makes `.` cross newlines, which extends the search frontier on
-      # multi-line text fields and amplifies catastrophic-backtracking
-      # cost for the worst patterns. `imx` covers every real use case
-      # the agent surface needs.
-      ALLOWED_REGEX_OPTIONS = "imx"
-
-      # Heuristic for nested-quantifier ReDoS patterns (catastrophic
-      # backtracking). Matches a quantifier (`+` or `*`) INSIDE a
+      # Allowed $options flag characters: the shared
+      # {Parse::RegexSecurity::ALLOWED_OPTIONS} list (`imsu`). The extended
+      # flag `x` is refused because it lets comments hide a quantifier from
+      # the pattern check.
+      ALLOWED_REGEX_OPTIONS = defined?(Parse::RegexSecurity::ALLOWED_OPTIONS) ? Parse::RegexSecurity::ALLOWED_OPTIONS : "imsu"
+
+      # Older heuristic for nested-quantifier ReDoS patterns, kept for
+      # callers that reference it. Patterns are now checked by
+      # {Parse::RegexSecurity.validate!}, which parses the pattern. This
+      # heuristic matches a quantifier (`+` or `*`) INSIDE a
       # parenthesized group that is itself followed by a quantifier
       # (`+`, `*`, or `?`) — the structural shape that drives
       # exponential time on adversarial inputs (`(a+)+`, `(a*)*`,
@@ -435,15 +434,17 @@ module Parse
       #
       #   1. $regex must be a String. No Hash/Array/Numeric values.
       #   2. Pattern length ≤ MAX_REGEX_PATTERN_LENGTH (256 chars).
-      #   3. Pattern must not match the nested-quantifier heuristic
-      #      (REDOS_NESTED_QUANTIFIER_RE).
+      #   3. Pattern must pass Parse::RegexSecurity.validate!, which
+      #      parses it and refuses repeated groups holding a quantifier,
+      #      alternation, or backreference, inline comments, and extended
+      #      mode.
       #
       # For $options:
       #
       #   1. Must be a String.
       #   2. Length ≤ 8 (defensive — real-world usage is 0-3 chars).
-      #   3. Every character must appear in ALLOWED_REGEX_OPTIONS (imx).
-      #      The `s` (dot-all) flag is intentionally rejected.
+      #   3. Every character must appear in ALLOWED_REGEX_OPTIONS (imsu).
+      #      The extended `x` flag is rejected.
       #
       # @raise [ConstraintSecurityError] on any rule violation.
       def assert_regex_operand_safe!(op, val)
@@ -465,12 +466,12 @@ module Parse
               reason: :regex_too_long,
             )
           end
-          if REDOS_NESTED_QUANTIFIER_RE.match?(val)
+          unless Parse::RegexSecurity.safe?(val, max_length: MAX_REGEX_PATTERN_LENGTH)
             raise ConstraintSecurityError.new(
               "$regex pattern #{val.inspect} contains a nested quantifier " \
-              "(`(...x+...)+` shape) that can trigger catastrophic " \
-              "backtracking on MongoDB's PCRE engine. Rewrite the pattern " \
-              "without nested quantifier groups.",
+              "or another backtracking-prone construct that can trigger " \
+              "catastrophic backtracking on MongoDB's PCRE engine. Rewrite " \
+              "the pattern without nested quantifier groups.",
               operator: op,
               reason: :regex_redos,
             )
@@ -495,8 +496,8 @@ module Parse
             raise ConstraintSecurityError.new(
               "$options contains disallowed flag(s) " \
               "#{unrecognized.uniq.inspect}. Allowed flags: " \
-              "#{ALLOWED_REGEX_OPTIONS.chars.inspect}. The dot-all " \
-              "`s` flag is intentionally rejected.",
+              "#{ALLOWED_REGEX_OPTIONS.chars.inspect}. The extended " \
+              "`x` flag is rejected.",
               operator: op,
               reason: :invalid_regex,
             )

data/lib/parse/agent/describe.rb

@@ -176,7 +176,8 @@ module Parse
           tenant_id: tenant_id,
           classes: filter_descriptor(@class_filter_only, @class_filter_except),
           tools: tools_descriptor,
-          methods: filter_descriptor(@method_filter_only, @method_filter_except, transform: ->(s) { s.to_s }),
+          methods: filter_descriptor(@method_filter_only, @method_filter_except, transform: ->(s) { s.to_s })
+            .merge(layers: method_filter_layers_descriptor),
           filters: per_agent_filters_summary,
           hidden_classes: Parse::Agent::MetadataRegistry.hidden_class_names,
           per_class: per_class_descriptor,
@@ -383,10 +384,15 @@ module Parse
         lines << "    except:    #{data[:tools][:except].inspect}" if data[:tools][:except]
         lines << "    effective: #{data[:tools][:effective].inspect}"
 
-        if data[:methods][:only] || data[:methods][:except]
+        inherited_layers = Array(data[:methods][:layers])[0...-1] if data[:methods][:only] || data[:methods][:except]
+        inherited_layers ||= Array(data[:methods][:layers])
+        if data[:methods][:only] || data[:methods][:except] || inherited_layers.any?
           lines << "  methods:"
           lines << "    only:    #{data[:methods][:only].inspect}" if data[:methods][:only]
           lines << "    except:  #{data[:methods][:except].inspect}" if data[:methods][:except]
+          inherited_layers.each do |layer|
+            lines << "    inherited: #{layer.compact.inspect}"
+          end
         end
 
         if data[:filters]

data/lib/parse/agent/errors.rb

@@ -89,6 +89,23 @@ module Parse
       end
     end
 
+    # Raised when a session-token agent needs its resolved claim set (for
+    # the SDK-side CLP check, an ACL `$match`, or a sub-agent subset check)
+    # but the token could not be resolved. A session agent is never treated
+    # as master-key posture just because its token did not resolve: the
+    # check fails closed instead. A subclass of {AccessDenied}, so tool
+    # dispatch reports it as an `:access_denied` refusal
+    # (`kind: :unresolved_identity`).
+    class UnresolvedIdentity < AccessDenied
+      def initialize(message = nil)
+        super(nil, message || "This agent's session could not be resolved, so its " \
+                              "permissions cannot be checked. The request was refused " \
+                              "rather than run without them; retry once Parse Server is " \
+                              "reachable, or rebuild the agent with a valid session token.",
+              kind: :unresolved_identity)
+      end
+    end
+
     # Authentication failure for MCP transport adapters. Custom auth blocks
     # passed to Parse::Agent::MCPRackApp should raise this (or a subclass) to
     # signal an unauthenticated/unauthorized request; the transport layer

data/lib/parse/agent/mcp_dispatcher.rb

@@ -229,7 +229,14 @@ 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)
+        # Snapshot the agent's OWN gate, not the effective one: a sub-agent
+        # with no gate of its own reads its parent's, and restoring that
+        # copy would pin it and stop the delegation.
+        prev_approval_gate = if agent.respond_to?(:approval_gate_override)
+            agent.approval_gate_override
+          elsif agent.respond_to?(:approval_gate)
+            agent.approval_gate
+          end
         prev_log_callback = agent.log_callback if agent.respond_to?(:log_callback)
 
         # Install the progress callback and cancellation token on the

data/lib/parse/agent/mcp_server.rb

@@ -115,6 +115,32 @@ module Parse
       # Loopback hosts that are safe to bind to without an API key.
       LOOPBACK_HOSTS = %w[127.0.0.1 ::1 localhost].freeze
 
+      # Shortest API key accepted for a non-loopback bind.
+      MIN_PUBLIC_API_KEY_LENGTH = 16
+
+      # The API key to enforce, or nil when none is configured. Surrounding
+      # whitespace (ASCII or Unicode) is stripped, and a blank result is no
+      # key.
+      # @param key [String, nil]
+      # @return [String, nil]
+      # Strip leading and trailing whitespace of any kind (ASCII or Unicode)
+      # with a linear scan from each end.
+      # @param str [String]
+      # @return [String]
+      def self.strip_unicode_space(str)
+        first = 0
+        last = str.length
+        first += 1 while first < last && str[first].match?(/[[:space:]]/)
+        last -= 1 while last > first && str[last - 1].match?(/[[:space:]]/)
+        str[first...last]
+      end
+
+      def self.normalize_api_key(key)
+        return nil if key.nil?
+        stripped = strip_unicode_space(key.to_s)
+        stripped.empty? ? nil : stripped
+      end
+
       def initialize(port: 3001, host: "127.0.0.1", permissions: :readonly,
                      session_token: nil, api_key: nil, rate_limiter: nil,
                      pre_auth_rate_limiter: nil,
@@ -126,7 +152,15 @@ module Parse
           raise ArgumentError, "pre_auth_rate_limiter must respond to #check!"
         end
 
-        effective_api_key = api_key || ENV["MCP_API_KEY"]
+        # One normalization for every check below: surrounding whitespace is
+        # stripped and a key that is empty after stripping counts as no key.
+        # A whitespace-only key used to pass the non-loopback bind check
+        # (`"   ".to_s.empty?` is false) and then disable request auth
+        # (`"   ".present?` is false), leaving a public endpoint open.
+        # An explicit blank `api_key:` does not hide a configured
+        # MCP_API_KEY.
+        effective_api_key = self.class.normalize_api_key(api_key) ||
+                            self.class.normalize_api_key(ENV["MCP_API_KEY"])
 
         # NEW-MCP-1: a non-loopback bind without an API key is an unauthenticated
         # network-exposed JSON-RPC endpoint. Refuse to start. Operators who
@@ -134,12 +168,19 @@ module Parse
         # auth — should bind to localhost and let the proxy forward, or
         # set MCP_API_KEY explicitly even when "the proxy authenticates"
         # (defense in depth).
-        if !LOOPBACK_HOSTS.include?(host.to_s) && effective_api_key.to_s.empty?
+        if !LOOPBACK_HOSTS.include?(host.to_s) && effective_api_key.nil?
           raise ArgumentError,
                 "MCPServer refuses to bind non-loopback host #{host.inspect} without an api_key. " \
                 "Set MCP_API_KEY in the environment, pass api_key: explicitly, or use a loopback " \
                 "host (one of: #{LOOPBACK_HOSTS.join(", ")})."
         end
+        # A short key on a public bind is guessable. Warn rather than refuse
+        # in a patch release so existing deployments keep starting.
+        if !LOOPBACK_HOSTS.include?(host.to_s) && effective_api_key.length < MIN_PUBLIC_API_KEY_LENGTH
+          warn "[Parse::Agent::MCPServer:SECURITY] api_key for non-loopback host #{host.inspect} " \
+               "is shorter than #{MIN_PUBLIC_API_KEY_LENGTH} characters. Use a long random key " \
+               "(for example SecureRandom.hex(32))."
+        end
 
         @port = port
         @host = host
@@ -250,8 +291,8 @@ module Parse
 
         # Tool list endpoint (requires auth if API key is configured)
         @server.mount_proc("/tools") do |req, res|
-          if @api_key.present?
-            provided_key = req[MCP_API_KEY_HEADER].to_s
+          if @api_key
+            provided_key = self.class.normalize_api_key(req[MCP_API_KEY_HEADER]).to_s
             unless ActiveSupport::SecurityUtils.secure_compare(@api_key, provided_key)
               error_response(res, 401, "Unauthorized: invalid or missing API key")
               next
@@ -353,8 +394,8 @@ module Parse
       # counters on each returned agent are scoped to that single request
       # and discarded when it ends, eliminating cross-request leakage.
       def agent_factory(env)
-        if @api_key.present?
-          provided_key = env["HTTP_X_MCP_API_KEY"].to_s
+        if @api_key
+          provided_key = self.class.normalize_api_key(env["HTTP_X_MCP_API_KEY"]).to_s
           unless ActiveSupport::SecurityUtils.secure_compare(@api_key, provided_key)
             raise Parse::Agent::Unauthorized.new("invalid or missing API key", reason: :bad_api_key)
           end