@corbado/observe 1.9.0 → 1.10.0

package/dist/analysis/client.mjs

@@ -62,6 +62,7 @@ import {
 } from "./utils/trusted-device-operation-full.mjs";
 import { ProvideDataOperationFull } from "./utils/provide-data-operation-full.mjs";
 import { PasswordManagerSampler } from "./utils/password-manager-sampler.mjs";
+import { CrossOriginSession, isValidCrossOriginContext } from "./cross-origin-session.mjs";
 var SDK_INFO = {
   name: SDK_NAME,
   version: SDK_VERSION
@@ -161,7 +162,8 @@ var CorbadoTracker = class _CorbadoTracker {
       logger: this.logger,
       url
     });
-    this.sessionId = this.resolveSessionId();
+    this.crossOrigin = this.createCrossOriginSession();
+    this.sessionId = this.resolveSession();
     this.queue = new RequestQueue(
       this.logger,
       transport,
@@ -173,6 +175,7 @@ var CorbadoTracker = class _CorbadoTracker {
         requestConfig: false,
         outboxLockName: namespacedKey(OUTBOX_LOCK_NAME, namespace),
         getDataPolicy: () => this.dataPolicy,
+        getCrossOriginSession: (sessionId) => this.crossOriginSessionMeta(sessionId),
         fixedData: this.fixedData !== void 0 || typeof __CBO_DATA_PMD__ === "boolean" || typeof __CBO_DATA_PRIVATE_MODE__ === "boolean",
         beforeEventBatchSend: (events) => this.attachUndeliveredDeviceInfo(events),
         // The queue is created before the device info manager; both are only called once it exists.
@@ -290,6 +293,10 @@ var CorbadoTracker = class _CorbadoTracker {
   probeSeqs = /* @__PURE__ */ new Map();
   windowObserver;
   passwordManagerSampler;
+  /** Cross-origin session cookie (`fixedDataConfig.crossOriginSession`); undefined when off. */
+  crossOrigin;
+  /** The session this load took from the cross-origin cookie, if any (`meta.crossOriginSession`). */
+  crossOriginAdoptedId;
   /** @internal Shared passive page observation and per-operation context registration. */
   getWindowObserver() {
     return this.windowObserver ??= new SharedWindowObserver(
@@ -526,6 +533,108 @@ var CorbadoTracker = class _CorbadoTracker {
       })
     );
   }
+  /** The cross-origin session cookie when `fixedDataConfig.crossOriginSession` is set and usable here. */
+  createCrossOriginSession() {
+    const option = this.fixedData?.crossOriginSession;
+    if (!option) {
+      return void 0;
+    }
+    try {
+      if (this.isTrackingBlocked()) {
+        return void 0;
+      }
+      return CrossOriginSession.create({
+        projectId: this.options.projectId,
+        cookieDomain: option.cookieDomain,
+        logger: this.logger,
+        inactivityMs: () => this.config.sessionInactivityMs,
+        report: (level, message) => this.reportTelemetry(level, message)
+      });
+    } catch (error) {
+      this.logger.error("Failed to set up the cross-origin session", error);
+      return void 0;
+    }
+  }
+  /**
+   * Last activity of the local session records BEFORE this load rewrites them (both paths, by id), so the
+   * cross-origin boot can tell a session that was active here from one this load just created.
+   */
+  readLocalSessionActivity() {
+    const activity = /* @__PURE__ */ new Map();
+    try {
+      const continuity = this.persistentStorage.getItem(SESSION_CONTINUITY_KEY);
+      if (continuity?.id && typeof continuity.lastActiveAt === "number") {
+        activity.set(continuity.id, continuity.lastActiveAt);
+      }
+      const perTab = this.sessionStorage.getItem(SESSION_STORAGE_KEY);
+      if (perTab && typeof perTab === "object" && perTab.id && typeof perTab.lastActiveAt === "number") {
+        activity.set(perTab.id, Math.max(activity.get(perTab.id) ?? 0, perTab.lastActiveAt));
+      }
+    } catch (error) {
+      this.logger.error("Failed to read local session activity", error);
+    }
+    return activity;
+  }
+  /**
+   * Reconcile the session this load resolved locally with the cross-origin cookie before the first event:
+   * adopt the cookie's session (and persist it locally, so reloads and same-origin tabs follow) or keep
+   * the local one, and continue the seq at or above the cookie's mark. Never throws.
+   */
+  bootCrossOriginSession(localActivity) {
+    try {
+      this.crossOriginAdoptedId = void 0;
+      const now = Date.now();
+      const continuity = this.config.sessionContinuity;
+      const localSeq = continuity ? Math.max(this.seq, this.persistentStorage.getItem(SEQ_STORAGE_KEY) ?? 0) : this.seq;
+      const result = this.crossOrigin?.boot(
+        {
+          sessionId: this.sessionId,
+          lastActiveAt: this.sessionId && localActivity.get(this.sessionId) || 0,
+          seq: localSeq
+        },
+        now
+      );
+      if (!result || !result.sessionId) {
+        return;
+      }
+      if (result.adopted) {
+        this.sessionId = result.sessionId;
+        this.crossOriginAdoptedId = result.sessionId;
+        if (continuity) {
+          this.persistContinuitySession(result.sessionId, now);
+        } else {
+          this.persistPerTabSession(result.sessionId, now);
+        }
+        this.logger.debug("Adopted cross-origin session id", result.sessionId);
+      }
+      this.seq = result.seq;
+      if (continuity) {
+        this.persistentStorage.setItem(SEQ_STORAGE_KEY, result.seq);
+      }
+    } catch (error) {
+      this.logger.error("Failed to apply the cross-origin session", error);
+    }
+  }
+  /**
+   * Resolve the session of this load: locally ({@link resolveSessionId}), then reconciled with the
+   * cross-origin cookie when that option is on. Used at boot and by the recovery in `getSessionId`.
+   */
+  resolveSession() {
+    if (!this.crossOrigin) {
+      return this.resolveSessionId();
+    }
+    const localActivity = this.readLocalSessionActivity();
+    this.sessionId = this.resolveSessionId();
+    this.bootCrossOriginSession(localActivity);
+    return this.sessionId;
+  }
+  /** `meta.crossOriginSession` of a batch of `sessionId`; undefined while the option is off on this page. */
+  crossOriginSessionMeta(sessionId) {
+    if (!this.crossOrigin?.isEnabled()) {
+      return void 0;
+    }
+    return sessionId && sessionId === this.crossOriginAdoptedId ? "adopted" : "own";
+  }
   resolveSessionId() {
     try {
       if (this.config.sessionContinuity) {
@@ -659,7 +768,9 @@ var CorbadoTracker = class _CorbadoTracker {
       if (this.sessionId && now - this.lastActivityWriteAt >= SESSION_ACTIVITY_WRITE_INTERVAL_MS) {
         this.persistPerTabSession(this.sessionId, now);
       }
-      return this.seq++;
+      const current = this.crossOrigin ? this.crossOrigin.claim(this.sessionId, this.seq, now) : this.seq;
+      this.seq = current + 1;
+      return current;
     }
     const allocate = () => {
       const now = Date.now();
@@ -689,7 +800,10 @@ var CorbadoTracker = class _CorbadoTracker {
       if (sessionChanged) {
         this.seq = typeof stored === "number" ? stored : 0;
       }
-      const current = typeof stored === "number" && stored > this.seq ? stored : this.seq;
+      let current = typeof stored === "number" && stored > this.seq ? stored : this.seq;
+      if (this.crossOrigin) {
+        current = this.crossOrigin.claim(this.sessionId, current, now);
+      }
       this.seq = current + 1;
       this.persistentStorage.setItem(SEQ_STORAGE_KEY, this.seq);
       return current;
@@ -1780,6 +1894,7 @@ var CorbadoTracker = class _CorbadoTracker {
    * resources are released either way.
    */
   async destroy() {
+    this.crossOrigin?.stop();
     this.configManager?.destroy();
     this.passwordManagerSampler?.destroy();
     this.windowObserver?.destroy();
@@ -1827,7 +1942,7 @@ var CorbadoTracker = class _CorbadoTracker {
    */
   getSessionId() {
     if (!this.sessionId) {
-      const recovered = this.resolveSessionId();
+      const recovered = this.resolveSession();
       if (recovered) {
         this.sessionId = recovered;
         this.queue.setSessionId(recovered);
@@ -1835,6 +1950,69 @@ var CorbadoTracker = class _CorbadoTracker {
     }
     return this.sessionId || void 0;
   }
+  /**
+   * Store an opaque context string with the cross-origin session, for the integration's own use on the
+   * next origin (e.g. a journey id and stage). Requires `fixedDataConfig.crossOriginSession`.
+   *
+   * @remarks
+   * The value travels in the shared cookie only (see {@link CrossOriginSessionConfig}): it is never sent
+   * to Corbado, but the browser sends the cookie with every request to every subdomain of the configured
+   * domain. It belongs to the current session: a tracker that adopts the session reads it with
+   * {@link CorbadoTracker.getCrossOriginContext}, and a new session (inactivity, `resetSession`) starts
+   * without it. At most 128 characters of `A-Z a-z 0-9 . _ ~ -`; never put personal data in it.
+   * `null`, `undefined` or `""` clears it.
+   *
+   * Never throws.
+   *
+   * @param context - The value to store; `null`, `undefined` or `""` clears it.
+   * @returns `true` when the value was accepted and written; `false` when it is invalid or the feature
+   * is off on this page (not configured, cookie blocked, domain mismatch, not HTTPS).
+   *
+   * @example
+   * ```typescript
+   * tracker.setCrossOriginContext(`v1.${journeyId}.passkey.b`);
+   * ```
+   */
+  setCrossOriginContext(context) {
+    try {
+      if (!this.crossOrigin) {
+        return false;
+      }
+      const value = context === null || context === void 0 || context === "" ? void 0 : context;
+      if (value !== void 0 && !isValidCrossOriginContext(value)) {
+        this.logger.debug("Ignoring invalid cross-origin context (expected <= 128 chars of [A-Za-z0-9._~-])");
+        return false;
+      }
+      const seq = this.config.sessionContinuity ? Math.max(this.seq, this.persistentStorage.getItem(SEQ_STORAGE_KEY) ?? 0) : this.seq;
+      const next = this.crossOrigin.setContext(this.sessionId, seq, value);
+      if (next === void 0) {
+        return false;
+      }
+      if (next > this.seq) {
+        this.seq = next;
+        if (this.config.sessionContinuity) {
+          this.persistentStorage.setItem(SEQ_STORAGE_KEY, next);
+        }
+      }
+      return true;
+    } catch (error) {
+      this.logger.error("Failed to set the cross-origin context", error);
+      return false;
+    }
+  }
+  /**
+   * The context string stored with the current cross-origin session (see
+   * {@link CorbadoTracker.setCrossOriginContext}), or `undefined` when none is set, the session has no
+   * context, or the feature is off on this page. Never throws.
+   */
+  getCrossOriginContext() {
+    try {
+      return this.crossOrigin?.getContext(this.sessionId);
+    } catch (error) {
+      this.logger.error("Failed to read the cross-origin context", error);
+      return void 0;
+    }
+  }
   /** @internal */
   resetSession() {
     const newSessionId = uuidv7();
@@ -1847,6 +2025,7 @@ var CorbadoTracker = class _CorbadoTracker {
     this.sessionId = newSessionId;
     this.seq = 0;
     this.queue.setSessionId(newSessionId);
+    this.crossOrigin?.reset(newSessionId);
     this.logger.debug(`Session reset: ${newSessionId}`);
     return newSessionId;
   }

package/dist/analysis/config-manager.mjs

@@ -1,36 +1,139 @@
 // src/config-manager.ts
-import { cacheConfig, loadCachedConfig, parseReliabilityConfig } from "./config.mjs";
+import {
+  cacheConfigRecord,
+  CONFIG_STORAGE_KEY,
+  loadCachedConfig,
+  loadConfigRecord,
+  parseReliabilityConfig
+} from "./config.mjs";
 import { sendFetch } from "./readers/network.mjs";
+import { listenWindow, readDocumentHidden } from "./readers/page.mjs";
 var CONFIG_FETCH_TIMEOUT_MS = 10 * 1e3;
-var CONFIG_REFRESH_INTERVAL_MS = 10 * 60 * 1e3;
+var CONFIG_MIN_ATTEMPT_GAP_MS = 60 * 1e3;
+var CONFIG_DEFAULT_TTL_MS = 60 * 60 * 1e3;
+var CONFIG_MIN_TTL_MS = 5 * 60 * 1e3;
+var CONFIG_MAX_TTL_MS = 24 * 60 * 60 * 1e3;
 var CONFIG_RETRY_DELAYS_MS = [1e3, 3e3];
+function configTtlMs(headers) {
+  const maxAge = /(?:^|[\s,])max-age\s*=\s*"?(\d+)"?/i.exec(headers?.get("Cache-Control") ?? "");
+  if (!maxAge) return CONFIG_DEFAULT_TTL_MS;
+  const age = Number(headers?.get("Age") ?? 0);
+  const ttlMs = (Number(maxAge[1]) - (Number.isFinite(age) && age > 0 ? age : 0)) * 1e3;
+  return Math.min(Math.max(ttlMs, CONFIG_MIN_TTL_MS), CONFIG_MAX_TTL_MS);
+}
 var ConfigManager = class {
   constructor(url, storage, logger) {
     this.url = url;
     this.storage = storage;
     this.logger = logger;
     this.initialConfig = loadCachedConfig(storage) ?? void 0;
+    this.appliedVersion = this.initialConfig?.version;
   }
   initialConfig;
-  refreshTimer;
   requestTimer;
   retryTimer;
   controller;
+  removers = [];
   fetching = false;
   stopped = false;
+  lastAttemptAt;
+  /** Version last handed to (or initially applied by) the tracker. */
+  appliedVersion;
   onConfig;
   start(onConfig) {
     if (this.stopped || this.onConfig) return;
     this.onConfig = onConfig;
-    void this.fetchConfig();
+    this.listen();
+    this.refresh();
   }
-  async fetchConfig(attempt = 0) {
-    if (this.stopped || this.fetching) return;
-    if (attempt === 0) {
-      clearTimeout(this.refreshTimer);
+  listen() {
+    if (typeof window === "undefined") return;
+    const onVisibilityChange = () => {
+      const hidden = typeof document === "undefined" || readDocumentHidden({
+        key: "page:lifecycle.visibility",
+        title: "Page visibility",
+        accessNote: "document.visibilityState",
+        group: "Page lifecycle",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "visibilityState",
+            label: "Whether the page is hidden",
+            exposure: "enum",
+            transform: { values: ["hidden", "other"] }
+          }
+        ]
+      });
+      if (!hidden) this.refresh();
+    };
+    this.removers.push(
+      listenWindow(
+        {
+          key: "page:lifecycle.visibilitychange",
+          title: "Page visibility changes",
+          accessNote: "visibilitychange event on document",
+          group: "Page lifecycle",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "event.visibilitychange",
+              label: "Page hidden or shown again",
+              exposure: "presence",
+              transform: { note: "checks whether Observe settings are due for a refresh when the page is shown" }
+            }
+          ]
+        },
+        "visibilitychange",
+        onVisibilityChange
+      ),
+      listenWindow(
+        {
+          key: "page:lifecycle.pageshow",
+          title: "Returning to the page",
+          accessNote: "pageshow event on window, its persisted flag",
+          group: "Page lifecycle",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "event.persisted",
+              label: "Page restored from the browser's back/forward cache",
+              exposure: "presence",
+              transform: { note: "checks whether Observe settings are due for a refresh" }
+            }
+          ]
+        },
+        "pageshow",
+        (event) => {
+          if (event.persisted) this.refresh();
+        }
+      )
+    );
+  }
+  /** Fetches when the cached config is stale; adopts a fresh config another tab stored meanwhile. */
+  refresh() {
+    try {
+      if (this.stopped || this.fetching) return;
+      const now = Date.now();
+      const record = loadConfigRecord(this.storage);
+      const { fetchedAt, expiresAt } = record ?? {};
+      if (record?.endpoint === this.url && typeof fetchedAt === "number" && typeof expiresAt === "number" && fetchedAt > 0 && expiresAt - fetchedAt <= CONFIG_MAX_TTL_MS && fetchedAt <= now && now < expiresAt) {
+        if (record.config.version !== this.appliedVersion) {
+          this.appliedVersion = record.config.version;
+          this.onConfig?.(record.config);
+        }
+        return;
+      }
+      const sinceAttempt = this.lastAttemptAt === void 0 ? Infinity : now - this.lastAttemptAt;
+      if (sinceAttempt >= 0 && sinceAttempt < CONFIG_MIN_ATTEMPT_GAP_MS) return;
+      this.lastAttemptAt = now;
       clearTimeout(this.retryTimer);
-      this.refreshTimer = setTimeout(() => void this.fetchConfig(), CONFIG_REFRESH_INTERVAL_MS);
+      void this.fetchConfig();
+    } catch (error) {
+      this.logger.error("Unexpected error in SDK config refresh", error);
     }
+  }
+  async fetchConfig(attempt = 0) {
+    if (this.stopped || this.fetching) return;
     this.fetching = true;
     const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
     this.controller = controller;
@@ -51,6 +154,18 @@ var ConfigManager = class {
               label: "Whether the server asked to retry later",
               exposure: "presence"
             },
+            {
+              path: "response.header.cache-control",
+              label: "How long the server allows reusing the settings",
+              exposure: "computed",
+              transform: { note: "max-age, reduced to the settings' expiry time" }
+            },
+            {
+              path: "response.header.age",
+              label: "How long the settings were already stored on the way",
+              exposure: "computed",
+              transform: { note: "subtracted from max-age for the settings' expiry time" }
+            },
             {
               path: "response.body",
               label: "Observe settings",
@@ -62,7 +177,9 @@ var ConfigManager = class {
         this.url,
         {
           method: "GET",
-          cache: "no-store",
+          // Revalidates the browser's HTTP cache entry (If-None-Match once the server sends an ETag)
+          // without a custom header, which would add a CORS preflight.
+          cache: "no-cache",
           ...controller ? { signal: controller.signal } : {}
         }
       );
@@ -75,7 +192,15 @@ var ConfigManager = class {
       const config = parseReliabilityConfig(raw);
       if (!config) throw new Error("Invalid SDK config response");
       if (this.stopped || controller?.signal.aborted) return;
-      cacheConfig(this.storage, config);
+      const now = Date.now();
+      cacheConfigRecord(this.storage, {
+        endpoint: this.url,
+        fetchedAt: now,
+        expiresAt: now + configTtlMs(response.headers),
+        config
+      });
+      if (loadConfigRecord(this.storage)) this.storage.removeItem(CONFIG_STORAGE_KEY);
+      this.appliedVersion = config.version;
       this.onConfig?.(config);
     } catch (error) {
       if (!this.stopped) {
@@ -94,7 +219,7 @@ var ConfigManager = class {
   }
   destroy() {
     this.stopped = true;
-    clearTimeout(this.refreshTimer);
+    this.removers.splice(0).forEach((remove) => remove());
     clearTimeout(this.requestTimer);
     clearTimeout(this.retryTimer);
     this.controller?.abort();
@@ -102,7 +227,11 @@ var ConfigManager = class {
   }
 };
 export {
+  CONFIG_DEFAULT_TTL_MS,
   CONFIG_FETCH_TIMEOUT_MS,
-  CONFIG_REFRESH_INTERVAL_MS,
-  ConfigManager
+  CONFIG_MAX_TTL_MS,
+  CONFIG_MIN_ATTEMPT_GAP_MS,
+  CONFIG_MIN_TTL_MS,
+  ConfigManager,
+  configTtlMs
 };

package/dist/analysis/config.mjs

@@ -1,5 +1,6 @@
 // src/config.ts
 var CONFIG_STORAGE_KEY = "cbo_sdk_config";
+var CONFIG_CACHE_STORAGE_KEY = "cbo_sdk_config_cache";
 var CONFIG_REQUEST_HEADER = "X-Corbado-Observe-Config";
 var DEFAULT_FLUSH_INTERVAL_MS = 500;
 var DEFAULT_SEQ_LOCK_TIMEOUT_MS = 50;
@@ -184,23 +185,32 @@ function resolveFixedDataConfig(raw) {
     const value = raw;
     const pmd = value.pmd;
     const pmdExplicit = typeof pmd === "boolean";
+    const crossOrigin = value.crossOriginSession;
+    const cookieDomain = crossOrigin && typeof crossOrigin === "object" && typeof crossOrigin.cookieDomain === "string" ? crossOrigin.cookieDomain : void 0;
     return {
       pmd: pmdExplicit ? pmd : false,
       pmdExplicit,
-      privateMode: asBoolean(value.privateMode, true)
+      privateMode: asBoolean(value.privateMode, true),
+      ...cookieDomain !== void 0 && { crossOriginSession: { cookieDomain } }
     };
   } catch {
     return void 0;
   }
 }
+function loadConfigRecord(storage) {
+  const record = storage.getItem(CONFIG_CACHE_STORAGE_KEY);
+  const config = record && typeof record === "object" ? parseReliabilityConfig(record.config) : null;
+  return config ? { ...record, config } : null;
+}
 function loadCachedConfig(storage) {
-  return parseReliabilityConfig(storage.getItem(CONFIG_STORAGE_KEY));
+  return loadConfigRecord(storage)?.config ?? parseReliabilityConfig(storage.getItem(CONFIG_STORAGE_KEY));
 }
-function cacheConfig(storage, config) {
-  storage.setItem(CONFIG_STORAGE_KEY, config);
+function cacheConfigRecord(storage, record) {
+  storage.setItem(CONFIG_CACHE_STORAGE_KEY, record);
 }
 export {
   CONFIG_BOUNDS,
+  CONFIG_CACHE_STORAGE_KEY,
   CONFIG_REQUEST_HEADER,
   CONFIG_STORAGE_KEY,
   DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS,
@@ -208,8 +218,9 @@ export {
   DEFAULT_RELIABILITY_CONFIG,
   DEFAULT_SEQ_LOCK_TIMEOUT_MS,
   DEFAULT_SESSION_INACTIVITY_MS,
-  cacheConfig,
+  cacheConfigRecord,
   loadCachedConfig,
+  loadConfigRecord,
   parseReliabilityConfig,
   resolveFixedDataConfig,
   resolveReliabilityConfig