where_is_waldo 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29833d47ae21a1aa5a1882e515152ddde9f7201eb9754cff81545495a0cd6d63
-  data.tar.gz: e7d41c790a9abbd4f3bdbd3ced6db38ce335629c189c0bd6404c40ce3874f82d
+  metadata.gz: 9caee3a6cb5747d9ce5ab460315fdaca5a9f05f7521dbe07f36a6d9fe5de48d9
+  data.tar.gz: f7e293f87b04039c7a2dbc21e6a80ef574a773438800588a9f87255b9336497a
 SHA512:
-  metadata.gz: f7634cd0688c8f56bb3292ae1f8c9db9146d1775552afb7f7801a5c898a97ab257bdbb80aa012c3a7ef79bfdd714bce7c1bb9a9c486d859e2f7bff5dd70891cc
-  data.tar.gz: 59335dc215e4666a577294fd9f383cd178102bf1c8f649b0bf30a738ec63be5078e0d541cb3f6d11b6ed9765b561fa45c17665fdc2fb4a8f8df23f59fc486815
+  metadata.gz: 95e63474cdbfff6c224b4bc4882bba3fb96cb157bf73a7769a1755f8b6326cba60e19aee6b06fc8fb58fc483496a68f8aa3e6bd03513a1782802ca123f8b9cb7
+  data.tar.gz: 9abb3e965ddf1a13722e5700c2c3c8927c9b6b43593801e592670ec4ab09483ce2a3cf2da6a764dfbfb204e238a0107cbd9628067c5e06b0d7920a24412a0726

data/CHANGELOG.md

@@ -3,6 +3,51 @@
 Notable changes to where_is_waldo. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## 0.1.5
+
+### Security / correctness
+
+- **Session keys are now namespaced by subject_id.** Both adapters previously
+  keyed session rows by `session_id` alone (`waldo:session:<sid>` in Redis;
+  `unique_by: session_column` upsert in the DB). If two authenticated
+  subjects independently supplied the same `session_id` — client-supplied
+  values, JWT `jti` reuse across users, etc. — one subject's `connect`
+  would overwrite the other's row, and subsequent `heartbeat`/`disconnect`
+  calls could reach into the wrong subject's presence. Now:
+  - **RedisAdapter**: session key is `waldo:session:<subject_id>:<session_id>`.
+    The reverse-map key `waldo:session_subject:<session_id>` is removed —
+    callers must pass `subject_id` to `heartbeat`, `session_status`, and
+    session-scoped `disconnect`, so the disambiguation is at the API
+    boundary rather than a lookup that could return the wrong subject.
+  - **DatabaseAdapter**: `Presence.upsert(unique_by: [subject_column,
+    session_column])`. `heartbeat` / `session_status` / session-scoped
+    `disconnect` all scope by both keys. The install generator's migration
+    template now creates a composite unique index on `(subject_column,
+    session_column)` instead of a unique index on `session_column` alone.
+
+### Breaking API changes
+
+- `heartbeat` — `subject_id:` is now a required kwarg
+  (`heartbeat(session_id:, subject_id:, ...)`).
+- `session_status` — signature is `session_status(session_id, subject_id)`
+  (previously `session_status(session_id)`).
+- `disconnect(session_id:)` — now raises `ArgumentError` when called with
+  `session_id:` but no `subject_id:`. Subject-only `disconnect(subject_id:)`
+  and paired `disconnect(session_id:, subject_id:)` are the two supported
+  shapes.
+- `Broadcaster.broadcast_to_session(session_id, subject_id, message_type, data)`
+  — `subject_id` inserted as the second positional argument (previously
+  `broadcast_to_session(session_id, message_type, data)`).
+
+### DB migration
+
+Hosts on the `:database` adapter must swap the unique index on the presences
+table:
+```ruby
+remove_index :presences, :<session_column>
+add_index :presences, [:<subject_column>, :<session_column>], unique: true
+```
+
 ## 0.1.4
 
 ### Fixed

data/VERSION

@@ -1 +1 @@
-0.1.4
+0.1.5

data/app/channels/where_is_waldo/presence_channel.rb

@@ -25,7 +25,7 @@ module WhereIsWaldo
     def unsubscribed
       return if presence_suppressed?
 
-      WhereIsWaldo.disconnect(session_id: waldo_session_id)
+      WhereIsWaldo.disconnect(session_id: waldo_session_id, subject_id: waldo_subject_id)
 
       # Recompute the subject's aggregate (they may still be present in another
       # tab/device) and announce the change to the org roster.
@@ -42,6 +42,7 @@ module WhereIsWaldo
 
       WhereIsWaldo.heartbeat(
         session_id: waldo_session_id,
+        subject_id: waldo_subject_id,
         tab_visible: tab_visible,
         subject_active: subject_active,
         last_activity_at: data[:last_activity_at],

data/app/services/where_is_waldo/adapters/base_adapter.rb

@@ -12,9 +12,11 @@ module WhereIsWaldo
         raise NotImplementedError
       end
 
-      # Remove a presence
-      # @param session_id [String] Session identifier (optional if subject_id provided)
-      # @param subject_id [Integer/String] Subject identifier (optional)
+      # Remove a presence. Session-scoped disconnect requires both keys so
+      # a caller-supplied session_id can't disconnect another subject's row.
+      # Subject-only disconnect removes every session for that subject.
+      # @param session_id [String] Session identifier (requires subject_id when set)
+      # @param subject_id [Integer/String] Subject identifier
       # @return [Boolean] success
       def disconnect(session_id: nil, subject_id: nil)
         raise NotImplementedError
@@ -22,11 +24,14 @@ module WhereIsWaldo
 
       # Update heartbeat
       # @param session_id [String] Session identifier
+      # @param subject_id [Integer/String] Subject identifier (required —
+      #   pairs with session_id to disambiguate colliding session ids across
+      #   subjects)
       # @param tab_visible [Boolean] Is tab in foreground
       # @param subject_active [Boolean] Recent activity
       # @param metadata [Hash] Additional data
       # @return [Boolean] success
-      def heartbeat(session_id:, tab_visible: true, subject_active: true, metadata: {})
+      def heartbeat(session_id:, subject_id:, tab_visible: true, subject_active: true, metadata: {})
         raise NotImplementedError
       end
 
@@ -65,8 +70,10 @@ module WhereIsWaldo
 
       # Get session status
       # @param session_id [String] Session identifier
+      # @param subject_id [Integer/String] Subject identifier — required
+      #   for the same reason as heartbeat (see above)
       # @return [Hash, nil] Presence record or nil
-      def session_status(session_id)
+      def session_status(session_id, subject_id)
         raise NotImplementedError
       end
 

data/app/services/where_is_waldo/adapters/database_adapter.rb

@@ -19,8 +19,12 @@ module WhereIsWaldo
           updated_at: now
         }
 
+        # (subject, session) is the unique key — see the install migration
+        # template. Keying on session alone would let a caller-supplied
+        # session_id colliding across two subjects upsert onto each other's
+        # row.
         # rubocop:disable Rails/SkipsModelValidations -- intentional for performance
-        Presence.upsert(attrs, unique_by: session_column)
+        Presence.upsert(attrs, unique_by: [subject_column, session_column])
         # rubocop:enable Rails/SkipsModelValidations
         true
       rescue StandardError => e
@@ -29,15 +33,21 @@ module WhereIsWaldo
       end
 
       def disconnect(session_id: nil, subject_id: nil)
+        raise ArgumentError, "disconnect(session_id:) requires subject_id:" if session_id && !subject_id
+
         scope = build_lookup_scope(session_id: session_id, subject_id: subject_id)
         scope.delete_all
         true
+      rescue ArgumentError
+        raise
       rescue StandardError => e
         Rails.logger.error "[WhereIsWaldo] Disconnect failed: #{e.message}"
         false
       end
 
-      def heartbeat(session_id:, tab_visible: true, subject_active: true, last_activity_at: nil, metadata: {})
+      # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+      def heartbeat(session_id:, subject_id:, tab_visible: true, subject_active: true, last_activity_at: nil, metadata: {})
+        # rubocop:enable Metrics/ParameterLists, Layout/LineLength
         now = Time.current
         updates = {
           last_heartbeat: now,
@@ -53,7 +63,9 @@ module WhereIsWaldo
         end
         updates[:metadata] = metadata if metadata.present?
 
-        scope = Presence.where(session_column => session_id)
+        # Scope by both — a caller-supplied session_id shouldn't be able to
+        # heartbeat another subject's row.
+        scope = Presence.where(session_column => session_id, subject_column => subject_id)
 
         # rubocop:disable Rails/SkipsModelValidations -- intentional for performance
         scope.update_all(updates).positive?
@@ -88,8 +100,8 @@ module WhereIsWaldo
              .transform_values { |rows| rows.map(&:as_presence_hash) }
       end
 
-      def session_status(session_id)
-        scope = Presence.where(session_column => session_id)
+      def session_status(session_id, subject_id)
+        scope = Presence.where(session_column => session_id, subject_column => subject_id)
         scope = scope.includes(:subject) if config.subject_class_constant
         scope.first&.as_presence_hash
       end
@@ -102,8 +114,8 @@ module WhereIsWaldo
       private
 
       def build_lookup_scope(session_id: nil, subject_id: nil)
-        if session_id
-          Presence.where(session_column => session_id)
+        if session_id && subject_id
+          Presence.where(session_column => session_id, subject_column => subject_id)
         elsif subject_id
           Presence.where(subject_column => subject_id)
         else

data/app/services/where_is_waldo/adapters/redis_adapter.rb

@@ -20,17 +20,15 @@ module WhereIsWaldo
         }
 
         redis.multi do |tx|
-          # Store session data
-          tx.set(session_key(session_id), presence_data.to_json, ex: ttl)
+          # Session key includes subject_id so two subjects with the same
+          # caller-supplied session_id can't overwrite each other's row.
+          tx.set(session_key(subject_id, session_id), presence_data.to_json, ex: ttl)
 
           # Add to online subjects sorted set with timestamp as score
           tx.zadd(online_subjects_key, now, subject_id)
 
           # Add to subject's sessions set
           tx.sadd(subject_sessions_key(subject_id), session_id)
-
-          # Map session to subject for reverse lookup
-          tx.set(session_subject_key(session_id), subject_id, ex: ttl)
         end
 
         true
@@ -41,19 +39,25 @@ module WhereIsWaldo
 
       def disconnect(session_id: nil, subject_id: nil)
         if session_id
-          disconnect_session(session_id)
+          raise ArgumentError, "disconnect(session_id:) requires subject_id:" unless subject_id
+
+          disconnect_session(subject_id, session_id)
         elsif subject_id
           disconnect_subject(subject_id)
         end
 
         true
+      rescue ArgumentError
+        raise
       rescue StandardError => e
         Rails.logger.error "[WhereIsWaldo] Redis disconnect failed: #{e.message}"
         false
       end
 
-      def heartbeat(session_id:, tab_visible: true, subject_active: true, last_activity_at: nil, metadata: {})
-        data = get_presence_data(session_id)
+      # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+      def heartbeat(session_id:, subject_id:, tab_visible: true, subject_active: true, last_activity_at: nil, metadata: {})
+        # rubocop:enable Metrics/ParameterLists, Layout/LineLength
+        data = get_presence_data(subject_id, session_id)
         return false unless data
 
         now = Time.current.to_i
@@ -69,7 +73,7 @@ module WhereIsWaldo
         data["metadata"] = data["metadata"].merge(metadata) if metadata.present?
 
         redis.multi do |tx|
-          tx.set(session_key(session_id), data.to_json, ex: ttl)
+          tx.set(session_key(subject_id, session_id), data.to_json, ex: ttl)
           tx.zadd(online_subjects_key, now, data["subject_id"])
         end
 
@@ -90,7 +94,7 @@ module WhereIsWaldo
         session_ids = redis.smembers(subject_sessions_key(subject_id))
 
         session_ids.filter_map do |sid|
-          data = get_presence_data(sid)
+          data = get_presence_data(subject_id, sid)
           build_presence_hash(data) if data
         end
       end
@@ -103,7 +107,7 @@ module WhereIsWaldo
         ids.each_with_object({}) do |sid, memo|
           session_ids = redis.smembers(subject_sessions_key(sid))
           live = session_ids.filter_map do |cid|
-            data = get_presence_data(cid)
+            data = get_presence_data(sid, cid)
             next unless data && data["last_heartbeat"].to_i >= threshold
 
             build_presence_hash(data)
@@ -112,8 +116,8 @@ module WhereIsWaldo
         end
       end
 
-      def session_status(session_id)
-        data = get_presence_data(session_id)
+      def session_status(session_id, subject_id)
+        data = get_presence_data(subject_id, session_id)
         return nil unless data
 
         build_presence_hash(data)
@@ -130,7 +134,7 @@ module WhereIsWaldo
           # Check if any sessions are still active
           session_ids = redis.smembers(subject_sessions_key(subject_id))
           all_stale = session_ids.all? do |sid|
-            data = get_presence_data(sid)
+            data = get_presence_data(subject_id, sid)
             !data || data["last_heartbeat"].to_i < threshold
           end
 
@@ -160,8 +164,11 @@ module WhereIsWaldo
         config.redis_prefix || "where_is_waldo"
       end
 
-      def session_key(session_id)
-        "#{key_prefix}:session:#{session_id}"
+      # Session data key. Namespaced by subject_id so a caller-supplied
+      # session_id colliding across two authenticated subjects doesn't let one
+      # clobber the other's presence row (see CHANGELOG 0.1.5).
+      def session_key(subject_id, session_id)
+        "#{key_prefix}:session:#{subject_id}:#{session_id}"
       end
 
       def online_subjects_key
@@ -172,27 +179,17 @@ module WhereIsWaldo
         "#{key_prefix}:subject:#{subject_id}:sessions"
       end
 
-      def session_subject_key(session_id)
-        "#{key_prefix}:session_subject:#{session_id}"
-      end
-
-      def get_presence_data(session_id)
-        json = redis.get(session_key(session_id))
+      def get_presence_data(subject_id, session_id)
+        json = redis.get(session_key(subject_id, session_id))
         return nil unless json
 
         JSON.parse(json)
       end
 
-      def disconnect_session(session_id)
-        data = get_presence_data(session_id)
-        return unless data
-
-        subject_id = data["subject_id"]
-
+      def disconnect_session(subject_id, session_id)
         redis.multi do |tx|
-          tx.del(session_key(session_id))
+          tx.del(session_key(subject_id, session_id))
           tx.srem(subject_sessions_key(subject_id), session_id)
-          tx.del(session_subject_key(session_id))
         end
 
         # If no more sessions for this subject, remove from online set
@@ -202,7 +199,7 @@ module WhereIsWaldo
 
       def disconnect_subject(subject_id)
         session_ids = redis.smembers(subject_sessions_key(subject_id))
-        session_ids.each { |sid| disconnect_session(sid) }
+        session_ids.each { |sid| disconnect_session(subject_id, sid) }
         redis.zrem(online_subjects_key, subject_id)
       end
 

data/app/services/where_is_waldo/broadcaster.rb

@@ -35,14 +35,16 @@ module WhereIsWaldo
 
       # Broadcast to a specific session
       # @param session_id [String] Session identifier
+      # @param subject_id [Integer/String] Subject identifier — required
+      #   to disambiguate colliding session ids across subjects
       # @param message_type [String, Symbol] Message type
       # @param data [Hash] Message payload
-      def broadcast_to_session(session_id, message_type, data = {})
-        status = PresenceService.session_status(session_id)
+      def broadcast_to_session(session_id, subject_id, message_type, data = {})
+        status = PresenceService.session_status(session_id, subject_id)
         return false unless status
 
         message = build_message(message_type, data, target_session: session_id)
-        ActionCable.server.broadcast(subject_stream(status[:subject_id]), message)
+        ActionCable.server.broadcast(subject_stream(subject_id), message)
         true
       end
 

data/app/services/where_is_waldo/presence_service.rb

@@ -29,14 +29,20 @@ module WhereIsWaldo
 
       # Update heartbeat for a session
       # @param session_id [String] Session identifier
+      # @param subject_id [Integer/String] Subject identifier (required —
+      #   pairs with session_id to disambiguate colliding session ids across
+      #   subjects)
       # @param tab_visible [Boolean] Is tab in foreground
       # @param subject_active [Boolean] Recent activity
       # @param last_activity_at [Integer] Unix timestamp (ms) of last user activity
       # @param metadata [Hash] Additional data to merge
       # @return [Boolean] success
-      def heartbeat(session_id:, tab_visible: true, subject_active: true, last_activity_at: nil, metadata: {})
+      # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+      def heartbeat(session_id:, subject_id:, tab_visible: true, subject_active: true, last_activity_at: nil, metadata: {})
+        # rubocop:enable Metrics/ParameterLists, Layout/LineLength
         adapter.heartbeat(
           session_id: session_id,
+          subject_id: subject_id,
           tab_visible: tab_visible,
           subject_active: subject_active,
           last_activity_at: last_activity_at,
@@ -85,6 +91,8 @@ module WhereIsWaldo
 
       # Get status of a specific session
       # @param session_id [String] Session identifier
+      # @param subject_id [Integer/String] Subject identifier — required
+      #   for the same reason as heartbeat
       # @return [Hash, nil] Presence record or nil
       delegate :session_status, to: :adapter
 

data/lib/generators/where_is_waldo/install/templates/create_presences.rb.tt

@@ -22,10 +22,15 @@ class Create<%= table_name.camelize %> < ActiveRecord::Migration[7.0]
       t.timestamps
     end
 
-    # Session must be unique
-    add_index :<%= table_name %>, :<%= session_column %>, unique: true
-
-    # Query by subject
+    # (subject, session) must be unique together. Keying by session alone
+    # would let two authenticated subjects that happen to collide on a
+    # session id (client-supplied values, JWT jti reuse, etc.) upsert onto
+    # each other's row.
+    add_index :<%= table_name %>, [:<%= subject_column %>, :<%= session_column %>], unique: true
+
+    # Session lookups (heartbeat, disconnect, session_status) always scope
+    # by (subject, session); the composite unique index above serves those.
+    # Query by subject alone
     add_index :<%= table_name %>, :<%= subject_column %>
 
     # Cleanup old records

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: where_is_waldo
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Scott Gibson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails