parse-stack-next 5.2.0 → 5.3.0

data/lib/parse/webhooks/payload.rb

@@ -64,6 +64,18 @@ module Parse
       attr_accessor :master, :user, :installation_id, :params, :function_name, :object, :trigger_name
       attr_accessor :query, :log, :objects
       attr_accessor :original, :update, :raw
+      # @!attribute [r] session_token
+      #   The caller's live Parse session token, captured from the incoming
+      #   webhook payload (`user.sessionToken`) before credentials are scrubbed
+      #   from {#user} / {#object} / {#original} / {#update}. Present only when
+      #   the originating request was made by a logged-in user -- a master-key
+      #   request carries no user and no token, so this is +nil+. It is
+      #   intentionally NOT one of {ATTRIBUTES}, so it never appears in
+      #   {#as_json} or in the redacted request log. Reach for it (or the
+      #   higher-level {#user_client} / {#user_agent}) only when a handler
+      #   deliberately wants to act on the server as the calling user.
+      #   @return [String, nil]
+      attr_reader :session_token
       # @!visibility private
       attr_accessor :webhook_class
       alias_method :installationId, :installation_id
@@ -78,24 +90,45 @@ 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.
+        # Capture the caller's session token from the *unscrubbed* user hash
+        # before scrub_credentials strips it below. Parse Server includes
+        # `user.sessionToken` on every trigger fired by a logged-in caller
+        # (it is absent for master-key-originated requests). Pulling it aside
+        # here -- rather than leaving it in @user -- keeps it out of any object
+        # a handler might persist and out of #as_json / the request log, while
+        # still letting a handler opt in to acting as the calling user via
+        # #session_token / #user_client / #user_agent.
+        @session_token = self.class.extract_session_token(hash[:user])
+        # 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 inline (live session tokens -- captured
+        # above for opt-in user-scoped clients first -- and 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,34 +136,69 @@ 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
 
+      # @!visibility private
+      # Pulls the caller's session token out of the (unscrubbed) +user+ hash.
+      # Parse Server sends it as the camelCase string key +sessionToken+; this
+      # tolerates a symbol key and the snake_case form too, mirroring the
+      # leniency in +scrub_credentials+. Returns +nil+ for a blank token or a
+      # non-Hash / absent user (a master-key request has no user).
+      def self.extract_session_token(user_hash)
+        return nil unless user_hash.is_a?(Hash)
+        token = user_hash["sessionToken"] || user_hash[:sessionToken] ||
+                user_hash["session_token"] || user_hash[:session_token]
+        token = token.to_s.strip
+        token.empty? ? nil : token
+      end
+
       # @return [ATTRIBUTES]
       def attributes
         ATTRIBUTES
       end
 
+      # Redacted inspection. The default Ruby `#inspect` would dump every ivar,
+      # including the captured `@session_token` and the *pre-scrub* `@raw` hash
+      # (which still holds the caller's sessionToken and any password hashes).
+      # That is exactly the surface an error reporter or a stray `p payload`
+      # hits, so show only non-sensitive routing fields and a boolean for the
+      # token's presence. Use #as_json / the individual accessors for the
+      # (already credential-scrubbed) object data.
+      def inspect
+        "#<#{self.class.name} trigger=#{@trigger_name.inspect} " \
+        "function=#{@function_name.inspect} class=#{parse_class.inspect} " \
+        "id=#{parse_id.inspect} master=#{@master ? true : false} " \
+        "session_token=#{@session_token ? "[FILTERED]" : "nil"}>"
+      end
+
       # Method to print to standard that utilizes the an internal id to make it easier
       # to trace incoming requests.
       def wlog(s)
@@ -152,6 +220,51 @@ module Parse
         @master.present?
       end
 
+      # true if this payload carried a caller session token -- i.e. the
+      # originating request was made by a logged-in user rather than the
+      # master key, so {#user_client} / {#user_agent} can act as that user.
+      # @return [Boolean]
+      def session_token?
+        !@session_token.nil?
+      end
+
+      # An opt-in, user-scoped {Parse::Client} for acting on the server as the
+      # webhook's calling user. It mirrors the default client's connection
+      # settings (+server_url+, +application_id+, +api_key+) but carries NO
+      # master key and BINDS the caller's {#session_token}, so every request it
+      # makes -- with no further ceremony -- is authorized by Parse Server as
+      # that user: ACL, CLP and +protectedFields+ are all enforced. (A
+      # `Parse.with_session` block still overrides the bound token if you need
+      # to act as someone else within a call.) Memoized per payload, since each
+      # webhook delivery carries a distinct token.
+      # @return [Parse::Client, nil] +nil+ when the payload carried no token.
+      def user_client
+        return nil if @session_token.nil?
+        @user_client ||= Parse::Client.client.become(@session_token)
+      end
+
+      # An opt-in, non-master {Parse::Agent} scoped to the webhook caller's
+      # session token. Because its client has no master key and it is built
+      # with a non-empty +session_token:+, the agent runs in CLIENT MODE:
+      # every tool/query routes through a path Parse Server (or the SDK's own
+      # ACL/CLP enforcement layer) authorizes as the calling user, with no
+      # master-key fallback to silently bypass row-level security. This is the
+      # handle to use when a handler should read or act strictly within the
+      # caller's permissions. Additional agent options (e.g.
+      # +permissions: :readwrite+) may be passed through.
+      # @param opts [Hash] extra keyword args forwarded to {Parse::Agent#initialize}.
+      # @return [Parse::Agent, nil] +nil+ when the payload carried no token.
+      def user_agent(**opts)
+        return nil if @session_token.nil?
+        require_relative "../agent" unless defined?(Parse::Agent)
+        # Strip the two identity kwargs from the passthrough: a Ruby double-splat
+        # that repeats an explicit keyword WINS, so user_agent(client: master)
+        # or user_agent(session_token: other) would otherwise silently defeat the
+        # whole point (scoping to the caller). The scoping is non-negotiable here.
+        opts = opts.except(:session_token, :client)
+        Parse::Agent.new(session_token: @session_token, client: user_client, **opts)
+      end
+
       # @return [String] the name of the Parse class for this request.
       def parse_class
         return @webhook_class if @webhook_class.present?
@@ -278,24 +391,82 @@ 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: there is no prior persisted state, so every
+        # populated data field is new. Build symmetry with the UPDATE path above
+        # by seeding the identity / system fields (objectId, timestamps, ACL,
+        # className, plus the credential / permission keys) into a pristine
+        # object, then overlaying the full object with dirty tracking. Because
+        # the overlay's protected_set is exactly the seed key set, the system
+        # fields come ONLY from the clean seed and the overlay touches ONLY
+        # declared data properties (nil -> value -> changed) -- so `*_changed?`
+        # reports every field the create populated while createdAt / updatedAt /
+        # ACL stay clean. This lets handlers key off dirty tracking uniformly
+        # across create and update (e.g. building a sync payload from changed
+        # fields). Credentials / _rperm / _wperm / authData / roles are filtered
+        # from the overlay (seeded read-only, never marked changed), and an
+        # after-trigger response is only true/false, so nothing here can persist
+        # a forged field.
+        if after_save? && @object.is_a?(Hash)
+          seed_keys = Parse::Properties::PROTECTED_INITIALIZE_KEYS +
+                      %w[objectId createdAt updatedAt ACL className __type]
+          seed = @object.slice(*seed_keys)
+          o = Parse::Object.build seed, parse_class
+          # `build` applies declared `default:` values onto the seed and then
+          # clears changes, baking each default into the "pristine" baseline.
+          # Without correction, the overlay's dirty guard (`unless val ==
+          # current`) would SUPPRESS marking any create value equal to its
+          # default (e.g. status: "draft", count: 0, archived: false), silently
+          # defeating this branch's whole purpose. Reset the default-bearing
+          # ivars to nil for the fields the overlay is about to set, then
+          # re-clear, so the overlay's guard sees a differing current ivar and
+          # marks every populated data field changed. (`*_changed?` / `changes`
+          # / `changed` then report the field; for a defaulted field the
+          # reported prior value is the default rather than nil, since the
+          # getter re-derives the default — its prior *effective* value.)
+          # `defaults_list` never contains the seeded system fields
+          # (objectId/createdAt/updatedAt/ACL), so this cannot disturb them;
+          # defaults for fields ABSENT from the payload are left intact so their
+          # value still reads through.
+          fmap = o.class.respond_to?(:field_map) ? o.class.field_map : {}
+          o.class.defaults_list.each do |k|
+            wire = (fmap[k] || k).to_s
+            next unless @object.key?(wire) || @object.key?(k.to_s)
+            o.instance_variable_set(:"@#{k}", nil)
+          end
+          o.clear_changes!
+          o.apply_attributes! @object, dirty_track: true, protected_set: seed_keys
+          return o
+        end
+
+        # Every other trigger (afterDelete, afterFind, and any before* path that
+        # did not match above): 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: parse-stack-next
 version: !ruby/object:Gem::Version
-  version: 5.2.0
+  version: 5.3.0
 platform: ruby
 authors:
 - Adrian Curtin
@@ -364,6 +364,7 @@ files:
 - lib/parse/model/core/field_guards.rb
 - lib/parse/model/core/indexing.rb
 - lib/parse/model/core/parse_reference.rb
+- lib/parse/model/core/pluralized_aliases.rb
 - lib/parse/model/core/properties.rb
 - lib/parse/model/core/querying.rb
 - lib/parse/model/core/schema.rb