parse-stack-next 5.2.1 → 5.3.0

data/docs/mcp_guide.md

@@ -3106,6 +3106,66 @@ Four different refusal reasons each produce a distinct `:error_code` and message
 
 **Resolution order at dispatch:** operator filter ▷ mutation gate ▷ mode ceiling ▷ in-tool class gate. Operator-filter precedence is deliberate — when a tool is excluded by both the operator's `tools: { except: [...] }` AND the mutation gate (or the mode ceiling), the operator-filter message wins so the operator looks at the right knob first. The mode-ceiling message names the tool, not the class — even when the request would have hit an `agent_hidden` class, the ceiling fires first for a refused tool, so the LLM does not learn anything about the class. For tools that pass the ceiling (e.g. `query_class`) the in-tool `assert_class_accessible!` runs next and the `agent_hidden` message echoes the class name supplied by the caller.
 
+### Client mode from a webhook — run a handler as the calling user (v5.3.0)
+
+Parse Server includes the caller's live session token (`user.sessionToken`) in
+every trigger webhook fired by a logged-in user (it is absent for a master-key
+request). `Parse::Webhooks::Payload` captures that token before scrubbing it out
+of `payload.user` / `payload.object` (so it never lands in `payload.as_json` or
+the request log) and exposes two opt-in, user-scoped handles — the webhook
+counterpart of constructing a client-mode agent by hand:
+
+```ruby
+Parse::Webhooks.route(:after_save, "Post") do
+  # self is the Parse::Webhooks::Payload.
+  next true unless session_token?            # master-key save → no caller token
+
+  # A client-mode Parse::Agent bound to the caller — ACL/CLP enforced, no
+  # master-key fallback. Same posture as Parse::Agent.new(session_token:, client: <no master_key>).
+  visible = user_agent.execute(:query_class, class_name: "Post", limit: 20)
+
+  # …or a raw user-scoped Parse::Client (token is BOUND, so plain REST calls
+  # are authorized as the user with no per-call session_token: needed):
+  mine = user_client.request(:get, "classes/Post").result
+  true
+end
+```
+
+| Payload handle | Returns | `nil` when |
+|----------------|---------|-----------|
+| `payload.session_token` | the caller's raw token (`String`) | master-key request (no user) |
+| `payload.user_agent(**opts)` | non-master `Parse::Agent` in **client mode**, token bound | no token |
+| `payload.user_client` | non-master `Parse::Client` with the token **bound** | no token |
+
+`user_client` binds the token via the new `Parse::Client.new(session_token:)`
+option, applied as the lowest-priority auth fallback on every request — an
+explicit per-call `session_token:`, a `Parse.with_session` block, or an explicit
+`use_master_key: true` all still take precedence. Everything the Client Mode
+ceiling above says about a hand-built client-mode agent applies verbatim to
+`payload.user_agent`: read tools only unless `allow_mutations: true`, and
+`acl_user:` / `acl_role:` are not available on a no-master client.
+
+The same user-scoped client is available client-side from a login
+(`Parse::User#session_client`, or `Parse.client.become(token)` from any token),
+and `Parse::User#with_session` / `Parse::Client#with_session` run a block as the
+user so ordinary model operations are implicitly scoped:
+
+```ruby
+client = Parse::User.login(username, password).session_client   # non-master, token bound
+Parse::Query.new("Post", client: client).results                # query as the user
+Parse::User.login(username, password).with_session { Post.query.count }
+```
+
+`with_session` (and `Parse.with_session`) authorize **REST-routed** operations
+(`find` / `get` / `count` / `save`) as the user. Mongo-direct queries
+(`results_direct`, `aggregate`, Atlas search) do NOT pick up the ambient
+session — they resolve auth from the query's own `session_token:` / `acl_user:`
+and otherwise run in **master** mode (a full master read, not anonymous), so
+scope them explicitly with a per-query `session_token:` or a scoped
+`Parse::Agent`. This is deliberate: mongo-direct scoping is always explicit in
+this SDK, so the ambient fiber state can never silently flip a mongo-direct
+query into user scope (or be mistaken for it).
+
 ---
 
 ## `agent_hidden` — Per-Class Agent-Surface Denial

data/lib/parse/client.rb

@@ -331,7 +331,86 @@ module Parse
     attr_accessor :cache
     attr_writer :retry_limit
     attr_reader :application_id, :api_key, :master_key, :server_url
+    # @return [String, nil] the session token bound to this client, if any
+    #   (see the `:session_token` constructor option). Applied as the
+    #   lowest-priority auth fallback on every request.
+    attr_reader :session_token
     alias_method :app_id, :application_id
+
+    # Redacted inspection. The default Ruby `#inspect` would dump every ivar,
+    # exposing the master key and any bound session token in cleartext wherever
+    # a client is logged or surfaced in an error reporter. Show only the
+    # connection identity and a boolean for each credential's presence.
+    def inspect
+      "#<#{self.class.name} server_url=#{@server_url.inspect} " \
+      "app_id=#{@application_id.inspect} master_key=#{@master_key ? "[FILTERED]" : "nil"} " \
+      "session_token=#{@session_token ? "[FILTERED]" : "nil"}>"
+    end
+
+    # A NEW non-master {Parse::Client} that mirrors THIS client's connection
+    # settings (`server_url` / `application_id` / `api_key`) but carries no
+    # master key and binds +session_token+, so it acts on the server as that
+    # user (ACL / CLP / `protectedFields` enforced, no master-key fallback).
+    # This is the general primitive behind {Parse::Webhooks::Payload#user_client}
+    # and {Parse::User#session_client}: derive a user-scoped client from a
+    # configured (e.g. master) client without re-specifying the connection.
+    #
+    #   user_client = Parse.client.become(user.session_token)
+    #   Parse::Query.new("Post", client: user_client).results   # as the user
+    #
+    # @param session_token [String, #session_token] the token to bind. A blank
+    #   token yields a tokenless non-master client (anonymous REST).
+    # @return [Parse::Client]
+    def become(session_token)
+      Parse::Client.new(
+        server_url: @server_url,
+        app_id: @application_id,
+        api_key: @api_key,
+        master_key: nil,
+        session_token: session_token,
+      )
+    end
+
+    # A NEW anonymous client that mirrors THIS client's connection but carries
+    # neither a master key nor a session token — every request it makes is
+    # unauthenticated (app-id + REST key only). Use it to drop the bound user
+    # identity for a one-off public read without mutating a shared client.
+    # Equivalent to {#become} with no token.
+    # @return [Parse::Client]
+    def anonymous
+      become(nil)
+    end
+
+    # Run a block with this client's bound {#session_token} active as the
+    # ambient session, so every query / object operation inside it that resolves
+    # the default client (e.g. `Post.count`, `Post.all`, `obj.save`) is
+    # authorized by Parse Server as that user — ACL and CLP enforced, master key
+    # suppressed — without threading `session_token:` through each call.
+    #
+    # This is the client-receiver flavor of {Parse.with_session} (and mirrors
+    # {Parse::User#with_session}); it scopes by binding the token as the AMBIENT
+    # session — it does not re-route operations through this client object, so
+    # the connection used inside the block is still the resolved default client.
+    # If you need operations to run against a different client, pass that client
+    # explicitly (e.g. `Parse::Query.new("Post", client: #{become}(...))`).
+    #
+    #   total = Parse::User.login(u, p).with_session { Post.count }   # readable Posts only
+    #
+    # Scopes REST-routed operations (`find` / `get` / `count` / `save`). It does
+    # NOT scope mongo-direct queries (`results_direct`, `aggregate`, Atlas
+    # search): those resolve auth from the query's own `session_token:` /
+    # `acl_user:` and, absent that, run in MASTER mode — so a mongo-direct read
+    # inside this block is a full master read, not anonymous. Scope mongo-direct
+    # explicitly with a per-query `session_token:` or a scoped {Parse::Agent}.
+    #
+    # @raise [ArgumentError] if this client has no bound session token (scoping
+    #   would be a no-op and almost certainly a mistake).
+    # @return the value of the block.
+    def with_session(&block)
+      raise ArgumentError, "Parse::Client#with_session requires a block" unless block_given?
+      raise ArgumentError, "Parse::Client#with_session requires a client with a bound session_token" if @session_token.nil?
+      Parse.with_session(@session_token, &block)
+    end
     # The client can support multiple sessions. The first session created, will be placed
     # under the default session tag. The :default session will be the default client to be used
     # by the other classes including Parse::Query and Parse::Objects
@@ -415,6 +494,14 @@ module Parse
     # @option opts [String] :master_key The Parse application master key (optional).
     #    If this key is set, it will be sent on every request sent by the client
     #    and your models. Defaults to ENV['PARSE_SERVER_MASTER_KEY'].
+    # @option opts [String] :session_token An optional session token bound to
+    #    this client. When set, every request that does not pass an explicit
+    #    `session_token:` / `use_master_key: true` and is not inside a
+    #    `Parse.with_session` block sends this token (and suppresses the master
+    #    key), so the client transparently acts as that user. Precedence is
+    #    explicit per-call > `Parse.with_session` ambient > this bound token.
+    #    Typically paired with `master_key: nil` to build a user-scoped client
+    #    (see {Parse::Webhooks::Payload#user_client}).
     # @option opts [Boolean, Symbol] :logging Controls request/response logging.
     #    - `true` - Enable logging at :info level
     #    - `:debug` - Enable verbose logging with headers and body content
@@ -492,7 +579,26 @@ module Parse
       @server_url = opts[:server_url] || ENV["PARSE_SERVER_URL"] || Parse::Protocol::SERVER_URL
       @application_id = opts[:application_id] || opts[:app_id] || ENV["PARSE_SERVER_APPLICATION_ID"] || ENV["PARSE_APP_ID"]
       @api_key = opts[:api_key] || opts[:rest_api_key] || ENV["PARSE_SERVER_REST_API_KEY"] || ENV["PARSE_API_KEY"]
-      @master_key = opts[:master_key] || ENV["PARSE_SERVER_MASTER_KEY"] || ENV["PARSE_MASTER_KEY"]
+      # Distinguish an explicit `master_key: nil` (deliberately a non-master
+      # client — what user_client / session_client / user_agent rely on) from
+      # an omitted key (fall back to ENV). The previous `opts[:master_key] ||
+      # ENV[...]` form silently re-inherited the process master key for the
+      # explicit-nil case, putting a "non-master" client back into master mode
+      # in any deployment that exports PARSE_SERVER_MASTER_KEY / PARSE_MASTER_KEY.
+      @master_key = if opts.key?(:master_key)
+                      opts[:master_key]
+                    else
+                      ENV["PARSE_SERVER_MASTER_KEY"] || ENV["PARSE_MASTER_KEY"]
+                    end
+      # Optional token bound to this client; applied per request as the
+      # lowest-priority auth fallback (see #request). Normalize blank/whitespace
+      # to nil so it never trips the "token present" branch at request time
+      # (where `present?` is false for whitespace) and silently fall back to the
+      # master key on a master-configured client.
+      bound_token = opts[:session_token]
+      bound_token = bound_token.session_token if bound_token.respond_to?(:session_token)
+      bound_token = bound_token.to_s.strip
+      @session_token = bound_token.empty? ? nil : bound_token
 
       @require_https = opts.fetch(:require_https, ENV["PARSE_REQUIRE_HTTPS"] == "true")
       @allow_faraday_proxy = opts.fetch(:allow_faraday_proxy, false)
@@ -1016,14 +1122,20 @@ module Parse
 
       token = opts[:session_token]
       # When no explicit token was passed AND the caller didn't ask to send
-      # the master key, fall through to the fiber-local ambient set by
-      # `Parse.with_session`. Explicit `use_master_key: true` is treated as
-      # a deliberate admin call and skips the ambient — otherwise an
-      # `admin.do_thing(use_master_key: true)` nested inside a
-      # `with_session(user)` block would silently downgrade.
+      # the master key, fall through to (in order) the fiber-local ambient set
+      # by `Parse.with_session`, then this client's own bound `@session_token`.
+      # Explicit `use_master_key: true` is treated as a deliberate admin call
+      # and skips both — otherwise an `admin.do_thing(use_master_key: true)`
+      # nested inside a `with_session(user)` block (or on a token-bound client)
+      # would silently downgrade. The ambient wins over the bound token so a
+      # `with_session` override inside a user-scoped client still takes effect.
       if token.nil? && !(explicit_master && opts[:use_master_key] == true)
         ambient = Parse.current_session_token
-        token = ambient if ambient.is_a?(String) && !ambient.empty?
+        # A whitespace-only ambient must not count as present: otherwise it
+        # blocks the bound-token fallback below and then fails the later
+        # `token.present?` check, silently sending the master key instead.
+        token = ambient if ambient.is_a?(String) && !ambient.strip.empty?
+        token = @session_token if (token.nil? || token.to_s.strip.empty?) && @session_token
       end
       if token.present?
         token = token.session_token if token.respond_to?(:session_token)

data/lib/parse/model/associations/belongs_to.rb

@@ -119,6 +119,23 @@ module Parse
 
         # These items are added as attributes with the special data type of :pointer
         def belongs_to(key, opts = {})
+          # An explicitly-passed `as:` that names a scalar data type
+          # (`:string`, `:integer`, `:boolean`, …) is almost always a mistake —
+          # you cannot point at a scalar — and most often means a `property`
+          # was written with `as:` out of habit. Reject it at declaration time.
+          # This is the only association footgun decidable without all models
+          # loaded: an unresolved *class* name may simply be a forward
+          # reference (the target is required later), so that check is deferred
+          # to {Parse.validate_associations!}.
+          explicit_as = opts.key?(:as) ? opts[:as] : nil
+          if explicit_as && Parse::Properties::TYPES.include?(explicit_as.to_s.to_sym)
+            scalar = explicit_as.to_s.to_sym
+            raise ArgumentError,
+                  "#{self}##{key}: `as: #{explicit_as.inspect}` names the reserved data type " \
+                  ":#{scalar}, not a Parse class. For a scalar column write " \
+                  "`property #{key.inspect}, #{scalar.inspect}`; if you really mean a Parse class " \
+                  "named #{scalar.to_s.camelize.inspect}, pass `class_name: #{scalar.to_s.camelize.inspect}` instead."
+          end
           opts = { as: key, field: key.to_s.camelize(:lower), required: false }.merge(opts)
           # `opts[:class_name]` is the explicit target Parse class name; it takes
           # precedence over the legacy `as: :symbol` shorthand (where the
@@ -134,6 +151,22 @@ module Parse
           set_attribute_method = :"#{key}_set_attribute!"
 
           if self.fields[key].present? && Parse::Properties::BASE_FIELD_MAP[key].nil?
+            existing_type = self.fields[key]
+            # A structural redeclaration that CHANGES the type to a pointer
+            # (e.g. a field first declared `property :owner, :string` and then
+            # `property :owner, as: :user` / `belongs_to :owner`) is almost
+            # always a bug — and, because `property … as:` now delegates here,
+            # it is the same silent-String failure mode this whole feature
+            # exists to fix. Honor the same `strict_property_redefinition`
+            # contract that `property` enforces so the conflict is not
+            # downgraded to a warning. A same-type reopen (existing :pointer)
+            # still just warns, matching the prior behavior.
+            if existing_type != :pointer && Parse.strict_property_redefinition
+              raise ArgumentError,
+                    "#{self}##{key} is already defined as :#{existing_type}; refusing to " \
+                    "redeclare it as a :pointer association (target #{klassName}). Set " \
+                    "Parse.strict_property_redefinition = false to fall back to warn-and-ignore."
+            end
             warn "Belongs relation #{self}##{key} already defined with type #{klassName}"
             return false
           end
@@ -151,6 +184,20 @@ module Parse
           # Mapping between local attribute name and the remote column name
           self.field_map.merge!(key => parse_field)
 
+          # Agent metadata: a belongs_to pointer can carry a semantic description
+          # (and per-value enum descriptions) just like a `property` can. This
+          # also lets `property :x, as: :user, _description: "..."` round-trip its
+          # metadata through the delegation in Parse::Properties#property.
+          if opts[:_description].present?
+            self.property_descriptions[key] = opts[:_description].to_s.freeze
+          end
+          if opts[:_enum].is_a?(Hash) && opts[:_enum].any?
+            normalized = opts[:_enum].each_with_object({}) do |(value, desc), h|
+              h[value.to_s] = desc.to_s.freeze
+            end
+            self.property_enum_descriptions[key] = normalized.freeze
+          end
+
           # used for dirty tracking
           define_attribute_methods key
 

data/lib/parse/model/classes/user.rb

@@ -835,6 +835,26 @@ module Parse
       @session
     end
 
+    # A non-master {Parse::Client} bound to this user's session token, for
+    # acting on the server *as this user* with full ACL / CLP / +protectedFields+
+    # enforcement and no master-key fallback. It mirrors the connection settings
+    # of +base+ (the configured client by default) but carries no master key and
+    # binds {#session_token}, so even raw REST calls through it are authorized as
+    # the user with no per-call ceremony. The web-counterpart of
+    # {Parse::Webhooks::Payload#user_client}; the typical client-side entry point
+    # is right after a login:
+    #
+    #   client = Parse::User.login(username, password).session_client
+    #   Parse::Query.new("Post", client: client).results   # scoped to the user
+    #
+    # @param base [Parse::Client] the client whose connection settings to mirror.
+    # @return [Parse::Client, nil] +nil+ when the user has no session token
+    #   (e.g. fetched/saved under the master key rather than logged in).
+    def session_client(base = self.client)
+      return nil if @session_token.nil? || @session_token.to_s.strip.empty?
+      base.become(@session_token)
+    end
+
     # @!visibility private
     # Keys that must never flow through +Parse::User.create+ from a
     # mass-assigned hash. +authData+ on the user-signup endpoint causes

data/lib/parse/model/core/pluralized_aliases.rb

@@ -0,0 +1,30 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  # Global `const_missing` hook that lazily resolves the plural form of a
+  # {Parse::Object} subclass constant to that class. Referencing `Posts`
+  # when a class `Post` exists installs `Posts` as an alias for `Post` on
+  # the referencing module and returns it, so query entry points like
+  # `Posts.where(...).count` work without any per-model boilerplate.
+  #
+  # The hook is prepended onto `Module` so it applies to constant lookups
+  # in any namespace (top-level and nested). It is tightly guarded: every
+  # path that is not a plural-of-a-Parse-class falls through to `super`,
+  # preserving normal `NameError` and autoloader (Zeitwerk/classic)
+  # behavior. The whole feature is gated on {Parse.pluralized_aliases?} so
+  # opting out (`Parse.pluralized_aliases = false`) makes this a near-zero
+  # cost pass-through.
+  #
+  # @see Parse.pluralized_aliases
+  # @see Parse.__pluralized_alias_for
+  module PluralizedAliases
+    def const_missing(name)
+      klass = Parse.__pluralized_alias_for(self, name) if defined?(Parse)
+      return klass unless klass.nil?
+      super
+    end
+  end
+end
+
+Module.prepend(Parse::PluralizedAliases)

data/lib/parse/model/core/properties.rb

@@ -197,6 +197,33 @@ module Parse
           # data_type = :timezone if key == :time_zone || key == :timezone
         end
 
+        # A property that names a pointer target — via `as:`/`class_name:` or an
+        # explicit :pointer data type — is really a belongs_to association, not a
+        # scalar column. Delegate so `property :rejected_by, as: :user` behaves
+        # identically to `belongs_to :rejected_by, as: :user` instead of silently
+        # storing a String (the `as:` option was previously dropped, leaving the
+        # field as the default :string type). Reusing belongs_to keeps the
+        # className-trust guard and autofetch/dirty-tracking in one place rather
+        # than duplicating pointer handling here. `opts` is still raw user input
+        # at this point (the defaults merge happens further down), so only an
+        # explicitly-passed :field is forwarded and belongs_to defaults the rest.
+        if opts.key?(:as) || opts.key?(:class_name) || data_type == :pointer
+          forwarded = %i[as class_name field required _description _enum]
+          bt_opts = {}
+          forwarded.each { |o| bt_opts[o] = opts[o] if opts.key?(o) }
+          # belongs_to has no scalar-property machinery (defaults, symbolize,
+          # enum validation, alias toggles, scope generation). Surface — rather
+          # than silently drop — any such option so a `default:`/`symbolize:` on
+          # a pointer property isn't quietly ignored.
+          dropped = opts.keys.map(&:to_sym) - forwarded
+          unless dropped.empty?
+            warn "[#{self}] property #{key.inspect} resolves to a pointer association; " \
+                 "ignoring unsupported option(s) #{dropped.map(&:inspect).join(', ')} " \
+                 "(not available on belongs_to)."
+          end
+          return belongs_to(key, bt_opts)
+        end
+
         data_type = :timezone if data_type == :string && (key == :time_zone || key == :timezone)
 
         # allow :bool for :boolean

data/lib/parse/model/core/querying.rb

@@ -120,6 +120,76 @@ module Parse
 
       alias_method :where, :query
 
+      # Define a pluralized constant alias for this class so the plural form
+      # can be used as a query entry point — e.g. `Posts.where(...).count`
+      # for a class `Post`. The alias is the same class object, so every
+      # class method (`where`, `query`, `count`, `find`, `all`, scopes)
+      # works through it and `Posts.parse_class` still returns `"Post"`.
+      #
+      # This is the explicit counterpart to the automatic
+      # {Parse.pluralized_aliases} behavior. Use it when automatic aliasing
+      # is disabled, when the class name ends in `s` (which the automatic
+      # path skips), when you want a custom plural, or for namespaced models
+      # (the alias is defined on the enclosing module, not at top level).
+      #
+      # @example default plural
+      #   class Post < Parse::Object
+      #     pluralized_alias!          # defines ::Posts => Post
+      #   end
+      #
+      # @example custom plural for a name ending in `s`
+      #   class Status < Parse::Object
+      #     pluralized_alias! :Statuses
+      #   end
+      #
+      # @example namespaced model
+      #   module Blog
+      #     class Post < Parse::Object
+      #       pluralized_alias!        # defines Blog::Posts => Blog::Post
+      #     end
+      #   end
+      #
+      # @param constant_name [Symbol, String, nil] the plural constant to
+      #   define; defaults to the ActiveSupport pluralization of the class's
+      #   demodulized name.
+      # @raise [ArgumentError] if the target constant already exists and is
+      #   not this class.
+      # @return [self, nil] self when an alias exists/was created; nil if the
+      #   class is anonymous or the plural matches the singular name.
+      def pluralized_alias!(constant_name = nil)
+        base = name
+        return nil if base.nil?
+        parts = base.split("::")
+        short = parts.last
+        plural = (constant_name && constant_name.to_s) || short.pluralize
+        return nil if plural == short
+        # NOTE: bare `Object` here would lexically resolve to `Parse::Object`
+        # (we are inside module Parse::Core::Querying), so the alias must be
+        # anchored at the true top level with `::Object`.
+        parent = parts.length > 1 ? parts[0..-2].join("::").constantize : ::Object
+        if parent.const_defined?(plural.to_sym, false)
+          existing = parent.const_get(plural.to_sym)
+          return self if existing.equal?(self)
+          # A code reloader (Zeitwerk in development) swaps `self` for a fresh
+          # class object but does not clean up the alias constant we set — it
+          # owns no autoload entry for it. On re-run of the class body the
+          # plural still points at the now-orphaned previous class. Re-point it
+          # to the current class instead of raising on every reload. Only a
+          # genuinely foreign constant (not a Parse model mapping to the same
+          # remote class) is treated as a conflict.
+          stale_reload = existing.is_a?(Class) && existing < Parse::Object &&
+                         existing.parse_class == parse_class
+          unless stale_reload
+            raise ArgumentError,
+                  "Cannot define pluralized alias #{plural} for #{base}: " \
+                  "constant already defined as #{existing}."
+          end
+          parent.send(:remove_const, plural.to_sym)
+        end
+        parent.const_set(plural.to_sym, self)
+        self
+      end
+
       # @param conditions (see Parse::Query#where)
       # @return (see Parse::Query#where)
       # @see Parse::Query#where

data/lib/parse/model/file.rb

@@ -734,10 +734,43 @@ module Parse
       ATTRIBUTES
     end
 
-    # @return [Boolean] Two files are equal if they have the same url
+    # The value used to decide whether two {Parse::File}s refer to the same
+    # underlying file -- for equality ({#==}) and, through it, for dirty
+    # tracking (the property setter compares files with `==` to decide whether
+    # a `:file` field changed).
+    #
+    # Today this is the bare canonical {#url}: signed-URL query parameters are
+    # stripped into `@presigned_url` and `force_ssl` coercion is applied, so two
+    # files at the same storage location compare equal regardless of how the URL
+    # was signed or whether it was `http`/`https`. The URL is the best identity
+    # signal currently available -- Parse Server's S3 files adapter does not
+    # surface a content digest (ETag / MD5 / sha256) through `Parse::File`.
+    #
+    # FUTURE DIRECTION: when a files adapter can expose a content hash, this is
+    # the single seam to override so equality keys off file *content* instead of
+    # URL -- e.g. a custom `Parse::File` subclass or adapter shim returning the
+    # S3 ETag / sha256 here. Overriding this one method updates {#==} (and a
+    # future `#eql?`/`#hash` pair, if added) without touching dirty tracking.
+    # No content-hash source exists yet, so the URL is authoritative for now.
+    # @return [String, nil]
+    def content_signature
+      url
+    end
+
+    # @return [Boolean] Two files are equal when their {#content_signature}
+    #   matches. Both sides go through the same reader, so the comparison is
+    #   symmetric and force_ssl-consistent: the previous `@url == u.url` form
+    #   compared one side's raw stored URL against the other's normalized
+    #   reader, so two files at the same location read as unequal whenever
+    #   {Parse::File.force_ssl} coerced one side from `http://` to `https://`
+    #   (and `a == b` disagreed with `b == a`). Because the default signature is
+    #   the bare canonical URL (signed-URL query parameters stripped into
+    #   `@presigned_url`), a freshly re-signed URL for the same object is equal
+    #   while a different underlying location is not. See {#content_signature}
+    #   for the content-hash override seam.
     def ==(u)
       return false unless u.is_a?(self.class)
-      @url == u.url
+      content_signature == u.content_signature
     end
 
     # Allows mass assignment from a Parse JSON hash.

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.2.1"
+    VERSION = "5.3.0"
   end
 end