Skip to content

🐸 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.json
index 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.json
index 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.ts
index 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: numb
return (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); for
diff --git a/server/src/db/redis/stickyResolve.integration.test.ts b/server/src/db/redis/stickyResolve.integration.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 enabled
const 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> {