Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

5.8 KB
Raw Blame
import crypto from "crypto";
import { lookupAsn, type AsnLookup } from "../../db/geolocation/asn.js";
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 {
  /**
   * The Site's salting setting when the caller already holds its Site
   * Configuration. Omit it and the config is fetched β€” a second read of a row
   * the tracking path has usually just loaded.
   */
  saltUserIds?: boolean;
  /** Request-scoped ASN resolver, shared with the rest of the ingestion path. */
  lookupAsn?: AsnLookup;
  /**
   * The moment the event belongs to β€” the same instant it will be timestamped
   * with. The daily salt is picked for *this* instant's UTC day rather than for
   * "now", so an event accepted at 23:59:59.9 can't be stamped with day D and
   * fingerprinted with day D+1's salt because ingestion took a millisecond to
   * reach the hash. Defaults to now for callers outside the tracking path.
   */
  receivedAt?: Date;
}

/** The UTC day (YYYY-MM-DD) an instant falls in. */
function utcDayOf(instant: Date): string {
  return instant.toISOString().split("T")[0];
}

class UserIdService {
  private cachedSalt: string | null = null;
  private cacheDate: string | null = null; // Store the date the salt was generated for (YYYY-MM-DD format)

  /**
   * Generates a deterministic salt for a given UTC day from a secret environment
   * variable. The salt is the same for the whole day and changes when the day
   * does. Caches the most recent day's salt in memory for efficiency.
   *
   * The day is a parameter, not a reading of the clock: the caller decides which
   * day an event belongs to, so a request straddling midnight hashes against one
   * day throughout.
   *
   * @throws {Error} If the BETTER_AUTH_SECRET environment variable is not set.
   * @returns {string} The daily salt as a hex string.
   */
  private getDailySalt(utcDay: string): string {
    if (!SECRET) {
      console.error(
        "FATAL: BETTER_AUTH_SECRET environment variable is not set. User ID generation will be insecure or fail."
      );
      throw new Error("BETTER_AUTH_SECRET environment variable is missing.");
    }

    if (this.cachedSalt && this.cacheDate === utcDay) {
      return this.cachedSalt;
    }

    const input = SECRET + utcDay;
    const newSalt = crypto.createHash("sha256").update(input).digest("hex");

    this.cachedSalt = newSalt;
    this.cacheDate = utcDay;
    return newSalt;
  }

  /**
   * Whether this Site salts user IDs β€” from the caller's already-loaded Site
   * Configuration when it has one, otherwise fetched.
   */
  private async isSalted(siteId: number, options: UserIdOptions): Promise<boolean> {
    if (options.saltUserIds !== undefined) return options.saltUserIds;
    const config = await siteConfig.getConfig(siteId);
    return !!config?.saltUserIds;
  }

  /**
   * 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
   * @param options Facts the caller already holds, so they aren't looked up again
   * @returns A truncated sha256 hash (12 chars) to identify the user
   */
  async generateUserId(ip: string, userAgent: string, siteId: number, options: UserIdOptions = {}): Promise<string> {
    const asnLookup = options.lookupAsn ?? lookupAsn;
    const isDatacenterEgress = (candidate: string) => isDatacenterAsn(asnLookup(candidate)?.asn);

    // Datacenter egress (corporate proxies, WARP, Private Relay) rotates IPs
    // 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 + identityUserAgent + (salted ? this.getDailySalt(saltDay) : ""))
      .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,
      // The UTC day the salt in rawUserId was built from.
      saltScope: salted ? saltDay : "",
      isDatacenterEgress,
    });
  }

  async generateUserIdFromClientId(clientId: string, siteId: number, options: UserIdOptions = {}): Promise<string> {
    const saltDay = utcDayOf(options.receivedAt ?? new Date());
    const salt = (await this.isSalted(siteId, options)) ? this.getDailySalt(saltDay) : "";

    return crypto.createHash("sha256").update(`${siteId}:${clientId}:${salt}`).digest("hex").substring(0, 12);
  }
}

export const userIdService = new UserIdService();