parse-stack-next 5.1.1 → 5.2.1

data/lib/parse/retrieval/retriever.rb

@@ -0,0 +1,274 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "chunker"
+require_relative "chunk"
+
+module Parse
+  # Retrieval-augmented-generation (RAG) helpers. `Parse::RAG` is a
+  # discoverability alias for this module.
+  #
+  # {.retrieve} is the agent-agnostic core: it embeds a natural-language
+  # query, runs Atlas `$vectorSearch` through the existing
+  # `Class.find_similar` (which enforces ACL/CLP mongo-direct), then
+  # splits each retrieved document's text field into scored
+  # {Parse::Retrieval::Chunk}s for presentation.
+  #
+  # The agent-facing `semantic_search` tool (see
+  # `lib/parse/retrieval/agent_tool.rb`) wraps {.retrieve} with the
+  # agent security envelope (tenant scope, `field_allowlist` projection,
+  # score quantization).
+  #
+  # == ACL model
+  #
+  # {.retrieve} does NOT implement a REST "two-stage" re-query. The
+  # vector path is mongo-direct only (Parse Server's REST `/aggregate`
+  # is master-key-only and bypasses ACL — see the project notes), and
+  # `acl_user:` / `acl_role:` scopes have no REST equivalent. ACL is
+  # enforced inside `find_similar` via a post-`$vectorSearch` `_rperm`
+  # `$match`. Scope kwargs (`session_token:` / `acl_user:` /
+  # `acl_role:` / `master:`) pass straight through `**scope_opts`.
+  module Retrieval
+    # Raised when a tenant-scope value conflicts with a caller-supplied
+    # `vector_filter` constraint on the same field — a scope-spoofing
+    # attempt. Mirrors the agent layer's tenant-scope refusal.
+    class TenantScopeConflict < ArgumentError; end
+
+    # Raised when the text field to chunk cannot be inferred from the
+    # class's `embed` declarations and was not passed explicitly.
+    class AmbiguousTextField < ArgumentError; end
+
+    module_function
+
+    # Recursively refuse any underscore-prefixed key, at any depth, in a
+    # caller-supplied filter. This is distinct from (and stricter than)
+    # the agent layer's flat `validate_keys!`: a Mongo-style filter is a
+    # nested structure, and an underscore key buried inside `$or` /
+    # `$elemMatch` / a hash value could clobber tenant scope or reach a
+    # reserved column (`_rperm`, `_p_*`, `_auth_data_*`). The walk is
+    # unconditional — it does not special-case operators.
+    #
+    # @param obj [Object] a filter Hash/Array (or anything; scalars pass).
+    # @param path [Array<String>] internal — accumulates the key path for
+    #   the error message.
+    # @raise [ArgumentError] on any `_`-prefixed key.
+    def assert_no_underscore_keys!(obj, path = [])
+      case obj
+      when Hash
+        obj.each do |k, v|
+          ks = k.to_s
+          if ks.start_with?("_")
+            raise ArgumentError,
+                  "filter key '#{(path + [ks]).join(".")}' is reserved (underscore-prefixed)."
+          end
+          assert_no_underscore_keys!(v, path + [ks])
+        end
+      when Array
+        obj.each_with_index { |v, i| assert_no_underscore_keys!(v, path + ["[#{i}]"]) }
+      end
+      obj
+    end
+
+    # Retrieve and chunk documents semantically similar to `query`.
+    #
+    # @param query [String] natural-language query.
+    # @param klass [Class, String] a Parse::Object subclass (or its
+    #   class name) declaring a `:vector` property. `class:` is accepted
+    #   as an alias.
+    # @param field [Symbol, nil] the `:vector` property to search.
+    #   Auto-resolved by `find_similar` when the class has exactly one.
+    # @param text_field [Symbol, nil] the text property to chunk for
+    #   presentation. Defaults to the sole text source of the class's
+    #   `embed` declaration; raises {AmbiguousTextField} when it can't be
+    #   inferred.
+    # @param k [Integer] number of documents to retrieve. Default 10.
+    # @param filter [Hash, nil] post-`$vectorSearch` `$match` filter.
+    # @param vector_filter [Hash, nil] Atlas-native pre-search filter.
+    # @param chunker [#chunk_with_meta, #chunk, nil] chunking strategy.
+    #   Defaults to {Chunker::FixedSizeOverlap}.
+    # @param tenant_scope [Hash, nil] `{ field:, value: }` merged into
+    #   `vector_filter` (closing the cross-tenant existence side
+    #   channel) — not just a post-stage match.
+    # @param score_quantize [Boolean] round scores to 1 decimal (limits
+    #   membership-inference probing in non-admin contexts).
+    # @param source_transform [#call, nil] optional callable applied to
+    #   each raw source record before it is stored on a Chunk. The agent
+    #   tool injects tenant-scope assertion + `field_allowlist`
+    #   projection here; a `StandardError` raised by the callable
+    #   propagates and aborts the whole call (fail-closed). Kept as an
+    #   injection point so this model-layer method stays free of any
+    #   agent-layer dependency.
+    # @param hybrid [Object, nil] reserved — raises {NotImplementedError}
+    #   if truthy. Hybrid (vector + lexical) retrieval lands in a later
+    #   release; the kwarg locks the API shape now.
+    # @param rerank [Object, nil] reserved — raises {NotImplementedError}
+    #   if non-nil. Cross-encoder rerank lands in a later release.
+    # @param scope_opts [Hash] ACL/CLP scope kwargs forwarded verbatim to
+    #   `find_similar`: `session_token:` / `acl_user:` / `acl_role:` /
+    #   `master:`.
+    # @return [Array<Parse::Retrieval::Chunk>] descending by score; chunk
+    #   order within a document is positional.
+    def retrieve(query:, klass: nil, field: nil, text_field: nil, k: 10,
+                 filter: nil, vector_filter: nil, chunker: nil,
+                 tenant_scope: nil, score_quantize: false,
+                 source_transform: nil, hybrid: nil, rerank: nil,
+                 **scope_opts)
+      raise NotImplementedError,
+            "Parse::Retrieval.retrieve: `hybrid:` is reserved for a future release." if hybrid
+      raise NotImplementedError,
+            "Parse::Retrieval.retrieve: `rerank:` is reserved for a future release." if rerank
+
+      # `class:` alias (reserved word — arrives via **scope_opts).
+      klass ||= scope_opts.delete(:class)
+      klass = resolve_class!(klass)
+
+      unless query.is_a?(String) && !query.strip.empty?
+        raise ArgumentError, "Parse::Retrieval.retrieve: `query:` must be a non-empty String."
+      end
+
+      resolved_text_field = (text_field || infer_text_field!(klass)).to_sym
+      merged_vector_filter = fold_tenant_scope(klass, vector_filter, tenant_scope)
+      chunker ||= default_chunker
+
+      raw_hits = klass.find_similar(
+        text: query,
+        k: k,
+        field: field,
+        filter: filter,
+        vector_filter: merged_vector_filter,
+        raw: true,
+        **scope_opts,
+      )
+      return [] if raw_hits.nil? || raw_hits.empty?
+
+      text_wire = wire_name(klass, resolved_text_field)
+
+      raw_hits.flat_map do |doc|
+        build_chunks_for(doc, klass, text_wire, score_quantize, source_transform, chunker)
+      end
+    end
+
+    # @!visibility private
+    def resolve_class!(klass)
+      resolved =
+        case klass
+        when nil
+          nil
+        when Class
+          klass
+        else
+          Parse::Model.find_class(klass.to_s)
+        end
+      unless resolved.is_a?(Class) && resolved.respond_to?(:find_similar)
+        raise ArgumentError,
+              "Parse::Retrieval.retrieve: `klass:`/`class:` must be a Parse::Object " \
+              "subclass with a :vector property (got #{klass.inspect})."
+      end
+      resolved
+    end
+
+    # @!visibility private
+    # Infer the text field to chunk from the class's `embed` directives:
+    # the sole text (non-image) source field. Raises when zero or more
+    # than one candidate exists — the caller must then pass `text_field:`.
+    def infer_text_field!(klass)
+      directives = klass.respond_to?(:embed_directives) ? klass.embed_directives.values : []
+      sources = directives.reject { |d| d.respond_to?(:image?) && d.image? }
+                          .flat_map(&:sources).uniq
+      return sources.first if sources.length == 1
+      raise AmbiguousTextField,
+            "Parse::Retrieval.retrieve: cannot infer the text field to chunk for " \
+            "#{klass} (candidates: #{sources.inspect}); pass `text_field:` explicitly."
+    end
+
+    # @!visibility private
+    def default_chunker
+      Chunker::FixedSizeOverlap.new(size: 800, overlap: 100)
+    end
+
+    # @!visibility private
+    # Merge the tenant scope into the Atlas pre-search filter using the
+    # field's wire/storage column name. A pre-existing constraint on the
+    # same field with a different value is a spoof attempt and is refused.
+    def fold_tenant_scope(klass, vector_filter, tenant_scope)
+      return vector_filter if tenant_scope.nil?
+      field = tenant_scope[:field] || tenant_scope["field"]
+      value = tenant_scope.key?(:value) ? tenant_scope[:value] : tenant_scope["value"]
+      return vector_filter if field.nil?
+
+      wire = wire_name(klass, field)
+      base = vector_filter ? vector_filter.dup : {}
+      existing_key = base.keys.find { |k| k.to_s == wire }
+      if existing_key && base[existing_key] != value
+        raise TenantScopeConflict,
+              "Parse::Retrieval.retrieve: vector_filter pins #{wire.inspect} to " \
+              "#{base[existing_key].inspect} but the tenant scope requires #{value.inspect}."
+      end
+      base[wire] = value
+      base
+    end
+
+    # @!visibility private
+    # Ruby property symbol -> wire/storage column name. Prefers the
+    # class's explicit field_map alias; falls back to lowerCamelCase
+    # columnization. Matches the resolution MetadataRegistry uses.
+    def wire_name(klass, field)
+      sym = field.to_sym
+      fmap = klass.respond_to?(:field_map) ? klass.field_map : {}
+      mapped = fmap[sym]
+      (mapped || sym.to_s.columnize).to_s
+    end
+
+    # @!visibility private
+    def fetch_field(doc, wire, sym)
+      return doc[wire] if doc.key?(wire)
+      return doc[wire.to_sym] if doc.key?(wire.to_sym)
+      return doc[sym.to_s] if doc.key?(sym.to_s)
+      doc[sym]
+    end
+
+    # @!visibility private
+    def build_chunks_for(doc, klass, text_wire, score_quantize, source_transform, chunker)
+      object_id = (doc["_id"] || doc[:_id] || doc["objectId"] || doc[:objectId]).to_s
+      raw_score = doc["_vscore"] || doc[:_vscore]
+      score = quantize_score(raw_score, score_quantize)
+
+      text = fetch_field(doc, text_wire, text_wire)
+      meta = chunker.respond_to?(:chunk_with_meta) ? chunker.chunk_with_meta(text) : nil
+      chunks = meta ? meta[:chunks] : Array(chunker.chunk(text))
+      truncated = meta ? meta[:truncated] : false
+      # A document that matched on its vector but carries no presentation
+      # text yields no chunks (skipped, not an empty-content chunk).
+      return [] if chunks.empty?
+
+      source = source_transform ? source_transform.call(doc) : doc
+      count = chunks.length
+      chunks.each_with_index.map do |content, idx|
+        Chunk.new(
+          id: "#{object_id}##{idx}",
+          content: content,
+          score: score,
+          source: source,
+          metadata: {
+            chunk_index: idx,
+            chunk_count: count,
+            chunks_truncated: truncated,
+            object_id: object_id,
+            class: klass.parse_class,
+          },
+        )
+      end
+    end
+
+    # @!visibility private
+    def quantize_score(score, quantize)
+      return score if score.nil?
+      f = score.to_f
+      quantize ? ((f * 10).round / 10.0) : f
+    end
+  end
+
+  # Discoverability alias. "RAG" ages badly as a term; `Retrieval` is
+  # the canonical name.
+  RAG = Retrieval
+end

data/lib/parse/retrieval.rb

@@ -0,0 +1,10 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Parse::Retrieval — retrieval-augmented-generation (RAG) helpers.
+#
+# Entry point that loads the chunker, the {Parse::Retrieval::Chunk}
+# value object, and the {Parse::Retrieval.retrieve} core. The
+# `semantic_search` agent tool (which depends on the agent layer) is
+# loaded separately from `lib/parse/agent.rb`.
+require_relative "retrieval/retriever"

data/lib/parse/schema.rb

@@ -231,16 +231,23 @@ module Parse
       end
 
       # Fields defined locally but missing on server.
-      # @return [Hash] field name => type pairs
+      #
+      # Iterates the model's `field_map` (one entry per canonical property,
+      # canonical name => wire column name) rather than `fields` (which carries
+      # both the snake_case and camelCase keys for every property and therefore
+      # double-counts multi-word fields). The wire name resolved from
+      # `field_map` is the authoritative server column — including custom
+      # `field:` mappings — so this both dedupes and fixes custom-column
+      # detection. Result is keyed by the CANONICAL (snake) name with the type
+      # taken from `fields[name]`.
+      # @return [Hash] canonical field name => type pairs
       def missing_on_server
-        return local_fields unless server_exists?
-
-        local = local_fields
-        server = server_field_names
+        server = server_exists? ? server_field_names : []
         missing = {}
-        local.each do |name, type|
-          name_str = name.to_s.camelize(:lower)
-          missing[name] = type unless server.include?(name_str) || core_field?(name)
+        @model_class.field_map.each do |name, wire|
+          next if core_field?(name)
+          next if server.include?(wire.to_s)
+          missing[name] = @model_class.fields[name]
         end
         missing
       end
@@ -262,15 +269,25 @@ module Parse
       end
 
       # Fields with type mismatches.
-      # @return [Hash] field name => { local: type, server: type }
+      #
+      # Iterates `field_map` (canonical name => wire column) rather than
+      # deriving the server key with `camelize(:lower)`, so a property with a
+      # custom `field:` wire column (e.g. `property :post_id, field:
+      # "postIdentifier"`) resolves to its real server column instead of a
+      # camelized guess. This both dedupes multi-word fields (which appear
+      # under two keys in `fields`) and matches the `missing_on_server`
+      # resolution path, so type drift on custom-mapped columns is no longer
+      # silently skipped.
+      # @return [Hash] canonical field name => { local: type, server: type }
       def type_mismatches
         return {} unless server_exists?
 
         mismatches = {}
-        local_fields.each do |name, local_type|
+        @model_class.field_map.each do |name, wire|
           next if core_field?(name)
-          name_str = name.to_s.camelize(:lower)
-          server_type = @server_schema.field_type(name_str)
+          local_type = @model_class.fields[name]
+          next if local_type.nil?
+          server_type = @server_schema.field_type(wire.to_s)
           next unless server_type
 
           # Normalize types for comparison
@@ -285,11 +302,30 @@ module Parse
       end
 
       # Check if schemas are in sync.
+      #
+      # Strict / bidirectional: requires the local and server schemas to match
+      # in BOTH directions — no fields missing on the server, no fields missing
+      # locally, and no type mismatches. A server that is a strict superset of
+      # the local model is NOT "in sync" by this measure (use
+      # {#server_covers_local?} for the one-way local ⊆ server check).
       # @return [Boolean]
       def in_sync?
         missing_on_server.empty? && missing_locally.empty? && type_mismatches.empty?
       end
 
+      # Check whether the server schema covers every locally-defined field.
+      #
+      # One-way (local ⊆ server): true when nothing the model declares is
+      # missing on the server and there are no type mismatches. Unlike
+      # {#in_sync?}, this ignores server-only columns, so a server that is a
+      # strict superset of the local model still satisfies it. This is the
+      # predicate that determines whether a migration has any work to do —
+      # extra server columns are not something the migrator would add.
+      # @return [Boolean]
+      def server_covers_local?
+        missing_on_server.empty? && type_mismatches.empty?
+      end
+
       # Generate a human-readable summary.
       # @return [String]
       def summary
@@ -355,9 +391,17 @@ module Parse
       end
 
       # Check if migration is needed.
+      #
+      # A migration is needed when the class does not yet exist on the server,
+      # or when the server does not already cover every locally-defined field.
+      # Defined in terms of the one-way {SchemaDiff#server_covers_local?} rather
+      # than the strict bidirectional {SchemaDiff#in_sync?} so that a server
+      # which is a strict superset of the local model (extra server-only
+      # columns the migrator would never add) does not report a "needed"
+      # migration with zero operations.
       # @return [Boolean]
       def needed?
-        !@diff.in_sync? || !@diff.server_exists?
+        !@diff.server_exists? || !@diff.server_covers_local?
       end
 
       # Get the operations that would be performed.
@@ -372,7 +416,7 @@ module Parse
         @diff.missing_on_server.each do |name, type|
           ops << {
             action: :add_field,
-            field: name.to_s.camelize(:lower),
+            field: @model_class.field_map[name].to_s,
             type: REVERSE_TYPE_MAP[type] || "String",
           }
         end
@@ -424,7 +468,7 @@ module Parse
 
         # Add missing fields
         @diff.missing_on_server.each do |name, type|
-          field_name = name.to_s.camelize(:lower)
+          field_name = @model_class.field_map[name].to_s
           field_schema = { "fields" => { field_name => field_definition(type) } }
 
           response = @client.update_schema(@model_class.parse_class, field_schema)
@@ -444,15 +488,20 @@ module Parse
 
       def build_schema
         fields = {}
-        @model_class.fields.each do |name, type|
+        # Iterate `field_map` (canonical name => wire column) rather than
+        # `fields`, which carries both the snake_case and camelCase keys for
+        # every property and would emit a duplicate/phantom column for each
+        # multi-word or custom-`field:` property.
+        @model_class.field_map.each do |name, wire|
           next if %i[id object_id created_at updated_at acl objectId createdAt updatedAt ACL].include?(name)
-          field_name = name.to_s.camelize(:lower)
-          fields[field_name] = field_definition(type)
+          fields[wire.to_s] = field_definition(@model_class.fields[name])
         end
 
-        # Add pointer targets
+        # Add pointer targets. `references` is keyed by the wire column name
+        # (the `parse_field`), so use it as-is — do not re-camelize, which
+        # would corrupt custom `field:` pointer columns.
         @model_class.references.each do |name, target_class|
-          field_name = name.to_s.camelize(:lower)
+          field_name = name.to_s
           fields[field_name] = {
             "type" => "Pointer",
             "targetClass" => target_class.to_s,

data/lib/parse/stack/version.rb

@@ -2,10 +2,10 @@
 # frozen_string_literal: true
 
 module Parse
-  # @author Anthony Persaud, Henry Spindell, Adrian Curtin
+  # @author Adrian Curtin, Anthony Persaud, Henry Spindell
   # The Parse Server SDK for Ruby
   module Stack
     # The current version.
-    VERSION = "5.1.1"
+    VERSION = "5.2.1"
   end
 end

data/lib/parse/webhooks/payload.rb

@@ -78,24 +78,35 @@ module Parse
         hash = Hash[hash.map { |k, v| [k.to_s.underscore.to_sym, v] }]
         @raw = hash
         @master = hash[:master]
-        # Strip protected mass-assignment keys (sessionToken, _rperm, _wperm,
-        # _hashed_password, authData, roles, etc.) BEFORE constructing the
-        # user object. Without this, an attacker reaching the webhook
-        # endpoint with a valid key (or with the optional unauthenticated
-        # mode enabled) can forge any of these fields on +payload.user+
-        # via the +objectId+-present hydration branch that bypasses the
-        # +Parse::Object#apply_attributes!+ protected-key filter.
+        # Webhook trigger payloads (beforeSave/afterSave/etc.) are delivered by
+        # Parse Server and, when a webhook key is configured (the default; see
+        # Parse::Webhooks.allow_unauthenticated for the opt-out used in tests /
+        # local dev), authenticated by it -- so they are treated as trusted,
+        # server-authoritative state. A handler is meant to receive the full
+        # object -- createdAt/updatedAt, ACL, internal fields and all. The only
+        # thing stripped here is genuine credential material a handler never
+        # legitimately needs to read (live session tokens, offline-crackable
+        # password hashes); see WEBHOOK_TRIGGER_CREDENTIAL_KEYS. Protection
+        # against *persisting* forged privileged fields lives on the write path
+        # (changes_payload emits only declared, dirty-tracked properties), not on
+        # this read path.
         if hash[:user].present?
-          @user = Parse::User.new(self.class.scrub_protected_keys(hash[:user]))
+          # Trusted hydration via .build (not .new) so server-sent timestamps and
+          # data fields remain readable; credentials are removed first. Note
+          # Parse::User applies its own protections, so `payload.user.auth_data`
+          # is not exposed here. The built object is pristine, so a handler that
+          # saves payload.user transmits nothing (no dirty changes) and cannot
+          # persist forgeries.
+          @user = Parse::User.build(self.class.scrub_credentials(hash[:user]))
         end
         @installation_id = hash[:installation_id]
         @params = hash[:params]
         @params = @params.with_indifferent_access if @params.is_a?(Hash)
         @function_name = hash[:function_name]
-        @object = self.class.scrub_protected_keys(hash[:object])
+        @object = self.class.scrub_credentials(hash[:object])
         @trigger_name = hash[:trigger_name]
-        @original = self.class.scrub_protected_keys(hash[:original])
-        @update = self.class.scrub_protected_keys(hash[:update]) || {}
+        @original = self.class.scrub_credentials(hash[:original])
+        @update = self.class.scrub_credentials(hash[:update]) || {}
         # Added for beforeFind and afterFind triggers
         @query = hash[:query]
         @objects = hash[:objects] || []
@@ -103,25 +114,32 @@ module Parse
       end
 
       # @!visibility private
-      # Routing metadata that must be preserved on payload hashes even
-      # though the general mass-assignment denylist forbids it. Stripping
-      # +className+ here breaks +parse_class+/+parse_object+ resolution and
-      # silently disables +payload_class_mismatch?+. The denylist still
-      # protects +Parse::Object#apply_attributes!+ at hydration time.
-      PAYLOAD_PRESERVED_KEYS = %w[className __type].freeze
+      # Genuine credential material that is stripped from every webhook trigger
+      # payload before a handler can see it, even though the rest of the
+      # (trusted, server-authoritative) payload passes through untouched. A
+      # session token is a live bearer credential; a password hash is
+      # offline-crackable. A handler has no legitimate reason to read either,
+      # and removing them keeps them out of logs and out of any object a handler
+      # might persist. Everything else Parse Server sends -- createdAt/updatedAt,
+      # ACL, authData, roles, _rperm/_wperm, internal fields -- is preserved so
+      # the handler observes the full object. Write-side protection
+      # (changes_payload emits only declared, dirty-tracked properties) is what
+      # prevents persisting forged privileged fields.
+      WEBHOOK_TRIGGER_CREDENTIAL_KEYS = %w[
+        sessionToken session_token
+        _hashed_password _password_history
+      ].freeze
 
       # @!visibility private
-      # Returns a copy of +obj+ with the +PROTECTED_MASS_ASSIGNMENT_KEYS+
-      # removed, except for routing metadata in +PAYLOAD_PRESERVED_KEYS+.
-      # Operates on string and symbol keys (Parse Server uses camelCase
+      # Returns a copy of +obj+ with only +WEBHOOK_TRIGGER_CREDENTIAL_KEYS+
+      # removed. Operates on string and symbol keys (Parse Server uses camelCase
       # strings on the wire; downstream code may have already symbolized).
       # Pass-through for non-Hash input.
-      def self.scrub_protected_keys(obj)
+      def self.scrub_credentials(obj)
         return obj unless obj.is_a?(Hash)
-        denied = Parse::Properties::PROTECTED_MASS_ASSIGNMENT_KEYS
+        denied = WEBHOOK_TRIGGER_CREDENTIAL_KEYS
         obj.reject do |k, _|
           name = k.to_s
-          next false if PAYLOAD_PRESERVED_KEYS.include?(name)
           denied.include?(name) || denied.include?(name.underscore)
         end
       end
@@ -278,24 +296,34 @@ module Parse
           if @original.present? && @original.is_a?(Hash)
             o = Parse::Object.build @original, parse_class
             o.apply_attributes! @object, dirty_track: true
-
-            if o.is_a?(Parse::User) && @update.present? && @update["authData"].present?
-              o.auth_data = @update["authData"]
-            end
             return o
           else #else the object must be new
             klass = Parse::Object.find_class parse_class
             # if we have a class, return that with updated changes, otherwise
             # default to regular object
-            if klass.present?
-              o = klass.new(@object || {})
-              if o.is_a?(Parse::User) && @update.present? && @update["authData"].present?
-                o.auth_data = @update["authData"]
-              end
-              return o
-            end # if klass.present?
+            return klass.new(@object || {}) if klass.present?
           end # if we have original
         end # if before_trigger?
+
+        # afterSave on an UPDATE: build the prior state, then overlay the final
+        # state with dirty tracking so `*_changed?` / `changes` work inside
+        # afterSave handlers (symmetric with the beforeSave path above). The
+        # filter uses the timestamp-preserving INITIALIZE key set rather than the
+        # wide mass-assignment set: the wide set would strip the incoming
+        # `updatedAt` from the overlay, leaving the prior `updatedAt` and breaking
+        # `existed?`. The diff still excludes credentials / _rperm / _wperm /
+        # authData / roles, and an after-trigger response is only true/false, so
+        # there is no path for a forged privileged field to be persisted.
+        if after_save? && @original.present? && @original.is_a?(Hash)
+          o = Parse::Object.build @original, parse_class
+          o.apply_attributes! @object, dirty_track: true,
+                                       protected_set: Parse::Properties::PROTECTED_INITIALIZE_KEYS
+          return o
+        end
+
+        # afterSave on a CREATE (and every other trigger): the full object as the
+        # server sent it. createdAt/updatedAt survive (only credentials are
+        # scrubbed), so `new?` / `existed?` read correctly.
         Parse::Object.build(@object, parse_class)
       end
 

data/lib/parse/webhooks.rb

@@ -233,11 +233,23 @@ module Parse
             # ran ActiveModel before_save callbacks locally. A client-spoofed
             # `_RB_` without master falls through and runs them here.
             unless trusted_ruby_initiated
-              prepare_result = result.prepare_save!
-              # If prepare_save! returns false (callback chain was halted), throw an error
-              if prepare_result == false
+              before_save_result = result.run_before_save_callbacks
+              # If a before_save callback halted the chain (returned false), reject the save.
+              if before_save_result == false
                 raise Parse::Webhooks::ResponseError, "Save halted by before_save callback"
               end
+              # Parse Server exposes no separate beforeCreate trigger, so the
+              # beforeSave hook is the single point at which before_create must
+              # run for a client-initiated create. Run it AFTER before_save, for
+              # new objects only -- matching ActiveModel order (before_save wraps
+              # before_create) and mirroring the afterSave hook, which runs
+              # after_create then after_save. `original.nil?` marks a create.
+              if payload && payload.original.nil?
+                create_result = result.run_before_create_callbacks
+                if create_result == false
+                  raise Parse::Webhooks::ResponseError, "Save halted by before_create callback"
+                end
+              end
             end
             # For before_save, return the changes payload (what Parse Server expects)
             result = result.changes_payload

data/parse-stack-next.gemspec

@@ -6,7 +6,7 @@ require "parse/stack/version"
 Gem::Specification.new do |spec|
   spec.name = "parse-stack-next"
   spec.version = Parse::Stack::VERSION
-  spec.authors = ["Anthony Persaud", "Henry Spindell", "Adrian Curtin"]
+  spec.authors =  ["Adrian Curtin", "Anthony Persaud", "Henry Spindell"]
   spec.email = ["adrian+parse-stack@neurosynq.net"]
 
   spec.summary = %q{Parse Server SDK for Ruby — ORM, queries, auth, and MongoDB-direct access}