@corbado/observe 1.14.1 → 1.15.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @corbado/observe
 
+## 1.15.1
+
+### Patch Changes
+
+- a2cb17d: Collection manifest v2 descriptors (tools-only subpaths `@corbado/observe/manifest`, `@corbado/autocapture/manifest`;
+  data only, nothing changes in the bundles):
+  - Contract (additive, optional): `Conditional` (`when`, now also `"!<switch>"`; `requires` = never-ship item id) on
+    side effects, gateway fields, generated and stored entries; `SideEffect`; stored `deleteOnly`, `note` and
+    `otherwise` (`StoredVariant`: what the entry becomes when its `when` does not hold).
+  - Side effects: `ac:request@1` wraps fetch and XMLHttpRequest; `ac:ceremony@1` wraps navigator.credentials (proxy
+    with `aap`); `sdk:input@1` / `ac:element@1` watch the document for added elements.
+  - Own storage: the private-mode library's temporary test storage is no longer a stored entry (only the
+    `sdk:private-mode@1` side effect); config cache `when: "!static"` (absent from static-config builds); legacy debug keys
+    `deleteOnly` (project-scoped keys); low outbox `when: "durableLowOutbox"` with a not-written variant; cross-origin
+    session cookie and email-link starts carry `requires`.
+  - Texts: password managers ("whether the person is signed in to them", "behavior"), transport IP address and
+    client hints.
+
+## 1.15.0
+
+### Minor Changes
+
+- 41434cb: Collection manifest v2 descriptors: new subpath `@corbado/observe/manifest` (Node ESM: `@corbado/observe/dist/manifest/index.mjs`) with the descriptor contract (`CapabilityDescriptor`, `GatewayDescriptor`), the v2 vocabulary (collection levels, categories, kind ladders) and the descriptors of `sdk:input@1`, `sdk:window@1`, `sdk:password-managers@1`, `sdk:private-mode@1` and the device and transport gateways. Every `never` promise names a proof test in this package. Runtime code never imports the descriptors: the npm, CDN and analysis builds contain none of it (checked by tests and `test:data-guards`). No runtime change.
+- b8ef6fb: Own storage and generated ids in the collection manifest v2 (gaps G2, G3), dark: the build define `__CBO_DATA_RETENTION__ = true` deletes queued events and low events older than 7 days from the outboxes when the tracker starts (never sent) and deletes expired email-link start notes on read instead of only ignoring them. The new tracker plugin `deviceHandleMaxAge(ms)` (a plugin option, not a top-level `init()` option; the autocapture runtime passes it from the static config) replaces an older device handle with a new one. Without the define and the plugin (npm, CDN) nothing changes. `@corbado/observe/manifest` adds the descriptors `sdk:own-storage` (every `cbo_` key with area, scope, ISO 8601 retention, owner and typed contents), `sdk:generated` (device handle, session, tab, page, event ids, counters, passkey stand-ins with lifetime and `exposedTo`, incl. `getSessionId`), `sdk:page` (today's page path, declared honestly) and `sdk:api`, and the device fields of private mode and password managers.
+- 4c509f6: Strict page gateway masking (collection manifest v2, gap G8), dark behind the build define `__CBO_DATA_PAGE_STRICT__`: the SDK's own source path masks every path segment (page templates come from an integration's `fixedSourcePath` policy), masks query parameters without `=` and keys that are not plain names unless allowlisted, and treats `sourcePathQuery: "all"` as `"allowlist"`. Without the define (npm, CDN) nothing changes.
+- 1760522: Static SDK config for builds that fix every switch at build time (collection manifest v2): when a bundler defines `__CBO_SDK_CONFIG__` (the complete reliability config as JSON text), the tracker runs exactly that config, makes no config request, neither reads nor writes the config cache, ignores init `sdkConfig` overrides, and `ConfigManager` is removed from the bundle (about 3.6 KB minified). A fixed `fixedDataConfig.pmd` still wins. Malformed text runs the built-in defaults and never throws. The npm and CDN builds never define it: unchanged.
+- c5fd614: WebAuthn allowlist `ac:ceremony@1` (collection manifest v2, gap G1), dark behind a build define: `ceremonyRequestOptions`, `ceremonyCreationOptions`, `ceremonyAssertionResponse` and `ceremonyCreationResponse` keep only the allowlisted fields in the existing payload format, so the backend parses them unchanged: the challenge becomes zeros of the same length (options and `clientDataJSON`), the signature, `getPublicKey()`, user name / display name / id, PRF results and unknown fields never leave, a present user handle becomes a placeholder (`userHandlePresent` becomes accurate), and credential ids are replaced by page-scoped random stand-ins of the same length unless the per-call option `passkeyReference` is set (`sanitizeRequestOptions` takes an optional second argument for it). Builds that define `__CBO_DATA_CEREMONY__ = true` route the existing `sanitize*` functions to the allowlist and drop the blocklist. Without the define (npm, CDN) the sanitizers are unchanged. The `@corbado/observe/manifest` subpath adds the `ac:ceremony@1` descriptor.
+
+### Patch Changes
+
+- 087d2ad: Debug mode no longer writes `cbo_visibility_change_debug` / `cbo_pagehide_debug` (they held the full, unmasked page
+  address; nothing read them); the script deletes what older versions left there. Manifest descriptors (data only, never
+  in a bundle): the sequence counters are a technical field of each record (`record:sdk.event#seq`, new source kind
+  `record`) instead of a generated id; `cbo_storage_schema` declared in local and session storage, both
+  `cbo_low_outbox_v1` key forms, the private-mode library's localStorage `test` key and its test databases per area;
+  `ac:ceremony@1` names page attributes as a second payload entry point next to request bodies.
+
 ## 1.14.1
 
 ### Patch Changes

package/dist/analysis/config.mjs

@@ -177,6 +177,23 @@ function resolveReliabilityConfig(serverConfig, overrides = {}) {
   resolved.retry.maxDelayMs = Math.max(resolved.retry.baseDelayMs, resolved.retry.maxDelayMs);
   return resolved;
 }
+var STATIC_CONFIG_VERSION = "static";
+function staticReliabilityConfig(json, pmd) {
+  let value;
+  try {
+    value = JSON.parse(json);
+  } catch {
+    value = void 0;
+  }
+  const valid = !!value && typeof value === "object" && !Array.isArray(value);
+  const fields = valid ? value : {};
+  const config = resolveReliabilityConfig(void 0, {
+    ...fields,
+    version: typeof fields.version === "string" && fields.version !== "" ? fields.version : STATIC_CONFIG_VERSION,
+    ...pmd !== void 0 && { pmd }
+  });
+  return { config, valid };
+}
 function resolveFixedDataConfig(raw) {
   try {
     if (!raw || typeof raw !== "object") {
@@ -215,10 +232,12 @@ export {
   DEFAULT_RELIABILITY_CONFIG,
   DEFAULT_SEQ_LOCK_TIMEOUT_MS,
   DEFAULT_SESSION_INACTIVITY_MS,
+  STATIC_CONFIG_VERSION,
   cacheConfigRecord,
   loadCachedConfig,
   loadConfigRecord,
   parseReliabilityConfig,
   resolveFixedDataConfig,
-  resolveReliabilityConfig
+  resolveReliabilityConfig,
+  staticReliabilityConfig
 };

package/dist/analysis/device.mjs

@@ -59,7 +59,7 @@ async function settlesWithin(promise, timeoutMs) {
   }
 }
 var DeviceCollector = class {
-  constructor(logger, storage, storageSource = "localstorage", sessionStorage, settings = () => DEFAULT_SETTINGS, emitTelemetry, privateModeEnabled = true) {
+  constructor(logger, storage, storageSource = "localstorage", sessionStorage, settings = () => DEFAULT_SETTINGS, emitTelemetry, privateModeEnabled = true, deviceHandleMaxAgeMs) {
     this.logger = logger;
     this.storage = storage;
     this.storageSource = storageSource;
@@ -67,6 +67,7 @@ var DeviceCollector = class {
     this.settings = settings;
     this.emitTelemetry = emitTelemetry;
     this.privateModeEnabled = privateModeEnabled;
+    this.deviceHandleMaxAgeMs = deviceHandleMaxAgeMs;
   }
   /** privateMode known on this page (from the cache or a detection), reused by every refresh. */
   pagePrivateMode;
@@ -525,7 +526,8 @@ var DeviceCollector = class {
   }
   getClientEnvHandle() {
     const existingClientEnvHandle = this.storage.getItem("cbo_client_env_handle");
-    if (existingClientEnvHandle) {
+    const maxAgeMs = this.deviceHandleMaxAgeMs;
+    if (existingClientEnvHandle && !(maxAgeMs !== void 0 && !(Date.now() - existingClientEnvHandle.timestamp <= maxAgeMs))) {
       return existingClientEnvHandle;
     }
     const newClientEnvHandleValue = uuidv7();

package/dist/analysis/index.mjs

@@ -13,6 +13,7 @@ export * from "./plugins/raw-errors.mjs";
 export * from "./plugins/probes.mjs";
 export * from "./plugins/fixed-source-path.mjs";
 export * from "./plugins/event-time.mjs";
+export * from "./plugins/device-handle-max-age.mjs";
 export * from "./probe-lane.mjs";
 export * from "./transport.mjs";
 export * from "./queue.mjs";
@@ -53,6 +54,12 @@ import {
   sanitizeRequestOptions,
   sanitizeAssertionResponse
 } from "./utils/webauthn-payloads.mjs";
+import {
+  ceremonyCreationOptions,
+  ceremonyRequestOptions,
+  ceremonyCreationResponse,
+  ceremonyAssertionResponse
+} from "./utils/webauthn-ceremony.mjs";
 function init(options) {
   const tracker = new CorbadoTracker(options);
   setDefaultTracker(tracker);
@@ -93,6 +100,10 @@ export {
   READER_EXPOSURES,
   SDK_NAME,
   SDK_VERSION,
+  ceremonyAssertionResponse,
+  ceremonyCreationOptions,
+  ceremonyCreationResponse,
+  ceremonyRequestOptions,
   destroy,
   detectPasswordManagerExtensions,
   getExperiments,

package/dist/analysis/plugins/device-handle-max-age.mjs

@@ -0,0 +1,8 @@
+// src/plugins/device-handle-max-age.ts
+function deviceHandleMaxAge(maxAgeMs) {
+  if (typeof maxAgeMs !== "number" || !Number.isFinite(maxAgeMs) || maxAgeMs <= 0) return {};
+  return { deviceHandleMaxAgeMs: maxAgeMs };
+}
+export {
+  deviceHandleMaxAge
+};

package/dist/analysis/queue.mjs

@@ -3,7 +3,7 @@ import { v7 as uuidv7 } from "uuid";
 import { AuthEventName } from "./types.mjs";
 import { CONFIG_REQUEST_HEADER, DEFAULT_RELIABILITY_CONFIG } from "./config.mjs";
 import { EventStore } from "./store/event-store.mjs";
-import { listenWindow, readDocumentHidden, readPageUrl } from "./readers/page.mjs";
+import { listenWindow, readDocumentHidden } from "./readers/page.mjs";
 var UNLOAD_BUDGET_BYTES = 6e4;
 var UNLOAD_PROBE_BYTES = 32e3;
 function utf8Length(text) {
@@ -19,6 +19,7 @@ function utf8Length(text) {
   }
   return bytes;
 }
+var LEGACY_DEBUG_KEYS = ["cbo_visibility_change_debug", "cbo_pagehide_debug"];
 var RequestQueue = class {
   constructor(logger, transport, sessionId, sdk, options = {}, storage) {
     this.logger = logger;
@@ -44,6 +45,7 @@ var RequestQueue = class {
       this.pending = this.store.all();
     }
     if (this.storage) {
+      for (const key of LEGACY_DEBUG_KEYS) this.storage.removeItem(key);
       this.lowStore = new EventStore(
         this.storage,
         this.logger,
@@ -636,7 +638,6 @@ var RequestQueue = class {
     if (typeof window === "undefined") return;
     this.onVisibilityChange = () => {
       try {
-        this.writeLifecycleDebugOutput("cbo_visibility_change_debug");
         if (readDocumentHidden({
           key: "page:lifecycle.visibility",
           title: "Page visibility",
@@ -661,7 +662,6 @@ var RequestQueue = class {
     };
     this.onPageHide = () => {
       try {
-        this.writeLifecycleDebugOutput("cbo_pagehide_debug");
         if (this.config.tph) {
           this.flushSync("pagehide");
         }
@@ -710,31 +710,6 @@ var RequestQueue = class {
       this.onPageHide
     );
   }
-  writeLifecycleDebugOutput(key) {
-    if (!this.debug || !this.storage) {
-      return;
-    }
-    const output = {
-      last_executed: Date.now(),
-      url: readPageUrl({
-        key: "page:location.url",
-        title: "Page address (debug output only)",
-        accessNote: "location.href, only written to the debug log",
-        group: "Page",
-        origin: "observe-external",
-        fields: [
-          {
-            path: "url",
-            label: "Full page address",
-            category: "technical",
-            exposure: "raw",
-            transform: { note: "debug mode only; written to own localStorage, never sent" }
-          }
-        ]
-      })
-    };
-    this.storage.setItem(key, output);
-  }
   /**
    * Synchronously flush pending events (and best-effort lows) during page unload.
    *

package/dist/analysis/readers/page.mjs

@@ -1,5 +1,5 @@
 // src/readers/page.ts
-import { applySourcePathQuery } from "../utils/source-path.mjs";
+import { applySourcePathQuery, applyStrictSourcePathQuery, maskPathSegments } from "../utils/source-path.mjs";
 function listenWindow(_meta, type, handler, options) {
   if (options === void 0) {
     window.addEventListener(type, handler);
@@ -18,6 +18,9 @@ function readPageUrl(_meta) {
   return window.location.href;
 }
 function readSourcePath(_meta, mode, allow) {
+  if (typeof __CBO_DATA_PAGE_STRICT__ === "boolean" && __CBO_DATA_PAGE_STRICT__) {
+    return `${maskPathSegments(window.location.pathname)}${applyStrictSourcePathQuery(window.location.search, allow)}`;
+  }
   const search = applySourcePathQuery(window.location.search, mode, allow);
   return `${window.location.pathname}${search}`;
 }

package/dist/analysis/store/event-store.mjs

@@ -4,6 +4,14 @@ var OUTBOX_STORAGE_KEY = "cbo_outbox";
 var OUTBOX_LOCK_NAME = "cbo_outbox";
 var DEFAULT_MAX_ENTRIES = 500;
 var DEFAULT_MAX_SERIALIZED_LENGTH = 512 * 1024;
+var OUTBOX_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+function outboxEntryTime(entry) {
+  const event = entry.event;
+  const time = typeof event.timestamp === "number" ? event.timestamp : event.ts;
+  if (typeof time === "number" && Number.isFinite(time)) return time;
+  const hex = /^([0-9a-f]{8})-?([0-9a-f]{4})-?7/i.exec(entry.id);
+  return hex ? parseInt(hex[1] + hex[2], 16) : void 0;
+}
 function isOutboxEntry(value) {
   if (!value || typeof value !== "object") {
     return false;
@@ -20,10 +28,23 @@ var EventStore = class {
     this.lockName = lockName;
     this.storageKey = storageKey;
     this.entries = this.read();
+    if (typeof __CBO_DATA_RETENTION__ === "boolean" && __CBO_DATA_RETENTION__) this.purgeExpired(Date.now());
   }
   entries = [];
   /** Malformed entries are dropped on every read; report only once per instance to avoid log spam. */
   reportedMalformed = false;
+  /** Deletes entries older than {@link OUTBOX_MAX_AGE_MS} (they are never sent). Never throws. */
+  purgeExpired(now) {
+    const expired = (entry) => {
+      const time = outboxEntryTime(entry);
+      return time !== void 0 && now - time > OUTBOX_MAX_AGE_MS;
+    };
+    if (!this.entries.some(expired)) return;
+    const count = this.entries.filter(expired).length;
+    this.entries = this.entries.filter((entry) => !expired(entry));
+    this.logger.debug(`EventStore deleted ${count} entries past the retention limit`);
+    void this.mutate((current) => current.filter((entry) => !expired(entry)));
+  }
   read() {
     const raw = this.storage.getItem(this.storageKey);
     if (!Array.isArray(raw)) {
@@ -129,5 +150,7 @@ export {
   DEFAULT_MAX_SERIALIZED_LENGTH,
   EventStore,
   OUTBOX_LOCK_NAME,
-  OUTBOX_STORAGE_KEY
+  OUTBOX_MAX_AGE_MS,
+  OUTBOX_STORAGE_KEY,
+  outboxEntryTime
 };

package/dist/analysis/tracker-core.mjs

@@ -16,6 +16,7 @@ import { migrateLegacyStorage } from "./storage/migration.mjs";
 import {
   DEFAULT_RELIABILITY_CONFIG,
   resolveFixedDataConfig,
+  staticReliabilityConfig,
   resolveReliabilityConfig
 } from "./config.mjs";
 import { ConfigManager } from "./config-manager.mjs";
@@ -91,25 +92,31 @@ var CorbadoTrackerCore = class _CorbadoTrackerCore {
     if (this.fixedData) {
       this.configOverrides.pmd = this.fixedData.pmd;
     }
-    const completeOverride = Object.keys(DEFAULT_RELIABILITY_CONFIG).every(
-      (key) => this.configOverrides[key] !== void 0
-    ) && Object.keys(DEFAULT_RELIABILITY_CONFIG.retry).every(
-      (key) => this.configOverrides.retry?.[key] !== void 0
-    );
-    if (!completeOverride) {
-      this.configManager = new ConfigManager(
-        options.apiBaseUrl + (options.apiConfigPath ?? "/v1/observe/config") + "/" + options.projectId,
-        this.persistentStorage,
-        this.logger
+    if (typeof __CBO_SDK_CONFIG__ === "string") {
+      const fixed = staticReliabilityConfig(__CBO_SDK_CONFIG__, this.fixedData?.pmd);
+      this.config = fixed.config;
+      if (!fixed.valid) this.logger.error("Invalid static SDK config: running the built-in defaults");
+    } else {
+      const completeOverride = Object.keys(DEFAULT_RELIABILITY_CONFIG).every(
+        (key) => this.configOverrides[key] !== void 0
+      ) && Object.keys(DEFAULT_RELIABILITY_CONFIG.retry).every(
+        (key) => this.configOverrides.retry?.[key] !== void 0
       );
-    }
-    const cachedConfig = this.configManager?.initialConfig;
-    this.config = resolveReliabilityConfig(cachedConfig, this.configOverrides);
-    if (!completeOverride && !cachedConfig && options.flushInterval != null && this.configOverrides.flushIntervalMs === void 0) {
-      this.config = { ...this.config, flushIntervalMs: options.flushInterval };
-    }
-    if (!completeOverride && !cachedConfig && options.deviceInfoCollectorTimeout != null && this.configOverrides.deviceInfoCollectorTimeoutMs === void 0) {
-      this.config = { ...this.config, deviceInfoCollectorTimeoutMs: options.deviceInfoCollectorTimeout };
+      if (!completeOverride) {
+        this.configManager = new ConfigManager(
+          options.apiBaseUrl + (options.apiConfigPath ?? "/v1/observe/config") + "/" + options.projectId,
+          this.persistentStorage,
+          this.logger
+        );
+      }
+      const cachedConfig = this.configManager?.initialConfig;
+      this.config = resolveReliabilityConfig(cachedConfig, this.configOverrides);
+      if (!completeOverride && !cachedConfig && options.flushInterval != null && this.configOverrides.flushIntervalMs === void 0) {
+        this.config = { ...this.config, flushIntervalMs: options.flushInterval };
+      }
+      if (!completeOverride && !cachedConfig && options.deviceInfoCollectorTimeout != null && this.configOverrides.deviceInfoCollectorTimeoutMs === void 0) {
+        this.config = { ...this.config, deviceInfoCollectorTimeoutMs: options.deviceInfoCollectorTimeout };
+      }
     }
     if (options.apiBaseUrl !== "") {
       if (!/^https?:\/\//.test(options.apiBaseUrl)) {
@@ -134,6 +141,7 @@ var CorbadoTrackerCore = class _CorbadoTrackerCore {
       if (plugin.rawErrors) this.rawErrors = plugin.rawErrors;
       if (typeof plugin.sourcePath === "function") this.fixedSourcePath = plugin.sourcePath;
       if (plugin.eventTime) this.eventClock = plugin.eventTime;
+      if (plugin.deviceHandleMaxAgeMs !== void 0) this.deviceHandleMaxAgeMs = plugin.deviceHandleMaxAgeMs;
     });
     if (options.fixedDataConfig?.crossOriginSession && !this.bridge) {
       this.logger.warn("fixedDataConfig.crossOriginSession is ignored without the crossOriginSession() plugin");
@@ -196,7 +204,8 @@ var CorbadoTrackerCore = class _CorbadoTrackerCore {
       // rather than reportTelemetry: the latter dedupes by exact message and is capped per load,
       // where ever-changing messages would crowd out real error diagnostics.
       (level, message) => this.telemetry(level, message),
-      this.fixedData?.privateMode ?? true
+      this.fixedData?.privateMode ?? true,
+      this.deviceHandleMaxAgeMs
     );
     this.deviceCollector = deviceInfoCollector;
     const deviceInfoDebounceTime = options.deviceInfoDebounceTime ?? 3e4;
@@ -276,6 +285,8 @@ var CorbadoTrackerCore = class _CorbadoTrackerCore {
   fixedSourcePath;
   /** Event clock of a plugin (never throws); undefined or an undefined result = `explicitTimestamp ?? Date.now()`. */
   eventClock;
+  /** Device-handle maximum of a plugin; undefined = no maximum. */
+  deviceHandleMaxAgeMs;
   /** @internal Shared passive page observation and per-operation context registration. */
   getWindowObserver() {
     return this.windowObserver ??= new SharedWindowObserver(

package/dist/analysis/utils/email-link-continuity.mjs

@@ -5,9 +5,14 @@ var MAX_ENTRIES = 10;
 function read(storage, now) {
   const raw = storage.getItem(EMAIL_LINK_STARTS_STORAGE_KEY);
   if (!Array.isArray(raw)) return [];
-  return raw.filter(
+  const valid = raw.filter(
     (entry) => !!entry && typeof entry === "object" && typeof entry.transactionId === "string" && typeof entry.anchor === "string" && typeof entry.sessionId === "string" && typeof entry.startedAt === "number" && now - entry.startedAt < EMAIL_LINK_START_TTL_MS
   );
+  if (typeof __CBO_DATA_RETENTION__ === "boolean" && __CBO_DATA_RETENTION__ && valid.length < raw.length) {
+    if (valid.length === 0) storage.removeItem(EMAIL_LINK_STARTS_STORAGE_KEY);
+    else storage.setItem(EMAIL_LINK_STARTS_STORAGE_KEY, valid);
+  }
+  return valid;
 }
 function rememberEmailLinkStart(storage, entry) {
   if (!storage) return;

package/dist/analysis/utils/source-path.mjs

@@ -33,7 +33,29 @@ function applySourcePathQuery(search, mode, allow) {
   });
   return `?${masked.join("&")}`;
 }
+var PLAIN_KEY = /^[A-Za-z][A-Za-z0-9_.\-[\]]{0,63}$/;
+function applyStrictSourcePathQuery(search, allow) {
+  if (search === "" || search === "?") return search;
+  const query = search.startsWith("?") ? search.slice(1) : search;
+  const masked = query.split("&").map((pair) => {
+    if (pair === "") return pair;
+    const separator = pair.indexOf("=");
+    const rawKey = separator === -1 ? pair : pair.slice(0, separator);
+    const key = decodeKey(rawKey);
+    if (isAllowed(key, allow)) return pair;
+    if (separator === -1) return MASKED_QUERY_VALUE;
+    const name = PLAIN_KEY.test(key) ? rawKey : MASKED_QUERY_VALUE;
+    return pair.length === separator + 1 ? `${name}=` : `${name}=${MASKED_QUERY_VALUE}`;
+  });
+  return `?${masked.join("&")}`;
+}
+function maskPathSegments(path) {
+  const segments = String(path ?? "").split("/").filter((segment) => segment !== "");
+  return segments.length === 0 ? "/" : "/" + segments.map(() => MASKED_QUERY_VALUE).join("/");
+}
 export {
   MASKED_QUERY_VALUE,
-  applySourcePathQuery
+  applySourcePathQuery,
+  applyStrictSourcePathQuery,
+  maskPathSegments
 };