fix(replay): generate session_id client-side to avoid NAT collisions

[ayushjhanwar-png]

Problem

The server's default replay `session_id` derivation hashes `salt + projectId + ip + user-agent`. Every user behind the same NAT (office, home WiFi, mobile carrier) collapses to the same `session_id` — their replay timelines get merged into one shared session.

Verified in our Dashverse office: multiple colleagues' recordings of Frameo showed up under the same replay id, viewable as one merged timeline.

Why upstream's suggested workaround doesn't fix this

Upstream is aware of the broader fingerprinting bug (issue #337). The maintainer suggested using the existing `__deviceId` property override:

"Overriding device id is something we want to improve. The plan is that the end user should be able to hook in a persistent identifier..."

BUT — the `__deviceId` override only affects `track` / `identify` event flows. The replay handler ignores property overrides and recomputes `deviceId` from IP+UA directly to look up the session. So `__deviceId` does not fix replay session merging.

The fix (two parts, scoped to replay only)

1. SDK side — `packages/sdks/web/src/index.ts`

• On replay start, generate a `session_id` client-side via `crypto.randomUUID()` and persist in `sessionStorage`.
• Per-tab (so different tabs = different sessions, like every analytics tool); rotates after 30 min idle (matches the existing server-side rotation rule).
• Also persists a `device_id` in `localStorage` — not sent on the wire today, reserved for future cross-tab stitching.
• Refresh `last_activity` on every chunk send so an actively-used tab keeps the same session indefinitely.
• Fall back to legacy server-derived id if browser storage is unavailable (sandboxed iframe, quota exhausted) — no regression for those edge cases.
• `crypto.randomUUID()` with a `Math.random`-based v4 UUID fallback for older browsers / http:// contexts.

2. Server side — `apps/api/src/controllers/track.controller.ts`

   let sessionId = payload.session_id;
-  if (ip && ua) {
+  if (!sessionId && ip && ua) {
     try {
       // existing IP+UA derivation
     }
   }

Trust the SDK-provided id when present; only derive from IP+UA as a fallback for SDKs that don't send one.

What this does NOT change

• ❌ `track` events — `deviceId` still derived from IP+UA (or existing `__deviceId` override)
• ❌ `identify` events — unchanged
• ❌ Analytics session counts, funnel analytics, retention — unchanged
• ❌ Profile attribution — unchanged

Only the replay session_id derivation is altered, and only when the SDK sends one.

Backward-compatibility / deployment safety

This is safe to ship to prod independently — frameo-pro and other consumers can update the SDK on their own timeline.

Step	Browser state	What happens
Today (no PR)	Old SDK	Server derives session_id from IP+UA. NAT users merged.
After this PR ships, before SDK bump	Old SDK	SDK still polls server for session_id (still IP+UA-derived), echoes it back on chunks. Server uses what SDK sent. Same result as today. No regression.
After SDK bump rolls out	New SDK	SDK generates UUID, sends with chunks. Server uses it. NAT collision gone for new sessions.

The only requirement: ship the server change first (this PR), then the SDK. Doing it in the opposite order would have the SDK send a UUID that the old server would override.

Trade-offs we accept

• Tab fragmentation: opening Frameo in 2 tabs = 2 replay sessions. Correct for replay (each tab is a coherent activity); minor over-counting in cross-tab journey analysis. Mitigated by the `device_id` in `localStorage` for future use.
• Long-tab idle: client-enforced 30-min rotation matches the server's existing 30-min rule. Same threshold; same dashboard semantics.
• Mobile Safari tab suspension: can clear sessionStorage when tab is suspended → new session on resume. Not data loss; `localStorage` device_id still survives.
• Storage-blocked browsers: SDK falls back to server-derived id. Same NAT collision as today for that <0.5% of traffic.
• Historical data: sessions already merged in CH stay merged. Only NEW recordings get unique IDs.

Test plan

• Typecheck clean for `@openpanel/web` and our two changed files
• Deploy this PR to dev cluster, send replay chunks from 2 different browsers behind same dev VPN IP, verify they go to different sessions
• Deploy to prod, monitor worker-cron flush success rate stays at 100%
• After SDK npm publish + frameo-pro bump, verify office colleagues' replays are now separated
• Verify replays from old cached SDKs (no `session_id` change) still record correctly

Related

• Upstream issue feat(ingestion): Kafka (Azure Event Hubs) event transport behind KAFKA_BROKERS #337 — "Three compounding data integrity issues" (closed, maintainer deferred Bug 1 to "use `__deviceId` override")
• Upstream PR fix(db): cheap verifyDay + memory caps (fix big-day OOM) + CodeRabbit fixes #393 — "feat: new session management" (merged, doesn't address NAT collision per se)