parse-stack-next 5.7.6 → 5.8.1

data/lib/parse/atlas_search.rb

@@ -8,6 +8,7 @@ require_relative "atlas_search/index_manager"
 require_relative "atlas_search/search_builder"
 require_relative "atlas_search/result"
 require_relative "atlas_search/session"
+require_relative "atlas_search/protected_paths"
 
 module Parse
   # Atlas Search module for MongoDB Atlas full-text search capabilities.
@@ -363,6 +364,7 @@ module Parse
 
         index_name = options[:index] || @default_index
         fields = normalize_fields(options[:fields])
+        assert_search_fields_allowed!(fields, protected_fields, resolution)
         limit = options[:limit] || 100
         skip_val = options[:skip] || 0
 
@@ -436,6 +438,15 @@ module Parse
           collection_name, resolution.permission_strings,
         )
         assert_highlight_field_allowed!(options[:highlight_field], protected_fields, resolution)
+        # The caller built this stage, so any operator path, sort key, or
+        # highlight inside it may name a protected field. Walk it and
+        # refuse before it runs: a protected field that decides matches
+        # or ranking leaks its value even though the output strips it.
+        ProtectedPaths.assert_search_stage_allowed!(
+          search_stage, protected_fields, resolution,
+          collection_name: collection_name,
+          method_name: "Parse::AtlasSearch.search_with_stage",
+        )
 
         search_pipeline!(
           collection_name, search_stage,
@@ -512,7 +523,8 @@ module Parse
           collection_name, resolution.permission_strings,
         )
         field_str = field.to_s
-        if !resolution.master? && protected_fields.include?(field_str)
+        if ProtectedPaths.enforce?(resolution, protected_fields) &&
+           ProtectedPaths.touches?(field_str, protected_fields)
           raise Parse::CLPScope::Denied.new(
             collection_name, :find,
             "Parse::AtlasSearch.autocomplete refused: field '#{field_str}' is in " \
@@ -547,6 +559,7 @@ module Parse
         unless resolution.master?
           acl_match = Parse::ACLScope.match_stage_for(resolution)
           pipeline << acl_match if acl_match
+          pipeline << pointer_fields_match_stage(pointer_fields, resolution) if pointer_fields
         end
 
         # Add filter if provided
@@ -648,6 +661,17 @@ module Parse
                 "accept that bucket counts include all rows, or use " \
                 "#search for ACL-scoped results without facets."
         end
+        # Inside Parse.without_master_key the only scope left is public,
+        # and $searchMeta bucket counts are not ACL-filtered there either,
+        # so they would count rows the block is meant to hide. Fail closed.
+        if Parse::ACLScope.master_key_suppressed?
+          raise FacetedSearchNotACLSafe,
+                "Parse::AtlasSearch.faceted_search cannot run inside " \
+                "Parse.without_master_key: $searchMeta bucket counts include " \
+                "rows the caller cannot read. Wrap the call in " \
+                "Parse.with_master_key to accept master-key counts, or use " \
+                "#search for ACL-scoped results without facets."
+        end
         # Wave-3b READPREF-4: see #search for rationale. Captured
         # before resolve_scope! pops the auth kwargs so the recursive
         # search() call below can re-thread it explicitly (resolve!
@@ -689,6 +713,21 @@ module Parse
           end
         end
 
+        # A non-master caller (the public fallback when no auth kwargs are
+        # passed) must not facet on, or text-match against, a protected
+        # field: bucket values and counts would reveal it directly, and a
+        # wildcard operator lets it decide which rows are counted.
+        unless resolution.master?
+          facet_protected = Parse::CLPScope.protected_fields_for(
+            collection_name, resolution.permission_strings,
+          )
+          ProtectedPaths.assert_search_stage_allowed!(
+            search_meta_stage, facet_protected, resolution,
+            collection_name: collection_name,
+            method_name: "Parse::AtlasSearch.faceted_search",
+          )
+        end
+
         # Execute facet query. $searchMeta MUST be the only / first
         # stage of its pipeline — Atlas rejects anything prepended.
         # Bypass Parse::MongoDB.aggregate (which would prepend a
@@ -788,6 +827,7 @@ module Parse
         unless resolution.master?
           acl_match = Parse::ACLScope.match_stage_for(resolution)
           pipeline << acl_match if acl_match
+          pipeline << pointer_fields_match_stage(pointer_fields, resolution) if pointer_fields
         end
 
         # Caller-supplied filter, sanitized against operator injection
@@ -797,6 +837,14 @@ module Parse
           pipeline << { "$match" => mongo_filter }
         end
 
+        # Sorting on a protected field orders rows by its value, which is
+        # the same oracle as matching on it.
+        if sort.is_a?(Hash) && !sort.empty?
+          ProtectedPaths.assert_paths_allowed!(
+            sort.keys.map(&:to_s), protected_fields, resolution,
+            collection_name: collection_name, what: "sort key",
+          )
+        end
         pipeline << { "$sort" => (sort || { "_score" => -1 }) }
         pipeline << { "$skip" => skip } if skip.to_i > 0
         pipeline << { "$limit" => limit }
@@ -816,6 +864,8 @@ module Parse
         unless resolution.master?
           Parse::ACLScope.redact_results!(raw_results, resolution)
           Parse::CLPScope.redact_protected_fields!(raw_results, protected_fields) if protected_fields.any?
+          # The pointerFields `$match` above already ran before `$limit`;
+          # this re-check is defense in depth and should drop nothing.
           if pointer_fields
             raw_results = Parse::CLPScope.filter_by_pointer_fields(
               raw_results, pointer_fields, resolution.user_id,
@@ -937,13 +987,37 @@ module Parse
           return Parse::ACLScope.resolve_for_role(acl_role, client: auth_client)
         end
 
-        if master == true
+        if master == true && !Parse::ACLScope.master_key_suppressed?
           return Parse::ACLScope::Resolution.new(
                    mode: :master, permission_strings: nil, user_id: nil, session: nil,
                    client: auth_client,
                  )
         end
 
+        # Inside `Parse.without_master_key` an explicit master request runs
+        # in the public scope, as Parse::ACLScope.resolve! does: no
+        # no-ACL banner (the caller did pass a scope), and either strict
+        # flag refuses the fallback.
+        if master == true
+          if @require_session_token == true || Parse::ACLScope.require_session_token == true
+            raise ACLRequired,
+                  "Parse::AtlasSearch.#{method_name} was called with master: true " \
+                  "inside Parse.without_master_key, which drops master mode, and " \
+                  "require_session_token refuses the public fallback. Pass " \
+                  "session_token:, or run the call inside Parse.with_master_key " \
+                  "if it needs master authority."
+          end
+          anonymous = Session::Resolved.new(nil, Set.new)
+          return Parse::ACLScope::Resolution.new(
+                   mode: :public,
+                   permission_strings: anonymous.permission_strings,
+                   user_id: nil,
+                   session: anonymous,
+                   client: auth_client,
+                   master_dropped: true,
+                 )
+        end
+
         if @require_session_token == true
           raise ACLRequired,
                 "Parse::AtlasSearch.#{method_name} requires session_token: or " \
@@ -980,13 +1054,12 @@ module Parse
       # does inline (we can't reuse that path because of the $search-
       # at-stage-0 invariant).
       def assert_clp_find!(collection_name, resolution)
-        return if resolution.nil? || resolution.master?
-        unless Parse::CLPScope.permits?(collection_name, :find, resolution.permission_strings)
-          raise Parse::CLPScope::Denied.new(
-            collection_name, :find,
-            "CLP refuses find on '#{collection_name}' for the current Atlas Search scope.",
-          )
-        end
+        # Same CLP branch evaluation as Parse::MongoDB.aggregate (public,
+        # user, and role grants first; then pointerFields / readUserFields).
+        # Raises Parse::CLPScope::Denied when the scope cannot find at all.
+        Parse::CLPScope.row_constraint_for!(collection_name, :find, resolution,
+                                            label: "Atlas Search")
+        nil
       end
 
       # Resolve and return pointerFields for `find` on the collection.
@@ -994,17 +1067,22 @@ module Parse
       # current scope has no user_id (acl_role-only / public agents).
       # Returns nil when master-mode or no pointerFields entry exists.
       def resolve_pointer_fields!(collection_name, resolution)
-        return nil if resolution.nil? || resolution.master?
-        pointer_fields = Parse::CLPScope.pointer_fields_for(collection_name, :find)
-        return nil if pointer_fields.nil?
-        if resolution.user_id.nil?
-          raise Parse::CLPScope::Denied.new(
-            collection_name, :find,
-            "CLP requires user identity (pointerFields=#{pointer_fields.inspect}) " \
-            "but the current Atlas Search scope has no user_id.",
-          )
-        end
-        pointer_fields
+        # nil when a public, user, or role grant already permits every row
+        # (Parse Server ignores pointer permissions then); otherwise the
+        # pointerFields plus readUserFields the rows must match. The older
+        # permits? / pointer_fields_for pair missed readUserFields entirely
+        # and over-restricted a public grant that also listed pointerFields.
+        Parse::CLPScope.row_constraint_for!(collection_name, :find, resolution,
+                                            label: "Atlas Search")
+      end
+
+      # The pointerFields / readUserFields ownership constraint as a
+      # `$match` stage, placed after the ACL `$match` and before `$sort` /
+      # `$limit`. Filtering the fetched rows afterwards returned short or
+      # empty pages whenever the top-ranked hits belonged to other users,
+      # even though eligible matches ranked below them.
+      def pointer_fields_match_stage(pointer_fields, resolution)
+        { "$match" => Parse::CLPScope.pointer_fields_predicate(pointer_fields, resolution.user_id) }
       end
 
       # ATLAS-4: refuse `highlight_field:` when the field is in the
@@ -1016,8 +1094,8 @@ module Parse
         return if highlight_field.nil?
         return if resolution.nil? || resolution.master?
         return if protected_fields.nil? || protected_fields.empty?
-        path = highlight_field.to_s
-        return unless protected_fields.include?(path)
+        return unless ProtectedPaths.touches?(highlight_field, protected_fields)
+        path = highlight_field.is_a?(String) || highlight_field.is_a?(Symbol) ? highlight_field.to_s : highlight_field.inspect
         raise Parse::CLPScope::Denied.new(
           nil, :find,
           "Parse::AtlasSearch.search refused: highlight_field '#{path}' is in " \
@@ -1026,6 +1104,35 @@ module Parse
         )
       end
 
+      # Refuse a scoped text search whose paths include a protected field,
+      # or that searches every field (no `fields:`) while the scope has
+      # protected fields. Stripping a protected field from the RESULT does
+      # not stop it from deciding which documents MATCH and how they RANK,
+      # so a caller could test guesses against its value. Master scopes and
+      # scopes with nothing protected are unaffected.
+      #
+      # @raise [Parse::CLPScope::Denied]
+      def assert_search_fields_allowed!(fields, protected_fields, resolution)
+        return if resolution.nil? || resolution.master?
+        return if protected_fields.nil? || protected_fields.empty?
+        if fields.nil? || fields.empty?
+          raise Parse::CLPScope::Denied.new(
+            nil, :find,
+            "Parse::AtlasSearch.search refused: a search over every field would " \
+            "match on protectedFields for the current scope; pass fields: with " \
+            "the fields to search.",
+          )
+        end
+        list = fields.is_a?(Array) ? fields : [fields]
+        hit = list.find { |f| ProtectedPaths.touches?(f, protected_fields) }
+        return unless hit
+        raise Parse::CLPScope::Denied.new(
+          nil, :find,
+          "Parse::AtlasSearch.search refused: field '#{hit}' is in protectedFields " \
+          "for the current scope; matching on it would reveal its value.",
+        )
+      end
+
       # Drop `_highlights` entries whose `path` matches a
       # protectedFields entry. Defense-in-depth complement to
       # {.assert_highlight_field_allowed!} — that gate refuses the
@@ -1035,13 +1142,14 @@ module Parse
       def strip_protected_highlights!(documents, protected_fields)
         return if documents.nil? || documents.empty?
         return if protected_fields.nil? || protected_fields.empty?
-        protected_set = protected_fields.to_set
         documents.each do |doc|
           next unless doc.is_a?(Hash)
           highlights = doc["_highlights"]
           next unless highlights.is_a?(Array)
           doc["_highlights"] = highlights.reject do |h|
-            h.is_a?(Hash) && protected_set.include?((h["path"] || h[:path]).to_s)
+            # A highlight entry with no usable path is dropped too: it
+            # cannot be shown to address an unprotected field.
+            h.is_a?(Hash) && ProtectedPaths.touches?(h["path"] || h[:path], protected_fields)
           end
         end
       end
@@ -1172,6 +1280,18 @@ module Parse
           Parse::PipelineSecurity.refuse_protected_field_references!(
             [{ "$match" => filter }], collection_name, resolution,
           )
+          # Predicate KEYS decide matches too: `{ "ssn" => /^1/ }` is the
+          # same oracle as the `$expr` form above. Refuse any key (top
+          # level or nested under $and/$or/$nor/$not, dotted or `_p_`
+          # storage form) that touches a protected field.
+          unless resolution.master?
+            protected_fields = Parse::CLPScope.protected_fields_for(
+              collection_name, resolution.permission_strings,
+            )
+            ProtectedPaths.assert_filter_allowed!(
+              filter, protected_fields, resolution, collection_name: collection_name,
+            )
+          end
         end
 
         filter

data/lib/parse/authorization.rb

@@ -97,12 +97,68 @@ module Parse
         @mutex.synchronize { @data.delete(key) }
       end
 
+      # Drop every entry whose value equals `value`. Lets the identity plane
+      # forget every token of one user after a revocation, since it is keyed
+      # by token and holds the user id as the value.
+      # @param value [Object]
+      # @return [Integer] number of entries removed.
+      def invalidate_value(value)
+        @mutex.synchronize do
+          before = @data.size
+          @data.delete_if { |_key, entry| entry[:value] == value }
+          before - @data.size
+        end
+      end
+
       # Drop every entry.
       def clear
         @mutex.synchronize { @data.clear }
       end
     end
 
+    # Process-local record of session objectId to owning user id, kept apart
+    # from the identity plane so no session token can ever read a record.
+    # Entries expire after `ttl` and the map holds at most {MAX_ENTRIES},
+    # dropping the oldest first. Values are stored typed
+    # (`{"session_owner" => user_id}`) so a shared store passed in its place
+    # cannot confuse a record with an identity entry either.
+    class SessionOwnerMap
+      MAX_ENTRIES = 10_000
+
+      def initialize
+        @data = {}
+        @mutex = Mutex.new
+      end
+
+      def get(key)
+        @mutex.synchronize do
+          entry = @data[key]
+          return nil if entry.nil?
+          if entry[:expires_at] < Time.now
+            @data.delete(key)
+            return nil
+          end
+          entry[:value]
+        end
+      end
+
+      def set(key, value, ttl:)
+        @mutex.synchronize do
+          @data.delete(key)
+          @data[key] = { value: value, expires_at: Time.now + ttl }
+          @data.shift while @data.size > MAX_ENTRIES
+        end
+      end
+
+      def invalidate(key)
+        @mutex.synchronize { @data.delete(key) }
+      end
+
+      def clear
+        @mutex.synchronize { @data.clear }
+      end
+    end
+
     # The outcome of resolving a caller. `user_id` is the `_User.objectId`
     # owning the session, or `nil` for an anonymous caller. `role_names` is a
     # `Set` of bare role names (no `role:` prefix) the user inherits
@@ -176,8 +232,26 @@ module Parse
         @role_cache_ttl = DEFAULT_ROLE_TTL
         @upstream_role_reader = nil
         @compare_upstream_roles = false
+        # Bumped by every invalidation. A token resolution captures it before
+        # calling `/users/me` and does not cache its answer when it moved, so
+        # a resolve already in flight when a session is revoked cannot put
+        # the revoked token back into the plane. A generation-capable plane
+        # (the shared Redis identity plane) keeps a plane-wide counter too,
+        # so the same holds across processes. See {#lookup_user_id}.
+        @invalidation_epoch = 0
+        @epoch_mutex = Mutex.new
+        @session_owner_cache = SessionOwnerMap.new
       end
 
+      # Where {#remember_session_owner} records which user owns a session
+      # objectId. A separate store from the identity plane, so a session
+      # token can never read a record. Defaults to a process-local
+      # {SessionOwnerMap}; set a shared store (anything with `get`, `set`
+      # with `ttl:`, `invalidate`, and `clear`) to share records across
+      # processes.
+      # @return [Object]
+      attr_accessor :session_owner_cache
+
       # Apply settings, leaving anything not passed unchanged.
       # @return [self]
       def configure(identity_cache: nil, role_cache: nil,
@@ -233,9 +307,40 @@ module Parse
       # @param session_token [String]
       def invalidate(session_token)
         return if session_token.nil?
+        bump_invalidation_epoch!
         @identity_cache.invalidate(session_token.to_s)
       end
 
+      # Forget every cached identity entry that resolves to `user_id`. Call
+      # after an event that revokes the user's sessions: a password change,
+      # account deletion, a session destroy, or "log out everywhere". The SDK
+      # calls it itself on those paths.
+      #
+      # The identity plane is keyed by token, so there is no direct way to
+      # name a user's entries. A generation-capable plane (the keyspaced
+      # Redis identity plane) bumps the user's generation, which rejects
+      # every entry for that user, including tokens this process never
+      # resolved. The default {MemoryCache} drops the matching values. A
+      # custom plane that supports neither is left to its TTL.
+      #
+      # The role entry is dropped too: it is cheap to rebuild and a deleted
+      # user should not keep a role closure around.
+      # @param user_id [String]
+      # @return [void]
+      def invalidate_user(user_id)
+        return if user_id.nil? || user_id.to_s.empty?
+        uid = user_id.to_s
+        bump_invalidation_epoch!
+        cache = @identity_cache
+        if generation_capable?(cache) && cache.respond_to?(:bump_generation)
+          cache.bump_generation(uid)
+        elsif cache.respond_to?(:invalidate_value)
+          cache.invalidate_value(uid)
+        end
+        @role_cache.invalidate(uid)
+        nil
+      end
+
       # Forget one user's cached role closure. Call after any `_Role.users`
       # mutation affecting them.
       # @param user_id [String]
@@ -244,10 +349,50 @@ module Parse
         @role_cache.invalidate(user_id.to_s)
       end
 
+      # Forget every cached role closure. Call after a `_Role.roles` hierarchy
+      # change, which can affect any user holding a role in that hierarchy.
+      def invalidate_all_roles
+        @role_cache.clear if @role_cache.respond_to?(:clear)
+      end
+
       # Drop every entry in both planes.
       def reset_caches!
+        bump_invalidation_epoch!
         @identity_cache.clear if @identity_cache.respond_to?(:clear)
         @role_cache.clear if @role_cache.respond_to?(:clear)
+        # A plane clear takes the plane-wide marker with it. Bump it again so
+        # it does not sit at a value a lookup that started before the reset
+        # could have captured.
+        bump_plane_epoch!
+      end
+
+      # Record which user owns a session objectId, so a later delete of that
+      # session can drop the owner's cached identities even when the delete
+      # can no longer read the session row (it is already gone, or not
+      # visible to the caller). Only the owner's user id is stored, never the
+      # token. Called when a `_Session` row with both is loaded from the
+      # server. The entry lives as long as an identity entry.
+      # @param session_id [String]
+      # @param user_id [String]
+      # @return [void]
+      def remember_session_owner(session_id, user_id)
+        return if session_id.to_s.empty? || user_id.to_s.empty?
+        @session_owner_cache.set(session_id.to_s, { "session_owner" => user_id.to_s }, ttl: @identity_cache_ttl)
+        nil
+      rescue StandardError
+        nil
+      end
+
+      # The owner recorded by {#remember_session_owner}, or nil.
+      # @param session_id [String]
+      # @return [String, nil]
+      def session_owner(session_id)
+        return nil if session_id.to_s.empty?
+        value = @session_owner_cache.get(session_id.to_s)
+        owner = value.is_a?(Hash) ? value["session_owner"] : nil
+        owner.is_a?(String) && !owner.empty? ? owner : nil
+      rescue StandardError
+        nil
       end
 
       def inspect
@@ -266,8 +411,21 @@ module Parse
         cached = cached_user_id(session_token)
         return cached unless cached.nil?
 
+        # Captured before `/users/me`: an invalidation that lands while the
+        # lookup is in flight must win over the answer it returns. The plane
+        # marker is created first if a clear removed it, so the snapshot
+        # never holds "no marker", which a concurrent reset also produces.
+        ensure_plane_marker!
+        snapshot = invalidation_snapshot
+        prior_uid, prior_gen = prior_generation(session_token)
+
         response = begin
-            @client.current_user(session_token)
+            # cache: false: a revoked or expired token must not re-resolve
+            # from a cached /users/me response after its identity entry is
+            # evicted or invalidated. The identity plane above is the only
+            # cache on this path, so its TTL and invalidation hooks bound
+            # revocation.
+            @client.current_user(session_token, cache: false)
           rescue => e
             raise InvalidSession, "session token lookup failed: #{e.class}: #{e.message}"
           end
@@ -278,10 +436,136 @@ module Parse
         raise InvalidSession, "session token resolved no user objectId" if user_id.nil? || user_id.to_s.empty?
 
         user_id = user_id.to_s
-        store_user_id(session_token, user_id)
+        # A stale entry for the same user tells us its generation from
+        # before the lookup; storing under it lets a bump made across
+        # processes during the lookup still reject the entry.
+        store_unless_invalidated(session_token, user_id, snapshot,
+                                 gen: prior_uid == user_id ? prior_gen : nil)
         user_id
       end
 
+      # Cache a resolved identity only if no invalidation happened since
+      # `snapshot` was taken, without a window between the check and the
+      # write.
+      #
+      # Every invalidation bumps the counters BEFORE it drops entries. The
+      # write is checked before and re-checked after; a change seen by the
+      # second check evicts what was just written. So an invalidation either
+      # bumped before the re-check (the entry is evicted here) or bumped
+      # after it, which means it also drops entries after the write (the
+      # entry is removed, or its generation goes stale, by the invalidation
+      # itself). Either way the revoked identity does not stay cached. The
+      # plane-wide counter extends this to invalidations made by other
+      # processes sharing a generation-capable plane.
+      def store_unless_invalidated(session_token, user_id, snapshot, gen: nil)
+        return unless snapshot_usable?(snapshot)
+        return unless invalidation_snapshot == snapshot
+        store_user_id(session_token, user_id, gen: gen)
+        return if invalidation_snapshot == snapshot
+        @identity_cache.invalidate(session_token)
+      rescue StandardError
+        # Not caching is always safe: the next read resolves again.
+        begin
+          @identity_cache.invalidate(session_token)
+        rescue StandardError
+          nil
+        end
+      end
+
+      # The process counter plus, on a generation-capable plane, the
+      # plane-wide counter shared by every process using that plane.
+      def invalidation_snapshot
+        [current_invalidation_epoch, plane_epoch]
+      end
+
+      # A snapshot whose plane counter could not be read cannot prove that no
+      # other process invalidated during the lookup, so it never caches.
+      #
+      # An absent marker on a plane that keeps one is not usable either: a
+      # reset in another process deletes the marker before it installs a new
+      # one, so "absent" before and after the write cannot prove that no reset
+      # ran in between. The re-check after the write compares against a
+      # present marker, so reading it absent there evicts the write.
+      def snapshot_usable?(snapshot)
+        snapshot[1] != :unavailable && snapshot[1] != :absent
+      end
+
+      # Create the plane-wide marker when the plane keeps one and it is
+      # missing (a fresh plane, or one a reset has just cleared).
+      def ensure_plane_marker!
+        cache = @identity_cache
+        if cache.respond_to?(:invalidation_nonce)
+          cache.bump_invalidation_nonce if cache.invalidation_nonce.nil?
+        elsif generation_capable?(cache) && cache.respond_to?(:bump_generation)
+          gen = cache.generation(PLANE_EPOCH_SUBJECT)
+          cache.bump_generation(PLANE_EPOCH_SUBJECT) if gen.nil? || gen.to_i.zero?
+        end
+      rescue StandardError
+        nil
+      end
+
+      def bump_invalidation_epoch!
+        @epoch_mutex.synchronize { @invalidation_epoch += 1 }
+        bump_plane_epoch!
+      end
+
+      def current_invalidation_epoch
+        @epoch_mutex.synchronize { @invalidation_epoch }
+      end
+
+      # Reserved generation subject for the plane-wide invalidation counter
+      # on a custom generation-capable plane without an invalidation nonce.
+      # Parse objectIds are alphanumeric, so it cannot name a real user.
+      PLANE_EPOCH_SUBJECT = "~identity-invalidations"
+
+      # The plane-wide invalidation marker: a random nonce replaced on every
+      # invalidation when the plane offers one ({Parse::Cache::SubCache}
+      # does), else a generation counter. nil when the plane has neither,
+      # `:absent` when the plane keeps one but it is missing (fresh or just
+      # cleared), `:unavailable` when reading it failed. A nonce never repeats,
+      # so a plane clear that drops it cannot make an old value come back. A
+      # generation counter can: a custom plane whose `clear` also deletes its
+      # generations restarts the counter, so a lookup racing another
+      # process's reset is bounded by `identity_cache_ttl`. Such a plane
+      # should implement `invalidation_nonce` / `bump_invalidation_nonce`.
+      def plane_epoch
+        cache = @identity_cache
+        if cache.respond_to?(:invalidation_nonce)
+          nonce = cache.invalidation_nonce
+          return nonce.nil? ? :absent : nonce
+        end
+        return nil unless generation_capable?(cache)
+        gen = cache.generation(PLANE_EPOCH_SUBJECT)
+        gen.nil? || gen.to_i.zero? ? :absent : gen
+      rescue StandardError
+        :unavailable
+      end
+
+      def bump_plane_epoch!
+        cache = @identity_cache
+        if cache.respond_to?(:bump_invalidation_nonce)
+          cache.bump_invalidation_nonce
+        elsif generation_capable?(cache) && cache.respond_to?(:bump_generation)
+          cache.bump_generation(PLANE_EPOCH_SUBJECT)
+        end
+      rescue StandardError
+        nil
+      end
+
+      # The user id and that user's current generation from a stale entry
+      # already stored for the token, read before `/users/me`.
+      # @return [Array(String, Object), Array(nil, nil)]
+      def prior_generation(session_token)
+        cache = @identity_cache
+        return [nil, nil] unless generation_capable?(cache)
+        raw = cache.get(session_token)
+        uid = raw.is_a?(Hash) ? (raw["user_id"] || raw[:user_id]) : nil
+        return [nil, nil] if uid.nil?
+        [uid.to_s, cache.generation(uid.to_s)]
+      rescue StandardError
+        [nil, nil]
+      end
+
       # Read the identity plane and, where the plane supports it, check that
       # the entry's generation is still current.
       #
@@ -316,10 +600,11 @@ module Parse
 
       # Write the identity entry, tagging it with the subject's current
       # generation when the plane can track one.
-      def store_user_id(session_token, user_id)
+      def store_user_id(session_token, user_id, gen: nil)
         cache = @identity_cache
         if generation_capable?(cache)
-          cache.set(session_token, { "user_id" => user_id, "gen" => cache.generation(user_id) },
+          gen = cache.generation(user_id) if gen.nil?
+          cache.set(session_token, { "user_id" => user_id, "gen" => gen },
                     ttl: @identity_cache_ttl)
         else
           cache.set(session_token, user_id, ttl: @identity_cache_ttl)