parse-stack-next 5.7.2 → 5.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b773e88a55f8771a7d898978652e9be673ec496627fcbaa0b0eb68b950486812
-  data.tar.gz: 7813d865cb6cc09b6c44070186dbf67383304d9407a5de58fdbb723cce4dc081
+  metadata.gz: ef10cccc964e68942152a64d489ea8044a99eb0b76a3fea00d75c311ddf94d23
+  data.tar.gz: 357793ece65c1bb58147e160fb8c95782e3496deac3a1b843a82faf9dcd06737
 SHA512:
-  metadata.gz: 1ffa5266044c369c673c8c5e4e57d4b37d882674eae6d8f7c79f3b1a8318a75dbd76d97036337d8a5416cfdcc022c1db3353e20de53857eaf8e37ac29913dfa7
-  data.tar.gz: e897bb63c7030751cbb2a9720e6fde91e23f6c118a6656e9063a84df4ec7305db1e3f8dd141e600f2e9765fb3660fdd26b0c36c2c321184c9743c6be976498c9
+  metadata.gz: 44ed4c55b5388cd068c723f01bfa02c3efa4fafe61adfa328197a76d0bcf4006eeab313d7d3a42a8b2088b43a4a6a25bd9b89868fe183daa744c3f324c0ef0f2
+  data.tar.gz: 721eebb0297114c0e439babab1c0c39bb1bb9697788ff4197b6d9cf072d80b1fb7d3783f1c629ea0062314321b0695565bd7e252c4e7c39e1940bcf93adabcb7

data/CHANGELOG.md

@@ -1,5 +1,108 @@
 ## parse-stack-next Changelog
 
+### 5.7.4
+
+#### Reset connections are retried instead of surfacing a raw Faraday error
+
+A focused fix release for the request retry mechanism. A stale keep-alive
+connection (a pooled persistent connection closed by the server or a load
+balancer after idling) failed the next request with a raw
+`Faraday::ConnectionFailed` / `Errno::ECONNRESET` instead of retrying, even
+though an immediate re-send on a fresh connection succeeds. Reset connections
+now retry under the same idempotency rules as read timeouts.
+
+- **FIXED**: `Parse::Client#request` now rescues `Faraday::ConnectionFailed`
+  and inspects the wrapped cause. Reset-class causes (`Errno::ECONNRESET`,
+  `Errno::EPIPE`, `Errno::ECONNABORTED`, and the `EOFError` raised when the
+  remote end closes a keep-alive socket cleanly) are transient, so idempotent
+  requests (GET, DELETE, op-free PUT, and any write covered by asserted
+  server-side request-id dedup) retry with the standard backoff. Connection
+  refused and DNS failures keep the previous fail-fast behavior and propagate
+  the raw `Faraday::ConnectionFailed` with no retry latency.
+- **CHANGED**: A reset connection that persists through the whole retry budget
+  now raises `Parse::Error::ConnectionError` (consistent with the read-timeout
+  path) instead of the raw `Faraday::ConnectionFailed`. Code that rescued
+  `Faraday::ConnectionFailed` to catch resets should rescue
+  `Parse::Error::ConnectionError` instead; refused and DNS failures still
+  raise `Faraday::ConnectionFailed`.
+
+### 5.7.3
+
+#### Stored values can no longer drive the operator's terminal
+
+- **NEW**: `Parse::TerminalSafe` is a canonical sanitizer for untrusted text
+  that is about to be written to a terminal, a log record, or an IRB `inspect`
+  line. `Parse::TerminalSafe.sanitize(str)` escapes ESC, BEL, backspace,
+  carriage return, the remaining C0 controls, DEL, the C1 controls (the 8-bit
+  CSI/OSC/DCS introducers, which a sanitizer that only looks for `0x1B`
+  misses), the zero-width characters, and the Unicode bidirectional overrides
+  and isolates. Tabs and newlines are preserved.
+  `Parse::TerminalSafe.sanitize_line(str)` escapes newlines and the Unicode
+  line and paragraph separators as well, for text interpolated into a single
+  log record. Control characters are escaped rather than deleted, so an
+  operator can still see that something tried. Non-UTF-8 and invalid-encoding
+  input is coerced first, so the sanitizer never raises on a binary response
+  body.
+- **FIXED**: Values read back from Parse Server reached the terminal with their
+  control bytes intact. A row whose field contained an OSC 52 sequence could
+  write an attacker-chosen payload into the operator's system clipboard, and
+  CSI and carriage-return sequences could clear the screen or overwrite lines
+  the operator had already read, so what was displayed was not what was stored.
+  Every such path now renders through `Parse::TerminalSafe`: the conversational
+  agent's answer and tool trace (`Parse::Agent::MCPClient::Result#to_s` and
+  `#inspect`, which run merely by evaluating `mcp.ask(...)` in IRB), the
+  request/response bodies and header values written by
+  `Parse::Middleware::Logging` and by the separate `Parse.logging = true`
+  printer in `Parse::Middleware::BodyBuilder`, the REST error text in logged
+  error summaries and in `Parse::Client`'s warning path, `Parse::Query`'s error
+  and explain warnings, the webhook request, payload, response, handler-error,
+  and afterSave-callback lines, and the event and handler-error lines emitted
+  by `Parse.watch`. Sanitization applies to rendering only: `result.text`,
+  `object.title`, and the parsed response body keep their exact bytes, so a
+  caller writing to a non-terminal surface is unaffected.
+- **FIXED**: The LLM provider failure paths in `Parse::Agent::MCPClient`
+  interpolated the raw provider response body into the exception message, and a
+  malformed success body raised a `JSON::ParserError` quoting the offending
+  bytes verbatim. IRB prints both raw, so a hostile or compromised LLM endpoint
+  could still land control sequences on the terminal through the failure path.
+  Both are escaped now, and the quoted body is capped.
+- **FIXED**: Untrusted text interpolated into a log record could contain a raw
+  newline and forge a second, attacker-authored log entry. Log records now use
+  the newline-escaping form, and the escape is applied before the body-length
+  cap so a truncated record stays on one line too.
+- **CHANGED**: `rake mcp:chat` escapes the answer, the tool-call trace, the
+  `/history` and `/compact` output, and error messages before printing them.
+
+#### `parse-console --url` no longer trusts the document it fetches
+
+- **BREAKING**: `parse-console --url` copied every key in the fetched JSON
+  document into the process environment, letting whoever served or tampered
+  with that document set arbitrary environment variables for the console
+  process, including ones the console never reads but Ruby, OpenSSL, or a
+  later `require` does. Only `PARSE_SERVER_URL`,
+  `PARSE_SERVER_APPLICATION_ID`, `PARSE_APP_ID`, `PARSE_SERVER_REST_API_KEY`,
+  `PARSE_API_KEY`, `PARSE_SERVER_MASTER_KEY`, and `PARSE_MASTER_KEY` are
+  copied now, and each value must be a string. **Migration:** a remote config
+  that carried additional variables must set them in the shell instead.
+- **FIXED**: `parse-console --url` parsed the fetched document with
+  `JSON.load`, which honors `json_class` additions and will instantiate
+  arbitrary already-loaded classes from the document. It uses `JSON.parse` now.
+- **CHANGED**: `parse-console --url` refuses plaintext HTTP unless the host is
+  loopback. The document carries the master key, so over plaintext anyone on
+  the path reads it and can substitute a server URL of their choosing. The
+  check runs against `URI#hostname`, so an IPv6 loopback literal and an
+  uppercase host both resolve correctly.
+- **FIXED**: `parse-console --url` fetches the document with a streaming
+  request under a 1 MiB cap, and revalidates the scheme and host on every
+  redirect hop (bounded at five). The previous open-uri call buffered the
+  entire response before any read limit applied, and followed redirects itself,
+  so a permitted loopback URL could bounce to arbitrary plaintext HTTP on the
+  public internet without the scheme check running again.
+- **FIXED**: `parse-console` echoed the supplied URL before validating it, and
+  printed the (possibly remotely supplied) server URL and application ID
+  verbatim after connecting. All three are escaped now, as is the error output
+  from the fetch path, which can quote the fetched bytes.
+
 ### 5.7.2
 
 #### `between` accepts Ruby Range values

data/bin/parse-console

@@ -2,9 +2,11 @@
 
 require 'optparse'
 require 'json'
-require 'open-uri'
+require 'net/http'
+require 'uri'
 require 'active_support'
 require 'active_support/core_ext'
+require 'parse/terminal_safe'
 
 DEFAULT_CONFIG_FILE = 'config.json'
 DEFAULT_CONFIG_CONTENTS = {
@@ -18,6 +20,88 @@ DEFAULT_CONFIG_CONTENTS = {
   }]
 }.freeze
 
+# Only these keys are copied out of a remote config document and into the
+# process environment. The loader used to copy every key it was handed, which
+# let whoever served (or tampered with) the document set arbitrary env vars for
+# the console process, including ones the console never reads but Ruby,
+# OpenSSL, or a later `require` does.
+REMOTE_CONFIG_ENV_ALLOWLIST = %w[
+  PARSE_SERVER_URL
+  PARSE_SERVER_APPLICATION_ID PARSE_APP_ID
+  PARSE_SERVER_REST_API_KEY   PARSE_API_KEY
+  PARSE_SERVER_MASTER_KEY     PARSE_MASTER_KEY
+].freeze
+
+# A remote config carries the master key. Over plaintext HTTP anyone on the path
+# reads it and can substitute a server URL of their choosing, so require TLS
+# except when pointing at the loopback interface.
+LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+
+REMOTE_CONFIG_MAX_BYTES = 1_048_576
+REMOTE_CONFIG_MAX_REDIRECTS = 5
+
+# SEC-20: never hand a user-supplied string to bare Kernel#open, where
+# `open("|command")` executes a subprocess. Parse an explicit URI and require an
+# HTTP(S) scheme instead.
+def validate_config_uri!(uri)
+  unless uri.is_a?(URI::HTTP) # URI::HTTPS < URI::HTTP, so this admits both
+    raise "Refusing to load config from a non-HTTP(S) URL: #{uri.to_s.inspect}"
+  end
+  # `hostname` (not `host`) so an IPv6 literal arrives as "::1" rather than
+  # "[::1]"; downcased so "LOCALHOST" is recognized too.
+  unless uri.is_a?(URI::HTTPS) || LOOPBACK_HOSTS.include?(uri.hostname.to_s.downcase)
+    raise "Refusing to fetch credentials over plaintext HTTP: #{uri.to_s.inspect}. " \
+          "Use https, or a loopback host for local testing."
+  end
+  uri
+end
+
+# Fetch a remote config document, streaming it under a hard byte cap and
+# revalidating every redirect hop.
+#
+# Both properties are the reason this is hand-rolled rather than an open-uri
+# one-liner. open-uri buffers the whole response before yielding the IO, so a
+# read cap on the returned handle limits only what is read back out of a body
+# that was already downloaded in full; and it follows redirects itself, so a
+# permitted `http://localhost/...` could bounce to arbitrary plaintext HTTP on
+# the public internet without the scheme check ever running again.
+def fetch_remote_config_body(url)
+  uri = validate_config_uri!(URI.parse(url))
+  redirects = 0
+
+  loop do
+    body = nil
+    Net::HTTP.start(uri.hostname, uri.port,
+                    use_ssl: uri.is_a?(URI::HTTPS),
+                    open_timeout: 10, read_timeout: 30) do |http|
+      http.request(Net::HTTP::Get.new(uri)) do |res|
+        case res
+        when Net::HTTPRedirection
+          location = res['location'].to_s
+          raise "Redirect with no Location header." if location.empty?
+          redirects += 1
+          if redirects > REMOTE_CONFIG_MAX_REDIRECTS
+            raise "Too many redirects (limit #{REMOTE_CONFIG_MAX_REDIRECTS})."
+          end
+          uri = validate_config_uri!(URI.join(uri.to_s, location))
+        when Net::HTTPSuccess
+          buffer = +''
+          res.read_body do |chunk|
+            buffer << chunk
+            if buffer.bytesize > REMOTE_CONFIG_MAX_BYTES
+              raise "Config exceeds #{REMOTE_CONFIG_MAX_BYTES} bytes; refusing to buffer more."
+            end
+          end
+          body = buffer
+        else
+          raise "Config fetch failed: HTTP #{res.code}."
+        end
+      end
+    end
+    return body if body
+  end
+end
+
 opts = { verbose: false, pry: false }
 opt_parser = OptionParser.new do |o|
 
@@ -73,26 +157,33 @@ opt_parser = OptionParser.new do |o|
     end
 
   end
-  o.on('--url URL', 'Load the env config from a url.') do |url|
+  o.on('--url URL', 'Load the env config from an https url.') do |url|
     begin
-      puts "Loading config: #{url}"
-      # SEC-20: do NOT pass a user-supplied string to bare Kernel#open —
-      # `open("|command")` executes a subprocess. Parse an explicit URI and
-      # require an HTTP(S) scheme, then use open-uri's URI::HTTP#open (a real
-      # network fetch), never the Kernel form.
-      uri = URI.parse(url)
-      unless uri.is_a?(URI::HTTP) # URI::HTTPS < URI::HTTP, so this admits both
-        raise "Refusing to load config from a non-HTTP(S) URL: #{url.inspect}"
-      end
-      json = JSON.load(uri.open)
+      # Echo the URL only in escaped form. It is operator-supplied but not yet
+      # validated at this point, and a pasted URL is exactly the kind of string
+      # that carries a control sequence.
+      puts "Loading config: #{Parse::TerminalSafe.sanitize_line(url)}"
+      # JSON.parse, never JSON.load: `load` honors `json_class` additions and
+      # will instantiate arbitrary loaded classes from the document.
+      json = JSON.parse(fetch_remote_config_body(url))
       raise "Contents not a JSON hash." unless json.is_a?(Hash)
-      json.each { |k,v| ENV[k.upcase] = v }
+      json.each do |k, v|
+        key = k.to_s.upcase
+        next unless REMOTE_CONFIG_ENV_ALLOWLIST.include?(key)
+        unless v.is_a?(String)
+          raise "Config key #{key} must be a string, got #{v.class}."
+        end
+        ENV[key] = v
+      end
       opts[:server_url] ||= ENV['PARSE_SERVER_URL']
       opts[:app_id]     ||= ENV['PARSE_SERVER_APPLICATION_ID'] || ENV['PARSE_APP_ID']
       opts[:api_key]    ||= ENV['PARSE_SERVER_REST_API_KEY']   || ENV['PARSE_API_KEY']
       opts[:master_key] ||= ENV['PARSE_SERVER_MASTER_KEY']     || ENV['PARSE_MASTER_KEY']
     rescue Exception => e
-      $stderr.puts "Error: Invalid JSON format for #{url} (#{e})"
+      # The message can quote the fetched document, so escape it: this is the
+      # one place where remote bytes reach the operator's terminal.
+      $stderr.puts "Error: Invalid JSON format for #{Parse::TerminalSafe.sanitize_line(url)} " \
+                   "(#{Parse::TerminalSafe.sanitize_line(e.message)})"
       exit 1
     end
   end
@@ -120,8 +211,9 @@ Parse.setup server_url: opts[:server_url],
             api_key: opts[:api_key],
             master_key: opts[:master_key]
 Parse.logging = true if opts[:verbose]
-puts "Server : #{Parse.client.server_url}"
-puts "App Id : #{Parse.client.app_id}"
+# Both of these can have come from a remote config document, so escape them.
+puts "Server : #{Parse::TerminalSafe.sanitize_line(Parse.client.server_url)}"
+puts "App Id : #{Parse::TerminalSafe.sanitize_line(Parse.client.app_id)}"
 puts "Master : #{Parse.client.master_key.present?}"
 
 if Parse.client.master_key.present?

data/examples/rag_chatbot.rb

@@ -208,9 +208,12 @@ def chat_loop(backend: :anthropic)
     chunks = retrieve(agent, question)
     answer = ChatAnswerer.public_send(backend, question, chunks)
 
-    puts "\n#{answer}\n"
+    # The answer is model output grounded in retrieved rows, and the object ids
+    # come from the database. Both are untrusted for terminal purposes: escape
+    # control sequences before writing them to a TTY.
+    puts "\n#{Parse::TerminalSafe.sanitize(answer)}\n"
     sources = chunks.map { |c| c.dig(:metadata, :object_id) }.uniq.join(", ")
-    puts "  (sources: #{sources})\n\n"
+    puts "  (sources: #{Parse::TerminalSafe.sanitize_line(sources)})\n\n"
   end
 end
 

data/lib/parse/agent/mcp_client.rb

@@ -6,6 +6,7 @@ require "uri"
 require "json"
 require "securerandom"
 require_relative "mcp_dispatcher"
+require_relative "../terminal_safe"
 
 module Parse
   class Agent
@@ -65,17 +66,25 @@ module Parse
         end
 
         # Pretty-print for IRB: tool trace, answer, then per-call usage line.
+        #
+        # Every interpolated part is attacker-influenced. The answer is LLM
+        # output that was itself conditioned on tenant rows, and tool arguments
+        # can echo stored values. Merely evaluating `mcp.ask(...)` in IRB writes
+        # this string to the terminal, so control sequences are escaped here.
+        # `text` itself is untouched: callers that render into a non-terminal
+        # surface still get the exact bytes.
         def to_s
           parts = []
           if tool_calls.any?
             parts << "─── tool calls (#{tool_calls.size}) ───"
             tool_calls.each_with_index do |tc, i|
               args_str = tc[:arguments].is_a?(Hash) ? tc[:arguments].inspect : tc[:arguments].to_s
-              parts << "  #{i + 1}. #{tc[:name]}(#{args_str})"
+              parts << "  #{i + 1}. #{Parse::TerminalSafe.sanitize_line(tc[:name])}" \
+                       "(#{Parse::TerminalSafe.sanitize_line(args_str)})"
             end
           end
           parts << "─── answer ───"
-          parts << text.to_s
+          parts << Parse::TerminalSafe.sanitize(text)
           parts << "─── usage ───" << "  #{usage}" if usage && usage.total_tokens.positive?
           parts.join("\n")
         end
@@ -311,6 +320,39 @@ module Parse
 
       private
 
+      # Maximum bytes of a provider response body quoted back in an exception.
+      LLM_ERROR_BODY_CAP = 2_000
+
+      # Check the HTTP status and parse the body, raising with a terminal-safe
+      # message on either failure.
+      #
+      # The provider's response body is untrusted output on both paths. An
+      # error body is echoed into the exception message, and a malformed
+      # success body produces a `JSON::ParserError` whose message quotes the
+      # offending bytes verbatim. Either exception is printed raw by IRB and by
+      # most logging setups, so an LLM endpoint (or a model repeating what a
+      # tenant row told it to say) could otherwise still land control sequences
+      # on the operator's terminal through the failure path.
+      #
+      # @param res [Net::HTTPResponse]
+      # @param label [String] provider name used in the message.
+      # @return [Hash] the parsed body.
+      def parse_llm_response!(res, label)
+        body = res.body.to_s
+        unless res.code.to_i.between?(200, 299)
+          quoted = Parse::TerminalSafe.sanitize_line(body[0, LLM_ERROR_BODY_CAP])
+          raise "#{label} failed: HTTP #{res.code} #{quoted}"
+        end
+
+        begin
+          JSON.parse(body)
+        rescue JSON::ParserError => e
+          raise JSON::ParserError,
+                "#{label} returned an unparseable body: " \
+                "#{Parse::TerminalSafe.sanitize_line(e.message)[0, LLM_ERROR_BODY_CAP]}"
+        end
+      end
+
       # Fetch the agent's MCP tool catalog and translate it into the LLM's
       # native function-calling schema. Cached per call (could be memoized
       # if tool lists grow large, but they're usually small).
@@ -447,11 +489,7 @@ module Parse
         res = Net::HTTP.start(uri.hostname, uri.port,
                               use_ssl: uri.scheme == "https",
                               read_timeout: @timeout) { |h| h.request(req) }
-        unless res.code.to_i.between?(200, 299)
-          raise "LLM call failed: HTTP #{res.code} #{res.body}"
-        end
-
-        parsed = JSON.parse(res.body)
+        parsed = parse_llm_response!(res, "LLM call")
         msg = parsed.dig("choices", 0, "message") || {}
         calls = Array(msg["tool_calls"]).map do |tc|
           args = tc.dig("function", "arguments")
@@ -497,11 +535,7 @@ module Parse
         res = Net::HTTP.start(uri.hostname, uri.port,
                               use_ssl: uri.scheme == "https",
                               read_timeout: @timeout) { |h| h.request(req) }
-        unless res.code.to_i.between?(200, 299)
-          raise "Anthropic call failed: HTTP #{res.code} #{res.body}"
-        end
-
-        parsed = JSON.parse(res.body)
+        parsed = parse_llm_response!(res, "Anthropic call")
         blocks = Array(parsed["content"])
         text = blocks.select { |b| b["type"] == "text" }.map { |b| b["text"] }.join("\n")
         calls = blocks.select { |b| b["type"] == "tool_use" }.map do |b|

data/lib/parse/client/body_builder.rb

@@ -9,6 +9,7 @@ require "active_support/core_ext"
 require "active_model/serializers/json"
 require "json"
 require "set"
+require_relative "../terminal_safe"
 
 module Parse
 
@@ -317,17 +318,23 @@ module Parse
           env[:body] = env[:body].to_json
         end
 
+        # `Parse.logging = true` routes here, so this legacy printer sees the
+        # same tenant-controlled bytes the Faraday logging middleware does and
+        # needs the same terminal-escape handling.
         if self.class.logging
-          puts "[Request #{env.method.upcase}] #{self.class.redact(env[:url].to_s)}"
+          puts "[Request #{env.method.upcase}] " \
+               "#{Parse::TerminalSafe.sanitize_line(self.class.redact(env[:url].to_s))}"
           env[:request_headers].each do |k, v|
             if REDACTED_HEADERS.include?(k.to_s.downcase)
-              puts "[Header] #{k} : [FILTERED]"
+              puts "[Header] #{Parse::TerminalSafe.sanitize_line(k)} : [FILTERED]"
             else
-              puts "[Header] #{k} : #{v}"
+              puts "[Header] #{Parse::TerminalSafe.sanitize_line(k)} : " \
+                   "#{Parse::TerminalSafe.sanitize_line(v)}"
             end
           end
 
-          puts "[Request Body] #{self.class.redact(env[:body].to_s)}"
+          puts "[Request Body] " \
+               "#{Parse::TerminalSafe.sanitize_line(self.class.redact(env[:body].to_s))}"
         end
         @app.call(env).on_complete do |response_env|
           # on a response, create a new Parse::Response and replace the :body
@@ -335,7 +342,7 @@ module Parse
           # @todo CHECK FOR HTTP STATUS CODES
           if self.class.logging
             puts "[[Response #{response_env[:status]}]] ----------------------------------"
-            puts self.class.redact(response_env.body.to_s)
+            puts Parse::TerminalSafe.sanitize(self.class.redact(response_env.body.to_s))
             puts "[[Response]] --------------------------------------\n"
           end
 

data/lib/parse/client/logging.rb

@@ -4,6 +4,7 @@
 require "faraday"
 require "logger"
 require_relative "url_redaction"
+require_relative "../terminal_safe"
 
 module Parse
   module Middleware
@@ -167,7 +168,8 @@ module Parse
           if Parse::Middleware::BodyBuilder::REDACTED_HEADERS.include?(key.to_s.downcase)
             logger.debug "  [#{prefix} Header] #{key}: [FILTERED]"
           else
-            logger.debug "  [#{prefix} Header] #{key}: #{value}"
+            logger.debug "  [#{prefix} Header] #{Parse::TerminalSafe.sanitize_line(key)}: " \
+                         "#{Parse::TerminalSafe.sanitize_line(value)}"
           end
         end
       end
@@ -196,6 +198,13 @@ module Parse
         # so truncation can't split a token across the boundary and slip past.
         content = Parse::Middleware::BodyBuilder.redact(content)
 
+        # Request and response bodies carry tenant-stored values verbatim. A
+        # stored ESC sequence would execute against the operator's terminal the
+        # moment they tail the log, so escape control characters and newlines
+        # here. Done BEFORE the length cap so the record is one line whether or
+        # not it was truncated.
+        content = Parse::TerminalSafe.sanitize_line(content)
+
         if content.length > max_length
           logger.debug "  [#{prefix} Body] #{content[0...max_length]}... (truncated, #{content.length} total)"
         elsif content.length > 0
@@ -216,15 +225,21 @@ module Parse
         end
       end
 
+      # The error text is whatever the server (or a stored value echoed back by
+      # the server) says, so it is untrusted. Escape terminal control sequences
+      # AND newlines: this is interpolated into a one-line log record, and a
+      # raw LF would let the text forge a second, attacker-authored entry.
       def error_summary(response_env)
         body = response_env[:body]
-        if body.is_a?(Parse::Response) && body.error?
-          "#{body.code}: #{body.error}"
-        elsif body.is_a?(Hash)
-          body["error"] || body[:error] || "Unknown error"
-        else
-          "HTTP #{response_env[:status]}"
-        end
+        summary =
+          if body.is_a?(Parse::Response) && body.error?
+            "#{body.code}: #{body.error}"
+          elsif body.is_a?(Hash)
+            body["error"] || body[:error] || "Unknown error"
+          else
+            "HTTP #{response_env[:status]}"
+          end
+        Parse::TerminalSafe.sanitize_line(summary)
       end
 
       def sanitize_url(url)

data/lib/parse/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require_relative "terminal_safe"
 
 # Attempt to load the persistent connection adapter for better performance.
 # Falls back gracefully to the default adapter if not available.
@@ -528,11 +529,19 @@ module Parse
       # @param name [String, nil] optional cloud-function or job name for context.
       # @return [nil]
       def _safe_warn(tag, response, name: nil)
+        # The server's error text and the request description both carry stored
+        # values through verbatim, and this lands in a log file or on a
+        # terminal. Escape control characters and newlines so a stored value
+        # can neither drive the terminal nor forge a second log record.
         err = Parse::Middleware::BodyBuilder.redact(response.error.to_s)[0, SAFE_WARN_MAX_ERROR_LENGTH]
+        err = Parse::TerminalSafe.sanitize_line(err)
         msg = if name
-            "[Parse:#{tag}] `#{name}` [#{response.code}] #{err} (HTTP #{response.http_status})"
+            "[Parse:#{tag}] `#{Parse::TerminalSafe.sanitize_line(name)}` " \
+            "[#{response.code}] #{err} (HTTP #{response.http_status})"
           else
-            "[Parse:#{tag}] [E-#{response.code}] #{response.request} : #{err} (#{response.http_status})"
+            "[Parse:#{tag}] [E-#{response.code}] " \
+            "#{Parse::TerminalSafe.sanitize_line(response.request)} : #{err} " \
+            "(#{response.http_status})"
           end
         logger = Parse::Middleware::Logging.logger
         if logger
@@ -1415,6 +1424,30 @@ module Parse
           retry
         end
         raise
+      rescue Faraday::ConnectionFailed => e
+        # `Faraday::ConnectionFailed` covers two very different failures under
+        # one class, so it is split on the wrapped cause (see
+        # #connection_reset_error?):
+        #
+        #   - RESET mid-flight (`Errno::ECONNRESET` / `Errno::EPIPE` /
+        #     `Errno::ECONNABORTED` / `EOFError`): the classic stale
+        #     keep-alive failure. A pooled persistent connection idled past
+        #     the server's (or an LB's) keep-alive window and was closed
+        #     remotely, and the next request on it dies at the socket.
+        #     Transient by nature (a fresh connection succeeds immediately),
+        #     so it retries under the same idempotency rules as a read
+        #     timeout: the outcome is unknown, so only idempotent requests
+        #     are re-sent.
+        #
+        #   - REFUSED (and DNS failure): the server is down or misconfigured.
+        #     Retrying only adds backoff latency and `[Parse:Retry]` noise
+        #     before the inevitable error, so it propagates raw and fast.
+        raise unless connection_reset_error?(e)
+        if _retry_count > 0 && idempotent_retry?(method, body, headers)
+          _retry_count = consume_retry_with_backoff(_retry_count, _retry_max, _request)
+          retry
+        end
+        raise Parse::Error::ConnectionError, "#{_request} : #{e.class} - #{e.message}"
       rescue Faraday::ClientError, Faraday::TimeoutError, Net::OpenTimeout => e
         # Request timed out mid-flight: the outcome is unknown (the server may
         # have received and applied the write but never answered), so only
@@ -1422,25 +1455,74 @@ module Parse
         #
         # Faraday 2.x raises `Faraday::TimeoutError` for a read timeout
         # (`Timeout::Error` / `Errno::ETIMEDOUT`); it subclasses `Faraday::Error`,
-        # not `ClientError`, so it must be listed explicitly to be caught. We
-        # deliberately do NOT catch `Faraday::ConnectionFailed` (connection
-        # refused/reset, plus the wrapped connect-timeout): refused is a
-        # non-transient "server down / misconfigured" failure, and auto-retrying
-        # it only adds backoff latency before the inevitable error. Broadening to
-        # reset connections safely (retry reset, fail fast on refused) is tracked
-        # as a follow-up.
+        # not `ClientError`, so it must be listed explicitly to be caught.
+        # `Faraday::ConnectionFailed` is handled in its own rescue above,
+        # split into retry-reset / fail-fast-refused.
         if _retry_count > 0 && idempotent_retry?(method, body, headers)
-          warn "[Parse:Retry] Retries remaining #{_retry_count} : #{_request}"
-          _retry_count -= 1
-          backoff_delay = RETRY_DELAY * (_retry_max - _retry_count)
-          _retry_delay = backoff_delay * (0.75 + rand * 0.5)
-          sleep _retry_delay if _retry_delay > 0
+          _retry_count = consume_retry_with_backoff(_retry_count, _retry_max, _request)
           retry
         end
         raise Parse::Error::ConnectionError, "#{_request} : #{e.class} - #{e.message}"
       end
     end
 
+    # Consumes one attempt from the retry budget: logs the remaining count,
+    # sleeps the linear backoff (RETRY_DELAY x attempt number, +/-25% jitter,
+    # never zero), and returns the decremented budget. Shared by the
+    # connection-reset and timeout rescue branches in {#request} so their
+    # backoff behavior cannot drift apart; the `retry` keyword itself must
+    # stay lexically inside each rescue clause, so it remains at the call
+    # sites. The 429/503 branch keeps its own inline version because it also
+    # honors a server-supplied Retry-After header.
+    # @param retry_count [Integer] the remaining retry budget (must be > 0).
+    # @param retry_max [Integer] the effective starting budget.
+    # @param request [Parse::Request] the request being retried (for logging).
+    # @return [Integer] the decremented retry budget.
+    def consume_retry_with_backoff(retry_count, retry_max, request)
+      warn "[Parse:Retry] Retries remaining #{retry_count} : #{request}"
+      retry_count -= 1
+      backoff_delay = RETRY_DELAY * (retry_max - retry_count)
+      retry_delay = backoff_delay * (0.75 + rand * 0.5)
+      sleep retry_delay if retry_delay > 0
+      retry_count
+    end
+
+    # The wrapped causes that mark a `Faraday::ConnectionFailed` as a RESET
+    # connection (transient, retry-safe for idempotent requests) rather than a
+    # REFUSED one (server down, fail fast). `EOFError` is what net/http raises
+    # when the remote end closes a keep-alive socket cleanly between requests;
+    # ECONNRESET/EPIPE/ECONNABORTED are the unclean variants.
+    # @!visibility private
+    CONNECTION_RESET_CAUSES = [
+      Errno::ECONNRESET, Errno::EPIPE, Errno::ECONNABORTED, EOFError,
+    ].freeze
+
+    # Message fallback for adapters that raise `Faraday::ConnectionFailed`
+    # with the cause flattened into the message instead of wrapped.
+    # @!visibility private
+    CONNECTION_RESET_MESSAGE = /connection reset|broken pipe|end of file reached/i
+
+    # Whether a `Faraday::ConnectionFailed` was caused by a reset/dropped
+    # connection (retryable) as opposed to connection-refused or a DNS
+    # failure (fail fast). Walks the wrapped exception and the `#cause`
+    # chain looking for a reset-class error.
+    # @param error [Exception] the rescued `Faraday::ConnectionFailed`.
+    # @return [Boolean]
+    def connection_reset_error?(error)
+      inner = error.respond_to?(:wrapped_exception) ? error.wrapped_exception : nil
+      inner ||= error.cause
+      seen = 0
+      while inner && seen < 8
+        return true if CONNECTION_RESET_CAUSES.any? { |klass| inner.is_a?(klass) }
+        inner = inner.cause
+        seen += 1
+      end
+      CONNECTION_RESET_MESSAGE.match?(error.message.to_s)
+    end
+
+    private :consume_retry_with_backoff, :connection_reset_error?
+    private_constant :CONNECTION_RESET_CAUSES, :CONNECTION_RESET_MESSAGE
+
     # Whether a request whose outcome is UNKNOWN (a 500/503 or a dropped
     # connection) is safe to transparently re-send.
     #

data/lib/parse/console.rb

@@ -23,6 +23,7 @@
 # tests / fixtures.
 
 require "timeout"
+require_relative "terminal_safe"
 
 module Parse
   module Console
@@ -65,7 +66,10 @@ module Parse
       events = Array(on || DEFAULT_WATCH_EVENTS).map(&:to_sym)
       printer = block_given? ? block : ->(ev, obj) {
         title = obj.respond_to?(:id) ? obj.id : obj.inspect
-        puts "[#{Time.now.iso8601}] #{klass.parse_class}.#{ev} #{title}"
+        # The row is tenant data arriving over a live-query socket and this
+        # line goes straight to the operator's terminal, so escape it.
+        puts "[#{Time.now.iso8601}] #{klass.parse_class}.#{ev} " \
+             "#{Parse::TerminalSafe.sanitize_line(title)}"
       }
 
       delivered = 0
@@ -78,11 +82,13 @@ module Parse
           begin
             printer.call(ev, obj)
           rescue StandardError => e
-            warn "[Parse.watch] handler raised #{e.class}: #{e.message}"
+            # The message can quote the row that triggered it.
+            warn "[Parse.watch] handler raised #{e.class}: " \
+                 "#{Parse::TerminalSafe.sanitize_line(e.message)}"
           end
         end
       end
-      sub.on(:error) { |err| warn "[Parse.watch] error: #{err}" }
+      sub.on(:error) { |err| warn "[Parse.watch] error: #{Parse::TerminalSafe.sanitize_line(err)}" }
 
       _block_until_interrupt
       delivered

data/lib/parse/query.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require_relative "client"
+require_relative "terminal_safe"
 require_relative "pipeline_security"
 require_relative "query/operation"
 require_relative "query/constraints"
@@ -1782,7 +1783,7 @@ module Parse
     def fetch!(compiled_query)
       response = client.find_objects(@table, compiled_query.as_json, headers: _headers, **_opts)
       if response.error?
-        puts "[ParseQuery] #{response.error}"
+        puts "[ParseQuery] #{Parse::TerminalSafe.sanitize_line(response.error)}"
       end
       response
     end
@@ -3596,12 +3597,12 @@ module Parse
         # non-master explain that worked on 8.x now returns a permission
         # error. Surface that as actionable guidance instead of a bare 403.
         if response.respond_to?(:permission_denied?) && response.permission_denied?
-          puts "[ParseQuery:Explain] #{response.error} — Parse Server 9.0+ defaults " \
+          puts "[ParseQuery:Explain] #{Parse::TerminalSafe.sanitize_line(response.error)} — Parse Server 9.0+ defaults " \
                "`allowPublicExplain` to false; query explain now requires the master key " \
                "(use_master_key: true) or `allowPublicExplain: true` in the server's " \
                "databaseOptions."
         else
-          puts "[ParseQuery:Explain] #{response.error}"
+          puts "[ParseQuery:Explain] #{Parse::TerminalSafe.sanitize_line(response.error)}"
         end
         return {}
       end

data/lib/parse/stack/version.rb

@@ -6,6 +6,6 @@ module Parse
   # The Parse Server SDK for Ruby
   module Stack
     # The current version.
-    VERSION = "5.7.2"
+    VERSION = "5.7.4"
   end
 end

data/lib/parse/stack.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require_relative "stack/version"
+require_relative "terminal_safe"
 require_relative "client"
 require_relative "query"
 require_relative "model/object"

data/lib/parse/terminal_safe.rb

@@ -0,0 +1,138 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  # Neutralizes terminal control sequences in untrusted text before it is
+  # written to a terminal, a log record, or an IRB `inspect` line.
+  #
+  # Parse Server returns whatever a tenant stored. Any string that originates
+  # in the database, in a server error message, or in an LLM answer is
+  # attacker-influenced, and a raw ESC byte in that string is not inert once it
+  # reaches a TTY. It can clear the screen, rewrite lines the operator has
+  # already read, retitle the window, or (via OSC 52) write the attacker's
+  # payload into the system clipboard so the operator's next paste runs it.
+  # Bidirectional overrides are the same class of problem: they reorder a line
+  # so what the operator reads is not what the bytes say.
+  #
+  # This module is the SDK's single answer to that. It escapes rather than
+  # deletes, so the offending bytes stay visible in the output (rendered as
+  # `\e`, `\u202E`, and friends) and an operator can still see that
+  # something tried.
+  #
+  # It sanitizes *rendering*, never storage. `result.text`, `object.title`, and
+  # the parsed response body keep their exact bytes. Only the human-readable
+  # form built for a terminal or a log line runs through here.
+  #
+  # @example Rendering an untrusted value
+  #   puts Parse::TerminalSafe.sanitize(post.title)
+  #
+  # @example A single-line log record. Newlines are escaped too, so a stored
+  #   value cannot forge a second log entry.
+  #   logger.warn "#{status} - #{Parse::TerminalSafe.sanitize_line(error)}"
+  module TerminalSafe
+    extend self
+
+    # Codepoint ranges neutralized on every call:
+    #
+    # - 0x00-0x08, 0x0B-0x1F: C0 controls except TAB (0x09) and LF (0x0A).
+    #   This is where ESC (0x1B, the CSI/OSC/DCS introducer), BEL (0x07, the
+    #   OSC string terminator), CR (0x0D, overwrite-the-line), and BS (0x08,
+    #   erase-the-previous-character) live.
+    # - 0x7F: DEL.
+    # - 0x80-0x9F: C1 controls, the 8-bit forms of the same introducers
+    #   (0x9B is CSI, 0x9D is OSC, 0x90 is DCS).
+    # - 0x061C: Arabic letter mark, an implicit bidirectional control that
+    #   reorders a line exactly like the explicit marks below.
+    # - 0x200B-0x200F: zero-width space, non-joiner, joiner, LRM, RLM.
+    # - 0x2028-0x2029: line and paragraph separator. Widely treated as a line
+    #   break by terminals, editors, and log readers, so leaving them intact
+    #   would reintroduce the forged-record problem that escaping LF solves.
+    #   A legitimate line break is LF, which is preserved.
+    # - 0x202A-0x202E: bidirectional embedding and override.
+    # - 0x2060-0x2064: word joiner and the invisible math operators.
+    # - 0x2066-0x2069: the bidirectional isolates.
+    # - 0xFEFF: zero-width no-break space (a BOM appearing mid-string).
+    #
+    # TAB and LF are deliberately absent: both are ordinary formatting in
+    # multi-line output. {#sanitize_line} escapes LF as well.
+    UNSAFE_RANGES = [
+      0x00..0x08, 0x0B..0x1F, 0x7F..0x9F,
+      0x061C..0x061C,
+      0x200B..0x200F, 0x2028..0x2029, 0x202A..0x202E,
+      0x2060..0x2064, 0x2066..0x2069,
+      0xFEFF..0xFEFF,
+    ].freeze
+
+    # Built from codepoints rather than written as literal escapes so the
+    # source of this file stays free of the very bytes it defends against.
+    def self.build_pattern(ranges)
+      body = ranges.map { |r| format("\\u{%04X}-\\u{%04X}", r.first, r.last) }.join
+      Regexp.new("[#{body}]")
+    end
+    private_class_method :build_pattern
+
+    UNSAFE_RE = build_pattern(UNSAFE_RANGES)
+
+    # The same set plus LF, for output that must occupy exactly one line.
+    UNSAFE_LINE_RE = build_pattern(UNSAFE_RANGES + [0x0A..0x0A])
+
+    # Readable escapes for the controls an operator is most likely to see.
+    # Everything else falls back to `\xNN` or `\uNNNN`.
+    NAMED_ESCAPES = {
+      "\0" => "\\0",
+      "\a" => "\\a",
+      "\b" => "\\b",
+      "\n" => "\\n",
+      "\v" => "\\v",
+      "\f" => "\\f",
+      "\r" => "\\r",
+      "\e" => "\\e",
+    }.freeze
+
+    # Escape terminal control sequences in `str`, preserving newlines and tabs.
+    #
+    # @param str [String, #to_s, nil] untrusted text.
+    # @return [String] the same text with control characters escaped. Non-UTF-8
+    #   and invalid-encoding input is coerced to UTF-8 first, so this never
+    #   raises on a binary response body.
+    def sanitize(str)
+      escape(str, UNSAFE_RE)
+    end
+
+    # Escape terminal control sequences and newlines, so untrusted text cannot
+    # forge additional lines. Use for anything written as a single log record
+    # or a single console line.
+    #
+    # @param str [String, #to_s, nil] untrusted text.
+    # @return [String]
+    def sanitize_line(str)
+      escape(str, UNSAFE_LINE_RE)
+    end
+
+    private
+
+    def escape(str, pattern)
+      s = coerce(str)
+      return s unless s.match?(pattern)
+      s.gsub(pattern) { |ch| escape_char(ch) }
+    end
+
+    # Force the input to valid UTF-8 without raising. A response body read off
+    # the wire can be ASCII-8BIT, and a truncated multi-byte sequence is not
+    # valid UTF-8. Either would make `match?` raise ArgumentError, which is
+    # exactly the wrong outcome for a defensive sanitizer.
+    def coerce(str)
+      s = str.is_a?(String) ? str : str.to_s
+      s = s.dup.force_encoding(Encoding::UTF_8) unless s.encoding == Encoding::UTF_8
+      s = s.scrub("�") unless s.valid_encoding?
+      s
+    end
+
+    def escape_char(ch)
+      named = NAMED_ESCAPES[ch]
+      return named if named
+      cp = ch.ord
+      cp <= 0xFF ? format("\\x%02X", cp) : format("\\u%04X", cp)
+    end
+  end
+end

data/lib/parse/webhooks.rb

@@ -11,6 +11,7 @@ require "active_model/serializers/json"
 require "rack"
 require "ostruct"
 require_relative "client"
+require_relative "terminal_safe"
 # Note: Do not require "stack" here - this file is loaded from stack.rb
 # and adding that require would create a circular dependency.
 require_relative "model/object"
@@ -326,7 +327,10 @@ module Parse
       # @param error [StandardError] the raised error.
       # @return [void]
       def report_handler_error(type, error)
-        warn "[Parse::Webhooks] #{type} handler raised #{error.class}: #{error.message}; " \
+        # The handler's message is application-authored but routinely quotes the
+        # payload that triggered it, which is caller-controlled.
+        warn "[Parse::Webhooks] #{type} handler raised #{error.class}: " \
+             "#{Parse::TerminalSafe.sanitize_line(error.message)}; " \
              "continuing with the remaining handlers " \
              "(Parse::Webhooks.abort_after_callbacks_on_error is false)"
         return unless defined?(ActiveSupport::Notifications)
@@ -671,9 +675,9 @@ module Parse
         # record contents/tokens, and the rest of this file routes log output
         # through the same redactor.
         warn "[Parse::Webhooks] afterSave #{phase} callback raised for " \
-             "#{obj.class}##{obj.id} -- the object is already persisted; " \
-             "logging and continuing: #{e.class}: " \
-             "#{Parse::Middleware::BodyBuilder.redact(e.message)}"
+             "#{obj.class}##{Parse::TerminalSafe.sanitize_line(obj.id)} -- the object is " \
+             "already persisted; logging and continuing: #{e.class}: " \
+             "#{Parse::TerminalSafe.sanitize_line(Parse::Middleware::BodyBuilder.redact(e.message))}"
         nil
       end
 
@@ -853,20 +857,29 @@ module Parse
         begin
           payload = Parse::Webhooks::Payload.new(body_str, webhook_class)
         rescue => e
-          warn "Invalid webhook payload format: #{e}"
+          warn "Invalid webhook payload format: #{Parse::TerminalSafe.sanitize_line(e.to_s)}"
           response.write error("Invalid payload format. Should be valid JSON.")
           return response.finish
         end
 
         if self.logging.present?
+          # Everything interpolated below arrives in the webhook request body:
+          # the trigger/function names, the object id, and the whole payload are
+          # caller-controlled, and these lines go to the app server's console.
+          # Escape control sequences so a stored value cannot drive the terminal
+          # of whoever is tailing the log.
           if payload.trigger?
-            puts "[Webhooks::Request] --> #{payload.trigger_name} #{payload.parse_class}:#{payload.parse_id}"
+            puts "[Webhooks::Request] --> #{Parse::TerminalSafe.sanitize_line(payload.trigger_name)} " \
+                 "#{Parse::TerminalSafe.sanitize_line(payload.parse_class)}:" \
+                 "#{Parse::TerminalSafe.sanitize_line(payload.parse_id)}"
           elsif payload.function?
-            puts "[ParseWebhooks Request] --> Function #{payload.function_name}"
+            puts "[ParseWebhooks Request] --> Function #{Parse::TerminalSafe.sanitize_line(payload.function_name)}"
           end
           if self.logging == :debug
             puts "[Webhooks::Payload] ----------------------------"
-            puts Parse::Middleware::BodyBuilder.redact(payload.as_json.to_json)
+            puts Parse::TerminalSafe.sanitize(
+              Parse::Middleware::BodyBuilder.redact(payload.as_json.to_json)
+            )
             puts "----------------------------------------------------\n"
           end
         end
@@ -891,14 +904,14 @@ module Parse
           else
             if self.logging.present?
               puts "[Webhooks] --> Could not find mapping route for " \
-                "#{Parse::Middleware::BodyBuilder.redact(payload.to_json)}"
+                "#{Parse::TerminalSafe.sanitize_line(Parse::Middleware::BodyBuilder.redact(payload.to_json))}"
             end
           end
 
           result = true if result.nil?
           if self.logging.present?
             puts "[Webhooks::Response] ----------------------------"
-            puts success(result)
+            puts Parse::TerminalSafe.sanitize(success(result))
             puts "----------------------------------------------------\n"
           end
           response.write success(result)
@@ -909,9 +922,13 @@ module Parse
           return response.finish
         rescue Parse::Webhooks::ResponseError, ActiveModel::ValidationError => e
           if payload.trigger?
-            puts "[Webhooks::ResponseError] >> #{payload.trigger_name} #{payload.parse_class}:#{payload.parse_id}: #{e}"
+            puts "[Webhooks::ResponseError] >> #{Parse::TerminalSafe.sanitize_line(payload.trigger_name)} " \
+                 "#{Parse::TerminalSafe.sanitize_line(payload.parse_class)}:" \
+                 "#{Parse::TerminalSafe.sanitize_line(payload.parse_id)}: " \
+                 "#{Parse::TerminalSafe.sanitize_line(e.to_s)}"
           elsif payload.function?
-            puts "[Webhooks::ResponseError] >> #{payload.function_name}: #{e}"
+            puts "[Webhooks::ResponseError] >> #{Parse::TerminalSafe.sanitize_line(payload.function_name)}: " \
+                 "#{Parse::TerminalSafe.sanitize_line(e.to_s)}"
           end
           response.write error(e.to_s)
           return response.finish

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: parse-stack-next
 version: !ruby/object:Gem::Version
-  version: 5.7.2
+  version: 5.7.4
 platform: ruby
 authors:
 - Adrian Curtin
@@ -422,6 +422,7 @@ files:
 - lib/parse/stack/railtie.rb
 - lib/parse/stack/tasks.rb
 - lib/parse/stack/version.rb
+- lib/parse/terminal_safe.rb
 - lib/parse/two_factor_auth.rb
 - lib/parse/two_factor_auth/user_extension.rb
 - lib/parse/vector_search.rb