@formo/analytics 1.35.2 → 1.37.0

package/dist/esm/src/wallet/WalletStateStore.js

@@ -0,0 +1,512 @@
+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 { ACTIVE_WALLET_KEY, ACTIVE_WALLET_TTL_MS } from "../constants";
+import { cookie } from "../storage";
+import { getIdentityCookieDomain, getIdentityCookieSecurity, } from "../storage/cookiePolicy";
+import { logger } from "../logger";
+import { validateAddress, validateAndChecksumAddress } from "../utils/address";
+import { isSolanaChainId } from "../solana";
+/**
+ * Wallet identity and chain state, and the cookie that outlives the page.
+ *
+ * Split out of `FormoAnalytics` so there is one owner for "which wallet is
+ * active, on which chain". Before this, `_chainState`, the derived
+ * `currentAddress`/`currentChainId`, the active-wallet cookie and the session
+ * generation were manipulated from a dozen places across a 3400-line class,
+ * which is what made the ordering races in #341 possible to write.
+ */
+var WalletStateStore = /** @class */ (function () {
+    function WalletStateStore(deps) {
+        this.deps = deps;
+        this.state = {
+            evm: {},
+            solana: {},
+        };
+        /**
+         * Ticket counter for wallet observations.
+         *
+         * Every signal from a wallet is handled asynchronously: resolving an
+         * address, emitting an event. Between the moment a handler decides what to
+         * do and the moment it commits, a newer signal can arrive and be fully
+         * processed. Whichever handler resumes last then writes its captured data
+         * over the newer state.
+         *
+         * Bespoke guards were added for each case as it was found - a per-provider
+         * disconnect count, a per-namespace session generation, a "currently
+         * processing" flag - and a fourth review round kept producing new ones,
+         * because each guard answers one question and none establishes an order.
+         *
+         * A ticket does. A handler takes one before its first await; anything it
+         * commits afterwards is refused if a newer observation has claimed the
+         * namespace since.
+         */
+        this.observationSeq = 0;
+        this.newestObservation = {
+            evm: 0,
+            solana: 0,
+        };
+        /**
+         * How many disconnects a namespace has begun.
+         *
+         * Separate from the observation ticket on purpose, because they answer
+         * different questions. A ticket asks "is the state I captured still the
+         * newest?", which is what a switch or a probe needs. This asks "did the
+         * wallet go away after I started?", which is what a connect handler needs.
+         *
+         * Conflating them loses connects: a connect observation superseded by a
+         * NEWER connect must still be reported by somebody, and the ticket cannot
+         * tell that apart from being superseded by a disconnect.
+         */
+        this.disconnectCount = {
+            evm: 0,
+            solana: 0,
+        };
+    }
+    Object.defineProperty(WalletStateStore.prototype, "activeNamespace", {
+        /** Which namespace currently owns the derived values, if any. */
+        get: function () {
+            return this._activeNamespace;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    // ── reads ────────────────────────────────────────────────────────────────
+    /** Which namespace a chain id belongs to. */
+    WalletStateStore.prototype.namespaceOf = function (chainId) {
+        return isSolanaChainId(chainId) ? "solana" : "evm";
+    };
+    Object.defineProperty(WalletStateStore.prototype, "evmAddress", {
+        get: function () {
+            return this.state.evm.address;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(WalletStateStore.prototype, "evmChainId", {
+        get: function () {
+            return this.state.evm.chainId;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(WalletStateStore.prototype, "provider", {
+        get: function () {
+            return this.state.evm.provider;
+        },
+        // ── writes ───────────────────────────────────────────────────────────────
+        set: function (next) {
+            this.displaceProvider(this.state.evm.provider, next);
+            this.state.evm.provider = next;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    /**
+     * Take a ticket for an observation about to be processed.
+     *
+     * MUST be called before the handler's first await, so the order recorded is
+     * the order the signals arrived in, not the order their async work happens
+     * to finish in.
+     */
+    WalletStateStore.prototype.observe = function (namespace) {
+        var id = ++this.observationSeq;
+        this.newestObservation[namespace] = id;
+        return { id: id, namespace: namespace };
+    };
+    /**
+     * Record that a namespace's wallet is being torn down.
+     *
+     * Called at EVERY teardown site before anything is awaited, and whether or
+     * not a disconnect event will be emitted: whether the app opted into
+     * disconnect autocapture has no bearing on ordering.
+     */
+    WalletStateStore.prototype.beginDisconnect = function (namespace) {
+        this.disconnectCount[namespace]++;
+    };
+    /** How many disconnects this namespace has begun so far. */
+    WalletStateStore.prototype.disconnectsSoFar = function (namespace) {
+        return this.disconnectCount[namespace];
+    };
+    /**
+     * The newest observation for a namespace, for a caller that must NOT
+     * supersede its own caller.
+     *
+     * `disconnect()` is reached both directly by a consumer and from a handler
+     * that already holds a ticket. Taking a fresh ticket there would invalidate
+     * the handler that called it. Reading the current value and checking it
+     * later asks the same question without changing the answer for anyone else.
+     */
+    WalletStateStore.prototype.snapshot = function (namespace) {
+        return this.newestObservation[namespace];
+    };
+    /** Whether nothing newer has claimed the namespace since `snapshot`. */
+    WalletStateStore.prototype.isUnchangedSince = function (namespace, snapshot) {
+        return this.newestObservation[namespace] === snapshot;
+    };
+    /**
+     * The current newest observation, as a ticket, WITHOUT taking a new one.
+     *
+     * For a handler that must respect the order but has nothing to claim: it
+     * still abandons its work if something newer arrives, but it does not
+     * supersede whatever is already in flight.
+     */
+    WalletStateStore.prototype.currentObservation = function (namespace) {
+        return { id: this.newestObservation[namespace], namespace: namespace };
+    };
+    /**
+     * Whether this observation is still the newest for its namespace.
+     *
+     * False means a newer signal arrived while this handler was suspended, and
+     * it must abandon whatever it captured rather than write it over the newer
+     * state. Superseding, not dropping: the newer handler is already running.
+     */
+    WalletStateStore.prototype.isCurrent = function (observation) {
+        return this.newestObservation[observation.namespace] === observation.id;
+    };
+    /**
+     * Update a namespace and re-derive `address`/`chainId`.
+     *
+     * Accepts a namespace or a chain id. A chain id is also stored as the
+     * namespace's chain unless the update names one explicitly.
+     */
+    WalletStateStore.prototype.set = function (namespaceOrChainId, update) {
+        var namespace = typeof namespaceOrChainId === "string"
+            ? namespaceOrChainId
+            : this.namespaceOf(namespaceOrChainId);
+        var ns = this.state[namespace];
+        // A plain write. Whether this transition is still the newest is decided
+        // by the observation ticket its caller holds, not by comparing addresses
+        // here: re-adopting the SAME wallet is a real transition, and no
+        // comparison of the values can tell that apart from nothing happening.
+        if ("address" in update)
+            ns.address = update.address;
+        if ("chainId" in update) {
+            ns.chainId = update.chainId;
+        }
+        else if (typeof namespaceOrChainId === "number") {
+            ns.chainId = namespaceOrChainId;
+        }
+        if (namespace === "evm" && "provider" in update) {
+            this.displaceProvider(ns.provider, update.provider);
+            ns.provider = update.provider;
+        }
+        this._activeNamespace = namespace;
+        this.syncDerived();
+    };
+    /** Wipe a namespace. Per-namespace so a Solana disconnect spares EVM. */
+    WalletStateStore.prototype.clear = function (namespaceOrChainId) {
+        var namespace = typeof namespaceOrChainId === "string"
+            ? namespaceOrChainId
+            : this.namespaceOf(namespaceOrChainId);
+        if (namespace === "evm") {
+            // Wiping the namespace drops the active provider with it.
+            this.displaceProvider(this.state.evm.provider, undefined);
+            this.state.evm = {};
+        }
+        else {
+            this.state.solana = {};
+        }
+        this.syncDerived();
+    };
+    /** Both namespaces, keeping the EVM provider so tracking can resume. */
+    WalletStateStore.prototype.reset = function () {
+        var evmProvider = this.state.evm.provider;
+        this.state = { evm: { provider: evmProvider }, solana: {} };
+        this._activeNamespace = undefined;
+        this.address = undefined;
+        this.chainId = undefined;
+    };
+    /** Drop the active provider without touching identity. */
+    WalletStateStore.prototype.clearProvider = function () {
+        this.provider = undefined;
+    };
+    /**
+     * Repoint the active identity at a wallet, as `identify(setActive)` does,
+     * without disturbing per-namespace chain state.
+     *
+     * Deliberately transient. The next wallet event for either namespace
+     * re-derives from namespace state and replaces this, which is the intended
+     * order: a wallet that actually connects outranks one merely named by
+     * `identify()`. The alternative, making an identify sticky until another
+     * identify, would silently mis-attribute every event after a connect.
+     */
+    WalletStateStore.prototype.setActiveAddress = function (address) {
+        this.address = address;
+        this.persist();
+    };
+    /** Repoint (or forget) the derived chain while keeping the wallet. */
+    WalletStateStore.prototype.setActiveChainId = function (chainId) {
+        this.chainId = chainId;
+        this.persist();
+    };
+    /** Forget the derived chain while keeping the wallet. */
+    WalletStateStore.prototype.clearActiveChainId = function () {
+        this.setActiveChainId(undefined);
+    };
+    // ── higher-level operations ──────────────────────────────────────────────
+    /**
+     * Record validated wallet/chain state WITHOUT emitting an event.
+     *
+     * Integrations (the wagmi handler among them) must call this on every
+     * connect / chain change / disconnect, even when the matching autocapture
+     * event is disabled. Otherwise `chainId` stays stale and the exclusion gate,
+     * which keys off it rather than the event payload, can be bypassed.
+     */
+    WalletStateStore.prototype.syncWalletState = function (params) {
+        var chainId = params.chainId, address = params.address;
+        // An integration adopting or dropping a wallet is a wallet signal like
+        // any other, so it takes its place in the order. Without this, a
+        // disconnect still in flight could not tell that the wagmi handler had
+        // already adopted a replacement.
+        this.observe(this.namespaceOf(chainId));
+        if (this.deps.isTrackingSuppressed()) {
+            // While suppressed we must never LEARN a new wallet, but we must still
+            // CLEAR a stale one. Otherwise a disconnect or switch observed on a
+            // suppressed route leaves the previous address in memory and in the
+            // cookie, ready to attach to later allowed-page events.
+            if (!address) {
+                this.clearForChain(chainId);
+                return;
+            }
+            if (chainId === null || chainId === undefined)
+                return;
+            var namespace = this.namespaceOf(chainId);
+            var known = this.state[namespace].address;
+            var incoming = validateAddress(address, chainId);
+            if (known && incoming && incoming !== known) {
+                // A switch away from the learned wallet invalidates it. Drop the
+                // stale one without learning the new address.
+                this.clear(chainId);
+            }
+            return;
+        }
+        if (!address) {
+            this.clearForChain(chainId);
+            return;
+        }
+        if (chainId === null || chainId === undefined)
+            return;
+        var valid = validateAddress(address, chainId);
+        if (!valid) {
+            logger.warn("syncWalletState: invalid address (\"".concat(address, "\") for chain ").concat(chainId));
+            return;
+        }
+        this.set(chainId, { address: valid });
+    };
+    /**
+     * Learn an EVM wallet observed on an autocaptured signature or transaction,
+     * when nothing is known yet.
+     *
+     * Deliberately conservative: it never overwrites a different wallet, and it
+     * corrects only a stale chain for the wallet already known.
+     */
+    WalletStateStore.prototype.backfill = function (address, chainId, provider) {
+        // Refuse a chain the provider has since moved off.
+        //
+        // A request captures its chain once and reuses that snapshot for every
+        // status it emits, which is right for the payload: a confirmation must
+        // not be relabelled mid-flight. Writing that captured value back into
+        // central state on a LATER status restored a chain the wallet had already
+        // left, and the unscoped events that fall back to it then bypassed an
+        // exclusion that should have caught them.
+        if (provider && chainId !== undefined && chainId !== 0) {
+            var live = this.deps.providerChainId(provider);
+            if (live !== undefined && live !== chainId)
+                chainId = live;
+        }
+        // `0` is kept deliberately. It means "could not resolve", and persisting
+        // it is what lets the exclusion gate refuse the unscoped events (page,
+        // track, identify) that carry no chain of their own. Erasing it to
+        // `undefined` looked tidier but removed the only marker distinguishing
+        // "unknown" from "no wallet yet".
+        // Never learn identity while suppressed. A signature observed on an
+        // excluded route must not populate the address for later allowed pages.
+        if (this.deps.isTrackingSuppressed())
+            return;
+        var known = this.evmAddress;
+        if (known) {
+            // Same wallet, newer chain: correct it rather than returning. A
+            // persisted wallet restores a chain from a previous session, and if the
+            // provider has since moved, the stale restored chain would stay in the
+            // derived value and carry the unscoped events past an exclusion.
+            // `0` means "could not resolve". Correcting a stale chain with a real
+            // one is the point of this branch; replacing a chain we already know
+            // with "unknown" only makes attribution worse, and would trip the
+            // exclusion gate's fail-closed rule against a wallet we can place.
+            var usable = chainId !== undefined && !(chainId === 0 && this.evmChainId);
+            if (usable &&
+                known.toLowerCase() === address.toLowerCase() &&
+                this.evmChainId !== chainId) {
+                this.set("evm", { address: known, chainId: chainId });
+            }
+            // A DIFFERENT address is another wallet's business; never overwrite.
+            return;
+        }
+        this.set("evm", { address: address, chainId: chainId });
+    };
+    /**
+     * Apply an EVM connect/switch seen while tracking is suppressed: never
+     * learn the wallet, but if it is a switch away from one already learned,
+     * drop the stale one so it cannot attach to a later allowed-page event.
+     */
+    WalletStateStore.prototype.clearStaleEvmWalletOnSwitchWhileSuppressed = function (address) {
+        var known = this.state.evm.address;
+        var incoming = validateAndChecksumAddress(address);
+        if (known && incoming && incoming !== known)
+            this.clear("evm");
+    };
+    // ── persistence ──────────────────────────────────────────────────────────
+    /**
+     * Persist (or clear) the wallet snapshot, so the next page load can
+     * repopulate identity before the wallet reconnects. Without it, every
+     * `track()` / `page()` between page-show and reconnection ships with no
+     * address.
+     */
+    WalletStateStore.prototype.persist = function () {
+        try {
+            // Visitor-level suppression is stable for the session, so purging is
+            // safe and prevents a stale snapshot outliving an opt-out.
+            if (this.deps.isPersistedIdentityPurgeRequired()) {
+                cookie().remove(ACTIVE_WALLET_KEY);
+                return;
+            }
+            if (this.address) {
+                // Page-level exclusion: do not write while on an excluded route, but
+                // leave any existing cookie alone. One written on an allowed page
+                // must survive a transient visit here.
+                if (this.deps.isPageExcluded())
+                    return;
+                var value = JSON.stringify(__assign({ address: this.address }, (this.chainId !== undefined && { chainId: this.chainId })));
+                var domain = getIdentityCookieDomain(this.deps.crossSubdomainCookies());
+                cookie().set(ACTIVE_WALLET_KEY, value, __assign(__assign({ path: "/", expires: new Date(Date.now() + ACTIVE_WALLET_TTL_MS).toUTCString() }, getIdentityCookieSecurity()), (domain ? { domain: domain } : {})));
+            }
+            else {
+                // No active wallet: clear the snapshot. This runs even on an excluded
+                // route, so a disconnect observed while suppressed actively removes
+                // stale identity rather than leaving it for later.
+                cookie().remove(ACTIVE_WALLET_KEY);
+            }
+        }
+        catch (err) {
+            logger.warn("Failed to persist current wallet snapshot", err);
+        }
+    };
+    /** Seed identity from the persisted snapshot, once, during construction. */
+    WalletStateStore.prototype.load = function () {
+        try {
+            if (this.deps.isPersistedIdentityPurgeRequired()) {
+                cookie().remove(ACTIVE_WALLET_KEY);
+                return;
+            }
+            // Page-level exclusion: don't restore into memory here, but keep the
+            // cookie so a later allowed-page load can.
+            if (this.deps.isPageExcluded())
+                return;
+            var raw = cookie().get(ACTIVE_WALLET_KEY);
+            if (!raw)
+                return;
+            var parsed = JSON.parse(raw);
+            if (!(parsed === null || parsed === void 0 ? void 0 : parsed.address))
+                return;
+            // A cookie is attacker-writable and survives across SDK versions, so
+            // the chain has to be a real number before anything trusts it. A string
+            // "137" restored as-is would never match a numeric exclusion list, so
+            // an excluded chain would silently start reporting again.
+            //
+            // A present-but-unusable chain rejects the WHOLE snapshot rather than
+            // being downgraded to "chainless". Downgrading looks harmless and is
+            // not: the namespace is derived from the chain, so a Solana wallet with
+            // a corrupt chain would be filed under EVM, and a later Solana
+            // disconnect would fall through to that phantom entry and keep
+            // attributing events to a wallet that had gone.
+            var rawChain = parsed.chainId;
+            var chainMissing = rawChain === undefined || rawChain === null;
+            if (!chainMissing &&
+                (typeof rawChain !== "number" || !Number.isFinite(rawChain))) {
+                cookie().remove(ACTIVE_WALLET_KEY);
+                return;
+            }
+            var chainId = chainMissing ? undefined : rawChain;
+            // With no chain to go on, the address shape decides. Defaulting to EVM
+            // filed a chainless Solana wallet under EVM, where later EVM handlers
+            // read it as `evmAddress` and emitted EVM state for a Solana wallet.
+            var namespace = chainId === undefined
+                ? validateAndChecksumAddress(parsed.address)
+                    ? "evm"
+                    : "solana"
+                : this.namespaceOf(chainId);
+            var validated = validateAddress(parsed.address, chainId);
+            if (!validated) {
+                cookie().remove(ACTIVE_WALLET_KEY);
+                return;
+            }
+            var ns = this.state[namespace];
+            ns.address = validated;
+            if (chainId !== undefined)
+                ns.chainId = chainId;
+            this._activeNamespace = namespace;
+            this.address = validated;
+            this.chainId = chainId;
+        }
+        catch (err) {
+            logger.warn("Failed to restore persisted wallet snapshot", err);
+            cookie().remove(ACTIVE_WALLET_KEY);
+        }
+    };
+    // ── internals ────────────────────────────────────────────────────────────
+    WalletStateStore.prototype.clearForChain = function (chainId) {
+        if (chainId !== undefined && chainId !== null) {
+            this.clear(chainId);
+        }
+        else {
+            this.clear("evm");
+            this.clear("solana");
+        }
+    };
+    WalletStateStore.prototype.displaceProvider = function (previous, next) {
+        if (previous && previous !== next)
+            this.deps.onProviderDisplaced(previous);
+    };
+    /**
+     * Re-derive `address`/`chainId` from the active namespace.
+     *
+     * Last-connected wins, then fall through to the other namespace so a
+     * still-connected wallet keeps attribution when its neighbour disconnects.
+     */
+    WalletStateStore.prototype.syncDerived = function () {
+        var active = this._activeNamespace;
+        if (active) {
+            var state = this.state[active];
+            if (state.address || state.chainId) {
+                this.address = state.address;
+                this.chainId = state.chainId;
+                this.persist();
+                return;
+            }
+        }
+        var other = active === "evm" ? "solana" : "evm";
+        var otherState = this.state[other];
+        if (otherState.address || otherState.chainId) {
+            this.address = otherState.address;
+            this.chainId = otherState.chainId;
+            this._activeNamespace = other;
+            this.persist();
+            return;
+        }
+        this.address = undefined;
+        this.chainId = undefined;
+        this.persist();
+    };
+    return WalletStateStore;
+}());
+export { WalletStateStore };
+//# sourceMappingURL=WalletStateStore.js.map