parse-stack-next 5.0.1 → 5.1.0

data/lib/parse/lock_backend.rb

@@ -0,0 +1,308 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "monitor"
+require "securerandom"
+
+module Parse
+  # Shared low-level primitives for both {Parse::CreateLock} (the
+  # internal lock used by `first_or_create!` / `create_or_update!`)
+  # and {Parse::Lock} (the public mutual-exclusion primitive). The
+  # extraction exists so {Parse::Lock} does not reach into
+  # {Parse::CreateLock}'s private methods via `.send` — a brittle
+  # coupling pattern called out in the v5.1.0 round-2 review. Both
+  # callers now depend on a small documented surface and any future
+  # refactor of the lock store discovery / degraded-detection
+  # heuristic / atomic-SETNX semantics happens in exactly one place.
+  #
+  # **Not a public API for application code.** `@!visibility private`
+  # is intentional. End users compose with locking through
+  # {Parse::Lock.acquire} (block-form) or `first_or_create!` /
+  # `create_or_update!` (find-or-create). This module is documented
+  # only because SDK extension authors and security auditors need to
+  # know where the SETNX semantics actually live.
+  #
+  # @api private
+  module LockBackend
+    # Base poll interval for the wait-loop spin in the caller's
+    # acquire loop. Caller adds jitter via {.poll_interval}; this
+    # constant is the midpoint.
+    DEFAULT_POLL_BASE = 0.05
+
+    # Half-width of the symmetric jitter applied around
+    # {DEFAULT_POLL_BASE}. Spreads contended-acquire spin starts so
+    # N waiters don't all hit `try_acquire` on the same monotonic
+    # tick after a release.
+    DEFAULT_POLL_JITTER = 0.015
+
+    # Throttle floor for {.handle_degraded}(`:warn_throttled`). One
+    # warning per process per this many seconds; subsequent degraded
+    # acquisitions are silent.
+    DEGRADED_WARNING_THROTTLE_SECONDS = 60
+
+    class << self
+      # Find the Moneta store the lock should write through. Resolved
+      # at call time (not memoized) so a test or an operator can swap
+      # `Parse.synchronize_create_store` after boot and see the change
+      # take effect on the next acquisition.
+      #
+      # @return [Object, nil] a Moneta-shaped store, or nil when none
+      #   is configured / the Parse client is unconfigured.
+      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
+
+      # Decide whether `store` is process-local (Memory / Null /
+      # missing-`:create` / nil) — i.e. cannot serve as a cross-
+      # process lock store, so the caller should fall back to a
+      # per-key in-process Mutex. The {Parse::Cache::Redis} wrapper
+      # is explicitly accepted because it doesn't expose a Moneta
+      # `.adapter` chain to walk.
+      #
+      # @param store [Object, nil] candidate store
+      # @return [Boolean]
+      def degraded_store?(store)
+        return true if store.nil?
+        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
+
+      # Emit the configured degraded-store warning. `source:` lets
+      # the caller tag the prefix so an operator reading
+      # `[Parse::Lock] Lock store is process-local` knows which
+      # caller surfaced the warning (vs `[Parse::CreateLock]` for
+      # the find-or-create path).
+      #
+      # @param mode [Symbol] one of `:warn`, `:warn_throttled`,
+      #   `:proceed`, `:raise`. Callers are responsible for
+      #   validating the symbol BEFORE calling this; an unknown
+      #   value here falls through to plain `:warn`.
+      # @param key [String] the (already-hashed) cache key — used
+      #   only for the debug snippet in the warning message.
+      # @param source [String] caller tag for the log prefix.
+      # @param unavailable_error [Class] error class to raise in
+      #   `:raise` mode. Lets each caller raise its own typed
+      #   error (Parse::CreateLockUnavailableError vs
+      #   Parse::Lock::UnavailableError) without coupling here.
+      def handle_degraded(mode, key, source: "Parse::LockBackend",
+                          unavailable_error: nil)
+        case mode
+        when :raise
+          err = unavailable_error || Parse::Error
+          raise err,
+                "#{source}: cross-process lock store unavailable; " \
+                "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 "[#{source}] 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 "[#{source}] Lock store is process-local; cross-process locking disabled. " \
+               "key_digest=#{key.is_a?(String) ? key[-12..] : key.inspect}"
+        end
+      end
+
+      # Atomic SETNX-style acquisition. Returns true on success,
+      # false on contention OR error (logged). Never raises — the
+      # caller's wait loop is the source of truth for "did we get
+      # the lock," and a transient store error should look the
+      # same to the loop as "someone else has it."
+      #
+      # @param store [Object] Moneta-shaped store responding to
+      #   `:create` and `:key?`.
+      # @param key [String] cache key (already prefixed/hashed).
+      # @param owner [String] unique-per-acquisition identifier
+      #   used by {.release}'s compare-and-delete.
+      # @param ttl [Integer] seconds before the store entry self-
+      #   clears (crash-recovery floor).
+      # @return [Boolean]
+      def try_acquire(store, key, owner, ttl)
+        # Prefer the store's native atomic lock primitive when it exposes
+        # one (Parse::Cache::Redis). That path uses raw-Redis
+        # `SET key owner NX EX ttl` with plain-string encoding so it pairs
+        # with the atomic compare-and-delete in {.release}. Falls back to
+        # Moneta `:create` (also an atomic SETNX) for raw-Moneta stores.
+        return store.lock_acquire(key, owner, ttl) if store.respond_to?(:lock_acquire)
+
+        # Trigger lazy TTL sweep on Moneta::Memory before `:create`
+        # (no-op on Redis). Without this, the 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::LockBackend] acquire error (#{e.class}): #{e.message}"
+        false
+      end
+
+      # Compare-and-delete release. When the store exposes an atomic
+      # primitive (Parse::Cache::Redis → server-side Lua CAD), use it so
+      # a holder whose lease expired and was re-acquired by someone else
+      # can never delete the new holder's key. Falls back to a
+      # best-effort GET-then-DEL for raw-Moneta stores, where the
+      # worst-case cross-holder-delete race is bounded by the short TTL
+      # (callers clamp `ttl:` to ≤ 30s) — documented residual risk for
+      # the non-Redis path.
+      #
+      # @param store [Object] Moneta-shaped store.
+      # @param key [String] cache key.
+      # @param owner [String] the owner token from {.try_acquire}.
+      def release(store, key, owner)
+        return store.lock_release(key, owner) if store.respond_to?(:lock_release)
+
+        current = store[key]
+        store.delete(key) if current == owner
+      rescue StandardError => e
+        warn "[Parse::LockBackend] release error (#{e.class}): #{e.message}"
+      end
+
+      # Jittered poll interval for the wait-loop. Symmetric jitter
+      # around {DEFAULT_POLL_BASE} of half-width
+      # {DEFAULT_POLL_JITTER}; the result is bounded but
+      # non-deterministic so contended waiters don't sync up.
+      #
+      # @return [Float] seconds.
+      def poll_interval
+        DEFAULT_POLL_BASE + (rand * 2 - 1) * DEFAULT_POLL_JITTER
+      end
+
+      # Per-key in-process Mutex registry for the degraded fallback
+      # path. The first acquisition for a given key creates the
+      # Mutex; subsequent acquisitions reuse it. Registry itself is
+      # guarded by a tiny outer Mutex so two threads racing the
+      # first acquisition of the same key get the same Mutex.
+      #
+      # @param key [String] cache key.
+      # @return [Mutex]
+      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
+
+      # @return [Float] CLOCK_MONOTONIC seconds.
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # Reset backend-owned state. Intended for test teardown —
+      # production code should never call this.
+      #
+      # @return [void]
+      def reset!
+        @degraded_warned_at = nil
+        @process_mutex_registry = nil
+        @process_mutex_registry_lock = nil
+        @auto_secret = nil
+        @plain_sha_warned = nil
+      end
+
+      # =====================================================================
+      # HMAC secret resolution (v5.1.0 — extracted from Parse::CreateLock so
+      # Parse::Lock can also derive HMAC-keyed cache keys when an operator-
+      # configured secret is available)
+      # =====================================================================
+
+      # Resolve the HMAC secret for lock-key derivation. Behavior depends
+      # on store type:
+      #
+      # * **Configured secret present** — returned verbatim (operator
+      #   set `Parse.synchronize_create_secret` or
+      #   `PARSE_STACK_LOCK_SECRET`).
+      # * **Degraded (process-local) store, no configured secret** —
+      #   returns the per-process auto-derived random secret. Locking
+      #   is already process-local in this branch, so a per-process
+      #   secret is fine and improves test/single-process privacy by
+      #   preventing `KEYS *` enumeration.
+      # * **Cross-process store, no configured secret** — returns `nil`
+      #   with a one-time warn. Per-process auto-derived secrets would
+      #   break cross-process key equality (and therefore the lock
+      #   itself), so the caller falls back to plain SHA-256 and gets a
+      #   loud nudge to configure a real secret.
+      #
+      # @param store [Object, nil] the lock store (used only for
+      #   degraded detection).
+      # @param source [String] caller tag for the warn-once message —
+      #   "Parse::CreateLock" or "Parse::Lock".
+      # @return [String, nil] the secret, or nil to indicate plain SHA.
+      def lock_secret_for(store:, source: "Parse::LockBackend")
+        configured = configured_secret
+        return configured if configured && !configured.empty?
+        if degraded_store?(store)
+          auto_secret
+        else
+          warn_plain_sha_once(source: source)
+          nil
+        end
+      end
+
+      # @return [String, nil] operator-configured HMAC secret from
+      #   `Parse.synchronize_create_secret` or
+      #   `PARSE_STACK_LOCK_SECRET`. The env-var and accessor names
+      #   carry "synchronize_create" / "LOCK" historical naming;
+      #   both `Parse::CreateLock` and `Parse::Lock` consume the same
+      #   value.
+      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
+
+      # @return [String] per-process random secret. Memoized.
+      def auto_secret
+        @auto_secret ||= SecureRandom.hex(32)
+      end
+
+      # One-time process-scoped warn when a cross-process lock store
+      # is in use without an operator-configured HMAC secret. The
+      # warning text explains both the enumeration risk (key material
+      # is deterministic) and the lock-pinning risk (when the cache
+      # and lock store share a Redis DB) and points at the
+      # remediation knobs.
+      def warn_plain_sha_once(source:)
+        return if @plain_sha_warned
+        @plain_sha_warned = true
+        warn "[#{source}: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 key " \
+             "material 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 lock key under a " \
+             "guessable digest and pin the lock for that resource until TTL expiry — a targeted DoS / " \
+             "lock-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."
+      end
+
+      private
+
+      # Walk the Moneta transformer chain to the bottom adapter so
+      # {.degraded_store?} can name-check the adapter class.
+      def walk_to_adapter(store)
+        current = store
+        while current.respond_to?(:adapter) && current.adapter && current.adapter != current
+          current = current.adapter
+        end
+        current
+      end
+    end
+  end
+end

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

@@ -50,6 +50,11 @@ module Parse
   #     .with_alert("Exclusive offer!")
   #     .send!
   #
+  # @note `_Audience` is hardcoded master-key-only at Parse Server's
+  #   REST layer (`SharedRest.js`). CLP changes via
+  #   {Parse::Object.set_clp} have no effect — manage audiences from a
+  #   master-key client or expose them through a Cloud Code function.
+  #
   # @see Parse::Push#to_audience
   # @see Parse::Object
   class Audience < Parse::Object

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

@@ -35,10 +35,117 @@ module Parse
   #
   #     has_one :session, ->{ where(installation_id: i.installation_id) }, scope_only: true
   #   end
+  # ## Class-Level Permissions on `_Installation`
+  #
+  # `_Installation` is special-cased inside Parse Server. Some operations are
+  # hardcoded at the REST layer and CANNOT be relaxed via CLP — calling
+  # {Parse::Object.set_clp} for them has no effect on the server's actual
+  # behavior, regardless of what you pass. Other operations work the way
+  # CLP normally does. The matrix:
+  #
+  # | Operation  | Behavior                                                                                  |
+  # |------------|-------------------------------------------------------------------------------------------|
+  # | `find`     | **Master key only. Hardcoded.** `set_clp :find, ...` is effectively ignored by the server. |
+  # | `delete`   | **Master key only. Hardcoded.** `set_clp :delete, ...` is effectively ignored by the server. |
+  # | `create`   | Open to anonymous clients (the `X-Parse-Installation-Id` header is the credential). Locking via CLP breaks first-launch device registration. |
+  # | `update`   | Open to clients whose `installationId` matches the record; else master key. Locking via CLP breaks silent device-token refresh and channel subscribe/unsubscribe before login. |
+  # | `get`      | CLP applies normally. Safe to tighten — SDKs don't usually GET their own installation from the server. |
+  # | `count`    | CLP applies normally. Safe to tighten to master-only (the push flow doesn't need it). |
+  # | `addField` | CLP applies normally. Safe to tighten to master-only as a hardening default. |
+  #
+  # ### What you can safely do with `set_clp` on `_Installation`
+  #
+  # * `set_clp :get, requires_authentication: true` (or `{}` for master-only)
+  # * `set_clp :count` (master-only)
+  # * `set_clp :addField` (master-only)
+  # * {Parse::Object.protect_fields} to hide `device_token`, `gcm_sender_id`,
+  #   `push_type`, etc. from non-master reads — these are write-only from the
+  #   client's perspective in normal SDK flows.
+  #
+  # ### What you should NOT do with `set_clp` on `_Installation`
+  #
+  # * `set_clp :create, requires_authentication: true` — breaks device
+  #   registration for users who haven't logged in yet.
+  # * `set_clp :update, requires_authentication: true` — breaks background
+  #   device-token refresh and pre-login channel subscribe/unsubscribe.
+  # * Pointer-based `set_read_user_fields` / `set_write_user_fields` —
+  #   an installation has no stable owning user (a device can outlive a user
+  #   session and change users), so user-pointer ACLing is unreliable here.
+  # * `set_clp :find, public: true` (or any other `:find` config) —
+  #   has no effect; the server enforces master-only at the REST layer.
+  #
+  # If your app actually does require login before any installation write,
+  # put that policy in a `beforeSave('_Installation')` Cloud Code trigger
+  # rather than in CLP — the trigger fires under master-key context and can
+  # inspect `request.user` directly without breaking the SDK's anonymous
+  # registration handshake.
+  #
   # @see Push
   # @see Parse::Object
   class Installation < Parse::Object
     parse_class Parse::Model::CLASS_INSTALLATION
+
+    class << self
+      # Override {Parse::Object.set_clp} on `_Installation` so that any
+      # attempt to change CLP from the SDK emits a one-time advisory.
+      # Parse Server hardcodes `find` and `delete` on `_Installation` to
+      # master-key-only at the REST layer, and gates `create`/`update`
+      # on the `X-Parse-Installation-Id` header rather than CLP — so
+      # most CLP changes here either do nothing or break the SDK's
+      # device-registration flow. Behavior is otherwise unchanged.
+      def set_clp(operation, **opts)
+        _warn_about_installation_clp!(:set_clp, operation)
+        super
+      end
+
+      # Same advisory for the bulk-config DSL.
+      def set_class_access(**ops_to_access)
+        _warn_about_installation_clp!(:set_class_access, ops_to_access.keys)
+        super
+      end
+
+      # `protect_fields` on `_Installation` is a documented-legitimate use
+      # (e.g. hiding `device_token` / `gcm_sender_id` / `push_type` from
+      # non-master reads), so we deliberately do NOT fire the
+      # find/delete-are-hardcoded advisory here. The advisory exists to
+      # nudge callers away from CLP changes that the server ignores;
+      # protectedFields is one of the four operations on _Installation
+      # that CLP actually controls.
+      def protect_fields(pattern, fields)
+        super
+      end
+
+      # Pointer-permission helpers on `_Installation` are a mistake in
+      # practice (devices have no stable owning user); warn loudly.
+      def set_read_user_fields(*fields)
+        _warn_about_installation_clp!(:set_read_user_fields, fields)
+        super
+      end
+
+      def set_write_user_fields(*fields)
+        _warn_about_installation_clp!(:set_write_user_fields, fields)
+        super
+      end
+
+      # @!visibility private
+      def _warn_about_installation_clp!(method, detail)
+        return if @_installation_clp_warned
+        @_installation_clp_warned = true
+        msg = "[Parse::Installation] #{method}(#{Array(detail).inspect}) on _Installation: " \
+              "Parse Server hardcodes find/delete on _Installation to master-key-only " \
+              "(CLP changes for those operations are ignored), and gates create/update " \
+              "on the X-Parse-Installation-Id header rather than CLP. Only get, count, " \
+              "addField, and protectedFields actually respond to CLP here. " \
+              "If you need login-required writes, use a beforeSave('_Installation') " \
+              "Cloud Code trigger instead. See Parse::Installation docs and " \
+              "docs/client_sdk_guide.md §6.3."
+        if Parse.respond_to?(:logger) && Parse.logger
+          Parse.logger.warn(msg)
+        else
+          Kernel.warn(msg)
+        end
+      end
+    end
     # @!attribute gcm_sender_id
     # This field only has meaning for Android installations that use the GCM
     # push type. It is reserved for directing Parse to send pushes to this
@@ -135,6 +242,21 @@ module Parse
     # @return [Parse::Session] The associated {Parse::Session} that might be tied to this installation
     has_one :session, -> { where(installation_id: i.installation_id) }, scope_only: true
 
+    # @!attribute user
+    # The {Parse::User} associated with this installation. Parse Server
+    # populates this pointer when the installation is created or updated
+    # by an authenticated client (the session-token holder on the
+    # request). It is useful for targeted push delivery — finding all
+    # installations belonging to a given user.
+    #
+    # **Caveat — do not use for ACL or CLP scoping.** Devices outlive
+    # sessions and can change users (account switch, sign-out, shared
+    # device), so the `user` pointer on `_Installation` is not a
+    # reliable owner identity. See the "What you should NOT do with
+    # `set_clp`" notes above for the broader context.
+    # @return [Parse::User]
+    belongs_to :user
+
     # =========================================================================
     # Channel Management - Class Methods
     # =========================================================================

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

@@ -59,7 +59,9 @@ module Parse
   # @note This collection is consumed by external scheduling tooling, not by
   #   Parse Server itself. {#params} is stored as a JSON string (not an
   #   Object) per the canonical Parse Server schema; use {#parsed_params} to
-  #   decode. Master-key access is typically required.
+  #   decode. `_JobSchedule` is hardcoded master-key-only at Parse Server's
+  #   REST layer (`SharedRest.js`) — CLP changes via
+  #   {Parse::Object.set_clp} have no effect.
   # @see Parse::JobStatus
   # @see Parse::Object
   class JobSchedule < Parse::Object

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

@@ -70,7 +70,10 @@ module Parse
   #    Parse::JobStatus.failed.where(:created_at.gt => yesterday).all
   #
   # @note This collection is written by Parse Server itself and read access
-  #   typically requires the master key. Parse Server does not garbage-collect
+  #   requires the master key. `_JobStatus` is hardcoded master-key-only at
+  #   Parse Server's REST layer (`SharedRest.js`) — CLP changes via
+  #   {Parse::Object.set_clp} have no effect. Use a master-key client (or a
+  #   Cloud Code function) to read it. Parse Server does not garbage-collect
   #   `_JobStatus` rows — long-running deployments accumulate history and
   #   should implement their own retention policy.
   # @see Parse::JobSchedule for the corresponding scheduled-run configuration.

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

@@ -43,7 +43,10 @@ module Parse
   #   recent = Parse::PushStatus.recent.limit(10).all
   #   recent.each { |s| puts "#{s.status}: #{s.num_sent} sent" }
   #
-  # @note This collection requires master key access
+  # @note `_PushStatus` is hardcoded master-key-only at Parse Server's
+  #   REST layer (`SharedRest.js`). CLP changes via
+  #   {Parse::Object.set_clp} have no effect — all reads and writes
+  #   require a master-key client.
   # @see Parse::Push
   # @see Parse::Object
   class PushStatus < Parse::Object

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

@@ -27,6 +27,13 @@ module Parse
   #      has_one :installation, ->{ where(installation_id: i.installation_id) }, scope_only: true
   #   end
   #
+  # @note CLP on `_Session` is mostly redundant: non-master `find` queries
+  #   are silently rewritten by Parse Server's REST layer
+  #   (`RestQuery.js`) to scope by `user = <current user>`, so a caller
+  #   never sees another user's sessions regardless of CLP. `find` also
+  #   requires a session token. You cannot grant cross-user session
+  #   visibility through {Parse::Object.set_clp}.
+  #
   # @see Parse::Object
   class Session < Parse::Object
     parse_class Parse::Model::CLASS_SESSION