πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
sticky resolve (#1083)
Goldflag0e9d69bc3a92
diff --git a/server/package-lock.json b/server/package-lock.jsonindex beb73370d..0cc330aef 100644--- a/server/package-lock.json+++ b/server/package-lock.json@@ -54,6 +54,7 @@},"devDependencies": {"@electric-sql/pglite": "^0.5.4",+ "@types/ioredis-mock": "^8.2.7","@types/jsdom": "^21.1.7","@types/luxon": "3.7.1","@types/node": "^20.14.8",@@ -64,6 +65,7 @@"@types/sqlstring": "2.3.2","drizzle-kit": "0.31.9","esbuild": "^0.25.5",+ "ioredis-mock": "^8.13.1","jsdom": "^26.1.0","knip": "^5.60.2","pino-pretty": "^13.1.1",@@ -2554,6 +2556,13 @@"hono": "^4"}},+ "node_modules/@ioredis/as-callback": {+ "version": "3.0.0",+ "resolved": "https://registry.npmjs.org/@ioredis/as-callback/-/as-callback-3.0.0.tgz",+ "integrity": "sha512-Kqv1rZ3WbgOrS+hgzJ5xG5WQuhvzzSTRYvNeyPMLOAM78MHSnuKI20JeJGbpuAt//LCuP0vsexZcorqW7kWhJg==",+ "dev": true,+ "license": "MIT"+ },"node_modules/@ioredis/commands": {"version": "1.4.0","resolved": "https://registry.npmjs.org/@ioredis/commands/-/commands-1.4.0.tgz",@@ -4657,6 +4666,16 @@"dev": true,"license": "MIT"},+ "node_modules/@types/ioredis-mock": {+ "version": "8.2.7",+ "resolved": "https://registry.npmjs.org/@types/ioredis-mock/-/ioredis-mock-8.2.7.tgz",+ "integrity": "sha512-YsGiaOIYBKeVvu/7GYziAD8qX3LJem5LK00d5PKykzsQJMLysAqXA61AkNuYWCekYl64tbMTqVOMF4SYoCPbQg==",+ "dev": true,+ "license": "MIT",+ "peerDependencies": {+ "ioredis": ">=5"+ }+ },"node_modules/@types/jsdom": {"version": "21.1.7","resolved": "https://registry.npmjs.org/@types/jsdom/-/jsdom-21.1.7.tgz",@@ -7014,6 +7033,28 @@}}},+ "node_modules/fengari": {+ "version": "0.1.5",+ "resolved": "https://registry.npmjs.org/fengari/-/fengari-0.1.5.tgz",+ "integrity": "sha512-0DS4Nn4rV8qyFlQCpKK8brT61EUtswynrpfFTcgLErcilBIBskSMQ86fO2WVuybr14ywyKdRjv91FiRZwnEuvQ==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "readline-sync": "^1.4.10",+ "sprintf-js": "^1.1.3",+ "tmp": "^0.2.5"+ }+ },+ "node_modules/fengari-interop": {+ "version": "0.1.4",+ "resolved": "https://registry.npmjs.org/fengari-interop/-/fengari-interop-0.1.4.tgz",+ "integrity": "sha512-4/CW/3PJUo3ebD4ACgE1g/3NGEYSq7OQAyETyypsAl/WeySDBbxExikkayNkZzbpgyC9GyJp8v1DU2VOXxNq7Q==",+ "dev": true,+ "license": "MIT",+ "peerDependencies": {+ "fengari": "^0.1.0"+ }+ },"node_modules/fill-range": {"version": "7.1.1","resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",@@ -7556,6 +7597,27 @@"url": "https://opencollective.com/ioredis"}},+ "node_modules/ioredis-mock": {+ "version": "8.13.1",+ "resolved": "https://registry.npmjs.org/ioredis-mock/-/ioredis-mock-8.13.1.tgz",+ "integrity": "sha512-Wsi50AU+cMiI32nAgfwpUaJVBtb4iQdVsOHl9M6R3tePCO/8vGsToCVIG82XWAxN4Se55TZoOzVseu+QngFLyw==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@ioredis/as-callback": "^3.0.0",+ "@ioredis/commands": "^1.4.0",+ "fengari": "^0.1.4",+ "fengari-interop": "^0.1.3",+ "semver": "^7.7.2"+ },+ "engines": {+ "node": ">=12.22"+ },+ "peerDependencies": {+ "@types/ioredis-mock": "^8",+ "ioredis": "^5"+ }+ },"node_modules/ip-address": {"version": "10.2.0","resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",@@ -9358,6 +9420,16 @@"integrity": "sha512-bCK/2Z4zLidyB4ReuIsvALH6w31YfAQDmXMqMx6FyfHqvBxtjC0eRumeSu4Bs3XtXwpyIywtSTrVT99BxY1f9w==","license": "MIT"},+ "node_modules/readline-sync": {+ "version": "1.4.10",+ "resolved": "https://registry.npmjs.org/readline-sync/-/readline-sync-1.4.10.tgz",+ "integrity": "sha512-gNva8/6UAe8QYepIQH/jQ2qn91Qj0B9sYjMBBs3QOB8F2CXcKgLxQaJRP76sWVRQt+QU+8fAkCbCvjjMFu7Ycw==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">= 0.8.0"+ }+ },"node_modules/real-require": {"version": "0.2.0","resolved": "https://registry.npmjs.org/real-require/-/real-require-0.2.0.tgz",@@ -10051,6 +10123,13 @@"node": ">= 10.x"}},+ "node_modules/sprintf-js": {+ "version": "1.1.3",+ "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.1.3.tgz",+ "integrity": "sha512-Oo+0REFV59/rz3gfJNKQiBlwfHaSESl1pcGyABQsnnIfWOFt6JNj5gCog2U6MLZ//IGYD+nA8nI+mTShREReaA==",+ "dev": true,+ "license": "BSD-3-Clause"+ },"node_modules/sqlstring": {"version": "2.3.3","resolved": "https://registry.npmjs.org/sqlstring/-/sqlstring-2.3.3.tgz",@@ -10350,6 +10429,16 @@"integrity": "sha512-Je6p7pkk+KMzMv2XXKmAE3McmolOQFdxkKw0R8EYNr7sELW46JqnNeTX8ybPiQgvg1ymCoF8LXs5fzFaZvJPTA==","license": "MIT"},+ "node_modules/tmp": {+ "version": "0.2.7",+ "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.2.7.tgz",+ "integrity": "sha512-e0votIpp4Uo2AJYSzVHV6xCcawuiez3DzqDAbrTc3YxBkplN6e+dM13ZeIcZnDg/QpSuU2zfZ3rzwY8ukEnaXw==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=14.14"+ }+ },"node_modules/to-regex-range": {"version": "5.0.1","resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",diff --git a/server/package.json b/server/package.jsonindex 91dbabb3c..481f5886a 100644--- a/server/package.json+++ b/server/package.json@@ -75,6 +75,7 @@},"devDependencies": {"@electric-sql/pglite": "^0.5.4",+ "@types/ioredis-mock": "^8.2.7","@types/jsdom": "^21.1.7","@types/luxon": "3.7.1","@types/node": "^20.14.8",@@ -85,6 +86,7 @@"@types/sqlstring": "2.3.2","drizzle-kit": "0.31.9","esbuild": "^0.25.5",+ "ioredis-mock": "^8.13.1","jsdom": "^26.1.0","knip": "^5.60.2","pino-pretty": "^13.1.1",diff --git a/server/src/db/redis/redis.ts b/server/src/db/redis/redis.tsindex 9e1fa50d7..0f59fb8e9 100644--- a/server/src/db/redis/redis.ts+++ b/server/src/db/redis/redis.ts@@ -1,5 +1,6 @@import { Redis } from "ioredis";import { createServiceLogger } from "../../lib/logger/logger.js";+import { STICKY_RESOLVE_LUA } from "./stickyResolveLua.js";const logger = createServiceLogger("redis");@@ -80,6 +81,81 @@ export function sessionGetOrCreate(key: string, candidateId: string, ttlMs: numbreturn (sessionRedis as SessionRedis).sessionGetOrCreate(key, candidateId, ttlMs);}+// Dedicated connection for sticky identity re-attachment, isolated for the same+// reason as `sessionRedis`: a slow call on a shared connection would head-of-line+// block session resolution for unrelated requests.+export const identityRedis = createRedisClient("identity");++// Sticky identity re-attachment: when a visitor behind a rotating proxy egress+// gets a brand-new fingerprint hash mid-visit, re-attach them to their previous+// identity instead of minting a phantom user β but only when the evidence is+// unambiguous (exactly one recently-active candidate under the same user agent).+//+// State per site:+// seen:<userId> flag: this fingerprint is a known identity (sliding TTL)+// cand (ZSET) identities recently seen through *datacenter egress* under+// one (site, UA[, salt day]), scored by last-seen ms β only+// eligible requests register, so a residential visitor can+// never be the lone candidate a datacenter arrival merges into+// alias (chain) durable re-attachment decision: raw fingerprint -> canonical;+// resolution follows chains to the terminal id and compresses+//+// Flow: alias hit -> follow it; known fingerprint -> keep it; new fingerprint ->+// attach iff eligible (datacenter egress) and exactly one candidate, else abstain+// and register as a new identity. Abstention means the failure mode stays "split"+// (status quo), never "merge". Runs as one Lua call so decisions are atomic+// across workers. Keys for the seen/alias touches of *other* identities are+// composed inside the script from prefix ARGVs β fine on single-node Redis, not+// cluster-safe. Script body lives in stickyResolveLua.ts so the behavioral tests+// exercise the identical Lua.+identityRedis.defineCommand("stickyResolve", {+ numberOfKeys: 3,+ lua: STICKY_RESOLVE_LUA,+});++export type StickyResolveOutcome = "alias" | "known" | "attach" | "abstain_none" | "abstain_multi" | "new";++export interface StickyResolveInput {+ seenKey: string;+ candidatesKey: string;+ aliasKey: string;+ rawUserId: string;+ nowMs: number;+ candidateWindowMs: number;+ seenTtlMs: number;+ aliasTtlMs: number;+ /** Whether this request may attempt re-attachment (datacenter-egress IPs only). */+ eligible: boolean;+ seenKeyPrefix: string;+ aliasKeyPrefix: string;+ maxCandidates: number;+}++interface IdentityRedis extends Redis {+ stickyResolve(...args: (string | number)[]): Promise<[string, StickyResolveOutcome]>;+}++/**+ * Resolve the canonical user id for a raw fingerprint hash, re-attaching rotated+ * proxy identities when unambiguous. Atomic across all workers; one round-trip.+ */+export function stickyResolve(input: StickyResolveInput): Promise<[string, StickyResolveOutcome]> {+ return (identityRedis as IdentityRedis).stickyResolve(+ input.seenKey,+ input.candidatesKey,+ input.aliasKey,+ input.rawUserId,+ input.nowMs,+ input.candidateWindowMs,+ input.seenTtlMs,+ input.aliasTtlMs,+ input.eligible ? "1" : "0",+ input.seenKeyPrefix,+ input.aliasKeyPrefix,+ input.maxCandidates+ );+}+// Rolling-window counters for the bot anomaly scorer. Each counter is a sorted// set: member -> observation, score -> time (ms). For event-rate counters the// member is a unique per-event token (so cardinality == event count); fordiff --git a/server/src/db/redis/stickyResolve.integration.test.ts b/server/src/db/redis/stickyResolve.integration.test.tsnew file mode 100644index 000000000..b5b74fa8a--- /dev/null+++ b/server/src/db/redis/stickyResolve.integration.test.ts@@ -0,0 +1,175 @@+import { beforeEach, describe, expect, it } from "vitest";+import RedisMock from "ioredis-mock";+import { STICKY_RESOLVE_LUA } from "./stickyResolveLua.js";++// Behavioral tests for the stickyResolve Lua script, executed for real by+// ioredis-mock's embedded Lua runtime. This is the decision core of sticky+// identity re-attachment β TS-level mocks can't cover it.++const WINDOW_MS = 5 * 60 * 1000;+const SEEN_TTL_MS = 30 * 60 * 1000;+const ALIAS_TTL_MS = 24 * 60 * 60 * 1000;+const MAX_CANDIDATES = 32;++const SEEN_PREFIX = "sticky:seen:1:";+const ALIAS_PREFIX = "sticky:alias:1:";+const CAND_KEY = "sticky:cand:1::ua1";++interface StickyMockRedis {+ stickyResolve(...args: (string | number)[]): Promise<[string, string]>;+ zadd(key: string, score: number, member: string): Promise<unknown>;+ zrange(key: string, start: number, stop: number): Promise<string[]>;+ get(key: string): Promise<string | null>;+ set(key: string, value: string): Promise<unknown>;+ exists(key: string): Promise<number>;+ flushall(): Promise<unknown>;+}++let redis: StickyMockRedis;++function resolve(rawId: string, opts: { nowMs?: number; eligible?: boolean; uaKey?: string } = {}) {+ const candKey = opts.uaKey ?? CAND_KEY;+ return redis.stickyResolve(+ `${SEEN_PREFIX}${rawId}`,+ candKey,+ `${ALIAS_PREFIX}${rawId}`,+ rawId,+ opts.nowMs ?? 1_000_000,+ WINDOW_MS,+ SEEN_TTL_MS,+ ALIAS_TTL_MS,+ opts.eligible === false ? "0" : "1",+ SEEN_PREFIX,+ ALIAS_PREFIX,+ MAX_CANDIDATES+ );+}++describe("stickyResolve Lua script", () => {+ beforeEach(async () => {+ const client = new RedisMock();+ client.defineCommand("stickyResolve", { numberOfKeys: 3, lua: STICKY_RESOLVE_LUA });+ redis = client as unknown as StickyMockRedis;+ await redis.flushall();+ });++ it("registers a first-time datacenter visitor as identity and candidate", async () => {+ const [userId, outcome] = await resolve("userA");++ expect(userId).toBe("userA");+ expect(outcome).toBe("abstain_none");+ expect(await redis.exists(`${SEEN_PREFIX}userA`)).toBe(1);+ expect(await redis.zrange(CAND_KEY, 0, -1)).toEqual(["userA"]);+ });++ it("registers a residential visitor as identity but never as a rotation candidate", async () => {+ const [userId, outcome] = await resolve("userA", { eligible: false });++ expect(userId).toBe("userA");+ expect(outcome).toBe("new");+ expect(await redis.exists(`${SEEN_PREFIX}userA`)).toBe(1);+ expect(await redis.zrange(CAND_KEY, 0, -1)).toEqual([]);+ });++ it("keeps a known fingerprint unchanged", async () => {+ await resolve("userA");+ const [userId, outcome] = await resolve("userA", { nowMs: 1_010_000 });++ expect(userId).toBe("userA");+ expect(outcome).toBe("known");+ });++ it("attaches a new datacenter fingerprint when exactly one candidate is active", async () => {+ await resolve("userA");+ const [userId, outcome] = await resolve("rotatedB", { nowMs: 1_010_000 });++ expect(userId).toBe("userA");+ expect(outcome).toBe("attach");+ expect(await redis.get(`${ALIAS_PREFIX}rotatedB`)).toBe("userA");+ // The rotated fingerprint never becomes an identity of its own.+ expect(await redis.exists(`${SEEN_PREFIX}rotatedB`)).toBe(0);+ expect(await redis.zrange(CAND_KEY, 0, -1)).toEqual(["userA"]);+ });++ it("never attaches a datacenter arrival to a residential-only visitor", async () => {+ // The P1 review case: an unrelated home-ISP visitor with the same common UA+ // browsed minutes earlier. They must not be merge bait.+ await resolve("residentialA", { eligible: false });+ const [userId, outcome] = await resolve("rotatedB", { nowMs: 1_010_000 });++ expect(userId).toBe("rotatedB");+ expect(outcome).toBe("abstain_none");+ expect(await redis.get(`${ALIAS_PREFIX}rotatedB`)).toBeNull();+ });++ it("follows the alias on subsequent events from the rotated fingerprint", async () => {+ await resolve("userA");+ await resolve("rotatedB", { nowMs: 1_010_000 });+ const [userId, outcome] = await resolve("rotatedB", { nowMs: 1_020_000 });++ expect(userId).toBe("userA");+ expect(outcome).toBe("alias");+ });++ it("abstains with several candidates (fleet UA behind one proxy)", async () => {+ await redis.zadd(CAND_KEY, 1_000_000, "userA");+ await redis.zadd(CAND_KEY, 1_001_000, "userB");++ const [userId, outcome] = await resolve("rotatedC", { nowMs: 1_010_000 });++ expect(userId).toBe("rotatedC");+ expect(outcome).toBe("abstain_multi");+ expect(await redis.get(`${ALIAS_PREFIX}rotatedC`)).toBeNull();+ });++ it("never attaches for residential egress even with one candidate present", async () => {+ await resolve("userA");+ const [userId, outcome] = await resolve("freshB", { nowMs: 1_010_000, eligible: false });++ expect(userId).toBe("freshB");+ expect(outcome).toBe("new");+ });++ it("ignores candidates outside the window", async () => {+ await resolve("userA");+ const [userId, outcome] = await resolve("rotatedB", { nowMs: 1_000_000 + WINDOW_MS + 1 });++ expect(userId).toBe("rotatedB");+ expect(outcome).toBe("abstain_none");+ });++ it("does not attach across user agents", async () => {+ await resolve("userA");+ const [userId, outcome] = await resolve("rotatedB", { nowMs: 1_010_000, uaKey: "sticky:cand:1::ua2" });++ expect(userId).toBe("rotatedB");+ expect(outcome).toBe("abstain_none");+ });++ it("resolves alias chains to the terminal id and compresses the path", async () => {+ // X -> A -> B -> C: A and B were each re-attached after their seen flags+ // lapsed. X's events must land on C, and X's alias must be rewritten to C+ // so the chain doesn't have to be walked again.+ await redis.set(`${ALIAS_PREFIX}userX`, "userA");+ await redis.set(`${ALIAS_PREFIX}userA`, "userB");+ await redis.set(`${ALIAS_PREFIX}userB`, "userC");++ const [userId, outcome] = await resolve("userX", { nowMs: 1_020_000 });++ expect(userId).toBe("userC");+ expect(outcome).toBe("alias");+ expect(await redis.get(`${ALIAS_PREFIX}userX`)).toBe("userC");+ });++ it("caps the candidate set without ever enabling a wrong single-candidate match", async () => {+ for (let i = 0; i < 40; i++) {+ await redis.zadd(CAND_KEY, 1_000_000 + i, `user${i}`);+ }++ const [, outcome] = await resolve("rotatedZ", { nowMs: 1_010_000 });+ expect(outcome).toBe("abstain_multi");++ const members = await redis.zrange(CAND_KEY, 0, -1);+ expect(members.length).toBeLessThanOrEqual(MAX_CANDIDATES);+ });+});diff --git a/server/src/db/redis/stickyResolveLua.ts b/server/src/db/redis/stickyResolveLua.tsnew file mode 100644index 000000000..9c0882f55--- /dev/null+++ b/server/src/db/redis/stickyResolveLua.ts@@ -0,0 +1,80 @@+// Lua body for the stickyResolve command. Kept in its own side-effect-free+// module so the behavioral tests can run the exact same script through a real+// Lua runtime (ioredis-mock) without importing the connection-creating redis.ts.+//+// KEYS: [1] seen:<rawId> [2] candidate ZSET [3] alias:<rawId>+// ARGV: rawId, nowMs, candidateWindowMs, seenTtlMs, aliasTtlMs, eligible(0/1),+// seenKeyPrefix, aliasKeyPrefix, maxCandidates+//+// Only requests arriving through eligible (datacenter) egress register their+// identity as a rotation candidate: a residential visitor must never become the+// "exactly one candidate" that a later datacenter arrival gets merged into.+// Seen flags are set for everyone regardless.+//+// Alias resolution follows the chain to its terminal id (bounded) and writes the+// terminal back (path compression), so a canonical that was itself re-attached+// never forks a visitor across intermediate ids.+export const STICKY_RESOLVE_LUA = `+ local rawId = ARGV[1]+ local now = tonumber(ARGV[2])+ local windowMs = tonumber(ARGV[3])+ local seenTtlMs = ARGV[4]+ local aliasTtlMs = ARGV[5]+ local eligible = ARGV[6] == '1'+ local seenPrefix = ARGV[7]+ local aliasPrefix = ARGV[8]+ local maxCandidates = tonumber(ARGV[9])++ local function touch(id)+ redis.call('SET', seenPrefix .. id, '1', 'PX', seenTtlMs)+ if eligible then+ redis.call('ZADD', KEYS[2], now, id)+ redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', '(' .. (now - windowMs))+ redis.call('ZREMRANGEBYRANK', KEYS[2], 0, -maxCandidates - 1)+ redis.call('PEXPIRE', KEYS[2], windowMs)+ end+ end++ local canonical = redis.call('GET', KEYS[3])+ if canonical then+ for _ = 1, 5 do+ local hop = redis.call('GET', aliasPrefix .. canonical)+ if not hop then break end+ canonical = hop+ end+ redis.call('SET', KEYS[3], canonical, 'PX', aliasTtlMs)+ touch(canonical)+ return {canonical, 'alias'}+ end++ if redis.call('EXISTS', KEYS[1]) == 1 then+ touch(rawId)+ return {rawId, 'known'}+ end++ if eligible then+ redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', '(' .. (now - windowMs))+ local candidates = redis.call('ZRANGE', KEYS[2], 0, -1)+ local matched = nil+ local count = 0+ for _, id in ipairs(candidates) do+ if id ~= rawId then+ count = count + 1+ matched = id+ end+ end+ if count == 1 then+ redis.call('SET', KEYS[3], matched, 'PX', aliasTtlMs)+ touch(matched)+ return {matched, 'attach'}+ end+ touch(rawId)+ if count == 0 then+ return {rawId, 'abstain_none'}+ end+ return {rawId, 'abstain_multi'}+ end++ touch(rawId)+ return {rawId, 'new'}+`;diff --git a/server/src/services/userId/stickyUserId.test.ts b/server/src/services/userId/stickyUserId.test.tsnew file mode 100644index 000000000..312a49d07--- /dev/null+++ b/server/src/services/userId/stickyUserId.test.ts@@ -0,0 +1,110 @@+import { beforeEach, describe, expect, it, vi } from "vitest";++const mocks = vi.hoisted(() => ({+ stickyResolve: vi.fn(),+ redisStatus: { value: "ready" },+}));++vi.mock("../../db/redis/redis.js", () => ({+ identityRedis: {+ get status() {+ return mocks.redisStatus.value;+ },+ },+ stickyResolve: (...args: unknown[]) => mocks.stickyResolve(...args),+}));++import { resolveStickyUserId, setStickyIdentityEnabledForTests } from "./stickyUserId.js";++const baseInput = {+ siteId: 123,+ rawUserId: "abc123def456",+ ipAddress: "203.0.113.10",+ userAgent: "Mozilla/5.0 Chrome/120 Safari/537.36",+ saltScope: "",+ nowMs: 1_000_000,+ isDatacenterEgress: () => true,+};++describe("resolveStickyUserId", () => {+ beforeEach(() => {+ setStickyIdentityEnabledForTests(true);+ mocks.redisStatus.value = "ready";+ mocks.stickyResolve.mockReset();+ mocks.stickyResolve.mockResolvedValue(["abc123def456", "known"]);+ });++ it("returns the resolved canonical id from Redis", async () => {+ mocks.stickyResolve.mockResolvedValue(["canonical9999", "attach"]);++ const userId = await resolveStickyUserId(baseInput);++ expect(userId).toBe("canonical9999");+ expect(mocks.stickyResolve).toHaveBeenCalledTimes(1);+ });++ it("builds keys scoped by site, salt partition, and UA hash", async () => {+ await resolveStickyUserId({ ...baseInput, saltScope: "2026-07-19" });++ const call = mocks.stickyResolve.mock.calls[0][0];+ expect(call.seenKey).toBe("sticky:seen:123:abc123def456");+ expect(call.aliasKey).toBe("sticky:alias:123:abc123def456");+ expect(call.seenKeyPrefix).toBe("sticky:seen:123:");+ expect(call.aliasKeyPrefix).toBe("sticky:alias:123:");+ expect(call.candidatesKey).toMatch(/^sticky:cand:123:2026-07-19:[0-9a-f]{16}$/);+ expect(call.rawUserId).toBe("abc123def456");+ expect(call.nowMs).toBe(1_000_000);+ });++ it("uses different candidate pools for different user agents", async () => {+ await resolveStickyUserId(baseInput);+ await resolveStickyUserId({ ...baseInput, userAgent: "Mozilla/5.0 Firefox/128" });++ const [first, second] = mocks.stickyResolve.mock.calls.map(call => call[0].candidatesKey);+ expect(first).not.toBe(second);+ });++ it("marks residential egress ineligible for re-attachment", async () => {+ await resolveStickyUserId({ ...baseInput, isDatacenterEgress: () => false });++ expect(mocks.stickyResolve.mock.calls[0][0].eligible).toBe(false);+ });++ it("marks datacenter egress eligible", async () => {+ await resolveStickyUserId(baseInput);++ expect(mocks.stickyResolve.mock.calls[0][0].eligible).toBe(true);+ });++ it("skips Redis entirely when the connection is not ready", async () => {+ mocks.redisStatus.value = "reconnecting";++ const userId = await resolveStickyUserId(baseInput);++ expect(userId).toBe(baseInput.rawUserId);+ expect(mocks.stickyResolve).not.toHaveBeenCalled();+ });++ it("skips when ip or user agent is missing", async () => {+ expect(await resolveStickyUserId({ ...baseInput, ipAddress: "" })).toBe(baseInput.rawUserId);+ expect(await resolveStickyUserId({ ...baseInput, userAgent: "" })).toBe(baseInput.rawUserId);+ expect(mocks.stickyResolve).not.toHaveBeenCalled();+ });++ it("falls back to the raw fingerprint when Redis fails, without throwing", async () => {+ mocks.stickyResolve.mockRejectedValue(new Error("redis down"));++ const userId = await resolveStickyUserId(baseInput);++ expect(userId).toBe(baseInput.rawUserId);+ });++ it("does nothing when disabled", async () => {+ setStickyIdentityEnabledForTests(false);++ const userId = await resolveStickyUserId(baseInput);++ expect(userId).toBe(baseInput.rawUserId);+ expect(mocks.stickyResolve).not.toHaveBeenCalled();+ });+});diff --git a/server/src/services/userId/stickyUserId.ts b/server/src/services/userId/stickyUserId.tsnew file mode 100644index 000000000..cb52832a9--- /dev/null+++ b/server/src/services/userId/stickyUserId.ts@@ -0,0 +1,104 @@+import crypto from "crypto";+import { lookupAsn } from "../../db/geolocation/asn.js";+import { identityRedis, stickyResolve } from "../../db/redis/redis.js";+import { createServiceLogger } from "../../lib/logger/logger.js";+import { isDatacenterAsn } from "../tracker/botBlocking/datacenterAsns.js";++const logger = createServiceLogger("sticky-identity");++// How far back a previous identity counts as a re-attachment candidate. Kept+// well under the 30-minute seen TTL: observed egress rotations happen+// mid-navigation (seconds apart), and a wide window only adds merge risk.+const CANDIDATE_WINDOW_MS = 5 * 60 * 1000;+// How long a fingerprint stays "known" without activity. Matches the session+// TTL so an identity outlives its session by exactly nothing.+const SEEN_TTL_MS = 30 * 60 * 1000;+// How long a re-attachment decision is remembered. Sliding, refreshed on use.+const ALIAS_TTL_MS = 24 * 60 * 60 * 1000;+// Cap on candidate-set size. We only care whether the count is 0 / 1 / many,+// so a small cap bounds memory without ever changing a decision.+const MAX_CANDIDATES = 32;++let stickyIdentityEnabled = process.env.DISABLE_STICKY_IDENTITY !== "true";++export interface StickyIdentityInput {+ siteId: number;+ /** The fingerprint hash generateUserId computed (bucketed IP + UA [+ salt]). */+ rawUserId: string;+ /** The exact client IP β used only for the datacenter-egress eligibility gate. */+ ipAddress: string;+ userAgent: string;+ /**+ * Candidate-pool partition for salted sites (the UTC date the salt was built+ * from). Prevents re-attachment across a salt rotation, which would defeat+ * the salt's cross-day unlinkability. Empty string for unsalted sites.+ */+ saltScope: string;+ nowMs?: number;+ /** Injectable for tests so eligibility can be exercised without the MaxMind DB. */+ isDatacenterEgress?: (ip: string) => boolean;+}++/**+ * Resolve the canonical anonymous user id for a fingerprint hash.+ *+ * Rotating datacenter egress (corporate proxies, WARP, Private Relay) can hand a+ * visitor a new IP outside their /24 bucket mid-visit, minting a phantom user.+ * When a never-seen fingerprint arrives from datacenter egress and exactly one+ * identity with the same user agent was active on this site β through datacenter+ * egress itself β in the last few minutes, re-attach to it; with zero or several+ * candidates, abstain β the failure mode stays "split" (today's behavior),+ * never "merge". Residential visitors are never rotation candidates, so an+ * unrelated home-ISP visitor sharing a common UA can't be merged into.+ *+ * Enhancement layer only: if Redis is unavailable the raw fingerprint is+ * returned immediately and ingestion is never delayed or broken.+ */+export async function resolveStickyUserId(input: StickyIdentityInput): Promise<string> {+ if (!stickyIdentityEnabled || !input.ipAddress || !input.userAgent) {+ return input.rawUserId;+ }+ // Unlike sessions there is no in-process fallback: sticky state is only+ // meaningful when shared across workers, so without Redis we just skip.+ if (identityRedis.status !== "ready") {+ return input.rawUserId;+ }++ const isDatacenterEgress = input.isDatacenterEgress ?? (ip => isDatacenterAsn(lookupAsn(ip)?.asn));+ const uaHash = crypto.createHash("sha256").update(input.userAgent).digest("hex").substring(0, 16);+ const seenKeyPrefix = `sticky:seen:${input.siteId}:`;+ const aliasKeyPrefix = `sticky:alias:${input.siteId}:`;++ try {+ const [userId, outcome] = await stickyResolve({+ seenKey: `${seenKeyPrefix}${input.rawUserId}`,+ candidatesKey: `sticky:cand:${input.siteId}:${input.saltScope}:${uaHash}`,+ aliasKey: `${aliasKeyPrefix}${input.rawUserId}`,+ rawUserId: input.rawUserId,+ nowMs: input.nowMs ?? Date.now(),+ candidateWindowMs: CANDIDATE_WINDOW_MS,+ seenTtlMs: SEEN_TTL_MS,+ aliasTtlMs: ALIAS_TTL_MS,+ eligible: isDatacenterEgress(input.ipAddress),+ seenKeyPrefix,+ aliasKeyPrefix,+ maxCandidates: MAX_CANDIDATES,+ });++ if (outcome === "attach") {+ logger.info(+ { siteId: input.siteId, rawUserId: input.rawUserId, canonicalUserId: userId },+ "Re-attached rotated egress fingerprint to existing identity"+ );+ }+ return userId;+ } catch (error) {+ logger.error({ err: error }, "Sticky identity resolution failed; using raw fingerprint");+ return input.rawUserId;+ }+}++/** Force sticky resolution on/off in tests regardless of env. */+export function setStickyIdentityEnabledForTests(enabled: boolean) {+ stickyIdentityEnabled = enabled;+}diff --git a/server/src/services/userId/userIdService.ts b/server/src/services/userId/userIdService.tsindex 169db8dfc..4d42bb07b 100644--- a/server/src/services/userId/userIdService.ts+++ b/server/src/services/userId/userIdService.ts@@ -2,6 +2,7 @@ import crypto from "crypto";import { SECRET } from "../../lib/const.js";import { siteConfig } from "../../lib/siteConfig.js";import { bucketIpForIdentity } from "./identityIpBucket.js";+import { resolveStickyUserId } from "./stickyUserId.js";class UserIdService {private cachedSalt: string | null = null;@@ -55,21 +56,23 @@ class UserIdService {// Only apply salt if the site has salting enabledconst config = await siteConfig.getConfig(siteId);- if (config && config.saltUserIds) {- const dailySalt = this.getDailySalt(); // Get the salt for the current day- return crypto- .createHash("sha256")- .update(identityIp + userAgent + dailySalt)- .digest("hex")- .substring(0, 12);- }-- // Otherwise, just hash IP and user agent- return crypto+ const salted = !!config?.saltUserIds;+ const rawUserId = crypto.createHash("sha256")- .update(identityIp + userAgent)+ .update(identityIp + userAgent + (salted ? this.getDailySalt() : "")).digest("hex").substring(0, 12);++ // Rotation can still cross bucket boundaries; sticky re-attachment glues an+ // unambiguously-matching new fingerprint back onto its previous identity.+ return resolveStickyUserId({+ siteId,+ rawUserId,+ ipAddress: ip,+ userAgent,+ // cacheDate is the UTC date the salt in rawUserId was built from.+ saltScope: salted ? (this.cacheDate ?? "") : "",+ });}async generateUserIdFromClientId(clientId: string, siteId: number): Promise<string> {