parse-stack-next 5.7.1 → 5.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cb6a2c813f0a1b2d624852680651ed289f7aac282fa24e246b28d0ed9e69383
-  data.tar.gz: a3984ae30555af28eadfdc19fa936103bb252bad332b0ddb8ead163277ae4bde
+  metadata.gz: e4017efda309de14faf52b86e26274cc097ee029d282a975f0144e324ac68250
+  data.tar.gz: e46cbf422955acc46ef7ceff8348a564712a9109051511dfec1bd2dce96356f0
 SHA512:
-  metadata.gz: d19428000255676b8a5f10ee0087bf3b6d21216c499f56d895d1ee50a646985a4297b725807b2b19878a8576415c8e1551471d34fa236e9bf90170e6e13abed5
-  data.tar.gz: 5db3159d3da214300df9e21760ae871f070f6a79d961fe9e082b5160dd0bd2c07cba5d64656791b961ab2c347e9ebf5151eb607fcf0a3768587a3c382476000e
+  metadata.gz: 1cee46e278c9ad77fab0d4f2869636c623b43e9e1b7d2ea0ea77f92be9ad8f6631bb6e5f92421997f92d42ba73470db659486595fe0993a50de93140eb6051fb
+  data.tar.gz: 36322b4f93132dd277476d999fc71511324d5a726979896ae08e4f6aea31d3aa4454fd41910a1c7758d229c9ff1000cb43de12ffaf8f795403e1ab7cf96f71ef

data/CHANGELOG.md

@@ -1,5 +1,168 @@
 ## parse-stack-next Changelog
 
+### 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
+
+- **NEW**: The `between` constraint now accepts a Ruby `Range` in addition to
+  a 2-element array, so `Person.where(:age.between => 5..25)` and
+  `Record.where(:date.between => 5.days.ago...2.days.ago)` work directly. An
+  inclusive range (`..`) maps its upper bound to `$lte`, matching the existing
+  array form, while an exclusive range (`...`) maps it to `$lt` instead.
+  Beginless (`..25`) and endless (`5..`) ranges are also supported and
+  constrain only the side that is present, so `Person.where(:age.between =>
+  18..)` compiles to `{"$gte" => 18}` with no upper bound. The array form is
+  unchanged, and both forms produce identical output for the same bounds.
+
+#### `Query#where_not_between` for the negated form of a range
+
+- **NEW**: `Query#where_not_between(field, value)` adds the logical negation
+  of `between`: `Person.query.where_not_between(:age, 5..25)` compiles to
+  `age < 5 OR age > 25`, accepting the same Range and 2-element Array forms
+  as `between` (exclusive ranges flip the upper side to `$gte`, and a
+  beginless or endless Range negates to a single one-sided comparison with
+  no `$or` needed). It is not available as a `field.not_between => value`
+  symbol constraint: a range's negation is inherently an `$or` of two
+  comparisons, and only one `$or` group can be safely merged into a
+  compiled query, so a symbol constraint that unilaterally emitted one
+  could silently collide with an existing `$or` from `or_where`/`|`.
+  `where_not_between` instead composes the negation the way
+  `Parse::Query.and` already does, so it correctly nests inside a query's
+  other `.where` conditions instead of replacing them, and raises
+  `ArgumentError` if the query already has an `$or` group rather than
+  silently dropping part of it.
+
+#### `embed_image` forwards a presigned URL when the source file has one
+
+- **FIXED**: `embed_image` always sent the source file's bare `file.url` to
+  the embedding provider (or to the SDK's own `:bytes`-mode downloader). On a
+  private-bucket file adapter (S3/GCS configured with `presignedUrl: true`),
+  `file.url` is the canonical URL with its signature stripped, so the
+  provider's fetch (or the SDK's download) got a 403 instead of the image.
+  `Parse::File` already captures the signed variant in `file.presigned_url`
+  whenever Parse Server returns one, but `embed_image` never read it.
+  Recompute now forwards `file.presigned_url` when it is present and not yet
+  expired, and falls back to the bare URL otherwise, for both `source: :url`
+  and `source: :bytes`. The stored digest is still keyed on the bare
+  canonical URL, so a save that only rotates the file's signature does not
+  trigger a needless re-embed. The validity check ignores
+  `presigned_url_valid?`'s default 60-second safety buffer (meant for a
+  browser render, not an immediate server-side fetch), since on a
+  private-bucket adapter the fallback URL is not fetchable at all and would
+  otherwise 403 for the last minute of every signature's life.
+  `Parse::Embeddings::ImageFetch::FetchedImage#url` now stores the
+  query-stripped URL rather than the presigned one, since a live signature
+  has no reason to survive into that value object's `#inspect` output.
+  `source: :url` mode can now forward a presigned URL to the embedding
+  provider under the same `Parse::Embeddings.trust_provider_url_fetch`
+  consent already required to forward any URL; operators relying on private
+  buckets should confirm the provider's egress handling covers
+  credential-bearing URLs, not just public ones.
+
+#### `Query#get` now resolves aliased `parse_class` names correctly
+
+- **FIXED**: `Query#get` looked up the target class with a raw
+  `Object.const_get(@table)`, which only worked when the Parse class name
+  matched the Ruby constant name exactly. A model that renames its table via
+  `parse_class "SomeOtherName"` was never found by this lookup, so `get`
+  silently fell back to a generic `Parse::Object`/`Parse::Pointer` instead of
+  hydrating the declared model. `Query#get` now passes the table name through
+  to `Parse::Object.build` as a string, letting it run its own
+  `Parse::Model.find_class` resolution, which already understands
+  `parse_class` aliasing.
+
+#### `_safe_warn` now writes through a configured logger
+
+- **FIXED**: Internal warnings for authentication, timeout, and cloud-code
+  errors (`Parse::Client._safe_warn`) always wrote to STDERR, even when an
+  app had configured `Parse.logger = Rails.logger` (or any other logger) for
+  the rest of its Parse request/response logging. These warnings now route
+  through `Parse::Middleware::Logging.logger` when one is configured, so they
+  land in the same place as the app's other logs; STDERR remains the fallback
+  when no logger is configured, matching prior behavior. Every call site
+  raises the corresponding typed `Parse::Error` immediately after this
+  warning, so a configured logger that itself raises (a closed handle, a
+  full disk, a remote-aggregator client erroring on a socket) now falls back
+  to STDERR rather than propagating in place of the real error and masking
+  it.
+
 ### 5.7.1
 
 #### Cache-invalidation webhooks no longer break every application hook for the same trigger

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/agent/mcp_dispatcher.rb

@@ -191,7 +191,7 @@ module Parse
 
         result_hash = dispatch(method, params, agent, id, logger, subscription_manager)
         { status: result_hash[:status], body: result_hash[:body] }
-      rescue Parse::Agent::Unauthorized => e
+      rescue Parse::Agent::Unauthorized
         { status: 401, body: jsonrpc_error(body.is_a?(Hash) ? body["id"] : nil, -32001, "Unauthorized") }
       rescue StandardError => e
         # Do not leak the exception class name (gem fingerprinting). Server-
@@ -295,7 +295,7 @@ module Parse
         else
           { status: 200, body: jsonrpc_envelope(id, result: result) }
         end
-      rescue Parse::Agent::Unauthorized => e
+      rescue Parse::Agent::Unauthorized
         { status: 401, body: jsonrpc_error(id, -32001, "Unauthorized") }
       rescue Parse::Agent::AccessDenied
         # Class-authorization denial (agent_hidden / classes: allowlist), e.g.

data/lib/parse/agent.rb

@@ -2475,7 +2475,6 @@ module Parse
       end
 
       ActiveSupport::Notifications.instrument("parse.agent.tool_call", payload) do
-        response = nil
         # Install a fresh embedding accumulator for this tool span. The
         # process-wide "parse.embeddings.embed" subscriber records each
         # embed into it; the ensure below reads + restores it so the

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/request.rb

@@ -17,12 +17,24 @@ module Parse
     # @!attribute [rw] body
     #   @return [Hash] the body of this request.
 
-    # TODO: Document opts and cache options.
-
     # @!attribute [rw] opts
-    #   @return [Hash] a set of options for this request.
+    #   @return [Hash] per-request options consumed by {Parse::Client#request}
+    #     when it builds the HTTP headers for this request. Recognized keys:
+    #     * `:cache` — `false` sends `Cache-Control: no-cache`; `:write_only`
+    #       skips the cache read but still writes the response; a `Numeric`
+    #       overrides the cache expiration (seconds) for this request only.
+    #     * `:use_master_key` — `false` forces the master key off for this
+    #       request even if the client has one configured.
+    #     * `:session_token` — a session token to authenticate this request as
+    #       a specific user, bypassing the client's default auth context.
+    #     * `:idempotent` — explicitly enables/disables idempotency-header
+    #       generation for this request, overriding the class-level defaults.
+    #     * `:request_id` — a caller-supplied idempotency key; see
+    #       {.enable_idempotency!}.
     # @!attribute [rw] cache
-    #   @return [Boolean]
+    #   @return [Boolean] unused by {Parse::Request} itself; retained as a
+    #     plain accessor for callers that stash a cache handle or flag
+    #     directly on the request object rather than through `opts[:cache]`.
     attr_accessor :method, :path, :body, :headers, :opts, :cache
 
     # @!visibility private