parse-stack-next 5.0.1 → 5.1.0

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

@@ -225,6 +225,24 @@ module Parse
     # @return [Array<Parse::Session>] A list of active Parse::Session objects.
     has_many :active_sessions, as: :session
 
+    # @!attribute installations
+    # A `has_many` query-form association resolving to all
+    # {Parse::Installation} records whose `user` pointer is this user.
+    # Useful for targeted push — e.g. sending a notification to every
+    # device the user is signed into. This is a query (no column is
+    # stored on `_User`); each access issues a `find` against
+    # `_Installation` for `where(user: self)`.
+    #
+    # **Requires a master-key client.** Parse Server hardcodes
+    # `_Installation` `find` to master-key-only at the REST layer, so
+    # this association will return an empty array (or fail-closed
+    # depending on agent scope) under a session-token-only / sessionless
+    # client. The `user` pointer is also not a reliable owner identity
+    # — devices outlive sessions and can change users — see
+    # {Parse::Installation} for the full caveat list.
+    # @return [Array<Parse::Installation>]
+    has_many :installations, as: :installation
+
     # CHANGE -- ACLs can be managed
     # before_save do
     #   # You cannot specify user ACLs.
@@ -278,6 +296,192 @@ module Parse
       def authdata_trusted?
         Thread.current[AUTHDATA_TRUST_KEY] == true
       end
+
+      # =========================================================================
+      # Field-visibility DSL for _User
+      # =========================================================================
+      #
+      # `_User` has two field-visibility flavors that vanilla
+      # {Parse::Object.protect_fields} can't express on its own because
+      # Parse Server's `protectedFieldsOwnerExempt` option special-cases
+      # the owning user (the user sees their own row in full unless the
+      # option is disabled). These helpers wrap that pattern.
+      #
+      # ## Prerequisites
+      #
+      # 1. Set `protectedFieldsOwnerExempt: false` in your Parse Server
+      #    startup options. With the historical default `true`, the owning
+      #    user is silently exempted from every `protectedFields` rule on
+      #    `_User`, so {.master_only_fields} would still be visible to the
+      #    user themselves. Parse Server's default for this option is
+      #    changing to `false` in a future version; until your server
+      #    adopts that default you must set it explicitly.
+      # 2. For {.self_visible_fields}: add a self-pointer field on `_User`
+      #    that points to the same user, and maintain it from a
+      #    `beforeSave('_User')` Cloud Code trigger:
+      #
+      #    ```js
+      #    Parse.Cloud.beforeSave(Parse.User, (req) => {
+      #      const u = req.object;
+      #      if (!u.get('self')) u.set('self', u);  // self-pointer
+      #    });
+      #    ```
+      #
+      # The SDK cannot install either of those — they're server-side
+      # configuration — but the helpers below will warn if they detect
+      # they're being mis-applied.
+
+      # Hide one or more fields from query/get responses for **all**
+      # non-master callers, including the owning user themselves.
+      # Useful for admin-only metadata living on `_User`
+      # (e.g. internal scoring, moderation notes).
+      #
+      # Requires Parse Server option `protectedFieldsOwnerExempt: false`.
+      # With the default `true`, the owning user still sees these fields
+      # on their own row.
+      #
+      # @param fields [Array<Symbol,String>] field names. Use snake_case
+      #   Ruby property names; they're auto-converted to camelCase.
+      # @return [Array<Symbol>] full master-only field list after this call.
+      # @example
+      #   class Parse::User
+      #     property :my_opinion_of_them, :string
+      #     master_only_fields :my_opinion_of_them
+      #   end
+      def master_only_fields(*fields)
+        @master_only_fields ||= []
+        @master_only_fields = (@master_only_fields + fields.flatten.map(&:to_sym)).uniq
+        _warn_about_owner_exempt_prereq!
+        _rebuild_user_protected_fields!
+        @master_only_fields.dup
+      end
+
+      # Hide one or more fields from public/role/other-user callers, but
+      # allow the **owning user** to see them. Useful for private profile
+      # data that belongs to the user (e.g. preferences, private notes).
+      #
+      # Requires:
+      # * Parse Server option `protectedFieldsOwnerExempt: false`.
+      # * A self-pointer field on `_User` (named via `via:`, default
+      #   `:self`) that is set to the row's own pointer by a
+      #   `beforeSave('_User')` Cloud Code trigger.
+      #
+      # @param fields [Array<Symbol,String>] field names. snake_case OK.
+      # @param via [Symbol,String] name of the self-pointer field on
+      #   `_User` (default `:self`).
+      # @return [Array<Symbol>]
+      # @example
+      #   class Parse::User
+      #     property :favorite_color, :string
+      #     self_visible_fields :favorite_color, via: :self
+      #   end
+      def self_visible_fields(*fields, via: :self)
+        @self_visible_fields ||= []
+        @self_visible_fields = (@self_visible_fields + fields.flatten.map(&:to_sym)).uniq
+        @self_pointer_field = via.to_sym
+        _warn_about_owner_exempt_prereq!
+        _warn_about_self_pointer_prereq!(via)
+        _rebuild_user_protected_fields!
+        @self_visible_fields.dup
+      end
+
+      # Override {Parse::Object.protect_fields} on `_User` so that ad-hoc
+      # uses (i.e. not through {.master_only_fields} /
+      # {.self_visible_fields}) emit a one-time advisory pointing at the
+      # higher-level helpers and the `protectedFieldsOwnerExempt` flag.
+      # The behavior is otherwise unchanged.
+      def protect_fields(pattern, fields)
+        _warn_about_user_protect_fields! unless @_user_field_dsl_active
+        super
+      end
+
+      # @!visibility private
+      def _rebuild_user_protected_fields!
+        @master_only_fields  ||= []
+        @self_visible_fields ||= []
+        pointer = @self_pointer_field || :self
+        all_hidden = (@master_only_fields + @self_visible_fields).uniq
+
+        @_user_field_dsl_active = true
+        begin
+          protect_fields("*", all_hidden) unless all_hidden.empty?
+          unless @self_visible_fields.empty?
+            protect_fields("userField:#{pointer}", @master_only_fields)
+          end
+        ensure
+          @_user_field_dsl_active = false
+        end
+      end
+
+      # @!visibility private
+      def _warn_about_user_protect_fields!
+        return if @_user_protect_fields_warned
+        @_user_protect_fields_warned = true
+        _emit_user_field_advisory(
+          "[Parse::User] protect_fields was called directly on _User. " \
+          "For master-only and owner-visible field patterns prefer " \
+          "`Parse::User.master_only_fields` and `Parse::User.self_visible_fields`. " \
+          "Either way, ensure Parse Server is started with " \
+          "`protectedFieldsOwnerExempt: false` (the historical default `true` — " \
+          "changing to `false` in a future Parse Server version — exempts the " \
+          "owning user from every protectedFields rule on _User, which silently " \
+          "negates these protections for the user's own row).",
+        )
+      end
+
+      # @!visibility private
+      # Fires once when `master_only_fields` / `self_visible_fields` is first
+      # used. Without `protectedFieldsOwnerExempt: false` in Parse Server's
+      # startup options, neither helper does what its name promises -- the
+      # default `true` silently exempts the owning user from every
+      # protectedFields rule on _User. The SDK can't introspect Parse
+      # Server's startup options, so we surface this as a one-time advisory
+      # at declaration time so it's loud enough to catch before deploy.
+      def _warn_about_owner_exempt_prereq!
+        return if @_owner_exempt_warned
+        @_owner_exempt_warned = true
+        _emit_user_field_advisory(
+          "[Parse::User] master_only_fields / self_visible_fields require " \
+          "Parse Server option `protectedFieldsOwnerExempt: false`. With the " \
+          "historical default `true`, the owning user is silently exempted " \
+          "from every protectedFields rule on _User, so a field declared " \
+          "master-only would still be visible to the user themselves on their " \
+          "own row. Parse Server's default for this option is changing to " \
+          "`false` in a future version (which makes these helpers work " \
+          "without extra config), but until your server adopts that default " \
+          "you must set `protectedFieldsOwnerExempt: false` in your " \
+          "ParseServer options BEFORE deploying. See docs/acl_clp_guide.md §4.2.",
+        )
+      end
+
+      # @!visibility private
+      # Fires once when `self_visible_fields` is first used. The Parse
+      # Server side requires (a) a self-pointer field on _User populated
+      # by a beforeSave('_User') trigger, AND (b) a one-shot backfill on
+      # any pre-existing user rows so the pointer is set before the
+      # `userField:<via>` group matches them.
+      def _warn_about_self_pointer_prereq!(via)
+        return if @_self_pointer_warned
+        @_self_pointer_warned = true
+        _emit_user_field_advisory(
+          "[Parse::User] self_visible_fields(via: :#{via}) requires a " \
+          "self-pointer field named `#{via}` on _User pointing at the same " \
+          "row, populated by a beforeSave('_User') Cloud Code trigger. " \
+          "Existing user rows ALSO need a one-shot backfill (the trigger " \
+          "only fires on save) -- without it, those rows never match the " \
+          "`userField:#{via}` group and the field stays hidden from the " \
+          "user themselves. See docs/acl_clp_guide.md §4.2.",
+        )
+      end
+
+      # @!visibility private
+      def _emit_user_field_advisory(msg)
+        if Parse.respond_to?(:logger) && Parse.logger
+          Parse.logger.warn(msg)
+        else
+          Kernel.warn(msg)
+        end
+      end
     end
 
     # @!visibility private

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

@@ -6,6 +6,7 @@ require "openssl"
 require "json"
 require "securerandom"
 require "monitor"
+require_relative "../../lock_backend"
 
 module Parse
   # Mutual-exclusion primitive for `first_or_create!` / `create_or_update!` to
@@ -70,25 +71,29 @@ module Parse
           master_key: master_key,
         )
 
-        store = lock_store
-        if degraded_store?(store)
-          handle_degraded(on_degraded, key)
-          return process_mutex(key).synchronize(&block)
+        store = LockBackend.lock_store
+        if LockBackend.degraded_store?(store)
+          LockBackend.handle_degraded(
+            on_degraded, key,
+            source: "Parse::CreateLock",
+            unavailable_error: Parse::CreateLockUnavailableError,
+          )
+          return LockBackend.process_mutex(key).synchronize(&block)
         end
 
         owner = SecureRandom.uuid
         acquired_at = nil
-        start = monotonic_now
+        start = LockBackend.monotonic_now
 
         loop do
-          if try_acquire(store, key, owner, ttl)
-            acquired_at = monotonic_now
+          if LockBackend.try_acquire(store, key, owner, ttl)
+            acquired_at = LockBackend.monotonic_now
             wait_ms = ((acquired_at - start) * 1000).round
             instrument("acquired", key, wait_ms: wait_ms)
             break
           end
 
-          elapsed = monotonic_now - start
+          elapsed = LockBackend.monotonic_now - start
           if elapsed >= wait
             waited_ms = (elapsed * 1000).round
             instrument("timeout", key, waited_ms: waited_ms)
@@ -96,15 +101,15 @@ module Parse
                   "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)
+          sleep(LockBackend.poll_interval)
         end
 
         begin
           yield
         ensure
           if acquired_at
-            release(store, key, owner)
-            held_ms = ((monotonic_now - acquired_at) * 1000).round
+            LockBackend.release(store, key, owner)
+            held_ms = ((LockBackend.monotonic_now - acquired_at) * 1000).round
             instrument("released", key, held_ms: held_ms)
           end
         end
@@ -123,7 +128,7 @@ module Parse
                 "synchronize key payload exceeds #{MAX_PAYLOAD_BYTES} bytes (got #{payload.bytesize})"
         end
 
-        secret = lock_secret_for(store: lock_store)
+        secret = lock_secret_for(store: LockBackend.lock_store)
         digest = if secret
             OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
           else
@@ -134,23 +139,14 @@ module Parse
 
       # @!visibility private
       def reset!
-        @auto_secret = nil
-        @plain_sha_warned = nil
-        @degraded_warned_at = nil
-        @process_mutex_registry = nil
+        # All resettable state lives on Parse::LockBackend now —
+        # @degraded_warned_at, @process_mutex_registry, @auto_secret,
+        # @plain_sha_warned. v5.1.0 extraction.
+        LockBackend.reset!
       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
@@ -253,133 +249,19 @@ module Parse
         end
       end
 
-      def degraded_store?(store)
-        return true if store.nil?
-        # The Parse::Cache::Redis wrapper (and its Pool) are known
-        # cross-process stores even though they don't expose a Moneta
-        # `.adapter` chain to walk. Anything that can't forward `#create`
-        # cannot serve as a lock store, so fall back to the process-local
-        # path rather than spinning until timeout on NoMethodError.
-        return false if defined?(Parse::Cache::Redis) && store.is_a?(Parse::Cache::Redis)
-        return true unless store.respond_to?(:create)
-        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
+      # All the lock infrastructure — store discovery, degraded
+      # detection, atomic-SETNX, release semantics, poll-interval
+      # jitter, process-mutex registry, AND HMAC secret resolution —
+      # lives on {Parse::LockBackend} now (v5.1.0 extraction). The
+      # only CreateLock-specific helper still here is `clamp` for
+      # the public API's input range.
 
       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. " \
-             "Risks of running without an HMAC secret: (1) lock keys are deterministic and may expose query_attrs " \
-             "content via Redis MONITOR/snapshots; (2) when the response cache and the lock store share a Redis DB, " \
-             "any caller with write access to Parse.cache can plant a `parse-stack:foc:v1:<sha>` key under a guessable " \
-             "digest of (app_id, class, principal, query_attrs) and suppress first_or_create!/create_or_update! for " \
-             "that tuple until TTL expiry — a targeted DoS / create-pinning primitive. " \
-             "Set PARSE_STACK_LOCK_SECRET (or Parse.synchronize_create_secret = '…') to enable HMAC keying, or " \
-             "point Parse.synchronize_create_store at a separate Redis DB from the response cache."
+        LockBackend.lock_secret_for(store: store, source: "Parse::CreateLock")
       end
 
       def instrument(event, key, payload = {})