@meshconnect/web-link-sdk 3.13.0 → 3.14.1

package/backupFlow.js

@@ -0,0 +1,536 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+import { addPopup, buildIframeAllowPolicy, iframeId, removePopup } from './utils/popup';
+import { sdkSpecs } from './utils/sdk-specs';
+import { BACKUP_CONFIG_MESSAGE_TYPE, DEFAULT_BACKUP_WIDGET_ORIGIN, JIT_RESPONSE_MESSAGE_TYPE, SESSION_NONCE_PARAM, buildBackupWidgetUrl, createSessionNonce } from './utils/backup';
+import { createBackupTierController } from './utils/backupTier';
+import { BridgeParent } from '@meshconnect/uwc-bridge-parent';
+import { removePrewarmIframe } from './utils/prewarm';
+/**
+ * Validate a host `onStatusPoll` result against the three-variant contract and
+ * return ONLY the contract fields. Throws on anything malformed — a missing,
+ * misspelled, or non-string `status`, or a `'ready'` without a non-empty string
+ * `address` — so the handler's catch fails the poll closed (`ok: false`). The
+ * previous builder silently coerced any unknown status to `'pending'` (which
+ * polls forever) and forwarded `'ready'` without an address (an invalid
+ * success); both are money-path failure modes. Extra fields (e.g. a raw backend
+ * response carrying identifiers/credentials) are dropped, never forwarded across
+ * the bridge to the widget's independent origin.
+ */
+export function sanitizeStatusResult(result) {
+    var status = typeof result === 'object' && result !== null
+        ? result.status
+        : undefined;
+    if (status === 'pending')
+        return { status: 'pending' };
+    if (status === 'failed')
+        return { status: 'failed' };
+    if (status === 'ready') {
+        var address = result.address;
+        if (typeof address !== 'string' || address.length === 0) {
+            throw new Error("onStatusPoll returned status 'ready' without a valid address");
+        }
+        var addressTag = result.addressTag;
+        // A memo/tag chain deposit without its tag can strand funds, so a tag that is
+        // present but not a string is malformed — fail closed rather than drop it and
+        // report a tag-less 'ready'. `null`/`undefined`/`''` mean "no tag".
+        if (addressTag !== undefined &&
+            addressTag !== null &&
+            typeof addressTag !== 'string') {
+            throw new Error("onStatusPoll returned status 'ready' with a non-string addressTag");
+        }
+        return typeof addressTag === 'string' && addressTag.length > 0
+            ? { status: 'ready', address: address, addressTag: addressTag }
+            : { status: 'ready', address: address };
+    }
+    throw new Error("onStatusPoll returned an invalid status: ".concat(JSON.stringify(status), " (expected 'pending' | 'ready' | 'failed')"));
+}
+export function createBackupFlow(host) {
+    // Set by `open`, delivered to the widget on its `loaded` handshake.
+    var backupSession;
+    // See `ActiveFlow`: `!backupSession` is NOT a safe token-forwarding gate, because
+    // an aborted re-open (`openLink` with a bad token, or `open` with a bad origin)
+    // clears `backupSession` while the previous backup iframe + listener are still
+    // live; a late `loaded` from that stale iframe would then pass a `!backupSession`
+    // check and ship `frontAccessTokens` to the independent backup origin. In that
+    // aborted/dead window `activeFlow` is `null`, so tokens are withheld.
+    var activeFlow = null;
+    // Tier-1 → Tier-2 cascade state machine, live only during a backup session.
+    var backupTierController = null;
+    // Monotonic id for the current backup session. Every async operation (JIT reply,
+    // cascade import, iframe `error`) captures the id it started under and re-checks
+    // it before acting, so work from a session that has ended or been replaced can
+    // never post into / clobber a later one (a reused `callId` must never associate a
+    // deposit address with the wrong session — money path).
+    var backupSessionId = 0;
+    // The widget iframe's window for the active backup session. Backup messages
+    // (`loaded`, JIT) are only honoured when they come from this exact window
+    // (`event.source`), so another frame cannot drive the client's callbacks.
+    var backupIframeWindow = null;
+    // Removes the Tier-1 `error` listener bound to the current backup iframe.
+    var removeBackupIframeErrorListener = null;
+    // True once cascaded to Tier 2, which loads the bundled widget in a SANDBOXED,
+    // opaque-origin iframe (blob: URL). Its `event.origin` is `'null'`, so messages
+    // are authenticated by `event.source` instead, and we post to it with a `'*'`
+    // target. (Tier 1 stays origin-pinned.)
+    var backupTier2 = false;
+    // Object URL backing the Tier-2 iframe; revoked on teardown to avoid a leak.
+    var backupTier2BlobUrl = null;
+    // This open's session nonce, put on the widget URL (`?sid=` / Tier-2 `#sid=`) and
+    // echoed by the widget on every message. Navigating a reused embedded iframe
+    // keeps its WindowProxy and Tier-1 sessions share an origin, so this is the only
+    // thing that tells a stale message from the previous document apart from the
+    // current open's — e.g. a queued `close` (spurious onExit) or `loaded` (would
+    // cancel the Tier-1 → Tier-2 fallback).
+    var sessionNonce = null;
+    // This open's explicit theme (`dark`/`light`; undefined for `system`/unset). Tier 1
+    // sends it as `?theme=`; Tier 2's blob: URL can't, so it is stamped onto the
+    // bundled HTML instead (`withWidgetTheme`).
+    var backupTheme;
+    /**
+     * Tear down any in-flight backup session state. Called when a session ends or
+     * when the primary (token) flow starts, so a pending Tier-1 timeout can never
+     * fire against a later iframe and a stale config can never be re-delivered.
+     * Bumping `backupSessionId` invalidates any async work still bound to the old id.
+     */
+    function reset() {
+        backupSession = undefined;
+        // Entering a fresh/dead state: no flow is live until one re-commits. This is
+        // what makes a late `loaded` from a stale backup iframe fail the token-
+        // forwarding gate (`activeFlow === 'primary'`) during an aborted re-open.
+        activeFlow = null;
+        backupTierController === null || backupTierController === void 0 ? void 0 : backupTierController.destroy();
+        backupTierController = null;
+        backupIframeWindow = null;
+        removeBackupIframeErrorListener === null || removeBackupIframeErrorListener === void 0 ? void 0 : removeBackupIframeErrorListener();
+        removeBackupIframeErrorListener = null;
+        backupTier2 = false;
+        sessionNonce = null;
+        backupTheme = undefined;
+        if (backupTier2BlobUrl) {
+            URL.revokeObjectURL(backupTier2BlobUrl);
+            backupTier2BlobUrl = null;
+        }
+        backupSessionId += 1;
+    }
+    /**
+     * Run the host's JIT callback for a widget request and post the result back over
+     * the bridge, correlated by `callId` (OR-452). `addressInit` runs `onAddressInit`
+     * (its return is ignored — a throw/reject is a failure); `statusPoll` runs
+     * `onStatusPoll` and returns its `{ status, address?, addressTag? }`. A missing
+     * callback fails closed so an address-less destination surfaces an error rather
+     * than hanging. The callbacks run in the host app with the client's own session —
+     * their credentials never enter the widget; only `(symbol, networkId)` and the
+     * resolved address cross the bridge.
+     */
+    function runJitRequest(payload) {
+        return __awaiter(this, void 0, void 0, function () {
+            var callId, method, symbol, networkId, sessionId, targetWindow, replyTarget, respond, isJitDestination, onAddressInit, onStatusPoll, result, e_1;
+            var _a, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0:
+                        if (!payload || typeof payload.callId !== 'string')
+                            return [2 /*return*/];
+                        callId = payload.callId, method = payload.method, symbol = payload.symbol, networkId = payload.networkId;
+                        sessionId = backupSessionId;
+                        targetWindow = backupIframeWindow;
+                        replyTarget = backupTier2 ? '*' : host.getLinkTokenOrigin();
+                        respond = function (response) {
+                            if (backupSessionId !== sessionId || !targetWindow || !replyTarget)
+                                return;
+                            try {
+                                targetWindow.postMessage({ type: JIT_RESPONSE_MESSAGE_TYPE, payload: response }, replyTarget);
+                            }
+                            catch (e) {
+                                console.error('Mesh SDK: Failed to deliver JIT response to the widget');
+                                console.error(e);
+                            }
+                        };
+                        _c.label = 1;
+                    case 1:
+                        _c.trys.push([1, 7, , 8]);
+                        // The request drives real address generation against the client's backend —
+                        // reject a malformed one rather than passing garbage to the callbacks.
+                        if (typeof symbol !== 'string' || typeof networkId !== 'string') {
+                            throw new TypeError('backup JIT request is missing a string symbol/networkId');
+                        }
+                        isJitDestination = backupSession === null || backupSession === void 0 ? void 0 : backupSession.destinations.some(function (d) { return d.symbol === symbol && d.networkId === networkId && !d.address; });
+                        if (!isJitDestination) {
+                            throw new Error('backup JIT request is not for an address-less destination in the session');
+                        }
+                        if (!(method === 'addressInit')) return [3 /*break*/, 3];
+                        onAddressInit = (_a = host.getOptions()) === null || _a === void 0 ? void 0 : _a.onAddressInit;
+                        if (!onAddressInit) {
+                            throw new Error('onAddressInit callback is required to resolve an address-less backup destination');
+                        }
+                        return [4 /*yield*/, onAddressInit(symbol, networkId)];
+                    case 2:
+                        _c.sent();
+                        respond({ callId: callId, ok: true });
+                        return [3 /*break*/, 6];
+                    case 3:
+                        if (!(method === 'statusPoll')) return [3 /*break*/, 5];
+                        onStatusPoll = (_b = host.getOptions()) === null || _b === void 0 ? void 0 : _b.onStatusPoll;
+                        if (!onStatusPoll) {
+                            throw new Error('onStatusPoll callback is required to resolve an address-less backup destination');
+                        }
+                        return [4 /*yield*/, onStatusPoll(symbol, networkId)
+                            // Validate against the three-variant contract and post ONLY the contract
+                            // fields to the widget's (independent) origin. A malformed result throws
+                            // here, so the catch fails the poll closed (`ok: false`) rather than
+                            // silently polling forever on a coerced 'pending' or forwarding a 'ready'
+                            // with no address. Extra fields (e.g. a raw backend response with
+                            // identifiers/credentials) are dropped, never forwarded.
+                        ];
+                    case 4:
+                        result = _c.sent();
+                        // Validate against the three-variant contract and post ONLY the contract
+                        // fields to the widget's (independent) origin. A malformed result throws
+                        // here, so the catch fails the poll closed (`ok: false`) rather than
+                        // silently polling forever on a coerced 'pending' or forwarding a 'ready'
+                        // with no address. Extra fields (e.g. a raw backend response with
+                        // identifiers/credentials) are dropped, never forwarded.
+                        respond({ callId: callId, ok: true, result: sanitizeStatusResult(result) });
+                        return [3 /*break*/, 6];
+                    case 5: throw new Error("Unknown backup JIT method: ".concat(String(method)));
+                    case 6: return [3 /*break*/, 8];
+                    case 7:
+                        e_1 = _c.sent();
+                        // Log the real error host-side, but send the widget a fixed, non-revealing
+                        // message — callback exceptions can contain URLs / identifiers / credentials,
+                        // which must not cross to the independent widget origin.
+                        console.error('Mesh SDK: backup JIT callback failed', e_1);
+                        respond({ callId: callId, ok: false, error: 'JIT callback failed' });
+                        return [3 /*break*/, 8];
+                    case 8: return [2 /*return*/];
+                }
+            });
+        });
+    }
+    /**
+     * Fail the backup flow closed: tear down the popup/bridge and listener and exit
+     * with an error (never leave a blank or hung screen — design §5A/§5H). Teardown
+     * runs before `onExit`, and `reset` clears the session, so the removed iframe
+     * cannot emit a later `close`/`done` that would call `onExit` twice.
+     */
+    function failBackupClosed(errorMessage) {
+        var _a, _b;
+        (_a = host.getBridgeParent()) === null || _a === void 0 ? void 0 : _a.destroy();
+        host.setBridgeParent(null);
+        removePopup();
+        host.removeMessageListener();
+        var onExit = (_b = host.getOptions()) === null || _b === void 0 ? void 0 : _b.onExit;
+        reset();
+        onExit === null || onExit === void 0 ? void 0 : onExit(errorMessage);
+    }
+    /**
+     * Cascade the backup flow from Tier 1 (widget from the backup origin) to Tier 2
+     * (the SDK-bundled offline widget) when the backup origin is unreachable (design
+     * §5H). Emits `backupTierChanged`, then swaps the current iframe to the bundled
+     * widget loaded as a SANDBOXED, opaque-origin `blob:` URL (not `srcdoc`) — see the
+     * detailed rationale at the swap below. The bundle is imported dynamically so
+     * Tier-1-only consumers can code-split the ~135 KB asset out of their main chunk.
+     *
+     * ⚠️ Host CSP: navigating the iframe to a `blob:` URL requires the embedding page's
+     * CSP to permit `blob:` in `frame-src`/`child-src` (or `default-src`). A host that
+     * only allows the Tier-1 origin there will block the Tier-2 frame and the fallback
+     * will time out — this is a documented integration requirement (see README).
+     */
+    function cascadeBackupToTier2(reason, sessionId) {
+        return __awaiter(this, void 0, void 0, function () {
+            var tier1Iframe, html, bundle, _a, iframe, blobUrl;
+            var _b, _c, _d;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        // Consumer code (often telemetry): a throw here must not abort the cascade —
+                        // that would leave Tier 1 dead with no Tier 2, and the fail-closed timer would
+                        // then report the whole backup flow unavailable.
+                        try {
+                            (_c = (_b = host.getOptions()) === null || _b === void 0 ? void 0 : _b.onEvent) === null || _c === void 0 ? void 0 : _c.call(_b, {
+                                type: 'backupTierChanged',
+                                payload: { from: 'tier1', to: 'tier2', reason: reason }
+                            });
+                        }
+                        catch (e) {
+                            console.error('Mesh SDK: onEvent threw while handling backupTierChanged', e);
+                        }
+                        // `onEvent` ran consumer code synchronously; if it opened a new flow, `reset`
+                        // advanced the session id — bail before touching any iframe.
+                        if (backupSessionId !== sessionId)
+                            return [2 /*return*/];
+                        // Tear down the Tier-1 surface synchronously (before the async import) so
+                        // nothing from it races the swap.
+                        backupIframeWindow = null;
+                        tier1Iframe = host.iframeElement();
+                        if (tier1Iframe) {
+                            (_d = host.getBridgeParent()) === null || _d === void 0 ? void 0 : _d.destroy();
+                            host.setBridgeParent(null);
+                            tier1Iframe.removeAttribute('src');
+                        }
+                        _e.label = 1;
+                    case 1:
+                        _e.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, import('./backup-bundle')];
+                    case 2:
+                        bundle = _e.sent();
+                        html = bundle.withWidgetTheme(bundle.getBundledOfflineWidget().html, backupTheme);
+                        return [3 /*break*/, 4];
+                    case 3:
+                        _a = _e.sent();
+                        // The bundled chunk could not be loaded (e.g. the host's own asset host is
+                        // unreachable). Fail closed — never a blank QR. Only if still this session.
+                        if (backupSessionId === sessionId) {
+                            failBackupClosed('Backup deposit flow is unavailable');
+                        }
+                        return [2 /*return*/];
+                    case 4:
+                        // The session may have ended or been replaced while the bundle was importing —
+                        // do not touch the current (possibly different) session's iframe.
+                        if (backupSessionId !== sessionId)
+                            return [2 /*return*/];
+                        iframe = host.iframeElement();
+                        if (!iframe) {
+                            failBackupClosed('Backup deposit flow is unavailable');
+                            return [2 /*return*/];
+                        }
+                        blobUrl = URL.createObjectURL(new Blob([html], { type: 'text/html' }));
+                        backupTier2BlobUrl = blobUrl;
+                        backupTier2 = true;
+                        iframe.removeAttribute('srcdoc');
+                        // allow-scripts WITHOUT allow-same-origin ⇒ opaque origin. The iframe's `allow`
+                        // (Permissions-Policy, incl. clipboard) set at mount is preserved for copy-address.
+                        iframe.setAttribute('sandbox', 'allow-scripts');
+                        // A blob: URL can't take a query, so the session nonce rides in the fragment.
+                        iframe.src = "".concat(blobUrl, "#").concat(SESSION_NONCE_PARAM, "=").concat(sessionNonce !== null && sessionNonce !== void 0 ? sessionNonce : '');
+                        host.setBridgeParent(new BridgeParent(iframe));
+                        backupIframeWindow = iframe.contentWindow;
+                        return [2 /*return*/];
+                }
+            });
+        });
+    }
+    function open(options, session, backupOptions) {
+        var _a, _b, _c, _d;
+        removePrewarmIframe();
+        // Every abort below tears down any prior backup flow first (reset) so a stale
+        // iframe from it can't keep reporting after this failed re-open calls onExit.
+        if (!session) {
+            reset();
+            (_a = options === null || options === void 0 ? void 0 : options.onExit) === null || _a === void 0 ? void 0 : _a.call(options, 'Invalid backup session!');
+            return;
+        }
+        var customIframeId = backupOptions === null || backupOptions === void 0 ? void 0 : backupOptions.customIframeId;
+        if ((options === null || options === void 0 ? void 0 : options.renderType) === 'embedded' && !customIframeId) {
+            var msg = 'Mesh SDK: Failed to open backup link - renderType "embedded" requires a customIframeId';
+            console.error(msg);
+            reset();
+            (_b = options === null || options === void 0 ? void 0 : options.onExit) === null || _b === void 0 ? void 0 : _b.call(options, msg);
+            return;
+        }
+        // Start a fresh backup session (clears any prior controller/timer), then make
+        // THIS createLink's options the live ones so the async JIT/cascade/exit
+        // callbacks below (which read `host.getOptions()`) resolve against this session.
+        reset();
+        if (options)
+            host.setOptions(options);
+        backupSession = session;
+        sessionNonce = createSessionNonce();
+        var widgetOrigin = (backupOptions === null || backupOptions === void 0 ? void 0 : backupOptions.widgetOrigin) || DEFAULT_BACKUP_WIDGET_ORIGIN;
+        var widgetUrl;
+        var widgetOriginParsed;
+        try {
+            // Only http(s) origins may be loaded into the iframe. `new URL().origin`
+            // alone would accept `javascript:`/`data:` schemes, which could execute in
+            // the iframe's initial same-origin context — reject anything else, matching
+            // the primary flow's protocol check.
+            var parsedOrigin = new URL(widgetOrigin);
+            if (parsedOrigin.protocol !== 'http:' &&
+                parsedOrigin.protocol !== 'https:') {
+                throw new Error('widgetOrigin must be an http(s) URL');
+            }
+            // The widget reads its params (incl. the required session nonce) from the
+            // query; with a fragment in the base they'd be appended after `#`, the widget
+            // couldn't echo `sid`, and every open would fall to Tier 2.
+            if (parsedOrigin.hash || widgetOrigin.includes('#')) {
+                throw new Error('widgetOrigin must not contain a fragment');
+            }
+            // The widget reads only `theme=dark|light`; `system`/unset is left to its
+            // own `prefers-color-scheme` fallback.
+            var theme = (options === null || options === void 0 ? void 0 : options.theme) === 'dark' || (options === null || options === void 0 ? void 0 : options.theme) === 'light'
+                ? options.theme
+                : undefined;
+            backupTheme = theme;
+            widgetUrl = buildBackupWidgetUrl(widgetOrigin, {
+                platform: sdkSpecs.platform,
+                sdkVersion: sdkSpecs.version,
+                theme: theme,
+                sessionNonce: sessionNonce
+            });
+            widgetOriginParsed = new URL(widgetUrl).origin;
+            host.setLinkTokenOrigin(widgetOriginParsed);
+        }
+        catch (_e) {
+            reset();
+            (_c = options === null || options === void 0 ? void 0 : options.onExit) === null || _c === void 0 ? void 0 : _c.call(options, 'Invalid backup widget origin!');
+            return;
+        }
+        // Origin validated — this backup flow is now the live one. (A later no-iframe
+        // abort below calls `reset()`, which clears this again.) Access tokens are never
+        // forwarded while `activeFlow === 'backup'`.
+        activeFlow = 'backup';
+        host.removeMessageListener();
+        if (customIframeId) {
+            var iframe_1 = document.getElementById(customIframeId);
+            if (!iframe_1) {
+                // No surface to render into — fail closed rather than leave the session
+                // active with no iframe/controller (which would hang with no onExit).
+                var msg = "Mesh SDK: No iframe found with id ".concat(customIframeId);
+                console.warn(msg);
+                reset();
+                (_d = options === null || options === void 0 ? void 0 : options.onExit) === null || _d === void 0 ? void 0 : _d.call(options, msg);
+                return;
+            }
+            iframe_1.allow = buildIframeAllowPolicy(widgetOriginParsed);
+            // A reused embedded iframe may still carry Tier-2 state from a prior backup
+            // session — clear `srcdoc` (precedence over `src`) and `sandbox` (opaque).
+            iframe_1.removeAttribute('srcdoc');
+            iframe_1.removeAttribute('sandbox');
+            iframe_1.src = widgetUrl;
+            host.setCurrentIframeId(customIframeId);
+        }
+        else {
+            host.setCurrentIframeId(iframeId);
+            addPopup(widgetUrl);
+        }
+        host.addMessageListener();
+        host.setTargetOrigin(window.location.origin);
+        var iframe = host.iframeElement();
+        if (iframe) {
+            host.setBridgeParent(new BridgeParent(iframe));
+            // Track this session's widget window so JIT requests are only honoured when
+            // they come from it (event.source check in `handleJitRequest`).
+            backupIframeWindow = iframe.contentWindow;
+            // Capture the session id so the cascade/fail-closed/error callbacks below
+            // only act while this session is still the active one.
+            var sessionId_1 = backupSessionId;
+            // Arm the Tier-1 → Tier-2 cascade. If the backup origin never completes its
+            // ready handshake (unreachable / served-but-broken), fall back to the
+            // bundled offline widget; if even that never becomes ready, fail closed.
+            backupTierController = createBackupTierController({
+                onFallback: function (reason) {
+                    if (backupSessionId === sessionId_1) {
+                        void cascadeBackupToTier2(reason, sessionId_1);
+                    }
+                },
+                onTier2Unavailable: function () {
+                    if (backupSessionId === sessionId_1) {
+                        failBackupClosed('Backup deposit flow is unavailable');
+                    }
+                }
+            });
+            // Best-effort hard-failure signal: a cross-origin iframe rarely fires `error`
+            // for a failed navigation (the ready-handshake timeout is the authoritative
+            // Tier-1 signal), but when it does fire we cascade at once instead of waiting
+            // the timeout out. Session-bound + removed on teardown so a late error from
+            // an old (embedded) iframe can't cascade a later session.
+            var onIframeError_1 = function () {
+                if (backupSessionId === sessionId_1) {
+                    backupTierController === null || backupTierController === void 0 ? void 0 : backupTierController.reportLoadError();
+                }
+            };
+            iframe.addEventListener('error', onIframeError_1);
+            removeBackupIframeErrorListener = function () {
+                return iframe.removeEventListener('error', onIframeError_1);
+            };
+            backupTierController.start();
+        }
+    }
+    function isFromActiveWidget(event) {
+        var _a;
+        return (!!backupSession &&
+            !!sessionNonce &&
+            !!event.source &&
+            event.source === backupIframeWindow &&
+            ((_a = event.data) === null || _a === void 0 ? void 0 : _a[SESSION_NONCE_PARAM]) === sessionNonce);
+    }
+    function handleJitRequest(event) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!isFromActiveWidget(event)) return [3 /*break*/, 2];
+                        return [4 /*yield*/, runJitRequest(event.data.payload)];
+                    case 1:
+                        _a.sent();
+                        _a.label = 2;
+                    case 2: return [2 /*return*/];
+                }
+            });
+        });
+    }
+    function completeReadyHandshake(event) {
+        // Only the backup widget's OWN window may complete the ready handshake. The
+        // host's message handler also admits host-origin messages (Tier 1), so without
+        // this an unrelated same-origin frame posting `{ type: 'loaded' }` would call
+        // `markReady()` and permanently cancel the Tier-1 → Tier-2 fallback. The nonce
+        // check stops a stale `loaded` from a previous open in a reused embedded iframe
+        // (same window, same origin) doing the same.
+        if (isFromActiveWidget(event)) {
+            // This `loaded` IS the ready handshake — cancel the pending tier timeout
+            // (Tier-1 healthy, or Tier-2 mounted) before delivering the config.
+            backupTierController === null || backupTierController === void 0 ? void 0 : backupTierController.markReady();
+            host.sendMessageToIframe({
+                type: BACKUP_CONFIG_MESSAGE_TYPE,
+                payload: backupSession
+            });
+        }
+    }
+    return {
+        reset: reset,
+        setPrimaryFlow: function () {
+            activeFlow = 'primary';
+        },
+        getActiveFlow: function () { return activeFlow; },
+        isTier2: function () { return backupTier2; },
+        isFromActiveWidget: isFromActiveWidget,
+        open: open,
+        handleJitRequest: handleJitRequest,
+        completeReadyHandshake: completeReadyHandshake
+    };
+}

package/index.d.ts

@@ -1,4 +1,5 @@
 export * from './utils/types';
 export * from './utils/event-types';
+export { BACKUP_CONFIG_MESSAGE_TYPE, DEFAULT_BACKUP_WIDGET_ORIGIN } from './utils/backup';
 export { createLink } from './Link';
 export type { BrokerType } from '@meshconnect/node-api';

package/index.js

@@ -1,3 +1,4 @@
 export * from './utils/types';
 export * from './utils/event-types';
+export { BACKUP_CONFIG_MESSAGE_TYPE, DEFAULT_BACKUP_WIDGET_ORIGIN } from './utils/backup';
 export { createLink } from './Link';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshconnect/web-link-sdk",
-  "version": "3.13.0",
+  "version": "3.14.1",
   "description": "A client-side JS library for integrating with Mesh Connect",
   "exports": "./index.js",
   "license": "MIT",
@@ -10,7 +10,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@meshconnect/node-api": "^2.0.28",
+    "@meshconnect/node-api": "^2.0.29",
     "@meshconnect/uwc-bridge-parent": "1.7.0"
   },
   "module": "./index.js",

package/utils/backup.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Default origin for the standalone backup deposit widget (OR-449): the production
+ * Cloudflare Worker. It is under the `meshconnect.com` zone but served by
+ * Cloudflare, not Azure, so it shares no failure domain with the primary Mesh API
+ * (design doc §5C) — if the core API is down the widget still loads. Matches the
+ * React Native SDK's default. Override per-call via `openLinkBackup`'s
+ * `widgetOrigin` option for staging, demo, or self-host. Money path: this origin
+ * serves the deposit-address UI during an outage.
+ */
+export declare const DEFAULT_BACKUP_WIDGET_ORIGIN = "https://backup.meshconnect.com";
+/**
+ * The `type` the backup widget's message bridge requires on the config it
+ * receives. The widget matches `event.data.type === 'meshBackupConfig'` and
+ * drops any message without it, so the config must be delivered as
+ * `{ type: BACKUP_CONFIG_MESSAGE_TYPE, payload: MeshBackupConfig }`.
+ */
+export declare const BACKUP_CONFIG_MESSAGE_TYPE = "meshBackupConfig";
+/**
+ * JIT-over-bridge RPC message types (OR-452). An address-less destination is
+ * resolved by the widget invoking the host's `onAddressInit`/`onStatusPoll`
+ * callbacks over this same postMessage bridge, correlated by `callId` — the
+ * widget never calls a client HTTP endpoint and holds no token.
+ *
+ * - Widget → host: `{ type: JIT_REQUEST_MESSAGE_TYPE, payload: MeshBackupJitRequestPayload }`
+ * - Host → widget: `{ type: JIT_RESPONSE_MESSAGE_TYPE, payload: MeshBackupJitResponsePayload }`
+ *
+ * ⚠️ KEEP IN SYNC with `mesh-backup-widget`'s `src/bridge/contract.ts` — the
+ * string values and payload shapes are the frozen cross-repo contract.
+ */
+export declare const JIT_REQUEST_MESSAGE_TYPE = "meshBackupJitRequest";
+export declare const JIT_RESPONSE_MESSAGE_TYPE = "meshBackupJitResponse";
+/**
+ * How long to wait for the Tier-1 widget's ready handshake (its `loaded`
+ * message) after the iframe starts loading the backup origin, before treating
+ * the origin as unreachable and cascading to the bundled Tier-2 assets.
+ *
+ * On the web this is the **authoritative** Tier-1 failure signal: a cross-origin
+ * iframe does not reliably fire a load `error` event for a network/DNS failure
+ * (and `onload` fires even for an error page), so a served-but-broken, hung, or
+ * captive-portal-intercepted origin is only caught by the absence of the ready
+ * handshake. 5000 ms absorbs a slow mobile network with margin (the widget shell
+ * is ~24 KB on a CDN) while keeping the degraded-path UX acceptable. Per-SDK
+ * tunable constant (design §5H).
+ */
+export declare const TIER1_READY_TIMEOUT_MS = 5000;
+/**
+ * Fail-closed safety net for Tier 2: the bundled assets load from a local `blob:`
+ * URL, so they should complete the ready handshake near-instantly.
+ * If they somehow do not within this window, the flow exits with an error rather
+ * than sitting on a blank screen (design §5A/§5H — never a blank QR). Deliberately
+ * generous because a Tier-2 timeout should be effectively unreachable.
+ */
+export declare const TIER2_READY_TIMEOUT_MS = 8000;
+export interface BackupWidgetUrlParams {
+    /** SDK platform identifier (`'web'`). */
+    platform: string;
+    /** SDK version, for widget-side diagnostics. */
+    sdkVersion: string;
+    /**
+     * Resolved colour theme. Appended as `?theme=dark|light` — the only theme
+     * value the backup widget reads. Omit for `system`/unset so the widget falls
+     * back to `prefers-color-scheme`.
+     */
+    theme?: 'dark' | 'light';
+    /**
+     * Per-open session nonce, appended as `?sid=`. The widget echoes it on every
+     * message it posts to the host, so a reused embedded iframe's stale messages
+     * from a previous open can be told apart (see `createSessionNonce`).
+     */
+    sessionNonce?: string;
+}
+/** URL parameter carrying the per-open session nonce (query for Tier 1, fragment
+ *  for the Tier-2 `blob:` URL). KEEP IN SYNC with `mesh-backup-widget`'s
+ *  `src/bridge/sessionNonce.ts`. */
+export declare const SESSION_NONCE_PARAM = "sid";
+/**
+ * A fresh, unguessable nonce for one backup open (128 bits, hex). Navigating an
+ * embedded iframe keeps its `WindowProxy` and Tier-1 sessions share an origin, so
+ * `event.source` + origin alone can't tell the current open's messages from ones
+ * the previous document queued before a reopen; the widget echoes this value as
+ * `sid` on every message and the SDK drops any that don't match.
+ */
+export declare function createSessionNonce(): string;
+/**
+ * Builds the URL the backup-widget iframe loads. Unlike the primary path there
+ * is no link token to decode — the widget is a static SPA at `origin` and is
+ * hydrated with the `MeshBackupConfig` over the message bridge after load. Only
+ * non-sensitive display hints are carried on the URL; the deposit config never
+ * appears in it.
+ *
+ * A trailing slash on `origin` is normalised away so params attach cleanly.
+ */
+export declare function buildBackupWidgetUrl(origin: string, params: BackupWidgetUrlParams): string;