@corbado/observe 1.9.0 → 1.10.0

package/dist/analysis/cross-origin-session.mjs

@@ -0,0 +1,422 @@
+// src/cross-origin-session.ts
+import { readCookieScope } from "./readers/page.mjs";
+import { cookieJar } from "./readers/storage.mjs";
+var CROSS_ORIGIN_COOKIE_PREFIX = "cbo_xs";
+var CROSS_ORIGIN_COOKIE_VERSION = "1";
+var CROSS_ORIGIN_SEQ_RESERVE = 20;
+var CROSS_ORIGIN_CONTEXT_MAX = 128;
+var CONTEXT_RE = /^[A-Za-z0-9._~-]{1,128}$/;
+var CROSS_ORIGIN_ACTIVITY_WRITE_INTERVAL_MS = 1e3;
+var FUTURE_TOLERANCE_MS = 5 * 60 * 1e3;
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var PROJECT_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+var DOMAIN_RE = /^[a-z0-9-]+(\.[a-z0-9-]+)+$/;
+var INT_RE = /^\d{1,15}$/;
+var CROSS_ORIGIN_MAX_SEQ_MARK = 1e9;
+var CROSS_ORIGIN_FOREIGN_GAP = 1e3;
+var CROSS_ORIGIN_MAX_SEQ_JUMP = 1e5;
+function isValidCrossOriginContext(value) {
+  return typeof value === "string" && CONTEXT_RE.test(value);
+}
+function parseCrossOriginCookie(value) {
+  const parts = value.split(".");
+  const [version, sessionId, lastActiveAt, seqMark] = parts;
+  if (parts.length < 4 || version !== CROSS_ORIGIN_COOKIE_VERSION || !sessionId || !UUID_RE.test(sessionId) || !lastActiveAt || !INT_RE.test(lastActiveAt) || !seqMark || !INT_RE.test(seqMark) || Number(seqMark) > CROSS_ORIGIN_MAX_SEQ_MARK) {
+    return void 0;
+  }
+  const context = parts.length > 4 ? parts.slice(4).join(".") : void 0;
+  if (context !== void 0 && !isValidCrossOriginContext(context)) {
+    return void 0;
+  }
+  return {
+    sessionId: sessionId.toLowerCase(),
+    lastActiveAt: Number(lastActiveAt),
+    seqMark: Number(seqMark),
+    ...context !== void 0 && { context }
+  };
+}
+function formatCrossOriginCookie(record) {
+  const parts = [
+    CROSS_ORIGIN_COOKIE_VERSION,
+    record.sessionId,
+    String(Math.floor(record.lastActiveAt)),
+    String(Math.floor(record.seqMark))
+  ];
+  if (record.context !== void 0) {
+    parts.push(record.context);
+  }
+  return parts.join(".");
+}
+function resolveCrossOriginDomain(raw, hostname) {
+  const domain = raw.trim().toLowerCase().replace(/^\./, "");
+  const host = hostname.toLowerCase();
+  if (!DOMAIN_RE.test(domain)) {
+    return void 0;
+  }
+  return host === domain || host.endsWith(`.${domain}`) ? domain : void 0;
+}
+var CrossOriginSession = class _CrossOriginSession {
+  constructor(name, domain, jar, contextJar, deps) {
+    this.name = name;
+    this.domain = domain;
+    this.jar = jar;
+    this.contextJar = contextJar;
+    this.deps = deps;
+  }
+  enabled = true;
+  /** Session the in-memory reservation, highest seen mark and context belong to. */
+  reservedFor;
+  /** Seq this page may allocate up to (exclusive) without rewriting the cookie. */
+  reservedMark = 0;
+  /** Highest plausible mark of {@link reservedFor} this page has seen or written. */
+  highestSeen = 0;
+  lastWriteAt = 0;
+  /** Context of {@link reservedFor} as last known to this page. */
+  context;
+  /**
+   * The feature for this page, or `undefined` when it cannot work here (invalid project id or domain, a
+   * domain that is not the page's host or a parent of it, a non-HTTPS page, no document). Never throws.
+   */
+  static create(deps) {
+    try {
+      if (typeof document === "undefined" || typeof window === "undefined") {
+        return void 0;
+      }
+      if (!PROJECT_ID_RE.test(deps.projectId)) {
+        deps.logger.debug("Cross-origin session off: project id is not cookie-safe");
+        return void 0;
+      }
+      const scope = deps.scope ? deps.scope() : readCookieScope({
+        key: "page:location.cookie-scope",
+        title: "Page host name for the shared session cookie",
+        accessNote: "location.hostname and location.protocol, compared with the configured shared cookie domain; not sent",
+        group: "Observe SDK state",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "hostname",
+            label: "Host name of the page",
+            exposure: "none",
+            transform: { note: "only compared with the configured parent domain; never sent or stored" }
+          },
+          {
+            path: "https",
+            label: "Whether the page uses a secure connection",
+            exposure: "none",
+            transform: { note: "the shared cookie is only used on secure pages; never sent or stored" }
+          }
+        ]
+      });
+      if (!scope.https) {
+        deps.logger.debug("Cross-origin session off: page is not served over HTTPS");
+        return void 0;
+      }
+      const domain = resolveCrossOriginDomain(deps.cookieDomain, scope.hostname);
+      if (!domain) {
+        deps.logger.warn(`Cross-origin session off: "${deps.cookieDomain}" is not the page's domain or a parent of it`);
+        deps.report("info", "cross-origin session: cookieDomain does not match the page");
+        return void 0;
+      }
+      const jar = deps.jar ?? cookieJar({
+        key: "storage:sdk.cross-origin-session",
+        title: "Observe session shared across your subdomains",
+        accessNote: "document.cookie, Observe's own cbo_xs_ cookie on the configured parent domain (Secure, SameSite Lax, Path /, expires after the session inactivity window); the browser sends it with every request to every subdomain of that domain",
+        group: "Observe SDK state",
+        origin: "observe-internal",
+        fields: [
+          {
+            path: "sessionId",
+            label: "Random Observe session id",
+            exposure: "token",
+            transform: {
+              pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+              max: 36,
+              note: "generated by the SDK; sent to Corbado as the session id of every batch; the cookie carries it to every subdomain of the configured domain"
+            }
+          },
+          {
+            path: "lastActiveAt",
+            label: "Time of the last tracked activity",
+            exposure: "none",
+            transform: {
+              note: "decides whether the session is still active; not sent to Corbado, but the cookie carries it to every subdomain of the configured domain"
+            }
+          },
+          {
+            path: "seqMark",
+            label: "Event counter position",
+            exposure: "none",
+            transform: {
+              note: "the next page continues event numbering above it; not sent to Corbado, but the cookie carries it to every subdomain of the configured domain"
+            }
+          }
+        ]
+      });
+      const contextJar = deps.jar ?? cookieJar({
+        key: "storage:sdk.cross-origin-context",
+        title: "Reference your integration keeps with the shared session",
+        accessNote: "document.cookie, the optional context part of Observe's cbo_xs_ cookie, set and read by the integration",
+        group: "Observe SDK state",
+        origin: "host-config",
+        fields: [
+          {
+            path: "context",
+            label: "Optional reference set by your integration",
+            exposure: "none",
+            transform: {
+              note: "opaque string of at most 128 cookie-safe characters chosen by the integration; not sent to Corbado, but the cookie carries it to every subdomain of the configured domain"
+            }
+          }
+        ]
+      });
+      return new _CrossOriginSession(`${CROSS_ORIGIN_COOKIE_PREFIX}_${deps.projectId}`, domain, jar, contextJar, deps);
+    } catch (error) {
+      deps.logger.error("Cross-origin session setup failed", error);
+      return void 0;
+    }
+  }
+  /** Whether the cookie is in use on this page (false after a failed write check or {@link stop}). */
+  isEnabled() {
+    return this.enabled;
+  }
+  /** No cookie access from now on (tracker destroyed). */
+  stop() {
+    this.enabled = false;
+  }
+  /**
+   * Decide the session of this load before its first event and claim the cookie for it.
+   *
+   * `local.lastActiveAt` is the local session's last activity BEFORE this load (0 when the local session
+   * was created by this load). The cookie's session is adopted when the local one is new or was active
+   * earlier than the cookie's; the same session continues at or above the cookie's mark. A local session
+   * that was active more recently takes the cookie over. Never throws; `undefined` when the feature is off.
+   */
+  boot(local, now = Date.now()) {
+    if (!this.enabled) {
+      return void 0;
+    }
+    try {
+      const cookie = this.read(this.jar, now);
+      let sessionId = local.sessionId;
+      let adopted = false;
+      if (cookie && cookie.sessionId !== sessionId && (!sessionId || local.lastActiveAt <= 0 || cookie.lastActiveAt > local.lastActiveAt)) {
+        sessionId = cookie.sessionId;
+        adopted = true;
+      }
+      let seq = adopted ? cookie?.seqMark ?? 0 : local.seq;
+      if (sessionId) {
+        const written = this.sync(this.jar, cookie, sessionId, seq, now, true, false);
+        seq = written.seq;
+        if (!this.isStored(written.value)) {
+          this.enabled = false;
+          this.deps.logger.debug("Cross-origin session off: the cookie could not be stored");
+          this.deps.report("info", "cross-origin session: cookie not stored");
+        }
+      }
+      return { sessionId, seq, adopted };
+    } catch (error) {
+      this.enabled = false;
+      this.deps.logger.error("Cross-origin session boot failed", error);
+      this.deps.report("error", "cross-origin session: boot failed");
+      return void 0;
+    }
+  }
+  /**
+   * Called for every seq allocation with the seq about to be used; returns the seq to use instead. Reads
+   * the cookie on every call (a string scan).
+   *
+   * - Cookie of this session: continue above another page's reservation once one exists above this
+   *   page's, renew the reservation when it is used up, otherwise refresh the activity at most once per
+   *   {@link CROSS_ORIGIN_ACTIVITY_WRITE_INTERVAL_MS}. The mark is never lowered.
+   * - No (valid) cookie: written as for this session.
+   * - Cookie of another session: left alone (see the module notes); the seq stays above the highest mark
+   *   this page saw for its session.
+   *
+   * Never throws.
+   */
+  claim(sessionId, seq, now = Date.now()) {
+    if (!this.enabled || !sessionId) {
+      return seq;
+    }
+    try {
+      const cookie = this.read(this.jar, now);
+      this.follow(sessionId);
+      const same = cookie?.sessionId === sessionId;
+      const mark = same ? this.plausibleMark(cookie.seqMark, seq) : void 0;
+      if (mark !== void 0) {
+        this.highestSeen = Math.max(this.highestSeen, mark);
+      }
+      if (cookie && !same) {
+        if (seq < this.reservedMark) {
+          return seq;
+        }
+        const next = Math.max(seq, this.highestSeen) + CROSS_ORIGIN_FOREIGN_GAP;
+        this.reservedMark = next + CROSS_ORIGIN_FOREIGN_GAP;
+        this.highestSeen = this.reservedMark;
+        return next;
+      }
+      const renew = seq >= this.reservedMark || mark !== void 0 && mark > this.reservedMark;
+      if (!renew && now - this.lastWriteAt < CROSS_ORIGIN_ACTIVITY_WRITE_INTERVAL_MS) {
+        return seq;
+      }
+      return this.sync(this.jar, cookie, sessionId, seq, now, renew, false).seq;
+    } catch (error) {
+      this.deps.logger.error("Cross-origin session cookie update failed", error);
+      return seq;
+    }
+  }
+  /** A new session of this page (`resetSession`): the cookie starts over with it, without context. */
+  reset(sessionId, now = Date.now()) {
+    if (!this.enabled || !sessionId) {
+      return;
+    }
+    try {
+      this.reservedFor = void 0;
+      this.follow(sessionId);
+      this.sync(this.jar, this.read(this.jar, now), sessionId, 0, now, true, true);
+    } catch (error) {
+      this.deps.logger.error("Cross-origin session cookie reset failed", error);
+    }
+  }
+  /**
+   * Store (or with `undefined` clear) the integration context of `sessionId`; this explicit call may take
+   * the cookie over from another session. `seq` is the page's best known next seq. Returns the next seq the
+   * page must continue at (a renewed reservation can move it up), or `undefined` when nothing was written.
+   */
+  setContext(sessionId, seq, context, now = Date.now()) {
+    if (!this.enabled || !sessionId) {
+      return void 0;
+    }
+    try {
+      const cookie = this.read(this.contextJar, now);
+      this.follow(sessionId);
+      this.context = context;
+      return this.sync(this.contextJar, cookie, sessionId, seq, now, seq >= this.reservedMark, true).seq;
+    } catch (error) {
+      this.deps.logger.error("Cross-origin session context update failed", error);
+      return void 0;
+    }
+  }
+  /** The integration context of `sessionId` (the cookie's when it holds that session, else this page's). */
+  getContext(sessionId, now = Date.now()) {
+    if (!this.enabled || !sessionId) {
+      return void 0;
+    }
+    try {
+      const cookie = this.read(this.contextJar, now);
+      if (cookie?.sessionId === sessionId) {
+        if (this.reservedFor === sessionId) {
+          this.context = cookie.context;
+        }
+        return cookie.context;
+      }
+    } catch (error) {
+      this.deps.logger.error("Cross-origin session context read failed", error);
+    }
+    return this.reservedFor === sessionId ? this.context : void 0;
+  }
+  /** Switch the in-memory state to `sessionId` (fresh reservation, nothing seen, no context) when it changed. */
+  follow(sessionId) {
+    if (this.reservedFor !== sessionId) {
+      this.reservedFor = sessionId;
+      this.reservedMark = 0;
+      this.highestSeen = 0;
+      this.context = void 0;
+    }
+  }
+  /** `mark` when it is plausible next to the page's own counter `seq`; a jump beyond the cap is reported and ignored. */
+  plausibleMark(mark, seq) {
+    if (mark - seq > CROSS_ORIGIN_MAX_SEQ_JUMP) {
+      this.deps.report("info", "cross-origin session: implausible seq mark ignored");
+      return void 0;
+    }
+    return mark;
+  }
+  /**
+   * Merge the cookie (already read) with this page's state and write it back for `sessionId`.
+   *
+   * - `renew`: allocate a new reservation from `seq` (jumping above the cookie's plausible mark of the same
+   *   session and anything seen before). Otherwise the mark only grows.
+   * - `ownContext`: this page's context wins (it was just set); otherwise the cookie's context of the same
+   *   session is taken over.
+   */
+  sync(jar, cookie, sessionId, seq, now, renew, ownContext) {
+    this.follow(sessionId);
+    const same = cookie?.sessionId === sessionId;
+    const cookieMark = same ? this.plausibleMark(cookie.seqMark, seq) : void 0;
+    if (cookieMark !== void 0) {
+      this.highestSeen = Math.max(this.highestSeen, cookieMark);
+    }
+    if (same && !ownContext) {
+      this.context = cookie.context;
+    }
+    let next = seq;
+    let mark;
+    if (renew) {
+      next = Math.max(seq, cookieMark ?? 0, this.highestSeen);
+      mark = next + CROSS_ORIGIN_SEQ_RESERVE;
+    } else {
+      mark = Math.max(this.reservedMark, this.highestSeen, seq);
+    }
+    const value = formatCrossOriginCookie({
+      sessionId,
+      lastActiveAt: now,
+      seqMark: mark,
+      ...this.context !== void 0 && { context: this.context }
+    });
+    this.write(jar, value);
+    if (renew) {
+      this.reservedMark = mark;
+    }
+    this.highestSeen = Math.max(this.highestSeen, mark);
+    this.lastWriteAt = now;
+    return { seq: next, value };
+  }
+  maxAgeSeconds() {
+    return Math.max(60, Math.ceil(this.deps.inactivityMs() / 1e3));
+  }
+  write(jar, value) {
+    jar.write(
+      `${this.name}=${value}; Domain=${this.domain}; Path=/; Max-Age=${this.maxAgeSeconds()}; SameSite=Lax; Secure`
+    );
+  }
+  /** Raw values of every cookie with this name (another path or a host-only copy can shadow it). */
+  rawValues(jar) {
+    const prefix = `${this.name}=`;
+    return jar.read().split(";").map((part) => part.trim()).filter((part) => part.startsWith(prefix)).map((part) => part.substring(prefix.length));
+  }
+  isStored(value) {
+    try {
+      return this.rawValues(this.jar).includes(value);
+    } catch {
+      return false;
+    }
+  }
+  /** The valid, unexpired record with the latest activity, or `undefined`. Throws when the cookie read throws. */
+  read(jar, now) {
+    const inactivityMs = this.deps.inactivityMs();
+    let best;
+    for (const raw of this.rawValues(jar)) {
+      const record = parseCrossOriginCookie(raw);
+      if (record && now - record.lastActiveAt < inactivityMs && record.lastActiveAt <= now + FUTURE_TOLERANCE_MS && (!best || record.lastActiveAt > best.lastActiveAt)) {
+        best = record;
+      }
+    }
+    return best;
+  }
+};
+export {
+  CROSS_ORIGIN_ACTIVITY_WRITE_INTERVAL_MS,
+  CROSS_ORIGIN_CONTEXT_MAX,
+  CROSS_ORIGIN_COOKIE_PREFIX,
+  CROSS_ORIGIN_COOKIE_VERSION,
+  CROSS_ORIGIN_FOREIGN_GAP,
+  CROSS_ORIGIN_MAX_SEQ_JUMP,
+  CROSS_ORIGIN_MAX_SEQ_MARK,
+  CROSS_ORIGIN_SEQ_RESERVE,
+  CrossOriginSession,
+  formatCrossOriginCookie,
+  isValidCrossOriginContext,
+  parseCrossOriginCookie,
+  resolveCrossOriginDomain
+};

package/dist/analysis/queue.mjs

@@ -37,6 +37,7 @@ var RequestQueue = class {
     this.requestConfig = options.requestConfig ?? true;
     this.onConfigReceived = options.onConfigReceived;
     this.getDataPolicy = options.getDataPolicy;
+    this.getCrossOriginSession = options.getCrossOriginSession;
     this.fixedData = options.fixedData === true;
     this.beforeEventBatchSend = options.beforeEventBatchSend;
     this.standaloneDeviceInfo = options.standaloneDeviceInfo;
@@ -105,6 +106,7 @@ var RequestQueue = class {
   requestConfig;
   onConfigReceived;
   getDataPolicy;
+  getCrossOriginSession;
   fixedData;
   beforeEventBatchSend;
   standaloneDeviceInfo;
@@ -487,6 +489,13 @@ var RequestQueue = class {
     if (this.fixedData) {
       batch.meta = { ...batch.meta, fixedData: true };
     }
+    try {
+      const crossOriginSession = this.getCrossOriginSession?.(batch.sessionId);
+      if (crossOriginSession) {
+        batch.meta = { ...batch.meta, crossOriginSession };
+      }
+    } catch {
+    }
     const retryCount = entries.reduce((max, entry) => Math.max(max, entry.attempts), 0);
     if (retryCount > 0) {
       batch.meta = { ...batch.meta, retryCount };

package/dist/analysis/readers/page.mjs

@@ -21,8 +21,12 @@ function readSourcePath(_meta, mode, allow) {
   const search = applySourcePathQuery(window.location.search, mode, allow);
   return `${window.location.pathname}${search}`;
 }
+function readCookieScope(_meta) {
+  return { hostname: window.location.hostname, https: window.location.protocol === "https:" };
+}
 export {
   listenWindow,
+  readCookieScope,
   readDocumentComplete,
   readDocumentHidden,
   readPageUrl,

package/dist/analysis/version.mjs

@@ -1,6 +1,6 @@
 // src/version.ts
 var SDK_NAME = "@corbado/observe";
-var SDK_VERSION = true ? "1.9.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.10.0" : "0.0.0-dev";
 export {
   SDK_NAME,
   SDK_VERSION