parse-stack-next 5.0.1 → 5.1.0

data/lib/parse/embeddings.rb

@@ -2,6 +2,8 @@
 # frozen_string_literal: true
 
 require "monitor"
+require "uri"
+require "ipaddr"
 
 module Parse
   # Pluggable embedding-provider registry for `:vector` properties and
@@ -74,6 +76,39 @@ module Parse
     # {ArgumentError} (not an {Error}) so config-time mistakes are
     # distinguishable from runtime provider failures.
     class ProviderNotRegistered < ArgumentError; end
+
+    # Raised when {Embeddings.trust_provider_url_fetch=} is assigned
+    # anything other than the deliberate-opt-in sentinel String, or
+    # when {.validate_image_url!} is called while the toggle is still
+    # off. Sentinel-gated opt-in mirrors {Parse::Object.acl_off_confirm}
+    # — a plain `true` is refused, preventing accidental enablement
+    # via `Parse::Embeddings.trust_provider_url_fetch = ENV['SOMETHING']`
+    # that an operator never intended to set. The only accepted value
+    # is the exact frozen String `"PROVIDER_EGRESS_VERIFIED"`.
+    #
+    # Threat model: image-URL forwarding hands an attacker-controlled
+    # URL (chat input, document field, agent tool argument) to a
+    # third-party provider that will then issue an HTTP request from
+    # its own network. Even with the SDK's CIDR / port / host
+    # allowlist enforced at validation time, the provider's actual
+    # fetch happens later (DNS-rebinding window) and can follow
+    # redirects the SDK never saw. Forcing operators to set a sentinel
+    # that explicitly names the egress risk makes it impossible to
+    # enable accidentally.
+    class ConfirmationRequired < Error; end
+
+    # Raised when {.validate_image_url!} rejects an input URL. Carries
+    # a `:reason` String so retry / logging code can branch on the
+    # specific failure mode (`:scheme`, `:port`, `:userinfo`, `:host_blocked`,
+    # `:host_not_allowlisted`, `:dns_rebound`, `:parse`).
+    class InvalidImageURL < Error
+      # @return [Symbol] failure-mode tag.
+      attr_reader :reason
+      def initialize(reason, message)
+        @reason = reason
+        super(message)
+      end
+    end
   end
 end
 
@@ -208,7 +243,303 @@ module Parse
       #
       # @return [void]
       def reset!
-        CONFIG_MUTEX.synchronize { @configuration = nil }
+        CONFIG_MUTEX.synchronize do
+          @configuration = nil
+          @allowed_image_hosts = nil
+          @trust_provider_url_fetch = nil
+        end
+      end
+
+      # =======================================================================
+      # Image-URL forwarding (v5.1) — SSRF-gated egress to provider boundaries
+      # =======================================================================
+
+      # The sentinel value that {.trust_provider_url_fetch=} requires.
+      # An exact match unlocks {.validate_image_url!} for URL forwarding
+      # to embedding providers. Any other value is refused with
+      # {ConfirmationRequired}. The constant is frozen so callers
+      # cannot mutate it in-place.
+      TRUST_PROVIDER_URL_FETCH_SENTINEL = "PROVIDER_EGRESS_VERIFIED"
+
+      # Configure the host allowlist that {.validate_image_url!} checks
+      # an incoming image URL's host against. Entries that begin with
+      # `.` match suffixes (`.cdn.example.com` matches
+      # `images.cdn.example.com` and `cdn.example.com` itself);
+      # entries without a leading `.` are exact-match.
+      #
+      # **Empty allowlist means "deny all".** This is the opposite
+      # default from {Parse::File.allowed_remote_hosts} (where empty
+      # means "any public host"). The asymmetry is deliberate: image
+      # URLs that reach {.validate_image_url!} typically originate from
+      # attacker-controlled inputs (chat queries, agent tool args,
+      # user-submitted document fields), so opening the surface
+      # requires an explicit operator declaration of which CDNs are
+      # trusted.
+      #
+      # @example Trust two CDN hostnames
+      #   Parse::Embeddings.allowed_image_hosts = [
+      #     "images.example-cdn.com",
+      #     ".cloudfront.net",   # any *.cloudfront.net host
+      #   ]
+      #
+      # @param hosts [Array<String>] hostnames or `.suffix` patterns.
+      # @return [Array<String>]
+      def allowed_image_hosts=(hosts)
+        unless hosts.is_a?(Array) && hosts.all? { |h| h.is_a?(String) && !h.empty? }
+          raise ArgumentError,
+                "Parse::Embeddings.allowed_image_hosts= expects Array<String> of " \
+                "non-empty hostnames or '.suffix' patterns (got #{hosts.inspect})."
+        end
+        CONFIG_MUTEX.synchronize { @allowed_image_hosts = hosts.dup.freeze }
+      end
+
+      # @return [Array<String>] currently-configured image-host allowlist (frozen).
+      def allowed_image_hosts
+        @allowed_image_hosts ||= [].freeze
+      end
+
+      # Sentinel-gated opt-in for forwarding image URLs to embedding
+      # providers. Assign the exact {TRUST_PROVIDER_URL_FETCH_SENTINEL}
+      # String to unlock; any other value (including `true`, `1`,
+      # `"true"`, or a non-matching String) raises
+      # {ConfirmationRequired}. Reset to `nil` to disable.
+      #
+      # @param value [String, nil] {TRUST_PROVIDER_URL_FETCH_SENTINEL} or nil.
+      # @raise [ConfirmationRequired] on any other value.
+      def trust_provider_url_fetch=(value)
+        if value.nil?
+          CONFIG_MUTEX.synchronize { @trust_provider_url_fetch = nil }
+          return
+        end
+        unless value.is_a?(String) && value == TRUST_PROVIDER_URL_FETCH_SENTINEL
+          raise ConfirmationRequired,
+                "Parse::Embeddings.trust_provider_url_fetch= requires the exact sentinel " \
+                "String #{TRUST_PROVIDER_URL_FETCH_SENTINEL.inspect}. Plain `true` and " \
+                "other values are refused — forwarding image URLs to a third-party " \
+                "provider lets that provider issue an HTTP request from its own network " \
+                "with attacker-controllable host/path. Set the sentinel only after you " \
+                "have configured Parse::Embeddings.allowed_image_hosts AND reviewed the " \
+                "provider's documented egress behavior (DNS rebinding window, redirect " \
+                "policy)."
+        end
+        CONFIG_MUTEX.synchronize { @trust_provider_url_fetch = value }
+      end
+
+      # @return [Boolean] whether image-URL forwarding is currently unlocked.
+      def trust_provider_url_fetch?
+        @trust_provider_url_fetch == TRUST_PROVIDER_URL_FETCH_SENTINEL
+      end
+
+      # Validate an image URL for forwarding to an embedding provider.
+      # Returns the canonicalized URL String on success; raises
+      # {InvalidImageURL} or {ConfirmationRequired} on failure.
+      #
+      # Validation layers (in order):
+      # 1. {.trust_provider_url_fetch?} sentinel must be set. Without
+      #    it, no URL — public or private — is forwarded.
+      # 2. URL parses as `https://` (or `http://` if `allow_insecure:`
+      #    is true; only intended for local development).
+      # 3. No userinfo (basic-auth credentials in the URL).
+      # 4. Port is in {Parse::File.allowed_remote_ports}.
+      # 5. Host resolves only to addresses NOT in
+      #    {Parse::File::BLOCKED_CIDRS} (CIDR check via
+      #    `Parse::File.assert_host_allowed!`). The same primitive is
+      #    used by {Parse::File.safe_open_url}, so the SSRF mechanism
+      #    is shared.
+      # 6. Host matches {.allowed_image_hosts}. Empty allowlist denies
+      #    every host — see {.allowed_image_hosts=} for rationale.
+      #
+      # The DNS-rebinding window between this validation and the
+      # provider's own fetch is the residual risk that
+      # {.trust_provider_url_fetch=} forces the operator to acknowledge.
+      #
+      # @param url [String] image URL.
+      # @param allow_insecure [Boolean] permit `http://` (default
+      #   false). Only meaningful for local development / container-
+      #   internal CDN proxies.
+      # @return [String] canonicalized URL (`URI.parse(url).to_s`).
+      # @raise [ConfirmationRequired] when the sentinel is unset.
+      # @raise [InvalidImageURL] on any other validation failure.
+      def validate_image_url!(url, allow_insecure: false)
+        unless trust_provider_url_fetch?
+          hint =
+            if allowed_image_hosts.empty?
+              " First populate Parse::Embeddings.allowed_image_hosts with the CDN " \
+              "hostnames you trust (currently empty — every host would be denied " \
+              "even after the sentinel is set)."
+            else
+              ""
+            end
+          raise ConfirmationRequired,
+                "Parse::Embeddings.validate_image_url! refused: image-URL forwarding is " \
+                "disabled. Set Parse::Embeddings.trust_provider_url_fetch = " \
+                "#{TRUST_PROVIDER_URL_FETCH_SENTINEL.inspect} to enable it.#{hint}"
+        end
+
+        unless url.is_a?(String) && !url.empty?
+          raise InvalidImageURL.new(:parse,
+            "Parse::Embeddings.validate_image_url!: url must be a non-empty String " \
+            "(got #{url.class}).")
+        end
+
+        uri = begin
+          URI.parse(url)
+        rescue URI::InvalidURIError => e
+          raise InvalidImageURL.new(:parse,
+            "Parse::Embeddings.validate_image_url!: invalid URL (#{e.message}).")
+        end
+
+        valid_schemes = allow_insecure ? %w[http https] : %w[https]
+        unless valid_schemes.include?(uri.scheme)
+          raise InvalidImageURL.new(:scheme,
+            "Parse::Embeddings.validate_image_url!: scheme must be #{valid_schemes.join(' or ')} " \
+            "(got #{uri.scheme.inspect}). Forwarding non-HTTPS image URLs to a provider " \
+            "leaks any embedded query-string secrets in cleartext.")
+        end
+
+        if uri.userinfo
+          raise InvalidImageURL.new(:userinfo,
+            "Parse::Embeddings.validate_image_url!: URL must not include userinfo " \
+            "credentials. Embedding providers will forward the full URL in their fetch " \
+            "and may log it.")
+        end
+
+        # `uri.hostname` returns the IDNA-decoded form WITHOUT IPv6
+        # brackets, where `uri.host` keeps the brackets. Using
+        # `hostname` makes the allowlist comparison work uniformly for
+        # IPv6 literals (operators write `::1`, not `[::1]`) and
+        # matches the form `Parse::File.assert_host_allowed!` expects.
+        host = uri.hostname
+        if host.nil? || host.empty?
+          raise InvalidImageURL.new(:parse,
+            "Parse::Embeddings.validate_image_url!: URL is missing a host.")
+        end
+
+        # Reject non-canonical IPv4 forms (decimal `2130706433`,
+        # octal `0177.0.0.1`, hex `0x7f.0.0.1`) before they reach
+        # resolution. Most stacks' Resolv returns [] for these, so
+        # they'd be blocked anyway — but via the resolution-failure
+        # branch (`:parse` reason) rather than the CIDR branch, which
+        # makes the failure mode look like a benign typo when it's
+        # actually an obfuscated-localhost SSRF attempt. Explicitly
+        # tagging the failure as `:host_blocked` keeps operator logs
+        # honest. We allow exactly: dotted-quad IPv4 (4 decimal
+        # octets), bracketed-or-bare IPv6 (parsed by IPAddr), and
+        # DNS hostnames (anything containing a letter or non-numeric
+        # character).
+        if ip_shaped_but_not_canonical?(host)
+          raise InvalidImageURL.new(:host_blocked,
+            "Parse::Embeddings.validate_image_url!: host #{host.inspect} is an obfuscated " \
+            "or non-canonical IP literal. Use dotted-quad IPv4 (a.b.c.d) or canonical IPv6. " \
+            "Decimal/octal/hex IP forms are refused to prevent localhost-bypass attempts.")
+        end
+
+        # **Image-host allowlist runs BEFORE the resolver hop.** Round-2
+        # audit (LOW finding #3) noted that a caller passing N URLs to
+        # a public `embed_image` API could amplify DNS traffic at ~N×
+        # before the allowlist filtered them out — the pure-string
+        # match is cheap, the resolution is a syscall. Allowlist-first
+        # ordering eliminates the amplification surface.
+        allowed = allowed_image_hosts
+        if allowed.empty?
+          raise InvalidImageURL.new(:host_not_allowlisted,
+            "Parse::Embeddings.validate_image_url!: Parse::Embeddings.allowed_image_hosts " \
+            "is empty — every image URL is denied. Add the CDN hostnames you trust before " \
+            "forwarding image URLs to a provider.")
+        end
+        permitted = allowed.any? do |entry|
+          if entry.start_with?(".")
+            host.downcase.end_with?(entry.downcase) ||
+              host.casecmp(entry[1..]).zero?
+          else
+            host.casecmp(entry).zero?
+          end
+        end
+        unless permitted
+          raise InvalidImageURL.new(:host_not_allowlisted,
+            "Parse::Embeddings.validate_image_url!: host #{host.inspect} not in " \
+            "Parse::Embeddings.allowed_image_hosts (#{allowed.inspect}).")
+        end
+
+        # Port allowlist runs after the host allowlist (cheap string
+        # check first). Reuses Parse::File's port allowlist — same
+        # threat model (internal-port probing via DNS rebinding).
+        port = uri.port || (uri.scheme == "https" ? 443 : 80)
+        require_relative "model/file"
+        unless Parse::File.allowed_remote_ports.include?(port)
+          raise InvalidImageURL.new(:port,
+            "Parse::Embeddings.validate_image_url!: port #{port} not in " \
+            "Parse::File.allowed_remote_ports.")
+        end
+
+        # CIDR + DNS resolution last — most expensive (syscall). An
+        # allowlisted CDN hostname pointing at a private IP (DNS
+        # poisoning / hostile-allowlist-entry / first-party rebind)
+        # is the residual surface this catches. Delegates to
+        # Parse::File's shared SSRF primitive.
+        begin
+          Parse::File.assert_host_allowed!(host)
+        rescue ArgumentError => e
+          tag = e.message.include?("private/internal address") ? :host_blocked : :parse
+          raise InvalidImageURL.new(tag,
+            "Parse::Embeddings.validate_image_url!: #{e.message}")
+        end
+
+        # Return the canonicalized URL so callers store/forward
+        # exactly what was validated, not the raw input.
+        uri.to_s
+      end
+
+      # @api private
+      # Return true when `host` looks like an obfuscated IP literal —
+      # rejecting hex (`0x7f.0.0.1`), octal-leading-zero (`0177.0.0.1`),
+      # decimal-blob (`2130706433`), and IPv4 short-forms (`127.1`,
+      # `127.0.1`) BEFORE they reach DNS resolution. Anything that's
+      # clearly a hostname (contains a letter) falls through; canonical
+      # dotted-quad IPv4 and canonical IPv6 fall through; everything
+      # else is treated as obfuscated.
+      #
+      # Round-2 audit identified two bypasses in the prior version:
+      # (1) `0x7f.0.0.1` passed the `[a-zA-Z]` early-out because of
+      # the `x`, and (2) bare-digit hostnames like `127.1` were
+      # accepted as DNS hostnames. This rewrite makes the check
+      # whitelist-shaped: explicit accept for canonical IPv4 / IPv6 /
+      # alpha-containing hostnames; explicit reject for hex prefix and
+      # any pure digits-and-dots that isn't a canonical 4-octet form.
+      def ip_shaped_but_not_canonical?(host)
+        # Hex prefix anywhere in the host (`0x7f`, `0.0X7f.0.1`) →
+        # obfuscated. Case-insensitive `x`.
+        return true if host =~ /(\A|\.)0[xX]/
+
+        # Strict canonical dotted-quad IPv4: exactly 4 decimal octets,
+        # 0..255, no leading zeros (except `0` itself).
+        if host =~ /\A\d+(?:\.\d+){3}\z/
+          octets = host.split(".")
+          return true if octets.any? { |s| s.length > 1 && s.start_with?("0") }  # octal
+          return true if octets.map(&:to_i).any? { |o| o > 255 }                 # > 255
+          return false
+        end
+
+        # Numeric-only with dots but not 4 octets (`127.1`, `1.2.3`,
+        # `1.2.3.4.5`) → IPv4 short-form / oversized. Refuse.
+        return true if host =~ /\A\d+(?:\.\d+)+\z/
+
+        # Pure-digit single label (`2130706433`, `0`, `42`) → decimal
+        # IP blob. Refuse.
+        return true if host =~ /\A\d+\z/
+
+        # Anything else: try parsing as IPv6 (canonical IPv6 literals
+        # like `::1`, `2001:db8::1`, `::ffff:1.2.3.4` succeed; the
+        # CIDR check downstream catches private ranges including
+        # IPv4-mapped IPv6 of private IPv4).
+        begin
+          IPAddr.new(host)
+          false
+        rescue IPAddr::InvalidAddressError
+          # Not an IP, not numeric-shaped → must be a hostname.
+          # Resolver downstream will validate or reject.
+          false
+        end
       end
     end
   end

data/lib/parse/live_query/client.rb

@@ -66,6 +66,39 @@ module Parse
       # @return [String, nil] Parse master key
       attr_reader :master_key
 
+      # @return [Boolean] whether this is an admin connection that sends
+      #   the master key on the connect frame. When true, EVERY
+      #   subscription on this connection bypasses ACL/CLP enforcement
+      #   (Parse Server resolves master-key authorization per-connection
+      #   at connect time, never per-subscription). Defaults to false.
+      attr_reader :use_master_key
+
+      # @return [Boolean] true when this connection will actually send a
+      #   master key on the connect frame: the admin opt-in
+      #   (`use_master_key: true`) is set AND a usable (non-empty String)
+      #   master key is present. The single source of truth for "will
+      #   this socket bypass ACL/CLP for every subscription." A bare
+      #   `use_master_key: true` with no key is NOT an admin connection.
+      def admin_connection?
+        @use_master_key && @master_key.is_a?(String) && !@master_key.empty?
+      end
+
+      # Redacting inspect — the default `inspect` dumps every instance
+      # variable, which would expose `@master_key`, `@client_key`, and
+      # the per-subscription session tokens in any log line, backtrace,
+      # Rails error page, or APM/error-reporter (Sentry / Honeybadger /
+      # Rollbar / Bugsnag) that renders the object. `Configuration#to_h`
+      # already redacts these; this keeps the live Client object
+      # consistent with that contract.
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} url=#{@url.inspect} " \
+        "application_id=#{@application_id.inspect} state=#{@state.inspect} " \
+        "admin_connection=#{admin_connection?} subscriptions=#{@subscriptions.size} " \
+        "client_key=#{redacted_secret(@client_key)} " \
+        "master_key=#{redacted_secret(@master_key)}>"
+      end
+
       # @return [Symbol] connection state (:disconnected, :connecting, :connected, :closed)
       attr_reader :state
 
@@ -106,11 +139,23 @@ module Parse
       #   explicitly to force client-mode (no master key on the
       #   subscription handshake) even when the parent Parse client has
       #   one. Omit the argument to fall back to the LiveQuery config
-      #   or the parent Parse client.
+      #   or the parent Parse client. NOTE: holding a master key does
+      #   NOT by itself elevate the connection — see `use_master_key:`.
+      # @param use_master_key [Boolean] build an ADMIN connection: send
+      #   the master key on the connect frame so the LiveQuery server
+      #   skips ACL/CLP enforcement for ALL subscriptions on this
+      #   socket. Defaults to false — connections are ACL-scoped by
+      #   their per-subscription session tokens unless you explicitly
+      #   opt in. Parse Server resolves master-key authorization
+      #   per-CONNECTION at connect time (`_handleConnect` →
+      #   `client.hasMasterKey`); there is no per-subscription master
+      #   key. For a process that needs both scoped and admin streams,
+      #   build two clients. Requires a master key to be present
+      #   (otherwise the flag is a no-op and a warning is emitted).
       # @param auto_connect [Boolean] connect immediately (default: true)
       # @param auto_reconnect [Boolean] automatically reconnect on disconnect (default: true)
       def initialize(url: nil, application_id: nil, client_key: nil, master_key: NOT_PROVIDED,
-                     auto_connect: nil, auto_reconnect: nil)
+                     use_master_key: NOT_PROVIDED, auto_connect: nil, auto_reconnect: nil)
         cfg = config
 
         # Use provided values or fall back to configuration/environment
@@ -124,6 +169,17 @@ module Parse
           else
             master_key
           end
+        # Admin-connection opt-in. Defaults to false (ACL-scoped). Only
+        # an explicit `use_master_key: true` here — or `config.use_master_key
+        # = true` — sends the master key on the connect frame. This is the
+        # v5.1.0 security fix: prior versions sent the master key on the
+        # connect frame whenever one was merely present, silently
+        # elevating every subscription on the socket past ACL/CLP.
+        @use_master_key = if use_master_key.equal?(NOT_PROVIDED)
+            cfg.respond_to?(:use_master_key) ? !!cfg.use_master_key : false
+          else
+            use_master_key == true
+          end
 
         @auto_connect = auto_connect.nil? ? cfg.auto_connect : auto_connect
         @auto_reconnect = auto_reconnect.nil? ? cfg.auto_reconnect : auto_reconnect
@@ -290,8 +346,25 @@ module Parse
       # @param where [Hash] query constraints
       # @param fields [Array<String>] specific fields to watch
       # @param session_token [String] session token for ACL-aware subscriptions
+      # @param use_master_key [Boolean] assert that this subscription
+      #   needs master-key (ACL-bypassing) scope. Parse Server has NO
+      #   per-subscription master key — authorization is fixed per
+      #   connection at connect time — so this flag does NOT elevate a
+      #   single subscription on a scoped socket. It is honored only when
+      #   this client is an admin connection (built with
+      #   `use_master_key: true`), in which case the whole connection is
+      #   already elevated. On a non-admin connection, passing
+      #   `use_master_key: true` emits a warning and the subscription
+      #   stays ACL-scoped. See {Subscription#initialize}.
+      # @yield [subscription] runs the block with the freshly-
+      #   constructed {Subscription} BEFORE the subscribe frame is
+      #   sent to the server, so callbacks registered inside the block
+      #   (`sub.on(:create) { … }`, etc.) are wired before any server
+      #   events can arrive. Optional — callers may still capture the
+      #   returned subscription and register callbacks later.
       # @return [Subscription]
-      def subscribe(class_name, where: {}, fields: nil, session_token: nil)
+      def subscribe(class_name, where: {}, fields: nil, session_token: nil,
+                    use_master_key: false, &block)
         # Handle Parse::Object subclass
         if class_name.is_a?(Class) && class_name < Parse::Object
           class_name = class_name.parse_class
@@ -316,12 +389,15 @@ module Parse
         # user-influenced filter path.
         Parse::PipelineSecurity.validate_filter!(where) if where.is_a?(Hash) && !where.empty?
 
+        warn_subscription_scope_mismatch(use_master_key, session_token)
+
         subscription = Subscription.new(
           client: self,
           class_name: class_name,
           query: where,
           fields: fields,
           session_token: session_token,
+          use_master_key: use_master_key,
         )
 
         @monitor.synchronize do
@@ -332,6 +408,29 @@ module Parse
                       request_id: subscription.request_id,
                       class_name: class_name)
 
+        # Yield the subscription BEFORE the subscribe frame goes out so
+        # caller-registered callbacks are wired before any server event
+        # can arrive on this request_id. Order matters: subscribe-frame-
+        # then-yield would race a fast server response against the
+        # callback registration on a hot socket.
+        #
+        # If the caller's block raises, ROLL BACK the registry insert
+        # before re-raising. Without this, the failed-block
+        # subscription stays in `@subscriptions` and the next
+        # `resubscribe_all` (triggered by a reconnect) wire-sends it
+        # to the server — a ghost subscription the caller thought
+        # they had aborted.
+        if block_given?
+          begin
+            yield(subscription)
+          rescue
+            @monitor.synchronize do
+              @subscriptions.delete(subscription.request_id)
+            end
+            raise
+          end
+        end
+
         # Send subscribe message if connected
         if connected?
           send_message(subscription.to_subscribe_message)
@@ -381,6 +480,13 @@ module Parse
 
       private
 
+      # Render a secret for {#inspect}: "[REDACTED]" when present,
+      # "nil" when absent. Mirrors Configuration#to_h's redaction so a
+      # secret value never reaches inspect output.
+      def redacted_secret(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?) ? "nil" : "[REDACTED]"
+      end
+
       # Get configuration object
       # @return [Configuration]
       def config
@@ -916,11 +1022,68 @@ module Parse
         }
 
         message[:clientKey] = @client_key if @client_key
-        message[:masterKey] = @master_key if @master_key
+        # Only elevate the connection when the caller explicitly opted
+        # into an admin connection. Parse Server reads `masterKey` ONCE,
+        # from the connect frame, and stores `client.hasMasterKey` for
+        # the lifetime of the socket; once set, every subscription
+        # bypasses ACL/CLP/protectedFields. Sending it unconditionally
+        # (the pre-5.1.0 behavior) silently elevated session-token
+        # subscriptions the caller believed were scoped.
+        if admin_connection?
+          message[:masterKey] = @master_key
+          warn_master_key_connection_once
+        elsif @use_master_key
+          # Opted into admin mode but no usable master key is present —
+          # the flag can't take effect. Warn rather than silently run
+          # ACL-scoped when the caller asked for admin.
+          Logging.warn("LiveQuery use_master_key: true but no master key is " \
+                       "configured — connection will be ACL-scoped, not elevated")
+        end
 
         send_message(message)
       end
 
+      # One-time loud warning that this connection bypasses ACL/CLP for
+      # every subscription. Master-key LiveQuery is connection-level, so
+      # this is the only place the risk can be surfaced.
+      def warn_master_key_connection_once
+        return if @master_key_warning_emitted
+        @master_key_warning_emitted = true
+        warn "[Parse::LiveQuery:SECURITY] connection established with master key " \
+             "(use_master_key: true) — ALL subscriptions on this connection " \
+             "BYPASS ACL/CLP enforcement and receive every matching object " \
+             "regardless of the object's ACL. Session tokens on subscriptions " \
+             "of this connection do NOT scope results. Use a non-admin client " \
+             "(the default) for end-user, ACL-scoped streams."
+      end
+
+      # Surface the two ways a caller's intended subscription scope can
+      # silently disagree with the connection's actual authorization.
+      # Both are "you think you're scoped (or elevated) but you're not."
+      def warn_subscription_scope_mismatch(use_master_key, session_token)
+        if use_master_key && !admin_connection?
+          return if @per_sub_master_key_warning_emitted
+          @per_sub_master_key_warning_emitted = true
+          warn "[Parse::LiveQuery:SECURITY] subscribe(use_master_key: true) on a " \
+               "non-admin connection has NO effect — Parse Server has no " \
+               "per-subscription master key; ACL-bypass authorization is fixed " \
+               "per connection at connect time. This subscription stays " \
+               "ACL-scoped (by its session token, or public if none). To bypass " \
+               "ACL, build an admin connection: " \
+               "Parse::LiveQuery::Client.new(use_master_key: true). For mixed " \
+               "scoped + admin needs, use two separate clients."
+        elsif admin_connection? && session_token
+          return if @admin_session_token_warning_emitted
+          @admin_session_token_warning_emitted = true
+          warn "[Parse::LiveQuery:SECURITY] subscribe(session_token:) on an admin " \
+               "connection (use_master_key: true) does NOT scope results — the " \
+               "connection bypasses ACL/CLP for every subscription, so this " \
+               "stream returns objects the session-token user cannot normally " \
+               "read. Use a non-admin client for ACL-scoped, session-token " \
+               "streams."
+        end
+      end
+
       # Send a message through the WebSocket
       def send_message(message)
         data = message.is_a?(String) ? message : message.to_json

data/lib/parse/live_query/configuration.rb

@@ -26,6 +26,14 @@ module Parse
       # @return [String] Parse master key (optional)
       attr_accessor :master_key
 
+      # @return [Boolean] build admin connections that send the master
+      #   key on the connect frame, bypassing ACL/CLP for ALL
+      #   subscriptions. Defaults to false — connections are ACL-scoped.
+      #   Set true ONLY for dedicated admin/event-tap consumers; never
+      #   for clients that serve end-user, session-scoped streams. See
+      #   {Parse::LiveQuery::Client#use_master_key}.
+      attr_accessor :use_master_key
+
       # @return [Boolean] automatically connect on client creation (default: true)
       attr_accessor :auto_connect
 
@@ -130,6 +138,9 @@ module Parse
         @application_id = nil
         @client_key = nil
         @master_key = nil
+        # ACL-scoped by default; opt into admin (ACL-bypassing)
+        # connections explicitly. See attr doc above.
+        @use_master_key = false
         @auto_connect = true
         @auto_reconnect = true
 
@@ -199,6 +210,7 @@ module Parse
           application_id: @application_id,
           client_key: @client_key.nil? ? nil : "[REDACTED]",
           master_key: @master_key.nil? ? nil : "[REDACTED]",
+          use_master_key: @use_master_key,
           auto_connect: @auto_connect,
           auto_reconnect: @auto_reconnect,
           ping_interval: @ping_interval,