πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
test(userIdService): add tests for user ID generation consistency across browser updates and different browsers
Bill Yangb9dc8143ebb1
diff --git a/server/src/services/userId/normalizeUserAgent.test.ts b/server/src/services/userId/normalizeUserAgent.test.tsnew file mode 100644index 000000000..3ca60a223--- /dev/null+++ b/server/src/services/userId/normalizeUserAgent.test.ts@@ -0,0 +1,171 @@+import { describe, expect, it } from "vitest";+import { normalizeUserAgentForIdentity } from "./normalizeUserAgent.js";++/**+ * Every fixture below is a real user agent captured off production ingestion+ * (op.gg's Rybbit instance, 2026-08-18), so the pairs that must collapse are+ * pairs that actually did split a visitor in two.+ */+const UA = {+ opggElectron251:+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) opgg-electron-app/2.5.1 Chrome/132.0.6834.210 Electron/34.5.7 Safari/537.36",+ opggElectron253:+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) opgg-electron-app/2.5.3 Chrome/142.0.7444.265 Electron/39.8.13 Safari/537.36",+ chromeWin150:+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36",+ chromeWin151:+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36",+ edgeWin151:+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36 Edg/151.0.0.0",+ safariIos1857:+ "Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.7 Mobile/15E148 Safari/604.1",+ safariIos266:+ "Mozilla/5.0 (iPhone; CPU iPhone OS 26_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6 Mobile/15E148 Safari/604.1",+ safariIpad266:+ "Mozilla/5.0 (iPad; CPU OS 26_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6 Mobile/15E148 Safari/604.1",+ chromeIos:+ "Mozilla/5.0 (iPhone; CPU iPhone OS 26_0_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/151.0.7922.112 Mobile/15E148 Safari/604.1",+ chromeIosPatched:+ "Mozilla/5.0 (iPhone; CPU iPhone OS 26_0_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/151.0.7922.140 Mobile/15E148 Safari/604.1",+ macSafari:+ "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15",+ androidS928N:+ "Mozilla/5.0 (Linux; Android 15; SM-S928N Build/AP3A.240905.015) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Mobile Safari/537.36",+ androidA536N:+ "Mozilla/5.0 (Linux; Android 15; SM-A536N Build/AP3A.240905.015) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Mobile Safari/537.36",+ reactNative:+ "Mozilla/5.0 (iPhone; CPU iPhone OS 26_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) RybbitReactNative/0.1.1 8.0.14",+ reactNativeBumped:+ "Mozilla/5.0 (iPhone; CPU iPhone OS 26_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) RybbitReactNative/0.2.0 8.1.0",+ firefox: "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:153.0) Gecko/20100101 Firefox/153.0",+ firefoxNext: "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:154.0) Gecko/20100101 Firefox/154.0",+ // In-app browsers put hardware identifiers in the same slash-delimited slot a+ // version normally occupies, which an over-eager rule will happily destroy.+ fbIosPhone12:+ "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 [FBAN/FBIOS;FBDV/iPhone12,8;FBAV/440.0.0.32.108]",+ fbIosPhone14:+ "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 [FBAN/FBIOS;FBDV/iPhone14,8;FBAV/440.0.0.32.108]",+ fbIosPhone12Updated:+ "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 [FBAN/FBIOS;FBDV/iPhone12,8;FBAV/441.0.0.28.90]",+ fbAndroidJ320F:+ "Mozilla/5.0 (Linux; Android 9; SM-J320F) AppleWebKit/537.36 [FBAN/EMA;FBDV/SM-J320F;FBCA/armeabi-v7a:armeabi;FBAV/239.0.0.10.109]",+ fbAndroidG930F:+ "Mozilla/5.0 (Linux; Android 9; SM-G930F) AppleWebKit/537.36 [FBAN/EMA;FBDV/SM-G930F;FBCA/armeabi-v7a:armeabi;FBAV/239.0.0.10.109]",+ // Two different handsets whose *model names* contain a dotted number.+ nokia61Plus:+ "Mozilla/5.0 (Linux; Android 10; Nokia 6.1 Plus Build/QKQ1.190828.002; wv) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.7778.178 Mobile Safari/537.36",+ nokia83Plus:+ "Mozilla/5.0 (Linux; Android 10; Nokia 8.3 Plus Build/QKQ1.190828.002; wv) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.7778.178 Mobile Safari/537.36",+};++const same = (a: string, b: string) => expect(normalizeUserAgentForIdentity(a)).toBe(normalizeUserAgentForIdentity(b));+const differs = (a: string, b: string) =>+ expect(normalizeUserAgentForIdentity(a)).not.toBe(normalizeUserAgentForIdentity(b));++describe("normalizeUserAgentForIdentity", () => {+ describe("survives updates", () => {+ // The regression this exists for: op.gg's auto-updater flipped the whole+ // install base to 2.5.3 inside a day (the diagnosed boundary was 2.5.2 β+ // 2.5.3), re-minting every id. The captured pair below spans the same+ // three-token move β app, Chromium and Electron versions all at once.+ it("collapses an Electron app update (app, Chromium and Electron all bumped)", () => {+ same(UA.opggElectron251, UA.opggElectron253);+ });++ it("collapses a Chrome major bump", () => same(UA.chromeWin150, UA.chromeWin151));++ it("collapses an iOS point release, which moves both the OS and Safari tokens", () => {+ same(UA.safariIos1857, UA.safariIos266);+ });++ // Chrome on iOS does not do UA reduction, so every patch used to reset it.+ it("collapses a Chrome-on-iOS patch", () => same(UA.chromeIos, UA.chromeIosPatched));++ it("collapses a Firefox bump, including the rv: revision", () => same(UA.firefox, UA.firefoxNext));++ it("collapses a React Native app bump, including the bare trailing version", () => {+ same(UA.reactNative, UA.reactNativeBumped);+ });+ });++ describe("keeps distinct devices distinct", () => {+ it("separates browser families on the same OS", () => differs(UA.chromeWin151, UA.edgeWin151));+ it("separates Firefox from Chrome", () => differs(UA.chromeWin151, UA.firefox));+ it("separates operating systems", () => differs(UA.chromeWin151, UA.macSafari));+ it("separates iPhone from iPad", () => differs(UA.safariIos266, UA.safariIpad266));+ it("separates Safari from Chrome on the same iPhone", () => differs(UA.safariIos266, UA.chromeIos));+ it("separates a native app from the browser on the same OS", () => {+ differs(UA.reactNative, UA.safariIos266);+ });++ // Android model strings carry digits but never change under the user, so+ // they are entropy worth keeping.+ it("keeps Android device models apart", () => differs(UA.androidS928N, UA.androidA536N));+ });++ describe("keeps hardware identifiers, which never change under the user", () => {+ // Regression: an earlier rule elided any slash value containing a digit,+ // turning `FBDV/iPhone12,8` into `FBDV/#,8` and fusing every iPhone model+ // that shared a point release.+ it("keeps the iOS device model in a Facebook in-app user agent", () => {+ expect(normalizeUserAgentForIdentity(UA.fbIosPhone12)).toContain("FBDV/iPhone12,8");+ });++ it("separates two iPhone models behind the same in-app browser", () => {+ differs(UA.fbIosPhone12, UA.fbIosPhone14);+ });++ it("still collapses the in-app browser's own version bump", () => {+ same(UA.fbIosPhone12, UA.fbIosPhone12Updated);+ });++ it("keeps the Android model and CPU ABI in a Facebook in-app user agent", () => {+ const normalized = normalizeUserAgentForIdentity(UA.fbAndroidJ320F);+ expect(normalized).toContain("FBDV/SM-J320F");+ expect(normalized).toContain("FBCA/armeabi-v7a:armeabi");+ });++ it("separates two Android models behind the same in-app browser", () => {+ differs(UA.fbAndroidJ320F, UA.fbAndroidG930F);+ });++ // Regression: a two-group bare-version rule read the `6.1` in `Nokia 6.1+ // Plus` as a version and merged it with every other dotted Nokia.+ it("keeps a dotted marketing model name", () => {+ expect(normalizeUserAgentForIdentity(UA.nokia61Plus)).toContain("Nokia 6.1 Plus");+ });++ it("separates two handsets whose model names differ only in their digits", () => {+ differs(UA.nokia61Plus, UA.nokia83Plus);+ });+ });++ describe("mechanics", () => {+ it("elides every version token in a representative desktop UA", () => {+ expect(normalizeUserAgentForIdentity(UA.chromeWin151)).toBe(+ "Mozilla/# (Windows NT #; Win64; x64) AppleWebKit/# (KHTML, like Gecko) Chrome/# Safari/#"+ );+ });++ it("keeps the Android model while eliding the OS and build", () => {+ expect(normalizeUserAgentForIdentity(UA.androidS928N)).toBe(+ "Mozilla/# (Linux; Android #; SM-S928N Build/#) AppleWebKit/# (KHTML, like Gecko) Chrome/# Mobile Safari/#"+ );+ });++ it("is idempotent, so a normalized value re-normalizes to itself", () => {+ for (const ua of Object.values(UA)) {+ const once = normalizeUserAgentForIdentity(ua);+ expect(normalizeUserAgentForIdentity(once)).toBe(once);+ }+ });++ it("passes an empty user agent through untouched", () => {+ expect(normalizeUserAgentForIdentity("")).toBe("");+ });++ it("leaves a version-free user agent alone", () => {+ expect(normalizeUserAgentForIdentity("Mediapartners-Google")).toBe("Mediapartners-Google");+ });+ });+});diff --git a/server/src/services/userId/normalizeUserAgent.ts b/server/src/services/userId/normalizeUserAgent.tsnew file mode 100644index 000000000..4fe6c8829--- /dev/null+++ b/server/src/services/userId/normalizeUserAgent.ts@@ -0,0 +1,133 @@+/**+ * Strip version numbers out of a user agent so the anonymous fingerprint+ * survives a browser or app update.+ *+ * `generateUserId` hashes the raw user agent, so every byte of it is part of a+ * visitor's identity β including the version tokens that change every time+ * their browser or app updates. An update therefore mints a brand-new "user"+ * for the same person on the same machine.+ *+ * On the web that damage is invisible because vendors stagger rollouts: the+ * resets dribble in over weeks and read as ordinary new-visitor acquisition.+ * It becomes obvious when an update is *synchronised* β an Electron app whose+ * auto-updater flips the whole install base inside a day re-mints every+ * identity at once, so any reporting window spanning the release counts each+ * machine twice (measured on op.gg's desktop app, 2026-08-14: `user_id`+ * overlap across the release boundary fell to 1.6%, and identity survived only+ * for the machines that had *not* updated).+ *+ * The fix is to hash a version-free view of the user agent. What we remove is+ * exactly what an update changes:+ *+ * - numeric version tokens after a slash β `Chrome/151.0.0.0`,+ * `Firefox/153.0`, `Edg/143.0.0.0`, `CriOS/151.0.7922.112`,+ * `Electron/39.8.13`, `Version/26.6`+ * - alphanumeric build ids under a known key β `Mobile/15E148`,+ * `Build/UP1A.231005.007`+ * - Gecko's `rv:153.0`+ * - OS versions β `Windows NT 10.0`, `Android 15`, `CPU iPhone OS 26_6`,+ * `Mac OS X 10_15_7`, `CrOS x86_64 14541.0.0`+ *+ * What we deliberately keep is everything that identifies the *device* rather+ * than its patch level: product names (`Chrome`, `CriOS`, `Edg`,+ * `opgg-electron-app`), form factor (`iPhone`, `iPad`, `Mobile`, `Macintosh`),+ * architecture (`Win64; x64`, `Intel`), and Android device models+ * (`SM-S928N`), hardware identifiers that sit where a version usually does+ * (`FBDV/SM-J320F`, `FBCA/armeabi-v7a`), and two-part marketing model names+ * (`Nokia 6.1 Plus`) β all of which carry digits but never change under the+ * user.++ * It is a heuristic, and it errs toward *missing* a version rather than+ * eliding a device token: a miss leaves today's behaviour (identity resets on+ * that update), while an over-elision actively fuses two people who were+ * previously counted apart. Some exotic native-app agents still reset β+ * Instagram's trailing bare APK version code, for one β which is part of why a+ * persistent client id (`anonymous_id`) remains the durable fix.+ *+ * This trades splitting for merging, the same trade `bucketIpForIdentity`+ * already makes: visitors who share an IP and a device class collapse into one+ * user, where before one visitor exploded into several across time. Merging+ * costs a headline number; splitting corrupts sessions, retention and+ * acquisition alike.+ *+ * Identity only. Reporting keeps parsing the raw user agent, so the browser and+ * OS *versions* shown in the dashboard are unaffected.+ */++/**+ * A slash-delimited *numeric* version: `Chrome/151.0.0.0`, `Version/26.6`,+ * `AppleWebKit/605.1.15`, `FBAV/440.0.0.32.108`, `MyApp/v2.3.1`.+ *+ * Deliberately numeric-only. An earlier draft elided any slash value that+ * merely *contained* a digit, which silently ate hardware identifiers that sit+ * in the same position and never change under the user β Facebook's+ * `FBDV/SM-J320F` (the Android `Build.MODEL`) and `FBCA/armeabi-v7a` (the CPU+ * ABI). Worse, `FBDV/iPhone12,8` became `FBDV/#,8`, collapsing every iPhone+ * model onto its point release and merging genuinely different phones.+ * Preserving anything non-numeric costs a few missed version tokens; the+ * alternative cost was fusing distinct devices, which is the failure this+ * whole module exists to prevent.+ */+const SLASHED_VERSION = /\/v?[0-9]+(?:[._][0-9]+)*/g;++/**+ * Build identifiers, which are alphanumeric rather than numeric and so fall+ * outside `SLASHED_VERSION`, but do change on every OS update:+ * `Build/UP1A.231005.007`, `Mobile/15E148`. Matched by key, because only these+ * keys are unambiguous β a bare alphanumeric token elsewhere is far more likely+ * to be a model name.+ */+const SLASHED_BUILD = /\b(Build|Mobile)\/[0-9A-Za-z._-]+/g;++/** Gecko's `rv:153.0` revision token. */+const GECKO_REVISION = /\brv:[0-9][0-9._]*/g;++/**+ * A bare, space-delimited dotted version β the trailing `8.0.14` in+ * `RybbitReactNative/0.1.1 8.0.14`, or Instagram's `76.0.0.15.395`.+ *+ * Three numeric groups minimum. Two would also match `Nokia 6.1 Plus` and+ * `Nokia 8.3 Plus`, whose `6.1` and `8.3` are *model* names β eliding them+ * merges two different handsets. Marketing names stop at two components;+ * software versions in this position generally have three or more. Applied+ * last, once the slash and OS rules have claimed the versions they own.+ */+const BARE_VERSION = /(?<=^|[ (;])[0-9]+(?:\.[0-9]+){2,}(?=$|[ );])/g;++/**+ * OS version numbers, matched only where an OS name introduces them so that+ * device models keep their digits. `_` separators cover Apple's `10_15_7`+ * style; the trailing `x86_64`-aware form covers ChromeOS.+ */+const OS_VERSIONS: RegExp[] = [+ /\b(Windows NT) [0-9][0-9._]*/g,+ /\b(Windows Phone(?: OS)?) [0-9][0-9._]*/g,+ /\b(Android)[ /][0-9][0-9._]*/g,+ /\b(CPU(?: iPhone)? OS) [0-9][0-9._]*/g,+ /\b(Mac OS X) [0-9][0-9._]*/g,+ /\b(CrOS [^ )]+) [0-9][0-9._]*/g,+];++/** Placeholder standing in for every elided version. */+const ELIDED = "#";++/**+ * The identity-bearing view of a user agent: the same string with every version+ * number replaced by `#`.+ *+ * Pure and allocation-light β this runs once per ingested event.+ */+export function normalizeUserAgentForIdentity(userAgent: string): string {+ if (!userAgent) return userAgent;++ let normalized = userAgent+ .replace(SLASHED_VERSION, `/${ELIDED}`)+ .replace(SLASHED_BUILD, `$1/${ELIDED}`)+ .replace(GECKO_REVISION, `rv:${ELIDED}`);++ for (const pattern of OS_VERSIONS) {+ normalized = normalized.replace(pattern, `$1 ${ELIDED}`);+ }++ return normalized.replace(BARE_VERSION, ELIDED);+}diff --git a/server/src/services/userId/userIdService.test.ts b/server/src/services/userId/userIdService.test.tsindex 1017569a9..1324e6b35 100644--- a/server/src/services/userId/userIdService.test.ts+++ b/server/src/services/userId/userIdService.test.ts@@ -130,4 +130,56 @@ describe("userIdService", () => {expect(dayTwo).toBe(dayOne);});++ // A browser or app update changes the version tokens in the user agent. Those+ // are stripped before hashing, so the same machine keeps its identity instead+ // of being counted as a second visitor.+ it("keeps one identity across a browser update", async () => {+ const before = await userIdService.generateUserId(+ "198.51.100.10",+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36",+ 42,+ { saltUserIds: false }+ );+ const after = await userIdService.generateUserId(+ "198.51.100.10",+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36",+ 42,+ { saltUserIds: false }+ );++ expect(after).toBe(before);+ });++ it("still separates different browsers on one IP", async () => {+ const chrome = await userIdService.generateUserId(+ "198.51.100.10",+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36",+ 42,+ { saltUserIds: false }+ );+ const firefox = await userIdService.generateUserId(+ "198.51.100.10",+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:153.0) Gecko/20100101 Firefox/153.0",+ 42,+ { saltUserIds: false }+ );++ expect(firefox).not.toBe(chrome);+ });++ // Sticky re-attachment keys its candidate pool on the user agent it is given,+ // and it keeps receiving the raw string. Handing it the normalized one would+ // pool every version variant together, which cuts both ways: a pool that was+ // empty can become a single candidate (a new, unreviewed re-attachment) just+ // as easily as a single candidate can become several (an abstention). Sticky+ // is a separate merge decision with its own evidence bar, so it stays on the+ // exact string it was designed and measured against.+ it("hands sticky re-attachment the raw user agent, not the normalized one", async () => {+ const userAgent =+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36";+ await userIdService.generateUserId("198.51.100.10", userAgent, 42, { saltUserIds: false });++ expect(mocks.resolveStickyUserId).toHaveBeenCalledWith(expect.objectContaining({ userAgent }));+ });});diff --git a/server/src/services/userId/userIdService.ts b/server/src/services/userId/userIdService.tsindex d55b78169..f8c71b582 100644--- a/server/src/services/userId/userIdService.ts+++ b/server/src/services/userId/userIdService.ts@@ -4,6 +4,7 @@ import { SECRET } from "../../lib/const.js";import { siteConfig } from "../../lib/siteConfig.js";import { isDatacenterAsn } from "../tracker/botBlocking/datacenterAsns.js";import { bucketIpForIdentity } from "./identityIpBucket.js";+import { normalizeUserAgentForIdentity } from "./normalizeUserAgent.js";import { resolveStickyUserId } from "./stickyUserId.js";export interface UserIdOptions {@@ -80,6 +81,12 @@ class UserIdService {* Generate a user ID based on IP and user agent* If the site has salting enabled, also includes a daily rotating salt*+ * The user agent is version-stripped before hashing, so a browser or app+ * update doesn't mint a new identity for the same machine β see+ * `normalizeUserAgentForIdentity`. The raw string is still what reporting+ * parses, and still what sticky re-attachment matches on, so only the+ * fingerprint changes.+ ** @param ip User's IP address* @param userAgent User's user agent string* @param siteId The site ID to check for salting configuration@@ -94,12 +101,17 @@ class UserIdService {// between requests; hash a coarse bucket so one visitor stays one user.const identityIp = bucketIpForIdentity(ip, isDatacenterEgress);+ // Version tokens change under the user on every browser or app update, so+ // they are stripped before hashing β otherwise an update splits one visitor+ // into two, all at once when the update is a synchronised app rollout.+ const identityUserAgent = normalizeUserAgentForIdentity(userAgent);+// The event's own day, fixed before anything is hashed against it.const saltDay = utcDayOf(options.receivedAt ?? new Date());const salted = await this.isSalted(siteId, options);const rawUserId = crypto.createHash("sha256")- .update(identityIp + userAgent + (salted ? this.getDailySalt(saltDay) : ""))+ .update(identityIp + identityUserAgent + (salted ? this.getDailySalt(saltDay) : "")).digest("hex").substring(0, 12);