parse-stack-next 4.5.0

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

@@ -0,0 +1,139 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/inflector"
+require "active_support/core_ext"
+# Note: Do not require "../object" here - this file is loaded from object.rb
+# and adding that require would create a circular dependency.
+
+module Parse
+  # Create all Parse::Object subclasses, including their properties and inferred
+  # associations by importing the schema for the remote collections in a Parse
+  # application. Uses the default configured client.
+  # @return [Array] an array of created Parse::Object subclasses.
+  # @see Parse::Model::Builder.build!
+  def self.auto_generate_models!
+    Parse.schemas.map do |schema|
+      Parse::Model::Builder.build!(schema)
+    end
+  end
+
+  # Namespace where +Parse.auto_generate_models!+ installs dynamically
+  # generated +Parse::Object+ subclasses derived from server-side schema.
+  # Isolating them here prevents server-returned className strings from
+  # rebinding top-level constants like ::File, ::Logger, ::Process.
+  module Generated
+  end
+
+  class Model
+    # This class provides a method to automatically generate Parse::Object subclasses, including
+    # their properties and inferred associations by importing the schema for the remote collections
+    # in a Parse application.
+    class Builder
+      # Regex matching className strings safe to install as a Ruby constant.
+      # Server-returned className must satisfy this; otherwise we refuse to
+      # touch the global namespace.
+      VALID_CLASS_NAME = /\A_?[A-Za-z][A-Za-z0-9_]{0,127}\z/.freeze
+
+      # Parse Server system classes that ship with the SDK as hand-written
+      # subclasses (Parse::User, Parse::Role, etc.). Schema-driven builds
+      # must NOT install additional fields or associations on these — a
+      # compromised Parse Server could otherwise inject an +is_admin+
+      # property onto the real +Parse::User+ class, or a +password_history+
+      # accessor onto +_Session+, by returning a poisoned schema.
+      PROTECTED_SYSTEM_CLASSES = %w[
+        _User _Role _Session _Installation _Product _Audience _PushStatus
+        _JobStatus _JobSchedule _Hooks _GlobalConfig _SCHEMA _GraphQLConfig
+        _Idempotency _Audit
+      ].freeze
+
+      # Builds a ruby Parse::Object subclass with the provided schema information.
+      # @param schema [Hash] the Parse-formatted hash schema for a collection. This hash
+      #  should two keys:
+      #  * className: Contains the name of the collection.
+      #  * field: A hash containg the column fields and their type.
+      # @raise ArgumentError when the className could not be inferred from the schema.
+      # @return [Array] an array of Parse::Object subclass constants.
+      def self.build!(schema)
+        unless schema.is_a?(Hash)
+          raise ArgumentError, "Schema parameter should be a Parse schema hash object."
+        end
+        schema = schema.with_indifferent_access
+        fields = schema[:fields] || {}
+        className = schema[:className]
+
+        if className.blank?
+          raise ArgumentError, "No valid className provided for schema hash"
+        end
+
+        # Strictly validate the server-returned className before any constant
+        # resolution. This blocks schema-poisoning attacks where a malicious
+        # or compromised Parse Server returns a className like "File",
+        # "Kernel", or "../foo" intending to either rebind a Ruby built-in
+        # constant via const_set or trigger arbitrary autoload via const_get.
+        parse_class_name = className.to_parse_class
+        unless parse_class_name.is_a?(String) && parse_class_name =~ VALID_CLASS_NAME
+          raise ArgumentError, "Unsafe className from schema: #{className.inspect}"
+        end
+
+        # Prefer the registered Parse::Object descendant lookup (never touches
+        # top-level constants). Only fall back to constant lookup within the
+        # Parse::Generated namespace, never on ::Object.
+        klass = Parse::Model.find_class(className)
+        if klass.nil?
+          if Parse::Generated.const_defined?(parse_class_name, false)
+            klass = Parse::Generated.const_get(parse_class_name, false)
+          end
+        end
+        if klass.nil?
+          klass = ::Class.new(Parse::Object)
+          Parse::Generated.const_set(parse_class_name, klass)
+        end
+        unless klass.is_a?(Class) && klass <= Parse::Object
+          raise ArgumentError, "Resolved class #{klass.inspect} for #{className.inspect} is not a Parse::Object subclass"
+        end
+
+        # Refuse to install schema-derived fields on protected system
+        # classes. The class is still returned (so callers that call
+        # build! purely for the class lookup continue to work) but no
+        # attacker-controlled belongs_to/has_many/property is added.
+        if PROTECTED_SYSTEM_CLASSES.include?(className.to_s)
+          return klass
+        end
+
+        base_fields = Parse::Properties::BASE.keys
+        class_fields = klass.field_map.values + [:className]
+        fields.each do |field, type|
+          field = field.to_sym
+          key = field.to_s.underscore.to_sym
+          next if base_fields.include?(field) || class_fields.include?(field)
+
+          data_type = type[:type].downcase.to_sym
+          if data_type == :pointer
+            klass.belongs_to key, as: safe_target_class(type[:targetClass]), field: field
+          elsif data_type == :relation
+            klass.has_many key, through: :relation, as: safe_target_class(type[:targetClass]), field: field
+          else
+            klass.property key, data_type, field: field
+          end
+          class_fields.push(field)
+        end
+        klass
+      end
+
+      # @!visibility private
+      # Validates a server-returned +targetClass+ string before forwarding
+      # it to +belongs_to+/+has_many+. Returns +nil+ for missing or
+      # invalid values so the association DSL falls back to its inferred
+      # default rather than installing an attacker-controlled class name
+      # (which could pivot a later type-confusion bypass).
+      def self.safe_target_class(target)
+        return nil if target.nil? || target.to_s.empty?
+        s = target.to_s
+        return nil unless s =~ VALID_CLASS_NAME
+        s
+      end
+    end
+  end
+end

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

@@ -0,0 +1,386 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "digest"
+require "openssl"
+require "json"
+require "securerandom"
+require "monitor"
+
+module Parse
+  # Mutual-exclusion primitive for `first_or_create!` / `create_or_update!` to
+  # prevent TOCTOU duplicate creation under concurrency. Backed by a Moneta
+  # cache store (typically Redis) using atomic `#create` (SETNX semantics).
+  #
+  # This is the *latency optimization* layer; a MongoDB unique index on the
+  # constrained tuple is the correctness floor that survives Redis outages,
+  # TTL expiry races, and bypassed locks. The lock here is best-effort and
+  # fails open by design when the store is unreachable.
+  #
+  # Threading model:
+  # - Process-local fallback: when the store is the in-memory Moneta adapter
+  #   (or unconfigured), the lock degrades to a per-key `Mutex`. Threads in
+  #   the same Ruby process serialize; cross-process callers do not. This is
+  #   safe for single-Puma-process tests but does not protect production
+  #   deployments with multiple dynos / workers.
+  # - Cross-process: when the store is Redis-backed Moneta, `#create` is
+  #   atomic and the lock excludes other processes.
+  #
+  # Key derivation: HMAC-SHA256 of a canonical payload when a secret is
+  # configured (preferred); plain SHA256 otherwise (deterministic across
+  # processes — required for Redis-backed locking — but key material is
+  # enumerable via Redis MONITOR/snapshots). Operators wanting hardened key
+  # material against snapshot/MONITOR exposure should set
+  # `PARSE_STACK_LOCK_SECRET` or `Parse.synchronize_create_secret`.
+  module CreateLock
+    DEFAULT_TTL = 3
+    DEFAULT_WAIT = 2.0
+    DEFAULT_POLL_BASE = 0.05
+    DEFAULT_POLL_JITTER = 0.015
+    MAX_TTL = 30
+    MAX_WAIT = 30
+    MAX_PAYLOAD_BYTES = 8_192
+    MAX_DEPTH = 4
+    KEY_PREFIX = "parse-stack:foc:v1:"
+    DEGRADED_WARNING_THROTTLE_SECONDS = 60
+
+    class << self
+      # Run `block` while holding a mutex keyed by the canonical form of
+      # `parse_class + auth context + query_attrs`. Yields nothing; the
+      # block's return value is returned.
+      #
+      # @param parse_class [String] the Parse class name
+      # @param query_attrs [Hash] the query attributes used to derive the key
+      # @param options [Hash] tuning: ttl:, wait:, on_degraded:
+      # @param session_token [String, nil] auth context — included in key
+      # @param master_key [Boolean, nil] auth context — included in key
+      # @raise [Parse::CreateLockInvalidKey] if query_attrs cannot be canonicalized
+      # @raise [Parse::CreateLockTimeoutError] if wait budget exceeded
+      def synchronize(parse_class:, query_attrs:, options: {}, session_token: nil, master_key: nil, &block)
+        raise ArgumentError, "block required" unless block_given?
+
+        ttl = clamp(Integer(options[:ttl] || DEFAULT_TTL), 1, MAX_TTL)
+        wait = clamp(Float(options[:wait] || DEFAULT_WAIT), 0.0, MAX_WAIT)
+        on_degraded = options[:on_degraded] || :warn
+
+        key = canonical_key(
+          parse_class: parse_class,
+          query_attrs: query_attrs,
+          session_token: session_token,
+          master_key: master_key,
+        )
+
+        store = lock_store
+        if degraded_store?(store)
+          handle_degraded(on_degraded, key)
+          return process_mutex(key).synchronize(&block)
+        end
+
+        owner = SecureRandom.uuid
+        acquired_at = nil
+        start = monotonic_now
+
+        loop do
+          if try_acquire(store, key, owner, ttl)
+            acquired_at = monotonic_now
+            wait_ms = ((acquired_at - start) * 1000).round
+            instrument("acquired", key, wait_ms: wait_ms)
+            break
+          end
+
+          elapsed = monotonic_now - start
+          if elapsed >= wait
+            waited_ms = (elapsed * 1000).round
+            instrument("timeout", key, waited_ms: waited_ms)
+            raise Parse::CreateLockTimeoutError,
+                  "Could not acquire create-lock for #{parse_class} within #{wait}s"
+          end
+          instrument("contended", key, elapsed_ms: (elapsed * 1000).round) if elapsed > 0
+          sleep(poll_interval)
+        end
+
+        begin
+          yield
+        ensure
+          if acquired_at
+            release(store, key, owner)
+            held_ms = ((monotonic_now - acquired_at) * 1000).round
+            instrument("released", key, held_ms: held_ms)
+          end
+        end
+      end
+
+      # Canonical lock key for the given inputs. Public for tests.
+      # @return [String]
+      def canonical_key(parse_class:, query_attrs:, session_token: nil, master_key: nil)
+        principal = principal_marker(session_token, master_key)
+        attrs_payload = canonicalize_attrs(query_attrs, parse_class: parse_class)
+        app_id = parse_application_id
+        payload = "#{app_id}|#{parse_class}|#{principal}|#{attrs_payload}"
+
+        if payload.bytesize > MAX_PAYLOAD_BYTES
+          raise Parse::CreateLockInvalidKey,
+                "synchronize key payload exceeds #{MAX_PAYLOAD_BYTES} bytes (got #{payload.bytesize})"
+        end
+
+        secret = lock_secret_for(store: lock_store)
+        digest = if secret
+            OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
+          else
+            Digest::SHA256.hexdigest(payload)
+          end
+        "#{KEY_PREFIX}#{digest}"
+      end
+
+      # @!visibility private
+      def reset!
+        @auto_secret = nil
+        @plain_sha_warned = nil
+        @degraded_warned_at = nil
+        @process_mutex_registry = nil
+      end
+
+      private
+
+      def lock_store
+        if Parse.respond_to?(:synchronize_create_store) && Parse.synchronize_create_store
+          return Parse.synchronize_create_store
+        end
+        Parse.cache
+      rescue Parse::Error::ConnectionError
+        nil
+      end
+
+      def parse_application_id
+        Parse.client.application_id
+      rescue Parse::Error::ConnectionError
+        "no-app-id"
+      end
+
+      def principal_marker(session_token, master_key)
+        return "default" if session_token.nil? && master_key.nil?
+        if session_token
+          "st:#{Digest::SHA256.hexdigest(session_token.to_s)[0, 16]}"
+        elsif master_key == true
+          "mk"
+        elsif master_key == false
+          "no-mk"
+        else
+          "default"
+        end
+      end
+
+      def canonicalize_attrs(query_attrs, parse_class: nil)
+        raise Parse::CreateLockInvalidKey, "synchronize requires non-empty query_attrs" if query_attrs.nil? || query_attrs.empty?
+        unless query_attrs.is_a?(Hash)
+          raise Parse::CreateLockInvalidKey, "synchronize query_attrs must be a Hash (got #{query_attrs.class})"
+        end
+
+        seen = {}
+        pairs = query_attrs.map do |k, v|
+          key_str = canonicalize_key_name(k)
+          if seen.key?(key_str)
+            class_ctx = parse_class ? " on #{parse_class}" : ""
+            raise Parse::CreateLockInvalidKey,
+                  "duplicate canonical key #{key_str.inspect}#{class_ctx} in synchronize query_attrs " \
+                  "(Parse::Operation has no eql?/hash override, so two instances with the " \
+                  "same operand+operator are distinct Hash keys but collapse here)"
+          end
+          seen[key_str] = true
+          [key_str, canonicalize_value(v, 0)]
+        end
+        sorted = pairs.sort_by(&:first).to_h
+        JSON.generate(sorted)
+      end
+
+      def canonicalize_key_name(key)
+        # Parse::Operation keys (e.g. :project.exists, :email.gt) encode as
+        # "<operand>\u0000op_<operator>" so the lock keys the filter shape, not
+        # just equality tuples. The null-byte separator is a structural marker
+        # that must never appear in plain string keys (rejected below) or in
+        # operand/operator names.
+        if key.is_a?(Parse::Operation) || (key.respond_to?(:operator) && key.respond_to?(:operand))
+          operand = key.operand.to_s
+          operator = key.operator.to_s
+          if operand.empty? || operator.empty? ||
+             operand.include?(".") || operator.include?(".") ||
+             operand.start_with?("$") || operator.start_with?("$") ||
+             operand.include?("\u0000") || operator.include?("\u0000")
+            raise Parse::CreateLockInvalidKey,
+                  "invalid Parse::Operation key in synchronize (got #{key.inspect})"
+          end
+          return "#{operand}\u0000op_#{operator}"
+        end
+        str = key.to_s
+        if str.include?(".") || str.include?("\u0000")
+          raise Parse::CreateLockInvalidKey,
+                "dotted or null-byte keys not allowed in synchronize (got #{key.inspect})"
+        end
+        str
+      end
+
+      def canonicalize_value(value, depth)
+        if depth > MAX_DEPTH
+          raise Parse::CreateLockInvalidKey, "synchronize values nested deeper than #{MAX_DEPTH} levels"
+        end
+
+        case value
+        when nil, true, false, Integer, Float, String, Symbol
+          value.is_a?(Symbol) ? value.to_s : value
+        when Time, DateTime
+          value.utc.iso8601(6)
+        when Date
+          value.iso8601
+        when Array
+          value.map { |v| canonicalize_value(v, depth + 1) }
+        when Parse::Pointer
+          if value.id.nil? || value.id.empty?
+            raise Parse::CreateLockInvalidKey,
+                  "unsaved Parse pointer cannot be a synchronize key component (#{value.parse_class}#nil)"
+          end
+          "ptr:#{value.parse_class}:#{value.id}"
+        when Hash
+          raise Parse::CreateLockInvalidKey,
+                "nested Hash values not allowed in synchronize (would be ambiguous against query operators)"
+        when Proc, Method, Regexp
+          raise Parse::CreateLockInvalidKey, "#{value.class} not allowed in synchronize values"
+        else
+          if value.respond_to?(:to_pointer)
+            ptr = value.to_pointer
+            return canonicalize_value(ptr, depth + 1)
+          end
+          raise Parse::CreateLockInvalidKey, "unsupported type #{value.class} in synchronize values"
+        end
+      end
+
+      def degraded_store?(store)
+        return true if store.nil?
+        bottom = walk_to_adapter(store)
+        return true if bottom.nil?
+        klass_name = bottom.class.name.to_s
+        klass_name.include?("Memory") || klass_name.include?("Null")
+      end
+
+      def walk_to_adapter(store)
+        current = store
+        # Walk transformer chain to find bottom Moneta adapter
+        while current.respond_to?(:adapter) && current.adapter && current.adapter != current
+          current = current.adapter
+        end
+        current
+      end
+
+      def handle_degraded(mode, key)
+        case mode
+        when :raise
+          raise Parse::CreateLockUnavailableError,
+                "synchronize requires a cross-process cache store (Redis); current store is process-local"
+        when :proceed
+          # silent
+        when :warn_throttled
+          now = monotonic_now
+          if @degraded_warned_at.nil? || (now - @degraded_warned_at) >= DEGRADED_WARNING_THROTTLE_SECONDS
+            @degraded_warned_at = now
+            warn "[Parse::CreateLock] Lock store is process-local (Moneta Memory/Null). " \
+                 "Cross-process locking is NOT in effect. Configure a Redis-backed cache to enable distributed locking."
+          end
+        else # :warn (default)
+          warn "[Parse::CreateLock] Lock store is process-local; cross-process locking disabled. " \
+               "key_digest=#{key[KEY_PREFIX.size, 12]}…"
+        end
+      end
+
+      def try_acquire(store, key, owner, ttl)
+        # Trigger lazy TTL sweep on Moneta::Memory before #create (no-op on Redis).
+        # Without this, Memory adapter returns false on #create even after TTL expiry
+        # until a #key? or #[] access flushes the stale entry.
+        store.key?(key)
+        store.create(key, owner, expires: ttl)
+      rescue StandardError => e
+        warn "[Parse::CreateLock] acquire error (#{e.class}): #{e.message}"
+        false
+      end
+
+      def release(store, key, owner)
+        # Best-effort compare-and-delete. Moneta does not expose atomic CAD;
+        # the worst-case race here is bounded by the short TTL (default #{DEFAULT_TTL}s).
+        current = store[key]
+        store.delete(key) if current == owner
+      rescue StandardError => e
+        warn "[Parse::CreateLock] release error (#{e.class}): #{e.message}"
+      end
+
+      def poll_interval
+        DEFAULT_POLL_BASE + (rand * 2 - 1) * DEFAULT_POLL_JITTER
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def clamp(value, lo, hi)
+        [lo, value, hi].sort[1]
+      end
+
+      def process_mutex(key)
+        @process_mutex_registry_lock ||= Mutex.new
+        @process_mutex_registry_lock.synchronize do
+          @process_mutex_registry ||= {}
+          @process_mutex_registry[key] ||= Mutex.new
+        end
+      end
+
+      def lock_secret_for(store:)
+        configured = configured_secret
+        return configured if configured && !configured.empty?
+
+        # No operator-configured secret. Behavior depends on store type:
+        # - Memory/Null adapter: locking is already process-local, so a
+        #   per-process auto-derived HMAC secret is fine and preserves
+        #   privacy in tests / single-process deployments.
+        # - Redis (or any cross-process store): a per-process secret would
+        #   break cross-process key equality, defeating the lock. Fall back
+        #   to plain SHA256 with a one-time warning so operators know to
+        #   harden key material.
+        if degraded_store?(store)
+          auto_secret
+        else
+          warn_plain_sha_once
+          nil
+        end
+      end
+
+      def configured_secret
+        if Parse.respond_to?(:synchronize_create_secret) && Parse.synchronize_create_secret
+          return Parse.synchronize_create_secret.to_s
+        end
+        ENV["PARSE_STACK_LOCK_SECRET"]
+      end
+
+      def auto_secret
+        @auto_secret ||= SecureRandom.hex(32)
+      end
+
+      def warn_plain_sha_once
+        return if @plain_sha_warned
+        @plain_sha_warned = true
+        warn "[Parse::CreateLock:SECURITY] No PARSE_STACK_LOCK_SECRET configured and Redis-backed store detected. " \
+             "Falling back to plain SHA256 for lock-key derivation so cross-process locking actually works. " \
+             "Lock keys are deterministic and may expose query_attrs content via Redis MONITOR/snapshots. " \
+             "Set PARSE_STACK_LOCK_SECRET (or Parse.synchronize_create_secret = '…') to enable HMAC keying."
+      end
+
+      def instrument(event, key, payload = {})
+        return unless defined?(ActiveSupport::Notifications)
+        ActiveSupport::Notifications.instrument(
+          "parse.synchronize_create.#{event}",
+          { key_digest: key[KEY_PREFIX.size, 12] }.merge(payload),
+        )
+      rescue StandardError
+        # never let telemetry break the lock
+      end
+    end
+  end
+end
+
+