@corbado/observe 1.7.2 → 1.9.0

package/dist/analysis/device.mjs

@@ -0,0 +1,640 @@
+// src/device.ts
+import { normalizeError } from "./utils/normalize-error.mjs";
+import { v7 as uuidv7 } from "uuid";
+import {
+  readBluetoothAvailability,
+  readClientCapabilities,
+  readConditionalMediationAvailable,
+  readJavaScriptHighEntropy,
+  readMaxTouchPoints,
+  readUserAgent,
+  readUserVerifyingPlatformAuthenticatorAvailable,
+  readWebdriver
+} from "./readers/device.mjs";
+import { readPrivateMode } from "./readers/private-mode.mjs";
+var DEVICE_INFO_FAST_TIMEOUT_MS = 300;
+var DEVICE_INFO_LATE_TIMEOUT_MS = 6e3;
+var PRIVATE_MODE_CACHE_KEY = "cbo_pm";
+var PRIVATE_MODE_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+var PRIVATE_MODE_DETECTOR_VERSION = "detectincognitojs@1.9.0";
+var DEFAULT_SETTINGS = {
+  timing: false
+};
+var TAB_ID_KEY = "cbo_tab_id";
+var TIMING_FIELD_CODES = {
+  bluetoothAvailable: "bt",
+  clientCapabilities: "cc",
+  userVerifyingPlatformAuthenticatorAvailable: "uvpaa",
+  conditionalMediationAvailable: "cm",
+  javaScriptHighEntropy: "he",
+  privateMode: "pm",
+  webdriver: "wd",
+  maxTouchPoints: "mtp"
+};
+function nowMs() {
+  return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+function timeoutError(field, source, timeoutMs) {
+  return {
+    field,
+    source,
+    error: { name: "TimeoutError", message: `Device info collection timed out after ${timeoutMs}ms` }
+  };
+}
+async function settlesWithin(promise, timeoutMs) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise.then(
+        () => true,
+        () => true
+      ),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
+      })
+    ]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+}
+var DeviceCollector = class {
+  constructor(logger, storage, storageSource = "localstorage", sessionStorage, settings = () => DEFAULT_SETTINGS, emitTelemetry, privateModeEnabled = true) {
+    this.logger = logger;
+    this.storage = storage;
+    this.storageSource = storageSource;
+    this.sessionStorage = sessionStorage;
+    this.settings = settings;
+    this.emitTelemetry = emitTelemetry;
+    this.privateModeEnabled = privateModeEnabled;
+  }
+  /** privateMode known on this page (from the cache or a detection), reused by every refresh. */
+  pagePrivateMode;
+  /** Detection runs at most once per page: a refresh never reruns the IndexedDB benchmark. */
+  privateModeDetectionStarted = false;
+  /** Last known value per fast field, so a refresh's fast snapshot does not drop a slow-but-stable field. */
+  lastKnown = {};
+  /**
+   * Collect device info in two steps and hand each snapshot to `publish`:
+   *  1. The fast snapshot: every fast field, published once all of them settled or
+   *     {@link DEVICE_INFO_FAST_TIMEOUT_MS} passed. An uncached privateMode is detected once per page,
+   *     started together with the fast fields; the fast snapshot includes privateMode when it is known
+   *     already (cache, an earlier detection on this page) or the detection finished in time.
+   *  2. At most one update: fields and a detection still running keep going until
+   *     {@link DEVICE_INFO_LATE_TIMEOUT_MS} after the collection start. Published when that work is done.
+   *
+   * Resolves once the run is complete. On a refresh (`refresh: true`), fast fields that did not
+   * settle in time fall back to their last known value in the fast snapshot.
+   *
+   * Error situations:
+   *  - Any thrown or rejected error while collecting an individual field: log "Failed to collect device info field", set the field to undefined, and add an entry to collectionErrors
+   *  - data.bluetoothAvailable is undefined when navigator is not available or navigator.bluetooth is falsy
+   *  - data.userVerifyingPlatformAuthenticatorAvailable is undefined when PublicKeyCredential is not available or isUserVerifyingPlatformAuthenticatorAvailable is missing
+   *  - data.conditionalMediationAvailable is undefined when PublicKeyCredential is not available or isConditionalMediationAvailable is missing
+   *  - data.clientCapabilities is undefined when PublicKeyCredential is not available or getClientCapabilities is missing
+   *  - data.javaScriptHighEntropy is undefined when navigator is not available or navigator.userAgentData is falsy, or when high-entropy values omit platform, mobile, or platformVersion
+   *  - data.webdriver is undefined when navigator is not available
+   *  - data.maxTouchPoints is undefined when navigator is not available or navigator.maxTouchPoints is not a number
+   *  - A field (or the privateMode detection) that does not settle within the late deadline: a TimeoutError entry "Device info collection timed out after 6000ms" in collectionErrors of the update
+   *  - The privateMode cache is unreadable, malformed, expired or from another detector version: detect instead; a failing cache write is logged and ignored
+   *  - The settings provider throwing: log "Failed to resolve device info collector settings" and collect with the built-in defaults
+   *  - `publish` throwing: log "Failed to publish device info" and continue
+   *  - Any other unexpected error: log "Failed to collect device info" and publish nothing further
+   */
+  async collect(publish, options = {}) {
+    try {
+      const settings = this.resolveSettings();
+      const startedAt = nowMs();
+      const clientEnvHandleEntry = this.getClientEnvHandle();
+      const base = {
+        type: "web",
+        clientEnvHandle: clientEnvHandleEntry.value,
+        clientEnvHandleMeta: {
+          timestamp: clientEnvHandleEntry.timestamp,
+          source: clientEnvHandleEntry.source
+        },
+        tabId: this.getTabId()
+      };
+      const privateModeOn = typeof __CBO_DATA_PRIVATE_MODE__ === "boolean" ? __CBO_DATA_PRIVATE_MODE__ : this.privateModeEnabled;
+      const privateMode = privateModeOn ? this.knownPrivateMode(settings.timing) : void 0;
+      let detected;
+      const detection = privateModeOn && privateMode === void 0 && !this.privateModeDetectionStarted ? this.detectPrivateMode(settings.timing).then((result) => {
+        detected = result;
+      }) : void 0;
+      const tasks = this.startFastFields();
+      await settlesWithin(Promise.all(tasks.map((task) => task.promise)), DEVICE_INFO_FAST_TIMEOUT_MS);
+      const fastMs = nowMs() - startedAt;
+      const fallback = options.refresh ? this.lastKnown : {};
+      if (settings.timing) {
+        this.reportFastTiming(fastMs, tasks);
+      }
+      const detectionErrors = () => detected?.error ? [detected.error] : [];
+      this.safePublish(
+        publish,
+        this.buildInfo(base, tasks, detected ? detected.value : privateMode, fallback, detectionErrors()),
+        "fast"
+      );
+      const late = tasks.filter((task) => !task.settled);
+      const detectionPending = detection !== void 0 && detected === void 0;
+      if (late.length === 0 && !detectionPending) {
+        return;
+      }
+      const lateStartedAt = nowMs();
+      await Promise.all([
+        settlesWithin(
+          Promise.all(late.map((task) => task.promise)),
+          DEVICE_INFO_LATE_TIMEOUT_MS - (lateStartedAt - startedAt)
+        ),
+        detection
+      ]);
+      const lateErrors = late.filter((task) => !task.settled).map((task) => timeoutError(task.field, task.source, DEVICE_INFO_LATE_TIMEOUT_MS));
+      lateErrors.push(...detectionErrors());
+      if (settings.timing && late.length > 0) {
+        this.reportLateTiming(nowMs() - startedAt, late);
+      }
+      this.safePublish(
+        publish,
+        this.buildInfo(base, tasks, detected ? detected.value : privateMode, fallback, lateErrors),
+        "update"
+      );
+    } catch (error) {
+      this.logger.error("Failed to collect device info", error);
+    }
+  }
+  /**
+   * Collect a complete snapshot: runs {@link collect} to the end and resolves with its last published
+   * snapshot (the update when there was one), or an empty object when nothing could be collected.
+   */
+  async getInfo() {
+    let latest;
+    await this.collect((info) => {
+      latest = info;
+    });
+    return latest ?? {};
+  }
+  startFastFields() {
+    return [
+      this.startField(
+        "bluetoothAvailable",
+        "navigator.bluetooth.getAvailability",
+        () => readBluetoothAvailability({
+          key: "browser-api:device.bluetooth-availability",
+          title: "Bluetooth availability",
+          accessNote: "navigator.bluetooth.getAvailability()",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result",
+              label: "Whether Bluetooth is available",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
+        })
+      ),
+      this.startField(
+        "clientCapabilities",
+        "PublicKeyCredential.getClientCapabilities",
+        () => readClientCapabilities({
+          key: "browser-api:device.client-capabilities",
+          title: "Passkey features supported by the browser",
+          accessNote: "PublicKeyCredential.getClientCapabilities(), every returned key",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result.<capability>",
+              label: "Supported passkey features",
+              exposure: "enum",
+              transform: { values: ["true", "false"], note: "open set of capability names, kept as reported" }
+            }
+          ]
+        })
+      ),
+      this.startField(
+        "userVerifyingPlatformAuthenticatorAvailable",
+        "PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable",
+        () => readUserVerifyingPlatformAuthenticatorAvailable({
+          key: "browser-api:device.uvpaa",
+          title: "Built-in passkey support on the device",
+          accessNote: "PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result",
+              label: "Whether the device has a built-in passkey authenticator",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
+        })
+      ),
+      this.startField(
+        "conditionalMediationAvailable",
+        "PublicKeyCredential.isConditionalMediationAvailable",
+        () => readConditionalMediationAvailable({
+          key: "browser-api:device.conditional-mediation",
+          title: "Passkey autofill availability",
+          accessNote: "PublicKeyCredential.isConditionalMediationAvailable()",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result",
+              label: "Whether passkey autofill is available",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
+        })
+      ),
+      this.startField(
+        "javaScriptHighEntropy",
+        "navigator.userAgentData.getHighEntropyValues",
+        () => readJavaScriptHighEntropy({
+          key: "browser-api:device.ua-high-entropy",
+          title: "Device platform, version and model reported by the browser",
+          accessNote: "User-Agent Client Hints: navigator.userAgentData.getHighEntropyValues()",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            { path: "result.platform", label: "Operating system", exposure: "raw" },
+            {
+              path: "result.mobile",
+              label: "Whether the device is a mobile device",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            },
+            { path: "result.platformVersion", label: "Operating system version", exposure: "raw" },
+            { path: "result.model", label: "Device model", exposure: "raw" }
+          ]
+        })
+      ),
+      this.startField(
+        "webdriver",
+        "navigator.webdriver",
+        () => readWebdriver({
+          key: "browser-api:device.webdriver",
+          title: "Browser automation flag",
+          accessNote: "navigator.webdriver",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result",
+              label: "Whether the browser is controlled by automation",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
+        })
+      ),
+      this.startField(
+        "maxTouchPoints",
+        "navigator.maxTouchPoints",
+        () => readMaxTouchPoints({
+          key: "browser-api:device.max-touch-points",
+          title: "Touch screen support",
+          accessNote: "navigator.maxTouchPoints",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [{ path: "result", label: "Number of touch points of the screen", exposure: "raw" }]
+        })
+      )
+    ];
+  }
+  /** Start one field; its promise never rejects, a failure becomes the field's collection error. */
+  startField(field, source, collect) {
+    const startedAt = nowMs();
+    const task = { field, source };
+    task.promise = Promise.resolve().then(collect).then(
+      (value) => ({ field, value, durationMs: nowMs() - startedAt }),
+      (error) => {
+        this.logger.error(`Failed to collect device info field "${field}"`, error);
+        return {
+          field,
+          durationMs: nowMs() - startedAt,
+          error: { field, source, error: normalizeError(error) ?? { message: "Unknown error" } }
+        };
+      }
+    ).then((result) => {
+      task.settled = result;
+      return result;
+    });
+    return task;
+  }
+  buildInfo(base, tasks, privateMode, fallback, extraErrors) {
+    const data = {};
+    const collectionErrors = [];
+    for (const task of tasks) {
+      if (task.settled) {
+        if (task.settled.error) {
+          collectionErrors.push(task.settled.error);
+        }
+        data[task.field] = task.settled.value;
+        this.remember(task.field, task.settled.value);
+      } else {
+        data[task.field] = fallback[task.field];
+      }
+    }
+    data.privateMode = privateMode;
+    collectionErrors.push(...extraErrors);
+    const deviceInfo = {
+      ...base,
+      data: {
+        bluetoothAvailable: data.bluetoothAvailable,
+        javaScriptHighEntropy: data.javaScriptHighEntropy,
+        privateMode: data.privateMode,
+        webdriver: data.webdriver,
+        conditionalMediationAvailable: data.conditionalMediationAvailable,
+        userVerifyingPlatformAuthenticatorAvailable: data.userVerifyingPlatformAuthenticatorAvailable,
+        clientCapabilities: data.clientCapabilities,
+        maxTouchPoints: data.maxTouchPoints
+      }
+    };
+    if (collectionErrors.length > 0) {
+      deviceInfo.collectionErrors = collectionErrors;
+    }
+    return deviceInfo;
+  }
+  remember(field, value) {
+    if (value !== void 0) {
+      this.lastKnown[field] = value;
+    }
+  }
+  safePublish(publish, info, phase) {
+    try {
+      publish(info, phase);
+    } catch (error) {
+      this.logger.error("Failed to publish device info", error);
+    }
+  }
+  /** privateMode as already known on this page, else from a valid cache entry (which then sticks for the page). */
+  knownPrivateMode(timing) {
+    if (this.pagePrivateMode !== void 0) {
+      return this.pagePrivateMode;
+    }
+    const cached = this.readPrivateModeCache();
+    if (cached) {
+      this.pagePrivateMode = cached.value;
+      if (timing) {
+        this.reportTelemetry(`device info privateMode from cache, age ${Math.round((Date.now() - cached.ts) / 1e3)}s`);
+      }
+    }
+    return this.pagePrivateMode;
+  }
+  /**
+   * The cache lives in localStorage only: in cookie storage mode the private-mode flag would be sent
+   * to the host's servers with every request, so it is not cached there (detection runs per page).
+   */
+  canCachePrivateMode() {
+    return this.storageSource === "localstorage";
+  }
+  readPrivateModeCache() {
+    if (!this.canCachePrivateMode()) {
+      return void 0;
+    }
+    try {
+      const entry = this.storage.getItem(PRIVATE_MODE_CACHE_KEY);
+      if (!entry || typeof entry !== "object" || typeof entry.value !== "boolean" || typeof entry.ts !== "number" || entry.dv !== PRIVATE_MODE_DETECTOR_VERSION) {
+        return void 0;
+      }
+      const age = Date.now() - entry.ts;
+      if (age < 0 || age >= PRIVATE_MODE_CACHE_TTL_MS) {
+        return void 0;
+      }
+      return entry;
+    } catch (error) {
+      this.logger.debug("Failed to read cached privateMode", error);
+      return void 0;
+    }
+  }
+  writePrivateModeCache(value) {
+    if (!this.canCachePrivateMode()) {
+      return;
+    }
+    try {
+      this.storage.setItem(PRIVATE_MODE_CACHE_KEY, {
+        value,
+        ts: Date.now(),
+        dv: PRIVATE_MODE_DETECTOR_VERSION
+      });
+    } catch (error) {
+      this.logger.error("Failed to cache privateMode", error);
+    }
+  }
+  /**
+   * Run the privateMode detection once for this page, bounded by the late deadline. A definite result
+   * is cached and reused by every later collection; a timeout or failure yields a collection error.
+   */
+  async detectPrivateMode(timing) {
+    this.privateModeDetectionStarted = true;
+    const source = "detectIncognito";
+    const startedAt = nowMs();
+    const task = this.startField(
+      "privateMode",
+      source,
+      () => typeof __CBO_DATA_PRIVATE_MODE__ === "boolean" && !__CBO_DATA_PRIVATE_MODE__ ? void 0 : readPrivateMode({
+        key: "browser-api:device.private-mode",
+        title: "Private browsing mode",
+        accessNote: "detectincognitojs library (IndexedDB, storage quota and browser-specific probes)",
+        group: "Device information",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "result.isPrivate",
+            label: "Whether private browsing is on",
+            exposure: "enum",
+            transform: { values: [true, false] }
+          }
+        ],
+        dataConfig: "privateMode"
+      })
+    );
+    const settled = await settlesWithin(task.promise, DEVICE_INFO_LATE_TIMEOUT_MS);
+    if (!settled || !task.settled) {
+      if (timing) {
+        this.reportTelemetry(`device info privateMode timed out after ${DEVICE_INFO_LATE_TIMEOUT_MS}ms`);
+      }
+      return { error: timeoutError("privateMode", source, DEVICE_INFO_LATE_TIMEOUT_MS) };
+    }
+    if (timing) {
+      this.reportTelemetry(`device info privateMode detected in ${Math.round(nowMs() - startedAt)}ms`);
+    }
+    if (task.settled.error) {
+      return { error: task.settled.error };
+    }
+    const value = task.settled.value;
+    if (typeof value !== "boolean") {
+      return { value: void 0 };
+    }
+    this.pagePrivateMode = value;
+    this.writePrivateModeCache(value);
+    return { value };
+  }
+  /**
+   * Resolve the settings for one collection run. A broken provider must never stop collection, so
+   * anything thrown degrades to the built-in defaults.
+   */
+  resolveSettings() {
+    try {
+      return { timing: this.settings()?.timing === true };
+    } catch (error) {
+      this.logger.error("Failed to resolve device info collector settings", error);
+      return DEFAULT_SETTINGS;
+    }
+  }
+  /**
+   * Emit the fast snapshot's durations as an info telemetry entry: the total wall time until the fast
+   * snapshot plus every fast field's own time, in definition order so two entries can be compared field
+   * by field. Per-field values use the short codes from `TIMING_FIELD_CODES` and carry no unit — the
+   * unit is stated once on the total, and all values are milliseconds. A field still running at the
+   * fast deadline reports the time it had run so far (it is reported again by the late entry).
+   */
+  reportFastTiming(totalMs, tasks) {
+    const perField = tasks.map((task) => `${TIMING_FIELD_CODES[task.field]}=${Math.round(task.settled?.durationMs ?? totalMs)}`).join(",");
+    this.reportTelemetry(`device info collected in ${Math.round(totalMs)}ms (${perField})`);
+  }
+  /** Emit the late fields' outcome: their duration, or `timeout` when they missed the late deadline. */
+  reportLateTiming(totalMs, late) {
+    const perField = late.map(
+      (task) => `${TIMING_FIELD_CODES[task.field]}=${task.settled ? Math.round(task.settled.durationMs) : "timeout"}`
+    ).join(",");
+    this.reportTelemetry(`device info late fields done in ${Math.round(totalMs)}ms (${perField})`);
+  }
+  reportTelemetry(message) {
+    if (!this.emitTelemetry) {
+      return;
+    }
+    try {
+      this.emitTelemetry("info", message);
+    } catch (error) {
+      this.logger.error("Failed to report device info timing", error);
+    }
+  }
+  /**
+   * Error situations:
+   *  - navigator is not available: user agent is treated as empty, osName and browserName are "other"
+   *  - navigator is available but userAgent is null or undefined: same as above
+   */
+  static getOsAndBrowserInfo() {
+    return {
+      osName: this.getOsName(),
+      browserName: this.getBrowserName()
+    };
+  }
+  static getUserAgent() {
+    return readUserAgent({
+      key: "browser-api:device.user-agent",
+      title: "Browser and operating system",
+      accessNote: "navigator.userAgent",
+      group: "Device information",
+      origin: "observe-external",
+      fields: [
+        {
+          path: "result",
+          label: "Browser and operating system",
+          exposure: "class",
+          transform: {
+            classes: [
+              "iOS",
+              "Android",
+              "Windows",
+              "macOS",
+              "Linux",
+              "ChromeOS",
+              "Chrome",
+              "Firefox",
+              "Safari",
+              "Edge",
+              "Opera",
+              "IE",
+              "other"
+            ]
+          }
+        }
+      ]
+    });
+  }
+  static getOsName() {
+    const ua = this.getUserAgent();
+    if (ua.includes("iOS")) {
+      return "iOS";
+    } else if (ua.includes("Android")) {
+      return "Android";
+    } else if (ua.includes("Windows")) {
+      return "Windows";
+    } else if (ua.includes("Macintosh")) {
+      return "macOS";
+    } else if (ua.includes("Linux")) {
+      return "Linux";
+    } else if (ua.includes("ChromeOS")) {
+      return "ChromeOS";
+    }
+    return "other";
+  }
+  static getBrowserName() {
+    const ua = this.getUserAgent();
+    if (ua.includes("Chrome")) {
+      return "Chrome";
+    } else if (ua.includes("Firefox")) {
+      return "Firefox";
+    } else if (ua.includes("Safari")) {
+      return "Safari";
+    } else if (ua.includes("Edge")) {
+      return "Edge";
+    } else if (ua.includes("Opera")) {
+      return "Opera";
+    } else if (ua.includes("IE")) {
+      return "IE";
+    }
+    return "other";
+  }
+  getClientEnvHandle() {
+    const existingClientEnvHandle = this.storage.getItem("cbo_client_env_handle");
+    if (existingClientEnvHandle) {
+      return existingClientEnvHandle;
+    }
+    const newClientEnvHandleValue = uuidv7();
+    const newClientEnvHandle = {
+      timestamp: Date.now(),
+      source: this.storageSource,
+      value: newClientEnvHandleValue
+    };
+    this.storage.setItem("cbo_client_env_handle", newClientEnvHandle);
+    return newClientEnvHandle;
+  }
+  /**
+   * Resolve a per-tab id from sessionStorage (unique per browsing context). Returns undefined when no
+   * session storage is available so two tabs sharing one localStorage-backed session can be distinguished.
+   *
+   * Public because the tracker also stamps this id onto every event's meta at track() time (see
+   * `EventMeta.tabId`); both callers share the same sessionStorage-backed id.
+   */
+  getTabId() {
+    if (!this.sessionStorage) {
+      return void 0;
+    }
+    const existing = this.sessionStorage.getItem(TAB_ID_KEY);
+    if (existing) {
+      return existing;
+    }
+    const tabId = uuidv7();
+    this.sessionStorage.setItem(TAB_ID_KEY, tabId);
+    if (this.sessionStorage.getItem(TAB_ID_KEY) !== tabId) {
+      return void 0;
+    }
+    return tabId;
+  }
+};
+export {
+  DEVICE_INFO_FAST_TIMEOUT_MS,
+  DEVICE_INFO_LATE_TIMEOUT_MS,
+  DeviceCollector,
+  PRIVATE_MODE_CACHE_KEY,
+  PRIVATE_MODE_CACHE_TTL_MS,
+  PRIVATE_MODE_DETECTOR_VERSION
+};

package/dist/analysis/handoff.mjs

@@ -0,0 +1,7 @@
+// src/handoff.ts
+function acceptHandoffs(step) {
+  return step;
+}
+export {
+  acceptHandoffs
+};