@formo/analytics 1.33.1 → 1.34.0

package/dist/esm/src/event/EventFactory.js

@@ -64,6 +64,7 @@ import mergeDeepRight from "../ramda/mergeDeepRight";
 import { session } from "../storage";
 import { version } from "../version";
 import { CHANNEL, CLICK_ID_PARAMS, DEFAULT_EXCLUDED_QUERY_PARAMS, DEFAULT_REFERRAL_PARAMS, PAGE_PROPERTIES_EXCLUDED_FIELDS, VERSION, } from "./constants";
+import { sanitizeTrafficSources } from "./sanitize";
 import { generateAnonymousId } from "./utils";
 import { detectBrowser } from "../browser/browsers";
 var ISO_3166_ALPHA_2_REGEX = /^[A-Z]{2}$/;
@@ -132,7 +133,7 @@ var EventFactory = /** @class */ (function () {
         /**
          * Returns the document referrer with same-host referrers filtered out.
          * Internal navigation populates `document.referrer` with the previous page
-         * on the same site, which is not an attribution signal — treating it as
+         * on the same site, which is not an attribution signal - treating it as
          * "external" would otherwise let an internal URL become the session's
          * first-touch referrer after a direct landing.
          */
@@ -151,12 +152,16 @@ var EventFactory = /** @class */ (function () {
         };
         this.getTrafficSources = function (url) {
             var urlObj = new URL(url);
-            var contextTrafficSources = __assign(__assign(__assign({}, _this.extractUTMParameters(url)), _this.extractClickIdParameters(urlObj)), { ref: _this.extractReferralParameter(urlObj), referrer: _this.getExternalReferrer() });
+            // Sanitize at the source so scanner-injected garbage (XSS probes in
+            // utm_*/click-id/ref query params) never wins the context-over-stored
+            // merge below, never gets persisted, and never reaches an event.
+            var contextTrafficSources = sanitizeTrafficSources(__assign(__assign(__assign({}, _this.extractUTMParameters(url)), _this.extractClickIdParameters(urlObj)), { ref: _this.extractReferralParameter(urlObj), referrer: _this.getExternalReferrer() }));
             // Sticky traffic sources may have been persisted by an older SDK version or
             // a looser config, before the current excludeQueryParams was in effect.
             // Honor the current denylist on the way out so excluded values can never
-            // resurface from session storage (or get re-persisted below).
-            var storedTrafficSources = _this.redactStoredTrafficSources(session().get(SESSION_TRAFFIC_SOURCE_KEY) || {});
+            // resurface from session storage (or get re-persisted below). Sanitizing
+            // here too flushes poisoned values persisted by a pre-sanitization SDK.
+            var storedTrafficSources = sanitizeTrafficSources(_this.redactStoredTrafficSources(session().get(SESSION_TRAFFIC_SOURCE_KEY) || {}));
             var mergedClickIds = {};
             for (var _i = 0, CLICK_ID_PARAMS_2 = CLICK_ID_PARAMS; _i < CLICK_ID_PARAMS_2.length; _i++) {
                 var p = CLICK_ID_PARAMS_2[_i];
@@ -587,8 +592,9 @@ var EventFactory = /** @class */ (function () {
     EventFactory.prototype.create = function (event, address, userId) {
         return __awaiter(this, void 0, void 0, function () {
             var formoEvent, _a, chainId;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
+            var _b, _c;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
                     case 0:
                         formoEvent = {};
                         _a = event.type;
@@ -606,39 +612,39 @@ var EventFactory = /** @class */ (function () {
                         return [3 /*break*/, 17];
                     case 1: return [4 /*yield*/, this.generatePageEvent(event.category, event.name, event.properties, event.context)];
                     case 2:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 3: return [4 /*yield*/, this.generateDetectWalletEvent(event.providerName, event.rdns, event.properties, event.context)];
                     case 4:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 5: return [4 /*yield*/, this.generateIdentifyEvent(event.providerName, event.rdns, event.address, event.userId, event.properties, event.context)];
                     case 6:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 7: return [4 /*yield*/, this.generateChainChangedEvent(event.chainId, event.address, event.properties, event.context)];
                     case 8:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 9: return [4 /*yield*/, this.generateConnectEvent(event.chainId, event.address, event.properties, event.context)];
                     case 10:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 11: return [4 /*yield*/, this.generateDisconnectEvent(event.chainId, event.address, event.properties, event.context)];
                     case 12:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 13: return [4 /*yield*/, this.generateSignatureEvent(event.status, event.chainId, event.address, event.message, event.properties, event.context)];
                     case 14:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 15: return [4 /*yield*/, this.generateTransactionEvent(event.status, event.chainId, event.address, event.data, event.to, event.value, event.transactionHash, event.function_name, event.function_args, event.properties, event.context)];
                     case 16:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 17: return [4 /*yield*/, this.generateTrackEvent(event.event, event.properties, event.context)];
                     case 18:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 19:
                         // Set address if not already set by the specific event generator
@@ -649,7 +655,17 @@ var EventFactory = /** @class */ (function () {
                             chainId = 'chainId' in event ? event.chainId : undefined;
                             formoEvent.address = this.validateEventAddress(address, chainId);
                         }
-                        formoEvent.user_id = userId || null;
+                        // An identify event asserts an explicit identity in its own payload (e.g. a
+                        // Privy DID for each wallet being clustered). Keep that payload user_id
+                        // rather than overwriting it with the active-session user id - otherwise a
+                        // clustering identify that intentionally leaves the active user unchanged
+                        // (setActive:false) would be stripped of its DID, defeating server-side
+                        // wallet clustering. Fall back to the active-session user id when the
+                        // identify payload carries none; all other events use the session user id.
+                        formoEvent.user_id =
+                            event.type === "identify"
+                                ? (_c = (_b = formoEvent.user_id) !== null && _b !== void 0 ? _b : userId) !== null && _c !== void 0 ? _c : null
+                                : userId || null;
                         return [2 /*return*/, formoEvent];
                 }
             });

package/dist/esm/src/event/sanitize.d.ts

@@ -0,0 +1,13 @@
+import { ITrafficSource } from "../types";
+declare const sanitizeClickId: (value: string) => string;
+declare const sanitizeRef: (value: string) => string;
+declare const sanitizeUtm: (value: string) => string;
+/**
+ * Sanitize every traffic-source field of a (possibly sparse) traffic-source
+ * object. `referrer` is left untouched: it is a browser-set URL already
+ * handled by redactUrl, not an attacker-controlled query parameter. Unknown
+ * keys fall through to the UTM rule, the most permissive one.
+ */
+declare const sanitizeTrafficSources: <T extends Partial<ITrafficSource>>(trafficSources: T) => T;
+export { sanitizeClickId, sanitizeRef, sanitizeUtm, sanitizeTrafficSources };
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/esm/src/event/sanitize.js

@@ -0,0 +1,88 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+import { CLICK_ID_PARAMS } from "./constants";
+/**
+ * Traffic-source value sanitization.
+ *
+ * Vulnerability scanners (e.g. Acunetix) crawl customer sites injecting XSS
+ * probes such as `javascript:domxssExecutionSink(1,"'\"><xsstag>()locxss")`
+ * or `<script>alert(1)</script>` into every query parameter. Without
+ * validation those payloads are captured verbatim as utm_* / click-id / ref
+ * values, persisted as sticky session traffic sources, and pollute the
+ * customer's attribution reporting. Each field class gets the tightest rule
+ * its legitimate values allow (verified against production data):
+ *
+ * - Click IDs are opaque platform-generated tokens (base64url-ish); every
+ *   legitimate production value matches the strict token pattern.
+ * - Referral codes are short tokens; >99.5% of production values match the
+ *   strict pattern and none of the remainder are legitimate (scanner
+ *   payloads, mangled encodings, URLs glued to codes).
+ * - UTM values are free-form (spaces, unicode, `+` are legitimate), so they
+ *   only reject markup/quote characters, dangerous URL schemes, control and
+ *   zero-width characters, and absurd lengths.
+ *
+ * Invalid values are dropped to "" — the same representation as "parameter
+ * absent" — rather than repaired, so a poisoned value can never be persisted
+ * or reported.
+ */
+var CLICK_ID_PATTERN = /^[A-Za-z0-9._-]{1,255}$/;
+var REF_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+var UTM_MAX_LENGTH = 255;
+// Markup/quote/backslash characters plus C0/C1 control characters and
+// zero-width / bidi / BOM / replacement characters (mangled-encoding
+// markers). Explicit ranges instead of \p{C} to avoid the `u`-flag
+// property-escape requirement.
+var UTM_FORBIDDEN_CHARS = /[<>"'`\\\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060\ufeff\ufffd]/;
+// Values smuggling an executable/URL scheme, e.g. `javascript:alert(1)`.
+var FORBIDDEN_SCHEME_PREFIX = /^\s*(javascript|data|vbscript):/i;
+var sanitizeClickId = function (value) {
+    return CLICK_ID_PATTERN.test(value) ? value : "";
+};
+var sanitizeRef = function (value) {
+    return REF_PATTERN.test(value) ? value : "";
+};
+var sanitizeUtm = function (value) {
+    return value.length <= UTM_MAX_LENGTH &&
+        !UTM_FORBIDDEN_CHARS.test(value) &&
+        !FORBIDDEN_SCHEME_PREFIX.test(value)
+        ? value
+        : "";
+};
+var CLICK_ID_KEYS = new Set(CLICK_ID_PARAMS);
+/**
+ * Sanitize every traffic-source field of a (possibly sparse) traffic-source
+ * object. `referrer` is left untouched: it is a browser-set URL already
+ * handled by redactUrl, not an attacker-controlled query parameter. Unknown
+ * keys fall through to the UTM rule, the most permissive one.
+ */
+var sanitizeTrafficSources = function (trafficSources) {
+    var result = __assign({}, trafficSources);
+    for (var _i = 0, _a = Object.keys(result); _i < _a.length; _i++) {
+        var key = _a[_i];
+        var value = result[key];
+        if (typeof value !== "string" || value === "" || key === "referrer") {
+            continue;
+        }
+        if (CLICK_ID_KEYS.has(key)) {
+            result[key] = sanitizeClickId(value);
+        }
+        else if (key === "ref") {
+            result[key] = sanitizeRef(value);
+        }
+        else {
+            result[key] = sanitizeUtm(value);
+        }
+    }
+    return result;
+};
+export { sanitizeClickId, sanitizeRef, sanitizeUtm, sanitizeTrafficSources };
+//# sourceMappingURL=sanitize.js.map

package/dist/esm/src/privy/index.d.ts

@@ -1,9 +1,14 @@
 /**
  * Privy integration module
  *
- * Provides utilities for enriching wallet profiles with Privy user data.
- * This module exports the property extraction utility and related types.
+ * Provides utilities for enriching wallet profiles with Privy user data:
+ * `parsePrivyProperties` (low-level parsing) and `identifyPrivyUser` (identify
+ * every linked wallet under the user's DID). The same behavior is also
+ * available as `formo.identify(user, { privy: true })`.
+ *
+ * This module is React-free so it can be used from the `core` entry.
  */
-export { parsePrivyProperties } from "./utils";
+export { parsePrivyProperties, identifyPrivyUser } from "./utils";
+export type { IdentifyPrivyUserOptions } from "./utils";
 export type { PrivyUser, PrivyLinkedAccount, PrivyAccountType, PrivyProfileProperties, PrivyWalletInfo, } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/src/privy/index.js

@@ -1,8 +1,12 @@
 /**
  * Privy integration module
  *
- * Provides utilities for enriching wallet profiles with Privy user data.
- * This module exports the property extraction utility and related types.
+ * Provides utilities for enriching wallet profiles with Privy user data:
+ * `parsePrivyProperties` (low-level parsing) and `identifyPrivyUser` (identify
+ * every linked wallet under the user's DID). The same behavior is also
+ * available as `formo.identify(user, { privy: true })`.
+ *
+ * This module is React-free so it can be used from the `core` entry.
  */
-export { parsePrivyProperties } from "./utils";
+export { parsePrivyProperties, identifyPrivyUser } from "./utils";
 //# sourceMappingURL=index.js.map

package/dist/esm/src/privy/types.d.ts

@@ -38,6 +38,16 @@ export interface PrivyLinkedAccount {
     telegramUserId?: string | null;
     firstName?: string | null;
     lastName?: string | null;
+    credentialId?: string | null;
+    customUserId?: string | null;
+    embeddedWallets?: Array<{
+        address: string;
+        chainType?: string | null;
+    }> | null;
+    smartWallets?: Array<{
+        address: string;
+        chainType?: string | null;
+    }> | null;
     firstVerifiedAt?: Date | null;
     latestVerifiedAt?: Date | null;
 }
@@ -51,8 +61,12 @@ export interface PrivyLinkedAccount {
 export interface PrivyUser {
     /** Privy user ID in DID format (e.g., "did:privy:cm3np...") */
     id: string;
-    /** Account creation timestamp */
-    createdAt?: Date;
+    /**
+     * Account creation timestamp. Privy's React SDK supplies a `Date`, but a user
+     * object from the REST API or one that made a JSON round-trip carries an ISO
+     * string or epoch number, so all three are accepted and normalized.
+     */
+    createdAt?: Date | string | number;
     /** All linked accounts */
     linkedAccounts?: PrivyLinkedAccount[];
     /** Optional custom metadata */
@@ -123,6 +137,11 @@ export interface PrivyUser {
         username: string | null;
         name: string | null;
     };
+    /** Privy's Twitch account exposes only subject/username - no email. */
+    twitch?: {
+        subject: string;
+        username: string | null;
+    };
     line?: {
         subject: string;
         name: string | null;
@@ -150,9 +169,11 @@ export interface PrivyProfileProperties {
     privyDid: string;
     privyCreatedAt?: number;
     email?: string;
+    phone?: string;
     apple?: string;
     discord?: string;
     twitter?: string;
+    twitch?: string;
     farcaster?: string;
     github?: string;
     google?: string;
@@ -162,6 +183,8 @@ export interface PrivyProfileProperties {
     telegram?: string;
     tiktok?: string;
     instagram?: string;
+    /** The `customUserId` of a linked `custom_auth` account, when present. */
+    customUserId?: string;
     [key: string]: unknown;
 }
 /**

package/dist/esm/src/privy/utils.d.ts

@@ -2,12 +2,19 @@
  * Utility functions for extracting profile properties from Privy user objects.
  */
 import { PrivyProfileProperties, PrivyUser, PrivyWalletInfo } from "./types";
+import { IFormoAnalytics } from "../types/base";
+import { IFormoEventProperties } from "../types/events";
 /**
  * Extract profile properties and wallet addresses from a Privy user object.
  *
  * Parses the Privy user's linked accounts into a flat properties object
  * (email, social accounts, etc.) and extracts all linked wallet addresses.
  *
+ * For most apps prefer the {@link identifyPrivyUser} one-liner, which builds on
+ * this function and also forwards per-wallet metadata and handles event
+ * attribution. Use `parsePrivyProperties` directly only for advanced/custom
+ * flows.
+ *
  * @param user - The Privy user object from `usePrivy()`
  * @returns An object with `properties` and `wallets`
  *
@@ -29,4 +36,97 @@ export declare function parsePrivyProperties(user: PrivyUser): {
     properties: PrivyProfileProperties;
     wallets: PrivyWalletInfo[];
 };
+/**
+ * Options for {@link identifyPrivyUser}.
+ */
+export interface IdentifyPrivyUserOptions {
+    /**
+     * Optional override for the wallet that should own event attribution - the
+     * one promoted to the SDK's current address/user, while every other linked
+     * wallet is recorded only for clustering.
+     *
+     * You usually don't need this. When omitted, the helper first uses the wallet
+     * the SDK already treats as active (a prior wagmi/EIP-1193 connect), then
+     * Privy's own surfaced wallet (`user.wallet`), then a best-effort guess
+     * (embedded wallets deprioritized, so the last external wallet). Pass it only
+     * when you want to pin attribution to a specific wallet - e.g. the currently
+     * connected wallet from `useWallets()[0]?.address`, which reflects the live
+     * active wallet more precisely than `user.wallet`.
+     *
+     * Matched strictly: if it doesn't correspond to one of the user's linked
+     * wallets, no wallet is promoted and the SDK's current wallet is left as-is
+     * (so a connected wallet that isn't linked in Privy is preserved).
+     */
+    activeAddress?: string;
+    /**
+     * Extra properties merged into every identify call, on top of the profile
+     * properties parsed from the Privy user (email, socials, DID, …) and the
+     * per-wallet metadata (`wallet_client`, `chain_type`, `is_embedded`).
+     *
+     * Identify events are deduped per `(wallet, user, properties)` within a
+     * session, so changing these properties re-emits with the updated profile
+     * rather than being swallowed. The flip side: a value that changes on every
+     * call (a timestamp, a random id) makes every identify a new event. Pass
+     * stable identity metadata here and put volatile values on `track()` events.
+     */
+    properties?: IFormoEventProperties;
+}
+/**
+ * Identify every wallet linked to a Privy user under that user's Privy DID.
+ *
+ * This is the one-liner replacement for hand-rolling a loop over
+ * {@link parsePrivyProperties}. For each linked wallet it calls
+ * `analytics.identify({ address, userId: user.id }, …)` with the shared
+ * profile properties plus that wallet's `wallet_client`, `chain_type`, and
+ * `is_embedded` metadata. Because every wallet is tagged with the same Privy
+ * `userId`, Formo can cluster them server-side into a single user.
+ *
+ * Attribution: only the active wallet (see
+ * {@link IdentifyPrivyUserOptions.activeAddress}) promotes the SDK's current
+ * address/user; every other linked wallet is recorded purely for clustering and
+ * does not repoint attribution. Because the clustering identifies don't touch
+ * active state, a connected wallet that isn't linked in Privy is left untouched
+ * rather than overwritten. This does not change the public `identify()` API.
+ *
+ * Before emitting, it reconciles the SDK's chain id with the active wallet's
+ * chain namespace (clearing a stale EVM chain id when a Solana wallet becomes
+ * active, and vice versa), so identifies aren't dropped by an `excludeChains`
+ * gate and later events aren't paired with the wrong chain. This happens here,
+ * so the direct helper and the `formo.identify(user, { privy: true })` form
+ * behave identically.
+ *
+ * Returns the active linked wallet's `{ address, chainType }` (the one now
+ * owning attribution), or `undefined` when no linked wallet matched the
+ * requested active address (or the user had no wallets).
+ *
+ * All linked wallet addresses used here come from `user.linkedAccounts`, which
+ * is fully available on the frontend from Privy's `usePrivy()` hook.
+ *
+ * Note: `identify()` is keyed on a wallet address, so a Privy user with no
+ * linked wallet is a no-op (nothing is emitted). Attaching a user identity that
+ * has no wallet is out of scope for this address-keyed helper.
+ *
+ * @param analytics - The Formo analytics instance (e.g. from `useFormo()`)
+ * @param user - The Privy user object from `usePrivy()`
+ * @param options - See {@link IdentifyPrivyUserOptions}
+ *
+ * @example
+ * ```ts
+ * import { identifyPrivyUser } from '@formo/analytics';
+ *
+ * const { user } = usePrivy();
+ * const { wallets } = useWallets();
+ * if (user) {
+ *   // activeAddress is optional - omit it if the SDK already tracks the
+ *   // connected wallet via a wagmi/EIP-1193 connect.
+ *   await identifyPrivyUser(formo, user, {
+ *     activeAddress: wallets[0]?.address,
+ *   });
+ * }
+ * ```
+ */
+export declare function identifyPrivyUser(analytics: IFormoAnalytics, user: PrivyUser, options?: IdentifyPrivyUserOptions): Promise<{
+    address: string;
+    chainType?: string;
+} | undefined>;
 //# sourceMappingURL=utils.d.ts.map