Release parse-stack v4.2.0: security & agent

Bump to v4.2.0 with extensive security hardening, new MCP agent features, streaming/cancellation support, and quality-of-life fixes.

Highlights:
- Mass-assignment hardening: constructor filters protected keys by default and adds a trusted: kwarg to allow internal hydration.
- Push/audience safety: strict errors for missing audiences, broadcast opt-in, and new error classes to avoid accidental global pushes.
- Pipeline / AtlasSearch / LookupRewriter hardening: disallow forensic $expr operators, denylist internal underscore collections in lookups, validate embedded AtlasSearch operators, and strip internal fields from results.
- Query DSL robustness: stricter validation/coercion for order, limit, skip, and first to avoid silent misbehavior.
- Agent/MCP improvements: per-instance tools/method filters, parent/recursion depth, strict filtering options, tool output schemas, progress reporting, cooperative cancellation, improved MCP protocol handling, pre-auth rate limiting, and richer audit metadata.
- Webhooks: exact Content-Type validation, replay protection (dedup LRU + optional HMAC timestamped signatures), and SSRF-safe webhook URL checks for registrations.
- Agent tools hardening: prevent builtin shadowing, enforce field allowlists on lookups and exports, and safer serialization/redaction of returned objects.
- MFA and role fixes: safer MFA setup/disable flows with authorization checks and prevention of role self-references; clarified role-hierarchy docs and added integration test.
- Misc: header redaction fixes for logging, keyword-arg forwarding fixes under Ruby 3, docs and CLI tweaks, and added tests for many new behaviors.

This release focuses on closing several fail-open attack surfaces and adding defensive APIs and runtime guards, while improving MCP streaming and operator auditability.

Author: AdrianCurtin

CHANGELOG.md

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    parse-stack (4.1.2)
+    parse-stack (4.2.0)
       activemodel (>= 6.1, < 9)
       activesupport (>= 6.1, < 9)
       faraday (~> 2.0)

Gemfile.lock

@@ -364,7 +364,7 @@ namespace :mcp do
   #   /trace   — toggle tool-call tracing on/off
   #   /cost    — show running token + USD cost totals
   #   /history — print conversation history
-  #   /exit    — leave the chat (also: /quit, Ctrl-D, empty line)
+  #   /exit    — leave the chat (also: /quit, exit, quit, Ctrl-D, empty line)
   # -------------------------------------------------------------------------
   desc "Conversational CLI: talk to your Parse data via the MCP agent"
   task :chat do
@@ -404,7 +404,7 @@ namespace :mcp do
       puts "  /trace   — toggle per-turn tool-call tracing on/off"
       puts "  /cost    — show running token + USD totals (and last turn)"
       puts "  /history — print the conversation log"
-      puts "  /exit    — leave (also /quit, Ctrl-D, empty line)"
+      puts "  /exit    — leave (also /quit, exit, quit, Ctrl-D, empty line)"
     end
 
     puts "=" * 70
@@ -421,7 +421,7 @@ namespace :mcp do
       next if line.empty?
 
       case line
-      when "/exit", "/quit"
+      when "/exit", "/quit", "exit", "quit"
         break
       when "/help"
         slash_help.call

Rakefile

@@ -0,0 +1,80 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  class Agent
+    # Cooperative cancellation token used by Parse::Agent::MCPDispatcher
+    # and Parse::Agent::MCPRackApp to signal in-flight tool calls that the
+    # client wants to stop work.
+    #
+    # The token is cooperative — tools must poll `cancelled?` at safe
+    # checkpoints (tool entry, after each Parse/Mongo roundtrip,
+    # between chunks). A tool that is blocked inside a synchronous I/O
+    # call will not observe the cancellation until the I/O returns.
+    # The Ruby-level `Timeout.timeout` already wrapping every tool call
+    # remains the hard upper bound on wasted work.
+    #
+    # Cancellation is triggered from two paths:
+    #
+    # 1. **SSE client disconnect.** `MCPRackApp::SSEBody#close` invokes
+    #    `cancel!(reason: :client_disconnect)` on the token before
+    #    killing the worker thread.
+    # 2. **`notifications/cancelled` JSON-RPC notification.** A separate
+    #    POST whose `params.requestId` matches an in-flight request
+    #    trips the token associated with that request (after a session
+    #    identity check — see MCPRackApp for details).
+    #
+    # @example Polling at a checkpoint
+    #   def my_tool(agent, **)
+    #     return cancelled_result if agent.cancelled?
+    #     data = expensive_io_call
+    #     return cancelled_result if agent.cancelled?
+    #     transform_and_return(data)
+    #   end
+    #
+    # @example Operator-facing cancel
+    #   token = Parse::Agent::CancellationToken.new
+    #   agent.cancellation_token = token
+    #   # later, from another thread:
+    #   token.cancel!(reason: :user_requested)
+    class CancellationToken
+      # @return [Symbol, String, nil] reason supplied to {#cancel!}, or nil
+      #   if the token has not been cancelled.
+      attr_reader :reason
+
+      def initialize
+        @cancelled = false
+        @reason    = nil
+        # Mutex protects the read-modify-write in {#cancel!} so a
+        # concurrent cancel from notifications/cancelled and client
+        # disconnect cannot lose a reason or partially update state.
+        # The hot poll path (#cancelled?) reads the boolean ivar
+        # directly — atomic on MRI and on each major Ruby
+        # implementation we ship against.
+        @mutex     = Mutex.new
+      end
+
+      # @return [Boolean] true once {#cancel!} has been called at least once.
+      def cancelled?
+        @cancelled
+      end
+
+      # Trip the token. Idempotent — subsequent calls are no-ops and do
+      # not overwrite the original reason.
+      #
+      # @param reason [Symbol, String, nil] short tag identifying the
+      #   trigger (e.g. `:client_disconnect`, `:notifications_cancelled`,
+      #   `:user_requested`).
+      # @return [Boolean] true if this call actually flipped the state,
+      #   false if the token was already cancelled.
+      def cancel!(reason: nil)
+        @mutex.synchronize do
+          return false if @cancelled
+          @cancelled = true
+          @reason    = reason
+          true
+        end
+      end
+    end
+  end
+end

docs/mcp_guide.md

@@ -82,6 +82,34 @@ def initialize(message, operator: nil)
       # Maximum query depth to prevent DoS via deeply nested structures
       MAX_QUERY_DEPTH = 8
 
+      # NEW-TOOLS-7: cap $regex pattern length. Patterns larger than this
+      # are rejected before reaching MongoDB. 256 is generous for the
+      # legitimate analyst-facing patterns the agent surface is designed
+      # for (prefix anchors, simple character classes) while keeping the
+      # 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
+      # parenthesized group that is itself followed by a quantifier
+      # (`+`, `*`, or `?`) — the structural shape that drives
+      # exponential time on adversarial inputs (`(a+)+`, `(a*)*`,
+      # `(x|y)+?` are all reachable). Stricter than the audit's
+      # suggested heuristic, which would false-positive on innocuous
+      # patterns like `^foo.*bar.*$`. Anchored prefixes without
+      # nested-quantifier-groups (`^bar(a+)+` is still refused; plain
+      # `^foo.*` is not).
+      REDOS_NESTED_QUANTIFIER_RE = /\([^)]*[+*][^)]*\)[+*?]/.freeze
+
       # Translate JSON constraints to Parse query format.
       # Validates all operators against the security whitelist.
       #
@@ -149,6 +177,9 @@ def translate_hash_value(hash, depth:)
         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)
                          else
@@ -237,6 +268,86 @@ def parse_type?(hash)
         %w[Pointer Date File GeoPoint Bytes Polygon Relation].include?(type)
       end
 
+      # NEW-TOOLS-7: validate $regex / $options operands.
+      #
+      # MongoDB's regex engine is PCRE (not RE2), so adversarial patterns
+      # with nested quantifiers (`(a+)+`, `(a*)*`, `(.|.)+`) cause
+      # catastrophic backtracking — quadratic-to-exponential matching
+      # cost per document. The agent surface lacks a per-pattern
+      # complexity gate at the Mongo level, so refuse the worst shapes
+      # at the SDK boundary. Three checks:
+      #
+      #   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).
+      #
+      # 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.
+      #
+      # @raise [ConstraintSecurityError] on any rule violation.
+      def assert_regex_operand_safe!(op, val)
+        if op == "$regex"
+          unless val.is_a?(String)
+            raise ConstraintSecurityError.new(
+              "$regex value must be a String (got #{val.class})",
+              operator: op,
+              reason: :invalid_regex,
+            )
+          end
+          if val.length > MAX_REGEX_PATTERN_LENGTH
+            raise ConstraintSecurityError.new(
+              "$regex pattern length #{val.length} exceeds " \
+              "#{MAX_REGEX_PATTERN_LENGTH} character cap. " \
+              "Narrow the pattern (e.g. anchored prefix `^xyz`) or filter " \
+              "via a non-regex constraint.",
+              operator: op,
+              reason: :regex_too_long,
+            )
+          end
+          if REDOS_NESTED_QUANTIFIER_RE.match?(val)
+            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.",
+              operator: op,
+              reason: :regex_redos,
+            )
+          end
+        elsif op == "$options"
+          unless val.is_a?(String)
+            raise ConstraintSecurityError.new(
+              "$options value must be a String (got #{val.class})",
+              operator: op,
+              reason: :invalid_regex,
+            )
+          end
+          if val.length > 8
+            raise ConstraintSecurityError.new(
+              "$options string is suspiciously long (#{val.length} chars).",
+              operator: op,
+              reason: :invalid_regex,
+            )
+          end
+          unrecognized = val.chars.reject { |c| ALLOWED_REGEX_OPTIONS.include?(c) }
+          unless unrecognized.empty?
+            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.",
+              operator: op,
+              reason: :invalid_regex,
+            )
+          end
+        end
+      end
+
       # Validate an operator is allowed (strict whitelist enforcement).
       #
       # @param op [String] the operator to validate

lib/parse/agent.rb

@@ -64,5 +64,33 @@ def initialize(message = "Unauthorized", reason: nil)
         super(message)
       end
     end
+
+    # Raised at construction when an agent built with `parent:` would
+    # exceed the inherited recursion depth budget. Defends against
+    # delegate_to_subagent (or any tool that constructs a Parse::Agent
+    # inside its handler) recursing without bound.
+    #
+    # The budget is decremented on every inherited construction; the
+    # zero-floor agent can still execute its own tools, but constructing
+    # another sub-agent with `parent: zero_floor_agent` raises this error.
+    class RecursionLimitExceeded < AgentError
+      attr_reader :depth
+
+      def initialize(message = nil, depth: nil)
+        @depth = depth
+        super(message || "Parse::Agent recursion depth exhausted (depth=#{depth.inspect}). " \
+                          "A sub-agent attempted to construct another sub-agent past the " \
+                          "configured recursion_depth: cap.")
+      end
+    end
+
+    # Raised inside the +call_method+ tool when the resolved
+    # +ClassName.method_name+ is excluded by the agent instance's
+    # +methods:+ filter. The execute() rescue maps this to a
+    # +:tool_filtered+ error_code so consumers can distinguish "the
+    # filter excluded this method" from "this method isn't declared
+    # agent-callable" (a Parse::Error) or "the tier doesn't allow it"
+    # (a +:permission_denied+).
+    class MethodFiltered < AgentError; end
   end
 end

lib/parse/agent/cancellation_token.rb

@@ -244,7 +244,54 @@ def reset!
         @history = []
       end
 
-      # The conversation message log. Read-only; use `ask` / `reset!` to mutate.
+      # Replace the conversation history with a previously-saved one. Pairs
+      # with the `history` reader to persist a session across process
+      # restarts: stash `client.history` between turns, then call
+      # `restore_history!(saved)` on a freshly constructed client to resume
+      # exactly where the previous one left off — without re-billing the
+      # provider for the original turns.
+      #
+      # Accepts the shape `history` produces: an Array of Hashes with
+      # `:role` and `:content` (Symbol- or String-keyed; normalized to
+      # Symbol-keyed Strings on entry). Permitted roles are `"user"`,
+      # `"assistant"`, and `"system"` — the only roles `@history` ever
+      # carries internally; tool calls live in `Result#transcript`, not in
+      # the in-memory history. Empty Arrays are allowed (equivalent to
+      # `reset!`).
+      #
+      # @param history [Array<Hash>] the conversation log to install.
+      # @return [Array<Hash>] the installed history.
+      # @raise [ArgumentError] when history is not an Array, an entry is
+      #   not a Hash, an entry has no role/content, or a role is outside
+      #   the supported set.
+      def restore_history!(history)
+        unless history.is_a?(Array)
+          raise ArgumentError, "restore_history! expects an Array, got #{history.class}"
+        end
+
+        normalized = history.each_with_index.map do |entry, i|
+          unless entry.is_a?(Hash)
+            raise ArgumentError, "restore_history!: entry #{i} is not a Hash (got #{entry.class})"
+          end
+          role    = entry[:role]    || entry["role"]
+          content = entry[:content] || entry["content"]
+          if role.to_s.empty?
+            raise ArgumentError, "restore_history!: entry #{i} is missing :role"
+          end
+          unless %w[user assistant system].include?(role.to_s)
+            raise ArgumentError, "restore_history!: entry #{i} has unsupported role #{role.inspect} (expected user/assistant/system)"
+          end
+          if content.nil?
+            raise ArgumentError, "restore_history!: entry #{i} is missing :content"
+          end
+          { role: role.to_s, content: content.to_s }
+        end
+
+        @history = normalized
+      end
+
+      # The conversation message log. Read-only; use `ask`, `reset!`, or
+      # `restore_history!` to mutate.
       # @return [Array<Hash>]
       def history
         @history.dup